pi-crew 0.2.19 → 0.2.21

package/src/runtime/async-runner.ts

@@ -1,4 +1,4 @@
-import { spawn, type SpawnOptions } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -102,14 +102,20 @@ export function getBackgroundRunnerCommand(
 ): { args: string[]; loader: "jiti" | "strip-types" } {
 	const loader = normalizeLoaderInput(loaderInput);
 	if (!loader) throw new Error(buildLoaderUnavailableMessage(packageRootFromRuntime()));
+	// Limit V8 heap to 512MB for the background runner to avoid triggering the
+	// Linux OOM killer. The runner itself is lightweight — it delegates work to
+	// child Pi processes — so 512MB is generous. Without this limit, Node.js
+	// defaults to ~1.5GB on 64-bit systems, which combined with jiti compilation
+	// and child processes can exhaust system memory.
+	const memoryLimit = "--max-old-space-size=512";
 	if (loader.kind === "jiti") {
 		return {
-			args: ["--import", pathToFileURL(loader.path).href, runnerPath, "--cwd", cwd, "--run-id", runId],
+			args: [memoryLimit, "--trace-uncaught", "--import", pathToFileURL(loader.path).href, runnerPath, "--cwd", cwd, "--run-id", runId],
 			loader: "jiti",
 		};
 	}
 	return {
-		args: ["--experimental-strip-types", runnerPath, "--cwd", cwd, "--run-id", runId],
+		args: [memoryLimit, "--experimental-strip-types", runnerPath, "--cwd", cwd, "--run-id", runId],
 		loader: "strip-types",
 	};
 }
@@ -119,42 +125,44 @@ export interface SpawnBackgroundTeamRunResult {
 	logPath: string;
 }
 
-export function buildBackgroundSpawnOptions(manifest: TeamRunManifest, logFd: number): SpawnOptions {
+export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise<SpawnBackgroundTeamRunResult> {
+	const runnerPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "background-runner.ts");
+	const logPath = path.join(manifest.stateRoot, "background.log");
+	fs.mkdirSync(manifest.stateRoot, { recursive: true });
+
 	// NOTE: Do NOT set PI_CREW_PARENT_PID for the background runner.
-	// The background runner is a top-level worker spawned by the team tool.
-	// When the team tool finishes, its process exits, and the background runner
-	// would incorrectly detect a "dead parent" and self-terminate.
-	// Child workers spawned BY the background runner will have the background
-	// runner as their parent, so they correctly die when the runner exits.
 	const { PI_CREW_PARENT_PID: _, ...envWithoutParentPid } = process.env;
-	return {
+
+	const loader = resolveTypeScriptLoader();
+	if (!loader) {
+		const message = buildLoaderUnavailableMessage(packageRootFromRuntime());
+		appendEvent(manifest.eventsPath, { type: "async.failed", runId: manifest.runId, message });
+		throw new Error(message);
+	}
+	const command = getBackgroundRunnerCommand(runnerPath, manifest.cwd, manifest.runId, loader);
+	fs.appendFileSync(logPath, `[pi-crew] background loader=${command.loader}\n`, "utf-8");
+
+	// Spawn the background runner as a fully detached process with its own session.
+	// BUG #17 FIX: setsid:true + detached:true creates a process that:
+	//   1. Has its own session (SID = PID) — immune to terminal/SIGTERM signals
+	//   2. Is detached (unref'd) — parent exit doesn't affect it
+	//   3. Has its own process group (PGID = PID) — process group kills don't reach it
+	//
+	// IMPORTANT: session_shutdown handlers must NOT kill async runners.
+	// See register.ts cleanupRuntime — the kill loop was commented out.
+	const child = spawn(process.execPath, command.args, {
 		cwd: manifest.cwd,
 		detached: true,
-		stdio: ["ignore", logFd, logFd],
+		setsid: true as any,
+		stdio: ["ignore", "pipe", "pipe"],
 		env: envWithoutParentPid,
 		windowsHide: true,
-	};
-}
+	} as any) as any;
+	child.on("error", (error: Error) => {
+		console.error(`[pi-crew] async spawn failed: ${error.message}`);
+	});
+	child.unref();
 
