@ferris1225/pi-subagents 4.3.0 → 4.3.2

package/src/dispatch.ts

@@ -24,7 +24,8 @@ import {
 	type RunView,
 	type RunWaitReason,
 } from "./monitor.ts";
-import type { SubagentRuntime } from "./runtime.ts";
+import { formatPhaseLeaseReceipt } from "./prompt.ts";
+import type { SubagentRuntime, SubagentThread } from "./runtime.ts";
 import { persistThreadCheckpoint } from "./thread-lifecycle.ts";
 import {
 	getProjectRoot,
@@ -60,7 +61,7 @@ const IsolationSchema = Type.Optional(
 const WaitSchema = Type.Optional(
 	Type.Boolean({
 		description:
-			"Block until every run started by this call settles, then return their results in-turn (each result still arrives as a completion message too). Only for one-shot (pi -p) sessions or a next step that needs these results within this turn.",
+			"Block until every run started by this call settles, then return each result exactly once in this tool response. If the tool call is aborted, undelivered results fall back to completion messages. Intended for one-shot (pi -p) sessions or an immediate dependent step.",
 	}),
 );
 
@@ -68,7 +69,7 @@ const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({
 		...NON_BLANK_TASK_OPTIONS,
-		description: "Self-contained task to delegate (the agent has no memory of this conversation)",
+		description: "Substantial self-contained phase worth a fresh paid context (the agent has no memory of this conversation)",
 	}),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	isolation: IsolationSchema,
@@ -77,9 +78,9 @@ const TaskItem = Type.Object({
 const SubagentParams = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (single mode)" })),
 	task: Type.Optional(
-		Type.String({ ...NON_BLANK_TASK_OPTIONS, description: "Self-contained task to delegate (single mode)" }),
+		Type.String({ ...NON_BLANK_TASK_OPTIONS, description: "Substantial self-contained phase worth a fresh paid context (single mode)" }),
 	),
-	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "Independently justified, disjoint phases for parallel execution" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 	isolation: IsolationSchema,
 	wait: WaitSchema,
@@ -136,9 +137,8 @@ function toolUsage(runtime: SubagentRuntime, runIds: number[]): { usage?: Usage
 }
 
 /** In-turn wait behind dispatch `wait: true` — the escape hatch for one-shot
- * `pi -p` parents that exit at end of turn: hold the call until every run it
- * started settles, then hand back their result blocks. Interactive sessions
- * never take this path; their results arrive as completion wake-ups. No
+ * `pi -p` parents that exit at end of turn or an immediate dependent step: hold
+ * the call until every run it started settles, then hand back result blocks. No
  * timer: a waiter resolves the moment its run's result registers (children
  * are bounded by the idle watchdog), an already-parked run answers
  * immediately with its resume handle, and the turn's abort signal remains the
@@ -327,11 +327,17 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		(mode: "single" | "parallel", background = false) =>
 		(results: SingleResult[]): SubagentDetails => ({ mode, results, background });
 
+	const phaseLeaseReceipt = (runIds: number[]): string =>
+		formatPhaseLeaseReceipt(
+			runIds
+				.map((runId) => runtime.threads.get(runId))
+				.filter((thread): thread is SubagentThread => thread !== undefined),
+		);
+
 	/** Pacing note appended to dispatch confirmations whenever runs are actually
 	 * waiting. Slot waits and repository-lane waits are stated separately with
 	 * the real capacity: a lane-serialized shared writer or a starting child
-	 * must never read as an exhausted pool, or the model stops dispatching while
-	 * slots are free. Empty when nothing is waiting. */
+	 * must never read as an exhausted pool. Empty when nothing is waiting. */
 	const queuePacingNote = (): string => {
 		const runs = monitor.getRuns();
 		const queuedWith = (reason: RunWaitReason): number =>
@@ -354,7 +360,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					(slotWaiting === 0 ? ` (${freeSlots} of ${capacity} slots free; parallel writers avoid the lane via worktree isolation)` : ""),
 			);
 		}
-		return ` Pacing: ${parts.join(" · ")}. Keep dispatching independent units.`;
+		return ` Pacing: ${parts.join(" · ")}.`;
 	};
 
 	const startBackground = createBackgroundDispatcher({
@@ -374,14 +380,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 	pi.registerTool({
 		name: "subagent",
 		label: "Subagent",
-		description: [
-			"Dispatch enabled agents as isolated leaf Pi child processes: single {agent, task} or parallel {tasks: [...]}. Dispatching never blocks your turn — runs proceed in the background and each completion resumes you automatically; never poll or restate delivered results.",
-			"Put every genuinely independent unit in one `tasks` array: there is no per-call cap, and runs beyond the machine's free process slots simply wait and start as slots free.",
-			"Parallel write-capable agents default to a detached Git worktree so writers run concurrently; explicit `shared` keeps the caller's checkout and serializes same-repository writers. Worktree setup failure never silently falls back to shared.",
-			"A configured child-model failure continues the retained session on the current main model.",
-		].join(" "),
-		promptSnippet:
-			"Dispatch isolated background agents for recon or implementation, and for cleanup, docs sync, or result merging only when that work exists; never blocks your turn, and completions wake you automatically.",
+		description: "Start paid leaf runs for broad reconnaissance or substantial self-contained work. Each active normalized task+cwd owns its phase; exact duplicates are rejected. Batch scopes must be independent. wait:true returns results in-turn; otherwise completions wake main. Parallel writers default to detached Git worktrees; isolation:'shared' serializes same-repository writes.",
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -451,17 +450,16 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			}
 
 			// Sub-agents run detached from the foreground turn: the editor stays
-			// available and completion messages later wake the main agent. The turn is
-			// NOT terminated here — the model can keep dispatching independent units
-			// or do its own work, and the background queue paces how many child
-			// processes actually run at once, so no per-call task cap is enforced.
+			// available for disjoint orchestration while the launch receipt leases
+			// each delegated phase. The queue paces child processes without changing
+			// phase ownership or requiring a per-call task cap.
 			if (params.tasks && params.tasks.length > 0) {
-				const results: SingleResult[] = [];
-				// Preserve caller order (and deterministic completion batching) while
-				// preparing each isolated filesystem before its queue entry can start.
-				for (const item of params.tasks) {
+				// Admission is synchronous and ordered; slow worktree preparation belongs
+				// to the bounded queue. Promise.all preserves caller result order while no
+				// item waits for a sibling's filesystem setup.
+				const results = await Promise.all(params.tasks.map((item) => {
 					const catalogAgent = agents.find((candidate) => candidate.name === item.agent);
-					results.push(await startBackground(
+					return startBackground(
 						item.agent,
 						item.task,
 						item.cwd,
@@ -472,13 +470,14 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							catalogAgent ? isWriteCapableAgent(catalogAgent) : undefined,
 							catalogAgent?.isolation,
 						),
-					));
-				}
+						{ deliveryRoute: params.wait ? "await" : "background" },
+					);
+				}));
 				const startedRuns = results.filter((result) => result.exitCode === -1);
 				const started = startedRuns.length;
-				const startedRefs = startedRuns.map((result) =>
-					result.runId === undefined ? result.agent : `#${result.runId} ${result.agent}`,
-				);
+				const startedIds = startedRuns
+					.map((result) => result.runId)
+					.filter((id): id is number => id !== undefined);
 				const failureLines = results.flatMap((result, index) => {
 					if (result.exitCode === -1) return [];
 					const reason = getResultOutput(result).trim() || "unknown startup failure";
@@ -489,21 +488,15 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				if (started === 0) {
 					// Pi marks custom-tool failures only when execute throws; returning an
 					// `isError` property is still a successful AgentToolResult.
-					throw new Error(`No background subagents were started.\n${failureLines.join("\n")}`);
+					throw new Error(`No subagents started.\n${failureLines.join("\n")}`);
 				}
 				if (params.wait) {
-					const startedIds = startedRuns
-						.map((result) => result.runId)
-						.filter((id): id is number => id !== undefined);
 					const blocks = await awaitRunResults(runtime, startedIds, signal, config.maxResultLines, ctx.cwd, makeProgress(makeDetails("parallel", true)(results)));
-					const text = [
-						`Started ${started} subagent${started === 1 ? "" : "s"} (${startedRefs.join(", ")}) and waited in-turn.`,
-						...(failureLines.length > 0
-							? [`${failureLines.length} task${failureLines.length === 1 ? "" : "s"} failed before launch:`, ...failureLines]
-							: []),
-						"",
-						blocks,
-					].join("\n");
+					if (signal?.aborted) runtime.fallbackAwaitDelivery(startedIds);
+					else runtime.completeAwaitDelivery(startedIds);
+					const text = failureLines.length > 0
+						? `${blocks}\n\nLaunch failures:\n${failureLines.join("\n")}`
+						: blocks;
 					return {
 						content: [{ type: "text", text }],
 						details: makeDetails("parallel", true)(results),
@@ -511,10 +504,8 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					};
 				}
 				const text = [
-					`Started ${started} background subagent${started === 1 ? "" : "s"}: ${startedRefs.join(", ")}. They run in the background and never block you — dispatch more independent units now or keep working; each result resumes you automatically when you are idle.`,
-					...(failureLines.length > 0
-						? [`${failureLines.length} task${failureLines.length === 1 ? "" : "s"} failed before launch:`, ...failureLines]
-						: []),
+					phaseLeaseReceipt(startedIds),
+					...(failureLines.length > 0 ? ["Launch failures:", ...failureLines] : []),
 				].join("\n") + queuePacingNote();
 				return {
 					content: [{ type: "text", text }],
@@ -534,21 +525,26 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					singleCatalogAgent ? isWriteCapableAgent(singleCatalogAgent) : undefined,
 					singleCatalogAgent?.isolation,
 				),
+				{ deliveryRoute: params.wait ? "await" : "background" },
 			);
 			if (result.exitCode !== -1) {
 				throw new Error(getResultOutput(result));
 			}
-			const runRef = result.runId === undefined ? result.agent : `#${result.runId} ${result.agent}`;
 			if (params.wait && result.runId !== undefined) {
 				const blocks = await awaitRunResults(runtime, [result.runId], signal, config.maxResultLines, ctx.cwd, makeProgress(makeDetails("single", true)([result])));
+				if (signal?.aborted) runtime.fallbackAwaitDelivery([result.runId]);
+				else runtime.completeAwaitDelivery([result.runId]);
 				return {
-					content: [{ type: "text", text: `Started ${runRef} and waited in-turn.\n\n${blocks}` }],
+					content: [{ type: "text", text: blocks }],
 					details: makeDetails("single", true)([result]),
 					...toolUsage(runtime, [result.runId]),
 				};
 			}
 			return {
-				content: [{ type: "text", text: `Started ${runRef} in the background. It never blocks you — dispatch more independent units now or keep working; its result resumes you automatically when you are idle.${queuePacingNote()}` }],
+				content: [{
+					type: "text",
+					text: phaseLeaseReceipt(result.runId === undefined ? [] : [result.runId]) + queuePacingNote(),
+				}],
 				details: makeDetails("single", true)([result]),
 			};
 

package/src/durable.ts

@@ -20,7 +20,7 @@ import { uptime } from "node:os";
 import { dirname, join } from "node:path";
 import type { UsageStats } from "./rpc-run.ts";
 import type { SubagentThread } from "./runtime.ts";
-import { getResultOutput, isFailedResult, getProjectRoot, PROJECT_ROOTS_DIR_NAME, type SingleResult } from "./spawn.ts";
+import { getResultOutput, isFailedResult, getProjectRoot, getSubagentsRoot, type SingleResult } from "./spawn.ts";
 import {
 	isPathInside,
 	restoreWorktreeIsolation,
@@ -34,7 +34,7 @@ export const THREADS_MANIFEST_FILE_NAME = "pi-subagents-threads.json";
 const THREADS_MANIFEST_VERSION = 1;
 
 /** Project directories whose newest file has not been touched for this long
- * are deleted wholesale on load, so per-project sessions/worktrees/results
+ * are deleted wholesale at session start, so per-project sessions/worktrees/results
  * can never accumulate forever. Parked threads' manifest references always
  * win over the age rule. */
 export const PROJECT_ROOT_MAX_AGE_MS = 3 * 24 * 60 * 60 * 1_000;
@@ -118,12 +118,6 @@ export function getThreadsManifestPath(configPath: string, cwd: string): string
 	return join(getProjectRoot(configPath, cwd), THREADS_MANIFEST_FILE_NAME);
 }
 
-/** Location of the pre-per-project global manifest; only read by the
- * one-time migration that folds it into the project roots. */
-function getLegacyManifestPath(configPath: string): string {
-	return join(dirname(configPath), THREADS_MANIFEST_FILE_NAME);
-}
-
 function normalizeUsage(value: unknown): UsageStats {
 	const raw = (value && typeof value === "object" ? value : {}) as Record<string, unknown>;
 	const num = (key: string): number => (typeof raw[key] === "number" && Number.isFinite(raw[key]) ? raw[key] : 0);
@@ -226,7 +220,7 @@ function projectManifestPaths(durableRoot: string): string[] {
  * sweeps that must see references from anywhere. */
 export async function readThreadRecords(configPath: string): Promise<ThreadRecord[]> {
 	const manifests = await Promise.all(
-		projectManifestPaths(join(dirname(configPath), PROJECT_ROOTS_DIR_NAME))
+		projectManifestPaths(getSubagentsRoot(configPath))
 			.map((path) => readManifestRecords(path)),
 	);
 	return manifests.flat();
@@ -365,12 +359,12 @@ async function discardRecordArtifacts(record: ThreadRecord): Promise<void> {
 }
 
 /** Drop records past their retention age along with their artifacts. Runs at
- * extension load; the fixed age honors the no-config-knobs policy. */
+ * session start; the fixed age honors the no-config-knobs policy. */
 export async function pruneThreadRecords(
 	configPath: string,
 	now = Date.now(),
 ): Promise<void> {
-	const durableRoot = join(dirname(configPath), PROJECT_ROOTS_DIR_NAME);
+	const durableRoot = getSubagentsRoot(configPath);
 	for (const path of projectManifestPaths(durableRoot)) {
 		await withFileMutationQueue(path, async () => {
 			const records = await readManifestRecords(path);
@@ -390,47 +384,6 @@ export async function pruneThreadRecords(
 	}
 }
 
-/** One-time move of the pre-per-project global manifest beside the config into
- * the project roots its records belong to, so an upgrade keeps parked work
- * resumable and pi home is left without a manifest. Existing project records
- * win over legacy ones; the legacy file is removed only after every group
- * landed, and an unreadable file stays put for the next boot. */
-export async function migrateLegacyThreadsManifest(configPath: string): Promise<void> {
-	const legacyPath = getLegacyManifestPath(configPath);
-	let records: ThreadRecord[];
-	try {
-		const parsed = JSON.parse(await readFile(legacyPath, "utf8")) as { records?: unknown };
-		if (!Array.isArray(parsed.records)) return;
-		records = parsed.records.flatMap((record) => {
-			const normalized = normalizeRecord(record);
-			return normalized ? [normalized] : [];
-		});
-	} catch {
-		return;
-	}
-	const groups = new Map<string, ThreadRecord[]>();
-	for (const record of records) {
-		const path = getThreadsManifestPath(configPath, record.cwd);
-		const group = groups.get(path);
-		if (group) group.push(record);
-		else groups.set(path, [record]);
-	}
-	let migrated = true;
-	for (const [path, group] of groups) {
-		await withFileMutationQueue(path, async () => {
-			const existing = await readManifestRecords(path);
-			const merged = [...existing];
-			for (const record of group) {
-				if (!merged.some((candidate) => candidate.runId === record.runId)) merged.push(record);
-			}
-			await writeManifest(path, merged);
-		}).catch(() => {
-			migrated = false;
-		});
-	}
-	if (migrated) await rm(legacyPath, { force: true }).catch(() => undefined);
-}
-
 /** Paths a manifest still references; used by the state-root sweep so
  * freshly created-but-unrecorded directories are never touched. */
 export function referencedDurablePaths(records: readonly ThreadRecord[]): Set<string> {
@@ -490,7 +443,7 @@ export async function pruneStaleProjectRoots(configPath: string, options: { now?
 	const now = options.now ?? Date.now();
 	const records = await readThreadRecords(configPath).catch(() => [] as ThreadRecord[]);
 	const referenced = referencedDurablePaths(records);
-	const root = join(dirname(configPath), PROJECT_ROOTS_DIR_NAME);
+	const root = getSubagentsRoot(configPath);
 	let projects: Dirent[];
 	try {
 		projects = readdirSync(root, { withFileTypes: true });

package/src/index.ts

@@ -78,24 +78,21 @@ export default function (pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.on("session_start", async () => {
+		await bootstrapDurableState(runtime);
+	});
 	registerAnnouncements(pi, runtime);
 
-	// Durable bootstrap: restore parked threads from the manifest so a reload or
-	// restart keeps status and resume working, then age out old records and sweep
-	// leaked temp/state directories. Registration never blocks on it and every
-	// stage is best-effort; the restore pass is published as runtime.durableRestore
-	// so the tools and the session-start notice wait for it instead of racing it.
-	void bootstrapDurableState(runtime);
-
-	// Proactive dispatch: inject the delegation directive into the parent system prompt.
+	// Inject the routing contract plus bounded live phase leases into each parent turn.
 	pi.on("before_agent_start", async (event, ctx) => {
+		await runtime.durableRestore;
 		const config = await loadConfig(configPath);
 		const { agents } = discoverAgents(ctx.cwd, {
 			scope: config.agentScope,
 			enabledNames: config.enabledAgents,
 			projectTrusted: ctx.isProjectTrusted?.() === true,
 		});
-		const directive = buildDelegationDirective(agents);
+		const directive = buildDelegationDirective(agents, runtime.threads.values());
 		if (!directive) return undefined;
 		return { systemPrompt: `${event.systemPrompt}\n${directive}` };
 	});

package/src/prompt.ts

@@ -1,76 +1,131 @@
 /**
  * Builds the delegation directive injected into the parent model's
  * system prompt via `before_agent_start`. It is paid on every turn, so it
- * stays a lean routing contract — when a child context pays for itself,
- * how wide to fan out, and how results come back. Tool metadata stays
- * intentionally minimal so role/process guidance is not paid for twice.
+ * stays a lean routing, phase-ownership, and verification contract.
+ * Detailed role guidance remains in each child's own prompt.
  */
 
+import { resolve } from "node:path";
 import type { AgentConfig } from "./agents.ts";
 import { formatCatalogEntry } from "./agents.ts";
 
+export interface PhaseLeaseSource {
+	id: number;
+	agentName: string;
+	task: string;
+	cwd: string;
+	state: "queued" | "resuming" | "running" | "interrupting" | "parked" | "completed" | "failed" | "stopped";
+	lifecycleOperation?: "park" | "resume" | "stop" | "settle";
+}
+
+const ACTIVE_LEASE_STATES = new Set<PhaseLeaseSource["state"]>([
+	"queued",
+	"resuming",
+	"running",
+	"interrupting",
+	"parked",
+]);
+const MAX_ACTIVE_LEASES = 2;
+const MAX_LEASE_TASK_LENGTH = 56;
+
 function bullets(lines: readonly string[]): string {
 	return lines.map((line) => `- ${line}`).join("\n");
 }
 
+function phaseForAgent(agentName: string): string {
+	if (agentName === "scout") return "broad reconnaissance";
+	if (agentName === "artisan") return "implementation and targeted checks";
+	if (agentName === "steward") return "pre-commit cleanup and cross-cutting docs";
+	return "delegated scope";
+}
+
+function isActivePhaseLease(source: PhaseLeaseSource): boolean {
+	return source.lifecycleOperation === "settle" || ACTIVE_LEASE_STATES.has(source.state);
+}
+
+function normalizedTask(task: string): string {
+	return task.replace(/\s+/gu, " ").trim();
+}
+
+function normalizedCwd(cwd: string): string {
+	const resolved = resolve(cwd);
+	return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+export function findDuplicateActiveDispatch(
+	sources: Iterable<PhaseLeaseSource>,
+	task: string,
+	cwd: string,
+): PhaseLeaseSource | undefined {
+	const taskKey = normalizedTask(task);
+	const cwdKey = normalizedCwd(cwd);
+	return [...sources].find((source) =>
+		isActivePhaseLease(source) &&
+		normalizedTask(source.task) === taskKey &&
+		normalizedCwd(source.cwd) === cwdKey,
+	);
+}
+
+function summarizeLeaseTask(task: string): string {
+	const oneLine = normalizedTask(task);
+	const characters = [...oneLine];
+	return characters.length <= MAX_LEASE_TASK_LENGTH
+		? oneLine
+		: `${characters.slice(0, MAX_LEASE_TASK_LENGTH - 1).join("")}…`;
+}
+
+function formatActivePhaseLeases(sources: Iterable<PhaseLeaseSource>): string {
+	const active = [...sources].filter(isActivePhaseLease);
+	if (active.length === 0) return "";
+	const lines = active.slice(0, MAX_ACTIVE_LEASES).map((source) => {
+		const state = source.lifecycleOperation === "settle" ? "settling" : source.state;
+		return `- #${source.id} ${phaseForAgent(source.agentName)} (${source.agentName}, ${state}): ${summarizeLeaseTask(source.task)}`;
+	});
+	if (active.length > MAX_ACTIVE_LEASES) {
+		lines.push(`- … ${active.length - MAX_ACTIVE_LEASES} more active lease${active.length - MAX_ACTIVE_LEASES === 1 ? "" : "s"} omitted`);
+	}
+	return lines.join("\n");
+}
+
+export function formatPhaseLeaseReceipt(sources: Iterable<PhaseLeaseSource>): string {
+	const leases = formatActivePhaseLeases(sources);
+	if (!leases) return "";
+	return `Active phase lease:\n${leases}\nDo not duplicate it; continue only disjoint work.`;
+}
+
 export function buildDelegationDirective(
 	agents: AgentConfig[],
+	activeLeaseSources: Iterable<PhaseLeaseSource> = [],
 ): string {
-	if (agents.length === 0) return "";
+	const activeLeases = formatActivePhaseLeases(activeLeaseSources);
+	if (agents.length === 0 && !activeLeases) return "";
 
-	const catalog = agents.map(formatCatalogEntry).join("\n");
+	const catalog = agents.length > 0 ? agents.map(formatCatalogEntry).join("\n") : "- (none enabled)";
 	const hasScout = agents.some((agent) => agent.name === "scout");
 	const hasArtisan = agents.some((agent) => agent.name === "artisan");
 	const hasSteward = agents.some((agent) => agent.name === "steward");
 
 	const dispatchRules = [
-		`Delegate aggressively: child contexts are cheap, yours is scarce. A unit is delegable when it can proceed independently and return a compact result${hasArtisan ? "; when the unit is a code change, default it to \`artisan\`" : ""}.`,
-		"Keep inline what fails either test — a lookup, a single focused edit, an answer already in context, or a single artifact you must absorb yourself (one issue, one spec), where delegation saves search, not that read. Cluster related questions into one brief instead of firing many small dispatches; a child loses context between runs.",
-		...(hasScout
-			? [
-				"`scout`: split a broad question into parallel scouts with disjoint scopes. Its findings are leads, never proof — re-read the cited line ranges before acting on them (a child you brief re-verifies).",
-			]
-			: []),
-		...(hasArtisan
-			? [
-				"`artisan`: brief it as the edit authorization for implement, fix, refactor, or test. Not cleanup, docs sync, or merging results.",
-			]
-			: []),
-		...(hasSteward
-			? [
-				"`steward`: dispatch only when the work is cleanup, documentation sync, or merging named result artifacts — do not invent a tidy pass. For cleanup, name the scope (uncommitted diff, Git range, directory). After a wide fan-out, pass the result-artifact paths to one steward and read its brief instead of every result yourself.",
-			]
-			: []),
-		"A discovered defect is not a change: re-read the current code and confirm it is not a false positive before you edit or brief a writer to edit.",
-		"Parallelize by default: map the todo list onto ONE `tasks` dispatch. One child owns one deliverable and its files; only genuinely dependent work waits for its prerequisite.",
-		"Brief each child completely — goal, exact paths, constraints, expected output; it has no conversation memory and cannot delegate. Resume parked threads with `subagent_control resume`.",
-	];
-
-	const handoffRules = [
-		"Dispatch never blocks or ends your turn — keep working, but only on what the children are not: never re-read a scope you just delegated. Each completion resumes you automatically; never sleep or poll for it.",
-		"Results are already shown; add only your conclusion or next action, never a restatement.",
-		"Never declare the overall task done while a dispatched run is still active.",
-	];
-
-	const verificationRules = [
-		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures, and inspect the actual diff before reporting completion.",
-		"Commit or push only when explicitly requested and applicable checks pass.",
+		"Main owns routing, architecture, integration, the final gate, and release. Each child starts a paid context; delegate only when saved main-context work exceeds handoff cost.",
+		"Keep atomic lookups, focused edits, known answers, and context-heavy work in main. Cluster related reconnaissance into one scout brief.",
+		...(hasScout ? ["`scout`: broad or unfamiliar reconnaissance; return compact findings and decisive citations."] : []),
+		...(hasArtisan ? ["`artisan`: substantial self-contained implementation, including affected tests, docs, comments, and targeted checks."] : []),
+		...(hasSteward ? ["`steward`: one pre-commit cleanup or cross-cutting docs/comments pass for a completed broad or multi-writer change; keep small diff hygiene inline."] : []),
+		"One owner per phase; dependent phases wait. A launch leases that phase: main may inspect its result, citations, diff, and check output but must not rerun it.",
+		"Parallelize only independently justified, disjoint scopes. Brief goal, scope, constraints, and expected output; resume retained work with `subagent_control`.",
+		"Completions deliver automatically. Never poll, restate a result, or finish while a run is active.",
+		"Inspect the integrated diff and actual check output. Never report an unrun check as passed.",
 	];
 
 	return `
-## Sub-agent delegation (pi-subagents)
-
-\`subagent\` runs isolated leaf Pi child processes in the background.
+## Sub-agent delegation
 
 Agents:
 ${catalog}
 
-Dispatch:
-${bullets(dispatchRules)}
-
-Result handoff:
-${bullets(handoffRules)}
+Rules:
+${bullets(dispatchRules)}${activeLeases ? `
 
-Verification:
-${bullets(verificationRules)}`;
+Active phase leases:
+${activeLeases}` : ""}`;
 }

package/src/recovery.ts

@@ -5,6 +5,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
+import { getSubagentsRoot } from "./spawn.ts";
 import { removeWorktreeGroup, worktreeGroupDir, type WorktreeFinalization } from "./worktree.ts";
 
 export const RECOVERY_MANIFEST_FILE_NAME = "pi-subagents-recovery.json";
@@ -27,7 +28,7 @@ interface RecoveryManifest {
 }
 
 export function getRecoveryManifestPath(configPath: string): string {
-	return join(dirname(configPath), RECOVERY_MANIFEST_FILE_NAME);
+	return join(getSubagentsRoot(configPath), RECOVERY_MANIFEST_FILE_NAME);
 }
 
 function normalizeRecord(value: unknown): RecoveryRecord | undefined {
@@ -46,21 +47,45 @@ function normalizeRecord(value: unknown): RecoveryRecord | undefined {
 	};
 }
 
-export async function readRecoveryRecords(configPath: string): Promise<RecoveryRecord[]> {
+interface RecoveryManifestRead {
+	valid: boolean;
+	records: RecoveryRecord[];
+}
+
+async function readManifest(path: string): Promise<RecoveryManifestRead> {
 	try {
-		const parsed = JSON.parse(await readFile(getRecoveryManifestPath(configPath), "utf8")) as {
-			records?: unknown;
+		const parsed = JSON.parse(await readFile(path, "utf8")) as { records?: unknown };
+		if (!Array.isArray(parsed.records)) return { valid: false, records: [] };
+		return {
+			valid: true,
+			records: parsed.records.flatMap((record) => {
+				const normalized = normalizeRecord(record);
+				return normalized ? [normalized] : [];
+			}),
 		};
-		if (!Array.isArray(parsed.records)) return [];
-		return parsed.records.flatMap((record) => {
-			const normalized = normalizeRecord(record);
-			return normalized ? [normalized] : [];
-		});
 	} catch {
-		return [];
+		return { valid: false, records: [] };
 	}
 }
 
+export async function readRecoveryRecords(configPath: string): Promise<RecoveryRecord[]> {
+	return (await readManifest(getRecoveryManifestPath(configPath))).records;
+}
+
+/** Move the previous agent-root manifest into the internal-state root without
+ * dropping retained artifact pointers. Invalid legacy files stay untouched. */
+export async function relocateRecoveryManifest(configPath: string): Promise<void> {
+	const legacyPath = join(dirname(configPath), RECOVERY_MANIFEST_FILE_NAME);
+	const currentPath = getRecoveryManifestPath(configPath);
+	if (legacyPath === currentPath || !existsSync(legacyPath)) return;
+	await withFileMutationQueue(legacyPath, async () => {
+		const legacy = await readManifest(legacyPath);
+		if (!legacy.valid) return;
+		await persistRecoveryRecords(configPath, legacy.records);
+		await rm(legacyPath, { force: true });
+	});
+}
+
 function recoveryKey(record: RecoveryRecord): string {
 	return `${record.runId}\0${record.worktreePath ?? ""}\0${record.patchPath ?? ""}\0${record.error ?? ""}`;
 }