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 receives the SDK's rate_limit_event and maps supported usage windows to account.rate-limits.updated telemetry. That telemetry updates account usage, but does not explain the pause in the thread. 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.

This PR is Claude only. The Codex side of the same problem (plan limits, Business workspace credits, spend caps) is #9236, so each provider is one concern.

Verification

• 100 focused tests pass (93 adapter tests and 7 usage-mapper tests), including 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.

Examples of the warning text covered by ClaudeAdapter.test.ts; current model-scoped windows can use the discovered model display name:

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

Current-main audit — September 4, 2026

Updated the existing author branch through main caf4981, preserving the newer usage-window mapper and model-fallback warning.

A receipt-gated replay against main reproduced the missing rejected-limit warning without consuming quota. The updated adapter emits the warning even when an event has no usage percentage or cannot be mapped to an account-usage row. It supports the current model-scoped weekly bucket, using the probe's display name when available. Allowed overage remains quiet, including allowed_warning without the optional derived flags.

At 236989c, 100 focused tests, server typecheck, and targeted lint pass. The added async tests wait for SDK event receipts rather than scheduler yields. The author's original real-account screenshots above are preserved, with their older wall-clock copy explicitly noted. This audit did not exhaust a live account.

The root reviewer also checked the current warning text in the real Linux Chromium client on main 89ee69e4. The following images are a disposable projection fixture before and after adding the exact emitted warning payload. The after image expands the completed fixture's work log. This checks existing client rendering and the current text, not provider ingestion, active-turn behavior, or an actual quota event. The separate receipt-gated adapter regressions provide the before/after ingestion proof.

Before, no warning activity in the fixture:

After, current warning text in the expanded work log:

The root reviewer read the complete three-file diff and all historical review threads. Current-head CI, correctness, Effect conventions and approvability pass; no unresolved threads remain.

Audit preparation: GPT 6 Astra via Codex in T3 Code.

---

Note

Low Risk
Scoped to Claude rate-limit handling and existing runtime-warning ingestion; no contract or client changes, with broad adapter test coverage.

Overview
When Claude Code rejects a subscription usage window mid-turn, the adapter now emits a runtime.warning (in addition to existing account.rate-limits.updated telemetry) so the work log shows that the turn is paused instead of spinning silently.

Warnings fire only while a turn is active, the limit status is rejected, and overage is not carrying the request. Copy names the limit window (5-hour, 7-day, etc.) and states the remaining wait from SDK resetsAt (epoch seconds), omitting the wait when reset time is missing or implausible. Announcements are deduped per turn by window:resetsAt keys so repeated SDK events and drifting countdown text do not spam rows; new turns (including synthetic ones) can warn again.

User docs add a short “Why did Claude stop halfway through a turn?” section describing the warning row. Adapter tests cover deduplication, overage/idle cases, interleaved limits, and malformed payloads.

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

Note

Fix ClaudeAdapter to surface usage-limit pauses in the thread

Makes usage-limit pauses from the Claude API visible in the conversation thread, so users see when the adapter is waiting for a rate-limit window to reset. Adds an observeUsageLimitEvents test helper that collects adapter runtime events and synchronizes on retry state changes via a synthetic API-retry message.

The accompanying test suite in ClaudeAdapter.test.ts covers warning deduplication per window, re-announcement across turns, interleaved-window handling, suppression for allowed or malformed events, overage scenarios, reset-time fallback text, model-name substitution for scoped limits, telemetry preservation, and session liveness after malformed reset data.

^{Macroscope summarized 236989c.}

[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: Team

Run ID: e29d6ed1-263f-44bc-b694-cd8e6e402c14

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

Warning

Your free Security trial is over. An organization admin can upgrade to Advanced for continuous pull request security review or dismiss this notice.

---

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

[macroscopeapp]

Approvability

Verdict: Approved at 236989c

Macroscope's review found this PR approvable — This is a narrowly scoped Claude adapter bug fix that surfaces an existing usage-limit pause using the established warning and thread-ingestion paths. It adds no schema or client changes and includes focused coverage for deduplication, overage, malformed data, and turn lifecycle cases.

^{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.

[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 ffb083c9e51d40df1152248b388478f56ff4e368. Configure here.}

Dismissing prior approval to re-evaluate c49192a

Dismissing prior approval to re-evaluate 236989c

[juliusmarminge]

Independent complete three-file review and historical-thread review finished. The warning remains gated to an active rejected turn without allowed overage. Limit-identity deduplication handles interleaved windows and fresh synthetic turns, while malformed reset values cannot kill the stream. 100 focused tests, scoped typecheck/lint and all current-head CI/reviews pass. Actual client rendering of the current text was verified with a clearly labeled disposable projection fixture; no fresh real-account exhaustion is claimed. This is a narrow missing-diagnostic fix with no lifecycle, contract or rendering-policy change. GPT 6 Astra via Codex in T3 Code.