fix(codex): expose bounded main quota refresh diagnostics

[Ingwannu]

Summary

• Address the diagnostic portion of [Bug]: Healthy ChatGPT Plus Codex login reports plan: null / quota: null and hides 5h/weekly usage #3644: main-account WHAM failures currently collapse to null plan/quota even when the native credential is usable.
• Add an ephemeral, generation-checked quotaRefresh outcome to the account API and opt-in account quota JSON. The outcome contains a fixed status and, only for HTTP errors, a numeric HTTP status. The CLI reconstructs this shape instead of copying arbitrary management response fields.
• Keep credential selection, authentication, admission, quota freshness, cache behavior, account rotation and persistence unchanged. Cache-only/deferred/invalidated results do not claim a new quota probe. Document the contract and decision rationale.

This does not fix or close the reporter's underlying Windows/WHAM failure. It supplies the missing diagnostic needed to identify that failure. It is also separate from the local Astra stream-failure investigation.

Verification

• Bun 1.4.0 targeted tests in fresh temporary HOME, OPENCODEX_HOME and CODEX_HOME: 21 pass, 0 fail, 50 assertions. Covers HTTP 401/403/429/503, fetch failure, response-body reset, malformed JSON, missing quota, timeout, fresh/cache distinction, existing terminal-auth behavior, CLI opt-in output, invalid diagnostic rejection and secret-canary omission.
• TypeScript: bun node_modules/typescript/bin/tsc --noEmit passes.
• Documentation build via the installed Astro CLI: 425 pages pass; existing chunk-size and missing 404-content warnings remain.
• Repository privacy scan and staged diff whitespace check pass.
• Dependency reuse was limited to an existing install with matching root and docs lockfile SHA-256s. All test/build homes were isolated; the five protected live runtime configuration files are unchanged.
• Full repository suite, exact-head hosted CI and independent maintainer security review are still required. This PR is deliberately draft, not review-ready, approved, merged or deployed. No live restart or runtime settings change occurred.

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

[github-actions]

✅ Deterministic PR hygiene checks passed.

[Ingwannu]

@lidge-jun #3644 관련 작은 진단 PR입니다.

쉽게 말하면, 지금은 로그인은 멀쩡해도 쿼터 조회가 실패하면 이유 없이 null만 나옵니다. 이 패치는 HTTP 오류인지, 타임아웃인지, 연결/응답 문제인지를 기존 API와 CLI JSON에 구분해서 보여 줍니다.

• 토큰·계정 식별자·원문 오류는 새 필드에 넣지 않습니다.
• 로그인, 계정 선택, 쿼터 차단, 캐시 정책은 그대로입니다.
• 집중 검사 21개, 타입 검사, privacy 검사, 문서 425페이지 빌드 통과했습니다.
• 아직 Draft입니다. 전체 CI와 독립 보안/코드 리뷰 후 판단해 주세요. 제가 작성한 PR이라 직접 승인/병합하지 않겠습니다.

제보자의 Windows 쿼터 조회 원인 자체나 #3657의 로컬 Astra 502를 해결했다고 주장하는 PR은 아닙니다. 실제 설정 파일과 실행 중인 데몬도 건드리지 않았습니다.

[lidge-jun]

리뷰 · 우선순위 63 / 80

설명

이 PR은 열린 #3644의 진단 조각입니다. ChatGPT Plus Codex 메인 로그인(__main__)은 살아 있는데 WHAM 사용량 조회가 실패하면 plan/quota가 null로만 보여, 로그인 실패·쿼터 소진·네트워크 오류를 구별할 수 없습니다. 지금 dev HEAD ba9a45570(package 2.43.0, 쿼터 패리티 스택 #3584→#3598→#3655 위에 있음)의 src/codex/auth-api.ts fetchMainAccountInfoWhileOwned()도 WHAM이 실패하거나 예외가 나면 EMPTY_MAIN_ACCOUNT_INFO만 돌리고, 실패 이유를 DTO에 안 남깁니다. 이 드래프트는 그 구멍을 메우기 위해 일회성 quotaRefresh 결과를 추가합니다. 상태 값은 ok / not_reported / http_error(+숫자 HTTP 상태) / timeout / network_error / invalid_response / internal_error로 고정되어 있고, 원문 응답·에러 메시지·자격 증명은 넣지 않습니다.

