feat(codex): add quota recovery policy contract

[luvs01]

Summary

• Add a dormant, default-off codexQuotaRecovery policy contract for the next bounded slice of [Feature]: opt-in reset-credit recovery after verified pre-stream quota exhaustion #657.
• Require exact double opt-in (enabled and autoRedeemResetCredit) plus an explicit alternate-first or reset-first priority before the effective policy can authorize future automatic redemption.
• Fail closed for inherited, accessor-backed, Proxy-mutated, or malformed live candidates, while a malformed hand edit disables only this policy and preserves the rest of the configuration.
• Document that this change does not consume a reset credit or replay a request; runtime integration remains a separate review.

Refs #657

Verification

• Base: current dev at 8b1c620839faf08b3e56927691a67dff925e8202; exact head: 3ae981423311972f5d46a75f26e8b82b7d96594b.
• Bun 1.3.14: policy/config focused tests — 50 passed.
• Bun 1.4.0-canary.1: policy/config focused tests — 50 passed.
• TypeScript typecheck passed with both Bun runtimes.
• Privacy scan passed.
• Documentation build passed (309 pages).
• git diff --check passed.
• Independent exact-head review found no remaining actionable P0-P2 issue after direct throwing-descriptor and revoked-Proxy inputs were made to return the same frozen disabled policy.
• A prior pinned Bun 1.3.14 Windows full-suite attempt was not green: unchanged Codex user-identity/catalog/lock tests cascaded after an empty Windows effective-account lookup, and Bun crashed with exit 3. The latest upstream Windows dispatch baseline has the same independent failure family; normal push CI skips Windows. Exact-head maintained CI remains required.

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:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features

  • Added an optional, disabled-by-default Codex quota recovery policy.
  • Added controls for enabling recovery, automatically redeeming reset credits, and choosing recovery priority.
  • Added validation and safe handling for malformed configuration values.

• Documentation

  • Documented configuration options, required opt-ins, supported priorities, defaults, and example JSON.
  • Clarified that the policy currently validates and persists settings without performing recovery actions.
  • Documented that invalid live updates are rejected and malformed edits disable only this policy.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 64d92f45-30a8-4e57-837a-272f09187bd0

📥 Commits

Reviewing files that changed from the base of the PR and between 64761a7 and 3ae9814.

📒 Files selected for processing (2)

• src/codex/reset-credit-policy.ts
• tests/codex-reset-credit-policy.test.ts

---

📝 Walkthrough

Walkthrough

The change adds the dormant codexQuotaRecovery policy, its public configuration contract, runtime normalization, safe validation, load-time warnings, documentation, and tests for malformed and accessor-backed values.

Changes

Codex quota recovery policy

Layer / File(s)	Summary
Policy contract and normalization src/types.ts, src/codex/reset-credit-policy.ts, tests/codex-reset-credit-policy.test.ts	Defines the optional policy, supported priorities, exact dual opt-in requirement, disabled fallback, and frozen normalized output.
Configuration validation and degradation src/config.ts	Safely inspects own descriptors, rejects malformed or accessor-backed policies, validates prepared candidates, and emits warnings when persisted values degrade to disabled behavior.
Validation coverage and configuration documentation tests/config-user-edits.test.ts, docs-site/src/content/docs/reference/configuration.md	Tests persistence, malformed values, proxies, accessors, inspection failures, and default behavior. Documents accepted values and current non-operational behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Mergeability Score: 🟡 Moderate · up to 3ae98

This change adds a default-off quota recovery policy contract without enabling automatic redemption, but the PR is not yet merge-ready because its required readiness checklist remains incomplete and exact-head CI is still outstanding; merge should wait for those gates to be completed.

Sequence Diagram(s)

sequenceDiagram
  participant ConfigSource
  participant validateConfigCandidate
  participant DescriptorSnapshot
  participant ConfigSchema
  ConfigSource->>validateConfigCandidate: submit configuration candidate
  validateConfigCandidate->>DescriptorSnapshot: inspect quota recovery descriptors
  DescriptorSnapshot->>ConfigSchema: provide prepared policy
  ConfigSchema-->>validateConfigCandidate: return validation result
  validateConfigCandidate-->>ConfigSource: accept policy or emit degradation warning

Loading

Possibly related PRs

• lidge-jun/opencodex#866: Adds rejection classification related to Codex quota recovery.
• lidge-jun/opencodex#955: Adds Codex cooldown recovery probing related to this policy.
• lidge-jun/opencodex#1353: Changes runtime handling of reset-derived quota outcomes during account retries.

Suggested labels: intake: hygiene-blocked

Suggested reviewers: lidge-jun, ingwannu

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the new Codex quota recovery policy contract, which is the primary change in the pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

[github-actions]

⏳ DRAFT

• review readiness checklist open (3/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 3/4).

Review readiness checklist

• ✅ All CI tests are green on my local testing.
• ⬜ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

3/4 boxes ticked.

This PR stays in draft until every box above is ticked.

[luvs01]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[lidge-jun]

The policy boundary is sound. effectiveCodexQuotaRecoveryPolicy() authorizes only the exact double opt-in plus an allowed priority (src/codex/reset-credit-policy.ts:27-48), while the write boundary snapshots own data descriptors before Zod evaluates unrelated candidate properties (src/config.ts:2361-2431). The tests exercise both authorization priorities, malformed/inherited/accessor inputs, Proxy inspection failures, and attempts by an unrelated accessor to replace the checked policy (tests/codex-reset-credit-policy.test.ts:18-58, tests/config-user-edits.test.ts:820-1008). The documentation accurately says this change does not redeem a credit or replay a request.

CodeRabbit reported no actionable finding, and I agree for the current dormant contract. The PR targets dev correctly.

This should still stay out of today's release: it introduces configuration for a future irreversible account action without delivering a user-facing bug fix, remains draft, is one commit behind dev, and its exact head has only hygiene/target checks rather than cross-platform CI evidence. Rebase, run maintained CI on the resulting head, and land it in the normal #657 sequence.

DISPOSITION: DEFER

[luvs01]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.