feat(usage): [m] swaps the Usage view for the plan's own meter

[as-koshiyama]

What

Plans are enforced in 5-hour windows — how many get started, and how deep each runs — and the Usage view's token table answers neither. m now swaps it for the plan's own meter: per day, the windows started, the average and deepest peak, and the deepest drawn as a bar against the cap itself (half a bar is halfway to the meter on every machine, not relative to the hottest day). 90%+ goes amber with ▲. The title carries the whole story in one line: count, span covered, average peak, hottest ever.

A window that reaches 100% and keeps going is where extra usage starts billing (#50), so the peaks here are the early warning token counts cannot give — this view is the pace half of that design, adjacent to #25.

Where the data comes from

Claude Desktop samples its plan meter every ~5 minutes into plan-usage-history.json ({t, org, u: {fh, sd}}). A new scan section reconstructs windows from the samples: a window starts when utilisation rises from zero, resumes after a gap of at least the window length, or drops sharply while sampling stayed continuous (a reset). Verified against a real machine: 15 windows over 13.6 days, avg peak 23%, hottest 75% — matching a hand analysis of the same file.

Honest limits, stated in the view and docs:

• The count is a floor — samples exist only while Claude Desktop runs.
• The reconstruction is heuristic; the sharp-drop threshold (30 points) is documented and tested from both sides.
• Claude-only: Codex's equivalent lives in its transcripts' rate_limits (already parsed by the usage scan) and is the natural follow-up.
• A machine without the file gets "No metering history on this machine" — never a zero that would read as an idle plan.
• Timestamps and percentages are all that is read; the org id in each sample is never kept (there is a test).

Verification

Nine new tests: window starts from each of the three conditions (and a 28-point drop correctly reading as decay, not reset), peak tracking, summary averages over peaks rather than samples, absence ≠ idleness, org-id never kept, the m toggle round-trip with rendered per-day rows and the ▲ flag, no-op off the Usage view, and the honest empty state. --demo seeds a fortnight including one near-cap brush so the amber path is visible. cargo fmt, clippy -D warnings, all 252 tests pass on the branch; docs (dashboard.md keys + a Metering windows section) and CHANGELOG included.

Independent of every open PR (#42–#45, #47–#49); the usual one-line CHANGELOG rebase applies, plus a two-line Scan fixture-literal touch-up against whichever of #44/#45 lands first — both already rehearsed on a local integration branch where the full stack passes 277 tests.

🤖 Generated with Claude Code

[as-koshiyama]

Superseded by #56, which packs this together with #52 and #49 into one branch for review.

@kleyt0n — flagging explicitly that this PR carried your approval of 2026-08-03 (commit 95f2152). Closing it discards that approval, so #56 needs a fresh one. The two commits (e09f8c4, 32eb523) are carried over intact and mapped in #56's body, and nothing in them changed since you approved.

[as-koshiyama]

Correction to my previous comment: I said "nothing in them changed since you approved". That was wrong.

Your approval was against 95f2152, this branch's tip. #56 carries e09f8c4 and 32eb523 but not 95f2152. Details and the reconciliation are in #56 (comment) — short version, the substance is covered there by other commits and tests pass, but the approved tip is not an ancestor of #56.