Repository navigation
fix(codex): place round-robin conversations on accounts with quota headroom - #8092
Conversation
…adroom Round-robin rotated new Codex conversations by count alone, so a fresh conversation could bind to an account already at 95% and then move to a cold prompt cache when that account ran out. New placements now skip accounts at or over their effective autoSwitchThreshold while any eligible account is under it, using the hasCodexQuotaHeadroom score fill-first and the priority tier already use. When every account is over, rotation covers all of them as before. Bound conversations, failover alternates and the lineage first-placement hint keep their existing behaviour. Docs: document the Codex rule, and correct the Claude quota strategy description, which keeps the active account until it reaches autoSwitchThreshold before moving to the least-used account.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
✅ Deterministic PR hygiene checks passed. |
|
No actionable comments were generated in the recent review.
|
| Layer / File(s) | Summary |
|---|---|
Headroom filtering and placement validation src/codex/routing/selection.ts, src/codex/routing/active-account.ts, tests/codex-integration/codex-round-robin-headroom.test.ts, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json, devlog/_plan/261102_codex_rr_headroom/010_plan.md |
Round-robin previews and picks filter eligible accounts by quota headroom when at least one eligible account has headroom. An unspent manual selection remains preferred, and selection falls back to the full eligible list when no account has headroom. Integration tests cover threshold cases, bindings, previews, rotation, failover, and lineage. |
Placement behavior reference structure/providers/codex-round-robin-placement.md, structure/providers/openai-accounts.md, structure/INDEX.md, structure/manifest.json |
Structural documentation describes the placement rule, threshold and usage handling, and cases where narrowing does not apply. The index and manifest map the document to the routing source. |
Provider guidance across locales docs-site/src/content/docs/*/reference/configuration/providers.md, docs-site/src/content/docs/reference/configuration/providers.md, docs-site/src/content/docs/*/guides/claude-code.md, docs-site/src/content/docs/guides/claude-code.md |
Provider references describe Codex round-robin headroom behavior and clarify Anthropic pool threshold and quota selection descriptions. Claude Code guides update the quota strategy description. |
Estimated code review effort: 3 (Moderate) | ~20 minutes
Change: Bug fix
Sequence Diagram(s)
sequenceDiagram
participant Selection as Codex round-robin selection
participant Candidates as roundRobinPlacementCandidates
participant Usage as Codex quota usage
participant Ring as Codex rotation ring
Selection->>Candidates: eligible accounts and pool scope
Candidates->>Usage: check usage against effective threshold
Usage-->>Candidates: headroom status
Candidates-->>Selection: headroom accounts or full eligible list
Selection->>Ring: preview or pick from candidates
Possibly related issues
- lidge-jun/opencodex#3376: This change adds quota-aware account preference to Codex placement. Reset-based ordering and other scheduling inputs are not described in the changes.
Suggested reviewers: luvs01, lcxhh521
Merge Risk: 
Minimal · up to 94588
-
The routing behavior matches the stated contract, including manual selections and Reserve scope handling; no merge-blocking issue was identified.
Pre-merge checks: 
4 · 
1
-
Failed checks: 1 warning Passed checks: 4 passedFull details: Docstring Coverage
-
Explanation
Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 6 functions across 3 files. (8 skipped: 8 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
-
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.
Manual selection seeds the round-robin ring so the next placement lands on the chosen account. The headroom preference dropped an over-threshold selection from the candidates, which cleared that seed. Keep the scope's unspent manual selection in the list; once a dispatch on it succeeds the selection is spent and the headroom preference applies again. Docs: translated quotaWindow rows now say per-account weekly bars come from usage probes or observed response headers, matching English.
Manual selection seeds the shared ring and each independent quota-scope ring, but recorded the one-shot preference for the shared scope only, so the round-robin headroom preference dropped an over-threshold selection from the next Reserve placement. Record the one-shot per seeded scope and clear it with the seeds on release. Only the shared one-shot guards the shared active cursor; a successful dispatch in a scope spends that scope's one-shot.
…lection under round-robin
|
Maintainer integration into Exact-head verification for
|
…adroom Adopted from upstream lidge-jun/opencodex 52dd19f (Refs lidge-jun#8092). Agent-Session: e8a31e5f-e03f-48f3-93e6-06bfe45e7916
Summary
Codex
accountPoolStrategy: "round-robin"rotated new conversations by count alone. A fresh conversation could therefore bind to an account already at 95%, and when that account ran out the conversation had to move to another account and rebuild its prompt cache from cold.New round-robin placements now skip accounts at or over their effective
autoSwitchThresholdwhile any eligible account is still under it. Example: with accounts at 95% / 10% / 10% and the default threshold of 80, new conversations alternate between the two 10% accounts; once every account is at or over its threshold, rotation covers all three exactly as before.src/codex/routing/selection.ts:roundRobinPlacementCandidatesnarrows the eligible list before the ring, for the committed pick and the preview peek alike, so preview still names the account resolve takes. It useshasCodexQuotaHeadroom, the score fill-first and the priority tier already use (per-account override, use-remaining = 0, hottest known weekly/30-day window refined by an unexpired short window; a threshold of 0 and unknown usage count as headroom). It is a preference, never eligibility.src/codex/routing/active-account.tsnow also records the one-shot per seeded scope (and clears it with the seeds on release), so Reserve honours it too. Only the shared one-shot guards the shared active cursor, as before.anthropicAccountPoolquotadescription. It does not simply rank accounts byquotaWindow: it keeps the active account until its usage reachesautoSwitchThreshold(default 80) or it cannot serve, then moves to the least-used account, preferring accounts still under their own threshold.structure/providers/codex-round-robin-placement.md(new, ownssrc/codex/routing/selection.ts), linked from the per-account thresholds section ofopenai-accounts.md.Note for reviewers: Claude round-robin does not read
autoSwitchThresholdfor new sessions (it only skips model-exhausted accounts); this PR leaves Claude routing unchanged and models the Codex rule on Claude's replacement picker ("prefer under threshold, fall back when none").Verification
tests/codex-integration/codex-round-robin-headroom.test.ts(19 cases). Against unchangedselection.tsat 6f1d3e6: 9 fail / 8 pass (placement skip, at-threshold edge, unknown usage, preview agreement, Reserve ring, sticky release, re-entry, cooldown re-placement, priority tier). With the change: 19 pass / 0 fail. The 8 that pass on both are boundary pins (all-over fallback, per-account and zero thresholds, short-window guard, bound conversation stays, failover order, model roster, lineage). The two manual-selection cases (shared, Reserve) were added for review findings; each fails when its fix is removed, and the Reserve case also fails if a shared success spends the Reserve one-shot.codex-installation-live-wshas timing failures (6-11s upgrade cases) on this loaded host that reproduce with baseselection.ts/active-account.tsrestored.bun run typecheck,bun run privacy:scan,bun run structure:check,bun scripts/file-size-ratchet.ts: pass.cd docs-site && bun install --frozen-lockfile && bun run build: 633 pages, 91,473 internal links checked, pass.bun scripts/test.ts --changed=dev --parallel=1at 1e647f0: NOT COMPLETE. The changed set selected the bulk of the suite (the diff reaches docs, structure and test-layout data); on this shared, loaded host (load average ~5, other lanes testing) it hit the runner's 900s cap after 16,311 pass / 0 fail across ~754 files, terminating insidetests/server/server-live-cancel.test.ts. That file fails 2/2 when run alone here with or without this change (verified by restoring the baseselection.ts), so it is a host-timing issue, not a regression. The remaining coverage is theci:fullUbuntu shards (test 1/4 to 4/4) on this PR.ci:fulllabel: the change reaches test-layout maps, the structure manifest and docs pages, which tests read as data.Checklist
Summary by CodeRabbit