pi-legion 2.0.4 → 3.0.0

package/index.ts

@@ -20,6 +20,8 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 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 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";
@@ -42,6 +44,7 @@ import {
 	loadSubagentSettings,
 	resolveSubagentSettings,
 } from "./src/agents/settings.ts";
+import { resolveTeamContext } from "./src/agents/context.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";
@@ -56,6 +59,7 @@ import { parseNestedPathEnv } from "./src/shared/nested-path.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 { currentChildContext } from "./src/supervisor/child-context.ts";
 import { setVerifyQueueListener } from "./src/runs/verify-queue.ts";
 import { applyEventRetention, checkpoint, formatHygieneReport, hygieneEnabled, runStartupHygiene } from "./src/runs/hygiene.ts";
 import {
@@ -80,6 +84,7 @@ import {
 } from "./src/extension/notify.ts";
 import { renderSubagentNotice } from "./src/extension/notice-renderer.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";
 import { expectedModelsFromSettings, parseDoctorSections, runLegionDoctor } from "./src/extension/legion-doctor.ts";
 import { readFileSync } from "node:fs";
@@ -99,6 +104,7 @@ import {
 	type ModelOrigin,
 	type RetireOptions,
 	SubagentError,
+	type SubagentsSettings,
 } from "./src/shared/types.ts";
 
 // ---------------------------------------------------------------------------
@@ -143,7 +149,7 @@ const SubagentParams = Type.Object({
 				Type.Literal("stop"),
 				Type.Literal("diagnose"),
 			],
-			{ description: "Defaults to launch. diagnose = Legion doctor self-check (extensions/models/spawn/memory/tools/storage/runtime); optional section filters like /legion doctor." },
+			{ description: "Defaults to launch. wait REQUIRES name or all:true (mutually exclusive) — bare wait is rejected. diagnose = Legion doctor self-check (extensions/models/spawn/memory/tools/storage/runtime); optional section filters like /legion doctor." },
 		),
 	),
 	agent: Type.Optional(
@@ -188,12 +194,12 @@ const SubagentParams = Type.Object({
 	name: Type.Optional(
 		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 (wait/stop/collect/…): addresses that child. For status: omit (or pass all:true) for a live-children overview; pass name for one child.",
+				"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 wait: REQUIRED unless all:true (mutually exclusive with all). On other control actions (stop/collect/…): addresses that child. For status: omit (or pass all:true) for a live-children overview; pass name for one child.",
 		}),
 	),
 	all: Type.Optional(
 		Type.Boolean({
-			description: "wait: wait for active children; stop: stop every non-retired child; status: overview of all live (non-retired) children under cwd",
+			description: "wait: REQUIRED unless name is set — wait for every live (working/blocked) child; mutually exclusive with name. stop: stop every non-retired child; status: overview of all live (non-retired) children under cwd",
 		}),
 	),
 	timeoutMs: Type.Optional(
@@ -201,6 +207,12 @@ const SubagentParams = Type.Object({
 			description: "wait: per-child timeout in ms; event-driven completion returns early (default: role turnTimeoutMs)",
 		}),
 	),
+	force: Type.Optional(
+		Type.Boolean({
+			description:
+			'stop only: when true, hard-retire via SIGTERM→SIGKILL + descendant sweep (retire hardening). Omit/false = graceful retire. Example: subagent({ action: "stop", name: "worker-0", force: true }).',
+		}),
+	),
 	message: Type.Optional(
 		Type.String({ description: "Text for steer/continue" }),
 	),
@@ -210,7 +222,7 @@ const SubagentParams = Type.Object({
 	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.',
+				'diagnose only: optional section filter (summary|extensions|models|spawn|memory|tools|storage|runtime|errors|next), same as `/legion doctor [section]`. Space/comma-separated for multiple.',
 		}),
 	),
 });
@@ -272,8 +284,8 @@ function settingsForLegion(settings: ReturnType<typeof loadSubagentSettings>): L
 	return { ...DEFAULT_LEGION_SETTINGS, ...(settings.legion ?? {}), phaseTimeouts: { ...DEFAULT_LEGION_SETTINGS.phaseTimeouts, ...(settings.legion?.phaseTimeouts ?? {}) } };
 }
 
