feat(store): the store learns to count — envelope burn, scoped forecast, cost

[lroolle]

What

The usage store recorded enough to forecast with; the code reading it counted wrong.

Burn was inflated ~3x. The weekday profile summed raw positive deltas of seven_day.utilization, so every stale reading — an idle session reporting numbers it last saw — was refunded and then re-earned. Measured on a real 23 MiB log: 146 points of "burn" for a week that moved 50. Burn is now the rise of a monotone envelope.

resets_at is not a window key. On 2026-08-17 an account's seven_day.utilization went 100.0 → 0.0 and stayed there, sampled by two independent writers, with seven_day.resets_at unchanged — the weekly counter can reset out of band. A newer key is certainly a new window; an unchanged one proves nothing. The envelope re-baselines only on a drop that is both sustained (≥2 consecutive samples) and deep (≥15 points). The failure mode is a bounded under-count, which costs a missed warning where the over-count cost a false alarm every render.

26% of the log was noise. session_start/session_end compared resets_at as a raw string; the server jitters it (06:00:00.515434 vs 06:00:00.087190), so nearly every fetch wrote a marker pair — 24,747 markers against 25,004 real samples, eaten straight out of the 32 MiB rotation cap.

Two more: an expired window is now never logged as a sample (an idle session, or a fixture piped in by hand, reported a window whose reset was already behind us); and week_scan now partitions by user.uuid, which the state-dir contract has required since v2 — the default dir predates account scoping and a real one holds a dozen uuids.

New

The scoped cap gets the learned forecast. fb caps ~Mon 14:00, 2d before reset — where linear pace is structurally silent, because 45% with four days left is a calm straight line. A week whose Tuesday burns 39%/day and whose Sunday burns 6%/day is not a line. _profile_walk now serves both the account 7d and the scoped cap so they cannot disagree about physics, and the scoped one only speaks for the scope its profile was built from (scoped_name).

The store records what a percentage costs. Claude Code hands us cost, tokens, context size, effort and CLI version on stdin every render; they were read for the badges and discarded. Each usage record now carries a session block, and forecast.cache gains a cost object pricing a 7d point in dollars — the join no single source can make, since the quota API reports percent and never dollars (limit_dollars is null on subscription) while transcripts report dollars and never percent. The denominator is paired: only points observed by a sample that also carried a dollar figure, or the months of dollar-free history price a week at pennies.

Docs

docs/api/state-dir.md gains a Reading the quota series section: the four properties above, plus the two things the series cannot tell you — gaps are not idleness (samples exist only while a statusline renders), and model is the logging session's, not the spender's.

Testing

413 tests (396 baseline + 17), shellcheck clean. Also deflaked three format_reset_relative fixtures that raced the clock — the fixture reads date, the function reads it again, and one tick flips 2h30m to 2h29m. Reproduced once in ten full runs.

No change to rows 2 and 3: v0.28.0's notice engine and layout are untouched.

🤖 Generated with Claude Code