fix(combos): one Anthropic account's 402 credit refusal cools the account, not the combo target

[vadymhimself]

Summary

• Depends on fix(combos): a spent generic OAuth account cools the account, not the combo target #7191. This branch is stacked on fix(combos): a spent generic OAuth account cools the account, not the combo target #7191's head (fix/combo-pool-account-cooldown-all-pools) because both edit the same failedAccount block in src/server/responses/core-combo.ts. Review or merge fix(combos): a spent generic OAuth account cools the account, not the combo target #7191 first; until then this diff also shows fix(combos): a spent generic OAuth account cools the account, not the combo target #7191's commit.
• Follow-up to fix(combos): a spent pool account must not cool the whole target (carry #6234) #6255 / fix(combos): a pool-held 429 must not park the combo target past the pool #6383, which stopped one identified Anthropic OAuth account's 429 from cooling the combo target. A 402 had no such scoping.
• The Anthropic OAuth pool rotates only on 401/403/429 (rotateAnthropicAccountOnResponseForInstance, and the dispatch loop that calls it), so a 402 carrying the credit-balance refusal reaches the combo layer with that account still selectable. comboFailureCooldownScope classifies 402 as provider-scoped, so every anthropic/* target in the combo cooled for the full cooldown. Traffic went to the fallback target, or got a zero-attempt 503, while a sibling account still answered. Reproduced on clean dev (60bf4c7) with the new test: isComboTargetInCooldown is true after account A's 402, and A has no pool health entry.
• Fix: when the failed child identifies exactly one pool account (the same formatAnthropicProviderForLog label match that cooledPoolAccountLabel uses) and the failure carries the exact credit-balance refusal (isAnthropicBillingFailure, the evidence failover.ts already reads), core-combo.ts records that account's refusal through the pool's own recordAnthropicAccountRefusal. It records it as 403, the entitlement backoff a 403 credit-balance refusal already gets. The combo then names the account only while getEligibleAnthropicAccounts is non-empty. resolve.ts treats a named-account 402 like the named-account 429: it records no target cooldown.
• Unchanged: a lone account (the pool's quorum guard refuses to record), an exhausted pool, an unidentified account (stock config with the pool flag off, before any rotation), API-key providers, Codex/generic OAuth 402s, and any 402 without the exact credit-balance wording all keep the provider-scoped cooldown. Nothing under src/oauth/ changes.

Verification

• Red/green: bun test tests/adapters/anthropic/anthropic-combo-account-cooldown.test.ts. The new 402 test fails on clean dev 60bf4c7 (target cooled) and passes here 5/5 runs. The added exhausted-pool test fails if the sibling-eligibility guard is removed (mutation-checked).
• bun run typecheck: clean.
• bun run structure:check: passed. structure/runtime.md documents the 402 case next to the fix(combos): a spent generic OAuth account cools the account, not the combo target #7191 text.
• bun run privacy:scan: passed.
• bun run test:changed (the core-combo graph covers 1739 files): 38223 pass, 27 fail, 3 errors. Every failure is in tests/cli/cli-access-audio-live, cli-connect-readiness, ocx-launcher-runtime, codex-integration/codex-runtime, native-codex-toggle, native-grok-toggle, and tests/service/*. Rerun in isolation, those 9 files give the identical 7 failures on clean dev and on this branch. The rest are load-dependent under the full parallel run. No combo, routing, or Anthropic test fails.
• The full bun run test has not been run locally.

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.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Improved combo failover for account-specific failures: eligible OAuth accounts returning 429 and Anthropic accounts with credit-balance errors can be skipped while other accounts remain available.
  • Combo targets are cooled when no eligible account remains, helping subsequent requests follow the appropriate fallback behavior.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

[vadymhimself]

@coderabbitai review

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: a5e0a666-5f39-4cd3-98e8-e8ea0a551b91

📥 Commits

Reviewing files that changed from the base of the PR and between 60bf4c7 and 223b855.

📒 Files selected for processing: 8

• scripts/test-layout/layout.json
• src/combos/resolve.ts
• src/server/responses/core-combo.ts
• structure/runtime.md
• tests/adapters/anthropic/anthropic-combo-account-cooldown.test.ts
• tests/fixtures/test-layout-expected.json
• tests/oauth/generic-oauth-combo-account-cooldown.test.ts
• tests/oauth/generic-oauth-failover.test.ts

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

Combo failure handling now identifies qualifying account-level failures for generic OAuth 429 responses and Anthropic OAuth credit-balance 402 responses. It records account refusals and applies combo-target cooldowns based on whether an eligible sibling account remains.

Changes: Combo Account Cooldown Handling

Layer / File(s)	Summary
Account failure attribution and rotation src/server/responses/core-combo.ts, src/combos/resolve.ts	Failure classification records qualifying Anthropic OAuth 402 refusals and rotates a uniquely identified generic OAuth account for target-scoped 429 responses. Account-scoped failure handling now includes identified-account 402 responses.
Cooldown tests and runtime contract tests/oauth/generic-oauth-combo-account-cooldown.test.ts, tests/adapters/anthropic/anthropic-combo-account-cooldown.test.ts, tests/oauth/generic-oauth-failover.test.ts, structure/runtime.md, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json	Tests cover generic OAuth 429 rotation and Anthropic OAuth 402 refusals when a sibling account is or is not eligible. The runtime contract and test-layout mappings are updated.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant CoreCombo as core-combo
  participant OAuthPool as Generic OAuth account pool
  participant Fallback as Fallback target
  Client->>CoreCombo: Send combo request
  CoreCombo->>OAuthPool: Request through selected account
  OAuthPool-->>CoreCombo: Return target-scoped 429
  CoreCombo->>OAuthPool: Rotate failed account using Retry-After
  OAuthPool-->>CoreCombo: Identify eligible sibling or no sibling
  CoreCombo->>Fallback: Continue when the selected target fails
  Fallback-->>Client: Return fallback response

Loading

Suggested reviewers: lidge-jun

Merge Risk: ⚪ Minimal · up to 223b8

This change handles account-level credit refusals and generic OAuth rate limits more precisely in combos. No concrete merge-blocking risk was identified in the supplied context.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 5 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the primary Anthropic OAuth 402 account-refusal behavior. It matches the implemented change and does not need to mention the additional generic OAuth 429 hand…

Full details: Docstring Coverage

Explanation

Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 5 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• 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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[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

• ⬜ Required local validation passed; commands, results, and any full-suite exception are documented.
• ⬜ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
• ⬜ 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.
@vadymhimself Tick the boxes once required local validation has passed with commands, results, and any full-suite exception documented, your branch is on the latest dev commit, and every correct Codex and CodeRabbit finding is resolved.

[lidge-jun]

Being carried into #7224 with your authorship preserved; this PR will be closed when the bundle lands.

[lidge-jun]

Landed on dev in 6ccb47a via #7224 (your change is its own commit in that bundle, and the squash keeps your authorship as Co-authored-by). Thank you!