fix(usage): parse a model-scoped weekly limit at 0% with no resets_at as real zero usage by emotionalboySY · Pull Request #534 · sirmalloc/ccstatusline

emotionalboySY · 2026-07-31T00:48:48Z

Symptom

On an account with a Fable weekly quota that hadn't used Fable yet in the current window, the fable-weekly-usage widget rendered nothing — and whenever the usage API entered an error window it degraded to error text instead. That's how I noticed: my statusline showed 7d-F: [Rate limited] for a full server-side 429 backoff window (Retry-After 3600) while the core session/weekly widgets kept rendering fine from the stdin rate_limits payload.

Root cause

/api/oauth/usage reports a model-scoped weekly quota like this before the scoped model has been used in the current window:

{
  "kind": "weekly_scoped", "group": "weekly", "percent": 0, "severity": "normal",
  "resets_at": null,
  "scope": { "model": { "id": null, "display_name": "Fable" }, "surface": null },
  "is_active": false
}

isPlaceholderUsageApiLimit() treats every percent 0 + resets_at null entry as a placeholder, so this entry is discarded and fableUsage stays undefined. Two consequences:

the widget renders blank even though the API explicitly reports the quota at 0%;
the field never makes it into usage.json, so per-model widgets lean on the conclusive-absence heuristic, and on API error paths without a usable stale cache (e.g. the cached token hash no longer matches after a token refresh) they fall back to getUsageErrorMessage() text like [Rate limited] for the whole backoff window.

I verified against the live API that this state is real data rather than a placeholder — the moment the scoped model is first used in the window, resets_at fills in while percent stays 0 (same account, minutes apart):

// before first Fable use this window
{ "kind": "weekly_scoped", "percent": 0, "resets_at": null, "scope": { "model": { "display_name": "Fable" } }, "is_active": false }

// right after first Fable use
{ "kind": "weekly_scoped", "percent": 0, "resets_at": "2026-07-31T11:59:59.663688+00:00", "scope": { "model": { "display_name": "Fable" } }, "is_active": false }

