pi-legion 2.0.0 → 2.0.1

package/index.ts

@@ -35,6 +35,7 @@ import {
 	type ActiveTeam,
 } from "./src/agents/teams.ts";
 import { resolveModel } from "./src/agents/model-resolution.ts";
+import { providerForModel, type ProviderLookup } from "./src/runs/provider-pin.ts";
 import { resolveStepModel } from "./src/agents/step-model.ts";
 import { checkModelScope } from "./src/agents/model-scope.ts";
 import {
@@ -52,7 +53,7 @@ import { attachUsageTotals, upsertUsage } from "./src/legion/usage.ts";
 import { getChildByName, getChildren, getNode, getSubtree, insertNode, type LegionNode, updateNode } from "./src/legion/nodes.ts";
 import { DEFAULT_LEGION_SETTINGS, type LegionSettings } from "./src/shared/types.ts";
 import { parseNestedPathEnv } from "./src/shared/nested-path.ts";
-import { allocateSiblingNames, makeName } from "./src/shared/name.ts";
+import { allocateSiblingNames, isValidAgentName, makeName } from "./src/shared/name.ts";
 import { deriveOutcome, isLastTurnComplete, parseSessionFile } from "./src/shared/session.ts";
 import { restoreHostNodeOptions } from "./src/supervisor/child-memory.ts";
 import { setVerifyQueueListener } from "./src/runs/verify-queue.ts";
@@ -81,7 +82,7 @@ import {
 import { renderSubagentNotice } from "./src/extension/notice-renderer.ts";
 import { PARENT_PLAYBOOK, TOOL_DESCRIPTION } from "./src/extension/playbook.ts";
 import { getAgentDir } from "./src/agents/paths.ts";
-import { expectedModelsFromSettings, runLegionDoctor } from "./src/extension/legion-doctor.ts";
+import { expectedModelsFromSettings, parseDoctorSections, runLegionDoctor } from "./src/extension/legion-doctor.ts";
 import { readFileSync } from "node:fs";
 import {
 	effectiveMaxDepth,
@@ -97,6 +98,7 @@ import {
 	DEFAULT_ON_BLOCKED,
 	ErrorCodes,
 	type ModelOrigin,
+	type RetireOptions,
 	SubagentError,
 } from "./src/shared/types.ts";
 
@@ -146,7 +148,7 @@ const SubagentParams = Type.Object({
 				Type.Literal("stop"),
 				Type.Literal("diagnose"),
 			],
-			{ description: "Defaults to launch. diagnose = Legion doctor full self-check (extensions/models/spawn/memory/tools/storage/runtime)." },
+			{ description: "Defaults to launch. diagnose = Legion doctor self-check (extensions/models/spawn/memory/tools/storage/runtime); optional section filters like /legion doctor." },
 		),
 	),
 	agent: Type.Optional(
@@ -189,7 +191,10 @@ const SubagentParams = Type.Object({
 		),
 	),
 	name: Type.Optional(
-		Type.String({ description: "Child handle name (control actions, including wait and stop)" }),
+		Type.String({
+			description:
+				"Child handle name. On launch (single agent+task): registers this exact name (lowercase [a-z][a-z0-9_-]{0,31}) instead of auto scout-N; collisions refuse. On control actions (status/wait/stop/…): addresses that child.",
+		}),
 	),
 	all: Type.Optional(
 		Type.Boolean({
@@ -207,6 +212,12 @@ const SubagentParams = Type.Object({
 	team: Type.Optional(
 		Type.String({ description: "Team to use for the launched child and its nested roster" }),
 	),
+	section: Type.Optional(
+		Type.String({
+			description:
+				'diagnose only: optional section filter (summary|extensions|models|spawn|memory|tools|storage|runtime|next), same as `/legion doctor [section]`. Space/comma-separated for multiple.',
+		}),
+	),
 });
 
 /** The validated tool parameters, as the model supplies them. */
@@ -469,7 +480,7 @@ async function resumeLegionChild(input: { pi: ExtensionAPI; supervisor: LegionSu
 	await store.updateChild(parentRun.runId, saved.name, (child) => Object.assign(child, handle.child));
 }
 
-export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervisorDeps = {}) {
+export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps = {}) {
 	cascadePromise = undefined;
 	const isChild = process.env.PI_SUBAGENT_CHILD === "1";
 	const allowNested = process.env[ALLOW_NESTED_ENV] === "1";
@@ -562,14 +573,22 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 			timer.unref?.();
 		}
 	});
-	const pendingUtilityRetires: Array<() => Promise<void>> = [];
+	const pendingUtilityRetires: Array<(opts?: RetireOptions) => Promise<void>> = [];
 	let sessionRuntime: SessionRuntime | undefined;
-	const shutdownRetireAll = async (): Promise<void> => {
+	const shutdownRetireAll = async (_event?: unknown, ctx?: { mode?: string }): Promise<void> => {
+		// pi --print / JSON exits when the parent turn ends. Async children
+		// have only just been spawned; retiring them here aborts the run
+		// before the first model call. Interactive quit still retires immediately.
+		const mode = ctx?.mode;
+		if (mode === "print" || mode === "json") {
+			await sessionRuntime?.drainBeforeShutdown();
+		}
 		const children = sessionRuntime?.activeJobs() ?? [];
 		sessionRuntime?.dispose();
+		const shutdownRetire: RetireOptions = { cause: "session-shutdown" };
 		await Promise.all([
-			...children.map((job) => job.retire?.().catch(() => {})),
-			...pendingUtilityRetires.map((retire) => retire().catch(() => {})),
+			...children.map((job) => job.retire?.(shutdownRetire).catch(() => {})),
+			...pendingUtilityRetires.map((retire) => retire(shutdownRetire).catch(() => {})),
 		]);
 		stopLegionRuntime();
 	};
@@ -786,6 +805,27 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 		runtime,
 		supervisor: rpcEventSource,
 		stop: stopChildren,
+		childStatus: (name, cwd) => {
+			try {
+				const found = findChild(runStoreFor(cwd).listRuns(), name);
+				if (!found) return undefined;
+				const child = found.child;
+				return {
+					name: child.name,
+					state: child.state,
+					agent: child.agent,
+					kind: child.kind,
+					sessionFile: child.sessionFile,
+					...(child.execution ? { execution: child.execution } : {}),
+					...(child.acceptance
+						? { acceptance: { status: child.acceptance.status, level: child.acceptance.level } }
+						: {}),
+					alive: supervisor.isAlive(child.name),
+				};
+			} catch {
+				return undefined;
+			}
+		},
 		commands: {
 			team: { loadCatalog: commandCatalogLoader },
 			agents: { loadCatalog: commandCatalogLoader },
@@ -868,6 +908,17 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 
 			if (action === "list") return ok(renderAgentList(agents, team, teamWarnings));
 			if (action === "diagnose") {
+				let sections;
+				try {
+					sections = parseDoctorSections(
+						typeof params.section === "string" ? params.section : undefined,
+					);
+				} catch (error) {
+					return fail(
+						error instanceof Error ? error.message : String(error),
+						ErrorCodes.INVALID_PARAMS,
+					);
+				}
 				let settings: unknown;
 				try {
 					settings = JSON.parse(readFileSync(path.join(getAgentDir(), "settings.json"), "utf8"));
@@ -881,6 +932,7 @@ export default function herdrSubagents(pi: ExtensionAPI, deps: ExtensionSupervis
 					expectedModels: expectedModelsFromSettings(settings),
 					sampleAgent: agents[0],
 					agents,
+					sections,
 					runtime: {
 						liveJobs: runtime.activeJobs().map((job) => ({
 							name: job.name,
@@ -1460,6 +1512,8 @@ async function launchFamily(input: {
 
 	const plan = buildPlan(params);
 	if (!plan.ok) return fail(plan.message, ErrorCodes.INVALID_PARAMS);
+	const nameGate = resolveExplicitLaunchName(params.name, plan.steps.length);
+	if (!nameGate.ok) return fail(nameGate.message, ErrorCodes.INVALID_PARAMS);
 
 	onUpdate?.({
 		content: [
@@ -1536,9 +1590,11 @@ async function launchFamily(input: {
 		dispatchModel: ctx.model
 			? `${ctx.model.provider}/${ctx.model.id}`
 			: undefined,
+		modelRegistry: ctx.modelRegistry,
 		results: [],
 		handles: [],
 		timeoutByName: new Map(),
+		...(nameGate.name ? { launchName: nameGate.name } : {}),
 	};
 
 	const interruptedResult = async (): Promise<AgentToolResult<unknown> | undefined> => {
@@ -1619,9 +1675,13 @@ interface LaunchSession {
 	runtime: SessionRuntime;
 	onUpdate?: AgentToolUpdateCallback;
 	dispatchModel: string | undefined;
+	/** Parent registry, used to pin `--provider` for ambiguous model ids (#123). */
+	modelRegistry: ProviderLookup | undefined;
 	results: string[];
 	handles: string[];
 	timeoutByName: Map<string, number>;
+	/** Explicit child name for this single-step launch; omit to auto-allocate. */
+	launchName?: string;
 }
 
 /**
@@ -1700,13 +1760,20 @@ async function launchStep(
 			return;
 		}
 
-		// Let `launch()` allocate from the supervisor-local registry; the index
-		// must not race separate subagent tool calls.
+		// Honor `name=` when the caller asked for one; otherwise let `launch()`
+		// allocate from the supervisor-local registry (scout-N). The index must
+		// not race separate subagent tool calls for auto names.
 		const handle = await session.orchestrator.launch({
 			agent: launchedAgent,
 			task: step.task,
+			...(session.launchName ? { name: session.launchName } : {}),
 			...(session.teamOverride ? { team: session.teamOverride } : {}),
 			...(resolved.model ? { model: resolved.model } : {}),
+			// Pin the provider (#123): a bare id like `workbuddy/...` may also
+			// exist under a static auth-less provider in models.json; under
+			// `--no-extensions` the child would resolve it there and die with
+			// "No API key found". The parent registry knows the live provider.
+			...(resolved.model ? { modelProvider: providerForModel(session.modelRegistry, resolved.model) } : {}),
 			// The origin decides whether an unacceptable model is refused or
 			// dropped, and only this layer can tell them apart (a parent model
 			// arrives as the same `dispatch` source as a per-run override).
@@ -1924,7 +1991,7 @@ async function launchUtilityFamily(input: {
 	legion?: LegionRuntimeIdentity;
 	eventBus: LegionEventBus;
 	onLegion: (identity: LegionRuntimeIdentity) => void;
-	onUtilityChild: (retire: () => Promise<void>) => void;
+	onUtilityChild: (retire: (opts?: RetireOptions) => Promise<void>) => void;
 }): Promise<AgentToolResult<unknown>> {
 	const plan = buildUtilityPlan(input.params);
 	if (!plan.ok) return fail(plan.message, ErrorCodes.INVALID_PARAMS);
@@ -2092,6 +2159,8 @@ async function launchUtilityFamily(input: {
 				task: item.step.task,
 				name: names.get(item.step),
 				...(item.resolved.model ? { model: item.resolved.model } : {}),
+				// Provider pin (#123) — see launchStep for the rationale.
+				...(item.resolved.model ? { modelProvider: providerForModel(input.ctx.modelRegistry, item.resolved.model) } : {}),
 				modelOrigin: item.modelOrigin,
 				...(item.step.worktree !== undefined ? { worktree: item.step.worktree } : {}),
 				utilityDispatch: true,
@@ -2099,10 +2168,10 @@ async function launchUtilityFamily(input: {
 			});
 			await persistChild(store, runId, orchestrator, handle.name);
 			let retirement: Promise<void> | undefined;
-			const retire = (): Promise<void> => {
+			const retire = (opts?: RetireOptions): Promise<void> => {
 				if (!retirement) {
 					const current = (async () => {
-						await orchestrator.retire(handle.name);
+						await orchestrator.retire(handle.name, opts);
 						await persistChild(store, runId, orchestrator, handle.name);
 					})();
 					retirement = current;
@@ -2112,9 +2181,9 @@ async function launchUtilityFamily(input: {
 				}
 				return retirement;
 			};
-			input.onUtilityChild(async () => {
+			input.onUtilityChild(async (opts) => {
 				try {
-					await retire();
+					await retire(opts);
 				} catch {
 					// Shutdown cleanup is best-effort; the supervisor owns final process state.
 				}
@@ -2141,7 +2210,7 @@ async function launchUtilityFamily(input: {
 		agent: string;
 		sessionFile: string;
 		orchestrator: Orchestrator;
-		retire: () => Promise<void>;
+		retire: (opts?: RetireOptions) => Promise<void>;
 	}> = [];
 	for (const launch of launches) {
 		if ("error" in launch) results.push(`✗ ${launch.item.agent.name}: ${launch.error}`);
@@ -2211,6 +2280,41 @@ async function launchUtilityFamily(input: {
 	};
 }
 
+/**
+ * Resolve an explicit `name=` on launch.
+ *
+ * Prefer honoring the caller's handle over auto `role-N`, so `/legion status <name>`
+ * and control actions match the tool parameter. Multi-step `tasks[]` cannot share
+ * one name; invalid grammar is refused rather than silently sanitized into a
+ * different handle the caller would not find.
+ */
+export function resolveExplicitLaunchName(
+	requested: string | undefined,
+	stepCount: number,
+): { ok: true; name?: string } | { ok: false; message: string } {
+	if (requested === undefined) return { ok: true };
+	const trimmed = requested.trim();
+	if (!trimmed) {
+		return { ok: false, message: "`name` must not be blank when provided." };
+	}
+	if (stepCount > 1) {
+		return {
+			ok: false,
+			message:
+				"`name` applies only to a single (agent+task) launch, not tasks[] with multiple steps.",
+		};
+	}
+	const normalized = trimmed.toLowerCase();
+	if (!isValidAgentName(normalized)) {
+		return {
+			ok: false,
+			message:
+				`invalid child name "${trimmed}": must match [a-z][a-z0-9_-]{0,31} (lowercase letter first, max 32 chars).`,
+		};
+	}
+	return { ok: true, name: normalized };
+}
+
 export function buildPlan(params: {
 	agent?: string;
 	task?: string;
@@ -2319,7 +2423,7 @@ function followJob(
 		orchestrator: Orchestrator;
 		store: RunStore;
 		watch: boolean;
-		retire?: () => Promise<void>;
+		retire?: (opts?: RetireOptions) => Promise<void>;
 		treeIdentity?: { nodeId: string; parentId: string | null; depth: number };
 	},
 ): void {
@@ -2350,12 +2454,12 @@ function followJob(
 		isAlive: () => input.orchestrator.isChildAlive(input.name),
 		persist: async () =>
 			persistChild(input.store, input.runId, input.orchestrator, input.name),
-		retire: async () => {
+		retire: async (opts) => {
 			if (input.retire) {
-				await input.retire();
+				await input.retire(opts);
 				return;
 			}
-			await input.orchestrator.retire(input.name);
+			await input.orchestrator.retire(input.name, opts);
 			await persistChild(
 				input.store,
 				input.runId,

package/package.json

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

package/skills/pi-legion/SKILL.md

@@ -32,14 +32,20 @@ directly.
 
 ## Legion visualization
 
-In an interactive Pi session, `/legion` opens the paged Legion tree. Navigate
-with `j`/`k` or the arrow keys, use Enter/Space to expand or collapse, `/` to
-search, and PageUp/PageDown to scroll; `q` or Esc closes the tree. Press `o` on
-the selected node, or use a component-routed mouse click in the full-screen
-tree, to open its live overlay. `/legion <name>` opens a node directly. If
-short names are ambiguous, use the full node ID shown in command completion.
-Esc closes an overlay and unsubscribes its node's live feed. OSC 8 links are
-visual anchors only; they do not open overlays or route clicks.
+In an interactive Pi session, bare `/legion` opens the **galaxy / tok-s / log**
+full view (when a viz snapshot is available and you did not pass `--tree`).
+Tab switches panes; arrows move or scroll; Enter selects an agent; `o` opens
+its live overlay; `q` or Esc closes. `/legion --tree` opens the classic paged
+tree (`j`/`k`, Enter/Space fold, `/` search, PageUp/PageDown). `/legion <name>`
+opens a node overlay directly; if short names are ambiguous, use the full node
+ID from completion. `/legion status` prints the whole tree in chat (same lines
+as `legion_tree`); `/legion status <name>` prints one node like
+`subagent({ action: "status", name })`. Esc closes an overlay and unsubscribes
+its live feed. OSC 8 links are visual anchors only.
+
+To stop live children yourself: `/legion stop` (or `/legion stop <name>`), idle
+Esc with an empty editor (confirm "Stop N running subagents?"), or `x` then `y`
+on the selected live agent in the `/legion` view or overlay.
 
 ## Tree tools and phases
 
@@ -92,7 +98,15 @@ subagent({ action: "resume", name: "worker-0" })
 subagent({ action: "retire", name: "worker-0" })
 ```
 
+A person can read that same status without a tool call: `/legion status` for
+the tree, `/legion status <name>` for one child.
+
 For a blocked extension UI request, the RPC supervisor bubbles the request up
 to the root Pi UI for human response by default. A child completion or a
 `legion_mail` message is not a substitute for checking its saved result and
 machine-recorded state.
+
+`pi --print` and JSON mode wait for live async children during session
+shutdown, up to each child's turn timeout. That keeps a just-spawned child
+from being retired before its first assistant message. To put the child's
+result in the same print turn, use `wait`, `collect`, or `async: false`.

package/src/agents/agents.ts

@@ -63,12 +63,24 @@ export const BUILTIN_AGENTS_DIR = path.resolve(
  * or vendored roles without copying them into the writable user agent dir. These
  * load as `user`-level, at LOWER precedence than the real user directory, so a
  * user's own definition of the same name still wins.
+ *
+ * Canonical env: `PI_LEGION_EXTRA_AGENT_DIRS`. The Herdr-era name
+ * `PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS` remains a compatibility alias for at
+ * least one minor version. When both are set, the new name wins (old ignored).
  */
-export const EXTRA_AGENT_DIRS_ENV = "PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS";
+export const EXTRA_AGENT_DIRS_ENV = "PI_LEGION_EXTRA_AGENT_DIRS";
 
-/** Split `PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS` into absolute directory paths. */
-function extraAgentDirs(): string[] {
-	const raw = process.env[EXTRA_AGENT_DIRS_ENV];
+/** @deprecated Use {@link EXTRA_AGENT_DIRS_ENV} (`PI_LEGION_EXTRA_AGENT_DIRS`). */
+export const LEGACY_EXTRA_AGENT_DIRS_ENV = "PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS";
+
+let legacyExtraAgentDirsWarned = false;
+
+/** @internal Reset one-shot deprecation warn (unit tests). */
+export function resetExtraAgentDirsDeprecationWarnForTests(): void {
+	legacyExtraAgentDirsWarned = false;
+}
+
+function splitExtraAgentDirEntries(raw: string | undefined): string[] {
 	if (!raw) return [];
 	return raw.split(path.delimiter).flatMap((entry) => {
 		const trimmed = entry.trim();
@@ -76,6 +88,49 @@ function extraAgentDirs(): string[] {
 	});
 }
 
+function envHasContent(value: string | undefined): value is string {
+	return value !== undefined && value.trim() !== "";
+}
+
+/**
+ * Resolve PATH-style extra agent dirs from env.
+ *
+ * Priority: `PI_LEGION_EXTRA_AGENT_DIRS` overrides
+ * `PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS` when both are set. Setting the legacy
+ * name alone still works and emits one stderr deprecation warning per process.
+ */
+export function resolveExtraAgentDirs(
+	env: NodeJS.ProcessEnv = process.env,
+	warn: (message: string) => void = (message) => console.warn(message),
+): string[] {
+	const modern = env[EXTRA_AGENT_DIRS_ENV];
+	const legacy = env[LEGACY_EXTRA_AGENT_DIRS_ENV];
+	const hasModern = envHasContent(modern);
+	const hasLegacy = envHasContent(legacy);
+
+	if (hasLegacy && !legacyExtraAgentDirsWarned) {
+		legacyExtraAgentDirsWarned = true;
+		if (hasModern) {
+			warn(
+				`[pi-legion] Both ${EXTRA_AGENT_DIRS_ENV} and ${LEGACY_EXTRA_AGENT_DIRS_ENV} are set; using ${EXTRA_AGENT_DIRS_ENV} (new name wins). Remove the deprecated ${LEGACY_EXTRA_AGENT_DIRS_ENV}.`,
+			);
+		} else {
+			warn(
+				`[pi-legion] ${LEGACY_EXTRA_AGENT_DIRS_ENV} is deprecated; use ${EXTRA_AGENT_DIRS_ENV}. The old name remains as a compatibility alias for at least one minor version.`,
+			);
+		}
+	}
+
+	if (hasModern) return splitExtraAgentDirEntries(modern);
+	if (hasLegacy) return splitExtraAgentDirEntries(legacy);
+	return [];
+}
+
+/** Split env extra-agent-dir entries into absolute directory paths. */
+function extraAgentDirs(): string[] {
+	return resolveExtraAgentDirs();
+}
+
 const VALID_KINDS: ReadonlySet<string> = new Set(AGENT_KINDS);
 
 const VALID_ON_BLOCKED: ReadonlySet<string> = new Set([
@@ -600,7 +655,7 @@ export interface DiscoverOptions {
  *
  * Precedence, lowest to highest:
  *   builtin (shipped with the package)
- *   extra dirs (`PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS`)
+ *   extra dirs (`PI_LEGION_EXTRA_AGENT_DIRS`, legacy `PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS`)
  *   user    (`~/.pi/agent/agents`)
  *   project (`<nearest>/.pi/agents`)
  *

package/src/api.ts

@@ -34,6 +34,7 @@ export {
 	BUILTIN_AGENT_NAMES,
 	BUILTIN_AGENTS_DIR,
 	EXTRA_AGENT_DIRS_ENV,
+	LEGACY_EXTRA_AGENT_DIRS_ENV,
 	discoverAgents,
 	findAgent,
 	findNearestProjectAgentsDir,
@@ -41,6 +42,7 @@ export {
 	formatAgentRoster,
 	loadAgentsFromDir,
 	parseAgentDocument,
+	resolveExtraAgentDirs,
 } from "./agents/agents.ts";
 export type { DiscoverOptions } from "./agents/agents.ts";
 export {

package/src/extension/legion-commands.ts

@@ -4,11 +4,16 @@ import { matchesKey, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { resolveStopTarget, runLegionStop, stopCompletions, type StopDeps } from "./legion-stop.ts";
 import {
 	DOCTOR_SECTIONS,
+	LEGION_SLASH_HELP_LINES,
 	expectedModelsFromSettings,
 	parseDoctorSections,
 	runLegionDoctor,
 	type DoctorRuntimeSnapshot,
 } from "./legion-doctor.ts";
+import {
+	renderLegionStatus,
+	type LegionChildStatusFacts,
+} from "./legion-status.ts";
 import { ALLOW_NESTED_ENV } from "./budget.ts";
 import {
 	createAgentsCommand,
@@ -91,6 +96,11 @@ export interface LegionCommandDeps {
 	supervisor: RpcEventSource;
 	/** Graceful retire via the subagent `stop` action (see legion-stop.ts). */
 	stop?: (params: { name?: string; all?: boolean }) => Promise<{ ok: boolean; text: string }>;
+	/**
+	 * Persisted child snapshot used by `subagent({ action: "status" })`.
+	 * Undefined when this process has no run-store record for `name`.
+	 */
+	childStatus?: (name: string, cwd: string) => LegionChildStatusFacts | undefined;
 	/** Existing user-facing subcommand handlers; absent only in isolated tests. */
 	commands?: {
 		team: TeamCommandDeps;
@@ -181,6 +191,32 @@ function nodeLabel(nodeId: string, name: string): string {
 	return `${name} (${nodeId})`;
 }
 
+/** Completions for `/legion status <prefix>`: tree nodes, then live jobs the tree does not already name. */
+function statusArgumentCompletions(
+	prefix: string,
+	deps: LegionCommandDeps,
+): Array<{ value: string; label: string }> {
+	const nodes = deps.runtime.treeNodes();
+	const out: Array<{ value: string; label: string }> = [];
+	const seen = new Set<string>();
+	const add = (value: string, label: string): void => {
+		if (!value.startsWith(prefix) || seen.has(value)) return;
+		seen.add(value);
+		out.push({ value: `status ${value}`, label });
+	};
+	for (const node of nodes) {
+		const value = nodes.filter((candidate) => candidate.name === node.name).length > 1
+			? node.id
+			: node.name;
+		add(value, nodeLabel(node.id, node.name));
+	}
+	for (const job of deps.runtime.activeJobs()) {
+		if (job.state === "retired") continue;
+		add(job.name, `${job.name} (live)`);
+	}
+	return out;
+}
+
 function resolveNode(
 	nodes: readonly TreeNodeSnapshot[],
 	query: string,
@@ -525,15 +561,7 @@ export function registerLegionCommand(
 	};
 	const helpText = [
 		"Legion commands:",
-		"  /legion team [list|use <name> [--global]|create <name> a,b,c [--global]]",
-		"  /legion agents [user|project|both]",
-		"  /legion on | 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]",
-		"  /legion --tree | /legion <node>",
-		"  /legion help",
+		...LEGION_SLASH_HELP_LINES.map((line) => `  ${line}`),
 	].join("\n");
 	pi.registerCommand(LEGION_COMMAND, {
 		description: "Open the Legion view or manage teams, agents, subagent runs, and settings",
@@ -554,6 +582,9 @@ export function registerLegionCommand(
 				return stopCompletions(rest, deps.runtime.activeJobs(), deps.runtime.treeNodes())
 					.map((item) => ({ value: `stop ${item.value}`, label: item.label }));
 			}
+			if (/^status\s/i.test(trimmed)) {
+				return statusArgumentCompletions(trimmed.replace(/^status\s+/i, ""), deps);
+			}
 			if (/^doctor(\s|$)/i.test(prefix)) {
 				const rest = prefix.replace(/^doctor\s*/i, "");
 				return DOCTOR_SECTIONS
@@ -570,6 +601,12 @@ export function registerLegionCommand(
 					}
 				}
 			}
+			if ("status".startsWith(prefix)) {
+				verbs.push({
+					value: "status",
+					label: "status [name] — tree summary, or one node (same text as subagent status)",
+				});
+			}
 			if ("doctor".startsWith(prefix)) {
 				verbs.push({ value: "doctor", label: "doctor [section] — full self-check (extensions/models/spawn/memory/tools/storage/runtime)" });
 			}
@@ -601,6 +638,23 @@ export function registerLegionCommand(
 				sendSlashText(pi, helpText);
 				return;
 			}
+			if (normalizedKeyword === "status") {
+				const report = renderLegionStatus({
+					query: rest.join(" "),
+					nodes: deps.runtime.treeNodes(),
+					jobs: deps.runtime.activeJobs(),
+					lookupChild: deps.childStatus
+						? (name) => deps.childStatus!(name, ctx.cwd)
+						: undefined,
+					now: Date.now(),
+				});
+				if (!report.ok) {
+					notify(ctx, report.text, "error");
+					return;
+				}
+				sendSlashText(pi, report.text);
+				return;
+			}
 			if (/^doctor(?:\s|$)/i.test(query)) {
 				const sectionArg = query.replace(/^doctor\s*/i, "").trim();
 				const report = buildDoctorReport(deps, ctx.cwd, sectionArg || undefined);