@fred-drake/anvil 0.0.1

package/src/paths.ts

@@ -0,0 +1,35 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export interface AnvilPathOptions {
+	cwd?: string;
+	homeDir?: string;
+}
+
+export interface WorkflowDirs {
+	user: string;
+	project: string;
+}
+
+export function getHomeDir(options: AnvilPathOptions = {}): string {
+	return options.homeDir ?? homedir();
+}
+
+export function getProjectCwd(options: AnvilPathOptions = {}): string {
+	return resolve(options.cwd ?? process.cwd());
+}
+
+export function getUserAnvilDir(options: AnvilPathOptions = {}): string {
+	return join(getHomeDir(options), ".pi", "agent", "anvil");
+}
+
+export function getProjectAnvilDir(options: AnvilPathOptions = {}): string {
+	return join(getProjectCwd(options), ".pi", "anvil");
+}
+
+export function getWorkflowDirs(options: AnvilPathOptions = {}): WorkflowDirs {
+	return {
+		user: join(getUserAnvilDir(options), "workflows"),
+		project: join(getProjectAnvilDir(options), "workflows"),
+	};
+}

package/src/prompts.ts

@@ -0,0 +1,253 @@
+import { shellEscape } from "./shell.ts";
+import type {
+	AgentCheck,
+	Templatable,
+	WorkflowContext,
+	WorkflowDefinition,
+	WorkflowDelegation,
+	WorkflowStep,
+	WorkflowSubagentBackend,
+} from "./types.ts";
+
+export interface StepInstructionOptions {
+	workflow: WorkflowDefinition;
+	step: WorkflowStep;
+	ctx: WorkflowContext;
+	stepIndex: number;
+	stepCount: number;
+	feedback?: string;
+}
+
+export async function renderTemplatable(template: Templatable, ctx: WorkflowContext): Promise<string> {
+	if (typeof template === "function") return template(ctx);
+	return renderTemplateString(template, ctx);
+}
+
+export async function renderCommandTemplatable(template: Templatable, ctx: WorkflowContext): Promise<string> {
+	if (typeof template === "function") return template(ctx);
+	return renderCommandTemplateString(template, ctx);
+}
+
+export function renderTemplateString(template: string, ctx: WorkflowContext): string {
+	return replaceTemplatePlaceholders(template, ctx, (value) => value);
+}
+
+export function renderCommandTemplateString(template: string, ctx: WorkflowContext): string {
+	return renderCommandPlaceholders(template, [
+		{ token: "{input}", variable: "__ANVIL_INPUT", value: ctx.input },
+		{ token: "{loop}", variable: "__ANVIL_LOOP", value: String(getCurrentLoopCount(ctx)) },
+	]);
+}
+
+function replaceTemplatePlaceholders(
+	template: string,
+	ctx: WorkflowContext,
+	escapeValue: (value: string) => string,
+): string {
+	return template
+		.replaceAll("{input}", escapeValue(ctx.input))
+		.replaceAll("{loop}", escapeValue(String(getCurrentLoopCount(ctx))));
+}
+
+type ShellQuote = "single" | "double" | undefined;
+
+interface CommandPlaceholder {
+	token: string;
+	variable: string;
+	value: string;
+}
+
+function renderCommandPlaceholders(template: string, placeholders: CommandPlaceholder[]): string {
+	let rendered = "";
+	let quote: ShellQuote;
+	let usedPlaceholder = false;
+
+	for (let index = 0; index < template.length;) {
+		const placeholder = placeholders.find((candidate) => template.startsWith(candidate.token, index));
+		if (placeholder) {
+			rendered += commandPlaceholderExpansion(placeholder.variable, quote);
+			index += placeholder.token.length;
+			usedPlaceholder = true;
+			continue;
+		}
+
+		const char = template[index]!;
+		if (char === "\\" && quote !== "single" && index + 1 < template.length) {
+			rendered += template.slice(index, index + 2);
+			index += 2;
+			continue;
+		}
+
+		rendered += char;
+		if (quote === "single") {
+			if (char === "'") quote = undefined;
+		} else if (quote === "double") {
+			if (char === '"') quote = undefined;
+		} else if (char === "'") {
+			quote = "single";
+		} else if (char === '"') {
+			quote = "double";
+		}
+		index += 1;
+	}
+
+	if (!usedPlaceholder) return template;
+
+	const assignments = placeholders
+		.map((placeholder) => `${placeholder.variable}=${shellEscape(placeholder.value)}`)
+		.join(" ");
+	return `${assignments}; ${rendered}`;
+}
+
+function commandPlaceholderExpansion(variable: string, quote: ShellQuote): string {
+	const parameterExpansion = `\${${variable}}`;
+	if (quote === "single") return `'"${parameterExpansion}"'`;
+	if (quote === "double") return parameterExpansion;
+	return `"${parameterExpansion}"`;
+}
+
+export async function buildStepInstruction(options: StepInstructionOptions): Promise<string> {
+	const renderedPrompt = await renderTemplatable(options.step.prompt, options.ctx);
+	const task = appendFeedback(renderedPrompt, options.feedback);
+	const title = options.step.title ?? options.step.id;
+	const header = `[anvil] Workflow "${options.workflow.name}" — step ${options.stepIndex + 1}/${options.stepCount}: ${title}`;
+
+	const delegation = resolveStepDelegation(options.workflow, options.step);
+	if (delegation.mode === "skill") {
+		return (
+			`${header}\n\n` +
+			`Delegate this workflow step to a subagent using skill "${delegation.skill}" if a delegation capability is available. ` +
+			`If no delegation capability is available, do the work directly in the main agent using that skill.\n\n` +
+			`Task:\n${task}`
+		);
+	}
+	if (delegation.mode === "auto") {
+		const hint = delegation.hint ? ` Prefer agent/skill "${delegation.hint}" if appropriate.` : "";
+		return (
+			`${header}\n\n` +
+			`Choose whether to use a subagent for this workflow step.${hint} ` +
+			`If a suitable delegation capability is available, delegate to the best agent or skill; otherwise do the work directly in the main agent.\n\n` +
+			`Task:\n${task}`
+		);
+	}
+
+	return `${header}\n\nDo this workflow step directly in the main agent. Do not delegate to a subagent.\n\n${task}`;
+}
+
+/** Task prompt for a step Anvil runs itself in a dedicated subagent session. */
+export async function buildSubagentStepTask(options: StepInstructionOptions): Promise<string> {
+	const renderedPrompt = await renderTemplatable(options.step.prompt, options.ctx);
+	const task = appendFeedback(renderedPrompt, options.feedback);
+	const title = options.step.title ?? options.step.id;
+	const header = `[anvil] Workflow "${options.workflow.name}" — step ${options.stepIndex + 1}/${options.stepCount}: ${title}`;
+
+	return (
+		`${header}\n\n` +
+		`You are a subagent session executing this workflow step. Complete the task autonomously, without asking for confirmation. ` +
+		`Your final message is reported back to the main workflow session as this step's outcome, so end with a concise summary of what you did.\n\n` +
+		`Task:\n${task}`
+	);
+}
+
+export function buildSubagentResultMessage(args: {
+	workflowName: string;
+	stepTitle: string;
+	stepIndex: number;
+	stepCount: number;
+	backend: WorkflowSubagentBackend;
+	summary: string;
+	sessionFile?: string;
+}): string {
+	const sessionLine = args.sessionFile ? `\n\nSubagent session: ${args.sessionFile}` : "";
+	return (
+		`[anvil] Workflow "${args.workflowName}" — step ${args.stepIndex + 1}/${args.stepCount} "${args.stepTitle}" ` +
+		`was executed by a ${args.backend} subagent session. Treat the summary below as this step's outcome; do not redo the work.\n\n` +
+		`Subagent summary:\n${args.summary}${sessionLine}`
+	);
+}
+
+export async function buildAgentCheckInstruction(args: {
+	workflow: WorkflowDefinition;
+	step: WorkflowStep;
+	check: AgentCheck;
+	ctx: WorkflowContext;
+	checkId: string;
+}): Promise<string> {
+	const criteria = await renderTemplatable(args.check.prompt, args.ctx);
+	const delegateLine = args.check.agent
+		? `\nIf you use subagents for evaluations, delegate this evaluation to subagent "${args.check.agent}".`
+		: "";
+
+	return `[anvil] Workflow "${args.workflow.name}" — evaluate step "${args.step.id}".\n\n` +
+		`Evaluation criteria:\n${criteria}${delegateLine}\n\n` +
+		`Call the \`anvil_verdict\` tool exactly once with:\n` +
+		`- check_id: ${args.checkId}\n` +
+		`- pass: true if the criteria are satisfied, otherwise false\n` +
+		`- reason: a concise explanation\n\n` +
+		`Do not report the verdict only in prose; the workflow engine only accepts the tool call.`;
+}
+
+export function buildVerdictReprompt(checkId: string): string {
+	return `[anvil] You did not report a verdict for check_id ${checkId}. Call the \`anvil_verdict\` tool now exactly once with check_id ${checkId}, pass, and reason.`;
+}
+
+export function appendFeedback(prompt: string, feedback?: string): string {
+	if (!feedback?.trim()) return prompt;
+	return `${prompt}\n\n## Feedback from failed check\n${feedback.trim()}`;
+}
+
+export type ResolvedStepDelegation =
+	| { mode: "none" }
+	| { mode: "auto"; hint?: string }
+	| { mode: "skill"; skill: string }
+	| { mode: "subagent"; backend: WorkflowSubagentBackend };
+
+export function resolveStepDelegation(workflow: WorkflowDefinition, step: WorkflowStep): ResolvedStepDelegation {
+	if (step.runInMain) return { mode: "none" };
+
+	const legacyHint = step.agent ?? workflow.defaults?.agent;
+	const configured = step.delegation ?? workflow.defaults?.delegation;
+	if (configured) return resolveConfiguredDelegation(configured, legacyHint);
+
+	return resolveAutoDelegation(legacyHint);
+}
+
+function resolveConfiguredDelegation(delegation: WorkflowDelegation, legacyHint?: string): ResolvedStepDelegation {
+	if (delegation === "auto") return resolveAutoDelegation(legacyHint);
+	if (delegation === "none") return { mode: "none" };
+	if ("subagent" in delegation) return { mode: "subagent", backend: delegation.subagent };
+	return { mode: "skill", skill: delegation.skill };
+}
+
+function resolveAutoDelegation(hint?: string): ResolvedStepDelegation {
+	const backend = detectAutoSubagentBackend();
+	return backend ? { mode: "subagent", backend } : hint ? { mode: "auto", hint } : { mode: "auto" };
+}
+
+export function detectAutoSubagentBackend(): WorkflowSubagentBackend | undefined {
+	if (process.env.HERDR_ENV === "1") return "herdr";
+	if (process.env.CMUX_SHELL_INTEGRATION === "1") return "cmux";
+	return undefined;
+}
+
+export function workflowSubagentBackends(workflow: WorkflowDefinition): WorkflowSubagentBackend[] {
+	const backends = new Set<WorkflowSubagentBackend>();
+	for (const step of workflow.steps) {
+		const delegation = resolveStepDelegation(workflow, step);
+		if (delegation.mode === "subagent") backends.add(delegation.backend);
+	}
+	return [...backends];
+}
+
+export function workflowUsesSubagentDelegation(workflow: WorkflowDefinition): boolean {
+	return workflowSubagentBackends(workflow).length > 0;
+}
+
+export function getCurrentLoopCount(ctx: WorkflowContext): number {
+	let count = 0;
+	const suffix = `->${ctx.step.id}`;
+	for (const [key, value] of Object.entries(ctx.loopCounts)) {
+		if (key.endsWith(suffix) && value > count) count = value;
+	}
+	return count;
+}

