sidekick-shared 0.27.1 → 0.27.3

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.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
+
+- `collectPromptHistory()` streams session files instead of reading each unread range into one buffer. A file whose unread part exceeded `maxFileBytes` used to be skipped on every call; now it is read in 1 MiB chunks up to `maxFileBytes` per call, stops after a complete line, keeps what it returned, and continues on the next call (cursor `backlog: true`), even if its size and mtime are unchanged. Memory stays near one chunk plus one record. Deadline, abort, `maxSessions`, `maxTotalBytes`, and the new `maxEntries` stop at the last complete line the same way instead of discarding the partly read file. The first file of a call always finishes its first record, so a record larger than the budget cannot stall. Lines split only at `\n`, so UTF-8 characters across chunk edges decode exactly; half-written final lines and bytes appended during a call wait for the next call.
+- Late answer metadata no longer depends on a replay window. `pending` now keeps `lineBytes`, `timestamp`, and `answer: { status, id?, model?, usage? }` (answer state, never text), the scan continues from the file's offset however far the answer is, and only the prompt's own line is re-read (and verified against its length and timestamp) when the prompt must be returned again. Replays that 0.27.1 dropped for exceeding `maxFileBytes` no longer happen.
+
+### Added
+
+- Bounds `maxRecordBytes` (default 16 MiB; a longer record is skipped as it streams past, without buffering, even across calls while it is still being written) and `maxEntries` (default 10 000), and bound name `'maxEntries'`.
+- `PromptHistoryResult.hasMore` (a bound left bytes or files unread) and `exclusions: PromptHistoryExclusion[]` (`{ provider, sessionId, reason: 'oversizedRecord' | 'malformedRecord', offset }`, up to 1000 per call). These are the only permanent exclusions; a prompt inside such a record is lost and consumes no ordinal.
+- Stats `sessionsWithBacklog`, `sessionsRewritten`, `recordsOverSizeLimit`, and `recordsMalformed`; types `PromptHistoryAnswerState` and `PromptHistoryExclusion`.
+- Rewrite detection: a file that shrank below its offset, whose first 4 KiB digest (`head`) changed, whose resume point no longer follows a newline, or whose pending prompt line no longer matches is read again from the start with fresh ordinals.
+
+### Changed
+
+- The cursor is `version: 3`: sessions gain optional `backlog`, `skipping`, and `head`; `pending` gains `lineBytes`, `timestamp`, and `answer`; the cursor gains `next`, the key of the file a call-wide stop left off at, where the next call starts. Version 1 and 2 cursors are accepted: each file is re-verified once, and a version 2 `pending` prompt is replayed from its line in resumable passes. Files 0.27.1 skipped for size were never in its cursor and are read in full; metadata 0.27.1 already abandoned is not recoverable. A session carried unchanged from an older cursor and not visited keeps its old shape (for example `pending` without `answer`).
+- `maxFileBytes` is now a per-file, per-call read budget instead of a skip threshold, and `stats.filesOverSizeLimit` counts files that used it up and continue on the next call.
+- The Claude first-answer fallback id for assistant records without `message.id` is the line's byte offset instead of a per-scan line index, so it stays stable across calls.
+
 ## [0.27.1] - 2026-09-22
 
 ### Fixed

package/README.md

@@ -9,6 +9,8 @@ Types, parsers, providers, readers, formatters, aggregation, search, reporting,
 
 ## Recent additions
 
+- **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.
 - **0.26.6: verified account switching** — `syncLiveAccountState()` reconciles the live Claude Code and Codex logins with saved profiles (registers unknown logins under their email, folds rotated tokens, merges duplicate Codex profiles, re-points the active pointer) and runs at startup, on account-change events, and as phase one of every switch; `getAccountHealth()` / `listAccountsWithHealth()` report secret-free `fresh | expiring | expired | unknown | missing` health; `switchAccount[Async]()` returns a `SwitchAccountResult` with verification, `runningConsumers`, `needsLogin`, and an `undoToken` for `undoLastSwitch()`; `detectRunningAccountConsumers()`, `getAccountLaunchEnv()`, `refreshInactiveAccounts()`, and `getCodexCredentialStoreMode()` are new. Claude logins run `claude auth login`, the Keychain suffix follows Claude Code 2.1.x, and the unused shell-hook helpers were removed.
