@ferris1225/pi-subagents 4.1.8 → 4.1.11

package/src/durable.ts

@@ -0,0 +1,336 @@
+/**
+ * Durable thread state: a manifest next to the config that lets parked and
+ * settled sub-agent threads survive pi reloads and restarts, plus the durable
+ * state root that keeps their retained sessions and isolated worktrees out of
+ * the OS temp directory.
+ *
+ * Records are small path/state snapshots, never full transcripts; the retained
+ * Pi session files and worktrees they point at remain the actual context.
+ * Writes are atomic (tmp+rename) and serialized through the same
+ * withFileMutationQueue as the recovery manifest.
+ */
+
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { UsageStats } from "./rpc-run.ts";
+import type { SubagentThread } from "./runtime.ts";
+import { getResultOutput, isFailedResult, type SingleResult } from "./spawn.ts";
+import {
+	restoreWorktreeIsolation,
+	type IsolationMode,
+	normalizeWorktreeSnapshot,
+	worktreeSnapshot,
+	type WorktreeSnapshot,
+} from "./worktree.ts";
+
+export const THREADS_MANIFEST_FILE_NAME = "pi-subagents-threads.json";
+const THREADS_MANIFEST_VERSION = 1;
+export const STATE_DIR_NAME = "pi-subagents-state";
+
+/** Fixed retention: settled results stop being resumable after a week,
+ * parked work (which may hold unintegrated changes) after a month. */
+export const SETTLED_RECORD_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+export const PARKED_RECORD_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
+
+/** Result excerpts are for status display after restore, not full transcripts. */
+const RESULT_SUMMARY_MAX_CHARS = 4_000;
+
+export interface ThreadResultSummary {
+	agent: string;
+	task: string;
+	exitCode: number;
+	failed: boolean;
+	stopReason?: string;
+	usage: UsageStats;
+	model?: string;
+	thinking?: string;
+	output: string;
+}
+
+export interface ThreadRecord {
+	runId: number;
+	createdAt: number;
+	updatedAt: number;
+	generation: number;
+	agentName: string;
+	task: string;
+	cwd: string;
+	executionCwd: string;
+	thinkingLevel?: string;
+	isolation: IsolationMode;
+	state: "parked" | "completed" | "failed";
+	elapsedMs: number;
+	sessionId?: string;
+	sessionDir?: string;
+	worktree?: WorktreeSnapshot;
+	childPids: number[];
+	resultSummary?: ThreadResultSummary;
+}
+
+interface ThreadsManifest {
+	version: number;
+	records: ThreadRecord[];
+}
+
+export function getStateRoot(configPath: string): string {
+	return join(dirname(configPath), STATE_DIR_NAME);
+}
+
+export function getThreadsManifestPath(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);
+	return {
+		input: num("input"),
+		output: num("output"),
+		cacheRead: num("cacheRead"),
+		cacheWrite: num("cacheWrite"),
+		cost: num("cost"),
+		contextTokens: num("contextTokens"),
+		turns: num("turns"),
+	};
+}
+
+function normalizeResultSummary(value: unknown): ThreadResultSummary | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	if (typeof raw.agent !== "string" || !raw.agent) return undefined;
+	if (typeof raw.output !== "string") return undefined;
+	return {
+		agent: raw.agent,
+		task: typeof raw.task === "string" ? raw.task : raw.agent,
+		exitCode: typeof raw.exitCode === "number" ? raw.exitCode : 0,
+		failed: raw.failed === true,
+		...(typeof raw.stopReason === "string" && raw.stopReason ? { stopReason: raw.stopReason } : {}),
+		usage: normalizeUsage(raw.usage),
+		...(typeof raw.model === "string" && raw.model ? { model: raw.model } : {}),
+		...(typeof raw.thinking === "string" && raw.thinking ? { thinking: raw.thinking } : {}),
+		output: raw.output,
+	};
+}
+
+function normalizeRecord(value: unknown): ThreadRecord | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	if (typeof raw.runId !== "number" || !Number.isInteger(raw.runId) || raw.runId < 1) return undefined;
+	if (typeof raw.createdAt !== "number" || !Number.isFinite(raw.createdAt)) return undefined;
+	if (typeof raw.updatedAt !== "number" || !Number.isFinite(raw.updatedAt)) return undefined;
+	if (typeof raw.agentName !== "string" || !raw.agentName) return undefined;
+	if (typeof raw.task !== "string" || !raw.task) return undefined;
+	if (typeof raw.cwd !== "string" || !raw.cwd) return undefined;
+	if (raw.isolation !== "shared" && raw.isolation !== "worktree") return undefined;
+	if (raw.state !== "parked" && raw.state !== "completed" && raw.state !== "failed") return undefined;
+	const worktree = raw.worktree === undefined ? undefined : normalizeWorktreeSnapshot(raw.worktree);
+	if (worktree === null) return undefined;
+	return {
+		runId: raw.runId,
+		createdAt: raw.createdAt,
+		updatedAt: raw.updatedAt,
+		generation: typeof raw.generation === "number" && Number.isInteger(raw.generation) && raw.generation >= 0 ? raw.generation : 0,
+		agentName: raw.agentName,
+		task: raw.task,
+		cwd: raw.cwd,
+		executionCwd: typeof raw.executionCwd === "string" && raw.executionCwd ? raw.executionCwd : raw.cwd,
+		...(typeof raw.thinkingLevel === "string" && raw.thinkingLevel ? { thinkingLevel: raw.thinkingLevel } : {}),
+		isolation: raw.isolation,
+		state: raw.state,
+		elapsedMs: typeof raw.elapsedMs === "number" && Number.isFinite(raw.elapsedMs) ? Math.max(0, raw.elapsedMs) : 0,
+		...(typeof raw.sessionId === "string" && raw.sessionId ? { sessionId: raw.sessionId } : {}),
+		...(typeof raw.sessionDir === "string" && raw.sessionDir ? { sessionDir: raw.sessionDir } : {}),
+		...(worktree ? { worktree } : {}),
+		childPids: Array.isArray(raw.childPids)
+			? raw.childPids.filter((pid): pid is number => typeof pid === "number" && Number.isInteger(pid) && pid > 0)
+			: [],
+		...(raw.resultSummary === undefined ? {} : { resultSummary: normalizeResultSummary(raw.resultSummary) }),
+	};
+}
+
+export async function readThreadRecords(configPath: string): Promise<ThreadRecord[]> {
+	try {
+		const parsed = JSON.parse(await readFile(getThreadsManifestPath(configPath), "utf8")) as {
+			records?: unknown;
+		};
+		if (!Array.isArray(parsed.records)) return [];
+		return parsed.records.flatMap((record) => {
+			const normalized = normalizeRecord(record);
+			return normalized ? [normalized] : [];
+		});
+	} catch {
+		return [];
+	}
+}
+
+async function writeManifest(configPath: string, records: readonly ThreadRecord[]): Promise<void> {
+	const path = getThreadsManifestPath(configPath);
+	if (records.length === 0) {
+		await rm(path, { force: true });
+		return;
+	}
+	await mkdir(dirname(path), { recursive: true });
+	const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		const manifest: ThreadsManifest = {
+			version: THREADS_MANIFEST_VERSION,
+			records: [...records],
+		};
+		await writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+		await rename(temporaryPath, path);
+	} finally {
+		await rm(temporaryPath, { force: true }).catch(() => undefined);
+	}
+}
+
+export async function upsertThreadRecord(configPath: string, record: ThreadRecord): Promise<void> {
+	const path = getThreadsManifestPath(configPath);
+	await withFileMutationQueue(path, async () => {
+		const records = await readThreadRecords(configPath);
+		const index = records.findIndex((candidate) => candidate.runId === record.runId);
+		const merged: ThreadRecord = index === -1
+			? record
+			: { ...record, createdAt: records[index]!.createdAt };
+		if (index === -1) records.push(merged);
+		else records[index] = merged;
+		await writeManifest(configPath, records);
+	});
+}
+
+export async function removeThreadRecord(configPath: string, runId: number): Promise<void> {
+	const path = getThreadsManifestPath(configPath);
+	await withFileMutationQueue(path, async () => {
+		const records = await readThreadRecords(configPath);
+		const next = records.filter((record) => record.runId !== runId);
+		if (next.length === records.length) return;
+		await writeManifest(configPath, next);
+	});
+}
+
+function truncateSummary(text: string): string {
+	if (text.length <= RESULT_SUMMARY_MAX_CHARS) return text;
+	return `${text.slice(0, RESULT_SUMMARY_MAX_CHARS - 1)}…`;
+}
+
+function summarizeResult(result: SingleResult): ThreadResultSummary | undefined {
+	if (!result) return undefined;
+	return {
+		agent: result.agent,
+		task: result.task,
+		exitCode: result.exitCode,
+		failed: isFailedResult(result),
+		...(result.stopReason ? { stopReason: result.stopReason } : {}),
+		usage: result.usage,
+		...(result.model ? { model: result.model } : {}),
+		...(result.thinking ? { thinking: result.thinking } : {}),
+		output: truncateSummary(getResultOutput(result)),
+	};
+}
+
+/** Project a live thread into its durable record. Only handles whose
+ * filesystem is still meaningful are persisted; finalized-and-removed
+ * worktrees keep just their checkpoint commit for continuation resumes. */
+export function threadRecordFromThread(
+	thread: SubagentThread,
+	state: "parked" | "completed" | "failed",
+	previous?: ThreadRecord,
+	now = Date.now(),
+): ThreadRecord {
+	const worktree = thread.worktree ? worktreeSnapshot(thread.worktree) : undefined;
+	return {
+		runId: thread.id,
+		createdAt: previous?.createdAt ?? now,
+		updatedAt: now,
+		generation: thread.generation,
+		agentName: thread.agentName,
+		task: thread.task,
+		cwd: thread.cwd,
+		executionCwd: thread.executionCwd,
+		...(thread.thinkingLevel ? { thinkingLevel: thread.thinkingLevel } : {}),
+		isolation: thread.isolation,
+		state,
+		elapsedMs: thread.elapsedMs,
+		...(thread.sessionId && thread.sessionDir ? { sessionId: thread.sessionId, sessionDir: thread.sessionDir } : {}),
+		...(worktree ? { worktree } : {}),
+		childPids: thread.control?.getChildPids?.() ?? [],
+		...(thread.lastResult ? { resultSummary: summarizeResult(thread.lastResult) } : {}),
+	};
+}
+
+/** Rebuild a displayable in-turn result from a persisted summary. The retained
+ * session holds the real context; this only lets subagent_wait/status show
+ * what the previous session's generation concluded. */
+export function restoredResultFromSummary(record: ThreadRecord): SingleResult | undefined {
+	const summary = record.resultSummary;
+	if (!summary) return undefined;
+	return {
+		agent: summary.agent,
+		task: summary.task,
+		exitCode: summary.exitCode,
+		messages: summary.output
+			? [{
+				role: "assistant",
+				content: [{ type: "text", text: summary.output }],
+				stopReason: "stop",
+			} as SingleResult["messages"][number]]
+			: [],
+		stderr: "",
+		usage: summary.usage,
+		isolation: record.isolation,
+		...(summary.model ? { model: summary.model } : {}),
+		...(summary.thinking ? { thinking: summary.thinking } : {}),
+		...(summary.stopReason ? { stopReason: summary.stopReason } : {}),
+		...(record.sessionId && record.sessionDir ? { sessionId: record.sessionId, sessionDir: record.sessionDir } : {}),
+	};
+}
+
+async function discardRecordArtifacts(record: ThreadRecord): Promise<void> {
+	if (record.sessionDir) {
+		await rm(record.sessionDir, { recursive: true, force: true }).catch(() => undefined);
+	}
+	if (record.worktree && (record.worktree.state === "active" || record.worktree.state === "retained")) {
+		const worktree = await restoreWorktreeIsolation(record.worktree).catch(() => undefined);
+		await worktree?.discard().catch(() => undefined);
+	}
+}
+
+/** Drop records past their retention age along with their artifacts. Runs at
+ * extension load; the fixed ages honor the no-config-knobs policy. */
+export async function pruneThreadRecords(
+	configPath: string,
+	now = Date.now(),
+): Promise<void> {
+	const path = getThreadsManifestPath(configPath);
+	await withFileMutationQueue(path, async () => {
+		const records = await readThreadRecords(configPath);
+		if (records.length === 0) return;
+		let changed = false;
+		const kept: ThreadRecord[] = [];
+		for (const record of records) {
+			const maxAge = record.state === "parked" ? PARKED_RECORD_MAX_AGE_MS : SETTLED_RECORD_MAX_AGE_MS;
+			if (now - record.updatedAt <= maxAge) {
+				kept.push(record);
+				continue;
+			}
+			changed = true;
+			await discardRecordArtifacts(record);
+		}
+		if (changed) await writeManifest(configPath, kept);
+	});
+}
+
+/** 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> {
+	const paths = new Set<string>();
+	for (const record of records) {
+		if (record.sessionDir) paths.add(record.sessionDir);
+		if (record.worktree) {
+			paths.add(record.worktree.tempDir);
+			if (existsSync(record.worktree.worktreePath)) paths.add(record.worktree.worktreePath);
+		}
+	}
+	return paths;
+}

package/src/format.ts

@@ -100,11 +100,6 @@ export function formatCompletionBlock(
 	const startupRetryNote = result.startupRetries
 		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
 		: "";
-	const relations = [
-		result.forkedFromRunId !== undefined ? `forked from #${result.forkedFromRunId}` : undefined,
-		(result.forkChildRunIds?.length ?? 0) > 0 ? `fork children ${result.forkChildRunIds!.map((id) => `#${id}`).join(", ")}` : undefined,
-	].filter((value): value is string => Boolean(value));
-	const relationNote = relations.length > 0 ? ` · ${relations.join(" · ")}` : "";
 	const runNote = result.runId !== undefined ? ` · run #${result.runId}` : "";
 	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${runNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, ""];
 	if (result.isolation === "worktree") {
@@ -118,13 +113,11 @@ export function formatCompletionBlock(
 							? "worktree · changes applied, but cleanup failed; recovery artifacts retained"
 							: "worktree · integration failed; recovery artifacts retained"
 						: "worktree · isolated";
-		lines.push(`Isolation: ${isolation}${relationNote}`);
+		lines.push(`Isolation: ${isolation}`);
 		if (result.integrationWorktreePath) lines.push(`Retained worktree: ${result.integrationWorktreePath}`);
 		if (result.integrationPatchPath) lines.push(`Retained patch: ${result.integrationPatchPath}`);
 		if (result.integrationError) lines.push(`Integration error: ${result.integrationError}`);
 		lines.push("");
-	} else if (relations.length > 0) {
-		lines.push(`Relation: ${relations.join(" · ")}`, "");
 	}
 	lines.push(text);
 	// Failed-tool diagnostics are deliberate opt-in via subagent_status: agents

package/src/index.ts

@@ -29,6 +29,7 @@ import { buildDelegationDirective } from "./prompt.ts";
 import { createRuntime } from "./runtime.ts";
 import { runSetup } from "./setup.ts";
 import { currentSubagentDepth } from "./spawn.ts";
+import { bootstrapDurableState } from "./thread-lifecycle.ts";
 import { registerLookupTools } from "./tools.ts";
 import { clearActiveRunsWidget } from "./widget.ts";
 
@@ -77,6 +78,12 @@ export default function (pi: ExtensionAPI): void {
 
 	registerAnnouncements(pi, runtime);
 
+	// Durable bootstrap: restore parked/settled 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. Fire-and-forget; every
+	// stage is best-effort and never blocks registration.
+	void bootstrapDurableState(runtime);
+
 	// Proactive dispatch: inject the delegation directive into the parent system prompt.
 	pi.on("before_agent_start", async (event, ctx) => {
 		const config = await loadConfig(configPath);

package/src/monitor.ts

@@ -18,8 +18,8 @@ import type { IsolationMode, WorktreeFinalizationStatus } from "./worktree.ts";
 // Types
 // ---------------------------------------------------------------------------
 
-export type RunStatus = "queued" | "running" | "steering" | "interrupting" | "parked" | "done" | "failed";
-export type ContinuationKind = "resume-retained" | "resume-appended" | "fork-retained" | "fork-appended" | "retarget";
+export type RunStatus = "queued" | "running" | "interrupting" | "parked" | "done" | "failed";
+export type ContinuationKind = "resume-retained" | "resume-appended";
 export type WorkflowStageStatus = "done" | "active" | "pending" | "changes" | "failed";
 
 /** Ephemeral projection of one real or currently planned managed stage. It is
@@ -31,7 +31,7 @@ export interface WorkflowStage {
 }
 
 export function isRunActiveStatus(status: RunStatus): boolean {
-	return status === "queued" || status === "running" || status === "steering" || status === "interrupting";
+	return status === "queued" || status === "running" || status === "interrupting";
 }
 
 /** Durable integration projection of a worktree-isolated run: pending before
@@ -57,8 +57,6 @@ export interface RunView {
 	/** Short worktree-group identity (mkdtemp suffix) shared by every run inside
 	 * one isolated worktree; changes when a continuation worktree is created. */
 	worktreeId?: string;
