pi-crew 0.11.6 → 0.11.8

package/src/runtime/rpc/frame-client.ts

@@ -0,0 +1,328 @@
+/**
+ * frame-client.ts — W7 (P2-3): strict-LF JSONL frame client for the pi RPC mode.
+ *
+ * WHY NOT the SDK's `RpcClient` (deviation recorded in README.md / review §R2.5):
+ *  1. It has NO public API to answer `extension_ui_request` records
+ *     (`send`/`process` are private; handleLine dispatches non-response records
+ *     to event listeners only) — answering dialogs is design gate 2.
+ *  2. Its `start()` spawns `node <cliPath|dist/cli.js>` cwd-relative — NOT the
+ *     host pi binary the stdio transport resolves via getPiSpawnCommand, so the
+ *     two transports would run different pi versions.
+ *  3. The process is not injectable — the W7 packet REQUIRES fake-stream tests
+ *     (no real pi spawn), which RpcClient makes impossible.
+ * The PROTOCOL SURFACE is still the SDK's: every record type here is imported
+ * from `@earendil-works/pi-coding-agent` (RpcCommand/RpcResponse/
+ * RpcExtensionUIRequest/RpcExtensionUIResponse), and the framing follows the
+ * SDK's own jsonl spec.
+ *
+ * FRAMING (SDK modes/rpc/jsonl.d.ts): records are LF-only. Payload strings may
+ * contain U+2028/U+2029, so splitting MUST be on "\n" ONLY — Node's readline
+ * splits on those separators too and is therefore NOT strict JSONL framing.
+ * This module hand-rolls the ~15-line splitter for exactly that reason.
+ *
+ * Robustness contract (prototype, but honest): a malformed line is COUNTED and
+ * dropped — never thrown; a matching valid frame afterwards still resolves.
+ */
+
+import { spawn } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+import type { RpcCommand, RpcExtensionUIRequest, RpcExtensionUIResponse } from "@earendil-works/pi-coding-agent";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { getPiSpawnCommand } from "../pi-spawn.ts";
+import { createUiRequestPolicy, type DialogAnswerPolicy, type UiRequestCounters } from "./ui-request-policy.ts";
+
+/** Cap on retained raw stdout/stderr text (prototype memory guard). */
+const RAW_OUTPUT_CAP_CHARS = 1_000_000;
+/** Default per-command response timeout — mirrors the SDK RpcClient's 30s. */
+const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
+/** Default orderly-shutdown window before SIGKILL fallback. */
+const DEFAULT_STOP_TIMEOUT_MS = 5_000;
+
+/** Process handle the frame client drives. Injectable for fake-stream tests. */
+export interface RpcSpawnHandle {
+	stdin: Writable;
+	stdout: Readable;
+	stderr: Readable;
+	/** Resolves with the exit code (null when killed by signal). */
+	exit: Promise<number | null>;
+	/** Send a signal. Must be idempotent-safe (client guards to kill once). */
+	kill(signal?: NodeJS.Signals): void;
+}
+
+/** Spawn function: receives the pi argv (after `--mode rpc` etc.), returns a handle. */
+export type RpcSpawnFn = (argv: string[]) => RpcSpawnHandle;
+
+/** Default spawner: host pi binary (PI_TEAMS_PI_BIN aware) with piped stdio. */
+function defaultSpawnFn(argv: string[]): RpcSpawnHandle {
+	const { command, args } = getPiSpawnCommand(argv);
+	const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+	return {
+		stdin: child.stdin as Writable,
+		stdout: child.stdout as Readable,
+		stderr: child.stderr as Readable,
+		exit: new Promise<number | null>((resolve) => {
+			child.once("exit", (code) => resolve(code));
+		}),
+		kill: (signal?: NodeJS.Signals) => {
+			try {
+				child.kill(signal ?? "SIGKILL");
+			} catch (error) {
+				logInternalError("rpc-frame-client.kill", error, "child.kill failed", "warn");
+			}
+		},
+	};
+}
+
+/** Combined transport counters (frame client + ui-request policy). */
+export interface RpcTransportCounters extends UiRequestCounters {
+	/** Frames that failed JSON.parse (or were empty lines). */
+	malformedFrames: number;
+	/** Response records matched to a pending command. */
+	responsesMatched: number;
+	/** Response records with an unknown/duplicate id (dropped). */
+	responsesUnmatched: number;
+}
+
+export interface RpcFrameClientOptions {
+	/** Injectable spawner (tests pass a fake-stream factory). Default: host pi binary. */
+	spawnFn?: RpcSpawnFn;
+	/** pi argv WITHOUT the binary (client prepends nothing; default ["--mode","rpc"]). */
+	argv?: string[];
+	/** GATE 2 dialog policy. Default "cancel" (universal safe answer). */
+	dialogPolicy?: DialogAnswerPolicy;
+	/** Per-command response timeout (ms). Default 30_000. */
+	commandTimeoutMs?: number;
+	/** Orderly-shutdown timeout before SIGKILL (ms). Default 5_000. */
+	stopTimeoutMs?: number;
+	/** Non-response, non-ui-request records (agent session events, extension_error). */
+	onEvent?: (event: unknown) => void;
+}
+
+interface PendingCommand {
+	resolve: (response: unknown) => void;
+	reject: (error: Error) => void;
+	timer: NodeJS.Timeout;
+}
+
+export interface RpcFrameClient {
+	/** Send a command; resolves with the success response, rejects on error/timeout. */
+	sendCommand(command: RpcCommand): Promise<unknown>;
+	/** Write an extension_ui_response directly (policy uses this). */
+	sendUiResponse(response: RpcExtensionUIResponse): void;
+	/** Counters snapshot (fresh object). */
+	counters(): RpcTransportCounters;
+	/** Retained raw stdout text (capped). */
+	stdoutText(): string;
+	/** Retained raw stderr text (capped). */
+	stderrText(): string;
+	/** The exit promise (resolves when the process exits). */
+	exited(): Promise<number | null>;
+	/** Orderly stop: end stdin → wait exit → SIGKILL fallback. Idempotent. */
+	stop(): Promise<void>;
+}
+
+function appendCapped(current: string, chunk: string): string {
+	const next = current + chunk;
+	return next.length > RAW_OUTPUT_CAP_CHARS ? next.slice(0, RAW_OUTPUT_CAP_CHARS) : next;
+}
+
+export function createRpcFrameClient(options: RpcFrameClientOptions = {}): RpcFrameClient {
+	const spawnFn = options.spawnFn ?? defaultSpawnFn;
+	const argv = options.argv ?? ["--mode", "rpc"];
+	const commandTimeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+	const stopTimeoutMs = options.stopTimeoutMs ?? DEFAULT_STOP_TIMEOUT_MS;
+
+	const handle = spawnFn(argv);
+
+	let stdoutText = "";
+	let stderrText = "";
+	let malformedFrames = 0;
+	let responsesMatched = 0;
+	let responsesUnmatched = 0;
+	let killed = false;
+	let stopPromise: Promise<void> | undefined;
+
+	const pending = new Map<string, PendingCommand>();
+	let sequence = 0;
+
+	const uiPolicy = createUiRequestPolicy({
+		dialogPolicy: options.dialogPolicy ?? "cancel",
+		writeResponse: (response) => writeUiResponse(response),
+		onWarn: (message) => logInternalError("rpc-frame-client.ui-policy", new Error(message), undefined, "warn"),
+	});
+
+	function writeLine(record: unknown): void {
+		try {
+			// void-append: the write is fire-and-forget; stream errors are
+			// handled by the stdin "error" listener below.
+			handle.stdin.write(`${JSON.stringify(record)}\n`);
+		} catch (error) {
+			logInternalError("rpc-frame-client.write", error, "stdin write failed", "warn");
+		}
+	}
+
+	function writeUiResponse(response: RpcExtensionUIRequest | RpcExtensionUIResponse): void {
+		writeLine(response);
+	}
+
+	function failPending(error: Error): void {
+		for (const entry of pending.values()) {
+			clearTimeout(entry.timer);
+			entry.reject(error);
+		}
+		pending.clear();
+	}
+
+	function handleLine(line: string): void {
+		if (line.length === 0) {
+			malformedFrames++;
+			return;
+		}
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			malformedFrames++;
+			logInternalError("rpc-frame-client.frame", new Error(`malformed frame dropped (${line.length} chars)`), undefined, "warn");
+			return;
+		}
+		const record = parsed as Record<string, unknown>;
+		if (record && record.type === "response") {
+			const id = typeof record.id === "string" ? record.id : undefined;
+			const entry = id !== undefined ? pending.get(id) : undefined;
+			if (id === undefined || entry === undefined) {
+				responsesUnmatched++;
+				return;
+			}
+			pending.delete(id);
+			clearTimeout(entry.timer);
+			responsesMatched++;
+			if (record.success === false) {
+				entry.reject(new Error(`rpc command failed: ${String(record.error ?? "unknown error")}`));
+			} else {
+				entry.resolve(record);
+			}
+			return;
+		}
+		if (record && record.type === "extension_ui_request") {
+			// Gate 1 + Gate 2 live here (count+drop / auto-answer).
+			uiPolicy.handle(parsed as RpcExtensionUIRequest);
+			return;
+		}
+		// Agent session events (`message_start`, `agent_settled`, ...) and
+		// anything else the server emits (e.g. extension_error).
+		options.onEvent?.(parsed);
+	}
+
+	function waitExitWithin(ms: number): Promise<boolean> {
+		return Promise.race([handle.exit.then(() => true), new Promise<boolean>((r) => setTimeout(() => r(false), ms))]);
+	}
+
+	function killOnce(): void {
+		if (killed) return;
+		killed = true;
+		handle.kill("SIGKILL");
+	}
+
+	// ── stdout pump: STRICT LF-only framing (see module header). ──────────
+	let buffer = "";
+	handle.stdout.setEncoding("utf8");
+	handle.stdout.on("data", (chunk: string) => {
+		stdoutText = appendCapped(stdoutText, chunk);
+		buffer += chunk;
+		let newlineAt = buffer.indexOf("\n");
+		while (newlineAt >= 0) {
+			const line = buffer.slice(0, newlineAt);
+			buffer = buffer.slice(newlineAt + 1);
+			handleLine(line);
+			newlineAt = buffer.indexOf("\n");
+		}
+	});
+	// Final flush + pending-failure. "end" covers orderly EOF; "close" also
+	// fires on destroy() (killed stream) where "end" never does — both paths
+	// must drain the leftover buffer and fail any still-pending commands.
+	let streamFinalized = false;
+	function finalizeStream(): void {
+		if (streamFinalized) return;
+		streamFinalized = true;
+		if (buffer.length > 0) {
+			// Final line without trailing LF: the server always writes LF, so a
+			// non-empty remainder means an abrupt cut — try to parse it anyway
+			// (a complete JSON object missing only the terminator is usable),
+			// otherwise it lands in malformedFrames.
+			const line = buffer;
+			buffer = "";
+			handleLine(line);
+		}
+		failPending(new Error("rpc transport: stdout closed before response"));
+	}
+	handle.stdout.on("end", () => finalizeStream());
+	handle.stdout.on("close", () => finalizeStream());
+	handle.stdout.on("error", (error) => {
+		logInternalError("rpc-frame-client.stdout", error, undefined, "warn");
+		failPending(new Error(`rpc transport: stdout error: ${error.message}`));
+	});
+
+	handle.stderr.setEncoding("utf8");
+	handle.stderr.on("data", (chunk: string) => {
+		stderrText = appendCapped(stderrText, chunk);
+	});
+	handle.stderr.on("error", (error) => {
+		logInternalError("rpc-frame-client.stderr", error, undefined, "warn");
+	});
+
+	// A dead stdin (EPIPE when the child exits first) must not crash the host.
+	handle.stdin.on("error", (error) => {
+		logInternalError("rpc-frame-client.stdin", error, undefined, "warn");
+	});
+
+	const client: RpcFrameClient = {
+		sendCommand(command: RpcCommand): Promise<unknown> {
+			sequence++;
+			const id = `pi-crew-rpc-${sequence}`;
+			const record = { id, ...command } as RpcCommand;
+			return new Promise((resolve, reject) => {
+				const timer = setTimeout(() => {
+					pending.delete(id);
+					reject(new Error(`rpc command timeout after ${commandTimeoutMs}ms: ${command.type}`));
+				}, commandTimeoutMs);
+				pending.set(id, { resolve, reject, timer });
+				writeLine(record);
+			});
+		},
+		sendUiResponse(response: RpcExtensionUIResponse): void {
+			writeUiResponse(response);
+		},
+		counters(): RpcTransportCounters {
+			return {
+				...uiPolicy.counters(),
+				malformedFrames,
+				responsesMatched,
+				responsesUnmatched,
+			};
+		},
+		stdoutText: () => stdoutText,
+		stderrText: () => stderrText,
+		exited: () => handle.exit,
+		stop(): Promise<void> {
+			if (stopPromise) return stopPromise;
+			stopPromise = (async () => {
+				// Orderly shutdown (rpc-mode.js onInputEnd → server shutdown,
+				// exit 0 per R2 live evidence): close stdin, wait, then kill.
+				try {
+					handle.stdin.end();
+				} catch (error) {
+					logInternalError("rpc-frame-client.stop", error, "stdin.end failed", "warn");
+				}
+				const exitedCleanly = await waitExitWithin(stopTimeoutMs);
+				if (!exitedCleanly) {
+					killOnce();
+					await waitExitWithin(2_000);
+				}
+				failPending(new Error("rpc transport stopped"));
+			})();
+			return stopPromise;
+		},
+	};
+	return client;
+}

