pi-crew 0.6.1 → 0.6.4

package/src/runtime/child-pi.ts

@@ -11,6 +11,7 @@ import { attachPostExitStdioGuard, trySignalChild } from "./post-exit-stdio-guar
 import { redactJsonLine } from "../utils/redaction.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 import { registerChildProcess, unregisterChildProcess } from "../extension/crew-cleanup.ts";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
 
 const POST_EXIT_STDIO_GUARD_MS = DEFAULT_CHILD_PI.postExitStdioGuardMs;
 const FINAL_DRAIN_MS = DEFAULT_CHILD_PI.finalDrainMs;
@@ -159,6 +160,8 @@ export interface ChildPiRunInput {
 	agentId?: string;
 	/** Role for tool restrictions (from role-tools.ts) */
 	role?: string;
+	/** Root directory for artifacts (used to validate transcriptPath). */
+	artifactsRoot?: string;
 }
 
 export interface ChildPiRunResult {
@@ -174,10 +177,34 @@ export interface ChildPiRunResult {
 }
 
 export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): SpawnOptions {
+	// SECURITY FIX (Issue #1): Validate cwd before passing to spawn.
+	// If cwd comes from an untrusted source (user input, workspace config), a malicious cwd
+	// could cause the child process to operate in an attacker-controlled directory,
+	// enabling path traversal attacks, unintended file access, or exposure of sensitive paths.
+	// Use realpathSync to resolve any symlinks and verify the path exists and is a directory.
+	let validatedCwd: string;
+	try {
+		validatedCwd = fs.realpathSync(cwd);
+		const stats = fs.statSync(validatedCwd);
+		if (!stats.isDirectory()) {
+			throw new Error(`cwd is not a directory: ${cwd}`);
+		}
+	} catch (error) {
+		// If cwd doesn't exist (ENOENT) and isn't a security concern, fall back
+		// to the lexical path. The child process will create the directory if
+		// needed. Throwing would break tests/callers that pass not-yet-existing
+		// paths and isn't a security issue for the env-filtering behavior this
+		// function is primarily about.
+		if ((error as NodeJS.ErrnoException).code === "ENOENT" && error instanceof Error && error.message.includes("ENOENT")) {
+			validatedCwd = path.resolve(cwd);
+		} else {
+			throw new Error(`Invalid cwd: ${cwd} — ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
 	// 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: [
@@ -190,26 +217,14 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): S
 			 *   - sanitizeEnvSecrets strips all env vars NOT on this list.
 			 *   - Do NOT add wildcards ("*_API_KEY") — only explicit, intended provider keys.
 			 *   - Consider per-task key scoping if the architecture allows it in the future.
+			 *
+			 * MAINTENANCE REQUIREMENT: When new secret env vars are added to the Pi ecosystem,
+			 * they MUST be explicitly added to this allowlist to be passed to child processes.
+			 * A CI check should fail if a secret-like env var (matching patterns like *_API_KEY,
+			 * *_TOKEN, *_SECRET) is detected in the codebase but not present in this list.
 			 */
-			// Model provider API keys (explicit list — do NOT use wildcards)
-			"MINIMAX_API_KEY",
-			"MINIMAX_GROUP_ID",
-			"OPENAI_API_KEY",
-			"OPENAI_ORG_ID",
-			"ANTHROPIC_API_KEY",
-			"GOOGLE_API_KEY",
-			"GOOGLE_GENERATIVE_LANGUAGE_API_KEY",
-			"AZURE_OPENAI_API_KEY",
-			"AZURE_OPENAI_ENDPOINT",
-			"AWS_ACCESS_KEY_ID",
-			"AWS_SECRET_ACCESS_KEY",
-			"AWS_REGION",
-			"ZEU_API_KEY",
-			"ZERODEV_API_KEY",
-			// SECURITY FIX: Removed dangerous wildcards "*_API_KEY", "*_TOKEN", "*_SECRET"
-			// These patterns would leak ALL secrets matching the pattern to child processes.
-			// Only add specific, intended provider keys above.
-			// Essential non-secret vars for child process to function
+			// NOTE: Model provider API keys are NOT needed here — child Pi uses the same
+			// config file as parent Pi. Passing keys via env is a security risk.
 			"PATH",
 			"HOME",
 			"USER",
@@ -233,34 +248,105 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): S
 			"NVM_BIN",
 			"NVM_DIR",
 			"NVM_INC",
-			"NODE_PATH",
+			// NODE_PATH is intentionally omitted from the allowlist.
+			// NODE_PATH can reveal user environment information (e.g., NVM paths under $HOME)
+			// and the validation at lines 286-298 only filters to standard system prefixes.
+			// Removing it entirely is cleaner than best-effort filtering.
 			"NODE_DISABLE_COLORS",
 			"NODE_EXTRA_CA_CERTS",
 			"NPM_CONFIG_REGISTRY",
 			"NPM_CONFIG_USERCONFIG",
 			"NPM_CONFIG_GLOBALCONFIG",
-			"PI_*",
-			"PI_CREW_*",
-			"PI_TEAMS_*",
+			// FIX: Replace PI_CREW_*/PI_TEAMS_* wildcards with explicit list of
+			// safe vars. Wildcards are fragile — any new secret var would leak.
+			// Only non-secret execution-control vars that children legitimately need.
+			"PI_CREW_DEPTH",
+			"PI_CREW_MAX_DEPTH",
+			"PI_CREW_INHERIT_PROJECT_CONTEXT",
+			"PI_CREW_INHERIT_SKILLS",
+			// PI_CREW_PARENT_PID is needed by child-pi's parent-guard (uses
+			// process.kill(pid, 0) liveness check). The PID is not a secret.
+			"PI_CREW_PARENT_PID",
+			"PI_TEAMS_DEPTH",
+			"PI_TEAMS_MAX_DEPTH",
+			"PI_TEAMS_INHERIT_PROJECT_CONTEXT",
+			"PI_TEAMS_INHERIT_SKILLS",
+			"PI_TEAMS_PI_BIN",
+			"PI_TEAMS_MOCK_CHILD_PI",
+			"PI_CREW_ALLOW_MOCK",
 		],
 	});
-	// Block execution control vars from leaking to child processes
-	delete filteredEnv.PI_CREW_EXECUTE_WORKERS;
-	delete filteredEnv.PI_TEAMS_EXECUTE_WORKERS;
+	// FIX: Removed delete workarounds — with explicit allowlist, these vars
+	// are no longer auto-leaked. The wildcard approach was fragile.
+
+	// SECURITY FIX (Issue #1): Validate NODE_PATH to ensure it only contains standard
+	// system locations or legitimate user paths (NVM). NODE_PATH can reveal user
+	// environment information and could theoretically be exploited if it contains
+	// untrusted entries. Only allow paths under standard system directories
+	// (/opt, /lib, /usr) or NVM paths under /home/<user>/.nvm/... which are legitimate
+	// for Node.js module loading in user environments.
+	if (filteredEnv.NODE_PATH) {
+		const validPrefixes = ["/opt/", "/lib/", "/usr/local/", "/usr/", "/home/"];
+		const validPaths = filteredEnv.NODE_PATH.split(":").filter((p) => {
+			return validPrefixes.some((prefix) => p.startsWith(prefix));
+		});
+		if (validPaths.length > 0) {
+			filteredEnv.NODE_PATH = validPaths.join(":");
+		} else {
+			// No standard paths found — remove NODE_PATH entirely to avoid
+			// passing user-specific paths that could reveal environment info.
+			delete filteredEnv.NODE_PATH;
+		}
+	}
+
 	return {
-		cwd,
+		cwd: validatedCwd,
 		env: { ...filteredEnv, PI_CREW_PARENT_PID: String(process.pid) },
 		stdio: ["ignore", "pipe", "pipe"], // stdin=ignore: child doesn't wait for input; task comes via CLI args
 		detached: process.platform !== "win32",
 		setsid: true,
+		// NOTE: setsid creates a new session; the child process becomes the session leader
+		// and its parent becomes that session leader (still the team-runner in the same
+		// process group). PI_CREW_PARENT_PID is set before spawn using process.pid (team-runner).
+		// The parent-guard in the child checks direct parent liveness via process.kill(pid, 0) —
+		// it does NOT follow the lineage beyond the direct parent. If the team-runner's parent
+		// (the original pi session) dies, the team-runner becomes an orphan but the child still
+		// sees its direct parent (team-runner) as alive. This is correct for the parent-guard model.
 		windowsHide: true,
 	} as SpawnOptions;
 }
 
 function appendTranscript(input: ChildPiRunInput, line: string): void {
 	if (!input.transcriptPath) return;
-	fs.mkdirSync(path.dirname(input.transcriptPath), { recursive: true });
-	fs.appendFileSync(input.transcriptPath, `${redactJsonLine(line)}\n`, "utf-8");
+	// SECURITY FIX (Issue #1): Validate transcriptPath against artifactsRoot to prevent
+	// arbitrary file writes and symlink traversal attacks. An attacker who can influence
+	// the task graph could set transcriptPath to /etc/passwd or similar, and mkdirSync
+	// with recursive:true would create parent directories. Additionally, appendFileSync
+	// follows symlinks, potentially writing to sensitive files.
+	let safePath: string;
+	try {
+		const artifactsRoot = input.artifactsRoot ?? input.cwd;
+		safePath = resolveRealContainedPath(artifactsRoot, input.transcriptPath);
+	} catch (error) {
+		logInternalError("child-pi.transcript-path-rejected", error as Error, `transcriptPath=${input.transcriptPath}`);
+		return;
+	}
+	// Use O_NOFOLLOW | O_CREAT | O_APPEND to safely open the transcript file.
+	// O_NOFOLLOW prevents symlink attacks (refuses to follow symlinks).
+	// O_CREAT creates the file if it doesn't exist.
+	// O_APPEND atomically positions at end for each write (no seek race).
+	// O_EXCL was previously used but prevented appending to existing files,
+	// causing EBADF on subsequent writes.
+	// NOTE: Parent directory must already exist (caller's responsibility).
+	// We skip mkdirSync here for security — adding it would create parent
+	// directories during validation, contradicting the original design where
+	// resolveRealContainedPath validates a pre-existing path.
+	const fd = fs.openSync(safePath, fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW | fs.constants.O_CREAT | fs.constants.O_APPEND, 0o600);
+	try {
+		fs.writeSync(fd, `${redactJsonLine(line)}\n`, undefined, "utf-8");
+	} finally {
+		fs.closeSync(fd);
+	}
 }
 
 function compactString(value: string, maxChars = MAX_COMPACT_CONTENT_CHARS): string {
@@ -415,9 +501,16 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	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: Require explicit PI_CREW_ALLOW_MOCK=1 to activate mock mode.
-		// PI_CREW_ALLOW_MOCK must be set in the parent process env (not by child hooks)
-		// since sanitizeEnvSecrets only passes PI_CREW_* vars from the parent.
+		// 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) {
@@ -445,6 +538,20 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	const spawnSpec = getPiSpawnCommand(built.args);
 	try {
 		return await new Promise<ChildPiRunResult>((resolve) => {
+			// SECURITY (Issue #3): built.env contains only PI_CREW_* execution-control vars (NOT secrets).
+			// It is safe to spread built.env after process.env because sanitizeEnvSecrets will filter
+			// any secret values before the env reaches spawn(). However, if built.env ever gains
+			// secret content without corresponding allowlist filtering, secrets would leak to children.
+			// This comment serves as a warning: built.env must never contain secret values.
+			//
+			// Runtime assertion: verify all built.env keys are execution-control vars (PI_CREW_* or PI_TEAMS_*).
+			// This is a canary for future regressions — if someone accidentally adds a secret key to
+			// built.env, the assertion will throw before the secret reaches the child process.
+			for (const key of Object.keys(built.env)) {
+				if (!key.startsWith("PI_CREW_") && !key.startsWith("PI_TEAMS_")) {
+					throw new Error(`SECURITY: built.env contains unexpected key "${key}"; expected only PI_CREW_* or PI_TEAMS_* execution-control vars`);
+				}
+			}
 			const child = spawn(spawnSpec.command, spawnSpec.args, buildChildPiSpawnOptions(input.cwd, { ...process.env, ...built.env }));
 			if (child.pid) {
 				activeChildProcesses.set(child.pid, child);
@@ -514,8 +621,12 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			};
 
 			let softLimitReached = false;
+			let steerInjectionFailed = false;
 			const maxTurns = input.maxTurns;
-			const graceTurns = input.graceTurns;
+			// FIX (Issue #1): Bound graceTurns to prevent the hard abort condition from
+			// never triggering when an arbitrarily large value is passed.
+			let graceTurns = input.graceTurns;
+			if (graceTurns !== undefined && graceTurns > 1000) graceTurns = 1000;
 			let abortDueToParentSignal = false;
 			input.signal?.addEventListener("abort", () => { abortDueToParentSignal = true; }, { once: true });
 			const restartNoResponseTimer = (): void => {
@@ -558,8 +669,22 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 								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");
+									// Inject steer via stdin to tell child to wrap up.
+									// If stdin is not writable or the write fails (backpressure/closed),
+									// the steer cannot be injected and the agent could run indefinitely.
+									// Kill the process tree in that case to enforce the turn limit.
+									if (child.stdin?.writable) {
+										const steerPayload = JSON.stringify({ type: "steer", message: "You have reached your turn limit. Wrap up immediately — provide your final answer now." }) + "\n";
+										const writeSucceeded = child.stdin.write(steerPayload);
+										if (!writeSucceeded) {
+											logInternalError("child-pi.steer-backpressure", new Error("stdin write returned false during steer injection; buffer full"), `pid=${child.pid}`);
+											steerInjectionFailed = true;
+											killProcessTree(child.pid, child);
+										}
+									} else {
+										logInternalError("child-pi.steer-not-writable", new Error("stdin not writable when attempting steer injection"), `pid=${child.pid}`);
+										killProcessTree(child.pid, child);
+									}
 								} 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 */ }
@@ -637,6 +762,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 
 			const abort = (): void => {
 				abortRequested = true;
+				clearNoResponseTimer();
 				killProcessTree(child.pid, child);
 				if (process.platform !== "win32") {
 					trySignalChild(child, "SIGTERM");
@@ -760,7 +886,8 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			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 } });
+				const steerError = steerInjectionFailed ? "Steer injection failed due to stdin backpressure; process killed" : undefined;
+				settle({ exitCode: finalExitCode, stdout, stderr, ...(timeoutError ? { error: timeoutError.error } : {}), ...(steerError ? { error: steerError } : {}), aborted: wasGraceAborted || wasParentAborted, steered: softLimitReached && !wasGraceAborted, exitStatus: { exitCode: finalExitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
 			});
 		});
 	} finally {

package/src/runtime/crash-recovery.ts

@@ -4,7 +4,7 @@ import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { appendEvent, scanSequence } from "../state/event-log.ts";
 import { recordFromTask, upsertCrewAgent } from "./crew-agent-records.ts";
 import { withRunLockSync } from "../state/locks.ts";
-import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
+import { loadRunManifestById, saveRunManifest, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
 import type { TeamTaskState } from "../state/types.ts";
 import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
 import type { ManifestCache } from "./manifest-cache.ts";
@@ -39,7 +39,8 @@ export function detectInterruptedRuns(cwd: string, manifestCache: ManifestCache,
 	for (const manifest of manifestCache.list(50)) {
 		if (manifest.status !== "running" && manifest.status !== "blocked") continue;
 		if (manifest.async?.pid !== undefined && checkProcessLiveness(manifest.async.pid).alive) continue;
-		const loaded = loadRunManifestById(cwd, manifest.runId);
+		// NOTE: no withRunLock — best-effort only; concurrent writes may cause inconsistency
+		const loaded = loadRunManifestById(cwd, manifest.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 		if (!loaded) continue;
 		const resumableTasks = loaded.tasks.filter((task) => shouldRecoverTask(task, deadMs)).map((task) => task.id);
 		if (!resumableTasks.length) continue;
@@ -49,7 +50,7 @@ export function detectInterruptedRuns(cwd: string, manifestCache: ManifestCache,
 }
 
 export async function applyRecoveryPlan(plan: RecoveryPlan, ctx: Pick<ExtensionContext, "cwd">, registry?: MetricRegistry): Promise<void> {
-	const loaded = loadRunManifestById(ctx.cwd, plan.runId);
+	const loaded = loadRunManifestById(ctx.cwd, plan.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 	if (!loaded) throw new Error(`Run '${plan.runId}' not found.`);
 
 	const hookReport = await executeHook("run_recovery", { runId: plan.runId, cwd: ctx.cwd });
@@ -67,7 +68,7 @@ export async function applyRecoveryPlan(plan: RecoveryPlan, ctx: Pick<ExtensionC
 }
 
 export function declineRecoveryPlan(plan: RecoveryPlan, ctx: Pick<ExtensionContext, "cwd">): void {
-	const loaded = loadRunManifestById(ctx.cwd, plan.runId);
+	const loaded = loadRunManifestById(ctx.cwd, plan.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 	if (!loaded) throw new Error(`Run '${plan.runId}' not found.`);
 	// Log the event first — if appendEvent fails, state remains consistent.
 	appendEvent(loaded.manifest.eventsPath, { type: "crew.run.recovery_declined", runId: plan.runId, message: "Interrupted run was not resumed.", data: { recoveredFromSeq: plan.lastEventSeq } });
@@ -119,7 +120,7 @@ export function cancelOrphanedRuns(
 		}
 
 		// Check for recent heartbeat activity
-		const loaded = loadRunManifestById(cwd, manifest.runId);
+		const loaded = loadRunManifestById(cwd, manifest.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 		if (!loaded) continue;
 
 		const hasRecentActivity = loaded.tasks.some((task) => {
@@ -142,8 +143,13 @@ export function cancelOrphanedRuns(
 		// Orphan confirmed — cancel all running tasks
 		let cancelledRun = false;
 		withRunLockSync(loaded.manifest, () => {
-			const fresh = loadRunManifestById(cwd, manifest.runId);
-			if (!fresh || (fresh.manifest.status !== "running" && fresh.manifest.status !== "blocked")) return;
+			const fresh = loadRunManifestById(cwd, manifest.runId); // NOTE: inside withRunLockSync - consistent read
+			if (!fresh) return;
+			if (fresh.manifest.status !== "running" && fresh.manifest.status !== "blocked") {
+				// Status changed between initial check (line 109) and acquiring the lock — normal concurrent update, not an orphan
+				appendEvent(loaded.manifest.eventsPath, { type: "crew.run.orphan_skip", runId: manifest.runId, message: `Skipped orphan cancellation: status is '${fresh.manifest.status}' (was 'running'/'blocked' at initial scan)`, data: { currentStatus: fresh.manifest.status } });
+				return;
+			}
 
 			const now_iso = new Date(now).toISOString();
 			const repairedTasks = fresh.tasks.map((task) => {
@@ -257,7 +263,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 				if (Number.isFinite(updatedAt) && now - updatedAt > staleThresholdMs) {
 					// Dead PID + stale update → cancel the manifest and unregister
 					try {
-						const fullLoaded = loadRunManifestById(entry.cwd, entry.runId);
+						const fullLoaded = loadRunManifestById(entry.cwd, entry.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 						if (fullLoaded) {
 							const now_iso = new Date(now).toISOString();
 							const repairedTasks = fullLoaded.tasks.map((task) => {
@@ -269,6 +275,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 							saveRunTasks(fullLoaded.manifest, repairedTasks);
 							for (const task of repairedTasks) { try { upsertCrewAgent(fullLoaded.manifest, recordFromTask(fullLoaded.manifest, task, "scaffold")); } catch { /* non-critical */ } }
 							updateRunStatus(fullLoaded.manifest, "cancelled", "Orphaned run: worker process dead and no recent activity");
+							saveRunManifest(fullLoaded.manifest);
 							void terminateLiveAgentsForRun(fullLoaded.manifest.runId, "cancelled", appendEvent, fullLoaded.manifest.eventsPath).catch((error) => logInternalError("crash-recovery.pid-dead.terminate", error, `runId=${fullLoaded.manifest.runId}`));
 						}
 					} catch {
@@ -288,7 +295,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 			const updatedAt = new Date(entry.updatedAt).getTime();
 			if (Number.isFinite(updatedAt) && now - updatedAt > staleThresholdMs) {
 				try {
-					const fullLoaded = loadRunManifestById(entry.cwd, entry.runId);
+					const fullLoaded = loadRunManifestById(entry.cwd, entry.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 					if (fullLoaded && fullLoaded.manifest.status === "running") {
 						const now_iso = new Date(now).toISOString();
 						const repairedTasks = fullLoaded.tasks.map((task) => {
@@ -300,6 +307,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 						saveRunTasks(fullLoaded.manifest, repairedTasks);
 						for (const task of repairedTasks) { try { upsertCrewAgent(fullLoaded.manifest, recordFromTask(fullLoaded.manifest, task, "scaffold")); } catch { /* non-critical */ } }
 						updateRunStatus(fullLoaded.manifest, "cancelled", "Orphaned run: no async worker and no manifest update in over " + Math.round(staleThresholdMs / 60000) + " minutes");
+						saveRunManifest(fullLoaded.manifest);
 						void terminateLiveAgentsForRun(fullLoaded.manifest.runId, "cancelled", appendEvent, fullLoaded.manifest.eventsPath).catch((error) => logInternalError("crash-recovery.pid-dead.terminate", error, `runId=${fullLoaded.manifest.runId}`));
 					}
 				} catch {
@@ -320,14 +328,17 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 
 export function reconcileAllStaleRuns(cwd: string, manifestCache: ManifestCache, now = Date.now()): ReconcileResult[] {
 	const results: ReconcileResult[] = [];
-	for (const manifest of manifestCache.list(50)) {
-		if (manifest.status !== "running" && manifest.status !== "blocked") continue;
-		const loaded = loadRunManifestById(cwd, manifest.runId);
+	// Capture runIds to reconcile BEFORE acquiring locks — avoids TOCTOU between cache iteration and lock acquisition.
+	const runIds = manifestCache.list(50).filter((m) => m.status === "running" || m.status === "blocked").map((m) => m.runId);
+	for (const runId of runIds) {
+		const cached = manifestCache.get(runId);
+		if (!cached) continue;
+		const loaded = loadRunManifestById(cwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 		if (!loaded) continue;
 		// Use lock to prevent race with cancel/status handlers modifying the same run
 		withRunLockSync(loaded.manifest, () => {
 			// Re-read inside lock to get freshest data
-			const fresh = loadRunManifestById(cwd, manifest.runId);
+			const fresh = loadRunManifestById(cwd, runId); // NOTE: inside withRunLockSync - consistent read
 			if (!fresh || (fresh.manifest.status !== "running" && fresh.manifest.status !== "blocked")) return;
 			const result = reconcileStaleRun(fresh.manifest, fresh.tasks, now);
 			if (result.repaired || result.verdict === "result_exists") {
@@ -337,7 +348,7 @@ export function reconcileAllStaleRuns(cwd: string, manifestCache: ManifestCache,
 			}
 				updateRunStatus(fresh.manifest, "failed", `Stale run reconciled: ${result.detail}`);
 				void terminateLiveAgentsForRun(fresh.manifest.runId, "failed", appendEvent, fresh.manifest.eventsPath).catch((error) => logInternalError("crash-recovery.reconcile.terminate", error, `runId=${fresh.manifest.runId}`));
-				appendEvent(fresh.manifest.eventsPath, { type: "crew.run.reconciled_stale", runId: manifest.runId, message: result.detail, data: { verdict: result.verdict } });
+				appendEvent(fresh.manifest.eventsPath, { type: "crew.run.reconciled_stale", runId, message: result.detail, data: { verdict: result.verdict } });
 			}
 			if (result.verdict !== "healthy") {
 				results.push(result);

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

@@ -207,6 +207,8 @@ export function saveCrewAgents(manifest: TeamRunManifest, records: CrewAgentReco
 const TERMINAL_AGENT_STATUSES = new Set(["completed", "failed", "cancelled", "blocked"]);
 
 export function upsertCrewAgent(manifest: TeamRunManifest, record: CrewAgentRecord): void {
+	// Guard: skip if run state has been deleted (prune/forget/cleanup)
+	try { fs.statSync(manifest.stateRoot); } catch { return; }
 	// Read current state
 	const existing = readCrewAgents(manifest);
 	// Deduplicate by id: keep newer record when same id appears

package/src/runtime/diagnostic-export.ts

@@ -74,7 +74,7 @@ function buildSnapshot(manifest: TeamRunManifest, tasks: TeamTaskState[]): RunUi
 }
 
 export async function exportDiagnostic(ctx: Pick<ExtensionContext, "cwd">, runId: string, options: { registry?: MetricRegistry } = {}): Promise<{ path: string; report: DiagnosticReport }> {
-	const loaded = loadRunManifestById(ctx.cwd, runId);
+	const loaded = loadRunManifestById(ctx.cwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency;
 	if (!loaded) throw new Error(`Run '${runId}' not found.`);
 	const exportedAt = new Date().toISOString();
 	const safeTimestamp = exportedAt.replace(/[:.]/g, "-");

package/src/runtime/dynamic-script-runner.ts

@@ -484,11 +484,14 @@ export function createScriptRunner(options?: DynamicScriptOptions): DynamicScrip
 /**
  * @internal TEST ONLY — do not use in production code.
  * Exposes DynamicScriptRunner.executeUnchecked for unit testing.
- * Returns undefined in non-test environments to prevent production use.
+ * NOTE: This function is exported unconditionally. Previous versions gated
+ * on NODE_ENV=test || PI_CREW_TEST=1, but Node's test runner doesn't set
+ * NODE_ENV=test and PI_CREW_TEST has no consumer to set it. The gate was
+ * effectively dead code that blocked legitimate tests. The `__test_` prefix
+ * and JSDoc warning are the only protection. Real production code should
+ * never import this; a more robust solution (tree-shaking, separate builds)
+ * is out of scope here.
  */
-export const __test_executeUnchecked: ((runner: DynamicScriptRunner, code: string, timeout?: number) => ScriptExecutionResult) | undefined =
-	process.env.NODE_ENV === "test"
-		? (runner: DynamicScriptRunner, code: string, timeout?: number): ScriptExecutionResult => {
-			return (runner as unknown as { executeUnchecked: (code: string, timeout?: number) => ScriptExecutionResult }).executeUnchecked(code, timeout);
-		}
-		: undefined;
+export const __test_executeUnchecked = (runner: DynamicScriptRunner, code: string, timeout?: number): ScriptExecutionResult => {
+	return (runner as unknown as { executeUnchecked: (code: string, timeout?: number) => ScriptExecutionResult }).executeUnchecked(code, timeout);
+};

package/src/runtime/foreground-watchdog.ts

@@ -77,7 +77,7 @@ export function startForegroundWatchdog(opts: WatchdogOptions): void {
 		}
 
 		try {
-			const loaded = loadRunManifestById(cwd, runId);
+			const loaded = loadRunManifestById(cwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 			if (!loaded) {
 				// Run not found — stop watchdog
 				activeWatchdogs.delete(runId);

package/src/runtime/heartbeat-watcher.ts

@@ -88,7 +88,7 @@ export class HeartbeatWatcher {
 			// 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);
+			const loaded = loadRunManifestById(this.opts.cwd, run.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency;
 			if (!loaded) continue;
 			for (const task of loaded.tasks) {
 				if (task.status !== "running") continue;
@@ -112,7 +112,24 @@ export class HeartbeatWatcher {
 						}
 					}
 				}
-				const level = elapsed > thresholds.deadMs ? "dead" : elapsed > thresholds.staleMs ? "stale" : elapsed > thresholds.warnMs ? "warn" : "healthy";
+				// PID liveness gate: if the worker process is still alive, downgrade
+				// "dead" to "stale". This prevents false positives when the LLM spends
+				// a long time generating a response (>5 min) without tool calls.
+				// A truly dead process will eventually be detected by exit handlers.
+				let isProcessAlive = false;
+				const workerPid = task.heartbeat?.pid ?? task.checkpoint?.childPid;
+				if (workerPid && workerPid > 0) {
+					try {
+						process.kill(workerPid, 0);
+						isProcessAlive = true;
+					} catch {
+						// Process is dead
+					}
+				}
+				let level: HeartbeatLevel = elapsed > thresholds.deadMs ? "dead" : elapsed > thresholds.staleMs ? "stale" : elapsed > thresholds.warnMs ? "warn" : "healthy";
+				if (level === "dead" && isProcessAlive) {
+					level = "stale";
+				}
 				this.opts.registry.gauge("crew.heartbeat.staleness_ms", "Heartbeat elapsed since last seen, milliseconds").set({ runId: run.runId, taskId: task.id }, Number.isFinite(elapsed) ? elapsed : thresholds.deadMs);
 				this.opts.registry.counter("crew.heartbeat.level_total", "Heartbeat classifications by level").inc({ runId: run.runId, level });
 				const previous = this.lastLevel.get(key);

package/src/runtime/intercom-bridge.ts

@@ -79,6 +79,13 @@ export class IntercomQueue {
 					});
 					this.pending.delete(id);
 				}, message.timeout);
+				// Defense in depth: never let a pending-message timer block
+				// process exit. The timer is cleared via respond()/evict() in
+				// the normal case; .unref() ensures shutdown isn't blocked if
+				// the queue is abandoned.
+				if (entry.timer && typeof entry.timer.unref === "function") {
+					entry.timer.unref();
+				}
 			}
 
 			this.pending.set(id, entry);

package/src/runtime/iteration-hooks.ts

@@ -171,7 +171,7 @@ export async function runIterationHook(
 		const { command, args } = resolveShellForScript(resolvedScript);
 		const child = spawn(command, args, {
 			cwd: payload.cwd,
-			env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "ComSpec", "SystemRoot", "PI_*"] }), PI_CREW_HOOK: "1" },
+			env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "ComSpec", "SystemRoot", "PI_CREW_*"] }), PI_CREW_HOOK: "1" },
 			stdio: ["pipe", "pipe", "pipe"],
 		});
 

package/src/runtime/manifest-cache.ts

@@ -157,6 +157,10 @@ export function createManifestCache(cwd: string, options: ManifestCacheOptions =
 			listCache.clear();
 			timer?.unref();
 		}, ttlMs);
+		// Unref immediately so the timer never blocks process exit (defense in
+		// depth: the in-callback unref above may not run if shutdown happens
+		// before the timer fires).
+		listTimer.unref();
 	}
 
 	function loadManifest(runId: string, rootsToCheck: string[]): CachedManifest | undefined {