sidekick-shared 0.27.2 → 0.27.4

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.27.4] - 2026-09-23
+
+### Added
+
+- `sidekick-shared/node` exports `createSessionProviders()`, the `CreateSessionProvidersOptions` / `CreateSessionProvidersResult` types, `SYNTHETIC_MODEL`, and the `ProviderId` / `SessionProviderBase` / `SessionProviderDiagnostic` types, re-exported from their own modules. `collectUsageEvents()` callers no longer need the package root, a CommonJS barrel that bundlers cannot tree-shake (about 420 KB minified saved in one esbuild consumer). Root exports are unchanged.
+- `CollectUsageEventsOptions.signal` (optional `AbortSignal`): `collectUsageEvents()` checks it before listing sessions and between sessions, and rejects with the signal's reason (`AbortError` by default). Only fully read sessions are cached. Without a signal nothing changes; counting, pricing, and the cache format (`USAGE_CACHE_VERSION` 2) are the same.
+- A packaging test walks every relative `require` reachable from `dist/node.js` and fails if it reaches `dist/index.js`.
+
+## [0.27.3] - 2026-09-23
+
+### Fixed
+
+- Claude Code split lines are counted once. `ClaudeCodeReader` runs every event through the new `ClaudeUsageDeduper`: the first line of a `message.id` carries its usage, identical repeats lose `usage`/`normalizedUsage`, and a repeat that grew (streamed `output_tokens`) carries only the growth with `message.usageKind: 'correction'`. `EventAggregator` adds corrections to tokens, cost, and per-model tokens without counting a call, context sample, or compaction; the usage cache merges them into their message's record. The CLI follow watcher (`JsonlSessionWatcher`) and `eventBridge` apply the same rule and carry `FollowEvent.usageKind`.
+- Codex duplicate `token_count` events are counted once. New `resolveCodexCallUsage(info, previousTotal)`: an unchanged `total_token_usage` yields no usage (rate limits still pass through), a missing `last_token_usage` yields the growth of the cumulative total instead of the total, and a total that drops re-baselines. Used by `CodexRolloutParser` and the Codex branch of `JsonlSessionWatcher`, which also splits cached input into `cacheTokens` now.
+- `sessionMessageSchema` accepts `stop_reason: null` (normalized to absent); such lines used to fail validation and drop the whole event.
+- `<synthetic>` Claude messages carry no usage, so they add no call, unpriced model row, or heuristic compaction.
+- Codex `scanSubagents()` finds spawned subagents through the new `CodexDatabase.getSpawnedChildThreads()` (`threads.source`), and `getThreadsByForkedFromId()` only queries when the column exists. The filesystem fallback also matches `source.subagent.thread_spawn.parent_thread_id`.
+- `SubagentStats` from every provider (Claude scanners, Codex, OpenCode) now fill `cacheReadTokens`, `cacheWriteTokens`, `reasoningTokens`, and `totalTokens` from normalized, deduplicated usage. Claude scanners read `agent-*.meta.json` (`readAgentMeta()`). Parsed subagent transcripts are cached by size and mtime.
+- Timeline `metadata.tokenCount` and the HTML report's per-message tokens are cache-inclusive totals instead of input + output.
+
+### Added
+
+- `sessionTokenTotals`: `collectSessionTokenTotals(provider, sessionPath, { mainThread? })`, `combineSessionTokenTotals()`, `readMainThreadTokenTotals()`, `scanSessionSubagents()`, `subagentTokenTotals()`, and the `SessionTokenTotals` / `SubagentTokenSummary` types: main thread, per-subagent, subagent total, and combined, in the `summarizeTokens` vocabulary.
+- `formatTokenBreakdown(summary, fmt?)`; `TokenSummary.reasoning` and `billedOutsideBuckets`; `TokenTotalsLike.reasoningTokens`; labels `TOKEN_MAIN_THREAD_LABEL`, `TOKEN_SUBAGENTS_LABEL`, `TOKEN_SESSION_TOTAL_LABEL`. `sumTokenTotals()` sums `reasoningTokens`, and `totalTokens` when every record has one.
+- `formatSessionText`/`formatSessionMarkdown`/`formatSessionJson` and `HtmlReportOptions` accept `subagents`; the JSON dump adds `tokenSummary` (`mainThread`, `subagents`, `subagentTotal`, `combined`). `readSessionReportInputs()` returns `subagents`.
+- `usageKind` on `SessionMessage`, `TokenUsage` (from `extractTokenUsage`), and `FollowEvent`; `StateFileContext.totalTokens` (optional); `CodexDbThread.source`, `agent_nickname`, `agent_role`.
+- Exports: `ClaudeUsageDeduper`, `SYNTHETIC_MODEL`, `dedupedRawClaudeUsage`, `normalizeClaudeUsage`, `addUsageToSubagent`, `resolveCodexCallUsage`, `readAgentMeta` (root); the session-total helpers also from `sidekick-shared/node`; `ClaudeUsageDeduper` and `SYNTHETIC_MODEL` from `sidekick-shared/browser`.
+
+### Changed
+
+- `collectUsageEvents()` reads Claude Code subagent transcripts (`<sessionId>/subagents/agent-*.jsonl`) with their parent session, and their sizes and mtimes join the fingerprint. Codex subagents are separate rollouts and are not added twice.
+- `USAGE_CACHE_VERSION` is 2 and `SNAPSHOT_SCHEMA_VERSION` is 6, so caches built with the old counting are re-read.
+- The text dump's compaction line reads "Context management:" and per-model token columns use "Total (incl. cache)"; the HTML report's "Cache" card is now "Cache hit".
+
 ## [0.27.2] - 2026-09-22
 
 ### Fixed

package/README.md

@@ -9,6 +9,8 @@ Types, parsers, providers, readers, formatters, aggregation, search, reporting,
 
 ## Recent additions
 
+- **0.27.4: usage events from the Node entry** — `sidekick-shared/node` now exports `createSessionProviders()`, `SYNTHETIC_MODEL`, and the `ProviderId` / `SessionProviderBase` / `SessionProviderDiagnostic` / `CreateSessionProviders*` types, so `collectUsageEvents()` callers never import the package root (a CommonJS barrel that bundlers cannot tree-shake). `collectUsageEvents()` accepts an optional `signal` that stops the collection before listing and between sessions.
+- **0.27.3: honest session totals** — Claude Code split lines are counted once: `ClaudeUsageDeduper` keeps a `message.id`'s first usage, strips identical repeats, and turns streamed growth into a `usageKind: 'correction'` delta that `EventAggregator` adds to tokens and cost without counting another call. `resolveCodexCallUsage()` drops duplicate Codex `token_count` events. `collectSessionTokenTotals()` (root and Node) returns `mainThread`, per-`subagents`, `subagentTotal`, and `combined` in the `summarizeTokens()` vocabulary, and `formatTokenBreakdown()` renders one line whose parts add up to the headline. `TokenSummary` gains `reasoning` / `billedOutsideBuckets`, and `SubagentStats` from every provider now carries cache, reasoning, and total tokens. The session dumps and `HtmlReportOptions` accept `subagents`, `readSessionReportInputs()` returns them, `collectUsageEvents()` reads Claude Code subagent transcripts, and `USAGE_CACHE_VERSION` 2 re-reads caches built with the old counting.
 - **0.27.2: streamed prompt history** — `collectPromptHistory()` reads session logs of any size in bounded, resumable passes instead of skipping files over `maxFileBytes`: every call keeps what it read, the cursor (`version: 3`) continues where each file stopped, and a pending prompt keeps its answer state so a far-away answer still settles it. Adds `maxRecordBytes` and `maxEntries` bounds, `hasMore`, permanently skipped records in `exclusions`, and rewrite detection.
 - **0.27.1: late prompt metadata** — `collectPromptHistory()` returns a prompt again, with the same provider, sessionId, ordinal, timestamp, and text, when its first answering call is written after an earlier collection, and entries gain `metadataStatus` (`pending` / `provisional` / `final`). The cursor becomes `version: 2`, keeps a replay offset and metadata digest for the one open prompt per file (no prompt text), and still accepts 0.27.0 cursors.
 - **0.27.0: human prompt history** — `collectPromptHistory()` (Node-only) returns the prompts a person typed in Claude Code and Codex sessions under a set of workspace roots (plus git worktree siblings), with fail-closed cwd scoping, untruncated text, stable per-session ordinals, the answering model and usage, a JSON-serializable resume cursor, and bounds that stop cleanly and report themselves in `boundsHit`. `isHumanPrompt()` / `humanPromptText()` expose the same classification for any canonical transcript message, and transcript provenance now keeps Claude Code's `isCompactSummary`, `originKind`, and `promptSource`. Claude Opus 5.5 gets its own pricing and context entries.
