fix: clear a permanent main refresh latch when the refresh token rotates

[iceteaSA]

Incident (2026-09-02, live)

The main account's background refresh got 400 invalid_grant "Refresh token expired" at 15:35Z. The plugin recorded it as permanent: true with a 24h nextRetryAt, keyed to the main account's rotation-invariant slot id (v1.21.0). The operator re-logged in at 16:17Z: new refresh + access token in auth.json, same slot. The latch did not clear. Every tick logged skipped backoff, the next due refresh would have been skipped, and the fresh 8h token would have died at expiry with a valid family on disk.

Before v1.21.0 the error was keyed to the refresh-token hash, so a new token cleared it. Re-keying to the stable identity (#164) lost that edge: clearStaleMainRefreshError only clears on identity mismatch, and re-login into the same slot leaves the identity unchanged by design.

Fix

• Record refreshTokenFingerprint (non-reversible tokenFingerprint() of the refresh token that was actually sent) on every refresh error, main and fallback.
• refreshBackoffActive(error, identity, now, currentFingerprint): an error whose recorded fingerprint differs from the current refresh token's is stale evidence — the family rotated or re-logged under the same slot — and no longer holds the backoff. Threaded at all six main call sites and all six fallback call sites.
• clearStaleMainRefreshError also clears and persists on fingerprint change.
• /claude-account reset-backoff (OpenCode + Pi): explicit operator escape hatch that clears mainLastRefreshError and the quota-API error under the current identity through the locked save path, bumping the generation / clearedAt fences so a stale cross-process writer cannot resurrect them.

Errors recorded before this change carry no fingerprint. Those hold until identity change or one reset-backoff — stated in the commit body and pinned by a test. Every error recorded from now on clears on re-login.

Proof

• Background tick with a persisted permanent error (fingerprint F1) and a rotated refresh token (F2) → refresh attempted, error cleared, "cleared stale backoff after token rotation" logged. Mutation (drop the fingerprint compare): 0 attempts, red.
• Same fingerprint → backoff holds.
• Fingerprint-less legacy error → holds; reset-backoff clears; next tick attempts. Mutation (Pi persistence removed): ENOENT, red.
• Fallback: permanent error F1, account.refresh now F2 → refresh attempted; mutation red.
• Root 1371/0 twice, typecheck, format, biome clean. Cross-family review (M3-thinking) REVISE→fixed: the first cut's legacy rule read a state field nothing writes; removed.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Fixes a permanent refresh backoff latch that survived re-login into the same account slot, which could let a fresh access token expire despite a valid refresh token on disk.

Bug Fixes

• Records a fingerprint of the refresh token that produced each refresh error, main and fallback.
• Backoff is ignored when the current refresh token's fingerprint differs from the recorded error's.

Migration

• Errors recorded before this change carry no fingerprint and hold until identity change or one /claude-account reset-backoff.
• Adds /claude-account reset-backoff for OpenCode and Pi to explicitly clear main refresh and quota backoff.

^{Written for commit f095ad5. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 7 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>