fix(codex): keep rediscovering main-account credits after an unavailable observation

[lidge-jun]

Summary

An opted-in ChatGPT main account whose included window is full can now rediscover its credits after a single bad credit observation, and its local refusal tells clients to retry within minutes instead of days.

Before this change the background recovery sweep only renewed credit evidence that was already spendable. One WHAM read with a zero, null, missing or spending-restricted balance (or omitted credits with rate_limit.allowed:false, which retracts evidence) made creditRecoveryNeeded() false, so the sweep stopped probing. Credits that were usable again were never observed, and every request kept failing locally in a few milliseconds with 429 "Codex main account reached its usage limit, and spending ChatGPT credits is off or no fresh spendable balance is available", while direct Codex spent the same credits normally (#6845). The refusal's Retry-After also pointed at the included-quota reset, which can be days away.

Now:

• An opted-in, unpaused main account with an exhausted included window stays eligible for recovery lookups when its credit evidence is missing, zero, restricted or retracted. The existing pacing still applies: exponential backoff from 5 to 60 minutes, shared query deadlines, single-flight, identity and credential fences, and needs-reauth/pause/consent checks. Positive evidence still renews from three minutes of age.
• Admission is unchanged. A request is still refused until a fresh positive or unlimited balance is observed; has_credits alone or approximate message counts never authorize spending.
• With consent on, this refusal's Retry-After is capped at the base five-minute metadata interval (or a sooner included reset). Without consent it still follows the included-quota reset.

structure/providers/openai-tiers.md, openai-accounts.md and the Codex integration guide describe the new recovery rule.

Closes #6845

Verification

• bun test tests/codex-integration/main-account-credit-renewal.test.ts tests/codex-integration/codex-credits-after-limit-main.test.ts tests/codex-integration/main-account-hard-lock-recovery.test.ts: 147 pass, 0 fail. New cases: positive → zero / null / restricted / omitted-with-allowed:false → later "3000" re-probes after backoff and restores admission; missing initial evidence probes; refusal continues while unavailable; consent off, paused and needs-reauth do not probe; the consented Retry-After is bounded.
• With both source files reverted, main-account-credit-renewal.test.ts gives 42 pass, 23 fail.
• bun test tests/lab/core-lab-boundary.test.ts tests/codex-integration/codex-quota-parser-parity.test.ts: 80 pass.
• bun run typecheck, bun run structure:check, bun run privacy:scan, file-size ratchet, docs build: pass.
• The reporter's exact WHAM payload is unknown, so this fixes the stuck-discovery path rather than proving which observation triggered it. Full suite not run locally; exact-head hosted CI is the gate.

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.

Summary by CodeRabbit

• Improvements
  • Opted-in, unpaused main accounts can continue credit recovery checks when credit information is missing, zero, restricted, or withdrawn. Requests remain blocked until fresh spendable credits are confirmed.
  • When credit recovery is enabled, refusal wait times are capped at five minutes or an earlier included-quota reset. Without consent, the existing quota-reset wait time remains.
  • Existing pause, reauthentication, and retry safeguards remain in effect.
• Documentation
  • Updated guidance on credit recovery and request wait times.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-10T09:18:42.558309Z	135ead8	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 47c32954-a752-4790-9154-4af8b879446f

---

📥 Commits

Reviewing files that changed from the base of the PR and between 6524ce8 and 04a1491.

---

📒 Files selected for processing (6)

• docs-site/src/content/docs/guides/codex-integration.md
• src/codex/auth-api/pool-mode-gate.ts
• src/codex/auth-context.ts
• structure/providers/openai-accounts.md
• structure/providers/openai-tiers.md
• tests/codex-integration/main-account-credit-renewal.test.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

---

---

📝 Walkthrough

Walkthrough

Eligible, opted-in main accounts can renew credit observations even when evidence is missing or non-spendable. Requests remain blocked until fresh spendable evidence is observed. Consent-dependent refusal timing and recovery behavior are also documented and tested.

Changes

Main-account credit recovery

Layer / File(s)	Summary
Recovery eligibility and observations src/codex/auth-api/pool-mode-gate.ts, tests/codex-integration/main-account-credit-renewal.test.ts	Recovery lookups can run when credit evidence is missing or non-spendable, subject to the existing account, usage-window, pause, and pacing conditions. Tests cover recovery observations, eligibility exclusions, retracted credits, and terminal-response pacing.
Credit refusal timing and policy src/codex/auth-context.ts, tests/codex-integration/main-account-credit-renewal.test.ts, structure/providers/openai-accounts.md, structure/providers/openai-tiers.md, docs-site/src/content/docs/guides/codex-integration.md	When credit recovery is enabled, the refusal deadline is capped by the next quota-query delay or an earlier usage reset. Tests and documentation describe consent-dependent retry timing and the requirement for fresh spendable evidence.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Possibly related PRs

• lidge-jun/opencodex#6669: Implements the earlier main-account credit-renewal behavior extended by this change.
• lidge-jun/opencodex#6693: Implements a related recovery path for opted-in main accounts after the usage window is full.
• lidge-jun/opencodex#6179: Establishes quota-query pacing used by the recovery checks and consented refusal deadline.

---

Merge Risk: ⚪ Minimal · up to 04a14

This change lets opted-in main accounts keep checking for recovered credits after the included window is exhausted. Requests stay blocked until spendable credits are confirmed. No merge-blocking risk was found.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: continuing to rediscover main-account credits after an unavailable observation.
Linked Issues check		[#6845] The implementation addresses the reported local 429 path. runMainAccountHardLockRecovery in src/codex/auth-api/pool-mode-gate.ts keeps an opted-in, unpaused main account eligible when cred…
Out of Scope Changes check		The reviewed changes stay within [#6845]. The source changes modify only main-account credit recovery eligibility and the related local refusal deadline. The added tests exercise those rules and their…

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files. (3 skipped: 3 unsupported.)

---

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

---

---

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.