feat(codex): prefer accounts near quota reset

[terrytan95]

Summary

Add the opt-in Codex-only reset-first account-pool strategy so usable quota whose 5-hour or weekly window resets soonest is consumed first. Existing eligibility, priority tiers, and the maximum-usage threshold run before reset ordering; ties or missing/elapsed reset evidence use lowest usage and stable pool order. Bound tasks retain affinity until the threshold or a failure requires a replacement, with matching preview and failover selection.

The dashboard, CLI help, management API, config type, and configuration docs expose the strategy. Threshold 0 preserves reset ordering while disabling usage filtering; if every eligible account exceeds the threshold, the existing best-effort lowest-usage fallback remains. Default strategies and Anthropic routing are unchanged; there are no dependencies or migrations.

Closes #4079. Related to the ordering portion of #3376 and #2874 / #2881. This is a narrower alternative: Codex only, minimum of the future 5-hour and weekly resets, no latest-first direction, history storage, capacity estimation, or Anthropic expansion. It does not close the broader umbrella issue.

Verification

• bun run typecheck — passed.
• bun run test — passed: 21,962 pass, 40 skip, 0 fail across seven runner groups.
• bun test tests/codex-integration/codex-pool-rotation.test.ts — 74 pass, including dual-window order, threshold crossing, affinity, preview, failover, expiry, priority and disabled-threshold behavior.
• bun test tests/server/account-pool-management-api.test.ts — 22 pass; includes reset-first persistence and config reload.
• cd gui && bun test tests/account-pool-strategy.test.tsx tests/codex-account-auto-switch.test.tsx — 34 pass; after adding the reset-first rendering case, the strategy file separately passed all 14 tests.
• cd gui && bun run lint:i18n && bun run build — passed (existing bundle-size warning).
• cd gui && bun run lint — passed after removing the temporary browser preview entry.
• cd docs-site && bun install --frozen-lockfile && bun run build — passed, 425 pages.
• bun run privacy:scan and git diff --check — passed.
• Ego browser: rendered the actual strategy component in an isolated local preview and verified all four options, including the new selection and threshold explanation. No live account or credential state was changed.
• Full GUI test suite and maintainer security review remain pending for review readiness. No release or deployment performed.

GUI screenshot (isolated component preview):

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.

Remote gate: hygiene reports unsponsored_surface for src/codex/auth-api.ts; a maintainer must review it and apply maintainer-sponsored. Local validation is green.

Maintainer review is requested for the existing management route's expanded strategy validation; this change adds no endpoint, credential operation, or auth bypass. Contributor draft is intentional; no self-approval or merge is requested.

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.

