feat: opt-in usage tracker — persistent rate-limit logging to JSONL

[tobiasstrebitzer]

What

An opt-in, off-by-default recorder that appends every distinct rate-limit observation to a JSONL file, so subscription-limit utilization can be analyzed later (e.g. correlated against token usage from Claude Code's session logs).

ccstatusline already fetches this data every 180s across all sessions; this optionally appends it to a log file instead of throwing it away after rendering.

How it works

Two write paths, one log ($XDG_DATA_HOME/ccstatusline/usage-log.jsonl or ~/.local/share/ccstatusline/usage-log.jsonl):

• stdin — on each piped render, the rate_limits object from the status payload is logged when its value changed. Captured from the raw pre-zod parse, so buckets not yet in StatusJSONSchema survive verbatim.
• api — inside fetchUsageData() at the cache-write point, the full /api/oauth/usage response body is logged when it changed. Because only the one process that performs the live fetch reaches that point, N concurrent sessions produce ~1 record per 180s window with no extra coordination.

Plus:

• Heartbeats (default every 10 min) distinguish "no usage occurred" from "ccstatusline wasn't running".
• Dedup is value-based per source (sha256 of the canonicalized payload) via a small state file next to the log. No locking; rare duplicate records under concurrency are harmless.
• Rotation at a configurable size (default 5 MB) to a single .1.jsonl file bounds growth.
• Failure isolation: every filesystem operation is best-effort swallow-and-continue, same style as the existing usage cache. A read-only disk still renders normally.

Config / UI

New usageTracker settings section (additive, defaulted — no settings version bump) and a 📊 Usage Tracker TUI screen: enable toggle, API logging toggle, heartbeat interval, rotation size, and the resolved log path. When API logging would introduce polling for a user with no usage widgets configured, the screen says so explicitly.

Users who only want the free stdin signal can turn API logging off and never cause an API call they weren't already making.

What it does NOT do

• No analysis, charts, or history UI — the JSONL file is the whole feature.
• No daemons or background processes.
• No new runtime dependencies.
• Nothing sensitive is written: percentages, reset timestamps, and a truncated token hash (the same fingerprint the cache already stores) — never tokens or credentials.

Testing

• bun run lint, bun test (1919 tests, including ~50 new ones covering canonicalization/signatures, dedup, heartbeats, rotation, corrupt state, unwritable dirs, and the prefetch gate), bun run build all green.
• Manually verified: unknown buckets survive verbatim; identical payloads append nothing; read-only data dir renders normally with exit 0; disabled (default) behavior is byte-identical to today and creates no files.

[tobiasstrebitzer]