Keep Account Pooler accounts usable when upstream rejects fresh tokens

[SawyerHood]

Human comments

What was wrong

During the 2026-09-25 Codex outage, chatgpt.com/backend-api/codex answered every request with HTTP 401 invalid_api_key ("Incorrect API key provided: sk-svcac…"), a key the pooler never sends. The hub refreshed the OAuth token, the refresh succeeded, the fresh token got the same 401, and markAuthError stored a permanent account error. Stored errors are never cleared automatically: selection skips errored accounts, freshSecret rethrows the stored error before refreshing, and bb pool account refresh <id> goes through the same path. Both Codex accounts stayed errored until they were removed and logged in again. A 403 marked the account without even trying a refresh.

What changed

• hub.ts: 401 and 403 both trigger one forced refresh. If the upstream rejects the newly issued token, the credential is proven valid, so the hub returns 503 (with the upstream detail) and records a token-keyed upstream backoff that holds the account out for one minute instead of marking an error. Rejection checks still guard against a late response poisoning a newer token. API-key accounts keep the old behavior.
• provider-adapter.ts: only HTTP 400/401 from the OAuth token endpoint are permanent refresh failures; other statuses and unreadable 200 bodies (parseOAuthRefreshResponse, used by both adapters) are transient.
• bb pool account refresh <id> / account.refreshUsage: for an errored OAuth account, forces a refresh past the stored error and clears it on success; a permanent failure updates the error message, and the CLI reports the account still in error.
• Docs: skill reference and CLI summary (PLUGIN_OVERVIEW.md is at the 4,000-character bundled-plugin cap).
• Deviation from the investigation's proposal: no automatic background retry of errored accounts. After this change an error means the OAuth server rejected the refresh token, so periodic retries cannot succeed, and replaying a rotated Codex refresh token can trip reuse detection.

How you verified

• New tests: Claude and Codex × 401/403 replay the outage's invalid_api_key body (503, no account error, no upstream or refresh traffic during the hold, recovery on the same token afterwards); manual refresh clears a stored invalid_grant error; refresh 403/404 and unreadable bodies are transient. All 10 fail against the previous source and pass now.
• Updated three existing expectations from 401/429 to 503 for fresh-token rejection.
• pnpm exec turbo run typecheck test --filter=bb-plugin-account-pool: 323 passed.

AGENT GENERATED

🤖 Generated with Claude Code