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

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 #697. 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 #697, 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 Block Reset Timer's test from feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% #697, including the fix that went in with it: the usage API's raw percent when prefetch accepted one, else the payload's own percent, at 100 or more. An API percent prefetch rejected, as stale or from a block that has since reset, never counts, even when the merged usage data still holds it. Block Reset Timer now calls the check 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% #697. The check takes the render context, since it reads the payload's percent.
• Same data, no extra requests. feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% #697'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 main, where the new state doesn't exist.

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% #697'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 today's main (after feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% #697 merged): the shared check follows feat(usage): Block Reset Timer can hide until the 5-hour block hits 100% #697's final rule above, with a new test that a rejected API percent at 100% doesn't hide Block Usage, and the Block Usage tests now 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.