pi-crew 0.1.49 → 0.2.0

package/src/runtime/pi-json-output.ts

@@ -1,111 +1,111 @@
-export interface ParsedPiUsage {
-	input?: number;
-	output?: number;
-	cacheRead?: number;
-	cacheWrite?: number;
-	cost?: number;
-	turns?: number;
-}
-
-export interface ParsedPiJsonOutput {
-	jsonEvents: number;
-	textEvents: string[];
-	finalText?: string;
-	usage?: ParsedPiUsage;
-}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
-}
-
-function numberField(obj: Record<string, unknown>, keys: string[]): number | undefined {
-	for (const key of keys) {
-		const value = obj[key];
-		if (typeof value === "number" && Number.isFinite(value)) return value;
-	}
-	return undefined;
-}
-
-function mergeUsage(target: ParsedPiUsage, source: ParsedPiUsage): ParsedPiUsage {
-	return {
-		input: source.input ?? target.input,
-		output: source.output ?? target.output,
-		cacheRead: source.cacheRead ?? target.cacheRead,
-		cacheWrite: source.cacheWrite ?? target.cacheWrite,
-		cost: source.cost ?? target.cost,
-		turns: source.turns ?? target.turns,
-	};
-}
-
-function extractUsage(value: unknown): ParsedPiUsage | undefined {
-	const obj = asRecord(value);
-	if (!obj) return undefined;
-	const direct: ParsedPiUsage = {
-		input: numberField(obj, ["input", "inputTokens", "input_tokens"]),
-		output: numberField(obj, ["output", "outputTokens", "output_tokens"]),
-		cacheRead: numberField(obj, ["cacheRead", "cache_read", "cacheReadTokens", "cache_read_tokens"]),
-		cacheWrite: numberField(obj, ["cacheWrite", "cache_write", "cacheWriteTokens", "cache_write_tokens"]),
-		cost: numberField(obj, ["cost", "costUsd", "cost_usd"]),
-		turns: numberField(obj, ["turns", "turnCount", "turn_count"]),
-	};
-	if (Object.values(direct).some((entry) => entry !== undefined)) return direct;
-	for (const key of ["usage", "tokenUsage", "tokens", "stats"]) {
-		const nested = extractUsage(obj[key]);
-		if (nested) return nested;
-	}
-	return undefined;
-}
-
-function textFromContent(content: unknown): string[] {
-	if (typeof content === "string") return [content];
-	if (!Array.isArray(content)) return [];
-	const text: string[] = [];
-	for (const part of content) {
-		const obj = asRecord(part);
-		if (!obj) continue;
-		if (obj.type === "text" && typeof obj.text === "string") text.push(obj.text);
-		else if (typeof obj.content === "string") text.push(obj.content);
-	}
-	return text;
-}
-
-function extractText(value: unknown): string[] {
-	const obj = asRecord(value);
-	if (!obj) return [];
-	const message = asRecord(obj.message);
-	if (message?.role !== undefined && message.role !== "assistant") return [];
-	const text: string[] = [];
-	if (typeof obj.text === "string") text.push(obj.text);
-	if (typeof obj.output === "string") text.push(obj.output);
-	if (typeof obj.finalOutput === "string") text.push(obj.finalOutput);
-	if (typeof obj.final_output === "string") text.push(obj.final_output);
-	if (!message) text.push(...textFromContent(obj.content));
-	if (message) text.push(...textFromContent(message.content));
-	return text.filter((entry) => entry.trim().length > 0);
-}
-
-export function parsePiJsonOutput(stdout: string): ParsedPiJsonOutput {
-	let jsonEvents = 0;
-	const textEvents: string[] = [];
-	let usage: ParsedPiUsage | undefined;
-	for (const line of stdout.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		let event: unknown;
-		try {
-			event = JSON.parse(trimmed) as unknown;
-		} catch {
-			continue;
-		}
-		jsonEvents++;
-		textEvents.push(...extractText(event));
-		const eventUsage = extractUsage(event);
-		if (eventUsage) usage = mergeUsage(usage ?? {}, eventUsage);
-	}
-	return {
-		jsonEvents,
-		textEvents,
-		finalText: textEvents.length > 0 ? textEvents[textEvents.length - 1] : undefined,
-		usage,
-	};
-}
+export interface ParsedPiUsage {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	cost?: number;
+	turns?: number;
+}
+
+export interface ParsedPiJsonOutput {
+	jsonEvents: number;
+	textEvents: string[];
+	finalText?: string;
+	usage?: ParsedPiUsage;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function numberField(obj: Record<string, unknown>, keys: string[]): number | undefined {
+	for (const key of keys) {
+		const value = obj[key];
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+	}
+	return undefined;
+}
+
+function mergeUsage(target: ParsedPiUsage, source: ParsedPiUsage): ParsedPiUsage {
+	return {
+		input: source.input ?? target.input,
+		output: source.output ?? target.output,
+		cacheRead: source.cacheRead ?? target.cacheRead,
+		cacheWrite: source.cacheWrite ?? target.cacheWrite,
+		cost: source.cost ?? target.cost,
+		turns: source.turns ?? target.turns,
+	};
+}
+
+function extractUsage(value: unknown): ParsedPiUsage | undefined {
+	const obj = asRecord(value);
+	if (!obj) return undefined;
+	const direct: ParsedPiUsage = {
+		input: numberField(obj, ["input", "inputTokens", "input_tokens"]),
+		output: numberField(obj, ["output", "outputTokens", "output_tokens"]),
+		cacheRead: numberField(obj, ["cacheRead", "cache_read", "cacheReadTokens", "cache_read_tokens"]),
+		cacheWrite: numberField(obj, ["cacheWrite", "cache_write", "cacheWriteTokens", "cache_write_tokens"]),
+		cost: numberField(obj, ["cost", "costUsd", "cost_usd"]),
+		turns: numberField(obj, ["turns", "turnCount", "turn_count"]),
+	};
+	if (Object.values(direct).some((entry) => entry !== undefined)) return direct;
+	for (const key of ["usage", "tokenUsage", "tokens", "stats"]) {
+		const nested = extractUsage(obj[key]);
+		if (nested) return nested;
+	}
+	return undefined;
+}
+
+function textFromContent(content: unknown): string[] {
+	if (typeof content === "string") return [content];
+	if (!Array.isArray(content)) return [];
+	const text: string[] = [];
+	for (const part of content) {
+		const obj = asRecord(part);
+		if (!obj) continue;
+		if (obj.type === "text" && typeof obj.text === "string") text.push(obj.text);
+		else if (typeof obj.content === "string") text.push(obj.content);
+	}
+	return text;
+}
+
+function extractText(value: unknown): string[] {
+	const obj = asRecord(value);
+	if (!obj) return [];
+	const message = asRecord(obj.message);
+	if (message?.role !== undefined && message.role !== "assistant") return [];
+	const text: string[] = [];
+	if (typeof obj.text === "string") text.push(obj.text);
+	if (typeof obj.output === "string") text.push(obj.output);
+	if (typeof obj.finalOutput === "string") text.push(obj.finalOutput);
+	if (typeof obj.final_output === "string") text.push(obj.final_output);
+	if (!message) text.push(...textFromContent(obj.content));
+	if (message) text.push(...textFromContent(message.content));
+	return text.filter((entry) => entry.trim().length > 0);
+}
+
+export function parsePiJsonOutput(stdout: string): ParsedPiJsonOutput {
+	let jsonEvents = 0;
+	const textEvents: string[] = [];
+	let usage: ParsedPiUsage | undefined;
+	for (const line of stdout.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		let event: unknown;
+		try {
+			event = JSON.parse(trimmed) as unknown;
+		} catch {
+			continue;
+		}
+		jsonEvents++;
+		textEvents.push(...extractText(event));
+		const eventUsage = extractUsage(event);
+		if (eventUsage) usage = mergeUsage(usage ?? {}, eventUsage);
+	}
+	return {
+		jsonEvents,
+		textEvents,
+		finalText: textEvents.length > 0 ? textEvents[textEvents.length - 1] : undefined,
+		usage,
+	};
+}

package/src/runtime/pi-spawn.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 
@@ -11,6 +12,48 @@ function isRunnableNodeScript(filePath: string): boolean {
 	return fs.existsSync(filePath) && /\.(?:mjs|cjs|js)$/i.test(filePath);
 }
 
+/**
+ * Check that a resolved path is within known safe prefixes.
+ * Allowed prefixes: npm global bin (APPDATA/npm), project node_modules/.bin,
+ * or the current process's execPath directory.
+ */
+function isWithinAllowedPrefixes(resolvedPath: string): boolean {
+	const normalized = path.resolve(resolvedPath).toLowerCase();
+
+	const allowedPrefixes: string[] = [];
+
+	// Current process execPath directory (e.g. node installation)
+	try {
+		const execDir = path.dirname(fs.realpathSync.native(process.execPath));
+		allowedPrefixes.push(execDir.toLowerCase());
+	} catch { /* ignore */ }
+
+	// npm global bin via APPDATA
+	if (process.env.APPDATA) {
+		allowedPrefixes.push(path.join(process.env.APPDATA, "npm").toLowerCase());
+	}
+
+	// Project-local node_modules/.bin
+	try {
+		const projectBin = path.resolve("node_modules", ".bin");
+		allowedPrefixes.push(projectBin.toLowerCase());
+	} catch { /* ignore */ }
+
+	// User home npm-global
+	try {
+		const homeNpm = path.join(os.homedir(), ".npm-global", "bin");
+		allowedPrefixes.push(homeNpm.toLowerCase());
+	} catch { /* ignore */ }
+
+	// User home .local/bin
+	try {
+		const homeLocal = path.join(os.homedir(), ".local", "bin");
+		allowedPrefixes.push(homeLocal.toLowerCase());
+	} catch { /* ignore */ }
+
+	return allowedPrefixes.some((prefix) => normalized.startsWith(prefix));
+}
+
 function resolvePiPackageRoot(): string | undefined {
 	try {
 		const entry = process.argv[1];
@@ -61,9 +104,6 @@ function findPiPackageJsonFrom(startDir: string): string | undefined {
 }
 
 function resolvePiCliScript(): string | undefined {
-	const explicit = process.env.PI_TEAMS_PI_BIN?.trim();
-	if (explicit && isRunnableNodeScript(explicit)) return explicit;
-
 	const argv1 = process.argv[1];
 	if (argv1) {
 		const argvPath = path.isAbsolute(argv1) ? argv1 : path.resolve(argv1);
@@ -85,11 +125,39 @@ function resolvePiCliScript(): string | undefined {
 	return undefined;
 }
 
+function validateExplicitBin(explicit: string): string | undefined {
+	const resolved = path.resolve(explicit);
+	if (!fs.existsSync(resolved)) return undefined;
+	// Reject paths outside allowed safe prefixes
+	if (!isWithinAllowedPrefixes(resolved)) {
+		throw new Error(
+			`PI_TEAMS_PI_BIN path '${resolved}' is outside allowed prefixes. ` +
+			`Allowed: npm global bin, project node_modules/.bin, APPDATA/npm, or process execPath directory.`,
+		);
+	}
+	// Reject if symlink points outside expected directories
+	try {
+		const real = fs.realpathSync(resolved);
+		if (!isWithinAllowedPrefixes(real)) {
+			throw new Error(
+				`PI_TEAMS_PI_BIN symlink target '${real}' is outside allowed prefixes.`,
+			);
+		}
+	} catch (e) {
+		if (e instanceof Error && e.message.includes("allowed prefixes")) throw e;
+		return undefined;
+	}
+	return resolved;
+}
+
 export function getPiSpawnCommand(args: string[]): PiSpawnCommand {
 	const explicit = process.env.PI_TEAMS_PI_BIN?.trim();
-	if (explicit && fs.existsSync(explicit)) {
-		if (isRunnableNodeScript(explicit)) return { command: process.execPath, args: [explicit, ...args] };
-		return { command: explicit, args };
+	if (explicit) {
+		const validated = validateExplicitBin(explicit);
+		if (validated) {
+			if (isRunnableNodeScript(validated)) return { command: process.execPath, args: [validated, ...args] };
+			return { command: validated, args };
+		}
 	}
 	if (process.platform === "win32") {
 		const script = resolvePiCliScript();

package/src/runtime/policy-engine.ts

@@ -1,79 +1,79 @@
-import type { CrewLimitsConfig } from "../config/config.ts";
-import type { PolicyDecision, PolicyDecisionAction, PolicyDecisionReason, TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { evaluateGreenContract } from "./green-contract.ts";
-import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
-
-export interface PolicyEngineInput {
-	manifest: TeamRunManifest;
-	tasks: TeamTaskState[];
-	limits?: CrewLimitsConfig;
-	now?: Date;
-}
-
-function decision(action: PolicyDecisionAction, reason: PolicyDecisionReason, message: string, taskId?: string): PolicyDecision {
-	return {
-		action,
-		reason,
-		message,
-		taskId,
-		createdAt: new Date().toISOString(),
-	};
-}
-
-function taskDepth(task: TeamTaskState, tasksById: Map<string, TeamTaskState>): number {
-	let depth = 0;
-	let current = task.graph?.parentId;
-	const seen = new Set<string>();
-	while (current && !seen.has(current)) {
-		seen.add(current);
-		depth += 1;
-		current = tasksById.get(current)?.graph?.parentId;
-	}
-	return depth;
-}
-
-export function evaluateCrewPolicy(input: PolicyEngineInput): PolicyDecision[] {
-	const decisions: PolicyDecision[] = [];
-	const maxTasksPerRun = Number.isFinite(input.limits?.maxTasksPerRun) ? input.limits!.maxTasksPerRun : undefined;
-	if (maxTasksPerRun !== undefined && input.tasks.length > maxTasksPerRun) {
-		decisions.push(decision("block", "limit_exceeded", `Run has ${input.tasks.length} tasks, exceeding maxTasksPerRun=${maxTasksPerRun}.`));
-	}
-	const runningCount = input.tasks.filter((task) => task.status === "running").length;
-	const maxConcurrentWorkers = Number.isFinite(input.limits?.maxConcurrentWorkers) ? input.limits!.maxConcurrentWorkers : undefined;
-	if (maxConcurrentWorkers !== undefined && runningCount > maxConcurrentWorkers) {
-		decisions.push(decision("block", "limit_exceeded", `Run has ${runningCount} running workers, exceeding maxConcurrentWorkers=${maxConcurrentWorkers}.`));
-	}
-	const tasksById = new Map(input.tasks.map((task) => [task.id, task]));
-
-	for (const task of input.tasks) {
-		if (input.limits?.maxChildrenPerTask !== undefined && (task.graph?.children.length ?? 0) > input.limits.maxChildrenPerTask) {
-			decisions.push(decision("block", "limit_exceeded", `Task has ${task.graph?.children.length ?? 0} children, exceeding maxChildrenPerTask=${input.limits.maxChildrenPerTask}.`, task.id));
-		}
-		if (input.limits?.maxTaskDepth !== undefined && taskDepth(task, tasksById) > input.limits.maxTaskDepth) {
-			decisions.push(decision("block", "limit_exceeded", `Task graph depth exceeds maxTaskDepth=${input.limits.maxTaskDepth}.`, task.id));
-		}
-		if (task.status === "failed") {
-			const retryCount = task.policy?.retryCount ?? 0;
-			const maxRetries = input.limits?.maxRetriesPerTask ?? 0;
-			decisions.push(decision(retryCount < maxRetries ? "retry" : "escalate", "task_failed", task.error ? `Task failed: ${task.error}` : "Task failed.", task.id));
-		}
-		if ((task.status === "running" || task.status === "queued") && task.heartbeat && task.heartbeat.alive !== false && isWorkerHeartbeatStale(task.heartbeat, input.limits?.heartbeatStaleMs ?? 60_000, input.now)) {
-			decisions.push(decision("escalate", "worker_stale", "Worker heartbeat is stale.", task.id));
-		}
-		if (task.taskPacket?.verification) {
-			const outcome = evaluateGreenContract(task.taskPacket.verification, task.verification);
-			if (!outcome.satisfied && task.status === "completed") {
-				decisions.push(decision("block", "green_unsatisfied", `Green contract unsatisfied: required=${outcome.requiredGreenLevel}, observed=${outcome.observedGreenLevel}.`, task.id));
-			}
-		}
-	}
-
-	if (decisions.length === 0 && input.tasks.length > 0 && input.tasks.every((task) => task.status === "completed")) {
-		decisions.push(decision("closeout", "run_complete", "All tasks completed and no policy blockers were found."));
-	}
-	return decisions;
-}
-
-export function summarizePolicyDecisions(decisions: PolicyDecision[]): string[] {
-	return decisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`);
-}
+import type { CrewLimitsConfig } from "../config/config.ts";
+import type { PolicyDecision, PolicyDecisionAction, PolicyDecisionReason, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { evaluateGreenContract } from "./green-contract.ts";
+import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
+
+export interface PolicyEngineInput {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	limits?: CrewLimitsConfig;
+	now?: Date;
+}
+
+function decision(action: PolicyDecisionAction, reason: PolicyDecisionReason, message: string, taskId?: string): PolicyDecision {
+	return {
+		action,
+		reason,
+		message,
+		taskId,
+		createdAt: new Date().toISOString(),
+	};
+}
+
+function taskDepth(task: TeamTaskState, tasksById: Map<string, TeamTaskState>): number {
+	let depth = 0;
+	let current = task.graph?.parentId;
+	const seen = new Set<string>();
+	while (current && !seen.has(current)) {
+		seen.add(current);
+		depth += 1;
+		current = tasksById.get(current)?.graph?.parentId;
+	}
+	return depth;
+}
+
+export function evaluateCrewPolicy(input: PolicyEngineInput): PolicyDecision[] {
+	const decisions: PolicyDecision[] = [];
+	const maxTasksPerRun = Number.isFinite(input.limits?.maxTasksPerRun) ? input.limits!.maxTasksPerRun : undefined;
+	if (maxTasksPerRun !== undefined && input.tasks.length > maxTasksPerRun) {
+		decisions.push(decision("block", "limit_exceeded", `Run has ${input.tasks.length} tasks, exceeding maxTasksPerRun=${maxTasksPerRun}.`));
+	}
+	const runningCount = input.tasks.filter((task) => task.status === "running").length;
+	const maxConcurrentWorkers = Number.isFinite(input.limits?.maxConcurrentWorkers) ? input.limits!.maxConcurrentWorkers : undefined;
+	if (maxConcurrentWorkers !== undefined && runningCount > maxConcurrentWorkers) {
+		decisions.push(decision("block", "limit_exceeded", `Run has ${runningCount} running workers, exceeding maxConcurrentWorkers=${maxConcurrentWorkers}.`));
+	}
+	const tasksById = new Map(input.tasks.map((task) => [task.id, task]));
+
+	for (const task of input.tasks) {
+		if (input.limits?.maxChildrenPerTask !== undefined && (task.graph?.children.length ?? 0) > input.limits.maxChildrenPerTask) {
+			decisions.push(decision("block", "limit_exceeded", `Task has ${task.graph?.children.length ?? 0} children, exceeding maxChildrenPerTask=${input.limits.maxChildrenPerTask}.`, task.id));
+		}
+		if (input.limits?.maxTaskDepth !== undefined && taskDepth(task, tasksById) > input.limits.maxTaskDepth) {
+			decisions.push(decision("block", "limit_exceeded", `Task graph depth exceeds maxTaskDepth=${input.limits.maxTaskDepth}.`, task.id));
+		}
+		if (task.status === "failed") {
+			const retryCount = task.policy?.retryCount ?? 0;
+			const maxRetries = input.limits?.maxRetriesPerTask ?? 0;
+			decisions.push(decision(retryCount < maxRetries ? "retry" : "escalate", "task_failed", task.error ? `Task failed: ${task.error}` : "Task failed.", task.id));
+		}
+		if ((task.status === "running" || task.status === "queued") && task.heartbeat && task.heartbeat.alive !== false && isWorkerHeartbeatStale(task.heartbeat, input.limits?.heartbeatStaleMs ?? 60_000, input.now)) {
+			decisions.push(decision("escalate", "worker_stale", "Worker heartbeat is stale.", task.id));
+		}
+		if (task.taskPacket?.verification) {
+			const outcome = evaluateGreenContract(task.taskPacket.verification, task.verification);
+			if (!outcome.satisfied && task.status === "completed") {
+				decisions.push(decision("block", "green_unsatisfied", `Green contract unsatisfied: required=${outcome.requiredGreenLevel}, observed=${outcome.observedGreenLevel}.`, task.id));
+			}
+		}
+	}
+
+	if (decisions.length === 0 && input.tasks.length > 0 && input.tasks.every((task) => task.status === "completed")) {
+		decisions.push(decision("closeout", "run_complete", "All tasks completed and no policy blockers were found."));
+	}
+	return decisions;
+}
+
+export function summarizePolicyDecisions(decisions: PolicyDecision[]): string[] {
+	return decisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`);
+}

package/src/runtime/post-checks.ts

@@ -0,0 +1,122 @@
+/**
+ * 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,
+			});
+		}
+	});
+}

package/src/runtime/process-status.ts

@@ -9,6 +9,8 @@ export interface ProcessLiveness {
 }
 
 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) {
@@ -50,7 +52,18 @@ export function hasStaleAsyncProcess(run: TeamRunManifest): boolean {
 }
 
 export function isDisplayActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now()): boolean {
-	if (!isActiveRunStatus(run.status) || hasStaleAsyncProcess(run) || isLikelyOrphanedActiveRun(run, agents, now)) return false;
+	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