fix(codex): classify spent subscription windows as quota rejections

[rikbrown]

The gap

forwardRequest distinguishes:

• Quota rejection — durable: hold the account for its reset window and rotate the request.
• Rate-limit throttle — momentary: pause the account, wait retry-after, and resend to the same account.

Quota rejection currently requires anthropic-ratelimit-unified-5h-status === 'rejected' or its 7d equivalent. The ChatGPT backend does not set these headers. It reports percentage quota in x-codex-*, which src/codex-quota.js already parses, so every Codex 429 entered the throttle path even when its subscription was spent.

With no sibling, the proxy slept a retry-after below the inline-absorb cap and resent to the exhausted subscription. With an idle sibling, the request could succeed after the single failover hop (#137), but the account stayed active behind a silent pause: the TUI showed it healthy, the throttledAt revalidation probe did not arm, and pauseAccount trained the concurrency learner from a spent quota.

The change

codexSpentWindows(headers) now reads the response through parseCodexQuota, the parser used by the quota sweep, and returns labels for windows at or past their limit. generalRejected tests whether the returned array has entries.

The parser groups x-codex-* families and uses each window's window-minutes, so it sees named model-scoped 5-hour windows that account-wide primary/secondary cannot. A spent session window can report flat values of 42% / 0% while refusing every request. classify also discards unparseable percentages and zero-length windows, which mean "not applicable".

updateQuota has already stored utilisation from these headers. The existing rejection branch then holds the account for retry-after and rotates. The log now includes the window, for example: Quota rejection (429) on "codex-1" (5h spent) — throttling 45s and switching account.

parseCodexQuota adds its missing @returns typedef, and rateLimitHeaders gets the Record<string, string> annotation now passed to it.

Hold semantics

The hold remains retry-after, clamped to [1s, 3600s], as in the Anthropic path. It does not use the window reset: retry-after is upstream's requested quiet period, while the recorded utilisation over the switch threshold keeps selection off the account for the rest of the window. Tests pin a 45s retry-after with a reset six hours out.

Verification

• npm test — 1871 pass, 0 fail, including six new test/codex-quota-rejection.test.js cases. They cover account-wide and named-family windows, non-cases, and end-to-end createProxyServer requests to a local Codex-429 upstream.
• Removing the new clause makes all three end-to-end tests fail on master: the two-account case leaves the account active and paused, and the lone-account cases wait 45s and call the exhausted subscription twice.
• npm run lint, npm run typecheck, and node scripts/typecheck-strict.mjs are clean; the ratchet reports 6 fewer strict diagnostics than base.
• Tests use no real endpoint or wall-clock time; they distinguish the paths by account state and upstream hit count.

Deliberate choice

A named family's weekly bucket is model-scoped, like Anthropic 7d_oi, which the existing branch treats as a Fable-only rejection without an account hold. This change treats it as general rejection. For now, upstream has refused this request on this account, the hold is bounded by retry-after, and updateQuota has recorded the bucket. codexSpentWindows labels already distinguish the case if a narrower model-scoped rejection is needed later.

🤖 Generated with Claude Code