@hank-warren/pi-stats 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hank Warren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @hank-warren/pi-stats
+
+A compact, theme-aware `/stats` dashboard for [Pi](https://pi.dev). It totals the usage already recorded in local Pi session JSONLs, including persisted `pi-subagents` child sessions.
+
+## Install
+
+```bash
+pi install npm:@hank-warren/pi-stats
+```
+
+Do not install this standalone package on a host that also installs the aggregate `hank-warren/pi-extensions` Git package; that would load the extension twice.
+
+## Use
+
+Run `/stats` in interactive mode. The dashboard temporarily replaces the editor and closes with `Escape`.
+
+- `Tab` or `←`/`→`: switch Overview and Models
+- `↑`/`↓`: scroll the model list
+- `r`: cycle All time, Last 7 days, and Last 30 days
+- `u`: force a full rescan and rebuild the session index
+- `Escape`: close
+
+The Overview shows current-session, selected-range, and all-time input, output, cache-read, cache-write, reasoning, cost, and cache-hit statistics, plus an activity heatmap and clearly labelled all-time session/streak highlights. Reasoning is shown as a subset of output and is never added to the total twice. The Models tab attributes assistant usage to the provider response model and keeps otherwise unattributed nested usage in `Tools/summaries`, so its totals reconcile.
+
+## What is counted
+
+Pi writes usage to assistant messages, usage-bearing tool results, compactions, and branch summaries. `pi-stats` recursively reads valid Pi session files and counts every recorded model call, including compacted and abandoned branches. Copied fork history is fingerprinted and counted once.
+
+Persisted subagent files in the conventional `run-*/session.jsonl` layout are included. `pi-processes` does not create model sessions; model usage around its tool calls already belongs to the parent Pi session and therefore needs no separate integration.
+
+The standard Pi session root, the current external session directory, `PI_CODING_AGENT_SESSION_DIR`, and a configured `subagents.defaultSessionDir` are discovered automatically. Add unusual one-off roots with the platform-delimited `PI_STATS_SESSION_DIRS` environment variable.
+
+## Cache and privacy
+
+Sessions remain authoritative. For fast repeat opens, the extension stores one disposable index:
+
+```text
+~/.pi/agent/pi-stats/cache.json
+```
+
+The location follows `PI_CODING_AGENT_DIR`. The cache contains file stat identity, session IDs/timestamps/working directories, model names, usage counters, and de-duplication fingerprints. It never stores prompts, responses, tool output, or other conversation content. It is written atomically with mode `0600` and can be deleted at any time; the next `/stats` invocation rebuilds it.
+
+No network or billing API is used. Displayed costs are the estimates already recorded by Pi.

package/cache.ts

@@ -0,0 +1,271 @@
+import { randomUUID } from "node:crypto";
+import { readFile, readdir, realpath, rename, stat, writeFile, mkdir, chmod, unlink } from "node:fs/promises";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { makeIndex, parseSessionText } from "./stats.ts";
+import type { CachedFileRecord, ScanDiagnostics, SessionRecord, StatsCacheFile, StatsIndex, UsageRecord } from "./types.ts";
+
+const CACHE_VERSION = 1 as const;
+const SKIP_DIRECTORIES = new Set(["subagent-artifacts"]);
+
+export interface ScanOptions {
+	agentDir: string;
+	activeSessionDir?: string;
+	env?: NodeJS.ProcessEnv;
+	sessionRoots?: string[];
+	force?: boolean;
+	signal?: AbortSignal;
+	onProgress?: (completed: number, total: number) => void;
+}
+
+function expandHome(value: string): string {
+	if (value === "~") return homedir();
+	if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+	return value;
+}
+
+async function settingsSubagentRoot(agentDir: string): Promise<string | undefined> {
+	try {
+		const settings = JSON.parse(await readFile(join(agentDir, "settings.json"), "utf8")) as unknown;
+		if (!settings || typeof settings !== "object") return undefined;
+		const subagents = (settings as { subagents?: unknown }).subagents;
+		if (!subagents || typeof subagents !== "object") return undefined;
+		const configured = (subagents as { defaultSessionDir?: unknown }).defaultSessionDir;
+		return typeof configured === "string" && configured.length > 0 ? expandHome(configured) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function resolveSessionRoots(options: ScanOptions): Promise<string[]> {
+	if (options.sessionRoots) return uniqueExistingDirectories(options.sessionRoots);
+	const env = options.env ?? process.env;
+	const roots = [join(options.agentDir, "sessions")];
+	if (env.PI_CODING_AGENT_SESSION_DIR) roots.push(expandHome(env.PI_CODING_AGENT_SESSION_DIR));
+	if (options.activeSessionDir) roots.push(options.activeSessionDir);
+	const configuredSubagents = await settingsSubagentRoot(options.agentDir);
+	if (configuredSubagents) roots.push(configuredSubagents);
+	if (env.PI_STATS_SESSION_DIRS) {
+		roots.push(...env.PI_STATS_SESSION_DIRS.split(delimiter).filter(Boolean).map(expandHome));
+	}
+	return uniqueExistingDirectories(roots);
+}
+
+async function uniqueExistingDirectories(paths: string[]): Promise<string[]> {
+	const result = new Set<string>();
+	for (const candidate of paths) {
+		try {
+			const resolved = await realpath(resolve(candidate));
+			if ((await stat(resolved)).isDirectory()) result.add(resolved);
+		} catch {
+			// Missing optional roots are expected.
+		}
+	}
+	return [...result];
+}
+
+async function discoverJsonlFiles(roots: readonly string[], signal?: AbortSignal): Promise<string[]> {
+	const found = new Set<string>();
+	const walk = async (directory: string): Promise<void> => {
+		signal?.throwIfAborted();
+		let entries;
+		try {
+			entries = await readdir(directory, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			signal?.throwIfAborted();
+			if (entry.isSymbolicLink()) continue;
+			const path = join(directory, entry.name);
+			if (entry.isDirectory()) {
+				if (!SKIP_DIRECTORIES.has(entry.name)) await walk(path);
+			} else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+				try {
+					found.add(await realpath(path));
+				} catch {
+					// File disappeared between directory listing and resolution.
+				}
+			}
+		}
+	};
+	for (const root of roots) await walk(root);
+	return [...found].sort();
+}
+
+function emptyCache(): StatsCacheFile {
+	return { version: CACHE_VERSION, files: {} };
+}
+
+function validNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function validUsageRecord(value: unknown): value is UsageRecord {
+	if (!value || typeof value !== "object") return false;
+	const record = value as Partial<UsageRecord>;
+	const usage = record.usage as Partial<UsageRecord["usage"]> | undefined;
+	return (
+		typeof record.fingerprint === "string" &&
+		validNumber(record.timestamp) &&
+		typeof record.model === "string" &&
+		(record.kind === "assistant" || record.kind === "tool" || record.kind === "summary") &&
+		Boolean(usage) &&
+		validNumber(usage?.input) &&
+		validNumber(usage?.output) &&
+		validNumber(usage?.cacheRead) &&
+		validNumber(usage?.cacheWrite) &&
+		validNumber(usage?.reasoning) &&
+		validNumber(usage?.cost) &&
+		validNumber(usage?.calls) &&
+		(record.childSessionFiles === undefined || (Array.isArray(record.childSessionFiles) && record.childSessionFiles.every((file) => typeof file === "string")))
+	);
+}
+
+function validSessionRecord(value: unknown): value is SessionRecord {
+	if (!value || typeof value !== "object") return false;
+	const session = value as Partial<SessionRecord>;
+	return (
+		typeof session.path === "string" &&
+		typeof session.sessionId === "string" &&
+		typeof session.cwd === "string" &&
+		validNumber(session.createdAt) &&
+		validNumber(session.lastActivityAt) &&
+		(session.source === "main" || session.source === "subagent") &&
+		Array.isArray(session.usage) &&
+		session.usage.every(validUsageRecord)
+	);
+}
+
+function validCache(value: unknown): value is StatsCacheFile {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<StatsCacheFile>;
+	if (candidate.version !== CACHE_VERSION || !candidate.files || typeof candidate.files !== "object") return false;
+	return Object.entries(candidate.files).every(([path, value]) => {
+		if (!path || !value || typeof value !== "object") return false;
+		const record = value as Partial<CachedFileRecord>;
+		return (
+			validNumber(record.size) &&
+			validNumber(record.mtimeMs) &&
+			validNumber(record.malformedLines) &&
+			(record.ignored === undefined || record.ignored === true) &&
+			(record.session === undefined || validSessionRecord(record.session))
+		);
+	});
+}
+
+async function loadCache(path: string): Promise<{ cache: StatsCacheFile; valid: boolean }> {
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf8")) as unknown;
+		if (!validCache(parsed)) return { cache: emptyCache(), valid: false };
+		return { cache: parsed, valid: true };
+	} catch {
+		return { cache: emptyCache(), valid: false };
+	}
+}
+
+async function cleanupStaleTemporaryFiles(path: string): Promise<void> {
+	const directory = dirname(path);
+	const prefix = `${basename(path)}.`;
+	const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+	try {
+		const entries = await readdir(directory, { withFileTypes: true });
+		await Promise.all(entries.map(async (entry) => {
+			if (!entry.isFile() || !entry.name.startsWith(prefix) || !entry.name.endsWith(".tmp")) return;
+			const candidate = join(directory, entry.name);
+			try {
+				if ((await stat(candidate)).mtimeMs < cutoff) await unlink(candidate);
+			} catch {
+				// Another process may already have removed it.
+			}
+		}));
+	} catch {
+		// The cache directory may not exist yet.
+	}
+}
+
+async function atomicWriteCache(path: string, cache: StatsCacheFile): Promise<void> {
+	await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+	const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temporary, JSON.stringify(cache), { encoding: "utf8", mode: 0o600 });
+		await rename(temporary, path);
+		await chmod(path, 0o600);
+	} catch (error) {
+		await unlink(temporary).catch(() => undefined);
+		throw error;
+	}
+}
+
+function sameFile(record: CachedFileRecord | undefined, size: number, mtimeMs: number): boolean {
+	return Boolean(record && record.size === size && record.mtimeMs === mtimeMs);
+}
+
+export function statsCachePath(agentDir: string): string {
+	return join(agentDir, "pi-stats", "cache.json");
+}
+
+export async function scanStats(options: ScanOptions): Promise<StatsIndex> {
+	const roots = await resolveSessionRoots(options);
+	const files = await discoverJsonlFiles(roots, options.signal);
+	const cachePath = statsCachePath(options.agentDir);
+	await cleanupStaleTemporaryFiles(cachePath);
+	const loaded = options.force ? { cache: emptyCache(), valid: false } : await loadCache(cachePath);
+	const next: StatsCacheFile = emptyCache();
+	const diagnostics: ScanDiagnostics = {
+		discoveredFiles: files.length,
+		parsedFiles: 0,
+		reusedFiles: 0,
+		ignoredFiles: 0,
+		unreadableFiles: 0,
+		malformedLines: 0,
+	};
+	let changed = options.force === true || !loaded.valid;
+
+	for (let index = 0; index < files.length; index++) {
+		options.signal?.throwIfAborted();
+		const file = files[index]!;
+		try {
+			const metadata = await stat(file);
+			const previous = loaded.cache.files[file];
+			if (!options.force && sameFile(previous, metadata.size, metadata.mtimeMs)) {
+				next.files[file] = previous!;
+				diagnostics.reusedFiles++;
+			} else {
+				const parsed = parseSessionText(file, await readFile(file, "utf8"));
+				next.files[file] = {
+					size: metadata.size,
+					mtimeMs: metadata.mtimeMs,
+					...(parsed.ignored ? { ignored: true as const } : {}),
+					...(parsed.session ? { session: parsed.session } : {}),
+					malformedLines: parsed.malformedLines,
+				};
+				diagnostics.parsedFiles++;
+				changed = true;
+			}
+			const current = next.files[file]!;
+			if (current.ignored) diagnostics.ignoredFiles++;
+			diagnostics.malformedLines += current.malformedLines;
+		} catch {
+			diagnostics.unreadableFiles++;
+			changed = true;
+		}
+		options.onProgress?.(index + 1, files.length);
+	}
+
+	if (Object.keys(loaded.cache.files).some((file) => !(file in next.files))) changed = true;
+	if (changed) {
+		await atomicWriteCache(cachePath, next).catch(() => {
+			// Stats remain usable if the optional cache cannot be written.
+		});
+	}
+	const sessions = Object.values(next.files).flatMap((record) => (record.session ? [record.session] : []));
+	return makeIndex(sessions, diagnostics);
+}
+
+export function isExternalSessionDirectory(activeSessionDir: string, agentDir: string): boolean {
+	const standard = resolve(agentDir, "sessions");
+	const active = resolve(activeSessionDir);
+	return active !== standard && !active.startsWith(`${standard}/`);
+}
+

