limits: make a failed quota fetch visible, and lock the normalizers with fixtures

[pitimon]

src/lib/usage-limits.js (~2,050 lines) is the most fragile code in the repo and the least verifiable.

It talks to ~9 providers' undocumented private endpoints, including some genuinely heroic work:

• extractGeminiOauthClientCredentials (:711) — pulls OAuth client credentials out of the installed Gemini binary
• parseKiroUsageOutput (:1029) — screen-scrapes the kiro CLI's text output
• detectAntigravityProcess (:1538) — finds the app by lsof-ing listening ports
• fetchCopilotLimits — had zero tests until feat(limits): show Copilot premium-request counts, not just a percentage #98 added the first

Any provider can change any of this without notice. The failure appears per-user at runtime, never in CI.

Part 1 — visible failure (the part that matters)

A quota chip exists so someone notices they are near a limit. A chip that silently disappears when its fetcher breaks is worse than no chip, because the user has been trained to look there and now reads absence as "plenty left".

Needs verifying before fixing: does every fetcher failure render a labelled degraded state on the Limits page and the provider card — "Cursor limits: token expired" — or does the chip just vanish? LimitChips returns a status line on data.error and null on !data.configured, so the shape exists; what is untested is whether every fetcher's failure path actually sets error rather than returning an unconfigured-looking object.

To verify: force each fetcher to fail (bad token, mocked 500, missing binary, timeout) and observe both surfaces.

Part 2 — schema-snapshot fixtures

Commit one sanitized real response per provider and test each normalizer against it.

This does not detect upstream drift — nothing short of live credentials does, and that is not worth it (see below). It does stop our own refactors from silently breaking parsing, which is the failure we can actually prevent. The test header should say so plainly rather than implying more coverage than it has.

Note for whoever collects these: responses contain account identifiers and plan details. Sanitize before committing, and treat the fixtures as public.

Explicitly not proposed

A live quota canary in CI. It needs real credentials for ~9 providers in repository secrets, with the rotation burden and the disclosure surface that implies, for a solo maintainer, to detect drift that a user hitting the Limits page detects anyway — provided Part 1 is done. Part 1 is the higher-value half for that reason.

Definition of done

• Every fetcher's failure path produces a user-visible labelled state on both the Limits page and the provider card
• A test per provider asserting that a failing fetch surfaces an error rather than an absent chip
• One sanitized response fixture per provider, with the normalizer tested against it
• Test header states what the fixtures do and do not protect against

[pitimon]

Part 1 is done (#119) — the half this issue calls the higher-value one.

Verified before fixing, as the issue asks. Drove getUsageLimits with a credentialed temp home across four failure modes plus a timeout. The suspicion recorded here was not borne out: every fetcher's failure path already returned { configured: true, error: … }, and getUsageLimits wraps each provider in a .catch that does the same. That is now locked in by tests rather than left as a reading of the source.

One real defect found, and it was two issues disagreeing rather than a bug: a 401/403/404 from wham produced no windows AND no error, so LimitChips fell through to return null and the Codex chip disappeared. The comment there says it renders "a neutral empty state instead of a red Fetch failed" — issue 52's fix — but the UI had no neutral state, so the intent became no state at all. Added notice as the third rendering state: same subtle line, neutral wording, actionable.

Part 2 is blocked on data I cannot produce

This issue asks for one sanitized REAL response per provider, committed as a fixture and tested against the normalizer. I do not have real responses for these nine private endpoints, and synthesising them from reading the normalizer would be circular — the fixture would encode my reading of the code rather than the provider's actual format, while being labelled as a real capture.

Worth noting what already exists, measured rather than assumed: every provider has substantial coverage across the suite (cursor 29 files, gemini 14, antigravity 9, kiro 7, copilot 4, kimi 3, zai 2, plus claude and codex in 30+ each). Those already do the job this issue names as Part 2's real value — "it does stop our own refactors from silently breaking parsing". What they do not do is start from a captured payload.

So the remaining work is a collection task, not a coding one: capture one response per provider from a live account, sanitize the account identifiers and plan details, and commit them. Leaving this open for whoever has the credentials.

The live-quota-canary alternative stays rejected for the reasons already written here.

[pitimon]

Phase 3 triage: Handoff / collection task

The user-visible failure half is already covered by #119. The remaining requirement is sanitized captures from real provider responses. This cannot be completed safely from code inspection: synthesizing fixtures from the normalizers would be circular and falsely label generated shapes as real upstream evidence.

Keeping this issue open for credential holders who can collect, sanitize, and verify real payloads. It is not a 0.40.0 release blocker and no live-provider credentials should be added to CI. Closure criteria remain: real sanitized fixture per provider, public-data review, and normalizer regression tests against those captures.

[pitimon]

2026-08-08 review: visible degraded/error surfaces are implemented; remaining fixture work requires sanitized real provider responses. No fixtures were invented from normalizer implementation or synthetic API shapes. Keeping #105 open until real credential-authorized captures from multiple providers can be sanitized and committed.