pi-legion 3.1.0 → 4.0.0

package/index.ts

@@ -21,7 +21,7 @@ import type {
 import { Type, type Static } from "typebox";
 import { RpcSupervisor } from "./src/supervisor/rpc-supervisor.ts";
 import { InProcessSupervisor } from "./src/supervisor/inprocess-supervisor.ts";
-import { RoutingSupervisor } from "./src/supervisor/routing-supervisor.ts";
+import { notifyInProcessSlotReleased, RoutingSupervisor } from "./src/supervisor/routing-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";
@@ -51,16 +51,17 @@ import { LegionPostman, registerLegionTools, type LegionMailCommand } from "./sr
 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 { appendEvent, maxEventId } 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, isValidAgentName, makeName } from "./src/shared/name.ts";
+import { allocateSiblingNames, isValidAgentName } from "./src/shared/name.ts";
 import { deriveOutcome, isLastTurnComplete, parseSessionFile } from "./src/shared/session.ts";
 import { restoreHostNodeOptions } from "./src/supervisor/child-memory.ts";
 import { currentChildContext } from "./src/supervisor/child-context.ts";
 import { setVerifyQueueListener } from "./src/runs/verify-queue.ts";
+import { setLaunchQueueListener } from "./src/supervisor/admission-queue.ts";
 import { applyEventRetention, checkpoint, formatHygieneReport, hygieneEnabled, runStartupHygiene } from "./src/runs/hygiene.ts";
 import {
 	createStatusNodeOpener,
@@ -108,6 +109,7 @@ import {
 	type SpawnMode,
 	SubagentError,
 	type SubagentsSettings,
+	type Handle,
 } from "./src/shared/types.ts";
 
 // ---------------------------------------------------------------------------
@@ -234,7 +236,17 @@ const SubagentParams = Type.Object({
 type SubagentParams = Static<typeof SubagentParams>;
 
 const VexillatioParams = Type.Object({
-	task: Type.String({ description: "Recon task: one clear question list" }),
+	// Optional on purpose: `tasks[]` is a complete request on its own, exactly like
+	// `subagent({ tasks })`. Leaving this required made pi's own argument check
+	// reject `{ tasks: [...] }` before `execute` ran, so every `tasks[]`-only call
+	// failed with `task: must have required properties task` and had to be retried
+	// with a dummy `task` label (models copy the `subagent` shape).
+	task: Type.Optional(
+		Type.String({
+			description:
+				"Recon task: one clear question list. Optional when `tasks[]` is provided (then it only labels the parent run).",
+		}),
+	),
 	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()),
@@ -309,10 +321,129 @@ function currentProcessSpawnMode(): SpawnMode {
 	return currentChildContext()?.spawnMode ?? "rpc";
 }
 
+/**
+ * The frozen interruption head line (`test/unit/teams.test.ts` matches it, and
+ * `esc-no-retire-v3` records why it leads every interrupted result).
+ */
+const INTERRUPTED_HEAD = "interrupted (parent turn ended; children still running)";
+
 function notice(pi: ExtensionAPI, text: string): void {
 	pi.sendMessage({ customType: SUBAGENT_NOTIFY_TYPE, content: text, display: true }, { triggerTurn: true, deliverAs: "followUp" });
 }
 
+/**
+ * Launch-admission-queue bounds from settings (issue #266, contract D6-a/D10).
+ *
+ * Frozen key names are `subagents.inprocess.maxQueuedLaunches` /
+ * `subagents.inprocess.launchQueueTimeoutMs`. An absent key is *omitted* rather
+ * than defaulted here: the single source of the defaults is
+ * `src/supervisor/admission-queue.ts`, and passing a literal 32/900000 from the
+ * adapter would create a second copy that can drift from the docs and sentinel.
+ */
+function launchQueueBounds(settings: {
+	inprocess?: { maxQueuedLaunches?: number; launchQueueTimeoutMs?: number };
+}): { maxPending?: number; timeoutMs?: number } {
+	const bounds: { maxPending?: number; timeoutMs?: number } = {};
+	if (settings.inprocess?.maxQueuedLaunches !== undefined) bounds.maxPending = settings.inprocess.maxQueuedLaunches;
+	if (settings.inprocess?.launchQueueTimeoutMs !== undefined) bounds.timeoutMs = settings.inprocess.launchQueueTimeoutMs;
+	return bounds;
+}
+
+/**
+ * D9/§13.4: the one user-visible line per queued / admitted / expired / stopped
+ * launch.
+ *
+ * Deliberately `triggerTurn: false` (unlike {@link notice}): admission is a
+ * mid-turn fact about work the caller already asked for, so waking the parent
+ * with a fresh turn for every queue transition would re-enter the agent for a
+ * purely cosmetic line. Anything the caller must act on still arrives through
+ * the tool result and, for `async:false`, the inline `↳ waited Ns` line.
+ */
+function launchQueueNoticeSink(pi: ExtensionAPI): (line: string) => void {
+	return (line: string) => {
+		try {
+			pi.sendMessage(
+				{ customType: SUBAGENT_NOTIFY_TYPE, content: line, display: true },
+				{ triggerTurn: false },
+			);
+		} catch {
+			// Cosmetic: a gone parent session must never break admission.
+		}
+	};
+}
+
+/**
+ * D9-1: the launch line's queue suffix, or `""` for a launch that spawned now.
+ *
+ * `▶ scout-7 (scout) supervisor=inprocess queued(3)` — the position is what the
+ * operator needs to know the launch is waiting rather than broken. Only the
+ * trailing segment is added: the line's published prefix and `details.spawns`
+ * (a renderer input) keep their existing shapes.
+ */
+function launchLineQueueSuffix(handle: Pick<Handle, "queued" | "queuePosition">): string {
+	if (handle.queued !== true) return "";
+	return handle.queuePosition === undefined ? " queued" : ` queued(${handle.queuePosition})`;
+}
+
+/**
+ * D8/A20: the honest wait line for an `async:false` child that queued.
+ *
+ * Read from the admitted `ChildRecord.queueWaitedMs` — never re-derived from a
+ * clock here, or the number would describe the adapter's own latency instead of
+ * the queue's. `""` when the child never waited.
+ */
+function queuedWaitLine(child: { name: string; queueWaitedMs?: number } | undefined): string {
+	if (!child || child.queueWaitedMs === undefined || child.queueWaitedMs <= 0) return "";
+	return `↳ ${child.name} waited ${Math.round(child.queueWaitedMs / 1000)}s in the launch queue`;
+}
+
+/**
+ * D6/D7: report a queue that an abort cleared out.
+ *
+ * "Empty queue and zero spawns" is only half the contract; the caller must also
+ * learn that N launches it asked for never ran. One line, names in `seq` order.
+ */
+function launchQueueFlushLine(flushed: readonly string[]): string {
+	if (flushed.length === 0) return "";
+	return `${flushed.length} queued launch(es) dropped: ${flushed.join(", ")}`;
+}
+
+/**
+ * #238: create and start the DB event source that feeds the legion bus on attach.
+ *
+ * This is the production attach path and it is exported so a unit test can drive
+ * it directly (same seam style as `buildPlan`/`resolveWaitTargets`): the seeding
+ * behaviour is a property of THIS call, not of `createDbEventSource`, and a test
+ * that only exercised the factory would keep passing if this seed were removed.
+ *
+ * Seeding at `MAX(id)` matters because `createDbEventSource`'s own default is 0,
+ * i.e. "replay the whole log". On a ledger with history that re-delivered every
+ * stored event through `onWidgetEvent` — one full `snapshotNodes()` plus a
+ * repaint each, ~2.5s of blocked UI at 120 nodes / 1000 events — to reach a
+ * state the DB already describes.
+ *
+ * Rows committed in the window between this seed query and the first poll are
+ * not lost: `poll()` only skips when `lastDataVersion` matches, that variable
+ * starts `undefined` (so the first poll always reads), and the cursor is only
+ * ever advanced from ids actually returned by `SELECT ... WHERE id > cursor`.
+ * A row committed after the seed is therefore either picked up by the first
+ * poll or dirties `data_version` and is picked up on the next tick. The seed is
+ * not atomic with `start()`, but it does not need to be.
+ *
+ * Note the drain loop's early `return`: it exits BEFORE `lastDataVersion` is
+ * assigned (that assignment is after the loop), so an interrupted drain leaves
+ * the version unlatched. That errs safe — the next poll re-reads from the
+ * cursor instead of skipping — but it is a re-read, not a "set then return".
+ */
+export function attachLegionRuntime(input: {
+	db: DatabaseSync;
+	eventBus: LegionEventBus;
+}): DbEventSource {
+	const dbEventSource = createDbEventSource(input.db, { cursor: maxEventId(input.db) });
+	dbEventSource.start(input.eventBus);
+	return dbEventSource;
+}
+
 function createLegionRuntime(input: {
 	pi: ExtensionAPI;
 	supervisor: LegionSupervisor;
@@ -329,8 +460,7 @@ function createLegionRuntime(input: {
 }): LegionRuntimeIdentity {
 	const self = getNode(input.db, input.nodeId);
 	const eventBus = input.eventBus;
-	const dbEventSource = createDbEventSource(input.db);
-	dbEventSource.start(eventBus);
+	const dbEventSource = attachLegionRuntime(input);
 	const postman = new LegionPostman({
 		db: input.db,
 		nodeId: input.nodeId,
@@ -508,7 +638,7 @@ async function resumeLegionChild(input: { pi: ExtensionAPI; supervisor: LegionSu
 	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: resolveTeamContext("child", catalog.settings, resumedTeam.team), parentPath: parentRun.path, ...rpcApproveFrom(catalog.settings), 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 } });
+	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: resolveTeamContext("child", catalog.settings, resumedTeam.team), parentPath: parentRun.path, ...rpcApproveFrom(catalog.settings), launchQueue: launchQueueBounds(catalog.settings), onLaunchQueueNotice: launchQueueNoticeSink(input.pi), 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));
@@ -537,6 +667,25 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 				else lastUi?.setStatus("legion-verify", undefined);
 			} catch { /* no UI */ }
 		});
+		// #266 D9-3: the launch admission queue's own pill. Deliberately a separate
+		// listener from verify's — different phases, and verify's is poll-driven.
+		// The contract's baseline is `legion-queue: N queued`; the `· 8/8 slots busy`
+		// tail needs `slotsInUse`/`slots`, which the pure queue does not know (the
+		// limit lives in the supervisor), so that dimension is omitted until the
+		// event carries it — the contract allows the omission explicitly.
+		setLaunchQueueListener((event) => {
+			try {
+				if (event.phase === "queued" || event.phase === "admitted") {
+					const suffix = event.slotsInUse !== undefined && event.slots !== undefined
+						? ` · ${event.slotsInUse}/${event.slots} slots busy`
+						: "";
+					lastUi?.setStatus("legion-queue", `legion-queue: ${event.queued} queued${suffix}`);
+					if (event.queued === 0) lastUi?.setStatus("legion-queue", undefined);
+				} else if (event.phase === "overflow" || event.phase === "expired" || event.phase === "flushed") {
+					lastUi?.setStatus("legion-queue", undefined);
+				}
+			} catch { /* no UI */ }
+		});
 	}
 	const onSpawnRefused = (message: string) => {
 		try { lastUi?.notify(`pi-legion: ${message}`, "error"); } catch { /* no UI (child / print mode) */ }
@@ -546,8 +695,20 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 	let lastCwd = process.cwd();
 	const supervisor = deps.supervisor ?? new RoutingSupervisor({
 		rpc: new RpcSupervisor({ onSpawnRefused }),
+		// The in-process supervisor is constructed here (not by RoutingSupervisor) so
+		// it can read live settings per spawn. That means `onSlotReleased` must be
+		// wired EXPLICITLY: RoutingSupervisor only adds it when it builds the
+		// backend itself (`options.inprocess ?? new InProcessSupervisor({...})`).
+		// Passing a pre-built instance used to drop the hook silently, so a freed
+		// slot never woke a launch-queue pump in production — admission then waited
+		// for the fallback recheck instead of firing on the release (#266 D2-d-2).
 		inprocess: new InProcessSupervisor({
 			onSpawnRefused,
+			// The event payload is not needed here: every Orchestrator on this run dir
+			// re-probes its own items, so a bare wake-up edge is the whole contract.
+			onSlotReleased: () => {
+				notifyInProcessSlotReleased();
+			},
 			getLimits: () => {
 				try {
 					return loadSubagentSettings({
@@ -562,7 +723,23 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		onSpawnRefused,
 	});
 	const verifyRunner = deps.verifyRunner;
-	const legionBus = createLegionEventBus();
+	// #238: the resident status widget defers its repaint to a microtask, which puts
+	// a paint failure outside the per-subscriber try/catch in `createLegionEventBus`.
+	// The runtime funnels that failure through `reportError` → `onHandlerError`, so
+	// a handler must actually be configured or the containment is silent. A widget
+	// repaint that throws (a stale UI context, a SQLITE_IOERR on the tree read) must
+	// never take the host down, and must leave a trace.
+	const legionBus = createLegionEventBus({
+		onHandlerError: (error, event, handler) => {
+			const detail = error instanceof Error ? error.message : String(error);
+			// `event === null` means a deferred failure with no event to attribute;
+			// `handler` is then an origin tag rather than a subscriber function.
+			const where = event
+				? `${event.type} node=${event.nodeId}`
+				: typeof handler === "string" ? handler : "deferred";
+			console.error(`[pi-legion] legion event handler failed (${where}): ${detail}`);
+		},
+	});
 	const rpcUIProxy = (supervisor as LegionSupervisor & { uiProxy?: UIProxy }).uiProxy;
 	const uiProxy = deps.uiProxy ?? rpcUIProxy ?? new InMemoryUIProxy();
 	const onBudgetRefused = deps.onBudgetRefused ?? ((event) => {
@@ -925,9 +1102,17 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		stop: stopChildren,
 		childStatus: (name, cwd) => {
 			try {
-				const found = findChild(runStoreFor(cwd).listRuns(), name);
+				const store = runStoreFor(cwd);
+				const runs = store.listRuns();
+				const found = findChild(runs, name);
 				if (!found) return undefined;
 				const child = found.child;
+				const alive = supervisor.isAlive(child.name);
+				// Run-dir ownership verdict (#209-3), the same one `subagent status`
+				// uses: `alive` is this process's in-memory registry and never holds a
+				// child launched elsewhere, so a foreign record needs the owner marker.
+				// Undefined while alive — liveness already wins there.
+				const owner = ownerVerdictFor(store, runs, child.name, alive);
 				return {
 					name: child.name,
 					state: child.state,
@@ -938,7 +1123,11 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 					...(child.acceptance
 						? { acceptance: { status: child.acceptance.status, level: child.acceptance.level } }
 						: {}),
-					alive: supervisor.isAlive(child.name),
+					// run.json records the arbitrated backend; a legacy record has none,
+					// and `renderLiveChildStatus` renders that as `unknown` — never `rpc`.
+					...(child.spawnMode ? { spawnMode: child.spawnMode } : {}),
+					alive,
+					...(owner ? { owner } : {}),
 				};
 			} catch {
 				return undefined;
@@ -1113,6 +1302,7 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 				params,
 				signal,
 				ctx,
+				pi,
 				supervisor,
 				uiProxy,
 				onBudgetRefused,
@@ -1139,7 +1329,16 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 					details !== null && typeof details === "object" && !Array.isArray(details)
 						? (details as Record<string, unknown>)
 						: undefined;
-				return ok("interrupted (parent turn ended; children still running)", carried);
+				// #266 D7: the inner interrupted result also carries the launch-queue
+				// flush line (`N queued launch(es) dropped: …`), which a bare head line
+				// would silently erase — the caller would think its launches still ran.
+				// An inner result that already reports the interruption is therefore
+				// kept as-is; only an otherwise-successful result is replaced.
+				const inner = (result.content ?? [])
+					.map((part) => (part.type === "text" ? part.text : ""))
+					.join("\n");
+				if (inner.includes(INTERRUPTED_HEAD)) return ok(inner, carried);
+				return ok(INTERRUPTED_HEAD, carried);
 			}
 			return result;
 		},
@@ -1398,13 +1597,28 @@ async function controlAction(input: {
 		}
 		if (!params.name) {
 			const runs = store.listRuns();
-			const live = listLiveChildrenForStatus(runs);
+			// Liveness facts are read once per name and reused by both the filter and
+			// the block, so `status` cannot classify a child one way and render it
+			// another (display-liveness D6 exit 1).
+			const factsByName = new Map<string, StatusLivenessFacts & { pid?: number }>();
+			const factsFor = (child: StatusChildRecord): StatusLivenessFacts & { pid?: number } => {
+				const cached = factsByName.get(child.name);
+				if (cached) return cached;
+				const alive = input.supervisor.isAlive(child.name);
+				const owner = ownerVerdictFor(store, runs, child.name, alive);
+				// A pid only exists for a child this process actually tracks; a
+				// record from another session has none, and none is invented.
+				const pid = input.runtime.get(child.name)?.pid;
+				const facts = { alive, ...(owner ? { owner } : {}), ...(pid ? { pid } : {}) };
+				factsByName.set(child.name, facts);
+				return facts;
+			};
+			const classified = classifyChildrenForStatus(runs, factsFor);
 			return ok(
 				renderStatusOverview(
-					live.map((child) => {
-						const alive = input.supervisor.isAlive(child.name);
-						const owner = ownerVerdictFor(store, runs, child.name, alive);
-						return { child, alive, ...(owner ? { owner } : {}) };
+					classified.map(({ child, live }) => {
+						const { pid, ...facts } = factsFor(child);
+						return { child, ...facts, ...(pid ? { pid } : {}), live };
 					}),
 				),
 			);
@@ -1658,6 +1872,7 @@ async function reviveChild(
 async function launchFamily(input: {
 	params: SubagentParams;
 	ctx: ExtensionContext;
+	pi: ExtensionAPI;
 	supervisor: LegionSupervisor;
 	uiProxy: UIProxy;
 	onBudgetRefused: NonNullable<ConstructorParameters<typeof Orchestrator>[0]["onBudgetRefused"]>;
@@ -1735,6 +1950,10 @@ async function launchFamily(input: {
 		worktreeBootstrapTimeoutMs: settings.legion?.worktreeBootstrapTimeoutMs,
 		...teamForChildren(input.team),
 		...rpcApproveFrom(settings),
+		// #266 D6-a/D10: queue bounds + the D9 notice channel. The command chain is
+		// the bug's main path (a 12-step `tasks[]` fanout against `maxChildrenPerNode`).
+		launchQueue: launchQueueBounds(settings),
+		onLaunchQueueNotice: launchQueueNoticeSink(input.pi),
 		...(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,
 	});
@@ -1764,6 +1983,7 @@ async function launchFamily(input: {
 		// abort (interrupted results run after that), so it is kept per name
 		// here — same precedent as `timeoutByName`.
 		spawnByName: new Map(),
+		pidByName: new Map(),
 		...(nameGate.name ? { launchName: nameGate.name } : {}),
 	};
 
@@ -1775,10 +1995,28 @@ async function launchFamily(input: {
 
 	const interruptedResult = async (): Promise<AgentToolResult<unknown> | undefined> => {
 		if (!input.signal?.aborted) return undefined;
+		// #266 D7/A5: a parent turn end empties the launch queue and spawns nothing.
+		// Deliberately only HERE (and in the vexillatio interrupt): Esc/wait
+		// interruptions end the parent's *wait*, not its turn, and must leave
+		// children — queued ones included — running (`esc-no-retire-v3`).
+		const flushed = orchestrator.flushLaunchQueue("parent turn ended");
 		for (const name of session.handles) await abandonLaunchedChild(session, name);
 		session.handles.length = 0;
+		const flushLine = launchQueueFlushLine(flushed);
 		return {
-			content: [{ type: "text", text: session.results.join("\n") || "interrupted (parent turn ended; children still running)" }],
+			content: [{
+				type: "text",
+				text: [
+					// The head line LEADS (same frozen shape as the vexillatio interrupt):
+					// the outer abort net keeps an inner result that already reports the
+					// interruption, and only a leading head makes that detection reliable
+					// — otherwise each `parent turn ended; child still running (watched)`
+					// line reads like a standalone notice and the flush line is lost.
+					INTERRUPTED_HEAD,
+					session.results.join("\n"),
+					flushLine,
+				].filter(Boolean).join("\n"),
+			}],
 			details: { runId: run.runId, handles: [], async: params.async ?? true, ...spawnDetails() },
 		};
 	};
@@ -1858,6 +2096,13 @@ interface LaunchSession {
 	timeoutByName: Map<string, number>;
 	/** Arbitrated backend per resolved handle; survives an abort clearing `handles`. */
 	spawnByName: Map<string, { name: string; agent: string; spawnMode: SpawnMode }>;
+	/**
+	 * Own process of an `rpc` child, keyed by name — same reason `timeoutByName`
+	 * exists: `Handle.pid` is not persisted, so a re-follow from `ChildRecord`
+	 * cannot recover it. Kept out of `spawnByName` so `details.spawns` (a
+	 * renderer input) keeps its published shape.
+	 */
+	pidByName: Map<string, number>;
 	/** Explicit child name for this single-step launch; omit to auto-allocate. */
 	launchName?: string;
 }
@@ -1952,9 +2197,8 @@ async function launchStep(
 			// `--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).
+			// The origin distinguishes a deliberate per-run model from the parent's
+			// model falling through; the launch line reports which one won.
 			modelOrigin: model.modelOrigin,
 			worktree: resolveLaunchWorktree({
 				roleDefault: effective.worktree,
@@ -1976,6 +2220,7 @@ async function launchStep(
 			agent: effective.name,
 			spawnMode: handle.spawnMode,
 		});
+		if (handle.pid) session.pidByName.set(handle.name, handle.pid);
 		if (effective.timeoutMs !== undefined) {
 			session.timeoutByName.set(handle.name, effective.timeoutMs);
 		}
@@ -1984,18 +2229,8 @@ async function launchStep(
 			return;
 		}
 		session.results.push(
-			`▶ ${handle.name} (${effective.name}) supervisor=${handle.spawnMode}`,
+			`▶ ${handle.name} (${effective.name}) supervisor=${handle.spawnMode}${launchLineQueueSuffix(handle)}`,
 		);
-		// 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
-		// reasonably believes the child is running the model they see on the
-		// parent — the same silent surprise this whole guard exists to remove.
-		if (handle.child.modelDropped?.length) {
-			session.results.push(
-				`  ⚠ ${effective.name} runs on ${effective.kind}'s own default: ` +
-					`${handle.child.modelDropped.join(", ")} does not apply to that CLI.`,
-			);
-		}
 		session.onUpdate?.({
 			content: [
 				{
@@ -2094,23 +2329,100 @@ function resolveStep(
 	};
 }
 
+/**
+ * Collect one child, tolerating the transient gap an admission creates.
+ *
+ * `pumpAdmissions` deletes the `queued` placeholder before replaying the real
+ * launch, so between those two steps the name exists in neither the placeholder
+ * map nor the freshly spawned record. `collect()` resolves names through
+ * `requireChild`, so a collect that lands in that window throws
+ * `unknown child: <name>` — a race, not a real failure, and one only a queued
+ * child can hit. The window is a microtask-or-two long (the replay is awaited),
+ * so a short bounded retry is enough; anything genuinely gone still surfaces.
+ *
+ * Only used by the sequential `async:false` path. `async:true` never collects
+ * here — its watcher goes through the same `collect` but is re-armed, so a retry
+ * loop there would fight the watcher instead of helping it.
+ */
+async function collectThroughAdmission(
+	session: LaunchSession,
+	name: string,
+	signal?: AbortSignal,
+): Promise<Awaited<ReturnType<Orchestrator["collect"]>>> {
+	const deadline = Date.now() + ADMISSION_SETTLE_TIMEOUT_MS;
+	for (;;) {
+		try {
+			return await session.orchestrator.collect(name, {
+				timeoutMs: session.timeoutByName.get(name) ?? DEFAULTS.turnTimeoutMs,
+				...(signal ? { signal } : {}),
+			});
+		} catch (error) {
+			const transient = error instanceof SubagentError && error.code === ErrorCodes.NOT_FOUND;
+			if (!transient || Date.now() >= deadline || signal?.aborted) throw error;
+			await new Promise((resolve) => setTimeout(resolve, ADMISSION_SETTLE_POLL_MS));
+		}
+	}
+}
+
+/**
+ * How long a collect may retry across the admission gap before reporting it.
+ *
+ * Deliberately much shorter than a turn timeout: the gap is two `await`s wide,
+ * so anything still missing after this long is not racing — it is gone.
+ */
+const ADMISSION_SETTLE_TIMEOUT_MS = 5_000;
+const ADMISSION_SETTLE_POLL_MS = 25;
+
 /** Wait for each launched child's turn, appending its outcome. */
 async function collectInline(session: LaunchSession, signal?: AbortSignal): Promise<void> {
-	for (const name of session.handles) {
+	// #266 D8: collect children that already hold a slot FIRST.
+	//
+	// A queued handle resolves synchronously (`launch()` returns it before any
+	// spawn), so it lands in `handles` BEFORE the admitted siblings. Collecting in
+	// raw launch order would therefore block on the queued child first — waiting
+	// for a slot that only those very siblings can release once THEY are
+	// collected — i.e. a deadlock, not a wait. Launch order is preserved within
+	// each group, so a run with no queue keeps its exact previous order.
+	const queuedHere = new Set(
+		session.orchestrator
+			.childrenSnapshot()
+			.filter((child) => child.state === "queued")
+			.map((child) => child.name),
+	);
+	const ordered = [
+		...session.handles.filter((name) => !queuedHere.has(name)),
+		...session.handles.filter((name) => queuedHere.has(name)),
+	];
+	for (const name of ordered) {
 		if (signal?.aborted) {
 			session.results.push("interrupted (parent turn ended; children still running)");
 			return;
 		}
 		try {
-			const collected = await session.orchestrator.collect(name, {
-				timeoutMs: session.timeoutByName.get(name) ?? DEFAULTS.turnTimeoutMs,
-				...(signal ? { signal } : {}),
-			});
+			const collected = await collectThroughAdmission(session, name, signal);
 			if (signal?.aborted || collected.execution.reason === "aborted by parent") {
 				session.results.push("interrupted (parent turn ended; children still running)");
 				return;
 			}
 			session.results.push(renderCollect(name, collected));
+			// #266 D8/A20: `async:false` must report the real wait, not just look slow.
+			// Read AFTER collect: `queueWaitedMs` is written at admission, so an item
+			// that is still waiting when the collect deadline fires has no line yet.
+			const waitedLine = queuedWaitLine(
+				session.orchestrator.childrenSnapshot().find((child) => child.name === name),
+			);
+			if (waitedLine) session.results.push(waitedLine);
+			// A finished child must release its slot BEFORE the next collect starts,
+			// or a queue can never drain: `collectInline` is sequential, and the
+			// caller's retire loop runs after every collect (so with `maxChildrenPerNode:
+			// 1` the second child would wait for a slot the first still holds).
+			// Gated on a non-empty queue so the un-queued fast path is unchanged.
+			if (
+				session.orchestrator.launchQueueEntries().length > 0 &&
+				shouldRecycleAfterCollect(collected.execution.status)
+			) {
+				await session.orchestrator.retire(name);
+			}
 		} catch (error) {
 			session.results.push(`✗ ${name}: collect failed: ${String(error)}`);
 		}
@@ -2143,10 +2455,16 @@ type UtilityPlan =
 	| { 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 singleTask = params.task ?? "";
+	const parallel = params.tasks?.length ? params.tasks : undefined;
+	// `tasks[]` wins and `task` degrades to a parent-run label, so both shapes
+	// accepted by the schema reach a launch: `{ task }`, `{ tasks }`, `{ task, tasks }`.
+	if (!parallel && !singleTask.trim()) {
+		return { ok: false, message: "Provide one of: `task` (single recon) or `tasks[]` (parallel recon)." };
+	}
+	const steps: UtilityTaskItem[] = parallel
+		? parallel
+		: [{ agent: params.agent?.trim() || "scout", task: singleTask }];
 	const unsupportedVerify = steps.findIndex((item) => item.verify !== undefined);
 	if (unsupportedVerify >= 0) {
 		return {
@@ -2323,6 +2641,10 @@ async function launchUtilityFamily(input: {
 			childContext: resolveTeamContext("child", catalog.settings, catalog.team),
 			team: catalog.team,
 			...rpcApproveFrom(catalog.settings),
+			// #266: the parallel-recon path shares the same bounds and notice channel
+			// as the command chain — one scheduler for every dispatch family (D2).
+			launchQueue: launchQueueBounds(catalog.settings),
+			onLaunchQueueNotice: launchQueueNoticeSink(input.pi),
 			onBudgetRefused: input.onBudgetRefused,
 			...(legion ? {
 				legion: {
@@ -2381,6 +2703,7 @@ async function launchUtilityFamily(input: {
 					agent: item.agent.name,
 					sessionFile: handle.sessionFile,
 					spawnMode: handle.spawnMode,
+					...(handle.pid ? { pid: handle.pid } : {}),
 					orchestrator,
 					retire,
 				},
@@ -2397,6 +2720,7 @@ async function launchUtilityFamily(input: {
 		agent: string;
 		sessionFile: string;
 		spawnMode: SpawnMode;
+		pid?: number;
 		orchestrator: Orchestrator;
 		retire: (opts?: RetireOptions) => Promise<void>;
 	}> = [];
@@ -2414,6 +2738,7 @@ async function launchUtilityFamily(input: {
 			timeoutMs,
 			// Arbitrated at launch; never re-derived here (#209).
 			spawnMode: handle.spawnMode,
+			...(handle.pid ? { pid: handle.pid } : {}),
 			orchestrator: handle.orchestrator,
 			store,
 			watch,
@@ -2445,6 +2770,17 @@ async function launchUtilityFamily(input: {
 			lines.push(`sessionFile: ${handle.sessionFile}`);
 			return lines.join("\n");
 		} catch (error) {
+			// #266: a queued item is never "failed" — it never started. Treating it as
+			// still running keeps it out of the failure list and lets the retry/watch
+			// path own it, instead of retiring a launch the caller only asked to wait on.
+			const queuedNow = handle.orchestrator
+				.childrenSnapshot()
+				.find((entry) => entry.name === handle.name)?.state === "queued";
+			if (queuedNow) {
+				followUtility(handle, true);
+				stillRunning.add(handle.name);
+				return `── ${handle.name} ──\nexecution: queued (waiting for a free slot)\nsessionFile: ${handle.sessionFile}`;
+			}
 			if (input.supervisor.isAlive(handle.name)) {
 				followUtility(handle, true);
 				stillRunning.add(handle.name);
@@ -2455,13 +2791,27 @@ async function launchUtilityFamily(input: {
 			return `✗ ${handle.name}: collect failed: ${error instanceof Error ? error.message : String(error)}\nsessionFile: ${handle.sessionFile}`;
 		}
 	}));
-	if (input.signal?.aborted) return interruptedUtilityResult({
-		runId,
-		handles,
-		stillRunning,
-		results,
-		collected,
-	});
+	if (input.signal?.aborted) {
+		// #266 D7/A5: same rule as the command chain — a parent turn end empties
+		// every dispatch family's queue and spawns nothing. Each utility item owns
+		// its own Orchestrator, so each one flushes its own view of the shared queue.
+		const flushed: string[] = [];
+		for (const handle of handles) {
+			const child = handle.orchestrator.childrenSnapshot().find((entry) => entry.name === handle.name);
+			// D9: a queued item produced no result, so it must never be reported as
+			// one. It is either dropped by the flush below (reported by name) or, if
+			// it was already admitted, genuinely still running.
+			if (child?.state === "queued") flushed.push(...handle.orchestrator.flushLaunchQueue("parent turn ended"));
+		}
+		return interruptedUtilityResult({
+			runId,
+			handles,
+			stillRunning,
+			results,
+			collected,
+			flushed,
+		});
+	}
 	results.push(...collected);
 	return {
 		content: [{ type: "text", text: results.join("\n\n") || "No utility agents were launched." }],
@@ -2493,9 +2843,18 @@ function interruptedUtilityResult(input: {
 	stillRunning: Set<string>;
 	results: string[];
 	collected: string[];
+	/** #266 D7: names the abort cleared out of the launch queue (seq order). */
+	flushed?: readonly string[];
 }): AgentToolResult<unknown> {
 	const head = "interrupted (parent turn ended; children still running)";
-	const segments = [...input.results, ...input.collected].filter((segment) => segment.length > 0);
+	// #266 D7: a dropped queued launch is the reason the rest of the result is
+	// short, so it is reported even when nothing was collected at all. Trailing,
+	// like the command chain's line: it reads as a summary of what was cleared.
+	const segments = [
+		...input.results,
+		...input.collected,
+		launchQueueFlushLine(input.flushed ?? []),
+	].filter((segment) => segment.length > 0);
 	const stillRunning = input.handles
 		.filter(({ name }) => input.stillRunning.has(name))
 		.map(({ name }) => name);
@@ -2663,6 +3022,13 @@ function followJob(
 		treeIdentity?: { nodeId: string; parentId: string | null; depth: number };
 		/** Arbitrated backend from `Handle.spawnMode`; omitted when unknown (#209). */
 		spawnMode?: SpawnMode;
+		/**
+		 * Own process of an `rpc` child (`Handle.pid`), for the memory probe.
+		 * Omitted when the caller has no handle at hand — a rebuilt orchestrator
+		 * only knows `ChildRecord`, and a pid is not persisted, so it must not be
+		 * guessed or looked up elsewhere.
+		 */
+		pid?: number;
 	},
 ): void {
 	const child = input.orchestrator
@@ -2683,6 +3049,7 @@ function followJob(
 		...(child?.thinking !== undefined ? { thinking: child.thinking } : {}),
 		...(child?.worktreeBranch ? { worktreeBranch: child.worktreeBranch } : {}),
 		...(spawnMode ? { spawnMode } : {}),
+		...(input.pid ? { pid: input.pid } : {}),
 		...(input.treeIdentity ? input.treeIdentity : child?.nodeId ? {
 			nodeId: child.nodeId,
 			parentId: child.nodeId.includes(".") ? child.nodeId.slice(0, child.nodeId.lastIndexOf(".")) : null,
@@ -2760,16 +3127,21 @@ function followChild(ctx: ChildContext, opts: { watch: boolean }): void {
 }
 
 /**
- * The arbitrated backend recorded for one handled child of this request.
+ * The arbitrated backend recorded for one handled child of this request, plus
+ * the OS process of that child when the launch reported one.
  *
  * Spreads to nothing when unknown, so the caller never has to invent a value.
  */
 function spawnModeOf(
 	session: LaunchSession,
 	name: string,
-): { spawnMode?: SpawnMode } {
+): { spawnMode?: SpawnMode; pid?: number } {
 	const recorded = session.spawnByName.get(name);
-	return recorded ? { spawnMode: recorded.spawnMode } : {};
+	const pid = session.pidByName.get(name);
+	return {
+		...(recorded ? { spawnMode: recorded.spawnMode } : {}),
+		...(pid ? { pid } : {}),
+	};
 }
 
 function followLaunched(
@@ -2840,6 +3212,10 @@ async function abandonLaunchedChild(session: LaunchSession, name: string): Promi
 		session.runtime.release(name);
 		return;
 	}
+	// #266: a launch that never started cannot be "still running". Reporting it as
+	// watched would contradict the `N queued launch(es) dropped` line and tell the
+	// caller to wait for a child that will never produce a turn.
+	if (child.state === "queued") return;
 	// 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 });
@@ -2851,40 +3227,132 @@ async function abandonLaunchedChild(session: LaunchSession, name: string): Promi
 // ---------------------------------------------------------------------------
 
 /**
- * Live (non-retired / non-exited) children under this cwd for status overview.
+ * Child-record states that are terminal, so a record carrying one is never live
+ * (display-liveness D6, exit 1). `failed`/`settled` live on the execution side
+ * rather than in `TaskState`, but a run.json written by another version (or a
+ * hand-edited record) can carry them and they are terminal either way, so the
+ * set is keyed on strings instead of the narrow state union.
+ */
+const TERMINAL_STATUS_CHILD_STATES = new Set<string>([
+	"retired",
+	"exited",
+	"failed",
+	"settled",
+]);
+
+/** The persisted child record shape, as resolved through the run store. */
+type StatusChildRecord = NonNullable<ReturnType<RunStore["findChild"]>>;
+
+/**
+ * Liveness facts for one child, supplied by the caller.
  *
- * Names can be reused after retire; prefer the newest live record per name
- * (same preference as {@link pickChildByName}).
+ * `alive` is this process's in-memory supervisor answer (it never holds a child
+ * launched by another session); `owner` is the run-dir ownership verdict that
+ * covers that hole (#209-3). See {@link ownerVerdictFor}.
  */
-export function listLiveChildrenForStatus(
+export interface StatusLivenessFacts {
+	alive: boolean;
+	/** `undefined` while `alive` — in-memory liveness already decided (#209-3). */
+	owner?: "live" | "dead" | "unknown";
+}
+
+/** One run record after the status filter ran (display-liveness D6 exit 1). */
+export interface StatusChildClassification {
+	child: StatusChildRecord;
+	/**
+	 * Counted in `Status · N live children`. `false` = listed but NOT counted:
+	 * the record's run-dir owner pid is gone (#209-3 / A3).
+	 */
+	live: boolean;
+}
+
+/**
+ * Split the persisted child records under this cwd into `live` and `dead`.
+ *
+ * A record is dead when its owner pid is gone and this process is not running
+ * it — not merely when its `state` says so. `owner === "unknown"` counts as
+ * live: filtering unknown out would hide a child that may well be starting, and
+ * D2 forbids collapsing unknown into dead. Its block still reports
+ * `owner: unknown` + `state=working`, so it is never *displayed* as confirmed
+ * live — it is only not hidden.
+ *
+ * Names can be reused after retire, so the newest record per name wins, except
+ * that a dead record never shadows an older record of the same name that is
+ * still alive (same preference as {@link pickChildByName}).
+ *
+ * Without `factsFor` the filter falls back to the record state alone; that keeps
+ * this callable from a context that has no store (and keeps the pre-liveness
+ * signature working), but the `status` exit must pass facts.
+ */
+export function classifyChildrenForStatus(
 	runs: ReturnType<RunStore["listRuns"]>,
-): NonNullable<ReturnType<RunStore["findChild"]>>[] {
+	factsFor?: (child: StatusChildRecord) => StatusLivenessFacts,
+): StatusChildClassification[] {
 	const ranked = [...runs].sort((a, b) => b.createdAt.localeCompare(a.createdAt));
-	const seen = new Set<string>();
-	const out: NonNullable<ReturnType<RunStore["findChild"]>>[] = [];
+	const candidates: StatusChildClassification[] = [];
 	for (const run of ranked) {
 		for (const child of run.children) {
-			if (child.state === "retired" || child.state === "exited") continue;
-			if (seen.has(child.name)) continue;
-			seen.add(child.name);
-			out.push(child);
+			if (TERMINAL_STATUS_CHILD_STATES.has(child.state)) continue;
+			const facts = factsFor?.(child);
+			// Dead = the run dir's owner pid is gone AND this process is not running
+			// it. `owner === "unknown"` (no marker, or no pid in it) is never dead:
+			// unknown must not be collapsed into dead (display-liveness D2).
+			const live = !(facts?.owner === "dead" && !facts.alive);
+			candidates.push({ child, live });
 		}
 	}
-	return out;
+	// Name reuse: a newer DEAD record must not shadow an older record of the
+	// same name that is still live (mirror of `pickChildByName`, which prefers a
+	// live match over a newer retired one). Among equals the newest wins, hence
+	// the newest-first iteration order.
+	const chosen = new Map<string, StatusChildClassification>();
+	for (const entry of candidates) {
+		const prior = chosen.get(entry.child.name);
+		if (!prior || !prior.live) chosen.set(entry.child.name, entry);
+	}
+	return candidates.filter((entry) => chosen.get(entry.child.name) === entry);
 }
 
-/** Multi-child status text: one {@link renderLiveChildStatus} block per live child. */
-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, owner }) =>
+/**
+ * Live children under this cwd for the status overview.
+ *
+ * Pass `factsFor` to decide liveness from owner evidence instead of the record
+ * state alone; see {@link classifyChildrenForStatus}.
+ */
+export function listLiveChildrenForStatus(
+	runs: ReturnType<RunStore["listRuns"]>,
+	factsFor?: (child: StatusChildRecord) => StatusLivenessFacts,
+): StatusChildRecord[] {
+	return classifyChildrenForStatus(runs, factsFor).flatMap((entry) =>
+		entry.live ? [entry.child] : [],
+	);
+}
+
+/** One child block for {@link renderStatusOverview}. */
+export interface StatusChildEntry {
+	child: StatusChildRecord;
+	alive: boolean;
+	/** Run-dir ownership verdict (#209-3); see {@link renderLiveChildStatus}. */
+	owner?: "live" | "dead" | "unknown";
+	/**
+	 * Own process of an `rpc` child, when this session launched it. A pid is
+	 * not persisted, so a record from another session has none — and none is
+	 * invented here (D3).
+	 */
+	pid?: number;
+	/**
+	 * `false` = listed but not counted in the header (owner pid gone, see
+	 * {@link classifyChildrenForStatus}). Absent means live, so callers that only
+	 * hold live children keep their meaning.
+	 */
+	live?: boolean;
+}
+
+/** Multi-child status text: one {@link renderLiveChildStatus} block per child. */
+export function renderStatusOverview(children: StatusChildEntry[]): string {
+	const deadCount = children.filter((entry) => entry.live === false).length;
+	const liveCount = children.length - deadCount;
+	const blocks = children.map(({ child, alive, owner, pid }) =>
 		renderLiveChildStatus({
 			name: child.name,
 			state: child.state,
@@ -2896,9 +3364,22 @@ export function renderStatusOverview(
 			spawnMode: child.spawnMode,
 			alive,
 			...(owner ? { owner } : {}),
+			...(pid ? { pid } : {}),
 		}),
 	);
-	return [`Status · ${children.length} live ${noun}`, "", blocks.join("\n\n")].join("\n");
+	const parts: string[] = [];
+	if (liveCount === 0) {
+		// Nothing live. With no record at all this stays the exact literal the
+		// tests pin; with records that are all dead the count line below says so,
+		// instead of implying the run directory is empty.
+		parts.push("No live children.");
+	} else {
+		const noun = liveCount === 1 ? "child" : "children";
+		parts.push(`Status · ${liveCount} live ${noun}`);
+	}
+	if (deadCount > 0) parts.push(`(${deadCount} dead)`);
+	if (blocks.length > 0) parts.push("", blocks.join("\n\n"));
+	return parts.join("\n");
 }
 
 /**