-export function spawnBackgroundTeamRun(manifest: TeamRunManifest): SpawnBackgroundTeamRunResult {
-	const runnerPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "background-runner.ts");
-	const logPath = path.join(manifest.stateRoot, "background.log");
-	fs.mkdirSync(manifest.stateRoot, { recursive: true });
-	const logFd = fs.openSync(logPath, "a");
-	try {
-		const loader = resolveTypeScriptLoader();
-		if (!loader) {
-			const message = buildLoaderUnavailableMessage(packageRootFromRuntime());
-			appendEvent(manifest.eventsPath, { type: "async.failed", runId: manifest.runId, message });
-			throw new Error(message);
-		}
-		const command = getBackgroundRunnerCommand(runnerPath, manifest.cwd, manifest.runId, loader);
-		fs.appendFileSync(logPath, `[pi-crew] background loader=${command.loader}\n`, "utf-8");
-		const child = spawn(process.execPath, command.args, buildBackgroundSpawnOptions(manifest, logFd));
-		child.unref();
-
-		return { pid: child.pid, logPath };
-	} finally {
-		fs.closeSync(logFd);
-	}
+	return { pid: child.pid, logPath };
 }
+

package/src/runtime/background-runner.ts

@@ -24,6 +24,34 @@ import { expandParallelResearchWorkflow } from "./parallel-research.ts";
 import { writeAsyncStartMarker } from "./async-marker.ts";
 import { startParentGuard, stopParentGuard } from "./parent-guard.ts";
 
+/**
+ * Heartbeat mechanism: periodically write a heartbeat file so the stale reconciler
+ * can distinguish "process died" from "process still alive but quiet".
+ * Without this, the reconciler relies solely on process.kill(pid, 0) which can
+ * false-positive when a process is SIGKILLed and the PID hasn't been recycled yet.
+ */
+function startHeartbeat(stateRoot: string, eventsPath: string, runId: string): () => void {
+	const heartbeatPath = path.join(stateRoot, "heartbeat.json");
+	const writeHeartbeat = (): void => {
+		try {
+			const mem = process.memoryUsage();
+			fs.writeFileSync(heartbeatPath, JSON.stringify({
+				pid: process.pid,
+				at: Date.now(),
+				runId,
+				memory: { heapUsedMb: Math.round(mem.heapUsed / 1024 / 1024), rssMb: Math.round(mem.rss / 1024 / 1024) },
+			}), "utf-8");
+		} catch {
+			/* ignore — best-effort */
+		}
+	};
+	// Write immediately so the stale reconciler can use heartbeat age as liveness evidence.
+	writeHeartbeat();
+	const interval = setInterval(writeHeartbeat, 15_000);
+	interval.unref();
+	return () => clearInterval(interval);
+}
+
 /**
  * Remove macOS malloc-stack-logging vars that get inherited by child shells.
  * Without this, every subprocess prints "MallocStackLogging: can't turn off..." to stderr.
@@ -69,28 +97,111 @@ function setupUnhandledRejectionGuard(state: { cwd?: string; runId?: string; eve
 	process.on("unhandledRejection", (reason, promise) => {
 		const message = reason instanceof Error ? reason.message : String(reason);
 		console.error("[background-runner] UNHANDLED REJECTION:", reason);
+		console.error("[background-runner] Stack:", reason instanceof Error ? reason.stack : "N/A");
 		try {
-			// Try to write async.failed event if we have the necessary state
 			if (state.eventsPath && state.runId) {
 				appendEvent(state.eventsPath, {
 					type: "async.failed",
 					runId: state.runId,
 					message: `Unhandled rejection: ${message}`,
-					data: { reason: String(reason), handled: false },
+					data: { reason: String(reason), stack: reason instanceof Error ? reason.stack : undefined, handled: false },
 				});
 			}
 		} catch (appendErr) {
 			console.error("[background-runner] Failed to write async.failed event:", appendErr);
 		}
+		// BUG #17 FIX: Do NOT call process.exit() here. Previously, unhandled
+		// rejection from child Pi workers would kill the entire background runner.
+		// Instead, set exitCode and let the run complete normally.
 		process.exitCode = 1;
-		// Give async operations a moment to flush before exit
-		setTimeout(() => process.exit(1), 100);
 	});
 }
 
 async function main(): Promise<void> {
+	// Redirect console to background.log since stdio is "ignore" in detached mode.
+	// Must be BEFORE any console.log/console.error calls.
+	const _cwd = argValue("--cwd");
+	const _runId = argValue("--run-id");
+	if (_cwd && _runId) {
+		try {
+			const logPath = path.join(_cwd, ".crew/state/runs", _runId, "background.log");
+			const logFd = fs.openSync(logPath, "a");
+			const origWrite = (prefix: string) => (data: any, ...args: any[]) => {
+				const msg = [data, ...args].map(String).join(" ") + "\n";
+				fs.writeSync(logFd, msg);
+			};
+			console.log = origWrite("OUT");
+			console.error = origWrite("ERR");
+		} catch { /* best-effort */ }
+	}
+
 	// Scrub macOS malloc vars BEFORE anything else — must be clean for all child processes
 	scrubProcessEnv();
