fix(codex): stop refreshing pool accounts whose refresh grant is already revoked - #6707

Summary

• A pool Codex account whose refresh grant the token endpoint already declared revoked or expired is persisted with a terminal validation verdict (lastCodexValidationTerminal + lastCodexValidationStatus: "failed"), and the health projection already reports it as reauth_required. Passive quota reads still called getValidCodexToken on every pass, though. When the account has no cached quota, or when showCodexCredits forces a cache bypass for an account that never reported credits (a dead grant never does), every dashboard poll, account listing, priming pass, and recovery probe POSTed the dead refresh token again.
• Observed on an installed 2.79.0 proxy: about 445 identical [codex] pool refresh: reauth status=401 code=refresh_token_reused lines in service.log for one pool account whose grant had been dead for a week. That count is consistent with one token-endpoint request per listing or poll. service.log has no timestamps, so I could not measure the actual rate.
• fetchPoolAccountQuota (src/codex/auth-api/pool-quota-probe.ts) now answers those passive reads with the stored verdict. It returns the same needsReauth: true, reauthReason: "refresh_failed" result the failed refresh would have produced, and re-marks the generation-scoped runtime flag. It makes no token request.
• The following still probe:
  • an explicit POST /api/codex-auth/accounts/refresh from any principal. This includes ocx account refresh openai (a raw-admin POST) and the dashboard refresh button. The route now passes a separate explicitRefresh intent through listCodexAuthAccounts to fetchPoolAccountQuota. validatePending is unchanged, so inference/validation consent stays GUI-session only.
  • a post-reset readback (afterDispatchSequence)
  • source-linked credentials, which spend no grant of their own
• Behavior change: only passive reads are held. These are GET /api/codex-auth/accounts listings (including ?refresh=1), dashboard quota polls (/api/provider-quotas), priming, and recovery probes. They report the stored verdict instead of retrying a grant already marked dead. Each explicit refresh command still retries once.
• The CodeRabbit finding on the first revision is addressed. That revision also held the raw-admin/CLI POST .../refresh. It now probes, and a regression case covers it.
• Recovery is unchanged. Every credential write (a re-login or a refresh commit) and every completed validation already drops the terminal marker, so the next read probes normally.
• structure/providers/openai-accounts.md records the new contract next to the existing refresh-failure classification paragraph.
• This change gates a token-refresh path, so it falls under the security-review guideline in AGENTS.md. It touches none of the maintainer-sponsored paths (src/oauth/, src/codex/auth-context.ts, src/codex/auth-api.ts, package.json, bun.lock).

Verification

• New regression cases in tests/helpers/pool-reauth-cause.ts. They are registered from tests/codex-integration/codex-auth-api.test.ts, which sits at its file-size cap, so no line was added there.
  • passive listings stop refreshing a pool grant the token endpoint already declared dead: with showCodexCredits: true and no cached quota, the first listing makes one token request and persists the terminal verdict. A second listing, a ?refresh=1 listing, and a listing after clearing the in-memory reauth mark (the restart case) make no further token requests and still report needsReauth: true / refresh_failed.
  • a dead pool grant is probed again after an explicit refresh command or a new credential. A raw-admin POST /api/codex-auth/accounts/refresh (what the CLI sends) probes once. A gui-session POST probes once. A ?refresh=1 listing between them stays held. A credential replacement then drops the verdict, so the next listing probes again.
• Fail-without-fix, checked for each change:
  • First commit: reverting only the guard in pool-quota-probe.ts gives bun test --isolate tests/codex-integration/codex-auth-api.test.ts -t 'dead' 1 pass / 1 fail. The passive case fails with 3 extra token requests.
  • CodeRabbit follow-up: reverting only the follow-up's src/ changes, so the raw-admin POST is held again, gives the same command 1 pass / 1 fail. The recovery case fails with Expected length: 2, Received length: 1.
• With the fix:
  • bun test --isolate tests/codex-integration/codex-auth-api.test.ts -t 'dead|refresh rejection|transient pool token|quota rejection': 5 pass / 0 fail.
  • bun test --isolate --timeout 30000 on every test file that imports or names the pool quota probe, pool-mode gate, account list, reset-credit service, or listCodexAuthAccounts (21 files), plus codex-account-store.test.ts, codex-account-store-refresh-classification.test.ts, and token-guardian.test.ts: 1244 pass / 1 skip / 0 fail across 24 files (6399 assertions), re-run at the follow-up commit.
  • bun run typecheck: exit 0. This and the four checks below were re-run at the follow-up commit.
  • bun run privacy:scan: passed.
  • bun run structure:check: passed.
  • bun scripts/file-size-ratchet.ts: passed.
  • git diff --check: clean.
  • bun run test:changed (first commit; not re-run for the follow-up) is not passing evidence. It selected 1531 of 2099 test files and was terminated at the repository's 900 s limit (exit 124). The incomplete log has 234 (fail) lines, all in files unrelated to this change (Lab, management/server auth, Kiro catalog, bearer admission, and others). I re-ran the five largest failing files alone on this branch and on unmodified dev (c30b5228d) in the same macOS environment, and they failed identically on both:
    • bearer-admission-routed-provider 21 pass / 45 fail
    • server-management-auth 27 pass / 21 fail
    • lab-fabric-task 22 pass / 31 fail
    • api-key-attribution 11 pass / 15 fail
    • kiro-model-catalog 1 pass / 13 fail
  • Those failures therefore come from this local environment, not from this change. Not every failure in the truncated log was attributed this way.
• Scope exception: the full bun run test suite was not run locally because a second worktree was running validation on the same machine at the same time. Full-suite coverage is left to CI.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• Bug Fixes

  • Passive quota checks now report when a stored account needs reauthentication, while retaining its cached quota and avoiding repeated token requests.
  • Explicit dashboard refreshes continue to retry quota checks. Post-reset checks and source-linked credentials also continue to probe.

• Improved Credential Recovery

  • Saving a new credential clears the terminal validation result, allowing a later quota check to proceed normally.