@youngjurry/pi-agents 0.7.4 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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.
+- Prevent the root Agent's necessarily `running` tool turn from appearing as a phantom running sub-agent.
+- Scope nested waits to the caller's own subtree while preserving `Ctrl+O` expansion.
+
 ## 0.7.4 - 2026-09-05
 
 - Match Pi's progressive Skill disclosure for sub-agent Roles instead of eagerly injecting complete `SKILL.md` files.

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,17 +180,20 @@ 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
+- Legacy flat files are archived only after every ordinary Pi main session has been scanned and no persisted agent-state reference exists
 - Referenced legacy flat child files are migrated when their main session is resumed
 - 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 full status tree is folded in the TUI by default and can be toggled with `Ctrl+O`
+- `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`
 - Failed notice delivery is re-queued instead of silently discarded
 - Notices pending when a turn is aborted or errors are deferred to the next explicit turn without restarting the interrupted agent
 - The extension never inserts messages between an assistant tool call and its tool result, keeping session history protocol-valid for strict gateways

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 { archiveUnownedLegacyFiles, 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,8 @@ export default function codexAgentsExtension(pi: ExtensionAPI): void {
 
 	let activeContext: ExtensionContext | undefined;
 	let widgetTui: { requestRender(): void } | undefined;
+	let storageMigrationReported = false;
+	let legacyArchiveStarted = false;
 
 	const updateUi = () => {
 		const ctx = activeContext;
@@ -124,6 +128,25 @@ 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");
+		}
+		if (!legacyArchiveStarted) {
+			legacyArchiveStarted = true;
+			void archiveUnownedLegacyFiles().then((report) => {
+				const current = activeContext;
+				if (!current) return;
+				if (report.error) {
+					current.ui.notify(`Legacy agent archive skipped: ${report.error}`, "warning");
+				} else if (report.archivedFiles > 0) {
+					current.ui.notify(`Archived ${report.archivedFiles} unowned legacy agent files to ${report.archiveDirectory}.`, "info");
+				}
+			});
+		}
 		const resumedExistingSession = event.reason === "resume"
 			|| (event.reason === "startup" && ctx.sessionManager.getEntries().some((entry) => entry.type === "message"));
 		if (resumedExistingSession) {
@@ -199,6 +222,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.4",
+  "version": "0.8.0",
   "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,247 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createInterface } from "node:readline";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { STATE_ENTRY_TYPE } from "./types.ts";
+
+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 interface LegacyArchiveReport {
+	archivedFiles: number;
+	retainedFiles: number;
+	scannedMainSessions: number;
+	archiveDirectory?: string;
+	error?: 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.
+	}
+}
+
+/** Move the old package-owned directory without overwriting newer data. */
+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 whenever it still exists rather than shadowing it with a
+	// different destination file that happens to share its relative name.
+	if (fs.existsSync(source)) return source;
+	const translated = path.join(getAgentStorageDirectory(), path.relative(legacyRoot, source));
+	return fs.existsSync(translated) ? translated : source;
+}
+
+function listMainSessionFiles(): string[] {
+	const sessionsRoot = path.join(getAgentDir(), "sessions");
+	if (!fs.existsSync(sessionsRoot)) return [];
+	const files: string[] = [];
+	for (const project of fs.readdirSync(sessionsRoot, { withFileTypes: true })) {
+		if (!project.isDirectory() && !project.isSymbolicLink()) continue;
+		const projectDirectory = path.join(sessionsRoot, project.name);
+		try {
+			for (const entry of fs.readdirSync(projectDirectory, { withFileTypes: true })) {
+				if (entry.isFile() && entry.name.endsWith(".jsonl")) files.push(path.join(projectDirectory, entry.name));
+			}
+		} catch {
+			// A failed directory scan makes archival unsafe.
+			throw new Error(`could not scan main session directory: ${projectDirectory}`);
+		}
+	}
+	return files;
+}
+
+function sessionFileIds(file: string): string[] {
+	const ids = new Set<string>();
+	const basename = path.basename(file);
+	const filenameMatch = basename.match(/_([0-9a-f-]{16,})\.jsonl$/i);
+	if (filenameMatch?.[1]) ids.add(filenameMatch[1]);
+	let descriptor: number | undefined;
+	try {
+		descriptor = fs.openSync(file, "r");
+		const buffer = Buffer.allocUnsafe(4096);
+		const bytesRead = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+		const firstLine = buffer.subarray(0, bytesRead).toString("utf8").split("\n", 1)[0];
+		if (firstLine) {
+			const header = JSON.parse(firstLine) as { type?: unknown; id?: unknown };
+			if (header.type === "session" && typeof header.id === "string") ids.add(header.id);
+		}
+	} catch {
+		// The filename ID remains usable for conservative reference detection.
+	} finally {
+		if (descriptor !== undefined) fs.closeSync(descriptor);
+	}
+	return [...ids];
+}
+
+function legacyFlatFiles(): Array<{ file: string; ids: string[] }> {
+	const roots = [getAgentStorageDirectory(), getLegacyAgentStorageDirectory()];
+	const files: Array<{ file: string; ids: string[] }> = [];
+	for (const root of roots) {
+		for (const kind of ["sessions", "results"] as const) {
+			const directory = path.join(root, kind);
+			if (!fs.existsSync(directory)) continue;
+			for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+				if (!entry.isFile()) continue;
+				if (kind === "sessions" && !entry.name.endsWith(".jsonl")) continue;
+				if (kind === "results" && !entry.name.endsWith(".md")) continue;
+				const file = path.join(directory, entry.name);
+				const ids = kind === "sessions"
+					? sessionFileIds(file)
+					: [path.basename(file, path.extname(file))];
+				files.push({ file, ids });
+			}
+		}
+	}
+	return files;
+}
+
+function uniqueArchiveTarget(directory: string, basename: string): string {
+	let target = path.join(directory, basename);
+	let suffix = 2;
+	while (fs.existsSync(target)) {
+		const extension = path.extname(basename);
+		const stem = path.basename(basename, extension);
+		target = path.join(directory, `${stem}-${suffix}${extension}`);
+		suffix++;
+	}
+	return target;
+}
+
+/**
+ * Archive legacy flat files only after scanning every ordinary Pi session for a
+ * persisted agent-state reference. Any scan failure leaves all candidates in place.
+ */
+export async function archiveUnownedLegacyFiles(): Promise<LegacyArchiveReport> {
+	let candidates: Array<{ file: string; ids: string[] }>;
+	let mainSessions: string[];
+	try {
+		candidates = legacyFlatFiles();
+		if (candidates.length === 0) return { archivedFiles: 0, retainedFiles: 0, scannedMainSessions: 0 };
+		mainSessions = listMainSessionFiles();
+	} catch (error) {
+		return {
+			archivedFiles: 0,
+			retainedFiles: 0,
+			scannedMainSessions: 0,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+
+	const referencedIds = new Set<string>();
+	const candidateIds = new Set(candidates.flatMap((candidate) => candidate.ids));
+	let scannedMainSessions = 0;
+	try {
+		for (const sessionFile of mainSessions) {
+			const lines = createInterface({ input: fs.createReadStream(sessionFile, { encoding: "utf8" }), crlfDelay: Infinity });
+			for await (const line of lines) {
+				if (!line.includes(STATE_ENTRY_TYPE)) continue;
+				for (const id of candidateIds) {
+					if (line.includes(id)) referencedIds.add(id);
+				}
+			}
+			scannedMainSessions++;
+		}
+	} catch (error) {
+		return {
+			archivedFiles: 0,
+			retainedFiles: candidates.length,
+			scannedMainSessions,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+
+	// An unidentifiable file cannot be proven unowned and must remain untouched.
+	const unowned = candidates.filter((candidate) => candidate.ids.length > 0 && !candidate.ids.some((id) => referencedIds.has(id)));
+	if (unowned.length === 0) {
+		return { archivedFiles: 0, retainedFiles: candidates.length, scannedMainSessions };
+	}
+	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+	const archiveDirectory = path.join(getAgentStorageDirectory(), "archive", "legacy-unowned", stamp);
+	let archivedFiles = 0;
+	try {
+		for (const candidate of unowned) {
+			const kind = candidate.file.endsWith(".jsonl") ? "sessions" : "results";
+			const destinationDirectory = path.join(archiveDirectory, kind);
+			fs.mkdirSync(destinationDirectory, { recursive: true });
+			fs.renameSync(candidate.file, uniqueArchiveTarget(destinationDirectory, path.basename(candidate.file)));
+			archivedFiles++;
+		}
+	} catch (error) {
+		return {
+			archivedFiles,
+			retainedFiles: candidates.length - archivedFiles,
+			scannedMainSessions,
+			archiveDirectory,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+	return {
+		archivedFiles,
+		retainedFiles: candidates.length - archivedFiles,
+		scannedMainSessions,
+		archiveDirectory,
+	};
+}

package/tools.ts

@@ -200,7 +200,7 @@ export function createCollaborationTools(control: AgentControl): ToolDefinition[
 			const outcome = await control.waitForMailbox(ctx, params.timeout_ms, signal);
 			if (outcome.aborted) throw new Error("wait_agent was aborted");
 			const notices = control.drainPendingMail(sender);
-			const agents = control.list(ctx);
+			const agents = control.list(ctx, sender).filter((agent) => agent.path !== sender);
 			const text = notices.length > 0
 				? `Mailbox activity received:\n\n${notices.join("\n\n")}`
 				: outcome.timedOut

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;