pi-crew 0.11.6 → 0.11.8

package/src/runtime/child-pi/child-pi.ts

@@ -27,6 +27,16 @@ import { ChildPiLineObserver } from "./child-pi-streams.ts";
 // Phase 2.3: the six timer constructs moved to child-pi-timers.ts (pure motion).
 import { createChildPiTimers } from "./child-pi-timers.ts";
 import { runMockChildPi } from "./mock-fixtures.ts";
+// W2 (session-file recovery): deterministic worker session flags + crash-path
+// tail-replay of the session JSONL (see session-recovery.ts header).
+import {
+	appendWorkerSessionArgs,
+	deriveSessionPaths,
+	recoverLastAssistantFromSession,
+	resolveSessionRecoveryEnabled,
+	type SessionRecoveryInfo,
+	shouldAttemptSessionRecovery,
+} from "./session-recovery.ts";
 
 // ── Re-exports from child-pi-kill.ts (H-7 decomposition step 2) ──
 // killProcessTree is internal (not previously exported) — keep that invariant.
@@ -43,9 +53,10 @@ export { buildChildPiSpawnOptions, buildFinalChildPiSpawnOptions } from "./child
 // ── Re-export from child-pi-streams.ts (H-7 decomposition step 4) ──
 export { ChildPiLineObserver } from "./child-pi-streams.ts";
 
-import { checkCrewDepth, cleanupTempDir } from "../model/pi-args.ts";
+import { checkCrewDepth, cleanupTempDir, resolveHermeticWorkers } from "../model/pi-args.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../process/post-exit-stdio-guard.ts";
 import { classifyProcessCrash } from "../recovery/crash-classification.ts";
+import { probePiVersion } from "./pi-version.ts";
 
 /** Maximum size (bytes) for the ChildPiLineObserver's line accumulation buffer.
  * When exceeded, the buffer is force-flushed to prevent unbounded memory growth
@@ -185,8 +196,18 @@ export interface ChildPiRunInput {
 	inheritContext?: boolean;
 	/** Pass to pi to mark certain commands as context-excluded. Default: false */
 	excludeContextBash?: boolean;
-	/** pi session ID for session naming (aligns with pi-crew run ID) */
+	/** pi session ID for session naming (aligns with pi-crew run ID). W2: now
+	 *  WIRED — flows to `--session-id` (deterministic worker session files for
+	 *  crash-path tail-recovery; see session-recovery.ts). */
 	sessionId?: string;
+	/** W2 (session-file recovery): explicit session directory override. When
+	 *  absent, derived per-worker as `<artifactsRoot>/sessions/<taskId>/` so
+	 *  session JSONL is cleaned up together with run artifacts. */
+	sessionDir?: string;
+	/** W2 (session-file recovery): explicit on/off (runtime.sessionRecovery
+	 *  config). Env PI_CREW_SESSION_RECOVERY overrides in either direction;
+	 * default ON. Only consulted on crash-ish settles (exitCode null / killed). */
+	sessionRecovery?: boolean;
 	/** Path to steering JSONL file for real-time steer injection. */
 	steeringFile?: string;
 	/** Run ID for cleanup tracking */