-function runStoreFor(cwd: string): RunStore {
-	const sharedDbPath = process.env[LEGION_DB_ENV];
+function runStoreFor(cwd: string, dbPathOverride?: string): RunStore {
+	const sharedDbPath = dbPathOverride ?? process.env[LEGION_DB_ENV];
 	if (sharedDbPath && path.isAbsolute(sharedDbPath)) {
 		const storeRoot = path.dirname(path.dirname(path.dirname(sharedDbPath)));
 		return new RunStore({ rootDir: storeRoot });
@@ -350,9 +362,17 @@ function resolveLegionIdentity(input: {
 	cached?: LegionRuntimeIdentity;
 	/** This process's session file (identity credential). From ctx.sessionManager. */
 	sessionFile?: string | undefined;
+	/**
+	 * In-process child identity (#197 D8): the orchestrator names the ledger row
+	 * this session owns. Wins over `process.env.PI_LEGION_DB/NODE_ID` because an
+	 * in-process child shares the parent's env and would otherwise read the
+	 * *parent's* identity — or nothing at all when the parent is root.
+	 */
+	legionNode?: { dbPath: string; nodeId: string } | undefined;
 }): LegionRuntimeIdentity | undefined {
-	const dbPath = process.env[LEGION_DB_ENV];
-	const nodeId = process.env[LEGION_NODE_ID_ENV];
+	const injected = input.legionNode;
+	const dbPath = injected?.dbPath ?? process.env[LEGION_DB_ENV];
+	const nodeId = injected?.nodeId ?? process.env[LEGION_NODE_ID_ENV];
 	if (Boolean(dbPath) !== Boolean(nodeId)) throw new Error("PI_LEGION_DB and PI_LEGION_NODE_ID must be set together");
 	if (dbPath && nodeId) {
 		if (!path.isAbsolute(dbPath)) throw new Error("PI_LEGION_DB must be an absolute path");
@@ -469,15 +489,26 @@ 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: catalog.settings.childContext, parentPath: parentRun.path, legion: { db: input.db, dbPath: input.dbPath, nodeId: parent.id, parentNodeId: parent.parentId, parentRunId: parentOfSupervisor?.runId ?? null, runId: parentRun.runId, runStore: store, settings: input.settings, eventBus: input.eventBus } });
+	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 } });
 	orchestrator.restore(parentRun);
 	const handle = await orchestrator.launch({ agent, task: input.message, name: saved.name, ...(input.node.team ? { team: input.node.team } : {}), ...(saved.model ? { model: saved.model } : {}), worktree: Boolean(saved.worktreePath) });
 	await store.updateChild(parentRun.runId, saved.name, (child) => Object.assign(child, handle.child));
 }
 
 export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps = {}) {
-	const isChild = process.env.PI_SUBAGENT_CHILD === "1";
-	const allowNested = process.env[ALLOW_NESTED_ENV] === "1";
+	// #197 D8: a session is a child if either transport says so. RPC children
+	// are separate processes marked in env; in-process children share the
+	// parent's `process.env`, so their marker can only come from the
+	// AsyncLocalStorage child context the orchestrator injects.
+	//
+	// Security note: the ALS context does not survive `spawn()`, so a real
+	// subprocess (`bash npm test`, a nested CLI, …) cannot inherit this
+	// identity. That is exactly the isolation the env channel lacked — see the
+	// "healthy ghost nodes" incident documented at the identity credential
+	// check in `resolveLegionIdentity`. Do not replace this with env injection.
+	const childContext = currentChildContext();
+	const isChild = process.env.PI_SUBAGENT_CHILD === "1" || childContext !== undefined;
+	const allowNested = process.env[ALLOW_NESTED_ENV] === "1" || childContext?.allowNested === true;
 	if (isChild) restoreHostNodeOptions();
 	else {
 		// Root UI: surface verify-queue waits instead of a silent stall.
@@ -488,10 +519,28 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			} catch { /* no UI */ }
 		});
 	}