package/src/shell.ts

@@ -0,0 +1,3 @@
+export function shellEscape(value: string): string {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/src/subagent/child.ts

@@ -0,0 +1,61 @@
+/**
+ * Extension loaded into Anvil-spawned subagent sessions (`pi -e .../child.ts`).
+ *
+ * When the agent finishes its turn, it writes a `<sessionFile>.exit` sidecar
+ * (consumed by the parent's pollForExit) and shuts the session down. Turns the
+ * user aborted with Escape stay open for inspection; provider-error turns exit
+ * with the error message so the parent reports a failure instead of a stale
+ * summary.
+ */
+import { writeFileSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+interface AssistantLike {
+	role?: string;
+	stopReason?: string;
+	errorMessage?: string;
+}
+
+export function shouldAutoExitOnAgentEnd(messages: AssistantLike[] | undefined): boolean {
+	if (messages) {
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const message = messages[i];
+			if (message?.role === "assistant") return message.stopReason !== "aborted";
+		}
+	}
+	return true;
+}
+
+export function findLatestAssistantError(messages: AssistantLike[] | undefined): string | undefined {
+	if (!messages) return undefined;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i];
+		if (message?.role !== "assistant") continue;
+		if (message.stopReason !== "error") return undefined;
+		return message.errorMessage?.trim() || "Subagent agent loop ended with stopReason=error.";
+	}
+	return undefined;
+}
+
+/* v8 ignore start -- loaded only inside spawned pi subagent sessions. */
+export default function anvilSubagentChild(pi: ExtensionAPI) {
+	const sessionFile = process.env.PI_ANVIL_SUBAGENT_SESSION;
+	if (!sessionFile) return;
+
+	pi.on("agent_end", (event, ctx) => {
+		const messages = (event as { messages?: AssistantLike[] }).messages;
+		if (!shouldAutoExitOnAgentEnd(messages)) return;
+
+		const errorMessage = findLatestAssistantError(messages);
+		try {
+			writeFileSync(
+				`${sessionFile}.exit`,
+				JSON.stringify(errorMessage ? { type: "error", errorMessage } : { type: "done" }),
+			);
+		} catch {
+			// Best effort — the terminal sentinel still reports the exit.
+		}
+		ctx.shutdown();
+	});
+}
+/* v8 ignore stop */

