sidekick-shared 0.28.2 → 0.29.0

package/CHANGELOG.md

@@ -5,6 +5,89 @@ 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.29.0] - 2026-11-01
+
+### Fixed
+
+- **OpenCode usage on the OpenAI provider is no longer under-counted.** OpenCode stores every token bucket separately for every provider: input without cached tokens since 2025-11, output without reasoning since 2026-04. The parser still treated `openai` messages as cache-inclusive with reasoning inside output, so it subtracted cache reads from input a second time and never billed reasoning. It now reads the layout from the message's stored `total` (older layouts are still recognized) and defaults to the current one.
+- **Cache tokens from OpenCode's older file storage are now counted.** Messages in that storage keep cache counts under `tokens.cache`, and the parser had ignored them.
+
+### Added
+
+- **Lean subpaths.** Every new subpath has types, a CommonJS build and a tree-shakable ES-module build, and a contract test pins each one's module set to the root's bindings.
+  - `sidekick-shared/pricing`: pure, 8 modules, no Zod. Model pricing and identity, usage normalization and cost, cost provenance, cost/token/duration formatting, and text token estimates.
+  - `sidekick-shared/codex`: Node only, 13 modules, no Zod. Codex homes and child-process env, `auth.json` helpers, credential-store mode, `findCodexRolloutFile()`, `codexRolloutOrigin()`, auth-status parsers and atomic JSON writers.
+  - `sidekick-shared/providerFailure`: pure, 1 module.
+  - `sidekick-shared/statusline/payload`: pure, 2 modules. The status-line stdin parser without the account, credential and snapshot code the full `statusline` entry loads.
+- **Usage events.** `collectUsageEvents()` events gain:
+  - `tokens.reasoningTokens`
+  - `promptOrdinal`: the prompt the call answered, using the same ordinals as `collectPromptHistory()` with default bounds
+  - `requestId`: the provider message id; Codex has none
+  - `subagent: { agentId, parentSessionId }`: Claude Code subagent transcripts, and Codex forks and spawned subagents
+
+  Priced cost is unchanged.
+
+- **`bucketUsage()`:**
+  - a `session` group dimension
+  - `pricedCostUsd`, null when no call in the row was priced
+  - `reasoningTokens`
+  - `excludeSynthetic`
+  - `modelKey: 'canonical'`, which merges model spellings into one row
+- **`findToolCallOrigins({ ids, workspacePaths, since })`** (Node) maps Claude Code `tool_use` ids and Codex `call_id`s to their session, file, time, tool name and the prompt ordinal they answered. Subagents and forks count against the parent's prompts.
+  - Workspace scoping and session keys match prompt history.
+  - Only lines containing a wanted id are parsed, and the walk stops once every id is found.
+- **Model identity and pricing:**
+  - `canonicalModelId()` strips provider/region prefixes, Bedrock and Vertex forms, date suffixes, `-latest` and `[1m]`.
+  - `isMovingModelAlias()`.
+  - `parseModelId().variant` for GPT tier names, and `compareModelIds()` ranks astra > sol > terra > luna within a version.
+  - `registerModelPricing(entries, { onlyIfMissing })` / `clearRegisteredModelPricing()` add a local price layer (provenance `source: 'registered'`). It survives LiteLLM hydration and imported catalogs and is never exported in catalog snapshots.
+  - `getPricingCatalogInfo()` reports the active catalog source (`static`, `litellm`, `stale-cache`, `imported`), when it was fetched, and a stable `digest`. `HydrateResult` gains `digest`.
+- **Cost provenance:** `costSourceFromPricingProvenance()`, and `mergeCostComponents()`, which ignores components not seen yet and zero-token unpriced parts. `formatCost(value, { source })` renders null or unpriced as "—" and estimates with " (est.)"; numeric output is unchanged.
+- **Provider failures:** `diagnoseProviderFailure()` decodes Codex `codexErrorInfo` in string or object form (`decodeCodexErrorInfo()`, `CODEX_ERROR_INFO_KINDS`). Every diagnosis gains `retryable`, optional in the type and schema. Evidence for inputs without `codexErrorInfo` is unchanged.
+- **Auth status parsers:** pure `parseClaudeAuthStatus()` for `claude auth status --json` and `parseCodexLoginStatus()` for `codex login status`. The Codex profile code now uses the latter.
+- **Prompt history:**
+  - `collectPromptHistory({ includeText: false })` returns metadata only. Ordinals, cursors and exclusions are identical in both modes, and cursors resume across modes.
+  - `PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES` documents that ordinals are only comparable with the default record bound.
+- **`codexRolloutOrigin()` / `codexSpawnParentFromSource()`:** pure fork and subagent detection from a rollout's `session_meta`.
+- **`createJsonlTail()`:**
+  - `onRewrite: 'restart' | 'end'`
+  - `noFollow` (`JsonlTailSymlinkError`)
+  - `checkpoint()` / `resumeFrom()`, which survive a restart
+  - an async `read()`
+- **`CodexRolloutParser`:** `maxPendingBytes`, `metadataOnly`, and `getPendingStats()`.
+- **`installCredentialGuard({ preserveEnv })`** keeps listed variables when they point at safe locations, and throws when one points at a real home.
+- **More exports:** `ProviderId` on `sidekick-shared/browser`. On `sidekick-shared/node`: `codexRefreshFingerprint()`, `compareCodexAuthFreshness()`, `getCodexCredentialStoreMode()`, `forceFileCredentialStore()` and the atomic JSON writers.
+
+### Changed
+
+- **Usage cache v3.** `USAGE_CACHE_VERSION` is 3, and files are named `*.v3.json`, so a 0.28 reader sharing `usage-cache/` and this version never overwrite each other. The first collection after upgrading re-reads each session once, and old files age out through the existing LRU pruning.
+- **Transcript projections.**
+  - Tool items gain `rawToolName` / `mcpServerName`, and projected `input` no longer carries internal `_sidekick*` keys. Raw `SessionEvent`s are unchanged.
+  - HTML reports show the raw tool and MCP server instead of those keys.
+  - The transcript schemas accept the new fields.
+- **Lighter bundles.** `formatCost()` moved to the `formatting` module (still exported from `modelInfo`), and table-derived pricing lookups are lazy. A tree-shaken bundle that imports only `formatCost()`, `shortModelName()` and `parseModelId()` drops from 12.7 KB to 2.1 KB minified.
+- `shortModelName()` / `getModelDisplayInfo()` use `canonicalModelId()`, so date-suffixed and provider-prefixed ids show their family label.
+- `findCodexRolloutFile()` lives in the light rollout-helpers module; it is still exported from the provider.
+
+## [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,29 @@ Types, parsers, providers, readers, formatters, aggregation, search, reporting,
 
 ## Recent additions
 
