pi-legion 4.0.0 → 5.0.0

package/src/extension/legion-tools.ts

@@ -38,6 +38,7 @@ import {
 	isTerminalPhase,
 	type LegionPhase,
 } from "../legion/state-machine.ts";
+import { isTerminalIn, type PhaseMachine } from "../legion/phase-machine.ts";
 import { upsertUsage } from "../legion/usage.ts";
 
 const POSTMAN_INTERVAL_MS = 2_000;
@@ -66,6 +67,8 @@ export interface LegionPostmanOptions {
 	resumeChild?: (node: LegionNode, mail: LegionMailCommand) => Promise<void>;
 	now?: () => number;
 	intervalMs?: number;
+	/** #298: the team root's declared phase machine (absent = built-in). */
+	machine?: PhaseMachine;
 }
 
 /** Poll and deliver mail only for children hosted by this process. */
@@ -78,6 +81,7 @@ export class LegionPostman {
 	private readonly sendRootMessage: (text: string) => void;
 	private readonly sendSelfMessage: (text: string) => void;
 	private readonly resumeChild?: LegionPostmanOptions["resumeChild"];
+	private readonly machine?: PhaseMachine;
 	private readonly now: () => number;
 	private readonly intervalMs: number;
 	private timer: ReturnType<typeof setInterval> | undefined;
@@ -94,6 +98,7 @@ export class LegionPostman {
 		this.sendRootMessage = options.sendRootMessage ?? (() => {});
 		this.sendSelfMessage = options.sendSelfMessage ?? (() => {});
 		this.resumeChild = options.resumeChild;
+		this.machine = options.machine;
 		this.now = options.now ?? Date.now;
 		this.intervalMs = options.intervalMs ?? POSTMAN_INTERVAL_MS;
 	}
@@ -295,9 +300,23 @@ export class LegionPostman {
 		return false;
 	}
 
+	/**
+	 * Terminal check that respects the team's own machine (#298).
+	 *
+	 * The old code asked `isTerminalPhase`, which only knew the three built-in
+	 * terminal names. Under a declared machine a phase is terminal because the
+	 * DECLARATION says so (`terminal: true` or no exits), so a custom name would
+	 * otherwise be treated as non-terminal and the auto-finish paths would act on
+	 * a team that had already finished.
+	 */
+	private isTerminalPhaseOf(phase: string): boolean {
+		if (this.machine) return isTerminalIn(this.machine, phase);
+		return isTerminalPhase(phase);
+	}
+
 	private failTeamIfAllChildrenFailed(timestamp: number): void {
 		const node = getNode(this.db, this.nodeId);
-		if (!node?.phase || !isPhase(node.phase) || isTerminalPhase(node.phase)) return;
+		if (!node?.phase || this.isTerminalPhaseOf(node.phase)) return;
 		const children = getChildren(this.db, node.id);
 		if (!children.length || children.some((child) => child.status !== "failed")) return;
 		const decision = evaluatePhaseTransition({
@@ -340,7 +359,7 @@ export class LegionPostman {
 
 	private checkOwnPhaseTimeout(timestamp: number): void {
 		const node = getNode(this.db, this.nodeId);
-		if (!node?.phase || !isPhase(node.phase) || isTerminalPhase(node.phase)) return;
+		if (!node?.phase || this.isTerminalPhaseOf(node.phase)) return;
 		const timeout = checkPhaseTimeout({
 			phase: node.phase,
 			phaseSince: node.phaseSince,
@@ -377,6 +396,8 @@ export interface RegisterLegionToolsOptions {
 	db: DatabaseSync;
 	nodeId: string;
 	role?: string;
+	/** #298: the team root's declared phase machine (absent = built-in). */
+	machine?: PhaseMachine;
 	settings?: LegionSettings;
 	eventBus?: Pick<LegionEventBus, "emit">;
 	cwd?: string;
@@ -468,7 +489,15 @@ export function registerLegionTools(pi: ExtensionAPI, options: RegisterLegionToo
 			label: "Legion phase",
 			description: "Request a validated centurion phase transition.",
 			parameters: Type.Object({
-				to: Type.Union(PHASES.map((value) => Type.Literal(value))),
+				// #298: the phase list is declared per team, so it cannot be a
+				// compile-time enum here. `requestLegionPhase` validates the value
+				// against the team's own machine and refuses anything unknown with
+				// the list of phases that DO exist.
+				to: Type.String({
+					description:
+						'Target phase. Default machine: planning, implementing, reviewing, verifying. ' +
+						'`done`/`failed`/`aborted` are controlled by the parent or supervisor.',
+				}),
 				note: Type.Optional(Type.String()),
 				evidence: Type.Optional(Type.String()),
 			}),
@@ -483,6 +512,7 @@ export function registerLegionTools(pi: ExtensionAPI, options: RegisterLegionToo
 					now: options.now,
 					runCommand: options.runCommand,
 					sendSelfMessage: options.sendSelfMessage,
+					...(options.machine ? { machine: options.machine } : {}),
 				});
 				return result.ok ? toolOk(result.message) : toolError(result.message, result.code ?? "INVALID_PARAMS");
 			},
@@ -523,6 +553,8 @@ export function formatTree(nodes: readonly LegionNode[]): string {
 export interface PhaseRequestOptions {
 	note?: string;
 	evidence?: string;
+	/** #298: the team's declared phase machine, when its card has one. */
+	machine?: PhaseMachine;
 	cwd: string;
 	runDir?: string;
 	settings?: LegionSettings;
@@ -533,18 +565,22 @@ export interface PhaseRequestOptions {
 }
 
 export type PhaseRequestResult =
-	| { ok: true; phase: LegionPhase; message: string }
+	| { ok: true; phase: string; message: string }
 	| { ok: false; message: string; code?: string };
 
 export async function requestLegionPhase(
 	db: DatabaseSync,
 	nodeId: string,
-	to: LegionPhase,
+	to: string,
 	options: PhaseRequestOptions,
 ): Promise<PhaseRequestResult> {
 	const now = options.now ?? Date.now;
 	const self = getNode(db, nodeId);
 	if (!self || self.role !== "centurion") return { ok: false, code: "INVALID_PARAMS", message: "legion_phase is centurion-only" };
+	// #298: the team's own machine decides which phases exist. `options.machine`
+	// carries the declaration from the node's role card; absent means the built-in
+	// four-phase pipeline.
+	const machine = options.machine;
 	if (to === "done" || to === "failed" || to === "aborted") {
 		return { ok: false, code: "INVALID_PARAMS", message: `${to} is controlled by the parent or supervisor` };
 	}
@@ -552,30 +588,39 @@ export async function requestLegionPhase(
 	const children = getChildren(db, nodeId);
 	const proposedContractPath = path.resolve(self.worktreePath ?? options.cwd, ".pi-legion", "contract.md");
 	let contractText: string | undefined;
-	if (self.phase === "planning" && to === "implementing") {
-		try { contractText = fs.readFileSync(proposedContractPath, "utf8"); } catch { contractText = undefined; }
-	}
-	const latestReviewer = children
-		.filter((child) => child.role === "reviewer" && child.status === "settled" && child.sessionFile)
-		.sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id))
-		.at(-1);
-	const reviewerVerdict = latestReviewer?.sessionFile
-		? extractVerdict(parseSessionFile(latestReviewer.sessionFile).lastTurnOutput ?? "")
+	try { contractText = fs.readFileSync(proposedContractPath, "utf8"); } catch { contractText = undefined; }
+	// #298: NO role names here any more. The old code scanned for a settled
+	// `role === "reviewer"` and for failed `role === "worker"` children, which made
+	// those roles load-bearing: a custom machine could declare any phases it liked
+	// and still be judged by the fixed pipeline's cast list.
+	//
+	// Now the question is asked structurally — "the newest settled child that
+	// reported a verdict" and "failures recorded before this phase began" — so any
+	// role can play any part.
+	const settledWithSession = children
+		.filter((child) => child.status === "settled" && child.sessionFile)
+		.sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id));
+	const latestVerdictChild = settledWithSession.at(-1);
+	const lastVerdict = latestVerdictChild?.sessionFile
+		? extractVerdict(parseSessionFile(latestVerdictChild.sessionFile).lastTurnOutput ?? "")
 		: null;
-	const reviewerVerdictOk = reviewerVerdict?.ok;
-	const failedWorkerHandledIds = self.phase === "implementing" && self.reworkCount > 0 && self.phaseSince !== null
-		? children.filter((child) => child.role === "worker" && child.status === "failed" && child.updatedAt < self.phaseSince!).map((child) => child.id)
+	const verdictOk = lastVerdict?.ok;
+	const failedHandledIds = self.phase !== null && self.reworkCount > 0 && self.phaseSince !== null
+		? children.filter((child) => child.status === "failed" && child.updatedAt < self.phaseSince!).map((child) => child.id)
 		: [];
+	const contractPresent = Boolean(contractText?.trim());
 	const decision = evaluatePhaseTransition({
-		from: isPhase(self.phase) ? self.phase : null,
+		from: self.phase ?? null,
 		to,
 		reworkCount: self.reworkCount,
-		contractPath: contractText?.trim() ? proposedContractPath : self.contractPath,
+		contractPath: contractPresent ? proposedContractPath : self.contractPath,
+		contractPresent,
 		children: children.map(({ id, role, status }) => ({ id, role, status })),
-		failedWorkerHandledIds,
-		reviewerVerdictOk,
+		failedWorkerHandledIds: failedHandledIds,
+		reviewerVerdictOk: verdictOk,
 		verificationPassed: readVerificationResult(self),
 		actorRole: self.role,
+		...(machine ? { machine } : {}),
 	}, now);
 
 	if (!decision.allowed) {

package/src/extension/notify.ts

@@ -18,12 +18,57 @@
  * still starts a new turn immediately.
  */
 
+import {
+	PROGRESS_MIN_FILES_CHANGED,
+	PROGRESS_MIN_TOOL_RESULTS,
+} from "../runs/progress-signal.ts";
 import { isTransientConnectionFailure } from "../shared/session.ts";
 
 export const SUBAGENT_NOTIFY_TYPE = "subagent-notify";
 
 export type CompletionStatus = "completed" | "failed" | "stopped" | "running";
 
+/**
+ * D2/D2-a progress measurement, as carried by a renewal proposal.
+ *
+ * Exactly W1's `ProgressMeasure` minus `progressed` (D2-a): the renderer
+ * re-derives the verdict from `PROGRESS_MIN_TOOL_RESULTS` /
+ * `PROGRESS_MIN_FILES_CHANGED`, so a notice can never claim progress the
+ * measurer would not, and the thresholds have one home. No extra fields, so
+ * a caller can pass a `ProgressMeasure` straight through.
+ */
+export interface RenewalProgress {
+	/** New `toolResult` rows since the renewal baseline (a tool returned). */
+	readonly toolResults: number;
+	/** New assistant messages since the baseline (shown, never decides — D2-a). */
+	readonly assistantMessages: number;
+	/** Files created/modified in the worktree; absent when not measurable. */
+	readonly filesChanged?: number;
+}
+
+/**
+ * D3: structured renewal proposal (subagent-renewal contract v1, W3).
+ *
+ * **Terminal paths only (D7).** A renewal proposal requires that the child is
+ * actually dead and its session file survived — so ONLY the path that observes
+ * a terminated child may populate it. `wait { timeoutMs }` and
+ * `collect { timeoutMs }` timeouts mean the parent gave up waiting while the
+ * child is still alive (`inprocess-supervisor` just resolves
+ * `{settled:false, reason:"timeout"}`): those call sites must leave `renewal`
+ * undefined, and then this field's absence keeps every renewal line out of the
+ * notice. Renewing a live child would spend a fresh turn budget on a child
+ * that never lost one. Locked by test "A3/D7".
+ */
+export interface RenewalProposal {
+	/** D2 measurement at the moment of termination. */
+	readonly progress: RenewalProgress;
+	/** D6: how many renewals already used. */
+	readonly used: number;
+	readonly max: number;
+	/** The exact command that renews this child (D4: always `continue`). */
+	readonly command: string;
+}
+
 export interface CompletionInput {
 	name: string;
 	agent?: string;
@@ -34,6 +79,13 @@ export interface CompletionInput {
 	sessionFile?: string;
 	acceptance?: { status: string; level?: string };
 	recycled?: boolean;
+	/**
+	 * D3: structured renewal proposal, present only when the renewal contract
+	 * fires. Only a **real termination** populates it — `wait`/`collect`
+	 * timeouts describe a still-alive child and must pass nothing here (D7);
+	 * see `RenewalProposal` for the full premise.
+	 */
+	renewal?: RenewalProposal | undefined;
 }
 
 export interface CompletionNotice {
@@ -160,6 +212,83 @@ export function previewOutput(
 	return `${trimmed.slice(0, max)}\n…(preview truncated${where})`;
 }
 
+/**
+ * D2-a verdict for a rendered proposal, recomputed from W1's exported
+ * thresholds so the notice and the measurer cannot disagree: 3 new tool
+ * results, or 1 changed file. Assistant messages are displayed but never
+ * decide — a model repeating itself grows that count forever, and that is
+ * exactly the case where a renewal must not be offered.
+ */
+function countsAsProgress(progress: RenewalProgress): boolean {
+	if (progress.toolResults >= PROGRESS_MIN_TOOL_RESULTS) return true;
+	return (
+		progress.filesChanged !== undefined &&
+		progress.filesChanged >= PROGRESS_MIN_FILES_CHANGED
+	);
+}
+
+/**
+ * D3: the trailing renewal block, as notice lines.
+ *
+ * Three shapes (the measurement line always leads — D3 asks for the judgement
+ * basis *and* the command, and "this child produced 47 tool results before it
+ * died" is the whole argument):
+ *
+ *   progressed: 47 tool results, 12 assistant messages, 6 files changed
+ *   renew: subagent({ action: "continue", name: "W2", message: "<what to continue>" })
+ *   renewals: 1/2
+ *
+ *   … no measurable progress since spawn — not offering a renewal      (A2)
+ *   … renewals exhausted (2/2) — split the task instead of renewing    (D6/A5)
+ *
+ * `used/max` is "renewals consumed so far", matching the exhausted line.
+ * An unmeasurable `filesChanged` drops out instead of printing `undefined`.
+ */
+export function formatRenewalBlock(renewal: RenewalProposal): string[] {
+	const bits = [
+		`${renewal.progress.toolResults} tool results`,
+		`${renewal.progress.assistantMessages} assistant messages`,
+	];
+	if (renewal.progress.filesChanged !== undefined) {
+		bits.push(`${renewal.progress.filesChanged} files changed`);
+	}
+	const lines = [`progressed: ${bits.join(", ")}`];
+	// A2/D2: renewing a child that moved no output forward just extends the
+	// hang by one full turn budget — the exact reason the role timeout exists.
+	if (!countsAsProgress(renewal.progress)) {
+		lines.push("no measurable progress since spawn — not offering a renewal");
+		return lines;
+	}
+	// D6/A5: the budget is a hard ceiling; past it the split is wrong, not the
+	// budget. Say so instead of offering a fourth attempt.
+	if (renewal.used >= renewal.max) {
+		lines.push(
+			`renewals exhausted (${renewal.used}/${renewal.max}) — split the task instead of renewing`,
+		);
+		return lines;
+	}
+	// D4/A8: renewal *is* `continue`; the caller hands us the finished command
+	// so the parent needs one line of typing, not a re-derivation.
+	lines.push(`renew: ${sanitizeNoticeField(renewal.command)}`);
+	lines.push(`renewals: ${renewal.used}/${renewal.max}`);
+	return lines;
+}
+
+/**
+ * The renewal block for a notice, or `undefined` when there is nothing to say.
+ *
+ * A completed child is never a renewal candidate (D1 condition 1): if the turn
+ * produced a verdict it is not a budget casualty, and offering `continue`
+ * would relaunch finished work.
+ */
+function renewalLinesFor(
+	status: CompletionStatus,
+	renewal: RenewalProposal | undefined,
+): string[] | undefined {
+	if (!renewal || status === "completed") return undefined;
+	return formatRenewalBlock(renewal);
+}
+
 export function formatCompletionNotice(input: CompletionInput): CompletionNotice {
 	const status = completionStatusOf(
 		input.execution.status,
@@ -185,7 +314,7 @@ export function formatCompletionNotice(input: CompletionInput): CompletionNotice
 	if (input.outputFile) previewHints.sessionFile = input.outputFile;
 	else if (input.sessionFile) previewHints.sessionFile = input.sessionFile;
 	const preview = previewOutput(input.output, PREVIEW_CHARS, previewHints);
-	const content = [
+	const lines: Array<string | undefined> = [
 		`Background task ${status}: **${label}**`,
 		"",
 		`execution: ${input.execution.status}${reason}`,
@@ -198,9 +327,12 @@ export function formatCompletionNotice(input: CompletionInput): CompletionNotice
 		input.recycled === false
 			? undefined
 			: "Child retired. Resume from the session file if you need this child again.",
-	]
-		.filter((line) => line !== undefined)
-		.join("\n");
+	];
+	// D3: the renewal proposal trails the failure body — appended, never woven
+	// in, so an unrenewable notice is byte-identical to what it was before.
+	const renewalLines = renewalLinesFor(status, input.renewal);
+	if (renewalLines) lines.push("", ...renewalLines);
+	const content = lines.filter((line) => line !== undefined).join("\n");
 	return {
 		content,
 		display: true,

package/src/extension/playbook.ts

@@ -9,11 +9,11 @@ export const PARENT_PLAYBOOK = [
 	"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: "...", 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. Children are in-process by default; a separate `pi` process is used only when the launch needs a worktree (centurion) or the role pins `spawnMode: rpc`. No pane or tab is created.",
+	"2. Prefer tasks[] for independent parallel work. Children are in-process by default; a separate `pi` process is used only when the launch needs a worktree — and since only a centurion may hold one, that is the only launch that goes over rpc. 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` with `name` or `all: true` 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? })`; `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 (`force: true` for hard retire when soft stop is insufficient). A `wait` timeout does not stop children — the result lists decisions (`extend` / `steer_again` / `stop` / `force_stop`) for the parent to choose. 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 run without host extensions unless the role inherits them, so a provider package the child needs must be passed explicitly. Do not tell a child to message or prompt the parent directly.",
 	"5. A collect timeout with a live child is a progress signal, not a verdict. Check status or session JSONL before deciding to steer or resume.",
-	"6. Isolation belongs to centurion. For N parallel isolated writers, dispatch N centurions (each owns one worktree); members stay `worktree: false` in-process. Passing `worktree: true` on a non-centurion warns once and is forced false.",
+	"6. Isolation belongs to centurion: each centurion owns one worktree, and members stay `worktree: false` in-process. Passing `worktree: true` on a non-centurion warns once and is forced false.",
 	"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.",
 	"Utility agents (`utility: true`, e.g. scout) can be dispatched by ANY role via the separate `vexillatio` tool — read-only helpers, always leaf, no depth budget. Its request shape matches `subagent`: either `vexillatio({ task, agent? })` or `vexillatio({ tasks: [{ agent, task }, …] })` (no top-level `task` needed; passing both only labels the parent run). The `subagent` tool stays for the command chain (worker/centurion).",
 	"Forbidden: direct bash access to legion.db, or launching child Pi processes by hand (use the subagent tool).",

package/src/extension/runtime.ts

@@ -36,6 +36,7 @@ import { progressFromSessionFile } from "../shared/progress.ts";
 import { readProcRss } from "../supervisor/proc-memory.ts";
 import { isTransientConnectionFailure } from "../shared/session.ts";
 import { isTerminalState, liveness } from "./liveness.ts";
+import type { RenewalProposal } from "./notify.ts";
 import {
 	DEFAULTS,
 	type AgentKind,
@@ -54,6 +55,7 @@ import { getSubtree } from "../legion/nodes.ts";
 import { attachUsageTotals } from "../legion/usage.ts";
 import { maxEventId } from "../legion/events.ts";
 import type { TreeNodeSnapshot } from "../tui/tree-view.ts";
+import type { PhaseMachine } from "../legion/phase-machine.ts";
 
 export interface CollectSnapshot {
 	execution: { status: string; reason?: string };
@@ -149,6 +151,25 @@ export interface SessionRuntimeDeps {
 	getTreeNodes?: () => readonly TreeNodeSnapshot[] | undefined;
 	/** Optional name-to-tree mapping for live RPC jobs backed by M2 ChildRecord.nodeId. */
 	getTreeIdentity?: (name: string) => LegionTreeIdentity | undefined;
+	/**
+	 * #298: the phase machine for a role, so the tree can show a team's own
+	 * workflow. Injected rather than imported because only the host knows the
+	 * resolved agent catalog (card `phases:` plus any team override).
+	 */
+	getPhaseMachine?: (role: string | null | undefined) => PhaseMachine | undefined;
+	/**
+	 * Renewal proposal for a finishing child (subagent-renewal-v1 D3).
+	 *
+	 * Injected rather than imported: the only builder lives in `index.ts`, which
+	 * already imports this module — a direct import would be a cycle. Returning
+	 * `undefined` is the correct answer for every path that must NOT offer a
+	 * renewal (D5 role opt-out, D1 completed, D7 still running, no baseline), so a
+	 * host that never supplies this hook simply gets today's notice verbatim.
+	 */
+	getRenewalProposal?: (
+		name: string,
+		execution: { status: string; reason?: string },
+	) => RenewalProposal | undefined;
 	/** Open the live activity viewer for a node selected in the resident status widget. */
 	onStatusNodeClick?: (nodeId: string) => void;
 	/** Above-input strip style; the extension uses "railway", the default stays "tree". */
@@ -809,7 +830,7 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			for (const nodeId of eventOverrides.keys()) if (!tree.has(nodeId)) eventOverrides.delete(nodeId);
 		}
 		const nodes = [...tree.values()].map((node) => ({ ...node }));
-		return mergeSpawnModes(nodes);
+		return mergePhaseMachines(mergeSpawnModes(nodes));
 	};
 
 	/**
@@ -834,6 +855,32 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 		return nodes;
 	};
 
+	/**
+	 * #298: attach the declaring team's machine to the node that owns it.
+	 *
+	 * Only a team root declares `phases:`, so children inherit it downward: showing
+	 * an empty machine on a worker would suggest it has none, when in fact it is
+	 * governed by its lead's. The nearest ancestor that resolves a machine wins.
+	 */
+	const mergePhaseMachines = (nodes: TreeNodeSnapshot[]): TreeNodeSnapshot[] => {
+		const byId = new Map(nodes.map((node) => [node.id, node]));
+		for (const node of nodes) {
+			let cursor: TreeNodeSnapshot | undefined = node;
+			let hops = 0;
+			while (cursor && hops < 64) {
+				const machine = deps.getPhaseMachine?.(cursor.role);
+				if (machine) {
+					node.phaseMachine = machine;
+					break;
+				}
+				const parentId: string | null = cursor.parentId ?? null;
+				cursor = parentId ? byId.get(parentId) : undefined;
+				hops += 1;
+			}
+		}
+		return nodes;
+	};
+
 	const storedNodeForJob = (
 		job: TrackedJob,
 		nodes: readonly TreeNodeSnapshot[],
@@ -1466,6 +1513,14 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 								recycled: shouldRecycleAfterCollect(
 									snapshot.execution.status,
 								),
+								// D3: only the terminating path attaches a proposal. The
+								// hook itself returns undefined for every case that must not
+								// offer one (completed / still-running / opted out / no
+								// baseline), so "absent" is meaningful, not a missing wire.
+								...(() => {
+									const renewal = deps.getRenewalProposal?.(job.name, snapshot.execution);
+									return renewal === undefined ? {} : { renewal };
+								})(),
 							},
 							triggerTurn,
 						});

package/src/extension/summary.ts

@@ -17,6 +17,7 @@ import {
 	RunStore,
 	pickChildByName,
 } from "../runs/store.ts";
+import { resolveChildAcrossStores, unknownChildMessage } from "../runs/store-lookup.ts";
 import type {
 	ChildRecord,
 	ExecutionStatus,
@@ -715,14 +716,22 @@ function summaryCompletions(
 		.map((name) => ({ value: all ? `--all ${name}` : name, label: name }));
 }
 
+/**
+ * Miss reporting for `/legion summary <name>` (#288).
+ *
+ * Was a hand-rolled sentence telling the caller to "pass the same cwd used for
+ * launch" -- advice that the cross-store lookup had already made obsolete, and
+ * advice the caller could not act on anyway (they do not know that cwd).
+ *
+ * Now it runs the same lookup `status` uses and prints `unknownChildMessage`,
+ * so every named operation reports a miss identically and lists what WAS found.
+ */
 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",
-	);
+	const { searched } = resolveChildAcrossStores({ name, cwd: ctx.cwd });
+	ctx.ui.notify(unknownChildMessage({ name, cwd: ctx.cwd, searched }), "error");
 }
 
 /** Build the `/legion summary [--all] [<name>]` handler. */

package/src/extension/timing.ts

@@ -18,6 +18,7 @@ import {
 	pickChildByName,
 } from "../runs/store.ts";
 import { sendSlashText, type LegionSubcommand } from "./slash.ts";
+import { resolveChildAcrossStores, unknownChildMessage } from "../runs/store-lookup.ts";
 import {
 	aggregateSubagentRuns,
 	formatDuration,
@@ -318,14 +319,17 @@ function timingCompletions(
 		}));
 }
 
+/**
+ * Miss reporting for `/legion timing <name>` (#288). Same cross-store lookup and
+ * same message as `status` and `summary`, so a miss reads identically everywhere
+ * and reports what was actually searched instead of advising an unknowable cwd.
+ */
 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",
-	);
+	const { searched } = resolveChildAcrossStores({ name, cwd: ctx.cwd });
+	ctx.ui.notify(unknownChildMessage({ name, cwd: ctx.cwd, searched }), "error");
 }
 
 function findTimingChild(