@hank-warren/pi-stats 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @hank-warren/pi-stats
 
+## 0.5.0
+
+### Minor Changes
+
+- Count Pi `usage` session entries and de-duplicate them against mirrored extension sidecars (#42).
+
+  Pi 0.86 added `SessionManager.appendUsage()`, which records model calls made outside the conversation, such as cache warming, as `type: "usage"` session entries. `/stats` now counts them in every total and shows them as `provider/model (<kind>)` rows. Unknown kinds are counted like any other usage.
+
+  An extension that also mirrors such a call into a usage sidecar for older pi-stats versions gives the sidecar the id `<sessionId>:<usageEntryId>`. That call is counted once, from the session entry. Sidecars without a matching entry, and entries without a matching sidecar, are still counted. The stats cache version is bumped, so existing caches are rescanned once.
+
+## 0.4.2
+
+### Patch Changes
+
+- Label the month the heatmap grid ends in. The axis keyed each month change off its column's Monday and dropped a label that no longer fit at the right edge, so the current month was missing from the axis on 56% of days. Columns are now named for the month holding their Thursday, and the rightmost label is clamped left instead of dropped.
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -39,7 +39,7 @@ Every tab is responsive: as the terminal narrows, lower-priority columns move to
 
 ## 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.
+Pi writes usage to assistant messages, usage-bearing tool results, compactions, branch summaries, and `usage` entries (Pi 0.86+, for model calls outside the conversation such as cache warming). `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.
 
 Tool calls are counted separately from tokens, because most of them record no model usage. Every tool result in a session is tallied by name, along with whether it reported an error. Provider tool-call ids are reused verbatim when a session is forked, so they double as the de-duplication key and a forked branch never inflates the counts. Namespaced names such as `functions.bash` are ranked under their base name.
 
@@ -53,7 +53,9 @@ Some extensions call a model outside the agent loop, so their usage never reache
 {"v":1,"id":"3f2b…","ts":"2026-08-11T22:41:03.118Z","source":"auto-permissions","label":"guardian","provider":"anthropic","model":"claude-fable-5","usage":{"input":812,"output":96,"cacheRead":18442,"cacheWrite":0,"reasoning":48,"cost":0.0121}}
 ```
 
-Records are de-duplicated by `id`, counted in every total, and shown as their own `provider/model (label)` row so the overhead stays visible. They never create sessions, so session counts, streaks, and session spans are unaffected. `@hank-warren/pi-auto-permissions` writes one for guardian reviews; set `PI_STATS_DISABLE_USAGE_SIDECARS=1` to ignore all of them.
+Records are de-duplicated by `id`, counted in every total, and shown as their own `provider/model (label)` row so the overhead stays visible. Session `usage` entries appear the same way as `provider/model (kind)`.
+
+An extension that records a call both ways — a session `usage` entry for Pi 0.86+ and a sidecar for older `pi-stats` versions — gives the sidecar the id `<sessionId>:<usageEntryId>` (the session header id and the usage entry id). That call is counted once, from the session entry; sidecars without a matching entry, and entries without a matching sidecar, are each counted normally. They never create sessions, so session counts, streaks, and session spans are unaffected. `@hank-warren/pi-auto-permissions` writes one for guardian reviews; set `PI_STATS_DISABLE_USAGE_SIDECARS=1` to ignore all of them.
 
 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.
 
@@ -99,3 +101,7 @@ Sessions remain authoritative. For fast repeat opens, the extension stores one d
 The location follows `PI_CODING_AGENT_DIR`. The cache contains file stat identity, session IDs/timestamps/working directories, model names, tool names with call and error counts, usage counters, and de-duplication fingerprints. It never stores prompts, responses, tool arguments, 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.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.

package/cache.ts

@@ -6,12 +6,12 @@ import { makeIndex, parseSessionText, parseUsageSidecar } from "./stats.ts";
 import type { CachedFileRecord, ScanDiagnostics, SessionRecord, StatsCacheFile, StatsIndex, UsageRecord } from "./types.ts";
 
 /** Bumped to 3 when tool-call records were added; older caches lack them and must be reparsed. */
-const CACHE_VERSION = 3 as const;
+const CACHE_VERSION = 4 as const;
 const SKIP_DIRECTORIES = new Set(["subagent-artifacts"]);
 /** Extensions record out-of-transcript model usage in <agentDir>/<extension>/usage.jsonl. */
 const USAGE_SIDECAR_NAMES = new Set(["usage.jsonl", "usage.jsonl.1"]);
 
-export interface ScanOptions {
+interface ScanOptions {
 	agentDir: string;
 	activeSessionDir?: string;
 	env?: NodeJS.ProcessEnv;
@@ -143,7 +143,12 @@ function validUsageRecord(value: unknown): value is UsageRecord {
 		typeof record.fingerprint === "string" &&
 		validNumber(record.timestamp) &&
 		typeof record.model === "string" &&
-		(record.kind === "assistant" || record.kind === "tool" || record.kind === "summary" || record.kind === "sidecar") &&
+		(record.kind === "assistant" ||
+			record.kind === "tool" ||
+			record.kind === "summary" ||
+			record.kind === "usage" ||
+			record.kind === "sidecar") &&
+		(record.sharedId === undefined || typeof record.sharedId === "string") &&
 		Boolean(usage) &&
 		validNumber(usage?.input) &&
 		validNumber(usage?.output) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-stats",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "A compact /stats dashboard for all-time Pi token usage, including persisted subagents.",
   "type": "module",
   "keywords": [
@@ -23,7 +23,7 @@
   },
   "homepage": "https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-stats#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.19.0"
   },
   "pi": {
     "extensions": [

package/stats.ts

@@ -43,7 +43,7 @@ function firstNumber(source: Record<string, unknown>, names: string[]): number {
 	return 0;
 }
 
-export function normalizeUsage(value: unknown): UsageTotals | undefined {
+function normalizeUsage(value: unknown): UsageTotals | undefined {
 	const usage = object(value);
 	if (!usage) return undefined;
 	const cost = object(usage.cost);
@@ -203,6 +203,22 @@ function normalizeEntry(
 			kind: "summary",
 		};
 	}
+
+	// Pi >=0.86 appendUsage(): model usage outside the conversation, such as cache warming.
+	if (entry.type === "usage") {
+		const usage = normalizeUsage(entry.usage);
+		if (!usage) return undefined;
+		const usageKind = typeof entry.kind === "string" && entry.kind.length > 0 ? entry.kind : "usage";
+		const model = `${modelName(entry.provider, entry.model)} (${usageKind})`;
+		return {
+			fingerprint: fingerprint([id, entry.timestamp, "usage", model, usage]),
+			timestamp: entryTimestamp,
+			model,
+			usage,
+			kind: "usage",
+			...(typeof entry.id === "string" && entry.id.length > 0 ? { sharedId: `${sessionId}:${entry.id}` } : {}),
+		};
+	}
 	return undefined;
 }
 
@@ -342,6 +358,7 @@ export function parseUsageSidecar(filePath: string, text: string): { records: Us
 			usage,
 			kind: "sidecar",
 			toolName: source,
+			...(typeof entry.id === "string" && entry.id.length > 0 ? { sharedId: entry.id } : {}),
 		});
 	}
 	return { records, malformedLines };
@@ -375,7 +392,7 @@ function hasPersistedSubagentChild(record: UsageRecord, sessionPaths: ReadonlySe
 	return record.toolName === "subagent" && Boolean(record.childSessionFiles?.some((file) => sessionPaths.has(resolve(file))));
 }
 
-export function deduplicateToolCalls(sessions: readonly SessionRecord[]): ToolCallRecord[] {
+function deduplicateToolCalls(sessions: readonly SessionRecord[]): ToolCallRecord[] {
 	const seen = new Set<string>();
 	const result: ToolCallRecord[] = [];
 	for (const session of sessions) {
@@ -391,9 +408,12 @@ export function deduplicateToolCalls(sessions: readonly SessionRecord[]): ToolCa
 export function deduplicateUsage(sessions: readonly SessionRecord[], sidecar: readonly UsageRecord[] = []): UsageRecord[] {
 	const sessionPaths = new Set(sessions.map((session) => resolve(session.path)));
 	const seen = new Set<string>();
+	const sharedIds = new Set<string>();
 	const result: UsageRecord[] = [];
 	for (const session of sessions) {
 		for (const record of session.usage) {
+			// Registered before the fork check so a copied entry still claims the original's sidecar.
+			if (record.sharedId) sharedIds.add(record.sharedId);
 			if (hasPersistedSubagentChild(record, sessionPaths)) continue;
 			if (seen.has(record.fingerprint)) continue;
 			seen.add(record.fingerprint);
@@ -401,6 +421,7 @@ export function deduplicateUsage(sessions: readonly SessionRecord[], sidecar: re
 		}
 	}
 	for (const record of sidecar) {
+		if (record.sharedId && sharedIds.has(record.sharedId)) continue;
 		if (seen.has(record.fingerprint)) continue;
 		seen.add(record.fingerprint);
 		result.push(record);

package/types.ts

@@ -8,15 +8,17 @@ export interface UsageTotals {
 	calls: number;
 }
 
-export type SessionSource = "main" | "subagent";
+type SessionSource = "main" | "subagent";
 
 export interface UsageRecord {
 	fingerprint: string;
 	timestamp: number;
 	model: string;
 	usage: UsageTotals;
-	kind: "assistant" | "tool" | "summary" | "sidecar";
+	kind: "assistant" | "tool" | "summary" | "usage" | "sidecar";
 	toolName?: string;
+	/** `<sessionId>:<usageEntryId>` on usage entries, the record id on sidecars; a match counts the call once. */
+	sharedId?: string;
 	childSessionFiles?: string[];
 }
 
@@ -55,7 +57,7 @@ export interface CachedFileRecord {
 }
 
 export interface StatsCacheFile {
-	version: 3;
+	version: 4;
 	files: Record<string, CachedFileRecord>;
 }
 

package/widget.ts

@@ -10,12 +10,12 @@ import {
 	type UsageTotals,
 } from "./types.ts";
 
-export type WidgetState =
+type WidgetState =
 	| { kind: "loading"; completed: number; total: number }
 	| { kind: "error"; message: string }
 	| { kind: "ready"; snapshot: StatsSnapshot };
 
-export interface StatsWidgetOptions {
+interface StatsWidgetOptions {
 	theme: Theme;
 	requestRender: () => void;
 	onClose: () => void;
@@ -37,7 +37,7 @@ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "
 const RANGES: StatsRange[] = ["all", "7d", "30d"];
 const RANGE_LABELS: Record<StatsRange, string> = { all: "All time", "7d": "Last 7 days", "30d": "Last 30 days" };
 
-export type StatsTab = "overview" | "models" | "tools" | "projects";
+type StatsTab = "overview" | "models" | "tools" | "projects";
 const TABS: StatsTab[] = ["overview", "models", "tools", "projects"];
 const TAB_LABELS: Record<StatsTab, string> = { overview: "Overview", models: "Models", tools: "Tools", projects: "Projects" };
 
@@ -76,6 +76,45 @@ function localDay(time: number): string {
 	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
 }
 
+/**
+ * The heatmap's month label row: one character per week column, `weeks` wide.
+ *
+ * A column belongs to the month holding its Thursday, so it is named for whichever month
+ * owns four or more of its seven days. Labels are placed right to left because only the
+ * right edge is constrained: each one sits at its month's first column unless its
+ * neighbour crowds it, and shifts left just enough to stay clear.
+ */
+export function monthAxis(start: Date, weeks: number): string {
+	const monthOf = (week: number): number => {
+		const thursday = new Date(start);
+		thursday.setDate(thursday.getDate() + week * 7 + 3);
+		return thursday.getMonth();
+	};
+	/** Three characters plus a space, so neighbouring labels never touch. */
+	const spacing = 4;
+
+	const boundaries: { column: number; month: number }[] = [];
+	for (let week = 0; week < weeks; week++) {
+		const month = monthOf(week);
+		if (month !== monthOf(week - 1)) boundaries.push({ column: week, month });
+	}
+	// A grid too short to leave its month has no boundary to label, so name it after its
+	// last column like every other grid.
+	if (boundaries.length === 0) boundaries.push({ column: 0, month: monthOf(weeks - 1) });
+
+	const placed: { column: number; month: number }[] = [];
+	let rightmost = weeks - 3;
+	for (let index = boundaries.length - 1; index >= 0 && rightmost >= 0; index--) {
+		const column = Math.min(boundaries[index]!.column, rightmost);
+		placed.unshift({ column, month: boundaries[index]!.month });
+		rightmost = column - spacing;
+	}
+
+	let row = "";
+	for (const { column, month } of placed) row = row.padEnd(column, " ") + MONTHS[month]!;
+	return row.padEnd(weeks, " ").slice(0, weeks);
+}
+
 function padRight(value: string, width: number): string {
 	const clipped = truncateToWidth(value, Math.max(0, width), "");
 	return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
@@ -424,22 +463,7 @@ export class StatsWidget implements Component {
 		const gap = Math.max(1, width - visibleWidth(heading) - visibleWidth(legend) - 1);
 		const lines = [`${heading}${" ".repeat(gap)}${theme.fg("dim", legend)}`];
 
-		let months = " ".repeat(HEATMAP_LABEL_WIDTH);
-		let lastLabel = -4;
-		for (let week = 0; week < weeks; week++) {
-			const date = new Date(start);
-			date.setDate(date.getDate() + week * 7);
-			const previous = new Date(date);
-			previous.setDate(previous.getDate() - 7);
-			if ((week === 0 || date.getMonth() !== previous.getMonth()) && week - lastLabel >= 4 && week + 3 <= weeks) {
-				months += MONTHS[date.getMonth()]!;
-				lastLabel = week;
-				week += 2;
-			} else {
-				months += " ";
-			}
-		}
-		lines.push(theme.fg("dim", months));
+		lines.push(theme.fg("dim", " ".repeat(HEATMAP_LABEL_WIDTH) + monthAxis(start, weeks)));
 
 		for (let weekday = 0; weekday < 7; weekday++) {
 			const label = weekday === 0 ? "Mon" : weekday === 2 ? "Wed" : weekday === 4 ? "Fri" : "   ";