fix(usage): preserve recent Claude quotas during rate limits

Closed
RA
7d ago
+1182-76

Summary

A transient HTTP 429 currently removes Claude's last successful quota result from the TUI and its shared startup cache. Successful responses also have no reuse interval, so repeated CLI invocations and frequent TUI refreshes can make unnecessary requests to the usage endpoint.

This change reuses successful Claude observations for 60 seconds and keeps an eligible previous observation visible during rate limiting, with its original update time and an explicit cached-data indicator.

Behavior

  • Honor valid Retry-After values, including HTTP dates, with the existing one-hour cap. When the header is missing or invalid, persist consecutive delays of 60, 120, 240 seconds and so on, capped at one hour. A successful response resets the backoff.
  • Store the last successful observation under a hash of the current access token. During a 429 or its cooldown, reuse that observation for at most one hour without advancing its timestamp. When no eligible observation exists, show the rate-limit diagnostic and remaining wait.
  • Coordinate requests across processes with a bounded request lock and recheck the cache and clock after acquiring it. Recognize the platform contention error reported by fs2, including Windows lock violations. Lock I/O failures return an actionable diagnostic instead of issuing an uncoordinated request; failed cache writes after lock acquisition retain the process's memory state.
  • Validate startup data against the current token's state. Credential failures and HTTP 401/403 cannot restore an old quota result. A persisted revision counter preserves invalidation ordering when memory and disk updates happen within the same second.
  • Add optional freshness metadata containing fetched_at and stale to usage JSON, preserving the existing top-level array. Light output and both wide and compact TUI layouts display the observation time and retry diagnostic. Other providers omit the new field.

Claude Code credentials remain read-only. This builds on the cooldown handling in #1188 and #1314.

Validation

  • cargo fmt --all -- --check — passed.
  • RUSTDOCFLAGS='-D warnings' cargo doc --locked --no-deps --workspace — passed.
  • cargo clippy --locked -p tokscale-cli --all-targets --all-features --no-deps -- -D warnings — passed.
  • cargo test --workspace --all-features --no-fail-fast — 4,836 passed, 0 failed, 6 ignored.
  • Focused Claude tests — 74 passed. Coverage includes request reuse, persistent backoff and recovery, HTTP-date handling, concurrent callers, storage failures, token isolation, clock changes, and authentication invalidation after a failed write. Additional tests cover startup cache validation, JSON compatibility, and cached-data presentation in compact terminals.

The full workspace Clippy command is blocked locally by the existing clippy::nonminimal_bool at crates/tokscale-core/src/scanner.rs:1744 with Rust 1.96.0. The same failure was reproduced on unmodified main; this PR leaves that file unchanged.