-	forkedFromRunId?: number;
-	forkChildRunIds?: number[];
 	status: RunStatus;
 	usage: UsageStats;
 	/** Concise current activity ("thinking", "read src/index.ts"); last writer wins. */
@@ -75,7 +73,7 @@ export interface RunView {
 	continuationKind?: ContinuationKind;
 	/** When set, this is an internal managed-workflow step. */
 	groupId?: string;
-	/** Human-readable role within a chain, e.g. "fix round 1" or "re-review round 1". */
+	/** Human-readable role within a workflow, e.g. "final review" or "final documentation sync". */
 	relationLabel?: string;
 	/** Stable owning run whose row represents the whole managed workflow. */
 	parentRunId?: number;
@@ -94,7 +92,6 @@ export interface RunChainMeta {
 	parentRunId?: number;
 	isolation?: IsolationMode;
 	worktreeId?: string;
-	forkedFromRunId?: number;
 	continuationKind?: ContinuationKind;
 }
 
@@ -325,13 +322,10 @@ export function formatElapsed(run: RunView, now: number = Date.now()): string {
 	return formatDuration(elapsedMilliseconds(run, now));
 }
 
-export function continuationLabel(kind: ContinuationKind | undefined, sourceRunId?: number): string | undefined {
+export function continuationLabel(kind: ContinuationKind | undefined): string | undefined {
 	switch (kind) {
 		case "resume-retained": return "resume: current objective";
 		case "resume-appended": return "resume: appended objective";
-		case "fork-retained": return `fork${sourceRunId === undefined ? "" : ` #${sourceRunId}`}: current objective`;
-		case "fork-appended": return `fork${sourceRunId === undefined ? "" : ` #${sourceRunId}`}: appended objective`;
-		case "retarget": return "retarget: replacement objective";
 		default: return undefined;
 	}
 }
@@ -452,6 +446,26 @@ export class MonitorStore {
 		return this.nextId++;
 	}
 
+	/** Keep newly allocated ids above a restored id so reload-restored threads
+	 * never collide with runs started in the current process. */
+	ensureNextIdAbove(id: number): void {
+		if (id >= this.nextId) this.nextId = id + 1;
+	}
+
+	/** Re-register a durable thread restored from a previous process. The row
+	 * keeps its stable id and historical elapsed time. */
+	restoreRun(view: Pick<RunView, "id" | "agent" | "task" | "status"> & Partial<RunView>): void {
+		if (this.find(view.id)) return;
+		this.runs.push({
+			label: runLabel(view.task),
+			usage: emptyUsage(),
+			elapsedMs: 0,
+			...view,
+		});
+		this.ensureNextIdAbove(view.id);
+		this.notify();
+	}
+
 	addRun(agent: string, task: string, model?: string, thinking?: string, meta?: RunChainMeta): number {
 		const id = this.reserveRunId();
 		this.runs.push({
@@ -468,7 +482,6 @@ export class MonitorStore {
 			...(meta?.relationLabel ? { relationLabel: meta.relationLabel } : {}),
 			...(meta?.parentRunId !== undefined ? { parentRunId: meta.parentRunId } : {}),
 			...(meta?.isolation ? { isolation: meta.isolation, integrationStatus: meta.isolation === "worktree" ? "pending" : undefined, ...(meta.worktreeId ? { worktreeId: meta.worktreeId } : {}) } : {}),
-			...(meta?.forkedFromRunId !== undefined ? { forkedFromRunId: meta.forkedFromRunId } : {}),
 			...(meta?.continuationKind ? { continuationKind: meta.continuationKind } : {}),
 		});
 		this.notify();
@@ -479,8 +492,8 @@ export class MonitorStore {
 		const run = this.find(id);
 		if (!run) return;
 		const previousStatus = run.status;
-		const wasExecuting = previousStatus === "running" || previousStatus === "steering" || previousStatus === "interrupting";
-		const isExecuting = status === "running" || status === "steering" || status === "interrupting";
+		const wasExecuting = previousStatus === "running" || previousStatus === "interrupting";
+		const isExecuting = status === "running" || status === "interrupting";
 		const now = Date.now();
 		run.status = status;
 		if (isExecuting && !wasExecuting) {
@@ -582,18 +595,8 @@ export class MonitorStore {
 		this.notify();
 	}
 
-	setForkRelation(sourceRunId: number, childRunId: number): void {
-		const source = this.find(sourceRunId);
-		if (source) {
-			source.forkChildRunIds ??= [];
-			if (!source.forkChildRunIds.includes(childRunId)) source.forkChildRunIds.push(childRunId);
-		}
-		const child = this.find(childRunId);
-		if (child) child.forkedFromRunId = sourceRunId;
-		this.notify();
-	}
 
-	/** Update the objective shown for a queued retarget or resumed generation. */
+	/** Update the objective shown for a resumed generation. */
 	setTask(id: number, task: string): void {
 		const run = this.find(id);
 		if (!run) return;
@@ -706,7 +709,7 @@ export class MonitorStore {
 	summarize(run: RunView): string {
 		const usage = formatUsageCompact(run.usage);
 		const parts = [run.managedWorkflow ? `${run.agent} workflow` : run.agent];
-		const continuation = continuationLabel(run.continuationKind, run.forkedFromRunId);
+		const continuation = continuationLabel(run.continuationKind);
 		if (continuation) parts.push(continuation);
 		if (run.relationLabel) parts.push(run.relationLabel);
 		if (!run.managedWorkflow && run.model) parts.push(run.model);
@@ -743,8 +746,6 @@ export function statusIcon(status: RunStatus, theme: Theme): string {
 	switch (status) {
 		case "running":
 			return theme.fg("accent", "●");
-		case "steering":
-			return theme.fg("accent", "◆");
 		case "interrupting":
 			return theme.fg("warning", "◐");
 		case "parked":
@@ -765,8 +766,6 @@ export function statusLabel(status: RunStatus): string {
 			return "ready";
 		case "running":
 			return "running";
-		case "steering":
-			return "steering";
 		case "interrupting":
 			return "interrupting";
 		case "parked":

package/src/prompt.ts

@@ -1,7 +1,9 @@
 /**
- * Builds the authoritative delegation directive injected into the parent model's
- * system prompt via `before_agent_start`. Tool metadata stays intentionally
- * minimal so role/process guidance is not paid for twice.
+ * 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.
  */
 
 import type { AgentConfig } from "./agents.ts";
@@ -22,13 +24,10 @@ export function buildDelegationDirective(
 	const hasCleaner = agents.some((agent) => agent.name === "cleaner");
 	const hasDocumenter = agents.some((agent) => agent.name === "documenter");
 	const hasReviewer = agents.some((agent) => agent.name === "reviewer");
-	const hasMultiple = agents.length > 1;
-	const autoFixEnabled = hasWorker;
 	const codeWriterNames = [
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
 	];
-	const reviewedWriterNames = [...codeWriterNames];
 	const namedWorktreeTargets = [
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
@@ -39,71 +38,54 @@ export function buildDelegationDirective(
 		: namedWorktreeTargets.length === 1
 			? `${namedWorktreeTargets[0]} or another`
 			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
-	const managedWriterWorkflowRule = reviewedWriterNames.length === 0
-		? undefined
-		: hasReviewer && hasDocumenter
-			? `Successful top-level ${reviewedWriterNames.join("/")} runs continue through the enabled reviewer gate. Only REVIEW_PASS can authorize documenter, which runs for DOCUMENTATION: NEEDED or a missing marker; the workflow delivers once. Never duplicate stages.`
-			: hasReviewer
-				? `Successful top-level ${reviewedWriterNames.join("/")} runs continue through the enabled reviewer gate and then deliver once; never duplicate the gate.`
-				: hasDocumenter
-					? `With reviewer disabled, successful top-level ${reviewedWriterNames.join("/")} runs use documenter as the conservative final fallback and then deliver once; never duplicate the fallback.`
-					: undefined;
 
 	const dispatchRules = [
-		"Keep small, known-target work in the main thread with direct tools: lookups and focused reads/edits do not justify a child context.",
+		"Route substantive work to sub-agents so your context stays lean for orchestration; inline only trivial work — a one-shot lookup, a single focused read/edit, or an answer already in context.",
 		...(hasExplorer
 			? [
-				"Use `explorer` proactively only for broad or cross-file reconnaissance: mapping unfamiliar code, tracing symbols/dependencies, or finding multi-file references. It is a lightweight retrieval index, never an automatic gate. Re-read load-bearing files before edits or high-risk decisions. Use a stronger model/specialist for dynamic, concurrent, migration, or security analysis.",
+				"Use `explorer` for any broad or multi-file search; it is a retrieval index, never a gate — re-read load-bearing files before acting on its findings.",
 			]
 			: []),
 		...(hasWorker
-			? ["Use `worker` for a self-contained implementation, fix, refactor, or test whose separate context pays for itself—not a small known-target edit."]
+			? ["Use `worker` for a self-contained implementation, fix, refactor, or test whose separate context pays for itself."]
 			: []),
 		...(hasCleaner
 			? [
-				`Use \`cleaner\` only as the separate evidence-first entry for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance; never substitute it for \`worker\`. It applies every safe proven in-scope cut without item-by-item approval. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+				`Use \`cleaner\` only for user-authorized cleanup or deduplication; it applies every safe proven cut without item-by-item approval, and never runs as a pre-commit gate or by PR count.`,
 			]
 			: []),
 		...(hasDocumenter
 			? [
-				`Use \`documenter\` directly only for explicit whole-codebase maintenance or standalone documentation/comment work; a top-level documenter delivers directly without an automatic reviewer.${codeWriterNames.length > 0 ? ` ${codeWriterNames.join("/")} must sync existing docs they directly affect; runtime runs documenter only after REVIEW_PASS with DOCUMENTATION: NEEDED or a missing marker, or as the reviewer-disabled fallback—never dispatch a duplicate.` : ""} It never changes runtime behavior, versions, or release state.`,
+				`Use \`documenter\` directly only for explicit standalone documentation work; a top-level documenter delivers without a gate.${codeWriterNames.length > 0 ? ` The runtime runs the final docs sync after REVIEW_PASS with DOCUMENTATION: NEEDED or a missing marker, or as the reviewer-disabled fallback; writers sync docs they directly affect — never dispatch a duplicate.` : ""}`,
 			]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for read-only assessments or a gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get one fresh read-only reviewer gate, independent of the writer.` : ""} Advisory output has no VERDICT and cannot authorize follow-up edits${hasDocumenter ? "; gates classify docs separately for the enabled documenter." : "."}`,
+				`Use \`reviewer\` for read-only assessments or gates.${codeWriterNames.length > 0 ? ` Successful ${codeWriterNames.join("/")} runs already get one fresh gate and then deliver once.` : ""} Advisory output has no VERDICT and cannot authorize edits; dispatch your own re-verification with \`advisory: true\`.`,
 			]
 			: []),
-		"Brief each child with the complete goal, exact paths, constraints, and expected output; it has no conversation memory.",
-		"Children are leaf processes without delegation tools; use `subagent_control fork` on a parked/settled thread for an independent continuation.",
-		...(hasMultiple
-			? [
-				"Dispatch independent work in one `tasks` array and let the resumed main agent start dependent work only after prerequisites finish.",
-			]
-			: []),
-		`Filesystem isolation: single tasks default to shared${hasWorker ? "; parallel worker tasks default to detached Git worktrees" : ""}${hasCleaner ? "; cleaner defaults to shared" : ""}${hasDocumenter ? "; documenter defaults to shared" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repository with committed HEAD. Read-only agents reject it, and setup/integration failure never falls back silently to shared.`,
+		"You own the fan-out breadth: every genuinely independent unit goes in one `tasks` array — there is no per-call cap, and extra tasks queue for the next free process slot. One child owns one coherent deliverable and its files; no two children share a file or re-answer the same question; dependent work starts only after its prerequisite delivers.",
+		"Brief each child with the complete goal, exact paths, constraints, and expected output; it has no conversation memory and cannot delegate. Continue a parked/settled thread with `subagent_control resume`.",
+		`Single tasks share the checkout${hasWorker ? "; parallel workers default to detached Git worktrees" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repo with committed HEAD; setup failure never silently falls back to shared.`,
 		"A configured child model/provider failure automatically continues the same retained session on the current main model; do not redispatch. Ordinary tool/task failures stay on the selected model.",
-		"Trust but verify: inspect actual changes/results before reporting completion.",
 	];
 
 	const handoffRules = [
-		"Dispatch ends this turn; results resume the main agent, even mid-turn. Never sleep, poll, or call `subagent_wait` to hold the turn.",
-		"Use `subagent_wait` with explicit `timeoutMs` only when the user asks to wait in-turn; its default lookup is non-blocking.",
-		"Results are already shown. Do not restate, paraphrase, or re-summarize them; add only your conclusion or next action.",
-		"A delivered result does not mean siblings are finished. Before declaring the overall task done, use `subagent_status` to confirm that no runs remain active.",
+		"Dispatch ends this turn; each completion resumes the main agent automatically — never sleep, poll, or call `subagent_wait` to hold the turn.",
+		"Results are already shown; add only your conclusion or next action, never a restatement.",
+		"Before declaring the overall task done, use `subagent_status` to confirm that no runs remain active.",
 	];
 
 	const verificationRules = [
-		"Never report an unrun check as passed; identify unavailable checks and pre-existing failures honestly.",
-		...(managedWriterWorkflowRule ? [managedWriterWorkflowRule] : []),
+		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures honestly, and inspect actual changes before reporting completion.",
 		...(hasReviewer
 			? [
 				...(hasDocumenter
 					? [
-						`A direct REVIEW_PASS with DOCUMENTATION: CLEAN delivers immediately; NEEDED or a missing marker runs one documentation sync. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps bounded worker/reviewer auto-fix, with docs considered only after its terminal REVIEW_PASS." : "cannot start fixes while worker is disabled."}`,
+						"A direct REVIEW_PASS with DOCUMENTATION: CLEAN delivers immediately; NEEDED or a missing marker runs one documentation sync.",
 					]
 					: []),
-				"Resolve every gate finding; do not bypass the auto-fix/re-review cap. A reviewer report without a standalone VERDICT is advisory and cannot trigger writes.",
+				"A REVIEW_FAIL — direct or from a managed gate — returns the findings to you: resolve them yourself, inline or via a worker you brief, without waiting for the user; the runtime never auto-fixes. Ask only for genuinely destructive or scope-changing fixes. Advisory reports cannot trigger writes.",
 				"Use multi-model cross-review only when explicitly requested or for genuinely high-risk security, unsafe/FFI, persistence-migration, or concurrency changes.",
 			]
 			: []),
@@ -113,9 +95,9 @@ export function buildDelegationDirective(
 	return `
 ## Sub-agent delegation (pi-subagents)
 
-The \`subagent\` tool starts isolated Pi child processes and context windows. Completions automatically resume the main agent.
+The \`subagent\` tool runs isolated leaf Pi child processes and context windows; each completion automatically resumes the main agent.
 
-Available agents:
+Agents:
 ${catalog}
 
 Dispatch: