pi-legion 2.0.0 → 2.0.2

package/index.ts

@@ -35,13 +35,14 @@ import {
 	type ActiveTeam,
 } from "./src/agents/teams.ts";
 import { resolveModel } from "./src/agents/model-resolution.ts";
+import { providerForModel, type ProviderLookup } from "./src/runs/provider-pin.ts";
 import { resolveStepModel } from "./src/agents/step-model.ts";
 import { checkModelScope } from "./src/agents/model-scope.ts";
 import {
 	loadSubagentSettings,
 	resolveSubagentSettings,
 } from "./src/agents/settings.ts";
-import { createSessionRuntime, renderLiveChildStatus, type SessionRuntime, type TrackedJob, shouldRecycleAfterCollect, type WaitResult } from "./src/extension/runtime.ts";
+import { createSessionRuntime, renderLiveChildStatus, type SessionRuntime, 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";
@@ -52,7 +53,7 @@ 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 { allocateSiblingNames, isValidAgentName, 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";
@@ -65,7 +66,6 @@ import {
 	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";
@@ -81,7 +81,7 @@ import {
 import { renderSubagentNotice } from "./src/extension/notice-renderer.ts";
 import { PARENT_PLAYBOOK, TOOL_DESCRIPTION } from "./src/extension/playbook.ts";
 import { getAgentDir } from "./src/agents/paths.ts";
-import { expectedModelsFromSettings, runLegionDoctor } from "./src/extension/legion-doctor.ts";
+import { expectedModelsFromSettings, parseDoctorSections, runLegionDoctor } from "./src/extension/legion-doctor.ts";
 import { readFileSync } from "node:fs";
 import {
 	effectiveMaxDepth,
@@ -97,13 +97,10 @@ import {
 	DEFAULT_ON_BLOCKED,
 	ErrorCodes,
 	type ModelOrigin,
+	type RetireOptions,
 	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
 // ---------------------------------------------------------------------------
@@ -146,7 +143,7 @@ const SubagentParams = Type.Object({
 				Type.Literal("stop"),
 				Type.Literal("diagnose"),
 			],
-			{ description: "Defaults to launch. diagnose = Legion doctor full self-check (extensions/models/spawn/memory/tools/storage/runtime)." },
+			{ description: "Defaults to launch. diagnose = Legion doctor self-check (extensions/models/spawn/memory/tools/storage/runtime); optional section filters like /legion doctor." },
 		),
 	),
 	agent: Type.Optional(
@@ -189,7 +186,10 @@ const SubagentParams = Type.Object({
 		),
 	),
 	name: Type.Optional(
-		Type.String({ description: "Child handle name (control actions, including wait and stop)" }),
+		Type.String({
+			description:
+				"Child handle name. On launch (single agent+task): registers this exact name (lowercase [a-z][a-z0-9_-]{0,31}) instead of auto scout-N; collisions refuse. On control actions (status/wait/stop/…): addresses that child.",
+		}),
 	),
 	all: Type.Optional(
 		Type.Boolean({
@@ -207,6 +207,12 @@ const SubagentParams = Type.Object({
 	team: Type.Optional(
 		Type.String({ description: "Team to use for the launched child and its nested roster" }),
 	),
+	section: Type.Optional(
+		Type.String({
+			description:
+				'diagnose only: optional section filter (summary|extensions|models|spawn|memory|tools|storage|runtime|next), same as `/legion doctor [section]`. Space/comma-separated for multiple.',
+		}),
+	),
 });
 
 /** The validated tool parameters, as the model supplies them. */
@@ -469,8 +475,7 @@ async function resumeLegionChild(input: { pi: ExtensionAPI; supervisor: LegionSu
 	await store.updateChild(parentRun.runId, saved.name, (child) => Object.assign(child, handle.child));
 }
 
-export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervisorDeps = {}) {
-	cascadePromise = undefined;
+export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps = {}) {
 	const isChild = process.env.PI_SUBAGENT_CHILD === "1";
 	const allowNested = process.env[ALLOW_NESTED_ENV] === "1";
 	if (isChild) restoreHostNodeOptions();
@@ -562,60 +567,25 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 			timer.unref?.();
 		}
 	});
-	const pendingUtilityRetires: Array<() => Promise<void>> = [];
+	const pendingUtilityRetires: Array<(opts?: RetireOptions) => Promise<void>> = [];
 	let sessionRuntime: SessionRuntime | undefined;
-	const shutdownRetireAll = async (): Promise<void> => {
+	const shutdownRetireAll = async (_event?: unknown, ctx?: { mode?: string }): Promise<void> => {
+		// pi --print / JSON exits when the parent turn ends. Async children
+		// have only just been spawned; retiring them here aborts the run
+		// before the first model call. Interactive quit still retires immediately.
+		const mode = ctx?.mode;
+		if (mode === "print" || mode === "json") {
+			await sessionRuntime?.drainBeforeShutdown();
+		}
 		const children = sessionRuntime?.activeJobs() ?? [];
 		sessionRuntime?.dispose();
+		const shutdownRetire: RetireOptions = { cause: "session-shutdown" };
 		await Promise.all([
-			...children.map((job) => job.retire?.().catch(() => {})),
-			...pendingUtilityRetires.map((retire) => retire().catch(() => {})),
+			...children.map((job) => job.retire?.(shutdownRetire).catch(() => {})),
+			...pendingUtilityRetires.map((retire) => retire(shutdownRetire).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();
-	});
 	if (process.env[UTILITY_CHILD_ENV] !== "1") {
 		pi.registerTool({
 			name: "vexillatio",
@@ -624,8 +594,7 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 			parameters: VexillatioParams,
 			async execute(_id, params, signal, _onUpdate, ctx: ExtensionContext): Promise<AgentToolResult<unknown>> {
 				if (signal?.aborted) {
-					await cascadeRetireAll();
-					return ok("interrupted (parent turn aborted)");
+					return ok("interrupted (parent turn ended; children still running)");
 				}
 				if (!subagentsEnabled(ctx.cwd)) {
 					return fail("subagents are disabled (subagents.enabled: false or /legion off). Re-enable with /legion on.", ErrorCodes.DISABLED);
@@ -654,8 +623,7 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 					onUtilityChild: (retire) => pendingUtilityRetires.push(retire),
 				});
 				if (signal?.aborted) {
-					await cascadeRetireAll();
-					return ok("interrupted (parent turn aborted)");
+					return ok("interrupted (parent turn ended; children still running)");
 				}
 				return result;
 			},
@@ -786,6 +754,27 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 		runtime,
 		supervisor: rpcEventSource,
 		stop: stopChildren,
+		childStatus: (name, cwd) => {
+			try {
+				const found = findChild(runStoreFor(cwd).listRuns(), name);
+				if (!found) return undefined;
+				const child = found.child;
+				return {
+					name: child.name,
+					state: child.state,
+					agent: child.agent,
+					kind: child.kind,
+					sessionFile: child.sessionFile,
+					...(child.execution ? { execution: child.execution } : {}),
+					...(child.acceptance
+						? { acceptance: { status: child.acceptance.status, level: child.acceptance.level } }
+						: {}),
+					alive: supervisor.isAlive(child.name),
+				};
+			} catch {
+				return undefined;
+			}
+		},
 		commands: {
 			team: { loadCatalog: commandCatalogLoader },
 			agents: { loadCatalog: commandCatalogLoader },
@@ -834,8 +823,7 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 			runtime.bind(ctx);
 			const action = params.action ?? "launch";
 			if (signal?.aborted && action !== "stop") {
-				await cascadeRetireAll();
-				return ok("interrupted (parent turn aborted)");
+				return ok("interrupted (parent turn ended; children still running)");
 			}
 			// Master switch: refuse NEW launches with a pointer to the toggle;
 			// control actions (status/collect/wait/…) must stay available so a
@@ -868,6 +856,17 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 
 			if (action === "list") return ok(renderAgentList(agents, team, teamWarnings));
 			if (action === "diagnose") {
+				let sections;
+				try {
+					sections = parseDoctorSections(
+						typeof params.section === "string" ? params.section : undefined,
+					);
+				} catch (error) {
+					return fail(
+						error instanceof Error ? error.message : String(error),
+						ErrorCodes.INVALID_PARAMS,
+					);
+				}
 				let settings: unknown;
 				try {
 					settings = JSON.parse(readFileSync(path.join(getAgentDir(), "settings.json"), "utf8"));
@@ -881,6 +880,7 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 					expectedModels: expectedModelsFromSettings(settings),
 					sampleAgent: agents[0],
 					agents,
+					sections,
 					runtime: {
 						liveJobs: runtime.activeJobs().map((job) => ({
 							name: job.name,
@@ -888,7 +888,7 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 							nodeId: job.nodeId,
 						})),
 						stopAvailable: true,
-						idleEscWired: true,
+						idleEscWired: false,
 						legionTools: ["subagent", "vexillatio"],
 						allowNestedEnv: process.env[ALLOW_NESTED_ENV] === "1",
 					},
@@ -908,8 +908,7 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 				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)");
+				return ok("interrupted (parent turn ended; children still running)");
 			}
 
 			// Control actions address an EXISTING child; launch-family actions
@@ -933,8 +932,7 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 					legion: activeLegion,
 				});
 				if (signal?.aborted && action !== "stop") {
-					await cascadeRetireAll();
-					return ok("interrupted (parent turn aborted)");
+					return ok("interrupted (parent turn ended; children still running)");
 				}
 				return result;
 			}
@@ -958,41 +956,13 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 				onUpdate,
 			});
 			if (signal?.aborted) {
-				await cascadeRetireAll();
-				return ok("interrupted (parent turn aborted)");
+				return ok("interrupted (parent turn ended; children still running)");
 			}
 			return result;
 		},
 	});
 
-	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 => {
-		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);
@@ -1023,7 +993,6 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 	});
 
 	pi.on("session_start", (event, ctx) => {
-		runtime.setParentIdle(ctx.isIdle?.() ?? true);
 		bindUi(event, ctx);
 	});
 	pi.on("session_info_changed", bindUi);
@@ -1036,11 +1005,9 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 		bindUi(event, ctx);
 	});
 	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);
