feat(usage): Limits tab with provider quota windows and Codex banked resets

[StiensWout]

Users on Codex or Claude Code subscriptions had no way to see how much of their quota was left or when it resets without leaving T3 Code. Both providers already emit a rate-limits event during turns, but its payload was untyped and the server dropped it on the floor.

This adds a Limits tab to the Usage page, next to Cost and Tokens. Each connected environment reports the account limits its providers know about, and the page shows one section per provider: a bar per window in use, filled by the share of quota spent, with a marker at how far into the window you are. Because the bar is the whole window, that marker is also where even spending would have put the fill, so a pace icon says whether you are ahead of, on, or under pace. Hovering a bar gives the exact figures and the reset time. Codex accounts with banked reset credits show the count with a confirmed Use a reset action.

How it works

• Adapters normalise their native payloads at the boundary into a typed UsageLimitsUpdate. Codex maps account/rateLimits/updated, Claude Code maps rate_limit_event, and both keep window ids stable so turn-driven updates merge onto the same rows.
• Codex is also read on demand: through a live session's app-server when one exists, otherwise through a short-lived codex app-server process, so limits never need an open thread. Reads may retry on a fresh process after a session failure; a redemption never does. Redemption is single-flight per instance and keeps one idempotency key until Codex reports an outcome.
• Claude Code has no on-demand call in the SDK, so the driver reads the claude.ai usage endpoint that the CLI's own /usage dialog uses, with the OAuth token Claude Code stored on disk. The token never leaves the server. It reads the endpoint's structured limits array, which is where model-scoped weekly buckets such as Fable carry their real names, and falls back to the legacy named keys. On macOS the credentials live in the Keychain and reading them from another process triggers a prompt on every refresh, so macOS relies on turn events until that becomes an explicit opt-in.
• A small in-memory UsageLimitsService keeps the latest snapshot per provider instance, folds in runtime events, refreshes on every subscribe and on every provider instance change, and streams changes over a new subscribeUsageLimits RPC. Full account reads replace the window set; sparse turn events merge by id. A failed read is recorded on the snapshot beside the last good numbers. Limits are account state rather than thread history, so nothing is persisted or event-sourced.
• The web client subscribes per environment only while the Limits tab is mounted, and lists every report, labelling the environment and the instance only when two share a provider.
• Mobile gets the same data as a Limits card on the usage screen: a bar per window in use, the elapsed marker, the pace against the clock, and the reset countdown. Redeeming a reset stays web-only for now.

Verification

• New tests for both mappers, the Claude endpoint mapper and tier derivation, and the limits service merge and subscribe behaviour. Existing adapter, driver, and usage page suites pass.
• Typecheck and lint clean on contracts, client-runtime, server, and web.
• Exercised against real Pro and Max accounts on a dev environment, including the standalone Codex read with no thread open.

Not in this PR

• Persisting snapshots across server restarts. Cost and Tokens rescan on every open too, and Limits already re-read from the providers on every open, so a stored snapshot would only add a second source of truth.
• Android screenshots. The machine that built this has no Android SDK, so the mobile card was verified by typecheck and lint only.

After

Light:

Dark:

Built with Claude Fable 5.1 in T3 Code.

---

Note

Medium Risk
Touches provider adapters, OAuth token reads for Claude limits, and Codex reset consumption with idempotency; incorrect merge on complete reads could briefly drop windows, though stamps protect newer turn events.

Overview
Adds subscription quota visibility on Usage via a new Limits metric alongside Cost and Tokens (web tab + mobile card). Clients subscribe per environment only while Limits is open; pull-to-refresh also re-fetches limits.

Server: Introduces typed usageLimits contracts, UsageLimitsService (in-memory snapshots, merge by window id, refresh on subscribe/instance changes), and WebSocket subscribeUsageLimits plus serverConsumeUsageLimitReset. Codex and Claude adapters now emit normalised UsageLimitsUpdate from turn events and optional on-demand reads (Codex via live or short-lived app-server; Claude via claude.ai usage API with stored OAuth, skipping macOS file creds to avoid Keychain prompts). Codex reset redemption is single-flight with stable idempotency keys.

UI: Bars per active window with elapsed marker, pace vs. even spend, reset countdowns, and web-only confirmed Use a reset for banked Codex credits. Shared @t3tools/shared/usageLimits keeps pace math consistent across web and mobile.

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

Note

Add Limits tab with provider quota windows and Codex banked resets

• Adds the UsageLimitsService backend in UsageLimitsService.ts. It reads account limits from Codex and Claude adapters, merges sparse runtime events, and serves snapshots over WebSocket.
• Adds normalization layers for Codex and Claude. These convert native rate-limit payloads into the shared UsageLimitsUpdate schema with windows, percentages, reset timestamps, and plan labels.
• Adds a "Limits" tab to the web and mobile usage pages. It shows usage bars, pace indicators, reset countdowns, and a confirmation dialog to redeem Codex banked reset credits.
• Adds shared utilities in usageLimits.ts for formatting countdowns, calculating elapsed window share, and classifying usage pace.
• Risk: UsageLimitsService.make stores state in memory. The make.apply merge operation removes stale windows during complete adapter reads unless a newer runtime event touched them.

^{Macroscope summarized 3e02d2e.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a cross-cutting Limits product feature with new provider account integrations, OAuth credential access, live RPC state, and an irreversible Codex reset-credit redemption action. Its authorization and account-affecting behavior require reviewer validation beyond an auto-approval assessment.

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

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

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

[juliusmarminge]

Superseded by #9507, which landed the usage Limits tab (distilled from this PR's Limits-tab placement, window bars, and pace maths). Closing as superseded — thank you @StiensWout.