pi-crew 0.2.2 → 0.2.4

package/src/runtime/post-checks.ts

@@ -1,122 +1,125 @@
-/**
- * Post-task backpressure checks — runs a configurable shell script after
- * task completion to verify workspace health before proceeding.
- *
- * Distilled from pi-autoresearch's post-check / backpressure pattern.
- */
-import { execFileSync } from "node:child_process";
-
-/** Default timeout for post-check scripts (5 minutes). */
-const DEFAULT_TIMEOUT_MS = 300_000;
-
-/** Environment variable name for the post-check script path. */
-const POST_CHECK_SCRIPT_ENV = "PI_CREW_POST_CHECK_SCRIPT";
-
-/**
- * Configuration for a post-task check.
- */
-export interface PostCheckConfig {
-	/** Path to the shell script to execute. */
-	scriptPath: string;
-	/** Timeout in milliseconds. Defaults to 300000 (5 minutes). */
-	timeoutMs: number;
-}
-
-/**
- * Result of running a post-task check.
- */
-export interface PostCheckResult {
-	/** Whether the check passed (exit code 0). */
-	passed: boolean;
-	/** Combined stdout + stderr from the script. */
-	output: string;
-	/** Wall-clock duration of the check in milliseconds. */
-	durationMs: number;
-	/** Whether the check timed out. */
-	timedOut: boolean;
-}
-
-/**
- * Resolve the effective post-check script path.
- * Prefers config.scriptPath; falls back to the PI_CREW_POST_CHECK_SCRIPT env var.
- */
-function resolveScriptPath(config: PostCheckConfig): string | undefined {
-	if (config.scriptPath && config.scriptPath.length > 0) {
-		return config.scriptPath;
-	}
-	return process.env[POST_CHECK_SCRIPT_ENV];
-}
-
-/**
- * Run a post-task backpressure check script.
- *
- * Executes the configured bash script and returns a structured result.
- * If no script path is available (neither config nor env var), the check
- * passes by default with a note.
- *
- * **Security note:** The script path is user-configurable (config or env var)
- * and executed with minimal environment (PATH, HOME, USER, LANG). Only use with trusted script
- * paths. No path containment validation is performed.
- *
- * @param config - Post-check configuration (script path and timeout)
- * @param cwd - Working directory for script execution
- * @returns PostCheckResult with pass/fail status, output, and timing
- */
-export async function runPostCheck(config: PostCheckConfig, cwd: string): Promise<PostCheckResult> {
-	const scriptPath = resolveScriptPath(config);
-	const timeoutMs = config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
-
-	if (!scriptPath) {
-		return {
-			passed: true,
-			output: "No post-check script configured; skipping.",
-			durationMs: 0,
-			timedOut: false,
-		};
-	}
-
-	const startTime = Date.now();
-
-	return new Promise<PostCheckResult>((resolve) => {
-		try {
-			const output = execFileSync("bash", [scriptPath], {
-				cwd,
-				timeout: timeoutMs,
-				encoding: "utf-8",
-				maxBuffer: 10 * 1024 * 1024, // 10 MB
-				env: { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp", USER: process.env.USER, LANG: process.env.LANG, PI_CREW_POST_CHECK: "1" },
-			});
-
-			const durationMs = Date.now() - startTime;
-			resolve({
-				passed: true,
-				output: output.trim(),
-				durationMs,
-				timedOut: false,
-			});
-		} catch (error: unknown) {
-			const durationMs = Date.now() - startTime;
-
-			// Determine if this was a timeout
-			// execFileSync throws with code 'ETIMEDOUT' or sets killed:true on timeout
-			const isTimedOut =
-				Boolean((error as NodeJS.ErrnoException & { killed?: boolean }).killed) ||
-				(error as NodeJS.ErrnoException).code === "ETIMEDOUT";
-
-			let output = "";
-			if (error instanceof Error) {
-				const execError = error as NodeJS.ErrnoException & { stdout?: string; stderr?: string };
-				output = [execError.stdout ?? "", execError.stderr ?? "", execError.message ?? ""].join("\n").trim();
-			} else {
-				output = String(error);
-			}
-
-			resolve({
-				passed: false,
-				output,
-				durationMs,
-				timedOut: isTimedOut,
-			});
-		}
-	});
-}
+/**
+ * Post-task backpressure checks — runs a configurable shell script after
+ * task completion to verify workspace health before proceeding.
+ *
+ * Distilled from pi-autoresearch's post-check / backpressure pattern.
+ */
+import { execFileSync } from "node:child_process";
+import { resolveShellForScript } from "../utils/resolve-shell.ts";
+import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
+
+/** Default timeout for post-check scripts (5 minutes). */
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+/** Environment variable name for the post-check script path. */
+const POST_CHECK_SCRIPT_ENV = "PI_CREW_POST_CHECK_SCRIPT";
+
+/**
+ * Configuration for a post-task check.
+ */
+export interface PostCheckConfig {
+	/** Path to the shell script to execute. */
+	scriptPath: string;
+	/** Timeout in milliseconds. Defaults to 300000 (5 minutes). */
+	timeoutMs: number;
+}
+
+/**
+ * Result of running a post-task check.
+ */
+export interface PostCheckResult {
+	/** Whether the check passed (exit code 0). */
+	passed: boolean;
+	/** Combined stdout + stderr from the script. */
+	output: string;
+	/** Wall-clock duration of the check in milliseconds. */
+	durationMs: number;
+	/** Whether the check timed out. */
+	timedOut: boolean;
+}
+
+/**
+ * Resolve the effective post-check script path.
+ * Prefers config.scriptPath; falls back to the PI_CREW_POST_CHECK_SCRIPT env var.
+ */
+function resolveScriptPath(config: PostCheckConfig): string | undefined {
+	if (config.scriptPath && config.scriptPath.length > 0) {
+		return config.scriptPath;
+	}
+	return process.env[POST_CHECK_SCRIPT_ENV];
+}
+
+/**
+ * Run a post-task backpressure check script.
+ *
+ * Executes the configured bash script and returns a structured result.
+ * If no script path is available (neither config nor env var), the check
+ * passes by default with a note.
+ *
+ * **Security note:** The script path is user-configurable (config or env var)
+ * and executed with minimal environment (PATH, HOME, USER, LANG). Only use with trusted script
+ * paths. No path containment validation is performed.
+ *
+ * @param config - Post-check configuration (script path and timeout)
+ * @param cwd - Working directory for script execution
+ * @returns PostCheckResult with pass/fail status, output, and timing
+ */
+export async function runPostCheck(config: PostCheckConfig, cwd: string): Promise<PostCheckResult> {
+	const scriptPath = resolveScriptPath(config);
+	const timeoutMs = config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
+
+	if (!scriptPath) {
+		return {
+			passed: true,
+			output: "No post-check script configured; skipping.",
+			durationMs: 0,
+			timedOut: false,
+		};
+	}
+
+	const startTime = Date.now();
+
+	return new Promise<PostCheckResult>((resolve) => {
+		try {
+			const { command, args } = resolveShellForScript(scriptPath);
+		const output = execFileSync(command, args, {
+				cwd,
+				timeout: timeoutMs,
+				encoding: "utf-8",
+				maxBuffer: 10 * 1024 * 1024, // 10 MB
+				env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "ComSpec", "SystemRoot", "PI_*"] }), PI_CREW_POST_CHECK: "1" },
+			});
+
+			const durationMs = Date.now() - startTime;
+			resolve({
+				passed: true,
+				output: output.trim(),
+				durationMs,
+				timedOut: false,
+			});
+		} catch (error: unknown) {
+			const durationMs = Date.now() - startTime;
+
+			// Determine if this was a timeout
+			// execFileSync throws with code 'ETIMEDOUT' or sets killed:true on timeout
+			const isTimedOut =
+				Boolean((error as NodeJS.ErrnoException & { killed?: boolean }).killed) ||
+				(error as NodeJS.ErrnoException).code === "ETIMEDOUT";
+
+			let output = "";
+			if (error instanceof Error) {
+				const execError = error as NodeJS.ErrnoException & { stdout?: string; stderr?: string };
+				output = [execError.stdout ?? "", execError.stderr ?? "", execError.message ?? ""].join("\n").trim();
+			} else {
+				output = String(error);
+			}
+
+			resolve({
+				passed: false,
+				output,
+				durationMs,
+				timedOut: isTimedOut,
+			});
+		}
+	});
+}

