@youngjurry/pi-agents 0.7.5 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.8.1 - 2026-09-10
+
+- Remove automatic legacy-file archival and its full main-session scan; the extension no longer archives or deletes user session data.
+- Retain only the lightweight `codex-agents` → `pi-agents` compatibility migration required for users upgrading directly from 0.7.x; it is a no-op for fresh installations.
+
+## 0.8.0 - 2026-09-09
+
+- Add `/agent-usage`, a read-only overlay that reports separate main/sub-agent token and cache totals plus combined tokens and cost without modifying root context.
+- Move package-owned storage from `~/.pi/agent/codex-agents/` to `~/.pi/agent/pi-agents/` and rename `agents-setting.json` to `settings.json` with collision-safe automatic migration.
+- Archive legacy flat session/result files only after scanning every ordinary Pi main session and confirming that no persisted agent state references their IDs.
+- Durably initialize queued child JSONL files before returning from batch spawn, preserving the original Session ID, child ownership metadata, and fork context across queueing and process restarts.
+- Repair missing queued-session files from affected older releases with their persisted IDs; already-lost historical fork context cannot be reconstructed.
+- Record the owning root Session ID directly in newly created child metadata.
+
 ## 0.7.5 - 2026-09-05
 
 - Exclude the active `wait_agent` caller from its folded child-status summary.

package/README.md

@@ -56,6 +56,16 @@ Viewer controls:
 
 This inspector is implemented only as a slash command and TUI overlay. It does not register an LLM tool, alter tool schemas or system prompts, add messages to the root context, switch sessions, wake agents, or expose child sessions through the normal `/resume` picker.
 
+## Usage accounting
+
+Pi's built-in `/session` remains the authoritative view of the main Agent and its cache behavior. Use the user-only command below for separately calculated main, sub-agent, and combined totals:
+
+```text
+/agent-usage
+```
+
+The read-only overlay reports main and child token totals, separate cache hit rates, combined tokens/cost, and any unreadable child sessions. It reads persisted child JSONL files without loading or waking their AgentSessions, does not add a main-session message, and does not alter provider-facing context. Pi currently has no extension hook that can add child tokens to built-in `/session` while excluding them from that command's cache statistics.
+
 ## Tools
 
 Only two compact collaboration schemas remain active:
@@ -140,7 +150,7 @@ Review carefully and return findings with exact paths.
 
 Global sub-agent settings live outside the installed package so updates cannot overwrite them:
 
