fix(claude): surface usage-limit pauses in the thread

[vitalyiegorov]

What Changed

When Claude Code hits a subscription usage limit mid-turn, the thread now shows a warning row saying which window ran out and when it resets, instead of silently spinning. Codex gets the same treatment for its flavor of the problem: when the app-server reports codexErrorInfo: "usageLimitExceeded", the row is now a labeled quota warning carrying Codex's own reset text, instead of a generic red Runtime error.

The Claude adapter already received the SDK's rate_limit_event and forwarded it as account.rate-limits.updated telemetry, which orchestration ingestion drops. A rejected status now also emits a runtime.warning — the same mechanism the adapter already uses for high-priority CLI notifications — which ingestion turns into a thread activity row that web and mobile already render as a warning line. No contract, schema, migration, or client changes.

The row states the remaining wait ("resets in 4h 20m"), not a wall-clock time. This code runs on the server while the row is read on clients that may sit in another timezone and locale, and that carry their own timestampFormat preference — a server-rendered 3:00 PM would be wrong for exactly the remote setups T3 Code is built for, and would reintroduce the implicit-locale default that #6190 and #7081 removed. A wait reads the same everywhere, needs no contract or client change, and the row's own client-formatted timestamp says when the wait started. The raw rate_limit_info still rides along as the warning's optional detail, so a future client-side renderer has the exact instant with no work now.

The notice is deduped on the limit's identity — each turn carries a set of window:resetsAt keys — not on the rendered row. A parked window re-fires as its sibling fields drift, and the remaining wait shrinks between those repeats, so keying on the text would emit a fresh row about once a minute. A turn can park on more than one window, so the set (rather than a single slot) keeps an interleaved repeat of an earlier window from re-announcing. The set is replaced whenever the turn id changes, so every new turn — including a synthetic one auto-started for a background agent — announces its pause again with no extra bookkeeping.

Three conditions gate the row, so it never claims a pause that isn't happening: the status must be rejected, the account must not be carrying the request on provisioned overage (overageStatus / isUsingOverage), and a turn must actually be in flight — the SDK stream stays live between turns, where "this turn is paused" would be false and would persist an orphan row with no turnId.

resetsAt is epoch seconds; an absent or implausible value (more than 30 days out) renders the row without a wait rather than a bogus one.

Why

Fixes #6513. The SDK parks the turn until the window reopens without emitting a result or turn.completed, so projection_turns.state stays running and the UI spins with zero indication. Users only discover the cause by typing "continue" and getting the limit error back — in the real thread that motivated this fix, that blind spot lasted 11 hours.

This deliberately does not add a turn watchdog or change turn/session state — it only surfaces the pause. Making the parked turn resolve itself is a separate concern.

Verification

• 76 adapter tests pass, including new cases: one row per turn under repeated rejected events; silence for allowed/allowed_warning/malformed payloads while a turn is genuinely in flight; silence between turns and when overage is carrying the request; one row when a parked window repeats five minutes later (the countdown drifts, the identity does not); a fresh row for a synthetic turn parked on the same window; one row per window when two windows interleave inside a turn; unusable resetsAt keeps the session alive; a retried turn re-announces the pause. The wait assertion is locale- and timezone-independent and pins the seconds-to-milliseconds scale (reading resetsAt as milliseconds would render minutes, not hours).
• Codex adapter: 28 tests pass, including two new cases — a usageLimitExceeded error maps to a runtime.warning keeping the provider's reset text, and other errors (internalServerError) still map to runtime.error with provider_error.
• Verified end-to-end against a real exhausted account (weekly limit hit): the SDK's genuine rejected event produced Claude usage limit reached. This turn is paused until the 7-day limit resets at Aug 16, 7:00 PM GMT+2. — exactly matching Claude's own You've hit your weekly limit · resets 7pm (Europe/Vienna) error text.

UI Changes

The row uses the existing runtime.warning styling (warning icon + tone) in the work log; no new UI components were added.

Every string this PR can put in front of a user, all pinned by assertions in ClaudeAdapter.test.ts:

When	Row text
Reset time known	Claude usage limit reached. This turn is paused until the 5-hour limit resets in 4h 20m.
Reset time absent or implausible	Claude usage limit reached. This turn is paused until the 5-hour limit resets.
Other windows	same, with 7-day / 7-day Opus / 7-day Sonnet / overage
Window unknown to this build	Claude usage limit reached. This turn is paused until the limit resets in 4h 20m.

That is the whole surface: one row, one sentence, at most once per turn per window. Nothing else changes about what users see — no new components, tones, sounds, or badges — and the row is emitted only while a turn is actually parked.

Before — a production thread where Claude hit the weekly limit mid-work. The turn died silently with a generic runtime error at 20:29; the reason only surfaced ~11 hours later when the user manually sent "continue" and got the limit error back:

After — same event class on this branch, against a genuinely exhausted account (no simulation): the SDK's real rejected rate-limit event now renders a labeled work-log row the moment it arrives, and its reset matches Claude's own error text below it. Note the capture predates the copy change described above: it shows the earlier wall-clock wording (resets at Aug 16, 7:00 PM GMT+2) where the branch now renders the equivalent wait (resets in 4h 20m). The row, its trigger, and its styling are otherwise unchanged, and re-capturing needs another genuinely exhausted window:

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes — n/a, no motion

Built with Claude Fable 5 in Claude Code.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes adapter event mapping that clients already render as work-log rows. Wrong gating or dedup could spam warnings or still hide a parked turn, but it does not alter auth, contracts, or turn state.

Overview
When a Claude turn parks on a subscription usage limit, the thread now shows a runtime.warning instead of spinning with no explanation. Codex usageLimitExceeded errors get the same treatment: a labeled warning with the provider’s reset text, not a red runtime error.

Claude still forwards every rate_limit_event as telemetry. A warning row is added only for a genuine pause: rejected, not carried by overage, and a turn actually in flight. Dedup is per turn on window:resetsAt, so repeats with a shrinking wait stay one row, interleaved windows each get a row, and a new (including synthetic) turn re-announces. The copy uses remaining wait (in 4h 20m), not a wall-clock time; missing or implausible resetsAt drops the wait without killing the session.

Docs add a short FAQ for the Claude stall.

^{Reviewed by Cursor Bugbot for commit ffb083c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Emit runtime.warning for rejected Claude usage-limit pauses in ClaudeAdapter

• Adds rate_limit_event handling in ClaudeAdapter that emits one runtime.warning per distinct rejected limit window during an active turn, with a human-readable wait duration derived from resetsAt
• Deduplicates repeats within the same turn via announcedUsageLimits on ClaudeSessionContext; allowed, overage-allowed, malformed, and between-turn events stay quiet while account.rate-limits.updated telemetry still fires for every event
• Adds CLAUDE_USAGE_LIMIT_WINDOWS labels and CLAUDE_USAGE_LIMIT_MAX_WAIT_MS (30 days) cap for rendering waits; unusable or missing resetsAt values drop the wait suffix without failing the session
• Documents the behavior in providers-claude.md with a FAQ entry
• Behavioral Change: the work log now shows new warning rows for usage-limit pauses; existing consumers of runtime.warning will see these additional events

^{Macroscope summarized ffb083c.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2e29995b-0828-468e-9961-603ce2c85285

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[macroscopeapp]

Approvability

Verdict: Skipped

Macroscope did not run approvability analysis for this PR. Macroscope could not determine whether this PR modifies its approvability configuration, so the PR was not approved automatically. A PR that may change the rules that govern approval is never approved automatically.

Dismissing prior approval to re-evaluate 6168200

[vitalyiegorov]

Understood — this is a routing call rather than a defect, so flagging the state for whoever picks it up.

The earlier verdict's blocking line ("1 blocking correctness issue found at or above your repo's Minimum Blocking Severity") is gone: both Medium findings on the dedup — the countdown-drift duplicate and the synthetic-turn silence — are fixed in ae15c15 by keying the dedup on the limit's identity (turnId:rateLimitType:resetsAt) rather than on the rendered row. Each has a regression test that I verified fails against the previous implementation, so they cannot silently come back.

To make the human review as small as possible, the description now lists every string this change can put in front of a user — four variants of one sentence, each pinned by an assertion. The whole user-visible surface is one work-log row, at most once per turn per window, emitted only while a turn is genuinely parked; no new components, tones, or notifications.

One transparency note on the screenshot: it was captured against a genuinely exhausted account and shows the wording from before the copy change, when the row rendered an absolute reset time. That copy now renders as a wait, for the reason described in the body — the server would otherwise bake its own timezone and locale into a row read on other machines, which #6190 and #7081 previously fixed elsewhere. I could not re-capture, since that needs another real exhausted window; the strings above are the current output and are asserted in the suite.

[vitalyiegorov]

Heads-up for whoever merges: the only failing check here is Vercel – t3code-marketing, which needs maintainer-approved deploys for fork branches and is currently flaking repo-wide (also failing on #7755 and #7749). This PR touches only apps/server and docs/user — no web or marketing files — so the deploy result is unrelated either way.

Everything else is green at b2d37f0: CI (Check/Test), Cursor Bugbot, Macroscope Correctness, CodeRabbit. The check is non-required (mergeStateStatus: UNSTABLE, not BLOCKED), so the PR is mergeable without waiting on the Vercel approval.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit ffb083c. Configure here.}

[cursor]

Overage exhaust silences pause row

Medium Severity

The pause row is suppressed whenever isUsingOverage or overageInUse is true, even if overageStatus is also rejected. Dual exhaustion (base window and overage both rejected while those flags stay true) is a documented SDK shape, so the turn can park again with no runtime.warning — the same silent spin this change aims to fix, for accounts that use overage.

 

^{Reviewed by Cursor Bugbot for commit ffb083c. Configure here.}