package/index.ts

@@ -0,0 +1,108 @@
+import { getAgentDir, type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { isExternalSessionDirectory, scanStats } from "./cache.ts";
+import { buildSnapshot, makeIndex, usageFromEntries } from "./stats.ts";
+import type { SessionRecord, StatsIndex, StatsRange } from "./types.ts";
+import { StatsWidget } from "./widget.ts";
+
+function includeInMemorySession(index: StatsIndex, ctx: ExtensionCommandContext): StatsIndex {
+	const sessionId = ctx.sessionManager.getSessionId();
+	if (index.sessions.some((session) => session.sessionId === sessionId)) return index;
+	const entries = ctx.sessionManager.getEntries();
+	const header = ctx.sessionManager.getHeader();
+	const createdAt = header?.timestamp ? Date.parse(header.timestamp) : Date.now();
+	const usage = usageFromEntries(
+		sessionId,
+		entries,
+		Number.isFinite(createdAt) ? createdAt : Date.now(),
+		ctx.sessionManager.getSessionFile() ?? "current-session.jsonl",
+	);
+	const session: SessionRecord = {
+		path: ctx.sessionManager.getSessionFile() ?? `in-memory:${sessionId}`,
+		sessionId,
+		cwd: ctx.cwd,
+		createdAt: Number.isFinite(createdAt) ? createdAt : Date.now(),
+		lastActivityAt: usage.reduce((latest, record) => Math.max(latest, record.timestamp), Number.isFinite(createdAt) ? createdAt : 0),
+		source: "main",
+		usage,
+	};
+	return makeIndex([...index.sessions, session], index.diagnostics);
+}
+
+export default function statsExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("stats", {
+		description: "Open all-time Pi token statistics",
+		handler: async (_args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/stats requires interactive TUI mode", "warning");
+				return;
+			}
+
+			const agentDir = getAgentDir();
+			const sessionDir = ctx.sessionManager.getSessionDir();
+			let controller: AbortController | undefined;
+			let currentIndex: StatsIndex | undefined;
+			let closed = false;
+
+			await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+				const snapshot = (range: StatsRange) =>
+					currentIndex
+						? buildSnapshot(
+								currentIndex,
+								ctx.sessionManager.getEntries(),
+								ctx.sessionManager.getSessionId(),
+								range,
+								Date.now(),
+								ctx.sessionManager.getSessionFile() ?? "current-session.jsonl",
+							)
+						: undefined;
+
+				const widget = new StatsWidget({
+					theme,
+					requestRender: () => tui.requestRender(),
+					onClose: () => {
+						closed = true;
+						controller?.abort();
+						done(undefined);
+					},
+					onRefresh: () => void refresh(true),
+					onDispose: () => {
+						closed = true;
+						controller?.abort();
+					},
+					getSnapshot: snapshot,
+				});
+
+				const refresh = async (force: boolean): Promise<void> => {
+					controller?.abort();
+					const refreshController = new AbortController();
+					controller = refreshController;
+					widget.setLoading();
+					let lastReported = 0;
+					try {
+						const scanned = await scanStats({
+							agentDir,
+							...(isExternalSessionDirectory(sessionDir, agentDir) ? { activeSessionDir: sessionDir } : {}),
+							force,
+							signal: refreshController.signal,
+							onProgress: (completed, total) => {
+								if (completed === total || completed - lastReported >= 8) {
+									lastReported = completed;
+									widget.setProgress(completed, total);
+								}
+							},
+						});
+						if (closed || refreshController.signal.aborted) return;
+						currentIndex = includeInMemorySession(scanned, ctx);
+						widget.setReady(snapshot(widget.getRange())!);
+					} catch (error) {
+						if (closed || refreshController.signal.aborted) return;
+						widget.setError(error instanceof Error ? error.message : String(error));
+					}
+				};
+
+				queueMicrotask(() => void refresh(false));
+				return widget;
+			});
+		},
+	});
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hank-warren/pi-stats",
+  "version": "0.1.0",
+  "description": "A compact /stats dashboard for all-time Pi token usage, including persisted subagents.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "stats",
+    "tokens",
+    "usage",
+    "dashboard"
+  ],
+  "author": "Hank Warren",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hank-warren/pi-extensions.git",
+    "directory": "packages/pi-stats"
+  },
+  "bugs": {
+    "url": "https://github.com/hank-warren/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-stats#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "cache.ts",
+    "stats.ts",
+    "types.ts",
+    "widget.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/stats.ts

@@ -0,0 +1,405 @@
+import { createHash } from "node:crypto";
+import { dirname, resolve } from "node:path";
+import {
+	addUsage,
+	emptyUsage,
+	totalTokens,
+	type DayStats,
+	type ModelStats,
+	type SessionRecord,
+	type StatsIndex,
+	type StatsRange,
+	type StatsSnapshot,
+	type UsageRecord,
+	type UsageTotals,
+} from "./types.ts";
+
+interface ParseResult {
+	ignored: boolean;
+	malformedLines: number;
+	session?: SessionRecord;
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function finite(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+function firstNumber(source: Record<string, unknown>, names: string[]): number {
+	for (const name of names) {
+		if (typeof source[name] === "number") return finite(source[name]);
+	}
+	return 0;
+}
+
+export function normalizeUsage(value: unknown): UsageTotals | undefined {
+	const usage = object(value);
+	if (!usage) return undefined;
+	const cost = object(usage.cost);
+	return {
+		input: firstNumber(usage, ["input", "inputTokens"]),
+		output: firstNumber(usage, ["output", "outputTokens"]),
+		cacheRead: firstNumber(usage, ["cacheRead", "cacheReadTokens"]),
+		cacheWrite: firstNumber(usage, ["cacheWrite", "cacheWriteTokens"]),
+		reasoning: firstNumber(usage, ["reasoning", "reasoningTokens"]),
+		cost: cost ? firstNumber(cost, ["total"]) : firstNumber(usage, ["costUsd", "cost"]),
+		calls: 1,
+	};
+}
+
+function timestamp(value: unknown, fallback: number): number {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string") {
+		const parsed = Date.parse(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return fallback;
+}
+
+function modelName(provider: unknown, model: unknown): string {
+	const providerText = typeof provider === "string" ? provider : "";
+	const modelText = typeof model === "string" && model.length > 0 ? model : "unknown";
+	if (!providerText || modelText.includes("/")) return modelText;
+	return `${providerText}/${modelText}`;
+}
+
+function detailsModel(details: unknown): string | undefined {
+	const candidate = object(details)?.model;
+	return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
+}
+
+function nestedSubagentUsage(details: unknown): UsageTotals | undefined {
+	const record = object(details);
+	if (!record) return undefined;
+	const aggregate = normalizeUsage(record.totalChildUsage);
+	if (aggregate) return aggregate;
+	if (!Array.isArray(record.results)) return undefined;
+	const total = emptyUsage();
+	let found = false;
+	for (const result of record.results) {
+		const normalized = normalizeUsage(object(result)?.usage);
+		if (!normalized) continue;
+		addUsage(total, normalized);
+		found = true;
+	}
+	return found ? total : undefined;
+}
+
+function childSessionFiles(details: unknown, sessionFile: string): string[] {
+	const found = new Set<string>();
+	const visit = (value: unknown, depth: number): void => {
+		if (depth > 6) return;
+		if (Array.isArray(value)) {
+			for (const item of value) visit(item, depth + 1);
+			return;
+		}
+		const record = object(value);
+		if (!record) return;
+		for (const [key, item] of Object.entries(record)) {
+			if (key === "sessionFile" && typeof item === "string" && item.length > 0) {
+				found.add(resolve(dirname(sessionFile), item));
+			} else if (typeof item === "object" && item !== null) {
+				visit(item, depth + 1);
+			}
+		}
+	};
+	visit(details, 0);
+	return [...found];
+}
+
+function fingerprint(parts: unknown[]): string {
+	return createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 32);
+}
+
+function normalizeEntry(
+	entryValue: unknown,
+	sessionId: string,
+	sessionFile: string,
+	lineIndex: number,
+	fallbackTimestamp: number,
+): UsageRecord | undefined {
+	const entry = object(entryValue);
+	if (!entry) return undefined;
+	const entryTimestamp = timestamp(entry.timestamp, fallbackTimestamp);
+	const id = typeof entry.id === "string" ? entry.id : `${sessionId}:${lineIndex}`;
+
+	if (entry.type === "message") {
+		const message = object(entry.message);
+		if (!message) return undefined;
+		const role = message.role;
+		if (role === "assistant") {
+			const usage = normalizeUsage(message.usage);
+			if (!usage) return undefined;
+			const model = modelName(message.provider, message.responseModel ?? message.model);
+			return {
+				fingerprint: fingerprint([id, entry.timestamp, "assistant", model, usage]),
+				timestamp: timestamp(message.timestamp, entryTimestamp),
+				model,
+				usage,
+				kind: "assistant",
+			};
+		}
+		if (role === "toolResult") {
+			const toolName = typeof message.toolName === "string" ? message.toolName : "tool";
+			const usage = normalizeUsage(message.usage) ?? (toolName === "subagent" ? nestedSubagentUsage(message.details) : undefined);
+			if (!usage) return undefined;
+			const model = detailsModel(message.details) ?? "Tools/summaries";
+			const children = toolName === "subagent" ? childSessionFiles(message.details, sessionFile) : [];
+			return {
+				fingerprint: fingerprint([id, entry.timestamp, "tool", toolName, model, usage]),
+				timestamp: timestamp(message.timestamp, entryTimestamp),
+				model,
+				usage,
+				kind: "tool",
+				toolName,
+				...(children.length > 0 ? { childSessionFiles: children } : {}),
+			};
+		}
+		return undefined;
+	}
+
+	if (entry.type === "compaction" || entry.type === "branch_summary") {
+		const usage = normalizeUsage(entry.usage);
+		if (!usage) return undefined;
+		return {
+			fingerprint: fingerprint([id, entry.timestamp, entry.type, "Tools/summaries", usage]),
+			timestamp: entryTimestamp,
+			model: "Tools/summaries",
+			usage,
+			kind: "summary",
+		};
+	}
+	return undefined;
+}
+
+function sessionSource(filePath: string): "main" | "subagent" {
+	return /(?:^|\/)run-\d+\/session\.jsonl$/.test(filePath) ? "subagent" : "main";
+}
+
+export function parseSessionText(filePath: string, text: string): ParseResult {
+	const lines = text.split("\n");
+	let header: Record<string, unknown> | undefined;
+	try {
+		header = object(JSON.parse(lines[0]?.trim() ?? ""));
+	} catch {
+		return { ignored: true, malformedLines: 0 };
+	}
+	if (!header || header.type !== "session" || typeof header.id !== "string") {
+		return { ignored: true, malformedLines: 0 };
+	}
+
+	const headerTimestamp = timestamp(header.timestamp, 0);
+	const usage: UsageRecord[] = [];
+	let malformedLines = 0;
+	let earliestActivityAt = Number.POSITIVE_INFINITY;
+	let lastActivityAt = headerTimestamp;
+	for (let index = 1; index < lines.length; index++) {
+		const line = lines[index]?.trim();
+		if (!line) continue;
+		try {
+			const entry = JSON.parse(line) as unknown;
+			const entryRecord = object(entry);
+			const entryTimestamp = timestamp(entryRecord?.timestamp, 0);
+			if (entryTimestamp > 0) {
+				earliestActivityAt = Math.min(earliestActivityAt, entryTimestamp);
+				lastActivityAt = Math.max(lastActivityAt, entryTimestamp);
+			}
+			const normalized = normalizeEntry(entry, header.id, filePath, index, headerTimestamp || entryTimestamp);
+			if (normalized) {
+				usage.push(normalized);
+				if (normalized.timestamp > 0) {
+					earliestActivityAt = Math.min(earliestActivityAt, normalized.timestamp);
+					lastActivityAt = Math.max(lastActivityAt, normalized.timestamp);
+				}
+			}
+		} catch {
+			malformedLines++;
+		}
+	}
+
+	const createdAt = headerTimestamp || (Number.isFinite(earliestActivityAt) ? earliestActivityAt : 0);
+	return {
+		ignored: false,
+		malformedLines,
+		session: {
+			path: resolve(filePath),
+			sessionId: header.id,
+			cwd: typeof header.cwd === "string" ? header.cwd : "",
+			createdAt,
+			lastActivityAt: Math.max(lastActivityAt, createdAt),
+			source: sessionSource(filePath),
+			usage,
+		},
+	};
+}
+
+export function usageFromEntries(
+	sessionId: string,
+	entries: readonly unknown[],
+	fallbackTimestamp = Date.now(),
+	sessionFile = "current-session.jsonl",
+): UsageRecord[] {
+	return entries.flatMap((entry, index) => {
+		const normalized = normalizeEntry(entry, sessionId, sessionFile, index, fallbackTimestamp);
+		return normalized ? [normalized] : [];
+	});
+}
+
+function hasPersistedSubagentChild(record: UsageRecord, sessionPaths: ReadonlySet<string>): boolean {
+	return record.toolName === "subagent" && Boolean(record.childSessionFiles?.some((file) => sessionPaths.has(resolve(file))));
+}
+
+export function deduplicateUsage(sessions: readonly SessionRecord[]): UsageRecord[] {
+	const sessionPaths = new Set(sessions.map((session) => resolve(session.path)));
+	const seen = new Set<string>();
+	const result: UsageRecord[] = [];
+	for (const session of sessions) {
+		for (const record of session.usage) {
+			if (hasPersistedSubagentChild(record, sessionPaths)) continue;
+			if (seen.has(record.fingerprint)) continue;
+			seen.add(record.fingerprint);
+			result.push(record);
+		}
+	}
+	return result;
+}
+
+function localDay(time: number): string {
+	const date = new Date(time);
+	const year = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${year}-${month}-${day}`;
+}
+
+function dayStart(now: number, daysBack: number): number {
+	const date = new Date(now);
+	date.setHours(0, 0, 0, 0);
+	date.setDate(date.getDate() - daysBack);
+	return date.getTime();
+}
+
+function rangeStart(range: StatsRange, now: number): number {
+	if (range === "7d") return dayStart(now, 6);
+	if (range === "30d") return dayStart(now, 29);
+	return Number.NEGATIVE_INFINITY;
+}
+
+function total(records: readonly UsageRecord[]): UsageTotals {
+	const result = emptyUsage();
+	for (const record of records) addUsage(result, record.usage);
+	return result;
+}
+
+function aggregateModels(records: readonly UsageRecord[]): ModelStats[] {
+	const byModel = new Map<string, UsageTotals>();
+	for (const record of records) {
+		const aggregate = byModel.get(record.model) ?? emptyUsage();
+		addUsage(aggregate, record.usage);
+		byModel.set(record.model, aggregate);
+	}
+	const grandTotal = [...byModel.values()].reduce((sum, usage) => sum + totalTokens(usage), 0);
+	return [...byModel.entries()]
+		.map(([model, usage]) => ({ ...usage, model, total: totalTokens(usage), share: grandTotal > 0 ? totalTokens(usage) / grandTotal : 0 }))
+		.sort((a, b) => b.total - a.total || a.model.localeCompare(b.model));
+}
+
+function streaks(days: readonly string[], now: number): { current: number; longest: number } {
+	const unique = [...new Set(days)].sort();
+	let longest = 0;
+	let run = 0;
+	let previous: Date | undefined;
+	for (const day of unique) {
+		const current = new Date(`${day}T12:00:00`);
+		if (previous) {
+			const expected = new Date(previous);
+			expected.setDate(expected.getDate() + 1);
+			run = localDay(expected.getTime()) === day ? run + 1 : 1;
+		} else {
+			run = 1;
+		}
+		longest = Math.max(longest, run);
+		previous = current;
+	}
+
+	let current = 0;
+	const set = new Set(unique);
+	const cursor = new Date(now);
+	cursor.setHours(12, 0, 0, 0);
+	while (set.has(localDay(cursor.getTime()))) {
+		current++;
+		cursor.setDate(cursor.getDate() - 1);
+	}
+	return { current, longest };
+}
+
+function uniqueSessions(sessions: readonly SessionRecord[]): SessionRecord[] {
+	const byId = new Map<string, SessionRecord>();
+	for (const session of sessions) {
+		const previous = byId.get(session.sessionId);
+		if (!previous || session.lastActivityAt > previous.lastActivityAt) byId.set(session.sessionId, session);
+	}
+	return [...byId.values()];
+}
+
+export function buildSnapshot(
+	index: StatsIndex,
+	currentEntries: readonly unknown[],
+	currentSessionId: string,
+	range: StatsRange,
+	now = Date.now(),
+	currentSessionFile = "current-session.jsonl",
+): StatsSnapshot {
+	const cutoff = rangeStart(range, now);
+	const periodRecords = range === "all"
+		? index.usage
+		: index.usage.filter((record) => record.timestamp >= cutoff && record.timestamp <= now);
+	const dayTotals = new Map<string, number>();
+	for (const record of index.usage) {
+		if (record.timestamp <= 0) continue;
+		const day = localDay(record.timestamp);
+		dayTotals.set(day, (dayTotals.get(day) ?? 0) + totalTokens(record.usage));
+	}
+	const days = [...dayTotals.entries()]
+		.map(([day, dayTotal]): DayStats => ({ day, total: dayTotal }))
+		.sort((a, b) => a.day.localeCompare(b.day));
+	const models = aggregateModels(periodRecords);
+	const allModels = aggregateModels(index.usage);
+	const sessions = uniqueSessions(index.sessions);
+	const sessionPaths = new Set(index.sessions.map((session) => resolve(session.path)));
+	const currentRecords = usageFromEntries(currentSessionId, currentEntries, now, currentSessionFile)
+		.filter((record) => !hasPersistedSubagentChild(record, sessionPaths));
+	const streak = streaks(days.map((day) => day.day), now);
+	const mostActiveDay = days.reduce<DayStats | undefined>((best, day) => (!best || day.total > best.total ? day : best), undefined);
+
+	return {
+		range,
+		allTime: total(index.usage),
+		period: total(periodRecords),
+		currentSession: total(currentRecords),
+		models,
+		days,
+		sessionCount: sessions.length,
+		mainSessionCount: sessions.filter((session) => session.source === "main").length,
+		subagentSessionCount: sessions.filter((session) => session.source === "subagent").length,
+		activeDays: days.length,
+		currentStreak: streak.current,
+		longestStreak: streak.longest,
+		...(mostActiveDay ? { mostActiveDay } : {}),
+		...(allModels[0] ? { favoriteModel: allModels[0].model } : {}),
+		longestSessionMs: sessions.reduce(
+			(longest, session) => Math.max(longest, session.createdAt > 0 ? Math.max(0, session.lastActivityAt - session.createdAt) : 0),
+			0,
+		),
+		diagnostics: index.diagnostics,
+	};
+}
+
+export function makeIndex(sessions: SessionRecord[], diagnostics: StatsIndex["diagnostics"]): StatsIndex {
+	return { sessions, usage: deduplicateUsage(sessions), diagnostics };
+}

package/types.ts

@@ -0,0 +1,109 @@
+export interface UsageTotals {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	reasoning: number;
+	cost: number;
+	calls: number;
+}
+
+export type SessionSource = "main" | "subagent";
+
+export interface UsageRecord {
+	fingerprint: string;
+	timestamp: number;
+	model: string;
+	usage: UsageTotals;
+	kind: "assistant" | "tool" | "summary";
+	toolName?: string;
+	childSessionFiles?: string[];
+}
+
+export interface SessionRecord {
+	path: string;
+	sessionId: string;
+	cwd: string;
+	createdAt: number;
+	lastActivityAt: number;
+	source: SessionSource;
+	usage: UsageRecord[];
+}
+
+export interface CachedFileRecord {
+	size: number;
+	mtimeMs: number;
+	ignored?: true;
+	session?: SessionRecord;
+	malformedLines: number;
+}
+
+export interface StatsCacheFile {
+	version: 1;
+	files: Record<string, CachedFileRecord>;
+}
+
+export interface ScanDiagnostics {
+	discoveredFiles: number;
+	parsedFiles: number;
+	reusedFiles: number;
+	ignoredFiles: number;
+	unreadableFiles: number;
+	malformedLines: number;
+}
+
+export interface StatsIndex {
+	sessions: SessionRecord[];
+	usage: UsageRecord[];
+	diagnostics: ScanDiagnostics;
+}
+
+export type StatsRange = "all" | "7d" | "30d";
+
+export interface ModelStats extends UsageTotals {
+	model: string;
+	total: number;
+	share: number;
+}
+
+export interface DayStats {
+	day: string;
+	total: number;
+}
+
+export interface StatsSnapshot {
+	range: StatsRange;
+	allTime: UsageTotals;
+	period: UsageTotals;
+	currentSession: UsageTotals;
+	models: ModelStats[];
+	days: DayStats[];
+	sessionCount: number;
+	mainSessionCount: number;
+	subagentSessionCount: number;
+	activeDays: number;
+	currentStreak: number;
+	longestStreak: number;
+	mostActiveDay?: DayStats;
+	favoriteModel?: string;
+	longestSessionMs: number;
+	diagnostics: ScanDiagnostics;
+}
+
+export function emptyUsage(): UsageTotals {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, cost: 0, calls: 0 };
+}
+
+export function addUsage(target: UsageTotals, usage: UsageTotals): void {
+	target.input += usage.input;
+	target.output += usage.output;
+	target.cacheRead += usage.cacheRead;
+	target.cacheWrite += usage.cacheWrite;
+	target.reasoning += usage.reasoning;
+	target.cost += usage.cost;
+	target.calls += usage.calls;
+}
+
+export function totalTokens(usage: UsageTotals): number {
+	return usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+}

package/widget.ts

@@ -0,0 +1,301 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { totalTokens, type StatsRange, type StatsSnapshot, type UsageTotals } from "./types.ts";
+
+export type WidgetState =
+	| { kind: "loading"; completed: number; total: number }
+	| { kind: "error"; message: string }
+	| { kind: "ready"; snapshot: StatsSnapshot };
+
+export interface StatsWidgetOptions {
+	theme: Theme;
+	requestRender: () => void;
+	onClose: () => void;
+	onRefresh: () => void;
+	getSnapshot: (range: StatsRange) => StatsSnapshot | undefined;
+	onDispose?: () => void;
+}
+
+const MODEL_PAGE_SIZE = 8;
+const RANGES: StatsRange[] = ["all", "7d", "30d"];
+const RANGE_LABELS: Record<StatsRange, string> = { all: "All time", "7d": "Last 7 days", "30d": "Last 30 days" };
+
+export function formatTokens(value: number): string {
+	const safe = Math.max(0, Math.round(value));
+	if (safe >= 1_000_000_000) return `${(safe / 1_000_000_000).toFixed(1)}b`;
+	if (safe >= 1_000_000) return `${(safe / 1_000_000).toFixed(1)}m`;
+	if (safe >= 1_000) return `${(safe / 1_000).toFixed(safe < 10_000 ? 1 : 0)}k`;
+	return String(safe);
+}
+
+function formatCost(value: number): string {
+	return `$${value.toFixed(value >= 100 ? 0 : value >= 10 ? 1 : 2)}`;
+}
+
+function formatDuration(milliseconds: number): string {
+	if (milliseconds <= 0) return "0m";
+	const minutes = Math.floor(milliseconds / 60_000);
+	const days = Math.floor(minutes / 1_440);
+	const hours = Math.floor((minutes % 1_440) / 60);
+	const mins = minutes % 60;
+	if (days > 0) return `${days}d ${hours}h`;
+	if (hours > 0) return `${hours}h ${mins}m`;
+	return `${mins}m`;
+}
+
+function cacheHit(usage: UsageTotals): string {
+	const prompt = usage.input + usage.cacheRead + usage.cacheWrite;
+	return prompt > 0 ? `${((usage.cacheRead / prompt) * 100).toFixed(1)}%` : "—";
+}
+
+function localDay(time: number): string {
+	const date = new Date(time);
+	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+
+function plainPad(value: string, width: number): string {
+	const clipped = truncateToWidth(value, Math.max(0, width), "");
+	return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+}
+
+export class StatsWidget implements Component {
+	private state: WidgetState = { kind: "loading", completed: 0, total: 0 };
+	private tab: "overview" | "models" = "overview";
+	private range: StatsRange = "all";
+	private modelOffset = 0;
+	private readonly options: StatsWidgetOptions;
+
+	constructor(options: StatsWidgetOptions) {
+		this.options = options;
+	}
+
+	getRange(): StatsRange {
+		return this.range;
+	}
+
+	setLoading(completed = 0, total = 0): void {
+		this.state = { kind: "loading", completed, total };
+		this.options.requestRender();
+	}
+
+	setProgress(completed: number, total: number): void {
+		if (this.state.kind !== "loading") return;
+		this.state = { kind: "loading", completed, total };
+		this.options.requestRender();
+	}
+
+	setReady(snapshot: StatsSnapshot): void {
+		this.state = { kind: "ready", snapshot };
+		this.modelOffset = Math.min(this.modelOffset, Math.max(0, snapshot.models.length - MODEL_PAGE_SIZE));
+		this.options.requestRender();
+	}
+
+	setError(message: string): void {
+		this.state = { kind: "error", message };
+		this.options.requestRender();
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.escape)) {
+			this.options.onClose();
+			return;
+		}
+		if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+			this.tab = this.tab === "overview" ? "models" : "overview";
+			this.options.requestRender();
+			return;
+		}
+		if (matchesKey(data, Key.left)) {
+			this.tab = this.tab === "models" ? "overview" : "models";
+			this.options.requestRender();
+			return;
+		}
+		if (data === "r" || data === "R") {
+			const next = RANGES[(RANGES.indexOf(this.range) + 1) % RANGES.length]!;
+			this.range = next;
+			const snapshot = this.options.getSnapshot(next);
+			if (snapshot) this.setReady(snapshot);
+			return;
+		}
+		if (data === "u" || data === "U") {
+			this.options.onRefresh();
+			return;
+		}
+		if (this.state.kind === "ready" && this.tab === "models") {
+			if (matchesKey(data, Key.down)) {
+				this.modelOffset = Math.min(Math.max(0, this.state.snapshot.models.length - MODEL_PAGE_SIZE), this.modelOffset + 1);
+				this.options.requestRender();
+			} else if (matchesKey(data, Key.up)) {
+				this.modelOffset = Math.max(0, this.modelOffset - 1);
+				this.options.requestRender();
+			}
+		}
+	}
+
+	dispose(): void {
+		this.options.onDispose?.();
+	}
+
+	invalidate(): void {
+		// Rendering uses the live injected theme and has no pre-baked cache.
+	}
+
+	render(width: number): string[] {
+		if (width <= 0) return [""];
+		const lines = this.renderContent(width).map((line) => truncateToWidth(line, width, ""));
+		return lines.length > 0 ? lines : [""];
+	}
+
+	private renderContent(width: number): string[] {
+		const { theme } = this.options;
+		const lines: string[] = [];
+		const selected = (text: string) => theme.bg("selectedBg", theme.fg("accent", theme.bold(` ${text} `)));
+		const normal = (text: string) => theme.fg("muted", ` ${text} `);
+		lines.push(theme.fg("borderAccent", "─".repeat(Math.max(1, width))));
+		lines.push(
+			`${theme.fg("accent", theme.bold(" PI STATS "))}  ${this.tab === "overview" ? selected("Overview") : normal("Overview")} ${this.tab === "models" ? selected("Models") : normal("Models")}`,
+		);
+
+		if (this.state.kind === "loading") {
+			const progress = this.state.total > 0 ? ` ${this.state.completed}/${this.state.total}` : "";
+			lines.push("", theme.fg("accent", " ◌ ") + theme.fg("text", `Scanning Pi sessions…${progress}`), "");
+			lines.push(theme.fg("dim", " Esc close"));
+			lines.push(theme.fg("borderMuted", "─".repeat(Math.max(1, width))));
+			return lines;
+		}
+		if (this.state.kind === "error") {
+			lines.push("", theme.fg("error", ` Stats unavailable: ${this.state.message}`), "");
+			lines.push(theme.fg("dim", " u retry · Esc close"));
+			lines.push(theme.fg("borderMuted", "─".repeat(Math.max(1, width))));
+			return lines;
+		}
+
+		const snapshot = this.state.snapshot;
+		lines.push(
+			` ${theme.fg("muted", "All-time tokens")} ${theme.fg("accent", theme.bold(formatTokens(totalTokens(snapshot.allTime))))}  ${theme.fg("dim", `• ${RANGE_LABELS[this.range]}`)}`,
+		);
+		lines.push(...(this.tab === "overview" ? this.renderOverview(snapshot, width) : this.renderModels(snapshot, width)));
+		const scanWarnings: string[] = [];
+		if (snapshot.diagnostics.unreadableFiles > 0) scanWarnings.push(`${snapshot.diagnostics.unreadableFiles} unreadable file(s)`);
+		if (snapshot.diagnostics.malformedLines > 0) scanWarnings.push(`${snapshot.diagnostics.malformedLines} malformed line(s)`);
+		const warning = scanWarnings.length > 0 ? theme.fg("warning", ` · ⚠ ${scanWarnings.join(" · ")}`) : "";
+		lines.push(theme.fg("dim", " Tab/←→ switch · r range · u refresh · Esc close") + warning);
+		lines.push(theme.fg("borderMuted", "─".repeat(Math.max(1, width))));
+		return lines;
+	}
+
+	private renderUsage(label: string, usage: UsageTotals, width: number): string[] {
+		const { theme } = this.options;
+		const heading = ` ${theme.fg("text", theme.bold(label))}  ${theme.fg("accent", formatTokens(totalTokens(usage)))} ${theme.fg("dim", `tokens · ${formatCost(usage.cost)} · cache hit ${cacheHit(usage)}`)}`;
+		const items = [
+			["Input", usage.input],
+			["Output", usage.output],
+			["Cache R", usage.cacheRead],
+			["Cache W", usage.cacheWrite],
+			["Reasoning ⊂ output", usage.reasoning],
+		] as const;
+		const formatted = items.map(([name, value]) => `${theme.fg("dim", name)} ${theme.fg("text", formatTokens(value))}`);
+		if (width >= 68) return [heading, `   ${formatted.join(theme.fg("dim", " · "))}`];
+		return [heading, `   ${formatted.slice(0, 2).join(theme.fg("dim", " · "))}`, `   ${formatted.slice(2).join(theme.fg("dim", " · "))}`];
+	}
+
+	private renderOverview(snapshot: StatsSnapshot, width: number): string[] {
+		const { theme } = this.options;
+		const lines = [
+			...this.renderUsage("Current session", snapshot.currentSession, width),
+			...this.renderUsage(RANGE_LABELS[snapshot.range], snapshot.period, width),
+		];
+		if (snapshot.range !== "all") lines.push(...this.renderUsage("All time", snapshot.allTime, width));
+		if (width >= 72) lines.push(...this.renderHeatmap(snapshot, width));
+
+		const sessions = `${snapshot.sessionCount} (${snapshot.mainSessionCount} main · ${snapshot.subagentSessionCount} subagents)`;
+		const active = `${snapshot.activeDays} · streak ${snapshot.currentStreak}/${snapshot.longestStreak}d`;
+		const topDay = snapshot.mostActiveDay ? `${snapshot.mostActiveDay.day} · ${formatTokens(snapshot.mostActiveDay.total)}` : "—";
+		const metrics = [
+			["All-time sessions", sessions],
+			["All-time active days", active],
+			["All-time favorite", snapshot.favoriteModel ?? "—"],
+			["All-time busiest", topDay],
+			["Longest session span", formatDuration(snapshot.longestSessionMs)],
+		] as const;
+		if (width >= 80) {
+			for (let index = 0; index < metrics.length; index += 2) {
+				const left = metrics[index]!;
+				const right = metrics[index + 1];
+				const leftText = `${theme.fg("dim", left[0])}: ${theme.fg("text", left[1])}`;
+				const padded = leftText + " ".repeat(Math.max(1, 42 - visibleWidth(leftText)));
+				lines.push(` ${padded}${right ? `${theme.fg("dim", right[0])}: ${theme.fg("text", right[1])}` : ""}`);
+			}
+		} else {
+			for (const [name, value] of metrics) lines.push(` ${theme.fg("dim", name)}: ${theme.fg("text", value)}`);
+		}
+		if (width >= 72 && snapshot.range === "all" && snapshot.allTime.input + snapshot.allTime.output > 0) {
+			const books = (snapshot.allTime.input + snapshot.allTime.output) / 400_000;
+			lines.push(theme.fg("muted", ` Your input + output are roughly ${books.toFixed(books >= 10 ? 0 : 1)}× the tokens in A Game of Thrones.`));
+		}
+		return lines;
+	}
+
+	private renderHeatmap(snapshot: StatsSnapshot, width: number): string[] {
+		const { theme } = this.options;
+		const weeks = Math.max(8, Math.min(53, width - 8));
+		const today = new Date();
+		today.setHours(12, 0, 0, 0);
+		const end = new Date(today);
+		end.setDate(end.getDate() + (7 - ((end.getDay() + 6) % 7) - 1));
+		const start = new Date(end);
+		start.setDate(start.getDate() - weeks * 7 + 1);
+		const totals = new Map(snapshot.days.map((day) => [day.day, day.total]));
+		const maximum = Math.max(0, ...snapshot.days.map((day) => day.total));
+		const glyph = (value: number): string => {
+			if (value <= 0 || maximum <= 0) return theme.fg("dim", "·");
+			const level = Math.max(1, Math.min(4, Math.ceil((Math.log1p(value) / Math.log1p(maximum)) * 4)));
+			if (level === 1) return theme.fg("muted", "░");
+			if (level === 2) return theme.fg("success", "▒");
+			if (level === 3) return theme.fg("warning", "▓");
+			return theme.fg("accent", "█");
+		};
+		const lines = [` ${theme.fg("muted", `All-time activity · trailing ${weeks} weeks`)}`];
+		for (let weekday = 0; weekday < 7; weekday++) {
+			const label = weekday === 0 ? "Mon" : weekday === 2 ? "Wed" : weekday === 4 ? "Fri" : "   ";
+			let row = ` ${theme.fg("dim", label)} `;
+			for (let week = 0; week < weeks; week++) {
+				const date = new Date(start);
+				date.setDate(date.getDate() + week * 7 + weekday);
+				row += glyph(totals.get(localDay(date.getTime())) ?? 0);
+			}
+			lines.push(row);
+		}
+		return lines;
+	}
+
+	private renderModels(snapshot: StatsSnapshot, width: number): string[] {
+		const { theme } = this.options;
+		if (snapshot.models.length === 0) return [theme.fg("muted", ` No model usage in ${RANGE_LABELS[snapshot.range].toLowerCase()}.`)];
+		const start = Math.min(this.modelOffset, Math.max(0, snapshot.models.length - MODEL_PAGE_SIZE));
+		const models = snapshot.models.slice(start, start + MODEL_PAGE_SIZE);
+		const lines: string[] = [];
+		if (width >= 110) {
+			lines.push(theme.fg("dim", ` ${plainPad("Model", 34)} ${plainPad("Calls", 7)} ${plainPad("Share", 7)} ${plainPad("Total", 9)} ${plainPad("Input", 9)} ${plainPad("Output", 9)} ${plainPad("Cache R/W", 17)} Cost`));
+			for (const model of models) {
+				lines.push(
+					` ${theme.fg("text", plainPad(model.model, 34))} ${plainPad(String(model.calls), 7)} ${plainPad(`${(model.share * 100).toFixed(1)}%`, 7)} ${plainPad(formatTokens(model.total), 9)} ${plainPad(formatTokens(model.input), 9)} ${plainPad(formatTokens(model.output), 9)} ${plainPad(`${formatTokens(model.cacheRead)}/${formatTokens(model.cacheWrite)}`, 17)} ${formatCost(model.cost)}`,
+				);
+				if (model.reasoning > 0) lines.push(theme.fg("dim", `   reasoning ⊂ output ${formatTokens(model.reasoning)}`));
+			}
+		} else if (width >= 72) {
+			lines.push(theme.fg("dim", ` ${plainPad("Model", 31)} ${plainPad("Calls", 7)} ${plainPad("Share", 7)} Total`));
+			for (const model of models) {
+				lines.push(` ${theme.fg("text", plainPad(model.model, 31))} ${plainPad(String(model.calls), 7)} ${plainPad(`${(model.share * 100).toFixed(1)}%`, 7)} ${formatTokens(model.total)}`);
+				lines.push(theme.fg("dim", `   in ${formatTokens(model.input)} · out ${formatTokens(model.output)} · cache ${formatTokens(model.cacheRead)}/${formatTokens(model.cacheWrite)} · reason ${formatTokens(model.reasoning)} · ${formatCost(model.cost)}`));
+			}
+		} else {
+			for (const model of models) {
+				lines.push(` ${theme.fg("text", theme.bold(model.model))} ${theme.fg("accent", formatTokens(model.total))} ${theme.fg("dim", `· ${(model.share * 100).toFixed(1)}% · ${model.calls} calls · ${formatCost(model.cost)}`)}`);
+				lines.push(theme.fg("dim", `   in ${formatTokens(model.input)} · out ${formatTokens(model.output)} · cache ${formatTokens(model.cacheRead)}/${formatTokens(model.cacheWrite)} · reason ${formatTokens(model.reasoning)}`));
+			}
+		}
+		if (snapshot.models.length > MODEL_PAGE_SIZE) lines.push(theme.fg("dim", ` ↑↓ models ${start + 1}-${Math.min(snapshot.models.length, start + MODEL_PAGE_SIZE)} of ${snapshot.models.length}`));
+		return lines;
+	}
+}