+	// Install signal handlers EARLY — log events before exiting so we can distinguish
+	// OOM/SIGKILL (no event) from SIGTERM/SIGINT (event written).
+	const signalLog = (sig: string): void => {
+		const cwd = argValue("--cwd");
+		const runId = argValue("--run-id");
+		if (cwd && runId) {
+			const loaded = loadRunManifestById(cwd, runId);
+			if (loaded) appendEvent(loaded.manifest.eventsPath, { type: "async.failed", runId, message: `Background runner received ${sig} — exiting.`, data: { signal: sig, pid: process.pid } });
+		}
+	};
+	// BUG #17 DIAGNOSTIC: Write exit code to file for debugging.
+	process.on("exit", (code) => {
+		try {
+			require("node:fs").appendFileSync(
+				manifest.stateRoot + '/exit-code.txt',
+				`${new Date().toISOString()} exit_code=${code} pid=${process.pid}\n`
+			);
+		} catch {}
+	});
+
+	process.on("SIGTERM", () => {
+		// BUG #17 FIX: Ignore SIGTERM.
+		// IMPORTANT: Perform real I/O here to flush io_uring state after EINTR.
+		// Without I/O, io_uring can enter corrupted state and cause silent crash.
+		const cwd = argValue("--cwd");
+		const runId = argValue("--run-id");
+		if (cwd && runId) {
+			try {
+				const loaded = loadRunManifestById(cwd, runId);
+				if (loaded) appendEvent(loaded.manifest.eventsPath, { type: "async.sigterm_ignored", runId, message: `SIGTERM ignored pid=${process.pid}`, data: { pid: process.pid, ppid: process.ppid } });
+			} catch { /* best-effort */ }
+		}
+	});
+	process.on("SIGINT", () => { signalLog("SIGINT"); process.exit(130); });
+	// BUG #17: Catch ALL signals to identify what kills the background runner
+	for (const sig of ["SIGHUP", "SIGUSR1", "SIGUSR2", "SIGPIPE", "SIGALRM", "SIGPROF", "SIGIO", "SIGPWR", "SIGSYS", "SIGURG", "SIGWINCH", "SIGCONT", "SIGTSTP", "SIGTTIN", "SIGTTOU", "SIGVTALRM", "SIGXCPU", "SIGXFSZ"] as const) {
+		try {
+			process.on(sig, () => {
+				signalLog(sig);
+				try {
+					const loaded = loadRunManifestById(cwd!, runId!);
+					if (loaded) appendEvent(loaded.manifest.eventsPath, { type: "async.signal", runId: runId!, message: `Background runner received ${sig}`, data: { signal: sig, pid: process.pid } });
+				} catch { /* best-effort */ }
+			});
+		} catch { /* some signals not supported on this platform */ }
+	}
+	// Hook Node.js abort — if process.exit is called with code 1 (uncaught exception, assert failure)
+	// we log it before exiting so it appears in background.log
+	const origExit = process.exit.bind(process);
+	// Intercept all exit(code) calls to log them as async.exit events before exiting.
+	// This surfaces uncaught exceptions / early exits that would otherwise vanish silently.
+	process.exit = ((code?: number | string): never => {
+		const cwd2 = argValue("--cwd");
+		const runId2 = argValue("--run-id");
+		const codeStr = code === undefined ? "<none>" : String(code);
+		if (cwd2 && runId2) {
+			try {
+				const loaded = loadRunManifestById(cwd2, runId2);
+				if (loaded) {
+					appendEvent(loaded.manifest.eventsPath, { type: "async.exit", runId: runId2, message: `Background runner exit(${codeStr}) pid=${process.pid}`, data: { code, pid: process.pid } });
+				}
+			} catch { /* best-effort */ }
+		}
+		return origExit(code);
+	}) as typeof process.exit;
 
 	// Start parent guard FIRST — if parent is already dead, exit immediately
 	const parentPid = Number(process.env.PI_CREW_PARENT_PID);
