feat(codex): estimate observed effective quota capacity

[lidge-jun]

Summary

• Estimate observed effective token capacity from same-source, same-reset account quota intervals and reported single-send usage attempts. Results contain a median, interval sample count and explicit low confidence; they are not provider token limits or routing inputs.
• Reject ambiguous duplicates, missing physical-attempt evidence, estimated/local/multisend usage and independent-model quotas. Preserve local-answer provenance in usage normalization. Bound ledger work and fence the asynchronous read against account publication and label changes.
• Extend the cached history API/CLI while preserving history when capacity evidence is unavailable. --limit limits displayed observations, not estimator input. [Feature]: retain quota history and make reset windows a scheduling input (capacity estimation, reset ordering, automatic activation) #3376 remains open for final cumulative execution and broader acceptance.

Ordinary manual chain: #4375 (identity) → #4404 (history) → this PR (capacity). Review this layer only; integration remains parent-coordinated.

Verification

• Local suites of every size, builds, typecheck and install: NOT RUN, per explicit maintainer instruction. Hosted CI validates the final cumulative tip.
• git diff --check and staged whitespace checks passed (source text only).
• Independent source-plan audit passed. Full implementation source/security review passed at 8845f63cc57b445089b6874467612a7256244139 after model-scope, insufficient-evidence display and rounding corrections; hosted runtime verification remains pending.
• Added hand-calculated capacity, interval/provenance/reset, duplicates, bounded scan, local/estimated usage, populated API and async identity-change regression coverage.

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.

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

[lidge-jun]

리뷰 · 우선순위 58 / 80

이 PR은 Codex 계정 로드맵의 용량(capacity) 층입니다. 부모 체인 #4375(게시 신원) → #4404(원본 관측 이력) 위에 올라가고, 베이스는 dev가 아니라 #4404 브랜치(codex/260912-60plus-accounts-history)입니다. 지금 dev HEAD는 7bfb2ad8a이고, 방금 #4403으로 status 포트 픽스처 플레이크를 고친 뒤 #4405로 패키지 버전을 2.53.0으로 열어 둔 상태이며, main에는 #4407로 검증된 2.52.0 트리가 이미 올라갔습니다. 그래서 이 PR은 “지금 당장 릴리스를 막는 버그”가 아니라, 이미 dev에 있는 쿼터 회피 열차와 나란히 가는 accounts 후속 기능입니다.

하는 일은 짧습니다. src/codex/quota-capacity.ts가 같은 소스·같은 reset 구간의 인접 관측을 짝짓고, 그 구간 안에 통째로 들어 있는 단일 전송(reported, non-estimated, non-local) 시도의 토큰을 모아 관측토큰 * 100 / 퍼센트델타로 창별 유효 용량을 추정합니다. 결과는 중앙값·표본 수·confidence low와 가정 목록만 붙고, 계정 선택·라우팅 입력으로는 쓰지 않습니다. GET /api/codex-auth/quota/history와 ocx account history가 이 추정을 붙이되, --limit은 화면에 보여줄 관측 수만 자르고 추정 입력은 보관된 전체 관측을 씁니다. 원장 읽기 전후에 publication UUID와 유일 logLabel을 다시 보고, 바뀌면 identity_changed로 추정을 버리고 이력만 갱신합니다. src/usage/log.ts는 locallyAnswered를 정규화에 남겨 로컬 응답이 표본이 되지 않게 합니다. 이 설계는 현재 dev의 structure/providers/openai-tiers.md 쿼터·이력 계약과 맞닿아 있고, “관측이 없으면 0이 아니라 근거 부족”이라는 기존 문구와도 같습니다.

라인별·경로별 문제는 아래입니다.

src/codex/quota-capacity.ts (요청/시도 중복 판정) - 같은 requestId/ordinal을 JSON.stringify로 비교합니다. 키 순서가 달라지면 내용이 같아도 ambiguous_usage로 떨어져 추정이 통째로 거절될 수 있습니다. 의도된 fail-closed라면 주석으로 고정하고, 아니면 필드 단위 비교로 바꾸는 편이 안전합니다.
auth-api history 핸들러 - 이 브랜치는 #4404 위에만 있으므로 dev에 단독 머지하면 history API·poolQuotaHistoryIdentity·관측 스토어가 없어 깨집니다. #4375 → #4404 → 이 PR 순으로만 올리는 것이 맞습니다.
structure/*.md 여러 파일 - 용량 추정 문단이 catalog.md, runtime.md, config.md, codex-home.md, gui-and-management-api.md, subagents.md, clients/claude-desktop.md, ops/docs-and-release.md에 거의 똑같이 복붙되어 있습니다. SSOT는 openai-tiers.md의 Observed effective token capacity 절이면 충분해 보이고, 나머지 파일 복붙은 이후 머지 충돌만 키웁니다.
PR checklist - Security-sensitive 항목이 아직 체크되지 않았고, 로컬 suite/build/typecheck/install은 메인테이너 지시로 NOT RUN입니다. hosted CI와 구현 소스 리뷰가 남아 있다는 본문 말과 같습니다.
#3376 - 본문이 최종 누적 실행·더 넓은 수용은 #3376에 남겨 둔다고 했습니다. 이 PR만으로 “용량 기능 완료”로 닫으면 안 됩니다.

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

• #4404를 먼저(또는 함께) dev에 올릴지, 용량 층을 쌓아 둔 채 history만 먼저 검증할지
• structure 문서 복붙 여덟 곳을 이번 PR에서 걷어 openai-tiers.md만 남길지
• JSON.stringify 중복 판정을 fail-closed로 공식 계약으로 둘지, 필드 비교로 바꿀지
• 보안/구현 소스 리뷰를 머지 전에 필수 게이트로 둘지 (체크리스트 미완료)

너의 추천
#4404가 dev에 안착하기 전에는 이 PR을 dev에 단독 머지하지 마세요. history 층 검증 후 체인으로 올리고, structure 복붙은 openai-tiers.md SSOT만 남기도록 줄이는 편이 좋습니다. JSON.stringify 비교는 주석으로 계약을 박거나 필드 비교로 고친 뒤, 보안 체크리스트와 hosted CI가 통과하면 머지하세요. #3376은 열어 두세요.

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

[github-actions]

✅ Deterministic PR hygiene checks passed.