pi-legion 3.0.1 → 3.1.0

package/index.ts

@@ -83,6 +83,7 @@ import {
 	SUBAGENT_NOTIFY_TYPE,
 } from "./src/extension/notify.ts";
 import { renderSubagentNotice } from "./src/extension/notice-renderer.ts";
+import { renderSpawnResult } from "./src/extension/spawn-render.ts";
 import { PARENT_PLAYBOOK, TOOL_DESCRIPTION } from "./src/extension/playbook.ts";
 import { configureSessionErrors, recordSessionError } from "./src/extension/session-errors.ts";
 import { getAgentDir } from "./src/agents/paths.ts";
@@ -94,6 +95,7 @@ import {
 	type OrchestratorLegionContext,
 } from "./src/runs/orchestrator.ts";
 import { RunStore, pickChildByName } from "./src/runs/store.ts";
+import { RUN_OWNER_FILE, ownerState } from "./src/runs/owner.ts";
 import { resolveLaunchWorktree } from "./src/runs/worktree.ts";
 import {
 	type AgentConfig,
@@ -103,6 +105,7 @@ import {
 	ErrorCodes,
 	type ModelOrigin,
 	type RetireOptions,
+	type SpawnMode,
 	SubagentError,
 	type SubagentsSettings,
 } from "./src/shared/types.ts";
@@ -122,7 +125,7 @@ const TaskItem = Type.Object({
 	worktree: Type.Optional(
 		Type.Boolean({
 			description:
-				"Parent decides isolation for this child. true = own git branch, child opens an MR. false = write the current checkout.",
+				"Parent decides isolation for this child. true = own git branch, child opens an MR. false = write the current checkout. Reserved for `centurion` (#214): any other role asking for true is downgraded to false with a one-time warning.",
 		}),
 	),
 	verify: Type.Optional(
@@ -174,7 +177,7 @@ const SubagentParams = Type.Object({
 	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).",
+				"Parent decides isolation. true = isolated git branch, child opens an MR. false = edit the current checkout. Reserved for `centurion` (#214): only a centurion gets a subtree worktree, every other role is downgraded to false with a one-time warning — dispatch a centurion when you need an isolated delivery unit.",
 		}),
 	),
 	verify: Type.Optional(
@@ -293,6 +296,19 @@ function runStoreFor(cwd: string, dbPathOverride?: string): RunStore {
 	return new RunStore({ rootDir: path.join(cwd, ".pi-subagents") });
 }
 
+/**
+ * Backend THIS process was started on (#209), for `run.json`'s `herdr.supervisor`.
+ *
+ * A host/root session and an RPC child are both ordinary `pi` processes, so the
+ * historic `rpc` marker is the truth for them. An in-process child shares this
+ * process, and its backend travels on the ALS child context — the one case where
+ * the truthful marker is not `rpc`. Reading it from there (instead of writing a
+ * literal) is what stops the record from claiming RPC for an inprocess child.
+ */
+function currentProcessSpawnMode(): SpawnMode {
+	return currentChildContext()?.spawnMode ?? "rpc";
+}
+
 function notice(pi: ExtensionAPI, text: string): void {
 	pi.sendMessage({ customType: SUBAGENT_NOTIFY_TYPE, content: text, display: true }, { triggerTurn: true, deliverAs: "followUp" });
 }
@@ -399,6 +415,9 @@ function resolveLegionIdentity(input: {
 		const nodeRuns = input.store.listRuns().filter((run) => run.nodeId === nodeId || run.herdr.node_id === nodeId);
 		let nodeRun = nodeRuns.at(-1);
 		if (!nodeRun) {
+			// Contract D3: a run synthesized while attaching to an already-existing
+			// node has no launch arbitration behind it, so it keeps the historic
+			// marker instead of inventing a backend.
 			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);
@@ -442,7 +461,7 @@ async function resumeLegionTeam(input: { identity: LegionRuntimeIdentity; input:
 }
 
 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 rootRun = input.store.createRun({ task: input.task, cwd: input.cwd, maxDepth: input.maxDepth, nodeId: "root", herdr: { supervisor: currentProcessSpawnMode() } });
 	const dbPath = path.resolve(legionDbPath(input.store.runDir(rootRun.runId)));
 	const db = openLegionDb(dbPath);
 	const now = Date.now();
@@ -692,6 +711,9 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			label: "Vexillatio",
 			description: "Launch only read-only utility agents and return their collected output.",
 			parameters: VexillatioParams,
+			// D4: pi never renders `details` on its own, so without this the
+			// arbitrated spawnMode in `details.handles[].spawnMode` is invisible.
+			renderResult: (result, opts, theme) => renderSpawnResult(result, opts, theme),
 			async execute(_id, params, signal, _onUpdate, ctx: ExtensionContext): Promise<AgentToolResult<unknown>> {
 				if (signal?.aborted) {
 					return ok("interrupted (parent turn ended; children still running)");
@@ -722,9 +744,10 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 					},
 					onUtilityChild: (retire) => pendingUtilityRetires.push(retire),
 				});
-				if (signal?.aborted) {
-					return ok("interrupted (parent turn ended; children still running)");
-				}
+				// `launchUtilityFamily` already folds the abort into its own return
+				// (head line + collected segments + `interrupted` details, #227 D4).
+				// Returning `result` unconditionally is what keeps that work visible;
+				// re-checking `signal.aborted` here would throw it away again.
 				return result;
 			},
 		});
@@ -760,10 +783,9 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 	const childActivitySources = new Set<string>();
 	let statusNodeOpener: ((nodeId: string) => void) | undefined;
 	let lastConfirm: ((message: string) => Promise<boolean>) | undefined;
-	// 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;
+	// Run-scoped completion deferral lives in the runtime outbox (D-A): a child
+	// finishing while this agent run is still active is held until
+	// `agent_settled` instead of being queued as an undrained followUp.
 	const rpcEventSource = supervisor as LegionSupervisor & RpcEventSource;
 	const runtime = createSessionRuntime({
 		sendMessage: (message, options) => pi.sendMessage(message, options),
@@ -957,6 +979,9 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		description: TOOL_DESCRIPTION,
 		parameters: SubagentParams,
 
+		// D4: the same renderer as `vexillatio` — it reads both detail shapes.
+		renderResult: (result, opts, theme) => renderSpawnResult(result, opts, theme),
+
 		// The parameter list is fixed by Pi's `ExtensionAPI.registerTool`
 		// contract — an options object is not ours to choose.
 		// pi-lens-ignore: long-parameter-list
@@ -999,7 +1024,6 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			runtime.setJoinConfig({
 				mode: settings.joinMode ?? DEFAULT_JOIN_MODE,
 				flushMs: settings.joinFlushMs ?? DEFAULT_FLUSH_MS,
-				parentBusy: () => parentTurnActive,
 			});
 
 			if (action === "list") return ok(renderAgentList(agents, team, teamWarnings));
@@ -1104,7 +1128,18 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 				onUpdate,
 			});
 			if (signal?.aborted) {
-				return ok("interrupted (parent turn ended; children still running)");
+				// The frozen head line still leads, but the machine facts must
+				// survive: `launchFamily` already returns its own interrupted result
+				// (frozen head + `runId` + `spawns`) when it observes the abort; this
+				// outer net only catches an abort seen after that check. Replacing the
+				// whole result with a bare `ok()` used to drop `details.spawns` — the
+				// only record of the arbitrated backend once `handles` is cleared (#209/D3).
+				const details = result.details;
+				const carried =
+					details !== null && typeof details === "object" && !Array.isArray(details)
+						? (details as Record<string, unknown>)
+						: undefined;
+				return ok("interrupted (parent turn ended; children still running)", carried);
 			}
 			return result;
 		},
@@ -1175,19 +1210,22 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 	});
 	pi.on("session_info_changed", bindUi);
 	pi.on("turn_start", (event, ctx) => {
-		parentTurnActive = true;
 		bindUi(event, ctx);
 	});
 	pi.on("turn_end", (event, ctx) => {
-		parentTurnActive = false;
 		bindUi(event, ctx);
 	});
 	pi.on("agent_start", (event, ctx) => {
+		runtime.notifyParentRunStart();
 		bindUi(event, ctx);
 	});
 	pi.on("agent_end", (event, ctx) => {
 		bindUi(event, ctx);
 	});
