@hcflabs/pi-subagent 0.0.0-stage → 27.10.7

package/extensions/isolated.ts

@@ -0,0 +1,945 @@
+import { basename } from "node:path";
+import type { JsonValue } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { capEphemeralSubagentOutput, utf8Prefix, type EphemeralSubagentExecutor } from "../dist/ephemeral.js";
+import {
+	createCanonicalGitRootResolver,
+	createExactJudgmentExecutor,
+} from "../dist/composition.js";
+import {
+	CheckedGitRuntime,
+	type DirectProcessRunner,
+} from "../dist/git-runtime.js";
+import { HerdrHostRuntime } from "../dist/herdr-runtime.js";
+import { inspectPruneCandidates, listHerdrPanes, removePruneCandidates, type PruneGuards, type PruneItem } from "../dist/prune.js";
+import { runProcess as directRunProcess } from "../dist/process.js";
+import { RoleLaunchRuntime, type LaunchRuntimeOptions } from "../dist/launch-runtime.js";
+import { IsolatedRunner, nextIntegrationAction, type ExecutePlan, type OperationContext, type RunResponse } from "../dist/runner.js";
+import {
+	IdOnlySchema,
+	ResumeRequestParameters,
+	StageRequestSchema,
+	IntegrationActionParameters,
+	parseIntegrationAction,
+	parseStageRequest,
+	parseIdOnly,
+	formatCheckCommand,
+	parseResumeRequest,
+	sameIdentity,
+	StatusOutputSchema,
+	type CheckBatchEvidence,
+	type ExecuteRequest,
+	type ExecutionPolicySnapshot,
+	type ModelClass,
+	type ReviewEvidence,
+	type RunState,
+	type WorktreeAllocationIntent,
+	type WorkspaceAllocationIntent,
+} from "../dist/schema.js";
+import { FileRunStore } from "../dist/store.js";
+import { workerOutputForMain } from "./result-transport.ts";
+import type { CleanupReport, IsolatedInventory, IsolatedRequest, PrunePlan } from "./subagent-command.ts";
+import type { DiscardPlan } from "../dist/discard.js";
+
+const LOOKUP_ROOT_TIMEOUT_MS = 5_000;
+const PUBLIC_EVIDENCE_MAX_BYTES = 512;
+/** Tool results return failed review verdicts in full up to this bound; follow-ups keep the short preview. */
+const PUBLIC_REVIEW_VERDICT_MAX_BYTES = 32 * 1024;
+const WORKSPACE_WIDGET_KEY = "pi-subagent-workspaces";
+const WIDGET_FIELD_MAX_CHARS = 32;
+const MAX_WORKSPACE_WIDGET_LINES = 6;
+
+export interface IsolatedExtensionComponents {
+	runner: IsolatedRunner;
+	resolveRoot: LaunchRuntimeOptions["resolveRoot"];
+}
+
+export type CreateIsolatedComponents = (options: {
+	pi: ExtensionAPI;
+	context(): ExtensionContext;
+	executor: EphemeralSubagentExecutor;
+	policy: ExecutionPolicySnapshot;
+	currentPolicy(): ExecutionPolicySnapshot;
+	onStateSaved(state: RunState): void;
+}) => IsolatedExtensionComponents;
+
+/** Construct the checked runtime while reusing the unified productive-assignment executor. */
+export const createIsolatedComponents: CreateIsolatedComponents = ({
+	pi, context, executor, policy, currentPolicy, onStateSaved,
+}) => {
+	const runProcess: DirectProcessRunner = async (command, args, options) => options.stdin === undefined
+		? await pi.exec(command, args, { cwd: options.cwd, signal: options.signal, timeout: options.timeoutMs })
+		: await directRunProcess(command, args, options);
+	const resolveRoot = createCanonicalGitRootResolver({ runProcess });
+	const git = new CheckedGitRuntime({ runProcess, executeReview: createExactJudgmentExecutor(executor) });
+	const executionBudget = () => ({
+		maxTurns: policy.maxTurns,
+		maxMs: null,
+		...(policy.maxTokens === undefined ? {} : { maxTokens: policy.maxTokens }),
+	});
+	const host = new HerdrHostRuntime({ inspectInFlightTaskCandidate: git.inspectInFlightTaskCandidate.bind(git), runProcess, executionBudget });
+	const coordinator = new RoleLaunchRuntime({
+		pi,
+		context,
+		resolveRoot,
+		preflightHost: async ({ root }, operation) => await host.preflightHost({ root }, operation),
+		inspectMainBase: async (input, operation) => await git.inspectMainBase(input, operation),
+	});
+	return {
+		resolveRoot,
+		runner: new IsolatedRunner(
+			coordinator,
+			host,
+			git,
+			new FileRunStore(undefined, onStateSaved),
+			executor,
+			policy,
+			currentPolicy,
+		),
+	};
+};
+
+function compactWidgetField(value: string): string {
+	const characters = [...value];
+	return characters.length <= WIDGET_FIELD_MAX_CHARS
+		? value
+		: `${characters.slice(0, WIDGET_FIELD_MAX_CHARS - 1).join("")}~`;
+}
+
+function workspaceBadge(role: string, modelClass: ModelClass): string {
+	const modelCode = { fast: "1", balanced: "2", frontier: "3", fav: "*" }[modelClass];
+	return `[${Array.from(role)[0]!.toUpperCase()}${modelCode}]`;
+}
+
+function workspaceStatus(status: RunState["tasks"][number]["status"]): string {
+	switch (status) {
+		case "ready_to_integrate": return "ready";
+		case "needs_attention": return "attention";
+		default: return status;
+	}
+}
+
+export function workspaceWidgetLines(state: RunState): string[] | undefined {
+	const rows = state.tasks.flatMap((taskState) => {
+		const task = state.request.tasks.find((candidate) => candidate.id === taskState.taskId);
+		if (!task) return [];
+		const status = workspaceStatus(taskState.status);
+		if (taskState.kind === "text") {
+			return taskState.status === "running" || taskState.status === "needs_attention"
+				? [`${status === "attention" ? "!" : "◌"} I ${workspaceBadge(task.role, task.modelClass)} ${compactWidgetField(task.id)} · ${status === "attention" ? `attention · ${compactWidgetField(taskState.failure ?? status)}` : status}`]
+				: [];
+		}
+		const attempt = taskState.attempts.at(-1);
+		const allocation = [...(attempt?.allocations ?? [])].reverse().find(
+			(candidate): candidate is WorkspaceAllocationIntent =>
+				candidate.kind === "workspace" && candidate.status !== "absent",
+		);
+		const workspaceCleanup = attempt?.cleanup.find((step) => step.kind === "workspace");
+		if (workspaceCleanup?.status === "completed" || (!allocation && !["allocating", "working", "attention"].includes(status))) return [];
+		const symbol = status === "attention" ? "!" : status === "ready" || status === "completed" ? "✓"
+			: ["working", "allocating", "integrating", "cleanup"].includes(status) ? "◌" : "■";
+		const detail = status === "ready" ? "candidate ready · Main not promoted"
+			: status === "attention" ? `attention · ${compactWidgetField(taskState.failure ?? "needs attention")}` : status;
+		return `${symbol} I ${workspaceBadge(task.role, task.modelClass)} ${compactWidgetField(task.id)} · ${detail}${allocation ? ` · ${compactWidgetField(allocation.label)}` : ""}`;
+	});
+	if (!rows.length) return undefined;
+	return state.status === "aborted"
+		? [`■ I ${compactWidgetField(state.request.id)} · request aborted`, ...rows]
+		: rows;
+}
+
+function renderWorkspaceWidget(ctx: ExtensionContext, rowsByRequest: Map<string, string[]>): void {
+	if (!ctx.hasUI) return;
+	const rowOrder = (row: string) => row.startsWith("!") ? 0 : row.startsWith("◌") ? 1
+		: row.endsWith(" · request aborted") ? 2 : 3;
+	const allRows = [...rowsByRequest.values()].flat().sort((a, b) => rowOrder(a) - rowOrder(b));
+	const shown = allRows.length > MAX_WORKSPACE_WIDGET_LINES
+		? [...allRows.slice(0, MAX_WORKSPACE_WIDGET_LINES - 1), `+${allRows.length - MAX_WORKSPACE_WIDGET_LINES + 1} more · /subagent`]
+		: allRows;
+	ctx.ui.setWidget(WORKSPACE_WIDGET_KEY, shown.length ? (_tui, theme) => ({
+		invalidate() {},
+		render(width) {
+			return shown.map((line) => {
+				const color = line.startsWith("!") ? "error" : line.startsWith("◌") ? "accent"
+					: line.startsWith("✓") ? "success" : line.startsWith("■") ? "warning" : undefined;
+				return truncateToWidth(color ? theme.fg(color, line[0]!) + line.slice(1) : line, width);
+			});
+		},
+	}) : undefined);
+}
+
+function updateWorkspaceWidgetSafely(ctx: ExtensionContext, state: RunState, rowsByRequest: Map<string, string[]>): void {
+	try {
+		const key = `${state.root}\0${state.request.id}`;
+		const rows = workspaceWidgetLines(state);
+		if (rows) rowsByRequest.set(key, rows);
+		else rowsByRequest.delete(key);
+		renderWorkspaceWidget(ctx, rowsByRequest);
+	} catch (error) {
+		console.error("Pi Subagent workspace widget update failed.", error);
+	}
+}
+
+/** Join report lines within a follow-up budget, naming how many were omitted. */
+function boundedReport(lines: readonly string[], omitted: string): string {
+	const report: string[] = [];
+	let bytes = 0;
+	let skipped = 0;
+	for (const line of lines.flatMap((entry) => entry.split("\n"))) {
+		const size = Buffer.byteLength(`${line}\n`, "utf8");
+		if (bytes + size > 7_900) { skipped++; continue; }
+		report.push(line);
+		bytes += size;
+	}
+	if (skipped) report.push(`[${skipped} ${omitted}]`);
+	return report.join("\n");
+}
+
+function boundedPublicText(value: string, maxBytes = PUBLIC_EVIDENCE_MAX_BYTES): string {
+	if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+	return `${utf8Prefix(value, maxBytes)}\n[truncated]`;
+}
+
+function publicFailedCheck(evidence: CheckBatchEvidence | undefined) {
+	if (!evidence || evidence.passed) return undefined;
+	const result = evidence.results.find((candidate) => candidate.code !== 0 || candidate.killed)
+		?? evidence.results.at(-1);
+	return {
+		phase: evidence.phase,
+		identityChanged: !sameIdentity(evidence.candidate, evidence.identityAfter),
+		...(result ? {
+			command: boundedPublicText(formatCheckCommand(result)),
+			code: result.code,
+			killed: result.killed,
+			...(result.stdout ? { stdout: boundedPublicText(result.stdout) } : {}),
+			...(result.stderr ? { stderr: boundedPublicText(result.stderr) } : {}),
+		} : {}),
+	};
+}
+
+function publicFailedReview(evidence: ReviewEvidence | undefined, verdictMaxBytes: number) {
+	if (!evidence || evidence.passed) return undefined;
+	const verdict = boundedPublicText(evidence.verdict, verdictMaxBytes);
+	return {
+		phase: evidence.phase,
+		verdict,
+		verdictTruncated: verdict !== evidence.verdict,
+		identityChanged: !sameIdentity(evidence.tip, evidence.identityAfter),
+	};
+}
+
+function publicTaskRecovery(task: RunState["tasks"][number], verdictMaxBytes: number) {
+	if (task.kind === "text") {
+		const attempt = task.attempts.at(-1);
+		return {
+			scope: "task" as const,
+			taskId: task.taskId,
+			...(task.failure ? { failure: boundedPublicText(task.failure) } : {}),
+			...(attempt ? { attempt: {
+				number: attempt.number,
+				status: attempt.status,
+				...(attempt.failure ? { failure: boundedPublicText(attempt.failure) } : {}),
+			} } : {}),
+		};
+	}
+
+	const attempt = task.attempts.at(-1);
+	const failedCheck = publicFailedCheck(attempt?.preliminaryChecks);
+	const failedReview = publicFailedReview(attempt?.preliminaryReview, verdictMaxBytes);
+	const cleanup = attempt?.cleanup
+		.filter((step) => step.status !== "completed")
+		.map((step) => ({
+			kind: step.kind,
+			status: step.status,
+			...(step.failure ? { failure: boundedPublicText(step.failure) } : {}),
+		}));
+	const worktreeCleanupPending = attempt?.cleanup.find((step) => step.kind === "worktree")?.status !== "completed";
+	const worktree = worktreeCleanupPending
+		? [...(attempt?.allocations ?? [])].reverse().find(
+			(intent): intent is WorktreeAllocationIntent => intent.kind === "worktree" && intent.status === "owned" && Boolean(intent.worktree),
+		)?.worktree
+		: undefined;
+	return {
+		scope: "task" as const,
+		taskId: task.taskId,
+		...(task.failure ? { failure: boundedPublicText(task.failure) } : {}),
+		...(worktree ? { retainedWorktree: {
+			path: boundedPublicText(worktree.path),
+			cwd: boundedPublicText(worktree.cwd),
+			branch: boundedPublicText(worktree.branch),
+		} } : {}),
+		...(failedCheck ? { failedCheck } : {}),
+		...(failedReview ? { failedReview } : {}),
+		...(cleanup?.length ? { cleanup } : {}),
+	};
+}
+
+function publicNeedsAttention(state: RunState, verdictMaxBytes: number, preferredTaskId?: string) {
+	if (state.status !== "needs_attention") return undefined;
+	const task = state.tasks.find((candidate) => candidate.status === "needs_attention" && candidate.taskId === preferredTaskId)
+		?? state.tasks.find((candidate) => candidate.status === "needs_attention");
+	if (task) return publicTaskRecovery(task, verdictMaxBytes);
+	if (state.final.failure || state.final.checks?.passed === false || state.final.review?.passed === false) {
+		const failedCheck = publicFailedCheck(state.final.checks);
+		const failedReview = publicFailedReview(state.final.review, verdictMaxBytes);
+		return {
+			scope: "final" as const,
+			...(state.final.failure ? { failure: boundedPublicText(state.final.failure) } : {}),
+			...(failedCheck ? { failedCheck } : {}),
+			...(failedReview ? { failedReview } : {}),
+		};
+	}
+	const nextAction = nextIntegrationAction(state);
+	return {
+		scope: "request" as const,
+		...(nextAction ? { nextAction } : { failure: "Request needs attention without a task or final failure." }),
+	};
+}
+
+function publicState(state: RunState, verdictMaxBytes: number, preferredTaskId?: string) {
+	const needsAttention = publicNeedsAttention(state, verdictMaxBytes, preferredTaskId);
+	return {
+		version: state.version,
+		id: state.request.id,
+		status: state.status,
+		accepted: state.accepted,
+		main: state.main,
+		tasks: state.tasks.map((task) => {
+			const textAttempt = task.kind === "text" ? task.attempts.at(-1) : undefined;
+			return {
+				taskId: task.taskId, status: task.status,
+				...(task.status === "completed" && textAttempt?.output ? { output: workerOutputForMain(boundedPublicText(textAttempt.output.text)) } : {}),
+				...(textAttempt?.cleanup ? { cleanup: {
+					...textAttempt.cleanup,
+					...(textAttempt.cleanup.outcome === "recovery" ? { note: boundedPublicText(textAttempt.cleanup.note) } : {}),
+				} } : {}),
+				...(task.kind === "changeset" && state.integration.candidates.length ? { attempts: task.attempts.map((attempt) => ({
+					number: attempt.number, superseded: attempt.superseded === true,
+					workerId: attempt.allocations.flatMap((item) => item.kind === "agent" && item.status === "owned" ? [item.agentName] : [])[0],
+					termination: attempt.termination?.status,
+					worktree: attempt.allocations.flatMap((item) => item.kind === "worktree" && item.status === "owned" && item.worktree ? [item.worktree.path] : [])[0],
+					cleanup: attempt.cleanup.filter((step) => step.status !== "completed"),
+				})) } : {}),
+			};
+		}),
+		final: { status: state.final.status },
+		integration: {
+			...(state.integration.refresh ? { refresh: state.integration.refresh } : {}),
+			candidates: state.integration.candidates.map(({ taskId, attempt, tip, base, checks, decision, worker }) => ({ taskId, attempt, tip, base, checked: checks.passed, worker, ...(decision ? { decision } : {}) })),
+			generations: state.integration.generations.map(({ number, status, worktree, integrationBase, combinedTip, correction, checks, review, promotion, supersededPromotion, failure, stages, cleanup, supersededFrom }) => ({
+				number, status, integrationBase, ...(supersededFrom ? { supersededFrom } : {}),
+				...(supersededPromotion ? { supersededPromotion: { status: supersededPromotion.status,
+					failure: boundedPublicText(supersededPromotion.failure ?? "") } } : {}),
+				...(cleanup ? { cleanup } : {}),
+				...(combinedTip ? { combinedTip } : {}),
+				...(correction ? { correction } : {}),
+				...(checks ? { checked: checks.passed, failedCheck: publicFailedCheck(checks) } : {}),
+				...(checks?.results.some((result) => result.reusedFrom) ? { reusedChecks: checks.results.flatMap((result) =>
+					result.reusedFrom ? [{ command: boundedPublicText(formatCheckCommand(result)), reusedFrom: result.reusedFrom }] : []) } : {}),
+				...(review ? { reviewed: review.passed, failedReview: publicFailedReview(review, verdictMaxBytes) } : {}),
+				...(promotion ? { promotion: promotion.status, ...(promotion.mainAfter ? { mainAfter: promotion.mainAfter } : {}),
+					...(promotion.failure ? { promotionFailure: boundedPublicText(promotion.failure) } : {}) } : {}),
+				...(failure ? { failure: boundedPublicText(failure) } : {}),
+				...(worktree ? { retainedWorktree: { path: worktree.path, branch: worktree.branch } } : {}),
+				stages: stages.map(({ taskId, attempt, source, onto, status, tip, failure }) => ({
+					taskId, attempt, source, onto, status, ...(tip ? { tip } : {}), ...(failure ? { failure: boundedPublicText(failure) } : {}),
+				})),
+			})),
+		},
+		...(needsAttention ? { needsAttention } : {}),
+		createdAt: state.createdAt,
+		updatedAt: state.updatedAt,
+	};
+}
+
+/** Model-visible failed review verdicts from every task, the final gate, and each generation, within one shared budget.
+ * Pi shows the model `content`, not `structuredContent`; task reviews appear even while sibling tasks still run. */
+function failedReviewText(state: RunState): string {
+	const reviews = [
+		...state.tasks.flatMap((task) => {
+			const review = task.kind === "changeset" ? task.attempts.at(-1)?.preliminaryReview : undefined;
+			return review && !review.passed ? [{ label: `Task ${task.taskId}`, review }] : [];
+		}),
+		...(state.final.review && !state.final.review.passed ? [{ label: "Final", review: state.final.review }] : []),
+		...state.integration.generations.flatMap(({ number, review }) => review && !review.passed ? [{ label: `Integration generation ${number}`, review }] : []),
+	].reduce<{ label: string; review: ReviewEvidence }[]>((merged, entry) => {
+		// Show an identical verdict once, but keep every scope that failed with it.
+		const same = merged.find(({ review }) => review.verdict === entry.review.verdict);
+		if (same) same.label = `${same.label}, ${entry.label}`;
+		else merged.push({ ...entry });
+		return merged;
+	}, []);
+	let budget = PUBLIC_REVIEW_VERDICT_MAX_BYTES;
+	let omitted = 0;
+	const parts: string[] = [];
+	for (const { label, review } of reviews) {
+		if (budget <= 0) { omitted++; continue; }
+		const verdict = boundedPublicText(review.verdict, budget);
+		budget -= Buffer.byteLength(verdict, "utf8");
+		parts.push(`\n\n${label}: failed ${review.phase} review verdict${verdict !== review.verdict ? " (truncated)" : ""}:\n${workerOutputForMain(verdict)}`);
+	}
+	if (omitted) parts.push(`\n\n${omitted} more failed review verdict(s) omitted from this text; structuredContent lists each one.`);
+	return parts.join("");
+}
+
+function hasTruncatedVerdict(state: ReturnType<typeof publicState>): boolean {
+	const attention = state.needsAttention;
+	return Boolean(attention && "failedReview" in attention && attention.failedReview?.verdictTruncated)
+		|| state.integration.generations.some((generation) => generation.failedReview?.verdictTruncated);
+}
+
+function inspectionNotices({ state, main, continuation }: RunResponse): string[] {
+	const lines = [
+		`Isolated request ${state.request.id}: ${state.status}; accepted: ${state.accepted}; final: ${state.final.status}; Main: ${main?.status ?? "not checked"}.`,
+		...(continuation ? [`Reported continuation: ${JSON.stringify(continuation)}`] : []),
+	];
+	if (main) lines.push(main.status === "unavailable"
+		? `Main inspection unavailable: ${boundedPublicText(main.failure)}; expected: ${JSON.stringify(main.expected)}`
+		: `Main ${main.status}: ${JSON.stringify({ expected: main.expected, actual: main.actual })}`);
+	if (state.integration.refresh) lines.push(`Integration refresh: ${state.integration.refresh.status}${state.integration.refresh.failure ? `; blockage: ${boundedPublicText(state.integration.refresh.failure)}` : ""}.`);
+	const attention = publicNeedsAttention(state, PUBLIC_EVIDENCE_MAX_BYTES);
+	if (attention && "nextAction" in attention) lines.push(`Next integration action: ${attention.nextAction}`);
+	else if (attention) lines.push(`Reported blockage: ${JSON.stringify({ scope: attention.scope, failure: attention.failure, failedCheck: "failedCheck" in attention ? attention.failedCheck : undefined, failedReview: "failedReview" in attention ? attention.failedReview : undefined })}`);
+	if (state.final.failure) lines.push(`Final blockage: ${boundedPublicText(state.final.failure)}`);
+	for (const task of state.tasks) {
+		lines.push(`Task ${task.taskId}: ${task.status}${task.failure ? `; blockage: ${boundedPublicText(task.failure)}` : ""}.`);
+		if (task.kind !== "changeset") continue;
+		for (const attempt of task.attempts) {
+			const label = `Task ${task.taskId} attempt ${attempt.number}`;
+			if (attempt.termination) lines.push(`${label} worker termination: ${JSON.stringify({ status: attempt.termination.status, workerId: attempt.termination.workerId, failure: attempt.termination.failure ? boundedPublicText(attempt.termination.failure) : undefined })}`);
+			for (const allocation of attempt.allocations) {
+				if (allocation.status === "absent") continue;
+				const cleanupKind = allocation.kind === "agent" ? "worker_tab" : allocation.kind;
+				const cleaned = (allocation.kind !== "agent" || attempt.termination?.status === "terminated")
+					&& attempt.cleanup.find((step) => step.kind === cleanupKind)?.status === "completed";
+				const branchPending = allocation.kind === "worktree"
+					&& attempt.cleanup.find((step) => step.kind === "branch")?.status !== "completed";
+				// A worktree can be gone while its branch is still retained. Keep its saved
+				// identity available for recovery, but never present the checkout as live.
+				if (allocation.status === "owned" && cleaned && !branchPending) continue;
+				const displayStatus = cleaned
+					? `${allocation.status}; ${branchPending ? "historical checkout; branch cleanup pending" : "cleanup completed (saved allocation)"}`
+					: allocation.kind === "agent" && attempt.termination?.status === "terminated"
+						? `${allocation.status}; worker terminated; tab cleanup pending`
+						: allocation.status;
+				const resource = allocation.kind === "worktree"
+					? { worktree: allocation.worktree && { path: allocation.worktree.path, cwd: allocation.worktree.cwd, branch: allocation.worktree.branch, repoRoot: allocation.worktree.repoRoot } }
+					: allocation.kind === "workspace" ? { label: allocation.label, workspaceId: allocation.workspaceId, worktreeCwd: allocation.worktreeCwd, mainRoot: allocation.mainRoot, herdrRepoRoot: allocation.herdrRepoRoot, repoKey: allocation.repoKey, rootTabId: allocation.rootTabId, rootPaneId: allocation.rootPaneId }
+					: allocation.kind === "worker_tab" ? { label: allocation.label, workspaceId: allocation.workspaceId, workspaceRootTabId: allocation.workspaceRootTabId, workspaceRootPaneId: allocation.workspaceRootPaneId, tabId: allocation.tabId, paneId: allocation.paneId, leasePath: allocation.leasePath, worktreeCwd: allocation.worktreeCwd }
+					: { agentName: allocation.agentName, workspaceId: allocation.workspaceId, tabId: allocation.tabId, paneId: allocation.paneId, leasePath: allocation.leasePath, worktreeCwd: allocation.worktreeCwd };
+				lines.push(`${label} ${allocation.kind} (${displayStatus}): ${JSON.stringify({ ...resource, possibleResources: allocation.possibleResources, failure: allocation.failure ? boundedPublicText(allocation.failure) : undefined })}`);
+			}
+			const cleanup = attempt.cleanup.filter((step) => step.status !== "completed");
+			if (cleanup.length) lines.push(`${label} cleanup pending: ${JSON.stringify(cleanup.map((step) => ({ kind: step.kind, status: step.status, failure: step.failure ? boundedPublicText(step.failure) : undefined })))}`);
+		}
+	}
+	for (const candidate of state.integration.candidates) lines.push(`Candidate ${candidate.taskId} attempt ${candidate.attempt}: ${candidate.worker}${candidate.decision ? `; ${candidate.decision}` : ""}; tip: ${JSON.stringify({ branch: candidate.tip.branch, head: candidate.tip.head })}.`);
+	for (const generation of state.integration.generations) {
+		const checkoutCleaned = generation.cleanup?.find((step) => step.kind === "worktree")?.status === "completed";
+		const branchCleaned = generation.cleanup?.find((step) => step.kind === "branch")?.status === "completed";
+		const retainedPath = generation.worktree && !(checkoutCleaned && branchCleaned);
+		if (!retainedPath && !generation.failure && !/conflict|failed|unknown/.test(generation.status)
+			&& !generation.cleanup?.some((step) => step.status !== "completed")
+			&& !generation.stages.some((stage) => stage.status === "conflict" || stage.failure)
+			&& !generation.promotion?.failure && !generation.supersededPromotion?.failure
+			&& generation !== state.integration.generations.at(-1)) continue;
+		const stagedTip = [...generation.stages].reverse().find((stage) => stage.tip)?.tip ?? generation.integrationBase;
+		lines.push(`Integration generation ${generation.number}: ${generation.status}; ${retainedPath ? `${checkoutCleaned ? "historical checkout; branch cleanup pending" : "worktree"}: ${JSON.stringify({ path: generation.worktree!.path, cwd: generation.worktree!.cwd, branch: generation.worktree!.branch, repoRoot: generation.worktree!.repoRoot })}; ` : ""}last staged tip: ${JSON.stringify(stagedTip)}${generation.correction ? `; correction tip: ${JSON.stringify(generation.correction.to)}` : ""}${generation.combinedTip ? `; combined tip: ${JSON.stringify(generation.combinedTip)}` : ""}${generation.failure ? `; blockage: ${boundedPublicText(generation.failure)}` : ""}.`);
+		for (const stage of generation.stages.filter((item) => item.status === "conflict" || item.failure)) lines.push(`Integration generation ${generation.number} stage ${stage.taskId} attempt ${stage.attempt}: ${stage.status}${stage.failure ? `; blockage: ${boundedPublicText(stage.failure)}` : ""}.`);
+		for (const promotion of [generation.promotion, generation.supersededPromotion]) if (promotion?.failure) lines.push(`Integration generation ${generation.number} promotion ${promotion.status}: ${boundedPublicText(promotion.failure)}`);
+		if (generation.cleanup?.some((step) => step.status !== "completed")) lines.push(`Integration generation ${generation.number} cleanup pending: ${JSON.stringify(generation.cleanup.filter((step) => step.status !== "completed").map((step) => ({ kind: step.kind, status: step.status, failure: step.failure ? boundedPublicText(step.failure) : undefined })))}`);
+	}
+	return lines;
+}
+
+function toolResult(response: RunResponse, ctx: ExtensionContext, rowsByRequest: Map<string, string[]>) {
+	updateWorkspaceWidgetSafely(ctx, response.state, rowsByRequest);
+	const preferredTaskId = response.continuation && "taskId" in response.continuation
+		? response.continuation.taskId
+		: undefined;
+	const workspaces = workspaceWidgetLines(response.state);
+	const text = ctx.hasUI === false && workspaces
+		? `${response.text}\n\nActive workspaces:\n${workspaces.join("\n")}`
+		: response.text;
+	return {
+		content: [{ type: "text" as const, text }],
+		details: {
+			state: publicState(response.state, PUBLIC_REVIEW_VERDICT_MAX_BYTES, preferredTaskId),
+			...(response.main ? { main: response.main } : {}),
+			...(response.continuation ? { continuation: response.continuation } : {}),
+		},
+	};
+}
+
+/** Bounded dry-run plan; a route missing from the coordinator report shows as unresolved. */
+export function formatExecutePlan({ request, root, main, routes }: ExecutePlan, hostChecked: boolean): { content: [{ type: "text"; text: string }]; details: unknown } {
+	const route = (role: string, modelClass: ModelClass) => {
+		const found = routes.find((candidate) => candidate.role === role && candidate.modelClass === modelClass);
+		return found ? { model: found.model, thinkingLevel: found.thinkingLevel } : undefined;
+	};
+	const label = (role: string, modelClass: ModelClass) => {
+		const resolved = route(role, modelClass);
+		return `${role} · ${modelClass} → ${resolved ? `${resolved.model} · thinking ${resolved.thinkingLevel}` : "route not reported"}`;
+	};
+	const changesets = request.tasks.some((task) => task.kind === "changeset");
+	const notChecked = [
+		...(changesets && !hostChecked ? ["Herdr host preflight (client and server versions, API schema, lsof, current workspace identity): it calls Herdr"] : []),
+		"request ID uniqueness and saved-state admission: they need the state lock",
+	];
+	const lines = [
+		`Dry run passed: isolated request ${request.id} in ${root} at Main ${main.head.slice(0, 12)} (${main.branch}). No state, worktree, Herdr tab, lease, or follow-up was created.`,
+		...request.tasks.map((task, index) => [
+			`${index + 1}. ${task.id} · ${task.kind} · ${label(task.role, task.modelClass)}`,
+			`   depends on: ${task.dependsOn.join(", ") || "none"} · context from: ${task.contextFrom.join(", ") || "none"}`,
+			...(task.kind === "changeset" ? [`   checks: ${task.checks.map(formatCheckCommand).join("; ")}`,
+				...(task.judgment ? [`   judgment: ${label(task.judgment.role, task.judgment.modelClass)}`] : [])] : []),
+		].join("\n")),
+		`Final checks: ${request.finalChecks.map(formatCheckCommand).join("; ") || "none"}`,
+		...(request.finalJudgment ? [`Final judgment: ${label(request.finalJudgment.role, request.finalJudgment.modelClass)}`] : []),
+		...notChecked.map((reason) => `Not checked: ${reason}.`),
+	];
+	return {
+		content: [{ type: "text", text: capEphemeralSubagentOutput(lines.join("\n")) }],
+		details: {
+			dryRun: true, mode: "isolated", id: request.id, root, main,
+			tasks: request.tasks.map((task) => ({ id: task.id, kind: task.kind, role: task.role, modelClass: task.modelClass,
+				...route(task.role, task.modelClass), dependsOn: task.dependsOn, contextFrom: task.contextFrom,
+				...(task.kind === "changeset" ? { checks: task.checks, ...(task.judgment ? { judgment: { ...task.judgment, ...route(task.judgment.role, task.judgment.modelClass) } } : {}) } : {}) })),
+			finalChecks: request.finalChecks,
+			...(request.finalJudgment ? { finalJudgment: { ...request.finalJudgment, ...route(request.finalJudgment.role, request.finalJudgment.modelClass) } } : {}),
+			notChecked,
+		},
+	};
+}
+
+export interface IsolatedSurface {
+	/** Dry run of execute: validates and resolves without durable state or Herdr calls. */
+	plan(request: ExecuteRequest, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<ReturnType<typeof formatExecutePlan>>;
+	execute(request: ExecuteRequest, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<ReturnType<typeof toolResult>>;
+	inventory(cwd: string, current?: () => boolean): Promise<IsolatedInventory>;
+	recover(cwd: string): Promise<string>;
+	prunePlan(cwd: string): Promise<PrunePlan>;
+	discardPlan(cwd: string, request: IsolatedRequest): Promise<DiscardPlan>;
+	discard(cwd: string, plan: DiscardPlan, current: () => boolean): Promise<CleanupReport>;
+	prune(cwd: string, items: readonly PruneItem[], allowIgnored: boolean, force: boolean, current: () => boolean): Promise<CleanupReport>;
+	inspect(root: string, requestId: string): Promise<readonly string[]>;
+	canFollowup(root: string, requestId: string, taskId: string): boolean;
+	enqueue(root: string, requestId: string, taskId: string, text: string, current: () => boolean): string;
+	drain(root: string, requestId: string, taskId: string, current: () => boolean): readonly string[];
+}
+
+export interface RegisterIsolatedOptions {
+	executor: EphemeralSubagentExecutor;
+	policy: ExecutionPolicySnapshot;
+	currentPolicy(): ExecutionPolicySnapshot;
+	/** Report new config issues, and throw when the config now blocks delegation, before each deferred Role launch. */
+	beforeRoleLaunch?(ctx: ExtensionContext): void;
+	componentsFactory?: CreateIsolatedComponents;
+}
+
+/** Register lifecycle surfaces; delegate_task remains the only start tool. */
+export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIsolatedOptions): IsolatedSurface {
+	const componentsFactory = options.componentsFactory ?? createIsolatedComponents;
+	let latestCtx: ExtensionContext | undefined;
+	let components: IsolatedExtensionComponents | undefined;
+	const workspaceRowsByRequest = new Map<string, string[]>();
+	let savedRevision = 0;
+	const stateListeners = new Set<(state: RunState) => void>();
+	const activeJobs = new Set<AbortController>();
+	const jobOwners = new Map<string, () => boolean>();
+	let sessionEpoch = 0;
+	let sessionClosed = false;
+
+	const latestContext = (): ExtensionContext => {
+		if (!latestCtx) throw new Error("Pi Subagent cannot resolve a Role before session context exists.");
+		return latestCtx;
+	};
+	const getComponents = () => components ??= componentsFactory({
+		pi,
+		// The launch runtime reads this context only to resolve a Role launch.
+		context: () => {
+			const ctx = latestContext();
+			options.beforeRoleLaunch?.(ctx);
+			return ctx;
+		},
+		executor: options.executor,
+		policy: options.policy,
+		currentPolicy: options.currentPolicy,
+		onStateSaved: (state) => {
+			savedRevision += 1;
+			for (const listener of stateListeners) listener(state);
+			const owner = jobOwners.get(`${state.root}\0${state.request.id}`);
+			if (!sessionClosed && (owner === undefined || owner())) {
+				updateWorkspaceWidgetSafely(latestContext(), state, workspaceRowsByRequest);
+			}
+		},
+	});
+	const lookupRoot = async (cwd: string, signal?: AbortSignal): Promise<string> => {
+		const startedAt = Date.now();
+		const context: OperationContext = {
+			signal: signal ?? new AbortController().signal,
+			timeoutMs: LOOKUP_ROOT_TIMEOUT_MS,
+			deadline: startedAt + LOOKUP_ROOT_TIMEOUT_MS,
+		};
+		return await getComponents().resolveRoot(cwd, context);
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		for (const controller of activeJobs) controller.abort();
+		sessionEpoch += 1;
+		sessionClosed = false;
+		latestCtx = ctx;
+		workspaceRowsByRequest.clear();
+		if (ctx.hasUI) ctx.ui.setWidget(WORKSPACE_WIDGET_KEY, undefined);
+	});
+	pi.on("session_shutdown", () => {
+		for (const controller of activeJobs) controller.abort();
+		sessionEpoch += 1;
+		sessionClosed = true;
+		workspaceRowsByRequest.clear();
+	});
+	pi.on("model_select", (event, ctx) => { latestCtx = { ...ctx, model: event.model } as ExtensionContext; });
+	pi.on("agent_settled", (_event, ctx) => { latestCtx = ctx; });
+
+	const pruneGuards = (root: string): PruneGuards => ({
+		ownership: async (checkouts) => await getComponents().runner.pruneOwnership(checkouts),
+		panes: async () => await listHerdrPanes(root),
+	});
+	const requireCurrent = (current: () => boolean) => {
+		if (!current() || sessionClosed) throw new Error("Session or branch changed; reopen /subagent.");
+	};
+	// FileRunStore emits the initial state only after fsync. A resumed run emits its
+	// recovery record after saving it; validation acknowledges its saved exact intent.
+	// Neither the tool call nor its abort signal
+	// owns productive work after that durable boundary.
+	const startInSession = async (
+		id: string,
+		root: string,
+		signal: AbortSignal | undefined,
+		ctx: ExtensionContext,
+		acknowledged: (state: RunState) => boolean,
+		start: (signal: AbortSignal) => Promise<RunResponse>,
+	): Promise<ReturnType<typeof toolResult>> => {
+		const epoch = sessionEpoch;
+		const sessionId = ctx.sessionManager?.getSessionId();
+		const key = `${root}\0${id}`;
+		if (jobOwners.has(key)) throw new Error(`Pi Subagent request ${id} is already active in this session runtime.`);
+		const deliverySuppression = () => sessionClosed ? "session closed"
+			: sessionEpoch !== epoch ? "session generation changed"
+			: ctx.sessionManager?.getSessionId() !== sessionId ? "launching session changed"
+			: latestCtx?.sessionManager?.getSessionId() !== sessionId ? "current session changed"
+			: undefined;
+		const canDeliver = () => deliverySuppression() === undefined;
+		const controller = new AbortController();
+		activeJobs.add(controller);
+		jobOwners.set(key, canDeliver);
+		const notified = new Set<string>();
+		const attentionNotified = new Set<string>();
+		let candidateListener: ((state: RunState) => void) | undefined;
+		const finish = () => {
+			activeJobs.delete(controller);
+			if (candidateListener) stateListeners.delete(candidateListener);
+			if (jobOwners.get(key) === canDeliver) jobOwners.delete(key);
+		};
+		const abortBeforeAck = () => controller.abort(signal?.reason);
+		if (signal?.aborted) abortBeforeAck();
+		else signal?.addEventListener("abort", abortBeforeAck, { once: true });
+		let latestState: RunState | undefined;
+		let durableAcknowledged = false;
+		let accept!: (state: RunState) => void;
+		let reject!: (error: unknown) => void;
+		const durable = new Promise<RunState>((resolve, fail) => { accept = resolve; reject = fail; });
+		const removeTurnAbort = () => signal?.removeEventListener("abort", abortBeforeAck);
+		const listener = (state: RunState) => {
+			if (state.root !== root || state.request.id !== id) return;
+			latestState = state;
+			if (!acknowledged(state)) return;
+			durableAcknowledged = true;
+			for (const candidate of state.integration.candidates) notified.add(`${candidate.taskId}\0${candidate.attempt}\0${candidate.tip.head}`);
+			stateListeners.delete(listener);
+			removeTurnAbort();
+			accept(state);
+		};
+		stateListeners.add(listener);
+		const deliver = (kind: "candidate" | "attention" | "terminal", text: string, response?: RunResponse) => {
+			const suppression = deliverySuppression();
+			if (suppression) {
+				console.warn(`Pi Subagent ${id}: ${kind} delivery suppressed (${suppression}); durable request retained.`);
+				return;
+			}
+			const state = response?.state ?? latestState;
+			try {
+				const preview = state ? publicState(state, PUBLIC_EVIDENCE_MAX_BYTES, response?.continuation && "taskId" in response.continuation
+					? response.continuation.taskId : undefined) : undefined;
+				const details = preview ? {
+					state: preview,
+					...(response?.continuation ? { continuation: response.continuation } : {}),
+				} : { id };
+				pi.sendMessage({
+					customType: "pi-subagent-isolated-result",
+					content: preview && hasTruncatedVerdict(preview)
+						? `${text}\n\nReview verdicts here are previews; run subagent_status for the full verdict.`
+						: text,
+					display: true,
+					details,
+				}, { triggerTurn: true, deliverAs: "followUp" });
+			} catch {
+				console.error(`Pi Subagent ${id}: ${kind} delivery failed (sendMessage threw); use subagent_status to recover. No delivery replayed.`);
+				if (ctx.hasUI) ctx.ui.notify(`Pi Subagent ${id} result delivery failed; use subagent_status to recover.`, "error");
+			}
+		};
+		candidateListener = (state) => {
+			if (state.root !== root || state.request.id !== id) return;
+			latestState = state;
+			if (state.status !== "running") return;
+			for (const task of state.tasks) {
+				if (task.status !== "needs_attention") {
+					attentionNotified.delete(task.taskId);
+					continue;
+				}
+				if (attentionNotified.has(task.taskId)) continue;
+				attentionNotified.add(task.taskId);
+				deliver("attention", `Pi Subagent ${id}: ${task.taskId} needs attention. Inspect subagent_status for the saved worker evidence; do not replay an uncertain prompt.`);
+			}
+			for (const candidate of state.integration.candidates) {
+				const identity = `${candidate.taskId}\0${candidate.attempt}\0${candidate.tip.head}`;
+				if (candidate.decision || notified.has(identity)) continue;
+				notified.add(identity);
+				deliver("candidate", `Pi Subagent ${id}: ${candidate.taskId} ready to integrate. Inspect the exact candidate with subagent_status and stage it now; other workers may still be running.`);
+			}
+		};
+		stateListeners.add(candidateListener);
+		void Promise.resolve().then(() => start(controller.signal)).then(
+			(response) => {
+				finish();
+				stateListeners.delete(listener);
+				removeTurnAbort();
+				if (!durableAcknowledged) {
+					reject(new Error(`Pi Subagent ${id} finished without a durable acknowledgement.`));
+					return;
+				}
+				deliver("terminal", `${response.text}\n\nState: ${JSON.stringify(publicState(response.state, PUBLIC_EVIDENCE_MAX_BYTES))}`, response);
+			},
+			(error: unknown) => {
+				finish();
+				stateListeners.delete(listener);
+				removeTurnAbort();
+				if (!durableAcknowledged) {
+					reject(error);
+					return;
+				}
+				deliver("terminal", `Pi Subagent ${id} stopped: ${boundedPublicText(error instanceof Error ? error.message : String(error))}. Use subagent_status to inspect the durable request before choosing an explicit recovery action.`);
+			},
+		);
+		const state = await durable;
+		if (!canDeliver()) throw new Error(`Pi Subagent ${id} was saved, but its launching session changed before acknowledgement. Use subagent_status to inspect the durable request.`);
+		return toolResult({ text: `Pi Subagent ${id}: durable request accepted; productive work continues. Use subagent_status to inspect progress.`, state }, ctx, workspaceRowsByRequest);
+	};
+
+	// Status stays callable from codemode scripts and hands them the same bounded public projection
+	// the model reads; every mutating tool below is model-only because its guarded transitions need
+	// Main's visible reasoning.
+	pi.registerTool({
+		name: "subagent_status",
+		label: "Subagent status",
+		description: "Read one durable isolated request without reconciling or changing resources.",
+		parameters: IdOnlySchema,
+		prepareArguments: parseIdOnly,
+		outputSchema: StatusOutputSchema,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			latestCtx = ctx;
+			const root = await lookupRoot(ctx.cwd, signal);
+			const response = await getComponents().runner.status(params.id, root, signal);
+			const result = toolResult(response, ctx, workspaceRowsByRequest);
+			const content = [{ type: "text" as const, text: `${result.content[0]!.text}${failedReviewText(response.state)}` }];
+			// The projection is plain JSON; its conditional fields are typed optional rather than absent.
+			return { ...result, content, structuredContent: result.details as JsonValue };
+		},
+	});
+	pi.registerTool({
+		name: "subagent_resume",
+		label: "Subagent resume",
+		description: "Resume one unfinished isolated request without resetting its recorded policy or correction count. For a retry that sends a same-worker correction, optional instruction (at most 32000 characters) is appended to that prompt as Main's instruction after the saved check or review failure; use it to name the exact fixes, including the review findings the worker must address. Other actions reject instruction.",
+		parameters: ResumeRequestParameters,
+		prepareArguments: parseResumeRequest,
+		exposure: "model-only",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			latestCtx = ctx;
+			const root = await lookupRoot(ctx.cwd, signal);
+			return await startInSession(params.id, root, signal, ctx,
+				(state) => state.recovery?.kind === "resume" && state.recovery.action === params.action
+					&& (!("taskId" in params) || state.recovery.taskId === params.taskId),
+				(runSignal) => getComponents().runner.resume(params, root, runSignal));
+		},
+	});
+	pi.registerTool({
+		name: "subagent_stage",
+		label: "Subagent stage",
+		description: "Main stages/resolves an exact candidate, or rejects/revises one. Rejection of a staged candidate freezes the old generation; explicitly restage chosen candidates in a new generation. Never writes Main.",
+		parameters: StageRequestSchema,
+		prepareArguments: parseStageRequest,
+		exposure: "model-only",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			latestCtx = ctx;
+			const root = await lookupRoot(ctx.cwd, signal);
+			return toolResult(await getComponents().runner.stage(params, root, signal), ctx, workspaceRowsByRequest);
+		},
+	});
+	pi.registerTool({
+		name: "subagent_integrate",
+		label: "Subagent integrate",
+		description: "Main advances staged dependents, refreshes after clean Main drift or evidence-less validation failure, validates in the background, corrects, promotes, reconciles interrupted validation/promotion, cleans up promoted resources, or explicitly releases rejected/superseded owned resources. Never replays an uncertain mutation.",
+		parameters: IntegrationActionParameters,
+		prepareArguments: parseIntegrationAction,
+		exposure: "model-only",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			latestCtx = ctx;
+			const root = await lookupRoot(ctx.cwd, signal);
+			if (params.action === "validate") {
+				return await startInSession(params.id, root, signal, ctx,
+					(state) => {
+						const generation = state.integration.generations.at(-1);
+						return generation?.number === params.generation && generation.status === "validating"
+							&& sameIdentity(generation.combinedTip!, params.expectedTip);
+					},
+					(runSignal) => getComponents().runner.integrate(params, root, runSignal));
+			}
+			if (params.action === "advance") {
+				return await startInSession(params.id, root, signal, ctx,
+					(state) => state.status === "running" && state.waves.at(-1)?.status === "dispatching"
+						&& sameIdentity(state.waves.at(-1)!.base, params.expectedTip),
+					(runSignal) => getComponents().runner.integrate(params, root, runSignal));
+			}
+			return toolResult(await getComponents().runner.integrate(params, root, signal), ctx, workspaceRowsByRequest);
+		},
+	});
+	pi.registerTool({
+		name: "subagent_abort",
+		label: "Subagent abort",
+		description: "Abort an isolated request; reject and release retained candidates and integration checkouts first unless their checkouts and branches are proved absent. Terminate only exact owned workers. Repeat abort to reconcile cleanup of unchanged allocations; preserve dirty or committed work.",
+		parameters: IdOnlySchema,
+		prepareArguments: parseIdOnly,
+		exposure: "model-only",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			latestCtx = ctx;
+			const root = await lookupRoot(ctx.cwd, signal);
+			return toolResult(await getComponents().runner.abort(params.id, root, signal), ctx, workspaceRowsByRequest);
+		},
+	});
+	return {
+		async inventory(cwd, current) {
+			const root = await lookupRoot(cwd);
+			const revision = savedRevision;
+			const { requests, invalidIds, states } = await getComponents().runner.listRequests(root);
+			if (current?.() && !sessionClosed && revision === savedRevision) {
+				workspaceRowsByRequest.clear();
+				for (const state of states) {
+					const rows = workspaceWidgetLines(state);
+					if (rows) workspaceRowsByRequest.set(`${state.root}\0${state.request.id}`, rows);
+				}
+				try { renderWorkspaceWidget(latestContext(), workspaceRowsByRequest); }
+				catch (error) { console.error("Pi Subagent workspace widget update failed.", error); }
+			}
+			const orphans = await getComponents().runner.listOrphanRequests(root);
+			const leaseLive = await getComponents().runner.hasProductiveRunLease(root);
+			return { root, leaseLive, requests: [...requests, ...orphans.requests], invalidIds: [...new Set([...invalidIds, ...orphans.invalidIds])] };
+		},
+		async recover(cwd) {
+			const root = await lookupRoot(cwd);
+			const { requests, invalidIds, leaseBusy } = await getComponents().runner.recoverRepository(root);
+			const lines = [
+				`Pi Subagent recovery in ${root}: ${leaseBusy ? "productive lease is live; no state changed" : "orphaned interruptions classified; no work replayed"}.`,
+				...(requests.length ? requests.map((response) => {
+					const state = response.state;
+					const blockers = state.tasks.flatMap((task) => [
+						...(task.failure ? [`${task.taskId}: ${boundedPublicText(task.failure)}`] : []),
+						...(task.kind === "changeset" && task.attempts.some((attempt) => attempt.prompts.some((prompt) => prompt.status === "ambiguous"))
+							? [`${task.taskId}: ambiguous worker prompt; do not replay`] : []),
+					]);
+					const generation = state.integration.generations.at(-1);
+					const readyCandidates = state.integration.candidates.filter((candidate) => candidate.worker === "retained" && !candidate.decision);
+					return [
+						`${state.request.id}: ${state.status}; Main ${response.main?.status ?? "not checked"}.`,
+						...blockers.map((blocker) => `  Blocker: ${blocker}`),
+						...(state.final.failure ? [`  Final blocker: ${boundedPublicText(state.final.failure)}`] : []),
+						...(generation?.failure ? [`  Integration blocker: ${boundedPublicText(generation.failure)}`] : []),
+						...(state.status !== "completed" && readyCandidates.length ? [`  ${readyCandidates.length} retained candidate(s); Main selects exact candidates with subagent_stage after subagent_status.`] : []),
+						...(state.status === "completed" ? ["  Retained resources after completion; inspect subagent_status for guarded cleanup."] : []),
+						...(generation ? [`  Generation ${generation.number}: ${generation.status}; inspect subagent_status before any subagent_integrate action.`] : []),
+						...(!leaseBusy && response.continuation ? [`  Reported next action: subagent_resume ${JSON.stringify(response.continuation)}.`] : []),
+					].join("\n");
+			}) : ["No unfinished or retained isolated requests."]),
+			...(invalidIds.length ? [`Unreadable state IDs (preserved; inspect with their compatible owner): ${invalidIds.map((id) => JSON.stringify(id)).join(", ")}.`] : []),
+			leaseBusy ? "Wait for the active productive run; use subagent_status to inspect its current state. No work was taken over."
+				: "Main: inspect subagent_status for exact identities and blockers before deciding stage, promote, resume, or guarded release. No worker prompt, merge, promotion, or cleanup was replayed.",
+			];
+			return boundedReport(lines, "recovery report lines omitted; use subagent_status for exact request evidence.");
+		},
+		async discardPlan(cwd, request) {
+			return await getComponents().runner.discardPlan(cwd, request.id, request.directory, {
+				panes: () => listHerdrPanes(cwd), current: () => !sessionClosed,
+				blocked: async () => jobOwners.has(`${request.root}\0${request.id}`) ? "A local job is active for this request." : undefined,
+			});
+		},
+		async discard(cwd, plan, current) {
+			requireCurrent(current);
+			const removals = await getComponents().runner.discard(cwd, plan, {
+				panes: () => listHerdrPanes(cwd), current: () => current() && !sessionClosed,
+				blocked: async () => jobOwners.has(`${plan.root}\0${plan.requestId}`) ? "A local job is active for this request." : undefined,
+			});
+			const count = (outcome: string) => removals.filter((item) => item.outcome === outcome).length;
+			return { failed: count("failed"), skipped: count("skipped"), text: boundedReport([`Close and delete ${plan.requestId}:`,
+				...removals.map((item) => `${item.outcome}: ${item.key}: ${item.reason}`),
+			], "removal report lines omitted; reopen /subagent to inspect retained resources.") };
+		},
+		async prunePlan(cwd) {
+			const root = await lookupRoot(cwd);
+			return { root, items: await inspectPruneCandidates(root, cwd, pruneGuards(root)) };
+		},
+		async prune(cwd, items, allowIgnored, force, current) {
+			requireCurrent(current);
+			const root = await lookupRoot(cwd);
+			const { removals, checkouts } = await removePruneCandidates(root, cwd, items, allowIgnored, force,
+				{ ...pruneGuards(root), current: () => current() && !sessionClosed });
+			const removed = removals.filter(({ outcome }) => outcome === "removed");
+			const reconciled = removed.length
+				? await getComponents().runner.reconcilePrunedAborts(checkouts, removed.map(({ item }) => basename(item.branch))) : [];
+			const count = (outcome: string) => removals.filter((item) => item.outcome === outcome).length;
+			return { failed: count("failed"), skipped: count("skipped"), text: boundedReport([
+				`Pi Subagent prune in ${root}: ${removed.length} removed, ${count("skipped")} skipped, ${count("failed")} failed.`,
+				...removals.map(({ outcome, item, reason }) => `${outcome}: ${item.path ?? "(no checkout)"} · ${item.branch} · ${reason}`),
+				...reconciled,
+			], "prune report lines omitted.") };
+		},
+		async inspect(root, requestId) {
+			const response = await getComponents().runner.status(requestId, root);
+			return inspectionNotices(response);
+		},
+		canFollowup: (root, requestId, taskId) => !sessionClosed && (components?.runner.canFollowup(root, requestId, taskId) ?? false),
+		enqueue(root, requestId, taskId, text, current) {
+			requireCurrent(current);
+			return getComponents().runner.queueFollowup(root, requestId, taskId, text);
+		},
+		drain(root, requestId, taskId, current) {
+			requireCurrent(current);
+			return getComponents().runner.drainFollowups(root, requestId, taskId);
+		},
+		async plan(request, signal, ctx) {
+			latestCtx = ctx;
+			latestContext();
+			const root = await lookupRoot(ctx.cwd, signal);
+			if (jobOwners.has(`${root}\0${request.id}`)) throw new Error(`Pi Subagent request ${request.id} is already active in this session runtime.`);
+			return formatExecutePlan(await getComponents().runner.plan(request, ctx.cwd, signal), false);
+		},
+		async execute(request, signal, ctx) {
+			latestCtx = ctx;
+			latestContext();
+			const root = await lookupRoot(ctx.cwd, signal);
+			return await startInSession(request.id, root, signal, ctx,
+				(state) => state.status === "pending" && state.createdAt === state.updatedAt
+					&& state.tasks.every((task) => task.status === "pending" && task.attempts.length === 0),
+				(runSignal) => getComponents().runner.execute(request, ctx.cwd, runSignal));
+		},
+	};
+}