@@ -99,14 +101,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()`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -116,7 +118,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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -271,6 +273,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
@@ -310,8 +332,10 @@ const result = await collectPromptHistory({
   cursor,
   bounds: {
     maxSessions: 1000,
-    maxFileBytes: 16 << 20,
+    maxFileBytes: 16 << 20, // per file per call; the rest is read next call
     maxTotalBytes: 256 << 20,
+    maxRecordBytes: 16 << 20, // one longer record is skipped and reported
+    maxEntries: 10_000,
     deadlineMs: 30_000,
   },
   signal: AbortSignal.timeout(60_000),
@@ -321,16 +345,19 @@ for (const entry of result.entries) {
   // { provider, sessionId, ordinal, timestamp, text, cwd, gitBranch?, model?, usage?, metadataStatus }
   // Upsert by (provider, sessionId, ordinal): a prompt comes back when its answer metadata changes.
 }
-saveCursor(result.cursor); // sensitive local state; unchanged files are skipped next time
-if (result.boundsHit.length > 0) console.warn('partial pass', result.boundsHit, result.stats);
+saveCursor(result.cursor); // sensitive local state; fully read unchanged files are skipped next time
+if (result.hasMore) scheduleAnotherCall(); // a bound stopped the pass; the cursor resumes it
+for (const exclusion of result.exclusions) console.warn('record left out', exclusion); // permanent
 ```
 
 - **Scope fails closed.** A prompt is returned only when its recorded working directory (the Claude line's `cwd`; the Codex `session_meta` / `turn_context` cwd) realpath-resolves to a root or somewhere inside one. Missing or unresolvable cwds are excluded and counted in `stats.promptsOutOfScope`; Codex scope never comes from the rollout's location. `cwd` is the only path in entries. Cursor keys hold no paths, but cursor values can (Codex resume state keeps the session's cwd and branch), so store the cursor as sensitive, local-only state.
 - **Parse-only.** No redaction and no network I/O; text is untruncated.
 - **Ordinals are stable.** Every human prompt in a file consumes one ordinal, even when it is out of scope, older than `since`, or lacks a timestamp (such lines are skipped and counted, never given a synthesized time). Entries are ordered by provider, session, then ordinal.
 - **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 of its line and a digest of what was returned (never prompt or answer text); the next call replays from that line and returns the prompt again, with the same provider, sessionId, ordinal, timestamp, and text, only when its model, usage, or status changed. A prompt closed by the next prompt without an answer comes back once as `final` with no usage. Consumers should upsert by identity. Cursors from 0.27.0 (`version: 1`) are accepted but cannot recover prompts they already returned without metadata.
-- **Bounds never throw.** Hitting `maxSessions`, `maxTotalBytes`, the deadline, or an abort stops the pass. An interrupted file contributes no entries, and the cursor covers only fully processed files, so the next call picks up where this one stopped. A file over `maxFileBytes` is different: it is skipped and counted in `stats.filesOverSizeLimit`, and calling again with the same bounds skips it again, so raise the bound to make progress on it. When only the replay of a pending prompt would exceed `maxFileBytes`, the replay is dropped and the file continues from its committed offset; that prompt is not revisited.
+- **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`.
+- **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.
 
 For an already-open incremental Codex rollout, keep one `CodexRolloutParser` per stream and pass each parsed `SessionEvent[]` batch to `projectSessionTranscript()` (or append the events to an existing projection). This preserves parser state for paired tool calls, model context, and cumulative token deltas; consumers should not convert raw `response_item` rows themselves.
 

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.
  */

package/dist/formatters/sessionDump.js

@@ -18,12 +18,19 @@ exports.formatDuration = formatDuration;
 const costProvenance_1 = require("../aggregation/costProvenance");
 const formatting_1 = require("../formatting");
 const tokenSummary_1 = require("../tokenSummary");
+const sessionTokenTotals_1 = require("../sessionTokenTotals");
+/** Main thread (the aggregated transcript) plus the session's subagents. */
+function sessionTokens(metrics, options) {
+    return (0, sessionTokenTotals_1.combineSessionTokenTotals)(metrics.tokens, options.subagents ?? []);
+}
 // ── JSON output ──
 /**
- * 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).
  */
-function formatSessionJson(metrics) {
-    return JSON.stringify(metrics, null, 2) + '\n';
+function formatSessionJson(metrics, options = {}) {
+    return (JSON.stringify({ ...metrics, tokenSummary: sessionTokens(metrics, options) }, null, 2) + '\n');
 }
 // ── Text output ──
 /**
@@ -40,13 +47,13 @@ function formatSessionText(metrics, options = {}) {
     lines.push(hr);
     lines.push('');
     // Token summary
-    lines.push(formatTokenSummary(metrics));
+    lines.push(...formatTokenSummary(metrics, sessionTokens(metrics, options)));
     lines.push('');
     // Model stats
     if (metrics.modelStats.length > 0) {
         lines.push('Models:');
         for (const m of metrics.modelStats) {
-            lines.push(`  ${m.model}: ${m.calls} calls, ${fmtTokens(m.tokens)} tokens, ${fmtCost(m.cost)}`);
+            lines.push(`  ${m.model}: ${m.calls} calls, ${fmtTokens(m.tokens)} total incl. cache, ${fmtCost(m.cost)}`);
         }
         lines.push('');
     }
@@ -70,7 +77,7 @@ function formatSessionText(metrics, options = {}) {
             parts.push(`${metrics.compactionCount} compaction(s)`);
         if (metrics.truncationCount > 0)
             parts.push(`${metrics.truncationCount} truncation(s)`);
-        lines.push(`Context: ${parts.join(', ')}`);
+        lines.push(`Context management: ${parts.join(', ')}`);
         lines.push('');
     }
     // Timeline
@@ -130,7 +137,18 @@ function formatSessionMarkdown(metrics, options = {}) {
     lines.push(`| Output | ${fmtTokens(metrics.tokens.outputTokens)} |`);
     lines.push(`| Cache write | ${fmtTokens(metrics.tokens.cacheWriteTokens)} |`);
     lines.push(`| Cache read | ${fmtTokens(metrics.tokens.cacheReadTokens)} |`);
-    lines.push(`| ${tokenSummary_1.TOKEN_TOTAL_LABEL} | ${fmtTokens((0, tokenSummary_1.summarizeTokens)(metrics.tokens).total)} |`);
+    const tokens = sessionTokens(metrics, options);
+    if (tokens.mainThread.billedOutsideBuckets > 0) {
+        lines.push(`| Reasoning (billed separately) | ${fmtTokens(tokens.mainThread.billedOutsideBuckets)} |`);
+    }
+    if (tokens.subagents.length > 0) {
+        lines.push(`| ${tokenSummary_1.TOKEN_MAIN_THREAD_LABEL} — ${tokenSummary_1.TOKEN_TOTAL_LABEL} | ${fmtTokens(tokens.mainThread.total)} |`);
+        lines.push(`| ${tokenSummary_1.TOKEN_SUBAGENTS_LABEL} (${tokens.subagents.length}) — ${tokenSummary_1.TOKEN_TOTAL_LABEL} | ${fmtTokens(tokens.subagentTotal.total)} |`);
+        lines.push(`| **${tokenSummary_1.TOKEN_SESSION_TOTAL_LABEL}** | **${fmtTokens(tokens.combined.total)}** |`);
+    }
+    else {
+        lines.push(`| ${tokenSummary_1.TOKEN_TOTAL_LABEL} | ${fmtTokens(tokens.mainThread.total)} |`);
+    }
     if (metrics.tokens.costUsd > 0) {
         lines.push(`| Cost | ${fmtCost(metrics.tokens.costUsd)} (${(0, costProvenance_1.describeCostProvenance)(metrics.tokens)}) |`);
     }
@@ -142,7 +160,7 @@ function formatSessionMarkdown(metrics, options = {}) {
     if (metrics.modelStats.length > 0) {
         lines.push('## Models');
         lines.push('');
-        lines.push(`| Model | Calls | Tokens | Cost |`);
+        lines.push(`| Model | Calls | ${tokenSummary_1.TOKEN_TOTAL_LABEL} | Cost |`);
         lines.push(`|-------|-------|--------|------|`);
         for (const m of metrics.modelStats) {
             lines.push(`| ${m.model} | ${m.calls} | ${fmtTokens(m.tokens)} | ${fmtCost(m.cost)} |`);
@@ -190,6 +208,16 @@ function formatSessionMarkdown(metrics, options = {}) {
         }
         lines.push('');
     }
+    if (tokens.subagents.length > 0) {
+        lines.push('## Subagent Tokens');
+        lines.push('');
+        lines.push(`| Agent | Type | Description | ${tokenSummary_1.TOKEN_TOTAL_LABEL} |`);
+        lines.push(`|-------|------|-------------|--------|`);
+        for (const agent of tokens.subagents) {
+            lines.push(`| ${agent.agentId} | ${agent.agentType ?? '-'} | ${agent.description ?? '-'} | ${fmtTokens(agent.summary.total)} |`);
+        }
+        lines.push('');
+    }
     // Timeline
     lines.push('## Timeline');
     lines.push('');
@@ -225,23 +253,17 @@ function formatHeader(metrics) {
     parts.push(`${metrics.eventCount} events`);
     return parts.join(' | ');
 }
-function formatTokenSummary(metrics) {
+function formatTokenSummary(metrics, tokens) {
     const t = metrics.tokens;
-    const total = (0, tokenSummary_1.summarizeTokens)(t).total;
-    const parts = [
-        `Tokens: ${fmtTokens(total)} total incl. cache`,
-        `(${fmtTokens(t.inputTokens)} in`,
-        `${fmtTokens(t.outputTokens)} out`,
-    ];
-    if (t.cacheReadTokens > 0)
-        parts.push(`${fmtTokens(t.cacheReadTokens)} cache-read`);
-    if (t.cacheWriteTokens > 0)
-        parts.push(`${fmtTokens(t.cacheWriteTokens)} cache-write`);
-    const line = parts.join(', ');
-    if (t.costUsd > 0) {
-        return `${line})  Cost: ${fmtCost(t.costUsd)} (${(0, costProvenance_1.describeCostProvenance)(t)})`;
+    let first = `Tokens: ${(0, tokenSummary_1.formatTokenBreakdown)(tokens.mainThread, fmtTokens)}`;
+    if (t.costUsd > 0)
+        first += `  Cost: ${fmtCost(t.costUsd)} (${(0, costProvenance_1.describeCostProvenance)(t)})`;
+    const lines = [first];
+    if (tokens.subagents.length > 0) {
+        lines.push(`${tokenSummary_1.TOKEN_SUBAGENTS_LABEL} (${tokens.subagents.length}): ${(0, tokenSummary_1.formatTokenBreakdown)(tokens.subagentTotal, fmtTokens)}`);
+        lines.push(`${tokenSummary_1.TOKEN_SESSION_TOTAL_LABEL}: ${fmtTokens(tokens.combined.total)}`);
     }
-    return line + ')';
+    return lines;
 }
 /** @internal Exported for tests. */
 function fmtTokens(n) {