Skip to content

fix(codex): place round-robin conversations on accounts with quota headroom - #8092

Merged
lidge-jun merged 5 commits into
devfrom
fix/codex-round-robin-headroom
Nov 2, 2026
Merged

lidge-jun merged 5 commits into
devfrom
fix/codex-round-robin-headroom

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

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 autoSwitchThreshold while 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: roundRobinPlacementCandidates narrows the eligible list before the ring, for the committed pick and the preview peek alike, so preview still names the account resolve takes. It uses hasCodexQuotaHeadroom, 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.
  • An operator's unspent manual selection stays in the candidates whatever its usage, so the ring's manual-selection seed still lands the next placement on the chosen account; once a dispatch on it succeeds the selection is spent and the headroom preference applies again. Manual selection already seeded the shared ring and each independent quota-scope ring (Reserve); src/codex/routing/active-account.ts now 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.
  • Unchanged by design: bound conversations keep their account past the threshold (round-robin never re-scores a live binding) and move only on cooldown, quota refusal, failover or pause; failover alternates keep plain ring order; a child of a live conversation still starts on its parent's account; idle-window steering already required headroom.
  • Per-scope pools hold: the ring and sticky count stay keyed per quota scope (Reserve), the narrowing runs after model-roster and priority-tier eligibility, and a sticky account that crosses the threshold is released for the next placement.
  • Docs (en, fr, ja, ko, ru, tr, zh-cn, zh-tw): document the Codex rule, and correct the Claude anthropicAccountPool quota description. It does not simply rank accounts by quotaWindow: it keeps the active account until its usage reaches autoSwitchThreshold (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, owns src/codex/routing/selection.ts), linked from the per-account thresholds section of openai-accounts.md.

Note for reviewers: Claude round-robin does not read autoSwitchThreshold for 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

  • New tests/codex-integration/codex-round-robin-headroom.test.ts (19 cases). Against unchanged selection.ts at 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.
  • Focused routing suites (codex-pool-rotation, codex-account-threshold-routing, codex-routing, codex-idle-window, codex-priority-failback, codex-use-remaining-quota, codex-preserve-signed-in, codex-pool-request-owned-main, codex-auth-context, codex-auth-api, codex-lineage-placement, codex-routing-cache-affinity-detour, test-layout guards) at c23b74d: 926 pass / 0 fail. Other files touching manual selection (codex-account-delete-atomicity, cli-account, codex-auth-release, codex-installation-sidecars, codex-account-threshold-auth/api, context-history-ownership): pass; codex-installation-live-ws has timing failures (6-11s upgrade cases) on this loaded host that reproduce with base selection.ts/active-account.ts restored.
  • 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=1 at 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 inside tests/server/server-live-cancel.test.ts. That file fails 2/2 when run alone here with or without this change (verified by restoring the base selection.ts), so it is a host-timing issue, not a regression. The remaining coverage is the ci:full Ubuntu shards (test 1/4 to 4/4) on this PR.
  • Review: Terra code review rounds 1-3 and CodeRabbit findings addressed in follow-up commits (docs preference wording; manual-selection seed; Reserve one-shot; locale weekly-bar sentence; test strengthening). Codex review: no findings.
  • ci:full label: the change reaches test-layout maps, the structure manifest and docs pages, which tests read as data.

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.

Summary by CodeRabbit

  • New Features
    • Codex round-robin placement now prefers eligible accounts below their effective usage thresholds. If none have headroom, placement rotates across all eligible accounts. Unspent manual selections remain preferred, and existing conversation bindings are unchanged.
  • Documentation
    • Clarified Codex account rotation and threshold behavior, and updated guidance on Anthropic quota-based account selection and usage windows.

…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.
@lidge-jun lidge-jun added the ci:full Run the four full Ubuntu test shards on this pull request label Nov 2, 2026
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 2, 2026 07:51
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-02T07:53:26.431621Z 1e647f0 PR opened
ℹ️ 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

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the bug Something isn't working label Nov 2, 2026
@coderabbitai

coderabbitai Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent review info
Run configuration
Commits

Reviewing files that changed from the base of the PR and between 9903b03 and 945882a.

Files selected for processing: 8
  • docs-site/src/content/docs/fr/reference/configuration/providers.md
  • docs-site/src/content/docs/ja/reference/configuration/providers.md
  • docs-site/src/content/docs/ko/reference/configuration/providers.md
  • docs-site/src/content/docs/reference/configuration/providers.md
  • docs-site/src/content/docs/ru/reference/configuration/providers.md
  • docs-site/src/content/docs/tr/reference/configuration/providers.md
  • docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
  • docs-site/src/content/docs/zh-tw/reference/configuration/providers.md

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

Walkthrough

Codex round-robin placement now prefers eligible accounts below their effective usage threshold when any have headroom. If none do, placement uses the full eligible list. Preview and committed picks use this rule, while bindings and failover selection remain unchanged. Tests and documentation cover placement boundaries and provider-pool guidance.

Changes: Codex placement and provider guidance

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
Loading

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: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning 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. Documenta… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main change: Codex round-robin conversations now prefer accounts with quota headroom.
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.
Full 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.

Share

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix comments: Fix CodeRabbit comments on this PR

Comment thread src/codex/routing/selection.ts Resolved
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.

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix comments: Fix CodeRabbit comments on this PR

@lidge-jun

Copy link
Copy Markdown
Owner Author

Maintainer integration into dev (MAINTAINERS.md maintainer-integration exception), requested by @lidge-jun. This is integration, not a self-approval or an independent review.

Exact-head verification for 945882a51:

  • Every reported check passed on this head, including gates and the four ci:full Ubuntu test shards.
  • The Codex review completed with no unresolved findings. All three CodeRabbit review threads were addressed and resolved; the manual-selection candidate and locale wording fixes are in 0b0b51a55, and a docs follow-up is in 945882a51.
  • Coordinator diff review: round-robin placement filters only NEW placements to accounts with headroom (hasCodexQuotaHeadroom), keeps the operator's unspent manual selection, falls back to the full eligible list, and leaves live bindings and failover untouched.
  • No authentication, credential, workflow, release or dependency change.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working ci:full Run the four full Ubuntu test shards on this pull request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant