@ferris1225/pi-subagents 0.29.0 → 0.32.2

package/src/spawn.ts

@@ -1,856 +1,562 @@
-/**
- * Sub-agent dispatch: each agent runs as an isolated `pi` child process
- * (`--mode json -p --no-session`). The agent's system prompt (the .md body) is
- * written to a temp file and passed via `--append-system-prompt` (which accepts a
- * file path). The task itself is sent through the child's stdin pipe, not another
- * temp file or command-line argument. Child stdout is a JSON-lines event stream;
- * we accumulate assistant messages from `message_end` events.
- *
- * Adapted from the official pi example `examples/extensions/subagent`.
- */
-
-import { spawn, type ChildProcess } from "node:child_process";
-import { existsSync, mkdirSync, unlinkSync, rmdirSync, writeFileSync } from "node:fs";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { basename, join } from "node:path";
-import { StringDecoder } from "node:string_decoder";
-import type { Message } from "@earendil-works/pi-ai";
-import type { AgentConfig, AgentSource } from "./agents.ts";
-import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
-
-/**
- * Limits are configurable: see maxConcurrency in config.ts (default 4, via
- * /subagents-setup or pi-subagents.json).
- */
-/** Default thinking level for sub-agents. pi clamps it to the resolved model's support. */
-export const SUBAGENT_THINKING_LEVEL: ThinkingLevel = DEFAULT_THINKING_LEVEL;
-export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
-export const SUBAGENT_KILL_GRACE_MS = 5_000;
-/** Default idle watchdog: terminate a child whose stdout goes silent for this
- * many milliseconds. 0 disables it. The actual value comes from config
- * (idleTimeoutSec); this constant is only a fallback for tests. */
-export const SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS = 0;
-
-/** Backoff schedule for retrying a child that exited before any model or tool
- * activity — the signature of a concurrent pi startup race, where several
- * sub-agents contending for pi's startup lock lose and exit with nothing on
- * stdout. Bounded and short so persistent launch failures are not amplified
- * while the startup lock clears. */
-export const SUBAGENT_STARTUP_RETRY_DELAYS_MS = [250, 750, 1500] as const;
-/** A genuine startup race fails well before a model request can complete. */
-export const MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS = 2000;
-
-/** Backoff schedule (ms) for retrying a run whose configured model failed at the
- * provider level with a TRANSIENT error (503/429/timeout/network/overloaded/...) —
- * i.e. NOT a terminal error (quota exhausted, billing, invalid API key). The same
- * model is relaunched (each relaunch gets its own startup-retry inner loop), so a
- * one-off provider hiccup recovers without demoting the configured agent model.
- *
- * This sits OUTSIDE pi-ai's per-request provider retry (default 3 attempts, 2/4/8s
- * backoff): when the provider still can't recover after its own retries, the
- * child exits carrying the final error, and this layer relaunches the whole run
- * up to len(delays) more times before falling back to the main-window model.
- *
- * Bounded and capped so a stubborn outage does not stall a dispatch forever. */
-export const SUBAGENT_RUN_LEVEL_RETRY_DELAYS_MS = [2_000, 4_000, 8_000, 16_000, 30_000] as const;
-
-export interface UsageStats {
-	input: number;
-	output: number;
-	cacheRead: number;
-	cacheWrite: number;
-	cost: number;
-	contextTokens: number;
-	turns: number;
-}
-
-export interface SingleResult {
-	agent: string;
-	agentSource: AgentSource | "unknown";
-	task: string;
-	exitCode: number; // -1 = still running
-	messages: Message[];
-	stderr: string;
-	usage: UsageStats;
-	model?: string;
-	/** Effective thinking strength this run was launched with. */
-	thinking?: string;
-	stopReason?: string;
-	errorMessage?: string;
-	/** Model the run degraded from: set when a failed run was retried with the main-window model. */
-	modelFallbackFrom?: string;
-	/** True when the result was synthesized from a thrown exception (spawn infra,
-	 * temp-file/fs errors, delivery bugs) instead of being produced by the agent
-	 * process. A dispatch failure is never a model-level failure. */
-	dispatchFailed?: boolean;
-	/** How many times the run was relaunched after a silent, zero-activity startup
-	 * exit (a concurrent pi startup race) before it produced a result. Set only when
-	 * the run actually recovered after retrying, so callers can surface it. */
-	startupRetries?: number;
-	/** How many times the SAME configured model was relaunched after a transient
-	 * provider-level failure (503/429/timeout/network/...) before the run produced
-	 * a result. Set on recovery and on fall-back to the main-window model; left
-	 * undefined for a terminal (quota/billing/invalid-key) error that short-
-	 * circuits before any retry, since no relaunch happened. */
-	modelRetries?: number;
-	/** Tool calls that failed inside the run (from tool_execution_end events). A
-	 * clean process exit can still hide a failed build/test/tool — the completion
-	 * message must surface these so the main agent is never misled by a rosy final
-	 * text (e.g. a worker that ended with "keep waiting" while its build failed). */
-	failedTools?: Array<{ toolName: string; error: string }>;
-}
-
-export interface SubagentDetails {
-	mode: "single" | "parallel";
-	results: SingleResult[];
-	/** The tool returned immediately while the child process continues in the background. */
-	background?: boolean;
-}
-
-export type SubagentLiveEvent =
-	| { kind: "status"; status: "queued" | "running" | "done" | "failed" }
-	| { kind: "usage"; usage: UsageStats; model?: string }
-	| { kind: "tool_start"; toolName: string; args: unknown }
-	| { kind: "tool_end"; toolName: string; isError: boolean }
-	| { kind: "thinking" }
-	| { kind: "text" };
-
-function emptyUsage(): UsageStats {
-	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
-}
-
-export function getFinalOutput(messages: Message[]): string {
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const msg = messages[i];
-		if (msg.role === "assistant") {
-			for (const part of msg.content) {
-				if (part.type === "text") return part.text;
-			}
-		}
-	}
-	return "";
-}
-
-/**
- * Parse the machine-readable verdict a reviewer emits (see agents/reviewer.md).
- * Only the LAST standalone `VERDICT: REVIEW_PASS/FAIL` line counts, so a report
- * that merely discusses the tokens cannot be misclassified. Returns undefined
- * when no verdict marker is present, so non-review agents are never mistaken
- * for reviews.
- */
-export function reviewVerdict(output: string): "pass" | "fail" | undefined {
-	const lines = output.split("\n");
-	for (let index = lines.length - 1; index >= 0; index--) {
-		const match = /^\s*VERDICT:\s*REVIEW_(PASS|FAIL)\s*$/i.exec(lines[index]);
-		if (match) return match[1].toUpperCase() === "PASS" ? "pass" : "fail";
-	}
-	return undefined;
-}
-
-/** Tool errors are usually the trailing lines of a long output (build logs);
- * keep the last non-empty lines, clipped to RESULT_LINE_MAX each. */
-export function extractToolErrorText(content: unknown): string {
-	const parts = Array.isArray(content) ? content : [];
-	const text = parts
-		.filter(
-			(part): part is { type: "text"; text: string } =>
-				typeof part === "object" &&
-				part !== null &&
-				(part as { type?: unknown }).type === "text" &&
-				typeof (part as { text?: unknown }).text === "string",
-		)
-		.map((part) => part.text)
-		.join("\n");
-	return text
-		.split("\n")
-		.map((line) => line.trim())
-		.filter(Boolean)
-		.slice(-3)
-		.map((line) => (line.length > RESULT_LINE_MAX ? `${line.slice(0, RESULT_LINE_MAX)}…` : line))
-		.join("\n");
-}
-
-/** Hard cap for a single line inside a truncated result (minified blobs must not blow up). */
-export const RESULT_LINE_MAX = 200;
-
-export interface TruncatedOutput {
-	/** The result text that fits in the completion message. */
-	text: string;
-	/** True when lines were dropped or shortened, so the full text is written to disk. */
-	truncated: boolean;
-}
-
-/** Cap result text for the main conversation: keep the first `maxLines` lines, at most RESULT_LINE_MAX chars each. */
-export function truncateResultOutput(output: string, maxLines: number): TruncatedOutput {
-	const lines = output.split("\n");
-	if (lines.length <= maxLines && lines.every((line) => line.length <= RESULT_LINE_MAX)) {
-		return { text: output, truncated: false };
-	}
-	const kept = lines.slice(0, maxLines).map((line) =>
-		line.length > RESULT_LINE_MAX ? `${line.slice(0, RESULT_LINE_MAX)}…` : line,
-	);
-	return { text: kept.join("\n"), truncated: true };
-}
-
-/** Persist the full result where the main agent can read it on demand. Returns the file path.
- * Results are grouped under a per-project subdirectory so concurrent projects don't
- * litter a single flat folder. */
-export function writeResultArtifact(output: string, agentName: string, cwd?: string): string {
-	const projectSlug = cwd
-		? basename(cwd).replace(/[^\w.-]+/g, "_") || "default"
-		: "default";
-	const dir = join(tmpdir(), "pi-subagents-results", projectSlug);
-	mkdirSync(dir, { recursive: true });
-	const safeName = agentName.replace(/[^\w.-]+/g, "_");
-	// A random suffix keeps same-millisecond writes from clobbering each other.
-	const unique = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-	const filePath = join(dir, `${unique}-${safeName}.md`);
-	writeFileSync(filePath, output, "utf8");
-	return filePath;
-}
-
-export function isFailedResult(result: SingleResult): boolean {
-	return result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
-}
-
-/**
- * True when a failed run never got usable output from its model: the provider
- * rejected the call before the model produced any text (bad model id, auth,
- * thinking level, quota, ...). Task-level failures — the model worked and the
- * task failed — and aborts/timeouts are NOT model-level and must not degrade.
- */
-export function isModelLevelFailure(result: SingleResult): boolean {
-	if (!isFailedResult(result)) return false;
-	if (result.stopReason === "aborted") return false;
-	// A result synthesized from a thrown exception (spawn infra, fs, delivery
-	// bugs) never came from the provider: it is a dispatch failure, not a
-	// model-level one, and must not be handed back as a model problem.
-	if (result.dispatchFailed) return false;
-	// An idle timeout (stdout went silent) signals a stalled provider connection,
-	// not a task-level failure: allow model fallback even if the model produced
-	// partial output before going quiet.
-	if (result.errorMessage?.includes("idle timeout")) return true;
-	// The model produced text: the failure belongs to the task, not the model.
-	if (getFinalOutput(result.messages)) return false;
-	// Require evidence the failure came from the model/provider (an error
-	// message or stderr), not from the child process failing to start.
-	return result.messages.length > 0 || result.stderr.trim().length > 0;
-}
-
-/** Patterns that signal a TERMINAL provider/account error: retrying the same
- * model (or falling back to the main-window model under the same account) cannot
- * fix it, so the run skips both run-level retry and model fallback and is handed
- * back to the main agent. This is the complement of pi-ai's transient-error set
- * (429/5xx/overloaded/network/timeout/...): anything NOT matching here is treated
- * as transient and retried on the same model before degrading.
- *
- * Mirrors pi-ai's NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN (quota/billing/
- * subscription-limit text) and adds the auth/credential failures the user cited
- * ("key无效"). Auth is account-scoped, so a fallback model on the same provider
- * would fail identically — hand it to the main agent immediately. */
-const TERMINAL_MODEL_ERROR_PATTERN =
-	/insufficient_quota|quota\s+exceeded|exceeded[^.\n]{0,40}quota|out\s+of\s+budget|billing|usage\s+limit|usage_limit|gousagelimiterror|freeusagelimiterror|monthly\s+usage\s+limit\s+reached|available\s+balance|invalid\s+(?:api\s+)?key|incorrect\s+api\s+key|unauthori[sz]ed|\b401\b|\b403\b|forbidden|permission\s+denied/i;
-
-/** True when a model-level failure carries a TERMINAL error message — quota
- * exhaustion, billing, an invalid API key, auth rejection. Such a run is NEVER
- * retried on the same model and never falls back to the main-window model: the
- * account is the bottleneck, so it is handed back to the main agent to fix.
- *
- * Caller must first confirm `isModelLevelFailure(result)` — aborts and
- * dispatch-crafted results never reach this classifier. */
-export function isTerminalModelError(result: SingleResult): boolean {
-	const message = result.errorMessage?.trim();
-	if (message) return TERMINAL_MODEL_ERROR_PATTERN.test(message);
-	// Only consult stderr when there is no structured errorMessage: pi-ai surfaces
-	// provider errors via message_end -> errorMessage, so a transient errorMessage
-	// (e.g. "503 Service Unavailable") must not be overridden by noisy stderr that
-	// happens to mention a terminal-looking word (an npm warning, a proxy banner).
-	// This keeps transient failures retryable even when stderr is chatty.
-	const stderr = result.stderr.trim();
-	return stderr.length > 0 && TERMINAL_MODEL_ERROR_PATTERN.test(stderr);
-}
-
-/**
- * True when a failed run produced NO model, tool, output, or usage activity
- * within the startup window — the signature of a concurrent pi startup race,
- * where the child lost pi's startup lock and exited before doing anything.
- * Such a run is safe to relaunch: nothing was mutated and no provider call
- * completed, so retrying cannot duplicate work.
- *
- * Fails closed: any final output, assistant message, usage, stderr, structured
- * error message, idle-timeout, abort, dispatch crash, or run that outlived the
- * startup window disqualifies the run from retry (it either did real work or
- * carries a real error that belongs to model fallback / normal failure
- * delivery instead). Only a clean, SILENT, fast, zero-activity exit retries.
- */
-export function isRetryableStartupFailure(result: SingleResult, durationMs: number): boolean {
-	if (result.exitCode === 0) return false;
-	if (result.stopReason === "aborted") return false;
-	if (result.dispatchFailed) return false;
-	if (result.errorMessage?.includes("idle timeout")) return false;
-	if (getFinalOutput(result.messages)) return false;
-	if (result.messages.length > 0) return false;
-	const usage = result.usage;
-	if (usage.turns || usage.input || usage.output || usage.cacheRead || usage.cacheWrite || usage.cost) return false;
-	if (durationMs > MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS) return false;
-	// Any stderr or structured error could be a real provider/config error (auth,
-	// bad model id, quota, ...) that must not be amplified by retry. A silent
-	// zero-activity exit — no stdout, no stderr, no error message — is the race.
-	if (result.stderr.trim().length > 0) return false;
-	if (result.errorMessage && result.errorMessage.trim().length > 0) return false;
-	return true;
-}
-
-/** Error surfaced when every startup-retry attempt still exited with no
- * activity. Tells the main agent the dispatch never reached a model and what to
- * do (retry, or lower maxConcurrency). */
-export function formatStartupRetryExhaustedError(model: string, attempts: number): string {
-	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child exited before any model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or temporarily lower maxConcurrency in /subagents-setup.`;
-}
-
-/** Wait out a startup-retry backoff. Resolves false immediately (do not retry)
- * when the signal is or becomes aborted during the wait, so cancellation never
- * delays delivering the last result. The timer is unref'd so it cannot keep the
- * event loop alive on shutdown. */
-export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal): Promise<boolean> {
-	if (delayMs <= 0) return !signal?.aborted;
-	if (!signal) {
-		return new Promise<boolean>((resolve) => {
-			const timer = setTimeout(() => resolve(true), delayMs);
-			if (typeof timer.unref === "function") timer.unref();
-		});
-	}
-	if (signal.aborted) return false;
-	return new Promise<boolean>((resolve) => {
-		let settled = false;
-		const finish = (shouldRetry: boolean): void => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			signal.removeEventListener("abort", onAbort);
-			resolve(shouldRetry);
-		};
-		const onAbort = (): void => finish(false);
-		const timer = setTimeout(() => finish(true), delayMs);
-		if (typeof timer.unref === "function") timer.unref();
-		signal.addEventListener("abort", onAbort, { once: true });
-	});
-}
-
-export function getResultOutput(result: SingleResult): string {
-	if (isFailedResult(result)) {
-		const error = result.errorMessage || result.stderr;
-		const partial = getFinalOutput(result.messages);
-		if (error && partial) return `${error}\n\n--- Partial output ---\n${partial}`;
-		return error || partial || "(no output)";
-	}
-	return getFinalOutput(result.messages) || "(no output)";
-}
-
-async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
-	const dir = await mkdtemp(join(tmpdir(), "pi-subagents-"));
-	const safeName = agentName.replace(/[^\w.-]+/g, "_");
-	const filePath = join(dir, `prompt-${safeName}.md`);
-	await writeFile(filePath, prompt, "utf8");
-	return { dir, filePath };
-}
-
-/** Resolve how to invoke the SAME pi build as the current process. */
-export function getPiInvocation(args: string[]): { command: string; args: string[] } {
-	const currentScript = process.argv[1];
-	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
-	if (currentScript && !isBunVirtualScript && existsSync(currentScript)) {
-		return { command: process.execPath, args: [currentScript, ...args] };
-	}
-	const execName = basename(process.execPath).toLowerCase();
-	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
-	if (!isGenericRuntime) return { command: process.execPath, args };
-	return { command: "pi", args };
-}
-
-/** Terminate the child and any tool processes it left behind. */
-function terminateProcessTree(proc: ChildProcess, force: boolean): void {
-	if (process.platform === "win32" && proc.pid !== undefined) {
-		const killer = spawn("taskkill", ["/pid", String(proc.pid), "/t", "/f"], {
-			stdio: "ignore",
-			windowsHide: true,
-		});
-		const fallback = (): void => {
-			try {
-				proc.kill(force ? "SIGKILL" : "SIGTERM");
-			} catch {
-				/* process may already be gone */
-			}
-		};
-		killer.on("error", fallback);
-		killer.on("close", (code) => {
-			if (code !== 0) fallback();
-		});
-		return;
-	}
-
-	try {
-		proc.kill(force ? "SIGKILL" : "SIGTERM");
-	} catch {
-		/* process may already be gone */
-	}
-}
-
-export function currentSubagentDepth(env: NodeJS.ProcessEnv = process.env): number {
-	const raw = env[DEPTH_ENV_VAR];
-	const parsed = raw === undefined ? 0 : Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
-}
-
-export interface RunSingleOptions {
-	defaultCwd: string;
-	agent: AgentConfig | undefined;
-	agentName: string;
-	task: string;
-	cwd?: string;
-	/** Thinking level passed to the child pi process. */
-	thinkingLevel?: ThinkingLevel;
-	/** Idle timeout in ms: terminate the child if its stdout produces no activity
-	 * for this duration. 0 (the default) disables the idle watchdog. */
-	idleTimeoutMs?: number;
-	/** Startup-retry backoff schedule (ms) for silent, zero-activity child exits
-	 * (a concurrent pi startup race). Defaults to SUBAGENT_STARTUP_RETRY_DELAYS_MS;
-	 * pass a shorter array in tests to keep them fast. */
-	startupRetryDelaysMs?: readonly number[];
-	/** Run-level backoff schedule (ms) for relaunching the SAME configured model
-	 * after a transient provider-level failure (503/429/timeout/network/...). Each
-	 * relaunch gets its own startup-retry inner loop. Defaults to
-	 * SUBAGENT_RUN_LEVEL_RETRY_DELAYS_MS; pass [] to disable (e.g. when an isolated
-	 * test wants to assert only the fallback path runs once). */
-	runLevelRetryDelaysMs?: readonly number[];
-	signal?: AbortSignal;
-	onLive?: (e: SubagentLiveEvent) => void;
-	makeDetails: (results: SingleResult[]) => SubagentDetails;
-	env?: NodeJS.ProcessEnv;
-}
-
-/** Spawn one agent as an isolated pi child process and collect its output. */
-export async function runSingleAgent(options: RunSingleOptions): Promise<SingleResult> {
-	const {
-		agent,
-		agentName,
-		task,
-		cwd,
-		thinkingLevel = SUBAGENT_THINKING_LEVEL,
-		idleTimeoutMs = SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS,
-		signal,
-		onLive,
-		makeDetails,
-	} = options;
-
-	if (!agent) {
-		return {
-			agent: agentName,
-			agentSource: "unknown",
-			task,
-			exitCode: 1,
-			messages: [],
-			stderr: `Unknown agent: "${agentName}".`,
-			usage: emptyUsage(),
-		};
-	}
-
-	// Defense in depth: even if another extension ignores the depth marker, a
-	// child process can never expose a tool named `subagent` back to its model.
-	const args: string[] = ["--mode", "json", "-p", "--no-session", "--exclude-tools", "subagent"];
-	if (agent.model) args.push("--model", agent.model);
-	// The configured level is clamped adaptively per model by pi.
-	args.push("--thinking", thinkingLevel);
-	if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
-
-	let tmpPromptDir: string | null = null;
-	let tmpPromptPath: string | null = null;
-
-	const currentResult: SingleResult = {
-		agent: agentName,
-		agentSource: agent.source,
-		task,
-		exitCode: 0,
-		messages: [],
-		stderr: "",
-		usage: emptyUsage(),
-		model: agent.model,
-		thinking: thinkingLevel,
-	};
-
-	try {
-		if (agent.systemPrompt.trim()) {
-			const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
-			tmpPromptDir = tmp.dir;
-			tmpPromptPath = tmp.filePath;
-			args.push("--append-system-prompt", tmpPromptPath);
-		}
-
-		let wasAborted = false;
-
-		// Increment depth so nested sub-agents can be guarded against runaway recursion.
-		const childDepth = currentSubagentDepth(options.env) + 1;
-		const childEnv: NodeJS.ProcessEnv = {
-			...(options.env ?? process.env),
-			[DEPTH_ENV_VAR]: String(childDepth),
-		};
-
-		const exitCode = await new Promise<number>((resolve) => {
-			const invocation = getPiInvocation(args);
-			const proc = spawn(invocation.command, invocation.args, {
-				cwd: cwd ?? options.defaultCwd,
-				shell: false,
-				stdio: ["pipe", "pipe", "pipe"],
-				env: childEnv,
-			});
-			let buffer = "";
-			let closed = false;
-			let termSent = false;
-			let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
-			let abortHandler: (() => void) | undefined;
-			let lastActivityAt = Date.now();
-			let idleTimer: ReturnType<typeof setInterval> | undefined;
-
-			const finish = (code: number | null): void => {
-				if (closed) return;
-				closed = true;
-				if (forceKillTimer) clearTimeout(forceKillTimer);
-				if (idleTimer) clearInterval(idleTimer);
-				if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
-				resolve(code ?? 1);
-			};
-
-			const terminate = (): void => {
-				if (closed) return;
-				if (!termSent) {
-					termSent = true;
-					terminateProcessTree(proc, false);
-				}
-				if (!forceKillTimer) {
-					forceKillTimer = setTimeout(() => {
-						if (!closed) terminateProcessTree(proc, true);
-					}, SUBAGENT_KILL_GRACE_MS);
-				}
-			};
-
-			const processLine = (line: string): void => {
-				if (!line.trim()) return;
-				let event: any;
-				try {
-					event = JSON.parse(line);
-				} catch {
-					return;
-				}
-
-				// Live event: agent started
-				if (event.type === "agent_start" || event.type === "turn_start") {
-					if (onLive) {
-						try {
-							onLive({ kind: "status", status: "running" });
-						} catch { /* never throw from event handling */ }
-					}
-				}
-
-				// Live event: streamed assistant reasoning / output text
-				if (event.type === "message_update") {
-					const t = event.assistantMessageEvent?.type;
-					if (t === "thinking_delta" || t === "text_delta") {
-						if (onLive) {
-							try {
-								onLive({ kind: t === "thinking_delta" ? "thinking" : "text" });
-							} catch { /* never throw from event handling */ }
-						}
-					}
-				}
-
-				// Live event: tool execution started
-				if (event.type === "tool_execution_start") {
-					if (onLive) {
-						try {
-							onLive({ kind: "tool_start", toolName: event.toolName ?? "unknown", args: event.args });
-						} catch { /* never throw from event handling */ }
-					}
-				}
-
-				// Live event: tool execution ended
-				if (event.type === "tool_execution_end") {
-					if (onLive) {
-						try {
-							onLive({ kind: "tool_end", toolName: event.toolName ?? "unknown", isError: Boolean(event.isError) });
-						} catch { /* never throw from event handling */ }
-					}
-					if (event.isError) {
-						(currentResult.failedTools ??= []).push({
-							toolName: event.toolName ?? "unknown",
-							error: extractToolErrorText(event.result?.content),
-						});
-					}
-				}
-
-				if (event.type === "message_end" && event.message) {
-					const msg = event.message as Message;
-					currentResult.messages.push(msg);
-					if (msg.role === "assistant") {
-						currentResult.usage.turns++;
-						const usage = (msg as any).usage;
-						if (usage) {
-							currentResult.usage.input += usage.input || 0;
-							currentResult.usage.output += usage.output || 0;
-							currentResult.usage.cacheRead += usage.cacheRead || 0;
-							currentResult.usage.cacheWrite += usage.cacheWrite || 0;
-							currentResult.usage.cost += usage.cost?.total || 0;
-							currentResult.usage.contextTokens = usage.totalTokens || 0;
-						}
-						if (!currentResult.model && (msg as any).model) currentResult.model = (msg as any).model;
-						if ((msg as any).stopReason) currentResult.stopReason = (msg as any).stopReason;
-						if ((msg as any).errorMessage) currentResult.errorMessage = (msg as any).errorMessage;
-					}
-					// Live event: usage snapshot after accumulation
-					if (onLive) {
-						try {
-							onLive({ kind: "usage", usage: { ...currentResult.usage }, model: currentResult.model });
-						} catch { /* never throw from event handling */ }
-					}
-				}
-
-				if (event.type === "tool_result_end" && event.message) {
-					currentResult.messages.push(event.message as Message);
-				}
-			};
-			// Send the task through the child stdin pipe instead of the process
-			// command line. This avoids OS argument-length limits and does not
-			// require another temporary file for conversation data.
-			proc.stdin?.on("error", () => undefined);
-			proc.stdin?.end(`Task: ${task}`);
-
-			// Decode stdout through a StringDecoder so multi-byte UTF-8 characters
-			// (CJK, emoji) split across chunk boundaries never produce U+FFFD
-			// replacement characters — a corrupted JSON line would drop the whole
-			// message (including a reviewer's verdict line) from parsing.
-			const stdoutDecoder = new StringDecoder("utf8");
-			proc.stdout.on("data", (data) => {
-				lastActivityAt = Date.now();
-				buffer += stdoutDecoder.write(data);
-				const lines = buffer.split("\n");
-				buffer = lines.pop() || "";
-				for (const line of lines) processLine(line);
-			});
-
-			proc.stderr.on("data", (data) => {
-				currentResult.stderr += data.toString();
-			});
-
-			proc.on("close", (code) => {
-				// Flush any bytes still held by the decoder (a trailing incomplete
-				// multi-byte sequence) before processing the final buffer.
-				buffer += stdoutDecoder.end();
-				if (buffer.trim()) processLine(buffer);
-				// A null exit code means the process was terminated by a signal and
-				// must be reported as failure, never as a false clean completion.
-				const failed =
-					code !== 0 ||
-					wasAborted ||
-					(signal?.aborted ?? false) ||
-					currentResult.stopReason === "error" ||
-					currentResult.stopReason === "aborted";
-				if (onLive) {
-					try {
-						onLive({ kind: "status", status: failed ? "failed" : "done" });
-					} catch { /* never throw from event handling */ }
-				}
-				finish(code);
-			});
-
-			proc.on("error", () => {
-				// Spawn itself failed; close may never fire, so finish the run here.
-				currentResult.stopReason = "error";
-				currentResult.errorMessage ??= "Failed to start the sub-agent process.";
-				if (onLive) {
-					try {
-						onLive({ kind: "status", status: "failed" });
-					} catch { /* never throw from event handling */ }
-				}
-				finish(1);
-			});
-
-			if (idleTimeoutMs > 0) {
-				const checkInterval = Math.min(10_000, Math.floor(idleTimeoutMs / 3));
-				idleTimer = setInterval(() => {
-					if (closed) return;
-					if (Date.now() - lastActivityAt >= idleTimeoutMs) {
-						if (idleTimer) clearInterval(idleTimer);
-						currentResult.stopReason = "error";
-						currentResult.errorMessage = `Subagent idle timeout: no activity for ${Math.ceil(idleTimeoutMs / 1000)} seconds.`;
-						terminate();
-					}
-				}, checkInterval);
-			}
-
-			if (signal) {
-				abortHandler = (): void => {
-					wasAborted = true;
-					terminate();
-				};
-				if (signal.aborted) abortHandler();
-				else signal.addEventListener("abort", abortHandler, { once: true });
-			}
-		});
-
-		currentResult.exitCode = exitCode;
-		if (wasAborted) {
-			currentResult.stopReason = "aborted";
-			currentResult.errorMessage ??= "Subagent was aborted";
-			if (onLive) {
-				try {
-					onLive({ kind: "status", status: "failed" });
-				} catch { /* never throw from event handling */ }
-			}
-		}
-		return currentResult;
-	} finally {
-		if (tmpPromptPath)
-			try {
-				unlinkSync(tmpPromptPath);
-			} catch {
-				/* ignore */
-			}
-		if (tmpPromptDir)
-			try {
-				rmdirSync(tmpPromptDir);
-			} catch {
-				/* ignore */
-			}
-	}
-}
-
-/**
- * Run one agent with three layers of resilience against transient dispatch failures:
- *
- * 1. Startup retry (inner loop): a concurrent pi startup race can make the child
- *    exit before any model/tool activity. Relaunch with backoff so the startup
- *    lock clears. The SAME model is retried — the race is in the host, not the
- *    model — and only a clean, silent, zero-activity exit qualifies (see
- *    isRetryableStartupFailure), so retrying can never duplicate real work.
- * 2. Run-level retry on the SAME configured model (middle): when the provider
- *    rejects the model before producing output with a TRANSIENT error
- *    (503/429/timeout/network/stream/...) — i.e. NOT a terminal one (quota
- *    exhausted, billing, an invalid API key, auth rejected — see
- *    isTerminalModelError) — relaunch the whole run up to
- *    SUBAGENT_RUN_LEVEL_RETRY_DELAYS_MS.length more times with backoff, so a
- *    one-off provider hiccup recovers without demoting the configured agent
- *    model. Each relaunch gets its own inner startup-retry loop. This sits
- *    outside pi-ai's per-request provider retry, which by then has already
- *    tried (default 3 attempts) and given up.
- * 3. Model fallback (outer): when the same model is still failing after all its
- *    run-level retries, retry once with the main window's current model. The
- *    fallback gets its own startup-retry loop, since a startup race can hit any
- *    relaunch regardless of model.
- *
- * Terminal model errors short-circuit straight to the caller (modelRetries is
- * set): the account is the bottleneck, so neither same-model retry nor a
- * same-account fallback can help, and the run is left for the main agent to fix.
- *
- * The fallback is per-run only and never persisted: a transient provider hiccup
- * must not silently downgrade the configured agent model.
- */
-export async function runSingleAgentWithModelFallback(
-	options: RunSingleOptions,
-	fallbackModelRef?: string,
-): Promise<SingleResult> {
-	const agent = options.agent;
-	const launchedRef = agent?.model;
-	const startupDelays = options.startupRetryDelaysMs ?? SUBAGENT_STARTUP_RETRY_DELAYS_MS;
-	// Run-level retry is opted out of with an explicit empty array (e.g. a test
-	// that wants to assert ONLY the fallback path runs once); undefined means
-	// "use the default 5-attempt transient-error schedule".
-	const runDelays = options.runLevelRetryDelaysMs ?? SUBAGENT_RUN_LEVEL_RETRY_DELAYS_MS;
-
-	const runWithStartupRetry = async (opts: RunSingleOptions): Promise<SingleResult> => {
-		let lastResult: SingleResult;
-		let retries = 0;
-		for (let attempt = 0; ; attempt++) {
-			const start = Date.now();
-			lastResult = await runSingleAgent(opts);
-			const durationMs = Date.now() - start;
-			if (!isRetryableStartupFailure(lastResult, durationMs)) {
-				if (retries > 0 && !isFailedResult(lastResult)) lastResult.startupRetries = retries;
-				return lastResult;
-			}
-			const delay = startupDelays[attempt];
-			if (delay === undefined) {
-				// Exhausted: the agent never reached a model. Surface the concurrency-race
-				// cause as a dispatch-level failure (no model was ever reached, so this
-				// must NOT trigger run-level retry or model fallback) so the main agent
-				// can retry or lower maxConcurrency.
-				lastResult.errorMessage = formatStartupRetryExhaustedError(
-					lastResult.model ?? opts.agent?.model ?? "default",
-					attempt + 1,
-				);
-				lastResult.stopReason ??= "error";
-				lastResult.dispatchFailed = true;
-				return lastResult;
-			}
-			// Flip the live status back to running so the widget does not flash a
-			// false "failed" while we wait out the backoff and relaunch the child.
-			try {
-				opts.onLive?.({ kind: "status", status: "running" });
-			} catch { /* never throw from event handling */ }
-			const shouldRetry = await waitForStartupRetry(delay, opts.signal);
-			if (!shouldRetry) return lastResult;
-			retries++;
-		}
-	};
-
-	let result = await runWithStartupRetry(options);
-
-	// After a model-level failure, classify before reacting. A TERMINAL error
-	// (quota/billing/invalid key/auth) is account-scoped: neither same-model
-	// retry nor a same-account fallback can help, so hand the run straight back
-	// to the main agent instead of burning its time on a doomed retry.
-	if (agent && launchedRef && isModelLevelFailure(result) && isTerminalModelError(result)) return result;
-
-	// A TRANSIENT provider failure (503/429/timeout/network/stream/...) is usually
-	// a one-off hiccup. Relaunch the SAME configured model up to runDelays.length
-	// more times with backoff before degrading to a fallback model — the run's own
-	// provider retry already tried and failed, so each relaunch here is an
-	// independent, fresh attempt that can recover without losing the configured
-	// model's capability to review.
-	let modelRetries = 0;
-	if (agent && launchedRef && isModelLevelFailure(result) && runDelays.length > 0) {
-		for (let attempt = 0; ; attempt++) {
-			const delay = runDelays[attempt];
-			if (delay === undefined) break;
-			try {
-				options.onLive?.({ kind: "status", status: "running" });
-			} catch { /* never throw from event handling */ }
-			const shouldRetry = await waitForStartupRetry(delay, options.signal);
-			if (!shouldRetry) return { ...result, modelRetries };
-			const retried = await runWithStartupRetry(options);
-			modelRetries++;
-			if (!isModelLevelFailure(retried) || isTerminalModelError(retried)) {
-				// Each relaunch redoes the work; failedTools reflect ONLY the final
-				// attempt (no stale build errors from earlier transient failures),
-				// so the completion message's claim stays accurate.
-				return { ...retried, modelRetries };
-			}
-			result = retried;
-		}
-	}
-
-	// Same-model retries exhausted (or none configured) and still failing: fall
-	// back to the main window's current model exactly once. Skipped when there is
-	// no fallback ref or it equals the configured model — a same-ref rerun would
-	// just repeat the already-exhausted failure for nothing.
-	if (agent && launchedRef && fallbackModelRef && launchedRef !== fallbackModelRef && isModelLevelFailure(result)) {
-		const retried = await runWithStartupRetry({ ...options, agent: { ...agent, model: fallbackModelRef } });
-		// The fallback replaces the result wholesale: `retried.failedTools` reflect
-		// ONLY the fallback (final) attempt. The original attempt's failedTools are
-		// intentionally not merged — a fallback relaunch redoes the work, so attaching
-		// the first attempt's stale build errors to a clean final attempt would
-		// misattribute failures the worker already fixed. This makes the README's
-		// "failed tool calls from the run's final attempt" claim accurate.
-		return { ...retried, modelFallbackFrom: launchedRef, modelRetries };
-	}
-	return { ...result, modelRetries };
-}
+/**
+ * Sub-agent result handling and resilient RPC launch orchestration.
+ *
+ * The process transport itself lives in rpc-run.ts. Each attempt starts pi in
+ * persistent `--mode rpc`, sends commands over strict LF-delimited JSONL, and
+ * settles only on `agent_settled`. This module preserves the existing startup
+ * retry, same-model retry, model fallback, accounting, and result formatting
+ * contracts around those attempts.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+import type { AgentConfig } from "./agents.ts";
+import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
+import {
+	currentSubagentDepth,
+	DEPTH_ENV_VAR,
+	extractToolErrorText,
+	getPiInvocation,
+	RpcRunControl,
+	runRpcAgentAttempt,
+	sessionExists,
+	SUBAGENT_KILL_GRACE_MS,
+	type RpcSingleResult,
+	type SubagentLiveEvent,
+	type SubagentRecordEvent,
+	type UsageStats,
+} from "./rpc-run.ts";
+
+export {
+	currentSubagentDepth,
+	DEPTH_ENV_VAR,
+	extractToolErrorText,
+	getPiInvocation,
+	RpcRunControl,
+	sessionExists,
+	SUBAGENT_KILL_GRACE_MS,
+};
+export type { SubagentLiveEvent, SubagentRecordEvent, UsageStats };
+
+export const SUBAGENT_THINKING_LEVEL: ThinkingLevel = DEFAULT_THINKING_LEVEL;
+/** 0 disables the watchdog; dispatch supplies the configured timeout. */
+export const SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS = 0;
+export const SUBAGENT_STARTUP_RETRY_DELAYS_MS = [250, 750, 1500] as const;
+export const MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS = 2000;
+export const SUBAGENT_RUN_LEVEL_RETRY_DELAYS_MS = [2_000, 4_000, 8_000, 16_000, 30_000] as const;
+
+export interface SingleResult extends RpcSingleResult {}
+
+export interface SubagentDetails {
+	mode: "single" | "parallel";
+	results: SingleResult[];
+	background?: boolean;
+}
+
+export function getFinalOutput(messages: Message[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "text") return part.text;
+			}
+		}
+	}
+	return "";
+}
+
+/** Only the last standalone reviewer verdict line counts. */
+export function reviewVerdict(output: string): "pass" | "fail" | undefined {
+	const lines = output.split("\n");
+	for (let index = lines.length - 1; index >= 0; index--) {
+		const match = /^\s*VERDICT:\s*REVIEW_(PASS|FAIL)\s*$/i.exec(lines[index]);
+		if (match) return match[1].toUpperCase() === "PASS" ? "pass" : "fail";
+	}
+	return undefined;
+}
+
+export const RESULT_LINE_MAX = 200;
+
+export interface TruncatedOutput {
+	text: string;
+	truncated: boolean;
+}
+
+export function truncateResultOutput(output: string, maxLines: number): TruncatedOutput {
+	const lines = output.split("\n");
+	if (lines.length <= maxLines && lines.every((line) => line.length <= RESULT_LINE_MAX)) {
+		return { text: output, truncated: false };
+	}
+	const kept = lines.slice(0, maxLines).map((line) =>
+		line.length > RESULT_LINE_MAX ? `${line.slice(0, RESULT_LINE_MAX)}…` : line,
+	);
+	return { text: kept.join("\n"), truncated: true };
+}
+
+export function writeResultArtifact(output: string, agentName: string, cwd?: string): string {
+	const projectSlug = cwd ? basename(cwd).replace(/[^\w.-]+/g, "_") || "default" : "default";
+	const dir = join(tmpdir(), "pi-subagents-results", projectSlug);
+	mkdirSync(dir, { recursive: true });
+	const safeName = agentName.replace(/[^\w.-]+/g, "_");
+	const unique = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+	const filePath = join(dir, `${unique}-${safeName}.md`);
+	writeFileSync(filePath, output, "utf8");
+	return filePath;
+}
+
+export function isFailedResult(result: SingleResult): boolean {
+	if (result.parked) return false;
+	return result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+}
+
+function lastAssistantMessage(messages: Message[]): Extract<Message, { role: "assistant" }> | undefined {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index];
+		if (message.role === "assistant") return message;
+	}
+	return undefined;
+}
+
+function assistantText(message: Extract<Message, { role: "assistant" }>): string {
+	return message.content
+		.filter((part): part is Extract<(typeof message.content)[number], { type: "text" }> => part.type === "text")
+		.map((part) => part.text)
+		.join("");
+}
+
+export function isModelLevelFailure(result: SingleResult): boolean {
+	if (!isFailedResult(result)) return false;
+	if (result.stopReason === "aborted") return false;
+	if (result.dispatchFailed) return false;
+	if (result.integrationStatus === "retained") return false;
+	if (result.errorMessage?.includes("idle timeout")) return true;
+	if (result.rpcPromptRejected) return true;
+
+	// Classification belongs to the final assistant turn, not the whole attempt.
+	// Earlier useful text or failed tool calls are retained session history and
+	// must not hide a later provider error (for example a second-turn 503).
+	const finalAssistant = lastAssistantMessage(result.messages);
+	if (finalAssistant) {
+		if (finalAssistant.stopReason !== "error") return false;
+		if (assistantText(finalAssistant).trim()) return false;
+		return Boolean(
+			finalAssistant.errorMessage?.trim() ||
+			result.errorMessage?.trim() ||
+			result.stderr.trim() ||
+			finalAssistant.content.length === 0
+		);
+	}
+
+	if ((result.failedTools?.length ?? 0) > 0) return false;
+	return Boolean(result.errorMessage?.trim()) || result.stderr.trim().length > 0;
+}
+
+const TERMINAL_MODEL_ERROR_PATTERN =
+	/insufficient_quota|quota\s+exceeded|exceeded[^.\n]{0,40}quota|out\s+of\s+budget|billing|usage\s+limit|usage_limit|gousagelimiterror|freeusagelimiterror|monthly\s+usage\s+limit\s+reached|available\s+balance|invalid\s+(?:api\s+)?key|incorrect\s+api\s+key|unauthori[sz]ed|\b401\b|\b403\b|forbidden|permission\s+denied/i;
+const PERMANENT_MODEL_CANDIDATE_ERROR_PATTERN =
+	/model[_ -]?not[_ -]?found|no\s+models?\s+(?:found|matched)|(?:model|provider)[^.\n]{0,80}(?:not\s+found|unknown|does\s+not\s+exist|unsupported|invalid)|(?:not\s+found|unknown|unsupported|invalid)[^.\n]{0,40}(?:model|provider)|\b404\b/i;
+
+export function isTerminalModelError(result: SingleResult): boolean {
+	const message = result.errorMessage?.trim();
+	if (message) return TERMINAL_MODEL_ERROR_PATTERN.test(message);
+	const stderr = result.stderr.trim();
+	return stderr.length > 0 && TERMINAL_MODEL_ERROR_PATTERN.test(stderr);
+}
+
+/** A permanent failure of this model/provider reference (stale id, unknown
+ * provider, 404 config route). Skip same-candidate backoff, but keep advancing
+ * through backup and current-main candidates. */
+export function isPermanentModelCandidateError(result: SingleResult): boolean {
+	const message = result.errorMessage?.trim();
+	if (message) return PERMANENT_MODEL_CANDIDATE_ERROR_PATTERN.test(message);
+	const stderr = result.stderr.trim();
+	return stderr.length > 0 && PERMANENT_MODEL_CANDIDATE_ERROR_PATTERN.test(stderr);
+}
+
+export function isRetryableStartupFailure(result: SingleResult, durationMs: number): boolean {
+	if (result.exitCode === 0) return false;
+	if (result.stopReason === "aborted") return false;
+	if (result.dispatchFailed) return false;
+	if (result.errorMessage?.includes("idle timeout")) return false;
+	if (getFinalOutput(result.messages)) return false;
+	if (result.messages.length > 0) return false;
+	const usage = result.usage;
+	if (usage.turns || usage.input || usage.output || usage.cacheRead || usage.cacheWrite || usage.cost) return false;
+	if (durationMs > MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS) return false;
+	if (result.stderr.trim().length > 0) return false;
+	if (result.errorMessage && result.errorMessage.trim().length > 0) return false;
+	return true;
+}
+
+export function formatStartupRetryExhaustedError(model: string, attempts: number): string {
+	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child exited before any model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or temporarily lower maxConcurrency in /subagents-setup.`;
+}
+
+export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal): Promise<boolean> {
+	if (delayMs <= 0) return !signal?.aborted;
+	if (!signal) {
+		return new Promise<boolean>((resolve) => {
+			const timer = setTimeout(() => resolve(true), delayMs);
+			if (typeof timer.unref === "function") timer.unref();
+		});
+	}
+	if (signal.aborted) return false;
+	return new Promise<boolean>((resolve) => {
+		let settled = false;
+		const finish = (shouldRetry: boolean): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+			resolve(shouldRetry);
+		};
+		const onAbort = (): void => finish(false);
+		const timer = setTimeout(() => finish(true), delayMs);
+		if (typeof timer.unref === "function") timer.unref();
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+async function waitForControlledRetry(
+	delayMs: number,
+	signal: AbortSignal | undefined,
+	control: RpcRunControl | undefined,
+): Promise<boolean> {
+	let remaining = delayMs;
+	while (remaining > 0) {
+		if (control?.isParkRequested() || control?.isStopRequested()) return false;
+		const slice = Math.min(remaining, 50);
+		if (!(await waitForStartupRetry(slice, signal))) return false;
+		remaining -= slice;
+	}
+	return !signal?.aborted && !control?.isParkRequested() && !control?.isStopRequested();
+}
+
+export function getResultOutput(result: SingleResult): string {
+	if (isFailedResult(result)) {
+		const error = result.errorMessage || result.stderr;
+		const partial = getFinalOutput(result.messages);
+		if (error && partial) return `${error}\n\n--- Partial output ---\n${partial}`;
+		return error || partial || "(no output)";
+	}
+	return getFinalOutput(result.messages) || "(no output)";
+}
+
+export function buildResumePrompt(task: string, reason: string): string {
+	return `You are resuming an earlier sub-agent session after ${reason}. Your earlier work — searches, reads, edits, and reasoning — is preserved in this session's history above; review it before acting. Original task: ${task}. Pick up exactly where you left off and finish it. Do NOT redo searches, reads, or edits you already completed unless a step clearly failed. Continue now.`;
+}
+
+export function buildFallbackResumeReason(fromModel?: string): string {
+	return fromModel
+		? `the previous model (${fromModel}) failed at the model/provider level, so the next model in its configured pool is continuing`
+		: "the previous model failed at the model/provider level, so the next model in its configured pool is continuing";
+}
+
+export interface RunSingleOptions {
+	defaultCwd: string;
+	agent: AgentConfig | undefined;
+	agentName: string;
+	task: string;
+	cwd?: string;
+	thinkingLevel?: ThinkingLevel;
+	idleTimeoutMs?: number;
+	startupRetryDelaysMs?: readonly number[];
+	runLevelRetryDelaysMs?: readonly number[];
+	sessionDir?: string;
+	sessionId?: string;
+	/** Initial RPC prompt. Kept under the old name to limit caller churn. */
+	stdinText?: string;
+	signal?: AbortSignal;
+	onLive?: (event: SubagentLiveEvent) => void;
+	/** Receives the raw streamed text/thinking deltas for the inspector
+	 * transcript; forwarded to the transport alongside onLive. */
+	onRecord?: (event: SubagentRecordEvent) => void;
+	makeDetails: (results: SingleResult[]) => SubagentDetails;
+	env?: NodeJS.ProcessEnv;
+	/** Stable logical-generation controller shared across retry attempts. */
+	control?: RpcRunControl;
+}
+
+function controlledDisposition(options: RunSingleOptions, base?: SingleResult): SingleResult | undefined {
+	const control = options.control;
+	if (!control?.isParkRequested() && !control?.isStopRequested()) return undefined;
+	const result: SingleResult = base ?? {
+		agent: options.agentName,
+		agentSource: options.agent?.source ?? "unknown",
+		task: control.getObjective(),
+		exitCode: 0,
+		messages: [],
+		stderr: "",
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+		model: options.agent?.model,
+		thinking: options.thinkingLevel,
+		sessionId: options.sessionId,
+		sessionDir: options.sessionDir,
+	};
+	result.task = control.getObjective();
+	if (control.isParkRequested()) {
+		result.parked = true;
+		result.exitCode = 0;
+		result.stopReason = undefined;
+		result.errorMessage = undefined;
+	} else {
+		result.parked = undefined;
+		result.exitCode = 1;
+		result.stopReason = "aborted";
+		result.errorMessage = control.getStopMessage();
+	}
+	return result;
+}
+
+/** Spawn one RPC attempt and wait for stable settlement. */
+export async function runSingleAgent(options: RunSingleOptions): Promise<SingleResult> {
+	const {
+		agent,
+		agentName,
+		thinkingLevel = SUBAGENT_THINKING_LEVEL,
+		idleTimeoutMs = SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS,
+		control,
+	} = options;
+	if (!agent) {
+		return {
+			agent: agentName,
+			agentSource: "unknown",
+			task: options.task,
+			exitCode: 1,
+			messages: [],
+			stderr: `Unknown agent: "${agentName}".`,
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+		};
+	}
+
+	const disposition = controlledDisposition(options);
+	if (disposition) return disposition;
+	const objective = control?.getObjective() ?? options.task;
+	let prompt = options.stdinText ?? `Task: ${objective}`;
+	if (control && objective !== options.task) {
+		prompt = options.sessionDir && sessionExists(options.sessionDir, options.sessionId ?? "")
+			? `Abandon the previous objective. New objective: ${objective}`
+			: `Task: ${objective}`;
+	}
+	const result = await runRpcAgentAttempt({
+		defaultCwd: options.defaultCwd,
+		agent,
+		agentName,
+		task: objective,
+		cwd: options.cwd,
+		thinkingLevel,
+		idleTimeoutMs,
+		sessionDir: options.sessionDir,
+		sessionId: options.sessionId,
+		prompt,
+		signal: options.signal,
+		onLive: options.onLive,
+		onRecord: options.onRecord,
+		env: options.env,
+		control,
+	});
+	result.task = control?.getObjective() ?? result.task;
+	return result;
+}
+
+/**
+ * Run one logical generation across an ordered model pool. Every candidate gets
+ * startup retries plus same-model retries for transient provider failures;
+ * terminal model errors skip those retries and advance immediately. All
+ * candidates resume the same retained pi session.
+ */
+export async function runSingleAgentWithModelFallback(
+	options: RunSingleOptions,
+	fallbackModelRefs: readonly string[] = [],
+): Promise<SingleResult> {
+	const agent = options.agent;
+	const launchedRef = agent?.model;
+	const startupDelays = options.startupRetryDelaysMs ?? SUBAGENT_STARTUP_RETRY_DELAYS_MS;
+	const runDelays = options.runLevelRetryDelaysMs ?? SUBAGENT_RUN_LEVEL_RETRY_DELAYS_MS;
+
+	const sessionId = options.sessionId ?? randomUUID();
+	const sessionDir = options.sessionDir ?? (await mkdtemp(join(tmpdir(), "pi-subagent-session-")));
+	const baseOptions: RunSingleOptions = { ...options, sessionDir, sessionId };
+
+	const dispatchFailure = async (error: unknown): Promise<SingleResult> => {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		const hasSession = sessionExists(sessionDir, sessionId);
+		if (!hasSession && !options.sessionDir) {
+			await rm(sessionDir, { recursive: true, force: true }).catch(() => undefined);
+		}
+		return {
+			agent: options.agentName,
+			agentSource: options.agent?.source ?? "unknown",
+			task: options.control?.getObjective() ?? options.task,
+			exitCode: 1,
+			messages: [],
+			stderr: errorMessage,
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			model: options.agent?.model,
+			thinking: options.thinkingLevel,
+			stopReason: "error",
+			errorMessage,
+			dispatchFailed: true,
+			...(hasSession || options.sessionDir ? { sessionId, sessionDir } : {}),
+		};
+	};
+
+	const runWithStartupRetry = async (opts: RunSingleOptions): Promise<SingleResult> => {
+		let lastResult: SingleResult;
+		let retries = 0;
+		for (let attempt = 0; ; attempt++) {
+			const immediate = controlledDisposition(opts);
+			if (immediate) {
+				if (immediate.parked && !options.sessionDir && !sessionExists(sessionDir, sessionId)) {
+					await rm(sessionDir, { recursive: true, force: true }).catch(() => undefined);
+					immediate.sessionId = undefined;
+					immediate.sessionDir = undefined;
+				}
+				return immediate;
+			}
+			const start = Date.now();
+			try {
+				lastResult = await runSingleAgent(opts);
+			} catch (error) {
+				const failed = await dispatchFailure(error);
+				return controlledDisposition(opts, failed) ?? failed;
+			}
+			const durationMs = Date.now() - start;
+			const controlled = controlledDisposition(opts, lastResult);
+			if (controlled) return controlled;
+			if (lastResult.parked || lastResult.stopReason === "aborted") return lastResult;
+			if (!isRetryableStartupFailure(lastResult, durationMs)) {
+				if (retries > 0 && !isFailedResult(lastResult)) lastResult.startupRetries = retries;
+				return lastResult;
+			}
+			const delay = startupDelays[attempt];
+			if (delay === undefined) {
+				lastResult.errorMessage = formatStartupRetryExhaustedError(
+					lastResult.model ?? opts.agent?.model ?? "default",
+					attempt + 1,
+				);
+				lastResult.stopReason ??= "error";
+				lastResult.dispatchFailed = true;
+				return lastResult;
+			}
+			opts.control?.markRetrying();
+			try {
+				opts.onLive?.({ kind: "status", status: "running" });
+			} catch {
+				/* never throw from event handling */
+			}
+			if (!(await waitForControlledRetry(delay, opts.signal, opts.control))) {
+				return controlledDisposition(opts, lastResult) ?? lastResult;
+			}
+			retries++;
+		}
+	};
+
+	const fallbackRefs: string[] = [];
+	const seenRefs = new Set<string>();
+	if (launchedRef?.trim()) seenRefs.add(launchedRef.trim());
+	for (const candidate of fallbackModelRefs) {
+		const ref = candidate.trim();
+		if (!ref || seenRefs.has(ref)) continue;
+		seenRefs.add(ref);
+		fallbackRefs.push(ref);
+	}
+
+	const candidates: Array<{ agent: AgentConfig | undefined; ref?: string }> = [
+		{ agent, ref: launchedRef?.trim() || undefined },
+	];
+	if (agent) {
+		for (const ref of fallbackRefs) candidates.push({ agent: { ...agent, model: ref }, ref });
+	}
+
+	let modelRetries = 0;
+	let fallbackUsed = false;
+	let result: SingleResult | undefined;
+
+	const finish = async (settled: SingleResult): Promise<SingleResult> => {
+		const persistedSession = sessionExists(sessionDir, sessionId);
+		if (!settled.dispatchFailed || persistedSession || options.sessionDir) {
+			settled.sessionId ??= sessionId;
+			settled.sessionDir ??= sessionDir;
+		} else {
+			await rm(sessionDir, { recursive: true, force: true }).catch(() => undefined);
+			settled.sessionId = undefined;
+			settled.sessionDir = undefined;
+		}
+		settled.task = options.control?.getObjective() ?? settled.task;
+		if (fallbackUsed && launchedRef) settled.modelFallbackFrom = launchedRef;
+		settled.modelRetries = modelRetries;
+		options.control?.markSettled();
+		return settled;
+	};
+
+	for (let candidateIndex = 0; candidateIndex < candidates.length; candidateIndex++) {
+		const candidate = candidates[candidateIndex];
+		fallbackUsed ||= candidateIndex > 0;
+		const previousModel = result?.model ?? candidates[candidateIndex - 1]?.ref;
+		const candidateOptions: RunSingleOptions = {
+			...baseOptions,
+			agent: candidate.agent,
+			...(candidateIndex > 0
+				? {
+					stdinText: buildResumePrompt(
+						options.control?.getObjective() ?? options.task,
+						buildFallbackResumeReason(previousModel),
+					),
+				}
+				: {}),
+		};
+		try {
+			options.onLive?.({
+				kind: "model",
+				model: candidate.ref,
+				...(candidateIndex > 0 && launchedRef ? { fallbackFrom: launchedRef } : {}),
+			});
+		} catch {
+			/* never throw from event handling */
+		}
+
+		result = await runWithStartupRetry(candidateOptions);
+		if (result.parked || result.stopReason === "aborted") return result;
+		if (!isModelLevelFailure(result)) return finish(result);
+
+		if (!isTerminalModelError(result) && !isPermanentModelCandidateError(result)) {
+			const retryOptions: RunSingleOptions = {
+				...candidateOptions,
+				stdinText: buildResumePrompt(
+					options.control?.getObjective() ?? options.task,
+					"a transient provider error on the same model",
+				),
+			};
+			for (const delay of runDelays) {
+				baseOptions.control?.markRetrying();
+				try {
+					options.onLive?.({ kind: "status", status: "running" });
+				} catch {
+					/* never throw from event handling */
+				}
+				if (!(await waitForControlledRetry(delay, options.signal, options.control))) {
+					return controlledDisposition(baseOptions, result) ?? result;
+				}
+				result = await runWithStartupRetry(retryOptions);
+				modelRetries++;
+				if (result.parked || result.stopReason === "aborted") return result;
+				if (
+					!isModelLevelFailure(result) ||
+					isTerminalModelError(result) ||
+					isPermanentModelCandidateError(result)
+				) break;
+			}
+		}
+
+		if (!isModelLevelFailure(result)) return finish(result);
+		// Transient exhaustion plus terminal/permanent candidate errors advance
+		// to the next configured candidate. Ordinary task/tool failures returned above.
+	}
+
+	return finish(result ?? (await dispatchFailure("No model candidate was attempted.")));
+}