pi-editor-footer 0.12.2 → 0.13.0

package/CHANGELOG.md

@@ -1,11 +1,58 @@
+# Changelog
+
+<!-- markdownlint-configure-file { "MD004": { "style": "asterisk" } } -->
+<!-- Bullets stay `*`: semantic-release's preset writes `*`, and this file is excluded from the
+     formatters so they cannot normalize them to `-`. Keep `# Changelog` as the FIRST line:
+     @semantic-release/changelog rewrites the title in place only while the file starts with
+     the configured `changelogTitle`, and prepends release notes above it otherwise. Do not
+     move this title below the comments, and do not remove the title. -->
+
+## [Unreleased]
+
+## [0.13.0] - 2026-09-25
+
+### Features
+
+* **cache:** add /cache graph, stats and export commands (#37)
+* **telemetry:** adopt streamed usage counts and provider-anchored TTFT (#33)
+
+### Bug Fixes
+
+* **timeline:** honor wallTime, tokens and cost toggles in Agent-run rows (#38)
+* **cache:** resolve promptTokens name clash, pin gate test, cover entry-id truncation (#38)
+* **imports:** use .js extensions for NodeNext module resolution
+
+### Documentation
+
+* **changelog:** attribute #38 ledger entries (#38)
+* **review:** resolve architecture-review minors and fossil comments (#38)
+* **agents:** point total-input single source at cache-math (#38)
+
+### Miscellaneous Chores
+
+* **scaffold:** refresh git contract to current scaffold (#34)
+* **scaffold:** refresh git contract gate to canonical Ledger-Waiver form (#35)
+* **scaffold:** retire release-job baselines in CI workflow (#36)
+
+## [0.12.3](https://github.com/Rianico/pi-editor-footer/compare/v0.12.2...v0.12.3) (2026-09-17)
+
+### Bug Fixes
+
+* **footer:** count total input tokens in footer statistics ([a2153a1](https://github.com/Rianico/pi-editor-footer/commit/a2153a1f0f4884e3879a610744a9e664a9124053))
+
+### Documentation
+
+* **agents:** mark agent-run token accounting a scope boundary ([ffbbee2](https://github.com/Rianico/pi-editor-footer/commit/ffbbee29300a40d6963e0916c7526e0a1ce49881))
+* document total input token semantics for the footer ([9480bf9](https://github.com/Rianico/pi-editor-footer/commit/9480bf9f1508930d75a5e53b94d944d00d1f6a2a))
+
+All notable changes to this project will be documented in this file.
+
 ## [0.12.2](https://github.com/Rianico/pi-editor-footer/compare/v0.12.1...v0.12.2) (2026-09-13)
 
 ### Bug Fixes
 
 * **context:** tier-color the context window section by usage ([#30](https://github.com/Rianico/pi-editor-footer/issues/30)) ([8152d90](https://github.com/Rianico/pi-editor-footer/commit/8152d90b3c1b4013154eff95cc885e79e7564f6f))
 
-## [Unreleased]
-
 ## [0.12.1](https://github.com/Rianico/pi-editor-footer/compare/v0.12.0...v0.12.1) (2026-09-07)
 
 ### Bug Fixes
@@ -24,10 +71,6 @@
 * allow pnpm builds for esbuild and genai ([36e139e](https://github.com/Rianico/pi-editor-footer/commit/36e139e9443ef928a4366c3d7c8afe494b6e0850))
 * make prepare tolerant to missing husky for pi install ([23ebb62](https://github.com/Rianico/pi-editor-footer/commit/23ebb62cd8d732656fd113da27c807ffa34579fc))
 
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
 ## [0.11.0] - 2026-08-29
 
 ### Changed

package/README.md

@@ -12,8 +12,8 @@ A [pi](https://pi.dev) extension that turns the editor chrome into a project-awa
 
 **Footer** — single line below the input, responsive via `fitSegmentsByPriority` and `alignRight`:
 - Left: `cwd` (`·` `git branch` + status `[! ? + ↑↓]` + stashed/conflicted) `•` `runtime` (`node`/`python`/`rust`/`go`… + version) `•` `timer` (`working`/`done`)
-- Right: `tokens` (` input |  output |  $cost`) immediately next to `context` (` [bar] % · tokens/contextWindow`)
-- Separators: `·` between `cwd` and `git`, `•` as default between other left components; `tokens` sits directly left of the context bar
+- Right: `tokens` (`↑ <total input> · ↓ <output> · $<cost>`) — `↑` counts every billed input token (uncached input + cache read + cache write), so it tracks the context bar's token figure instead of `usage.input` alone
+- Separators: `·` between `cwd` and `git`, `•` as default between other left components; the `context` bar (`<pct> · <tokens>/<window> | c <hit%>`) sits on the top border next to the model label, not in the footer
 - `cwd` respects `workspaceDisplay` (`~/development/ai/pi-skill-desc` vs `pi-skill-desc`, switchable in settings)
 - `context` bar uses `stressColor` and `renderBar` (12 cols max) with `•`/`·` handling
 - Extension statuses line (`wrapTextWithAnsi`) when `footerSegments.extensionStatuses`
@@ -58,7 +58,6 @@ pi-editor-footer/
 │   ├── index.ts               # extension entry, widget/header/footer install, /model-info
 │   ├── tracking-editor.ts     # TrackingEditor (Editor slot, highlight, border, cursor)
 │   ├── footer.ts              # renderFooter / installFooter (cwd·git • runtime • tokens·context)
-│   ├── header.ts              # header disabled, cwd preserved in footer
 │   ├── detail-render.ts       # wrap/scroll/ellipsis (tested)
 │   ├── window-presentation.ts # bordered themed box (tested)
 │   ├── model-info.ts          # top border glow+label

package/dist/agent-run-ledger.js

@@ -8,7 +8,7 @@
  * occupancy, capped to contextWindow and session totals.
  *
  * Previously this logic was scattered across 3 call sites (telemetry.peekAgentLive
- * max-vs-sum, live-border.refreshContextBar 70L capping, index.agent_settled 60L
+ * max-vs-sum, the context-bar refresh since moved into live-border (then 70L capping), index.agent_settled 60L
  * baseline fallback) with divergent caps. Bugs required holding 3 sites in one head.
  *
  * Depth: small interface (setBaseline / startRun / recordTurn / getTotals / getLive
@@ -62,6 +62,9 @@ export function aggregateAgentTurns(turns, live, startMs, now) {
     let stallCount = 0;
     let generationMs = 0;
     let ttftMs = 0;
+    // First observed provider TTFT across turns (run's initial request latency);
+    // null when no turn saw before_provider_request. Mirrors ttftMs below.
+    let ttftProviderMs = null;
     for (const t of turns) {
         inputTokens = Math.max(inputTokens, t.inputTokens);
         outputTokens += t.outputTokens;
@@ -72,6 +75,7 @@ export function aggregateAgentTurns(turns, live, startMs, now) {
     }
     if (turns.length > 0)
         ttftMs = turns[0].ttftMs;
+    ttftProviderMs = turns.map((t) => t.ttftProviderMs).find((v) => v != null) ?? null;
     if (live) {
         inputTokens = Math.max(inputTokens, live.inputTokens);
         outputTokens += live.outputTokens;
@@ -81,6 +85,8 @@ export function aggregateAgentTurns(turns, live, startMs, now) {
         generationMs += live.generationMs;
         if (ttftMs === 0)
             ttftMs = live.ttftMs;
+        if (ttftProviderMs === null)
+            ttftProviderMs = live.ttftProviderMs ?? null;
     }
     totalTokens = inputTokens + outputTokens;
     const totalMs = startMs === null ? 0 : Math.max(0, now - startMs);
@@ -101,6 +107,7 @@ export function aggregateAgentTurns(turns, live, startMs, now) {
         totalTokens,
         costUsd: validCost ? costUsd : 0,
         measurementMs,
+        ttftProviderMs,
         estimated: live?.estimated === true,
     };
 }
@@ -246,47 +253,6 @@ export class AgentRunLedger {
             cost: snapshotTotals.cost,
         };
     }
-    /**
-     * Idle display totals for LiveBorder when not running.
-     * Prefers liveAgent/liveTelemetry when available; else baseline delta, capped to idle.
-     */
-    getIdleDisplayTotals(snapshotTotals, contextTokens, liveAgent) {
-        let displayInput;
-        let displayOutput;
-        let displayCost;
-        if (liveAgent) {
-            displayInput = liveAgent.inputTokens;
-            displayOutput = liveAgent.outputTokens;
-            displayCost = liveAgent.costUsd;
-        }
-        else if (this.baseline) {
-            const d = deltaFromBaseline(snapshotTotals, this.baseline);
-            displayInput = d.input;
-            displayOutput = d.output;
-            displayCost = d.cost;
-        }
-        else {
-            displayInput = snapshotTotals.input;
-            displayOutput = snapshotTotals.output;
-            displayCost = snapshotTotals.cost;
-        }
-        const cappedInput = capInputForIdle(displayInput, contextTokens, snapshotTotals.input);
-        return {
-            tps: null,
-            ttftMs: 0,
-            totalMs: 0,
-            inputTokens: cappedInput,
-            outputTokens: displayOutput,
-            stallMs: 0,
-            stallCount: 0,
-            rateUsdPerMTokens: null,
-            generationMs: 0,
-            totalTokens: cappedInput + displayOutput,
-            costUsd: displayCost,
-            measurementMs: null,
-            estimated: false,
-        };
-    }
     /**
      * Idle authoritative display (hybrid Q7 b): snapshot delta capped, for use when
      * not running to show billed total without ~ after agent_end.
@@ -323,36 +289,6 @@ export class AgentRunLedger {
             estimated: false,
         };
     }
-    /**
-     * Live display totals when running: liveTurn input (current window) replaces
-     * agentLive input, output/cost remain per-agent sum, capped to live context only.
-     * @deprecated — retained for backward compat; prefer getIncrementalLiveDisplayTotals for Q1/Q9.
-     */
-    getLiveDisplayTotals(liveTurn, agentLive, contextTokens) {
-        if (!agentLive && !liveTurn)
-            return null;
-        let displayLive = agentLive;
-        if (agentLive && liveTurn) {
-            displayLive = {
-                ...agentLive,
-                inputTokens: liveTurn.inputTokens,
-                totalTokens: liveTurn.inputTokens + agentLive.outputTokens,
-            };
-        }
-        else if (!agentLive && liveTurn) {
-            // Edge: no agent yet but liveTurn exists — use liveTurn window
-            displayLive = liveTurn;
-        }
-        if (!displayLive)
-            return null;
-        const cappedInput = capInputForLive(displayLive.inputTokens, contextTokens);
-        return {
-            ...displayLive,
-            inputTokens: cappedInput,
-            totalTokens: cappedInput + displayLive.outputTokens,
-            estimated: true,
-        };
-    }
     /**
      * Incremental live display (Q1/Q6/Q9): trigger + Σ(outputs+tools) + liveDelta, capped to live.
      * Replaces max(input) with synthetic accumulation, per-agent_run independent.

package/dist/ansi-color.js

@@ -16,11 +16,11 @@ const BASIC16 = [
     [0, 255, 255],
     [255, 255, 255],
 ];
-/** 6x6x6 colour-cube channel values (indices 0-5). */
+/** 6x6x6 color-cube channel values (indices 0-5). */
 const CUBE_VALUES = [0, 95, 135, 175, 215, 255];
 /** Grayscale ramp values (indices 232-255: 24 grays from 8 to 238). */
 const GRAY_VALUES = Array.from({ length: 24 }, (_, i) => 8 + i * 10);
-/** Anything but the truecolor marker means the 256-colour ramp. */
+/** Anything but the truecolor marker means the 256-color ramp. */
 export function normalizeColorMode(mode) {
     return mode === "truecolor" ? "truecolor" : "256color";
 }
@@ -74,7 +74,7 @@ function colorDistance(r1, g1, b1, r2, g2, b2) {
     // Weighted Euclidean distance (the eye is more sensitive to green).
     return dr * dr * 0.299 + dg * dg * 0.587 + db * db * 0.114;
 }
-/** Quantise RGB to the closest xterm-256 index (same rule as the theme loader). */
+/** Quantize RGB to the closest xterm-256 index (same rule as the theme loader). */
 export function rgbTo256(r, g, b) {
     const rIdx = findClosestCubeIndex(r);
     const gIdx = findClosestCubeIndex(g);
@@ -90,7 +90,7 @@ export function rgbTo256(r, g, b) {
     const grayIndex = 232 + grayIdx;
     const grayDist = colorDistance(r, g, b, grayValue, grayValue, grayValue);
     const spread = Math.max(r, g, b) - Math.min(r, g, b);
-    // Only consider grayscale when the colour is nearly neutral AND closer.
+    // Only consider grayscale when the color is nearly neutral AND closer.
     if (spread < 10 && grayDist < cubeDist)
         return grayIndex;
     return cubeIndex;
@@ -126,14 +126,14 @@ export function parseFgAnsiToRgb(theme, color) {
         return indexToRgb(Number(palette[1]));
     return null;
 }
-/** SGR foreground sequence for an RGB value at the terminal's colour fidelity. */
+/** SGR foreground sequence for an RGB value at the terminal's color fidelity. */
 export function rgbToFgAnsi({ r, g, b }, mode) {
     return normalizeColorMode(mode) === "truecolor"
         ? `\x1b[38;2;${r};${g};${b}m`
         : `\x1b[38;5;${rgbTo256(r, g, b)}m`;
 }
 /**
- * Colour `s` with an exact hex, bypassing the theme's named-token lookup.
+ * Color `s` with an exact hex, bypassing the theme's named-token lookup.
  * Returned painter resets only the foreground (`\x1b[39m`), matching `theme.fg`.
  */
 export function hexFg(hex, mode) {

package/dist/border-renderer.js

@@ -1,5 +1,5 @@
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { applyModelInfo, buildLabel } from "./model-info.js";
+import { buildLabel, resolveThinkingGlow } from "./model-info.js";
 function stripAnsi(s) {
     return s.replace(/\x1b\[[0-9;]*m/g, "");
 }
@@ -28,18 +28,9 @@ export class BorderRenderer {
         if (hasTop) {
             const theme = this.getLiveTheme();
             const info = this.getModelInfo();
-            const glow = (s) => {
-                try {
-                    const maybeGlow = // SAFETY: intentional unsafe cast — validated at runtime
-                     theme.getThinkingBorderColor;
-                    if (typeof maybeGlow === "function")
-                        return maybeGlow.call(theme, info.level)(s);
-                }
-                catch {
-                    // SAFETY: best-effort UI, ignore recoverable error
-                }
-                return s;
-            };
+            // C3: single glow home in model-info.ts; identity fallback explicit at this site.
+            const glowFor = resolveThinkingGlow(theme);
+            const glow = (s) => (glowFor ? glowFor(info.level, s) : s);
             // When tokens line exists, right moves to that line (one padding) — don't duplicate on top
             const topRightForTop = opts.topTokensText ? "" : opts.topRightText;
             if (opts.glowEnabled) {
@@ -53,8 +44,7 @@ export class BorderRenderer {
                     out = embedTopWithLeftAndRight(out, width, leftLabel, topRightForTop, glow);
                 }
                 else {
-                    // Only left (model+context), no right — use applyModelInfo replacement but with combined left
-                    // Reuse embedTopWithLeftAndRight with empty right
+                    // Only left (model+context), no right — reuse embedTopWithLeftAndRight with empty right
                     out = embedTopWithLeftAndRight(out, width, leftLabel, "", glow);
                 }
             }
@@ -90,18 +80,9 @@ export class BorderRenderer {
         // Bottom embedding (telemetry left/right)
         if (opts.telemetryText || opts.bottomLeftText) {
             const theme = this.getLiveTheme();
-            const glow = (s) => {
-                try {
-                    const maybeGlow = // SAFETY: intentional unsafe cast — validated at runtime
-                     theme.getThinkingBorderColor;
-                    if (typeof maybeGlow === "function")
-                        return maybeGlow.call(theme, this.getModelInfo().level)(s);
-                }
-                catch {
-                    // SAFETY: best-effort UI, ignore recoverable error
-                }
-                return s;
-            };
+            // C3: single glow home; this site re-reads the live model level per call — kept explicit.
+            const glowFor = resolveThinkingGlow(theme);
+            const glow = (s) => (glowFor ? glowFor(this.getModelInfo().level, s) : s);
             out = embedBottomBorder(out, width, opts.bottomLeftText ?? "", opts.telemetryText ?? "", glow);
         }
         return out;
@@ -190,7 +171,7 @@ function embedTopRightBorder(lines, width, rightText, getGlow) {
     if (/^─── [↑↓] \d+ more/.test(plainTop))
         return lines;
     const rightW = visibleWidth(rightText);
-    // left label already embedded by applyModelInfo — its visible width is width - middle - right
+    // left label already embedded on the top border — its visible width is width - middle - right
     // We need to truncate right if too wide, preserving at least 10 chars for left
     const maxRight = Math.max(0, width - 12);
     let displayRight = rightText;

package/dist/cache-command.js

@@ -0,0 +1,99 @@
+import { exportStatsCsv } from "./cache-export.js";
+import { GRAPH_VIEWS, graphViewLabel, renderGraphBody, } from "./cache-graph-view.js";
+import { ScrollDialog } from "./cache-scroll-dialog.js";
+import { collectCacheSessionMetrics } from "./cache-session-data.js";
+import { renderStatsBody } from "./cache-stats-view.js";
+import { chartGlyphsForMode } from "./icons.js";
+function normalizeSubcommand(args) {
+    return args.trim().toLowerCase();
+}
+function usageText() {
+    return "Usage: /cache graph | /cache stats | /cache export";
+}
+const OVERLAY_OPTIONS = {
+    anchor: "center",
+    width: "90%",
+    maxHeight: "90%",
+    margin: 1,
+};
+const SUBCOMMANDS = [
+    { value: "graph", label: "graph", description: "Show cache hit % graph over time" },
+    { value: "stats", label: "stats", description: "Show token/cache breakdown table" },
+    { value: "export", label: "export", description: "Export stats data to a CSV at project root" },
+];
+export function registerCacheCommand(pi, options) {
+    pi.registerCommand("cache", {
+        description: "Show cache hit graph, token/cache statistics, or export CSV",
+        getArgumentCompletions(prefix) {
+            const filtered = SUBCOMMANDS.filter((item) => item.value.startsWith(prefix.toLowerCase()));
+            return filtered.length > 0 ? filtered : SUBCOMMANDS;
+        },
+        handler: async (args, ctx) => {
+            const subcommand = normalizeSubcommand(args);
+            if (subcommand !== "graph" && subcommand !== "stats" && subcommand !== "export") {
+                ctx.ui.notify(usageText(), "info");
+                return;
+            }
+            // SAFETY: pi seam — runtime sessionManager provides getEntries/getBranch/getSessionName/getSessionFile
+            const sessionManager = ctx.sessionManager;
+            let metrics = collectCacheSessionMetrics(sessionManager);
+            if (subcommand === "export") {
+                // SAFETY: pi seam — same structural cast as above
+                const filePath = await exportStatsCsv(ctx.cwd, ctx.sessionManager, metrics);
+                ctx.ui.notify(`Exported cache stats CSV to ${filePath}`, "info");
+                return;
+            }
+            if (!ctx.hasUI) {
+                ctx.ui.notify("/cache graph and /cache stats require interactive TUI mode. Use /cache export in non-interactive mode.", "info");
+                return;
+            }
+            if (subcommand === "graph") {
+                let currentView = "per-turn";
+                await ctx.ui.custom((_tui, theme, _keybindings, done) => new ScrollDialog(theme, {
+                    title: "Context Cache Graph",
+                    getTitle: () => `Context Cache Graph — ${graphViewLabel(currentView)}`,
+                    helpText: "1/2/3 view • r refresh • v cycle • ↑/↓ scroll • PgUp/PgDn • q/Esc close",
+                    renderBody: (innerWidth) => renderGraphBody(theme, metrics, innerWidth, currentView, chartGlyphsForMode(options.getConfig().icons.mode)),
+                    onKey: (data) => {
+                        if (data === "r") {
+                            metrics = collectCacheSessionMetrics(sessionManager);
+                            return true;
+                        }
+                        if (data === "1")
+                            currentView = "per-turn";
+                        else if (data === "2")
+                            currentView = "cumulative-percent";
+                        else if (data === "3")
+                            currentView = "cumulative-total";
+                        else if (data === "v") {
+                            const idx = GRAPH_VIEWS.indexOf(currentView);
+                            currentView = GRAPH_VIEWS[(idx + 1) % GRAPH_VIEWS.length];
+                        }
+                        else if (data === "V") {
+                            const idx = GRAPH_VIEWS.indexOf(currentView);
+                            currentView = GRAPH_VIEWS[(idx + GRAPH_VIEWS.length - 1) % GRAPH_VIEWS.length];
+                        }
+                        else {
+                            return false;
+                        }
+                        return true; // recognised key — re-render even when the view is unchanged
+                    },
+                }, () => done(undefined)), { overlay: true, overlayOptions: OVERLAY_OPTIONS });
+                return;
+            }
+            // stats
+            await ctx.ui.custom((_tui, theme, _keybindings, done) => new ScrollDialog(theme, {
+                title: "Context Cache Stats",
+                helpText: "r refresh • ↑/↓ scroll • PgUp/PgDn • q/Esc close",
+                renderBody: (innerWidth) => renderStatsBody(theme, metrics, innerWidth),
+                onKey: (data) => {
+                    if (data === "r") {
+                        metrics = collectCacheSessionMetrics(sessionManager);
+                        return true;
+                    }
+                    return false;
+                },
+            }, () => done(undefined)), { overlay: true, overlayOptions: OVERLAY_OPTIONS });
+        },
+    });
+}

package/dist/cache-cumulative.js

@@ -0,0 +1,24 @@
+import { computeCacheHitPercent } from "./cache-math.js";
+/**
+ * Running cumulative totals across all messages in session append order.
+ * Pure function — no UI/theme dependency.
+ */
+export function computeCumulativeSeries(messages) {
+    const cumInput = [];
+    const cumCacheRead = [];
+    const cumCacheWrite = [];
+    const cumHitPercent = [];
+    let sumInput = 0;
+    let sumCacheRead = 0;
+    let sumCacheWrite = 0;
+    for (const msg of messages) {
+        sumInput += msg.input;
+        sumCacheRead += msg.cacheRead;
+        sumCacheWrite += msg.cacheWrite;
+        cumInput.push(sumInput);
+        cumCacheRead.push(sumCacheRead);
+        cumCacheWrite.push(sumCacheWrite);
+        cumHitPercent.push(computeCacheHitPercent(sumInput, sumCacheRead, sumCacheWrite));
+    }
+    return { cumInput, cumCacheRead, cumCacheWrite, cumHitPercent };
+}

package/dist/cache-export.js

@@ -0,0 +1,132 @@
+import { writeFile } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { summarizeHitPercent } from "./cache-format.js";
+import { promptTokens } from "./cache-math.js";
+export function csvEscape(value) {
+    const text = value == null ? "" : String(value);
+    if (/[",\n]/.test(text)) {
+        return `"${text.replaceAll('"', '""')}"`;
+    }
+    return text;
+}
+export function sanitizeFileName(name) {
+    const sanitized = name
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "");
+    return sanitized.length > 0 ? sanitized : "session";
+}
+function resolveSessionBaseName(sessionManager) {
+    const sessionName = sessionManager.getSessionName()?.trim();
+    if (sessionName)
+        return sanitizeFileName(sessionName);
+    const sessionFile = sessionManager.getSessionFile();
+    if (sessionFile) {
+        return sanitizeFileName(basename(sessionFile, extname(sessionFile)));
+    }
+    return "session";
+}
+const headers = [
+    "row_type",
+    "scope",
+    "assistant_messages",
+    "sequence",
+    "active_branch_sequence",
+    "is_on_active_branch",
+    "entry_id",
+    "timestamp",
+    "time",
+    "provider",
+    "model",
+    "model_key",
+    "prompt_tokens",
+    "received_tokens",
+    "cache_hit_tokens",
+    "cache_write_tokens",
+    "total_tokens",
+    "cache_hit_percent",
+    "delta_sent_tokens",
+    "delta_received_tokens",
+    "delta_cache_hit_tokens",
+    "delta_cache_write_tokens",
+    "delta_hit_rate_percent",
+    "notes",
+];
+function summaryRows(metrics) {
+    const treeHitRate = summarizeHitPercent(metrics.treeTotals);
+    const branchHitRate = summarizeHitPercent(metrics.activeBranchTotals);
+    return [
+        {
+            row_type: "summary",
+            scope: "active_branch",
+            assistant_messages: metrics.activeBranchTotals.assistantMessages,
+            prompt_tokens: promptTokens(metrics.activeBranchTotals.input, metrics.activeBranchTotals.cacheRead, metrics.activeBranchTotals.cacheWrite),
+            received_tokens: metrics.activeBranchTotals.output,
+            cache_hit_tokens: metrics.activeBranchTotals.cacheRead,
+            cache_write_tokens: metrics.activeBranchTotals.cacheWrite,
+            total_tokens: metrics.activeBranchTotals.totalTokens,
+            cache_hit_percent: branchHitRate,
+            notes: "Matches the active-branch cumulative totals shown in /cache stats",
+        },
+        {
+            row_type: "summary",
+            scope: "whole_tree",
+            assistant_messages: metrics.treeTotals.assistantMessages,
+            prompt_tokens: promptTokens(metrics.treeTotals.input, metrics.treeTotals.cacheRead, metrics.treeTotals.cacheWrite),
+            received_tokens: metrics.treeTotals.output,
+            cache_hit_tokens: metrics.treeTotals.cacheRead,
+            cache_write_tokens: metrics.treeTotals.cacheWrite,
+            total_tokens: metrics.treeTotals.totalTokens,
+            cache_hit_percent: treeHitRate,
+            notes: "Matches the whole-tree cumulative totals shown in /cache stats",
+        },
+        {
+            row_type: "summary",
+            scope: "delta_tree_minus_branch",
+            assistant_messages: metrics.treeTotals.assistantMessages - metrics.activeBranchTotals.assistantMessages,
+            delta_sent_tokens: metrics.treeTotals.input - metrics.activeBranchTotals.input,
+            delta_received_tokens: metrics.treeTotals.output - metrics.activeBranchTotals.output,
+            delta_cache_hit_tokens: metrics.treeTotals.cacheRead - metrics.activeBranchTotals.cacheRead,
+            delta_cache_write_tokens: metrics.treeTotals.cacheWrite - metrics.activeBranchTotals.cacheWrite,
+            delta_hit_rate_percent: treeHitRate - branchHitRate,
+            notes: "Matches the delta row shown in /cache stats",
+        },
+    ];
+}
+function messageRows(metrics) {
+    return metrics.allMessages.map((metric) => ({
+        row_type: "message",
+        scope: metric.isOnActiveBranch ? "active_branch" : "other_branch",
+        sequence: metric.sequence,
+        active_branch_sequence: metric.activeBranchSequence ?? "",
+        is_on_active_branch: metric.isOnActiveBranch,
+        entry_id: metric.entryId,
+        timestamp: metric.timestamp,
+        time: metric.timestamp.slice(11, 19),
+        provider: metric.provider,
+        model: metric.model,
+        model_key: `${metric.provider}/${metric.model}`,
+        prompt_tokens: promptTokens(metric.input, metric.cacheRead, metric.cacheWrite),
+        received_tokens: metric.output,
+        cache_hit_tokens: metric.cacheRead,
+        cache_write_tokens: metric.cacheWrite,
+        total_tokens: metric.totalTokens,
+        cache_hit_percent: metric.cacheHitPercent,
+        notes: "Matches a per-message row in /cache stats",
+    }));
+}
+export function buildCsv(metrics) {
+    const rows = [...summaryRows(metrics), ...messageRows(metrics)];
+    const csvRows = [headers.join(",")];
+    for (const row of rows) {
+        csvRows.push(headers.map((header) => csvEscape(row[header])).join(","));
+    }
+    return csvRows.join("\n") + "\n";
+}
+export async function exportStatsCsv(cwd, sessionManager, metrics) {
+    const fileBaseName = resolveSessionBaseName(sessionManager);
+    const filePath = join(cwd, `${fileBaseName}.csv`);
+    await writeFile(filePath, buildCsv(metrics), "utf8");
+    return filePath;
+}

package/dist/cache-format.js

@@ -0,0 +1,30 @@
+import { computeCacheHitPercent, promptTokens } from "./cache-math.js";
+// formatInt keeps thousands separators: the stats table aligns columns on
+// full-width numbers, so fmtTokens (k/M compaction) does not fit here.
+export function formatInt(value) {
+    return new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 }).format(Math.round(value));
+}
+export function formatPercent(value) {
+    return `${value.toFixed(1)}%`;
+}
+export function shortModelName(provider, model) {
+    return `${provider}/${model}`;
+}
+export function summarizeHitPercent(totals) {
+    return computeCacheHitPercent(totals.input, totals.cacheRead, totals.cacheWrite);
+}
+/** Object-shaped delegate — the formula lives in `cache-math.ts:promptTokens`. */
+export function promptTokensOfTotals(totals) {
+    return promptTokens(totals.input, totals.cacheRead, totals.cacheWrite);
+}
+export function formatTotalsLine(label, totals) {
+    return [
+        `${label}:`,
+        `${formatInt(totals.assistantMessages)} turns`,
+        `prompt ${formatInt(promptTokensOfTotals(totals))}`,
+        `received ${formatInt(totals.output)}`,
+        `cache hit ${formatInt(totals.cacheRead)}`,
+        `cache write ${formatInt(totals.cacheWrite)}`,
+        `hit rate ${formatPercent(summarizeHitPercent(totals))}`,
+    ].join(" • ");
+}