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/broker-issuer.ts";
import { BoundedTail } from "../compaction/compact-stages/bounded-tail.ts";
import { FINAL_DRAIN_MS, HARD_KILL_MS, POST_EXIT_STDIO_GUARD_MS, RESPONSE_TIMEOUT_MS } from "./child-pi-constants.ts";
import { 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 { checkCrewDepth, cleanupTempDir } from "../model/pi-args.ts";
import { attachPostExitStdioGuard, trySignalChild } from "../process/post-exit-stdio-guard.ts";
import { classifyProcessCrash } from "../recovery/crash-classification.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;
	/** Team-role thinking override (takes precedence over agent.thinking). */
	thinkingOverride?: string;
	/** Root directory for artifacts (used to validate transcriptPath). */
	artifactsRoot?: string;
	/** Phase 1 scratchpad: model-fallback attempt index (0-based) for per-attempt
	 * snapshot relativePath `scratchpad/<taskId>.attempt-<attempt>.snapshot.json`
	 * (C3). Optional — worker defaults to attempt 0 when unset (e.g. custom
	 * agent spawn outside child-executor). */
	attempt?: number;
	/**
	 * 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 (RT-11):
				// ALWAYS register — every spawned child must be visible to host-SIGTERM
				// cleanup. Use synthetic IDs when the caller omitted runId/agentId so the
				// PID is still tracked for killProcessPid on session shutdown.
				registerChildProcess(
					child.pid,
					input.runId ?? `untracked-run-${child.pid}`,
					input.agentId ?? `untracked-agent-${child.pid}`,
				);
			} else {
				input.onLifecycleEvent?.({
					type: "spawn_error",
					error: "spawn returned no pid",
					ts: new Date().toISOString(),
				});
			}
			// P0-1: O(1)-amortized bounded accumulators (segment ring) — replaces the O(n²)
			// appendBoundedTail rebuild-per-line pattern that re-scanned 512 KiB every line.
			const stdoutTail = new BoundedTail();
			const stderrTail = new BoundedTail();
			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);
			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;
					// P0-1: snapshot the bounded stderr accumulator once for this timer fire.
					const stderr = stderrTail.value();
					// 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: stdoutTail.value(),
								stderr: stderrTail.value(),
								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();
					stdoutTail.push(`${line}\n`);
					input.onStdoutLine?.(line);
				},
				onJsonEvent: (event) => {
					if (!steeringController.isHardAbortInitiated()) restartNoResponseTimer();
					// 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);
						}
					}
					// 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();
				stderrTail.push(chunk.toString("utf-8"));
			});
			child.on("error", (error) => {
				// P0-1: snapshot the bounded accumulators once for this handler.
				const stdout = stdoutTail.value();
				const stderr = stderrTail.value();
				// 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)"}`,
				);
				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) => {
				// P0-1: snapshot the bounded stderr accumulator once for this handler.
				const stderr = stderrTail.value();
				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;
				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) => {
				// P0-1: snapshot the bounded accumulators once for this handler.
				const stdout = stdoutTail.value();
				const stderr = stderrTail.value();
				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;
				// 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 } : {}),
					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);
		}
	}
}
