pi-crew 0.11.7 → 0.11.9

package/src/runtime/process/zombie-scanner.ts

@@ -18,6 +18,22 @@
  * is no longer alive (parent crashed/exited without reaping the child). A sub-agent
  * whose parent is still running is NOT a zombie — it's a legitimate in-flight task.
  *
+ * R3-16 (2026-10-04): a SECOND class — "foreign pi processes" — is detected via
+ * the CLI-entry markers `AI_AGENT=pi` / `PI_CODING_AGENT=true` (SDK docs
+ * environment-variables.md:15-16: both are set at runtime by the CLI/RPC entry
+ * points and inherited by children). Because they are set POST-exec, they show
+ * up in a process's own frozen /proc/<pid>/environ ONLY when that process was
+ * spawned BY another pi process — a top-level interactive main session's
+ * at-exec environ never carries them. Discriminator hierarchy:
+ *   1. `PI_CREW_KIND=subagent` → crew worker (zombies/live arrays, authoritative);
+ *   2. markers + pi-looking argv + not self/not an ancestor → foreign, REPORT ONLY.
+ * The argv gate matters: every shell/tool/MCP-server process pi spawns INHERITS
+ * the markers (uv/python/bash/xclip …), so marker presence alone over-matches.
+ * Residual ambiguity: a pi the USER deliberately starts from inside a pi shell
+ * tool (nested pi) inherits the markers too and is indistinguishable from a
+ * leak. No 100%-reliable discriminator exists for that residue → foreign
+ * entries are a WARN listing with caveat, NEVER offered as kill candidates.
+ *
  * This module is READ-ONLY. It never kills anything. The caller (doctor --zombies)
  * prints the list and asks for explicit confirmation before any kill.
  */
@@ -51,10 +67,29 @@ export interface ZombieScanResult {
 	zombies: ZombieSubagent[];
 	/** Sub-agents whose parent is still alive — shown for transparency, never killed. */
 	live: ZombieSubagent[];
+	/** R3-16: non-crew pi processes carrying the CLI markers
+	 *  (AI_AGENT=pi / PI_CODING_AGENT=true) with a pi-looking argv. REPORT ONLY —
+	 *  never a kill candidate (a user-started nested pi is indistinguishable
+	 *  from a leaked one; see module header). */
+	foreign: ForeignPiProcess[];
 	/** Errors encountered while scanning (per-pid). Never aborts the whole scan. */
 	errors: string[];
 }
 
