feat(codex): spend free resets when the Codex pool runs dry

[rikbrown]

Draft — stacks on #430. This branch is one commit on top of #430, so the shown diff includes it until that PR merges. Review the redemption commit with git diff feat/codex-reset-credit-count..feat/codex-reset-credits. It also overlaps #429 in server.js's refusal branch; whichever lands first requires the other to rebase.

The gap

OpenAI grants ChatGPT/Codex subscriptions occasional free rate-limit reset credits. Redeeming one clears that account's spent rate-limit windows before their reset. The Codex client exposes it as a manual action only.

A pooled Codex account can therefore sit out a weekly window while an expiring credit remains unused. With two spent accounts, every request gets 429 (none available) while the reset sits in the account's billing state.

What changed

New src/codex-reset-credits.js redeems credits. forwardRequest invokes it when selection cannot choose a Codex account.

Trigger. When every Codex account is over threshold, selection returns (none available) before an upstream request. The hook is in forwardRequest's !account branch, after candidate discovery and before hold/retry-after paths. It receives only accounts whose unavailableReason a reset can clear: quota and throttled, not disabled, capped, entitlement, error, or route. It runs only for Codex requests. A decline or throw preserves the refusal byte-for-byte; success reselects without consuming a retry budget because there was no upstream attempt.

Policy. shouldRedeemReset is pure and fully table-tested. A redemption requires a spent weekly window, never only a 5-hour window. It also requires either a dry Codex pool or a credit expiring within three days. is_supported_by_plan: false credits are removed before expiry reasoning.

One credit per dry pool. Three guards enforce it:

1. Concurrent refusals join one attempt.
2. A credit spend, or a failure that cannot rule one out, holds the entire fleet rather than only the touched account.
3. The pool is resolved for each decision, so an account returned to service makes siblings decline because another Codex account can serve.

ctx.resetRedeemTried limits each request to one attempt when upstream reports success but the account remains unselectable.

Off unless armed. autoRedeemResets is a fleet switch, false by default, in createDefaultConfig and config.example.json. It is available from the TUI settings screen and applies on reload. accounts[].autoRedeemReset is veto-only: it can say never, not yes.

Time budget. The attempt waits inline because a dry pool cannot rotate. One 10s deadline covers token refresh, detail fetch, consume, and re-read, leaving the rest of the Codex client's 60s response-head budget. ensureTokenFresh races the deadline because it has no timeout and concurrent refusals join it. A late refresh continues in the background; the attempt declines. Steps with nothing left are skipped and decline with cooldown.

Wire format

The endpoints are not in the public OpenAI API and are documented nowhere. They were recovered from the Codex binary and verified against a live account:

GET /wham/rate-limit-reset-credits	detail rows: id, status, expires_at, is_supported_by_plan
POST /wham/rate-limit-reset-credits/consume	{redeem_request_id, credit_id?}

Two details are covered by tests:

• The verdict field is code, not outcome; values are reset, nothing_to_reset, no_credit, and already_redeemed.
• Failure can return HTTP 200. Classifying by status would treat no credits as a successful redemption.

A transport error, timeout, or unreadable body does not mean upstream declined: it may have acted on the POST. The fleet-wide hold follows, and redeem_request_id is an idempotency key reused by a retry. already_redeemed is treated as success.

Detail-row granted_at / expires_at are ISO-8601 strings; the app-server layer uses epoch seconds for the same fields.

Verification

• npm test — 1936 tests pass, including 62 new tests in test/codex-reset-credits.test.js; the base PR provides the file's other 6.
• npm run lint, npm run typecheck — clean.
• node scripts/typecheck-strict.mjs — the new file has 0 strict diagnostics and the tree is 8 below this PR's base. A required Record<string, any> annotation on hooks in index.js also fixes pre-existing diagnostics.

No test calls the network. Tests inject fetch; two proxy-level tests use a local http server. Tests specifically verify that a failed quota re-read holds all other accounts, a consume without a received verdict stops the walk, and a token refresh exceeding the budget is left running.

The behaviour was observed with two accounts at 100% weekly with a credit: requests were refused before sending, the credit was redeemed on refusal, and the request was served.

Deliberate limitations

• A live Codex 429 on a chosen account is another spent-weekly trigger, but recognising a spent x-codex-* window as a durable quota rejection is separate work. Once the 429 path identifies it, the second trigger is a few lines using the same ResetCreditRedeemer.
• The default remains off. No per-account key can arm it.

🤖 Generated with Claude Code