pi-legion 4.0.0 → 5.0.0

package/index.ts

@@ -21,6 +21,7 @@ import type {
 import { Type, type Static } from "typebox";
 import { RpcSupervisor } from "./src/supervisor/rpc-supervisor.ts";
 import { InProcessSupervisor } from "./src/supervisor/inprocess-supervisor.ts";
+import { runAtAbsoluteDepth } from "./src/supervisor/inprocess-depth.ts";
 import { notifyInProcessSlotReleased, RoutingSupervisor } from "./src/supervisor/routing-supervisor.ts";
 import type { LegionSupervisor } from "./src/supervisor/types.ts";
 import { InMemoryUIProxy, type UIProxy } from "./src/supervisor/ui-proxy.ts";
@@ -48,6 +49,7 @@ import { resolveTeamContext } from "./src/agents/context.ts";
 import { createSessionRuntime, renderLiveChildStatus, type SessionRuntime, shouldRecycleAfterCollect, type WaitResult } from "./src/extension/runtime.ts";
 import { createDbEventSource, createLegionEventBus, type DbEventSource, type LegionEventBus } from "./src/extension/event-bus.ts";
 import { LegionPostman, registerLegionTools, type LegionMailCommand } from "./src/extension/legion-tools.ts";
+import type { PhaseMachine } from "./src/legion/phase-machine.ts";
 import { LEGION_DB_ENV, LEGION_NODE_ID_ENV } from "./src/runs/args.ts";
 import type { VerifyRunner } from "./src/runs/acceptance.ts";
 import { legionDbPath, openLegionDb, type DatabaseSync } from "./src/legion/db.ts";
@@ -57,7 +59,12 @@ import { getChildByName, getChildren, getNode, getSubtree, insertNode, type Legi
 import { DEFAULT_LEGION_SETTINGS, type LegionSettings } from "./src/shared/types.ts";
 import { parseNestedPathEnv } from "./src/shared/nested-path.ts";
 import { allocateSiblingNames, isValidAgentName } from "./src/shared/name.ts";
-import { deriveOutcome, isLastTurnComplete, parseSessionFile } from "./src/shared/session.ts";
+import {
+	deriveOutcome,
+	isLastTurnComplete,
+	NO_ASSISTANT_ABORT_REASON,
+	parseSessionFile,
+} from "./src/shared/session.ts";
 import { restoreHostNodeOptions } from "./src/supervisor/child-memory.ts";
 import { currentChildContext } from "./src/supervisor/child-context.ts";
 import { setVerifyQueueListener } from "./src/runs/verify-queue.ts";
@@ -81,11 +88,14 @@ import {
 } from "./src/extension/blocked.ts";
 import { formatAlreadyRecycled } from "./src/extension/recycle.ts";
 import {
+	completionStatusOf,
+	type RenewalProposal,
 	SUBAGENT_NOTIFY_TYPE,
 } from "./src/extension/notify.ts";
 import { renderSubagentNotice } from "./src/extension/notice-renderer.ts";
 import { renderSpawnResult } from "./src/extension/spawn-render.ts";
 import { PARENT_PLAYBOOK, TOOL_DESCRIPTION } from "./src/extension/playbook.ts";
+import { CHILD_ROLE_ENV } from "./src/extension/child-guard.ts";
 import { configureSessionErrors, recordSessionError } from "./src/extension/session-errors.ts";
 import { getAgentDir } from "./src/agents/paths.ts";
 import { expectedModelsFromSettings, parseDoctorSections, runLegionDoctor } from "./src/extension/legion-doctor.ts";
@@ -96,19 +106,31 @@ import {
 	type OrchestratorLegionContext,
 } from "./src/runs/orchestrator.ts";
 import { RunStore, pickChildByName } from "./src/runs/store.ts";
+import {
+	candidateStoreRoots,
+	resolveChildAcrossStores,
+	unknownChildMessage,
+	type CandidateStore,
+} from "./src/runs/store-lookup.ts";
 import { RUN_OWNER_FILE, ownerState } from "./src/runs/owner.ts";
+import { measureProgress, readSessionLines } from "./src/runs/progress-signal.ts";
 import { resolveLaunchWorktree } from "./src/runs/worktree.ts";
 import {
 	type AgentConfig,
 	type AgentScope,
+	type ChildRecord,
 	DEFAULTS,
+	DEFAULT_MAX_RENEWALS,
 	DEFAULT_ON_BLOCKED,
+	DEFAULT_RENEWABLE,
 	ErrorCodes,
+	type Execution,
 	type ModelOrigin,
 	type RetireOptions,
 	type SpawnMode,
 	SubagentError,
 	type SubagentsSettings,
+	unknownChildError,
 	type Handle,
 } from "./src/shared/types.ts";
 
@@ -119,7 +141,12 @@ import {
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate" }),
-	cwd: Type.Optional(Type.String()),
+	cwd: Type.Optional(
+		Type.String({
+			description:
+				"Directory the child records live under (`<cwd>/.pi-subagents`), used by launch and by every control action. Defaults to the session cwd. A name miss searches the neighbouring stores too, so this is rarely needed.",
+		}),
+	),
 	model: Type.Optional(Type.String()),
 	preset: Type.Optional(
 		Type.String({ description: "Named kind+model+thinking preset" }),
@@ -175,7 +202,12 @@ const SubagentParams = Type.Object({
 	preset: Type.Optional(
 		Type.String({ description: "Named kind+model+thinking preset" }),
 	),
-	cwd: Type.Optional(Type.String()),
+	cwd: Type.Optional(
+		Type.String({
+			description:
+				"Directory the child records live under (`<cwd>/.pi-subagents`) for launch and every control action. Defaults to the session cwd. A name miss also searches neighbouring stores, so setting this is rarely needed.",
+		}),
+	),
 	worktree: Type.Optional(
 		Type.Boolean({
 			description:
@@ -249,7 +281,12 @@ const VexillatioParams = Type.Object({
 	),
 	agent: Type.Optional(Type.String({ description: "Utility agent name (default: scout)" })),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Parallel recon launches" })),
-	cwd: Type.Optional(Type.String()),
+	cwd: Type.Optional(
+		Type.String({
+			description:
+				"Directory the child records live under (`<cwd>/.pi-subagents`) for launch and every control action. Defaults to the session cwd. A name miss also searches neighbouring stores, so setting this is rarely needed.",
+		}),
+	),
 	model: Type.Optional(Type.String()),
 	timeoutMs: Type.Optional(Type.Number({ description: "Per-child wait in ms, default 600000" })),
 });
@@ -328,7 +365,19 @@ function currentProcessSpawnMode(): SpawnMode {
 const INTERRUPTED_HEAD = "interrupted (parent turn ended; children still running)";
 
 function notice(pi: ExtensionAPI, text: string): void {
-	pi.sendMessage({ customType: SUBAGENT_NOTIFY_TYPE, content: text, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+	// #273: `sendMessage` is a host ACTION and pi throws
+	// "Extension runtime not initialized. Action methods cannot be called during
+	// extension loading." if it is reached before the runtime is up. An error
+	// handler that is more fatal than the error it reports turns "a resume
+	// failed" into "the whole agent process died", which is what happened on the
+	// centurion recovery path. Degrade to stderr instead; the caller still gets
+	// the fact, and nothing crashes.
+	try {
+		pi.sendMessage({ customType: SUBAGENT_NOTIFY_TYPE, content: text, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		console.error(`[pi-legion] notice not delivered (${reason}): ${text}`);
+	}
 }
 
 /**
@@ -444,6 +493,26 @@ export function attachLegionRuntime(input: {
 	return dbEventSource;
 }
 
+/**
+ * The phase machine for a legion node, from its role card (#298).
+ *
+ * Reads `phases:` off the agent definition for the node's role. Absent means the
+ * built-in machine, so an undeclared team is unaffected. A card that declares an
+ * invalid machine never reaches here: `parseAgentDocument` rejects it at load.
+ */
+function phaseMachineForRole(role: string | null | undefined, cwd: string, settings: SubagentsSettings): PhaseMachine | undefined {
+	if (!role) return undefined;
+	try {
+		const discovery = discoverAgents(cwd, "user", { includeBuiltin: settings.disableBuiltins !== true });
+		const overridden = applyAgentOverrides(discovery.agents, settings.agentOverrides);
+		return findAgent(overridden, role)?.phases;
+	} catch {
+		// Discovery is best-effort here: a broken project dir must not stop a team
+		// from attaching, and the built-in machine still works.
+		return undefined;
+	}
+}
+
 function createLegionRuntime(input: {
 	pi: ExtensionAPI;
 	supervisor: LegionSupervisor;
@@ -457,6 +526,8 @@ function createLegionRuntime(input: {
 	settings: LegionSettings;
 	eventBus: LegionEventBus;
 	registerTools: boolean;
+	/** #298: the team root's declared phase machine, when its card supplies one. */
+	machine?: PhaseMachine;
 }): LegionRuntimeIdentity {
 	const self = getNode(input.db, input.nodeId);
 	const eventBus = input.eventBus;
@@ -469,6 +540,7 @@ function createLegionRuntime(input: {
 		eventBus,
 		sendRootMessage: (text: string) => notice(input.pi, text),
 		sendSelfMessage: (text: string) => notice(input.pi, text),
+		...(input.machine ? { machine: input.machine } : {}),
 		resumeChild: (node: LegionNode, mail: LegionMailCommand) => resumeLegionChild({
 			pi: input.pi, supervisor: input.supervisor, db: input.db, dbPath: input.dbPath,
 			eventBus, settings: input.settings, cwd: input.cwd, storeRootDir: input.storeRootDir,
@@ -493,7 +565,7 @@ function createLegionRuntime(input: {
 		postman,
 		childNodeId: (name) => getChildByName(input.db, input.nodeId, name)?.id,
 	};
-	if (input.registerTools && input.nodeId !== "root") registerLegionTools(input.pi, { db: input.db, nodeId: input.nodeId, role: self?.role, settings: input.settings, cwd: input.cwd, runDir: input.runDir, eventBus, sendSelfMessage: (text: string) => notice(input.pi, text) });
+	if (input.registerTools && input.nodeId !== "root") registerLegionTools(input.pi, { db: input.db, nodeId: input.nodeId, role: self?.role, settings: input.settings, cwd: input.cwd, runDir: input.runDir, eventBus, sendSelfMessage: (text: string) => notice(input.pi, text), ...(input.machine ? { machine: input.machine } : {}) });
 	postman.start();
 	return identity;
 }
@@ -551,8 +623,31 @@ function resolveLegionIdentity(input: {
 			nodeRun = input.store.createRun({ task: node.taskSummary ?? `Resume ${node.role} node ${node.id}`, cwd: input.cwd, path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH), maxDepth: effectiveMaxDepth(input.settings.legion?.maxDepth), nodeId, herdr: { supervisor: "rpc", node_id: nodeId } });
 		}
 		if (node.runId !== nodeRun.runId) updateLegionRunId(db, nodeId, nodeRun.runId);
-		const identity = createLegionRuntime({ pi: input.pi, supervisor: input.supervisor, db, dbPath: absoluteDbPath, nodeId, rootRunId: getNode(db, "root")?.runId ?? path.basename(path.dirname(absoluteDbPath)), runDir: input.store.runDir(nodeRun.runId), cwd: input.cwd, storeRootDir: input.store.rootDir, settings: settingsForLegion(input.settings), eventBus: input.eventBus, registerTools: true });
-		if (node.role === "centurion") void resumeLegionTeam({ identity, input });
+		const machine = phaseMachineForRole(node.role, input.cwd, input.settings);
+		const identity = createLegionRuntime({ pi: input.pi, supervisor: input.supervisor, db, dbPath: absoluteDbPath, nodeId, rootRunId: getNode(db, "root")?.runId ?? path.basename(path.dirname(absoluteDbPath)), runDir: input.store.runDir(nodeRun.runId), cwd: input.cwd, storeRootDir: input.store.rootDir, settings: settingsForLegion(input.settings), eventBus: input.eventBus, registerTools: true, ...(machine ? { machine } : {}) });
+		// #273: `createLegionRuntime` runs during extension LOADING, where host
+		// actions (sendMessage, spawn, ui) are not available yet. Defer the team
+		// recovery to the next tick so a failure inside it cannot crash the load
+		// path, and so any notice it emits has a live runtime to go to.
+		if (node.role === "centurion") {
+			// #275: run the recovery at depth 0 explicitly. `queueMicrotask`
+			// INHERITS the AsyncLocalStorage depth (verified: `als.getStore()`
+			// inside a queued microtask still reads the parent's value), so a
+			// recovery queued from a nested context would start already deep and
+			// report `nesting limit reached (depth N, max 4)` for a two-level
+			// chain. `runAtAbsoluteDepth(0, …)` is the mechanism this codebase
+			// already uses for exactly that reason (see inprocess-depth.ts
+			// "REV2-1"): the recovery runs at the TOP of the tree, not under
+			// whatever context happened to enqueue it.
+			queueMicrotask(() => {
+				void runAtAbsoluteDepth(0, async () => {
+					await resumeLegionTeam({ identity, input });
+				}).catch((error: unknown) => {
+					const reason = error instanceof Error ? error.message : String(error);
+					console.error(`[pi-legion] team recovery for ${identity.nodeId} failed: ${reason}`);
+				});
+			});
+		}
 		return identity;
 	}
 	if (input.cached?.nodeId === "root" && path.resolve(input.cached.storeRootDir) === path.resolve(input.store.rootDir)) return input.cached;
@@ -644,6 +739,51 @@ async function resumeLegionChild(input: { pi: ExtensionAPI; supervisor: LegionSu
 	await store.updateChild(parentRun.runId, saved.name, (child) => Object.assign(child, handle.child));
 }
 
+/**
+ * The live legion runtime for THIS process, held at module scope rather than in
+ * the `piLegion` closure (#283).
+ *
+ * `pi` re-runs the extension factory for every `DefaultResourceLoader.reload()`,
+ * and an in-process child session creates its own loader
+ * (`inprocess-supervisor.ts` builds one per `createAgentSession`). So a single
+ * process can enter `piLegion` many times. A closure-local `let` reset to
+ * `undefined` on each entry defeated the cache inside `resolveLegionIdentity`,
+ * which then opened a fresh `legion.db` — and never closed it. Measured on a
+ * centurion dispatching one in-process scout: one extra open per entry, ~2.5k
+ * leaked descriptors per 20 s, RSS climbing to 6 GB until V8 aborted with
+ * `JavaScript heap out of memory`.
+ */
+/**
+ * Runtime handles for THIS process, keyed by ledger path (#283).
+ *
+ * Two independent facts force a map rather than a single slot:
+ *
+ * 1. `pi` re-runs the extension factory for every `DefaultResourceLoader.reload()`,
+ *    and an in-process child session builds its OWN loader per
+ *    `createAgentSession` — so one process enters `piLegion` many times. A
+ *    closure-local binding reset on every entry defeated the `cached`
+ *    short-circuit in `resolveLegionIdentity`, which then opened a fresh
+ *    `legion.db` per entry and never closed it: measured on a centurion
+ *    dispatching one in-process scout, ~2.5k leaked descriptors per 20 s and RSS
+ *    climbing to 6 GB until V8 aborted with `JavaScript heap out of memory`.
+ * 2. Those entries do NOT share one ledger. A parent and its in-process child
+ *    legitimately own different `legion.db` files, and each registers its own
+ *    `session_shutdown`. With a single slot the child's shutdown closed the
+ *    PARENT's database, surfacing later as `database is not open` from whichever
+ *    pump or admission probe ran next.
+ *
+ * Keying by (resolved path, nodeId) keeps the reuse (2) while giving each owner
+ * its own lifecycle (1).
+ *
+ * The path alone is NOT enough: a parent and its in-process child share ONE
+ * ledger file (the child inherits `dbPath` from the orchestrator's launch
+ * context) and differ only by the node row they own. Keying by path made them
+ * collide, so the child's shutdown closed the parent's handle and a sibling's
+ * next spawn failed with `database is not open` (#285 follow-up).
+ */
+const legionIdentityKey = (dbPath: string, nodeId: string): string => `${dbPath}\u0000${nodeId}`;
+const legionIdentities = new Map<string, LegionRuntimeIdentity>();
+
 export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps = {}) {
 	// #197 D8: a session is a child if either transport says so. RPC children
 	// are separate processes marked in env; in-process children share the
@@ -761,16 +901,50 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			return true;
 		}
 	};
-	let legionIdentity: LegionRuntimeIdentity | undefined;
-	const stopLegionRuntime = (): void => {
-		if (!legionIdentity) return;
-		legionIdentity.postman.stop();
-		legionIdentity.dbEventSource.stop();
-		// #40: bound the ledger and fold the WAL back before closing.
-		if (hygieneEnabled() && !isChild) applyEventRetention(legionIdentity.db);
-		else checkpoint(legionIdentity.db);
-		legionIdentity.db.close();
-		legionIdentity = undefined;
+	/**
+	 * Close one ledger handle (by resolved path) or every handle this process
+	 * opened. Shutdown handlers pass their own path so a child session teardown
+	 * cannot close the parent's database (#283).
+	 */
+	const stopLegionRuntime = (key?: string): void => {
+		const targets = key === undefined
+			? [...legionIdentities.entries()]
+			: (legionIdentities.has(key) ? [[key, legionIdentities.get(key)!] as const] : []);
+		for (const [key, identity] of targets) {
+			legionIdentities.delete(key);
+			identity.postman.stop();
+			identity.dbEventSource.stop();
+			// #40: bound the ledger and fold the WAL back before closing.
+			if (hygieneEnabled() && !isChild) applyEventRetention(identity.db);
+			else checkpoint(identity.db);
+			identity.db.close();
+		}
+	};
+	/** The handle this extension entry owns, if any (see `legionIdentities`). */
+	let ownLegionKey: string | undefined;
+	const ownLegionIdentity = (): LegionRuntimeIdentity | undefined =>
+		ownLegionKey === undefined ? undefined : legionIdentities.get(ownLegionKey);
+	/**
+	 * Register a resolved identity and make it this entry's own (#283/#285).
+	 *
+	 * One rule for every call site: the map holds at most one live handle per
+	 * ledger path, and an existing handle is only closed when THIS entry is
+	 * replacing the path it already owned. Reassigning across paths never closes
+	 * anything — a sibling entry (parent vs in-process child) may still be using
+	 * the handle, and closing it surfaced as `database is not open` from that
+	 * sibling's next spawn.
+	 */
+	const adoptLegionIdentity = (identity: LegionRuntimeIdentity): void => {
+		const key = legionIdentityKey(identity.dbPath, identity.nodeId);
+		const existing = legionIdentities.get(key);
+		// Only close when this entry is replacing the key it ALREADY owns: that
+		// handle is provably ours. A handle owned by a sibling (same ledger file,
+		// different node) is not ours to close.
+		if (existing && existing !== identity && ownLegionKey === key) {
+			stopLegionRuntime(key);
+		}
+		if (existing !== identity) legionIdentities.set(key, identity);
+		ownLegionKey = key;
 	};
 	const initializeLegionRuntime = (ctx: Pick<ExtensionContext, "cwd"> & { sessionFile?: string; legionNode?: { dbPath: string; nodeId: string } }): void => {
 		// The injected node's dbPath is authoritative: an in-process child shares the
@@ -780,9 +954,27 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			userSettingsPath: path.join(getAgentDir(), "settings.json"),
 			projectSettingsPath: path.join(ctx.cwd, ".pi", "settings.json"),
 		});
-		const next = resolveLegionIdentity({ pi, supervisor, store, cwd: ctx.cwd, settings, eventBus: legionBus, cached: legionIdentity, sessionFile: ctx.sessionFile, legionNode: ctx.legionNode });
-		if (legionIdentity && next !== legionIdentity) stopLegionRuntime();
-		legionIdentity = next;
+		// Resolve the ledger path BEFORE asking for a cache entry: a fresh factory
+		// entry starts with no owned path, but the same database may already have a
+		// live handle from an earlier entry in this process (#283).
+		const targetPath = ctx.legionNode?.dbPath ?? process.env[LEGION_DB_ENV];
+		const targetNode = ctx.legionNode?.nodeId ?? process.env[LEGION_NODE_ID_ENV];
+		const cached = targetPath !== undefined && targetNode !== undefined && path.isAbsolute(targetPath)
+			? legionIdentities.get(legionIdentityKey(path.resolve(targetPath), targetNode))
+			: ownLegionIdentity();
+		const next = resolveLegionIdentity({ pi, supervisor, store, cwd: ctx.cwd, settings, eventBus: legionBus, cached, sessionFile: ctx.sessionFile, legionNode: ctx.legionNode });
+		if (next === undefined) return;
+		// Index by ledger path: a re-entry for the SAME database reuses the cached
+		// handle, a different database (parent vs its in-process child) gets its
+		// own slot.
+		//
+		// Never close `cached` here just because this entry resolved elsewhere.
+		// `resolveLegionIdentity` returns a DIFFERENT object for the same path when
+		// the node/session changed, and that earlier handle may still be in use by
+		// the entry that opened it — closing it produced `database is not open`
+		// from a sibling's spawn (#285 follow-up). Only the entry that owns a path
+		// closes it, via its own session_shutdown.
+		adoptLegionIdentity(next);
 	};
 	if (isChild) {
 		registerChildGuard(pi);
@@ -836,7 +1028,7 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		}
 		const { storeRoot, notify } = pendingHygiene;
 		try {
-			const report = runStartupHygiene({ storeRoot, protectRunIds: legionIdentity ? [legionIdentity.rootRunId] : [] });
+			const report = runStartupHygiene({ storeRoot, protectRunIds: ownLegionIdentity() ? [ownLegionIdentity()!.rootRunId] : [] });
 			const text = formatHygieneReport(report);
 			if (text) notify?.(text);
 		} catch (error) {
@@ -880,7 +1072,9 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			...children.map((job) => job.retire?.(shutdownRetire).catch(() => {})),
 			...pendingUtilityRetires.map((retire) => retire(shutdownRetire).catch(() => {})),
 		]);
-		stopLegionRuntime();
+		// Scope to the ledger THIS entry opened: a parent and its in-process child
+		// both register a shutdown handler, and each must close only its own (#283).
+		stopLegionRuntime(ownLegionKey);
 	};
 	if (process.env[UTILITY_CHILD_ENV] !== "1") {
 		pi.registerTool({
@@ -913,11 +1107,10 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 					sessionCwd: ctx.cwd,
 					signal,
 					isChild,
-					legion: legionIdentity,
+					legion: ownLegionIdentity(),
 					eventBus: legionBus,
 					onLegion: (identity) => {
-						if (legionIdentity && legionIdentity !== identity) stopLegionRuntime();
-						legionIdentity = identity;
+						adoptLegionIdentity(identity);
 					},
 					onUtilityChild: (retire) => pendingUtilityRetires.push(retire),
 				});
@@ -941,16 +1134,25 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			catalog.settings,
 			catalog.team,
 		);
+		// A centurion running as a NESTED child is still a "parent" for templating
+		// purposes — it dispatches its own squad — but it must not be offered itself:
+		// the runtime refuses a non-root centurion dispatch (a nested centurion is
+		// a second command chain the root cannot collect), so listing it invites a
+		// call that can only fail. Leaving it out keeps the roster truthful.
+		const selfRole = process.env[CHILD_ROLE_ENV];
+		const rosterAgents = selfRole
+			? catalog.agents.filter((agent) => agent.name !== selfRole)
+			: catalog.agents;
 		return {
 			systemPrompt: `${event.systemPrompt}\n\n${PARENT_PLAYBOOK}\n\n${renderParentRoster(
-				catalog.agents,
+				rosterAgents,
 				catalog.team,
 				catalog.teamWarnings,
 			)}${parentContext ? `\n\n${parentContext}` : ""}`,
 		};
 	});
 	if (process.env[UTILITY_CHILD_ENV] === "1") {
-		pi.on("session_shutdown", () => stopLegionRuntime());
+		pi.on("session_shutdown", () => stopLegionRuntime(ownLegionKey));
 		return;
 	}
 	let lastUi: ExtensionUIContext | undefined;
@@ -970,13 +1172,37 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		statusStrip: process.env.PI_LEGION_STRIP === "tree" ? "tree" : "railway",
 		eventBus: legionBus,
 		getTreeNodes: () => {
-			const identity = legionIdentity;
+			const identity = ownLegionIdentity();
 			return identity
 				? attachUsageTotals(identity.db, getSubtree(identity.db, identity.nodeId))
 				: [];
 		},
+		// #298: let the tree render a team's declared workflow. Cached per role
+		// because agent discovery touches the filesystem and the tree re-renders on
+		// every event.
+		getPhaseMachine: (() => {
+			const cache = new Map<string, PhaseMachine | undefined>();
+			return (role) => {
+				if (!role) return undefined;
+				if (cache.has(role)) return cache.get(role);
+				let machine: PhaseMachine | undefined;
+				try {
+					// `loadCatalog` already applies agentOverrides and team selection, so
+					// this is the same definition the launch path resolves.
+					const catalog = loadCatalog(lastCwd, lastCwd, undefined);
+					machine = findAgent(catalog.agents, role)?.phases;
+				} catch {
+					// Discovery must never break rendering: a malformed project dir would
+					// otherwise blank the tree.
+					machine = undefined;
+				}
+				cache.set(role, machine);
+				return machine;
+			};
+		})(),
 		getTreeIdentity: (name) => {
-			const node = legionIdentity && getChildByName(legionIdentity.db, legionIdentity.nodeId, name);
+			const own = ownLegionIdentity();
+			const node = own && getChildByName(own.db, own.nodeId, name);
 			return node ? {
 				nodeId: node.id,
 				parentId: node.parentId,
@@ -984,10 +1210,37 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 				supervisorName: name,
 			} : undefined;
 		},
+		/**
+		 * subagent-renewal-v1 D3: the one renewal proposal the completion notice
+		 * may carry.
+		 *
+		 * Read from the persisted ChildRecord so a proposal survives process
+		 * boundaries (each tool call is a fresh process). Every "do not offer"
+		 * rule — D1 completed, D7 still running, D5 role opt-out, D8 no baseline —
+		 * lives inside `renewalProposalFor`, so returning its undefined is the
+		 * whole decision.
+		 */
+		getRenewalProposal: (name, execution) => {
+			// Each tool call is a fresh process, so the child record comes off disk
+			// rather than from any in-memory launch state.
+			const cwd = lastCwd;
+			if (!cwd) return undefined;
+			const located = findChild(runStoreFor(cwd).listRuns(), name);
+			if (!located) return undefined;
+			const catalog = loadCatalog(cwd, cwd, undefined);
+			const def = findControlAgent(catalog.agents, catalog.allAgents, located.child.agent);
+			return renewalProposalFor({
+				agent: def,
+				child: located.child,
+				sessionFile: located.child.sessionFile,
+				execution,
+				name,
+			});
+		},
 		subscribeSupervisorEvents: (name, listener, options) => rpcEventSource.onEvent?.(
 			name,
 			(event) => {
-				const nodeId = legionIdentity?.childNodeId(name);
+				const nodeId = ownLegionIdentity()?.childNodeId(name);
 				if (nodeId) publishSupervisorEvent(legionBus, nodeId, event, options);
 				listener(event);
 			},
@@ -1259,12 +1512,12 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 
 			let activeLegion: LegionRuntimeIdentity | undefined;
 			try {
-				activeLegion = resolveLegionIdentity({ pi, supervisor, store, cwd, settings, eventBus: legionBus, cached: legionIdentity, sessionFile: ctx.sessionManager?.getSessionFile() });
+				activeLegion = resolveLegionIdentity({ pi, supervisor, store, cwd, settings, eventBus: legionBus, cached: ownLegionIdentity(), sessionFile: ctx.sessionManager?.getSessionFile() });
 				if (!activeLegion && action === "launch" && !isChild) {
 					const plan = buildPlan(params);
 					if (plan.ok) activeLegion = createRootLegion({ pi, supervisor, store, cwd, task: plan.task, settings, maxDepth: effectiveMaxDepth(settings.legion?.maxDepth), eventBus: legionBus });
 				}
-				if (activeLegion) legionIdentity = activeLegion;
+				if (activeLegion) adoptLegionIdentity(activeLegion);
 			} catch (error) {
 				return fail(`legion runtime initialization failed: ${error instanceof Error ? error.message : String(error)}`, ErrorCodes.INVALID_PARAMS);
 			}
@@ -1285,6 +1538,9 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 					verifyRunner,
 					store,
 					cwd,
+					// #270: the session cwd is a second store worth searching when the
+					// call passes an explicit `cwd` that differs from it.
+					...(ctx.cwd && ctx.cwd !== cwd ? { callerCwd: ctx.cwd } : {}),
 					agents,
 					allAgents,
 					team,
@@ -1355,7 +1611,7 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 	};
 
 	uiProxy.onRequest((pending) => {
-		const legionNodeId = legionIdentity?.childNodeId(pending.childName);
+		const legionNodeId = ownLegionIdentity()?.childNodeId(pending.childName);
 		if (legionNodeId) publishUIRequest(legionBus, legionNodeId, pending.request.method);
 		const ui = lastUi;
 		if (!ui) return;
@@ -1516,6 +1772,11 @@ async function controlAction(input: {
 	verifyRunner?: VerifyRunner;
 	store: RunStore;
 	cwd: string;
+	/**
+	 * #270: the session's own cwd, when the call also passes an explicit `cwd`.
+	 * Child records may live in either store, so both are searched on a miss.
+	 */
+	callerCwd?: string;
 	agents: AgentConfig[];
 	allAgents: AgentConfig[];
 	team: ActiveTeam;
@@ -1566,7 +1827,7 @@ async function controlAction(input: {
 				// all names but before the serial loop reaches it. Treat that target as
 				// stopped; only rebuild if its persisted record is not already retired.
 				const found = findChild(input.store.listRuns(), name);
-				if (!found) throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
+				if (!found) throw unknownChildError(name);
 				if (found.child.state === "retired") return;
 				const orchestrator = new Orchestrator({
 					supervisor: input.supervisor,
@@ -1624,8 +1885,15 @@ async function controlAction(input: {
 			);
 		}
 		const runs = store.listRuns();
-		const found = findChild(runs, params.name);
-		if (!found) return unknownChild(params.name, store, cwd);
+		// #270: a miss in this store is not a miss overall — a worktree child's
+		// record lives under its own store, which this one cannot enumerate.
+		const found = findChild(runs, params.name) ?? findChildAcrossStores({
+			name: params.name,
+			cwd,
+			callerCwd: input.callerCwd,
+			ownRoot: store.rootDir,
+		});
+		if (!found) return unknownChild(params.name, store, cwd, input.callerCwd);
 		const alive = input.supervisor.isAlive(params.name);
 		const owner = ownerVerdictFor(store, runs, params.name, alive);
 		return ok(renderLiveChildStatus({
@@ -1649,8 +1917,15 @@ async function controlAction(input: {
 		);
 	}
 
-	const found = findChild(store.listRuns(), params.name);
-	if (!found) return unknownChild(params.name, store, cwd);
+	const found =
+		findChild(store.listRuns(), params.name) ??
+		findChildAcrossStores({
+			name: params.name,
+			cwd,
+			callerCwd: input.callerCwd,
+			ownRoot: store.rootDir,
+		});
+	if (!found) return unknownChild(params.name, store, cwd, input.callerCwd);
 
 	const orchestrator = new Orchestrator({
 		supervisor: input.supervisor,
@@ -1713,13 +1988,29 @@ function unknownChild(
 	name: string,
 	store: RunStore,
 	cwd: string,
+	callerCwd?: string,
 ): AgentToolResult<unknown> {
-	const known = store.listRuns().flatMap((run) => run.children.map((child) => child.name));
+	// #270: search the stores that can plausibly hold the record before giving up.
+	// A worktree child's store lives under `<runDir>/worktrees/<name>/.pi-subagents`,
+	// which the root store can never enumerate, so a single-store lookup reports a
+	// miss for a child that plainly exists.
+	// The store already searched comes first, then every other candidate
+	// (caller cwd, worktree stores). `resolveChildAcrossStores` re-searches the
+	// own store too — that is deliberate: it returns the `searched` list the
+	// message needs, and a store with no runs simply drops out of it.
+	const { searched } = resolveChildAcrossStores({
+		name,
+		cwd,
+		callerCwd,
+		roots: [
+			{ rootDir: path.resolve(store.rootDir), reason: "cwd" as const },
+			...candidateStoreRoots({ cwd, callerCwd }).filter(
+				(candidate) => candidate.rootDir !== path.resolve(store.rootDir),
+			),
+		],
+	});
 	return fail(
-		`unknown child: ${name} (no run under ${cwd}/.pi-subagents` +
-			`${known.length ? `; known here: ${known.join(", ")}` : ""}). ` +
-			`Child records are scoped to the \`cwd\` they were launched from — ` +
-			`pass the same \`cwd\` you used for \`launch\`.`,
+		unknownChildMessage({ name, cwd, searched: searched as CandidateStore[] }),
 		ErrorCodes.NOT_FOUND,
 	);
 }
@@ -1810,6 +2101,171 @@ async function retireChild(
 	}
 }
 
+/**
+ * D8: a fresh progress baseline, taken from the session file as it is NOW.
+ *
+ * A child that has just been spawned (or relaunched from its session) may have
+ * an empty or not-yet-created session file; `lines: 0` is then the honest
+ * answer and everything written afterwards counts as progress. Never throws —
+ * an unreadable file is "nothing written yet", not a launch failure.
+ */
+export function renewalBaselineFor(
+	sessionFile: string,
+	at: number = Date.now(),
+	readLines: (file: string) => string[] | undefined = readSessionLines,
+): { at: number; lines: number } {
+	return { at, lines: readLines(sessionFile)?.length ?? 0 };
+}
+
+/**
+ * D5-a: was this child **cut off by its turn budget** rather than finishing?
+ *
+ * `continue`/`resume` works on every terminal child, but only a budget casualty
+ * should spend a renewal (D6) — otherwise an ordinary retry after a normal
+ * failure quietly eats the budget, and the budget stops meaning anything.
+ *
+ * Judgement order is frozen by D5-a and follows `src/shared/session.ts`'s
+ * measured semantics (F29), most reliable first:
+ *
+ *  1. `stopReason === "toolUse"` — the final assistant row was still waiting on
+ *     a tool when the process went away: the classic budget-exhaustion shape.
+ *  2. No assistant message for the last prompt — F29: a hard kill writes no
+ *     assistant row at all, so "missing reply" IS the abort signal.
+ *  3. `reason` mentions `terminated` — the host's own label, the weakest of the
+ *     three because wording is not a contract.
+ *
+ * A clean `stop` / `length` turn (the user simply asked for another round)
+ * matches none of them and does **not** spend a renewal.
+ *
+ * `shouldRecycleAfterCollect` is deliberately NOT used: it only separates
+ * terminal from non-terminal, which is a different question.
+ */
+export function wasBudgetCut(execution: Execution | undefined): boolean {
+	if (!execution) return false;
+	// 1. Terminated while a tool call was outstanding.
+	if (execution.stopReason === "toolUse") return true;
+	// 2. F29 hard kill: the turn has no assistant row at all.
+	if (
+		execution.reason === NO_ASSISTANT_ABORT_REASON &&
+		execution.stopReason !== "stop" &&
+		execution.stopReason !== "length"
+	) {
+		return true;
+	}
+	// 3. Host wording, last resort.
+	return execution.reason?.toLowerCase().includes("terminated") ?? false;
+}
+
+/**
+ * D3: the renewal proposal to attach to a **real termination** notice, or
+ * `undefined` when the contract says not to offer one.
+ *
+ * Extracted as a pure function (not inlined at the notify call site) because
+ * the whole decision is testable without launching a child: "was the budget
+ * cut + is the role renewable + has it a baseline" is arithmetic, not I/O.
+ *
+ * The four exits, all locked by tests:
+ * - **D1** a `completed` child is never a renewal candidate: it produced a
+ *   verdict, so offering `continue` would relaunch finished work.
+ * - **D7/A3** a `running` snapshot is a `wait`/`collect` deadline on a **live**
+ *   child (`inprocess-supervisor` merely resolved `{settled:false}`); the child
+ *   never lost a budget, so renewing it would spend a fresh one for nothing.
+ * - **D5/A4** `renewable: false` → no proposal at all, so the notice keeps the
+ *   exact pre-W3 bytes (no renewal lines).
+ * - **A2** no measurable progress is still **reported**: the caller passes the
+ *   measurement through and `notify.ts` prints "no measurable progress". The
+ *   proposal is withheld only for the three reasons above, never for "we could
+ *   not tell".
+ *
+ * **A5/D6**: `used >= max` still gets a proposal — the renderer turns it into
+ * `renewals exhausted (used/max) — split the task instead of renewing`. That is
+ * a deliberate hand-off to the human, not silence.
+ *
+ * `maxRenewals: 0` (D6) is "renewal disabled": `renewable` is the role-level
+ * switch, `0` the budget-level one, and both must agree before an offer is made.
+ */
+export function renewalProposalFor(input: {
+	agent: Pick<AgentConfig, "renewable" | "maxRenewals"> | undefined;
+	child: Pick<ChildRecord, "renewalBaseline" | "renewalsUsed">;
+	/** Session file the progress measurement reads; the resume credential (D8). */
+	sessionFile: string;
+	execution: { status: string; reason?: string };
+	name: string;
+	/** Injectable for tests; defaults to W1's measurer over the real session file. */
+	measure?: (sessionFile: string, baseline: { at: number; lines: number }) => {
+		toolResults: number;
+		assistantMessages: number;
+		filesChanged?: number;
+	};
+}): RenewalProposal | undefined {
+	const status = completionStatusOf(
+		input.execution.status,
+		// Acceptance is not part of this decision: D1 keys on the completion
+		// status alone, and `unknown` + a parsed verdict is handled by the
+		// caller's own status, not re-derived here.
+		undefined,
+	);
+	// D1: a finished child is not a renewal candidate.
+	if (status === "completed") return undefined;
+	// D7: `running` is a live child behind a `wait`/`collect` deadline.
+	if (status === "running") return undefined;
+	// D5: the role forbids renewal (e.g. scout: a timed-out search was mis-scoped).
+	if ((input.agent?.renewable ?? DEFAULT_RENEWABLE) === false) return undefined;
+	const max = input.agent?.maxRenewals ?? DEFAULT_MAX_RENEWALS;
+	// D6: `0` disables renewal outright; offering `0/0` would be a lie.
+	if (max <= 0) return undefined;
+	// D8: no baseline means nothing to measure against (#266-era records).
+	const baseline = input.child.renewalBaseline;
+	if (!baseline) return undefined;
+
+	const used = input.child.renewalsUsed ?? 0;
+	// D2 puts the worktree probe last, so the measurement is session-file only.
+	const measured = (input.measure ?? defaultRenewalMeasure)(
+		input.sessionFile,
+		baseline,
+	);
+	return {
+		progress: {
+			toolResults: measured.toolResults,
+			assistantMessages: measured.assistantMessages,
+			...(measured.filesChanged !== undefined
+				? { filesChanged: measured.filesChanged }
+				: {}),
+		},
+		used,
+		max,
+		// D4/A8: renewal IS `continue`; the parent gets a finished command.
+		command: `subagent({ action: "continue", name: "${input.name}", message: "<what to continue>" })`,
+	};
+}
+
+/** Session-file half of {@link renewalProposalFor}; no worktree probe (D2 puts it last). */
+function defaultRenewalMeasure(
+	sessionFile: string,
+	baseline: { at: number; lines: number },
+): { toolResults: number; assistantMessages: number; filesChanged?: number } {
+	return measureProgress({ sessionFile, baseline });
+}
+
+/**
+ * D6/D8: charge one renewal to a child, D5-a's way.
+ *
+ * Split out from `reviveChild` so the arithmetic is testable in isolation: the
+ * caller has already decided (via {@link wasBudgetCut}) whether this continue
+ * was a budget casualty, and only then does the counter move.
+ *
+ * Absent `renewalsUsed` means "never renewed" (#266-era record), so it reads as
+ * 0 rather than throwing. The baseline is the caller's business: it must come
+ * from the **relaunched** session file, which only that layer holds.
+ */
+export function chargeRenewal(
+	child: Pick<ChildRecord, "renewalsUsed">,
+): number {
+	const used = (child.renewalsUsed ?? 0) + 1;
+	child.renewalsUsed = used;
+	return used;
+}
+
 /**
  * Continue or resume a child.
  *
@@ -1855,6 +2311,32 @@ async function reviveChild(
 			name,
 			...(found.child.model ? { model: found.child.model } : {}),
 		});
+		// D6/D8/D5-a: spend one renewal, but only if this child was actually cut
+		// off by its turn budget.
+		//
+		// `continue` is legal on every terminal child (D4), yet an ordinary retry
+		// after a normal `stop` must not eat the budget — otherwise two harmless
+		// retries would silently exhaust the allowance that exists for genuine
+		// budget casualties. `wasBudgetCut` answers that from the session shape
+		// (F29/D5-a), not from `shouldRecycleAfterCollect` (terminal vs not, a
+		// different question).
+		//
+		// The baseline is reset in both branches. A non-budget continue still
+		// moved the child's own "since" line forward: keeping the old baseline
+		// would count this whole extra turn as progress at the next termination
+		// and overstate how much the child achieved under the current budget.
+		const resumedChild =
+			orchestrator.childrenSnapshot().find((entry) => entry.name === handle.name) ??
+			found.child;
+		// Read the verdict from `found.child`, NOT the orchestrator's record: `launch`
+		// clears `previous.execution` before returning (it is a relaunch), and
+		// `found` is a freshly parsed copy from `store.listRuns()`, so the pre-resume
+		// outcome is still intact there. Reading the orchestrator's object here
+		// would see `undefined` on every single resume and never charge anything.
+		const budgetCut = wasBudgetCut(found.child.execution);
+		resumedChild.renewalBaseline = renewalBaselineFor(handle.sessionFile);
+		if (budgetCut) chargeRenewal(resumedChild);
+		await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, handle.name);
 		followChild(ctx, { watch: true });
 		return ok(
 			`Resumed ${handle.name} from its session. Context preserved from ${handle.sessionFile}`,
@@ -3173,6 +3655,39 @@ function followLaunched(
 	});
 }
 
+/**
+ * Persist the orchestrator's current view of one child.
+ *
+ * RunStore is async while Orchestrator's `onChildUpdate` is synchronous, so
+ * persistence is done explicitly here rather than from inside the callback
+ * (which would leave floating promises).
+ */
+/**
+ * D8: give a child its spawn-time progress baseline exactly once.
+ *
+ * Called before every persist, so whichever launch path created the record
+ * seeds it at (as near as makes no difference) spawn time: `persistChild` runs
+ * immediately after `launch()` on every path — fresh launch, `tasks[]` fan-out,
+ * utility dispatch — and the session file is empty-ish at that moment by
+ * definition (`lines: 0` is then the honest answer, see {@link renewalBaselineFor}).
+ *
+ * The guard is "absent", never "stale":
+ * - a record written before this field existed seeds on its next write, which
+ *   is the first moment anything is known about it;
+ * - a renewed child keeps the baseline `reviveChild` handed it, so D8's
+ *   "count only what happened since the renewal" cannot be undone here.
+ */
+export function seedRenewalState(
+	child: Pick<ChildRecord, "sessionFile" | "renewalBaseline" | "renewalsUsed">,
+	now: number = Date.now(),
+	readLines: (file: string) => string[] | undefined = readSessionLines,
+): void {
+	if (!child.renewalBaseline) {
+		child.renewalBaseline = renewalBaselineFor(child.sessionFile, now, readLines);
+	}
+	if (child.renewalsUsed === undefined) child.renewalsUsed = 0;
+}
+
 /**
  * Persist the orchestrator's current view of one child.
  *
@@ -3189,6 +3704,10 @@ async function persistChild(
 ): Promise<void> {
 	const child = orchestrator.childrenSnapshot().find((c) => c.name === name);
 	if (!child) return;
+	// D8: every persist path is a launch path on its first call, so this is where
+	// a fresh child gets its baseline (see `seedRenewalState` for why it is safe
+	// to run unconditionally on later persists too).
+	seedRenewalState(child);
 	try {
 		const recorded = store.findChild(runId, name);
 		if (!recorded) {
@@ -3723,6 +4242,41 @@ function findControlAgent(
 	);
 }
 
+/**
+ * #270: resolve a child from another store when this one has no record.
+ *
+ * Only reached on a miss, so the common case (child launched here) costs
+ * nothing. The returned shape matches {@link findChild} so callers do not care
+ * which store answered — except that `runDir` now belongs to the owning store,
+ * which is why the caller re-derives its orchestrator run directory from it.
+ */
+function findChildAcrossStores(input: {
+	name: string;
+	cwd: string;
+	callerCwd?: string | undefined;
+	ownRoot: string;
+}): {
+	runId: string;
+	run: ReturnType<RunStore["listRuns"]>[number];
+	child: NonNullable<ReturnType<RunStore["findChild"]>>;
+} | null {
+	const { found } = resolveChildAcrossStores({
+		name: input.name,
+		cwd: input.cwd,
+		callerCwd: input.callerCwd,
+		roots: candidateStoreRoots({ cwd: input.cwd, callerCwd: input.callerCwd }).filter(
+			(candidate) => path.resolve(candidate.rootDir) !== path.resolve(input.ownRoot),
+		),
+	});
+	if (!found) return null;
+	// Read the owning store again for the full record: `resolveChildAcrossStores`
+	// only reports where the name was seen.
+	const runs = new RunStore({ rootDir: found.storeRoot }).listRuns();
+	const picked = pickChildByName(runs, input.name);
+	if (!picked) return null;
+	return { runId: picked.run.runId, run: picked.run, child: picked.child };
+}
+
 function findChild(
 	runs: ReturnType<RunStore["listRuns"]>,
 	name: string,