@@ -100,27 +211,52 @@ async function main(): Promise<void> {
 	const runId = argValue("--run-id");
 	if (!cwd || !runId) throw new Error("Usage: background-runner.ts --cwd <cwd> --run-id <runId>");
 
+	// Log PGID and SID for debugging process group isolation
+	try {
+		const stat = fs.readFileSync("/proc/self/stat", "utf8").split(" ");
+		console.log(`[background-runner] DEBUG: pid=${process.pid} ppid=${process.ppid} pgid=${stat[4]} sid=${stat[5]} cwd=${cwd} runId=${runId}`);
+	} catch {
+		console.log(`[background-runner] DEBUG: pid=${process.pid} ppid=${process.ppid} cwd=${cwd} runId=${runId}`);
+	}
+
 	const loaded = loadRunManifestById(cwd, runId);
 	if (!loaded) throw new Error(`Run '${runId}' not found.`);
 	let { manifest, tasks } = loaded;
 
+	console.log(`[background-runner] DEBUG: manifest loaded, eventsPath=${manifest.eventsPath}`);
+
 	// Setup unhandled rejection guard EARLY — must be before any async operations
 	// that might produce unhandled rejections during cleanup.
 	const rejectionGuardState = { cwd, runId, eventsPath: loaded.manifest.eventsPath };
 	setupUnhandledRejectionGuard(rejectionGuardState);
 
 	appendEvent(manifest.eventsPath, { type: "async.started", runId: manifest.runId, data: { pid: process.pid } });
+	console.log(`[background-runner] DEBUG: async.started written, pid=${process.pid}`);
 	writeAsyncStartMarker(manifest, { pid: process.pid, startedAt: new Date().toISOString() });
+	const stopHeartbeat = startHeartbeat(manifest.stateRoot, manifest.eventsPath, manifest.runId);
 	const stopInterruptGuard = startInterruptGuard(manifest);
+	console.log(`[background-runner] DEBUG: heartbeat+interrupt guard started`);
+	// BUG #17: Keep-alive interval prevents event loop from exiting during
+	// jiti compilation. Pure empty interval (no I/O to avoid io_uring issues).
+	const keepAlive = setInterval(() => {}, 5000);
+
 
 	try {
+		console.log(`[background-runner] DEBUG: about to call discoverAgents`);
 		const agents = allAgents(discoverAgents(cwd));
+		console.log(`[background-runner] DEBUG: discoverAgents done, ${agents.length} agents`);
+		fs.fsyncSync(fs.openSync(manifest.eventsPath, "a")); // FORCE flush so we see this before death
+		console.log(`[background-runner] DEBUG: calling directTeamAndWorkflowFromRun`);
 		const direct = directTeamAndWorkflowFromRun(manifest, tasks, agents);
+		console.log(`[background-runner] DEBUG: direct done, finding team`);
 		const team = direct?.team ?? allTeams(discoverTeams(cwd)).find((candidate) => candidate.name === manifest.team);
 		if (!team) throw new Error(`Team '${manifest.team}' not found.`);
+		console.log(`[background-runner] DEBUG: team=${team.name}, finding workflow`);
 		const baseWorkflow = direct?.workflow ?? allWorkflows(discoverWorkflows(cwd)).find((candidate) => candidate.name === manifest.workflow);
 		if (!baseWorkflow) throw new Error(`Workflow '${manifest.workflow ?? ""}' not found.`);
+		console.log(`[background-runner] DEBUG: workflow=${baseWorkflow.name}`);
 		const workflow = expandParallelResearchWorkflow(baseWorkflow, cwd);
+		console.log(`[background-runner] DEBUG: loading config`);
 		const loadedConfig = loadConfig(cwd);
 		const runConfig = manifest.runConfig && typeof manifest.runConfig === "object" && !Array.isArray(manifest.runConfig) ? manifest.runConfig as typeof loadedConfig.config : loadedConfig.config;
 		const runtime = manifest.runtimeResolution ? { kind: manifest.runtimeResolution.kind, requestedMode: manifest.runtimeResolution.requestedMode, available: manifest.runtimeResolution.available, fallback: manifest.runtimeResolution.fallback, steer: manifest.runtimeResolution.kind === "live-session", resume: manifest.runtimeResolution.kind === "live-session", liveToolActivity: manifest.runtimeResolution.kind === "live-session", transcript: manifest.runtimeResolution.kind !== "scaffold", reason: manifest.runtimeResolution.reason, safety: manifest.runtimeResolution.safety } : await resolveCrewRuntime(runConfig);
@@ -130,12 +266,27 @@ async function main(): Promise<void> {
 		appendEvent(manifest.eventsPath, { type: "runtime.resolved", runId: manifest.runId, message: `Runtime resolved: ${runtime.kind} safety=${runtime.safety}`, data: { runtimeResolution, async: true } });
 		if (runtime.safety === "blocked") throw new Error(runtime.reason ?? "Child worker execution is disabled; refusing to create no-op scaffold subagents.");
 		const executeWorkers = runtime.kind !== "scaffold";
-		// Use ownerSessionId for workspaceId to ensure agents are only visible to the session that spawned them.
+	// Use ownerSessionId for workspaceId to ensure agents are only visible to the session that spawned them.
 		// manifest.cwd would cause cross-session visibility since all sessions share the same project directory.
-		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers, limits: runConfig.limits, runtime, runtimeConfig: runConfig.runtime, skillOverride: manifest.skillOverride, reliability: runConfig.reliability, workspaceId: manifest.ownerSessionId ?? manifest.cwd });
+		// Mark this as background mode so task-runner writes events to background.log for debugging.
+		process.env.PI_CREW_BACKGROUND_MODE = "1";
+		// BUG #17: Keep-alive interval (NOT unref'd) prevents event loop from exiting
+		// during jiti compilation of team-runner.ts. Without this, the event loop
+		// can drain when import() blocks, causing the process to exit prematurely.
+		console.log(`[background-runner] DEBUG: calling executeTeamRun`);
+		let result;
+		try {
+			result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers, limits: runConfig.limits, runtime, runtimeConfig: runConfig.runtime, skillOverride: manifest.skillOverride, reliability: runConfig.reliability, workspaceId: manifest.ownerSessionId ?? manifest.cwd });
+			console.log(`[background-runner] DEBUG: executeTeamRun returned, status=${result.manifest.status}`);
+		} catch (execError) {
+			console.log(`[background-runner] DEBUG: executeTeamRun THREW: ${execError instanceof Error ? execError.message : String(execError)}`);
+			console.log(`[background-runner] DEBUG: stack: ${execError instanceof Error ? execError.stack : "N/A"}`);
+			throw execError;
+		}
 		manifest = result.manifest;
 		tasks = result.tasks;
 		appendEvent(manifest.eventsPath, { type: "async.completed", runId: manifest.runId, data: { status: manifest.status, tasks: tasks.length } });
