feat(usage): Block Usage can hide at 100%, swapping with Block Reset Timer - #89

Standalone, cut from main (rebuilt 2026-10-26 after #71 merged upstream as sirmalloc#697).

What

Block Usage gets a new hide state, when the 5-hour block is at 100% (at-limit, off by default). It's the mirror of Block Reset Timer's under-limit state from #71. With both turned on, the two widgets take turns: the block's percent shows until the limit, then the reset countdown takes its place.

Why

At the limit, the percent stops telling you anything: it reads 100% until the block resets, and what you want to know then is when you can work again. With only #71, a line that pairs the two shows both at the limit:

5h: 100.0%  |  5h reset 1hr 43m

and the percent next to the countdown is noise. Hiding it leaves the one number that matters:

5h reset 1hr 43m

How

• One shared check. isAtSessionLimit in widgets/shared/usage-display.ts holds feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% #71's test (the usage API's raw percent when there is one, else the payload's, at 100 or more). Block Reset Timer now calls it instead of its inline copy, and Block Usage's new state calls the same function, so the two always flip in the same render: never both, never neither. 99.7% that a whole-number percent shows as 100% still counts as under the limit, as in feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% #71.
• Same data, no extra requests. feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% #71's prefetch rule asks the usage API for the block's percent for a Block Reset Timer with under-limit. It now covers a Block Usage with at-limit too, through the same cache, so a line with both makes one request, and a line with neither state makes none (tested).
• What stays the same: with the state off, Block Usage renders exactly as before; unknown usage keeps its no-data behavior ([Timeout] and friends, or hidden with no-data); the TUI preview keeps its sample.
• The 5h label in front of the countdown: with under-limit on, Block Reset Timer only appears at the limit, so relabeling it (e, e.g. 5h reset ) keeps the 5h label where the percent was. USAGE.md says so next to both states.

Demo

Block Usage (at-limit) and Block Reset Timer (under-limit, label 5h reset ), piped with the 5-hour block at 61% and at 100% (fake rate_limits, reset 1hr 43m away). Before is #71's branch, where the new state does nothing.

Powerline

Before:

After:

Plain

Before:

After:

Turning the state on in the line editor: h on Block Usage, check "when the 5-hour block is at 100%", and the row reads (hide: at-limit). The preview keeps its sample.

Powerline

Plain

Testing

• bun test: 3209 pass, 0 fail (26 new: the shared check's cases, Block Usage's state, the swap with Block Reset Timer, and the prefetch). bun run lint passes.
  • Block Usage: shown at 60% and 99.7%, hidden at 100% and 100.4%, the API's percent over a lagging payload's (both directions), unknown usage unchanged with and without no-data, state off at 100%, preview unaffected.
  • Swap: for five usage cases, exactly one of Block Usage (at-limit) and Block Reset Timer (under-limit) renders.
  • Prefetch: fetches the block's percent for at-limit even when rate_limits has one, fetches once for a line with both states, doesn't fetch without the state, and falls back to the payload's percent when the fetch fails.
• Under Node (Vitest), the four changed test files pass, 146 of 146.
• Built CLI under Bun 1.4.2 and Node 26.10.0, with a fake login and a seeded usage cache (no API call), at 61% and 100%: all runtimes agree in plain and Powerline modes (5h: 61.0% / 5h reset 1hr 42m); the TUI opens and exits cleanly under both.
• After merging feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% #71's fix that ignores a cached block percent once its block has reset (it now applies to at-limit too, through the same shared check): bun test 3211 pass, 0 fail; bun run lint passes.
• Rebuilt as one commit on main after feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% #71 merged upstream as feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% sirmalloc/ccstatusline#697, with sirmalloc's fix: the shared check reads the usage API's percent when prefetch accepted one, else the payload's own, never a rejected API percent the merged usage data still holds. New test that a rejected API percent at 100% doesn't hide Block Usage; the Block Usage tests pass the payload's percent through the render context as Block Reset Timer's do. bun test 3277 pass, 0 fail; bun run lint passes.