pi-legion 2.0.2 → 2.0.4

package/CHANGELOG.md

@@ -11,6 +11,39 @@ summary so you can see **2.x vs 0.16** without leaving the tree.
 
 ## [Unreleased]
 
+## [2.0.4] — 2026-10-15
+
+### Added
+
+- `/legion timing [--json] [<name>]`: subagent wall / generation / other timing table
+  (reuses session summary parsers; live wall marked `+`; footer span vs sum_wall)
+  (#148 / #150).
+- `/legion` independent **timing** panel (4th pane): wide right-top / stacked bottom /
+  portrait between chart↔log; fields align CLI timing; Tab / ↑↓ / Enter / `o` →
+  context float (#151 / #152).
+- TUI context viewer is a floating modal (dim mask, title **主**/**子**); Esc / mask
+  closes without retire or stop (#147 / #149).
+
+### Fixed
+
+- `subagent({ action: "status" })` without `name` returns a live-children overview
+  (consistent with wait/stop `all` and slash `/legion status`) (#145 / #146).
+- Chart `tok/s · by role` x-domain freezes while idle: `to` advances only on
+  substantive `tokensOut` / `generationMs` samples (not wall-clock / flat-collapse)
+  (#153 / #154).
+
+## [2.0.3] — 2026-10-15
+
+### Fixed
+
+- `maxChildrenPerNode` only counts **live/running** children; `retire` (including
+  Already-retired no-op) frees the budget slot so a full tree can launch again
+  after retire. Session keep for resume does **not** occupy the concurrent slot
+  (#142 / #143).
+- Header tok/s uses `MIN_RATE_GENERATION_MS=1000` (same floor as tree rows): when
+  the in-window generation delta is under 1s, fall back to wall-clock so tiny
+  `dGen` cannot explode rates into the millions (#140 / #141).
+
 ## [2.0.2] — 2026-10-16
 
 ### Fixed
@@ -131,6 +164,10 @@ branch — pin `pi-legion@0.16.x` if you still need that model. See
 Earlier 0.11–0.15 history (including the `pi-herdr-swarm` /
 `@zzjcool/pi-herdr-subagents` renames) lives in git tags and older Releases.
 
-[Unreleased]: https://github.com/zzjcool/pi-legion/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/zzjcool/pi-legion/compare/v2.0.4...HEAD
+[2.0.4]: https://github.com/zzjcool/pi-legion/compare/v2.0.3...v2.0.4
+[2.0.3]: https://github.com/zzjcool/pi-legion/compare/v2.0.2...v2.0.3
+[2.0.2]: https://github.com/zzjcool/pi-legion/compare/v2.0.1...v2.0.2
+[2.0.1]: https://github.com/zzjcool/pi-legion/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/zzjcool/pi-legion/releases/tag/v2.0.0
 [0.16.x]: https://github.com/zzjcool/pi-legion/releases

package/docs/legion-v2-contract.md

@@ -359,7 +359,7 @@ interface LegionEventBus {
 | 项 | 默认 | 判定 |
 |---|---|---|
 | `maxDepth`（全树深度） | 4 | 硬顶 = `MAX_NESTED_PATH_ENTRIES`（血缘路径在 4 处饱和；settings/env 超 4 截断——告警在 M1-integration 的 launch 路径接入，M0 阶段截断静默可接受）。每进程生效上限 C：根 `C = min(env 运营者覆盖, settings.legion.maxDepth, 4)`；深度 d、上限 C 的父 launch 角色 R：先过闸门 `d+1 > C` → BUDGET_EXCEEDED；再经 `PI_SUBAGENT_MAX_DEPTH` 下发 `C子 = min(C, d + R, 4)`（R 缺省=不收紧；非法值按叶子 R=1 处理；语义 = 子树代数含自身，位置无关，只收紧不放宽）。不变量：C子 ≤ C父，且每进程 depth ≤ maxDepth |
-| `maxChildrenPerNode`（单节点扇出） | 8 | 父 supervisor 查自己子节点数 |
+| `maxChildrenPerNode`（单节点扇出） | 8 | 父 supervisor 查自己 **live** 子节点数（`starting`/`running`/`blocked`；`settled`/`failed`/`retired` 不占槽，session 可保留 resume） |
 | `maxActiveNodes`（全树并发 running+starting） | 30 | **全树真闸门**（替代只当 hint 的 maxConcurrentAgents）：launch 前一条 SQL，超限 BUDGET_EXCEEDED + `budget_refused` 事件 |
 
 ### 11.2 心跳与孤儿：postman 循环每次刷新直接子节点 `updated_at`。根 supervisor 每 60s 扫描：非终态 + `updated_at` 超 90s = `orphan_detected` 事件 + mail 通知 CEO。恢复 = resume 链（CEO 裁决，auto-resume 默认关）。孤儿判定可判定化：**非终态 ∧ 无活跃进程 ∧ 心跳超时**。

package/index.ts

@@ -188,12 +188,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 (status/wait/stop/…): addresses that 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 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.",
 		}),
 	),
 	all: Type.Optional(
 		Type.Boolean({
-			description: "wait: wait for active children; stop: stop every non-retired child",
+			description: "wait: wait for active children; stop: stop every non-retired child; status: overview of all live (non-retired) children under cwd",
 		}),
 	),
 	timeoutMs: Type.Optional(
@@ -1167,6 +1167,39 @@ async function controlAction(input: {
 		});
 	}
 
+	// status: no name (or all:true) → live-children overview; named → one child.
+	if (action === "status") {
+		if (params.name && params.all) {
+			return fail(
+				"`name` and `all` are mutually exclusive for status.",
+				ErrorCodes.INVALID_PARAMS,
+			);
+		}
+		if (!params.name) {
+			const live = listLiveChildrenForStatus(store.listRuns());
+			return ok(
+				renderStatusOverview(
+					live.map((child) => ({
+						child,
+						alive: input.supervisor.isAlive(child.name),
+					})),
+				),
+			);
+		}
+		const found = findChild(store.listRuns(), params.name);
+		if (!found) return unknownChild(params.name, store, cwd);
+		return ok(renderLiveChildStatus({
+			name: found.child.name,
+			state: found.child.state,
+			agent: found.child.agent,
+			kind: found.child.kind,
+			sessionFile: found.child.sessionFile,
+			execution: found.child.execution,
+			acceptance: found.child.acceptance,
+			alive: input.supervisor.isAlive(params.name),
+		}));
+	}
+
 	if (!params.name) {
 		return fail(
 			`\`name\` is required for the "${action}" action.`,
@@ -1200,18 +1233,6 @@ async function controlAction(input: {
 		orchestrator,
 	};
 
-	if (action === "status") {
-		return ok(renderLiveChildStatus({
-			name: found.child.name,
-			state: found.child.state,
-			agent: found.child.agent,
-			kind: found.child.kind,
-			sessionFile: found.child.sessionFile,
-			execution: found.child.execution,
-			acceptance: found.child.acceptance,
-			alive: input.supervisor.isAlive(params.name),
-		}));
-	}
 	if (action === "steer") return steerChild(ctx);
 	if (action === "collect") return collectChild(ctx, input.signal);
 	if (action === "retire") return retireChild(ctx);
@@ -1224,7 +1245,7 @@ async function controlAction(input: {
 interface ChildContext {
 	action: string;
 	params: SubagentParams;
-	/** Always set: `controlAction` rejects a request without a name. */
+	/** Always set: named control actions reject a request without a name. */
 	name: string;
 	supervisor: LegionSupervisor;
 	uiProxy: UIProxy;
@@ -2508,6 +2529,53 @@ async function abandonLaunchedChild(session: LaunchSession, name: string): Promi
 // wait (§1.5): block for results instead of relying on async notices
 // ---------------------------------------------------------------------------
 
+/**
+ * Live (non-retired / non-exited) children under this cwd for status overview.
+ *
+ * Names can be reused after retire; prefer the newest live record per name
+ * (same preference as {@link pickChildByName}).
+ */
+export function listLiveChildrenForStatus(
+	runs: ReturnType<RunStore["listRuns"]>,
+): NonNullable<ReturnType<RunStore["findChild"]>>[] {
+	const ranked = [...runs].sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+	const seen = new Set<string>();
+	const out: NonNullable<ReturnType<RunStore["findChild"]>>[] = [];
+	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);
+		}
+	}
+	return out;
+}
+
+/** Multi-child status text: one {@link renderLiveChildStatus} block per live child. */
+export function renderStatusOverview(
+	children: Array<{
+		child: NonNullable<ReturnType<RunStore["findChild"]>>;
+		alive: boolean;
+	}>,
+): string {
+	if (children.length === 0) return "No live children.";
+	const noun = children.length === 1 ? "child" : "children";
+	const blocks = children.map(({ child, alive }) =>
+		renderLiveChildStatus({
+			name: child.name,
+			state: child.state,
+			agent: child.agent,
+			kind: child.kind,
+			sessionFile: child.sessionFile,
+			execution: child.execution,
+			acceptance: child.acceptance,
+			alive,
+		}),
+	);
+	return [`Status · ${children.length} live ${noun}`, "", blocks.join("\n\n")].join("\n");
+}
+
 /**
  * Resolve which children a wait targets.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-legion",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "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",

package/src/extension/legion-commands.ts

@@ -26,6 +26,7 @@ import {
 	type ToggleCommandDeps,
 } from "./slash.ts";
 import { createSummaryCommand } from "./summary.ts";
+import { createTimingCommand } from "./timing.ts";
 import { getAgentDir } from "../agents/paths.ts";
 import type {
 	ExtensionAPI,
@@ -304,6 +305,8 @@ function liveNode(
 		status: node.status,
 		createdAt: node.createdAt,
 		updatedAt: node.updatedAt,
+		parentId: node.parentId,
+		depth: node.depth,
 		...(node.turn === undefined ? {} : { turn: node.turn }),
 		...(node.turns === undefined ? {} : { turns: node.turns }),
 		sessionFile: node.sessionFile,
@@ -432,7 +435,8 @@ function openLiveOverlay(
 	});
 	void ui.custom(factory, {
 		overlay: true,
-		overlayOptions: { width: "100%" },
+		// Full-screen host overlay so the viewer paints its own dim mask + floating frame.
+		overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", row: 0, col: 0 },
 		onHandle: (handle) => controller.getCurrent()?.attachOverlayHandle(handle),
 	}).catch((error: unknown) => reportOverlayOpenError(controller, ui, error));
 }
@@ -558,6 +562,7 @@ export function registerLegionCommand(
 				}
 			: {}),
 		summary: createSummaryCommand(pi),
+		timing: createTimingCommand(pi),
 	};
 	const helpText = [
 		"Legion commands:",
@@ -567,7 +572,7 @@ export function registerLegionCommand(
 		description: "Open the Legion view or manage teams, agents, subagent runs, and settings",
 		getArgumentCompletions(prefix) {
 			const trimmed = prefix.trimStart();
-			if (/^(team|agents|on|off|summary)\s/i.test(trimmed)) {
+			if (/^(team|agents|on|off|summary|timing)\s/i.test(trimmed)) {
 				const key = trimmed.split(/\s+/, 1)[0]?.toLowerCase() ?? "";
 				if (key === "on" || key === "off") return null;
 				const command = subcommands[key];
@@ -595,7 +600,7 @@ export function registerLegionCommand(
 			const nodes = deps.runtime.treeNodes();
 			const verbs: { value: string; label: string }[] = [];
 			if (!prefix.includes(" ")) {
-				for (const command of ["team", "agents", "on", "off", "summary", "help"]) {
+				for (const command of ["team", "agents", "on", "off", "summary", "timing", "help"]) {
 					if (command.startsWith(prefix)) {
 						verbs.push({ value: command, label: command });
 					}

package/src/extension/legion-doctor.ts

@@ -68,6 +68,7 @@ export const LEGION_SLASH_HELP_LINES = [
 	"/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 timing [--json] [<name>] — wall / generation / other timing for children",
 	"/legion doctor [section]",
 	"/legion stop [name|all]",
 	"/legion --tree | /legion <node>",

package/src/extension/playbook.ts

@@ -11,7 +11,7 @@ export const PARENT_PLAYBOOK = [
 	"   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. Esc / wait interrupt only ends the parent turn's wait — children keep running and settle still notifies; only an explicit `stop` or session exit retires them. A wait interrupted by Esc returns `interrupted (parent turn ended; children still running)`. 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.",
+	"4. Later control is only through `subagent({ action, name?, message? })`; `status` with no name (or `all: true`) overviews live children, with `name` for one child; 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.",
 	"7. Launch with `verify: [\"npm run typecheck\", \"npm test\"]` when the project has a mechanical verifier. The extension runs those commands itself in the child worktree at collect time; the child does not need to paste test output.",
@@ -23,7 +23,7 @@ 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. 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 interrupted; Esc does not retire children — use `stop` (or exit the session) to retire them.",
+	"Actions: launch (default), continue, steer, resume, status, collect, wait, list, retire, stop, diagnose. `status` with no name (or `all: true`) returns a live-children overview; with `name` returns that one child (unknown → NOT_FOUND). `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 interrupted; Esc does not retire children — use `stop` (or exit the session) to retire them.",
 ].join(" ");
 
 /** Split shell commands into sequential chunks while preserving old helper API. */