It is also the same semantic state that a null legacy per-model bucket already reports as 0 via getUsageApiBucketUtilization() (the #343 convention), so today the two encodings of "quota exists, unused" are treated inconsistently.

Fix

Exempt entries whose scope names a concrete model from the placeholder guard: their percent: 0 is surfaced as a real 0% reading, while the reset field stays unset until the window actually starts (the WINDOW_RESET_FIELD_SENTINELS mapping already handles that for requirement checks).

The guard is unchanged for unscoped session / weekly_all entries, so the #343 phantom-0% protection still applies where it was aimed. Accounts without a per-model quota omit the weekly_scoped entry entirely, so this cannot resurrect a phantom window — the conclusive-absence heuristic still covers that case, and keeps a dedicated test.

Tests

parses an unused fable quota (0%, no resets_at) as real zero usage and serves it from cache — probe-harness test updated from the previous placeholder-fable one; now also asserts the field round-trips through usage.json.
treats a missing fable window as conclusive when core usage fields are present — new probe test preserving conclusive-absence coverage with a truly absent fable window.
treats a model-scoped weekly limit at 0% with no resets_at as real zero usage, not a placeholder — parse-level test replacing absent when fable placeholder (percent 0, no resets_at), which asserted the old behavior.
treats a limits[] entry with percent 0 and no resets_at as a placeholder (#343 rationale) — unchanged and passing (unscoped guard intact).

bun test on the usage suites: 114 pass; 1 pre-existing environment-dependent failure on my Windows machine (preserves root errors within a process... times out at 5000 ms on an unmodified checkout too). bun run lint (tsc + eslint) clean.

🤖 Generated with Claude Code

… as real zero usage A weekly_scoped limits[] entry naming a concrete model reports percent 0 / resets_at null until that model is first used in the current window (resets_at fills in on first use while percent stays 0), so it is a real 0% reading, not a placeholder. The placeholder guard discarded it, leaving the per-model usage field undefined: the widget rendered blank and, since the field never entered the cache, API error windows degraded per-model widgets to error text such as [Rate limited] instead of a real reading. Exempt model-scoped entries from the placeholder guard. Unscoped session/weekly_all entries keep the sirmalloc#343 phantom-0% protection, and truly absent per-model windows are still covered by the conclusive-absence heuristic. Co-Authored-By: Claude Fable 5 <[email protected]>

Upstream: TUI kept off the render path (sirmalloc#575), flex mode default full (sirmalloc#590), usage cache fingerprinted by refresh token (sirmalloc#536), CLAUDE_CONFIG_DIR keychain credential first (sirmalloc#573), llms.txt (sirmalloc#527), faster terminal width probing (sirmalloc#501), git/jj symbol slots (sirmalloc#574), model-scoped 0% quota as real zero (sirmalloc#534), custom-command output cache + timeout (sirmalloc#539), usage-percent widgets on a shared module (sirmalloc#545), hideable reset-timer placeholders (sirmalloc#542), git command timeouts (sirmalloc#559, sirmalloc#585) Hand edits outside conflicts: - src/widgets/shared/usage-percent-widget.ts: compat fix - pass RenderContext to getUsageProgressBarWidth (fork narrow/medium bar widths) and add fork short labels WS:/WO: that the extracted Sonnet/Opus widgets used to render; point the fable-weekly kind at the fork field weeklyFableUsage / resolveWeeklyFableUsageWindow (upstream's fableUsage / resolveFableUsageWindow do not exist in the fork and crashed the render) - .fork-keep-deleted: drop llms.txt (points agents at the upstream package and at docs the fork deletes) Conflict resolutions that deviate from upstream on purpose: - src/types/Settings.ts: keep fork default flexMode full-minus-40 (upstream sirmalloc#590 switched to full) - src/utils/terminal.ts: keep fork tmux $TMUX_PANE width probe, ported to execFileSync; upstream's CCSTATUSLINE_WIDTH override in getTerminalWidth replaces the fork copy - src/ccstatusline.ts: keep getTerminalWidth() without the per-session width cache options (fork invariant); add upstream customCommandCacheTtlSeconds - src/widgets/WeeklyFableUsage.ts (+ test): keep fork widget (Fable:/F: labels, 0% for accounts without Fable, weeklyFableUsage field) instead of upstream's shared-module FableWeeklyUsage - src/utils/__tests__/usage-fetch.test.ts: adopt upstream sirmalloc#534 real-zero semantics on the fork field weeklyFableUsage - docs/test-retirements.md: ledger entries for four tests upstream renamed or replaced (sirmalloc#542, sirmalloc#534) and one duplicate upstream test dropped - src/utils/__tests__/usage-fetch.test.ts: compat - upstream's model-scoped real-zero test expects the fork field weeklyFableUsage - src/widgets/__tests__/WeeklyFableUsage.test.ts: compat - set the shared suite's new required expectedWholePercentTime - src/tui/components/__tests__/ImportPreviewDialog.test.ts: fork deviation - default flexMode is full-minus-40, so the non-default side is full - src/utils/__tests__/usage-fetch.test.ts: drop upstream's duplicate "missing fable window" test that used the upstream-only fableUsage field

Weekly Pace can measure the Sonnet, Opus or Fable weekly bucket (`s` cycles), and the per-model usage fields derive from WEEKLY_MODEL_USAGE_BUCKETS, so a Sonnet/Opus bucket the account never reports no longer holds the usage lock open and leaves [Timeout] on screen. Changes on top of the PR: - src/utils/usage-types.ts: hasTrustworthyPaceUsage trusts any defined reading. The PR's "0% with no reset = placeholder" rule predates upstream sirmalloc#534 (model-scoped 0% is real zero); placeholder filtering stays in usage-fetch - src/widgets/__tests__/WeeklyPace.test.ts: the placeholder-zero test now asserts the real-zero verdict - README.md, package.json: dropped the PR's stale v2.4.14 entry and version bump; credited in the v2.4.19 entry - src/utils/__tests__/usage-fetch.test.ts: 20s timeout on the ~14-subprocess "preserves root errors" test, which exceeded the 5s default under machine load on every commit attempt

emotionalboySY mentioned this pull request Aug 4, 2026

fix(usage): fingerprint the usage cache by refresh token so a routine token refresh is not read as an account switch #536

Merged

Merge remote-tracking branch 'origin/main' into pull-requests/pr534

b811853

sirmalloc merged commit 339691e into sirmalloc:main Sep 17, 2026
3 checks passed

This was referenced Sep 18, 2026

Upstream Parity: ccstatusline v2.2.30 released (17 commits ahead) adrijshikhar/cxstatusline#56

Closed

ccstatusline: update to 2.2.30 theblazehen/packaging#387

Merged

Navigation Menu

Repository navigation

fix(usage): parse a model-scoped weekly limit at 0% with no resets_at as real zero usage - #534

fix(usage): parse a model-scoped weekly limit at 0% with no resets_at as real zero usage#534
sirmalloc merged 2 commits into
sirmalloc:mainfrom
emotionalboySY:fix/scoped-weekly-limit-unused-zero

emotionalboySY commented Jul 31, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

emotionalboySY commented Jul 31, 2026

Symptom

Root cause

Fix

Tests

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants