fix(cursor): show Enterprise spend against the personal spend limit in Usage → Limits#28485

Problem

Cursor Enterprise users see no Cursor entry in Usage → Limits. The account is signed in and working, but the provider disappears from the page, even though Cursor's own app shows Enterprise users their spend against a personal spend limit.

How this was established on a real Enterprise account: DashboardService/GetCurrentPeriodUsage with the body {} (what main sends) returns 200 with no planUsage, and its billing-cycle start and end are both "now". cursorUsageResponseToLimits turned that into a bare unsupported result, and the Limits page hides bare unsupported providers. The same request with {"includePooledUsage": true} returns the real billing cycle, all-zero planUsage percentages with no limit, and a spendLimitUsage block with limitType: "team", overallLimit/overallUsed in cents, and pooledLimit (the whole team's budget). I cross-checked overallLimit and overallUsed against Cursor's app: they match the personal spend limit and cumulative spend it shows. They also match GetDailySpendByCategory and GetAggregatedUsageEvents for the same cycle.

Fixes #28477

Change

• The usage request sends {"includePooledUsage": true}.
• When Cursor reports a team pool (pooledLimit) but no included allowance (planUsage.limit not above 0 and every plan percentage 0), Limits shows one Spend bar instead of plan bars. The bar is used ÷ limit of a matched pair: overallLimit/overallUsed, otherwise individualLimit/individualUsed. A missing used value counts as 0, because protobuf JSON omits zeros. On the account above it shows about 6% used, with the reset at the end of the billing cycle.
• In every other case the plan bars stay as they are. That covers a non-zero percentage, an included allowance, or no pool marker, so a fresh-cycle Pro account at 0% still shows its plan bars.
• If neither plan bars nor a personal spend limit are available, Cursor returns unsupported with "Cursor doesn't report a personal spend limit for this account. Open Cursor's dashboard with the same account to see its usage." and an externalUsage link to https://cursor.com/dashboard?tab=usage. This reuses the existing external-usage row, so the Usage page, composer usage panel, desktop, mobile, and /usage-limits show the link with no client changes. Web thread details show the explanation as a tooltip without the link, as they already do for Codex's link-only result.
• resetsAt is dropped when Cursor's cycle end is not after its start (the {}-body shape), so we don't show a reset that is already due.
• A Spend bar at 100% marks every Cursor model as exhausted for fallback routing (exhaustedUsageWindow). CURSOR_USAGE_WINDOWS gets a "Spend" entry for its label and description.
• docs/user/usage.md explains the Spend bar and the dashboard-link fallback.

There are no contract changes.

Scope and approval

This is one problem in one provider's usage mapping: an Enterprise account that Cursor can describe vanishes from Limits. I filed #28477, which has not been triaged yet. The first version of this PR only showed a dashboard link. I replaced it with the Spend bar after confirming that Cursor's own app shows Enterprise spend against the personal limit.

What to know before merging:

• includePooledUsage is undocumented, and I found no Cursor client that sends it. If Cursor ignores or drops it, the response falls back to the {} shape and users get the dashboard link instead of a broken or missing row.
• I haven't tested Pro or Team accounts live with this flag. They are protected by the pooledLimit and plan-limit checks and by tests for fresh-cycle Pro (with and without a pool marker), for non-zero percentages next to a pool, and for spend limits that sit beside plan usage.
• This does not fix #19008, where browser or API-key sign-in never probes Cursor usage, and it does not overlap the open PRs for that bug (#24443, #26670, #28118, #28449). Browser-sign-in Enterprise users also need #19008 before they see this row.

Verification

• Focused tests: vp test run packages/provider-cursor/src/server/usageLimits.test.ts packages/shared/src/usageLimits.test.ts → Test Files 2 passed (2), Tests 71 passed (71). They pin the request body, the real Enterprise response → Spend at 6.422% with a 2026-12-01 reset, the start = end shape without a reset, matched limit/used pairs, plan-bar gating for pooled and non-pooled responses, the dashboard-link fallback, and Spend exhausting all Cursor models in the shared fallback test.
• I removed each gating check one at a time and re-ran the tests to confirm they catch it. Without the planUsage.limit check, the pooled fresh-cycle Pro row fails because it gets Spend instead of plan bars. Without the percentage checks, the non-zero-percent-with-pool row fails. Both checks were restored afterwards.
• vp run check:changed: format, lint, knip, typecheck (33 packages), and tests (3 files) all pass.
• Read-only live probes of the real Enterprise account, with and without includePooledUsage, gave the shapes described above.
• Before/after screenshots of web Usage → Limits, filtered to Cursor, at the same 1280×800 viewport, against an isolated dev server. My own Cursor instance uses browser sign-in, so it hits #19008 and never reaches this code. For the captures I used a temporary, uncommitted stub. It marked the Cursor snapshot as enabled and authenticated, and set its usageLimits from cursorUsageResponseToLimits(<the real includePooledUsage Enterprise response, cycle 2026-11-01 → 2026-12-01>, now). "Before" uses the function from main, which ignores spendLimitUsage and shows the zeroed plan percentages as "100% left". (With main's real {} request, Cursor disappears from the page entirely.) "After" uses this branch. The "Requires access to your Cursor login in macOS Keychain" card appears in both because the stub left Keychain usage off. It is unrelated to this change.

Not checked:

• No live end-to-end run with my own browser-sign-in instance, because of #19008.
• I haven't confirmed that the ?tab=usage deep link opens the usage tab for every account type.
• No capture on a mobile device. Mobile renders the same shared windows and external-usage row.

Council review

Rounds 1–2 reviewed the earlier link-only fix. Rounds 3–4 reviewed the Spend-bar version that replaced it. *In rounds 3–4, Gemini's sandbox couldn't read the worktree, so it reviewed from the diff description and the base files. Round-3 fixes: matched spend pair, pooled-budget gating, docs order, and a comment. Round-4 nits: pooled fixtures and test organization.

Written by Claude Opus 5.5 in Claude Code via T3 Code, with Grok 4.7 (Cursor) for small edits.

Fixes pingdotgg/t3code#28477