package/src/subagent/cmux.ts

@@ -0,0 +1,227 @@
+/**
+ * Minimal cmux backend for Anvil's declarative subagent steps.
+ *
+ * Ported (cmux-only) from HazAT/pi-interactive-subagents: surfaces are cmux
+ * tabs; the first subagent creates a right split, later ones add tabs to the
+ * same pane. Completion is detected via a `<sessionFile>.exit` sidecar written
+ * by the child extension, with the terminal sentinel as crash fallback.
+ */
+import { execFile } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { promisify } from "node:util";
+import { shellEscape } from "../shell.ts";
+import { interpretExitSidecar, pollForExitWithReadScreen } from "./exit.ts";
+import type { SubagentExit } from "./exit.ts";
+export {
+	DEFAULT_READ_SCREEN_FAILURE_LIMIT,
+	DEFAULT_SUBAGENT_TIMEOUT_MS,
+	SUBAGENT_SENTINEL_PREFIX,
+} from "./exit.ts";
+
+const execFileAsync = promisify(execFile);
+
+/** Tracked subagent pane — reused across launches so tabs stack instead of splitting. */
+let subagentPane: string | null = null;
+
+export { shellEscape };
+
+/* v8 ignore start -- cmux process/UI launch integration is covered by source-level contracts and manual cmux behavior. */
+export function isCmuxAvailable(): boolean {
+	return Boolean(process.env.CMUX_SOCKET_PATH);
+}
+
+export function cmuxUnavailableMessage(): string {
+	return 'cmux is not available. Start pi inside cmux (`cmux pi`) to run workflows with `delegation: { subagent: "cmux" }`.';
+}
+
+interface FocusSnapshot {
+	surfaceRef?: string;
+	paneRef?: string;
+}
+
+interface CreatedSurface {
+	surface: string;
+	paneRef?: string;
+}
+
+async function readCmuxJson(args: string[]): Promise<Record<string, unknown> | null> {
+	try {
+		const { stdout } = await execFileAsync("cmux", args, { encoding: "utf8" });
+		if (!stdout.trim()) return null;
+		const parsed = JSON.parse(stdout);
+		return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : null;
+	} catch {
+		return null;
+	}
+}
+
+function toFocusSnapshot(value: unknown): FocusSnapshot | null {
+	if (!value || typeof value !== "object") return null;
+	const record = value as { surface_ref?: unknown; pane_ref?: unknown };
+	const surfaceRef = typeof record.surface_ref === "string" && record.surface_ref ? record.surface_ref : undefined;
+	const paneRef = typeof record.pane_ref === "string" && record.pane_ref ? record.pane_ref : undefined;
+	return surfaceRef || paneRef ? { surfaceRef, paneRef } : null;
+}
+
+async function captureIdentify(): Promise<{ focused: FocusSnapshot | null; caller: FocusSnapshot | null }> {
+	const parsed = await readCmuxJson(["identify", "--json"]);
+	return {
+		focused: toFocusSnapshot(parsed?.focused),
+		caller: toFocusSnapshot(parsed?.caller),
+	};
+}
+
+async function readPaneRefForSurface(surface: string): Promise<string | undefined> {
+	const parsed = await readCmuxJson(["identify", "--surface", surface]);
+	if (!parsed) return undefined;
+	if (parsed.surface_ref === surface && typeof parsed.pane_ref === "string" && parsed.pane_ref) return parsed.pane_ref;
+	const caller = parsed.caller;
+	if (caller && typeof caller === "object") {
+		const record = caller as { surface_ref?: unknown; pane_ref?: unknown };
+		if (record.surface_ref === surface && typeof record.pane_ref === "string" && record.pane_ref) return record.pane_ref;
+	}
+	return undefined;
+}
+
+async function restoreFocus(snapshot: FocusSnapshot | null): Promise<void> {
+	if (!snapshot) return;
+	try {
+		if (snapshot.paneRef) await execFileAsync("cmux", ["focus-pane", "--pane", snapshot.paneRef], { encoding: "utf8" });
+		if (snapshot.surfaceRef) await execFileAsync("cmux", ["focus-panel", "--panel", snapshot.surfaceRef], { encoding: "utf8" });
+	} catch {
+		// Best-effort focus restoration only.
+	}
+}
+
+function focusMatches(focus: FocusSnapshot | null, snapshot: FocusSnapshot | null | undefined): boolean {
+	if (!focus || !snapshot) return false;
+	return (!!snapshot.surfaceRef && focus.surfaceRef === snapshot.surfaceRef) || (!!snapshot.paneRef && focus.paneRef === snapshot.paneRef);
+}
+
+/**
+ * Creating a split/surface can steal keyboard focus. If focus landed on the
+ * new child (or settled back onto the caller's pane), put it back where it was.
+ */
+async function restoreFocusIfStolen(snapshot: FocusSnapshot | null, child: CreatedSurface, caller: FocusSnapshot | null): Promise<void> {
+	if (!snapshot) return;
+	await sleep(100);
+	const current = (await captureIdentify()).focused;
+	if (
+		focusMatches(current, { surfaceRef: child.surface, paneRef: child.paneRef }) ||
+		focusMatches(current, caller)
+	) {
+		await restoreFocus(snapshot);
+	}
+}
+
+function parseCreatedSurface(output: string, command: string): CreatedSurface {
+	const surfaceMatch = output.match(/surface:\d+/);
+	if (!surfaceMatch) throw new Error(`Unexpected cmux ${command} output: ${output}`);
+	return { surface: surfaceMatch[0], paneRef: output.match(/pane:\d+/)?.[0] };
+}
+
+async function renameSurface(surface: string, name: string): Promise<void> {
+	await execFileAsync("cmux", ["rename-tab", "--surface", surface, name], { encoding: "utf8" });
+}
+
+async function createSplitSurface(name: string): Promise<CreatedSurface> {
+	const { focused, caller } = await captureIdentify();
+	let child: CreatedSurface | null = null;
+	try {
+		const args = ["new-split", "right"];
+		if (process.env.CMUX_SURFACE_ID) args.push("--surface", process.env.CMUX_SURFACE_ID);
+		const { stdout } = await execFileAsync("cmux", args, { encoding: "utf8" });
+		child = parseCreatedSurface(stdout.trim(), "new-split");
+		child.paneRef ??= await readPaneRefForSurface(child.surface);
+		await renameSurface(child.surface, name);
+		return child;
+	} finally {
+		if (child) await restoreFocusIfStolen(focused, child, caller);
+		else await restoreFocus(focused);
+	}
+}
+
+async function createSurfaceInPane(name: string, pane: string): Promise<string> {
+	const { focused, caller } = await captureIdentify();
+	let child: CreatedSurface | null = null;
+	try {
+		const { stdout } = await execFileAsync("cmux", ["new-surface", "--pane", pane], { encoding: "utf8" });
+		child = parseCreatedSurface(stdout.trim(), "new-surface");
+		child.paneRef ??= pane;
+		await renameSurface(child.surface, name);
+		return child.surface;
+	} finally {
+		if (child) await restoreFocusIfStolen(focused, child, caller);
+		else await restoreFocus(focused);
+	}
+}
+
+/**
+ * Create a terminal surface for a subagent. The first call creates a right
+ * split; subsequent calls add tabs to that pane so splits don't keep shrinking.
+ * Returns a `surface:<n>` identifier.
+ */
+export async function createSurface(name: string): Promise<string> {
+	if (subagentPane) {
+		try {
+			const { stdout: tree } = await execFileAsync("cmux", ["tree"], { encoding: "utf8" });
+			if (new RegExp(`(^|\\s)${escapeRegExp(subagentPane)}($|\\s)`).test(tree)) {
+				return createSurfaceInPane(name, subagentPane);
+			}
+		} catch {}
+		subagentPane = null;
+	}
+
+	const created = await createSplitSurface(name);
+	subagentPane = created.paneRef ?? null;
+	return created.surface;
+}
+
+/**
+ * Send a command by writing it to a script file and executing that, so long
+ * commands survive terminal line-wrapping. The script is kept for debugging.
+ */
+export async function sendLongCommand(surface: string, command: string, scriptPath: string): Promise<void> {
+	mkdirSync(dirname(scriptPath), { recursive: true });
+	writeFileSync(scriptPath, `#!/bin/bash\n${command}\n`, { mode: 0o600 });
+	await execFileAsync("cmux", ["send", "--surface", surface, `bash ${shellEscape(scriptPath)}\n`], { encoding: "utf8" });
+}
+
+export async function readScreen(surface: string, lines = 5): Promise<string> {
+	const { stdout } = await execFileAsync("cmux", ["read-screen", "--surface", surface, "--lines", String(lines)], {
+		encoding: "utf8",
+	});
+	return stdout;
+}
+
+export async function closeSurface(surface: string): Promise<void> {
+	await execFileAsync("cmux", ["close-surface", "--surface", surface], { encoding: "utf8" });
+}
+/* v8 ignore stop */
+
+export type { SubagentExit };
+
+/**
+ * Poll until the subagent exits: `.exit` sidecar first (written by the child
+ * extension), terminal sentinel as fallback for crashes / early shell errors.
+ */
+export function pollForExit(
+	surface: string,
+	sessionFile: string,
+	signal?: AbortSignal,
+	intervalMs?: number,
+	timeoutMs?: number,
+): Promise<SubagentExit> {
+	return pollForExitWithReadScreen(readScreen, surface, sessionFile, signal, intervalMs, timeoutMs);
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export const __testing__ = { interpretExitSidecar };

package/src/subagent/exit.ts

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { AnvilAbortError, throwIfAborted } from "../errors.ts";
+
+export const SUBAGENT_SENTINEL_PREFIX = "__ANVIL_SUBAGENT_DONE_";
+const SENTINEL_RE = /__ANVIL_SUBAGENT_DONE_(\d+)__/;
+const MISSING_CWD_PROMPT_RE = /cwd from session file does not exist/i;
+const CONTINUE_CANCEL_PROMPT_RE = /continue in current cwd[\s\S]*?(?:^|\n)\s*(?:→\s*)?Continue\b[\s\S]*?(?:^|\n)\s*Cancel\b/im;
+export const DEFAULT_SUBAGENT_TIMEOUT_MS = 1_800_000;
+export const DEFAULT_READ_SCREEN_FAILURE_LIMIT = 2;
+
+export interface SubagentExit {
+	reason: "done" | "error" | "sentinel";
+	exitCode: number;
+	errorMessage?: string;
+}
+
+export type ReadSubagentScreen = (surface: string, lines?: number) => Promise<string>;
+
+export function interpretExitSidecar(data: unknown): SubagentExit {
+	const record = (typeof data === "object" && data !== null ? data : {}) as { type?: unknown; errorMessage?: unknown };
+	if (record.type === "error") {
+		const errorMessage =
+			typeof record.errorMessage === "string" && record.errorMessage.trim()
+				? record.errorMessage
+				: "Subagent exited with stopReason=error.";
+		return { reason: "error", exitCode: 1, errorMessage };
+	}
+	return { reason: "done", exitCode: 0 };
+}
+
+function consumeExitSidecar(sessionFile: string): SubagentExit | undefined {
+	try {
+		const exitFile = `${sessionFile}.exit`;
+		if (!existsSync(exitFile)) return undefined;
+		const data = JSON.parse(readFileSync(exitFile, "utf8"));
+		rmSync(exitFile, { force: true });
+		return interpretExitSidecar(data);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Poll until the subagent exits: `.exit` sidecar first (written by the child
+ * extension), terminal sentinel as fallback for crashes / early shell errors.
+ *
+ * The screen reader is injected by each multiplexer backend so Herdr panes are
+ * polled with `herdr pane read` and cmux surfaces with `cmux read-screen`.
+ */
+export async function pollForExitWithReadScreen(
+	readScreen: ReadSubagentScreen,
+	surface: string,
+	sessionFile: string,
+	signal?: AbortSignal,
+	intervalMs = 1000,
+	timeoutMs = DEFAULT_SUBAGENT_TIMEOUT_MS,
+): Promise<SubagentExit> {
+	const deadline = Date.now() + timeoutMs;
+	let consecutiveReadFailures = 0;
+	for (;;) {
+		throwIfAborted(signal);
+		if (Date.now() >= deadline) throw new Error(`Subagent timed out after ${timeoutMs}ms`);
+
+		const sidecar = consumeExitSidecar(sessionFile);
+		if (sidecar) return sidecar;
+
+		try {
+			const screen = await readScreen(surface, 5);
+			consecutiveReadFailures = 0;
+			const match = screen.match(SENTINEL_RE);
+			if (match) return { reason: "sentinel", exitCode: Number.parseInt(match[1]!, 10) };
+			const blockingPrompt = detectBlockingPiStartupPrompt(screen);
+			if (blockingPrompt) return { reason: "error", exitCode: 1, errorMessage: blockingPrompt };
+		} catch {
+			// Surface may already be gone — give the child a short grace period to write the sidecar,
+			// then fail fast instead of waiting for the full subagent timeout.
+			if (Date.now() >= deadline) throw new Error(`Subagent timed out after ${timeoutMs}ms`);
+			const lateSidecar = consumeExitSidecar(sessionFile);
+			if (lateSidecar) return lateSidecar;
+			consecutiveReadFailures += 1;
+			if (consecutiveReadFailures >= DEFAULT_READ_SCREEN_FAILURE_LIMIT) {
+				throw new Error(`Subagent surface closed before completion: ${surface}`);
+			}
+		}
+
+		await sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())), signal);
+	}
+}
+
+function detectBlockingPiStartupPrompt(screen: string): string | undefined {
+	if (MISSING_CWD_PROMPT_RE.test(screen)) {
+		return "Pi startup prompt blocked subagent auto-exit: cwd from session file does not exist.";
+	}
+	if (CONTINUE_CANCEL_PROMPT_RE.test(screen)) {
+		return "Pi startup prompt blocked subagent auto-exit; rerun the step after the session startup prompt is resolved.";
+	}
+	return undefined;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) return reject(new AnvilAbortError());
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		function onAbort() {
+			clearTimeout(timer);
+			reject(new AnvilAbortError());
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}