@@ -100,14 +102,14 @@ returns the platform default that both overrides bypass.
 | **Observed Sessions (V1)**        | Versioned provider-neutral observation contracts — `createProviderSessionAdapterV1()` / `derivePendingUserRequestV1()` with `ObservedAgentSessionV1`, `ProviderCapabilitiesV1`, `PendingUserRequestV1`, `SessionEvidenceRefV1`, and provenance/confidence wrapper types (Zod schemas in `sidekick-shared/schemas`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | **Parsers**                       | JSONL event parsing, OpenCode/Codex format normalization, subagent scanning, session path resolution, debug log parsing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | **Watchers**                      | Live session file watching with event bridging, plus `createJsonlTail()` for raw incremental JSONL consumers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| **Formatters**                    | Display helpers (`formatTokenCount()`, `formatDurationMs()`), tool summary, noise classification, session dump (text/markdown/JSON), event highlighting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| **Formatters**                    | Display helpers (`formatTokenCount()`, `formatDurationMs()`), the shared token vocabulary (`summarizeTokens()`, `formatTokenBreakdown()`, `TOKEN_*_LABEL`s) and session totals incl. subagents (`collectSessionTokenTotals()`), tool summary, noise classification, session dump (text/markdown/JSON), event highlighting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | **Search**                        | Cross-session full-text search, advanced filtering (substring, fuzzy, regex, date)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | **Aggregation**                   | Event aggregation, frequency tracking, activity heatmaps, pattern extraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | **Analytics**                     | Session-quality scoring (beta) with factor contributions and weekly trends (`scoreSessionQuality()`, `calculateQualityTrend()`), code-impact metrics including cost per changed line and per-model churn/cost (`calculateCodeImpact()`), and reported-vs-heuristic compaction accounting (`calculateCompactionLedger()`, `formatCompactionLedger()`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **Error History**                 | Shared error taxonomy (`categorizeError()`, `extractErrorMessage()`) plus append-only per-project failure history (`appendErrorHistory()`, `readErrorHistory()`, `getTopFailingTools()`) behind per-tool/hour/model error rollups                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | **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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| **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)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | **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                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | **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()`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -117,7 +119,7 @@ returns the platform default that both overrides bypass.
 | **Model Info & Pricing**          | Model family parsing (Anthropic / OpenAI / Google, including legacy `claude-3-opus-…` and `claude-3-5-sonnet-…` IDs), context-window lookup (including Fable 5.1 / Opus 5.5 / Opus 5 / Opus 4.8 / Opus 4.7 1M and GPT-5.x / GPT-6 variants), pricing tables with optional LiteLLM hydration, normalized non-double-counting cost (`calculateNormalizedUsageCost()`, fed by `normalizeProviderUsage()` / `extractNormalizedUsage()`), legacy cost helpers retained but deprecated (`calculateCost()`, `calculateCostWithProvenance()`), `mergeCostSources()`, display helpers (`shortModelName()`, `getModelDisplayInfo()`, `compareModelIds()`, `sortModelIds()`, `formatCost()`), and cross-realm catalog transfer — `exportResolvedModelCatalog()` / `importResolvedModelCatalog()` move resolved context windows and pricing (with provenance, prefix inheritance explicit) between Node and browser realms, and `registerModelAlias()` resolves short or host-specific names to canonical ids                                                                  |
 | **Quota Polling**                 | `QuotaPoller` class with exponential backoff, active/idle intervals, and cached fallback. Stays dormant while no account exists and wakes through the account-change signal                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | **Multi-Provider Quota**          | `MultiProviderQuotaService` orchestrates Claude polling + peak-hours + account labels + Codex/z.ai quota updates behind one typed event stream. `CodexQuotaWatcher` watches the active Codex rollout for live rate limits with snapshot fallback; z.ai quota uses the API resolver with snapshot fallback. All three stay dormant without a matching account and wake on account changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| **Accounts**                      | Multi-provider account registry (v2) with per-provider active account, save/switch/remove, v1 migration, `ensureDefaultAccounts()` for startup bootstrap (migrations, abandoned-login cleanup, then `syncLiveAccountState()`), `syncLiveAccountState()` to register live logins the registry has never seen under their email, fold rotated tokens into their profile, and merge duplicate Codex profiles, `getAccountHealth()` / `listAccountsWithHealth()` for secret-free `fresh`/`expiring`/`expired`/`unknown`/`missing` health with access/refresh expiry,`getActiveAccountStatus()` for a single-pass active-account read across providers,`onAccountsChanged()`for push-based login/logout/switch notification (process-local mutations, filesystem watches, and a catch-up poll), and live-first`resolveActiveClaudeAccount()`/`resolveActiveCodexAccount()` that report the currently logged-in account (self-healing the saved pointer) for display                                                                                                     |
+| **Accounts**                      | Multi-provider account registry (v2) with per-provider active account, save/switch/remove, v1 migration, `ensureDefaultAccounts()` for startup bootstrap (migrations, abandoned-login cleanup, then `syncLiveAccountState()`), `syncLiveAccountState()` to register live logins the registry has never seen under their email, fold rotated tokens into their profile, and merge duplicate Codex profiles, `getAccountHealth()` / `listAccountsWithHealth()` for secret-free `fresh`/`expiring`/`expired`/`unknown`/`missing` health with access/refresh expiry, `getActiveAccountStatus()` for a single-pass active-account read across providers, `onAccountsChanged()` for push-based login/logout/switch notification (process-local mutations, filesystem watches, and a catch-up poll), and live-first `resolveActiveClaudeAccount()` /`resolveActiveCodexAccount()` that report the currently logged-in account (self-healing the saved pointer) for display                                                                                                |
 | **Account Management 2.0**        | Provider-neutral acquisition + switching: `beginAccountLogin()` / `getAccountLoginStatus()` / `finalizeAccountLogin()` / `spawnAccountLogin()` drive a TTY-less, profile-isolated login that doesn't disturb the active account until finalization; `listAllAccounts()` and `switchAccount()` expose a shared switcher across Claude and Codex; as of 0.26.6 switches are two-phase and verified, return a `SwitchAccountResult` with `runningConsumers`, `needsLogin`, and an `undoToken` (`undoLastSwitch()`), refuse expired or missing credentials unless forced, and `beginAccountLogin({ existingAccountId })` re-authenticates a saved profile in place. Every status/finalize/switch entry point also has an `-Async` variant (`getAccountLoginStatusAsync()`, `finalizeAccountLoginAsync()`, `switchAccountAsync()`, …) that keeps `codex` CLI probes off the event loop — prefer those from hosts with a UI loop. Claude accounts get canonical profile homes with account-scoped macOS keychain suffixes and startup migration from legacy flat backups |
 | **Isolated launch & auto-switch** | `getAccountLaunchEnv()` builds an isolated `CLAUDE_CONFIG_DIR` / `CODEX_HOME` environment (plus `envUnset`) for running a CLI as a saved account without switching, `writeLauncher()` / `removeLauncher()` write POSIX launcher scripts, `detectRunningAccountConsumers()` / `findRunningProcesses()` find CLIs and desktop apps that hold a login (`ps` / `tasklist`), `refreshInactiveAccounts()` is an opt-in keep-alive through the official CLIs, and a default-off `AutoSwitchController` (`decideAutoSwitch()`) moves to a healthier saved account when quota crosses a configured threshold; its `switchAccount` callback may return a Promise and defaults to `switchAccountAsync()`                                                                                                                                                                                                                                                                                                                                                                      |
 | **Codex Profiles**                | Codex account lifecycle — prepare, finalize, switch, remove — switching atomically swaps the profile's backed-up credentials into the system `~/.codex/auth.json`, with rotated-token staleness protection, one-time dual-home migration, and legacy multi-home session monitoring                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -129,17 +131,17 @@ returns the platform default that both overrides bypass.
 
 `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()`.                                                                                                                                                                                                                                                                                                                                                                                                |
-| `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()`), session previews (`listSessionPreviews()` / `readSessionPreview()` plus the bounded-concurrency `listSessionPreviewsAsync()` / `readSessionPreviewAsync()`), Codex history/rollout lookup (`readCodexHistory()`, `findCodexRolloutFile()`), and resilient observed-session collection (`fs` + providers). |
-| `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()`.                                                                                                                                                                                                                                                                          |
+| 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()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `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()`), 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()`), and resilient observed-session collection (`fs` + providers). |
+| `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()`.                                                                                                                                                                                                                                                                                                                                                                                         |
 
 ### Browser / webview runtimes
 