package/src/runtime/post-exit-stdio-guard.ts

@@ -1,86 +1,86 @@
-import type { ChildProcess } from "node:child_process";
-
-interface PostExitStdioGuardOptions {
-	idleMs: number;
-	hardMs: number;
-}
-
-export interface ChildWithPipedStdio {
-	stdout: ChildProcess["stdout"];
-	stderr: ChildProcess["stderr"];
-	on: ChildProcess["on"];
-}
-
-export interface ChildWithKill {
-	kill(signal?: NodeJS.Signals | number): boolean;
-}
-
-export function trySignalChild(child: ChildWithKill, signal: NodeJS.Signals): boolean {
-	try {
-		return child.kill(signal);
-	} catch {
-		return false;
-	}
-}
-
-export function attachPostExitStdioGuard(child: ChildWithPipedStdio, options: PostExitStdioGuardOptions): () => void {
-	const { idleMs, hardMs } = options;
-	let exited = false;
-	let stdoutEnded = false;
-	let stderrEnded = false;
-	let idleTimer: ReturnType<typeof setTimeout> | undefined;
-	let hardTimer: ReturnType<typeof setTimeout> | undefined;
-
-	const destroyUnendedStdio = (): void => {
-		if (!stdoutEnded) {
-			try {
-				child.stdout?.destroy();
-		} catch {}
-		}
-		if (!stderrEnded) {
-			try {
-				child.stderr?.destroy();
-		} catch {}
-		}
-	};
-
-	const clearTimers = (): void => {
-		if (idleTimer) {
-			clearTimeout(idleTimer);
-			idleTimer = undefined;
-		}
-		if (hardTimer) {
-			clearTimeout(hardTimer);
-			hardTimer = undefined;
-		}
-	};
-
-	const armIdleTimer = () => {
-		if (!exited) return;
-		if (idleTimer) clearTimeout(idleTimer);
-		idleTimer = setTimeout(destroyUnendedStdio, idleMs);
-		idleTimer.unref();
-	};
-
-	child.stdout?.on("data", armIdleTimer);
-	child.stderr?.on("data", armIdleTimer);
-	child.stdout?.on("end", () => {
-		stdoutEnded = true;
-		if (stdoutEnded && stderrEnded) clearTimers();
-	});
-	child.stderr?.on("end", () => {
-		stderrEnded = true;
-		if (stdoutEnded && stderrEnded) clearTimers();
-	});
-	child.on("exit", () => {
-		exited = true;
-		armIdleTimer();
-		if (hardTimer) return;
-		hardTimer = setTimeout(destroyUnendedStdio, hardMs);
-		hardTimer.unref();
-	});
-	child.on("close", clearTimers);
-	child.on("error", clearTimers);
-
-	return clearTimers;
-}
+import type { ChildProcess } from "node:child_process";
+
+interface PostExitStdioGuardOptions {
+	idleMs: number;
+	hardMs: number;
+}
+
+export interface ChildWithPipedStdio {
+	stdout: ChildProcess["stdout"];
+	stderr: ChildProcess["stderr"];
+	on: ChildProcess["on"];
+}
+
+export interface ChildWithKill {
+	kill(signal?: NodeJS.Signals | number): boolean;
+}
+
+export function trySignalChild(child: ChildWithKill, signal: NodeJS.Signals): boolean {
+	try {
+		return child.kill(signal);
+	} catch {
+		return false;
+	}
+}
+
+export function attachPostExitStdioGuard(child: ChildWithPipedStdio, options: PostExitStdioGuardOptions): () => void {
+	const { idleMs, hardMs } = options;
+	let exited = false;
+	let stdoutEnded = false;
+	let stderrEnded = false;
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	let hardTimer: ReturnType<typeof setTimeout> | undefined;
+
+	const destroyUnendedStdio = (): void => {
+		if (!stdoutEnded) {
+			try {
+				child.stdout?.destroy();
+		} catch {}
+		}
+		if (!stderrEnded) {
+			try {
+				child.stderr?.destroy();
+		} catch {}
+		}
+	};
+
+	const clearTimers = (): void => {
+		if (idleTimer) {
+			clearTimeout(idleTimer);
+			idleTimer = undefined;
+		}
+		if (hardTimer) {
+			clearTimeout(hardTimer);
+			hardTimer = undefined;
+		}
+	};
+
+	const armIdleTimer = () => {
+		if (!exited) return;
+		if (idleTimer) clearTimeout(idleTimer);
+		idleTimer = setTimeout(destroyUnendedStdio, idleMs);
+		idleTimer.unref();
+	};
+
+	child.stdout?.on("data", armIdleTimer);
+	child.stderr?.on("data", armIdleTimer);
+	child.stdout?.on("end", () => {
+		stdoutEnded = true;
+		if (stdoutEnded && stderrEnded) clearTimers();
+	});
+	child.stderr?.on("end", () => {
+		stderrEnded = true;
+		if (stdoutEnded && stderrEnded) clearTimers();
+	});
+	child.on("exit", () => {
+		exited = true;
+		armIdleTimer();
+		if (hardTimer) return;
+		hardTimer = setTimeout(destroyUnendedStdio, hardMs);
+		hardTimer.unref();
+	});
+	child.on("close", clearTimers);
+	child.on("error", clearTimers);
+
+	return clearTimers;
+}

