sidekick-shared 0.28.2 → 0.28.3

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to sidekick-shared will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.28.3] - 2026-10-31
+
+### Fixed
+
+- **`fetchQuota()` marks a missing window instead of reporting 0%.** Claude Ultra (formerly Max 20x) has no 5-hour limit since 2026-10-30, and the usage endpoint returns `five_hour: null`. `fetchQuota()` read that as `{ utilization: 0, resetsAt: '' }`, the same as an idle window. Null or missing windows are now `{ utilization: 0, resetsAt: '', absent: true }`, with no projection; consumers that ignore `absent` see the old values.
+- **`writeQuotaSnapshot()` no longer freezes a provider's snapshot.** It kept the sample with the later first-window reset, so once that window disappeared or reset without restarting, every newer sample (empty reset) lost and readers kept the pre-change numbers. An existing window that had already reset at the newer sample's capture time now yields. A newer capture wins when a window appears or disappears (`absent` changes). Status-line and history writes keep an API sample's `planLabel`, `planType`, `extraUsage`, and still-running extra meters.
+- **`quotaFromStatuslinePayload()` no longer resurrects expired windows.** It copies a missing window from the fallback only when the fallback is `absent` or has not reset yet.
+- **`resolveQuota()` and `resolveZaiQuota()` report an expired cache.** A snapshot whose every window has reset since is returned as unavailable, with an error naming its date and age, instead of as live numbers.
+- `evaluateQuotaThresholds()` never alerts on an absent window. Quota-history daily averages count only samples where the window exists, and history samples keep `absent`.
+- `formatStatusline()` leads with the second window when the first is absent, shows its reset day when more than a day away, never prints the current time for an empty reset, and labels windows from `windowMs`.
+- Codex quota from `quotaFromCodexRateLimits()` names windows by `window_minutes` (`5-Hour`, `Weekly`), falling back to `Primary` / `Secondary`. It sets `windowMs` and marks a null window `absent`.
+
+### Added
+
+- `quotaStateFromClaudeUsagePayload()` parses the usage endpoint's server-driven `limits[]` meters into `QuotaState.limits`: `QuotaLimitRow` with kind, group, a derived label such as `7-Day (Fable)`, utilization, reset, window length, projection, scope, severity, the headline pick, and `weekly_scoped_shares` allowances. Older servers' `seven_day_opus` / `seven_day_sonnet` / `seven_day_overage_included` fill it instead. It also parses `extra_usage` into `QuotaState.extraUsage`, and a missing headline window is filled from its `session` / `weekly_all` meter.
+- `fetchQuota(token, { plan })` and `withClaudePlan()` stamp `planType` and `planLabel` from credential plan facts. `claudePlanLabel()` maps `default_claude_max_20x` to Ultra and `default_claude_max_5x` to Max. `resolveQuota()` passes the plan automatically, and `QuotaPoller`'s `getAccessToken` may return the credentials record (`QuotaPollerCredentials`) to do the same.
+- Pure helpers on the root and `sidekick-shared/browser`: `quotaWindowApplies()`, `quotaWindowHasData()`, `quotaWindowLabel()`, `quotaWindowShortLabel()`, `extraQuotaRows()`, `formatExtraUsage()`, and `claudePlanLabel()`. Also `quotaSampleExpired()`, plus `quotaHistoryWindow()` on the root and statusline entries.
+- Schemas: `quotaWindowSchema` gains `absent` / `windowMs`, `quotaStateSchema` gains `limits` / `extraUsage` / `planLabel` (`quotaLimitRowSchema`, `quotaExtraUsageSchema`), history samples gain `absent`, and `state.json` gains window `absent` plus quota `planLabel` / `extraLimits` (`stateFileQuotaLimitSchema`; `schemaVersion` stays 1).
+
 ## [0.28.2] - 2026-10-30
 
 ### Fixed

package/README.md

@@ -9,6 +9,7 @@ Types, parsers, providers, readers, formatters, aggregation, search, reporting,
 
 ## Recent additions
 
