feat(codex): opt in to remaining included quota (carry #6629)

[lidge-jun]

Summary

Carry #6629 by @Yuxin-Qiao from source head 2a7add53cabd24e26be203e1472daef37a7f2790 onto dev at 7640a942b35044c974e534b84d5a8049f4a8ae9a.

• Add the default-off, persistent per-account codexUseRemainingQuotaAccountIds preference through ocx account use-remaining openai <id|alias|main> <on|off|status> and authenticated GET/PUT /api/codex-auth/accounts/use-remaining.
• Opted-in accounts disable proactive usage switching; main-account effective hard-lock thresholds become 100%. Stored thresholds remain unchanged and apply again when the preference is disabled. CLI receipts validate the effective thresholds.
• Keep manual/automatic pause, entitlement, reauthentication, upstream cooldown, and paid-credit consent guards. This preference grants no paid-credit permission and redeems no reset grants. Preserve newer native-main refresh and credit-policy changes while resolving the stale conflicts.
• Extend regression coverage for positive credit balance without consent, main credit refusal with hard lock disabled, model entitlement, round-robin, automatic pause, and quarantine. Synchronize English/Chinese user docs, architecture contracts, and the generated CLI surface. No GUI changes.

Closes #6629.

Co-authored-by: Yuxin Qiao 104957188+Yuxin-Qiao@users.noreply.github.com

Verification

Every test/check used fresh isolated OPENCODEX_HOME=$(mktemp -d) CODEX_HOME=$(mktemp -d). Tests also used OCX_TEST_NO_QUEUE=1 for the explicitly concurrent lanes, while keeping one test worker.

• bun scripts/test.ts --parallel=1 tests/codex-integration/codex-use-remaining-quota.test.ts tests/cli/cli-account-policy.test.ts tests/codex-integration/main-account-hard-lock-auth.test.ts — 159 passed, 0 failed before the additional guard cases.
• bun scripts/test.ts --parallel=1 tests/codex-integration/codex-use-remaining-quota.test.ts tests/codex-integration/main-account-hard-lock-auth.test.ts — final auth coverage: 72 passed, 0 failed.
• bun scripts/test.ts --parallel=1 tests/codex-integration/codex-account-threshold-routing.test.ts tests/codex-integration/codex-account-threshold-api.test.ts tests/codex-integration/codex-account-threshold-auth.test.ts tests/codex-integration/main-account-hard-lock-thresholds.test.ts tests/codex-integration/codex-credits-after-limit.test.ts tests/codex-integration/codex-credits-after-limit-main.test.ts tests/codex-integration/low-quota-protection.test.ts tests/codex-integration/codex-model-entitlement-admission.test.ts — 142 passed, 0 failed.
• bun scripts/test.ts --parallel=1 tests/ci-workflows/file-size-ratchet.test.ts tests/test-layout.test.ts tests/test-layout-tooling.test.ts tests/ci-workflows/skill-ocx.test.ts tests/lab/core-lab-boundary.test.ts tests/server/management-route-registry.test.ts tests/cli/cli-capability-account-workflows.test.ts — 115 passed, 0 failed.
• bun run typecheck — passed after final test additions.
• bun run skill:surface — regenerated successfully; the skill synchronization tests above passed.
• bun run privacy:scan — passed.
• bun run structure:check — passed after folding the added API note into the existing paragraph to honor the 600-line cap (initially failed at 602 lines).
• git diff --cached --check — passed.
• cd docs-site && bun install --frozen-lockfile && bun run build — passed; 577 pages and 81,204 internal links checked.

Full-suite and local cross-platform runs were omitted because approximately 20 concurrent lanes share this machine. Focused quota, account-policy, auth, routing, credit, layout and boundary coverage ran serially; broader suite/platform coverage is left to the dispatched ci.yml run. No real-account quota consumption was performed. No passing remote CI or maintainer approval is claimed.

Independent security review, round 1 (head 307c2b47d63b41891c2cc548cf1525838cdcffb6). Every threshold-0 short-circuit (hasCodexQuotaHeadroom, the request-owned main pin, active rotation, priority failback, subagent fallback) still runs pause, cooldown, entitlement, reauthentication and the credit-consent hold (CodexPoolAccountCreditsOffError / CodexMainAccountCreditsOffError) independently. The preference therefore cannot spend paid credits, and the main lock at 100% still refuses at the limit. The new GET/PUT pass through the central requireManagementAuth gate for /api/*. The PUT has no await between reading and saving the runtime config, rolls back the live list when a save fails, and account deletion's whole-config rollback covers the key. The one fix pushed in this round moves the CLI note in structure/cli-management.md out of the document header and into its account-policy section.

• OCX_TEST_NO_QUEUE=1 bun run test:changed (merge base 7640a942b): 38005 pass / 107 skip / 21 fail / 4 errors. The failing files were rerun serially on this head and on clean origin/dev 7640a942b (cli-access-audio-live, sibling-home-client-sync, native-codex-toggle, native-grok-toggle, service-ownership-state, service-sqlite-home, service, server-auth). Both heads gave 481 pass / 5 fail, with the same five audio-live and sibling-home failures. The other parallel-run failures did not reproduce serially, so there is no regression.
• bun scripts/test.ts --parallel=1 over structure-ssot, file-size-ratchet, test-layout, test-layout-tooling, core-lab-boundary, repo-hygiene, skill-ocx, codex-use-remaining-quota, cli-account-policy, main-account-hard-lock-auth and management-route-registry: 327 pass, 0 fail.
• bun run typecheck, bun run privacy:scan, bun run skill:surface:check, bun run structure:check and git diff --check all passed.

Cross-platform CI dispatched on exact head 307c2b47d63b41891c2cc548cf1525838cdcffb6: https://github.com/lidge-jun/opencodex/actions/runs/38716156883 (queued at handoff; the superseded run for 4a700abe0 was cancelled).

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. An independent security review (round 1, above) found no blocking issue; under MAINTAINERS.md, maintainers keep the merge decision.

Summary by CodeRabbit

• New Features

  • Added a persistent setting to let individual OpenAI accounts use their remaining included quota before switching. Check or change it with ocx account use-remaining openai <account> status|on|off.
  • For the main account, enabling the setting moves hard-lock thresholds to 100%. Previously configured thresholds resume when the setting is turned off.
  • Added authenticated API support for reading and updating the setting.
  • The setting does not enable paid credits or override pauses, reauthentication, cooldowns, or account eligibility checks.

• Documentation

  • Updated account and configuration guides in English and Chinese with usage details and policy limits.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 164253e0-30b9-4256-8001-6bef9bcf55dc

📥 Commits

Reviewing files that changed from the base of the PR and between 977b4f4 and e195efd.

📒 Files selected for processing: 2

• scripts/test-layout/layout.json
• tests/fixtures/test-layout-expected.json

+---------------------------------------------+
| Rabbit in the repo, here to fix that bug 🎶 |
+---------------------------------------------+
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

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: feec2922-0fe0-4321-96ff-38893d83d240

📥 Commits

Reviewing files that changed from the base of the PR and between 307c2b4 and 977b4f4.

📒 Files selected for processing: 7

• docs-site/src/content/docs/reference/configuration/providers.md
• scripts/test-layout/layout.json
• src/codex/main-account-hard-lock.ts
• src/config/diagnostics.ts
• src/config/schema/config-schema.ts
• src/types/config.ts
• tests/fixtures/test-layout-expected.json

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

📝 Walkthrough

Adds a persistent per-account preference for using remaining included quota. The preference changes effective auto-switch and main-account hard-lock thresholds. Authenticated API routes and a CLI command read and update the setting.

Changes: Remaining Quota Preference

Layer / File(s)	Summary
Persist the preference and apply effective thresholds src/types/config.ts, src/config/schema/config-schema.ts, src/config/diagnostics.ts, src/codex/account-use-remaining.ts, src/codex/auth-context.ts, src/codex/account-auto-switch.ts, src/codex/main-account-hard-lock.ts, src/codex/account-lifecycle.ts	Adds and validates the account-ID preference. Opted-in accounts have an effective auto-switch threshold of zero. The main account has effective short- and long-window hard-lock thresholds of 100. Deleting an account removes its preference.
Expose the preference through the authenticated API src/codex/auth-api/account-list.ts, src/codex/auth-api/routes.ts, src/codex/auth-api/use-remaining-route.ts, src/server/management/route-registry.ts	Adds the preference to account DTOs and handles authenticated GET and PUT requests. PUT validates the request, saves the setting, and restores the prior live state if saving fails. Responses include effective thresholds.
Add CLI controls and validate policy receipts src/cli/account-policy-dto.ts, src/cli/account-policy.ts, src/cli/account.ts, src/cli/capabilities-accounts.ts, src/cli/registry.ts, tests/cli/cli-account-policy.test.ts	Adds ocx account use-remaining with on, off, and status modes. The CLI checks API receipts and reports the effective auto-switch threshold. Tests cover command actions, receipt validation, and invalid arguments.
Verify threshold, routing, and persistence behavior tests/codex-integration/*, tests/codex-integration/main-account-hard-lock-auth.test.ts, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json	Adds integration coverage for threshold changes, account selection constraints, API authentication and rollback, account deletion cleanup, and main-account materialization.
Document the command and configuration docs-site/src/content/docs/reference/cli/providers-accounts.md, docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md, docs-site/src/content/docs/reference/configuration/providers.md, skills/ocx/references/*, structure/cli-management.md, structure/config.md, structure/gui-and-management-api.md, structure/providers/openai-accounts.md	Updates CLI, configuration, capability, and architecture references to describe the preference, its threshold effects, and its policy limits.

Priority: ➖ Normal

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant CLI
  participant AuthAPI
  participant RuntimeConfig
  Operator->>CLI: Run use-remaining with account and action
  CLI->>AuthAPI: Send GET status or PUT preference
  AuthAPI->>RuntimeConfig: Save preference for PUT
  AuthAPI-->>CLI: Return setting and effective thresholds
  CLI-->>Operator: Report preference status

Loading

Merge Risk: ⚪ Minimal · up to 977b4

Opted-in accounts skip quota-driven switching without bypassing pause, reauthentication, entitlement, cooldown, or credit-consent protections. No actionable merge-blocking risk remains from the reviewed change; it is mergeable subject to normal project checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 23.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 30 functions across 20 files. (3 skipped:…	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: adding an opt-in for remaining included quota in Codex.
Linked Issues check		Issue #6629 is closed and supplies historical context only. The PR objectives state that no active directly linked issue remains. Therefore, no active linked-issue coding requirements apply.
Out of Scope Changes check		The available whole-PR summary shows changes that remain within the stated feature scope: the persistent account preference, CLI and authenticated API surfaces, configuration validation and rollback, …

Full details: Docstring Coverage

Explanation

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

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 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.}

[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-15T09:56:32.126506Z	307c2b4	Draft marked ready

ℹ️ 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.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

Maintainer integration into dev (MAINTAINERS.md dev maintainer-integration policy; batch integration authorized by @lidge-jun on 2026-10-15).

• Head: e195efdd8ca02517903c51b1d55ce3802d189449 (tree 0a3b0a2fafca137aea98077367fe192c0e44ead3) = this branch merged with origin/dev d9ef8625b9. Integration note: auto-resolved union conflicts: scripts/test-layout/layout.json.
• Exact-head evidence: GitHub-hosted Actions for this account have not been assigning runners since 2026-10-15 13:30 UTC, so by owner decision the evidence is a full bun run test (Bun 1.4.3 test runner, root and GUI dependencies installed, GUI built) of this exact tree on a maintainer host (macOS arm64): exit 1, 9 min, 4 failing test(s), each also failing in the same host's baseline run of dev 60bf4c7 (environment-only): a secondary ensure parent preserves shared Grok, Codex and Claude agent bytes, connected Desktop uses hub IDs across a cold restart (stored profile=false), live audio readiness and bounded closure > native open and non-readiness events cannot cla, update stops the running proxy before replacing files > npm launcher restarts the stopped .
• Local gates on the same tree: bun run typecheck, file-size ratchet, test-layout and structure:check.
• Hosted CI checks for this head may still be queued; they are not claimed as evidence.