+		console.log(`[background-runner] DEBUG: async.completed written, status=${manifest.status}`);
 		if (manifest.status === "failed" || manifest.status === "cancelled" || manifest.status === "blocked") process.exitCode = 1;
 	} catch (error) {
 		// Terminate live agents on failure too — agents are done when the run fails
@@ -151,10 +302,17 @@ async function main(): Promise<void> {
 		manifest = updateRunStatus(manifest, "failed", message);
 		appendEvent(manifest.eventsPath, { type: "async.failed", runId: manifest.runId, message });
 		process.exitCode = 1;
+		console.log(`[background-runner] DEBUG: catch block, error=${error instanceof Error ? error.message : String(error)}`);
 	} finally {
+		console.log(`[background-runner] DEBUG: finally block, exitCode=${process.exitCode}`);
 		stopInterruptGuard();
 		stopParentGuard();
+		stopHeartbeat();
+		clearInterval(keepAlive);
 	}
 }
 
-await main();
+await main().catch((err) => {
+	console.error(`[background-runner] DEBUG: main() uncaught: ${err?.message ?? err}`);
+	process.exit(1);
+});

package/src/runtime/child-pi.ts

@@ -115,6 +115,8 @@ export interface ChildPiLifecycleEvent {
 	exitCode?: number | null;
 	/** Error message for error events. */
 	error?: string;
+	/** Stderr captured at timeout moment (for response_timeout events). */
+	stderr?: string;
 	/** Timestamp (ISO). */
 	ts: string;
 }