+- **0.29.0: lean entries, usage attribution, and honest pricing**
+  - **New subpaths:**
+    - `sidekick-shared/pricing`: pure, 8 modules. Pricing, model identity, usage cost, cost provenance, formatting and token estimates.
+    - `sidekick-shared/codex`: Node, no Zod, 13 modules. Codex homes and env, `auth.json` helpers, rollout lookup and origin, auth-status parsers.
+    - `sidekick-shared/providerFailure`: pure.
+    - `sidekick-shared/statusline/payload`: pure. The status-line stdin parser without account or quota code.
+  - **Usage events:** `collectUsageEvents()` events carry reasoning tokens, the `promptOrdinal` they answered (the same ordinals as prompt history), the provider message id, and `subagent` attribution. The cache is v3, written as `*.v3.json` so 0.28 readers sharing the folder are unaffected.
+  - **`bucketUsage()`** gains a `session` dimension, `pricedCostUsd` (null when nothing was priced), `reasoningTokens`, `excludeSynthetic`, and `modelKey: 'canonical'`.
+  - **`findToolCallOrigins()`** maps tool-call ids to their session, time and prompt ordinal.
+  - **Pricing:**
+    - `canonicalModelId()` merges spellings of one model id.
+    - `registerModelPricing()` adds local prices that survive catalog hydration.
+    - `getPricingCatalogInfo()` reports which catalog priced a cost, with a stable digest.
+    - `formatCost(value, { source })` renders null and unpriced costs as "—" and estimates with " (est.)".
+  - **Provider failures:** `diagnoseProviderFailure()` decodes Codex `codexErrorInfo` and sets `retryable`.
+  - **Also new:**
+    - `parseClaudeAuthStatus()` and `parseCodexLoginStatus()`
+    - `collectPromptHistory({ includeText: false })`
+    - `createJsonlTail()` checkpoints, `onRewrite: 'end'`, `noFollow` and async `read()`
+    - Codex parser `maxPendingBytes` and `metadataOnly`
+    - transcript projections expose `rawToolName` and `mcpServerName` without leaking internal keys
+    - `installCredentialGuard({ preserveEnv })`
+- **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 +137,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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -133,20 +156,24 @@ returns the platform default that both overrides bypass.
 
 ## Supported import paths
 