-	const supervisor = deps.supervisor ?? new RpcSupervisor({
-		onSpawnRefused: (message) => {
-			try { lastUi?.notify(`pi-legion: ${message}`, "error"); } catch { /* no UI (child / print mode) */ }
-		},
+	const onSpawnRefused = (message: string) => {
+		try { lastUi?.notify(`pi-legion: ${message}`, "error"); } catch { /* no UI (child / print mode) */ }
+	};
+	// Mutable host cwd so inprocess limits can re-read project settings as the
+	// extension follows the parent session's working directory (#197).
+	let lastCwd = process.cwd();
+	const supervisor = deps.supervisor ?? new RoutingSupervisor({
+		rpc: new RpcSupervisor({ onSpawnRefused }),
+		inprocess: new InProcessSupervisor({
+			onSpawnRefused,
+			getLimits: () => {
+				try {
+					return loadSubagentSettings({
+						userSettingsPath: path.join(getAgentDir(), "settings.json"),
+						projectSettingsPath: path.join(lastCwd, ".pi", "settings.json"),
+					}).inprocess;
+				} catch {
+					return undefined;
+				}
+			},
+		}),
+		onSpawnRefused,
 	});
 	const verifyRunner = deps.verifyRunner;
 	const legionBus = createLegionEventBus();
@@ -516,7 +565,6 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			return true;
 		}
 	};
-	let lastCwd = process.cwd();
 	let legionIdentity: LegionRuntimeIdentity | undefined;
 	const stopLegionRuntime = (): void => {
 		if (!legionIdentity) return;
@@ -528,13 +576,15 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		legionIdentity.db.close();
 		legionIdentity = undefined;
 	};
-	const initializeLegionRuntime = (ctx: Pick<ExtensionContext, "cwd"> & { sessionFile?: string }): void => {
-		const store = runStoreFor(ctx.cwd);
+	const initializeLegionRuntime = (ctx: Pick<ExtensionContext, "cwd"> & { sessionFile?: string; legionNode?: { dbPath: string; nodeId: string } }): void => {
+		// The injected node's dbPath is authoritative: an in-process child shares the
+		// parent's env, so PI_LEGION_DB here belongs to the parent (or is unset).
+		const store = runStoreFor(ctx.cwd, ctx.legionNode?.dbPath);
 		const settings = loadSubagentSettings({
 			userSettingsPath: path.join(getAgentDir(), "settings.json"),
 			projectSettingsPath: path.join(ctx.cwd, ".pi", "settings.json"),
 		});
-		const next = resolveLegionIdentity({ pi, supervisor, store, cwd: ctx.cwd, settings, eventBus: legionBus, cached: legionIdentity, sessionFile: ctx.sessionFile });
+		const next = resolveLegionIdentity({ pi, supervisor, store, cwd: ctx.cwd, settings, eventBus: legionBus, cached: legionIdentity, sessionFile: ctx.sessionFile, legionNode: ctx.legionNode });
 		if (legionIdentity && next !== legionIdentity) stopLegionRuntime();
 		legionIdentity = next;
 	};
@@ -546,30 +596,80 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			try { initializeLegionRuntime({ cwd: process.cwd() }); }
 			catch (error) { console.error(`[pi-legion] legion initialization failed: ${error instanceof Error ? error.message : String(error)}`); }
 		}