@@ -136,6 +138,10 @@ export interface ChildPiRunInput {
 	finalDrainMs?: 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;
 }
 
 export interface ChildPiRunResult {
@@ -144,18 +150,57 @@ export interface ChildPiRunResult {
 	stderr: string;
 	error?: 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;
 }
 
 export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): SpawnOptions {
-	// Filter out env vars whose keys match secret patterns to avoid leaking credentials to child processes
-	const filteredEnv = sanitizeEnvSecrets(env);
+	// Filter out env vars whose keys match secret patterns to avoid leaking credentials to child processes.
+	// IMPORTANT: preserve model provider API keys — they are needed by the child Pi to call the LLM.
+	// Also preserve essential non-secret vars (PATH, HOME, USER, etc.) so the child process can function.
+	// Bug #10 fix: allow-list preserves model provider keys.
+	// Bug #12 fix: essential env vars (PATH, HOME, etc.) are always preserved so child can find npm/node.
+	const filteredEnv = sanitizeEnvSecrets(env, {
+		allowList: [
+			// Model provider API keys (these are safe to pass — they're meant for API calls)
+			"MINIMAX_*",
+			"OPENAI_*",
+			"ANTHROPIC_*",
+			"GOOGLE_*",
+			"AZURE_*",
+			"AWS_*",
+			"ZEU_*",
+			"ZERODEV_*",
+			"*_API_KEY",
+			"*_TOKEN",
+			"*_SECRET",
+			// Essential non-secret vars for child process to function
+			"PATH",
+			"HOME",
+			"USER",
+			"SHELL",
+			"TERM",
+			"LANG",
+			"LC_*",
+			"XDG_*",
+			"NVM_*",
+			"NODE_*",
+			"npm_*",
+			"PI_*",
+			"PI_CREW_*",
+			"PI_TEAMS_*",
+		],
+	});
 	return {
 		cwd,
 		env: { ...filteredEnv, PI_CREW_PARENT_PID: String(process.pid) },
-		stdio: ["ignore", "pipe", "pipe"],
+		stdio: ["ignore", "pipe", "pipe"], // stdin=ignore: child doesn't wait for input; task comes via CLI args
 		detached: process.platform !== "win32",
+		setsid: true,
 		windowsHide: true,
-	};
+	} as SpawnOptions;
 }
 
 function appendTranscript(input: ChildPiRunInput, line: string): void {
@@ -326,7 +371,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 		if (mock === "retryable-failure") return { exitCode: 1, stdout: "", stderr: "rate limit: mock failure" };
 		return { exitCode: 1, stdout: "", stderr: `mock failure: ${mock}` };
 	}