-`~/.pi/agent/codex-agents/agents-setting.json`
+`~/.pi/agent/pi-agents/settings.json`
 
 ```json
 {
@@ -170,14 +180,17 @@ The settings file is optional, but spawning requires a model from either the tas
 - Default resident child sessions: 3, configurable with `maxResidentSubagents`
 - `spawn_agents` starts tasks until all execution slots are occupied and records the remainder as `queued`
 - Queued tasks are lightweight, persistent, FIFO ordered, and do not occupy resident-session capacity
+- Queued session identity, child ownership metadata, and sanitized fork context are durably written before the batch spawn returns
 - `list_agents(view="status")` reports each waiting task's queue position plus current running/queued capacity
 - The live widget shows `Agents active: <running>/<limit> · queued: <waiting>` and labels waiting paths explicitly
 - Completed/interrupted sessions are unloaded by LRU when residency is full
-- Child sessions persist under `~/.pi/agent/codex-agents/roots/<root-session-id>/sessions/` and reload lazily
-- Full final answers persist under `~/.pi/agent/codex-agents/roots/<root-session-id>/results/`
+- Child sessions persist under `~/.pi/agent/pi-agents/roots/<root-session-id>/sessions/` and reload lazily
+- Full final answers persist under `~/.pi/agent/pi-agents/roots/<root-session-id>/results/`
 - Each root storage group records its owning main-session file in `owner.json`
-- Resuming an existing main session removes groups whose owning main-session file has been deleted; new sessions and `/reload` do not trigger cleanup
+- The former `~/.pi/agent/codex-agents/` directory and `agents-setting.json` filename migrate automatically without overwriting newer files
+- Resuming an existing main session removes groups whose owning main-session file has been deleted; new sessions and `/reload` do not trigger grouped cleanup
 - Referenced legacy flat child files are migrated when their main session is resumed
+- The extension never automatically archives or deletes legacy flat files
 - Parents receive a compact completion notice instead of the full answer; use `list_agents(view="results")` or read the result file on demand
 - Notices to a busy agent are queued safely: `wait_agent` returns them in its own result, and any leftovers are delivered right after a successful recipient turn
 - `wait_agent` sends only newly queued mailbox notices to the model; its child status tree excludes the active caller, is folded in the TUI by default, and can be toggled with `Ctrl+O`

package/control.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Model } from "@earendil-works/pi-ai";
+import type { Model, Usage } from "@earendil-works/pi-ai";
 import {
 	buildSessionContext,
 	createAgentSession,
@@ -47,12 +47,15 @@ import {
 	type AgentRole,
 	type AgentRoleView,
 	type AgentTranscriptView,
+	type AgentUsageReport,
+	type AgentUsageTotals,
 	type AgentView,
 	type ForkContextPayload,
 	type PersistedAgent,
 	type PersistedTreeState,
 	type RootBinding,
 } from "./types.ts";
+import { getAgentStorageDirectory, resolveMigratedStoragePath } from "./storage.ts";
 
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 const MIN_WAIT_TIMEOUT_MS = 10_000;
@@ -100,6 +103,46 @@ interface RootStorageOwner {
 	rootSessionFile?: string;
 }
 
+function emptyUsageTotals(): AgentUsageTotals {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, cost: 0 };
+}
+
+function addUsage(target: AgentUsageTotals, usage: Usage | undefined): void {
+	if (!usage) return;
+	target.input += usage.input || 0;
+	target.output += usage.output || 0;
+	target.cacheRead += usage.cacheRead || 0;
+	target.cacheWrite += usage.cacheWrite || 0;
+	target.total = target.input + target.output + target.cacheRead + target.cacheWrite;
+	target.cost += usage.cost?.total || 0;
+}
+
+function addUsageTotals(target: AgentUsageTotals, source: AgentUsageTotals): void {
+	target.input += source.input;
+	target.output += source.output;
+	target.cacheRead += source.cacheRead;
+	target.cacheWrite += source.cacheWrite;
+	target.total = target.input + target.output + target.cacheRead + target.cacheWrite;
+	target.cost += source.cost;
+}
+
+function sessionUsage(sessionManager: Pick<SessionManager, "getEntries">): AgentUsageTotals {
+	const totals = emptyUsageTotals();
+	for (const entry of sessionManager.getEntries()) {
+		if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
+			addUsage(totals, entry.usage);
+		}
+		if (entry.type !== "message") continue;
+		const message = entry.message;
+		if (message.role === "assistant" || message.role === "toolResult") addUsage(totals, message.usage);
+	}
+	return totals;
+}
+
+function normalizeCost(value: number): number {
+	return Math.round(value * 1_000_000_000) / 1_000_000_000;
+}
+
 function normalizeAgentName(name: string): string {
 	const normalized = name.trim();
 	if (!normalized) throw new Error("task_name must not be empty");
@@ -170,9 +213,9 @@ export class AgentControl {
 	private uiDialogTail: Promise<void> = Promise.resolve();
 	private userOverlayDepth = 0;
 	private readonly userOverlayWaiters = new Set<() => void>();
-	private readonly rootStorageDirectory = path.join(getAgentDir(), "codex-agents", "roots");
-	private childSessionDirectory = path.join(getAgentDir(), "codex-agents", "sessions");
-	private agentResultDirectory = path.join(getAgentDir(), "codex-agents", "results");
+	private readonly rootStorageDirectory = path.join(getAgentStorageDirectory(), "roots");
+	private childSessionDirectory = path.join(getAgentStorageDirectory(), "sessions");
+	private agentResultDirectory = path.join(getAgentStorageDirectory(), "results");
 
 	constructor(
 		private readonly pi: ExtensionAPI,
@@ -268,9 +311,11 @@ export class AgentControl {
 
 	private migrateStoredFile(file: string | undefined, directory: string): { path: string | undefined; migrated: boolean } {
 		if (!file) return { path: undefined, migrated: false };
-		const source = path.resolve(file);
+		const original = path.resolve(file);
+		const source = resolveMigratedStoragePath(original);
+		const translated = source !== original;
 		const destinationDirectory = path.resolve(directory);
-		if (path.dirname(source) === destinationDirectory) return { path: source, migrated: false };
+		if (path.dirname(source) === destinationDirectory) return { path: source, migrated: translated };
 		const target = path.join(destinationDirectory, path.basename(source));
 		try {
 			fs.mkdirSync(destinationDirectory, { recursive: true });
@@ -326,7 +371,8 @@ export class AgentControl {
 			}
 			if (owner.version !== 1 || typeof owner.rootSessionId !== "string") continue;
 			if (owner.rootSessionId === currentSessionId) continue;
-			if (owner.rootSessionFile && fs.existsSync(owner.rootSessionFile)) continue;
+			// Missing ownership evidence is not proof of an orphan.
+			if (!owner.rootSessionFile || fs.existsSync(owner.rootSessionFile)) continue;
 			try {
 				fs.rmSync(directory, { recursive: true, force: true });
 				removed++;
@@ -547,7 +593,7 @@ export class AgentControl {
 	private async resolveModel(ctx: ExtensionContext, requested?: string): Promise<Model<any>> {
 		const value = requested?.trim();
 		if (!value) {
-			throw new Error("no sub-agent model configured; set a task model, Role model, or defaultModel in agents-setting.json");
+			throw new Error("no sub-agent model configured; set a task model, Role model, or defaultModel in pi-agents/settings.json");
 		}
 		const runtime = await this.getModelRuntime(ctx);
 		const slash = value.indexOf("/");
@@ -823,6 +869,26 @@ export class AgentControl {
 		return prepared;
 	}
 
+	private persistQueuedSession(sessionManager: SessionManager): string {
+		const sessionFile = sessionManager.getSessionFile();
+		const header = sessionManager.getHeader();
+		if (!sessionFile || !header) throw new Error("failed to initialize a persisted sub-agent session");
+		fs.mkdirSync(path.dirname(sessionFile), { recursive: true });
+		const entries = [header, ...sessionManager.getEntries()];
+		const descriptor = fs.openSync(sessionFile, "wx");
+		let completed = false;
+		try {
+			fs.writeFileSync(descriptor, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf8");
+			fs.fsyncSync(descriptor);
+			completed = true;
+		} finally {
+			try { fs.closeSync(descriptor); } finally {
+				if (!completed) fs.rmSync(sessionFile, { force: true });
+			}
+		}
+		return sessionFile;
+	}
+
 	private materializeQueuedBatch(ctx: ExtensionContext, prepared: PreparedSpawn[]): AgentRecord[] {
 		const records: AgentRecord[] = [];
 		const baseTime = Date.now();
@@ -858,15 +924,15 @@ export class AgentControl {
 						payload: item.request.message,
 					}),
 				};
-				record.sessionFile = sessionManager.getSessionFile();
 				records.push(record);
-				if (!record.sessionFile) throw new Error(`failed to create persisted session for ${record.path}`);
 				sessionManager.appendCustomEntry(CHILD_META_ENTRY_TYPE, {
 					path: record.path,
 					parentPath: record.parentPath,
+					rootSessionId: this.root!.sessionId,
 					role: record.role,
 				});
 				sessionManager.appendCustomEntry(FORK_CONTEXT_ENTRY_TYPE, { messages: item.forkMessages });
+				record.sessionFile = this.persistQueuedSession(sessionManager);
 			}
 		} catch (error) {
 			for (const record of records) {
@@ -1098,6 +1164,44 @@ export class AgentControl {
 		return this.view(record);
 	}
 
+	getUsage(ctx: ExtensionContext): AgentUsageReport {
+		this.callerPath(ctx);
+		const main = sessionUsage(ctx.sessionManager);
+		const subagents = emptyUsageTotals();
+		let unreadableSubagents = 0;
+		const countedSessionIds = new Set<string>();
+		for (const record of this.agentsByPath.values()) {
+			try {
+				const liveManager = record.session?.sessionManager;
+				const storedFile = record.sessionFile ? resolveMigratedStoragePath(record.sessionFile) : undefined;
+				if (!liveManager && (!storedFile || !fs.existsSync(storedFile))) {
+					unreadableSubagents++;
+					continue;
+				}
+				const manager = liveManager ?? SessionManager.open(storedFile!);
+				const sessionId = manager.getSessionId();
+				if (countedSessionIds.has(sessionId)) continue;
+				countedSessionIds.add(sessionId);
+				addUsageTotals(subagents, sessionUsage(manager));
+			} catch {
+				unreadableSubagents++;
+			}
+		}
+		const combined = emptyUsageTotals();
+		addUsageTotals(combined, main);
+		addUsageTotals(combined, subagents);
+		main.cost = normalizeCost(main.cost);
+		subagents.cost = normalizeCost(subagents.cost);
+		combined.cost = normalizeCost(combined.cost);
+		return {
+			main,
+			subagents,
+			combined,
+			subagentCount: this.agentsByPath.size,
+			unreadableSubagents,
+		};
+	}
+
 	list(ctx: ExtensionContext, prefix?: string, includeResults = false): AgentView[] {
 		const callerPath = this.callerPath(ctx);
 		const resolvedPrefix = prefix?.trim() ? this.resolveReference(callerPath, prefix) : undefined;
@@ -1284,7 +1388,29 @@ export class AgentControl {
 		if (!record.sessionFile) throw new Error(`agent ${record.path} has no persisted session file`);
 		if (!this.root) throw new Error("root session is not bound");
 		await this.evictForResidency(record.path);
-		const sessionManager = SessionManager.open(record.sessionFile);
+		const migratedSessionFile = resolveMigratedStoragePath(record.sessionFile);
+		if (migratedSessionFile !== record.sessionFile) {
+			record.sessionFile = migratedSessionFile;
+			this.persistState();
+		}
+		let sessionManager: SessionManager;
+		if (fs.existsSync(record.sessionFile)) {
+			sessionManager = SessionManager.open(record.sessionFile);
+		} else {
+			// Older queue releases persisted only a future path. Recreate a durable
+			// session with the recorded identity; its lost fork context is unrecoverable.
+			sessionManager = SessionManager.create(this.root.cwd, this.childSessionDirectory, { id: record.id });
+			sessionManager.appendCustomEntry(CHILD_META_ENTRY_TYPE, {
+				path: record.path,
+				parentPath: record.parentPath,
+				rootSessionId: this.root.sessionId,
+				role: record.role,
+			});
+			sessionManager.appendCustomEntry(FORK_CONTEXT_ENTRY_TYPE, { messages: [] });
+			record.sessionFile = this.persistQueuedSession(sessionManager);
+			this.persistState();
+			sessionManager = SessionManager.open(record.sessionFile);
+		}
 		const forkContext = this.forkContextFromSessionManager(sessionManager);
 		const role = resolveRole(this.root.cwd, this.root.ctx.isProjectTrusted(), record.role);
 		const settingsManager = SettingsManager.create(this.root.cwd, getAgentDir());

package/index.ts

@@ -5,8 +5,9 @@ import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { AgentControl } from "./control.ts";
 import { getAgentSettingsPath, loadAgentSettings, resolveAgentLimits } from "./settings.ts";
 import { createCollaborationTools } from "./tools.ts";
+import { migrateLegacyAgentStorage } from "./storage.ts";
 import { EXTENSION_ID, ROOT_PATH, type AgentLifecycleStatus, type AgentView } from "./types.ts";
-import { AgentPickerComponent, AgentTranscriptViewer } from "./viewer.ts";
+import { AgentPickerComponent, AgentTranscriptViewer, AgentUsageViewer, formatAgentUsage } from "./viewer.ts";
 
 const SELF_PATH = fileURLToPath(import.meta.url);
 const WIDGET_KEY = "codex-agents-tree";
@@ -85,6 +86,7 @@ class AgentTreeWidget {
 }
 
 export default function codexAgentsExtension(pi: ExtensionAPI): void {
+	const storageMigration = migrateLegacyAgentStorage();
 	const limits = resolveAgentLimits(loadAgentSettings(), getAgentSettingsPath());
 	const control = new AgentControl(
 		pi,
@@ -98,6 +100,7 @@ export default function codexAgentsExtension(pi: ExtensionAPI): void {
 
 	let activeContext: ExtensionContext | undefined;
 	let widgetTui: { requestRender(): void } | undefined;
+	let storageMigrationReported = false;
 
 	const updateUi = () => {
 		const ctx = activeContext;
@@ -124,6 +127,13 @@ export default function codexAgentsExtension(pi: ExtensionAPI): void {
 	pi.on("session_start", (event, ctx) => {
 		activeContext = ctx;
 		control.bindRoot(ctx);
+		if (!storageMigrationReported) {
+			storageMigrationReported = true;
+			if (storageMigration.movedEntries > 0) {
+				ctx.ui.notify(`Migrated agent storage to ~/.pi/agent/pi-agents (${storageMigration.movedEntries} entries).`, "info");
+			}
+			for (const warning of storageMigration.warnings) ctx.ui.notify(`Agent storage migration: ${warning}`, "warning");
+		}
 		const resumedExistingSession = event.reason === "resume"
 			|| (event.reason === "startup" && ctx.sessionManager.getEntries().some((entry) => entry.type === "message"));
 		if (resumedExistingSession) {
@@ -199,6 +209,36 @@ export default function codexAgentsExtension(pi: ExtensionAPI): void {
 		return new Text(`${header}\n${theme.fg("customMessageText", body)}`, 1, 0);
 	});
 
+	pi.registerCommand("agent-usage", {
+		description: "Show main, sub-agent, and combined token usage",
+		handler: async (_args, ctx) => {
+			activeContext = ctx;
+			let report;
+			try {
+				report = control.getUsage(ctx);
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				return;
+			}
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify(formatAgentUsage(report), "info");
+				return;
+			}
+			const releaseUserOverlay = control.beginUserOverlay();
+			try {
+				await ctx.ui.custom<void>(
+					(_tui, theme, keybindings, done) => new AgentUsageViewer(theme, keybindings, report, done),
+					{
+						overlay: true,
+						overlayOptions: { anchor: "center", width: "62%", maxHeight: "70%", margin: 1 },
+					},
+				);
+			} finally {
+				releaseUserOverlay();
+			}
+		},
+	});
+
 	pi.registerCommand("agents", {
 		description: "Browse sub-agent status and inspect read-only session transcripts",
 		getArgumentCompletions: (prefix) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youngjurry/pi-agents",
-  "version": "0.7.5",
+  "version": "0.8.1",
   "description": "Persistent in-process Codex-style multi-agent collaboration for Pi",
   "author": "youngjurry",
   "type": "module",

package/settings.ts

@@ -6,7 +6,10 @@ import {
 	getSupportedThinkingLevels,
 	type Model,
 } from "@earendil-works/pi-ai";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+	getAgentSettingsPath as getCurrentAgentSettingsPath,
+	getLegacyAgentSettingsPaths,
+} from "./storage.ts";
 
 export const DEFAULT_MAX_CONCURRENT_SUBAGENTS = 3;
 export const DEFAULT_MAX_RESIDENT_SUBAGENTS = 3;
@@ -26,7 +29,7 @@ export interface AgentLimits {
 }
 
 export function getAgentSettingsPath(): string {
-	return path.join(getAgentDir(), "codex-agents", "agents-setting.json");
+	return getCurrentAgentSettingsPath();
 }
 
 export function selectAgentModel(...candidates: Array<string | undefined>): string | undefined {
@@ -53,30 +56,34 @@ export function selectAgentThinkingLevel(
 }
 
 export function loadAgentSettings(filePath = getAgentSettingsPath()): AgentSettings {
-	if (!fs.existsSync(filePath)) return {};
+	let resolvedPath = filePath;
+	if (!fs.existsSync(resolvedPath) && path.resolve(filePath) === path.resolve(getAgentSettingsPath())) {
+		resolvedPath = getLegacyAgentSettingsPaths().find((candidate) => fs.existsSync(candidate)) ?? resolvedPath;
+	}
+	if (!fs.existsSync(resolvedPath)) return {};
 
 	let value: unknown;
 	try {
-		value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+		value = JSON.parse(fs.readFileSync(resolvedPath, "utf8"));
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
-		throw new Error(`failed to read agent settings at ${filePath}: ${message}`);
+		throw new Error(`failed to read agent settings at ${resolvedPath}: ${message}`);
 	}
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		throw new Error(`agent settings at ${filePath} must contain a JSON object`);
+		throw new Error(`agent settings at ${resolvedPath} must contain a JSON object`);
 	}
 
 	const raw = value as Record<string, unknown>;
 	const settings: AgentSettings = {};
 	if (raw.defaultModel !== undefined) {
 		if (typeof raw.defaultModel !== "string" || !raw.defaultModel.trim()) {
-			throw new Error(`defaultModel in ${filePath} must be a non-empty provider/model string`);
+			throw new Error(`defaultModel in ${resolvedPath} must be a non-empty provider/model string`);
 		}
 		settings.defaultModel = raw.defaultModel.trim();
 	}
 	if (raw.defaultThinkingLevel !== undefined) {
 		if (typeof raw.defaultThinkingLevel !== "string" || !CHILD_THINKING_LEVELS.includes(raw.defaultThinkingLevel as ThinkingLevel)) {
-			throw new Error(`defaultThinkingLevel in ${filePath} must be one of: ${CHILD_THINKING_LEVELS.join(", ")}`);
+			throw new Error(`defaultThinkingLevel in ${resolvedPath} must be one of: ${CHILD_THINKING_LEVELS.join(", ")}`);
 		}
 		settings.defaultThinkingLevel = raw.defaultThinkingLevel as ThinkingLevel;
 	}
@@ -84,7 +91,7 @@ export function loadAgentSettings(filePath = getAgentSettingsPath()): AgentSetti
 		const limit = raw[key];
 		if (limit === undefined) continue;
 		if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1) {
-			throw new Error(`${key} in ${filePath} must be a positive integer`);
+			throw new Error(`${key} in ${resolvedPath} must be a positive integer`);
 		}
 		settings[key] = limit;
 	}

package/storage.ts

@@ -0,0 +1,87 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const STORAGE_DIRECTORY_NAME = "pi-agents";
+const LEGACY_STORAGE_DIRECTORY_NAME = "codex-agents";
+const SETTINGS_FILE_NAME = "settings.json";
+const LEGACY_SETTINGS_FILE_NAME = "agents-setting.json";
+
+export interface StorageMigrationReport {
+	movedEntries: number;
+	warnings: string[];
+}
+
+export function getAgentStorageDirectory(): string {
+	return path.join(getAgentDir(), STORAGE_DIRECTORY_NAME);
+}
+
+export function getLegacyAgentStorageDirectory(): string {
+	return path.join(getAgentDir(), LEGACY_STORAGE_DIRECTORY_NAME);
+}
+
+export function getAgentSettingsPath(): string {
+	return path.join(getAgentStorageDirectory(), SETTINGS_FILE_NAME);
+}
+
+export function getLegacyAgentSettingsPaths(): string[] {
+	return [
+		path.join(getAgentStorageDirectory(), LEGACY_SETTINGS_FILE_NAME),
+		path.join(getLegacyAgentStorageDirectory(), LEGACY_SETTINGS_FILE_NAME),
+	];
+}
+
+function mergeWithoutOverwrite(source: string, destination: string, report: StorageMigrationReport): void {
+	if (!fs.existsSync(source)) return;
+	if (!fs.existsSync(destination)) {
+		fs.mkdirSync(path.dirname(destination), { recursive: true });
+		fs.renameSync(source, destination);
+		report.movedEntries++;
+		return;
+	}
+	const sourceStat = fs.statSync(source);
+	const destinationStat = fs.statSync(destination);
+	if (!sourceStat.isDirectory() || !destinationStat.isDirectory()) {
+		report.warnings.push(`storage migration left a conflicting path untouched: ${source}`);
+		return;
+	}
+	for (const entry of fs.readdirSync(source)) {
+		mergeWithoutOverwrite(path.join(source, entry), path.join(destination, entry), report);
+	}
+	try {
+		if (fs.readdirSync(source).length === 0) fs.rmdirSync(source);
+	} catch {
+		// A partial migration remains readable through the legacy path fallback.
+	}
+}
+
+/**
+ * Preserve the 0.7.x upgrade path. For a fresh installation this is only an
+ * existence check and performs no writes.
+ */
+export function migrateLegacyAgentStorage(): StorageMigrationReport {
+	const report: StorageMigrationReport = { movedEntries: 0, warnings: [] };
+	const source = getLegacyAgentStorageDirectory();
+	const destination = getAgentStorageDirectory();
+	try {
+		mergeWithoutOverwrite(source, destination, report);
+		const legacySettings = path.join(destination, LEGACY_SETTINGS_FILE_NAME);
+		const settings = getAgentSettingsPath();
+		if (fs.existsSync(legacySettings)) mergeWithoutOverwrite(legacySettings, settings, report);
+	} catch (error) {
+		report.warnings.push(error instanceof Error ? error.message : String(error));
+	}
+	return report;
+}
+
+/** Translate paths persisted before the storage directory rename. */
+export function resolveMigratedStoragePath(file: string): string {
+	const source = path.resolve(file);
+	const legacyRoot = path.resolve(getLegacyAgentStorageDirectory());
+	if (source !== legacyRoot && !source.startsWith(`${legacyRoot}${path.sep}`)) return source;
+	// A collision-safe merge leaves the legacy source in place. Prefer the exact
+	// persisted path instead of shadowing it with a different destination file.
+	if (fs.existsSync(source)) return source;
+	const translated = path.join(getAgentStorageDirectory(), path.relative(legacyRoot, source));
+	return fs.existsSync(translated) ? translated : source;
+}

package/types.ts

@@ -104,6 +104,23 @@ export interface AgentCounts {
 	residentSlots: number;
 }
 
+export interface AgentUsageTotals {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	total: number;
+	cost: number;
+}
+
+export interface AgentUsageReport {
+	main: AgentUsageTotals;
+	subagents: AgentUsageTotals;
+	combined: AgentUsageTotals;
+	subagentCount: number;
+	unreadableSubagents: number;
+}
+
 export interface AgentTranscriptView {
 	agent: AgentView;
 	sessionFile: string;
@@ -137,6 +154,7 @@ export interface ForkContextPayload {
 export interface ChildMetaPayload {
 	path: string;
 	parentPath: string;
+	rootSessionId?: string;
 	role?: string;
 }
 

package/viewer.ts

@@ -17,7 +17,13 @@ import {
 	visibleWidth,
 	type TUI,
 } from "@earendil-works/pi-tui";
-import { ROOT_PATH, type AgentTranscriptView, type AgentView } from "./types.ts";
+import {
+	ROOT_PATH,
+	type AgentTranscriptView,
+	type AgentUsageReport,
+	type AgentUsageTotals,
+	type AgentView,
+} from "./types.ts";
 
 type ChangeSubscriber = (listener: () => void) => () => void;
 
@@ -73,6 +79,77 @@ function itemLine(agent: AgentView, theme: Theme, width: number): string {
 	return `${clipped}${" ".repeat(Math.max(1, width - visibleWidth(clipped) - visibleWidth(right)))}${right}`;
 }
 
+function usagePromptTokens(usage: AgentUsageTotals): number {
+	return usage.input + usage.cacheRead + usage.cacheWrite;
+}
+
+function usageCacheRate(usage: AgentUsageTotals): string {
+	const prompt = usagePromptTokens(usage);
+	return prompt > 0 ? `${((usage.cacheRead / prompt) * 100).toFixed(1)}%` : "n/a";
+}
+
+export function formatAgentUsage(report: AgentUsageReport): string {
+	const lines = [
+		"Agent Usage",
+		"",
+		`Main agent:  ${report.main.total.toLocaleString()} tokens · cache ${usageCacheRate(report.main)}`,
+		`Sub-agents:  ${report.subagents.total.toLocaleString()} tokens · cache ${usageCacheRate(report.subagents)}`,
+		`Combined:    ${report.combined.total.toLocaleString()} tokens`,
+		"",
+		`Sub-agents counted: ${report.subagentCount - report.unreadableSubagents}/${report.subagentCount}`,
+	];
+	if (report.combined.cost > 0) lines.push(`Combined cost: $${report.combined.cost.toFixed(3)}`);
+	if (report.unreadableSubagents > 0) lines.push(`Unreadable sessions: ${report.unreadableSubagents}`);
+	return lines.join("\n");
+}
+
+export class AgentUsageViewer {
+	constructor(
+		private readonly theme: Theme,
+		private readonly keybindings: KeybindingsManager,
+		private readonly report: AgentUsageReport,
+		private readonly done: () => void,
+	) {}
+
+	handleInput(data: string): void {
+		if (this.keybindings.matches(data, "tui.select.cancel") || this.keybindings.matches(data, "tui.select.confirm")) {
+			this.done();
+		}
+	}
+
+	render(width: number): string[] {
+		const innerWidth = Math.max(1, width - 2);
+		const row = (label: string, usage: AgentUsageTotals, includeCache: boolean): string => {
+			const cache = includeCache ? ` · cache ${usageCacheRate(usage)}` : "";
+			return ` ${this.theme.fg("dim", `${label}:`)} ${usage.total.toLocaleString()} tokens${cache}`;
+		};
+		const lines = [
+			framedRule(this.theme, innerWidth, "╭", "╮"),
+			framedRow(this.theme, ` ${this.theme.fg("accent", this.theme.bold("Agent Usage"))}`, innerWidth),
+			framedRule(this.theme, innerWidth, "├", "┤"),
+			framedRow(this.theme, row("Main agent", this.report.main, true), innerWidth),
+			framedRow(this.theme, row("Sub-agents", this.report.subagents, true), innerWidth),
+			framedRow(this.theme, row("Combined", this.report.combined, false), innerWidth),
+			framedRow(this.theme, "", innerWidth),
+			framedRow(this.theme, ` ${this.theme.fg("dim", "Sub-agents counted:")} ${this.report.subagentCount - this.report.unreadableSubagents}/${this.report.subagentCount}`, innerWidth),
+		];
+		if (this.report.combined.cost > 0) {
+			lines.push(framedRow(this.theme, ` ${this.theme.fg("dim", "Combined cost:")} $${this.report.combined.cost.toFixed(3)}`, innerWidth));
+		}
+		if (this.report.unreadableSubagents > 0) {
+			lines.push(framedRow(this.theme, ` ${this.theme.fg("warning", `Unreadable sessions: ${this.report.unreadableSubagents}`)}`, innerWidth));
+		}
+		lines.push(
+			framedRule(this.theme, innerWidth, "├", "┤"),
+			framedRow(this.theme, ` ${this.theme.fg("dim", "Enter / Esc close")}`, innerWidth),
+			framedRule(this.theme, innerWidth, "╰", "╯"),
+		);
+		return lines;
+	}
+
+	invalidate(): void {}
+}
+
 export class AgentPickerComponent {
 	private agents: AgentView[] = [];
 	private selectedIndex = 0;