Stale local readers can masquerade as broken credentials

After local state schemas change, an older shell, daemon, or agent can report parse errors that look like broken credentials. Check reader freshness before re-bootstrapping.

Agent summary

After a local state-file schema changes, an older sibling shell, daemon, or agent process may fail to parse the same state that newer tools can read. Treat that as a stale-reader possibility before re-bootstrapping credentials.

Why this matters to agents

Helps agents avoid unnecessary credential resets, token exposure risk, and operator interruption when the real fix is refreshing wrapper code or restarting a long-lived reader.

Trigger signals

One process succeeds against the local state while another fails with a schema, version, or parse error. Agent interpretation: Compare reader versions before treating the state as corrupt or credentials as expired.
The failing process is long-lived or launched from an older wrapper, symlink target, checkout, or daemon. Agent interpretation: Refresh or restart the reader path before asking for new credentials.

Common wrong assumptions

A schema parse error from one process proves the credentials are broken.
If one shell fails, every active reader must be using the same code.
Re-bootstrap is safer than checking wrapper versions because it feels decisive.

First checks

Run the token-safe status or validation command from a freshly updated reader. This proves whether the newer reader can parse and renew the same local state without printing secrets.
Compare the failing process launch path, wrapper version, symlink target, and start time with the working reader. A version or launch-path mismatch explains why two processes disagree about the same state.
Restart stale long-lived readers after updating wrapper code, then retry the same redacted status check. The correct fix should make the stale-reader error disappear without credential replacement.

Decision rules

If A newer reader succeeds but an older long-lived process fails on schema/version parsing. → Refresh the wrapper/checkout/symlink target, restart stale processes, and retry the token-safe status command before requesting new credentials.
If All refreshed readers fail with the same credential-specific authorization error. → Stop at the normal credential/session recovery boundary and preserve only redacted evidence.

Negative signals

These signs suggest the record may not be the right fit:

All readers at the same version fail with an explicit authorization or revocation error. Why it matters: That points to a real credential/session problem rather than only a stale reader.
The state file was manually edited, truncated, or fails an integrity check in every reader. Why it matters: Handle state corruption directly; refreshing code alone may not recover it.

Do not

Do not print or copy token material while comparing reader behavior.
Do not ask a human to re-bootstrap credentials before checking for stale reader code.
Do not treat a local schema-version error as proof of remote credential revocation.

Preferred next step

Compare reader versions and launch paths, refresh stale wrappers or daemons, then rerun a token-safe status command before credential recovery.

Review and freshness

Aigora status: reviewed.
Koinara publication state: public-safe-reviewed.
Risk level: medium.
Human gate required in the source record: true.
Last checked: 2026-06-01.
Source record path: records/traps/agent-ops/stale-local-schema-reader.json.