pi-crew 0.9.53 → 0.9.55

package/src/runtime/child-pi.ts

@@ -0,0 +1,1105 @@
+import { spawn } from "node:child_process";
+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 { DEFAULT_CHILD_PI } from "../config/defaults.ts";
+import { registerChildProcess, unregisterChildProcess } from "../extension/crew-cleanup.ts";
+import { atomicWriteFile } from "../state/atomic-write.ts";
+import type { WorkerExitStatus } from "../state/types.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { redactSecretString } from "../utils/redaction.ts";
+import { getActiveBrokerIssuer } from "./broker-issuer.ts";
+import { FINAL_DRAIN_MS, HARD_KILL_MS, POST_EXIT_STDIO_GUARD_MS, RESPONSE_TIMEOUT_MS } from "./child-pi-constants.ts";
+import { appendBoundedTail, clearHardKillTimer, killProcessTree, registerActiveChild, unregisterActiveChild } from "./child-pi-kill.ts";
+import { buildFinalChildPiSpawnOptions, prepareSpawnContext } from "./child-pi-spawn.ts";
+import { ChildPiSteeringController } from "./child-pi-steering.ts";
+// Internal helpers for active-child bookkeeping (extracted to child-pi-kill.ts).
+import { ChildPiLineObserver } from "./child-pi-streams.ts";
+
+// ── Re-exports from child-pi-kill.ts (H-7 decomposition step 2) ──
+// killProcessTree is internal (not previously exported) — keep that invariant.
+export {
+	killProcessPid,
+	terminateActiveChildPiProcesses,
+} from "./child-pi-kill.ts";
+// ── Re-export from child-pi-spawn.ts (H-7 decomposition step 6) ──
+// buildChildPiSpawnOptions was previously exported from child-pi.ts. Keep the
+// public API surface stable by re-exporting from the new module.
+// buildFinalChildPiSpawnOptions (BLOCKER 2 / S5) — composed spawn helper that
+// owns the canary + filter + spread sequence; lives in child-pi-spawn.ts.
+export { buildChildPiSpawnOptions, buildFinalChildPiSpawnOptions } from "./child-pi-spawn.ts";
+// ── Re-export from child-pi-streams.ts (H-7 decomposition step 4) ──
+export { ChildPiLineObserver } from "./child-pi-streams.ts";
+
+import { classifyProcessCrash } from "./crash-classification.ts";
+import { checkCrewDepth, cleanupTempDir } from "./pi-args.ts";
+
+import { attachPostExitStdioGuard, trySignalChild } from "./post-exit-stdio-guard.ts";
+
+/** Maximum size (bytes) for the ChildPiLineObserver's line accumulation buffer.
+ * When exceeded, the buffer is force-flushed to prevent unbounded memory growth
+ * from chatty child processes that produce output without newlines.
+ * (Constant moved to child-pi-constants.ts.) */
+
+// Periodic cleanup of dead child process entries to prevent memory leaks.
+/**
+ * SEC-1: Extract a redacted stderr/stdout excerpt for embedding in lifecycle
+ * events and error messages. The in-memory stdout/stderr accumulators receive
+ * RAW worker output (only structurally compacted via compactChildPiEvent —
+ * NOT secret-redacted), so any slice embedded into a persisted event must be
+ * redacted here. Otherwise worker-emitted secrets (API keys, tokens returned
+ * from a tool call) leak through diagnostic logs that bypass artifact-store
+ * redaction.
+ *
+ * Extracted as a single helper (8 call sites were duplicating this) so the
+ * redaction boundary is unit-testable directly. The real spawn error/timeout
+ * paths are integration-level and NOT reachable via PI_TEAMS_MOCK_CHILD_PI
+ * (the mock returns before the lifecycle-event handlers run), so a behavior
+ * test must target this helper rather than the full runChildPi path.
+ */
+export function redactStderrExcerpt(stderr: string, maxChars: number): string {
+	return redactSecretString(stderr.slice(-maxChars));
+}
+
+/**
+ * B6: spawn taskkill and attach an 'error' listener. spawn() emits ENOENT/EACCES
+ * asynchronously via the 'error' event (not as a throw), so an unlistened spawn
+ * can crash the parent as an uncaught exception. taskkill is a standard Windows
+ * binary so this is defensive, but the listener keeps failures bounded.
+ */
+
+/** Structured lifecycle event emitted by child-pi for critical transitions. */
+export interface ChildPiLifecycleEvent {
+	/** Event discriminator. */
+	type: "spawned" | "spawn_error" | "response_timeout" | "final_drain" | "hard_kill" | "exit" | "close";
+	/** Process ID when available. */
+	pid?: number;
+	/** Exit code for exit/close events. */
+	exitCode?: number | null;
+	/** Error message for error events. */
+	error?: string;
+	/** Stderr captured at timeout moment (for response_timeout events). */
+	stderr?: string;
+	/** Last N chars of stderr for error context (exit/error events). */
+	stderrExcerpt?: string;
+	/** Timestamp (ISO). */
+	ts: string;
+	/** F12: optional cause for `final_drain` events. `"stdout-quiet"` indicates
+	 *  the drain was triggered by the quiet-window early-exit rather than the
+	 *  default 5 s ceiling. Other drain reasons (default) leave this undefined. */
+	reason?: "stdout-quiet";
+	/** Phase-0 diagnostic (HB-003a): the signal that killed the child (when
+	 *  available). Was previously discarded after building the error string. */
+	signal?: string;
+	/** Phase-0 diagnostic (HB-003a): final-drain race timing, present only on
+	 *  exit events where a drain timer was armed. Surfaces the exit-null race. */
+	diagnostic?: {
+		finalDrainArmed: boolean;
+		forcedFinalDrain: boolean;
+		finalDrainFiredMonotonicMs?: number;
+		finalAssistantEventMonotonicMs?: number;
+		exitMonotonicMs: number;
+	};
+}
+
+export interface ChildPiRunInput {
+	cwd: string;
+	task: string;
+	agent: AgentConfig;
+	model?: string;
+	skillPaths?: string[];
+	signal?: AbortSignal;
+	transcriptPath?: string;
+	onStdoutLine?: (line: string) => void;
+	onJsonEvent?: (event: unknown) => void;
+	onSpawn?: (pid: number) => void;
+	/** Structured lifecycle events for durable logging (spawn, crash, timeout, kill, exit). */
+	onLifecycleEvent?: (event: ChildPiLifecycleEvent) => void;
+	maxDepth?: number;
+	finalDrainMs?: number;
+	/** F12: early-exit the drain when stdout has been silent for this many ms
+	 *  after the final assistant event. Set to ≥ finalDrainMs to disable. */
+	finalDrainQuietMs?: number;
+	hardKillMs?: number;
+	responseTimeoutMs?: number;
+	/** Soft limit on assistant turns — inject steer at this count. */
+	maxTurns?: number;
+	/** Extra turns after soft limit before hard abort. Default: 5. */
+	graceTurns?: number;
+	/** Parent conversation context to inherit when inheritContext is true. */
+	parentContext?: string;
+	/** When true, prepend parentContext to the task prompt. */
+	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) */
+	sessionId?: string;
+	/** Path to steering JSONL file for real-time steer injection. */
+	steeringFile?: string;
+	/** Run ID for cleanup tracking */
+	runId?: string;
+	/** Agent ID for cleanup tracking */
+	agentId?: string;
+	/** Role for tool restrictions (from role-tools.ts) */
+	role?: string;
+	/** Root directory for artifacts (used to validate transcriptPath). */
+	artifactsRoot?: string;
+	/**
+	 * Optional broker spawn context (Phase 0 inter-pi broker). When present,
+	 * `prepareSpawnContext` injects `PI_CREW_BROKER_SOCKET` and
+	 * `PI_CREW_BROKER_TOKEN` into the child env (control-namespace keys,
+	 * accepted by `assertOnlyControlEnvKeys`). The token is a 128-bit random
+	 * value issued by the parent's CrewBroker at spawn time; it lives only
+	 * in the parent's in-memory `Map<runId, token>` and in the child's env.
+	 * NEVER persisted to manifest, events, mailbox, or any run-dir file.
+	 */
+	brokerSpawn?: { socketPath: string; token: string };
+	/**
+	 * Optional Phase 0 broker credentials issuer. Called only when
+	 * `brokerSpawn` is not already set on the input. The default no-op
+	 * issuer returns undefined, leaving the child to run without broker
+	 * credentials (today's behavior — file paths remain authoritative).
+	 * The production wiring passes a closure that delegates to the
+	 * session's `CrewBrokerLifecycleController.issueForChild`.
+	 */
+	brokerIssuer?: (runId: string, taskId?: string) => Promise<{ socketPath: string; token: string } | undefined>;
+}
+
+export interface ChildPiRunResult {
+	exitCode: number | null;
+	stdout: string;
+	stderr: string;
+	error?: string;
+	/** RAW (uncapped) final assistant text, captured at stream-parse time BEFORE
+	 *  the 16K transcript compaction. This is the AUTHORITATIVE worker output —
+	 *  it becomes results/<id>.txt so downstream dependencies are not bounded by
+	 *  the transcript's telemetry cap. Undefined when no assistant text was seen
+	 *  (mock paths, error paths) — callers MUST fall back to transcript-derived
+	 *  finalText. See research-findings/output-handling-deep-dive.md §A. */
+	rawFinalText?: string;
+	exitStatus?: WorkerExitStatus;
+	/** True if the agent was hard-aborted (max_turns + grace exceeded). */
+	aborted?: 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
+	 *  assistant text lines) from the run. Populated by ChildPiLineObserver so that
+	 *  workers that exhaust their budget on tool calls (never emit final assistant
+	 *  text) still produce a non-empty result. Consumers should prefer rawFinalText
+	 *  first — this is a last-resort fallback. */
+	intermediateFindings?: string;
+}
+
+// Base allowlist of non-provider env vars always passed to child workers.
+// ── Transcript batching + compaction (H-7 decomposition step 1) ────────
+// Extracted to ./child-pi-transcript.ts. Re-exported here to preserve the
+// existing public API surface.
+export {
+	appendTranscript,
+	compactString,
+	compactValue,
+	flushPendingTranscriptWrites,
+	resetTranscriptBatchState,
+} from "./child-pi-transcript.ts";
+
+/** Mock-only path — real code path reuses a single observer.
+ *  OPT-06 follow-up: returns a Promise so callers can await the transcript
+ *  drain before resolving runChildPi. Without this, mock-mode callers that
+ *  read the transcript file post-run see ENOENT (the async file handle had
+ *  not yet been opened). */
+async function observeStdoutChunk(input: ChildPiRunInput, text: string): Promise<void> {
+	const observer = new ChildPiLineObserver(input);
+	observer.observe(text);
+	await observer.flush();
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function isFinalAssistantEvent(event: unknown): boolean {
+	const obj = asRecord(event);
+	if (obj?.type !== "message_end") return false;
+	const message = asRecord(obj.message);
+	const role = message?.role;
+	if (role !== undefined && role !== "assistant") return false;
+	const stopReason =
+		typeof message?.stopReason === "string" ? message.stopReason : typeof obj.stopReason === "string" ? obj.stopReason : undefined;
+	if (stopReason !== undefined && stopReason !== "stop") return false;
+	const content = Array.isArray(message?.content) ? message.content : [];
+	return !content.some((part) => asRecord(part)?.type === "toolCall");
+}
+
+export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResult> {
+	// Phase 1 (live-session parity): prepend parent context when inheritContext is true.
+	// This mirrors the effectivePrompt logic in live-session-runtime.ts so that
+	// child-process workers receive the same inherited-context treatment.
+	const effectiveTask =
+		input.inheritContext === true && input.parentContext
+			? `${input.parentContext}\n\n---\n# Child Worker Task\n${input.task}`
+			: input.task;
+	const depth = checkCrewDepth(input.maxDepth);
+	if (depth.blocked)
+		return {
+			exitCode: 1,
+			stdout: "",
+			stderr: `pi-crew depth guard blocked child worker: depth ${depth.depth} >= max ${depth.maxDepth}`,
+		};
+	const mock = process.env.PI_TEAMS_MOCK_CHILD_PI;
+	if (mock) {
+		// SECURITY (Issue #2): Mock mode security model is intentionally asymmetric.
+		// PI_TEAMS_MOCK_CHILD_PI is in the allowlist (passed to children) but
+		// PI_CREW_ALLOW_MOCK is NOT in the allowlist — it is only checked in the
+		// parent process scope. This means:
+		//   (1) If an attacker sets PI_CREW_ALLOW_MOCK in the parent's environment,
+		//       it will NOT be passed to child processes (safe).
+		//   (2) Mock mode activation in the child always fails the PI_CREW_ALLOW_MOCK
+		//       check, so mock mode can only be triggered from the parent process.
+		// This asymmetry is intentional: PI_CREW_ALLOW_MOCK must be set in the Pi root
+		// process (the entry point that spawns children), not inherited from a parent.
+		// Setup hooks cannot inject PI_CREW_ALLOW_MOCK into the parent's env.
+		const allowMock = process.env.PI_CREW_ALLOW_MOCK === "1" || process.env.PI_CREW_ALLOW_MOCK === "true";
+		if (!allowMock) {
+			return {
+				exitCode: 1,
+				stdout: "",
+				stderr: "Mock mode requires PI_CREW_ALLOW_MOCK=1",
+			};
+		}
+		// SECURITY: Log mock mode activation prominently for audit trail
+		logInternalError("child-pi.mock", new Error(`Mock mode active: ${mock}`), "NOT running real agents");
+		if (mock === "success") {
+			const stdout = `[MOCK] Success for ${input.agent.name}\n`;
+			await observeStdoutChunk(input, stdout);
+			return { exitCode: 0, stdout, stderr: "" };
+		}
+		if (mock === "json-success" || mock === "adaptive-plan") {
+			const text =
+				mock === "adaptive-plan" && effectiveTask.includes("ADAPTIVE_PLAN_JSON_START")
+					? `[MOCK] Adaptive plan\nADAPTIVE_PLAN_JSON_START\n${JSON.stringify({
+							phases: [
+								{
+									name: "research",
+									tasks: [
+										{
+											role: "explorer",
+											task: "Explore adaptive target",
+										},
+										{
+											role: "analyst",
+											task: "Analyze adaptive target",
+										},
+										{
+											role: "planner",
+											task: "Plan adaptive target",
+										},
+									],
+								},
+								{
+									name: "build",
+									tasks: [
+										{
+											role: "executor",
+											task: "Implement adaptive target",
+										},
+									],
+								},
+								{
+									name: "check",
+									tasks: [
+										{
+											role: "reviewer",
+											task: "Review adaptive target",
+										},
+										{
+											role: "test-engineer",
+											task: "Test adaptive target",
+										},
+										{
+											role: "writer",
+											task: "Summarize adaptive target",
+										},
+									],
+								},
+							],
+						})}\nADAPTIVE_PLAN_JSON_END`
+					: `[MOCK] JSON success for ${input.agent.name}`;
+			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
+			await observeStdoutChunk(input, stdout);
+			return { exitCode: 0, stdout, stderr: "" };
+		}
+		if (mock === "retryable-failure")
+			return {
+				exitCode: 1,
+				stdout: "",
+				stderr: "[MOCK] rate limit: mock failure",
+			};
+		// E2E fallback-chain fixture: invocation #1 returns a SILENT retryable
+		// failure (exit code 0, no real assistant text, message_end carries a
+		// retryable-pattern errorMessage). Invocation #2+ delegates to the
+		// standard json-success shape. Counter lives in os.tmpdir() keyed by
+		// process.pid + mock name so concurrent test processes don't collide.
+		// The test cleans up the file in its finally block.
+		if (mock === "retryable-failure-then-success") {
+			const counterFile = path.join(os.tmpdir(), `pi-crew-mock-counter-${process.pid}-retryable-failure-then-success`);
+			let count = 0;
+			try {
+				const raw = fs.readFileSync(counterFile, "utf-8");
+				const parsed = Number.parseInt(raw.trim(), 10);
+				if (Number.isFinite(parsed) && parsed >= 0) count = parsed;
+			} catch {
+				// file missing or unreadable — first invocation in this process
+			}
+			count += 1;
+			try {
+				atomicWriteFile(counterFile, String(count));
+			} catch (error) {
+				logInternalError("child-pi.mock-counter-write", error as Error, `file=${counterFile}`);
+			}
+			if (count === 1) {
+				// Silent retryable failure: exit 0, no real text, message_end
+				// carries errorMessage matching `/provider[_ ]?error/i` so that
+				// `detectRetryableModelFailureFromOutput` surfaces it as an error
+				// and `isRetryableModelFailure` routes the next attempt to the
+				// next candidate model. `stopReason:"error"` (NOT "stop") so
+				// `isFinalAssistantEvent` does NOT prematurely terminate the run.
+				const failureEvent = {
+					type: "message_end",
+					message: {
+						role: "assistant",
+						content: [],
+						errorMessage: "Provider error: api_error",
+						stopReason: "error",
+					},
+				};
+				const stdout = `${JSON.stringify(failureEvent)}\n`;
+				await observeStdoutChunk(input, stdout);
+				return { exitCode: 0, stdout, stderr: "" };
+			}
+			// Subsequent invocations: delegate to json-success shape so the
+			// fallback chain's second attempt succeeds and the run completes.
+			const text = `[MOCK] JSON success for ${input.agent.name}`;
+			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
+			await observeStdoutChunk(input, stdout);
+			return { exitCode: 0, stdout, stderr: "" };
+		}
+		return { exitCode: 1, stdout: "", stderr: `[MOCK] failure: ${mock}` };
+	}
+	// H-7 step 6: spawn/env/args preparation extracted to child-pi-spawn.ts.
+	// prepareSpawnContext builds the worker args, attaches the steering file env,
+	// and handles the pre-spawn abort check (returns an immediate-abort result
+	// if the parent signal has already fired).
+	//
+	// Phase 0 broker: if the caller did not pre-fill `brokerSpawn`, ask the
+	// optional issuer for one. The issuer is gated by the lifecycle controller
+	// (root-session + flag); a no-op issuer yields undefined (no credentials).
+	let brokerSpawn = input.brokerSpawn;
+	const brokerIssuer = input.brokerIssuer ?? getActiveBrokerIssuer();
+	if (!brokerSpawn && brokerIssuer && input.runId) {
+		try {
+			brokerSpawn = await brokerIssuer(input.runId, input.agentId);
+		} catch {
+			brokerSpawn = undefined;
+		}
+	}
+	const spawnPrep = prepareSpawnContext(brokerSpawn ? { ...input, brokerSpawn } : input, effectiveTask);
+	if (spawnPrep.kind === "aborted") return spawnPrep.result;
+	const { spawnSpec, mergedEnv, tempDir, builtEnv } = spawnPrep.ctx;
+	try {
+		return await new Promise<ChildPiRunResult>((resolve) => {
+			// Compose the final SpawnOptions: canary + filter + spread are now
+			// owned by buildFinalChildPiSpawnOptions (see child-pi-spawn.ts, BLOCKER 2 / S5).
+			const spawnOptions = buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model);
+			const child = spawn(spawnSpec.command, spawnSpec.args, spawnOptions);
+			if (child.pid) {
+				registerActiveChild(child.pid, child);
+				input.onSpawn?.(child.pid);
+				input.onLifecycleEvent?.({
+					type: "spawned",
+					pid: child.pid,
+					ts: new Date().toISOString(),
+				});
+				// Register with cleanup handler for graceful shutdown
+				if (input.runId && input.agentId) {
+					registerChildProcess(child.pid, input.runId, input.agentId);
+				}
+			} else {
+				input.onLifecycleEvent?.({
+					type: "spawn_error",
+					error: "spawn returned no pid",
+					ts: new Date().toISOString(),
+				});
+			}
+			let stdout = "";
+			let stderr = "";
+			let settled = false;
+			let childExited = false;
+			let postExitGuardCleanup: (() => void) | undefined;
+			let finalDrainTimer: NodeJS.Timeout | undefined;
+			let hardKillTimer: NodeJS.Timeout | undefined;
+			let noResponseTimer: NodeJS.Timeout | undefined;
+			const finalDrainMs = input.finalDrainMs ?? FINAL_DRAIN_MS;
+			const hardKillMs = input.hardKillMs ?? HARD_KILL_MS;
+			// Phase-0 diagnostic (HB-003a): track the final-drain race that produces
+			// `exit null` for ctx.agent({disableTools:true}). These vars are READ-ONLY
+			// instrumentation — no behavior change. finalDrainArmed lets the close
+			// handler know a drain timer existed even after clearFinalDrainTimers() ran;
+			// spawnMonotonicMs gives us relative timing to distinguish a race from a crash.
+			let finalDrainArmed = false;
+			// F12: monotonic timestamp of the last stdout JSON event (any event —
+			// we want to know when stdout *stopped*, not when the final assistant
+			// event arrived). Updated on every onJsonEvent dispatch.
+			let lastStdoutActivityMonotonicMs = performance.now();
+			let finalDrainFiredMonotonicMs: number | undefined;
+			const spawnMonotonicMs = performance.now();
+			let finalAssistantEventMonotonicMs: number | undefined;
+			// FIX (Round 14): Bound the env-controlled response timeout to
+			// [1_000ms, 3_600_000ms] (1s–1h) so a hostile or accidental value
+			// (e.g. 1, or 999_999_999) cannot disable the timeout or cause
+			// instant kills. Out-of-range values fall back to the input or
+			// built-in default.
+			const RESPONSE_TIMEOUT_MIN_MS = 1_000;
+			const RESPONSE_TIMEOUT_MAX_MS = 3_600_000;
+			const responseTimeoutEnv = Number.parseInt(process.env.PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS ?? "", 10);
+			const envInRange =
+				Number.isFinite(responseTimeoutEnv) &&
+				responseTimeoutEnv >= RESPONSE_TIMEOUT_MIN_MS &&
+				responseTimeoutEnv <= RESPONSE_TIMEOUT_MAX_MS;
+			const responseTimeoutMs = envInRange ? responseTimeoutEnv : (input.responseTimeoutMs ?? RESPONSE_TIMEOUT_MS);
+			let responseTimeoutHit = false;
+			let forcedFinalDrain = false;
+			let abortRequested = input.signal?.aborted === true;
+			let hardKilled = false;
+			const cleanupErrors: string[] = [];
+			const steeringController = new ChildPiSteeringController(input.maxTurns, input.graceTurns);
+			// Track in-flight operations for proper rejection on unexpected exit
+			interface PendingOperation {
+				id: string;
+				type: "prompt" | "steer" | "json_event";
+				startedAt: number;
+			}
+			const pendingOperations = new Map<string, PendingOperation>();
+			let operationIdCounter = 0;
+
+			const startOperation = (type: PendingOperation["type"]): string => {
+				const id = `op-${++operationIdCounter}`;
+				pendingOperations.set(id, { id, type, startedAt: Date.now() });
+				return id;
+			};
+
+			const completeOperation = (id: string): void => {
+				pendingOperations.delete(id);
+			};
+
+			const rejectPendingOperations = (error: Error): void => {
+				pendingOperations.forEach((op, id) => {
+					logInternalError(
+						"child-pi.pending-operation-rejected",
+						error,
+						`opId=${id} type=${op.type} elapsed=${Date.now() - op.startedAt}ms`,
+					);
+				});
+				pendingOperations.clear();
+			};
+
+			const steerInjectionFailed = false;
+			let abortDueToParentSignal = false;
+			// CP-1: track whether the turn-limit hard-abort has been initiated. Once
+			// true, we must NOT restart the no-response timer — the child is already
+			// being killed via killProcessTree (SIGTERM → SIGKILL after 3s), and
+			// restarting the timer would delay detection of a SIGTERM-ignoring child.
+			// Round 27 (BUG 4): extract to a named handler so settle() can remove it.
+			// The previous anonymous listener was never removed → on runs with >10
+			// tasks sharing one AbortSignal (background-runner), Node emitted
+			// MaxListenersExceededWarning and each leaked listener pinned the task's
+			// stack frame (abortDueToParentSignal closure) in memory. { once: true }
+			// only auto-removes AFTER the signal fires; on normal completion it leaks.
+			const onParentAbort = (): void => {
+				abortDueToParentSignal = true;
+			};
+			input.signal?.addEventListener("abort", onParentAbort, {
+				once: true,
+			});
+			const restartNoResponseTimer = (): void => {
+				if (responseTimeoutMs <= 0) return;
+				if (noResponseTimer) clearTimeout(noResponseTimer);
+				noResponseTimer = setTimeout(() => {
+					responseTimeoutHit = true;
+					// Capture stderr at timeout moment for debugging
+					// SEC-1: redact secrets before embedding in lifecycle event so
+					// worker-emitted secrets (API keys etc.) don't bypass redaction.
+					const timeoutStderr = redactStderrExcerpt(stderr, 1024); // Last 1KB of stderr (redacted, SEC-1)
+					input.onLifecycleEvent?.({
+						type: "response_timeout",
+						pid: child.pid,
+						error: `No output for ${responseTimeoutMs}ms`,
+						ts: new Date().toISOString(),
+						stderr: timeoutStderr || undefined,
+					});
+					killProcessTree(child.pid, child);
+					try {
+						child.kill(process.platform === "win32" ? undefined : "SIGTERM");
+					} catch (error) {
+						logInternalError("child-pi.response-timeout-term", error, `pid=${child.pid}`);
+					}
+					// #3 hardening: if the child never exits (zombie) and neither the
+					// 'exit' nor 'close' event ever fires, the promise would hang forever.
+					// SIGKILL fires ~3s after SIGTERM via hardKillTimer in killProcessPid,
+					// but on platforms where SIGKILL also fails (e.g. permission issues),
+					// add a bounded safety settle so the promise always resolves. Using
+					// hardKillMs + 2s as the safety window: enough for SIGKILL to work
+					// normally, but forces settle if the process is truly immortal.
+					// NOTE: we do NOT clear hardKillTimer here (that would defeat its purpose);
+					// we intentionally add a parallel safety path.
+					const SAFETY_SETTLE_MS = HARD_KILL_MS + 2000;
+					const safetyTimer = setTimeout(() => {
+						if (settled || childExited) return;
+						logInternalError(
+							"child-pi.settle-safety-fired",
+							new Error(`Child did not exit within ${SAFETY_SETTLE_MS}ms of kill; forcing settle`),
+							`pid=${child.pid}, responseTimeoutMs=${responseTimeoutMs}`,
+						);
+						// Verify the child is still alive before forcing settle.
+						// If it somehow exited between childExited=false and here, the
+						// settled/childExited guard prevents double-settle (harmless but noisy).
+						try {
+							process.kill(child.pid!, 0);
+							// Child still alive — force settle with timeout error.
+							const timeoutErr = `Child Pi produced no new output for ${responseTimeoutMs}ms; killed but did not exit within ${SAFETY_SETTLE_MS}ms (possible zombie).`;
+							void settle({
+								exitCode: null,
+								stdout,
+								stderr,
+								error: timeoutErr,
+								exitStatus: {
+									exitCode: null,
+									cancelled: abortRequested,
+									timedOut: true,
+									killed: hardKilled,
+									cleanupErrors,
+									finalDrainMs,
+									crashClass: "timeout",
+								},
+							});
+						} catch {
+							// ESRCH / EPERM — child is already gone. The 'exit'/'close' handler
+							// will fire shortly (or already fired in a race). Let it settle normally.
+						}
+					}, SAFETY_SETTLE_MS);
+					safetyTimer.unref();
+				}, responseTimeoutMs);
+				noResponseTimer.unref();
+			};
+			const clearNoResponseTimer = (): void => {
+				if (noResponseTimer) clearTimeout(noResponseTimer);
+				noResponseTimer = undefined;
+			};
+			restartNoResponseTimer();
+			const lineObserver = new ChildPiLineObserver({
+				...input,
+				onStdoutLine: (line) => {
+					if (!steeringController.isHardAbortInitiated()) restartNoResponseTimer();
+					stdout = appendBoundedTail(stdout, `${line}\n`);
+					input.onStdoutLine?.(line);
+				},
+				onJsonEvent: (event) => {
+					if (!steeringController.isHardAbortInitiated()) restartNoResponseTimer();
+					const eventOpId = startOperation("json_event");
+					try {
+						// Turn-count-based steering: soft limit steer + hard abort after graceTurns
+						if (event && typeof event === "object" && !Array.isArray(event)) {
+							const obj = event as Record<string, unknown>;
+							if (obj.type === "turn_end") {
+								// H-7 step 5: steering state machine extracted to ChildPiSteeringController.
+								const action = steeringController.onTurnEnd(child.pid, child, input.steeringFile);
+								if (action.kind === "hardAbort") killProcessTree(action.pid, action.child);
+							}
+						}
+						completeOperation(eventOpId);
+					} catch (err) {
+						completeOperation(eventOpId);
+						throw err;
+					}
+					// F12: capture monotonic timestamp BEFORE dispatching — any stdout
+					// JSON event counts as activity. This lets the quiet-window
+					// detection measure "time since last byte of stdout" accurately
+					// regardless of what onJsonEvent does.
+					lastStdoutActivityMonotonicMs = performance.now();
+					input.onJsonEvent?.(event);
+					if (!isFinalAssistantEvent(event) || childExited || settled || finalDrainTimer) return;
+					finalAssistantEventMonotonicMs = performance.now();
+					finalDrainArmed = true; // Phase-0 diagnostic: track that a drain timer was created.
+					// F12: alongside the 5 s ceiling timer, start a polling watcher
+					// that fires the drain early if stdout goes quiet for `quietMs`
+					// after the final assistant event. Heavy children that emit a
+					// stopReason=stop message_end and then sit idle will exit in
+					// ~quietMs (default 800 ms) instead of up to up to 5 s. unref() so
+					// the poller never holds the event loop on shutdown.
+					// NOTE: The polling watcher is NOT explicitly cleared on process exit.
+					// This is safe because: (1) it's unref()'d, so it won't prevent exit;
+					// (2) the `settled || childExited` guard at the top prevents firing
+					// after the child has exited; (3) sending SIGTERM to an already-
+					// exiting process is harmless. The `finalDrainQuietMs` config allows
+					// disabling this behavior (set >= finalDrainMs, e.g., 10000).
+					const quietMs = input.finalDrainQuietMs ?? DEFAULT_CHILD_PI.finalDrainQuietMs;
+					if (quietMs < (input.finalDrainMs ?? DEFAULT_CHILD_PI.finalDrainMs)) {
+						const pollHandle = setInterval(() => {
+							if (settled || childExited) {
+								clearInterval(pollHandle);
+								pollHandle.unref();
+								return;
+							}
+							const sinceLast = performance.now() - lastStdoutActivityMonotonicMs;
+							if (sinceLast >= quietMs) {
+								clearInterval(pollHandle);
+								pollHandle.unref();
+								// Trigger the same drain path as the 5 s timer:
+								// mark forced, fire final_drain lifecycle, SIGTERM.
+								forcedFinalDrain = true;
+								finalDrainFiredMonotonicMs = performance.now();
+								input.onLifecycleEvent?.({
+									type: "final_drain",
+									pid: child.pid,
+									ts: new Date().toISOString(),
+									reason: "stdout-quiet",
+								});
+								try {
+									child.kill(process.platform === "win32" ? undefined : "SIGTERM");
+								} catch (error) {
+									logInternalError("child-pi.quiet-drain-term", error, `pid=${child.pid}`);
+								}
+								// Mark for hard kill fallback so the existing timer is
+								// still reaped if it ever fires later.
+								hardKillTimer = setTimeout(() => {
+									if (settled || childExited) return;
+									try {
+										hardKilled = true;
+										input.onLifecycleEvent?.({
+											type: "hard_kill",
+											pid: child.pid,
+											ts: new Date().toISOString(),
+										});
+										child.kill(process.platform === "win32" ? undefined : "SIGKILL");
+									} catch (error) {
+										logInternalError("child-pi.quiet-drain-hard-kill", error, `pid=${child.pid}`);
+									}
+								}, hardKillMs);
+								hardKillTimer.unref();
+								// Cancel the 5 s ceiling so we don't double-fire.
+								if (finalDrainTimer) {
+									clearTimeout(finalDrainTimer);
+									finalDrainTimer = undefined;
+								}
+							}
+						}, 200);
+						pollHandle.unref();
+					}
+					finalDrainTimer = setTimeout(() => {
+						if (settled || childExited) return;
+						forcedFinalDrain = true;
+						finalDrainFiredMonotonicMs = performance.now(); // Phase-0 diagnostic: race timing.
+						input.onLifecycleEvent?.({
+							type: "final_drain",
+							pid: child.pid,
+							ts: new Date().toISOString(),
+						});
+						try {
+							child.kill(process.platform === "win32" ? undefined : "SIGTERM");
+						} catch (error) {
+							logInternalError("child-pi.final-drain-term", error, `pid=${child.pid}`);
+						}
+						hardKillTimer = setTimeout(() => {
+							if (settled || childExited) return;
+							try {
+								hardKilled = true;
+								input.onLifecycleEvent?.({
+									type: "hard_kill",
+									pid: child.pid,
+									ts: new Date().toISOString(),
+								});
+								child.kill(process.platform === "win32" ? undefined : "SIGKILL");
+							} catch (error) {
+								logInternalError("child-pi.final-drain-kill", error, `pid=${child.pid}`);
+							}
+						}, hardKillMs);
+						hardKillTimer.unref();
+					}, finalDrainMs);
+					finalDrainTimer.unref();
+				},
+			});
+
+			const clearFinalDrainTimers = (): void => {
+				if (finalDrainTimer) clearTimeout(finalDrainTimer);
+				if (hardKillTimer) clearTimeout(hardKillTimer);
+				finalDrainTimer = undefined;
+				hardKillTimer = undefined;
+			};
+			const clearPostExitGuard = (): void => {
+				if (postExitGuardCleanup) {
+					postExitGuardCleanup();
+					postExitGuardCleanup = undefined;
+				}
+			};
+			const clearChildPiTimeouts = (): void => {
+				clearNoResponseTimer();
+				clearFinalDrainTimers();
+				clearPostExitGuard();
+			};
+
+			const settle = (result: ChildPiRunResult): Promise<void> => {
+				if (settled) return Promise.resolve();
+				settled = true;
+				clearChildPiTimeouts();
+				// OPT-06 follow-up: lineObserver.flush() is now async (returns
+				// Promise<void>) and drains the module-scoped transcript batch buffer
+				// before resolving. We must await it before calling `resolve()`
+				// below so callers that read the transcript file post-`runChildPi`
+				// see all written lines. Caller invocations of `settle` from
+				// sync event handlers (`child.on('close'|'exit'|'error')`,
+				// safety timer) use `void settle(...)` — errors are caught and
+				// logged inside, and `resolve()` only fires after the drain
+				// completes, so runChildPi's outer Promise resolves with a
+				// durable transcript on disk.
+				return lineObserver
+					.flush()
+					.then(() => {
+						input.signal?.removeEventListener("abort", abort);
+						input.signal?.removeEventListener("abort", onParentAbort);
+						try {
+							cleanupTempDir(tempDir);
+						} catch (error) {
+							cleanupErrors.push(error instanceof Error ? error.message : String(error));
+						}
+						// Catch all errors from settle to prevent unhandled rejection from propagating
+						try {
+							resolve({
+								...result,
+								rawFinalText: lineObserver.getRawFinalText(),
+								intermediateFindings: lineObserver.getIntermediateFindings(),
+								exitStatus: result.exitStatus ?? {
+									exitCode: result.exitCode,
+									cancelled: abortRequested,
+									timedOut: responseTimeoutHit,
+									killed: hardKilled,
+									// Phase-0 diagnostic (HB-003a): surface the final-drain race state.
+									// finalDrainArmed lets Phase 1 decide whether a signal-death (exitCode=null)
+									// should be treated as a forced final drain. READ-ONLY for now.
+									...(finalDrainArmed || forcedFinalDrain
+										? {
+												finalDrainArmed,
+												forcedFinalDrain,
+												finalDrainFiredMonotonicMs,
+											}
+										: {}),
+									cleanupErrors,
+									finalDrainMs,
+								},
+							});
+						} catch (resolveError) {
+							logInternalError(
+								"child-pi.settle-resolve",
+								resolveError,
+								`result=${JSON.stringify({ exitCode: result.exitCode })}`,
+							);
+						}
+					})
+					.catch((flushError) => {
+						// Drain failed — log and still resolve so runChildPi doesn't hang.
+						logInternalError(
+							"child-pi.settle-flush-failed",
+							flushError,
+							`result=${JSON.stringify({ exitCode: result.exitCode })}`,
+						);
+						input.signal?.removeEventListener("abort", abort);
+						input.signal?.removeEventListener("abort", onParentAbort);
+						try {
+							cleanupTempDir(tempDir);
+						} catch (error) {
+							cleanupErrors.push(error instanceof Error ? error.message : String(error));
+						}
+						try {
+							resolve({
+								...result,
+								rawFinalText: lineObserver.getRawFinalText(),
+								intermediateFindings: lineObserver.getIntermediateFindings(),
+								exitStatus: result.exitStatus ?? {
+									exitCode: result.exitCode,
+									cancelled: abortRequested,
+									timedOut: responseTimeoutHit,
+									killed: hardKilled,
+									...(finalDrainArmed || forcedFinalDrain
+										? {
+												finalDrainArmed,
+												forcedFinalDrain,
+												finalDrainFiredMonotonicMs,
+											}
+										: {}),
+									cleanupErrors,
+									finalDrainMs,
+								},
+							});
+						} catch (resolveError) {
+							logInternalError(
+								"child-pi.settle-resolve",
+								resolveError,
+								`result=${JSON.stringify({ exitCode: result.exitCode })}`,
+							);
+						}
+					});
+			};
+
+			const abort = (): void => {
+				abortRequested = true;
+				clearNoResponseTimer();
+				killProcessTree(child.pid, child);
+				if (process.platform !== "win32") {
+					trySignalChild(child, "SIGTERM");
+				}
+				try {
+					child.kill(process.platform === "win32" ? undefined : "SIGTERM");
+				} catch {
+					// Ignore kill races.
+				}
+				// 3.5 — fast-escalate to SIGKILL within 200ms on explicit cancel
+				// so /team-cancel completes round-trip well under the operator
+				// expectation. The standard finalDrainMs / HARD_KILL_MS paths
+				// are for graceful drain, not user-initiated cancel.
+				const cancelHardKill = setTimeout(() => {
+					if (settled || childExited) return;
+					try {
+						hardKilled = true;
+						child.kill(process.platform === "win32" ? undefined : "SIGKILL");
+					} catch (error) {
+						logInternalError("child-pi.cancel-fast-kill", error, `pid=${child.pid}`);
+					}
+				}, 200);
+				cancelHardKill.unref();
+			};
+
+			input.signal?.addEventListener("abort", abort, { once: true });
+			// 3.1 — soft watermark backpressure. When inbound stdout exceeds
+			// 256KB before the next macrotask, pause for 50ms so the line
+			// observer + ancillary handlers get to drain. Prevents the runaway
+			// case where a chatty child saturates the parent event loop.
+			const BACKPRESSURE_HIGH = 256 * 1024;
+			let backpressureBytes = 0;
+			const releaseBackpressure = (): void => {
+				backpressureBytes = 0;
+				try {
+					child.stdout?.resume();
+				} catch {
+					/* ignore */
+				}
+			};
+			child.stdout?.on("data", (chunk: Buffer) => {
+				if (!steeringController.isHardAbortInitiated()) restartNoResponseTimer();
+				const text = chunk.toString("utf-8");
+				backpressureBytes += text.length;
+				try {
+					lineObserver.observe(text);
+				} catch (err) {
+					logInternalError("child-pi.line-observer-observe", err, `text=${text.slice(0, 100)}`);
+				}
+				if (backpressureBytes > BACKPRESSURE_HIGH && child.stdout && !child.stdout.isPaused()) {
+					try {
+						child.stdout.pause();
+					} catch {
+						/* ignore */
+					}
+					const timer = setTimeout(releaseBackpressure, 50);
+					timer.unref();
+				}
+			});
+			child.stderr?.on("data", (chunk: Buffer) => {
+				if (!steeringController.isHardAbortInitiated()) restartNoResponseTimer();
+				stderr = appendBoundedTail(stderr, chunk.toString("utf-8"));
+			});
+			child.on("error", (error) => {
+				// Reject pending operations with process error context
+				// SEC-1: redact stderr secrets embedded in the error message + excerpt.
+				const processError = new Error(
+					`Child Pi process error: ${error.message}. Stderr: ${redactStderrExcerpt(stderr, 500) || "(none)"}`,
+				);
+				rejectPendingOperations(processError);
+				try {
+					input.onLifecycleEvent?.({
+						type: "spawn_error",
+						pid: child.pid,
+						error: processError.message,
+						ts: new Date().toISOString(),
+						stderrExcerpt: redactStderrExcerpt(stderr, 500) || undefined,
+					});
+				} catch (err) {
+					logInternalError("child-pi.on-lifecycle-event", err, `event=error, pid=${child.pid}`);
+				}
+				void settle({
+					exitCode: null,
+					stdout,
+					stderr,
+					error: processError.message,
+					exitStatus: {
+						exitCode: null,
+						cancelled: abortRequested,
+						timedOut: responseTimeoutHit,
+						killed: false,
+						cleanupErrors,
+						finalDrainMs,
+						crashClass: classifyProcessCrash({
+							exitCode: null,
+							cancelled: abortRequested,
+							timedOut: responseTimeoutHit,
+							spawnError: error,
+							stderrSnippet: stderr ? redactStderrExcerpt(stderr, 1000) : undefined,
+						}).crashClass,
+					},
+				});
+			});
+			child.on("exit", (code, signal) => {
+				if (child.pid) {
+					unregisterActiveChild(child.pid);
+					clearHardKillTimer(child.pid);
+					// Unregister from cleanup handler
+					unregisterChildProcess(child.pid);
+				}
+				// Build comprehensive exit error for unexpected exits
+				// Round-10 test fix: also require non-zero exit code OR a known abnormal condition.
+				// Previously fired "exited unexpectedly" on every clean exit (code=0) because the
+				// OS-level 'exit' event fires BEFORE pi's 'agent_end' JSON event reaches the line
+				// observer (race). Worker actually succeeded but onLifecycleEvent reported an error.
+				const abnormalExit = code !== 0 && code !== null;
+				const isUnexpectedExit = !childExited && !settled && !responseTimeoutHit && !abortRequested && abnormalExit;
+				const exitError = isUnexpectedExit
+					? new Error(
+							`Child Pi process exited unexpectedly (code=${code ?? "null"} signal=${signal ?? "null"}). ` +
+								`Stderr: ${redactStderrExcerpt(stderr, 1000) || "(none)"}`,
+						)
+					: null;
+				if (exitError) {
+					rejectPendingOperations(exitError);
+				}
+				try {
+					// Phase-0 diagnostic (HB-003a): capture signal + drain timing in the
+					// exit lifecycle event so the exit-null race is diagnosable instead of
+					// opaque. `signal` was previously discarded after building the error msg.
+					input.onLifecycleEvent?.({
+						type: "exit",
+						pid: child.pid,
+						exitCode: code,
+						ts: new Date().toISOString(),
+						error: exitError?.message,
+						stderrExcerpt: isUnexpectedExit ? redactStderrExcerpt(stderr, 1000) || undefined : undefined,
+						// Phase-0 diagnostic fields (kept optional — no type change required).
+						...(signal ? { signal } : {}),
+						...(finalDrainArmed || forcedFinalDrain
+							? {
+									diagnostic: {
+										finalDrainArmed,
+										forcedFinalDrain,
+										finalDrainFiredMonotonicMs,
+										finalAssistantEventMonotonicMs,
+										exitMonotonicMs: performance.now() - spawnMonotonicMs,
+									},
+								}
+							: {}),
+					});
+				} catch (err) {
+					logInternalError("child-pi.on-lifecycle-event", err, `event=exit, pid=${child.pid}`);
+				}
+				childExited = true;
+				clearNoResponseTimer();
+				clearFinalDrainTimers();
+				if (!postExitGuardCleanup) {
+					postExitGuardCleanup = attachPostExitStdioGuard(child, {
+						idleMs: POST_EXIT_STDIO_GUARD_MS,
+						hardMs: HARD_KILL_MS,
+					});
+				}
+			});
+			child.on("close", (exitCode) => {
+				if (child.pid) {
+					unregisterActiveChild(child.pid);
+					clearHardKillTimer(child.pid);
+					// Unregister from cleanup handler
+					unregisterChildProcess(child.pid);
+				}
+				try {
+					input.onLifecycleEvent?.({
+						type: "close",
+						pid: child.pid,
+						exitCode,
+						ts: new Date().toISOString(),
+					});
+				} catch (err) {
+					logInternalError("child-pi.on-lifecycle-event", err, `event=close, pid=${child.pid}`);
+				}
+				const timeoutError =
+					responseTimeoutHit && !stderr.trim()
+						? {
+								error: `Child Pi produced no new output for ${responseTimeoutMs}ms; process was terminated as unresponsive.`,
+							}
+						: responseTimeoutHit && stderr.trim()
+							? {
+									error: `Child Pi timed out after ${responseTimeoutMs}ms with stderr: ${redactStderrExcerpt(stderr, 500)}`,
+								}
+							: undefined;
+				// M6 fix: log when forced final drain converts non-zero exit to 0.
+				// This is expected in normal operation (child finished cleanly but linger was killed),
+				// but the telemetry helps detect regressions where crashes are hidden.
+				if (forcedFinalDrain && !timeoutError && exitCode !== 0) {
+					logInternalError(
+						"child-pi.final-drain-zero-exit",
+						new Error(`Child exit code overridden to 0 after forced final drain (original=${exitCode})`),
+						`pid=${child.pid}, finalDrainMs=${finalDrainMs}`,
+					);
+				}
+				const finalExitCode = forcedFinalDrain && !timeoutError ? 0 : exitCode;
+				const wasGraceAborted =
+					steeringController.isSoftLimitReached() &&
+					steeringController.getTurnCount() >=
+						(steeringController.getMaxTurns() ?? 0) + (steeringController.getGraceTurns() ?? 5);
+				const wasParentAborted = abortDueToParentSignal && !wasGraceAborted;
+				// steerInjectionFailed is now always false (Phase-1 fix: steer backpressure
+				// is logged, not fatal). The steerError branch is retained for safety in
+				// case a future change reintroduces a fatal steer path.
+				const steerError = steerInjectionFailed ? "Steer injection failed due to stdin backpressure; process killed" : undefined;
+				// P0 crash taxonomy: classify the exit so callers/dashboards can bucket
+				// failure modes (timeout vs cancel vs native panic vs signal …).
+				// The classifier is a pure function; this is the single integration point.
+				const crashClassification = classifyProcessCrash({
+					exitCode: finalExitCode,
+					signal: child.signalCode ?? undefined,
+					cancelled: abortRequested,
+					timedOut: responseTimeoutHit,
+					killed: hardKilled,
+					spawnError: undefined,
+					stderrSnippet: stderr ? redactStderrExcerpt(stderr, 1000) : undefined,
+				});
+				void settle({
+					exitCode: finalExitCode,
+					stdout,
+					stderr,
+					...(timeoutError ? { error: timeoutError.error } : {}),
+					...(steerError ? { error: steerError } : {}),
+					aborted: wasGraceAborted || wasParentAborted,
+					steered: steeringController.isSoftLimitReached() && !wasGraceAborted,
+					exitStatus: {
+						exitCode: finalExitCode,
+						cancelled: abortRequested,
+						timedOut: responseTimeoutHit,
+						killed: hardKilled,
+						cleanupErrors,
+						finalDrainMs,
+						crashClass: crashClassification.crashClass,
+					},
+				});
+			});
+		});
+	} finally {
+		// cleanupTempDir is already called inside settle(), but guard against
+		// the case where settle() was never reached (spawn throws synchronously).
+		if (tempDir && fs.existsSync(tempDir)) {
+			cleanupTempDir(tempDir);
+		}
+	}
+}