pi-crew 0.11.6 → 0.11.7

package/src/runtime/model/pi-args.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentConfig } from "../../agents/agent-config.ts";
+import { getCrewEnvBool } from "../../config/env-vars.ts";
 import { atomicWriteFile } from "../../state/atomic-write.ts";
 import { hasRunStateLayout, packageRoot, userPiRoot } from "../../utils/paths.ts";
 
@@ -40,6 +41,15 @@ export interface BuildPiWorkerArgsInput {
 	agent: AgentConfig;
 	model?: string;
 	sessionEnabled?: boolean;
+	/** W2 (session-file recovery): deterministic pi session id for this worker
+	 *  (`--session-id`, SDK ≥ 0.76.0 — below pi-crew's tested host floor 0.99.2,
+	 *  so emitted unconditionally when set; no capability gate). Same id across
+	 *  retries appends to one session file (SDK §R2.2) — cross-attempt resume. */
+	sessionId?: string;
+	/** W2 (session-file recovery): directory for this worker's session JSONL
+	 *  (`--session-dir`, SDK ≥ 0.30.0). Run-scoped per-worker dir, e.g.
+	 *  `<artifactsRoot>/sessions/<taskId>/` — lives and dies with run artifacts. */
+	sessionDir?: string;
 	maxDepth?: number;
 	skillPaths?: string[];
 	env?: NodeJS.ProcessEnv;
@@ -47,6 +57,24 @@ export interface BuildPiWorkerArgsInput {
 	role?: string;
 	/** Per-role thinking override (teamRole.thinking). Takes precedence over agent.thinking. */
 	thinkingOverride?: string;
+	/** R3-1 (Pi 1.0.0 deep-learn round 3): run-static worker header (Protocol
+	 *  block, mailbox contract, workspace structure, runtime context) riding the
+	 *  `--append-system-prompt` channel instead of the user-message concatenation.
+	 *  Compaction summarizes the user-message span (compaction.md:150-160) but the
+	 *  system prompt survives intact — the parts that must NEVER be lost move here.
+	 *  Task text + dependency context stay in the user message (they SHOULD be
+	 *  summarizable). Final append order: builtin → agent.systemPrompt (if any,
+	 *  honoring its declared replace/append mode) → this header. Probe-verified
+	 *  2026-10-04 (/tmp/pi-r3impl): the append channel and AGENTS.md discovery
+	 *  (project_context section) coexist in one system message. */
+	systemPromptAppend?: string;
+	/** R3-19/D5 (hermetic worker spawns): pass `--no-extensions` on the worker
+	 *  argv. Resolved via resolveHermeticWorkers — env
+	 *  PI_CREW_HERMETIC_WORKERS beats this beats default TRUE. Explicit `-e
+	 *  prompt-runtime` (pushed unconditionally below), agent `extensions:`
+	 *  declarations, and `--skill` flags are unaffected (cli.md:186-191:
+	 *  explicit -e and --skill survive --no-extensions/--no-skills). */
+	hermeticWorkers?: boolean;
 }
 
 export interface BuildPiWorkerArgsResult {
@@ -90,6 +118,17 @@ export function resolveCrewMaxDepth(inputMaxDepth?: number, env: NodeJS.ProcessE
 	return DEFAULT_MAX_CREW_DEPTH;
 }
 
+/**
+ * R3-19/D5 (hermetic worker spawns): resolution order mirrors
+ * resolveSessionRecoveryEnabled — env PI_CREW_HERMETIC_WORKERS beats the
+ * explicit config/runtime value beats default TRUE.
+ */
+export function resolveHermeticWorkers(explicit?: boolean): boolean {
+	const env = getCrewEnvBool("PI_CREW_HERMETIC_WORKERS");
+	if (env !== undefined) return env;
+	return explicit ?? true;
+}
+
 export function checkCrewDepth(
 	inputMaxDepth?: number,
 	env: NodeJS.ProcessEnv = process.env,
@@ -265,6 +304,18 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 	// never sets it, so it can never be matched as a sub-agent.
 	const args = ["--mode", "json", "-p"];
 	if (input.sessionEnabled === false) args.push("--no-session");
+	// W2 (session-file recovery): deterministic session identity so a worker
+	// that dies without a final assistant event (exitCode null / killed) can
+	// have its last COMPLETE assistant turn tail-recovered from the session
+	// JSONL (child-pi.ts settle path → session-recovery.ts). Both flags are
+	// SDK-era flags older than the tested host floor (fact pack §1: session-id
+	// 0.76.0, session-dir 0.30.0 < 0.99.2) → unconditional add, same as the
+	// existing --no-session/--model emissions. Skipped when sessions are off —
+	// under --no-session pi persists nothing, the flags would be meaningless.
+	if (input.sessionEnabled !== false) {
+		if (input.sessionId) args.push("--session-id", input.sessionId);
+		if (input.sessionDir) args.push("--session-dir", input.sessionDir);
+	}
 
 	const resolvedModel = input.model ?? input.agent.model;
 	// H1.a: teamRole.thinking (passed as thinkingOverride) takes precedence over agent.thinking.
@@ -278,8 +329,13 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 		args.push("--thinking", effectiveThinking);
 	}
 
-	// D5 (spec v0.7 §6): default loadout = FULL session (như main session).
-	// --no-extensions/--no-skills/--tools CHỈ xuất hiện khi agent .md khai explicit.
+	// D5 (spec v0.7 §6): default loadout = FULL session (như main session) —
+	// --no-skills/--tools CHỈ xuất hiện khi agent .md khai explicit. R3-19/D5
+	// reversal (2026-10-04): extension discovery is now hermetic by default
+	// (--no-extensions below, off-switch runtime.hermeticWorkers / env
+	// PI_CREW_HERMETIC_WORKERS) — the ambient package stack cost ~1.37s/spawn
+	// and leaked 8 direct-exposure MCP tools + 5 host tools into every worker
+	// (probe C §R3b.6: 431ms vs 1806ms to first stdout record).
 	// "message" MUST stay in CONTROL_TOOLS: it is registered by prompt-runtime
 	// behind the PI_CREW_MSG_ENABLED dormant-env gate (child-pi-spawn.ts sets it
 	// unconditionally), but pi's --tools allowlist filters the tool SURFACE — a
@@ -332,7 +388,13 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 	const excluded = new Set((input.agent.excludeExtensions ?? []).map((name) => path.basename(name).toLowerCase()));
 	declaredExtensions = declaredExtensions.filter((ext) => !excluded.has(path.basename(ext).toLowerCase()));
 	for (const ext of declaredExtensions) args.push("--extension", ext);
-	// KHÔNG còn --no-extensions (extension discovery hoạt động như main session).
+	// R3-19/D5: hermetic spawns — disable discovered/configured/built-in
+	// extensions on worker argv. cli.md:186-187: "Explicit -e paths still
+	// load" — the unconditional prompt-runtime push above and the agent
+	// `extensions:` declarations below survive; --skill flags are a separate
+	// gate. Default ON (resolveHermeticWorkers); surface TUI panes strip the
+	// flag (child-pi.ts stripHeadlessOnlyFlags).
+	if (resolveHermeticWorkers(input.hermeticWorkers)) args.push("--no-extensions");
 	if (input.agent.inheritSkills === false) args.push("--no-skills");
 	for (const skillPath of input.skillPaths ?? []) args.push("--skill", skillPath);
 
@@ -346,6 +408,45 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 		atomicWriteFile(promptPath, input.agent.systemPrompt, { mode: 0o600 });
 		args.push(input.agent.systemPromptMode === "append" ? "--append-system-prompt" : "--system-prompt", promptPath);
 	}
+	// R3-1: run-static header rides its own --append-system-prompt file. pi
+	// parses --system-prompt and --append-system-prompt independently and the
+	// append flag is repeatable (cli/args.js:71-77; appends join with "\n\n" in
+	// argv order), so pushing it AFTER the agent flag yields the required final
+	// order builtin → agent.systemPrompt → run-static header in BOTH modes
+	// (replace mode: agent file replaces builtin, header appends after it;
+	// append mode: two append files in argv order).
+	if (input.systemPromptAppend?.trim()) {
+		if (!tempDir) {
+			const tmpBase = getPiTempBase();
+			tempDir = createSafeTempDir(tmpBase, `pi-crew-${process.pid}-`);
+		}
+		const headerPath = path.join(tempDir, "worker-header.md");
+		atomicWriteFile(headerPath, input.systemPromptAppend, { mode: 0o600 });
+		args.push("--append-system-prompt", headerPath);
+	}
+
+	// D1 (R3-3, pinned 2026-10-04): deterministic project-trust for worker
+	// spawns — `--no-approve` (cli alias -na). The command-line override applies
+	// FIRST in pi's trust resolution (security.md "How Pi chooses a trust
+	// decision"), before any extension, saved decision in ~/.pi/agent/trust.json,
+	// or defaultProjectTrust — so worker behavior no longer varies with the
+	// ambient trust store of the machine (P-C probe: /home/bom/source/my_pi and
+	// /tmp were pre-trusted there). Decision rationale vs the D1 criteria:
+	// (a) no ambient-trust dependency ✓ (CLI override wins);
+	// (b) write capability intact ✓ (security.md:33 — project trust does NOT
+	//     limit what tool calls can access; only startup resource loading is
+	//     gated, so workers still write files in the task cwd);
+	// (c) minimal scope ✓ (declines rather than grants; one command; not
+	//     persisted to trust.json).
+	// AGENTS.md/CLAUDE.md context files load REGARDLESS of project trust
+	// (security.md:57) — probe-verified 2026-10-04 (/tmp/pi-r3impl probe2: the
+	// project_context section is present with --no-approve), so the R3-18
+	// repo-instruction auto-load is preserved. `-a` was rejected: it grants
+	// maximal project trust (loads .pi/mcp.json, .pi/extensions… from untrusted
+	// task cwds) — the opposite of minimal scope, and redundant with the D5
+	// hermetic posture. Surface TUI spawns strip this flag (child-pi.ts
+	// trySurfaceBranch) to keep the interactive trust prompt available.
+	args.push("--no-approve");
 
 	// G3 (SDD-2 W-B, spill-always): task text NEVER rides argv — argv is
 	// world-readable via /proc/<pid>/cmdline, leaking task content (and any

package/src/runtime/peer-dep.ts

@@ -69,6 +69,9 @@ let cachedResolve: ResolvedPeerDep | undefined | null = null;
 let cachedModule: PeerDepModule | undefined;
 let primingPromise: Promise<PeerDepModule> | undefined;
 
+/** Warn-once guard for the legacy-fork resolution notice (W6/P2-4, 2026-10-03). */
+let forkResolutionWarned = false;
+
 /**
  * Build the ordered list of "resolution bases" — paths to seed
  * `createRequire(...).resolve()` from. Node walks UP `node_modules` from each
@@ -212,6 +215,24 @@ function tryResolveFrom(base: string): ResolvedPeerDep | undefined {
 	}
 }
 
+/**
+ * W6/P2-4 (pi 1.0.0 adoption wave, 2026-10-03): the @mariozechner fork stopped
+ * publishing (npm latest 0.73.1, 2026-05-07) and sits outside the
+ * @earendil-works semver guarantees, but resolution code + tests still
+ * deliberately support it (Windows global installs, issue #33) and there is
+ * no install-base evidence it is unused — kept, not removed. Warn once per
+ * process so installs relying on it know to migrate to the canonical package.
+ */
+function warnIfForkResolved(name: string): void {
+	if (name !== "@mariozechner/pi-coding-agent" || forkResolutionWarned) return;
+	forkResolutionWarned = true;
+	console.warn(
+		`[pi-crew] notice: resolved the legacy peer dependency "${name}" (fork last published 0.73.1, 2026-05-07). ` +
+			`The canonical package is "@earendil-works/pi-coding-agent"; pi-crew keeps the fork for compatibility, ` +
+			`but support may be removed in a future release.`,
+	);
+}
+
 /** Resolve the peer dep install dir + ESM entry URL. Memoized (sync). */
 export function resolvePeerDep(): ResolvedPeerDep | undefined {
 	if (cachedResolve !== null) return cachedResolve ?? undefined;
@@ -225,6 +246,7 @@ export function resolvePeerDep(): ResolvedPeerDep | undefined {
 	for (const base of bases) {
 		const found = tryResolveFrom(base);
 		if (found) {
+			warnIfForkResolved(found.name);
 			cachedResolve = found;
 			return found;
 		}
@@ -234,6 +256,7 @@ export function resolvePeerDep(): ResolvedPeerDep | undefined {
 	for (const base of peerDepNpmGlobalBases()) {
 		const found = tryResolveFrom(base);
 		if (found) {
+			warnIfForkResolved(found.name);
 			cachedResolve = found;
 			return found;
 		}
@@ -317,4 +340,5 @@ export function __resetPeerDepCacheForTest(): void {
 	cachedResolve = null;
 	cachedModule = undefined;
 	primingPromise = undefined;
+	forkResolutionWarned = false;
 }

package/src/runtime/rpc/README.md

@@ -0,0 +1,100 @@
+# RPC worker transport — W7 (P2-3) EXPERIMENTAL PROTOTYPE
+
+Opt-in, **not wired into live dispatch**. The production stdio child-pi path
+(`child-pi.ts`) is untouched; `run-worker.ts` returns a structured
+**not-implemented** result when the RPC transport is requested (see below).
+
+## What this is
+
+A JSONL frame client that speaks the pi SDK's RPC mode protocol
+(`pi --mode rpc`) on stdin/stdout, implementing the two Round-2 design gates
+the adoption review (§R2.5) proved are mandatory for any RPC transport:
+
+1. **`extension_ui_request` drain policy** (`ui-request-policy.ts`) —
+   fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`,
+   `set_editor_text`) are counted per method and dropped. Round-2 live
+   evidence: 15 of the first 16 records a worker emits belong to this family.
+2. **Dialog auto-answer policy** (`cancel` | `block`) — dialog methods
+   (`select`/`confirm`/`input`/`editor`) park a server-side promise that NEVER
+   resolves if unanswered (ask-over-RPC deadlock, R2.5). `cancel` (default)
+   answers the universal safe answer `{type:"extension_ui_response", id,
+   cancelled:true}` (select/input → undefined, confirm → false). `block`
+   leaves it pending on purpose (debug). **There is no auto-confirm mode —
+   deliberate security decision.** An unattended transport must never say
+   "yes" for the user.
+
+Counters (fake-stream asserted): `uiRequestsDrained`, `drainedByMethod`,
+`dialogsCancelled`, `dialogsBlocked`, `malformedFrames`, `responsesMatched`,
+`responsesUnmatched`.
+
+## Deviation from "use SDK RpcClient" — recorded, evidence-based
+
+The task's original phrasing said "transport dùng SDK RpcClient/runRpcMode".
+The verified recon packet (adaptive-07) proved `RpcClient` unusable for this
+prototype and the leader routed the packet through; deviation accepted per
+packet §C:
+
+1. **No public API to answer `extension_ui_request`** — `send`/`process` are
+   private; non-response records go to event listeners only. Gate 2 would
+   require bracket-accessing private members.
+2. **Version skew** — `RpcClient.start()` spawns `node <cliPath ?? "dist/cli.js">`
+   cwd-relative, NOT the host pi binary the stdio transport resolves
+   (`getPiSpawnCommand` / `PI_TEAMS_PI_BIN`).
+3. **Not injectable** — the W7 test requirement ("fake RPC stream, no real
+   spawn") is impossible against `RpcClient`.
+
+`runRpcMode` is a server-side embed API — inapplicable (pi-crew is a spawner,
+not an embedder).
+
+So: **own strict-LF frame loop over the SDK's exported protocol TYPES**
+(`RpcCommand` / `RpcResponse` / `RpcExtensionUIRequest` /
+`RpcExtensionUIResponse` — all imported from `@earendil-works/pi-coding-agent`).
+The framing rule follows the SDK's own `modes/rpc/jsonl.d.ts` spec: split on
+`\n` ONLY. **Node readline is unsafe here** — it also splits on U+2028/U+2029,
+which are legal inside JSON strings. `serializeJsonLine` /
+`attachJsonlLineReader` are not exported top-level, hence the ~15-line
+hand-rolled splitter.
+
+## Config & env
+
+- `runtime.workerTransport: "stdio" (default) | "rpc"` — declared in
+  `src/schema/config-schema.ts` + `src/config/types.ts`. **Config→seam plumbing
+  is NOT wired yet** (needs a `parseRuntimeConfig` line in
+  `config-validation.ts`, which is outside this lane's file ownership);
+  the live gate is env `PI_CREW_WORKER_TRANSPORT` (`runWorker` has no config
+  access — packet §A).
+- `PI_CREW_WORKER_TRANSPORT=rpc` — selects the transport at the
+  `run-worker.ts` seam. Currently produces the structured not-implemented
+  result (honest prototype) rather than a live spawn.
+- `PI_CREW_RPC_DIALOG_ANSWER=cancel|block` — GATE 2 policy (default `cancel`,
+  invalid fails safe to `cancel`).
+
+## Why the seam returns not-implemented instead of calling `runRpcWorker`
+
+The task's honesty clause allowed exactly this: this lane may not live-spawn
+pi (Round 2 already spent the live probes), so a live-wired seam would ship an
+end-to-end path that NO test can validate — one env var away from silently
+degrading real runs. `runRpcWorker` is complete and fake-stream unit tested
+(prompt → `agent_settled` → orderly stop → `ChildPiRunResult` mapping, abort
+via RPC `abort` command); flipping the seam is a one-line integration change
+after a live-fire probe validates:
+
+- the exact `--mode rpc` argv/env parity with `prepareSpawnContext`
+  (print-mode argv assembly is stdio-specific),
+- session/event stream shape assumptions (`message_end` assistant text →
+  `rawFinalText`),
+- the Round-2 remaining unknowns (`--approve` probe anomaly, rpc3).
+
+## Files
+
+- `frame-client.ts` — strict-LF JSONL frame client, pending-command map with
+  per-command timeout, malformed-frame resilience (count + drop, never throw),
+  orderly stop (stdin end → exit → SIGKILL fallback, kill-once guard).
+- `ui-request-policy.ts` — the two design gates + counters.
+- `rpc-worker.ts` — env resolvers (`resolveWorkerTransport`,
+  `resolveDialogAnswerPolicy`) + `runRpcWorker` prototype runner.
+
+## Production-ready? Honestly: NO.
+
+Prototype-grade. Validated only against fake streams
+(`test/unit/runtime/rpc/`). No live spawn has been attempted from this code.

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;
+}