+		// #197 D8: an in-process child never sees `session_start` — the SDK emits it
+		// from `bindExtensions`, which only rpc / print / interactive modes call;
+		// `createAgentSession` does not. So the handler further down is dead for
+		// this transport and the injected identity is attached here instead.
+		//
+		// It is attached on the first ctx-bearing event rather than at extension
+		// load: the identity credential (this session's transcript file) only
+		// exists on `ctx.sessionManager`, and skipping it would defeat the
+		// ghost-node guard inside `resolveLegionIdentity`.
+		if (childContext?.nodeId && childContext.dbPath) {
+			const legionNode = { dbPath: childContext.dbPath, nodeId: childContext.nodeId };
+			let attached = false;
+			const attachInjectedChildIdentity = (_event: unknown, ctx?: { cwd?: string; sessionManager?: { getSessionFile?: () => string | undefined } }): void => {
+				if (attached) return;
+				attached = true;
+				try {
+					initializeLegionRuntime({
+						cwd: ctx?.cwd ?? process.cwd(),
+						legionNode,
+						sessionFile: ctx?.sessionManager?.getSessionFile?.(),
+					});
+				} catch (error) {
+					console.error(`[pi-legion] legion initialization failed: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			};
+			pi.on("before_agent_start", attachInjectedChildIdentity);
+		}
 	}
+	// #37/#38/#40/#181: one best-effort storage sweep per root process.
+	// Deferred 1.5s so interactive first paint is not blocked; unref so a long
+	// idle session can exit. Short --print sessions exit before the timer —
+	// flushHygieneIfPending on session_shutdown still runs the sweep once.
 	let hygieneScheduled = false;
+	let hygieneCompleted = false;
+	let pendingHygiene: { storeRoot: string; timer?: ReturnType<typeof setTimeout>; notify?: (text: string) => void } | undefined;
+	const flushHygieneIfPending = (): void => {
+		if (hygieneCompleted || !pendingHygiene || !hygieneEnabled()) return;
+		hygieneCompleted = true;
+		if (pendingHygiene.timer) {
+			clearTimeout(pendingHygiene.timer);
+			pendingHygiene.timer = undefined;
+		}
+		const { storeRoot, notify } = pendingHygiene;
+		try {
+			const report = runStartupHygiene({ storeRoot, protectRunIds: legionIdentity ? [legionIdentity.rootRunId] : [] });
+			const text = formatHygieneReport(report);
+			if (text) notify?.(text);
+		} catch (error) {
+			console.error(`[pi-legion] storage sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
 	pi.on("session_start", (_event, ctx) => {
 		try { initializeLegionRuntime({ cwd: ctx.cwd, sessionFile: ctx.sessionManager?.getSessionFile() }); }
 		catch (error) { console.error(`[pi-legion] legion initialization failed: ${error instanceof Error ? error.message : String(error)}`); }
-		// #37/#38/#40: one deferred, best-effort storage sweep per root process.
 		if (!isChild && !hygieneScheduled && hygieneEnabled()) {
 			hygieneScheduled = true;
 			const storeRoot = runStoreFor(ctx.cwd).rootDir;
 			const timer = setTimeout(() => {
-				try {
-					const report = runStartupHygiene({ storeRoot, protectRunIds: legionIdentity ? [legionIdentity.rootRunId] : [] });
-					const text = formatHygieneReport(report);
-					if (text) ctx.ui?.notify?.(text, "info");
-				} catch (error) {
-					console.error(`[pi-legion] storage sweep failed: ${error instanceof Error ? error.message : String(error)}`);
-				}
+				flushHygieneIfPending();
 			}, 1_500);
 			timer.unref?.();
+			pendingHygiene = {
+				storeRoot,
+				timer,
+				notify: (text) => ctx.ui?.notify?.(text, "info"),
+			};
 		}
 	});
 	const pendingUtilityRetires: Array<(opts?: RetireOptions) => Promise<void>> = [];
 	let sessionRuntime: SessionRuntime | undefined;
 	const shutdownRetireAll = async (_event?: unknown, ctx?: { mode?: string }): Promise<void> => {
+		// #181: short --print exits before the deferred timer; flush now so
+		// orphan rpc-child-* dirs still get swept on a clean exit.
+		if (!isChild) flushHygieneIfPending();
 		// 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.
@@ -636,7 +736,11 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		if (Array.isArray(tools) && !tools.includes("subagent") && !tools.includes("vexillatio")) return;
 		if (ctx?.cwd) lastCwd = ctx.cwd;
 		const catalog = loadCatalog(lastCwd, lastCwd, undefined);
-		const parentContext = catalog.settings.parentContext?.trim();
+		const parentContext = resolveTeamContext(
+			"parent",
+			catalog.settings,
+			catalog.team,
+		);
 		return {
 			systemPrompt: `${event.systemPrompt}\n\n${PARENT_PLAYBOOK}\n\n${renderParentRoster(
 				catalog.agents,
@@ -650,6 +754,10 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		return;
 	}
 	let lastUi: ExtensionUIContext | undefined;
+	/** Child slugs currently reported as OSC id=legion/<slug>. */
+	const childOscIds = new Set<string>();
+	/** Extension activity sources forwarded from children via RPC. */
+	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
@@ -686,9 +794,41 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			},
 			options,
 		) ?? (() => {}),
-		emitBusy: (active, label) => {
+		emitBusy: (active, label, children = []) => {
 			try { pi.events.emit("pi-legion:busy", active ? { active: true, label } : { active: false }); }
 			catch { /* optional display integration */ }
+			const ui = lastUi as (ExtensionUIContext & {
+				setActivity?: (source: string, activity: { message?: string } | undefined) => void;
+				setProgramRecord?: (status: { state: "working" | "clear"; id: string; message?: string }) => void;
+			}) | undefined;
+			const next = new Set(active ? children : []);
+			// Drop RPC-fan-in activities for retired children (and everything on full clear).
+			if (typeof ui?.setActivity === "function") {
+				for (const source of [...childActivitySources]) {
+					const slug = source.startsWith("legion/") ? source.slice("legion/".length).split("/")[0] : undefined;
+					if (!active || !slug || !next.has(slug)) {
+						try { ui.setActivity(source, undefined); } catch { /* ignore */ }
+						childActivitySources.delete(source);
+					}
+				}
+				try {
+					ui.setActivity("legion", active ? { message: label } : undefined);
+				} catch { /* setActivity is optional until Pi ships it */ }
+			}
+			if (typeof ui?.setProgramRecord === "function") {
+				for (const slug of [...childOscIds]) {
+					if (!next.has(slug)) {
+						try { ui.setProgramRecord({ id: `legion/${slug}`, state: "clear" }); } catch { /* ignore */ }
+						childOscIds.delete(slug);
+					}
+				}
+				for (const slug of next) {
+					try {
+						ui.setProgramRecord({ id: `legion/${slug}`, state: "working", message: slug });
+						childOscIds.add(slug);
+					} catch { /* ignore */ }
+				}
+			}
 		},
 	});
 	sessionRuntime = runtime;
@@ -723,6 +863,8 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 				userSettingsPath: path.join(getAgentDir(), "settings.json"),
 				projectSettingsPath: path.join(cwd, ".pi", "settings.json"),
 			}),
+			// #182: suppress "拆 scout" nag while launches are forbidden.
+			subagentsEnabled: (cwd) => subagentsEnabled(cwd),
 		});
 	}
 	// The parent transcript records every finish; the renderer keeps a
@@ -731,12 +873,17 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 
 	// User stop controls (/legion stop, idle Esc, `x` in /legion): a thin wrapper
 	// over the subagent tool's `stop` action — graceful retire of tracked children.
-	const stopChildren = async (params: { name?: string; all?: boolean }): Promise<{ ok: boolean; text: string }> => {
+	// Nova follow-up: `/legion stop --force` can pass `force: true` here (#179).
+	const stopChildren = async (params: {
+		name?: string;
+		all?: boolean;
+		force?: boolean;
+	}): Promise<{ ok: boolean; text: string }> => {
 		const result = await stopAction({
 			params,
 			runtime,
-			retire: async (name) => {
-				await runtime.get(name)?.retire?.();
+			retire: async (name, opts) => {
+				await runtime.get(name)?.retire?.(opts);
 			},
 		});
 		const text = result.content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
@@ -837,6 +984,7 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			}
 			const cwd = params.cwd ?? ctx.cwd;
 			const store = runStoreFor(cwd);
+			configureSessionErrors({ storeRoot: store.rootDir, tool: "subagent", action });
 			const catalog = loadCatalog(ctx.cwd, cwd, params.agentScope);
 			const { allAgents, settings } = catalog;
 			const teamName = action === "launch" ? params.team : undefined;
@@ -990,6 +1138,36 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		else if (request.method === "setWidget") ui.setWidget(request.widgetKey, request.widgetLines, { placement: request.widgetPlacement });
 		else if (request.method === "setTitle") ui.setTitle(request.title);
 		else if (request.method === "set_editor_text") ui.setEditorText(request.text);
+		else if (request.method === "setActivity") {
+			const uiExt = ui as ExtensionUIContext & {
+				setActivity?: (source: string, activity: { message?: string } | undefined) => void;
+			};
+			if (typeof uiExt.setActivity !== "function") return;
+			const source = `legion/${pending.childName}/${request.source}`;
+			if (request.activity) {
+				childActivitySources.add(source);
+				uiExt.setActivity(source, request.activity);
+			} else {
+				childActivitySources.delete(source);
+				uiExt.setActivity(source, undefined);
+			}
+		} else if (request.method === "setProgramRecord") {
+			const record = request.record;
+			const uiExt = ui as ExtensionUIContext & {
+				setProgramRecord?: (status: {
+					state: "idle" | "working" | "blocked" | "done" | "error" | "clear";
+					id: string;
+					app?: string;
+					kind?: "permission" | "question" | "auth";
+					message?: string;
+				}) => void;
+			};
+			if (typeof uiExt.setProgramRecord !== "function") return;
+			const id = record.id.startsWith("legion/")
+				? record.id
+				: `legion/${pending.childName}/${record.id}`;
+			uiExt.setProgramRecord({ ...record, id });
+		}
 	});
 
 	pi.on("session_start", (event, ctx) => {
@@ -1118,7 +1296,7 @@ async function controlAction(input: {
 		}
 		if (!params.name && !params.all) {
 			return fail(
-				"`name` or `all` is required for wait",
+				"`name` or `all` is required for wait (try all:true or name:\"child-name\")",
 				ErrorCodes.INVALID_PARAMS,
 			);
 		}
@@ -1134,13 +1312,16 @@ async function controlAction(input: {
 	}
 
 	if (action === "stop") {
+		const force = params.force === true;
+		const retireOpts = force ? { graceful: false as const } : undefined;
 		return stopAction({
 			params,
 			runtime: input.runtime,
-			retire: async (name) => {
+			retire: async (name, opts) => {
+				const merged = opts ?? retireOpts;
 				const job = input.runtime.get(name);
 				if (job?.retire) {
-					await job.retire();
+					await job.retire(merged);
 					return;
 				}
 				// A completion watch can retire/release a target after stop snapshots
@@ -1155,13 +1336,14 @@ async function controlAction(input: {
 					runDir: input.store.runDir(found.runId),
 					cwd: input.cwd,
 					maxDepth: input.settings.legion?.maxDepth,
-					childContext: input.settings.childContext,
+					childContext: resolveTeamContext("child", input.settings, input.team),
 					...teamForChildren(input.team),
+					...rpcApproveFrom(input.settings),
 					...(input.legion ? { legion: { ...input.legion, runId: found.runId, runStore: input.store } } : {}),
 					onBudgetRefused: input.onBudgetRefused,
 				});
 				orchestrator.restore(found.run);
-				await orchestrator.retire(name);
+				await orchestrator.retire(name, merged);
 				await persistChild(input.store, found.runId, orchestrator, name);
 			},
 		});
@@ -1216,11 +1398,12 @@ async function controlAction(input: {
 		runDir: store.runDir(found.runId),
 		cwd,
 		maxDepth: input.settings.legion?.maxDepth,
-		childContext: input.settings.childContext,
+		childContext: resolveTeamContext("child", input.settings, input.team),
 		verifyRunner: input.verifyRunner,
 		worktreeBootstrap: input.settings.legion?.worktreeBootstrap,
 		worktreeBootstrapTimeoutMs: input.settings.legion?.worktreeBootstrapTimeoutMs,
 		...teamForChildren(input.team),
+		...rpcApproveFrom(input.settings),
 		...(input.legion ? { legion: { ...input.legion, runId: found.runId, runStore: store } } : {}),
 		onBudgetRefused: input.onBudgetRefused,
 	});
@@ -1500,11 +1683,12 @@ async function launchFamily(input: {
 		cwd,
 		maxDepth: settings.legion?.maxDepth,
 		maxSpawns: settings.maxSubagentSpawnsPerSession ?? null,
-		childContext: settings.childContext,
+		childContext: resolveTeamContext("child", settings, input.team),
 		verifyRunner: input.verifyRunner,
 		worktreeBootstrap: settings.legion?.worktreeBootstrap,
 		worktreeBootstrapTimeoutMs: settings.legion?.worktreeBootstrapTimeoutMs,
 		...teamForChildren(input.team),
+		...rpcApproveFrom(settings),
 		...(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,
 	});
@@ -2071,8 +2255,9 @@ async function launchUtilityFamily(input: {
 			cwd,
 			maxDepth: catalog.settings.legion?.maxDepth,
 			maxSpawns: catalog.settings.maxSubagentSpawnsPerSession ?? null,
-			childContext: catalog.settings.childContext,
+			childContext: resolveTeamContext("child", catalog.settings, catalog.team),
 			team: catalog.team,
+			...rpcApproveFrom(catalog.settings),
 			onBudgetRefused: input.onBudgetRefused,
 			...(legion ? {
 				legion: {
@@ -2597,7 +2782,7 @@ export function resolveWaitTargets(
 		return { ok: true, names: live.map((job) => job.name) };
 	}
 	const name = params.name;
-	if (!name) return { ok: false, message: "`name` or `all` is required for wait" };
+	if (!name) return { ok: false, message: "`name` or `all` is required for wait (try all:true or name:\"child-name\")" };
 	if (live.some((job) => job.name === name)) {
 		return { ok: true, names: [name] };
 	}
@@ -2607,6 +2792,63 @@ export function resolveWaitTargets(
 	};
 }
 
+/** Parent-side decision hints when wait leaves children live (#179). */
+export const WAIT_PARENT_DECISIONS = [
+	"extend",
+	"steer_again",
+	"stop",
+	"force_stop",
+] as const;
+
+export type WaitParentDecision = (typeof WAIT_PARENT_DECISIONS)[number];
+
+export const WAIT_TIMEOUT_HINT =
+	"wait does not stop children; choose stop/force_stop or extend/steer";
+
+export interface WaitStillRunningChild {
+	name: string;
+	elapsedMs: number;
+	budgetMs?: number;
+}
+
+/** Structured wait result when children are still live after wait (#179). */
+export interface WaitTimeoutDetails {
+	status: "wait_timeout" | "budget_exceeded" | "still_running";
+	done: number;
+	stillRunning: WaitStillRunningChild[];
+	decisions: WaitParentDecision[];
+	hint: string;
+}
+
+/** Build parent-decision payload when wait leaves children live. Does not stop them. */
+export function buildWaitTimeoutDetails(
+	results: WaitResult[],
+): WaitTimeoutDetails | undefined {
+	const stillRunning: WaitStillRunningChild[] = [];
+	let timedOut = false;
+	let done = 0;
+	for (const result of results) {
+		if (result.snapshot) {
+			done += 1;
+			continue;
+		}
+		if (!result.stillRunning) continue;
+		if (result.timedOut) timedOut = true;
+		stillRunning.push({
+			name: result.name,
+			elapsedMs: result.elapsedMs ?? 0,
+		});
+	}
+	if (stillRunning.length === 0) return undefined;
+	return {
+		status: timedOut ? "wait_timeout" : "still_running",
+		done,
+		stillRunning,
+		decisions: [...WAIT_PARENT_DECISIONS],
+		hint: WAIT_TIMEOUT_HINT,
+	};
+}
+
 /** Render one wait result, reusing the collect shape for finished children. */
 export function renderWait(results: WaitResult[]): string {
 	let done = 0;
@@ -2619,7 +2861,9 @@ export function renderWait(results: WaitResult[]): string {
 			parts.push(renderCollect(result.name, result.snapshot));
 		} else if (result.stillRunning) {
 			running += 1;
-			parts.push(`── ${result.name} ──\nstill running`);
+			const elapsed =
+				result.elapsedMs !== undefined ? ` (elapsed ${result.elapsedMs}ms)` : "";
+			parts.push(`── ${result.name} ──\nstill running${elapsed}`);
 		} else if (result.interrupted) {
 			interrupted += 1;
 			parts.push(`── ${result.name} ──\ninterrupted (parent turn ended; children still running)`);
@@ -2629,14 +2873,23 @@ export function renderWait(results: WaitResult[]): string {
 	}
 	parts.push(`${done} done, ${running} still running`);
 	if (interrupted > 0) parts.push(`${interrupted} interrupted`);
+	const details = buildWaitTimeoutDetails(results);
+	if (details) {
+		parts.push(`status: ${details.status}`);
+		parts.push(`decisions: ${details.decisions.join(", ")}`);
+		parts.push(`hint: ${details.hint}`);
+	}
 	return parts.join("\n");
 }
 
-/** Gracefully retire a named child or every child tracked by this session. */
+/**
+ * Retire a named child or every child tracked by this session.
+ * `force: true` → hard path (graceful:false / SIGTERM→SIGKILL); omit/false → graceful.
+ */
 export async function stopAction(input: {
-	params: { name?: string; all?: boolean };
+	params: { name?: string; all?: boolean; force?: boolean };
 	runtime: SessionRuntime;
-	retire: (name: string) => Promise<void>;
+	retire: (name: string, opts?: RetireOptions) => Promise<void>;
 }): Promise<AgentToolResult<unknown>> {
 	const { params, runtime, retire } = input;
 	if (params.name && params.all) {
@@ -2645,6 +2898,8 @@ export async function stopAction(input: {
 	if (!params.name && !params.all) {
 		return fail("`name` or `all` is required for stop", ErrorCodes.INVALID_PARAMS);
 	}
+	const force = params.force === true;
+	const retireOpts: RetireOptions | undefined = force ? { graceful: false } : undefined;
 	const jobs = runtime.activeJobs();
 	const active = jobs.filter((job) => job.state !== "retired");
 	let targets: string[];
@@ -2669,18 +2924,19 @@ export async function stopAction(input: {
 		try {
 			// The runtime job may have been released after the target snapshot was
 			// taken. The retire adapter can then resolve its persisted run record.
-			await retire(name);
+			await retire(name, retireOpts);
 			runtime.release(name);
 			stopped.push(name);
 		} catch (error) {
-			// If the graceful-retire chain fails, restore the completion watcher so a
+			// If the retire chain fails, restore the completion watcher so a
 			// still-live child is not orphaned by the explicit stop attempt.
 			if (runtime.get(name)) runtime.rewatch(name);
 			failures.push(`${name}: ${String(error)}`);
 		}
 	}
+	const mode = force ? "force-stopped" : "Stopped";
 	const summary = stopped.length
-		? `Stopped ${stopped.length} child${stopped.length === 1 ? "" : "ren"}: ${stopped.join(", ")}.`
+		? `${mode} ${stopped.length} child${stopped.length === 1 ? "" : "ren"}: ${stopped.join(", ")}.`
 		: "No children were stopped.";
 	return failures.length
 		? fail(`${summary}\nFailed to stop: ${failures.join("; ")}`, ErrorCodes.RETIRE_FAILED)
@@ -2732,7 +2988,11 @@ export async function waitAction(input: {
 			}),
 		);
 	const results = await runtime.wait(targets.names, { timeoutMs, ...(signal ? { signal } : {}) });
-	return ok(renderWait(results));
+	const text = renderWait(results);
+	const details = buildWaitTimeoutDetails(results);
+	return details
+		? { content: [{ type: "text", text }], details }
+		: ok(text);
 }
 
 export function renderAgentList(
@@ -2789,6 +3049,11 @@ function teamForChildren(team: ActiveTeam): { team?: ActiveTeam } {
 	return team.name !== DEFAULT_TEAM || team.source === "env" ? { team } : {};
 }
 
+/** Opt-in `--approve` for RPC children (`subagents.rpc.approve`, #193). */
+function rpcApproveFrom(settings: Pick<SubagentsSettings, "rpc">): { rpcApprove?: boolean } {
+	return settings.rpc?.approve === true ? { rpcApprove: true } : {};
+}
+
 /** Prefer a role under the active team, then fall back for existing children. */
 function findControlAgent(
 	agents: AgentConfig[],
@@ -2911,5 +3176,6 @@ function ok(text: string): AgentToolResult<unknown> {
  * `details` and the message text carries the failure signal.
  */
 function fail(text: string, code: string): AgentToolResult<unknown> {
+	recordSessionError({ code, message: text });
 	return { content: [{ type: "text", text }], details: { error: code } };
 }