package/src/runtime/rpc/rpc-worker.ts

@@ -0,0 +1,271 @@
+/**
+ * rpc-worker.ts — W7 (P2-3): EXPERIMENTAL RPC worker transport.
+ *
+ * STATUS — WIRED at the run-worker seam behind PI_CREW_WORKER_TRANSPORT=rpc
+ * (integration phase, 2026-10-04), after a LIVE-FIRE probe against a real
+ * `pi --mode rpc` process came back GREEN on all four probe items:
+ *   (a) extension_ui_request drain: 24 drained (setStatus×20, setWidget×3,
+ *       notify×1 — pi-crew extension widgets visible in the raw frames);
+ *   (b) prompt round-trip: ack 24ms, agent_settled 4.2s, rawFinalText="OK";
+ *   (c) dialog (confirm) auto-answered by the "cancel" policy
+ *       (extension_ui_response cancelled:true → ui.confirm resolved false →
+ *       the model literally echoed "false"), NO deadlock (settled 1.7s);
+ *   (d) steer mid-turn: disposition "queued", RTT 53ms, final text honored
+ *       ("STOP"); all runs exited 0 with orderly stdin-end shutdown.
+ * Raw probe artifacts: /tmp/rpc-lf/probe1{,b}.{log,stdout.txt,stderr.txt},
+ * probe2.*, probe3.* (2026-10-04, lane D6).
+ *
+ * runRpcWorker: prompt → collect session events until `agent_settled` →
+ * orderly stop → map to ChildPiRunResult. Abort/steer signals send the RPC
+ * `abort` command before stopping. If the transport fails BEFORE any agent
+ * output (early spawn/handshake failure), runWorker falls back to the stdio
+ * transport (structured warn, no double-execution of a consumed task).
+ *
+ * LIFECYCLE HARDENING (DR1/DR5, deep-review 2026-10-05 §2):
+ * - DR1 settle-hang: the settle wait is RACED against `client.exited()` and
+ *   a belt-and-suspenders turn timeout — a child that crashes after the
+ *   prompt was accepted (or stays live-but-silent) can no longer hold the
+ *   await open forever (and with it the global worker-cap slot). Both
+ *   losers map to the early-failure result shape so the stdio fallback
+ *   engages and the slot is released.
+ * - DR5 double-execution: `SettleTracking.agentStarted` records that a
+ *   session event was observed after the prompt was sent; a failure in that
+ *   state is NEVER retried (surfaced via result.rpcAgentStarted — see
+ *   isEarlyRpcTransportFailure), closing the started-but-no-text window.
+ */
+
+import { getCrewEnv, getCrewEnvInt } from "../../config/env-vars.ts";
+import type { ChildPiRunResult } from "../child-pi/child-pi.ts";
+import { createRpcFrameClient, type RpcFrameClientOptions } from "./frame-client.ts";
+import type { DialogAnswerPolicy } from "./ui-request-policy.ts";
+
+/** Env knob selecting the transport at the run-worker seam. */
+export const WORKER_TRANSPORT_ENV = "PI_CREW_WORKER_TRANSPORT";
+/** Env knob for the dialog auto-answer policy (GATE 2). */
+export const RPC_DIALOG_ANSWER_ENV = "PI_CREW_RPC_DIALOG_ANSWER";
+/** Env knob for the DR1 turn timeout (ms) — env-only, RPC stays experimental. */
+export const RPC_TURN_TIMEOUT_ENV = "PI_CREW_RPC_TURN_TIMEOUT_MS";
+/** Default DR1 turn bound: 10 minutes (registry default mirrors this literal). */
+export const DEFAULT_RPC_TURN_TIMEOUT_MS = 600_000;
+
+export type WorkerTransport = "stdio" | "rpc";
+
+/** Minimal surface of runWorker's input the RPC path consumes. */
+export interface RpcWorkerInput {
+	cwd?: string;
+	task: string;
+	model?: string;
+	signal?: AbortSignal;
+	/** Optional client overrides (tests inject a fake spawner + tiny timeouts). */
+	rpc?: Pick<RpcFrameClientOptions, "spawnFn" | "argv" | "commandTimeoutMs" | "stopTimeoutMs" | "dialogPolicy">;
+}
+
+/**
+ * Live-fire argv for the RPC transport (probe-verified 2026-10-04).
+ *
+ * `--no-session` is the SAFE prototype default: a worker spawned without
+ * deterministic session identity (`--session-id`/`--session-dir` — stdio-only
+ * today, see pi-args.ts W2) would otherwise attach to the cwd project's
+ * DEFAULT session and pollute the user's live session. Ephemeral workers are
+ * correct worker semantics until rpc-mode session identity is designed.
+ *
+ * Limitation vs the stdio argv (documented, deliberate): the model string is
+ * passed RAW — no applyThinkingSuffix composition, no agent/system-prompt
+ * files, no hermetic flags. Those remain stdio-only until each is probed.
+ */
+export function buildRpcWorkerArgv(model?: string): string[] {
+	const argv = ["--mode", "rpc", "--no-session"];
+	if (model) argv.push("--model", model);
+	return argv;
+}
+
+/**
+ * Resolve the worker transport. Precedence: env > config > default stdio
+ * (the repo's established order — the env var stays the live experimental
+ * gate and WINS over config whenever it is set, even when its value is
+ * invalid: an operator who sets PI_CREW_WORKER_TRANSPORT is driving via env,
+ * so the config value is not consulted behind their back). The config value
+ * (runtime.workerTransport, threaded to the seam via WorkerSpawnInput by the
+ * callers that carry runtimeConfig — D1/DR2) applies only when env is unset.
+ * FAILSAFE: anything other than exactly "rpc" (after trim) resolves to the
+ * default stdio transport.
+ */
+export function resolveWorkerTransport(
+	configValue?: WorkerTransport,
+	read: (name: string) => string | undefined = getCrewEnv,
+): WorkerTransport {
+	const raw = read(WORKER_TRANSPORT_ENV)?.trim();
+	if (raw === "rpc") return "rpc";
+	if (raw === "stdio") return "stdio";
+	if (raw !== undefined) return "stdio"; // env set but invalid → failsafe stdio
+	return configValue === "rpc" ? "rpc" : "stdio";
+}
+
+/**
+ * Resolve the dialog auto-answer policy (GATE 2). "cancel" (default) is the
+ * universal safe answer; "block" leaves the server promise pending on purpose
+ * (debugging). Auto-confirm is deliberately NOT a policy (security gate — see
+ * ui-request-policy.ts). Invalid values fail safe to "cancel".
+ */
+export function resolveDialogAnswerPolicy(read: (name: string) => string | undefined = getCrewEnv): DialogAnswerPolicy {
+	return read(RPC_DIALOG_ANSWER_ENV)?.trim() === "block" ? "block" : "cancel";
+}
+
+/**
+ * Resolve the DR1 turn timeout (ms). Belt-and-suspenders bound for a
+ * live-but-silent child: the settle wait also races this timeout, so even a
+ * child that never exits cannot hold the worker-cap slot forever. Read via
+ * the env registry (getCrewEnvInt — the registry default "600000" applies
+ * when unset/unparseable); a parsed value ≤ 0 falls back to the default —
+ * there is deliberately NO disable value while RPC stays experimental.
+ */
+export function resolveRpcTurnTimeoutMs(read: (name: string) => number | undefined = getCrewEnvInt): number {
+	const value = read(RPC_TURN_TIMEOUT_ENV);
+	return typeof value === "number" && value > 0 ? value : DEFAULT_RPC_TURN_TIMEOUT_MS;
+}
+
+interface SettleTracking {
+	lastAssistantText: string | undefined;
+	settled: boolean;
+	/**
+	 * DR5 double-execution guard: true once ANY session event other than
+	 * `agent_settled` (message_start / message_end / extension_error / …)
+	 * was observed after the prompt command was WRITTEN. "Written" rather
+	 * than strictly "after the prompt ACK": the frame client processes a
+	 * stdout chunk's lines synchronously while the sendCommand promise only
+	 * resolves in a later microtask — an event coalesced into the same chunk
+	 * as the ACK would slip past a strict ACK gate, reopening the exact
+	 * window this guard exists to close. `agent_settled` itself does NOT
+	 * count (it ends the turn; a settled-with-no-other-event turn is an
+	 * empty turn, not a started one — keeps prompt-preflight rejections
+	 * retry-safe).
+	 */
+	agentStarted: boolean;
+}
+
+function extractAssistantText(message: unknown): string | undefined {
+	if (typeof message !== "object" || message === null) return undefined;
+	const role = (message as { role?: unknown }).role;
+	if (role !== "assistant") return undefined;
+	const content = (message as { content?: unknown }).content;
+	if (!Array.isArray(content)) return undefined;
+	const parts: string[] = [];
+	for (const part of content) {
+		if (typeof part === "object" && part !== null && (part as { type?: unknown }).type === "text") {
+			const text = (part as { text?: unknown }).text;
+			if (typeof text === "string") parts.push(text);
+		}
+	}
+	return parts.length > 0 ? parts.join("\n") : undefined;
+}
+
+/**
+ * Run one worker turn over the RPC frame transport (EXPERIMENTAL — see module
+ * header for live-fire status). Spawn failure surfaces as a structured result
+ * (error field), never a throw from the transport itself.
+ */
+export async function runRpcWorker(input: RpcWorkerInput): Promise<ChildPiRunResult> {
+	const tracking: SettleTracking = { lastAssistantText: undefined, settled: false, agentStarted: false };
+	let settleResolve: (() => void) | undefined;
+	const settledPromise = new Promise<void>((resolve) => {
+		settleResolve = resolve;
+	});
+	let abortError: Error | undefined;
+	// DR5: set synchronously right before the prompt command is written (see
+	// SettleTracking.agentStarted for why "written", not "ACKed").
+	let promptSent = false;
+
+	const overrides = input.rpc ?? {};
+	const client = createRpcFrameClient({
+		...overrides,
+		// Live-fire argv unless the caller (tests) overrides wholesale.
+		argv: overrides.argv ?? buildRpcWorkerArgv(input.model),
+		dialogPolicy: overrides.dialogPolicy ?? resolveDialogAnswerPolicy(),
+		onEvent: (event) => {
+			const record = event as { type?: unknown; message?: unknown };
+			if (record?.type === "message_end") {
+				const text = extractAssistantText(record.message);
+				if (text !== undefined) tracking.lastAssistantText = text;
+			} else if (record?.type === "agent_settled") {
+				tracking.settled = true;
+				settleResolve?.();
+			}
+			// DR5: any other session event after the prompt was sent marks the
+			// agent turn as begun (see SettleTracking.agentStarted docstring).
+			if (promptSent && !tracking.settled) tracking.agentStarted = true;
+		},
+	});
+
+	const onAbort = () => {
+		// Ask the server to abort the current run, then stop orderly. The
+		// command may race the shutdown — a rejection is expected and logged.
+		client
+			.sendCommand({ type: "abort" })
+			.catch((error: Error) => {
+				abortError = error;
+			})
+			.finally(() => {
+				// biome-ignore lint/suspicious/noEmptyBlockStatements: stop() never rejects by design — void-append .catch per lane rules.
+				void client.stop().catch(() => {});
+				settleResolve?.();
+			});
+	};
+	input.signal?.addEventListener("abort", onAbort, { once: true });
+
+	let runError: string | undefined;
+	// DR1: belt-and-suspenders turn timeout — even a child that never exits
+	// must not hold the settle wait (and the worker-cap slot around it) open.
+	const turnTimeoutMs = resolveRpcTurnTimeoutMs();
+	let turnTimeoutReject: ((error: Error) => void) | undefined;
+	const turnTimeoutPromise = new Promise<never>((_resolve, reject) => {
+		turnTimeoutReject = reject;
+	});
+	const turnTimer = setTimeout(() => {
+		turnTimeoutReject?.(new Error(`rpc transport: turn timeout after ${turnTimeoutMs}ms without agent_settled`));
+	}, turnTimeoutMs);
+	turnTimer.unref?.();
+	try {
+		promptSent = true;
+		await client.sendCommand({ type: "prompt", message: input.task });
+		// DR1: race the settle against process exit and the turn timeout. Both
+		// losers carry the early-failure shape (error set, no rawFinalText —
+		// unless assistant text was already captured, which correctly blocks
+		// retry via the existing predicate); the settled-check inside the exit
+		// branch keeps a settle frame that lands in the same tick as the exit
+		// from being misread as a crash. Promise.race attaches handlers to all
+		// participants, so the losers' later rejections are absorbed (no
+		// unhandled-rejection), and the abort branch still resolves
+		// settledPromise first (abort is never swallowed).
+		await Promise.race([
+			settledPromise,
+			client.exited().then((code) => {
+				if (!tracking.settled) throw new Error("rpc transport: exited before agent_settled");
+				return code;
+			}),
+			turnTimeoutPromise,
+		]);
+	} catch (error) {
+		runError = error instanceof Error ? error.message : String(error);
+	} finally {
+		clearTimeout(turnTimer);
+		input.signal?.removeEventListener("abort", onAbort);
+		// biome-ignore lint/suspicious/noEmptyBlockStatements: stop() never rejects by design — void-append .catch per lane rules.
+		await client.stop().catch(() => {});
+	}
+
+	const exitCode = await client.exited();
+	const result: ChildPiRunResult = {
+		exitCode,
+		stdout: client.stdoutText(),
+		stderr: client.stderrText(),
+	};
+	if (runError) result.error = runError;
+	else if (abortError && !tracking.settled) result.error = `rpc abort failed: ${abortError.message}`;
+	if (tracking.lastAssistantText !== undefined) result.rawFinalText = tracking.lastAssistantText;
+	// DR5 bridge: explicit result field (NOT an error-string marker) so the
+	// non-retryable contract is testable and greppable — isEarlyRpcTransportFailure
+	// consults it (run-worker.ts). Set whenever the agent turn had begun.
+	if (tracking.agentStarted) result.rpcAgentStarted = true;
+	if (input.signal?.aborted) result.aborted = true;
+	return result;
+}