fix(usage): show empty sessions when weekly quota is exhausted

[AlexChambers]

Usage → Limits previously counted session quota from Claude and Codex accounts whose overall weekly allowance was exhausted. This made a four-account pool show 95% session quota when only 73% was usable.

The shared presentation now counts those blocked sessions as empty. Refill estimates respect both reset times: a session that resets first becomes usable at the weekly reset; an exhausted session that resets later stays blocked until its own reset; a partly spent session can regain only its unused portion at the weekly reset. Missing or stale reset times have no estimate. Web and mobile hatching uses the amount actually expected back. Claude model-specific weekly allowances retain their reported values, since an exhausted overall allowance does not establish that overage-inclusive model allowances are unusable. Provider snapshots and enforcement are unchanged.

Built on @AlexChambers' original contribution in #20349, preserving its commits and merging current main. This addresses the session-pooling portion of #19035.

Verification:

• Fresh test reduction: shared suite 54 → 52 tests, then four distinct clock/refresh edge cases added for the rebuilt behavior: 56 shared tests. Three focused regressions failed against both main and the original implementation before the rebuild.
• 80 tests passed across shared usage limits and the two mobile widget suites. Targeted lint, shared/web/mobile typechecks and diff checks passed.
• Two independent full-diff review rounds with Claude Opus 5.5 and Codex GPT-6 Sol found no confirmed code blockers. The ordering description was corrected after review. The conservative missing-clock behavior is intentional; partial-refill hatches retain the existing right-edge placement.
• Headless Linux web client, fixed synthetic four-account snapshot and clock, matching 1280×800 viewport. Main's pooling/component code is the baseline; the current head is the result. Temporary fixtures were removed. A locally served Liberation Sans fallback made text visible in the headless browser and was used for both captures.

Before: session 95%, model weekly 81%	After: session 73%, model weekly 81%

Not verified: live provider quota refresh or paid overage behavior, macOS, Windows, native iOS/Android, or the Electron shell. Widget behavior is covered by focused tests; the mobile UI received code review and typechecking. No merge was performed.

Implementation: GPT-6.1 Sol through the Codex harness in T3 Code; tests: GPT-6 Astra; adversarial review: Claude Opus 5.5 and GPT-6 Sol.

[macroscopeapp]

Approvability

Verdict: Approved at 49f54b0

Macroscope's review found this PR approvable — This is a narrowly scoped usage-display bug fix that derives exhausted session/model rows from an exhausted weekly quota without changing stored provider data or quota enforcement. It includes targeted regression coverage for affected and unaffected providers, reset metadata, and refresh behavior.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 773aa476-777a-4c42-85a8-52bbc51878d3

📥 Commits

Reviewing files that changed from the base of the PR and between e58a485 and 49f54b0.

📒 Files selected for processing: 3

• docs/user/usage.md
• packages/shared/src/usageLimits.test.ts
• packages/shared/src/usageLimits.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

When a Claude Agent or Codex weekly limit is exhausted, covered session windows are pooled as fully used. Claude Agent model-specific weekly windows are also affected. The changes include tests for pooling and reset behavior, plus usage documentation.

Changes: Exhausted weekly quota pooling

Layer / File(s)	Summary
Apply exhausted weekly limits to covered windows packages/shared/src/usageLimits.ts, packages/shared/src/usageLimits.test.ts, docs/user/usage.md	poolWindows treats covered windows as 100% used when the applicable weekly limit reaches 100%. The weekly window’s reset time and duration are applied. Tests cover pooled values, unchanged source usage, and missing or invalid reset times. The documentation describes the displayed session and model limits.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 49f54

The change makes pooled usage displays show empty sessions when the weekly quota is exhausted. No actionable merge risk was identified.

### Architecture Summary

Architecture risk: 🔵 Low · up to 49f54

The change affects 2 systems.

Changed systems: packages/shared, docs

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — packages/shared (library) was modified; 2 changed files map to changed impact.
• observed — docs (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in docs/user/usage.md: Documents that Claude and Codex sessions display 0% remaining and the weekly reset time when an account has no weekly quota left; Claude’s model-specific weekly rows do likewise.
• observed — Modified behavior in packages/shared/src/usageLimits.test.ts: Added a test expecting exhausted weekly limits sharing a reset time to count as empty in session and model rows, with pooled remaining values of 73, 13, and 57 and reset restoration of 25. It also checks that pooling does not mutate source usage and that refreshed zero-usage limits yield 100% remaining.
• observed — Modified behavior in packages/shared/src/usageLimits.test.ts: Added cases expecting session remaining to use the exhausted weekly limit only for the specified driver and window combinations: Codex secondary at 100% yields 0; Claude seven_day at 99% and seven_day_fable at 100%, and Cursor seven_day at 100%, yield 60.
• observed — Modified behavior in packages/shared/src/usageLimits.test.ts: Added cases for weekly reset values of undefined and "invalid"; both expect session remaining to be 0 and the reset list to be empty.

Pre-merge checks: 3 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Linked Issues check		Issue [#19035] requires an exhausted account segment to show a lock and count down to the weekly reset. The implementation derives usedPercent: 100, resetsAt, and windowDurationMins in `poolWind…	Add the required lock state or lock indicator for session and affected Claude model-weekly segments when the covering weekly quota is exhausted. Add regression coverage for the indicator and weekly countdown.

Passed checks: 3 passed

Check name	Status	Explanation
Out of Scope Changes check		The changed files stay within issue [#19035]. The shared pooling change implements the exhausted-weekly rule. The tests cover the pooled values, reset inheritance, refreshed quota, provider boundaries…
Title check		The title clearly and concisely describes the primary change: showing empty sessions when the weekly quota is exhausted.
Description check		The description clearly explains the problem, implementation, scope, verification results, screenshots, and unverified environments. It does not use the template headings exactly and does not explicit…

Full details: Out of Scope Changes check

Explanation

The changed files stay within issue [#19035]. The shared pooling change implements the exhausted-weekly rule. The tests cover the pooled values, reset inheritance, refreshed quota, provider boundaries, and invalid resets. The usage guide documents the resulting behavior. No unrelated product or quota-enforcement changes are present.

Full details: Description check

Explanation

The description clearly explains the problem, implementation, scope, verification results, screenshots, and unverified environments. It does not use the template headings exactly and does not explicitly document maintainer approval or explain the approval exemption, but it is otherwise complete and directly related to the change.

Full details: Linked Issues check

Explanation

Issue [#19035] requires an exhausted account segment to show a lock and count down to the weekly reset. The implementation derives usedPercent: 100, resetsAt, and windowDurationMins in poolWindows, so the zero-remaining values and reset timing are covered. The diff adds no lock state or lock indicator, and the PR explicitly excludes lock indicators. This leaves one direct coding requirement unmet.

Resolution

Add the required lock state or lock indicator for session and affected Claude model-weekly segments when the covering weekly quota is exhausted. Add regression coverage for the indicator and weekly countdown.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[juliusmarminge]

Taking over this one. I’ll keep the work on this PR, reduce the tests to the behaviors that matter, and check weekly exhaustion against session resets and model allowances before rebuilding it. Thanks @AlexChambers for the reproduction and proof.