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 main change: adding the Codex quota recovery policy contract.

✨ 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 (1/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 1/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.

1/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.

[lidge-jun]

Triage note (2026-08-15, maintainer): keeping as draft. The codexQuotaRecovery contract is sound (fail-closed validation, explicit no-credit-consumption documentation) and orthogonal to the combo quota work. But it is a dormant no-op on its own — landing it before the #657 runtime wiring risks contract drift. Please rebase and run full CI when the adjoining runtime-integration slice is ready, and land them together.

[lidge-jun]

리뷰 · 우선순위 48 / 80

dev 기준 이 PR은 codexQuotaRecovery 정책만 넣습니다. 런타임에서 reset credit를 쓰거나 요청을 replay하지 않습니다. effectiveCodexQuotaRecoveryPolicy는 own data property의 enabled === true와 autoRedeemResetCredit === true와 priority가 alternate-first|reset-first일 때만 automaticRedemptionAllowed를 켭니다. getter/inherited/Proxy throw는 전부 frozen disabled입니다. Draft이고 checklist의 CI/latest-dev/ready가 비어 있으며 mergeable이 UNKNOWN이라 점수를 내렸습니다.

파일 로드와 live write가 갈립니다. configSchema는 codexQuotaRecoverySchema.optional().catch(undefined)라 잘못된 손편집은 이 필드만 지우고 나머지를 살립니다. validateConfigCandidate는 prepareConfigCandidate가 own descriptor를 스냅샷한 뒤 정책을 freeze하고, accessor면 전체 candidate를 거절합니다. checkedCodexQuotaRecovery는 세 필드가 own data여야 하고 다른 키는 거절합니다. 손편집 degrade와 API 거절을 나눈 것은 본문과 맞습니다.

effectiveCodexQuotaRecoveryPolicy에서 priority가 이상한 문자열이면 validPriority는 false라 redemption은 꺼지지만, 반환 priority는 alternate-first이고 enabled/autoRedeemResetCredit은 true일 수 있습니다. 호출부가 enabled만 보면 허용된 것처럼 보입니다. 권한은 automaticRedemptionAllowed만 봐야 합니다. 이 helper를 호출하는 프로덕션 경로가 이 PR에는 없습니다. #1829 ledger와 이어질 때 그 플래그만 써야 합니다.

해결방안: (1) Draft를 유지한 채 consume 경로를 넣지 마십시오. (2) 다음 슬라이스는 automaticRedemptionAllowed만 보고 enabled만으로 redeem하지 못하게 테스트를 고정하십시오. (3) 잘못된 priority가 enabled true + default priority로 보이는 점을 문서/테스트에 남기십시오. (4) 현재 dev rebase와 mergeability를 확인한 뒤에만 Ready로 올리십시오. 범위는 #657의 계약 레이어로 맞고, 동작 변경이 없어 리뷰 부담은 작습니다.

이 댓글은 grok-bot이 작성했습니다