-`sidekick-shared` ships three public entry points plus a few convenience subpaths. Pick the one that matches your runtime. As of 0.25.0 every documented subpath declares explicit `types` / `import` / `require` / `default` export conditions and resolves under Vite and TypeScript's legacy `moduleResolution: node` without consumer-side aliases.
-
-| 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/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/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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+`sidekick-shared` ships three main entry points (the root, `/browser`, `/node`) plus narrower single-purpose subpaths. Pick the one that matches your runtime. As of 0.25.0 every documented subpath declares explicit `types` / `import` / `require` / `default` export conditions and resolves under Vite and TypeScript's legacy `moduleResolution: node` without consumer-side aliases.
+
+| 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()`), `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()`), tool-call origins (`findToolCallOrigins()`), 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()`), Codex `auth.json` and credential-store helpers (`codexRefreshFingerprint()`, `compareCodexAuthFreshness()`, `getCodexCredentialStoreMode()`, `forceFileCredentialStore()`), the atomic JSON writers, 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 cost, token, and duration display helpers (`formatCost()`, `formatTokenCount()`, `formatDurationMs()`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `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 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `sidekick-shared/pricing`            | Any runtime                | Pure, 8 modules, no Zod: model pricing and identity (`canonicalModelId()`, `parseModelId()`, `compareModelIds()`, `resolveModelPricing()`, `registerModelPricing()`, `getPricingCatalogInfo()`), usage normalization and cost (`normalizeProviderUsage()`, `calculateNormalizedUsageCost()`), cost provenance (`costSourceFromPricingProvenance()`, `mergeCostComponents()`, `mergeCostSources()`), `formatCost()` / `formatTokenCount()` / `formatDurationMs()`, and `estimateTextTokens()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `sidekick-shared/codex`              | Node only                  | 13 modules, no Zod: Codex homes and the child-process env (`getSystemCodexHome()`, `resolveSidekickCodexHome()`, `getCodexExecutionEnv()`), `auth.json` helpers (`parseCodexAuthJson()`, `codexRefreshFingerprint()`, `compareCodexAuthFreshness()`), `getCodexCredentialStoreMode()` / `forceFileCredentialStore()`, `findCodexRolloutFile()`, `codexRolloutOrigin()`, `parseCodexLoginStatus()` / `parseClaudeAuthStatus()`, and `atomicWriteJson()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `sidekick-shared/providerFailure`    | Any runtime                | Pure, 1 module: `diagnoseProviderFailure()`, `decodeCodexErrorInfo()`, and the identifier lists.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `sidekick-shared/statusline/payload` | Any runtime                | Pure, 2 modules: `parseClaudeStatuslinePayload()` / `quotaFromStatuslinePayload()` without the account, credential, or snapshot code the full `statusline` entry loads.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 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.
 
@@ -164,7 +191,7 @@ const guard = installCredentialGuard();
 afterEach(() => guard.assertNoViolations());
 ```
 
-The guard points `HOME` (and `USERPROFILE`, `APPDATA`, `LOCALAPPDATA`) at a temp directory it removes on exit, unsets `CLAUDE_CONFIG_DIR`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`, `CODEX_HOME`, and `SIDEKICK_CONFIG_DIR`, and patches the real `child_process` and `fs` modules. Spawning `security`, `claude`, or `codex` throws (a promisified `execFile` or `exec` rejects instead, and otherwise keeps Node's `{ stdout, stderr }` result), writing under the real `~/.claude`, `~/.claude.json`, `~/.codex`, or `~/.config/sidekick` throws, and reads there are recorded. Production code often swallows errors, so `assertNoViolations()` reports what was recorded even when nothing threw. A `vi.mock('child_process')` factory replaces the module and bypasses the guard for that file.
+The guard points `HOME` (and `USERPROFILE`, `APPDATA`, `LOCALAPPDATA`) at a temp directory it removes on exit, unsets `CLAUDE_CONFIG_DIR`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`, `CODEX_HOME`, and `SIDEKICK_CONFIG_DIR` (pass `preserveEnv: ['SIDEKICK_CONFIG_DIR', …]` to keep any of these four when they point at a fixture; one pointing at a real home throws), and patches the real `child_process` and `fs` modules. Spawning `security`, `claude`, or `codex` throws (a promisified `execFile` or `exec` rejects instead, and otherwise keeps Node's `{ stdout, stderr }` result), writing under the real `~/.claude`, `~/.claude.json`, `~/.codex`, or `~/.config/sidekick` throws, and reads there are recorded. Production code often swallows errors, so `assertNoViolations()` reports what was recorded even when nothing threw. A `vi.mock('child_process')` factory replaces the module and bypasses the guard for that file.
 
 ### Browser / webview runtimes
 
@@ -382,11 +409,32 @@ for (const exclusion of result.exclusions) console.warn('record left out', exclu
 - **Model and usage** come from the first model call that answered the prompt (Claude: the first non-synthetic assistant message, with split records of that call replacing rather than adding usage; Codex: the first `token_count` with the model from `turn_context`). Later tool-loop calls never replace it. `inputTokens` is uncached input, and missing usage stays `undefined`, never zero.
 - **Late answers enrich the same prompt.** A prompt can be collected before its answer is written. `metadataStatus` is `pending` (no answering call yet), `provisional` (Claude call still being written, `stop_reason: null`), or `final`. While a file's last prompt is not final, the cursor keeps the byte offset and length of its line, its timestamp, and its answer state so far (first-answer message id, model, and usage, never prompt or answer text). The next call continues from where the file stopped, however far the answer is, and returns the prompt again with the same provider, sessionId, ordinal, timestamp, and text only when its model, usage, or status changed; the text comes from re-reading that one line. A prompt closed by the next prompt without an answer comes back once as `final` with no usage. Consumers should upsert by identity.
 - **Large files are streamed and resumable.** Files are read in 1 MiB chunks and every pass stops after a complete line, so memory stays near one chunk plus one record whatever the file size. `maxFileBytes` is the most one file may read in one call: a file with more left keeps what it returned, records `backlog` in its cursor, is counted in `stats.filesOverSizeLimit`, and continues on the next call even if its size and mtime have not changed. `maxSessions`, `maxTotalBytes`, `maxEntries`, the deadline, and an abort stop the whole call the same way, and `cursor.next` makes the next call start with the file that was stopped, so a large or busy session cannot starve the others. The first file of a call always finishes its first record, so a record larger than the budget still moves forward. Bytes appended during a call and a half-written final line wait for the next call. `boundsHit` lists these resumable stops and `hasMore` says whether calling again would read more. No bound throws.
-- **Permanent exclusions are reported.** A record over `maxRecordBytes` is skipped as it streams past without being buffered, even when it is still being written, and a complete line that is not JSON is skipped. Each is counted (`stats.recordsOverSizeLimit`, `stats.recordsMalformed`) and listed in `exclusions` with its byte offset. A prompt inside such a record is lost and does not consume an ordinal. A file that shrank or whose first 4 KiB changed is treated as rewritten: it is read again from the start with fresh ordinals and counted in `stats.sessionsRewritten`.
+- **Permanent exclusions are reported.** A record over `maxRecordBytes` is skipped as it streams past without being buffered, even when it is still being written, and a complete line that is not JSON is skipped. Each is counted (`stats.recordsOverSizeLimit`, `stats.recordsMalformed`) and listed in `exclusions` with its byte offset. A prompt inside such a record is lost and does not consume an ordinal. Ordinals are therefore only comparable across runs and consumers that use the default bound, exported as `PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES` (16 MiB). A file that shrank or whose first 4 KiB changed is treated as rewritten: it is read again from the start with fresh ordinals and counted in `stats.sessionsRewritten`.
 - **Change reporting.** `changed` lists the sessions (provider, sessionId, `sessionKey`) whose cursor entry this call added, advanced, moved, or dropped after a rewrite, so a consumer never has to diff cursor internals. `progressed` is false when nothing new was read, which tells a stalled `hasMore` loop apart from one that is moving. `sessionKey` is opaque and equal to the cursor key; it tells apart two files that carry the same session id. `isPromptHistorySessionSettled(cursor.sessions[key])` says whether a cursor entry is fully read with no prompt waiting for its answer, and `parsePromptHistoryCursor(stored)` validates a stored cursor (versions 1 to 3) and returns it as `version: 3` with malformed entries dropped, or `undefined`.
 - **Moved files.** A session whose file is listed again under another path (Codex moves an archived thread's rollout to `archived_sessions/`) keeps its cursor entry and ordinals instead of being read again as a new session.
 - **Cursor versions.** Output is `version: 3`. Cursors from 0.27.0 (`version: 1`) and 0.27.1 (`version: 2`) are accepted: each file is re-verified once, and a 0.27.1 pending prompt is replayed from its line in resumable passes, so it now settles even when its answer is far away. Files 0.27.1 skipped for size were never in its cursor and are read in full on the first call. Metadata that 0.27.1 already gave up on (a pending replay that exceeded `maxFileBytes`) was not saved and cannot be recovered, and a 0.27.0 cursor still cannot recover prompts it returned without metadata.
 
+- **Metadata only.** `includeText: false` returns the same entries, ordinals, cursors and exclusions with `text: ''` and `textOmitted: true`, for callers that only need ordinals and timestamps. A cursor written in either mode resumes in the other.
+
+### Find where a tool call came from
+
+`findToolCallOrigins()` (Node-only) maps Claude Code `tool_use` ids and Codex `call_id`s to the record that issued them. It uses the scope, listing and session keys of `collectPromptHistory()`, so results join with prompt entries:
+
+```typescript
+import { findToolCallOrigins } from 'sidekick-shared/node';
+
+const origins = await findToolCallOrigins({
+  ids: ['toolu_01…', 'call_4df5…'],
+  workspacePaths: ['/Users/me/code/app'],
+  since: new Date('2026-10-01'), // prunes by file modification time
+});
+for (const [id, origin] of origins) {
+  // { provider, sessionId, sessionKey, filePath, timestamp, afterOrdinal, toolName?, subagent? }
+}
+```
+
+Only lines containing a wanted id are parsed, Claude Code subagent transcripts are searched too, and the walk stops once every id is found. `afterOrdinal` counts in the prompt history of `sessionId`. For a Codex subagent or fork, that is the parent session; the call's own rollout is in `filePath` and `subagent.agentId`. Ids that are not found are absent from the map.
+
 ### Collect whole sessions of prompts
 
 `collectSessionPromptHistory()` (Node-only) returns every human prompt of each matching session, grouped by session, for consumers that classify a session as a whole. It reads each session from the start with the same scanners as `collectPromptHistory()`, so text, scope, model and usage, and ordinals are identical. The replies and interaction signals that the prompt filter leaves out are opt-in.
@@ -586,6 +634,38 @@ is read and counted once. The result's `roots` names what was listed, and
 every event carries the `filePath` of its session. When no root resolves,
 no session is read.
 
+#### Attribute usage to prompts and subagents
+
+Since 0.29.0 each event says which prompt it answered and who made the call:
+
+- **`promptOrdinal`** is the ordinal of the last human prompt at or before the call. These are the same ordinals `collectPromptHistory()` returns with default bounds, so usage joins with prompt entries on `(provider, sessionId, ordinal)`. It is `null` before the first prompt, and for a Codex fork or subagent, which has no prompts of its own. It is absent for OpenCode, which has no prompt history.
+- **`tokens.reasoningTokens`** is set when the provider reported reasoning. It is informational: cost is unchanged because it is already priced from the billable output. Codex counts reasoning inside `outputTokens`; OpenCode reports it separately.
+- **`requestId`** is the provider's message id (Claude Code, OpenCode). Codex records none.
+- **`subagent: { agentId, parentSessionId }`** marks calls made by Claude Code subagent transcripts and by Codex spawned subagents or forks.
+
+```typescript
+import { bucketUsage } from 'sidekick-shared/browser';
+
+// Per session per day, model spellings merged, placeholders dropped.
+const rows = bucketUsage(events, {
+  granularity: 'day',
+  groupBy: ['session', 'model'],
+  modelKey: 'canonical', // claude-opus-5-5-20261001 and claude-opus-5-5 share a row
+  excludeSynthetic: true,
+});
+// row.pricedCostUsd is null when no call in the row was priced; row.costUsd keeps 0 for compatibility.
+
+// Cost per prompt:
+const perPrompt = new Map<string, number>();
+for (const event of events) {
+  if (event.promptOrdinal == null || event.costUsd == null) continue;
+  const key = `${event.provider}:${event.sessionId}:${event.promptOrdinal}`;
+  perPrompt.set(key, (perPrompt.get(key) ?? 0) + event.costUsd);
+}
+```
+
+The cache is versioned (`USAGE_CACHE_VERSION` 3, files named `*.v3.json`), so the first collection after upgrading re-reads each session once.
+
 ### Detect the active session provider
 
 For a single-provider surface, auto-detect and construct just one:
@@ -625,9 +705,9 @@ console.log(`Found ${tasks.length} tasks`);
 
 ### Diagnose terminal provider failures
 
-`diagnoseProviderFailure()` is a pure, synchronous helper exported from `sidekick-shared` and `sidekick-shared/browser`. The caller decides whether an SDK event is terminal: a Codex `ErrorItem`, including a reconnect notice, must not become terminal merely because its message can be classified.
+`diagnoseProviderFailure()` is a pure, synchronous helper exported from `sidekick-shared`, `sidekick-shared/browser`, and `sidekick-shared/providerFailure`. The caller decides whether an SDK event is terminal: a Codex `ErrorItem`, including a reconnect notice, must not become terminal merely because its message can be classified.
 
-The identifier lists behind the result types are exported alongside it as readonly arrays (`PROVIDER_FAILURE_CODES`, `PROVIDER_RECOVERY_ACTIONS`, `PROVIDER_CREDENTIAL_KINDS`, `PROVIDER_AUTHENTICATION_STATES`, `PROVIDER_AUTHENTICATION_SOURCES`, `PROVIDER_FAILURE_EVIDENCE_SOURCES`). To validate a diagnosis that crossed a process boundary, use `providerFailureDiagnosisSchema` from `sidekick-shared/schemas`; it is built from the same arrays, so it accepts every value a given release can return.
+The identifier lists behind the result types are exported alongside it as readonly arrays (`PROVIDER_FAILURE_CODES`, `PROVIDER_RECOVERY_ACTIONS`, `PROVIDER_CREDENTIAL_KINDS`, `PROVIDER_AUTHENTICATION_STATES`, `PROVIDER_AUTHENTICATION_SOURCES`, `PROVIDER_FAILURE_EVIDENCE_SOURCES`, and since 0.29.0 `CODEX_ERROR_INFO_KINDS`). To validate a diagnosis that crossed a process boundary, use `providerFailureDiagnosisSchema` from `sidekick-shared/schemas`; it is built from the same arrays, so it accepts every value a given release can return.
 
 ```typescript
 import { diagnoseProviderFailure } from 'sidekick-shared/browser';
@@ -667,6 +747,8 @@ The result contains `provider`, caller-supplied `credentialKind`, `diagnosis`, `
 
 Recognized structured request codes take precedence over HTTP status, followed by narrow message patterns. A bare 401 establishes credential rejection, with recovery chosen from the credential kind; a bare 403 does not distinguish authentication from execution policy and remains unknown, while a message containing `denied by policy` is `execution_policy_denied` regardless of status. An explicit OAuth or refresh-token rejection (`refresh token is invalid`) outranks overlapping thread/conversation-expiry wording; `login has expired` and `please re-authenticate` resolve according to the credential kind. Ambiguous phrases such as `Session expired` or `Permission denied` on their own remain unknown. Explicit credential rejection from the request overrides a successful local OAuth check. OAuth observations never validate API keys. Thread/conversation failures, 5xx responses, DNS failures, and connection resets do not establish rejected account credentials. The reported `Reconnecting... 2/5 (unexpected status 503 Service Unavailable: upstream connect error or disconnect/reset before headers. reset reason: connection termination)` is classified as `service_unavailable`, with message provenance and HTTP 503, if the caller supplies it as a terminal error.
 
+Since 0.29.0 every diagnosis also carries `retryable`. It is true when sending the same request again, after any `retryAfter`, can reasonably succeed: a rate limit that lifts, overload, 5xx, timeouts and failed connections, but not a Codex `usageLimitExceeded` with no known reset. The field is optional in the type and the schema, so diagnoses from older producers stay valid. Codex's structured `codexErrorInfo` is decoded on the error or any nested `error`, `cause`, `response`, `data`, `body` or `errors` entry, in string or object form (`usageLimitExceeded`, `serverOverloaded`, `httpConnectionFailed: { httpStatusCode }`, `unauthorized`, `contextWindowExceeded`, …). The evidence entry records it as `codexErrorInfo`, and `decodeCodexErrorInfo()` exposes the decoder. `parseClaudeAuthStatus()` and `parseCodexLoginStatus()` are pure parsers for `claude auth status --json` and `codex login status` output.
+
 The projection contains no raw errors, stacks, credentials, or request URLs. Product wording belongs to consumers. The helper performs no I/O, credential reads, SDK calls, stream control, retries, or UI actions. Existing transcript/tool `ErrorCategory` and quota-specific guidance contracts remain unchanged.
 
 ### Check public provider service status
@@ -723,7 +805,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 +818,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 +850,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
@@ -797,6 +887,48 @@ console.log(formatCost(costUsd)); // "$0.01"
 cache/reasoning normalization above and misprices OpenAI-style usage, where
 cached tokens are already included in the input count.
 
+#### Model identity, local prices, and the pricing basis
+
+```typescript
+import {
+  canonicalModelId,
+  registerModelPricing,
+  getPricingCatalogInfo,
+  formatCost,
+  mergeCostComponents,
+  costSourceFromPricingProvenance,
+} from 'sidekick-shared/pricing';
+
+canonicalModelId('us.anthropic.claude-opus-5-5-20261001-v1:0'); // 'claude-opus-5-5'
+canonicalModelId('azure/us/gpt-6.1-terra'); // 'gpt-6.1-terra'
+
+// Fill a gap the catalogs do not price yet (never overrides an exact price)...
+registerModelPricing(
+  {
+    'gpt-7-sol': {
+      inputCostPerMillion: 3,
+      outputCostPerMillion: 15,
+      cacheWriteCostPerMillion: 3.75,
+      cacheReadCostPerMillion: 0.3,
+    },
+  },
+  { onlyIfMissing: true },
+);
+// ...or, without onlyIfMissing, set prices that win over every catalog (e.g. negotiated rates).
+
+getPricingCatalogInfo();
+// { source: 'litellm' | 'stale-cache' | 'imported' | 'static', fetchedAt?, digest: 'fnv1a64:…', catalogEntries, registeredEntries }
+
+formatCost(null); // '—'
+formatCost(1.5, { source: 'estimated' }); // '$1.50 (est.)'
+mergeCostComponents([
+  { source: 'reported', tokens: 1200 },
+  { source: 'unpriced', tokens: 0 }, // zero-token unpriced parts do not taint the total
+]); // 'reported'
+```
+
+Registered prices survive `hydratePricingCatalog()` and are reported with provenance `source: 'registered'`. They are local configuration, so `exportResolvedModelCatalog()` never includes them. Store `getPricingCatalogInfo().digest` next to a synced cost so a later re-price can be told apart from a usage change. `isMovingModelAlias()` names agent-CLI aliases (`default`, `auto`, `sonnet`, `opus`, …) whose concrete model changes over time; don't apply dollar caps to them. `parseModelId()` reports a `variant` for GPT tier names, and `compareModelIds()` ranks astra > sol > terra > luna within a version.
+
 ### Extract token usage and tool calls from events
 
 ```typescript
@@ -913,7 +1045,14 @@ const tail = createJsonlTail({
 tail.start();
 ```
 
-A poll reads from the last position to the end of the file in chunks of `maxReadBytes` (default 1 MiB), so a cold start on a large file never allocates more than one chunk plus one line. `onEvent` receives each line's `{ offset, length }` as its second argument. A line longer than `maxLineBytes` (default 16 MiB) is skipped as it streams past, even while it is still being written, and reported to `onError`. The tail also checks that it is still reading the same content. When the path now names another file (`replaced`), the file shrank (`truncated`), or its first 4 KiB or the byte before the resume point changed (`rewritten`), it starts over from offset 0 and calls `onReset({ reason, previousOffset })` before the events from the start arrive. `createJsonlTail()` is also exported from `sidekick-shared/node`.
+A poll reads from the last position to the end of the file in chunks of `maxReadBytes` (default 1 MiB), so a cold start on a large file never allocates more than one chunk plus one line. `onEvent` receives each line's `{ offset, length }` as its second argument. A line longer than `maxLineBytes` (default 16 MiB) is skipped as it streams past, even while it is still being written, and reported to `onError`. The tail also checks that it is still reading the same content. When the path now names another file (`replaced`), the file shrank (`truncated`), or its first 4 KiB or the byte before the resume point changed (`rewritten`), it starts over (from offset 0 by default; see `onRewrite`) and calls `onReset({ reason, previousOffset })` before the events from the start arrive. `createJsonlTail()` is also exported from `sidekick-shared/node`.
+
+Since 0.29.0:
+
+- `onRewrite: 'end'` continues from the rewritten file's last complete line instead of replaying it, and `onReset` then also receives the `offset` reading continues from. The default is `'restart'`.
+- `noFollow: true` refuses a symlinked path (`JsonlTailSymlinkError`, code `JSONL_TAIL_SYMLINK`) instead of following it.
+- `checkpoint()` returns a JSON-serializable `{ version: 1, offset, identity, prefixDigest }`. A new tail's `resumeFrom(checkpoint)` continues from it after a restart, and returns false (applying the rewrite policy) when the file is no longer the one checkpointed.
+- `read()` is an async pull that returns the new complete lines.
 
 `SessionWatcherCallbacks.onBatchComplete` is also available through `createWatcher()`. Save aggregation state only after a complete event batch and only when the state includes the full history (a completed replay or a compatible restored checkpoint). Live-only state is incomplete and must not replace a full-history checkpoint. JSONL positions end at complete lines; Codex readers reconstruct parser context when seeking. OpenCode's SQLite timestamp cursor does not persist row-version deduplication, so the dashboards replay OpenCode history instead of restoring a snapshot.
 
@@ -938,12 +1077,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 +1092,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 +1100,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/authStatus.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure parsers for the provider CLIs' read-only sign-in status commands,
+ * `claude auth status --json` and `codex login status`. They do no I/O. The
+ * caller runs the command with its own environment, home, and timeout, and
+ * passes the output here.
+ *
+ * A status command reports which credential the CLI would use. It does not
+ * prove that a request will authenticate: an expired or revoked token can
+ * still read as logged in.
+ *
+ * @module authStatus
+ */
+/** `claude auth status --json`, projected. */
+export interface ParsedClaudeAuthStatus {
+    /** True only when the output is a JSON object with `"loggedIn": true`. */
+    loggedIn: boolean;
+    /** `authMethod` as reported, e.g. `claude.ai`, `oauth_token`, or `api_key`. */
+    method?: string;
+    email?: string;
+    subscriptionType?: string;
+    /**
+     * The parsed JSON object. When it is absent the output was not a JSON
+     * object, so `loggedIn: false` means "unrecognized", not "signed out".
+     */
+    raw?: unknown;
+}
+/** `codex login status`, projected. */
+export interface ParsedCodexLoginStatus {
+    /** True only when the output starts with `Logged in`. */
+    loggedIn: boolean;
+    /**
+     * `api-key` for any API-key login, `chatgpt` for a ChatGPT sign-in. Absent
+     * for other logins (access tokens) and when not logged in.
+     */
+    method?: 'chatgpt' | 'api-key';
+    /**
+     * The first line of output, bounded, without the masked key Codex appends to
+     * an API-key login. For display and logs, not for decisions.
+     */
+    detail?: string;
+}
+/**
+ * Parse the stdout of `claude auth status --json`. Claude Code exits 1 while
+ * printing valid signed-out JSON, so parse stdout whatever the exit status
+ * was. Only a JSON `"loggedIn": true` counts as logged in.
+ */
+export declare function parseClaudeAuthStatus(stdout: string): ParsedClaudeAuthStatus;
+/**
+ * Parse the output of `codex login status`. Codex prints its status line to
+ * stderr (`Logged in using ChatGPT`, `Logged in using an API key - sk-…`,
+ * `Not logged in`), so pass both streams. The exit status is not consulted:
+ * callers that require exit 0 check it themselves.
+ */
+export declare function parseCodexLoginStatus(stdout: string, stderr?: string): ParsedCodexLoginStatus;