[yuanyuanlove]

Summary

• Add an opt-in, Codex-only quota-weighted account-pool strategy across configuration, CLI, management API, and the dashboard, with translated labels, affected user guides, one authoritative structure note, and regression coverage. The default strategy remains quota. Enable it with ocx account pool openai --strategy quota-weighted.
• Keep this PR focused: retain the runtime, CLI schemas, GUI, all new GUI/CLI/API/backend regression coverage, affected translated guides and the owning routing contract. Omit duplicated structure cross-links, optional help/error-copy edits, and generated CLI surface/recipe changes. Five pre-existing translated CLI usage lists were also synchronized with the new option.
• Carry the original quota-weighted contribution from source commit ed31c59b5261577f7bcb4fbcef79644922d72c90, preserving its attribution, and include two follow-up correctness fixes found during local validation.

Actual effect on account rotation

• Each eligible account is scored by its smallest remaining share across the applicable known usage windows. A tight weekly/monthly window therefore still caps the score even when the short window is about to reset.
• A measured reset observation no older than five minutes can give its own window a bounded near-reset lift of up to 10% (5% in the wider band). A reset deadline alone never implies replenished quota. Stale, unmeasured, or future-dated observation evidence adds no lift.
• After existing model and priority selection, when every candidate's quota is known, the account with the maximum score receives new/unbound assignments. Exact maximum-score ties rotate evenly. Close unequal scores do not receive equal shares: with scores of 60 and 59, the 60-score account receives new assignments until the scores or eligibility change.
• While any candidate's governing quota is unknown, the scheduler keeps the raw proportional weights instead. Unknown quota has weight 1, retaining a small probing share so the account can become observed. This is weighted scheduling across assignments, not a claim of random selection probabilities.
• Healthy existing session/thread bindings remain sticky under the existing affinity policy. This strategy primarily changes placement of new/unbound work; it does not reshuffle every request in an ongoing task. Independent model-quota scopes continue to use quota ordering, and optional idle-window steering keeps its existing precedence.
• Effective thresholds, cooldowns/probe admission, pauses, reauthentication, model/plan eligibility, priority, main-account ownership/read fences, refresh backoff, and credits policy remain in force. Threshold 0 disables threshold filtering only. There is no zero-weight fallback that bypasses known exhaustion or a credits-off hold, and paid credits still require the existing explicit opt-in.

The intended benefit is better use of relative remaining quota among eligible accounts for new work. The score compares percentages, not absolute plan capacity, and does not increase total quota or guarantee higher throughput.

Follow-up fixes

• Preserve per-window observation clocks across credits-only and partial quota-cache updates. Rewriting a cache entry, carrying an old window, hydration, or cloning no longer makes old reset evidence fresh again. The existing cache/disk schema is unchanged.
• Keep the existing last-resort soft-health recovery path reachable when normal healthy positive-weight selection is empty. Only positive raw-weight candidates can recover. Admission-ready candidates are considered before model/priority/weight ordering, so a non-probeable Retry-After candidate or an already-held probe cannot hide a recoverable sibling. Preview only checks availability; final authentication still enforces cooldowns and owns the probe lease. The threshold, exhaustion, credits, pause, reauthentication, model/plan, main-account, and refresh-backoff fences continue to apply.

Verification

Exact locally validated content

• Integrated upstream base: 7a4286052fe7a4f26c5691ecc380b91262508a6c (dev at integration time).
• Publication-time upstream read: dev advanced to 4ed45e9516e4421197d7cb0dd95a3d2f316aa0c9, one commit ahead of the integrated base. That CLI carry overlaps only the two test-registration files, at separate hunks; it has not been merged or locally validated with this candidate. Live mergeability and exact-head CI must still be checked.
• Earlier comparison base before integration: c03eafd46bdae15aba058850e409c0598309e2ed.
• Original candidate: f276879c03185eecf2f5a3c29016a701e476c877.
• Final integrated Git tree: 170487c49c34ed183ac3d17ef2b6ccbdf12fe5de (frozen local source commit b6eab4b444f2bf5e7817ee9d69f1d9c39b2554a1).
• Pre-integration validated feature tree: c21a11f7df6d4cf41b3f29a072df33ba1c3dbf0a.
• The feature patch was independently round-tripped through a temporary Git index, then cleanly integrated with the 7a4286052 dev baseline. A separate SHA-only tree reconstruction also reproduced the final integrated tree exactly. Scope against that integrated baseline: 47 files, +1,060/-75; the two follow-up fixes affect 8 files, +379/-38 against the original candidate.
• Local runner: Bun 1.4.3. The test wrapper, preload, dependency locks, proxy/network settings, and security settings were unchanged. Tests used isolated homes/configuration/credentials; no real-account or provider smoke test was performed.

