pi-legion 0.16.0 → 2.0.0

package/index.ts

@@ -16,9 +16,12 @@ import type { AgentToolResult, AgentToolUpdateCallback } from "@earendil-works/p
 import type {
 	ExtensionAPI,
 	ExtensionContext,
+	ExtensionUIContext,
 } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
-import { createHerdrClient } from "./src/herdr/client.ts";
+import { RpcSupervisor } from "./src/supervisor/rpc-supervisor.ts";
+import type { LegionSupervisor } from "./src/supervisor/types.ts";
+import { InMemoryUIProxy, type UIProxy } from "./src/supervisor/ui-proxy.ts";
 import { discoverAgents, findAgent, formatAgentRoster, BUILTIN_AGENTS_DIR } from "./src/agents/agents.ts";
 import {
 	applyAgentOverrides,
@@ -28,6 +31,7 @@ import {
 import {
 	applyTeam,
 	DEFAULT_TEAM,
+	TEAM_ENV,
 	type ActiveTeam,
 } from "./src/agents/teams.ts";
 import { resolveModel } from "./src/agents/model-resolution.ts";
@@ -37,39 +41,53 @@ import {
 	loadSubagentSettings,
 	resolveSubagentSettings,
 } from "./src/agents/settings.ts";
-import { createSessionRuntime, type SessionRuntime, shouldRecycleAfterCollect, type WaitResult } from "./src/extension/runtime.ts";
+import { createSessionRuntime, renderLiveChildStatus, type SessionRuntime, type TrackedJob, shouldRecycleAfterCollect, type WaitResult } from "./src/extension/runtime.ts";
+import { createDbEventSource, createLegionEventBus, type DbEventSource, type LegionEventBus } from "./src/extension/event-bus.ts";
+import { LegionPostman, registerLegionTools, type LegionMailCommand } from "./src/extension/legion-tools.ts";
+import { LEGION_DB_ENV, LEGION_NODE_ID_ENV } from "./src/runs/args.ts";
+import type { VerifyRunner } from "./src/runs/acceptance.ts";
+import { legionDbPath, openLegionDb, type DatabaseSync } from "./src/legion/db.ts";
+import { appendEvent } from "./src/legion/events.ts";
+import { attachUsageTotals, upsertUsage } from "./src/legion/usage.ts";
+import { getChildByName, getChildren, getNode, getSubtree, insertNode, type LegionNode, updateNode } from "./src/legion/nodes.ts";
+import { DEFAULT_LEGION_SETTINGS, type LegionSettings } from "./src/shared/types.ts";
+import { parseNestedPathEnv } from "./src/shared/nested-path.ts";
+import { allocateSiblingNames, makeName } from "./src/shared/name.ts";
+import { deriveOutcome, isLastTurnComplete, parseSessionFile } from "./src/shared/session.ts";
+import { restoreHostNodeOptions } from "./src/supervisor/child-memory.ts";
+import { setVerifyQueueListener } from "./src/runs/verify-queue.ts";
+import { applyEventRetention, checkpoint, formatHygieneReport, hygieneEnabled, runStartupHygiene } from "./src/runs/hygiene.ts";
+import {
+	createStatusNodeOpener,
+	publishSupervisorEvent,
+	publishUIRequest,
+	registerLegionCommand,
+	type RpcEventSource,
+	confirmAndStopNode,
+} from "./src/extension/legion-commands.ts";
+import { createIdleEscStop, liveJobs } from "./src/extension/legion-stop.ts";
 import { DEFAULT_FLUSH_MS, DEFAULT_JOIN_MODE } from "./src/extension/join.ts";
 import { registerChildGuard } from "./src/extension/child-guard.ts";
+import { registerScoutGuard } from "./src/extension/scout-guard.ts";
 import { ALLOW_NESTED_ENV } from "./src/extension/budget.ts";
 import {
 	applyOnBlockedPolicy,
 	followUpFor,
 } from "./src/extension/blocked.ts";
 import { formatAlreadyRecycled } from "./src/extension/recycle.ts";
-import { ParentPaneLabeler } from "./src/extension/parent-label.ts";
 import {
 	SUBAGENT_NOTIFY_TYPE,
 } from "./src/extension/notify.ts";
 import { renderSubagentNotice } from "./src/extension/notice-renderer.ts";
-import {
-	registerProfileCommands,
-	registerAgentsCommand,
-	registerTeamCommand,
-	registerToggleCommand,
-} from "./src/extension/slash.ts";
-import { registerSummaryCommand } from "./src/extension/summary.ts";
-import {
-	blockMessage,
-	forbiddenDispatchReason,
-	PARENT_PLAYBOOK,
-	TOOL_DESCRIPTION,
-} from "./src/extension/playbook.ts";
+import { PARENT_PLAYBOOK, TOOL_DESCRIPTION } from "./src/extension/playbook.ts";
 import { getAgentDir } from "./src/agents/paths.ts";
-import { Orchestrator } from "./src/runs/orchestrator.ts";
+import { expectedModelsFromSettings, runLegionDoctor } from "./src/extension/legion-doctor.ts";
+import { readFileSync } from "node:fs";
 import {
-	createSessionLayout,
-	type SessionLayout,
-} from "./src/runs/layout.ts";
+	effectiveMaxDepth,
+	Orchestrator,
+	type OrchestratorLegionContext,
+} from "./src/runs/orchestrator.ts";
 import { RunStore, pickChildByName } from "./src/runs/store.ts";
 import { resolveLaunchWorktree } from "./src/runs/worktree.ts";
 import {
@@ -78,22 +96,18 @@ import {
 	DEFAULTS,
 	DEFAULT_ON_BLOCKED,
 	ErrorCodes,
-	type HerdrClient,
 	type ModelOrigin,
-	type Placement,
 	SubagentError,
 } from "./src/shared/types.ts";
 
+// The parent turn owns its child lifetime. Parallel tool aborts in one turn
+// share this graceful-retire cascade; turn_start begins a fresh cycle.
+let cascadePromise: Promise<void> | undefined;
+
 // ---------------------------------------------------------------------------
 // Parameters
 // ---------------------------------------------------------------------------
 
-const PlacementSchema = Type.Union([
-	Type.Literal("split-down"),
-	Type.Literal("split-right"),
-	Type.Literal("new-tab"),
-]);
-
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate" }),
@@ -108,6 +122,12 @@ const TaskItem = Type.Object({
 				"Parent decides isolation for this child. true = own git branch, child opens an MR. false = write the current checkout.",
 		}),
 	),
+	verify: Type.Optional(
+		Type.Array(Type.String(), {
+			description:
+				"Commands the extension runs itself in the child worktree at collect time; first non-zero exit rejects the verdict.",
+		}),
+	),
 });
 
 const SubagentParams = Type.Object({
@@ -123,8 +143,10 @@ const SubagentParams = Type.Object({
 				Type.Literal("collect"),
 				Type.Literal("list"),
 				Type.Literal("wait"),
+				Type.Literal("stop"),
+				Type.Literal("diagnose"),
 			],
-			{ description: "Defaults to launch." },
+			{ description: "Defaults to launch. diagnose = Legion doctor full self-check (extensions/models/spawn/memory/tools/storage/runtime)." },
 		),
 	),
 	agent: Type.Optional(
@@ -146,13 +168,18 @@ const SubagentParams = Type.Object({
 		Type.String({ description: "Named kind+model+thinking preset" }),
 	),
 	cwd: Type.Optional(Type.String()),
-	placement: Type.Optional(PlacementSchema),
 	worktree: Type.Optional(
 		Type.Boolean({
 			description:
 				"Parent decides isolation. true = isolated git branch, child opens an MR. false = edit the current checkout. Omit to use the role default (bundled worker: true).",
 		}),
 	),
+	verify: Type.Optional(
+		Type.Array(Type.String(), {
+			description:
+			"Verification commands the extension runs itself in the child worktree at collect time (launch only). Each must exit 0; the first non-zero exit rejects the child's verdict as `rejected (verified-path)`. The worker does not need to paste test output.",
+		}),
+	),
 	agentScope: Type.Optional(
 		Type.Union(
 			[Type.Literal("user"), Type.Literal("project"), Type.Literal("both")],
@@ -162,26 +189,40 @@ const SubagentParams = Type.Object({
 		),
 	),
 	name: Type.Optional(
-		Type.String({ description: "Child handle name (control actions)" }),
+		Type.String({ description: "Child handle name (control actions, including wait and stop)" }),
 	),
 	all: Type.Optional(
 		Type.Boolean({
-			description: "wait: wait for every currently-running child in this session",
+			description: "wait: wait for active children; stop: stop every non-retired child",
 		}),
 	),
 	timeoutMs: Type.Optional(
 		Type.Number({
-			description: "wait: per-child timeout in ms (default: role turnTimeoutMs)",
+			description: "wait: per-child timeout in ms; event-driven completion returns early (default: role turnTimeoutMs)",
 		}),
 	),
 	message: Type.Optional(
 		Type.String({ description: "Text for steer/continue" }),
 	),
+	team: Type.Optional(
+		Type.String({ description: "Team to use for the launched child and its nested roster" }),
+	),
 });
 
 /** The validated tool parameters, as the model supplies them. */
 type SubagentParams = Static<typeof SubagentParams>;
 
+const VexillatioParams = Type.Object({
+	task: Type.String({ description: "Recon task: one clear question list" }),
+	agent: Type.Optional(Type.String({ description: "Utility agent name (default: scout)" })),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "Parallel recon launches" })),
+	cwd: Type.Optional(Type.String()),
+	model: Type.Optional(Type.String()),
+	timeoutMs: Type.Optional(Type.Number({ description: "Per-child wait in ms, default 600000" })),
+});
+
+const UTILITY_CHILD_ENV = "PI_SUBAGENT_UTILITY_CHILD";
+
 const blockedUi = new WeakMap<
 	SessionRuntime,
 	{
@@ -194,51 +235,495 @@ const blockedUi = new WeakMap<
 // Extension
 // ---------------------------------------------------------------------------
 
-export default function herdrSubagents(pi: ExtensionAPI) {
+export interface ExtensionSupervisorDeps {
+	supervisor?: LegionSupervisor;
+	uiProxy?: UIProxy;
+	onBudgetRefused?: NonNullable<ConstructorParameters<typeof Orchestrator>[0]["onBudgetRefused"]>;
+	/** Injected verify runner for tests; production falls back to the real shell runner. */
+	verifyRunner?: VerifyRunner;
+}
+
+interface LegionRuntimeIdentity {
+	pi: ExtensionAPI;
+	db: DatabaseSync;
+	dbPath: string;
+	runStore: RunStore;
+	nodeId: string;
+	parentNodeId: string | null;
+	parentRunId: string | null;
+	runId: string;
+	runDir: string;
+	rootRunId: string;
+	storeRootDir: string;
+	settings: LegionSettings;
+	eventBus: LegionEventBus;
+	dbEventSource: DbEventSource;
+	postman: LegionPostman;
+	childNodeId(name: string): string | undefined;
+}
+
+function settingsForLegion(settings: ReturnType<typeof loadSubagentSettings>): LegionSettings {
+	return { ...DEFAULT_LEGION_SETTINGS, ...(settings.legion ?? {}), phaseTimeouts: { ...DEFAULT_LEGION_SETTINGS.phaseTimeouts, ...(settings.legion?.phaseTimeouts ?? {}) } };
+}
+
+function runStoreFor(cwd: string): RunStore {
+	const sharedDbPath = process.env[LEGION_DB_ENV];
+	if (sharedDbPath && path.isAbsolute(sharedDbPath)) {
+		const storeRoot = path.dirname(path.dirname(path.dirname(sharedDbPath)));
+		return new RunStore({ rootDir: storeRoot });
+	}
+	return new RunStore({ rootDir: path.join(cwd, ".pi-subagents") });
+}
+
+function notice(pi: ExtensionAPI, text: string): void {
+	pi.sendMessage({ customType: SUBAGENT_NOTIFY_TYPE, content: text, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+}
+
+function createLegionRuntime(input: {
+	pi: ExtensionAPI;
+	supervisor: LegionSupervisor;
+	db: DatabaseSync;
+	dbPath: string;
+	nodeId: string;
+	rootRunId: string;
+	runDir: string;
+	cwd: string;
+	storeRootDir: string;
+	settings: LegionSettings;
+	eventBus: LegionEventBus;
+	registerTools: boolean;
+}): LegionRuntimeIdentity {
+	const self = getNode(input.db, input.nodeId);
+	const eventBus = input.eventBus;
+	const dbEventSource = createDbEventSource(input.db);
+	dbEventSource.start(eventBus);
+	const postman = new LegionPostman({
+		db: input.db,
+		nodeId: input.nodeId,
+		supervisor: input.supervisor,
+		settings: input.settings,
+		eventBus,
+		sendRootMessage: (text: string) => notice(input.pi, text),
+		sendSelfMessage: (text: string) => notice(input.pi, text),
+		resumeChild: (node: LegionNode, mail: LegionMailCommand) => resumeLegionChild({
+			pi: input.pi, supervisor: input.supervisor, db: input.db, dbPath: input.dbPath,
+			eventBus, settings: input.settings, cwd: input.cwd, storeRootDir: input.storeRootDir,
+			parentNodeId: input.nodeId, node, message: mail.text,
+		}),
+	});
+	const identity: LegionRuntimeIdentity = {
+		pi: input.pi,
+		db: input.db,
+		dbPath: input.dbPath,
+		runStore: new RunStore({ rootDir: input.storeRootDir }),
+		nodeId: input.nodeId,
+		parentNodeId: self?.parentId ?? null,
+		parentRunId: self?.parentId ? getNode(input.db, self.parentId)?.runId ?? null : null,
+		runId: self?.runId ?? input.rootRunId,
+		runDir: input.runDir,
+		rootRunId: input.rootRunId,
+		storeRootDir: input.storeRootDir,
+		settings: input.settings,
+		eventBus,
+		dbEventSource,
+		postman,
+		childNodeId: (name) => getChildByName(input.db, input.nodeId, name)?.id,
+	};
+	if (input.registerTools && input.nodeId !== "root") registerLegionTools(input.pi, { db: input.db, nodeId: input.nodeId, role: self?.role, settings: input.settings, cwd: input.cwd, runDir: input.runDir, eventBus, sendSelfMessage: (text: string) => notice(input.pi, text) });
+	postman.start();
+	return identity;
+}
+
+function resolveLegionIdentity(input: {
+	pi: ExtensionAPI;
+	supervisor: LegionSupervisor;
+	store: RunStore;
+	cwd: string;
+	settings: ReturnType<typeof loadSubagentSettings>;
+	eventBus: LegionEventBus;
+	cached?: LegionRuntimeIdentity;
+	/** This process's session file (identity credential). From ctx.sessionManager. */
+	sessionFile?: string | undefined;
+}): LegionRuntimeIdentity | undefined {
+	const dbPath = process.env[LEGION_DB_ENV];
+	const nodeId = process.env[LEGION_NODE_ID_ENV];
+	if (Boolean(dbPath) !== Boolean(nodeId)) throw new Error("PI_LEGION_DB and PI_LEGION_NODE_ID must be set together");
+	if (dbPath && nodeId) {
+		if (!path.isAbsolute(dbPath)) throw new Error("PI_LEGION_DB must be an absolute path");
+		if (input.cached?.dbPath === path.resolve(dbPath) && input.cached.nodeId === nodeId) return input.cached;
+		const absoluteDbPath = path.resolve(dbPath);
+		const db = openLegionDb(absoluteDbPath);
+		const node = getNode(db, nodeId);
+		if (!node) { db.close(); throw new Error(`legion node not found: ${nodeId}`); }
+		// Identity credential check: the node's recorded sessionFile must match
+		// THIS process's session. A child env (PI_LEGION_DB/PI_LEGION_NODE_ID)
+		// inherited by an arbitrary subprocess (e.g. a scout running `npm test`
+		// whose tests load this extension) must not adopt the scout's tree
+		// identity — that produced the "healthy ghost nodes" incident: fake
+		// launches persisted into the live ledger. A mismatch means the env
+		// belongs to an ancestor process, not to us; refuse to attach.
+		const mySession = input.sessionFile;
+		if (mySession && node.sessionFile && path.resolve(mySession) !== path.resolve(node.sessionFile)) {
+			db.close();
+			throw new Error(
+					`legion identity mismatch: node ${nodeId} belongs to session ${node.sessionFile}, ` +
+						`but this process runs ${mySession}; inherited PI_LEGION_* env is not yours to adopt`,
+			);
+		}
+		const nodeRuns = input.store.listRuns().filter((run) => run.nodeId === nodeId || run.herdr.node_id === nodeId);
+		let nodeRun = nodeRuns.at(-1);
+		if (!nodeRun) {
+			nodeRun = input.store.createRun({ task: node.taskSummary ?? `Resume ${node.role} node ${node.id}`, cwd: input.cwd, path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH), maxDepth: effectiveMaxDepth(input.settings.legion?.maxDepth), nodeId, herdr: { supervisor: "rpc", node_id: nodeId } });
+		}
+		if (node.runId !== nodeRun.runId) updateLegionRunId(db, nodeId, nodeRun.runId);
+		const identity = createLegionRuntime({ pi: input.pi, supervisor: input.supervisor, db, dbPath: absoluteDbPath, nodeId, rootRunId: getNode(db, "root")?.runId ?? path.basename(path.dirname(absoluteDbPath)), runDir: input.store.runDir(nodeRun.runId), cwd: input.cwd, storeRootDir: input.store.rootDir, settings: settingsForLegion(input.settings), eventBus: input.eventBus, registerTools: true });
+		if (node.role === "centurion") void resumeLegionTeam({ identity, input });
+		return identity;
+	}
+	if (input.cached?.nodeId === "root" && path.resolve(input.cached.storeRootDir) === path.resolve(input.store.rootDir)) return input.cached;
+	// A root runtime belongs to the current Pi session. Do not adopt a different
+	// session's most recent tree merely because it shares the same project cwd.
+	return undefined;
+}
+
+function updateLegionRunId(db: DatabaseSync, nodeId: string, runId: string): void {
+	db.prepare("UPDATE nodes SET run_id = ?, updated_at = ? WHERE id = ?").run(runId, Date.now(), nodeId);
+}
+
+async function resumeLegionTeam(input: { identity: LegionRuntimeIdentity; input: { pi: ExtensionAPI; supervisor: LegionSupervisor; cwd: string } }): Promise<void> {
+	for (const node of getChildren(input.identity.db, input.identity.nodeId)) {
+		if (["settled", "failed"].includes(node.status) || ["done", "failed", "aborted"].includes(node.phase ?? "") || input.input.supervisor.isAlive(node.name)) continue;
+		if (node.sessionFile) {
+			const parsed = parseSessionFile(node.sessionFile);
+			const recovered = deriveOutcome(parsed);
+			if (isLastTurnComplete(parsed) && recovered.status === "success") {
+				updateNode(input.identity.db, node.id, { status: "settled" });
+				appendEvent(input.identity.db, node.id, "node_settled", { recoveredFromSession: true, execution: recovered.status });
+				const usage = recovered.usage;
+				if (usage) upsertUsage(input.identity.db, { nodeId: node.id, tokensIn: usage.input + usage.cacheRead + usage.cacheWrite, tokensOut: usage.output, costUsd: usage.cost });
+				continue;
+			}
+			if (isLastTurnComplete(parsed) && recovered.status !== "running" && recovered.status !== "unknown") {
+				updateNode(input.identity.db, node.id, { status: "failed" });
+				appendEvent(input.identity.db, node.id, "node_failed", { recoveredFromSession: true, execution: recovered.status, reason: recovered.reason });
+				continue;
+			}
+		}
+		try {
+			await resumeLegionChild({ pi: input.input.pi, supervisor: input.input.supervisor, db: input.identity.db, dbPath: input.identity.dbPath, eventBus: input.identity.eventBus, settings: input.identity.settings, cwd: input.input.cwd, storeRootDir: input.identity.storeRootDir, parentNodeId: input.identity.nodeId, node, message: `Resume from saved session ${node.sessionFile} and continue interrupted work.` });
+		} catch (error) { notice(input.input.pi, `Could not resume ${node.id}: ${error instanceof Error ? error.message : String(error)}`); }
+	}
+}
+
+function createRootLegion(input: { pi: ExtensionAPI; supervisor: LegionSupervisor; store: RunStore; cwd: string; task: string; settings: ReturnType<typeof loadSubagentSettings>; maxDepth: number; eventBus: LegionEventBus }): LegionRuntimeIdentity {
+	const rootRun = input.store.createRun({ task: input.task, cwd: input.cwd, maxDepth: input.maxDepth, nodeId: "root", herdr: { supervisor: "rpc" } });
+	const dbPath = path.resolve(legionDbPath(input.store.runDir(rootRun.runId)));
+	const db = openLegionDb(dbPath);
+	const now = Date.now();
+	insertNode(db, { id: "root", parentId: null, name: "root", role: "root", kind: "pi", depth: 0, runId: rootRun.runId, status: "running", taskSummary: input.task.slice(0, 2_000), createdAt: now, updatedAt: now }, () => now);
+	appendEvent(db, "root", "node_launched", { runId: rootRun.runId, task: input.task }, { now: () => now });
+	return createLegionRuntime({ pi: input.pi, supervisor: input.supervisor, db, dbPath, nodeId: "root", rootRunId: rootRun.runId, runDir: input.store.runDir(rootRun.runId), cwd: input.cwd, storeRootDir: input.store.rootDir, settings: settingsForLegion(input.settings), eventBus: input.eventBus, registerTools: false });
+}
+
+async function resumeLegionChild(input: { pi: ExtensionAPI; supervisor: LegionSupervisor; db: DatabaseSync; dbPath: string; eventBus: LegionEventBus; settings: LegionSettings; cwd: string; storeRootDir: string; parentNodeId: string; node: LegionNode; message: string }): Promise<void> {
+	const parent = getNode(input.db, input.parentNodeId);
+	if (!parent || !input.node.runId || !input.node.sessionFile) throw new Error(`resume credentials missing for ${input.node.id}`);
+	const store = new RunStore({ rootDir: input.storeRootDir });
+	const nodeRun = store.readRun(input.node.runId);
+	if (!nodeRun) throw new Error(`resume run.json not found: ${input.node.runId}`);
+	const parentRunId = parent.runId;
+	if (!parentRunId) throw new Error(`parent run id missing for ${input.node.id}`);
+	let parentRun = store.readRun(parentRunId);
+	if (!parentRun) throw new Error(`parent run.json not found: ${parentRunId}`);
+	let saved = parentRun.children.find((child) => child.nodeId === input.node.id || child.sessionFile === input.node.sessionFile);
+	if (!saved) {
+		await store.addChild(parentRunId, {
+			name: input.node.name,
+			nodeId: input.node.id,
+			sessionFile: input.node.sessionFile,
+			ownerToken: `legion-${input.node.id}`,
+			state: input.node.status === "settled" ? "awaiting" : "retired",
+			spawnedAt: new Date(input.node.createdAt).toISOString(),
+			agent: input.node.role,
+			kind: input.node.kind as AgentConfig["kind"],
+			...(input.node.model ? { model: input.node.model } : {}),
+			...(input.node.worktreePath ? { worktreePath: input.node.worktreePath } : {}),
+		});
+		parentRun = store.readRun(parentRunId)!;
+		saved = parentRun.children.find((child) => child.nodeId === input.node.id);
+	}
+	if (!saved) throw new Error(`resume child record not found: ${input.node.id}`);
+	const cwd = input.node.worktreePath ?? parent.worktreePath ?? parentRun.cwd ?? input.cwd;
+	const catalog = loadCatalog(cwd, cwd, undefined);
+	const resumedTeam = input.node.team
+		? applyTeam(catalog.allAgents, { ...catalog.settings, team: input.node.team }, { ...process.env, [TEAM_ENV]: input.node.team })
+		: { agents: catalog.agents, team: catalog.team, warnings: catalog.teamWarnings };
+	const agent = findControlAgent(resumedTeam.agents, catalog.allAgents, input.node.role);
+	if (!agent) throw new Error(`resume role no longer exists: ${input.node.role}`);
+	const childRun = store.readRun(input.node.runId);
+	if (!childRun) throw new Error(`child run.json not found: ${input.node.runId}`);
+	const parentOfSupervisor = parent.parentId ? getNode(input.db, parent.parentId) : null;
+	const orchestrator = new Orchestrator({ supervisor: input.supervisor, runDir: store.runDir(parentRun.runId), cwd, maxDepth: catalog.settings.legion?.maxDepth, maxSpawns: catalog.settings.maxSubagentSpawnsPerSession ?? null, team: resumedTeam.team, childContext: catalog.settings.childContext, parentPath: parentRun.path, legion: { db: input.db, dbPath: input.dbPath, nodeId: parent.id, parentNodeId: parent.parentId, parentRunId: parentOfSupervisor?.runId ?? null, runId: parentRun.runId, runStore: store, settings: input.settings, eventBus: input.eventBus } });
+	orchestrator.restore(parentRun);
+	const handle = await orchestrator.launch({ agent, task: input.message, name: saved.name, ...(input.node.team ? { team: input.node.team } : {}), ...(saved.model ? { model: saved.model } : {}), worktree: Boolean(saved.worktreePath) });
+	await store.updateChild(parentRun.runId, saved.name, (child) => Object.assign(child, handle.child));
+}
+
+export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervisorDeps = {}) {
+	cascadePromise = undefined;
 	const isChild = process.env.PI_SUBAGENT_CHILD === "1";
 	const allowNested = process.env[ALLOW_NESTED_ENV] === "1";
+	if (isChild) restoreHostNodeOptions();
+	else {
+		// Root UI: surface verify-queue waits instead of a silent stall.
+		setVerifyQueueListener((event) => {
+			try {
+				if (event.phase === "waiting") lastUi?.setStatus("legion-verify", `verify queued ${Math.round(event.waitedMs / 1000)}s · ${event.holders}/${event.limit} slots busy`);
+				else lastUi?.setStatus("legion-verify", undefined);
+			} catch { /* no UI */ }
+		});
+	}
+	const supervisor = deps.supervisor ?? new RpcSupervisor({
+		onSpawnRefused: (message) => {
+			try { lastUi?.notify(`pi-legion: ${message}`, "error"); } catch { /* no UI (child / print mode) */ }
+		},
+	});
+	const verifyRunner = deps.verifyRunner;
+	const legionBus = createLegionEventBus();
+	const rpcUIProxy = (supervisor as LegionSupervisor & { uiProxy?: UIProxy }).uiProxy;
+	const uiProxy = deps.uiProxy ?? rpcUIProxy ?? new InMemoryUIProxy();
+	const onBudgetRefused = deps.onBudgetRefused ?? ((event) => {
+		try { pi.events.emit("pi-legion:budget_refused", event); } catch { /* optional host event */ }
+	});
+	let sessionEnabledOverride: boolean | undefined;
+	const subagentsEnabled = (cwd: string): boolean => {
+		if (sessionEnabledOverride !== undefined) return sessionEnabledOverride;
+		try {
+			return loadSubagentSettings({
+				userSettingsPath: path.join(getAgentDir(), "settings.json"),
+				projectSettingsPath: path.join(cwd, ".pi", "settings.json"),
+			}).enabled !== false;
+		} catch (error) {
+			console.warn(
+				"[pi-legion] Unable to load settings while checking whether subagents are enabled; defaulting to enabled.",
+				error,
+			);
+			return true;
+		}
+	};
+	let lastCwd = process.cwd();
+	let legionIdentity: LegionRuntimeIdentity | undefined;
+	const stopLegionRuntime = (): void => {
+		if (!legionIdentity) return;
+		legionIdentity.postman.stop();
+		legionIdentity.dbEventSource.stop();
+		// #40: bound the ledger and fold the WAL back before closing.
+		if (hygieneEnabled() && !isChild) applyEventRetention(legionIdentity.db);
+		else checkpoint(legionIdentity.db);
+		legionIdentity.db.close();
+		legionIdentity = undefined;
+	};
+	const initializeLegionRuntime = (ctx: Pick<ExtensionContext, "cwd"> & { sessionFile?: string }): void => {
+		const store = runStoreFor(ctx.cwd);
+		const settings = loadSubagentSettings({
+			userSettingsPath: path.join(getAgentDir(), "settings.json"),
+			projectSettingsPath: path.join(ctx.cwd, ".pi", "settings.json"),
+		});
+		const next = resolveLegionIdentity({ pi, supervisor, store, cwd: ctx.cwd, settings, eventBus: legionBus, cached: legionIdentity, sessionFile: ctx.sessionFile });
+		if (legionIdentity && next !== legionIdentity) stopLegionRuntime();
+		legionIdentity = next;
+	};
 	if (isChild) {
 		registerChildGuard(pi);
-		if (!allowNested) return;
+		if (process.env[LEGION_DB_ENV] && process.env[LEGION_NODE_ID_ENV]) {
+			// Boot-time attach: no ExtensionContext yet, so no session credential —
+			// the session_start handler re-runs this with the real credential.
+			try { initializeLegionRuntime({ cwd: process.cwd() }); }
+			catch (error) { console.error(`[pi-legion] legion initialization failed: ${error instanceof Error ? error.message : String(error)}`); }
+		}
 	}
-
-	// The parent transcript records every finish; the renderer keeps a
-	// completed child to one line so visibility does not cost a screen.
-	pi.registerMessageRenderer(SUBAGENT_NOTIFY_TYPE, renderSubagentNotice);
-
-	// The parent pane's own id: absent when pi runs outside herdr, in which
-	// case every labeler call is a no-op.
-	const parentLabeler = new ParentPaneLabeler({
-		client: createHerdrClient(),
-		paneId: process.env.HERDR_PANE_ID,
+	let hygieneScheduled = false;
+	pi.on("session_start", (_event, ctx) => {
+		try { initializeLegionRuntime({ cwd: ctx.cwd, sessionFile: ctx.sessionManager?.getSessionFile() }); }
+		catch (error) { console.error(`[pi-legion] legion initialization failed: ${error instanceof Error ? error.message : String(error)}`); }
+		// #37/#38/#40: one deferred, best-effort storage sweep per root process.
+		if (!isChild && !hygieneScheduled && hygieneEnabled()) {
+			hygieneScheduled = true;
+			const storeRoot = runStoreFor(ctx.cwd).rootDir;
+			const timer = setTimeout(() => {
+				try {
+					const report = runStartupHygiene({ storeRoot, protectRunIds: legionIdentity ? [legionIdentity.rootRunId] : [] });
+					const text = formatHygieneReport(report);
+					if (text) ctx.ui?.notify?.(text, "info");
+				} catch (error) {
+					console.error(`[pi-legion] storage sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			}, 1_500);
+			timer.unref?.();
+		}
+	});
+	const pendingUtilityRetires: Array<() => Promise<void>> = [];
+	let sessionRuntime: SessionRuntime | undefined;
+	const shutdownRetireAll = async (): Promise<void> => {
+		const children = sessionRuntime?.activeJobs() ?? [];
+		sessionRuntime?.dispose();
+		await Promise.all([
+			...children.map((job) => job.retire?.().catch(() => {})),
+			...pendingUtilityRetires.map((retire) => retire().catch(() => {})),
+		]);
+		stopLegionRuntime();
+	};
+	let cascadingJobs = new Set<TrackedJob>();
+	let cascadingUtilityRetires = new Set<() => Promise<void>>();
+	const cascadeRetireAll = (): Promise<void> => {
+		const jobs = (sessionRuntime?.activeJobs() ?? []).filter(
+			(job) => job.state !== "retired" && !cascadingJobs.has(job),
+		);
+		const utilityRetires = pendingUtilityRetires.filter(
+			(retire) => !cascadingUtilityRetires.has(retire),
+		);
+		if (!cascadePromise) cascadePromise = Promise.resolve();
+		if (jobs.length === 0 && utilityRetires.length === 0) return cascadePromise;
+		for (const job of jobs) {
+			cascadingJobs.add(job);
+			sessionRuntime?.cancelWatch(job.name);
+		}
+		for (const retire of utilityRetires) cascadingUtilityRetires.add(retire);
+		const retirements = [
+			...jobs.map((job) => async () => job.retire?.()),
+			...utilityRetires.map((retire) => async () => retire()),
+		];
+		cascadePromise = cascadePromise.then(async () => {
+			// allSettled waits for every graceful retire without turning a child
+			// failure into a user-visible result or skipping runtime release.
+			await Promise.allSettled(retirements.map((retire) => retire()));
+			for (const job of jobs) sessionRuntime?.release(job.name);
+		});
+		return cascadePromise;
+	};
+	// Register before the child early-return paths below: a command-chain child
+	// may use vexillatio across multiple turns without creating a session runtime.
+	pi.on("turn_start", () => {
+		cascadePromise = undefined;
+		cascadingJobs = new Set();
+		cascadingUtilityRetires = new Set();
+	});
+	// An async launch has already returned when ESC lands: no subagent-family
+	// tool call is in flight to observe the abort signal, so the run's settle
+	// event is the last chance to retire this turn's children. Never awaited —
+	// a graceful retire may take seconds and must not stall the settle path.
+	pi.on("agent_settled", (event) => {
+		if (!event.aborted) return;
+		void cascadeRetireAll();
 	});
-	const layout = createSessionLayout();
-	let lastModelRegistry: ExtensionContext["modelRegistry"] | undefined;
+	if (process.env[UTILITY_CHILD_ENV] !== "1") {
+		pi.registerTool({
+			name: "vexillatio",
+			label: "Vexillatio",
+			description: "Launch only read-only utility agents and return their collected output.",
+			parameters: VexillatioParams,
+			async execute(_id, params, signal, _onUpdate, ctx: ExtensionContext): Promise<AgentToolResult<unknown>> {
+				if (signal?.aborted) {
+					await cascadeRetireAll();
+					return ok("interrupted (parent turn aborted)");
+				}
+				if (!subagentsEnabled(ctx.cwd)) {
+					return fail("subagents are disabled (subagents.enabled: false or /legion off). Re-enable with /legion on.", ErrorCodes.DISABLED);
+				}
+				const runtime = sessionRuntime;
+				if (!runtime) return fail("session runtime is not initialized", ErrorCodes.INVALID_PARAMS);
+				runtime.bind(ctx);
+				const result = await launchUtilityFamily({
+					pi,
+					ctx,
+					runtime,
+					params,
+					supervisor,
+					uiProxy,
+					onBudgetRefused,
+					cwd: params.cwd ?? ctx.cwd,
+					sessionCwd: ctx.cwd,
+					signal,
+					isChild,
+					legion: legionIdentity,
+					eventBus: legionBus,
+					onLegion: (identity) => {
+						if (legionIdentity && legionIdentity !== identity) stopLegionRuntime();
+						legionIdentity = identity;
+					},
+					onUtilityChild: (retire) => pendingUtilityRetires.push(retire),
+				});
+				if (signal?.aborted) {
+					await cascadeRetireAll();
+					return ok("interrupted (parent turn aborted)");
+				}
+				return result;
+			},
+		});
+	}
+	pi.on("before_agent_start", (event, ctx) => {
+		if (process.env[UTILITY_CHILD_ENV] === "1") return;
+		if (!subagentsEnabled(ctx?.cwd ?? lastCwd)) return;
+		const tools = event.systemPromptOptions?.selectedTools;
+		if (Array.isArray(tools) && !tools.includes("subagent") && !tools.includes("vexillatio")) return;
+		if (ctx?.cwd) lastCwd = ctx.cwd;
+		const catalog = loadCatalog(lastCwd, lastCwd, undefined);
+		const parentContext = catalog.settings.parentContext?.trim();
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n${PARENT_PLAYBOOK}\n\n${renderParentRoster(
+				catalog.agents,
+				catalog.team,
+				catalog.teamWarnings,
+			)}${parentContext ? `\n\n${parentContext}` : ""}`,
+		};
+	});
+	if (process.env[UTILITY_CHILD_ENV] === "1") {
+		pi.on("session_shutdown", () => stopLegionRuntime());
+		return;
+	}
+	let lastUi: ExtensionUIContext | undefined;
+	let statusNodeOpener: ((nodeId: string) => void) | undefined;
 	let lastConfirm: ((message: string) => Promise<boolean>) | undefined;
-	let lastCwd = process.cwd();
 	// turn_start/turn_end maintain this so a flush window can wait out a
 	// busy parent instead of queueing behind the whole turn (join extends
 	// the window at most MAX_BUSY_EXTENSIONS times).
 	let parentTurnActive = false;
+	const rpcEventSource = supervisor as LegionSupervisor & RpcEventSource;
 	const runtime = createSessionRuntime({
 		sendMessage: (message, options) => pi.sendMessage(message, options),
+		onStatusNodeClick: (nodeId) => statusNodeOpener?.(nodeId),
+		statusStrip: process.env.PI_LEGION_STRIP === "tree" ? "tree" : "railway",
+		eventBus: legionBus,
+		getTreeNodes: () => {
+			const identity = legionIdentity;
+			return identity
+				? attachUsageTotals(identity.db, getSubtree(identity.db, identity.nodeId))
+				: [];
+		},
+		getTreeIdentity: (name) => {
+			const node = legionIdentity && getChildByName(legionIdentity.db, legionIdentity.nodeId, name);
+			return node ? {
+				nodeId: node.id,
+				parentId: node.parentId,
+				depth: node.depth,
+				supervisorName: name,
+			} : undefined;
+		},
+		subscribeSupervisorEvents: (name, listener, options) => rpcEventSource.onEvent?.(
+			name,
+			(event) => {
+				const nodeId = legionIdentity?.childNodeId(name);
+				if (nodeId) publishSupervisorEvent(legionBus, nodeId, event, options);
+				listener(event);
+			},
+			options,
+		) ?? (() => {}),
 		emitBusy: (active, label) => {
-			// Sidebar annotation (research option C): herdr's own integration
-			// reports the parent `idle` the moment its turn settles — exactly
-			// when it is WAITING on subagents. Label the idle state so the
-			// sidebar says `waiting` instead of reading done. Display-layer only;
-			// the status icon stays herdr's call.
-			parentLabeler.report(active ? label : undefined);
-			try {
-				pi.events.emit(
-					"herdr:busy",
-					active ? { active: true, label } : { active: false },
-				);
-			} catch {
-				// herdr's busy overlay is optional; the TUI widget is the primary signal.
-			}
+			try { pi.events.emit("pi-legion:busy", active ? { active: true, label } : { active: false }); }
+			catch { /* optional display integration */ }
 		},
 	});
+	sessionRuntime = runtime;
 	blockedUi.set(runtime, {
 		getConfirm: () => lastConfirm,
 		notifyBlocked: (message) => {
@@ -252,69 +737,83 @@ export default function herdrSubagents(pi: ExtensionAPI) {
 					{ triggerTurn: true, deliverAs: "followUp" },
 				);
 			} catch {
-				// Parent session is gone; the child pane stays open for a later steer.
+				// Parent session may already be gone.
 			}
 		},
 	});
 
-	registerProfileCommands(pi, {
-		getModelRegistry: () => lastModelRegistry,
-	});
-	registerSummaryCommand(pi);
-
-	// ── Master switch ────────────────────────────────────────────────────
-	// Session-level override over `subagents.enabled` (user+project settings).
-	// `undefined` means "follow settings" so /reload picks up file changes;
-	// the toggle command is what writes to this variable.
-	let sessionEnabledOverride: boolean | undefined;
-	/** Effective enabled state: session override > merged settings. */
-	const subagentsEnabled = (cwd: string): boolean => {
-		if (sessionEnabledOverride !== undefined) return sessionEnabledOverride;
-		try {
-			return (
-				loadSubagentSettings({
-					userSettingsPath: path.join(getAgentDir(), "settings.json"),
-					projectSettingsPath: path.join(cwd, ".pi", "settings.json"),
-				}).enabled !== false
-			);
-		} catch (error) {
-			console.warn(
-				"[pi-legion] Unable to load settings while checking whether subagents are enabled; defaulting to enabled.",
-				error,
-			);
-			return true;
-		}
-	};
-
-	registerToggleCommand(pi, {
-		sessionEnabled: () => subagentsEnabled(lastCwd),
-		setSessionEnabled: (enabled) => {
-			sessionEnabledOverride = enabled;
-		},
-		settingsEnabled: (cwd) =>
-			loadSubagentSettings({
+	if (isChild && !allowNested) {
+		pi.on("session_shutdown", shutdownRetireAll);
+		return;
+	}
+	// #17: main session only. Children (PI_SUBAGENT_ROLE / PI_SUBAGENT_CHILD)
+	// must not count their own reads or inject this reminder. Nested children
+	// also have isChild set, so they skip this even though they continue below.
+	if (!isChild) {
+		registerScoutGuard(pi, {
+			loadSettings: (cwd) => loadSubagentSettings({
 				userSettingsPath: path.join(getAgentDir(), "settings.json"),
 				projectSettingsPath: path.join(cwd, ".pi", "settings.json"),
-			}).enabled !== false,
-		runningChildren: () =>
-			runtime
-				.activeJobs()
-				.filter((job) => job.state === "working" || job.state === "blocked")
-				.length,
-	});
+			}),
+		});
+	}
+	// The parent transcript records every finish; the renderer keeps a
+	// completed child to one line so visibility does not cost a screen.
+	pi.registerMessageRenderer(SUBAGENT_NOTIFY_TYPE, renderSubagentNotice);
 
-	// The human-facing roster: what the model gets injected into its system
-	// prompt each turn, but on demand and with resolved models. The catalog
-	// loading is the same function the tool uses, so the two listings cannot
-	// drift apart. Re-loads on every invocation — cheap (a few stat+read calls)
-	// and always fresh after an agent file is edited.
+	// User stop controls (/legion stop, idle Esc, `x` in /legion): a thin wrapper
+	// over the subagent tool's `stop` action — graceful retire of tracked children.
+	const stopChildren = async (params: { name?: string; all?: boolean }): Promise<{ ok: boolean; text: string }> => {
+		const result = await stopAction({
+			params,
+			runtime,
+			retire: async (name) => {
+				await runtime.get(name)?.retire?.();
+			},
+		});
+		const text = result.content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
+		const details = result.details as { error?: string } | undefined;
+		runtime.refreshUi();
+		return { ok: !details?.error, text };
+	};
 	const commandCatalogLoader = (input: {
 		sessionCwd: string;
 		runCwd: string;
 		scope: AgentScope | undefined;
 	}) => loadCatalog(input.sessionCwd, input.runCwd, input.scope);
-	registerAgentsCommand(pi, { loadCatalog: commandCatalogLoader });
-	registerTeamCommand(pi, { loadCatalog: commandCatalogLoader });
+	const liveOverlayController = registerLegionCommand(pi, {
+		bus: legionBus,
+		runtime,
+		supervisor: rpcEventSource,
+		stop: stopChildren,
+		commands: {
+			team: { loadCatalog: commandCatalogLoader },
+			agents: { loadCatalog: commandCatalogLoader },
+			toggle: {
+				sessionEnabled: () => subagentsEnabled(lastCwd),
+				setSessionEnabled: (enabled) => {
+					sessionEnabledOverride = enabled;
+				},
+				settingsEnabled: (cwd) =>
+					loadSubagentSettings({
+						userSettingsPath: path.join(getAgentDir(), "settings.json"),
+						projectSettingsPath: path.join(cwd, ".pi", "settings.json"),
+					}).enabled !== false,
+				runningChildren: () =>
+					runtime
+						.activeJobs()
+						.filter((job) => job.state === "working" || job.state === "blocked")
+						.length,
+			},
+		},
+	});
+	statusNodeOpener = createStatusNodeOpener(
+		pi,
+		liveOverlayController,
+		() => lastUi,
+		() => lastCwd,
+		(ui, nodeId) => void confirmAndStopNode(ui, { runtime, stop: stopChildren }, nodeId),
+	);
 
 	pi.registerTool({
 		name: "subagent",
@@ -328,34 +827,39 @@ export default function herdrSubagents(pi: ExtensionAPI) {
 		async execute(
 			_id,
 			params,
-			_signal,
+			signal,
 			onUpdate,
 			ctx: ExtensionContext,
 		): Promise<AgentToolResult<unknown>> {
 			runtime.bind(ctx);
+			const action = params.action ?? "launch";
+			if (signal?.aborted && action !== "stop") {
+				await cascadeRetireAll();
+				return ok("interrupted (parent turn aborted)");
+			}
 			// Master switch: refuse NEW launches with a pointer to the toggle;
 			// control actions (status/collect/wait/…) must stay available so a
 			// disable with live children remains observable and collectable.
-			const action = params.action ?? "launch";
 			if (!subagentsEnabled(ctx.cwd) && (action === "launch" || !action)) {
 				return fail(
-					"subagents are disabled (subagents.enabled: false or /subagents-toggle off). " +
-						"Existing children are unaffected; re-enable with /subagents-toggle on.",
+					"subagents are disabled (subagents.enabled: false or /legion off). " +
+						"Existing children are unaffected; re-enable with /legion on.",
 					ErrorCodes.DISABLED,
 				);
 			}
-			const client = createHerdrClient();
-			if (!(await client.available())) {
-				return fail(
-					"herdr is not available. Install it (https://herdr.dev) or check HERDR_BIN.",
-					ErrorCodes.HERDR_UNAVAILABLE,
-				);
-			}
-
 			const cwd = params.cwd ?? ctx.cwd;
-			const store = new RunStore({ rootDir: path.join(cwd, ".pi-subagents") });
+			const store = runStoreFor(cwd);
 			const catalog = loadCatalog(ctx.cwd, cwd, params.agentScope);
-			const { agents, allAgents, settings, team, teamWarnings } = catalog;
+			const { allAgents, settings } = catalog;
+			const teamName = action === "launch" ? params.team : undefined;
+			const selectedTeam = teamName
+				? applyTeam(allAgents, { ...settings, team: teamName }, { ...process.env, [TEAM_ENV]: teamName })
+				: { agents: catalog.agents, team: catalog.team, warnings: catalog.teamWarnings };
+			const agents = selectedTeam.agents;
+			const team = selectedTeam.team;
+			const teamWarnings = teamName
+				? [...selectedTeam.warnings, ...catalog.utilityWarnings]
+				: selectedTeam.warnings;
 			runtime.setJoinConfig({
 				mode: settings.joinMode ?? DEFAULT_JOIN_MODE,
 				flushMs: settings.joinFlushMs ?? DEFAULT_FLUSH_MS,
@@ -363,77 +867,133 @@ export default function herdrSubagents(pi: ExtensionAPI) {
 			});
 
 			if (action === "list") return ok(renderAgentList(agents, team, teamWarnings));
+			if (action === "diagnose") {
+				let settings: unknown;
+				try {
+					settings = JSON.parse(readFileSync(path.join(getAgentDir(), "settings.json"), "utf8"));
+				} catch {
+					settings = undefined;
+				}
+				const report = runLegionDoctor({
+					agentDir: getAgentDir(),
+					cwd,
+					storeRoot: store.rootDir,
+					expectedModels: expectedModelsFromSettings(settings),
+					sampleAgent: agents[0],
+					agents,
+					runtime: {
+						liveJobs: runtime.activeJobs().map((job) => ({
+							name: job.name,
+							state: job.state,
+							nodeId: job.nodeId,
+						})),
+						stopAvailable: true,
+						idleEscWired: true,
+						legionTools: ["subagent", "vexillatio"],
+						allowNestedEnv: process.env[ALLOW_NESTED_ENV] === "1",
+					},
+				});
+				return ok(report.text);
+			}
+
+			let activeLegion: LegionRuntimeIdentity | undefined;
+			try {
+				activeLegion = resolveLegionIdentity({ pi, supervisor, store, cwd, settings, eventBus: legionBus, cached: legionIdentity, sessionFile: ctx.sessionManager?.getSessionFile() });
+				if (!activeLegion && action === "launch" && !isChild) {
+					const plan = buildPlan(params);
+					if (plan.ok) activeLegion = createRootLegion({ pi, supervisor, store, cwd, task: plan.task, settings, maxDepth: effectiveMaxDepth(settings.legion?.maxDepth), eventBus: legionBus });
+				}
+				if (activeLegion) legionIdentity = activeLegion;
+			} catch (error) {
+				return fail(`legion runtime initialization failed: ${error instanceof Error ? error.message : String(error)}`, ErrorCodes.INVALID_PARAMS);
+			}
+			if (signal?.aborted && action !== "stop") {
+				await cascadeRetireAll();
+				return ok("interrupted (parent turn aborted)");
+			}
 
 			// Control actions address an EXISTING child; launch-family actions
 			// create new ones. The two share almost nothing, so they are separate.
 			if (action !== "launch") {
-				return controlAction({
+				const result = await controlAction({
 					action,
 					params,
-					client,
+					signal,
+					supervisor,
+					uiProxy,
+					onBudgetRefused,
+					verifyRunner,
 					store,
 					cwd,
 					agents,
 					allAgents,
 					team,
 					runtime,
-					layout,
 					settings,
+					legion: activeLegion,
 				});
+				if (signal?.aborted && action !== "stop") {
+					await cascadeRetireAll();
+					return ok("interrupted (parent turn aborted)");
+				}
+				return result;
 			}
 
-			return launchFamily({
+			const result = await launchFamily({
 				params,
+				signal,
 				ctx,
-				client,
+				supervisor,
+				uiProxy,
+				onBudgetRefused,
+				verifyRunner,
 				store,
 				cwd,
 				agents,
 				allAgents,
 				settings,
 				team,
+				legion: activeLegion,
 				runtime,
-				layout,
 				onUpdate,
 			});
+			if (signal?.aborted) {
+				await cascadeRetireAll();
+				return ok("interrupted (parent turn aborted)");
+			}
+			return result;
 		},
 	});
 
-	pi.on("before_agent_start", (event, ctx) => {
-		if (isChild && !allowNested) return;
-		// Master switch: when disabled, stop injecting the playbook and the
-		// roster so the model is not coached toward a tool that will refuse.
-		if (!subagentsEnabled(ctx?.cwd ?? lastCwd)) return;
-		const tools = event.systemPromptOptions?.selectedTools;
-		if (Array.isArray(tools) && !tools.includes("subagent")) return;
-		if (ctx?.cwd) lastCwd = ctx.cwd;
-		const catalog = loadCatalog(lastCwd, lastCwd, undefined);
-		const parentContext = catalog.settings.parentContext?.trim();
-		return {
-			systemPrompt: `${event.systemPrompt}\n\n${PARENT_PLAYBOOK}\n\n${renderParentRoster(
-				catalog.agents,
-				catalog.team,
-				catalog.teamWarnings,
-			)}${parentContext ? `\n\n${parentContext}` : ""}`,
-		};
-	});
-
-	pi.on("tool_call", (event, ctx) => {
-		if (event.toolName !== "bash") return;
-		// Master switch: when disabled, the user (or the model) may legitimately
-		// drive herdr by hand; the guard only makes sense while we own dispatch.
-		// Prefer the event's own ctx over lastCwd: it cannot go stale between
-		// the bindUi events that maintain lastCwd.
-		if (!subagentsEnabled(ctx?.cwd ?? lastCwd)) return;
-		const command =
-			typeof event.input.command === "string" ? event.input.command : "";
-		const reason = forbiddenDispatchReason(command);
-		if (!reason) return;
-		return { block: true, reason: blockMessage(reason) };
+	let lastCtx: ExtensionContext | undefined;
+	let escUi: ExtensionUIContext | undefined;
+	let escUnsubscribe: (() => void) | undefined;
+	const idleEscStop = createIdleEscStop({
+		isIdle: () => lastCtx?.isIdle?.() ?? false,
+		editorEmpty: () => !(lastUi?.getEditorText?.() ?? "").trim(),
+		uiBusy: () => {
+			const tui = runtime.statusTui() as { hasOverlay?: () => boolean; getFocusedComponent?: () => unknown } | undefined;
+			if (!tui) return true;
+			if (tui.hasOverlay?.()) return true;
+			const focused = tui.getFocusedComponent?.() as { getText?: unknown } | null | undefined;
+			// Only the prompt editor may have focus: dialogs/selectors keep pi's Esc.
+			return !focused || typeof focused.getText !== "function" || !("onEscape" in focused);
+		},
+		liveCount: () => liveJobs(runtime.activeJobs()).length,
+		confirm: (title, message) => lastUi ? lastUi.confirm(title, message) : Promise.resolve(false),
+		stopAll: async () => {
+			const result = await stopChildren({ all: true });
+			lastUi?.notify(result.text, result.ok ? "info" : "error");
+		},
 	});
-
 	const bindUi = (_event: unknown, ctx: ExtensionContext): void => {
-		lastModelRegistry = ctx.modelRegistry;
+		lastCtx = ctx;
+		if (ctx.hasUI && ctx.ui !== escUi && typeof ctx.ui?.onTerminalInput === "function") {
+			escUnsubscribe?.();
+			escUi = ctx.ui;
+			escUnsubscribe = ctx.ui.onTerminalInput(idleEscStop);
+		}
+		lastUi = ctx.hasUI ? ctx.ui : undefined;
 		if (ctx.cwd) lastCwd = ctx.cwd;
 		runtime.bind(ctx);
 		lastConfirm =
@@ -442,7 +1002,30 @@ export default function herdrSubagents(pi: ExtensionAPI) {
 				: undefined;
 	};
 
-	pi.on("session_start", bindUi);
+	uiProxy.onRequest((pending) => {
+		const legionNodeId = legionIdentity?.childNodeId(pending.childName);
+		if (legionNodeId) publishUIRequest(legionBus, legionNodeId, pending.request.method);
+		const ui = lastUi;
+		if (!ui) return;
+		const request = pending.request;
+		if (request.method === "confirm") return;
+		if (request.method === "select") {
+			void ui.select(request.title, request.options).then((value) => uiProxy.respond(pending.id, value === undefined ? { cancelled: true } : { value }));
+		} else if (request.method === "input") {
+			void ui.input(request.title, request.placeholder).then((value) => uiProxy.respond(pending.id, value === undefined ? { cancelled: true } : { value }));
+		} else if (request.method === "editor") {
+			void ui.editor(request.title, request.prefill).then((value) => uiProxy.respond(pending.id, value === undefined ? { cancelled: true } : { value }));
+		} else if (request.method === "notify") ui.notify(request.message, request.notifyType);
+		else if (request.method === "setStatus") ui.setStatus(request.statusKey, request.statusText);
+		else if (request.method === "setWidget") ui.setWidget(request.widgetKey, request.widgetLines, { placement: request.widgetPlacement });
+		else if (request.method === "setTitle") ui.setTitle(request.title);
+		else if (request.method === "set_editor_text") ui.setEditorText(request.text);
+	});
+
+	pi.on("session_start", (event, ctx) => {
+		runtime.setParentIdle(ctx.isIdle?.() ?? true);
+		bindUi(event, ctx);
+	});
 	pi.on("session_info_changed", bindUi);
 	pi.on("turn_start", (event, ctx) => {
 		parentTurnActive = true;
@@ -452,29 +1035,32 @@ export default function herdrSubagents(pi: ExtensionAPI) {
 		parentTurnActive = false;
 		bindUi(event, ctx);
 	});
-	pi.on("agent_start", bindUi);
-	pi.on("agent_end", bindUi);
+	pi.on("agent_start", (event, ctx) => {
+		runtime.setParentIdle(false);
+		bindUi(event, ctx);
+	});
+	pi.on("agent_end", (event, ctx) => {
+		runtime.setParentIdle(true);
+		bindUi(event, ctx);
+	});
 	pi.on("input", bindUi);
 	pi.on("tool_result", (_event, ctx) => {
 		bindUi(_event, ctx);
 		runtime.refreshUi();
 	});
-	pi.on("session_shutdown", () => {
-		runtime.dispose();
-		void parentLabeler.clear();
-	});
+	pi.on("session_shutdown", shutdownRetireAll);
 }
 
 /**
  * Load the effective agent catalog for a request.
  *
- * User settings (`~/.pi/agent/settings.json`, including a loaded profile) merge
+ * User settings (`~/.pi/agent/settings.json`) merge
  * with project `.pi/settings.json`. Agent directories are resolved from the
  * run's `cwd`. Bundled roles are included unless `subagents.disableBuiltins`
  * opts out.
  *
  * Also returns the discovery directories, for listings that tell the user
- * WHERE the roles came from (the /subagents-agents command).
+ * WHERE the roles came from (the /legion agents command).
  */
 export function loadCatalog(
 	sessionCwd: string,
@@ -488,6 +1074,7 @@ export function loadCatalog(
 	teamWarnings: string[];
 	projectAgentsDir: string | null;
 	builtinAgentsDir: string;
+	utilityWarnings: string[];
 } {
 	const settings = loadSubagentSettings({
 		userSettingsPath: path.join(getAgentDir(), "settings.json"),
@@ -498,6 +1085,14 @@ export function loadCatalog(
 	});
 	const overridden = applyAgentOverrides(discovery.agents, settings.agentOverrides);
 	const teamResult = applyTeam(overridden, settings);
+	const utilityWarnings = [...new Map(
+		[...overridden, ...teamResult.agents]
+			.filter((agent) => agent.utility && agent.allowNestedSubagents)
+			.map((agent) => [
+				agent.name,
+				`Utility agent "${agent.name}" sets allowNestedSubagents: true; utility identity takes precedence and nested dispatch is ignored.`,
+			] as const),
+	).values()];
 	const resolveDefaults = (items: AgentConfig[]): AgentConfig[] =>
 		applyDefaultOnBlocked(
 			applyDefaultModel(items, settings.defaultModel),
@@ -509,7 +1104,8 @@ export function loadCatalog(
 		agents: resolveDefaults(teamResult.agents),
 		allAgents: resolveDefaults(overridden),
 		team: teamResult.team,
-		teamWarnings: teamResult.warnings,
+		teamWarnings: [...teamResult.warnings, ...utilityWarnings],
+		utilityWarnings,
 		settings,
 		projectAgentsDir: discovery.projectAgentsDir,
 		builtinAgentsDir: discovery.builtinAgentsDir ?? BUILTIN_AGENTS_DIR,
@@ -530,14 +1126,18 @@ export function loadCatalog(
 async function controlAction(input: {
 	action: string;
 	params: SubagentParams;
-	client: HerdrClient;
+	signal?: AbortSignal;
+	legion?: OrchestratorLegionContext;
+	supervisor: LegionSupervisor;
+	uiProxy: UIProxy;
+	onBudgetRefused: NonNullable<ConstructorParameters<typeof Orchestrator>[0]["onBudgetRefused"]>;
+	verifyRunner?: VerifyRunner;
 	store: RunStore;
 	cwd: string;
 	agents: AgentConfig[];
 	allAgents: AgentConfig[];
 	team: ActiveTeam;
 	runtime: SessionRuntime;
-	layout: SessionLayout;
 	settings: ReturnType<typeof loadSubagentSettings>;
 }): Promise<AgentToolResult<unknown>> {
 	const { action, params, store, cwd } = input;
@@ -557,6 +1157,7 @@ async function controlAction(input: {
 		}
 		return waitAction({
 			params,
+			signal: input.signal,
 			runtime: input.runtime,
 			agents: input.agents,
 			allAgents: input.allAgents,
@@ -565,6 +1166,40 @@ async function controlAction(input: {
 		});
 	}
 
+	if (action === "stop") {
+		return stopAction({
+			params,
+			runtime: input.runtime,
+			retire: async (name) => {
+				const job = input.runtime.get(name);
+				if (job?.retire) {
+					await job.retire();
+					return;
+				}
+				// A completion watch can retire/release a target after stop snapshots
+				// all names but before the serial loop reaches it. Treat that target as
+				// stopped; only rebuild if its persisted record is not already retired.
+				const found = findChild(input.store.listRuns(), name);
+				if (!found) throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
+				if (found.child.state === "retired") return;
+				const orchestrator = new Orchestrator({
+					supervisor: input.supervisor,
+					uiProxy: input.uiProxy,
+					runDir: input.store.runDir(found.runId),
+					cwd: input.cwd,
+					maxDepth: input.settings.legion?.maxDepth,
+					childContext: input.settings.childContext,
+					...teamForChildren(input.team),
+					...(input.legion ? { legion: { ...input.legion, runId: found.runId, runStore: input.store } } : {}),
+					onBudgetRefused: input.onBudgetRefused,
+				});
+				orchestrator.restore(found.run);
+				await orchestrator.retire(name);
+				await persistChild(input.store, found.runId, orchestrator, name);
+			},
+		});
+	}
+
 	if (!params.name) {
 		return fail(
 			`\`name\` is required for the "${action}" action.`,
@@ -576,14 +1211,18 @@ async function controlAction(input: {
 	if (!found) return unknownChild(params.name, store, cwd);
 
 	const orchestrator = new Orchestrator({
-		client: input.client,
+		supervisor: input.supervisor,
+		uiProxy: input.uiProxy,
 		runDir: store.runDir(found.runId),
 		cwd,
-		layout: input.layout,
-		workspaceId: process.env.HERDR_WORKSPACE_ID,
-		parentPaneId: process.env.HERDR_PANE_ID,
+		maxDepth: input.settings.legion?.maxDepth,
 		childContext: input.settings.childContext,
+		verifyRunner: input.verifyRunner,
+		worktreeBootstrap: input.settings.legion?.worktreeBootstrap,
+		worktreeBootstrapTimeoutMs: input.settings.legion?.worktreeBootstrapTimeoutMs,
 		...teamForChildren(input.team),
+		...(input.legion ? { legion: { ...input.legion, runId: found.runId, runStore: store } } : {}),
+		onBudgetRefused: input.onBudgetRefused,
 	});
 	orchestrator.restore(found.run);
 
@@ -594,9 +1233,20 @@ async function controlAction(input: {
 		orchestrator,
 	};
 
-	if (action === "status") return renderChild(found.child, "status");
+	if (action === "status") {
+		return ok(renderLiveChildStatus({
+			name: found.child.name,
+			state: found.child.state,
+			agent: found.child.agent,
+			kind: found.child.kind,
+			sessionFile: found.child.sessionFile,
+			execution: found.child.execution,
+			acceptance: found.child.acceptance,
+			alive: input.supervisor.isAlive(params.name),
+		}));
+	}
 	if (action === "steer") return steerChild(ctx);
-	if (action === "collect") return collectChild(ctx);
+	if (action === "collect") return collectChild(ctx, input.signal);
 	if (action === "retire") return retireChild(ctx);
 	if (action === "continue" || action === "resume") return reviveChild(ctx);
 
@@ -609,7 +1259,9 @@ interface ChildContext {
 	params: SubagentParams;
 	/** Always set: `controlAction` rejects a request without a name. */
 	name: string;
-	client: HerdrClient;
+	supervisor: LegionSupervisor;
+	uiProxy: UIProxy;
+	onBudgetRefused: NonNullable<ConstructorParameters<typeof Orchestrator>[0]["onBudgetRefused"]>;
 	store: RunStore;
 	cwd: string;
 	agents: AgentConfig[];
@@ -631,14 +1283,7 @@ function unknownChild(
 	store: RunStore,
 	cwd: string,
 ): AgentToolResult<unknown> {
-	const known = store
-		.listRuns()
-		.filter((r) => {
-			const owner = process.env.HERDR_PANE_ID?.trim();
-			if (!owner) return true;
-			return r.herdr.parentPaneId === owner;
-		})
-		.flatMap((r) => r.children.map((c) => c.name));
+	const known = store.listRuns().flatMap((run) => run.children.map((child) => child.name));
 	return fail(
 		`unknown child: ${name} (no run under ${cwd}/.pi-subagents` +
 			`${known.length ? `; known here: ${known.join(", ")}` : ""}). ` +
@@ -667,12 +1312,17 @@ async function steerChild(
 /** Wait for the child's current turn and derive its outcome from the session. */
 async function collectChild(
 	ctx: ChildContext,
+	signal?: AbortSignal,
 ): Promise<AgentToolResult<unknown>> {
 	try {
-		const pending = ctx.runtime.consumeCollect(ctx.name);
+		if (signal?.aborted) return ok("interrupted (parent turn aborted)");
+		const pending = signal
+			? ctx.runtime.consumeCollectInterruptible(ctx.name, signal)
+			: ctx.runtime.consumeCollect(ctx.name);
 		if (pending) {
 			const collected = await pending;
-			await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name);
+			if (!collected || signal?.aborted) return ok("interrupted (parent turn aborted)");
+			await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name, { preserveRetired: true });
 			return ok(renderCollect(ctx.name, collected));
 		}
 
@@ -685,12 +1335,16 @@ async function collectChild(
 			ctx.found.child.agent,
 		);
 		const timeoutMs = agentDef?.timeoutMs ?? DEFAULTS.turnTimeoutMs;
-		const collected = await ctx.orchestrator.collect(ctx.name, { timeoutMs });
-		await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name);
-		if (
-			shouldRecycleAfterCollect(collected.execution.status) &&
-			!collected.blocked
-		) {
+		const collected = await ctx.orchestrator.collect(ctx.name, {
+			timeoutMs,
+			...(signal ? { signal } : {}),
+		});
+		if (signal?.aborted || collected.execution.reason === "aborted by parent") {
+			return ok("interrupted (parent turn aborted)");
+		}
+		const retireAlreadyFinishedJob = shouldRecycleAfterCollect(collected.execution.status) && !collected.blocked;
+		await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name, { preserveRetired: !retireAlreadyFinishedJob });
+		if (retireAlreadyFinishedJob) {
 			await ctx.orchestrator.retire(ctx.name);
 			await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name);
 		}
@@ -701,7 +1355,7 @@ async function collectChild(
 	}
 }
 
-/** Recycle the child: snapshot the outcome, exit the agent, close the pane. */
+/** Retire the RPC child while preserving its outcome and session for resume. */
 async function retireChild(
 	ctx: ChildContext,
 ): Promise<AgentToolResult<unknown>> {
@@ -718,7 +1372,7 @@ async function retireChild(
 		await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name);
 		return ok(
 			`Retired ${ctx.name} (execution=${child.execution?.status ?? "unknown"}). ` +
-				`Pane closed; session kept for resume: ${child.sessionFile}`,
+				`RPC process stopped; session kept for resume: ${child.sessionFile}`,
 		);
 	} catch (error) {
 		return fail(`retire failed: ${String(error)}`, ErrorCodes.RETIRE_FAILED);
@@ -729,12 +1383,12 @@ async function retireChild(
  * Continue or resume a child.
  *
  * A live agent is prompted in place; an exited one is relaunched from its
- * persisted session so its context survives the pane being gone (F12).
+ * persisted session so its context survives the process being gone (F12).
  */
 async function reviveChild(
 	ctx: ChildContext,
 ): Promise<AgentToolResult<unknown>> {
-	const { action, params, client, name, found, orchestrator } = ctx;
+	const { action, params, supervisor, name, found, orchestrator } = ctx;
 
 	if (!params.message) {
 		return fail(
@@ -756,23 +1410,11 @@ async function reviveChild(
 	}
 
 	try {
-		const agentState = await client.agentGet(name);
-		if (agentState.ok) {
+		if (supervisor.isAlive(name)) {
 			await orchestrator.steer(name, params.message);
 			followChild(ctx, { watch: true });
 			return ok(
-				`${action === "resume" ? "Resumed" : "Continued"} ${name} (live agent prompted).`,
-			);
-		}
-		// Only a DEFINITIVE not-found means the agent exited and must be
-		// relaunched. Any other failure (a wedged or timed-out herdr CLI) says
-		// nothing about the child — relaunching now would collide with the live
-		// agent holding the name (F16) or spawn a duplicate.
-		if (agentState.error.code !== ErrorCodes.NOT_FOUND) {
-			return fail(
-				`${action} failed: cannot determine whether ${name} is alive ` +
-					`(herdr: ${agentState.error.message}). Retry shortly.`,
-				agentState.error.code,
+				`${action === "resume" ? "Resumed" : "Continued"} ${name} (live RPC child steered).`,
 			);
 		}
 
@@ -784,8 +1426,7 @@ async function reviveChild(
 		});
 		followChild(ctx, { watch: true });
 		return ok(
-			`Resumed ${handle.name} from its session (pane ${handle.paneId}). ` +
-				`Context preserved from ${handle.sessionFile}`,
+			`Resumed ${handle.name} from its session. Context preserved from ${handle.sessionFile}`,
 		);
 	} catch (error) {
 		return fail(`${action} failed: ${String(error)}`, ErrorCodes.START_FAILED);
@@ -800,19 +1441,22 @@ async function reviveChild(
 async function launchFamily(input: {
 	params: SubagentParams;
 	ctx: ExtensionContext;
-	client: HerdrClient;
+	supervisor: LegionSupervisor;
+	uiProxy: UIProxy;
+	onBudgetRefused: NonNullable<ConstructorParameters<typeof Orchestrator>[0]["onBudgetRefused"]>;
+	verifyRunner?: VerifyRunner;
 	store: RunStore;
 	cwd: string;
 	agents: AgentConfig[];
 	allAgents: AgentConfig[];
 	settings: ReturnType<typeof resolveSubagentSettings>;
 	team: ActiveTeam;
+	legion?: LegionRuntimeIdentity;
 	runtime: SessionRuntime;
-	layout: SessionLayout;
+	signal?: AbortSignal;
 	onUpdate?: AgentToolUpdateCallback;
 }): Promise<AgentToolResult<unknown>> {
-	const { params, ctx, store, cwd, agents, settings, runtime, layout, onUpdate } =
-		input;
+	const { params, ctx, store, cwd, agents, settings, runtime, onUpdate } = input;
 
 	const plan = buildPlan(params);
 	if (!plan.ok) return fail(plan.message, ErrorCodes.INVALID_PARAMS);
@@ -821,40 +1465,65 @@ async function launchFamily(input: {
 		content: [
 			{
 				type: "text",
-				text: `playbook: ${plan.steps.map((s) => s.agent).join(", ")} → type-tab → pane → start → watch`,
+				text: `playbook: ${plan.steps.map((s) => s.agent).join(", ")} → RPC launch → watch`,
 			},
 		],
 		details: {},
 	});
 
-	const run = store.createRun({
-		task: plan.task,
-		cwd,
-		herdr: {
-			...(process.env.HERDR_WORKSPACE_ID
-				? { workspaceId: process.env.HERDR_WORKSPACE_ID }
-				: {}),
-			...(process.env.HERDR_PANE_ID
-				? { parentPaneId: process.env.HERDR_PANE_ID }
-				: {}),
-		},
-	});
+	const maxDepth = effectiveMaxDepth(settings.legion?.maxDepth);
+	const legion = input.legion;
+	let run = legion ? store.readRun(legion.runId) : null;
+	if (!run) {
+		run = store.createRun({
+			task: plan.task,
+			cwd,
+			maxDepth,
+			...(legion ? { path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH), nodeId: legion.nodeId, herdr: { supervisor: "rpc" as const, node_id: legion.nodeId } } : { herdr: { supervisor: "rpc" as const } }),
+		});
+		if (legion && legion.nodeId !== "root" && legion.parentRunId) {
+			const node = getNode(legion.db, legion.nodeId);
+			if (node?.sessionFile) {
+				const parentRun = store.readRun(legion.parentRunId);
+				if (parentRun && !parentRun.children.some((child) => child.nodeId === node.id)) {
+					await store.addChild(legion.parentRunId, {
+						name: node.name,
+						nodeId: node.id,
+						sessionFile: node.sessionFile,
+						ownerToken: node.id,
+						state: "working",
+						spawnedAt: run.createdAt,
+						agent: node.role,
+						kind: node.kind as AgentConfig["kind"],
+						...(node.model ? { model: node.model } : {}),
+						...(node.worktreePath ? { worktreePath: node.worktreePath } : {}),
+					});
+				}
+			}
+			updateLegionRunId(legion.db, legion.nodeId, run.runId);
+		}
+	}
 	const orchestrator = new Orchestrator({
-		client: input.client,
-		runDir: store.runDir(run.runId),
+		supervisor: input.supervisor,
+		uiProxy: input.uiProxy,
+		runDir: legion?.runDir ?? store.runDir(run.runId),
 		cwd,
-		layout,
-		// Enforce the session spawn budget so a runaway fan-out cannot exhaust
-		// the machine (ErrorCodes.BUDGET_EXCEEDED).
+		maxDepth: settings.legion?.maxDepth,
 		maxSpawns: settings.maxSubagentSpawnsPerSession ?? null,
-		workspaceId: process.env.HERDR_WORKSPACE_ID,
-		parentPaneId: process.env.HERDR_PANE_ID,
 		childContext: settings.childContext,
+		verifyRunner: input.verifyRunner,
+		worktreeBootstrap: settings.legion?.worktreeBootstrap,
+		worktreeBootstrapTimeoutMs: settings.legion?.worktreeBootstrapTimeoutMs,
 		...teamForChildren(input.team),
+		...(legion ? { legion: { db: legion.db, dbPath: legion.dbPath, nodeId: legion.nodeId, runId: run.runId, parentNodeId: legion.parentNodeId ?? undefined, parentRunId: legion.parentRunId ?? undefined, runStore: store, settings: legion.settings, eventBus: legion.eventBus } } : {}),
+		onBudgetRefused: input.onBudgetRefused,
 	});
+	orchestrator.restore(run);
 
 	const session: LaunchSession = {
 		params,
+		signal: input.signal,
+		teamOverride: params.team,
 		store,
 		agents,
 		allAgents: input.allAgents,
@@ -872,13 +1541,27 @@ async function launchFamily(input: {
 		timeoutByName: new Map(),
 	};
 
+	const interruptedResult = async (): Promise<AgentToolResult<unknown> | undefined> => {
+		if (!input.signal?.aborted) return undefined;
+		for (const name of session.handles) await abandonLaunchedChild(session, name);
+		session.handles.length = 0;
+		return {
+			content: [{ type: "text", text: session.results.join("\n") || "interrupted (parent turn aborted)" }],
+			details: { runId: run.runId, handles: [], async: params.async ?? true },
+		};
+	};
+
 	// Every planned child is independent and launches concurrently.
 	await Promise.all(plan.steps.map((step) => launchStep(session, step)));
+	const interruptedLaunch = await interruptedResult();
+	if (interruptedLaunch) return interruptedLaunch;
 
 	// Persist children first so a crash during the wait still leaves a record.
 	for (const name of session.handles) {
 		await persistChild(store, run.runId, orchestrator, name);
 	}
+	const interruptedPersistence = await interruptedResult();
+	if (interruptedPersistence) return interruptedPersistence;
 
 	// Collect inline unless the caller asked for async (the default).
 	// Async: the session runtime watches each child and wakes the parent
@@ -888,11 +1571,16 @@ async function launchFamily(input: {
 		followLaunched(session, name, { watch: isAsync });
 	}
 	if (!isAsync) {
-		await collectInline(session);
+		await collectInline(session, input.signal);
 		for (const name of session.handles) {
 			const child = orchestrator
 				.childrenSnapshot()
 				.find((c) => c.name === name);
+			if (input.signal?.aborted && (!child?.execution || !shouldRecycleAfterCollect(child.execution.status))) {
+				followLaunched(session, name, { watch: true });
+				await persistChild(store, run.runId, orchestrator, name);
+				continue;
+			}
 			if (
 				child?.execution &&
 				shouldRecycleAfterCollect(child.execution.status)
@@ -904,19 +1592,9 @@ async function launchFamily(input: {
 		}
 	}
 
-	// Record the type-tab the children joined so a later process can see it.
-	if (orchestrator.tabId) {
-		await store.updateRun(run.runId, (r) => {
-			r.herdr = {
-				...r.herdr,
-				tabId: orchestrator.tabId ?? undefined,
-			};
-		});
-	}
-
 	if (isAsync && session.handles.length > 0) {
 		session.results.push(
-			"↳ async: a completion message is queued when each child finishes. If this session is idle it wakes immediately; if it is still working the notice waits until the current turn ends. Running children show next to the input. Do not tell children to message the parent; do not poll just to wait.",
+			"↳ async: a completion message is queued when each RPC child finishes. It wakes this session when idle; otherwise it is delivered after the current turn. Use wait or collect for results. Do not tell children to message the parent.",
 		);
 	}
 
@@ -929,6 +1607,8 @@ async function launchFamily(input: {
 /** Accumulated state for one launch-family request. */
 interface LaunchSession {
 	params: SubagentParams;
+	signal?: AbortSignal;
+	teamOverride?: string;
 	store: RunStore;
 	agents: AgentConfig[];
 	allAgents: AgentConfig[];
@@ -950,8 +1630,9 @@ interface LaunchSession {
  */
 async function launchStep(
 	session: LaunchSession,
-	step: { agent: string; task: string; model?: string; preset?: string; worktree?: boolean },
+	step: { agent: string; task: string; model?: string; preset?: string; worktree?: boolean; verify?: string[] },
 ): Promise<void> {
+	if (session.signal?.aborted) return;
 	const agent = findAgent(session.agents, step.agent);
 	if (!agent) {
 		session.results.push(
@@ -981,6 +1662,34 @@ async function launchStep(
 		const effective = model.agent;
 		const resolved = model.resolved;
 
+		// `verify:` on the launch call becomes a criterion with an explicit
+		// `command`, so `applyVerification` runs it in the child worktree at
+		// collect time — the extension verifies the child's verdict instead
+		// of trusting pasted test output. Blank entries are dropped; an empty
+		// result is a no-op. Never mutated onto the shared agent object: the
+		// catalog would hand the same reference to every later launch.
+		const verifyCommands = (step.verify ?? session.params.verify ?? [])
+			.map((command) => command.trim())
+			.filter(Boolean);
+		const launchedAgent = verifyCommands.length
+			? {
+				...effective,
+				acceptance: {
+					...(effective.acceptance ?? { level: "attested" as const }),
+					criteria: [
+						...(effective.acceptance?.criteria ?? []),
+						{
+							id: "task-verify",
+							must: "Launcher-supplied verify commands pass (run by the extension, not the child)",
+							evidence: ["verification-output"],
+							severity: "required" as const,
+							command: verifyCommands.join(" && "),
+						},
+					],
+				},
+			}
+			: effective;
+
 		const violation = checkModelScope(
 			resolved.model,
 			session.settings.modelScope,
@@ -991,31 +1700,39 @@ async function launchStep(
 			return;
 		}
 
-		// Let `launch()` allocate: it consults the GLOBAL herdr name namespace.
-		// Pre-allocating here from local state alone would bypass that check and
-		// collide with another session's agent.
+		// Let `launch()` allocate from the supervisor-local registry; the index
+		// must not race separate subagent tool calls.
 		const handle = await session.orchestrator.launch({
-			agent: effective,
+			agent: launchedAgent,
 			task: step.task,
+			...(session.teamOverride ? { team: session.teamOverride } : {}),
 			...(resolved.model ? { model: resolved.model } : {}),
 			// The origin decides whether an unacceptable model is refused or
 			// dropped, and only this layer can tell them apart (a parent model
 			// arrives as the same `dispatch` source as a per-run override).
 			modelOrigin: model.modelOrigin,
-			...(model.placement ? { placement: model.placement } : {}),
 			worktree: resolveLaunchWorktree({
 				roleDefault: effective.worktree,
 				launch: session.params.worktree,
 				step: step.worktree,
 			}),
 		});
-		await session.store.addChild(session.runId, handle.child);
+		const recorded = session.store.findChild(session.runId, handle.name);
+		if (recorded?.nodeId && recorded.nodeId === handle.child.nodeId) {
+			await session.store.updateChild(session.runId, handle.name, (child) => Object.assign(child, handle.child));
+		} else {
+			await session.store.addChild(session.runId, handle.child);
+		}
 		session.handles.push(handle.name);
 		if (effective.timeoutMs !== undefined) {
 			session.timeoutByName.set(handle.name, effective.timeoutMs);
 		}
+		if (session.signal?.aborted) {
+			await abandonLaunchedChild(session, handle.name);
+			return;
+		}
 		session.results.push(
-			`▶ ${handle.name} (${effective.name}) pane=${handle.paneId}`,
+			`▶ ${handle.name} (${effective.name}) supervisor=rpc`,
 		);
 		// An inherited model the target CLI cannot express is dropped on purpose
 		// (the parent's pi model means nothing to cursor). Say so, or the user
@@ -1031,7 +1748,7 @@ async function launchStep(
 			content: [
 				{
 					type: "text",
-					text: `playbook: ${handle.name} started in ${handle.paneId}`,
+					text: `playbook: ${handle.name} started via RPC`,
 				},
 			],
 			details: {},
@@ -1068,7 +1785,7 @@ export function unknownAgentLine(
 ): string {
 	const available = agents.map((a) => a.name).join(", ") || "none";
 	if (teamName) {
-		return `✗ unknown agent "${requested}" in team "${teamName}". Available: ${available}. Switch with /subagents-team use ${teamName} (or "default").`;
+		return `✗ unknown agent "${requested}" in team "${teamName}". Available: ${available}. Switch with /legion team use ${teamName} (or "default").`;
 	}
 	return `✗ unknown agent "${requested}". Available: ${available}`;
 }
@@ -1093,7 +1810,7 @@ export function unknownAgentLineForCatalog(
 }
 
 /**
- * Resolve the model and placement one step will launch with.
+ * Resolve the model one step will launch with.
  *
  * The precedence logic itself lives in `resolveStepModel`
  * (`src/agents/step-model.ts`), which is pure and unit-tested; this wrapper
@@ -1107,7 +1824,6 @@ function resolveStep(
 	step: { model?: string; preset?: string },
 ): {
 	resolved: ReturnType<typeof resolveModel>;
-	placement?: Placement;
 	agent: AgentConfig;
 	modelOrigin: ModelOrigin;
 } {
@@ -1121,19 +1837,27 @@ function resolveStep(
 	});
 	return {
 		resolved: result.resolved,
-		...(params.placement ? { placement: params.placement as Placement } : {}),
 		agent: result.agent,
 		modelOrigin: result.modelOrigin,
 	};
 }
 
 /** Wait for each launched child's turn, appending its outcome. */
-async function collectInline(session: LaunchSession): Promise<void> {
+async function collectInline(session: LaunchSession, signal?: AbortSignal): Promise<void> {
 	for (const name of session.handles) {
+		if (signal?.aborted) {
+			session.results.push("interrupted (parent turn aborted)");
+			return;
+		}
 		try {
 			const collected = await session.orchestrator.collect(name, {
 				timeoutMs: session.timeoutByName.get(name) ?? DEFAULTS.turnTimeoutMs,
+				...(signal ? { signal } : {}),
 			});
+			if (signal?.aborted || collected.execution.reason === "aborted by parent") {
+				session.results.push("interrupted (parent turn aborted)");
+				return;
+			}
 			session.results.push(renderCollect(name, collected));
 		} catch (error) {
 			session.results.push(`✗ ${name}: collect failed: ${String(error)}`);
@@ -1159,6 +1883,334 @@ type Plan =
 	  }
 	| { ok: false; message: string };
 
+type UtilityTaskItem = Static<typeof TaskItem>;
+type VexillatioParams = Static<typeof VexillatioParams>;
+
+type UtilityPlan =
+	| { ok: true; steps: UtilityTaskItem[] }
+	| { ok: false; message: string };
+
+function buildUtilityPlan(params: VexillatioParams): UtilityPlan {
+	if (!params.task.trim()) return { ok: false, message: "`task` must not be blank." };
+	const steps: UtilityTaskItem[] = params.tasks?.length
+		? params.tasks
+		: [{ agent: params.agent?.trim() || "scout", task: params.task }];
+	const unsupportedVerify = steps.findIndex((item) => item.verify !== undefined);
+	if (unsupportedVerify >= 0) {
+		return {
+			ok: false,
+			message: `tasks[] step ${unsupportedVerify + 1} cannot include \`verify\`; vexillatio does not run verification commands.`,
+		};
+	}
+	const invalid = steps.findIndex((item) => !item.agent.trim() || !item.task.trim());
+	if (invalid >= 0) {
+		return { ok: false, message: `tasks[] step ${invalid + 1} must include non-blank \`agent\` and \`task\`.` };
+	}
+	return { ok: true, steps };
+}
+
+async function launchUtilityFamily(input: {
+	pi: ExtensionAPI;
+	ctx: ExtensionContext;
+	params: VexillatioParams;
+	runtime: SessionRuntime;
+	signal?: AbortSignal;
+	supervisor: LegionSupervisor;
+	uiProxy: UIProxy;
+	onBudgetRefused: NonNullable<ConstructorParameters<typeof Orchestrator>[0]["onBudgetRefused"]>;
+	cwd: string;
+	sessionCwd: string;
+	isChild: boolean;
+	legion?: LegionRuntimeIdentity;
+	eventBus: LegionEventBus;
+	onLegion: (identity: LegionRuntimeIdentity) => void;
+	onUtilityChild: (retire: () => Promise<void>) => void;
+}): Promise<AgentToolResult<unknown>> {
+	const plan = buildUtilityPlan(input.params);
+	if (!plan.ok) return fail(plan.message, ErrorCodes.INVALID_PARAMS);
+
+	const catalog = loadCatalog(input.sessionCwd, input.cwd, undefined);
+	const prepared: Array<{
+		step: UtilityTaskItem;
+		agent: AgentConfig;
+		resolved: ReturnType<typeof resolveStepModel>["resolved"];
+		modelOrigin: ModelOrigin;
+	}> = [];
+	for (const step of plan.steps) {
+		const selectedAgent = findAgent(catalog.agents, step.agent);
+		const fallbackAgent = findAgent(catalog.allAgents, step.agent);
+		const teamMembers = catalog.settings.teams?.[catalog.team.name]?.members ?? [];
+		const explicitlyMentionedByTeam = Boolean(
+			!selectedAgent &&
+			fallbackAgent &&
+			catalog.team.name !== DEFAULT_TEAM &&
+			teamMembers.some((member) => {
+				const reference = typeof member === "string" ? member.trim() : member.agent.trim();
+				if (reference === "*") return false;
+				return findAgent(catalog.allAgents, reference)?.name === fallbackAgent.name;
+			}),
+		);
+		if (explicitlyMentionedByTeam) {
+			return fail(
+				unknownAgentLineForCatalog(
+					catalog.agents,
+					catalog.allAgents,
+					step.agent,
+					catalog.team,
+					catalog.settings,
+				),
+				ErrorCodes.INVALID_PARAMS,
+			);
+		}
+		const agent = selectedAgent ?? fallbackAgent;
+		if (!agent?.utility) {
+			return fail(
+				`not a utility agent: ${step.agent} (mark it with 'utility: true')`,
+				ErrorCodes.INVALID_PARAMS,
+			);
+		}
+		if (agent.disabled) {
+			return fail(`utility agent is disabled: ${agent.name}`, ErrorCodes.DISABLED);
+		}
+		try {
+			const resolvedStep = resolveStepModel({
+				agent,
+				step: {
+					...(step.model !== undefined ? { model: step.model } : {}),
+					...(step.preset !== undefined ? { preset: step.preset } : {}),
+				},
+				params: { ...(input.params.model !== undefined ? { model: input.params.model } : {}) },
+				...(input.ctx.model ? { dispatchModel: `${input.ctx.model.provider}/${input.ctx.model.id}` } : {}),
+				settings: catalog.settings,
+			});
+			const violation = checkModelScope(
+				resolvedStep.resolved.model,
+				catalog.settings.modelScope,
+				resolvedStep.modelOrigin,
+			);
+			if (violation?.severity === "error") {
+				return fail(violation.message, ErrorCodes.INVALID_PARAMS);
+			}
+			prepared.push({
+				step,
+				agent: resolvedStep.agent,
+				resolved: resolvedStep.resolved,
+				modelOrigin: resolvedStep.modelOrigin,
+			});
+		} catch (error) {
+			return fail(`✗ ${step.agent}: ${error instanceof Error ? error.message : String(error)}`, ErrorCodes.INVALID_PARAMS);
+		}
+	}
+
+	const firstPrepared = prepared[0];
+	const runTask = prepared.length === 1 && firstPrepared
+		? firstPrepared.step.task
+		: `${prepared.length} parallel utility tasks`;
+	const rootStore = runStoreFor(input.cwd);
+	let legion = resolveLegionIdentity({
+		pi: input.pi,
+		supervisor: input.supervisor,
+		store: rootStore,
+		cwd: input.cwd,
+		settings: catalog.settings,
+		eventBus: input.eventBus,
+		cached: input.legion,
+		sessionFile: input.ctx.sessionManager?.getSessionFile(),
+	});
+	if (!legion && !input.isChild) {
+		legion = createRootLegion({
+			pi: input.pi,
+			supervisor: input.supervisor,
+			store: rootStore,
+			cwd: input.cwd,
+			task: `vexillatio: ${runTask}`,
+			settings: catalog.settings,
+			maxDepth: effectiveMaxDepth(catalog.settings.legion?.maxDepth),
+			eventBus: input.eventBus,
+		});
+	}
+	if (legion) input.onLegion(legion);
+
+	const store = legion?.runStore ?? rootStore;
+	const run = legion
+		? store.readRun(legion.runId)
+		: store.createRun({
+			task: runTask,
+			cwd: input.cwd,
+			maxDepth: effectiveMaxDepth(catalog.settings.legion?.maxDepth),
+			path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH),
+			herdr: { supervisor: "rpc" },
+		});
+	if (!run) return fail("vexillatio parent run is not available", ErrorCodes.NOT_FOUND);
+	const runId = run.runId;
+	const timeoutMs = input.params.timeoutMs ?? 600_000;
+	// §2.6: continue numbering from this parent's existing children only —
+	// do NOT scan store.listRuns() (that made names climb across sessions, #42).
+	const existingNames: string[] = legion
+		? getChildren(legion.db, legion.nodeId).map((child) => child.name)
+		: run.children.map((child) => child.name);
+	const allocated = allocateSiblingNames(
+		prepared.map((item) => item.agent.name),
+		existingNames,
+		(name) => input.supervisor.isAlive(name),
+	);
+	const names = new Map<UtilityTaskItem, string>();
+	for (let i = 0; i < prepared.length; i++) names.set(prepared[i]!.step, allocated[i]!);
+
+	const results: string[] = [];
+	const stillRunning = new Set<string>();
+	const launches = await Promise.all(prepared.map(async (item) => {
+		const cwd = item.step.cwd ? path.resolve(input.cwd, item.step.cwd) : input.cwd;
+		const orchestrator = new Orchestrator({
+			supervisor: input.supervisor,
+			uiProxy: input.uiProxy,
+			runDir: legion?.runDir ?? store.runDir(runId),
+			cwd,
+			maxDepth: catalog.settings.legion?.maxDepth,
+			maxSpawns: catalog.settings.maxSubagentSpawnsPerSession ?? null,
+			childContext: catalog.settings.childContext,
+			team: catalog.team,
+			onBudgetRefused: input.onBudgetRefused,
+			...(legion ? {
+				legion: {
+					db: legion.db,
+					dbPath: legion.dbPath,
+					nodeId: legion.nodeId,
+					runId,
+					parentNodeId: legion.parentNodeId,
+					parentRunId: legion.parentRunId ?? undefined,
+					runStore: store,
+					settings: legion.settings,
+					eventBus: legion.eventBus,
+				},
+			} : {}),
+		});
+		orchestrator.restore(run);
+		try {
+			const handle = await orchestrator.launch({
+				agent: item.agent,
+				task: item.step.task,
+				name: names.get(item.step),
+				...(item.resolved.model ? { model: item.resolved.model } : {}),
+				modelOrigin: item.modelOrigin,
+				...(item.step.worktree !== undefined ? { worktree: item.step.worktree } : {}),
+				utilityDispatch: true,
+				stripLegionIdentity: true,
+			});
+			await persistChild(store, runId, orchestrator, handle.name);
+			let retirement: Promise<void> | undefined;
+			const retire = (): Promise<void> => {
+				if (!retirement) {
+					const current = (async () => {
+						await orchestrator.retire(handle.name);
+						await persistChild(store, runId, orchestrator, handle.name);
+					})();
+					retirement = current;
+					void current.catch(() => {
+						if (retirement === current) retirement = undefined;
+					});
+				}
+				return retirement;
+			};
+			input.onUtilityChild(async () => {
+				try {
+					await retire();
+				} catch {
+					// Shutdown cleanup is best-effort; the supervisor owns final process state.
+				}
+			});
+			return {
+				item,
+				value: {
+					name: handle.name,
+					agent: item.agent.name,
+					sessionFile: handle.sessionFile,
+					orchestrator,
+					retire,
+				},
+			};
+		} catch (error) {
+			return {
+				item,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	}));
+	const handles: Array<{
+		name: string;
+		agent: string;
+		sessionFile: string;
+		orchestrator: Orchestrator;
+		retire: () => Promise<void>;
+	}> = [];
+	for (const launch of launches) {
+		if ("error" in launch) results.push(`✗ ${launch.item.agent.name}: ${launch.error}`);
+		else handles.push(launch.value);
+	}
+
+	const followUtility = (handle: (typeof handles)[number], watch: boolean): void => {
+		followJob(input.runtime, {
+			name: handle.name,
+			runId,
+			agent: handle.agent,
+			sessionFile: handle.sessionFile,
+			timeoutMs,
+			orchestrator: handle.orchestrator,
+			store,
+			watch,
+			retire: handle.retire,
+		});
+	};
+	for (const handle of handles) followUtility(handle, false);
+
+	const collected = await Promise.all(handles.map(async (handle) => {
+		try {
+			const result = await handle.orchestrator.collect(handle.name, {
+				timeoutMs,
+				...(input.signal ? { signal: input.signal } : {}),
+			});
+			await persistChild(store, runId, handle.orchestrator, handle.name);
+			if (result.blocked || !shouldRecycleAfterCollect(result.execution.status)) {
+				followUtility(handle, true);
+				stillRunning.add(handle.name);
+			} else {
+				await handle.retire();
+				input.runtime.release(handle.name);
+			}
+			const lines = [
+				`── ${handle.name} ──`,
+				`execution: ${result.execution.status}${result.execution.reason ? ` (${result.execution.reason})` : ""}`,
+				result.output || "(no output)",
+			];
+			if (result.outputFile) lines.push(`outputFile: ${result.outputFile}`);
+			lines.push(`sessionFile: ${handle.sessionFile}`);
+			return lines.join("\n");
+		} catch (error) {
+			if (input.supervisor.isAlive(handle.name)) {
+				followUtility(handle, true);
+				stillRunning.add(handle.name);
+			} else {
+				await handle.retire().catch(() => {});
+				input.runtime.release(handle.name);
+			}
+			return `✗ ${handle.name}: collect failed: ${error instanceof Error ? error.message : String(error)}\nsessionFile: ${handle.sessionFile}`;
+		}
+	}));
+	if (input.signal?.aborted) return ok("interrupted (parent turn aborted)");
+	results.push(...collected);
+	return {
+		content: [{ type: "text", text: results.join("\n\n") || "No utility agents were launched." }],
+		details: {
+			runId,
+			handles: handles.map(({ name, agent, sessionFile }) => ({ name, agent, sessionFile })),
+			async: false,
+			...(stillRunning.size > 0
+				? { stillRunning: handles.filter(({ name }) => stillRunning.has(name)).map(({ name }) => name) }
+				: {}),
+		},
+	};
+}
+
 export function buildPlan(params: {
 	agent?: string;
 	task?: string;
@@ -1169,8 +2221,10 @@ export function buildPlan(params: {
 		model?: string;
 		preset?: string;
 		worktree?: boolean;
+		verify?: string[];
 	}>;
 	worktree?: boolean;
+	verify?: string[];
 }): Plan {
 	const hasSingle = isPresent(params.agent) && isPresent(params.task);
 	const hasTasks = Boolean(params.tasks?.length);
@@ -1219,6 +2273,7 @@ interface PlanStep {
 	model?: string;
 	preset?: string;
 	worktree?: boolean;
+	verify?: string[];
 }
 
 /**
@@ -1264,13 +2319,14 @@ function followJob(
 		orchestrator: Orchestrator;
 		store: RunStore;
 		watch: boolean;
+		retire?: () => Promise<void>;
+		treeIdentity?: { nodeId: string; parentId: string | null; depth: number };
 	},
 ): void {
 	const child = input.orchestrator
 		.childrenSnapshot()
 		.find((entry) => entry.name === input.name);
 	const existing = runtime.get(input.name);
-	const nonPi = child?.kind && child.kind !== "pi";
 	runtime.track({
 		name: input.name,
 		runId: input.runId,
@@ -1281,14 +2337,24 @@ function followJob(
 		...(child?.model ? { model: child.model } : {}),
 		...(child?.thinking !== undefined ? { thinking: child.thinking } : {}),
 		...(child?.worktreeBranch ? { worktreeBranch: child.worktreeBranch } : {}),
-		...(nonPi
-			? { probe: () => input.orchestrator.probeProgress(input.name) }
-			: {}),
-		collect: () =>
-			input.orchestrator.collect(input.name, { timeoutMs: input.timeoutMs }),
+		...(input.treeIdentity ? input.treeIdentity : child?.nodeId ? {
+			nodeId: child.nodeId,
+			parentId: child.nodeId.includes(".") ? child.nodeId.slice(0, child.nodeId.lastIndexOf(".")) : null,
+			depth: child.nodeId.split(".").length - 1,
+		} : {}),
+		collect: (opts) =>
+			input.orchestrator.collect(input.name, {
+				timeoutMs: input.timeoutMs,
+				...(opts?.signal ? { signal: opts.signal } : {}),
+			}),
+		isAlive: () => input.orchestrator.isChildAlive(input.name),
 		persist: async () =>
 			persistChild(input.store, input.runId, input.orchestrator, input.name),
 		retire: async () => {
+			if (input.retire) {
+				await input.retire();
+				return;
+			}
 			await input.orchestrator.retire(input.name);
 			await persistChild(
 				input.store,
@@ -1337,6 +2403,13 @@ function followChild(ctx: ChildContext, opts: { watch: boolean }): void {
 		orchestrator: ctx.orchestrator,
 		store: ctx.store,
 		watch: opts.watch,
+		...(ctx.found.child.nodeId ? {
+			treeIdentity: {
+				nodeId: ctx.found.child.nodeId,
+				parentId: ctx.found.child.nodeId.includes(".") ? ctx.found.child.nodeId.slice(0, ctx.found.child.nodeId.lastIndexOf(".")) : null,
+				depth: ctx.found.child.nodeId.split(".").length - 1,
+			},
+		} : {}),
 	});
 }
 
@@ -1357,6 +2430,13 @@ function followLaunched(
 		orchestrator: session.orchestrator,
 		store: session.store,
 		watch: opts.watch,
+		...(child?.nodeId ? {
+			treeIdentity: {
+				nodeId: child.nodeId,
+				parentId: child.nodeId.includes(".") ? child.nodeId.slice(0, child.nodeId.lastIndexOf(".")) : null,
+				depth: child.nodeId.split(".").length - 1,
+			},
+		} : {}),
 	});
 }
 
@@ -1372,13 +2452,44 @@ async function persistChild(
 	runId: string,
 	orchestrator: Orchestrator,
 	name: string,
+	opts: { preserveRetired?: boolean } = {},
 ): Promise<void> {
 	const child = orchestrator.childrenSnapshot().find((c) => c.name === name);
 	if (!child) return;
 	try {
-		await store.updateChild(runId, name, (c) => Object.assign(c, child));
+		const recorded = store.findChild(runId, name);
+		if (!recorded) {
+			await store.addChild(runId, child);
+			return;
+		}
+		if (recorded.nodeId !== child.nodeId) return;
+		await store.updateChild(runId, name, (current) => {
+			if (opts.preserveRetired && current.state === "retired" && child.state !== "retired") return;
+			Object.assign(current, child);
+		});
 	} catch {
-		// Not persisted yet (or already removed) — the caller's own addChild wins.
+		// Persistence is best-effort when a competing lifecycle callback wins the write.
+	}
+}
+
+async function abandonLaunchedChild(session: LaunchSession, name: string): Promise<void> {
+	const child = session.orchestrator.childrenSnapshot().find((entry) => entry.name === name);
+	if (!child) return;
+	if (child.state === "retired") {
+		session.runtime.release(name);
+		return;
+	}
+	child.execution = { status: "failed", reason: "launch abandoned because parent turn aborted" };
+	child.acceptance = { status: "rejected", level: "none", reason: "aborted by parent" };
+	try {
+		await session.orchestrator.retire(name);
+		await persistChild(session.store, session.runId, session.orchestrator, name);
+		session.runtime.release(name);
+		session.results.push(`✗ ${name}: abandoned because parent turn aborted (child retired)`);
+	} catch (error) {
+		await persistChild(session.store, session.runId, session.orchestrator, name);
+		followLaunched(session, name, { watch: true });
+		session.results.push(`✗ ${name}: abandon retire failed: ${String(error)}; completion remains watched`);
 	}
 }
 
@@ -1421,6 +2532,7 @@ export function resolveWaitTargets(
 export function renderWait(results: WaitResult[]): string {
 	let done = 0;
 	let running = 0;
+	let interrupted = 0;
 	const parts: string[] = [];
 	for (const result of results) {
 		if (result.snapshot) {
@@ -1429,23 +2541,83 @@ export function renderWait(results: WaitResult[]): string {
 		} else if (result.stillRunning) {
 			running += 1;
 			parts.push(`── ${result.name} ──\nstill running`);
+		} else if (result.interrupted) {
+			interrupted += 1;
+			parts.push(`── ${result.name} ──\ninterrupted (parent turn aborted)`);
 		} else {
 			parts.push(`── ${result.name} ──\nnot tracked (no live job, no finished cache)`);
 		}
 	}
 	parts.push(`${done} done, ${running} still running`);
+	if (interrupted > 0) parts.push(`${interrupted} interrupted`);
 	return parts.join("\n");
 }
 
+/** Gracefully retire a named child or every child tracked by this session. */
+export async function stopAction(input: {
+	params: { name?: string; all?: boolean };
+	runtime: SessionRuntime;
+	retire: (name: string) => Promise<void>;
+}): Promise<AgentToolResult<unknown>> {
+	const { params, runtime, retire } = input;
+	if (params.name && params.all) {
+		return fail("`name` and `all` are mutually exclusive for stop.", ErrorCodes.INVALID_PARAMS);
+	}
+	if (!params.name && !params.all) {
+		return fail("`name` or `all` is required for stop", ErrorCodes.INVALID_PARAMS);
+	}
+	const jobs = runtime.activeJobs();
+	const active = jobs.filter((job) => job.state !== "retired");
+	let targets: string[];
+	if (params.all) {
+		targets = active.map((job) => job.name);
+	} else {
+		const target = jobs.find((job) => job.name === params.name);
+		if (!target) {
+			return fail(`unknown child: ${params.name} (not tracked by this session).`, ErrorCodes.NOT_FOUND);
+		}
+		targets = target.state === "retired" ? [] : [target.name];
+	}
+	if (targets.length === 0) return ok("No non-retired children to stop.");
+
+	// Stop every watcher before any retire starts: a later target must not finish
+	// its own watch (and notify/release) while an earlier target is being retired.
+	for (const name of targets) runtime.cancelWatch(name);
+
+	const stopped: string[] = [];
+	const failures: string[] = [];
+	for (const name of targets) {
+		try {
+			// The runtime job may have been released after the target snapshot was
+			// taken. The retire adapter can then resolve its persisted run record.
+			await retire(name);
+			runtime.release(name);
+			stopped.push(name);
+		} catch (error) {
+			// If the graceful-retire chain fails, restore the completion watcher so a
+			// still-live child is not orphaned by the explicit stop attempt.
+			if (runtime.get(name)) runtime.rewatch(name);
+			failures.push(`${name}: ${String(error)}`);
+		}
+	}
+	const summary = stopped.length
+		? `Stopped ${stopped.length} child${stopped.length === 1 ? "" : "ren"}: ${stopped.join(", ")}.`
+		: "No children were stopped.";
+	return failures.length
+		? fail(`${summary}\nFailed to stop: ${failures.join("; ")}`, ErrorCodes.RETIRE_FAILED)
+		: ok(summary);
+}
+
 export async function waitAction(input: {
 	params: SubagentParams;
+	signal?: AbortSignal;
 	runtime: SessionRuntime;
 	agents: AgentConfig[];
 	allAgents?: AgentConfig[];
 	store: RunStore;
 	cwd: string;
 }): Promise<AgentToolResult<unknown>> {
-	const { params, runtime, agents, allAgents = agents, store, cwd } = input;
+	const { params, signal, runtime, agents, allAgents = agents, store, cwd } = input;
 	const jobs = runtime.activeJobs();
 	let targets = resolveWaitTargets(
 		{ name: params.name, all: params.all },
@@ -1480,7 +2652,7 @@ export async function waitAction(input: {
 				);
 			}),
 		);
-	const results = await runtime.wait(targets.names, { timeoutMs });
+	const results = await runtime.wait(targets.names, { timeoutMs, ...(signal ? { signal } : {}) });
 	return ok(renderWait(results));
 }
 
@@ -1559,9 +2731,7 @@ function findChild(
 	run: ReturnType<RunStore["listRuns"]>[number];
 	child: NonNullable<ReturnType<RunStore["findChild"]>>;
 } | null {
-	const picked = pickChildByName(runs, name, {
-		parentPaneId: process.env.HERDR_PANE_ID,
-	});
+	const picked = pickChildByName(runs, name);
 	if (!picked) return null;
 	return { runId: picked.run.runId, run: picked.run, child: picked.child };
 }
@@ -1572,7 +2742,7 @@ function renderChild(
 ): AgentToolResult<unknown> {
 	const lines = [
 		`${child.name} — state=${child.state} agent=${child.agent ?? "?"} kind=${child.kind ?? "?"}`,
-		`pane=${child.paneId ?? "(recycled)"}`,
+		"supervisor=rpc",
 		`session=${child.sessionFile}`,
 	];
 	if (child.execution) {
@@ -1603,6 +2773,7 @@ function renderCollect(
 		acceptance: {
 			status: string;
 			level?: string;
+			reason?: string;
 			pendingCriteria?: Array<{
 				id: string;
 				must: string;
@@ -1617,9 +2788,14 @@ function renderCollect(
 		`execution: ${collected.execution.status}${collected.execution.reason ? ` (${collected.execution.reason})` : ""}`,
 		`acceptance: ${collected.acceptance.status}${collected.acceptance.level ? ` (${collected.acceptance.level})` : ""}`,
 	];
+	// The mechanical verify outcome (which command failed / which commands had
+	// to pass) is the parent's primary trust anchor — surface it inline.
+	if (collected.acceptance.reason && /^(verified by|verification failed)/.test(collected.acceptance.reason)) {
+		lines.push(collected.acceptance.reason);
+	}
 	if (collected.blocked) {
 		lines.push(
-			"blocked: waiting for a tool approval — the pane is still open. Approve in the parent confirm, or steer the child.",
+			"blocked: waiting for child UI approval. Answer the pending request in the parent UI, or steer the child.",
 		);
 	}