[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

---

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/codex/auth-api.ts.

[github-actions]

⏳ DRAFT

• hygiene: unsponsored_surface.

What to do

• 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/codex/auth-api.ts.

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.

✅ 4/4 boxes ticked.

This pull request was already a draft. Its draft status will be preserved after every issue above is resolved.

[lidge-jun]

리뷰 · 우선순위 61 / 80

설명

이 PR은 Codex 계정 풀에 옵트인 전략 reset-first를 추가한다. 작성자 terrytan95, 브랜치 terry-quota-reset-first, base dev, Closes #4079. 로컬 dev HEAD 8026405d9(#4067, 2.49.0), 이번 웨이크 SHA 변동 없음. 약 +242/−38.

동작 요약. 이미 적격이고 autoSwitchThreshold 아래인 계정 중에서, 미래 5시간(shortResetAt)·주간(weeklyResetAt) 리셋 중 더 가까운 시각이 빠른 계정을 고른다. priority tier·health·threshold는 기존과 같고, 묶인 태스크는 threshold/실패 전까지 affinity를 유지하며, 교체·preview·failover도 같은 순서를 쓴다. 없거나 지난 리셋 증거는 순위에서 밀리고, 동률은 최저 usage → 안정 pool 순서. threshold 0이면 usage 필터만 끄고 reset 순서는 유지. 기본 전략(quota)과 Anthropic 라우팅은 그대로.

구현 축: pickResetFirstCodexAccount / resetFirstAffinityReplacement in src/codex/routing.ts, Codex 전용 parseCodexAccountPoolStrategy(parseAccountPoolStrategy는 reset-first를 거부 → OAuth Anthropic 관리 API도 거부), OcxConfig.accountPoolStrategy 타입만 | "reset-first" 확장, GUI는 codex prop일 때만 옵션 노출, CLI help·management API·8 locale 문서. #3376 우산(히스토리·capacity·Anthropic·latest 방향)은 닫지 않는 좁은 슬라이스이고 #2874/#2881과도 그 관계로 명시됨. types/config 대분할 무효화·중복 close 아님.

게이트: Draft + intake: hygiene-blocked. hygiene unsponsored_surface — src/codex/auth-api.ts. enforce-target fail. 기능 자체는 계정 풀 UX/스케줄링이라 스폰서 리뷰 부담은 #4081보다 가볍지만, 게이트 규칙은 동일하다.

라인 - 이게 무슨 문제다

게이트 unsponsored_surface (src/codex/auth-api.ts) - pool-strategy PUT이 reset-first를 받아들이도록 파서만 바꿨다. 동작 리스크는 낮아 보이지만 스폰서 라벨 없이는 Ready/머지 불가. Draft 유지가 맞다.

30일(monthlyResetAt) 창 미포함 - usage score는 5h/주/30d 중 hottest를 쓰는데, reset-first 비교는 5h+weekly만 본다. 이슈 #4079·본문이 의도한 좁은 계약이다. 다만 운영자가 “quota 바와 리셋 정렬이 어긋난다”고 느낄 수 있으니, GUI hint/문서에 30d는 순위에 안 들어간다는 한 줄을 넣는 편이 좋다.

비영어 locale 문서 - fr/ja/ko/ru/… providers.md에 reset-first 설명 문단이 영어 그대로 들어가 있다. 표의 전략 enum만 번역되고 본문 설명은 영어. i18n 일관성·docs lint 정책에 걸릴 수 있다. 각 locale 문장으로 옮기거나, 공통 영어 note 위치를 문서 규칙에 맞게 정리하자.

Math.min(...resets) empty - resets가 비면 Infinity라 “리셋 증거 없음” 계정이 증거 있는 계정과 섞이지 않는다. 전원 증거 없음이면 전부 Infinity로 묶여 최저 usage 폴백. 의과 맞다. 다만 주석에 “empty → Infinity, excluded from earliest unless all empty”를 한 줄 넣으면 다음 기여자가 실수하기 어렵다.

Affinity 교체 - threshold를 넘긴 뒤에야 reset 순으로 갈아탄다. quota 전략의 “더 시원한 계정으로 선제 이동”과는 다르다. 문서 hint(“bound tasks switch only at the threshold or on failure”)와 일치한다. 제품으로 OK.

OcxAccountPoolRotationStrategy를 직접 확장하지 않고 config 필드만 유니온 - Anthropic/OAuth 쪽이 공유 파서로 reset-first를 삼키지 않게 한 설계라 좋다. CLI는 서버가 검증하므로 anthropic에 reset-first를내면 400이 나와야 한다(기존 oauth-account-routes). 스모크로 한 줄 테스트가 있으면 더 안전.

메인테이너의 판단이 필요한 지점

• auth-api 표면을 maintainer-sponsored로 받을지(기능 리스크 vs 게이트 형식).
• #3376을 부분 close/추적 코멘트로 연결할지, #4079만 close로 둘지(본문은 #4079만 Closes — 유지 추천).
• 30d 리셋을 같은 열차에 넣을지 follow-up으로 둘지.
• 비영어 docs 영어 문단을 머지 조건으로 둘지.

너의 추천

#4079를 닫는 구현으로 방향이 맞다. 지금 당장 머지는 말고 스폰서 후 Ready. 다음 스텝: (1) 메인테이너 스폰서, (2) locale 영어 문단 정리 또는 번역, (3) 30d 제외를 UI/문서에 명시, (4) CI green 후 dev 독립 머지. #3376·#2874는 열린 채로 두고 “ordering 일부만 충족” 코멘트를 이슈에 남기면 충분하다. 2.49 tip 필수 슬라이스는 아니어서 61점.

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