@@ -272,6 +274,26 @@ for (const provider of providers) {
 
 Every provider computes `SessionFileStats` the same way — one reader pass through the shared `EventAggregator` — so per-model `tokens` are cache-inclusive, `costUsd` carries `costProvenance`, `toolFailures` splits out failed calls, and compaction and truncation counts are real for Claude Code, Codex, and OpenCode alike. `computeSessionFileStats(events, options)` does the same for events you already hold, and `firstUserPrompt(events)` derives the label.
 
+`readSessionStats()` covers the session's own transcript. Subagents run in their own transcripts, so for a session total that includes them use `collectSessionTokenTotals()` (pass `{ mainThread }` when you already aggregated the transcript to skip re-reading it):
+
+```typescript
+import {
+  ClaudeCodeProvider,
+  collectSessionTokenTotals,
+  formatTokenBreakdown,
+  formatTokenCount,
+  TOKEN_SESSION_TOTAL_LABEL,
+} from 'sidekick-shared';
+
+const provider = new ClaudeCodeProvider();
+const totals = collectSessionTokenTotals(provider, '/path/to/session.jsonl');
+// { mainThread, subagents: [{ agentId, agentType?, description?, summary }], subagentTotal, combined }
+console.log(TOKEN_SESSION_TOTAL_LABEL, formatTokenBreakdown(totals.combined, formatTokenCount));
+for (const agent of totals.subagents) console.log(agent.agentId, agent.summary.total);
+```
+
+Every `TokenSummary` reports `total`, `context`, the four buckets, `reasoning`, and `billedOutsideBuckets` (reasoning billed outside `output`), and `formatTokenBreakdown()` shows that part only when it is non-zero, so the parts always add up to `total`.
+
 ### Read canonical session history
 
 ```typescript
@@ -460,6 +482,27 @@ const { providers, diagnostics } = createSessionProviders({
 Repeated identical degradations are coalesced, so the diagnostic stream stays
 bounded across long-lived polling and subscription cycles.
 
+### Collect usage events from the Node entry
+
+Everything `collectUsageEvents()` needs is exported from `sidekick-shared/node`,
+which never loads the package root, so bundlers keep only what you use:
+
+```typescript
+import { collectUsageEvents, createSessionProviders, SYNTHETIC_MODEL } from 'sidekick-shared/node';
+
+const { providers } = createSessionProviders({ providerIds: ['claude-code', 'codex'] });
+const { events } = await collectUsageEvents({
+  providers,
+  since: '2026-09-01',
+  workspacePath: '/path/to/repo',
+  signal: AbortSignal.timeout(30_000), // optional: stop before listing and between sessions
+});
+const priced = events.filter((event) => event.model !== SYNTHETIC_MODEL);
+```
+
+On abort the promise rejects with the signal's reason (an `AbortError` by
+default); sessions read before the abort keep their cache entries.
+
 ### Detect the active session provider
 
 For a single-provider surface, auto-detect and construct just one:

package/dist/aggregation/EventAggregator.d.ts

@@ -13,8 +13,8 @@ import type { EventAggregatorOptions, AggregatedTokens, ModelUsageStats, BurnRat
 import type { SerializedFrequencyState } from './FrequencyTracker';
 import type { SerializedHeatmapState } from './HeatmapTracker';
 import type { SerializedPatternState } from './PatternExtractor';
-/** Schema version for serialized snapshots. */
-export declare const SNAPSHOT_SCHEMA_VERSION = 5;
+/** Schema version for serialized snapshots. v6: token totals count each Claude response and Codex call once. */
+export declare const SNAPSHOT_SCHEMA_VERSION = 6;
 /**
  * JSON-serializable snapshot of EventAggregator state.
  * Used by session snapshot sidecar files for fast resume.
@@ -187,7 +187,17 @@ export declare class EventAggregator {
     serialize(): SerializedAggregatorState;
     /** Restores mutable state from a serialized snapshot. Clears transient state (pending calls). */
     restore(state: SerializedAggregatorState): boolean;
+    /**
+     * Add one usage record to the running totals. A `'correction'` tops up a call
+     * already counted (a later split line of the same response grew), so it adds
+     * tokens and cost but no call, context sample, or compaction check.
+     */
     private accumulateUsage;
+    /**
+     * Per-model usage. Accumulate reasoning tokens and an inverted-sticky
+     * `priced` flag so one unpriced event taints the aggregate (UI renders "—").
+     */
+    private accumulateModelUsage;
     private updateBurnRate;
     private processLatency;
     private extractToolsFromContent;

package/dist/aggregation/EventAggregator.js

@@ -30,8 +30,8 @@ const DEFAULT_CONTEXT_TIMELINE_CAP = 2_000;
 const DEFAULT_BURN_WINDOW_MS = 5 * 60_000;
 const DEFAULT_BURN_SAMPLE_MS = 10_000;
 const COMPACTION_DROP_THRESHOLD = 0.8; // >20% drop
-/** Schema version for serialized snapshots. */
-exports.SNAPSHOT_SCHEMA_VERSION = 5;
+/** Schema version for serialized snapshots. v6: token totals count each Claude response and Codex call once. */
+exports.SNAPSHOT_SCHEMA_VERSION = 6;
 // ── Goal gate detection regex ──
 const GOAL_GATE_REGEX = /\b(CRITICAL|MUST|blocker|required|must.?complete|goal.?gate|essential|do.?not.?skip|blocking)\b/i;
 // ── Todo dependency parsing ──
@@ -206,7 +206,7 @@ class EventAggregator {
         // 5. Token accumulation
         const normalizedUsage = (0, usageNormalization_1.extractNormalizedUsage)(event);
         if (normalizedUsage) {
-            const usageCost = this.accumulateUsage(normalizedUsage, event.timestamp, event.message.model);
+            const usageCost = this.accumulateUsage(normalizedUsage, event.timestamp, event.message.model, event.message.usageKind);
             this.attributePlanUsage(normalizedUsage.totalTokens, usageCost);
         }
         if (event.type !== 'system') {
@@ -265,7 +265,7 @@ class EventAggregator {
                 reasoningIncludedInOutput: false,
                 reportedCostUsd: event.cost,
             });
-            const cost = this.accumulateUsage(normalized, event.timestamp, event.model);
+            const cost = this.accumulateUsage(normalized, event.timestamp, event.model, event.usageKind);
             this.attributePlanUsage(normalized.totalTokens, cost);
         }
         else if (typeof event.cost === 'number' && Number.isFinite(event.cost) && event.cost >= 0) {
@@ -637,7 +637,13 @@ class EventAggregator {
     // ═══════════════════════════════════════════════════════════════════════
     // Private: Token & Context
     // ═══════════════════════════════════════════════════════════════════════
-    accumulateUsage(usage, timestamp, model) {
+    /**
+     * Add one usage record to the running totals. A `'correction'` tops up a call
+     * already counted (a later split line of the same response grew), so it adds
+     * tokens and cost but no call, context sample, or compaction check.
+     */
+    accumulateUsage(usage, timestamp, model, kind = 'call') {
+        const isCall = kind !== 'correction';
         const inputTok = usage.uncachedInputTokens;
         const outputTok = usage.outputTokens;
         const cacheWrite = usage.cacheWriteTokens;
@@ -654,19 +660,25 @@ class EventAggregator {
         this.reasoningTokens += reasoningTok;
         this.totalTokens += usage.totalTokens;
         this.costUsd += cost;
+        const callIncrement = isCall ? 1 : 0;
         if (pricedUsage.source === 'provider-reported') {
             this.reportedCostUsd += cost;
-            this.reportedCalls += 1;
+            this.reportedCalls += callIncrement;
         }
         else if (pricedUsage.source === 'unpriced') {
-            this.unpricedCalls += 1;
+            this.unpricedCalls += callIncrement;
         }
         else {
             this.estimatedCostUsd += cost;
-            this.estimatedCalls += 1;
+            this.estimatedCalls += callIncrement;
         }
         // Burn rate sample accumulation
         this.tokensSinceLastSample += usage.totalTokens;
+        if (!isCall) {
+            this.accumulateModelUsage(usage, model, cost, priced, false);
+            this.updateBurnRate(timestamp);
+            return cost;
+        }
         // Context size computation
         let contextSize;
         if (this.computeContextSize) {
@@ -706,8 +718,21 @@ class EventAggregator {
         if (this.contextTimeline.length > this.contextTimelineCap) {
             this.contextTimeline.splice(0, this.contextTimeline.length - this.contextTimelineCap);
         }
-        // Per-model usage. Accumulate reasoning tokens and an inverted-sticky
-        // `priced` flag so one unpriced event taints the aggregate (UI renders "—").
+        this.accumulateModelUsage(usage, model, cost, priced, true);
+        // Burn rate sampling
+        this.updateBurnRate(timestamp);
+        return cost;
+    }
+    /**
+     * Per-model usage. Accumulate reasoning tokens and an inverted-sticky
+     * `priced` flag so one unpriced event taints the aggregate (UI renders "—").
+     */
+    accumulateModelUsage(usage, model, cost, priced, countCall) {
+        const inputTok = usage.uncachedInputTokens;
+        const outputTok = usage.outputTokens;
+        const cacheWrite = usage.cacheWriteTokens;
+        const cacheRead = usage.cacheReadTokens;
+        const reasoningTok = usage.reasoningTokens;
         const perModelKey = model ?? this.currentModel ?? 'unknown';
         const acc = this.modelUsage.get(perModelKey) ?? {
             calls: 0,
@@ -720,7 +745,8 @@ class EventAggregator {
             cost: 0,
             priced: true,
         };
-        acc.calls++;
+        if (countCall)
+            acc.calls++;
         acc.tokens += usage.totalTokens;
         acc.inputTokens += inputTok;
         acc.outputTokens += outputTok;
@@ -731,9 +757,6 @@ class EventAggregator {
         if (!priced)
             acc.priced = false;
         this.modelUsage.set(perModelKey, acc);
-        // Burn rate sampling
-        this.updateBurnRate(timestamp);
-        return cost;
     }
     // ═══════════════════════════════════════════════════════════════════════
     // Private: Burn Rate
@@ -1813,9 +1836,11 @@ class EventAggregator {
                 noiseLevel = 'ai';
                 if (event.message.model)
                     metadata.model = event.message.model;
-                if (event.message.usage) {
-                    metadata.tokenCount =
-                        event.message.usage.input_tokens + event.message.usage.output_tokens;
+                {
+                    // Cache-inclusive, like every other token total (see tokenSummary).
+                    const usage = (0, usageNormalization_1.extractNormalizedUsage)(event);
+                    if (usage)
+                        metadata.tokenCount = usage.totalTokens;
                 }
                 break;
             case 'tool_use': {
@@ -1892,8 +1917,13 @@ class EventAggregator {
                 noiseLevel = 'ai';
                 if (event.model)
                     metadata.model = event.model;
-                if (event.tokens)
-                    metadata.tokenCount = event.tokens.input + event.tokens.output;
+                if (event.tokens) {
+                    metadata.tokenCount =
+                        event.tokens.input +
+                            event.tokens.output +
+                            (event.cacheTokens?.read ?? 0) +
+                            (event.cacheTokens?.write ?? 0);
+                }
                 break;
             case 'tool_use':
                 tlType = 'tool_call';

package/dist/browser.d.ts

@@ -11,8 +11,9 @@ export { getModelContextWindowSize, resolveModelContextWindow, DEFAULT_CONTEXT_W
 export type { ModelCatalogMatch, ModelContextWindowProvenance, ModelContextWindowSource, ResolvedModelContextWindow, } from './modelContext';
 export { normalizeProviderUsage, extractNormalizedUsage, calculateNormalizedUsageCost, } from './usageNormalization';
 export type { UsageProvider, UsageSemantics, UsageNormalizationProvenance, ProviderUsageInput, AnthropicUsageInput, OpenAIUsageInput, SidekickUsageInput, NormalizedUsage, PricingProvenance, NormalizedUsageCostInput, NormalizedUsageCost, } from './usageNormalization';
-export { summarizeTokens, sumTokenTotals, TOKEN_CONTEXT_LABEL, TOKEN_TOTAL_LABEL, } from './tokenSummary';
+export { formatTokenBreakdown, summarizeTokens, sumTokenTotals, TOKEN_CONTEXT_LABEL, TOKEN_MAIN_THREAD_LABEL, TOKEN_SESSION_TOTAL_LABEL, TOKEN_SUBAGENTS_LABEL, TOKEN_TOTAL_LABEL, } from './tokenSummary';
 export type { TokenSummary, TokenTotalsLike } from './tokenSummary';
+export { ClaudeUsageDeduper, SYNTHETIC_MODEL } from './usage/claudeUsageDedupe';
 export { estimateTextTokens, estimateSerializedTokens } from './tokenEstimation';
 export type { ExactTokenCounterContext, ExactTokenCounter, TokenEstimationMethod, TokenEstimationConfidence, TokenEstimationOptions, TokenEstimate, } from './tokenEstimation';
 export { projectSessionTranscript } from './transcript';

package/dist/browser.js

@@ -9,8 +9,8 @@
  * For pricing hydration (LiteLLM catalog refresh), use `sidekick-shared/node`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESOLVED_MODEL_CATALOG_SCHEMA_VERSION = exports.resolveModelAlias = exports.registerModelAlias = exports.importResolvedModelCatalog = exports.exportResolvedModelCatalog = exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.resolveModelPricing = exports.getModelPricing = exports.parseModelId = exports.segmentAssistantTurn = exports.reasoningSummary = exports.isAssistantTurnSubagentTool = exports.extractTurnSubagents = exports.assistantTurnEventsFromSessionEvents = exports.SESSION_PROVIDER_IDS = exports.RUNTIME_QUOTA_PROVIDER_IDS = exports.QUOTA_PROVIDER_IDS = exports.MODEL_PROVIDER_IDS = exports.ACCOUNT_PROVIDER_IDS = exports.createSessionContextProjector = exports.calculateSessionContextPressure = exports.buildSessionContextSnapshot = exports.parseMcpToolName = exports.parseLocalDateKey = exports.formatTokenCount = exports.formatLocalDateKey = exports.formatDurationMs = exports.addLocalDays = exports.projectSessionTranscript = exports.estimateSerializedTokens = exports.estimateTextTokens = exports.TOKEN_TOTAL_LABEL = exports.TOKEN_CONTEXT_LABEL = exports.sumTokenTotals = exports.summarizeTokens = exports.calculateNormalizedUsageCost = exports.extractNormalizedUsage = exports.normalizeProviderUsage = exports.DEFAULT_CONTEXT_WINDOW = exports.resolveModelContextWindow = exports.getModelContextWindowSize = void 0;
-exports.diagnoseProviderFailure = exports.mergeFailingToolWindows = exports.failingToolTrend = exports.FAILING_TOOL_TREND_ARROWS = exports.sessionSummaryFromStats = exports.removeSessionSummary = exports.markFileImported = exports.isFileImported = exports.applySessionSummary = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.findActiveBillingBlock = exports.computeBillingBlocks = exports.BILLING_BLOCK_DURATION_MS = void 0;
+exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.resolveModelPricing = exports.getModelPricing = exports.parseModelId = exports.segmentAssistantTurn = exports.reasoningSummary = exports.isAssistantTurnSubagentTool = exports.extractTurnSubagents = exports.assistantTurnEventsFromSessionEvents = exports.SESSION_PROVIDER_IDS = exports.RUNTIME_QUOTA_PROVIDER_IDS = exports.QUOTA_PROVIDER_IDS = exports.MODEL_PROVIDER_IDS = exports.ACCOUNT_PROVIDER_IDS = exports.createSessionContextProjector = exports.calculateSessionContextPressure = exports.buildSessionContextSnapshot = exports.parseMcpToolName = exports.parseLocalDateKey = exports.formatTokenCount = exports.formatLocalDateKey = exports.formatDurationMs = exports.addLocalDays = exports.projectSessionTranscript = exports.estimateSerializedTokens = exports.estimateTextTokens = exports.SYNTHETIC_MODEL = exports.ClaudeUsageDeduper = exports.TOKEN_TOTAL_LABEL = exports.TOKEN_SUBAGENTS_LABEL = exports.TOKEN_SESSION_TOTAL_LABEL = exports.TOKEN_MAIN_THREAD_LABEL = exports.TOKEN_CONTEXT_LABEL = exports.sumTokenTotals = exports.summarizeTokens = exports.formatTokenBreakdown = exports.calculateNormalizedUsageCost = exports.extractNormalizedUsage = exports.normalizeProviderUsage = exports.DEFAULT_CONTEXT_WINDOW = exports.resolveModelContextWindow = exports.getModelContextWindowSize = void 0;
+exports.diagnoseProviderFailure = exports.mergeFailingToolWindows = exports.failingToolTrend = exports.FAILING_TOOL_TREND_ARROWS = exports.sessionSummaryFromStats = exports.removeSessionSummary = exports.markFileImported = exports.isFileImported = exports.applySessionSummary = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.findActiveBillingBlock = exports.computeBillingBlocks = exports.BILLING_BLOCK_DURATION_MS = exports.RESOLVED_MODEL_CATALOG_SCHEMA_VERSION = exports.resolveModelAlias = exports.registerModelAlias = exports.importResolvedModelCatalog = exports.exportResolvedModelCatalog = exports.formatCost = void 0;
 var modelContext_1 = require("./modelContext");
 Object.defineProperty(exports, "getModelContextWindowSize", { enumerable: true, get: function () { return modelContext_1.getModelContextWindowSize; } });
 Object.defineProperty(exports, "resolveModelContextWindow", { enumerable: true, get: function () { return modelContext_1.resolveModelContextWindow; } });
@@ -20,10 +20,17 @@ Object.defineProperty(exports, "normalizeProviderUsage", { enumerable: true, get
 Object.defineProperty(exports, "extractNormalizedUsage", { enumerable: true, get: function () { return usageNormalization_1.extractNormalizedUsage; } });
 Object.defineProperty(exports, "calculateNormalizedUsageCost", { enumerable: true, get: function () { return usageNormalization_1.calculateNormalizedUsageCost; } });
 var tokenSummary_1 = require("./tokenSummary");
+Object.defineProperty(exports, "formatTokenBreakdown", { enumerable: true, get: function () { return tokenSummary_1.formatTokenBreakdown; } });
 Object.defineProperty(exports, "summarizeTokens", { enumerable: true, get: function () { return tokenSummary_1.summarizeTokens; } });
 Object.defineProperty(exports, "sumTokenTotals", { enumerable: true, get: function () { return tokenSummary_1.sumTokenTotals; } });
 Object.defineProperty(exports, "TOKEN_CONTEXT_LABEL", { enumerable: true, get: function () { return tokenSummary_1.TOKEN_CONTEXT_LABEL; } });
+Object.defineProperty(exports, "TOKEN_MAIN_THREAD_LABEL", { enumerable: true, get: function () { return tokenSummary_1.TOKEN_MAIN_THREAD_LABEL; } });
+Object.defineProperty(exports, "TOKEN_SESSION_TOTAL_LABEL", { enumerable: true, get: function () { return tokenSummary_1.TOKEN_SESSION_TOTAL_LABEL; } });
+Object.defineProperty(exports, "TOKEN_SUBAGENTS_LABEL", { enumerable: true, get: function () { return tokenSummary_1.TOKEN_SUBAGENTS_LABEL; } });
 Object.defineProperty(exports, "TOKEN_TOTAL_LABEL", { enumerable: true, get: function () { return tokenSummary_1.TOKEN_TOTAL_LABEL; } });
+var claudeUsageDedupe_1 = require("./usage/claudeUsageDedupe");
+Object.defineProperty(exports, "ClaudeUsageDeduper", { enumerable: true, get: function () { return claudeUsageDedupe_1.ClaudeUsageDeduper; } });
+Object.defineProperty(exports, "SYNTHETIC_MODEL", { enumerable: true, get: function () { return claudeUsageDedupe_1.SYNTHETIC_MODEL; } });
 var tokenEstimation_1 = require("./tokenEstimation");
 Object.defineProperty(exports, "estimateTextTokens", { enumerable: true, get: function () { return tokenEstimation_1.estimateTextTokens; } });
 Object.defineProperty(exports, "estimateSerializedTokens", { enumerable: true, get: function () { return tokenEstimation_1.estimateSerializedTokens; } });

package/dist/extractors/tokenUsage.js

@@ -39,5 +39,6 @@ function extractTokenUsage(event) {
         timestamp: new Date(event.timestamp),
         reportedCost: usage.reported_cost,
         reasoningTokens: usage.reasoning_tokens,
+        ...(event.message?.usageKind ? { usageKind: event.message.usageKind } : {}),
     };
 }

package/dist/formatters/sessionDump.d.ts

@@ -7,6 +7,7 @@
  * @module formatters/sessionDump
  */
 import type { AggregatedMetrics } from '../aggregation/types';
+import type { SubagentStats } from '../types/sessionEvent';
 /** Options for text and markdown formatters. */
 export interface SessionDumpOptions {
     /** Terminal width for text output (default 120). */
@@ -15,11 +16,18 @@ export interface SessionDumpOptions {
     expand?: boolean;
     /** Session file name to display in markdown summary table. */
     sessionFileName?: string;
+    /**
+     * The session's subagents (`provider.scanSubagents()`). Their tokens are
+     * reported beside the main thread and added to the session total.
+     */
+    subagents?: readonly SubagentStats[];
 }
 /**
- * Serialize aggregated metrics as pretty-printed JSON.
+ * Serialize aggregated metrics as pretty-printed JSON, plus a `tokenSummary`
+ * block in the shared vocabulary: `mainThread`, per-subagent summaries,
+ * `subagentTotal`, and `combined` (main thread plus subagents).
  */
-export declare function formatSessionJson(metrics: AggregatedMetrics): string;
+export declare function formatSessionJson(metrics: AggregatedMetrics, options?: Pick<SessionDumpOptions, 'subagents'>): string;
 /**
  * Format aggregated metrics as a plain-text report.
  */