Commands below name the pinned runner as bun; JUnit output paths are shortened to <phase.xml>.

The same explicit, source-audited 13-file command ran on clean integration baseline (7a4286052) and the final integrated tree. The integration safety review rechecked the sole upstream test import change and its execution owners before running:

bun scripts/test.ts --parallel=4 --reporter=junit --reporter-outfile=<phase.xml> \
  ./tests/codex-integration/codex-pool-rotation.test.ts \
  ./tests/codex-integration/codex-preserve-signed-in.test.ts \
  ./tests/codex-integration/codex-pool-plan-exclusion.test.ts \
  ./tests/codex-integration/codex-pool-refresh-backoff.test.ts \
  ./tests/codex-integration/codex-quota-capacity.test.ts \
  ./tests/codex-integration/codex-quota-history.test.ts \
  ./tests/codex-integration/codex-quota-parser-parity.test.ts \
  ./tests/codex-integration/main-quota-evidence-validation.test.ts \
  ./tests/routing/routing-policy-pool-quota.test.ts \
  ./tests/oauth/pool-kernel-generic-sweep.test.ts \
  ./tests/cli/cli-account-pool-verbs.test.ts \
  ./tests/cli/cli-capabilities-arguments.test.ts \
  ./tests/test-layout.test.ts

Result on each side: 477 passed, 0 failed, 0 skipped, with all 477 file/class/test-name/status identities equal and no added failing identity. Earlier comparisons on the previous base, original candidate, and pre-integration feature tree also passed the same 477 cases; those historical runs do not expand the current allowlist scope.

Final-candidate-specific regressions were run separately and are not included in the common baseline count:

bun scripts/test.ts --parallel=4 --reporter=junit --reporter-outfile=<final-only.xml> \
  ./tests/codex-integration/codex-quota-weighted.test.ts \
  ./tests/codex-integration/codex-quota-weighted-recovery.test.ts

Result: 67 passed, 0 failed, 0 skipped. Coverage includes the known-quota dominant tier, equal-score rotation, unknown-quota probing, reset-evidence freshness after partial/credits writes, and soft-health recovery/probe admission ordering.

The focused 47-file tree was rechecked directly after scope reduction. The same 477 identities also match the clean integration baseline exactly. GUI strategy tests passed on this exact final tree: 25 passed, 0 failed.

cd gui
bun test --isolate tests/account-pool-strategy.test.tsx
bun run lint:i18n
bun run build

GUI i18n lint and build passed. Final integrated static checks passed:

bun run typecheck
bun run privacy:scan
bun run structure:check
bun run skill:surface:check
bun scripts/file-size-ratchet.ts
git diff --check
git diff --cached --check

A final independent read-only source review reported no remaining concrete quota-weighted integration finding. The separate pre-existing upstream lifecycle limitation is documented below. This does not constitute maintainer security approval.

Earlier evidence, with different scope

Before the two follow-up fixes, original candidate f276879 passed a local nine-file backend set (384 tests), cd gui && bun test --isolate tests/account-pool-strategy.test.tsx (25 tests), and cd gui && bun run build. The same GUI build also passed once on the clean base. These are historical checks of the original candidate/base, not additional final-tree backend or GUI results. No separate root build was performed.

Incomplete validation and draft blockers

