@oh-my-pi/pi-coding-agent 17.2.8 → 17.2.10

package/src/index.ts

@@ -2,12 +2,12 @@ import { HookEditorComponent, HookInputComponent, HookSelectorComponent } from "
 
 // Core session management
 
+export * as zod from "@oh-my-pi/omptype/zod";
+export { z } from "@oh-my-pi/omptype/zod";
 // Re-export TUI components for custom tool rendering
 export { Container, Markdown, Spacer, Text } from "@oh-my-pi/pi-tui";
 // Logging
 export { getAgentDir, logger, VERSION } from "@oh-my-pi/pi-utils";
-export * as zod from "zod/v4";
-export { z } from "zod/v4";
 export * from "./config/keybindings";
 export * from "./config/model-registry";
 // Prompt templates

package/src/internal-urls/memory-protocol.ts

@@ -222,6 +222,18 @@ function mnemopiSessionStatesFromRegistry(): MnemopiSessionState[] {
 	return states;
 }
 
+function memoryBackendFromContext(context?: ResolveContext): string | undefined {
+	if (!context?.settings || typeof context.settings !== "object") return undefined;
+	try {
+		const get = Reflect.get(context.settings, "get");
+		if (typeof get !== "function") return undefined;
+		const backend = Reflect.apply(get, context.settings, ["memory.backend"]);
+		return typeof backend === "string" ? backend : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /**
  * Look up a mnemopi memory row by id across every live session's scoped banks.
  * First hit wins; returns `null` when the id is not stored anywhere in scope.
@@ -278,6 +290,10 @@ export class MemoryProtocolHandler implements ProtocolHandler {
 	readonly immutable = true;
 
 	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
+		const backend = memoryBackendFromContext(context);
+		if (backend === "off") {
+			throw new Error("Unknown protocol: memory://");
+		}
 		const namespace = url.rawHost || url.hostname;
 		if (!namespace) {
 			throw new Error("memory:// URL requires a namespace: memory://root or memory://<memory-id>");
@@ -290,6 +306,23 @@ export class MemoryProtocolHandler implements ProtocolHandler {
 		// clipped recall preview before overwriting it (issue #4443).
 		if (namespace !== MEMORY_NAMESPACE) {
 			const mnemopiStates = mnemopiSessionStatesFromRegistry();
+			const hindsightActive =
+				backend === "hindsight" ||
+				(mnemopiStates.length === 0 &&
+					AgentRegistry.global()
+						.list()
+						.some(ref => ref.session?.getHindsightSessionState?.()));
+			if (hindsightActive) {
+				// Hindsight keeps memories server-side and exposes no
+				// `memory://<id>` addressing, yet the shared `recall` tool
+				// description still steers a follow-up `read memory://<id>`.
+				// Return a corrective pointer so that stray read self-corrects in
+				// one turn instead of derailing on the generic namespace error
+				// (issue #7587).
+				throw new Error(
+					"Hindsight memories are not addressable via memory://. Recall results are final — use `recall` to search or `reflect` to synthesize. `read memory://<id>` is only available with memory.backend=mnemopi.",
+				);
+			}
 			if (mnemopiStates.length === 0) {
 				throw new Error(
 					`Unknown memory namespace: ${namespace}. Supported: ${MEMORY_NAMESPACE} (file-backed memory summary), or a mnemopi memory id when memory.backend=mnemopi is active.`,

package/src/launch/terminal-output.ts

@@ -1,5 +1,5 @@
 import { logger } from "@oh-my-pi/pi-utils";
-import xterm, { type Terminal as XtermTerminal } from "@xterm/headless";
+import xterm, { type Terminal as XtermTerminal } from "@oh-my-pi/pi-utils/vterm";
 import { readTerminalRows } from "../tools/terminal-output";
 import { DAEMON_PTY_COLUMNS, DAEMON_PTY_ROWS } from "./protocol";
 

package/src/lsp/client.ts

@@ -17,7 +17,7 @@ import type {
 	ServerConfig,
 	WorkspaceEdit,
 } from "./types";
-import { detectLanguageId, fileToUri } from "./utils";
+import { detectLanguageId, EquivalentUriMap, fileToUri } from "./utils";
 
 // =============================================================================
 // Client State
@@ -787,7 +787,7 @@ export async function getOrCreateClient(
 			proc,
 			config,
 			requestId: 0,
-			diagnostics: new Map(),
+			diagnostics: new EquivalentUriMap(),
 			diagnosticsVersion: 0,
 			dynamicCapabilityRegistrations: new Map(),
 			openFiles: new Map(),

package/src/lsp/utils.ts

@@ -78,6 +78,35 @@ function laxUriToFile(uri: string): string {
 	return filePath;
 }
 
+/** Map that treats equivalent file URI spellings as the same key. */
+export class EquivalentUriMap<Value> extends Map<string, Value> {
+	#key(uri: string): string {
+		if (!uri.startsWith("file://")) return uri;
+		const filePath = path.normalize(uriToFile(uri));
+		return process.platform === "win32" ? filePath.toLowerCase() : filePath;
+	}
+
+	override delete(uri: string): boolean {
+		const key = this.#key(uri);
+		return super.delete(key);
+	}
+
+	override get(uri: string): Value | undefined {
+		const key = this.#key(uri);
+		return super.get(key);
+	}
+
+	override has(uri: string): boolean {
+		const key = this.#key(uri);
+		return super.has(key);
+	}
+
+	override set(uri: string, value: Value): this {
+		const key = this.#key(uri);
+		return super.set(key, value);
+	}
+}
+
 // =============================================================================
 // Diagnostic Formatting
 // =============================================================================

package/src/main.ts

@@ -21,7 +21,7 @@ import {
 	setProjectDir,
 	VERSION,
 } from "@oh-my-pi/pi-utils";
-import chalk from "chalk";
+import chalk from "@oh-my-pi/pi-utils/chalk";
 import { reset as resetCapabilities } from "./capability";
 import { type Args, reportUnrecognizedFlags } from "./cli/args";
 import { applyExtensionFlags, type ExtensionFlagSink } from "./cli/extension-flags";
@@ -52,6 +52,7 @@ import {
 } from "./discovery/helpers";
 import { injectOmpExtensionCliRoots } from "./discovery/omp-extension-roots";
 import { formatExtensionLoadNotifications } from "./extensibility/extensions/load-errors";
+import { loadExtensions } from "./extensibility/extensions/loader";
 import { ExtensionRunner } from "./extensibility/extensions/runner";
 import type { ExtensionUIContext } from "./extensibility/extensions/types";
 import { scheduleMarketplaceAutoUpdate } from "./extensibility/plugins/marketplace-auto-update";
@@ -358,11 +359,31 @@ export interface AcpSessionFactoryOptions {
 	sessionDir?: string;
 	authStorage: AuthStorage;
 	modelRegistry: ModelRegistry;
-	parsedArgs: Pick<Args, "apiKey">;
+	parsedArgs: Pick<Args, "apiKey" | "trustedExtensions">;
 	rawArgs: string[];
 	createSession: (options: CreateAgentSessionOptions) => Promise<CreateAgentSessionResult>;
 }
 
+async function loadTrustedSessionExtensions(
+	options: Pick<CreateAgentSessionOptions, "additionalExtensionPaths">,
+	cwd: string,
+	eventBus: EventBus,
+) {
+	const paths = options.additionalExtensionPaths ?? [];
+	for (const trustedPath of paths) {
+		let stat: fsSync.Stats;
+		try {
+			stat = fsSync.statSync(trustedPath);
+		} catch {
+			throw new Error(`Trusted extension must be an existing module file: ${trustedPath}`);
+		}
+		if (!stat.isFile()) {
+			throw new Error(`Trusted extension must be a module file, not a directory: ${trustedPath}`);
+		}
+	}
+	return loadExtensions(paths, cwd, eventBus);
+}
+
 /**
  * Build the per-`session/new` factory used by ACP mode.
  *
@@ -385,6 +406,16 @@ export function createAcpSessionFactory(args: AcpSessionFactoryOptions): AcpSess
 		// policy (PR #3736 follow-up).
 		const titleSystemPromptSource = discoverTitleSystemPromptFile(cwd);
 		const titleSystemPrompt = await resolvePromptInput(titleSystemPromptSource, "title system prompt");
+		const eventBus = new EventBus();
+		const trustedExtensions =
+			args.parsedArgs.trustedExtensions && args.parsedArgs.trustedExtensions.length > 0
+				? await loadTrustedSessionExtensions(args.baseOptions, cwd, eventBus)
+				: undefined;
+		if (trustedExtensions && trustedExtensions.errors.length > 0) {
+			throw new Error(
+				`Trusted extension failed to load: ${trustedExtensions.errors.map(item => item.error).join("; ")}`,
+			);
+		}
 		const { session: nextSession } = await args.createSession({
 			...args.baseOptions,
 			cwd,
@@ -398,6 +429,8 @@ export function createAcpSessionFactory(args: AcpSessionFactoryOptions): AcpSess
 			deferUsageReserveConfirmation: true,
 			enableMCP: false,
 			titleSystemPrompt,
+			eventBus,
+			preloadedExtensions: trustedExtensions,
 		});
 		if (args.parsedArgs.apiKey && !args.baseOptions.model && nextSession.model) {
 			args.authStorage.setRuntimeApiKey(nextSession.model.provider, args.parsedArgs.apiKey);
@@ -1114,14 +1147,34 @@ export async function buildSessionOptions(
 		options.rules = [];
 	}
 
-	// Additional extension paths from CLI
-	const cliExtensionPaths = [...(parsed.extensions ?? []), ...(parsed.hooks ?? [])];
-	if (cliExtensionPaths.length > 0) {
-		options.additionalExtensionPaths = cliExtensionPaths;
-	}
-
-	if (parsed.noExtensions) {
+	// Trusted extension paths are an exact allowlist for extension modules.
+	if (parsed.trustedExtensions && parsed.trustedExtensions.length > 0) {
+		const trustedPaths = parsed.trustedExtensions.map(trustedPath => {
+			let resolvedPath: string;
+			let stat: fsSync.Stats;
+			try {
+				resolvedPath = fsSync.realpathSync.native(trustedPath);
+				stat = fsSync.statSync(resolvedPath);
+			} catch {
+				throw new Error(`Trusted extension must be an existing module file: ${trustedPath}`);
+			}
+			if (!stat.isFile()) {
+				throw new Error(`Trusted extension must be a module file, not a directory: ${trustedPath}`);
+			}
+			return resolvedPath;
+		});
 		options.disableExtensionDiscovery = true;
+		options.additionalExtensionPaths = trustedPaths;
+	} else {
+		// Additional extension paths from CLI
+		const cliExtensionPaths = [...(parsed.extensions ?? []), ...(parsed.hooks ?? [])];
+		if (cliExtensionPaths.length > 0) {
+			options.additionalExtensionPaths = cliExtensionPaths;
+		}
+
+		if (parsed.noExtensions) {
+			options.disableExtensionDiscovery = true;
+		}
 	}
 
 	return options;
@@ -1194,16 +1247,20 @@ export async function runRootCommand(
 	// warning before we reach the await site below.
 	pluginPreloadPromise.catch(() => {});
 
-	// Register CLI-provided extension package paths (`--extension`, `--hook`) so
-	// the `omp-plugins` discovery provider can surface their `skills/`, `hooks/`,
-	// `tools/`, `commands/`, `rules/`, `prompts/`, and `.mcp.json` sub-trees.
-	// Explicit roots remain authorized under `--no-extensions`; only ambient
-	// extension discovery is disabled.
-	const cliExtensions = [...(parsedArgs.extensions ?? []), ...(parsedArgs.hooks ?? [])];
-	injectOmpExtensionCliRoots(cliExtensions, home, getProjectDir(), {
-		mode: parsedArgs.noExtensions ? "explicit-only" : "merge",
-		replace: true,
-	});
+	// Trusted files load as exact module paths, never as package roots whose
+	// sibling hooks/tools/commands/MCP content could be discovered implicitly.
+	if (!parsedArgs.trustedExtensions?.length) {
+		// Register CLI-provided extension package paths (`--extension`, `--hook`) so
+		// the `omp-plugins` discovery provider can surface their `skills/`, `hooks/`,
+		// `tools/`, `commands/`, `rules/`, `prompts/`, and `.mcp.json` sub-trees.
+		// Explicit roots remain authorized under `--no-extensions`; only ambient
+		// extension discovery is disabled.
+		const cliExtensions = [...(parsedArgs.extensions ?? []), ...(parsedArgs.hooks ?? [])];
+		injectOmpExtensionCliRoots(cliExtensions, home, getProjectDir(), {
+			mode: parsedArgs.noExtensions ? "explicit-only" : "merge",
+			replace: true,
+		});
+	}
 
 	let cwd = getProjectDir();
 	// Classify the host before opening auth or settings storage so every
@@ -1542,12 +1599,14 @@ export async function runRootCommand(
 		// string-flag value such as `--target @notes.md` is the flag's value, not a
 		// file — and the same result is handed to createAgentSession via
 		// `preloadedExtensions` so the discovery work is not repeated.
-		if (isInteractive) {
+		if (isInteractive && !parsedArgs.trustedExtensions?.length) {
 			sessionOptions.extensions = [...(sessionOptions.extensions ?? []), createWarpEventBridgeExtension()];
 		}
 
 		const eventBus = new EventBus();
-		const extensionsResult = await loadSessionExtensions(sessionOptions, cwd, settingsInstance, eventBus);
+		const extensionsResult = parsedArgs.trustedExtensions?.length
+			? await loadTrustedSessionExtensions(sessionOptions, cwd, eventBus)
+			: await loadSessionExtensions(sessionOptions, cwd, settingsInstance, eventBus);
 		const extensionFlagSink: ExtensionFlagSink = {
 			getFlags: () => ExtensionRunner.aggregateFlags(extensionsResult.extensions),
 			setFlagValue: (name, value) => {
@@ -1556,6 +1615,11 @@ export async function runRootCommand(
 		};
 		const initialArgs = applyExtensionFlags(extensionFlagSink, rawArgs) ?? parsedArgs;
 		normalizeContinueSessionArgs(initialArgs, rawArgs);
+		if ((parsedArgs.trustedExtensions?.length ?? 0) > 0 && extensionsResult.errors.length > 0) {
+			throw new Error(
+				`Trusted extension failed to load: ${extensionsResult.errors.map(item => item.error).join("; ")}`,
+			);
+		}
 		for (const message of formatExtensionLoadNotifications(extensionsResult.errors)) {
 			if (isInteractive) {
 				notifs.push({ kind: "warn", message });

package/src/markit/converters/docx.ts

@@ -1,6 +1,6 @@
 // Adapted from markit-ai (MIT). See ../NOTICE.
 import * as path from "node:path";
-import mammoth from "mammoth";
+import mammoth from "@oh-my-pi/pi-utils/docx";
 import { createTurndown, normalizeTablesHtml } from "../../utils/turndown";
 import type { ConversionResult, Converter, StreamInfo } from "../types";
 

package/src/markit/converters/epub.ts

@@ -1,5 +1,5 @@
 // Adapted from markit-ai (MIT). See ../NOTICE.
-import { XMLParser } from "fast-xml-parser";
+import { XMLParser } from "@oh-my-pi/pi-utils/xml";
 import { createTurndown, normalizeTablesHtml } from "../../utils/turndown";
 import { unzip, unzipText } from "../../utils/zip";
 import type { ConversionResult, Converter, StreamInfo } from "../types";

package/src/markit/converters/pptx.ts

@@ -1,6 +1,6 @@
 // Adapted from markit-ai (MIT). See ../NOTICE.
 import * as path from "node:path";
-import { XMLParser } from "fast-xml-parser";
+import { XMLParser } from "@oh-my-pi/pi-utils/xml";
 import { unzip, unzipText } from "../../utils/zip";
 import type { ConversionResult, Converter, StreamInfo } from "../types";
 

package/src/markit/converters/xlsx.ts

@@ -1,5 +1,5 @@
 // Adapted from markit-ai (MIT). See ../NOTICE.
-import { XMLParser } from "fast-xml-parser";
+import { XMLParser } from "@oh-my-pi/pi-utils/xml";
 import { unzip, unzipText } from "../../utils/zip";
 import type { ConversionResult, Converter, StreamInfo } from "../types";
 

package/src/modes/acp/acp-agent.ts

@@ -1,5 +1,8 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { AssistantMessage, Model } from "@oh-my-pi/pi-ai";
+import { getBlobsDir, isEnoent, logger, type postmortem, VERSION } from "@oh-my-pi/pi-utils";
 import {
 	type Agent,
 	type AgentSideConnection,
@@ -39,10 +42,7 @@ import {
 	type SetSessionModeRequest,
 	type SetSessionModeResponse,
 	type Usage,
-} from "@agentclientprotocol/sdk";
-import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
-import type { AssistantMessage, Model } from "@oh-my-pi/pi-ai";
-import { getBlobsDir, isEnoent, logger, type postmortem, VERSION } from "@oh-my-pi/pi-utils";
+} from "@oh-my-pi/pi-utils/acp";
 import { disableProvider, enableProvider, reset as resetCapabilities } from "../../capability";
 import { Settings } from "../../config/settings";
 import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../../discovery/helpers";
@@ -2312,7 +2312,7 @@ export class AcpAgent implements Agent {
 			this.#clientCapabilities,
 		);
 		if (this.#clientCapabilities?.elicitation?.form != null) {
-			record.session.setUsageFallbackConfirmer(confirmation => {
+			record.session.setUsageFallbackConfirmer((confirmation, signal) => {
 				const reserve =
 					confirmation.remainingPercent === undefined
 						? "inside the configured reserve margin"
@@ -2320,6 +2320,7 @@ export class AcpAgent implements Agent {
 				return uiContext.confirm(
 					"Coding-plan reserve reached",
 					`${confirmation.from} has ${reserve}. Switch to ${confirmation.to}? Choose No to keep using the current plan.`,
+					{ signal },
 				);
 			});
 		}
@@ -2347,7 +2348,7 @@ export class AcpAgent implements Agent {
 					record.session.sessionManager.appendLabelChange(targetId, label);
 				},
 				getActiveTools: () => record.session.getEnabledToolNames(),
-				getAllTools: () => record.session.getAllToolNames(),
+				getAllTools: () => record.session.getAllToolInfos(),
 				setActiveTools: toolNames => record.session.setActiveToolsByName(toolNames),
 				getCommands: () => getSessionSlashCommands(record.session),
 				setModel: async model => {

package/src/modes/acp/acp-client-bridge.ts

@@ -11,7 +11,7 @@ import type {
 	ClientCapabilities,
 	RequestPermissionRequest,
 	ToolCallUpdate,
-} from "@agentclientprotocol/sdk";
+} from "@oh-my-pi/pi-utils/acp";
 import type {
 	ClientBridge,
 	ClientBridgeCapabilities,

package/src/modes/acp/acp-event-mapper.ts

@@ -5,7 +5,7 @@ import type {
 	ToolCallContent,
 	ToolCallLocation,
 	ToolKind,
-} from "@agentclientprotocol/sdk";
+} from "@oh-my-pi/pi-utils/acp";
 import { parseXdUrl } from "../../internal-urls/xd-protocol";
 import type { AgentSessionEvent } from "../../session/agent-session";
 import { resolveToCwd } from "../../tools/path-utils";

package/src/modes/acp/acp-mode.ts

@@ -1,6 +1,6 @@
 import * as stream from "node:stream";
-import { AgentSideConnection, ndJsonStream, type Stream } from "@agentclientprotocol/sdk";
 import { postmortem } from "@oh-my-pi/pi-utils";
+import { AgentSideConnection, ndJsonStream, type Stream } from "@oh-my-pi/pi-utils/acp";
 import type { AgentSession } from "../../session/agent-session";
 import { AcpAgent } from "./acp-agent";
 

package/src/modes/components/agent-hub-projection.ts

@@ -0,0 +1,248 @@
+import type { AgentMetricsSummary, AgentRef, AgentStatus } from "../../registry/agent-registry";
+import { MAIN_AGENT_ID } from "../../registry/agent-registry";
+import type { ObservableSession } from "../session-observer-registry";
+
+export type AgentMetrics = AgentMetricsSummary;
+
+export interface AggregateMetrics extends AgentMetrics {
+	reportedAgents: number;
+	/** Rows whose duration is an observer-measured active runtime. */
+	activeDurationAgents: number;
+}
+
+export interface AgentTreeProjection {
+	rows: AgentRef[];
+	depthById: Map<string, number>;
+	parentById: Map<string, string>;
+	lastSiblingById: Map<string, boolean>;
+}
+
+export const STATUS_ORDER: Record<AgentStatus, number> = { running: 0, idle: 1, parked: 2, aborted: 3 };
+
+function finiteMetric(value: number | undefined): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/** Exact observer usage for one roster entry. */
+export function progressMetrics(observed: ObservableSession | undefined): AgentMetrics | undefined {
+	const progress = observed?.progress;
+	if (!progress) return undefined;
+	const { tokens, requests, toolCount: tools, cost, durationMs } = progress;
+	if (
+		typeof tokens !== "number" ||
+		!Number.isFinite(tokens) ||
+		typeof requests !== "number" ||
+		!Number.isFinite(requests) ||
+		typeof tools !== "number" ||
+		!Number.isFinite(tools) ||
+		typeof cost !== "number" ||
+		!Number.isFinite(cost) ||
+		typeof durationMs !== "number" ||
+		!Number.isFinite(durationMs)
+	) {
+		return undefined;
+	}
+	return {
+		tokens,
+		requests,
+		tools,
+		cost,
+		durationMs,
+		durationKind: "active",
+		contextTokens:
+			typeof progress.contextTokens === "number" && Number.isFinite(progress.contextTokens)
+				? progress.contextTokens
+				: undefined,
+		contextWindow:
+			typeof progress.contextWindow === "number" && Number.isFinite(progress.contextWindow)
+				? progress.contextWindow
+				: undefined,
+	};
+}
+
+/**
+ * Read direct assistant usage from a live session. SessionStats also includes
+ * usage embedded in completed `task` tool results, so using it for a parent
+ * row would double-count child rows in the aggregate.
+ */
+export function readSessionMetrics(session: NonNullable<AgentRef["session"]>): AgentMetrics | undefined {
+	try {
+		const stats = session.getSessionStats();
+		const messages = session.agent?.state?.messages;
+		if (!Array.isArray(messages)) {
+			return {
+				tokens: stats.tokens.input + stats.tokens.output + stats.tokens.cacheWrite,
+				requests: stats.assistantMessages,
+				tools: stats.toolCalls,
+				cost: stats.cost,
+				durationMs: 0,
+				durationKind: "unknown",
+				contextTokens: stats.contextUsage?.tokens,
+				contextWindow: stats.contextUsage?.contextWindow,
+			};
+		}
+
+		let tokens = 0;
+		let requests = 0;
+		let tools = 0;
+		let cost = 0;
+		for (const message of messages) {
+			if (message.role !== "assistant") continue;
+			requests++;
+			tokens += message.usage.input + message.usage.output + message.usage.cacheWrite;
+			tools += message.content.filter(content => content.type === "toolCall").length;
+			cost += message.usage.cost.total;
+		}
+		return {
+			tokens,
+			requests,
+			tools,
+			cost,
+			durationMs: 0,
+			durationKind: "unknown",
+			contextTokens: stats.contextUsage?.tokens,
+			contextWindow: stats.contextUsage?.contextWindow,
+		};
+	} catch {
+		// Render-only doubles and sessions being torn down may not expose a
+		// complete statistics host. Missing metrics are preferable to a broken hub.
+		return undefined;
+	}
+}
+
+export function aggregateMetrics(args: {
+	rows: readonly AgentRef[];
+	observedById: ReadonlyMap<string, ObservableSession>;
+	metricsFor: (ref: AgentRef, observed: ObservableSession | undefined) => AgentMetrics | undefined;
+	fallbackStatsSession: (
+		ref: AgentRef,
+		observed: ObservableSession | undefined,
+	) => NonNullable<AgentRef["session"]> | undefined;
+	sessionMetrics: WeakMap<object, { metrics: AgentMetrics | undefined }>;
+	refreshFallback: boolean;
+}): { metrics: AggregateMetrics; hasFallbackLiveSessions: boolean } {
+	const total: AggregateMetrics = {
+		tokens: 0,
+		requests: 0,
+		tools: 0,
+		cost: 0,
+		durationMs: 0,
+		durationKind: "active",
+		reportedAgents: 0,
+		activeDurationAgents: 0,
+	};
+	let hasFallbackLiveSessions = false;
+	const countedFallbackSessions = new Set<NonNullable<AgentRef["session"]>>();
+	for (const ref of args.rows) {
+		const observed = args.observedById.get(ref.id);
+		const fallbackSession = args.fallbackStatsSession(ref, observed);
+		if (fallbackSession) {
+			hasFallbackLiveSessions = true;
+			if (args.refreshFallback || !args.sessionMetrics.has(fallbackSession)) {
+				args.sessionMetrics.set(fallbackSession, { metrics: readSessionMetrics(fallbackSession) });
+			}
+		}
+		const metrics = args.metricsFor(ref, observed);
+		if (!metrics || (fallbackSession && countedFallbackSessions.has(fallbackSession))) continue;
+		if (fallbackSession) countedFallbackSessions.add(fallbackSession);
+		total.reportedAgents++;
+		total.tokens += finiteMetric(metrics.tokens);
+		total.requests += finiteMetric(metrics.requests);
+		total.tools += finiteMetric(metrics.tools);
+		total.cost += finiteMetric(metrics.cost);
+		if (metrics.durationKind === "active") {
+			total.durationMs += finiteMetric(metrics.durationMs);
+			total.activeDurationAgents++;
+		}
+	}
+	return { metrics: total, hasFallbackLiveSessions };
+}
+
+/** Parent-before-child projection preserving the roster's stable sibling order. */
+export function projectAgentTree(refs: readonly AgentRef[]): AgentTreeProjection {
+	const ids = new Set<string>();
+	const operationalIndex = new Map<string, number>();
+	for (let i = 0; i < refs.length; i++) {
+		ids.add(refs[i].id);
+		operationalIndex.set(refs[i].id, i);
+	}
+
+	const parentById = new Map<string, string>();
+	const children = new Map<string, AgentRef[]>();
+	for (const ref of refs) {
+		const parent =
+			ref.parentId && ref.parentId !== MAIN_AGENT_ID && ids.has(ref.parentId) ? ref.parentId : MAIN_AGENT_ID;
+		parentById.set(ref.id, parent);
+		const siblings = children.get(parent);
+		if (siblings) siblings.push(ref);
+		else children.set(parent, [ref]);
+	}
+
+	// A tree group occupies the position of its earliest operational row.
+	// Compute subtree minima iteratively so pathological lineage depth remains stack-safe.
+	const subtreeOrder = new Map<string, number>();
+	const visiting = new Set<string>();
+	const ranked = new Set<string>();
+	for (const start of refs) {
+		if (ranked.has(start.id)) continue;
+		const stack: Array<{ ref: AgentRef; expanded: boolean }> = [{ ref: start, expanded: false }];
+		while (stack.length > 0) {
+			const current = stack.pop();
+			if (!current) continue;
+			if (current.expanded) {
+				let order = operationalIndex.get(current.ref.id) ?? Number.MAX_SAFE_INTEGER;
+				for (const child of children.get(current.ref.id) ?? []) {
+					order = Math.min(order, subtreeOrder.get(child.id) ?? Number.MAX_SAFE_INTEGER);
+				}
+				subtreeOrder.set(current.ref.id, order);
+				visiting.delete(current.ref.id);
+				ranked.add(current.ref.id);
+				continue;
+			}
+			if (ranked.has(current.ref.id) || visiting.has(current.ref.id)) continue;
+			visiting.add(current.ref.id);
+			stack.push({ ref: current.ref, expanded: true });
+			const descendants = children.get(current.ref.id);
+			if (!descendants) continue;
+			for (let i = descendants.length - 1; i >= 0; i--) {
+				const child = descendants[i];
+				if (!ranked.has(child.id) && !visiting.has(child.id)) stack.push({ ref: child, expanded: false });
+			}
+		}
+	}
+	for (const siblings of children.values()) {
+		siblings.sort(
+			(a, b) =>
+				(subtreeOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (subtreeOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER) ||
+				(operationalIndex.get(a.id) ?? Number.MAX_SAFE_INTEGER) -
+					(operationalIndex.get(b.id) ?? Number.MAX_SAFE_INTEGER),
+		);
+	}
+
+	const lastSiblingById = new Map<string, boolean>();
+	for (const siblings of children.values()) {
+		for (let i = 0; i < siblings.length; i++) lastSiblingById.set(siblings[i].id, i === siblings.length - 1);
+	}
+
+	const rows: AgentRef[] = [];
+	const visited = new Set<string>();
+	const depthById = new Map<string, number>();
+	const visit = (root: AgentRef, rootDepth: number): void => {
+		const stack: Array<{ ref: AgentRef; depth: number }> = [{ ref: root, depth: rootDepth }];
+		while (stack.length > 0) {
+			const current = stack.pop();
+			if (!current || visited.has(current.ref.id)) continue;
+			visited.add(current.ref.id);
+			depthById.set(current.ref.id, current.depth);
+			rows.push(current.ref);
+			const descendants = children.get(current.ref.id);
+			if (!descendants) continue;
+			for (let i = descendants.length - 1; i >= 0; i--)
+				stack.push({ ref: descendants[i], depth: current.depth + 1 });
+		}
+	};
+	for (const root of children.get(MAIN_AGENT_ID) ?? []) visit(root, 0);
+	// Corrupt persisted parent cycles remain visible as roots instead of disappearing.
+	for (const ref of refs) visit(ref, 0);
+	return { rows, depthById, parentById, lastSiblingById };
+}