fix(codex): renew main-account credit evidence before expiry - #6669

Summary

A main account with Use credits after limit enabled can receive a local 429 when its cached credit observation expires. This renews same-account authenticated credit evidence through the existing recovery worker, and distinguishes the resulting refusals: disabled consent, reported balance unavailability, spending restriction, expired information, and unverified information.

Only expired evidence that was otherwise spendable receives a shorter client check-again hint. The request remains refused with the same 429 error identity and real usage reset time; known same-generation WHAM pacing and account-wide cooldown deadlines cannot be shortened. The hint is not a promise of recovery or an extra WHAM dispatch. Enabling credits grants permission, not funds: fresh zero/has-no-credits, unknown or restricted balances remain refused, including after an earlier positive observation. Existing native ownership, credential generations, hard-lock, pause, reauthentication and worker backoff protections remain intact; no new timer, queue, auth-file read in refusal formatting, inference validation or reset-credit redemption is added.

The owning credit contracts and English/Chinese documentation describe these boundaries. The same PR branch incorporates current dev at 0cd680a543e9618f61d31b99fbe9319016784782 without rewriting the prior commits.

Verification

• Current head is ddddbcd36656300f747181dd077726cf17e110c2: one explanatory comment only beside hasSpendableCodexCredits(quota, credits.observedAt). The call's argument and all executable content are unchanged. The addressed inline nit is resolved; no validation was rerun for this comment-only delta.
• GitHub-hosted behavioral verification completed: evidence is explicitly reused from the previous tested head 2fe6433b40b8f670c6e1c2d00cb0dc8c57977590: GitHub-hosted run 37497235029, attempt 1, author's fork workflow 341992376, lane=release-gates, with 20 new behavior cases passing, 17 successful jobs and 8 skipped jobs. There is no new exact-head CI claim for ddddbcd366. This does not replace required upstream CI or maintainer approval.
• A single maintainer security/sponsorship request has been posted to the already-requested reviewers, which originally also asked about a hosted-only alternative. The later explicit local-validation request has now been completed successfully, superseding that waiver question. Maintainer security review and sponsorship remain pending. The branch is one commit behind the synchronized upstream ancestry, and no current unresolved review thread remains; author readiness for maintainer review is also now attested, without claiming maintainer acceptance.
• The original Linux shard 3 log records all 20 new behavior cases passing, including enabled consent with zero balance or hasCredits=false, both later-WHAM200 empty and omitted-credit cases, solely stale positive/unlimited information, unknown/future/invalid evidence, actual HTTP 429/reset/Retry-After invariants, no auth-file I/O on caller-owned refusal, and existing credential/upstream delays. The immediate query-count assertion and the later 68-second backoff assertion both remain exactly one query; no assertion or production guard was weakened.
• Linux four-shard and macOS two-shard jobs passed using the existing bash scripts/ci/run-bun-test-batches.sh "$TEST_SHARD". Typecheck (bun x tsc --noEmit and declared supplemental checks), GUI tests (cd gui && bun test --isolate tests), privacy (bun run privacy:scan), skill-surface and release-helper checks, CLI help, storage/API checks, Docker, keyring jobs and Rust desktop-shell checks succeeded. GUI lint/build/preview steps and packaged desktop E2E were skipped, not claimed passing.
• Skipped job families on the tested 2fe6433b40 head: Windows full-suite matrix/9, structure gate, npm-global matrix, macOS control, standalone privacy gate, remote-helper matrix, setup-action matrix and documentation build. Privacy did run successfully inside gates. Scope-selected skips are not evidence those checks executed.
• Explicitly reused unchanged-document evidence: documentation build and structure gate succeeded at 743c148fac6e34eee89318531f8890e998b6d363; the corresponding source/document files are unchanged through the current head. That whole run failed on a test import and is not relabeled as passing. These are historical scoped results, not executions on 2fe6433b40.
• Failure history retained: 743c run 37485958162 failed on the wrong test export (18 success / 3 failure / 5 skip); the two test references were repaired to the existing mapCodexAuthContextErrorToResponse. d9a run 37491861747 failed because the missing-credit test inherited a prior fixture's recovery generation (14 success / 3 failure / 8 skip); setup/cleanup now use existing clearMainAccountInfoCache, matching the existing recovery fixture, and assert the first query immediately. Neither repair changes production backoff or introduces a reset API.
• Earlier run 37440111654 succeeded at 53d0886b6d9c079327c023e93e9f7e82c58d84c5 with the original 11 renewal cases passing. It remains historical evidence only.
• Windows local validation passed on the current head ddddbcd36656300f747181dd077726cf17e110c2. The isolated worktree was materialized for these commands and dependencies installed with bun install --frozen-lockfile. Used the worktree's lockfile-resolved Bun 1.4.0 and TypeScript 7.0.2; tracked source and lockfile remained unchanged.
• bun test --isolate tests/codex-integration/codex-credits-after-limit-main.test.ts tests/codex-integration/main-account-hard-lock-recovery.test.ts — exit 0; 113 passed, 0 failed, 0 skipped; 905 assertions; 5.63 seconds. These use the existing protected preload, temporary homes, synthetic credentials and mocked requests; no live-account inference or installed service was exercised.
• bun run typecheck — exit 0, executing bun x tsc --noEmit with no compiler diagnostics. Full stdout/stderr and exact executable/cwd/versions/exit receipts were retained for both commands.
• Local full-suite exception: the user explicitly selected these two affected regression files plus root typecheck as the local complement to the existing hosted Linux four-shard/macOS two-shard evidence for unchanged executable content. No local full suite, GUI suite or build is claimed; the earlier GitHub evidence and its skips retain their stated scope. The previous GitHub-only/no-local-run statements are historical and have been superseded by this explicit local request. Author readiness remains separate from maintainer approval.
• Installed runtime/config/service remain unchanged by the follow-up. Earlier installed 2.78.0 evidence covers the previously accepted renewal implementation, not deployment of this branch's refusal/message changes. Explicit maintainer authentication/security review remains required. The authorized inline reply was posted and the addressed nit resolved. No maintainer approval, merge or release is claimed.

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. Explicit maintainer security review remains pending.

Review readiness

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

• New Features

  • For opted-in main accounts with a full usage window, credit availability is refreshed as the cached balance observation nears expiry. This can help requests use available credits without extending the usage window.
  • Requests may still be blocked by an empty balance, spending restrictions, a failed refresh, or a main-account hard lock. Refusal messages distinguish disabled spending, unavailable or unverified balances, and restrictions.
  • Expired evidence of previously spendable credits may include a shorter retry hint. It does not guarantee recovery or override an upstream delay.

• Documentation

  • Clarified that checking credit availability uses authenticated usage information and does not send a model validation request.