fix(usage): fingerprint the usage cache by refresh token so a routine token refresh is not read as an account switch - #536

Symptom

A server-side 429 with Retry-After: 3600 left every usage widget rendering [Rate limited] for the full hour, even though usage.json held a complete, usable snapshot the entire time. The stale-cache fallback that exists for exactly this case never fired.

7d: [Rate limited] | 7d-F: [Rate limited]

// ~/.cache/ccstatusline/usage.json, written 2h38m earlier
{"sessionUsage":0,"weeklyUsage":8,"weeklyResetAt":"2026-08-07T12:00:00Z",
 "weeklySonnetUsage":0,"weeklyOpusUsage":0,"fableUsage":16,
 "fableResetAt":"2026-08-07T12:00:00Z","tokenHash":"fe98a0af7b2e6fe5"}

// ~/.cache/ccstatusline/usage.lock
{"blockedUntil":1785803730,"error":"rate-limited"}

Root cause

The cache fingerprint hashes claudeAiOauth.accessToken. Per the comment on fingerprintUsageToken, its job is to catch a login switch:

persisted alongside the cache so a login switch (e.g. enterprise<->personal, a different token) invalidates the cache immediately instead of waiting out the TTL

But the access token is reissued on a short cycle, so an ordinary refresh of the very same account changes the fingerprint too, and readStaleUsageCache() discards the snapshot as if the account had switched. On my machine, minutes apart:

Same account, same subscription — the session token simply rotated.

This is worst exactly when the cache is load-bearing. Once a backoff lock is active, every render goes through getStaleUsageOrError(), finds the fingerprint mismatched, drops a valid snapshot and returns error text until the lock expires — up to the server's Retry-After.

In practice the widgets left visibly broken are the per-model ones (weekly-opus-usage, fable-weekly-usage), since session / weekly_all can still be served from the stdin rate_limits payload.

Fix

Fingerprint the refresh token instead. It identifies the login rather than the session — roughly two orders of magnitude longer-lived (~13 days vs ~8 hours in the values above) — so the account-switch guard keeps working without churning every few hours. It falls back to the access token when absent, so older credential files and any keychain entry that stores only an access token behave exactly as before.

getUsageToken() keeps its signature and still returns the access token used for the API call; the credentials record it is now built from carries the refresh token purely for fingerprinting.

What I did not do

My first attempt was to relax the fallback instead — serve the fingerprint-mismatched cache while a transient error (rate-limited / timeout / api-error) is in effect. Two existing tests deliberately pin the opposite behavior:

• does not serve a mismatched account cache during an active lock
• does not serve a mismatched account cache during a rate-limit backoff

Those assertions are right — a mismatched fingerprint should not be served. The bug is that a refresh produces a mismatch at all, so this fixes the fingerprint rather than weakening the guard. Both tests still pass unmodified.

Compatibility

Caches written by earlier versions carry an access-token hash, so the first run after upgrading sees one mismatch and refetches once, then stores the new fingerprint. No user-visible effect beyond a single extra request.

Tests

Three added to the fetchUsageData error handling probe suite:

• serves a fresh cache after the access token was refreshed (same login) — refresh token unchanged, access token reissued; cache is served with requestCount 0.
• serves a stale cache through a rate-limit backoff after the access token was refreshed — the reported scenario: cache past CACHE_MAX_AGE, active rate-limited lock, refreshed access token. Asserts the snapshot renders and no request is made (the backoff is still honored).
• refetches when the refresh token changes (account switch) — a different login still invalidates immediately.

bun test src/utils/__tests__/: 791 pass / 3 fail, against a 788 pass / 3 fail baseline on an unmodified checkout — same three failures, all environment-dependent on my Windows machine (saves through a symlinked settings file..., silences child stderr on best-effort probes..., and preserves root errors within a process... timing out at 5000 ms). bun run lint (tsc + eslint) clean.

Related

#534 — different root cause (placeholder parsing of an unused model-scoped quota), same user-visible text. That one is about a field never reaching the cache; this one is about a cache that has the field being thrown away. They are independent and do not conflict.

🤖 Generated with Claude Code