pi-legion 2.0.0 → 2.0.1

package/src/extension/legion-doctor.ts

@@ -2,8 +2,9 @@
  * `/legion doctor` and `subagent action=diagnose`: broad self-check for
  * pi-legion (inspired by `pi list` / `pi auth check` / `pi --help`).
  *
- * Sections are filterable via `/legion doctor <section>` so the main agent can
- * pull only what it needs, then act on the structured Next steps.
+ * Sections are filterable via `/legion doctor [section]` or
+ * `subagent({ action: "diagnose", section })` so the main agent can pull only
+ * what it needs, then act on the structured Next steps.
  */
 
 import { execFileSync } from "node:child_process";
@@ -13,11 +14,16 @@ import * as path from "node:path";
 import {
 	CHILD_EXTENSIONS_ENV,
 	CHILD_INHERIT_EXTENSIONS_ENV,
-	childExtraExtensions,
-	childInheritsExtensions,
 	buildPiArgs,
+	childExtraExtensions,
 	childGuardExtensionPath,
+	childInheritsExtensions,
+	collectChildExtensions,
 } from "../runs/args.ts";
+import {
+	collectRoleToolExtensionIssues,
+	roleToolGateNextSteps,
+} from "../runs/role-tool-gates.ts";
 import { getAgentDir } from "../agents/paths.ts";
 import {
 	CHILD_MAX_OLD_SPACE_ENV,
@@ -50,6 +56,24 @@ import { IDLE_STOP_HINT, IDLE_STOP_HINT_SHORT } from "./legion-stop.ts";
 import type { AgentConfig } from "../shared/types.ts";
 import { recentSpawnFailures, type SpawnFailureRecord } from "./spawn-hints.ts";
 
+/**
+ * Canonical slash surface. `/legion help` and the doctor Tools section both
+ * print these lines so the two lists cannot drift.
+ */
+export const LEGION_SLASH_HELP_LINES = [
+	"/legion — open the Legion view (TUI)",
+	"/legion status [name] — whole-tree summary, or one node (same text as subagent status)",
+	"/legion team [list|use <name> [--global]|create <name> a,b,c [--global]]",
+	"/legion agents [user|project|both]",
+	"/legion on | /legion off — enable/disable subagents for this session (status is shown after each run)",
+	"/scout-guard | /no-scout-guard — session override for the main-session scout guard",
+	"/legion summary [--all] [<name>]",
+	"/legion doctor [section]",
+	"/legion stop [name|all]",
+	"/legion --tree | /legion <node>",
+	"/legion help",
+] as const;
+
 export const DOCTOR_SECTIONS = [
 	"summary",
 	"extensions",
@@ -64,6 +88,15 @@ export const DOCTOR_SECTIONS = [
 
 export type DoctorSection = (typeof DOCTOR_SECTIONS)[number];
 
+/**
+ * Doctor warns when `.hygiene-last.json` is missing or older than this.
+ * Shorter than the 14-day run-retention default so a week without a root
+ * restart surfaces before retention pruning goes quiet (#85).
+ */
+export const HYGIENE_SWEEP_STALE_DAYS = 7;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
 export interface DoctorPackage {
 	source: string;
 	name: string;
@@ -352,17 +385,10 @@ export function parseDoctorSections(raw: string | undefined): DoctorSection[] |
 	return out.length ? out : undefined;
 }
 
-function extensionsForRole(agent: AgentConfig, env: NodeJS.ProcessEnv, extras: string[]): string[] {
+function extensionsForRole(agent: AgentConfig, env: NodeJS.ProcessEnv, _extras: string[]): string[] {
 	if (childInheritsExtensions(agent, env)) return ["(all host-discovered extensions)"];
-	const seen = new Set<string>();
-	const out: string[] = [];
-	for (const ext of [...(agent.extensions ?? []), ...(agent.subagentOnlyExtensions ?? []), ...extras, childGuardExtensionPath()]) {
-		const resolved = path.resolve(ext);
-		if (seen.has(resolved)) continue;
-		seen.add(resolved);
-		out.push(ext);
-	}
-	return out;
+	// Same effective list as `buildPiArgs` / `collectChildExtensions` (#89 builtin:codemode).
+	return collectChildExtensions(agent, env);
 }
 
 function scanOrphanTemps(storeRoot: string): { total: number; orphanDead: number; live: number; unknown: number; samples: string[] } {
@@ -401,6 +427,61 @@ function formatBytes(n: number): string {
 	return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
 }
 
+interface HygieneLastMarker {
+	at?: number;
+	removedTempDirs?: number;
+	prunedRuns?: number;
+	deletedEvents?: number;
+	freedBytes?: number;
+	errors?: number;
+}
+
+function readHygieneLast(storeRoot: string): HygieneLastMarker | undefined {
+	const last = readJson(path.join(storeRoot, HYGIENE_LAST_FILE));
+	if (!last || typeof last !== "object") return undefined;
+	return last as HygieneLastMarker;
+}
+
+function hygieneSweepAt(last: HygieneLastMarker | undefined): number | undefined {
+	return typeof last?.at === "number" && Number.isFinite(last.at) ? last.at : undefined;
+}
+
+/**
+ * Mirrors `envNumber` in hygiene.ts: blank or non-finite / negative values
+ * fall back to the built-in default, so doctor labels those as default.
+ */
+function hygieneConfigSource(env: NodeJS.ProcessEnv, key: string): "default" | "env" {
+	const raw = env[key]?.trim();
+	if (!raw) return "default";
+	const n = Number(raw);
+	return Number.isFinite(n) && n >= 0 ? "env" : "default";
+}
+
+function formatHygieneToggleSource(env: NodeJS.ProcessEnv): string {
+	const raw = env[HYGIENE_ENV.disable]?.trim();
+	if (!raw) return `default; ${HYGIENE_ENV.disable}`;
+	return `env ${HYGIENE_ENV.disable}=${raw}`;
+}
+
+/** Effective `resolveHygieneConfig()` values, each tagged default or env. */
+function formatHygieneConfigLines(env: NodeJS.ProcessEnv): string[] {
+	const hy = resolveHygieneConfig(env);
+	const rows: Array<[string, string, string]> = [
+		["retentionDays", `${hy.retentionDays}d`, HYGIENE_ENV.retentionDays],
+		["staleNodeHours", `${hy.staleNodeHours}h`, HYGIENE_ENV.staleNodeHours],
+		["legacyTempHours", `${hy.legacyTempHours}h`, HYGIENE_ENV.legacyTempHours],
+		["eventRetentionDays", `${hy.eventRetentionDays}d`, HYGIENE_ENV.eventRetentionDays],
+		["eventMaxRows", String(hy.eventMaxRows), HYGIENE_ENV.eventMaxRows],
+	];
+	return rows.map(([label, value, envKey]) => {
+		const source = hygieneConfigSource(env, envKey);
+		return `    ${label}=${value} (${source === "env" ? `env ${envKey}` : "default"})`;
+	});
+}
+
+const HYGIENE_SWEEP_HINT =
+	`Restart the root pi session so startup hygiene runs, or check ${HYGIENE_ENV.disable}=0.`;
+
 export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 	const env = options.env ?? process.env;
 	const agentDir = options.agentDir ?? getAgentDir();
@@ -524,20 +605,12 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 	}
 
 	const agents = options.agents ?? (options.sampleAgent ? [options.sampleAgent] : []);
+	// #97: extensible tool→extension gates (lens #70, codemode #89, …).
 	for (const agent of agents) {
-		const needsLens = (agent.tools ?? []).some((t) => /lens|symbol_search|project_report|module_report|read_symbol|read_enclosing/i.test(t));
-		const exts = extensionsForRole(agent, env, extras);
-		const hasLens =
-			childInheritsExtensions(agent, env) ||
-			exts.some((e) => /pi-lens/i.test(e));
-		if (needsLens && !hasLens && !inheritGlobal) {
-			issues.push({
-				severity: "warning",
-				code: "ROLE_MISSING_LENS",
-				section: "extensions",
-				message: `Role "${agent.name}" lists lens tools but would not load pi-lens under --no-extensions.`,
-				fix: `Add pi-lens to ${agent.name}'s extensions: frontmatter, or to ${CHILD_EXTENSIONS_ENV}.`,
-			});
+		const inherits = childInheritsExtensions(agent, env) || inheritGlobal;
+		const exts = inherits ? [] : extensionsForRole(agent, env, extras);
+		for (const issue of collectRoleToolExtensionIssues(agent, exts, { inheritsExtensions: inherits })) {
+			issues.push(issue);
 		}
 	}
 
@@ -575,6 +648,7 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 
 	const storeRoot = options.storeRoot ?? (options.cwd ? path.join(options.cwd, ".pi-subagents") : undefined);
 	const orphans = storeRoot ? scanOrphanTemps(storeRoot) : undefined;
+	const hygieneLast = storeRoot ? readHygieneLast(storeRoot) : undefined;
 	if (orphans && orphans.orphanDead > 0) {
 		issues.push({
 			severity: "info",
@@ -583,6 +657,19 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 			message: `${orphans.orphanDead} rpc-child temp dir(s) have a dead owner (startup hygiene will remove them).`,
 		});
 	}
+	const sweepAt = hygieneSweepAt(hygieneLast);
+	const sweepStale = storeRoot !== undefined && (sweepAt === undefined || Date.now() - sweepAt > HYGIENE_SWEEP_STALE_DAYS * DAY_MS);
+	if (sweepStale) {
+		issues.push({
+			severity: "info",
+			code: "HYGIENE_SWEEP_STALE",
+			section: "storage",
+			message: sweepAt === undefined
+				? `No ${HYGIENE_LAST_FILE} marker — startup hygiene has not recorded a sweep.`
+				: `Last hygiene sweep ${new Date(sweepAt).toISOString()} is older than ${HYGIENE_SWEEP_STALE_DAYS} days.`,
+			fix: HYGIENE_SWEEP_HINT,
+		});
+	}
 
 	const verify = inspectVerifySlots(resolveVerifyQueueConfig(env));
 	const staleVerify = verify.holders.filter((h) => h.alive === false);
@@ -718,29 +805,28 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 
 	if (want(selected, "tools")) {
 		push("## Tools / commands");
-		push("- slash: `/legion` (view), `/legion doctor [section]`, `/legion stop [name|all]`, `/legion --tree`, `/legion <name>`");
+		push("- slash:");
+		for (const line of LEGION_SLASH_HELP_LINES) push(`    ${line}`);
 		push(`- stop wired: ${runtime.stopAvailable === undefined ? "(unknown)" : runtime.stopAvailable ? "yes" : "no"}`);
 		push(`- idle Esc stop wired: ${runtime.idleEscWired === undefined ? "(unknown)" : runtime.idleEscWired ? "yes" : "no"}`);
 		push(`- idle strip hints: "${IDLE_STOP_HINT}" / short "${IDLE_STOP_HINT_SHORT}"`);
 		push(`- legion tools registered: ${(runtime.legionTools ?? ["(unknown — typically subagent, vexillatio, legion-* mail/tools)"]).join(", ")}`);
-		push("- diagnose: `subagent({ action: \"diagnose\" })` or `subagent({ action: \"diagnose\" })` with section via `/legion doctor <section>`");
+		push("- slash: `/legion doctor [section]`");
+		push("- tool: `subagent({ action: \"diagnose\", section? })` — optional section filter (same as `/legion doctor [section]`)");
 		push("");
 	}
 
 	if (want(selected, "storage")) {
 		push("## Storage / hygiene");
-		push(`- hygiene enabled: ${hygieneEnabled(env)}`);
-		const hy = resolveHygieneConfig(env);
-		push(`- retention: runs ${hy.retentionDays}d, stale nodes ${hy.staleNodeHours}h, legacy temps ${hy.legacyTempHours}h, events ${hy.eventRetentionDays}d / max ${hy.eventMaxRows}`);
-		push(`- env: ${HYGIENE_ENV.disable}, ${HYGIENE_ENV.retentionDays}, ${HYGIENE_ENV.staleNodeHours}, …`);
+		push(`- hygiene enabled: ${hygieneEnabled(env)} (${formatHygieneToggleSource(env)})`);
+		push("- resolveHygieneConfig():");
+		for (const line of formatHygieneConfigLines(env)) push(line);
 		if (!storeRoot) {
 			push("- storeRoot: (not provided — pass cwd/storeRoot for db/orphan stats)");
 		} else {
 			push(`- storeRoot: ${homeize(storeRoot, home)}`);
-			const lastPath = path.join(storeRoot, HYGIENE_LAST_FILE);
-			const last = readJson(lastPath) as { at?: number; removedTempDirs?: number; prunedRuns?: number; deletedEvents?: number; freedBytes?: number; errors?: number } | undefined;
-			if (last?.at) {
-				push(`- last sweep: ${new Date(last.at).toISOString()} (removedTemps=${last.removedTempDirs ?? 0}, prunedRuns=${last.prunedRuns ?? 0}, deletedEvents=${last.deletedEvents ?? 0}, freed=${formatBytes(last.freedBytes ?? 0)}, errors=${last.errors ?? 0})`);
+			if (sweepAt !== undefined) {
+				push(`- last sweep: ${new Date(sweepAt).toISOString()} (removedTemps=${hygieneLast?.removedTempDirs ?? 0}, prunedRuns=${hygieneLast?.prunedRuns ?? 0}, deletedEvents=${hygieneLast?.deletedEvents ?? 0}, freed=${formatBytes(hygieneLast?.freedBytes ?? 0)}, errors=${hygieneLast?.errors ?? 0})`);
 			} else {
 				push("- last sweep: (no marker yet — written on next root-session startup hygiene)");
 			}
@@ -817,15 +903,16 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 			steps.push(`export ${CHILD_EXTENSIONS_ENV}=${providerExtHome.join(",")}  # then restart pi`);
 			steps.push(`# or role frontmatter extensions: […] / inheritExtensions: true (more RAM)`);
 		}
-		if (issues.some((i) => i.code === "ROLE_MISSING_LENS")) {
-			steps.push("Add pi-lens extension path to roles that list lens_* tools, or to PI_LEGION_CHILD_EXTENSIONS.");
-		}
+		steps.push(...roleToolGateNextSteps(issues));
 		if (issues.some((i) => i.code === "MEMORY_GATE_WOULD_REFUSE")) {
 			steps.push("Stop idle children (`/legion stop`) or lower/disable PI_LEGION_MIN_FREE_MEM_MB before launching more.");
 		}
 		if (issues.some((i) => i.code === "ORPHAN_TEMPS")) {
 			steps.push("Orphan temps clear on next root session start; or restart pi to trigger hygiene.");
 		}
+		if (selected.has("storage") && issues.some((i) => i.code === "HYGIENE_SWEEP_STALE")) {
+			steps.push(HYGIENE_SWEEP_HINT);
+		}
 		if (issues.some((i) => i.code === "STALE_VERIFY_SLOTS")) {
 			steps.push("Stale verify locks are reclaimed automatically; delete slot-*.lock under the lock dir if a slot stays stuck.");
 		}

package/src/extension/legion-status.ts

@@ -0,0 +1,172 @@
+/**
+ * `/legion status [name]` — chat text for humans.
+ *
+ * No name: the whole tree, same lines as `formatTree` (the legion_tree summary).
+ * A name: `renderLiveChildStatus`, the same text as `subagent({ action: "status" })`
+ * when a run-store child record is available.
+ */
+
+import { NODE_STATUSES, type LegionNode } from "../legion/nodes.ts";
+import { formatTree } from "./legion-tools.ts";
+import {
+	renderLiveChildStatus,
+	type LiveChildStatusInput,
+} from "./runtime.ts";
+
+/** Child snapshot the status tool already prints. `now` is supplied by the caller. */
+export type LegionChildStatusFacts = Omit<LiveChildStatusInput, "now">;
+
+export interface LegionStatusJob {
+	name: string;
+	nodeId?: string;
+	state: string;
+}
+
+export interface LegionStatusInput {
+	/** Empty shows the tree. Otherwise a node id, short id, or child name. */
+	query?: string;
+	nodes: readonly LegionNode[];
+	jobs?: readonly LegionStatusJob[];
+	/**
+	 * Persisted child behind the subagent status action.
+	 * Undefined when this process has no run-store record for the name.
+	 */
+	lookupChild?: (name: string) => LegionChildStatusFacts | undefined;
+	now?: number;
+}
+
+export interface LegionStatusReport {
+	ok: boolean;
+	text: string;
+}
+
+const LIVE_NODE_STATUSES = new Set(["starting", "running", "blocked"]);
+
+function nodesMatching(nodes: readonly LegionNode[], query: string): LegionNode[] {
+	const byId = nodes.filter((node) => node.id === query);
+	if (byId.length > 0) return byId;
+	return nodes.filter((node) =>
+		node.name === query || node.id.slice(node.id.lastIndexOf(".") + 1) === query,
+	);
+}
+
+function statusCounts(nodes: readonly LegionNode[]): string {
+	const counts = new Map<string, number>();
+	for (const node of nodes) counts.set(node.status, (counts.get(node.status) ?? 0) + 1);
+	const known = new Set<string>(NODE_STATUSES);
+	const ordered = [
+		...NODE_STATUSES.filter((status) => counts.has(status)),
+		...[...counts.keys()].filter((status) => !known.has(status)),
+	];
+	return ordered.map((status) => `${status}=${counts.get(status)}`).join(", ");
+}
+
+function withNow(facts: LegionChildStatusFacts, now: number | undefined): LiveChildStatusInput {
+	return now === undefined ? facts : { ...facts, now };
+}
+
+function liveJobForNode(node: LegionNode, jobs: readonly LegionStatusJob[]): LegionStatusJob | undefined {
+	return jobs.find((job) =>
+		job.state !== "retired" && (job.nodeId === node.id || (job.nodeId === undefined && job.name === node.name)),
+	);
+}
+
+function renderFacts(facts: LegionChildStatusFacts, now: number | undefined): string {
+	return renderLiveChildStatus(withNow(facts, now));
+}
+
+function renderNode(
+	node: LegionNode,
+	jobs: readonly LegionStatusJob[],
+	lookupChild: LegionStatusInput["lookupChild"],
+	now: number | undefined,
+): string {
+	const facts = lookupChild?.(node.name);
+	if (facts) return renderFacts(facts, now);
+	const job = liveJobForNode(node, jobs);
+	const alive = job
+		? job.state === "working" || job.state === "blocked"
+		: LIVE_NODE_STATUSES.has(node.status);
+	return renderLiveChildStatus(withNow({
+		name: node.name,
+		state: node.status,
+		agent: node.role,
+		kind: node.kind,
+		sessionFile: node.sessionFile ?? "",
+		alive,
+	}, now));
+}
+
+function renderJob(
+	job: LegionStatusJob,
+	lookupChild: LegionStatusInput["lookupChild"],
+	now: number | undefined,
+): string {
+	const facts = lookupChild?.(job.name);
+	if (facts) return renderFacts(facts, now);
+	return renderLiveChildStatus(withNow({
+		name: job.name,
+		state: job.state,
+		sessionFile: "",
+		alive: job.state === "working" || job.state === "blocked",
+	}, now));
+}
+
+function jobsOutsideTree(nodes: readonly LegionNode[], jobs: readonly LegionStatusJob[]): LegionStatusJob[] {
+	const ids = new Set(nodes.map((node) => node.id));
+	const names = new Set(nodes.map((node) => node.name));
+	return jobs.filter((job) =>
+		job.state !== "retired" &&
+		(job.nodeId === undefined || !ids.has(job.nodeId)) &&
+		!names.has(job.name),
+	);
+}
+
+function renderTree(nodes: readonly LegionNode[], jobs: readonly LegionStatusJob[]): string {
+	const noun = nodes.length === 1 ? "node" : "nodes";
+	const counts = nodes.length > 0 ? ` · ${statusCounts(nodes)}` : "";
+	const lines = [`Legion status · ${nodes.length} ${noun}${counts}`];
+	lines.push("");
+	lines.push(nodes.length > 0 ? formatTree(nodes) : "No legion nodes.");
+	const extras = jobsOutsideTree(nodes, jobs);
+	if (extras.length > 0) {
+		lines.push("", "Live jobs not in the tree:");
+		for (const job of extras) lines.push(`- ${job.name} state=${job.state}`);
+	}
+	lines.push("", "One node: /legion status <name>");
+	return lines.join("\n");
+}
+
+/** Human-readable `/legion status` text. `ok: false` is an unknown or ambiguous name. */
+export function renderLegionStatus(input: LegionStatusInput): LegionStatusReport {
+	const query = input.query?.trim() ?? "";
+	const jobs = input.jobs ?? [];
+	if (!query) return { ok: true, text: renderTree(input.nodes, jobs) };
+
+	const matches = nodesMatching(input.nodes, query);
+	if (matches.length > 1) {
+		return {
+			ok: false,
+			text: `"${query}" is ambiguous; use a full node id with /legion status <node-id>.`,
+		};
+	}
+	if (matches.length === 1) {
+		return { ok: true, text: renderNode(matches[0]!, jobs, input.lookupChild, input.now) };
+	}
+
+	const namedJobs = jobs.filter((job) => job.name === query || job.nodeId === query);
+	if (namedJobs.length > 1) {
+		return {
+			ok: false,
+			text: `"${query}" is ambiguous; use a full node id with /legion status <node-id>.`,
+		};
+	}
+	if (namedJobs.length === 1) {
+		return { ok: true, text: renderJob(namedJobs[0]!, input.lookupChild, input.now) };
+	}
+
+	const facts = input.lookupChild?.(query);
+	if (facts) return { ok: true, text: renderFacts(facts, input.now) };
+
+	return { ok: false, text: `Unknown Legion node "${query}".` };
+}

package/src/extension/playbook.ts

@@ -7,10 +7,10 @@ export const PLAYBOOK_NAME = "pi-legion-playbook";
 export const PARENT_PLAYBOOK = [
 	"Pi Legion playbook (frozen — do not invent a launch recipe):",
 	"1. Call the `subagent` tool immediately with the matching role from the roster in this prompt. Do not substitute bash/curl/web fetch for a search or research role.",
-	'   One child:  subagent({ agent: "<role>", task: "..." })',
+	'   One child:  subagent({ agent: "<role>", task: "...", name?: "scout-a" })  // optional name= registers that handle (not auto scout-N)',
 	"   Parallel:   subagent({ tasks: [{ agent, task }, { agent, task }] })",
 	"2. Prefer tasks[] for independent parallel work. Child processes are headless RPC children; no pane or tab is created.",
-	"3. Then return control. A completion message wakes this session when idle; if it is still working, the notice waits until the current turn ends. Use `wait` when you need blocking results, and `collect` to inspect a child's session JSONL. Pressing Esc to abort a parent turn gracefully retires its children; a wait interrupted by Esc returns `interrupted (parent turn aborted)` after cascade shutdown.",
+	"3. Then return control. A completion message wakes this session when idle; if it is still working, the notice waits until the current turn ends. Use `wait` when you need blocking results, and `collect` to inspect a child's session JSONL. Pressing Esc to abort a parent turn gracefully retires its children; a wait interrupted by Esc returns `interrupted (parent turn aborted)` after cascade shutdown. In `pi --print` or JSON mode, session shutdown waits for live async children to settle (up to each child's turn timeout) before retiring them. Use same-turn `wait`/`collect` or `async: false` when that print turn must include the child's result.",
 	"4. Later control is only through `subagent({ action, name, message })`; use `stop` to gracefully retire one child or all tracked children. If a child exits oddly (Model not found, missing tools, memory refused, …), call `subagent({ action: \"diagnose\" })` or ask the user to run `/legion doctor` / `/legion doctor models` — children use `--no-extensions`, so provider packages must be passed explicitly. Do not tell a child to message or prompt the parent directly.",
 	"5. A collect timeout with a live RPC child is a progress signal, not a verdict. Check status or session JSONL before deciding to steer or resume.",
 	"6. Isolation is YOUR call. Pass `worktree: true` when another parent may write this repo or the child must ship via MR; pass `worktree: false` to share the checkout. Omit it for the role default.",
@@ -22,7 +22,7 @@ export const PARENT_PLAYBOOK = [
 export const TOOL_DESCRIPTION = [
 	PARENT_PLAYBOOK,
 	"Roles: the system prompt lists every loaded role. Prefer the matching role over doing that work yourself.",
-	"Launch is async by default. Outcomes come from the child session JSONL.",
+	"Launch is async by default. Outcomes come from the child session JSONL. In non-interactive `pi --print` / JSON mode, shutdown waits for those children before retiring them; pass `async: false` or call `wait`/`collect` in the same turn to fold the result into the print output.",
 	"Actions: launch (default), continue, steer, resume, status, collect, wait, list, retire, stop, diagnose. `diagnose` prints the Legion doctor report (host vs child extensions/providers/models/memory). `wait` is event-driven: it returns when a child settles, times out, or the parent turn is aborted; an Esc abort also gracefully retires children owned by that turn. `stop` explicitly and gracefully retires selected children.",
 ].join(" ");
 

package/src/extension/runtime.ts

@@ -30,7 +30,7 @@ import {
 } from "../tui/status.ts";
 import { progressFromSessionFile } from "../shared/progress.ts";
 import { isTransientConnectionFailure } from "../shared/session.ts";
-import { DEFAULTS, type AgentKind } from "../shared/types.ts";
+import { DEFAULTS, type AgentKind, type RetireOptions } from "../shared/types.ts";
 import type {
 	EventSubscriptionOptions,
 	SupervisorEvent,
@@ -81,7 +81,7 @@ export interface TrackedJobInput {
 	isAlive?: () => boolean;
 	persist?: (snapshot: CollectSnapshot) => Promise<void>;
 	/** Retire the RPC child after a terminal collect. Blocked children stay alive. */
-	retire?: () => Promise<void>;
+	retire?: (opts?: RetireOptions) => Promise<void>;
 	/**
 	 * Called when collect reports a blocked child. `resume` rewatches after
 	 * the parent approved or denied; `hold` keeps the widget up.
@@ -190,10 +190,35 @@ export function lastJsonlEventAgeMs(sessionFile: string, now: number): number |
 	}
 }
 
+/** Quiet age at or above this is treated as a long silent stretch (P2a). */
+export const LONG_QUIET_MS = 30_000;
+
+/**
+ * Lead line for a living child: process is up, session JSONL quiet for N seconds.
+ * `ageMs` undefined means the session file is missing or unreadable.
+ * Long quiet (>= {@link LONG_QUIET_MS}) adds `(living)` so 「活着但安静」reads first.
+ */
+export function formatAliveQuiet(ageMs: number | undefined): string {
+	if (ageMs === undefined) return "alive · quiet unknown";
+	const secs = Math.floor(ageMs / 1000);
+	if (ageMs >= LONG_QUIET_MS) return `alive · quiet ${secs}s (living)`;
+	return `alive · quiet ${secs}s`;
+}
+
+/** @deprecated Prefer {@link formatAliveQuiet}; kept for older call sites. */
 export function formatLastEventAge(ageMs: number): string {
 	return `last event ${Math.floor(ageMs / 1000)}s ago`;
 }
 
+/**
+ * Collect-deadline / transient-connection / "still alive" reasons are progress
+ * signals, not verdicts. Showing them next to quiet age steals the eye.
+ */
+export function isAliveProgressSignalReason(reason: string | undefined): boolean {
+	if (!reason) return false;
+	return /still alive|rpc child alive|transient connection/i.test(reason);
+}
+
 function persistedSnapshotIsStale(input: LiveChildStatusInput): boolean {
 	if (!input.alive) return false;
 	if (input.state === "retired" || input.state === "exited") return true;
@@ -202,12 +227,27 @@ function persistedSnapshotIsStale(input: LiveChildStatusInput): boolean {
 	return isTransientConnectionFailure(execution);
 }
 
+function formatExecutionStatusLine(
+	alive: boolean,
+	execution: { status: string; reason?: string },
+): string {
+	const label = alive ? "execution snapshot" : "execution";
+	// Alive + progress-signal reason: status only — quiet age owns the liveness story.
+	if (alive && isAliveProgressSignalReason(execution.reason)) {
+		return `${label}: ${execution.status}`;
+	}
+	return `${label}: ${execution.status}${execution.reason ? ` (${execution.reason})` : ""}`;
+}
+
 /**
- * Status text for one child.
+ * Status text for one child (`/legion status <name>` and `subagent status`).
  *
- * A living child always reports how long the session JSONL has been quiet.
- * A retired/failed record left behind by a connection blip is not the current
- * state while that process is still alive.
+ * Living children lead with `alive · quiet Ns` so a long silent reasoning
+ * stretch is obvious before any execution/acceptance snapshot. Progress-signal
+ * reasons (collect deadline, transient connection) are omitted from the
+ * snapshot line while alive so they do not steal attention from quiet age.
+ * A retired or failed record left by a connection blip is not treated as
+ * current state while the RPC process is still alive.
  */
 export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 	const stale = persistedSnapshotIsStale(input);
@@ -217,13 +257,18 @@ export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 		: input.execution;
 	const lines = [
 		`${input.name} — state=${state} agent=${input.agent ?? "?"} kind=${input.kind ?? "?"}`,
+	];
+	if (input.alive) {
+		const age = lastJsonlEventAgeMs(input.sessionFile, input.now ?? Date.now());
+		lines.push(formatAliveQuiet(age));
+	}
+	// Quiet age first; path metadata after snapshots so old store lines stay below.
+	const meta = [
 		"supervisor=rpc",
 		`session=${input.sessionFile}`,
 	];
 	if (execution) {
-		lines.push(
-			`execution: ${execution.status}${execution.reason ? ` (${execution.reason})` : ""}`,
-		);
+		lines.push(formatExecutionStatusLine(input.alive, execution));
 		if (execution.usage) {
 			lines.push(
 				`usage: in=${execution.usage.input} out=${execution.usage.output} cost=${execution.usage.cost.toFixed(4)}`,
@@ -231,14 +276,12 @@ export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 		}
 	}
 	if (!stale && input.acceptance) {
+		const acceptanceLabel = input.alive ? "acceptance snapshot" : "acceptance";
 		lines.push(
-			`acceptance: ${input.acceptance.status}${input.acceptance.level ? ` (${input.acceptance.level})` : ""}`,
+			`${acceptanceLabel}: ${input.acceptance.status}${input.acceptance.level ? ` (${input.acceptance.level})` : ""}`,
 		);
 	}
-	if (input.alive) {
-		const age = lastJsonlEventAgeMs(input.sessionFile, input.now ?? Date.now());
-		if (age !== undefined) lines.push(formatLastEventAge(age));
-	}
+	lines.push(...meta);
 	if (stale) {
 		const persistedExecution = input.execution
 			? `execution=${input.execution.status}${input.execution.reason ? ` (${input.execution.reason})` : ""}`
@@ -310,6 +353,11 @@ export interface SessionRuntime {
 		names: string[],
 		opts?: { timeoutMs?: number; signal?: AbortSignal },
 	): Promise<WaitResult[]>;
+	/**
+	 * Non-interactive shutdown: let in-flight collects finish before the
+	 * caller retires whatever is still alive. Watches do not re-arm.
+	 */
+	drainBeforeShutdown(): Promise<void>;
 	dispose(): void;
 }
 
@@ -329,6 +377,8 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 	let dbEventSource: DbEventSource | undefined;
 	let timer: ReturnType<typeof setInterval> | undefined;
 	let disposed = false;
+	let draining = false;
+	let drainPromise: Promise<void> | undefined;
 	let busyRaised = false;
 
 	// Smart join: batch completion notices per runId. The deliver sink merges
@@ -800,6 +850,15 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 				try {
 					snapshot = await ensureCollect(job);
 					if (disposed || job.generation !== gen) return;
+					// Print/json shutdown is waiting on this collect. A timeout or
+					// a blocked child must stay tracked so the caller can retire
+					// it; re-arming would start another turn after the process
+					// has already decided to exit.
+					if (draining && !shouldRecycleAfterCollect(snapshot.execution.status)) {
+						hold = true;
+						job.watching = false;
+						return;
+					}
 					if (snapshot.blocked) {
 						job.state = "blocked";
 						refreshUi();
@@ -1087,6 +1146,26 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			);
 		},
 
+		drainBeforeShutdown() {
+			if (disposed) return Promise.resolve();
+			if (drainPromise) return drainPromise;
+			draining = true;
+			const pending = [...jobs.values()];
+			drainPromise = (async () => {
+				await Promise.all(pending.map(async (job) => {
+					try {
+						await ensureCollect(job);
+					} catch {
+						// The watch records the failure; shutdown still retires the child.
+					}
+				}));
+				// The watch continuation shares this collect and must observe
+				// `draining` before the caller snapshots the jobs it will retire.
+				await new Promise<void>((resolve) => setImmediate(resolve));
+			})();
+			return drainPromise;
+		},
+
 		dispose() {
 			if (disposed) return;
 			disposed = true;