@@ -197,6 +218,24 @@ export interface ChildPiRunInput {
 	role?: string;
 	/** Team-role thinking override (takes precedence over agent.thinking). */
 	thinkingOverride?: string;
+	/** R3-1: run-static worker header for the --append-system-prompt channel
+	 *  (renderTaskPrompt().stablePrefix). Threaded by child-executor so the
+	 *  Protocol/mailbox/workspace/runtime-context block survives compaction
+	 *  instead of living in the summarizable user-message span. */
+	systemPromptAppend?: string;
+	/** R3-19/D5 (hermetic worker spawns): thread runtime.hermeticWorkers to
+	 *  buildPiWorkerArgs (--no-extensions). Env PI_CREW_HERMETIC_WORKERS
+	 *  overrides either way; default TRUE. */
+	hermeticWorkers?: boolean;
+	/** U9 (pi 1.0.4 version floor): host pi binary version for the argv
+	 *  builder's version-gated flags (--no-mcp at the 1.0.4 floor). runChildPi
+	 *  OVERWRITES this with the single-flight probePiVersion() result whenever
+	 *  this spawn can consume a version-gated flag (parity non-hermetic + not
+	 *  pre-aborted); on hermetic spawns (the default — no version-gated flag
+	 *  consulted) the field passes through untouched and the probe is SKIPPED,
+	 *  keeping default-path spawns (and unit-test surface paths) free of a real
+	 *  `pi --version` child. See child-pi/pi-version.ts for the floor registry. */
+	piVersion?: string | null;
 	/** Root directory for artifacts (used to validate transcriptPath). */
 	artifactsRoot?: string;
 	/** I5: run events JSONL path — threaded to the worker so its scratchpad
@@ -283,6 +322,19 @@ export interface ChildPiRunResult {
 	exitStatus?: WorkerExitStatus;
 	/** True if the agent was hard-aborted (max_turns + grace exceeded). */
 	aborted?: boolean;
+	/**
+	 * DR5 (RPC double-execution guard, deep-review 2026-10-05 §2): set by the
+	 * RPC transport when a session event (message_start/message_end/…) was
+	 * observed after the prompt was sent but the turn never settled — i.e.
+	 * the agent turn HAD begun when the transport failed, even though no
+	 * assistant text was captured. `isEarlyRpcTransportFailure` treats this
+	 * as non-retryable: the turn may already have performed side effects, and
+	 * double-executing a task that already produced work is worse than
+	 * surfacing the transport error. An explicit result field (not an
+	 * error-string marker) so the contract is testable and greppable; the
+	 * stdio transport never sets it.
+	 */
+	rpcAgentStarted?: boolean;
 	/** True if the agent was steered to wrap up (hit soft turn limit) but finished in time. */
 	steered?: boolean;
 	/** #7 hardening: bounded digest of intermediate findings (last N tool results or
@@ -291,6 +343,13 @@ export interface ChildPiRunResult {
 	 *  text) still produce a non-empty result. Consumers should prefer rawFinalText
 	 *  first — this is a last-resort fallback. */
 	intermediateFindings?: string;
+	/** W2 (session-file recovery): present when the worker died WITHOUT a
+	 *  final assistant event (exitCode null / killed) and a COMPLETE assistant
+	 *  record was tail-recovered from the worker's session JSONL (deterministic
+	 *  `--session-id`/`--session-dir` under the run artifacts root). Consumers
+	 *  treat it as a crash-path supplement to rawFinalText — never a replacement
+	 *  for clean-path output, and manifest polling is untouched. */
+	recoveredFromSession?: SessionRecoveryInfo;
 	/**
 	 * MuxSurface A1: present ONLY when the worker booted inside a multiplexer
 	 * pane instead of a stdio pipe (spec §13.1). Downstream (T9 EventLogTailSource,
@@ -371,6 +430,17 @@ function safeLoadSurfaceConfig(cwd: string): PiTeamsConfig {
 	}
 }
 
+/**
+ * D1/D5: flags that apply to HEADLESS worker spawns only. The surface TUI
+ * branch strips them before booting a pane — a pane hosts a full interactive
+ * pi session where the interactive trust prompt must stay available and the
+ * ambient extension stack is part of the human-visible session (task mandate:
+ * worker spawn CHỈ, KHÔNG đụng surface TUI spawn).
+ */
+function stripHeadlessOnlyFlags(args: string[]): string[] {
+	return args.filter((arg) => arg !== "--no-approve" && arg !== "--no-extensions");
+}
+
 /**
  * MuxSurface A1 spawn branch (spec §13.1). Returns a ChildPiRunResult when the
  * worker was booted INSIDE a multiplexer pane (no stdio process is spawned and
@@ -413,7 +483,7 @@ async function trySurfaceBranch(
 			livePaneCount: degradeController ? degradeController.livePaneCount() : (surfaceOpts?.livePaneCount ?? 0),
 			taskId,
 			cwd: input.cwd,
-			piArgs: builtArgs,
+			piArgs: stripHeadlessOnlyFlags(builtArgs),
 			stateRoot: input.eventsPath ? path.dirname(input.eventsPath) : "",
 			baseDir: surfaceOpts?.baseDir,
 			deps: preResolved ? { provider: preResolved } : {},
@@ -681,9 +751,39 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			brokerSpawn = undefined;
 		}
 	}
-	const spawnPrep = prepareSpawnContext(brokerSpawn ? { ...input, brokerSpawn } : input, effectiveTask, depthEnv);
+	// U9 (pi 1.0.4 version floor): resolve the host pi binary's version ONCE per
+	// process (probePiVersion — single-flight memoized, injectable exec seam,
+	// never rejects) and thread it into the argv builder via input. Probed ONLY
+	// when this spawn can consume a version-gated flag: the parity
+	// (non-hermetic) argv applies the --no-mcp floor at 1.0.4, while hermetic
+	// spawns (the default) are already MCP-clean via --no-extensions and consult
+	// no version-gated flag — skipping the probe there keeps every default-path
+	// spawn — and the unit-test surface paths — free of a real `pi --version`
+	// child. An already-aborted signal skips too: prepareSpawnContext's B5
+	// guard below returns before the argv is ever consumed.
+	const versionedInput: ChildPiRunInput =
+		!input.signal?.aborted && !resolveHermeticWorkers(input.hermeticWorkers) ? { ...input, piVersion: await probePiVersion() } : input;
+	const spawnPrep = prepareSpawnContext(brokerSpawn ? { ...versionedInput, brokerSpawn } : versionedInput, effectiveTask, depthEnv);
 	if (spawnPrep.kind === "aborted") return spawnPrep.result;
 	const { spawnSpec, mergedEnv, tempDir, builtEnv, builtArgs } = spawnPrep.ctx;
+	// W2 (session-file recovery): resolve the worker's deterministic session
+	// identity (per-worker dir under the run artifacts root) and arm it on BOTH
+	// argv views — the headless spawnSpec.args ([script, ...builtArgs]) and the
+	// raw builtArgs (also consumed by the surface branch). prepareSpawnContext
+	// does not forward session identity to the arg builder (ownership boundary
+	// with child-pi-spawn.ts — see the lane report), so this is the in-zone
+	// activation point; appendWorkerSessionArgs is idempotent, making the move
+	// to builder-side forwarding later a zero-diff no-op.
+	const workerSession = deriveSessionPaths(input);
+	const sessionRecoveryEnabled = resolveSessionRecoveryEnabled(input.sessionRecovery);
+	if (workerSession) {
+		try {
+			fs.mkdirSync(workerSession.sessionDir, { recursive: true });
+		} catch {
+			// Unwritable target → spawn proceeds; recovery simply finds no files.
+		}
+		appendWorkerSessionArgs(spawnSpec.args, builtArgs, workerSession);
+	}
 	// MuxSurface A1 (spec §13.1): attempt booting the worker in a mux pane BEFORE
 	// spawning a stdio pipe. Returns a finished result in surface mode (pane exit
 	// awaited) or null → fall through to the classic headless spawn below.
@@ -869,6 +969,22 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				clearPostExitGuard();
 			};
 
+			// W2 (session-file recovery): crash-path augment — when the worker died
+			// WITHOUT a final assistant event (exitCode null / killed), tail-replay
+			// its session JSONL and surface the last COMPLETE assistant record on the
+			// resolved result. Best-effort and deadline-bounded (session-recovery.ts)
+			// so settle can never hang on pathological IO. This AUGMENTS the result —
+			// manifest polling (heartbeat-watcher / detached-run-results) is untouched.
+			const recoverForSettle = async (settleResult: ChildPiRunResult): Promise<SessionRecoveryInfo | undefined> => {
+				if (!workerSession || !sessionRecoveryEnabled) return undefined;
+				if (!shouldAttemptSessionRecovery(settleResult, hardKilled)) return undefined;
+				try {
+					return (await recoverLastAssistantFromSession(workerSession.sessionDir, workerSession.sessionId)) ?? undefined;
+				} catch {
+					return undefined;
+				}
+			};
+
 			const settle = (result: ChildPiRunResult): Promise<void> => {
 				if (settled) return Promise.resolve();
 				settled = true;
@@ -885,7 +1001,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				// durable transcript on disk.
 				return lineObserver
 					.flush()
-					.then(() => {
+					.then(async () => {
 						input.signal?.removeEventListener("abort", abort);
 						input.signal?.removeEventListener("abort", onParentAbort);
 						try {
@@ -893,12 +1009,16 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 						} catch (error) {
 							cleanupErrors.push(error instanceof Error ? error.message : String(error));
 						}
+						// W2: crash-path session tail-recovery (await BEFORE resolve so the
+						// recovered record rides the same settled result object).
+						const recoveredFromSession = await recoverForSettle(result);
 						// Catch all errors from settle to prevent unhandled rejection from propagating
 						try {
 							resolve({
 								...result,
 								rawFinalText: lineObserver.getRawFinalText(),
 								intermediateFindings: lineObserver.getIntermediateFindings(),
+								...(recoveredFromSession ? { recoveredFromSession } : {}),
 								exitStatus: result.exitStatus ?? {
 									exitCode: result.exitCode,
 									cancelled: abortRequested,
@@ -926,7 +1046,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 							);
 						}
 					})
-					.catch((flushError) => {
+					.catch(async (flushError) => {
 						// Drain failed — log and still resolve so runChildPi doesn't hang.
 						logInternalError(
 							"child-pi.settle-flush-failed",
@@ -940,11 +1060,15 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 						} catch (error) {
 							cleanupErrors.push(error instanceof Error ? error.message : String(error));
 						}
+						// W2: crash-path session tail-recovery — same augment on the
+						// drain-failed path (a torn flush is itself crash-adjacent).
+						const recoveredFromSession = await recoverForSettle(result);
 						try {
 							resolve({
 								...result,
 								rawFinalText: lineObserver.getRawFinalText(),
 								intermediateFindings: lineObserver.getIntermediateFindings(),
+								...(recoveredFromSession ? { recoveredFromSession } : {}),
 								exitStatus: result.exitStatus ?? {
 									exitCode: result.exitCode,
 									cancelled: abortRequested,

package/src/runtime/child-pi/pi-version.ts

@@ -0,0 +1,187 @@
+/**
+ * pi-version.ts — host `pi` binary version probe + hand-rolled comparison
+ * (U9, pi 1.0.4 adoption wave).
+ *
+ * WHY HAND-ROLLED (no `semver` dependency): pi-crew's package policy is ZERO
+ * new runtime dependencies (AGENTS.md / wave constraint). The comparison
+ * surface pi-crew actually needs is major.minor.patch + simple pre-release
+ * ordering + conservative null on malformed input — pulling in `semver` for
+ * that costs a dependency (plus its transitive tree) that every install pays
+ * for a decision made at most once per process. If a richer need appears
+ * (ranges, build-metadata ordering), REVISIT this decision explicitly — do
+ * not silently grow this file into a partial semver implementation.
+ *
+ * PROBE CONTRACT (probePiVersion):
+ *   - Execs the SAME binary the stdio transport spawns: getPiSpawnCommand
+ *     (PI_TEAMS_PI_BIN aware) with `--version` — probing a different install
+ *     than the one we spawn would gate flags on the wrong version.
+ *   - The exec is INJECTABLE (ExecPiVersionFn seam) so unit tests never spawn
+ *     a real child; the default seam wraps node:child_process execFile with a
+ *     5s timeout (utf8).
+ *   - Single-flight memoized per process: the FIRST call creates the promise;
+ *     every later call (any args) returns the same one. Failures memoize too
+ *     (null = unknown) — a missing/old pi binary does not re-probe per spawn.
+ *   - NEVER rejects: spawn error / nonzero exit / timeout / unparseable
+ *     stdout all resolve null. The result is a hint, never a failure channel.
+ *
+ * COMPARISON CONTRACT (comparePiVersion):
+ *   - Strict `major.minor.patch[-prerelease][+build]` (official semver shape;
+ *     leading zeros rejected). Build metadata is IGNORED per semver §10.
+ *   - Malformed input (either side, incl. null/undefined) → null — callers
+ *     treat null as "unknown" and conservatively emit NO version-gated flag.
+ *   - Pre-release ordering (semver §11, simplified): release > pre-release;
+ *     identifiers compared pairwise (numeric identifiers numerically and
+ *     LOWER than alphanumeric; alphanumeric lexically); a shorter identifier
+ *     list is lower when all preceding identifiers are equal.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getPiSpawnCommand } from "../pi-spawn.ts";
+
+/** Probe timeout (ms). `pi --version` is a fast print; 5s absorbs slow cold starts. */
+export const PI_VERSION_PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * Injectable exec seam for {@link probePiVersion}. Mirrors the
+ * promisify(execFile) shape: resolves {stdout, stderr} on exit 0, REJECTS on
+ * spawn error / nonzero exit / timeout. Tests pass a fake — the default
+ * seam would spawn a real child (forbidden in unit tests).
+ */
+export type ExecPiVersionFn = (
+	file: string,
+	args: string[],
+	options: { timeout: number; encoding: "utf8" },
+) => Promise<{ stdout?: string; stderr?: string }>;
+
+const execFileAsync = promisify(execFile);
+
+const defaultExec: ExecPiVersionFn = (file, args, options) => execFileAsync(file, args, options);
+
+/**
+ * ── Version-floor registry (U9) ─────────────────────────────────────────────
+ * Every argv flag pi-crew gates on the HOST pi binary's version is listed
+ * here so "which pi needs which flag" is greppable in ONE place. The emit
+ * sites live in src/runtime/model/pi-args.ts (parity non-hermetic block).
+ *
+ *   - `1.0.4` → `--no-mcp`: disconnects ambient MCP servers outright ("no
+ *     servers connect, no MCP tools or /mcp" — cli.md:198), strictly stronger
+ *     than the U2-lite `mcp__*` --exclude-tools tool-cut. Emitted ONLY on
+ *     parity (non-hermetic) spawns whose probed piVersion >= this floor.
+ *
+ * Future candidates: none yet. When adding one, append the floor constant
+ * here + the gate at the emit site — pre-floor hosts must NEVER see the flag
+ * (pi's strict parser rejects unknown options with a nonzero exit).
+ */
+export const PI_NO_MCP_FLOOR = "1.0.4";
+
+// Probe-side extraction is LENIENT (tolerates "pi 1.0.4" / banners); the
+// strict validation lives in parseVersion below. First version-shaped token
+// in stdout wins.
+const VERSION_TOKEN_RE = /\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\b/;
+
+// Strict semver shape (official regex, numeric identifiers without leading
+// zeros). Anything else is "unknown" — never a guess.
+const STRICT_SEMVER_RE =
+	/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+interface ParsedVersion {
+	major: number;
+	minor: number;
+	patch: number;
+	/** null = release (no pre-release). Build metadata is dropped at parse. */
+	prerelease: string[] | null;
+}
+
+function parseVersion(value: string | null | undefined): ParsedVersion | null {
+	if (typeof value !== "string") return null;
+	const match = STRICT_SEMVER_RE.exec(value.trim());
+	if (!match) return null;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	const prerelease = match[4] === undefined ? null : match[4].split(".");
+	return { major, minor, patch, prerelease };
+}
+
+/** Semver §11 identifier compare: numeric < alphanumeric; numeric numeric-ly, alphanumeric lexically. */
+function comparePrereleaseIdentifiers(a: string, b: string): -1 | 0 | 1 {
+	const aNumeric = /^\d+$/.test(a);
+	const bNumeric = /^\d+$/.test(b);
+	if (aNumeric && bNumeric) {
+		const delta = Number(a) - Number(b);
+		return delta < 0 ? -1 : delta > 0 ? 1 : 0;
+	}
+	if (aNumeric) return -1; // numeric identifiers have LOWER precedence
+	if (bNumeric) return 1;
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Compare two pi version strings. Returns -1 | 0 | 1, or null when EITHER
+ * side is malformed/unknown (conservative — callers must treat null as
+ * "emit nothing version-gated"). Build metadata is ignored (semver §10).
+ */
+export function comparePiVersion(a: string | null | undefined, b: string | null | undefined): -1 | 0 | 1 | null {
+	const pa = parseVersion(a);
+	const pb = parseVersion(b);
+	if (!pa || !pb) return null;
+	for (const key of ["major", "minor", "patch"] as const) {
+		if (pa[key] !== pb[key]) return pa[key] < pb[key] ? -1 : 1;
+	}
+	if (pa.prerelease === null && pb.prerelease === null) return 0;
+	if (pa.prerelease === null) return 1; // release > pre-release
+	if (pb.prerelease === null) return -1;
+	const ids = pa.prerelease;
+	const other = pb.prerelease;
+	for (let i = 0; i < Math.min(ids.length, other.length); i++) {
+		const cmp = comparePrereleaseIdentifiers(ids[i] as string, other[i] as string);
+		if (cmp !== 0) return cmp;
+	}
+	if (ids.length !== other.length) return ids.length < other.length ? -1 : 1; // larger set wins
+	return 0;
+}
+
+/**
+ * Floor gate: true ONLY when `version` parses and is >= `floor`. Unknown
+ * (null/undefined) or malformed versions are BELOW every floor — the
+ * conservative "never emit a flag the host may reject" posture.
+ */
+export function piVersionAtLeast(version: string | null | undefined, floor: string): boolean {
+	const cmp = comparePiVersion(version, floor);
+	return cmp !== null && cmp >= 0;
+}
+
+/** Memoized single-flight probe promise (null = unknown, failures included). */
+let memoizedProbe: Promise<string | null> | null = null;
+
+async function runPiVersionProbe(exec: ExecPiVersionFn): Promise<string | null> {
+	const { command, args } = getPiSpawnCommand(["--version"]);
+	const { stdout } = await exec(command, args, { timeout: PI_VERSION_PROBE_TIMEOUT_MS, encoding: "utf8" });
+	const text = typeof stdout === "string" ? stdout : "";
+	const hit = VERSION_TOKEN_RE.exec(text);
+	return hit ? hit[0] : null;
+}
+
+/**
+ * Resolve the host pi binary's version (`pi --version`), single-flight
+ * memoized per process. The `exec` seam is consumed only by the call that
+ * actually creates the memo — later calls reuse the settled promise no
+ * matter what they pass. NEVER rejects; unknown resolves null.
+ */
+export function probePiVersion(exec: ExecPiVersionFn = defaultExec): Promise<string | null> {
+	if (!memoizedProbe) memoizedProbe = runPiVersionProbe(exec).catch(() => null);
+	return memoizedProbe;
+}
+
+/** @internal Test-only: drop the memoized probe so the next call re-probes with a fresh seam. */
+export function __test_resetPiVersionMemo(): void {
+	memoizedProbe = null;
+}
+
+/** @internal Test-only: is a probe memoized? (null = no probe has run yet —
+ *  lets tests prove a code path never TOUCHED the probe, which the call
+ *  counter alone cannot show once single-flight kicks in). */
+export function __test_peekPiVersionMemo(): Promise<string | null> | null {
+	return memoizedProbe;
+}