변경은 좁습니다. 새 파일 src/codex/quota-refresh-outcome.ts가 타입과 CLI 쪽 투영(projectCodexQuotaRefreshOutcome)을 담당하고, auth-api.ts는 WHAM 시도가 실제로 나갔을 때만 결과를 붙이며 캐시 재사용·자격 유예·무효 스냅샷에서는 필드를 생략합니다. src/cli/account-api.ts는 --quota일 때만 같은 어휘로 다시 복사해, 관리 API가 이상한 필드를 실어도 CLI가 삼키지 않게 합니다. 문서(providers-accounts.md, structure/05_gui-and-management-api.md)와 테스트(HTTP 401/403/429/503, fetch 실패, 본문 리셋, JSON 깨짐, timeout, fresh/cache 구분, 시크릿 카나리 미포함)가 같이 들어 있습니다. 인증·admission·쿼터 신선도·캐시·로테이션·영속화는 건드리지 않는다고 본문에 적혀 있고, 코드 모양도 그 약속과 대체로 맞습니다. Windows/WHAM 원인 수정이나 풀 계정 진단, GUI 막대 복구는 범위 밖입니다. 작성자도 드래프트·exact-head CI 전이라고 명시했습니다.

이 방향은 #3644에 남긴 grok-bot 리뷰(민감정보 없는 WHAM 카테고리 먼저)와 같고, 지금 dev가 밀고 있는 제공자 쿼터 관측 스택과도 잘 맞습니다. 다만 제품 쿼터 API(src/providers/quota*.ts)나 GUI QuotaBars에는 아직 연결되지 않아서, 머지되어도 대시보드 막대는 null이면 계속 숨겨질 수 있습니다. 그건 의도된 1단계로 보이며, 원인 수정 PR과 섞지 않는 편이 안전합니다.

라인 src/codex/auth-api.ts WHAM !resp.ok 반환 - HEAD에서는 EMPTY만 돌리던 자리에 quotaRefresh: { status: "http_error", httpStatus }를 붙인다. 터미널 인증 실패 시에만 reauth 하는 기존 규칙은 유지된다. 좋지만, 401/403이 diagnostic이면서도 대시보드 문구가 “쿼터 없음”으로만 보이면 사용자 혼란이 남을 수 있다(문서에 로그인≠WHAM 성공을 적어 둔 것은 맞다).
라인 catch 분류(quotaPhase) - request/body/decode/publish 단계로 timeout·network·invalid_response·internal_error를 나눈다. publish 단계 예외는 드물고 internal_error로 뭉쳐진다. 캐시 기록 실패까지 같은 버킷인 점은 감수할 만하다.
경로 src/cli/account-api.ts - includeQuota일 때 projectCodexQuotaRefreshOutcome로만 복사한다. 잘못된 status/httpStatus는 필드 자체가 빠진다. 테스트가 카나리를 잠근 것은 좋다.
경로 quota-refresh-outcome.ts - 주석대로 admission/entitlement 증거로 쓰지 말 것. 다른 PR이 이 값으로 로테이션을 돌리기 시작하면 계약이 깨진다.
경로 GUI / pool - 메인 계정 진단만이다. 풀 계정 WHAM·ProviderAccountQuota UI는 여전히 null만 본다. #3644 UI 증상은 이 PR만으로 안 사라질 수 있다.
드래프트·CI - 작성자가 exact-head 전체 CI와 보안 리뷰를 아직이라고 했다. resolve-pr/label/hygiene만 초록인 상태로는 admin merge하지 말 것.

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

• 드래프트를 Ready로 올린 뒤 exact-head CI 초록이면 [Bug]: Healthy ChatGPT Plus Codex login reports plan: null / quota: null and hides 5h/weekly usage #3644 진단 1차로 머지할지, GUI에 카테고리 표시까지 한 PR에 묶을지
• 풀 계정 진단도 같은 quotaRefresh 어휘로 이어서 받을지, 메인만 고정할지
• http_error 401/403을 대시보드 노트에 어떻게 보여줄지(재로그인 유도 vs “사용량 조회만 실패”)
• 머지 후 #3644를 부분 진행으로 둘지, 진단 이슈를 분리 클로즈할지

너의 추천
방향은 받고, Ready + exact-head CI 초록 전에는 머지하지 않는다. 범위는 진단만 유지하고 GUI 채우기·plan 추측·null→0·강제 reauth는 거부한다. CI 통과 후 메인 진단으로 머지하고, #3644는 리포터의 실제 quotaRefresh 값을 받은 뒤 원인 수정 PR을 별도로 받는다. 아스트라 스트림 이슈 #3657과 묶지 말 것.

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

[lidge-jun]

Implemented by #3693 and merged into dev as 71edeec8807d99e8e56a8c093f74da27d163d47a. Original author attribution is preserved. Current-head hosted CI and independent security review passed; remote focused verification: 554pass/0fail. Dev ancestry confirmed before closing.

[lidge-jun]

Landed via #3693 at 71edeec