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.

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).
• 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

Low Risk
Adapter-only UX for existing SDK rate-limit events via the existing runtime.warning path; no auth, contracts, or turn-state changes.

Overview
When Claude hits a subscription usage limit mid-turn, the thread now shows a runtime warning instead of spinning silently. The adapter already forwarded rate_limit_event as telemetry; a rejected window now also emits one work-log row per distinct limit while a turn is actually parked.

The row names the window (5-hour, 7-day, etc.) and remaining wait (resets in 4h 20m), not a wall-clock time. Dedup is on window:resetsAt per turn so repeats with a shrinking countdown do not spam, interleaved windows each get a row, and a new or synthetic turn re-announces. Allowed, overage-carried, idle, and malformed events stay off the work log; unusable resetsAt drops the wait suffix without killing the session.

^{Reviewed by Cursor Bugbot for commit 3e6a808. 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 3e6a808.}

[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: 4c441d34-0833-4354-a22d-fd1b087021a0

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: Not approved

Macroscope's review found this PR not approvable — This PR introduces new user-facing behavior by showing Claude usage-limit warnings in the thread when turns are paused. While well-tested and following existing patterns, new user-visible messaging warrants human review to validate UX decisions.

^{You can add or adjust custom eligibility rules. Learn more.}

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.

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

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

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