+	pi.on("agent_settled", (event, ctx) => {
+		runtime.notifyParentSettled();
+		bindUi(event, ctx);
+	});
 	pi.on("input", bindUi);
 	pi.on("tool_result", (_event, ctx) => {
 		bindUi(_event, ctx);
@@ -1317,6 +1355,7 @@ async function controlAction(input: {
 		return stopAction({
 			params,
 			runtime: input.runtime,
+			store: input.store,
 			retire: async (name, opts) => {
 				const merged = opts ?? retireOpts;
 				const job = input.runtime.get(name);
@@ -1358,18 +1397,23 @@ async function controlAction(input: {
 			);
 		}
 		if (!params.name) {
-			const live = listLiveChildrenForStatus(store.listRuns());
+			const runs = store.listRuns();
+			const live = listLiveChildrenForStatus(runs);
 			return ok(
 				renderStatusOverview(
-					live.map((child) => ({
-						child,
-						alive: input.supervisor.isAlive(child.name),
-					})),
+					live.map((child) => {
+						const alive = input.supervisor.isAlive(child.name);
+						const owner = ownerVerdictFor(store, runs, child.name, alive);
+						return { child, alive, ...(owner ? { owner } : {}) };
+					}),
 				),
 			);
 		}
-		const found = findChild(store.listRuns(), params.name);
+		const runs = store.listRuns();
+		const found = findChild(runs, params.name);
 		if (!found) return unknownChild(params.name, store, cwd);
+		const alive = input.supervisor.isAlive(params.name);
+		const owner = ownerVerdictFor(store, runs, params.name, alive);
 		return ok(renderLiveChildStatus({
 			name: found.child.name,
 			state: found.child.state,
@@ -1378,7 +1422,9 @@ async function controlAction(input: {
 			sessionFile: found.child.sessionFile,
 			execution: found.child.execution,
 			acceptance: found.child.acceptance,
-			alive: input.supervisor.isAlive(params.name),
+			spawnMode: found.child.spawnMode,
+			alive,
+			...(owner ? { owner } : {}),
 		}));
 	}
 
@@ -1526,7 +1572,7 @@ async function collectChild(
 	}
 }
 
-/** Retire the RPC child while preserving its outcome and session for resume. */
+/** Retire the child while preserving its outcome and session for resume. */
 async function retireChild(
 	ctx: ChildContext,
 ): Promise<AgentToolResult<unknown>> {
@@ -1543,7 +1589,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"}). ` +
-				`RPC process stopped; session kept for resume: ${child.sessionFile}`,
+				`Child stopped; session kept for resume: ${child.sessionFile}`,
 		);
 	} catch (error) {
 		return fail(`retire failed: ${String(error)}`, ErrorCodes.RETIRE_FAILED);
@@ -1585,7 +1631,7 @@ async function reviveChild(
 			await orchestrator.steer(name, params.message);
 			followChild(ctx, { watch: true });
 			return ok(
-				`${action === "resume" ? "Resumed" : "Continued"} ${name} (live RPC child steered).`,
+				`${action === "resume" ? "Resumed" : "Continued"} ${name} (live child steered).`,
 			);
 		}
 
@@ -1638,7 +1684,7 @@ async function launchFamily(input: {
 		content: [
 			{
 				type: "text",
-				text: `playbook: ${plan.steps.map((s) => s.agent).join(", ")} → RPC launch → watch`,
+				text: `playbook: ${plan.steps.map((s) => s.agent).join(", ")} → launch → watch`,
 			},
 		],
 		details: {},
@@ -1652,7 +1698,7 @@ async function launchFamily(input: {
 			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 } }),
+			...(legion ? { path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH), nodeId: legion.nodeId, herdr: { supervisor: currentProcessSpawnMode(), node_id: legion.nodeId } } : { herdr: { supervisor: currentProcessSpawnMode() } }),
 		});
 		if (legion && legion.nodeId !== "root" && legion.parentRunId) {
 			const node = getNode(legion.db, legion.nodeId);
@@ -1714,16 +1760,26 @@ async function launchFamily(input: {
 		results: [],
 		handles: [],
 		timeoutByName: new Map(),
+		// #209/D3: the arbitrated mode survives `handles` being cleared on an
+		// abort (interrupted results run after that), so it is kept per name
+		// here — same precedent as `timeoutByName`.
+		spawnByName: new Map(),
 		...(nameGate.name ? { launchName: nameGate.name } : {}),
 	};
 
+	/** `details.spawns` for the handles this request actually resolved. */
+	const spawnDetails = () => {
+		const spawns = [...session.spawnByName.values()];
+		return spawns.length > 0 ? { spawns } : {};
+	};
+
 	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 ended; children still running)" }],
-			details: { runId: run.runId, handles: [], async: params.async ?? true },
+			details: { runId: run.runId, handles: [], async: params.async ?? true, ...spawnDetails() },
 		};
 	};
 
@@ -1770,13 +1826,13 @@ async function launchFamily(input: {
 
 	if (isAsync && session.handles.length > 0) {
 		session.results.push(
-			"↳ 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.",
+			"↳ async: a completion message is queued when each 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.",
 		);
 	}
 
 	return {
 		content: [{ type: "text", text: session.results.join("\n") }],
-		details: { runId: run.runId, handles: session.handles, async: isAsync },
+		details: { runId: run.runId, handles: session.handles, async: isAsync, ...spawnDetails() },
 	};
 }
 
@@ -1800,6 +1856,8 @@ interface LaunchSession {
 	results: string[];
 	handles: string[];
 	timeoutByName: Map<string, number>;
+	/** Arbitrated backend per resolved handle; survives an abort clearing `handles`. */
+	spawnByName: Map<string, { name: string; agent: string; spawnMode: SpawnMode }>;
 	/** Explicit child name for this single-step launch; omit to auto-allocate. */
 	launchName?: string;
 }
@@ -1911,6 +1969,13 @@ async function launchStep(
 			await session.store.addChild(session.runId, handle.child);
 		}
 		session.handles.push(handle.name);
+		// Recorded before the abort check below: an interrupted result runs after
+		// `handles` is cleared and still has to name the arbitrated backend.
+		session.spawnByName.set(handle.name, {
+			name: handle.name,
+			agent: effective.name,
+			spawnMode: handle.spawnMode,
+		});
 		if (effective.timeoutMs !== undefined) {
 			session.timeoutByName.set(handle.name, effective.timeoutMs);
 		}
@@ -1919,7 +1984,7 @@ async function launchStep(
 			return;
 		}
 		session.results.push(
-			`▶ ${handle.name} (${effective.name}) supervisor=rpc`,
+			`▶ ${handle.name} (${effective.name}) supervisor=${handle.spawnMode}`,
 		);
 		// 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
@@ -1935,7 +2000,7 @@ async function launchStep(
 			content: [
 				{
 					type: "text",
-					text: `playbook: ${handle.name} started via RPC`,
+					text: `playbook: ${handle.name} started (supervisor=${handle.spawnMode})`,
 				},
 			],
 			details: {},
@@ -2226,7 +2291,7 @@ async function launchUtilityFamily(input: {
 			cwd: input.cwd,
 			maxDepth: effectiveMaxDepth(catalog.settings.legion?.maxDepth),
 			path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH),
-			herdr: { supervisor: "rpc" },
+			herdr: { supervisor: currentProcessSpawnMode() },
 		});
 	if (!run) return fail("vexillatio parent run is not available", ErrorCodes.NOT_FOUND);
 	const runId = run.runId;
@@ -2315,6 +2380,7 @@ async function launchUtilityFamily(input: {
 					name: handle.name,
 					agent: item.agent.name,
 					sessionFile: handle.sessionFile,
+					spawnMode: handle.spawnMode,
 					orchestrator,
 					retire,
 				},
@@ -2330,6 +2396,7 @@ async function launchUtilityFamily(input: {
 		name: string;
 		agent: string;
 		sessionFile: string;
+		spawnMode: SpawnMode;
 		orchestrator: Orchestrator;
 		retire: (opts?: RetireOptions) => Promise<void>;
 	}> = [];
@@ -2345,6 +2412,8 @@ async function launchUtilityFamily(input: {
 			agent: handle.agent,
 			sessionFile: handle.sessionFile,
 			timeoutMs,
+			// Arbitrated at launch; never re-derived here (#209).
+			spawnMode: handle.spawnMode,
 			orchestrator: handle.orchestrator,
 			store,
 			watch,
@@ -2386,13 +2455,19 @@ async function launchUtilityFamily(input: {
 			return `✗ ${handle.name}: collect failed: ${error instanceof Error ? error.message : String(error)}\nsessionFile: ${handle.sessionFile}`;
 		}
 	}));
-	if (input.signal?.aborted) return ok("interrupted (parent turn ended; children still running)");
+	if (input.signal?.aborted) return interruptedUtilityResult({
+		runId,
+		handles,
+		stillRunning,
+		results,
+		collected,
+	});
 	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 })),
+			handles: handles.map(({ name, agent, sessionFile, spawnMode }) => ({ name, agent, sessionFile, spawnMode })),
 			async: false,
 			...(stillRunning.size > 0
 				? { stillRunning: handles.filter(({ name }) => stillRunning.has(name)).map(({ name }) => name) }
@@ -2401,6 +2476,46 @@ async function launchUtilityFamily(input: {
 	};
 }
 
+/**
+ * Build the interrupted vexillatio result from what the collect loop already produced.
+ *
+ * `#227 D4`: an abort must not throw away work that already finished. The frozen
+ * head line stays first and verbatim (`test/unit/teams.test.ts` matches it with a
+ * regex), the collected segments are appended below it, and `details` carries the
+ * same machine facts a non-interrupted return publishes plus `interrupted: true`.
+ *
+ * With no handles (every launch failed) the text degrades to the head line plus
+ * the failure lines only — no empty segment.
+ */
+function interruptedUtilityResult(input: {
+	runId: string;
+	handles: Array<{ name: string; agent: string; sessionFile: string; spawnMode?: SpawnMode }>;
+	stillRunning: Set<string>;
+	results: string[];
+	collected: string[];
+}): AgentToolResult<unknown> {
+	const head = "interrupted (parent turn ended; children still running)";
+	const segments = [...input.results, ...input.collected].filter((segment) => segment.length > 0);
+	const stillRunning = input.handles
+		.filter(({ name }) => input.stillRunning.has(name))
+		.map(({ name }) => name);
+	// Routed through `ok()` so the widened `details` parameter has exactly one
+	// real consumer instead of being a dead signature (#227 review F3).
+	return ok(segments.length > 0 ? `${head}\n\n${segments.join("\n\n")}` : head, {
+		runId: input.runId,
+		handles: input.handles.map(({ name, agent, sessionFile, spawnMode }) => ({
+			name,
+			agent,
+			sessionFile,
+			// Optional on purpose: a legacy handle must render as absent, never `rpc`.
+			...(spawnMode ? { spawnMode } : {}),
+		})),
+		async: false,
+		interrupted: true,
+		...(stillRunning.length > 0 ? { stillRunning } : {}),
+	});
+}
+
 /**
  * Resolve an explicit `name=` on launch.
  *
@@ -2546,12 +2661,17 @@ function followJob(
 		watch: boolean;
 		retire?: (opts?: RetireOptions) => Promise<void>;
 		treeIdentity?: { nodeId: string; parentId: string | null; depth: number };
+		/** Arbitrated backend from `Handle.spawnMode`; omitted when unknown (#209). */
+		spawnMode?: SpawnMode;
 	},
 ): void {
 	const child = input.orchestrator
 		.childrenSnapshot()
 		.find((entry) => entry.name === input.name);
 	const existing = runtime.get(input.name);
+	// The caller's Handle owns the arbitration; the persisted ChildRecord records
+	// the same decision. Neither is re-derived here — no handle, no value.
+	const spawnMode = input.spawnMode ?? child?.spawnMode;
 	runtime.track({
 		name: input.name,
 		runId: input.runId,
@@ -2562,6 +2682,7 @@ function followJob(
 		...(child?.model ? { model: child.model } : {}),
 		...(child?.thinking !== undefined ? { thinking: child.thinking } : {}),
 		...(child?.worktreeBranch ? { worktreeBranch: child.worktreeBranch } : {}),
+		...(spawnMode ? { spawnMode } : {}),
 		...(input.treeIdentity ? input.treeIdentity : child?.nodeId ? {
 			nodeId: child.nodeId,
 			parentId: child.nodeId.includes(".") ? child.nodeId.slice(0, child.nodeId.lastIndexOf(".")) : null,
@@ -2638,6 +2759,19 @@ function followChild(ctx: ChildContext, opts: { watch: boolean }): void {
 	});
 }
 
+/**
+ * The arbitrated backend recorded for one handled child of this request.
+ *
+ * Spreads to nothing when unknown, so the caller never has to invent a value.
+ */
+function spawnModeOf(
+	session: LaunchSession,
+	name: string,
+): { spawnMode?: SpawnMode } {
+	const recorded = session.spawnByName.get(name);
+	return recorded ? { spawnMode: recorded.spawnMode } : {};
+}
+
 function followLaunched(
 	session: LaunchSession,
 	name: string,
@@ -2655,6 +2789,8 @@ function followLaunched(
 		orchestrator: session.orchestrator,
 		store: session.store,
 		watch: opts.watch,
+		// Handle-derived, recorded before an abort can clear `handles` (#209).
+		...spawnModeOf(session, name),
 		...(child?.nodeId ? {
 			treeIdentity: {
 				nodeId: child.nodeId,
@@ -2742,11 +2878,13 @@ export function renderStatusOverview(
 	children: Array<{
 		child: NonNullable<ReturnType<RunStore["findChild"]>>;
 		alive: boolean;
+		/** Run-dir ownership verdict (#209-3); see {@link renderLiveChildStatus}. */
+		owner?: "live" | "dead" | "unknown";
 	}>,
 ): string {
 	if (children.length === 0) return "No live children.";
 	const noun = children.length === 1 ? "child" : "children";
-	const blocks = children.map(({ child, alive }) =>
+	const blocks = children.map(({ child, alive, owner }) =>
 		renderLiveChildStatus({
 			name: child.name,
 			state: child.state,
@@ -2755,7 +2893,9 @@ export function renderStatusOverview(
 			sessionFile: child.sessionFile,
 			execution: child.execution,
 			acceptance: child.acceptance,
+			spawnMode: child.spawnMode,
 			alive,
+			...(owner ? { owner } : {}),
 		}),
 	);
 	return [`Status · ${children.length} live ${noun}`, "", blocks.join("\n\n")].join("\n");
@@ -2882,6 +3022,26 @@ export function renderWait(results: WaitResult[]): string {
 	return parts.join("\n");
 }
 
+/**
+ * Run-dir ownership verdict for a child THIS process does not track (#209-3).
+ *
+ * `supervisor.isAlive` is an in-memory registry of children spawned by this
+ * process, so it is always false for a foreign run (another session, or a
+ * restart). The run dir's `owner.json` pid is the durable liveness marker; it
+ * only needs to be consulted when the in-memory answer is "not alive".
+ */
+function ownerVerdictFor(
+	store: RunStore,
+	runs: ReturnType<RunStore["listRuns"]>,
+	name: string,
+	alive: boolean,
+): "live" | "dead" | "unknown" | undefined {
+	if (alive) return undefined;
+	const picked = pickChildByName(runs, name);
+	if (!picked) return "unknown";
+	return ownerState(path.join(store.runDir(picked.run.runId), RUN_OWNER_FILE));
+}
+
 /**
  * Retire a named child or every child tracked by this session.
  * `force: true` → hard path (graceful:false / SIGTERM→SIGKILL); omit/false → graceful.
@@ -2889,6 +3049,11 @@ export function renderWait(results: WaitResult[]): string {
 export async function stopAction(input: {
 	params: { name?: string; all?: boolean; force?: boolean };
 	runtime: SessionRuntime;
+	/**
+	 * Run store used to resolve a named target this session does not track
+	 * (foreign/restarted runs). Omitted callers keep the runtime-only scope.
+	 */
+	store?: RunStore;
 	retire: (name: string, opts?: RetireOptions) => Promise<void>;
 }): Promise<AgentToolResult<unknown>> {
 	const { params, runtime, retire } = input;
@@ -2906,11 +3071,21 @@ export async function stopAction(input: {
 	if (params.all) {
 		targets = active.map((job) => job.name);
 	} else {
-		const target = jobs.find((job) => job.name === params.name);
+		// Local const so the earlier `name`/`all` guard narrows through the lookup.
+		const name = params.name;
+		const target = name ? jobs.find((job) => job.name === name) : undefined;
 		if (!target) {
-			return fail(`unknown child: ${params.name} (not tracked by this session).`, ErrorCodes.NOT_FOUND);
+			// Not tracked by this session, but a foreign/restarted run may still
+			// own a persisted record — the same records `status` can display. Fall
+			// back to it so stop and retire agree on what is reachable.
+			const found = input.store && name ? findChild(input.store.listRuns(), name) : null;
+			if (!found) {
+				return fail(`unknown child: ${params.name} (not tracked by this session).`, ErrorCodes.NOT_FOUND);
+			}
+			targets = found.child.state === "retired" ? [] : [found.child.name];
+		} else {
+			targets = target.state === "retired" ? [] : [target.name];
 		}
-		targets = target.state === "retired" ? [] : [target.name];
 	}
 	if (targets.length === 0) return ok("No non-retired children to stop.");
 
@@ -3080,34 +3255,6 @@ function findChild(
 	return { runId: picked.run.runId, run: picked.run, child: picked.child };
 }
 
-function renderChild(
-	child: NonNullable<ReturnType<RunStore["findChild"]>>,
-	action: string,
-): AgentToolResult<unknown> {
-	const lines = [
-		`${child.name} — state=${child.state} agent=${child.agent ?? "?"} kind=${child.kind ?? "?"}`,
-		"supervisor=rpc",
-		`session=${child.sessionFile}`,
-	];
-	if (child.execution) {
-		lines.push(
-			`execution: ${child.execution.status}${child.execution.reason ? ` (${child.execution.reason})` : ""}`,
-		);
-		if (child.execution.usage) {
-			lines.push(
-				`usage: in=${child.execution.usage.input} out=${child.execution.usage.output} cost=${child.execution.usage.cost.toFixed(4)}`,
-			);
-		}
-	}
-	if (child.acceptance)
-		lines.push(
-			`acceptance: ${child.acceptance.status} (${child.acceptance.level})`,
-		);
-	if (action === "collect" && !child.execution)
-		lines.push("(not yet collected — call collect while the agent is alive)");
-	return ok(lines.join("\n"));
-}
-
 function renderCollect(
 	name: string,
 	collected: {
@@ -3165,8 +3312,20 @@ function renderCollect(
 	return lines.join("\n");
 }
 
-function ok(text: string): AgentToolResult<unknown> {
-	return { content: [{ type: "text", text }], details: {} };
+/**
+ * Render a success/neutral result to the model.
+ *
+ * `details` defaults to `{}`; callers that already computed machine facts
+ * (runId/handles for an interrupted collect) pass them through instead of
+ * discarding them (#227 D4) — `interruptedUtilityResult` is that caller.
+ * `isError` is deliberately never set — the rendering chain and every assertion
+ * in this repo work without it.
+ */
+function ok(
+	text: string,
+	details: Record<string, unknown> = {},
+): AgentToolResult<unknown> {
+	return { content: [{ type: "text", text }], details };
 }
 
 /**