@@ -1315,13 +1282,13 @@ async function collectChild(
 	signal?: AbortSignal,
 ): Promise<AgentToolResult<unknown>> {
 	try {
-		if (signal?.aborted) return ok("interrupted (parent turn aborted)");
+		if (signal?.aborted) return ok("interrupted (parent turn ended; children still running)");
 		const pending = signal
 			? ctx.runtime.consumeCollectInterruptible(ctx.name, signal)
 			: ctx.runtime.consumeCollect(ctx.name);
 		if (pending) {
 			const collected = await pending;
-			if (!collected || signal?.aborted) return ok("interrupted (parent turn aborted)");
+			if (!collected || signal?.aborted) return ok("interrupted (parent turn ended; children still running)");
 			await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name, { preserveRetired: true });
 			return ok(renderCollect(ctx.name, collected));
 		}
@@ -1340,7 +1307,7 @@ async function collectChild(
 			...(signal ? { signal } : {}),
 		});
 		if (signal?.aborted || collected.execution.reason === "aborted by parent") {
-			return ok("interrupted (parent turn aborted)");
+			return ok("interrupted (parent turn ended; children still running)");
 		}
 		const retireAlreadyFinishedJob = shouldRecycleAfterCollect(collected.execution.status) && !collected.blocked;
 		await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name, { preserveRetired: !retireAlreadyFinishedJob });
