Skip to content

v3.5.0 — Per-session quota-status files

Choose a tag to compare

View all tags
@vsits-proxy-builder vsits-proxy-builder released this 05 May 19:18
· 101 commits to main since this release
v3.5.0
379da7e
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Per-session quota-status files — fixes cross-session contamination on multi-agent hosts where multiple Claude Code sessions share one cache-fix proxy.

Breaking change

~/.claude/quota-status.json (single global file) is replaced with:

  • ~/.claude/quota-status/account.json — account-global fields (Q5h/Q7d utilization, status, overage)
  • ~/.claude/quota-status/sessions/<filename>.json — per-session cache fields (TTL tier, hit rate, cache_creation/read)

<filename> is derived from CC's x-claude-code-session-id header via a deterministic safe-name rule: UUIDs and similar safe ids pass through, malformed inputs map to inv-<sha256-prefix>. Path-traversal-safe by construction.

If you have a custom statusline script reading the legacy path, update it to read both files and apply the same filename rule. The bundled tools/quota-statusline.sh has been migrated as a reference; see its Python heredoc for the inline rule reimplementation.

The legacy file is auto-deleted on the first request after upgrade. Per-session files older than CACHE_FIX_QUOTA_STATUS_TTL_DAYS (default 7) are swept on write (throttled to once per minute).

Why

Surfaced 2026-05-05 during root-cause investigation of a /coffee warmer misdiagnosis on visits-01 (6+ concurrent CC sessions through one proxy). The warmer reported "TTL just flipped to 5m" because it read the global file in the millisecond after another agent's cold rebuild landed. The reading session's actual TTL was unchanged. Misdiagnosis was harmless that day but cost an hour of analysis because nothing carried per-session attribution.

The same race contaminates /coffee's "is the cache still warm?" gate — false-warm reads skip needed warmer pings (downgrade to 5m); false-cold reads fire unnecessary cold rebuilds. Both cost real money on the rebuild path.

Single-agent users were unaffected and remain so under the fix — for them, "global" and "per-session" are equivalent.

Bonus fix

microcompact-stability: session-id fallback chain now includes x-claude-code-session-id (the canonical CC header). Was previously checking only meta.session_id, x-session-id, and x-anthropic-session-id, returning a null hashed-session-id for most CC requests in the wild and weakening per-session attribution in microcompact diagnostics.

Upgrade

npm install -g claude-code-cache-fix@3.5.0

The legacy ~/.claude/quota-status.json is deleted automatically on the first request through the upgraded proxy. No other migration steps needed for users on the bundled statusline.

Tests

698 → 733 (+35): new tests for the sessionFilename rule (including path-traversal coverage), file-write happy paths and fallbacks, atomic write contract, legacy-file cleanup (one-shot per process), TTL sweep behavior + throttling + env-override, microcompact session-id fallback chain precedence, pipeline integration covering happy path + two-session interleaving + path-traversal safety, plus T1–T5 statusline smoke tests.

Architecture

  • Directive PR: #105 — design, filename rule, layout decisions
  • Issue: #104 — original bug report and consumer analysis

Contributors

Surfaced and root-caused by AI Team Lead during the warmer-misdiagnosis investigation. Implementation reviewed by Codex GPT (multiple passes — directive + implementation review).

Assets 2
Loading