fix(usage): verify OAuth rotation before withheld attribution

[luvs01]

Motivation

• Budget-refusal telemetry could report rotation-send-budget even when no alternate OAuth account was immediately eligible because the quorum check ignores per-account cooldowns.
• This produced ambiguous audit logs for 429-driven recoveries in the continuation, passthrough and run-turn paths and needed a non-mutating, cooldown-aware availability check.

Description

• Add hasEligibleGenericOAuthFailoverTarget(...) to src/oauth/generic-account-failover.ts to answer whether a model-family-aware alternate exists right now without mutating health state.
• Gate noteAttemptRecoveryWithheld(...) on that check in the continuation, passthrough, and run-turn paths so the withheld reason is only emitted when a real failover target exists.
• structure/transports/responses.md documents the cooldown-aware gate.
• Regression coverage in tests/oauth/generic-oauth-failover.test.ts asserts the withheld reason is suppressed when every alternate is in cooldown.

Testing

• bun test tests/oauth/generic-oauth-failover.test.ts: 47 tests pass.

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/oauth/generic-account-failover.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/oauth/generic-account-failover.ts.
• Tick all four boxes in the PR description once you're done (currently 0/4).

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.

0/4 boxes ticked.

This pull request was already a draft. Its draft status will be preserved after every issue above is resolved.
@luvs01 Tick the boxes once your local CI is green, your branch is on the latest dev commit, and every correct Codex and CodeRabbit finding is resolved.

[lidge-jun]

리뷰 · 우선순위 40 / 80

이 PR은 429 로그의 한 줄을 고칩니다. 계정 교체를 못 했을 때, 지금은 “계정이 두 개라서 바꿀 수 있었는데 이번 요청의 전송 한도가 막았다”(rotation-send-budget)고 적는 경우가 있습니다. 그런데 그 “두 개” 판정은 쿨다운을 무시합니다. 다른 계정이 잠시 쉬고 있어도 같은 로그가 남아서, 한도 때문에 못 바꾼 건지 지금 당장 쓸 계정이 없는 건지 구분이 안 됐습니다.

새 함수 hasEligibleGenericOAuthFailoverTarget은 기록을 바꾸지 않고, 지금 이 모델에 바로 넘길 다른 계정이 있는지만 답합니다. continuation, passthrough, run-turn 세 군데에서 그 답이 참일 때만 위 로그를 남깁니다. 계정을 실제로 바꾸는 동작은 그대로입니다. 설명 문서 한 줄이 추가됐습니다.

라인 tests/oauth/generic-oauth-failover.test.ts hasEligibleGenericOAuthFailoverTarget("xai", ids[1]!) - “다른 계정이 쿨다운이면 false”만 검사합니다. “다른 계정이 지금 쓸 수 있으면 true”는 없습니다. 함수가 항상 false여도 이 테스트는 통과하고, 그러면 한도 때문에 못 바꾼 정상 경우의 로그까지 사라집니다.
라인 같은 파일 budget-withheld attribution proves a cooldown-eligible generic OAuth target - 여러 파일을 이어 붙인 소스에서 함수 호출이 세 번인지만 셉니다. 그 호출이 noteAttemptRecoveryWithheld를 감싸는지는 안 봅니다. 함수를 호출하고도 로그를 항상 남겨도 테스트는 통과합니다.

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

로그 약속은 “이유가 없으면 지금 바꿀 대상이 없다, rotation-send-budget이면 대상은 있었는데 한도가 막았다”입니다. 이 PR은 쿨다운 중인 다른 계정을 “대상 없음”과 같은 칸으로 넣습니다. 운영자가 “둘째 계정은 있지만 쉬는 중”을 따로 보고 싶으면, 이유를 지우지 말고 다른 이유 문자열이 필요합니다. 이 파일은 인증 표면이라 hygiene가 maintainer-sponsored를 요구합니다. PR은 아직 Draft이고 체크리스트는 0/4입니다.

너의 추천

true 케이스를 단위 테스트로 하나 넣고, 세 호출부가 로그를 조건으로 감싸는지 소스 검사도 그 if에 붙이세요. 셋째 이유 문자열이 필요 없다고 확인되면, 스폰서 라벨과 체크리스트를 채운 뒤 Ready로 올리면 됩니다. types.ts/config.ts 분할이나 미리보기 배포와는 관계없습니다.

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

[luvs01]

Review feedback applied on f6778bfb70:nn- Added the positive unit case: with two uncooled accounts, hasEligibleGenericOAuthFailoverTarget returns true from either side - an always-false implementation can no longer pass silently.n- The source assertion now also requires each of the 3 call sites to wrap noteAttemptRecoveryWithheld in the eligibility condition, not merely call the function nearby.nnOn the third reason string: not needed - cooled-alternate is already visible via genericFailoverRetryAfterSeconds and the existing enabled-quorum log; the review question is answered by keeping the two-state attribution.nnTests: generic-oauth-failover48 pass. Note: this file touches the auth surface, so themaintainer-sponsored` hygiene label is still required before ready.

[lidge-jun]

Carried in #5608: both commits are cherry-picked with authorship kept, plus a follow-up that gives the eligibility probe the same live two-account roster guard rotation uses, with a regression test. Closing as superseded. Thank you @luvs01.