@@ -1460,6 +1427,8 @@ async function launchFamily(input: {
 
 	const plan = buildPlan(params);
 	if (!plan.ok) return fail(plan.message, ErrorCodes.INVALID_PARAMS);
+	const nameGate = resolveExplicitLaunchName(params.name, plan.steps.length);
+	if (!nameGate.ok) return fail(nameGate.message, ErrorCodes.INVALID_PARAMS);
 
 	onUpdate?.({
 		content: [
@@ -1536,9 +1505,11 @@ async function launchFamily(input: {
 		dispatchModel: ctx.model
 			? `${ctx.model.provider}/${ctx.model.id}`
 			: undefined,
+		modelRegistry: ctx.modelRegistry,
 		results: [],
 		handles: [],
 		timeoutByName: new Map(),
+		...(nameGate.name ? { launchName: nameGate.name } : {}),
 	};
 
 	const interruptedResult = async (): Promise<AgentToolResult<unknown> | undefined> => {
@@ -1546,7 +1517,7 @@ async function launchFamily(input: {
 		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)" }],
+			content: [{ type: "text", text: session.results.join("\n") || "interrupted (parent turn ended; children still running)" }],
 			details: { runId: run.runId, handles: [], async: params.async ?? true },
 		};
 	};
@@ -1619,9 +1590,13 @@ interface LaunchSession {
 	runtime: SessionRuntime;
 	onUpdate?: AgentToolUpdateCallback;
 	dispatchModel: string | undefined;
+	/** Parent registry, used to pin `--provider` for ambiguous model ids (#123). */
+	modelRegistry: ProviderLookup | undefined;
 	results: string[];
 	handles: string[];
 	timeoutByName: Map<string, number>;
+	/** Explicit child name for this single-step launch; omit to auto-allocate. */
+	launchName?: string;
 }
 
 /**
@@ -1700,13 +1675,20 @@ async function launchStep(
 			return;
 		}
 
-		// Let `launch()` allocate from the supervisor-local registry; the index
-		// must not race separate subagent tool calls.
+		// Honor `name=` when the caller asked for one; otherwise let `launch()`
+		// allocate from the supervisor-local registry (scout-N). The index must
+		// not race separate subagent tool calls for auto names.
 		const handle = await session.orchestrator.launch({
 			agent: launchedAgent,
 			task: step.task,
+			...(session.launchName ? { name: session.launchName } : {}),
 			...(session.teamOverride ? { team: session.teamOverride } : {}),
 			...(resolved.model ? { model: resolved.model } : {}),
+			// Pin the provider (#123): a bare id like `workbuddy/...` may also
+			// exist under a static auth-less provider in models.json; under
+			// `--no-extensions` the child would resolve it there and die with
+			// "No API key found". The parent registry knows the live provider.
+			...(resolved.model ? { modelProvider: providerForModel(session.modelRegistry, 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).
@@ -1846,7 +1828,7 @@ function resolveStep(
 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)");
+			session.results.push("interrupted (parent turn ended; children still running)");
 			return;
 		}
 		try {
@@ -1855,7 +1837,7 @@ async function collectInline(session: LaunchSession, signal?: AbortSignal): Prom
 				...(signal ? { signal } : {}),
 			});
 			if (signal?.aborted || collected.execution.reason === "aborted by parent") {
-				session.results.push("interrupted (parent turn aborted)");
+				session.results.push("interrupted (parent turn ended; children still running)");
 				return;
 			}
 			session.results.push(renderCollect(name, collected));
@@ -1924,7 +1906,7 @@ async function launchUtilityFamily(input: {
 	legion?: LegionRuntimeIdentity;
 	eventBus: LegionEventBus;
 	onLegion: (identity: LegionRuntimeIdentity) => void;
-	onUtilityChild: (retire: () => Promise<void>) => void;
+	onUtilityChild: (retire: (opts?: RetireOptions) => Promise<void>) => void;
 }): Promise<AgentToolResult<unknown>> {
 	const plan = buildUtilityPlan(input.params);
 	if (!plan.ok) return fail(plan.message, ErrorCodes.INVALID_PARAMS);
@@ -2092,6 +2074,8 @@ async function launchUtilityFamily(input: {
 				task: item.step.task,
 				name: names.get(item.step),
 				...(item.resolved.model ? { model: item.resolved.model } : {}),
+				// Provider pin (#123) — see launchStep for the rationale.
+				...(item.resolved.model ? { modelProvider: providerForModel(input.ctx.modelRegistry, item.resolved.model) } : {}),
 				modelOrigin: item.modelOrigin,
 				...(item.step.worktree !== undefined ? { worktree: item.step.worktree } : {}),
 				utilityDispatch: true,
@@ -2099,10 +2083,10 @@ async function launchUtilityFamily(input: {
 			});
 			await persistChild(store, runId, orchestrator, handle.name);
 			let retirement: Promise<void> | undefined;
-			const retire = (): Promise<void> => {
+			const retire = (opts?: RetireOptions): Promise<void> => {
 				if (!retirement) {
 					const current = (async () => {
-						await orchestrator.retire(handle.name);
+						await orchestrator.retire(handle.name, opts);
 						await persistChild(store, runId, orchestrator, handle.name);
 					})();
 					retirement = current;
@@ -2112,9 +2096,9 @@ async function launchUtilityFamily(input: {
 				}
 				return retirement;
 			};
-			input.onUtilityChild(async () => {
+			input.onUtilityChild(async (opts) => {
 				try {
-					await retire();
+					await retire(opts);
 				} catch {
 					// Shutdown cleanup is best-effort; the supervisor owns final process state.
 				}
@@ -2141,7 +2125,7 @@ async function launchUtilityFamily(input: {
 		agent: string;
 		sessionFile: string;
 		orchestrator: Orchestrator;
-		retire: () => Promise<void>;
+		retire: (opts?: RetireOptions) => Promise<void>;
 	}> = [];
 	for (const launch of launches) {
 		if ("error" in launch) results.push(`✗ ${launch.item.agent.name}: ${launch.error}`);
@@ -2196,7 +2180,7 @@ 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 aborted)");
+	if (input.signal?.aborted) return ok("interrupted (parent turn ended; children still running)");
 	results.push(...collected);
 	return {
 		content: [{ type: "text", text: results.join("\n\n") || "No utility agents were launched." }],
@@ -2211,6 +2195,41 @@ async function launchUtilityFamily(input: {
 	};
 }
 
+/**
+ * Resolve an explicit `name=` on launch.
+ *
+ * Prefer honoring the caller's handle over auto `role-N`, so `/legion status <name>`
+ * and control actions match the tool parameter. Multi-step `tasks[]` cannot share
+ * one name; invalid grammar is refused rather than silently sanitized into a
+ * different handle the caller would not find.
+ */
+export function resolveExplicitLaunchName(
+	requested: string | undefined,
+	stepCount: number,
+): { ok: true; name?: string } | { ok: false; message: string } {
+	if (requested === undefined) return { ok: true };
+	const trimmed = requested.trim();
+	if (!trimmed) {
+		return { ok: false, message: "`name` must not be blank when provided." };
+	}
+	if (stepCount > 1) {
+		return {
+			ok: false,
+			message:
+				"`name` applies only to a single (agent+task) launch, not tasks[] with multiple steps.",
+		};
+	}
+	const normalized = trimmed.toLowerCase();
+	if (!isValidAgentName(normalized)) {
+		return {
+			ok: false,
+			message:
+				`invalid child name "${trimmed}": must match [a-z][a-z0-9_-]{0,31} (lowercase letter first, max 32 chars).`,
+		};
+	}
+	return { ok: true, name: normalized };
+}
+
 export function buildPlan(params: {
 	agent?: string;
 	task?: string;
@@ -2319,7 +2338,7 @@ function followJob(
 		orchestrator: Orchestrator;
 		store: RunStore;
 		watch: boolean;
-		retire?: () => Promise<void>;
+		retire?: (opts?: RetireOptions) => Promise<void>;
 		treeIdentity?: { nodeId: string; parentId: string | null; depth: number };
 	},
 ): void {
@@ -2350,12 +2369,12 @@ function followJob(
 		isAlive: () => input.orchestrator.isChildAlive(input.name),
 		persist: async () =>
 			persistChild(input.store, input.runId, input.orchestrator, input.name),
-		retire: async () => {
+		retire: async (opts) => {
 			if (input.retire) {
-				await input.retire();
+				await input.retire(opts);
 				return;
 			}
-			await input.orchestrator.retire(input.name);
+			await input.orchestrator.retire(input.name, opts);
 			await persistChild(
 				input.store,
 				input.runId,
@@ -2479,18 +2498,10 @@ async function abandonLaunchedChild(session: LaunchSession, name: string): Promi
 		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`);
-	}
+	// Esc / parent-turn abort must not retire: child keeps running; follow+watch
+	// so settle still notifies the parent (esc-no-retire-v3).
+	followLaunched(session, name, { watch: true });
+	session.results.push(`▶ ${name}: parent turn ended; child still running (watched)`);
 }
 
 // ---------------------------------------------------------------------------
@@ -2543,7 +2554,7 @@ export function renderWait(results: WaitResult[]): string {
 			parts.push(`── ${result.name} ──\nstill running`);
 		} else if (result.interrupted) {
 			interrupted += 1;
-			parts.push(`── ${result.name} ──\ninterrupted (parent turn aborted)`);
+			parts.push(`── ${result.name} ──\ninterrupted (parent turn ended; children still running)`);
 		} else {
 			parts.push(`── ${result.name} ──\nnot tracked (no live job, no finished cache)`);
 		}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-legion",
-  "version": "2.0.0",
-  "description": "Herdr-backed subagents for Pi: visible, steerable, resumable child agents in Herdr panes",
+  "version": "2.0.2",
+  "description": "Pi Legion v2: recursive centurion trees on headless Pi RPC; shared SQLite WAL legion.db. Four-stage planning/implementing/reviewing/verifying state machine, parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -15,9 +15,12 @@
   "keywords": [
     "pi-package",
     "pi",
-    "herdr",
+    "pi-extension",
+    "legion",
+    "rpc",
     "subagents",
-    "agents"
+    "agents",
+    "centurion"
   ],
   "publishConfig": {
     "access": "public"
@@ -41,6 +44,7 @@
     "skills/**/*",
     "docs/**/*.md",
     "README.md",
+    "CHANGELOG.md",
     "CONTRIBUTING.md",
     "LICENSE"
   ],