package/src/runtime/process-status.ts

@@ -1,73 +1,97 @@
-import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
-import type { TeamRunManifest } from "../state/types.ts";
-export { hasAsyncStartMarker } from "./async-marker.ts";
-
-export interface ProcessLiveness {
-	pid?: number;
-	alive: boolean;
-	detail: string;
-}
-
-const ORPHANED_ACTIVE_RUN_MS = 10 * 60 * 1000;
-/** How long a completed run stays visible in the widget after completion. */
-const COMPLETED_VISIBILITY_GRACE_MS = 8000;
-
-export function checkProcessLiveness(pid: number | undefined): ProcessLiveness {
-	if (pid === undefined || !Number.isInteger(pid) || pid <= 0) {
-		return { pid, alive: false, detail: "no pid recorded" };
-	}
-	try {
-		process.kill(pid, 0);
-		return { pid, alive: true, detail: "process is alive" };
-	} catch (error) {
-		const nodeError = error as NodeJS.ErrnoException;
-		if (nodeError.code === "EPERM") return { pid, alive: true, detail: "process exists but permission is denied" };
-		if (nodeError.code === "ESRCH") return { pid, alive: false, detail: "process does not exist" };
-		const message = error instanceof Error ? error.message : String(error);
-		return { pid, alive: false, detail: message };
-	}
-}
-
-export function isActiveRunStatus(status: string): boolean {
-	return status === "queued" || status === "planning" || status === "running" || status === "waiting";
-}
-
-export function isLikelyOrphanedActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now(), staleMs = ORPHANED_ACTIVE_RUN_MS): boolean {
-	if (!isActiveRunStatus(run.status)) return false;
-	if (run.async?.pid !== undefined) return false;
-	const updatedAt = new Date(run.updatedAt).getTime();
-	if (!Number.isFinite(updatedAt) || now - updatedAt < staleMs) return false;
-	if (agents.length === 0) return run.summary === "Creating workflow prompts and placeholder results.";
-	return agents.every((agent) => agent.status === "queued" && !agent.completedAt && !agent.progress);
-}
-
-function hasDurableActiveAgentEvidence(agent: CrewAgentRecord): boolean {
-	if (agent.status !== "running" && agent.status !== "queued") return false;
-	return Boolean(agent.statusPath || agent.eventsPath || agent.outputPath || agent.progress || agent.toolUses || agent.jsonEvents);
-}
-
-export function hasStaleAsyncProcess(run: TeamRunManifest): boolean {
-	if (!isActiveRunStatus(run.status) || !run.async) return false;
-	return !checkProcessLiveness(run.async.pid).alive;
-}
-
-export function isDisplayActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now()): boolean {
-	if (hasStaleAsyncProcess(run) || isLikelyOrphanedActiveRun(run, agents, now)) return false;
-	// Grace period: show completed runs for a few seconds so users see the result.
-	if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
-		const lastAgentActivity = agents.reduce<number>((max, agent) => {
-			const ts = agent.completedAt ?? agent.startedAt;
-			const parsed = ts ? new Date(ts).getTime() : 0;
-			return Number.isFinite(parsed) && parsed > max ? parsed : max;
-		}, new Date(run.updatedAt).getTime());
-		if (Number.isFinite(lastAgentActivity) && now - lastAgentActivity < COMPLETED_VISIBILITY_GRACE_MS) return true;
-		return false;
-	}
-	if (!isActiveRunStatus(run.status)) return false;
-	// Keep the always-visible widget quiet until a worker actually exists.
-	// Empty active manifests can be created briefly at startup, by old fixture/scaffold
-	// runs, or from cross-cwd registry history; showing them causes noisy 0/0 rows and
-	// needless spinner redraws. The full dashboard can still list historical runs.
-	if (agents.length === 0) return false;
-	return agents.some(hasDurableActiveAgentEvidence);
-}
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+export { hasAsyncStartMarker } from "./async-marker.ts";
+
+export interface ProcessLiveness {
+	pid?: number;
+	alive: boolean;
+	detail: string;
+}
+
+const ORPHANED_ACTIVE_RUN_MS = 10 * 60 * 1000;
+/** How long a completed run stays visible in the widget after completion. */
+const COMPLETED_VISIBILITY_GRACE_MS = 8000;
+/** Maximum age (ms) for an active run before it's considered stale.
+ * After this time, PID-only liveness is unreliable due to PID recycling. */
+const STALE_ACTIVE_RUN_MS = 30 * 60 * 1000;
+
+export function checkProcessLiveness(pid: number | undefined): ProcessLiveness {
+	if (pid === undefined || !Number.isInteger(pid) || pid <= 0) {
+		return { pid, alive: false, detail: "no pid recorded" };
+	}
+	try {
+		process.kill(pid, 0);
+		return { pid, alive: true, detail: "process is alive" };
+	} catch (error) {
+		const nodeError = error as NodeJS.ErrnoException;
+		if (nodeError.code === "EPERM") return { pid, alive: true, detail: "process exists but permission is denied" };
+		if (nodeError.code === "ESRCH") return { pid, alive: false, detail: "process does not exist" };
+		const message = error instanceof Error ? error.message : String(error);
+		return { pid, alive: false, detail: message };
+	}
+}
+
+export function isActiveRunStatus(status: string): boolean {
+	return status === "queued" || status === "planning" || status === "running" || status === "waiting";
+}
+
+export function isFinishedRunStatus(status: string): boolean {
+	return status === "completed" || status === "failed" || status === "cancelled" || status === "blocked";
+}
+
+export function isLikelyOrphanedActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now(), staleMs = ORPHANED_ACTIVE_RUN_MS): boolean {
+	if (!isActiveRunStatus(run.status)) return false;
+	if (run.async?.pid !== undefined) return false;
+	const updatedAt = new Date(run.updatedAt).getTime();
+	if (!Number.isFinite(updatedAt) || now - updatedAt < staleMs) return false;
+	if (agents.length === 0) return run.summary === "Creating workflow prompts and placeholder results.";
+	return agents.every((agent) => agent.status === "queued" && !agent.completedAt && !agent.progress);
+}
+
+function hasDurableActiveAgentEvidence(agent: CrewAgentRecord): boolean {
+	if (agent.status !== "running" && agent.status !== "queued") return false;
+	return Boolean(agent.statusPath || agent.eventsPath || agent.outputPath || agent.progress || agent.toolUses || agent.jsonEvents);
+}
+
+export function hasStaleAsyncProcess(run: TeamRunManifest, now = Date.now()): boolean {
+	if (!isActiveRunStatus(run.status) || !run.async) return false;
+	const pidAlive = checkProcessLiveness(run.async.pid).alive;
+	if (!pidAlive) return true;
+	// PID is alive, but check if the run is suspiciously old.
+	// PID recycling means a stale PID could point to an unrelated process.
+	const updatedAt = new Date(run.updatedAt).getTime();
+	const age = now - updatedAt;
+	if (Number.isFinite(updatedAt) && age > STALE_ACTIVE_RUN_MS) {
+		// Additional evidence: if no agent has recent activity, treat as stale.
+		// The real process would have updated the manifest within 30 minutes.
+		return true;
+	}
+	return false;
+}
+
+export function isDisplayActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now()): boolean {
+	if (hasStaleAsyncProcess(run, now) || isLikelyOrphanedActiveRun(run, agents, now)) return false;
+	// Hard filter: if an active-status run hasn't been updated in > STALE_ACTIVE_RUN_MS
+	// and has no async PID tracking, it's a ghost from a crashed process.
+	if (isActiveRunStatus(run.status) && !run.async) {
+		const updatedAt = new Date(run.updatedAt).getTime();
+		if (Number.isFinite(updatedAt) && now - updatedAt > STALE_ACTIVE_RUN_MS) return false;
+	}
+	// Grace period: show completed runs for a few seconds so users see the result.
+	if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
+		const lastAgentActivity = agents.reduce<number>((max, agent) => {
+			const ts = agent.completedAt ?? agent.startedAt;
+			const parsed = ts ? new Date(ts).getTime() : 0;
+			return Number.isFinite(parsed) && parsed > max ? parsed : max;
+		}, new Date(run.updatedAt).getTime());
+		if (Number.isFinite(lastAgentActivity) && now - lastAgentActivity < COMPLETED_VISIBILITY_GRACE_MS) return true;
+		return false;
+	}
+	if (!isActiveRunStatus(run.status)) return false;
+	// Keep the always-visible widget quiet until a worker actually exists.
+	// Empty active manifests can be created briefly at startup, by old fixture/scaffold
+	// runs, or from cross-cwd registry history; showing them causes noisy 0/0 rows and
+	// needless spinner redraws. The full dashboard can still list historical runs.
+	if (agents.length === 0) return false;
+	return agents.some(hasDurableActiveAgentEvidence);
+}