+export interface ForeignPiProcess {
+	pid: number;
+	ppid: number;
+	/** Parent dead or re-parented to init (ppid=1) — strongest available orphan signal. */
+	orphaned: boolean;
+	/** argv carries headless markers (`--mode json` / `-p` / `--print`) — an
+	 *  interactive TUI session never does; combined with orphaned this is the
+	 *  highest-confidence "likely leak" pair, still WARN-only. */
+	headless: boolean;
+	rssKb: number;
+	elapsedSec: number | undefined;
+	cmd: string;
+}
+
 /** Read /proc/<pid>/environ as a key=value record. Returns {} if unreadable. */
 function readProcEnviron(pid: number): Record<string, string> {
 	try {
@@ -121,12 +156,17 @@ function isPidAlive(pid: number): boolean {
 }
 
 function readProcCmdline(pid: number): string {
+	return readProcCmdlineTokens(pid).join(" ").trim() || `pid ${pid}`;
+}
+
+/** /proc/<pid>/cmdline as argv tokens (NUL-split). Empty array if unreadable. */
+function readProcCmdlineTokens(pid: number): string[] {
 	try {
 		// /proc/<pid>/cmdline is NUL-separated argv.
 		const raw = fs.readFileSync(`/proc/${pid}/cmdline`, "utf-8");
-		return raw.split("\0").filter(Boolean).join(" ").trim() || `pid ${pid}`;
+		return raw.split("\0").filter(Boolean);
 	} catch {
-		return `pid ${pid}`;
+		return [];
 	}
 }
 
@@ -169,13 +209,16 @@ function listCandidatePids(): number[] {
  * has no side effects.
  */
 export function scanZombieSubagents(): ZombieScanResult {
-	const result: ZombieScanResult = { zombies: [], live: [], errors: [] };
+	const result: ZombieScanResult = { zombies: [], live: [], foreign: [], errors: [] };
 	if (process.platform !== "linux") {
 		result.errors.push("zombie scan is Linux-only (/proc required); skipping on " + process.platform);
 		return result;
 	}
 
 	const myUid = tryGetUid();
+	// R3-16: self + ancestors are live hosting sessions (main session / crew
+	// host chain) — never reportable as foreign, even when they carry markers.
+	const ancestors = collectAncestorPids();
 	for (const pid of listCandidatePids()) {
 		try {
 			// Cheap rejection first: only inspect processes we own (avoid scanning system procs).
@@ -185,7 +228,33 @@ export function scanZombieSubagents(): ZombieScanResult {
 			// AUTHORITATIVE GATE: a process is a pi-crew sub-agent ONLY if it carries
 			// PI_CREW_KIND=subagent. The user's main session never sets this, so it can
 			// never be matched — this is the fix for accidentally killing main sessions.
-			if (environ.PI_CREW_KIND !== "subagent") continue;
+			// R3-16: non-crew processes get ONE extra look — the foreign pi branch
+			// below (markers + pi-looking argv, REPORT ONLY); all else is invisible.
+			if (environ.PI_CREW_KIND !== "subagent") {
+				// Exact value match matters: other agents reuse the AI_AGENT name with
+				// their own value (claude-code sets AI_AGENT=claude-code_…_agent), and
+				// marker INHERITORS (shells, MCP servers, xclip) are filtered by the
+				// argv gate below. Crew workers never reach here — the gate above owns
+				// them (pi-crew also scrubs these markers from worker env).
+				const hasPiMarker = environ.AI_AGENT === "pi" || environ.PI_CODING_AGENT === "true";
+				if (hasPiMarker && pid !== process.pid && !ancestors.has(pid)) {
+					const tokens = readProcCmdlineTokens(pid);
+					if (looksLikePiBinary(tokens)) {
+						const foreignStat = readProcStat(pid);
+						const ppid = foreignStat?.ppid ?? 0;
+						result.foreign.push({
+							pid,
+							ppid,
+							orphaned: ppid <= 1 || !isPidAlive(ppid),
+							headless: isHeadlessArgv(tokens),
+							rssKb: readProcRssKb(pid),
+							elapsedSec: foreignStat?.elapsedSec,
+							cmd: readProcCmdline(pid),
+						});
+					}
+				}
+				continue;
+			}
 
 			const crewParentPid = Number.parseInt(environ.PI_CREW_PARENT_PID ?? "", 10);
 			const stat = readProcStat(pid);
@@ -216,9 +285,11 @@ export function scanZombieSubagents(): ZombieScanResult {
 		}
 	}
 
-	// Sort: zombies first by descending RSS (biggest leaks first), live by pid.
+	// Sort: zombies first by descending RSS (biggest leaks first), live by pid;
+	// foreign: orphans first (the likely leaks), then by descending RSS.
 	result.zombies.sort((a, b) => b.rssKb - a.rssKb);
 	result.live.sort((a, b) => a.pid - b.pid);
+	result.foreign.sort((a, b) => Number(b.orphaned) - Number(a.orphaned) || b.rssKb - a.rssKb);
 	return result;
 }
 
@@ -241,6 +312,63 @@ function getProcUid(pid: number): number | undefined {
 	}
 }
 
+function pathBasename(p: string): string {
+	const idx = p.lastIndexOf("/");
+	return idx === -1 ? p : p.slice(idx + 1);
+}
+
+/**
+ * R3-16: does the argv look like the pi CLI binary itself?
+ *
+ * Every process pi spawns (bash, uv, python MCP servers, xclip, …) INHERITS the
+ * AI_AGENT/PI_CODING_AGENT markers, so marker presence alone over-matches the
+ * user's own tool processes. Only pi-looking argv[0..1] counts (argv[0] itself,
+ * or a node-style script path at argv[1]): basename `pi` (covers
+ * /usr/local/bin/pi, .nvm/…/bin/pi, ./pi), `pi-coding-agent`, or a path
+ * containing pi-coding-agent (node …/pi-coding-agent/dist/…). Tokens deeper
+ * than argv[1] are ARGUMENTS (e.g. `bash -c "pi …"`) — never the binary.
+ */
+function looksLikePiBinary(tokens: string[]): boolean {
+	for (const token of tokens.slice(0, 2)) {
+		const base = pathBasename(token);
+		if (base === "pi" || base === "pi-coding-agent" || base === "pi.js") return true;
+		if (token.includes("pi-coding-agent")) return true;
+	}
+	return false;
+}
+
+/** R3-16: headless argv detection — an interactive TUI session never carries these. */
+function isHeadlessArgv(tokens: string[]): boolean {
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i] ?? "";
+		if (token === "-p" || token === "--print" || token === "--mode=json") return true;
+		if (token === "--mode" && tokens[i + 1] === "json") return true;
+	}
+	return false;
+}
+
+/**
+ * R3-16: the scanner's own ancestor chain (self's parent up to init).
+ *
+ * Any pi process on this chain is a LIVE hosting session (the user's main
+ * session / a crew host) and must never be reported — even in the nested case
+ * (worker runs doctor → its parent crew host and the user's main session above
+ * it sit on this chain and carry markers when pi-in-pi). Bounded at 64 hops to
+ * survive a hypothetical pid cycle.
+ */
+function collectAncestorPids(): Set<number> {
+	const chain = new Set<number>();
+	let current = process.ppid;
+	let guard = 0;
+	while (current > 1 && guard++ < 64) {
+		chain.add(current);
+		const stat = readProcStat(current);
+		if (!stat || stat.ppid <= 0) break;
+		current = stat.ppid;
+	}
+	return chain;
+}
+
 /**
  * Render a ZombieScanResult as human-readable text for the doctor report.
  * Explicitly labels main-session safety and never suggests killing live parents.
@@ -252,7 +380,7 @@ export function formatZombieReport(scan: ZombieScanResult): string {
 	lines.push(`Sub-agents identified by PI_CREW_KIND=subagent marker. Main sessions (no marker) are never listed.`);
 	lines.push("");
 
-	if (scan.zombies.length === 0 && scan.live.length === 0) {
+	if (scan.zombies.length === 0 && scan.live.length === 0 && scan.foreign.length === 0) {
 		lines.push("No pi-crew sub-agent processes found.");
 		if (scan.errors.length > 0) {
 			lines.push("");
@@ -284,6 +412,23 @@ export function formatZombieReport(scan: ZombieScanResult): string {
 		lines.push("");
 	}
 
+	if (scan.foreign.length > 0) {
+		lines.push(`### WARN — Foreign pi processes, REPORT ONLY (${scan.foreign.length})`);
+		lines.push("CLI-spawned pi processes (AI_AGENT=pi / PI_CODING_AGENT=true markers) that are");
+		lines.push("NOT pi-crew children. A top-level interactive session never carries these");
+		lines.push("markers in its own environment (the CLI sets them post-exec) — but a pi YOU");
+		lines.push("deliberately started from inside a pi shell looks identical to a leak.");
+		lines.push("NO reliable discriminator exists for that residue: verify cmd / session-dir");
+		lines.push("/ cwd by hand before ever killing one. These are never kill candidates and");
+		lines.push("never feed pane cleanup. This tool never kills.");
+		lines.push("");
+		lines.push("  PID       PPID     STATE             RSS       CMD");
+		for (const f of scan.foreign) {
+			lines.push(formatForeignRow(f));
+		}
+		lines.push("");
+	}
+
 	if (scan.errors.length > 0) {
 		lines.push(`Scan errors (${scan.errors.length}, first 5 shown):`);
 		for (const err of scan.errors.slice(0, 5)) lines.push(`  - ${err}`);
@@ -301,6 +446,14 @@ function formatZombieRow(z: ZombieSubagent): string {
 	return `  ${String(z.pid).padEnd(9)}${String(z.crewParentPid).padEnd(8)}${formatRss(z.rssKb).padEnd(10)}${(z.role ?? "?").padEnd(14)}${surface.padEnd(16)}${z.cmd.slice(0, 44)}`;
 }
 
+/** One table row for the R3-16 foreign section — state carries the triage flags. */
+function formatForeignRow(f: ForeignPiProcess): string {
+	// "orphaned" = parent dead/re-parented to init (strongest leak signal);
+	// "headless" = --mode json / -p argv (never an interactive TUI session).
+	const state = `${f.orphaned ? "orphaned" : "live-parent"}${f.headless ? " headless" : ""}`;
+	return `  ${String(f.pid).padEnd(9)}${String(f.ppid).padEnd(8)}${state.padEnd(17)}${formatRss(f.rssKb).padEnd(10)}${f.cmd.slice(0, 40)}`;
+}
+
 function formatRss(kb: number): string {
 	if (kb >= 1024 * 1024) return `${(kb / 1024 / 1024).toFixed(1)}G`;
 	if (kb >= 1024) return `${(kb / 1024).toFixed(0)}M`;
@@ -308,4 +461,12 @@ function formatRss(kb: number): string {
 }
 
 // Re-export for tests + callers that want to inspect proc helpers in isolation.
-export const __test = { readProcEnviron, isPidAlive, computeElapsedSec };
+export const __test = {
+	readProcEnviron,
+	isPidAlive,
+	computeElapsedSec,
+	readProcCmdlineTokens,
+	looksLikePiBinary,
+	isHeadlessArgv,
+	collectAncestorPids,
+};

package/src/runtime/rpc/README.md

@@ -1,8 +1,10 @@
-# RPC worker transport — W7 (P2-3) EXPERIMENTAL PROTOTYPE
+# RPC worker transport — W7 (P2-3) EXPERIMENTAL
 
-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).
+Opt-in behind `PI_CREW_WORKER_TRANSPORT=rpc`. **WIRED at the run-worker seam as
+of 2026-10-04** (integration phase, lane D6) after the live-fire probe below —
+previously the seam returned a structured not-implemented result. The
+production stdio child-pi path (`child-pi.ts`) is untouched for the default
+transport; the rpc path carries a REDUCED input (see Limitations).
 
 ## What this is
 
@@ -64,26 +66,58 @@ hand-rolled splitter.
   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.
+  `run-worker.ts` seam. WIRED 2026-10-04: calls `runRpcWorker` for real
+  (worker-cap slot semantics identical to stdio; early transport failure →
+  one structured-warn fallback to the stdio path inside the same slot).
 - `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).
+## Why the seam was not wired before 2026-10-04
+
+The original lane was not allowed to live-spawn pi, so a live-wired seam would
+have shipped an end-to-end path that NO test could validate — one env var away
+from silently degrading real runs. The integration phase (this lane) ran the
+live-fire probe FIRST and only then flipped the seam.
+
+## Live-fire probe 2026-10-04 — GREEN → seam wired
+
+Probe setup: real `pi --mode rpc --no-session` spawned by the unmodified
+frame-client default spawner (`getPiSpawnCommand`), scripts importing directly
+from `src/runtime/rpc/` via `node --experimental-strip-types`, PI_CREW_* /
+PI_TEAMS_* env scrubbed, isolated cwd `/tmp/rpc-lf/`, `timeout -k 5 120` per
+run. Raw artifacts (kept on disk): `/tmp/rpc-lf/probe1{,b}.{log,stdout.txt,stderr.txt}`
+(probe1b = default settings model), `probe2.*` (dialog), `probe3.*` (steer).
+
+| # | Item | Result |
+|---|------|--------|
+| a | `extension_ui_request` drain (GATE 1 live) | **24 drained** on probe1b (`setStatus`×20, `setWidget`×3, `notify`×1 — pi-crew widget keys visible in raw frames); 0 malformed, 0 unmatched responses |
+| b | prompt round-trip | ack **24 ms**, `agent_settled` **4.2 s**, `rawFinalText="OK"`, child exit **0**, orderly stdin-end shutdown |
+| c | dialog (confirm) | **executed** (not skipped): a `-e` mini extension opened a real `confirm` → policy `cancel` answered `extension_ui_response {cancelled:true}` → `ui.confirm` resolved `false` → the model literally echoed `"false"`; settled 1.7 s, **no deadlock**, `dialogsCancelled=1` |
+| d | steer mid-turn | `steer` at t+1.6 s → response RTT **53 ms**, disposition **`"queued"`**, final assistant text honored (`"STOP"`), settled 6.5 s, exit 0 |
+
+First run (probe1) used `--thinking off` against a reasoning-only model
+(`chiase/deepseek-v4.1-flash`, thinkingLevelMap has only `max`) → the assistant
+message came back `content: []` with usage 0. Not a frame-client defect — the
+turn still completed and settled — but a live argv caveat: **do not pass
+`--thinking off` to reasoning-only models**; the wired seam passes the model
+raw and never emits `--thinking`.
+
+### Limitations of the wired rpc path (honest list)
+
+- Input mapping is the minimal prototype surface: `cwd`/`task`/`model`/`signal`.
+  Agent config, system-prompt files, skills, transcript path, steering file,
+  lifecycle/stdout callbacks, `maxTurns`/`graceTurns` remain **stdio-only**.
+- The model string is passed RAW (`--model <model>`), no `applyThinkingSuffix`
+  composition — thinking level comes from the settings default.
+- Workers are ephemeral (`--no-session`): no deterministic session identity
+  (`--session-id`/`--session-dir`, W2 crash recovery) for rpc yet. Attaching a
+  worker to the cwd project's default session would pollute the user's session.
+- `runtime.workerTransport` config key is still NOT plumbed to the seam
+  (needs a `parseRuntimeConfig` line in `config-validation.ts`, outside the
+  lane's ownership); the env var is the only live gate.
+- Early-failure fallback: only a result with `error` set, NO `rawFinalText`,
+  and NOT aborted is retried on stdio (double-execution guard,
+  `isEarlyRpcTransportFailure` in run-worker.ts).
 
 ## Files
 
@@ -92,9 +126,14 @@ after a live-fire probe validates:
   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.
+  `resolveDialogAnswerPolicy`), the live-fire argv builder
+  (`buildRpcWorkerArgv`) + the `runRpcWorker` runner the seam calls.
 
-## Production-ready? Honestly: NO.
+## Production-ready? Honestly: NOT for general agent configs.
 
-Prototype-grade. Validated only against fake streams
-(`test/unit/runtime/rpc/`). No live spawn has been attempted from this code.
+Live-fire validated for the probe scenarios above (small prompt, one confirm
+dialog, one steer, plain model, default extensions). The stdio transport
+remains the default and the only complete path (agent config, system prompts,
+skills, session identity, retries semantics). Do not enable
+`PI_CREW_WORKER_TRANSPORT=rpc` outside experiments until the Limitations
+list above shrinks.

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

@@ -1,22 +1,40 @@
 /**
- * rpc-worker.ts — W7 (P2-3): EXPERIMENTAL RPC worker transport (prototype).
+ * rpc-worker.ts — W7 (P2-3): EXPERIMENTAL RPC worker transport.
  *
- * STATUS — NOT WIRED INTO LIVE DISPATCH (honest prototype):
- * `runWorker` (run-worker.ts) consults {@link resolveWorkerTransport}; when it
- * resolves "rpc" the seam currently returns a structured not-implemented
- * result instead of calling {@link runRpcWorker}. Reason: this lane is
- * forbidden from live-spawning pi (Round-2 evidence already covers the live
- * probes; unit tests use fake streams only), so the live path would ship
- * completely unvalidated. Flipping the seam to call runRpcWorker is the
- * integration-phase follow-up AFTER a live-fire probe (see README.md).
+ * 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 itself is complete and fake-stream tested:
- *   prompt → collect session events until `agent_settled` → orderly stop →
- *   map to ChildPiRunResult. Abort/steer signals send the RPC `abort` command
- *   before stopping.
+ * 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 } from "../../config/env-vars.ts";
+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";
@@ -25,6 +43,10 @@ import type { DialogAnswerPolicy } from "./ui-request-policy.ts";
 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";
 
@@ -39,15 +61,44 @@ export interface RpcWorkerInput {
 }
 
 /**
- * Resolve the worker transport. The env var is the live prototype gate
- * (runWorker has no config access — packet §A); the `runtime.workerTransport`
- * config key is declared in config-schema.ts/types.ts and reaches this seam
- * in the integration phase. FAILSAFE: anything other than exactly "rpc"
- * (after trim) resolves to the default stdio transport.
+ * 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(read: (name: string) => string | undefined = getCrewEnv): WorkerTransport {
-	const raw = read(WORKER_TRANSPORT_ENV);
-	return raw?.trim() === "rpc" ? "rpc" : "stdio";
+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";
 }
 
 /**
@@ -60,9 +111,36 @@ export function resolveDialogAnswerPolicy(read: (name: string) => string | undef
 	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 {
@@ -82,20 +160,26 @@ function extractAssistantText(message: unknown): string | undefined {
 }
 
 /**
- * Run one worker turn over the RPC frame transport (EXPERIMENTAL prototype —
- * see module header). Never spawned by production dispatch in this lane.
+ * 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 };
+	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 };
@@ -106,6 +190,9 @@ export async function runRpcWorker(input: RpcWorkerInput): Promise<ChildPiRunRes
 				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;
 		},
 	});
 
@@ -126,12 +213,41 @@ export async function runRpcWorker(input: RpcWorkerInput): Promise<ChildPiRunRes
 	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 });
-		await settledPromise;
+		// 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(() => {});
@@ -146,6 +262,10 @@ export async function runRpcWorker(input: RpcWorkerInput): Promise<ChildPiRunRes
 	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;
 }