• Broad/full-suite validation is incomplete. An attempted 1,823-file common baseline run was stopped by an executor safety denial after an unexpected external Grok chat-proxy connection attempt. It produced no complete baseline JUnit result, and the candidate broad phase never ran. The denial was not bypassed, and proxy/security settings were not changed. The four previously blocked opaque-blob/compaction-override files were never run. Subsequent testing was limited to the explicitly audited local allowlist above.
• Earlier cloud broad testing of the original candidate also contained 793 failures and 13 errors. Only 56 representative failures were reproduced on the base; that does not establish that every historical failure was environmental. No full-suite-green claim is made for this change.
• Coverage outside the local allowlist, including the retained management-API/CLI integration cases, broader transport integration, the full GUI suite, real provider behavior, and cross-platform validation, remains outstanding. The documentation-site build was not run because its dependencies are not installed in this isolated workspace. The optional legacy CLI help/error lists were left at the upstream version; the functional strategy parser and modern CLI schemas accept the new strategy. Required CI must pass on the eventual exact PR head before merge.
• The upstream version at integration time is retained alongside the enhancement. As noted above, dev advanced by one further commit during publication preparation. The focused tree based on 7a4286052fe7a4f26c5691ecc380b91262508a6c passed the source-audited 477 common cases, 67 specialized cases, 25 focused GUI cases, typecheck, privacy/structure/surface/file-size checks, GUI i18n lint and GUI build. This remains focused validation, not a full runtime-suite or cross-platform claim.
• GUI screenshot is missing and visual UI verification is pending. This PR changes gui/, so the screenshot requirement remains unmet and the enforcement check may remain blocked. Add a real screenshot to the PR description, without committing screenshot evidence to the PR branch.
• Maintainer sponsorship/security review for the authentication/management-boundary changes remains required. Local privacy/static checks and source review do not replace it. Codex/CodeRabbit review and exact-head CI are still pending.

A separate upstream limitation was found by read-only integration review: account-lifecycle.ts replaced the broad routing cleanup with leaf cleanup calls but omitted the failure-window cleanup. Native-main identity replacement may therefore retain the previous identity's degraded failure-window state. This already exists in upstream 7a4286052 and is not introduced by this PR; it is intentionally kept outside this focused change. No live-account reproduction was performed.

This PR is intentionally a draft while these gaps remain.

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. All four remain unchecked pending validation and review of the final published head.

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Co-authored-by: yuanyuanlove yuanyuanlove@users.noreply.github.com

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• 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 hygiene checks failed.

• unsponsored_surface — This changes an authentication, workflow, release-automation, or dependency surface. MAINTAINERS.md requires security review for these; ask a maintainer to apply maintainer-sponsored once they have reviewed it. Paths: src/oauth/pool-kernel.ts.

[github-actions]

⏳ DRAFT

• UI screenshot required. hygiene: unsponsored_surface.

What to do

• Add a screenshot of the UI change to the PR description.
• Fix unsponsored_surface — This changes an authentication, workflow, release-automation, or dependency surface. MAINTAINERS.md requires security review for these; ask a maintainer to apply maintainer-sponsored once they have reviewed it. Paths: src/oauth/pool-kernel.ts.
• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ Required local validation passed; commands, results, and any full-suite exception are documented.
• ⬜ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

This pull request was already a draft. Its draft status will be preserved after every issue above is resolved.
@yuanyuanlove Tick the boxes once required local validation has passed with commands, results, and any full-suite exception documented, your branch is on the latest dev commit, and every correct Codex and CodeRabbit finding is resolved.

[Ingwannu]

Intake at 3ed3f03046: current hygiene fails specifically with unsponsored_surface; owner/maintainer sponsorship is a review decision, not a generic test failure or a label to self-apply. Keep Draft until that boundary and owner GUI acceptance are settled. Routing validation must distinguish fresh versus unknown quota, disabled-feature parity, dynamic eligibility/cohort changes, deterministic tie-breaking, generation replacement, pinned/exact-account precedence and foreground affinity; weighted scores alone do not prove those contracts. Preserve original contribution attribution through any carry/squash and keep screenshot/platform evidence exact-head. No live account rotation, quota use or scan was executed here.

[lidge-jun]

Thank you for the work here. We're closing this to keep the review queue manageable: the scheduling design is still open in #7206, and the draft currently fails CI. You're welcome to reopen this or open a smaller PR against dev.