-	const built = buildPiWorkerArgs({ task: input.task, agent: input.agent, model: input.model, sessionEnabled: false, maxDepth: input.maxDepth, skillPaths: input.skillPaths });
+	const built = buildPiWorkerArgs({ task: input.task, agent: input.agent, model: input.model, sessionEnabled: true, maxDepth: input.maxDepth, skillPaths: input.skillPaths });
 	const spawnSpec = getPiSpawnCommand(built.args);
 	try {
 		return await new Promise<ChildPiRunResult>((resolve) => {
@@ -355,12 +400,20 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			let abortRequested = input.signal?.aborted === true;
 			let hardKilled = false;
 			const cleanupErrors: string[] = [];
+			let turnCount = 0;
+			let softLimitReached = false;
+			const maxTurns = input.maxTurns;
+			const graceTurns = input.graceTurns;
+			let abortDueToParentSignal = false;
+			input.signal?.addEventListener("abort", () => { abortDueToParentSignal = true; }, { once: true });
 			const restartNoResponseTimer = (): void => {
 				if (responseTimeoutMs <= 0) return;
 				if (noResponseTimer) clearTimeout(noResponseTimer);
 				noResponseTimer = setTimeout(() => {
 					responseTimeoutHit = true;
-					input.onLifecycleEvent?.({ type: "response_timeout", pid: child.pid, error: `No output for ${responseTimeoutMs}ms`, ts: new Date().toISOString() });
+					// Capture stderr at timeout moment for debugging
+					const timeoutStderr = stderr.slice(-1024); // Last 1KB of stderr
+					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");
@@ -384,6 +437,21 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				},
 				onJsonEvent: (event) => {
 					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") {
+							turnCount += 1;
+							if (maxTurns !== undefined && !softLimitReached && turnCount >= maxTurns) {
+								softLimitReached = true;
+								// Inject steer via stdin to tell child to wrap up
+								child.stdin?.write(JSON.stringify({ type: "steer", message: "You have reached your turn limit. Wrap up immediately — provide your final answer now." }) + "\n");
+							} else if (maxTurns !== undefined && softLimitReached && turnCount >= maxTurns + (graceTurns ?? 5)) {
+								// Hard abort — terminate after grace turns
+								try { child.kill(process.platform === "win32" ? undefined : "SIGTERM"); } catch { /* best-effort */ }
+							}
+						}
+					}
 					input.onJsonEvent?.(event);
 					if (!isFinalAssistantEvent(event) || childExited || settled || finalDrainTimer) return;
 					finalDrainTimer = setTimeout(() => {
@@ -440,7 +508,12 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				} catch (error) {
 					cleanupErrors.push(error instanceof Error ? error.message : String(error));
 				}
-				resolve({ ...result, exitStatus: result.exitStatus ?? { exitCode: result.exitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
+				// Catch all errors from settle to prevent unhandled rejection from propagating
+				try {
+					resolve({ ...result, exitStatus: result.exitStatus ?? { exitCode: result.exitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
+				} catch (resolveError) {
+					logInternalError("child-pi.settle-resolve", resolveError, `result=${JSON.stringify({ exitCode: result.exitCode })}`);
+				}
 			};
 
 			const abort = (): void => {
@@ -485,7 +558,11 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				restartNoResponseTimer();
 				const text = chunk.toString("utf-8");
 				backpressureBytes += text.length;
-				lineObserver.observe(text);
+				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);
@@ -497,7 +574,11 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				stderr = appendBoundedTail(stderr, chunk.toString("utf-8"));
 			});
 			child.on("error", (error) => {
-				input.onLifecycleEvent?.({ type: "spawn_error", pid: child.pid, error: error.message, ts: new Date().toISOString() });
+				try {
+					input.onLifecycleEvent?.({ type: "spawn_error", pid: child.pid, error: error.message, ts: new Date().toISOString() });
+				} catch (err) {
+					logInternalError("child-pi.on-lifecycle-event", err, `event=error, pid=${child.pid}`);
+				}
 				settle({ exitCode: null, stdout, stderr, error: error.message });
 			});
 			child.on("exit", (code) => {
@@ -505,7 +586,11 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					activeChildProcesses.delete(child.pid);
 					clearHardKillTimer(child.pid);
 				}
-				input.onLifecycleEvent?.({ type: "exit", pid: child.pid, exitCode: code, ts: new Date().toISOString() });
+				try {
+					input.onLifecycleEvent?.({ type: "exit", pid: child.pid, exitCode: code, ts: new Date().toISOString() });
+				} catch (err) {
+					logInternalError("child-pi.on-lifecycle-event", err, `event=exit, pid=${child.pid}`);
+				}
 				childExited = true;
 				clearNoResponseTimer();
 				clearFinalDrainTimers();
@@ -521,14 +606,22 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					activeChildProcesses.delete(child.pid);
 					clearHardKillTimer(child.pid);
 				}
-				input.onLifecycleEvent?.({ type: "close", pid: child.pid, exitCode, ts: new Date().toISOString() });
-				const timeoutError = responseTimeoutHit && !stderr.trim() ? { error: `Child Pi produced no new output for ${responseTimeoutMs}ms; process was terminated as unresponsive.` } : undefined;
-				const finalExitCode = forcedFinalDrain && !timeoutError ? 0 : exitCode;
-				// A final assistant event is the child Pi contract for "the worker produced its answer".
-				// Some Pi processes can linger during post-final cleanup/stdio shutdown; finalDrain terminates
-				// that lingering process so the parent can continue, but it must not turn a completed
-				// subagent answer into a failed task. Real pre-final response timeouts still report errors.
-				settle({ exitCode: finalExitCode, stdout, stderr, ...(timeoutError ? { error: timeoutError.error } : {}), exitStatus: { exitCode: finalExitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
+				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: ${stderr.slice(-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 = softLimitReached && turnCount >= (maxTurns ?? 0) + (graceTurns ?? 5);
+				const wasParentAborted = abortDueToParentSignal && !wasGraceAborted;
+				settle({ exitCode: finalExitCode, stdout, stderr, ...(timeoutError ? { error: timeoutError.error } : {}), aborted: wasGraceAborted || wasParentAborted, steered: softLimitReached && !wasGraceAborted, exitStatus: { exitCode: finalExitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
 			});
 		});
 	} finally {

package/src/runtime/code-summary.ts

@@ -88,7 +88,7 @@ function findBraceRanges(lines: string[], openPattern: RegExp, minBody: number):
 // ── TypeScript / JavaScript ──
 
 const TS_FN_SIG =
-	/^\s*(export\s+)?(async\s+)?function\s|^\s*(export\s+)?(static\s+|get\s+|set\s+|private\s+|public\s+|protected\s+|readonly\s+)*\*?\s*\w+\s*[\(<]/;
+	/^\s*(export\s+)?(async\s+)?function\s|^\s*(export\s+)?(static\s+|get\s+|set\s+|private\s+|public\s+|protected\s+|readonly\s+)*\*?\s*\w+\s*[(<]/;
 const TS_CLASS_SIG = /^\s*(export\s+)?(default\s+)?(abstract\s+)?class\s/;
 const TS_STRUCT_SIG = /^\s*(export\s+)?(default\s+)?(const|let|var)\s+\w+\s*=\s*(\[[\s]*$|\{[\s]*$)/;
 

package/src/runtime/crash-recovery.ts

@@ -24,7 +24,7 @@ export interface RecoveryPlan {
 }
 
 function isTerminalTask(task: TeamTaskState): boolean {
-	return task.status === "completed" || task.status === "failed" || task.status === "cancelled" || task.status === "skipped";
+	return task.status === "completed" || task.status === "failed" || task.status === "cancelled" || task.status === "skipped" || task.status === "needs_attention";
 }
 
 function shouldRecoverTask(task: TeamTaskState, deadMs: number): boolean {

package/src/runtime/crew-agent-runtime.ts

@@ -2,7 +2,7 @@ import type { TeamTaskStatus } from "../state/contracts.ts";
 import type { CrewActivityState, ModelRoutingState, UsageState } from "../state/types.ts";
 
 export type CrewRuntimeKind = "scaffold" | "child-process" | "live-session";
-export type CrewAgentStatus = "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled" | "stopped";
+export type CrewAgentStatus = "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled" | "stopped" | "needs_attention";
 
 export interface CrewAgentRecentTool {
 	tool: string;
@@ -56,5 +56,6 @@ export function taskStatusToAgentStatus(status: TeamTaskStatus): CrewAgentStatus
 	if (status === "cancelled" || status === "skipped") return "cancelled";
 	if (status === "running") return "running";
 	if (status === "waiting") return "waiting";
+	if (status === "needs_attention") return "needs_attention";
 	return "queued";
 }

package/src/runtime/heartbeat-watcher.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import type { NotificationDescriptor } from "../extension/notification-router.ts";
 import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { appendEvent } from "../state/event-log.ts";
@@ -84,6 +85,9 @@ export class HeartbeatWatcher {
 
 		for (const run of this.opts.manifestCache.list(50)) {
 			if (run.status !== "running") continue;
+			// Bug #5 fix: if stateRoot doesn't exist, the run was pruned — skip it silently.
+			// This prevents stale "heartbeat dead" notifications for runs that no longer exist.
+			if (!fs.existsSync(run.stateRoot)) continue;
 			const loaded = loadRunManifestById(this.opts.cwd, run.runId);
 			if (!loaded) continue;
 			for (const task of loaded.tasks) {

package/src/runtime/live-agent-manager.ts

@@ -200,7 +200,7 @@ export function evictStaleLiveAgentHandles(now = Date.now()): number {
 }
 
 export function listLiveAgents(): LiveAgentHandle[] {
-	return [...liveAgents.values()].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+	return [...liveAgents.values()].sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
 }
 
 export function listActiveLiveAgents(): LiveAgentHandle[] {

package/src/runtime/live-session-runtime.ts

@@ -267,8 +267,9 @@ function liveSystemPrompt(input: LiveSessionSpawnInput): string {
 function filterActiveTools(session: LiveSessionLike, agent: AgentConfig): void {
 	if (typeof session.getActiveToolNames !== "function" || typeof session.setActiveToolsByName !== "function") return;
 	const recursiveTools = new Set(["team", "Team", "Agent", "get_subagent_result", "steer_subagent"]);
+	const disallowed = agent.disallowedTools?.length ? new Set(agent.disallowedTools) : undefined;
 	const allowed = agent.tools?.length ? new Set(agent.tools) : undefined;
-	const active = session.getActiveToolNames().filter((name) => !recursiveTools.has(name) && (!allowed || allowed.has(name)));
+	const active = session.getActiveToolNames().filter((name) => !recursiveTools.has(name) && (!disallowed || !disallowed.has(name)) && (!allowed || allowed.has(name)));
 	session.setActiveToolsByName(active);
 }