package/src/extension/timing.ts

@@ -0,0 +1,391 @@
+/**
+ * Subagent timing slash command (`/legion timing`).
+ *
+ * Reuses summary.ts duration resolution + session parse (via aggregateSubagentRuns
+ * / parseSessionFile). Zero schema change — wall from spawnedAt/retiredAt|now,
+ * generation from ParsedSession.generationMs, other = max(0, wall − gen).
+ */
+
+import * as path from "node:path";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { parseSessionFile } from "../shared/session.ts";
+import type { ChildRecord, RunRecord, TaskState } from "../shared/types.ts";
+import {
+	RunStore,
+	pickChildByName,
+} from "../runs/store.ts";
+import { sendSlashText, type LegionSubcommand } from "./slash.ts";
+import {
+	aggregateSubagentRuns,
+	formatDuration,
+	type SummaryChild,
+	type SummarySession,
+	type SubagentSummary,
+} from "./summary.ts";
+import { breakdown } from "../shared/timing-breakdown.ts";
+
+export { breakdown } from "../shared/timing-breakdown.ts";
+
+const TIMING_USAGE = "Usage: /legion timing [--json] [<name>]";
+
+export interface TimingChild {
+	name: string;
+	role: string;
+	state: TaskState;
+	/** Still in a running lifecycle state (working/blocked/awaiting). */
+	live: boolean;
+	wall_ms: number;
+	/** Session-derived model generation wall; null when no turn data. */
+	generation_ms: number | null;
+	/** max(0, wall − gen); null when generation_ms unavailable. Coarse bucket. */
+	other_ms: number | null;
+	turns: number | null;
+	startedAtMs: number | null;
+	endedAtMs: number | null;
+	/** True when wall_ms tracks the live clock (retiredAt absent + running). */
+	liveWall: boolean;
+}
+
+export interface TimingReport {
+	children: TimingChild[];
+	/** Earliest spawn → latest end across children with known endpoints. */
+	span_ms: number | null;
+	sum_wall_ms: number;
+	cwd?: string;
+}
+
+export interface TimingFormatOptions {
+	cwd?: string;
+	json?: boolean;
+}
+
+function sessionHasTurns(
+	session: SummarySession | undefined,
+): session is SummarySession {
+	return Boolean(session && session.turns.length > 0);
+}
+
+/** Map one SummaryChild (already duration-resolved) into a timing row. */
+export function timingChildFromSummary(child: SummaryChild): TimingChild {
+	const generation_ms = sessionHasTurns(child.session)
+		? child.session.generationMs
+		: null;
+	const parts = breakdown(child.durationMs, generation_ms);
+	return {
+		name: child.child.name,
+		role: child.role,
+		state: child.child.state,
+		live: child.running,
+		wall_ms: parts.wall_ms,
+		generation_ms: parts.generation_ms,
+		other_ms: parts.other_ms,
+		turns: child.turns,
+		startedAtMs: child.startedAtMs,
+		endedAtMs: child.endedAtMs,
+		liveWall: child.liveDuration,
+	};
+}
+
+/**
+ * Build a timing report from the same aggregation path as `/legion summary`.
+ * Children are sorted by startedAt (unknowns last), then name.
+ */
+export function buildTimingReport(
+	summary: SubagentSummary,
+	options: { cwd?: string } = {},
+): TimingReport {
+	const children: TimingChild[] = [];
+	for (const group of summary.groups) {
+		for (const child of group.children) {
+			children.push(timingChildFromSummary(child));
+		}
+	}
+	children.sort((a, b) => {
+		if (a.startedAtMs === null && b.startedAtMs === null) {
+			return a.name.localeCompare(b.name);
+		}
+		if (a.startedAtMs === null) return 1;
+		if (b.startedAtMs === null) return -1;
+		return a.startedAtMs - b.startedAtMs || a.name.localeCompare(b.name);
+	});
+
+	const started = children
+		.map((c) => c.startedAtMs)
+		.filter((v): v is number => v !== null);
+	const ended = children
+		.map((c) => c.endedAtMs)
+		.filter((v): v is number => v !== null);
+	const span_ms =
+		started.length > 0 && ended.length > 0
+			? Math.max(0, Math.max(...ended) - Math.min(...started))
+			: null;
+	const sum_wall_ms = children.reduce((sum, c) => sum + c.wall_ms, 0);
+
+	return {
+		children,
+		span_ms,
+		sum_wall_ms,
+		...(options.cwd
+			? { cwd: options.cwd }
+			: summary.cwd
+				? { cwd: summary.cwd }
+				: {}),
+	};
+}
+
+function formatMsCell(
+	ms: number | null,
+	opts: { live?: boolean } = {},
+): string {
+	if (ms === null) return "—";
+	const rendered = formatDuration(ms);
+	return opts.live ? `${rendered}+` : rendered;
+}
+
+function formatOptionalMs(ms: number | null): string {
+	return ms === null ? "—" : formatDuration(ms);
+}
+
+function formatTurns(turns: number | null): string {
+	return turns === null ? "—" : String(turns);
+}
+
+/** Human table for all children + optional concurrency footer. */
+export function formatTimingTable(
+	report: TimingReport,
+	options: TimingFormatOptions = {},
+): string {
+	if (report.children.length === 0) {
+		const cwd = options.cwd ?? report.cwd ?? process.cwd();
+		return `No subagent runs under ${cwd}.\nLaunch children with the subagent tool to see timing here.`;
+	}
+
+	const lines = [
+		`Subagent timing — ${report.children.length} children`,
+		"",
+		"| name | state | wall | gen | other | turns |",
+		"|---|---|---|---|---|---|",
+	];
+	for (const child of report.children) {
+		const wall =
+			child.startedAtMs === null
+				? "—"
+				: formatMsCell(child.wall_ms, { live: child.liveWall });
+		lines.push(
+			`| ${child.name} | ${child.state} | ${wall} | ${formatOptionalMs(child.generation_ms)} | ${formatOptionalMs(child.other_ms)} | ${formatTurns(child.turns)} |`,
+		);
+	}
+
+	if (report.span_ms !== null && report.children.length > 0) {
+		const ratio =
+			report.span_ms > 0
+				? (report.sum_wall_ms / report.span_ms).toFixed(2)
+				: "—";
+		lines.push(
+			"",
+			`span ${formatDuration(report.span_ms)} · sum wall ${formatDuration(report.sum_wall_ms)} · concurrency ~${ratio}×`,
+		);
+	}
+	return lines.join("\n");
+}
+
+/** Single-child detail (same口径 as summary detail, timing-focused). */
+export function formatTimingDetail(child: TimingChild, run: RunRecord): string {
+	const title = `${child.name} — ${child.role}`;
+	const lines = [
+		title,
+		`  state: ${child.state}${child.live ? " (live)" : ""}`,
+		`  run: ${run.runId}`,
+	];
+	const wall =
+		child.startedAtMs === null
+			? "—"
+			: formatMsCell(child.wall_ms, { live: child.liveWall });
+	lines.push(`  wall: ${wall}`);
+	lines.push(`  generation: ${formatOptionalMs(child.generation_ms)}`);
+	lines.push(
+		`  other: ${formatOptionalMs(child.other_ms)} (wall − gen; not precise wait/tool)`,
+	);
+	lines.push(`  turns: ${formatTurns(child.turns)}`);
+	return lines.join("\n");
+}
+
+function childToJson(child: TimingChild): Record<string, unknown> {
+	return {
+		name: child.name,
+		role: child.role,
+		state: child.state,
+		live: child.live,
+		wall_ms: child.wall_ms,
+		generation_ms: child.generation_ms,
+		other_ms: child.other_ms,
+		turns: child.turns,
+	};
+}
+
+export function formatTimingJson(
+	report: TimingReport,
+	detail?: { child: TimingChild; run: RunRecord },
+): string {
+	if (detail) {
+		return JSON.stringify(
+			{
+				...childToJson(detail.child),
+				runId: detail.run.runId,
+			},
+			null,
+			2,
+		);
+	}
+	return JSON.stringify(
+		{
+			children: report.children.map(childToJson),
+			span_ms: report.span_ms,
+			sum_wall_ms: report.sum_wall_ms,
+			...(report.span_ms !== null && report.span_ms > 0
+				? {
+						concurrency_ratio: Number(
+							(report.sum_wall_ms / report.span_ms).toFixed(4),
+						),
+					}
+				: {}),
+		},
+		null,
+		2,
+	);
+}
+
+function parseTimingArgs(
+	args: string,
+):
+	| { ok: true; json: boolean; name?: string }
+	| { ok: false; message: string } {
+	const tokens = args.trim().split(/\s+/).filter(Boolean);
+	let json = false;
+	let name: string | undefined;
+	for (const token of tokens) {
+		if (token === "--json") {
+			if (json) return { ok: false, message: TIMING_USAGE };
+			json = true;
+			continue;
+		}
+		if (token.startsWith("-")) return { ok: false, message: TIMING_USAGE };
+		if (name !== undefined) return { ok: false, message: TIMING_USAGE };
+		name = token;
+	}
+	return { ok: true, json, ...(name ? { name } : {}) };
+}
+
+function sessionMapFor(runs: readonly RunRecord[]): Map<string, SummarySession> {
+	const sessions = new Map<string, SummarySession>();
+	for (const run of runs) {
+		for (const child of run.children) {
+			if (child.sessionFile) {
+				sessions.set(child.sessionFile, parseSessionFile(child.sessionFile));
+			}
+		}
+	}
+	return sessions;
+}
+
+function timingCompletions(
+	prefix: string,
+	cwd: string,
+): Array<{ value: string; label: string }> | null {
+	const trimmed = prefix.trimStart();
+	if (trimmed.startsWith("--") && !trimmed.includes(" ")) {
+		return "--json".startsWith(trimmed)
+			? [{ value: "--json", label: "--json" }]
+			: [];
+	}
+	const json = /^--json\s+/.test(trimmed);
+	const namePrefix = json ? trimmed.replace(/^--json\s+/, "") : prefix.trim();
+	if (namePrefix.includes(" ")) return null;
+	const store = new RunStore({ rootDir: path.join(cwd, ".pi-subagents") });
+	const names = new Set<string>();
+	for (const run of store.listRuns()) {
+		for (const child of run.children) names.add(child.name);
+	}
+	return [...names]
+		.filter((name) => name.startsWith(namePrefix))
+		.sort((a, b) => a.localeCompare(b))
+		.map((name) => ({
+			value: json ? `--json ${name}` : name,
+			label: name,
+		}));
+}
+
+function notifyUnknownChild(
+	ctx: ExtensionCommandContext,
+	name: string,
+): void {
+	ctx.ui.notify(
+		`unknown child: ${name} (no run under ${ctx.cwd}/.pi-subagents). Child records are scoped to the cwd they were launched from — pass the same cwd used for launch.`,
+		"error",
+	);
+}
+
+function findTimingChild(
+	report: TimingReport,
+	summary: SubagentSummary,
+	name: string,
+): { timing: TimingChild; run: RunRecord; child: ChildRecord } | null {
+	const picked = pickChildByName(summary.runs, name);
+	if (!picked) return null;
+	const timing = report.children.find((c) => c.name === picked.child.name);
+	if (!timing) return null;
+	return { timing, run: picked.run, child: picked.child };
+}
+
+/** Build the `/legion timing [--json] [<name>]` handler. */
+export function createTimingCommand(pi: ExtensionAPI): LegionSubcommand {
+	let completionCwd = process.cwd();
+	return {
+		description: "Show wall / generation / other timing for subagent children",
+		getArgumentCompletions: (prefix) => timingCompletions(prefix, completionCwd),
+		handler: async (args, ctx) => {
+			completionCwd = ctx.cwd;
+			const parsed = parseTimingArgs(args);
+			if (parsed.ok === false) {
+				ctx.ui.notify(parsed.message, "error");
+				return;
+			}
+			const store = new RunStore({
+				rootDir: path.join(ctx.cwd, ".pi-subagents"),
+			});
+			const runs = store.listRuns();
+			const sessions = sessionMapFor(runs);
+			const now = Date.now();
+			const summary = aggregateSubagentRuns(runs, { now, sessions });
+			const report = buildTimingReport(summary, { cwd: ctx.cwd });
+
+			if (parsed.name) {
+				const found = findTimingChild(report, summary, parsed.name);
+				if (!found) {
+					notifyUnknownChild(ctx, parsed.name);
+					return;
+				}
+				sendSlashText(
+					pi,
+					parsed.json
+						? formatTimingJson(report, {
+								child: found.timing,
+								run: found.run,
+							})
+						: formatTimingDetail(found.timing, found.run),
+				);
+				return;
+			}
+
+			sendSlashText(
+				pi,
+				parsed.json
+					? formatTimingJson(report)
+					: formatTimingTable(report, { cwd: ctx.cwd }),
+			);
+		},
+	};
+}