+- **0.28.3: plans without a 5-hour window** — a null `five_hour` from the Claude usage endpoint (Ultra, since 2026-10-30) becomes `fiveHour.absent` instead of 0% used. The endpoint's server-driven `limits[]` meters, `extra_usage`, and the credential plan land on `QuotaState.limits` / `extraUsage` / `planLabel` (`quotaStateFromClaudeUsagePayload()`, `fetchQuota(token, { plan })`). Pure helpers `quotaWindowApplies()` / `quotaWindowHasData()` / `quotaWindowLabel()` / `quotaWindowShortLabel()` / `extraQuotaRows()` / `formatExtraUsage()` / `claudePlanLabel()` are on the root and browser entries, and `quotaHistoryWindow()` is on the root and statusline entries. `writeQuotaSnapshot()` no longer freezes once a window disappears or resets, and `resolveQuota()` reports a fully expired cache as unavailable.
 - **0.28.1: credential guard keeps `promisify(execFile)`** — after `installCredentialGuard()`, `promisify(execFile)` and `promisify(exec)` resolve to `{ stdout, stderr }` again (0.28.0 dropped Node's `util.promisify.custom`, so they returned the bare stdout string), and the promisified calls are guarded too.
 - **0.28.0: ES modules, narrow entries, and new readers** — a `module` export condition gives bundlers a tree-shakable ES-module build (Node keeps CommonJS); browser-safe parsers and helpers move onto `/browser` and the provider-home helpers onto `/node`; `sidekick-shared/testing` publishes the credential guard; `providerFailureDiagnosisSchema` joins `/schemas`; prompt history reports `changed` / `progressed` / `roots` and takes `sessionRefs`; signals carry `toolCategory` and `mcpServer`; `collectUsageEvents()` takes `workspacePaths`; `createJsonlTail()` is bounded and reports resets; and Claude sessions follow `CLAUDE_CONFIG_DIR` while Codex lookups include `archived_sessions/`.
 - **0.27.6: one usable copy per login** — Claude Code and Codex rotate refresh tokens, so a second usable copy of a login invalidates the first ("Not logged in · Please run /login"). The live account now keeps no profile-home credential, only a private backup; `syncLiveAccountState()` demotes a leftover copy (installing it first when it is newer) and reports `demoted`, `repaired`, and `journal`. Live writes pass `decideLiveClaudeWrite()` or the Codex equivalent: a switch captures the outgoing login first even with `force`, holds Claude Code's refresh lock, is journaled so the next sync finishes or rolls it back, and keeps live MCP tokens. Claude Keychain writes use Claude Code's hex method and are read back (`ClaudeCredentialWriteError`), so blobs over about 4 KB are no longer truncated. New root APIs: `readClaudeCredentialStore()`, `inspectClaudeCredentialStores()` / `repairClaudeCredentialStores()`, `inspectCodexCredentialStores()` / `repairCodexCredentialStores()`, `readClaudeCredentialLedger()`, `readStoredCodexAccount()`, `syncCodexLiveStateAsync()`, `discardAccountLogin()`, `writeAccountLauncher()`, and non-persisting health inspection (`persist: false`). `writeActiveCredentials()` now requires a config directory; `writeLauncher()`, `applyActiveClaudeToLiveHome()`, and `resolveActiveClaudeHome()` are deprecated.
@@ -114,8 +115,8 @@ returns the platform default that both overrides bypass.
 | **Session Context**               | Provider-neutral context evidence snapshots (`buildSessionContextSnapshot()`, `calculateSessionContextPressure()`, `createSessionContextProjector()`, `readSessionContextSnapshot()`): layered evidence sources, low/medium/high context pressure, and observed capabilities (tools, MCP servers, permission mode, rate limits)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | **Assistant Turns**               | Browser-safe timeline/process/answer projection for provider-normalized assistant turns (`segmentAssistantTurn()`, `assistantTurnEventsFromSessionEvents()`), including interleaved reasoning, compact tool groups, and Claude `Task` subagent refs without prompt leakage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | **Report**                        | Self-contained HTML session report generation; `readSessionReportInputs()` returns metrics, transcript, and `subagents` for the session total                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| **Credentials**                   | Claude Max OAuth credential reading (macOS Keychain with a `~/.claude/.credentials.json` fallback; the file on Linux and Windows). `readClaudeCredentialStore()` returns `ok` / `absent` / `corrupt` / `error`; `writeActiveCredentials()` requires a config directory and reads every write back (`ClaudeCredentialWriteError`). `decideLiveClaudeWrite()`, `claudeRefreshFingerprint()`, `claudeLoginOnly()`, and `mergeClaudeLoginIntoLive()` expose the live-write policy. As of 0.27.6, `inspectClaudeCredentialStores()` / `repairClaudeCredentialStores()` and `inspectCodexCredentialStores()` / `repairCodexCredentialStores()` find and repair unused, duplicate, and unreadable stores Sidekick provably owns (repairs are dry runs unless `dryRun: false`), with Claude ownership recorded by `readClaudeCredentialLedger()`                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| **Quota**                         | Claude Max subscription quota fetching (5-hour and 7-day windows), Codex rate-limit extraction from event streams (plus Codex reset credits via `fetchCodexResetCreditsFromApi()`, attached to quota state by `fetchCodexQuotaFromApi()`), and authoritative z.ai Coding Plan quota fetching via `resolveZaiQuota()` / `fetchZaiQuotaFromApi()` (reads z.ai's `api/monitor/usage/quota/limit` endpoint with cached-snapshot fallback). The observed-traffic z.ai estimator was removed from the package root exports in 0.23.0 and every remaining export of it is `@deprecated` — `resolveZaiQuota()` is the single supported z.ai quota API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| **Credentials**                   | Claude subscription (Pro / Max / Ultra) OAuth credential reading (macOS Keychain with a `~/.claude/.credentials.json` fallback; the file on Linux and Windows). `readClaudeCredentialStore()` returns `ok` / `absent` / `corrupt` / `error`; `writeActiveCredentials()` requires a config directory and reads every write back (`ClaudeCredentialWriteError`). `decideLiveClaudeWrite()`, `claudeRefreshFingerprint()`, `claudeLoginOnly()`, and `mergeClaudeLoginIntoLive()` expose the live-write policy. As of 0.27.6, `inspectClaudeCredentialStores()` / `repairClaudeCredentialStores()` and `inspectCodexCredentialStores()` / `repairCodexCredentialStores()` find and repair unused, duplicate, and unreadable stores Sidekick provably owns (repairs are dry runs unless `dryRun: false`), with Claude ownership recorded by `readClaudeCredentialLedger()`                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Quota**                         | Claude subscription quota fetching (5-hour and 7-day windows; `fiveHour.absent` on plans without a 5-hour limit such as Ultra; server meters in `limits`, `extraUsage`, and `planLabel`), Codex rate-limit extraction from event streams (plus Codex reset credits via `fetchCodexResetCreditsFromApi()`, attached to quota state by `fetchCodexQuotaFromApi()`), and authoritative z.ai Coding Plan quota fetching via `resolveZaiQuota()` / `fetchZaiQuotaFromApi()` (reads z.ai's `api/monitor/usage/quota/limit` endpoint with cached-snapshot fallback). The observed-traffic z.ai estimator was removed from the package root exports in 0.23.0 and every remaining export of it is `@deprecated` — `resolveZaiQuota()` is the single supported z.ai quota API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | **Provider Status**               | `fetchProviderServiceStatus()` returns explicit observed/unavailable public status with components and unresolved incidents from status.claude.com and status.openai.com; `fetchProviderStatus()` / `fetchOpenAIStatus()` remain as lossy legacy projections (`toLegacyProviderStatus()`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | **Doctor**                        | Typed cross-provider health diagnostics — `runDoctor()` checks project identity, sessions, accounts, providers, and dependencies into a `HealthReport`; `formatHealthReport()` renders it and `getSessionDiagnostics()` retains the legacy Claude Code path probe; `runDoctor({ provider })` diagnoses the selected session provider                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | **Schemas**                       | Zod schemas for runtime validation of data crossing process/IPC boundaries — JSONL session events (`sessionEventSchema`, `messageUsageSchema`, `sessionMessageSchema`), assistant turns, observed-session V1 records, quota, account status, account management, quota history, and the public `state.json` contract (`sidekickStateFileSchema`, exported only from `sidekick-shared/schemas`) — plus `extractSessionEvents()` to unwrap `progress`-wrapped events. Account and quota APIs guarantee results valid against the same-release schemas. Also published fs-free via the [`sidekick-shared/schemas`](#supported-import-paths) subpath                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -138,14 +139,14 @@ returns the platform default that both overrides bypass.
 | Path                           | Runtime                    | What it exposes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | ------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `sidekick-shared`              | Node (CLI, extension host) | Full public API (readers, providers, parsers, pricing, …).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `sidekick-shared/browser`      | **Browser / webview**      | Pure helpers: usage normalization/pricing, token estimation, transcript and assistant-turn projection, model/context math, `parseMcpToolName()`, the `CodexRolloutParser` with the Codex rollout and session-event types, human-prompt detection (`isHumanPrompt()` / `humanPromptText()`), and `renderHandoffUrlTemplate()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `sidekick-shared/browser`      | **Browser / webview**      | Pure helpers: usage normalization/pricing, token estimation, transcript and assistant-turn projection, model/context math, `parseMcpToolName()`, the `CodexRolloutParser` with the Codex rollout and session-event types, human-prompt detection (`isHumanPrompt()` / `humanPromptText()`), `renderHandoffUrlTemplate()`, and the quota window helpers (`quotaWindowApplies()`, `quotaWindowHasData()`, `quotaWindowLabel()`, `quotaWindowShortLabel()`, `extraQuotaRows()`, `formatExtraUsage()`, `claudePlanLabel()`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `sidekick-shared/node`         | Node only                  | LiteLLM pricing and context-window hydration, public provider service status (`fetchProviderServiceStatus()`), observed context-window persistence, recent-session/transcript reads, human prompt history (`collectPromptHistory()`, and whole sessions with `collectSessionPromptHistory()`), usage events from session logs (`collectUsageEvents()` with `createSessionProviders()` and `SYNTHETIC_MODEL`), session previews (`listSessionPreviews()` / `readSessionPreview()` plus the bounded-concurrency `listSessionPreviewsAsync()` / `readSessionPreviewAsync()`), Codex history/rollout lookup (`readCodexHistory()`, `findCodexRolloutFile()`), resilient observed-session collection (`fs` + providers), the provider homes the CLIs read (`getLiveClaudeHome()`, `getClaudeProjectsDir()`, `getSystemCodexHome()`, `getCodexMonitoringHomes()`, `getCodexExecutionEnv()`), Claude session-directory encoding (`encodeClaudeWorkspacePath()`, `getClaudeSessionDirectory()`), and the config root (`getConfigDir()`, `CONFIG_DIR_ENV_VAR`). |
 | `sidekick-shared/phrases`      | Any runtime                | Phrase arrays + `getRandomPhrase()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `sidekick-shared/modelContext` | Any runtime                | Direct access to the context-window module.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `sidekick-shared/modelInfo`    | Any runtime                | Direct access to model parsing and cost math.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `sidekick-shared/formatting`   | Any runtime                | Direct access to pure token and duration display helpers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `sidekick-shared/schemas`      | Any runtime                | Pure Zod boundary schemas (session events, assistant turns, observed-session V1, quota, account status, account management, quota history, the `state.json` contract) — fs-free, no Node builtins.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `sidekick-shared/statusline`   | Node only                  | Cache-only statusline surface: account status + quota snapshot readers and writers, `formatStatusline()`, burn-rate estimates, quota freshness helpers, `parseClaudeStatuslinePayload()` / `quotaFromStatuslinePayload()`, and `readStateFile()` / `writeStateFile()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `sidekick-shared/statusline`   | Node only                  | Cache-only statusline surface: account status + quota snapshot readers and writers, `formatStatusline()`, burn-rate estimates, quota freshness and window helpers (`quotaWindowApplies()`, `quotaWindowHasData()`, `quotaWindowShortLabel()`, `quotaHistoryWindow()`), `parseClaudeStatuslinePayload()` / `quotaFromStatuslinePayload()`, and `readStateFile()` / `writeStateFile()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `sidekick-shared/testing`      | Node test runners          | `installCredentialGuard()` keeps a test process away from the real `security` / `claude` / `codex` binaries and the real Claude, Codex, and Sidekick homes, and the Claude Code / Codex session-log builders (`createSessionLogFixtures()`, `writeJsonl()`, …). Framework-free.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 Since 0.28.0 every subpath also has a `module` condition pointing at an ES-module build in `dist/esm/`. Bundlers that read it (esbuild, Vite, Rollup, webpack) tree-shake unused exports, so importing one helper from `sidekick-shared/node` bundles a few hundred bytes instead of the whole entry. Node itself never reads `module` and keeps loading the CommonJS build for both `require` and `import`, so a process never holds two copies of module state.
@@ -723,7 +724,8 @@ if (!peak.unavailable && peak.isPeak) {
 import { resolveQuota } from 'sidekick-shared';
 
 // Default: fresh persisted sample (status line, session, or API; under five minutes) →
-// session logs (Codex rollouts) → provider API → older sample labelled by age.
+// session logs (Codex rollouts) → provider API → older sample labelled by age
+// (one whose every window has already reset resolves as 'unavailable').
 const quota = await resolveQuota({ providerId: 'claude-code' });
 console.log(quota.resolution); // 'snapshot-fresh' | 'session' | 'api' | 'snapshot-aging' | 'snapshot-stale' | 'unavailable'
 console.log(quota.source, quota.capturedSource, quota.freshness, quota.ageMs);
@@ -735,21 +737,26 @@ await resolveQuota({ providerId: 'codex', workspacePath: process.cwd(), preferFr
 await resolveQuota({ providerId: 'claude-code', allowApi: false });
 ```
 
-`resolveQuota()` is shared by `sidekick quota`, `quota --all`, the MCP `get_quota_status` tool, and dashboard startup. CLI and MCP Codex queries pass `preferFresh: false` to fetch live utilization and reset credits every time; dashboard schedules and default cache preferences are unchanged. After a failed live query, the newer session or persisted sample wins by `capturedAt`, with ties going to the persisted sample and missing timestamps treated as oldest. Only a selected session sample is persisted. Fallback results keep their source and age plus the API `failure` descriptor. `allowApi: false` always prevents network access, including when `preferFresh` is false. Every side effect is injectable (`readSnapshot`, `writeSnapshot`, `fetchImpl`, `getClaudeAccessToken`, the account resolvers) for tests.
+`resolveQuota()` is shared by `sidekick quota`, `quota --all`, the MCP `get_quota_status` tool, and dashboard startup. CLI and MCP Codex queries pass `preferFresh: false` to fetch live utilization and reset credits every time; dashboard schedules and default cache preferences are unchanged. After a failed live query, the newer session or persisted sample wins by `capturedAt`, with ties going to the persisted sample and missing timestamps treated as oldest. Only a selected session sample is persisted. Fallback results keep their source and age plus the API `failure` descriptor. `allowApi: false` always prevents network access, including when `preferFresh` is false. Claude results carry `planLabel` from the stored credentials (not when `getClaudeAccessToken` is injected), and a snapshot whose every window has reset resolves as `unavailable` with an error naming its date and age. Every side effect is injectable (`readSnapshot`, `writeSnapshot`, `fetchImpl`, `getClaudeAccessToken`, the account resolvers) for tests.
 
 ### Fetch subscription quota
 
 ```typescript
-import { fetchQuota, readClaudeMaxCredentials } from 'sidekick-shared';
+import { extraQuotaRows, fetchQuota, readClaudeMaxCredentials } from 'sidekick-shared';
 
 // Returns a Promise — without `await`, the object is always truthy and
 // `accessToken` is undefined, which surfaces later as an auth failure.
 // Use `readClaudeMaxAccessTokenSync()` from a synchronous call site.
 const creds = await readClaudeMaxCredentials();
 if (creds) {
-  const quota = await fetchQuota(creds.accessToken);
+  // Passing the credentials as `plan` stamps planLabel ('Pro' | 'Max' | 'Ultra' | …).
+  const quota = await fetchQuota(creds.accessToken, { plan: creds });
   if (quota.available) {
-    console.log(`5-hour utilization: ${quota.fiveHour.utilization}%`);
+    if (quota.fiveHour.absent) console.log(`No 5-hour limit on ${quota.planLabel ?? 'this plan'}`);
+    else console.log(`5-hour utilization: ${quota.fiveHour.utilization}%`);
+    console.log(`7-day utilization: ${quota.sevenDay.utilization}%`);
+    // Extra meters beyond the two headline windows, e.g. "7-Day (Fable)".
+    for (const row of extraQuotaRows(quota)) console.log(`${row.label}: ${row.utilization}%`);
   } else {
     console.log(quota.failureKind, quota.httpStatus, quota.retryAfterMs);
   }
@@ -762,6 +769,8 @@ Unavailable quota responses remain non-throwing and may include:
 - `httpStatus`: HTTP response status when available
 - `retryAfterMs`: retry delay in milliseconds for `429` responses when the API provides `Retry-After`
 
+`fiveHour` and `sevenDay` are always present; `absent: true` marks a window the plan does not have (Claude Ultra's five-hour limit, a Codex plan's missing second window), with `0` / `''` placeholders so older readers keep working. Use `quotaWindowApplies()` / `quotaWindowHasData()` instead of testing `resetsAt` yourself, and `quotaStateFromClaudeUsagePayload()` to normalize a usage-endpoint body you fetched elsewhere.
+
 For first-party style messaging, `describeQuotaFailure()` maps unavailable quota states to stable alert keys plus display-ready severity/title/message/detail fields for CLI and VS Code consumers.
 
 ### Model info and cost calculation
@@ -938,12 +947,13 @@ console.log(matches, report.sessionProvider, report.checks);
 ### Poll quota with backoff
 
 ```typescript
-import { QuotaPoller } from 'sidekick-shared';
+import { QuotaPoller, readClaudeMaxCredentials } from 'sidekick-shared';
 
 const poller = new QuotaPoller({
   activeIntervalMs: 300_000,
   idleIntervalMs: 300_000,
-  getAccessToken: async () => token,
+  // Return the token, or the credentials record to also stamp planLabel.
+  getAccessToken: async () => readClaudeMaxCredentials(),
 });
 poller.onUpdate((state) => console.log(state));
 poller.start();
@@ -952,7 +962,7 @@ poller.start();
 ### Orchestrate quota across Claude and Codex
 
 ```typescript
-import { MultiProviderQuotaService } from 'sidekick-shared';
+import { MultiProviderQuotaService, quotaWindowApplies } from 'sidekick-shared';
 
 const service = new MultiProviderQuotaService({
   // Optional — when set, an internal CodexQuotaWatcher is created and managed.
@@ -960,7 +970,13 @@ const service = new MultiProviderQuotaService({
 });
 
 service.onUpdate(({ claude, codex }) => {
-  if (claude) console.log('Claude:', claude.fiveHour.utilization, claude.peakHours?.label);
+  // Ultra has no five-hour window (`fiveHour.absent`); show the weekly one instead.
+  if (claude) {
+    const fiveHour = quotaWindowApplies(claude.fiveHour)
+      ? `${claude.fiveHour.utilization}%`
+      : 'no 5-hour limit';
+    console.log('Claude:', fiveHour, `7d ${claude.sevenDay.utilization}%`, claude.peakHours?.label);
+  }
   if (codex) console.log('Codex:', codex.fiveHour.utilization, codex.accountLabel);
 });
 

package/dist/browser.d.ts

@@ -54,3 +54,5 @@ export { renderHandoffUrlTemplate } from './handoffUrl';
 export type { HandoffUrlIdentifiers } from './handoffUrl';
 export { classifyTool, TOOL_CATEGORIES } from './toolCategory';
 export type { ClassifyToolOptions, ToolCategory } from './toolCategory';
+export { claudePlanLabel, extraQuotaRows, formatExtraUsage, quotaWindowApplies, quotaWindowHasData, quotaWindowLabel, quotaWindowShortLabel, } from './quota';
+export type { QuotaExtraUsage, QuotaLimitRow, QuotaWindow } from './quota';

package/dist/browser.js

@@ -10,7 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.resolveModelPricing = exports.getModelPricing = exports.parseModelId = exports.segmentAssistantTurn = exports.reasoningSummary = exports.isAssistantTurnSubagentTool = exports.extractTurnSubagents = exports.assistantTurnEventsFromSessionEvents = exports.SESSION_PROVIDER_IDS = exports.RUNTIME_QUOTA_PROVIDER_IDS = exports.QUOTA_PROVIDER_IDS = exports.MODEL_PROVIDER_IDS = exports.ACCOUNT_PROVIDER_IDS = exports.createSessionContextProjector = exports.calculateSessionContextPressure = exports.buildSessionContextSnapshot = exports.parseMcpToolName = exports.parseLocalDateKey = exports.formatTokenCount = exports.formatLocalDateKey = exports.formatDurationMs = exports.addLocalDays = exports.projectSessionTranscript = exports.estimateSerializedTokens = exports.estimateTextTokens = exports.ASCII_CHARS_PER_TOKEN = exports.SYNTHETIC_MODEL = exports.ClaudeUsageDeduper = exports.TOKEN_TOTAL_LABEL = exports.TOKEN_SUBAGENTS_LABEL = exports.TOKEN_SESSION_TOTAL_LABEL = exports.TOKEN_MAIN_THREAD_LABEL = exports.TOKEN_CONTEXT_LABEL = exports.sumTokenTotals = exports.summarizeTokens = exports.formatTokenBreakdown = exports.calculateNormalizedUsageCost = exports.extractNormalizedUsage = exports.normalizeProviderUsage = exports.DEFAULT_CONTEXT_WINDOW = exports.resolveModelContextWindow = exports.getModelContextWindowSize = void 0;
-exports.TOOL_CATEGORIES = exports.classifyTool = exports.renderHandoffUrlTemplate = exports.isHumanPrompt = exports.humanPromptText = exports.HUMAN_CODEX_SOURCES = exports.HUMAN_CLAUDE_ENTRYPOINTS = exports.resolveCodexCallUsage = exports.normalizeCodexToolInput = exports.normalizeCodexToolName = exports.extractPatchFilePaths = exports.DEFAULT_MAX_TRACKED_TOOL_CALLS = exports.CodexRolloutParser = exports.isAggregateCodexLimit = exports.PROVIDER_RECOVERY_ACTIONS = exports.PROVIDER_FAILURE_EVIDENCE_SOURCES = exports.PROVIDER_FAILURE_CODES = exports.PROVIDER_CREDENTIAL_KINDS = exports.PROVIDER_AUTHENTICATION_STATES = exports.PROVIDER_AUTHENTICATION_SOURCES = exports.diagnoseProviderFailure = exports.mergeFailingToolWindows = exports.failingToolTrend = exports.FAILING_TOOL_TREND_ARROWS = exports.sessionSummaryFromStats = exports.removeSessionSummary = exports.markFileImported = exports.isFileImported = exports.applySessionSummary = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.findActiveBillingBlock = exports.computeBillingBlocks = exports.BILLING_BLOCK_DURATION_MS = exports.RESOLVED_MODEL_CATALOG_SCHEMA_VERSION = exports.resolveModelAlias = exports.registerModelAlias = exports.importResolvedModelCatalog = exports.exportResolvedModelCatalog = exports.formatCost = exports.sortModelIds = void 0;
+exports.quotaWindowShortLabel = exports.quotaWindowLabel = exports.quotaWindowHasData = exports.quotaWindowApplies = exports.formatExtraUsage = exports.extraQuotaRows = exports.claudePlanLabel = exports.TOOL_CATEGORIES = exports.classifyTool = exports.renderHandoffUrlTemplate = exports.isHumanPrompt = exports.humanPromptText = exports.HUMAN_CODEX_SOURCES = exports.HUMAN_CLAUDE_ENTRYPOINTS = exports.resolveCodexCallUsage = exports.normalizeCodexToolInput = exports.normalizeCodexToolName = exports.extractPatchFilePaths = exports.DEFAULT_MAX_TRACKED_TOOL_CALLS = exports.CodexRolloutParser = exports.isAggregateCodexLimit = exports.PROVIDER_RECOVERY_ACTIONS = exports.PROVIDER_FAILURE_EVIDENCE_SOURCES = exports.PROVIDER_FAILURE_CODES = exports.PROVIDER_CREDENTIAL_KINDS = exports.PROVIDER_AUTHENTICATION_STATES = exports.PROVIDER_AUTHENTICATION_SOURCES = exports.diagnoseProviderFailure = exports.mergeFailingToolWindows = exports.failingToolTrend = exports.FAILING_TOOL_TREND_ARROWS = exports.sessionSummaryFromStats = exports.removeSessionSummary = exports.markFileImported = exports.isFileImported = exports.applySessionSummary = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.findActiveBillingBlock = exports.computeBillingBlocks = exports.BILLING_BLOCK_DURATION_MS = exports.RESOLVED_MODEL_CATALOG_SCHEMA_VERSION = exports.resolveModelAlias = exports.registerModelAlias = exports.importResolvedModelCatalog = exports.exportResolvedModelCatalog = exports.formatCost = exports.sortModelIds = void 0;
 var modelContext_1 = require("./modelContext");
 Object.defineProperty(exports, "getModelContextWindowSize", { enumerable: true, get: function () { return modelContext_1.getModelContextWindowSize; } });
 Object.defineProperty(exports, "resolveModelContextWindow", { enumerable: true, get: function () { return modelContext_1.resolveModelContextWindow; } });
@@ -129,3 +129,12 @@ Object.defineProperty(exports, "renderHandoffUrlTemplate", { enumerable: true, g
 var toolCategory_1 = require("./toolCategory");
 Object.defineProperty(exports, "classifyTool", { enumerable: true, get: function () { return toolCategory_1.classifyTool; } });
 Object.defineProperty(exports, "TOOL_CATEGORIES", { enumerable: true, get: function () { return toolCategory_1.TOOL_CATEGORIES; } });
+// Quota window helpers (pure; safe for webviews)
+var quota_1 = require("./quota");
+Object.defineProperty(exports, "claudePlanLabel", { enumerable: true, get: function () { return quota_1.claudePlanLabel; } });
+Object.defineProperty(exports, "extraQuotaRows", { enumerable: true, get: function () { return quota_1.extraQuotaRows; } });
+Object.defineProperty(exports, "formatExtraUsage", { enumerable: true, get: function () { return quota_1.formatExtraUsage; } });
+Object.defineProperty(exports, "quotaWindowApplies", { enumerable: true, get: function () { return quota_1.quotaWindowApplies; } });
+Object.defineProperty(exports, "quotaWindowHasData", { enumerable: true, get: function () { return quota_1.quotaWindowHasData; } });
+Object.defineProperty(exports, "quotaWindowLabel", { enumerable: true, get: function () { return quota_1.quotaWindowLabel; } });
+Object.defineProperty(exports, "quotaWindowShortLabel", { enumerable: true, get: function () { return quota_1.quotaWindowShortLabel; } });

package/dist/codexQuota.js

@@ -93,6 +93,11 @@ function isPreferredQuotaHit(candidate, current) {
 function normalizePercent(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
+function reportedWindowMs(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? value * 60_000
+        : undefined;
+}
 function windowMinutesToMs(value, fallbackMs) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0
         ? value * 60_000
@@ -235,26 +240,34 @@ function quotaFromCodexRateLimits(rateLimits, source = 'session', capturedAt = n
     const secondary = rateLimits?.secondary;
     if (!primary && !secondary)
         return null;
+    const primaryMs = reportedWindowMs(primary?.window_minutes);
+    const secondaryMs = reportedWindowMs(secondary?.window_minutes);
     return (0, quota_1.withQuotaProjections)({
+        // A plan can report one window only (e.g. a weekly primary with no
+        // secondary); the missing one is marked `absent` rather than shown as 0%.
         fiveHour: primary
             ? {
                 utilization: normalizePercent(primary.used_percent),
                 resetsAt: timestampToIso(primary.resets_at),
+                ...(primaryMs !== undefined ? { windowMs: primaryMs } : {}),
             }
-            : { utilization: 0, resetsAt: '' },
+            : { utilization: 0, resetsAt: '', absent: true },
         sevenDay: secondary
             ? {
                 utilization: normalizePercent(secondary.used_percent),
                 resetsAt: timestampToIso(secondary.resets_at),
+                ...(secondaryMs !== undefined ? { windowMs: secondaryMs } : {}),
             }
-            : { utilization: 0, resetsAt: '' },
+            : { utilization: 0, resetsAt: '', absent: true },
         available: true,
         providerId: 'codex',
         source,
         capturedAt,
         stale: source === 'cache',
-        fiveHourLabel: 'Primary',
-        sevenDayLabel: 'Secondary',
+        // Name each window by its reported length (`5-Hour`, `Weekly`), falling
+        // back to the positional names when the length is not reported.
+        fiveHourLabel: (0, quota_1.quotaWindowLabel)(primaryMs, 'Primary'),
+        sevenDayLabel: (0, quota_1.quotaWindowLabel)(secondaryMs, 'Secondary'),
         limitId: rateLimits?.limit_id,
         limitName: rateLimits?.limit_name ?? undefined,
         credits: rateLimits?.credits,

package/dist/esm/browser.js

@@ -32,3 +32,5 @@ export { HUMAN_CLAUDE_ENTRYPOINTS, HUMAN_CODEX_SOURCES, humanPromptText, isHuman
 export { renderHandoffUrlTemplate } from './handoffUrl';
 // Tool categories across providers
 export { classifyTool, TOOL_CATEGORIES } from './toolCategory';
+// Quota window helpers (pure; safe for webviews)
+export { claudePlanLabel, extraQuotaRows, formatExtraUsage, quotaWindowApplies, quotaWindowHasData, quotaWindowLabel, quotaWindowShortLabel, } from './quota';

package/dist/esm/codexQuota.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { getActiveCodexAccount, getCodexMonitoringHomes, resolveSidekickCodexHome, } from './codexProfiles';
 import { readQuotaSnapshot, writeQuotaSnapshot } from './quotaSnapshots';
-import { FIVE_HOUR_WINDOW_MS, SEVEN_DAY_WINDOW_MS, withQuotaProjections } from './quota';
+import { FIVE_HOUR_WINDOW_MS, SEVEN_DAY_WINDOW_MS, quotaWindowLabel, withQuotaProjections, } from './quota';
 import { CodexProvider } from './providers/codex';
 import { walkRolloutFiles } from './providers/rolloutWalker';
 import { isAggregateCodexLimit } from './types/codex';
@@ -51,6 +51,11 @@ function isPreferredQuotaHit(candidate, current) {
 function normalizePercent(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
+function reportedWindowMs(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? value * 60_000
+        : undefined;
+}
 function windowMinutesToMs(value, fallbackMs) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0
         ? value * 60_000
@@ -193,26 +198,34 @@ export function quotaFromCodexRateLimits(rateLimits, source = 'session', capture
     const secondary = rateLimits?.secondary;
     if (!primary && !secondary)
         return null;
+    const primaryMs = reportedWindowMs(primary?.window_minutes);
+    const secondaryMs = reportedWindowMs(secondary?.window_minutes);
     return withQuotaProjections({
+        // A plan can report one window only (e.g. a weekly primary with no
+        // secondary); the missing one is marked `absent` rather than shown as 0%.
         fiveHour: primary
             ? {
                 utilization: normalizePercent(primary.used_percent),
                 resetsAt: timestampToIso(primary.resets_at),
+                ...(primaryMs !== undefined ? { windowMs: primaryMs } : {}),
             }
-            : { utilization: 0, resetsAt: '' },
+            : { utilization: 0, resetsAt: '', absent: true },
         sevenDay: secondary
             ? {
                 utilization: normalizePercent(secondary.used_percent),
                 resetsAt: timestampToIso(secondary.resets_at),
+                ...(secondaryMs !== undefined ? { windowMs: secondaryMs } : {}),
             }
-            : { utilization: 0, resetsAt: '' },
+            : { utilization: 0, resetsAt: '', absent: true },
         available: true,
         providerId: 'codex',
         source,
         capturedAt,
         stale: source === 'cache',
-        fiveHourLabel: 'Primary',
-        sevenDayLabel: 'Secondary',
+        // Name each window by its reported length (`5-Hour`, `Weekly`), falling
+        // back to the positional names when the length is not reported.
+        fiveHourLabel: quotaWindowLabel(primaryMs, 'Primary'),
+        sevenDayLabel: quotaWindowLabel(secondaryMs, 'Secondary'),
         limitId: rateLimits?.limit_id,
         limitName: rateLimits?.limit_name ?? undefined,
         credits: rateLimits?.credits,

package/dist/esm/index.js

@@ -146,7 +146,7 @@ export { getCodexProfilesDir, getCodexProfileHome, getCodexMonitoringHomes, getS
 export { writeAccountLauncher, writeLauncher, removeLauncher } from './terminalSync';
 export { DEFAULT_AUTO_SWITCH_CONFIG, decideAutoSwitch, AutoSwitchController } from './autoSwitch';
 // Quota
-export { FIVE_HOUR_WINDOW_MS, QUOTA_PROVIDER_IDS, SEVEN_DAY_WINDOW_MS, fetchQuota, projectQuotaWindow, withQuotaProjections, } from './quota';
+export { FIVE_HOUR_WINDOW_MS, QUOTA_PROVIDER_IDS, SEVEN_DAY_WINDOW_MS, claudePlanLabel, extraQuotaRows, fetchQuota, formatExtraUsage, projectQuotaWindow, quotaSampleExpired, quotaStateFromClaudeUsagePayload, quotaWindowApplies, quotaWindowHasData, quotaWindowLabel, quotaWindowShortLabel, withClaudePlan, withQuotaProjections, } from './quota';
 export { describeQuotaFailure } from './quotaPresentation';
 export { QuotaPoller } from './quotaPoller';
 export { readQuotaSnapshot, writeQuotaSnapshot } from './quotaSnapshots';
@@ -154,7 +154,7 @@ export { resolveQuota } from './quotaResolver';
 export { classifyQuotaFreshness, formatQuotaAge, QUOTA_AGING_MAX_AGE_MS, QUOTA_FRESH_MAX_AGE_MS, } from './quota';
 export { DEFAULT_QUOTA_THRESHOLDS, describeQuotaThresholdAlert, evaluateQuotaThresholds, } from './quotaThresholds';
 export { parseClaudeStatuslinePayload, quotaFromStatuslinePayload, } from './statusline/claudeStatuslinePayload';
-export { appendQuotaHistorySample, readQuotaHistoryRange, readQuotaHistoryDailyBuckets, pruneQuotaHistory, getWorkspaceIdFromPath, } from './quotaHistory';
+export { appendQuotaHistorySample, readQuotaHistoryRange, readQuotaHistoryDailyBuckets, pruneQuotaHistory, getWorkspaceIdFromPath, quotaHistoryWindow, } from './quotaHistory';
 export { fetchCodexResetCreditsFromApi, fetchCodexQuotaFromApi, quotaFromCodexRateLimits, readLatestCodexQuotaFromRollouts, resolveCodexQuota, resolveCodexQuotaFromLocalSources, } from './codexQuota';
 export { CodexQuotaWatcher } from './codexQuotaWatcher';
 export { fetchZaiQuotaFromApi, quotaStateFromZaiQuotaLimitPayload, readZaiCredentials, resolveZaiQuota, } from './zaiQuotaApi';
@@ -185,7 +185,7 @@ export { extractToolCall, extractToolCalls, ToolCallTracker } from './extractors
 // Schemas — Zod runtime validation for session events
 export { messageUsageSchema, sessionMessageSchema, sessionEventSchema, permissionModeSchema, extractSessionEvents, } from './schemas/sessionEvent';
 // Schemas — Zod runtime validation for quota / provider quota / peak hours
-export { quotaWindowSchema, quotaStateSchema, quotaFailureKindSchema, quotaProviderIdSchema, quotaSourceSchema, codexResetCreditSchema, codexResetCreditsSnapshotSchema, peakHoursStateSchema, quotaFailureDescriptorSchema, runtimeQuotaProviderSchema, providerQuotaStateSchema, claudeProviderQuotaStateSchema, codexProviderQuotaStateSchema, zaiProviderQuotaStateSchema, providerQuotaMapSchema, } from './schemas/quota';
+export { quotaWindowSchema, quotaStateSchema, quotaLimitRowSchema, quotaExtraUsageSchema, quotaFailureKindSchema, quotaProviderIdSchema, quotaSourceSchema, codexResetCreditSchema, codexResetCreditsSnapshotSchema, peakHoursStateSchema, quotaFailureDescriptorSchema, runtimeQuotaProviderSchema, providerQuotaStateSchema, claudeProviderQuotaStateSchema, codexProviderQuotaStateSchema, zaiProviderQuotaStateSchema, providerQuotaMapSchema, } from './schemas/quota';
 // Schemas — Zod runtime validation for quota history
 export { quotaHistoryRuntimeProviderSchema, quotaHistorySampleSchema, quotaHistoryDailyBucketSchema, } from './schemas/quotaHistory';
 // Schemas — Zod runtime validation for provider-failure diagnoses

package/dist/esm/multiProviderQuotaService.js

@@ -290,7 +290,7 @@ export class MultiProviderQuotaService {
             await this.refreshPeakHours();
             const creds = await this.readClaudeCredentials();
             if (!creds) {
-                this.handleUnavailableState(makeUnavailableClaudeState('Renew your Claude Max OAuth to view quota', 'auth'));
+                this.handleUnavailableState(makeUnavailableClaudeState('Renew your Claude login to view quota', 'auth'));
                 return;
             }
             const state = await this.fetchClaudeQuota(creds.accessToken);