Improve Claude OAuth 429 rate limit handling

[LeoLin990405]

Summary

• handle Claude OAuth usage HTTP 429 as a dedicated rate-limit error with actionable guidance instead of surfacing the raw JSON body
• add a small background backoff gate that respects Retry-After and lets user-initiated refreshes bypass stale cooldowns
• avoid invalidating cached Claude OAuth credentials on usage rate limits, while preserving existing auth invalidation for real auth errors

Related: #575

Testing

• swift build --target CodexBarCore
• swift build --product CodexBarCLI
• swift build --target CodexBarWidget
• git diff --check
• swift test --filter ClaudeOAuthTests (blocked before project tests run: local toolchain fails compiling KeyboardShortcuts #Preview macros with missing PreviewsMacros.SwiftUIView plugin)

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed May 27, 2026, 3:02 AM ET / 07:02 UTC.

Summary
The PR adds dedicated Claude OAuth HTTP 429 handling, Retry-After-backed background cooldown state, cache-preserving rate-limit errors, and focused Claude OAuth tests.

Reproducibility: yes. Source inspection shows a high-confidence current-main path where a 429 from the Claude OAuth usage endpoint falls through to generic serverError handling and then invalidates the OAuth cache; I did not run a live Anthropic 429 reproduction.

Review metrics: 3 noteworthy metrics.

• Diff size: 4 files changed, +173/-2. The diff is compact but touches the core Claude OAuth fetch path and provider tests.
• Persisted state: 1 UserDefaults key added. The new cooldown key can affect runtime behavior across app launches and upgrades.
• Latest checks: 3 in progress, 1 passed, 0 failed observed. Maintainers should wait for the latest pushed head to finish validation before merge.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Add redacted runtime proof showing the OAuth 429 guidance, cooldown behavior, credential preservation, and user refresh bypass after the fix.
• Let the latest-head checks finish and fix any failure they report.
• Have a maintainer confirm the persisted cooldown and cache-preservation policy before merge.

Proof guidance:
Needs real behavior proof before merge: The PR body lists builds and a blocked focused test run, but no after-fix app, CLI, terminal, log, recording, or linked artifact proof for the OAuth 429 path; the contributor should add redacted proof and update the PR body to trigger review, or ask a maintainer for @clawsweeper re-review if it does not rerun.

Risk before merge

• The PR intentionally changes Claude OAuth auth behavior by preserving cached credentials on 429 and adding a persisted global UserDefaults cooldown gate; maintainers should confirm that policy and scope before merge.
• The latest head was not fully validated at review time because three GitHub Actions checks were still in progress.
• The contributor has not added after-fix real behavior proof showing the 429 guidance, cooldown behavior, credential preservation, and user refresh bypass path in a real or controlled runtime setup.

Maintainer options:

1. Require latest-head OAuth proof (recommended)
   Ask for redacted app, CLI, terminal, log, recording, or linked artifact proof showing a Claude OAuth 429 now surfaces guidance, records or bypasses cooldown as intended, preserves credentials, and recovers on user refresh.
2. Accept the auth policy deliberately
   Maintainers can land the persisted cooldown and cache-preservation behavior if they explicitly confirm this is the intended Claude OAuth provider policy.
3. Narrow the cooldown scope first
   If the global persisted gate is too broad, revise it to a shorter-lived or more narrowly scoped cooldown before merging.

Next step before merge
Human-only: the remaining blockers are contributor-supplied real behavior proof, unsettled latest-head checks, and maintainer acceptance of the auth-cache/cooldown policy; no narrow code repair was found.

Security
Cleared: No concrete security or supply-chain regression was found; the diff adds no dependencies, scripts, secret handling, or broader permissions.

Review details

Best possible solution:

Merge a narrow Claude OAuth 429 fix after maintainers accept the cache/cooldown policy, the latest-head checks are green, and the PR includes redacted runtime proof of the changed behavior.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection shows a high-confidence current-main path where a 429 from the Claude OAuth usage endpoint falls through to generic serverError handling and then invalidates the OAuth cache; I did not run a live Anthropic 429 reproduction.

Is this the best way to solve the issue?

Yes, the proposed direction is narrow: classify 429 separately, show actionable guidance, preserve credentials, and back off background retries. The persisted cooldown scope still needs maintainer acceptance, real behavior proof, and green latest-head validation.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 79f61e63ac2d.

Label changes

Label changes:

• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.

Label justifications:

• P2: This is a normal-priority Claude OAuth usability/auth handling fix with provider-specific blast radius.
• merge-risk: 🚨 auth-provider: The PR changes OAuth 429 classification, credential-cache invalidation behavior, and provider refresh cooldown behavior.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists builds and a blocked focused test run, but no after-fix app, CLI, terminal, log, recording, or linked artifact proof for the OAuth 429 path; the contributor should add redacted proof and update the PR body to trigger review, or ask a maintainer for @clawsweeper re-review if it does not rerun.

Evidence reviewed

What I checked:

• AGENTS.md read and applied: Repository policy was read fully and applied to focus the review on Claude provider/auth behavior, focused tests, and runtime proof expectations. (AGENTS.md:1, 79f61e63ac2d)
• Current-main 429 handling: Current main handles 200, 401, and 403 explicitly; other statuses, including HTTP 429, fall through to serverError with response body text. (Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthUsageFetcher.swift:57, 79f61e63ac2d)
• Current-main cache invalidation path: Current main invalidates the Claude OAuth credential cache for ClaudeOAuthFetchError before surfacing oauthFailed, so a generic 429 follows the cache invalidation path today. (Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift:303, 79f61e63ac2d)
• PR diff scope: The latest PR diff adds ClaudeOAuthFetchError.rateLimited, Retry-After parsing, a persisted ClaudeOAuthUsageRateLimitGate, cache-preserving 429 handling, and ClaudeOAuthTests coverage. (Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthUsageFetcher.swift:6, 539f3c4ba4ee)
• Latest-head checks: For head 539f3c4, GitGuardian completed successfully while lint-build-test and both Linux CLI builds were still in progress at review time. (539f3c4ba4ee)
• Real behavior proof missing: The PR body lists build commands and a blocked focused test run, and the only issue comment is the prior ClawSweeper review; no after-fix runtime output, logs, screenshot, recording, or linked artifact was present. (539f3c4ba4ee)

Likely related people:

• steipete: Recent path history shows repeated Claude OAuth/provider HTTP work, including provider HTTP centralization, OAuth scope handling, Admin API usage, and quota/usage fixes. (role: feature owner and recent area contributor; confidence: high; commits: ad33b32773bd, d0a79d9855d0, aa8977ef994d; files: Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthUsageFetcher.swift, Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift, Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentials.swift)
• ratulsarna: Path history shows prior Claude OAuth usage and source-selection work adjacent to the OAuth usage and error-handling path changed here. (role: adjacent OAuth contributor; confidence: medium; commits: 4f2656b74c5c, 5f9b46df8fa6; files: Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthUsageFetcher.swift, Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift)
• Yuxin-Qiao: Recent ClaudeUsageFetcher history includes Claude CLI subscription usage handling and OAuth extra usage normalization near the usage-loading behavior affected by this PR. (role: recent area contributor; confidence: medium; commits: 126dc9238715, 11f920652804; files: Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift, Tests/CodexBarTests/ClaudeOAuthTests.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.