pi-crew 0.9.29 → 0.9.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.29",
+  "version": "0.9.31",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/extension/register.ts

@@ -139,6 +139,9 @@ export { __test__subagentSpawnParams };
 export function registerPiTeams(pi: ExtensionAPI): void {
 	const disposeI18n = initI18n(pi);
 	resetTimings();
+	// S06: Verbose/debug flags for pi-crew diagnostics
+	const verbose = process.env.PI_CREW_VERBOSE === "1" || process.argv.includes("--verbose");
+	const debug = process.env.PI_CREW_DEBUG === "1" || process.argv.includes("--debug");
 	time("register:start");
 	// Cold-start race fix (general): pre-warm the hot module graph NOW, during
 	// single-threaded registration, before any concurrent subagent can spawn.

package/src/prompt/prompt-runtime.ts

@@ -1,5 +1,8 @@
 import * as fs from "node:fs";
+import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { logInternalError } from "../utils/internal-error.ts";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
 
 export const PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV = "PI_TEAMS_INHERIT_PROJECT_CONTEXT";
 export const PI_TEAMS_INHERIT_SKILLS_ENV = "PI_TEAMS_INHERIT_SKILLS";
@@ -12,6 +15,99 @@ const PROJECT_CONTEXT_HEADER = "\n\n# Project Context\n\nProject-specific instru
 const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions for specific tasks.";
 const DATE_HEADER = "\nCurrent date:";
 
+// ── FIX-02: Steering content sanitization limits ──────────────────────────
+// Bounded to keep a malformed/malicious steer entry from blowing up the
+// worker's prompt budget or smuggling control sequences into the agent.
+const MAX_STEER_MESSAGE_LENGTH = 4096;
+const MAX_STEER_MESSAGE_NEWLINES = 50;
+// C0 control characters minus the printable whitespace (\t \n \r). These
+// are the bytes most useful for ANSI escapes, terminal-control tricks, and
+// NUL-injection attacks when steer content reaches the worker's UI.
+const STEER_CONTROL_CHAR_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+
+export interface SteerSanitizeResult {
+	valid: boolean;
+	reason?: string;
+	message?: string;
+}
+
+export interface SteerEntry {
+	type?: string;
+	message?: string;
+}
+
+/**
+ * Validate a single steering-file entry before forwarding it to
+ * `pi.sendMessage`. FIX-02: reject oversized payloads, excessive newlines,
+ * or control characters that could be used to confuse the worker UI.
+ */
+export function sanitizeSteerMessage(entry: SteerEntry): SteerSanitizeResult {
+	const message = entry.message;
+	if (typeof message !== "string" || message.length === 0) {
+		return { valid: false, reason: "missing-or-empty-message" };
+	}
+	if (message.length > MAX_STEER_MESSAGE_LENGTH) {
+		return { valid: false, reason: `message-too-long:${message.length}` };
+	}
+	const newlineCount = (message.match(/\n/g) ?? []).length;
+	if (newlineCount > MAX_STEER_MESSAGE_NEWLINES) {
+		return { valid: false, reason: `too-many-newlines:${newlineCount}` };
+	}
+	if (STEER_CONTROL_CHAR_PATTERN.test(message)) {
+		return { valid: false, reason: "contains-control-characters" };
+	}
+	return { valid: true, message };
+}
+
+// ── FIX-03: Steering file path containment validation ─────────────────────
+// The steering file path is inherited from the parent via env, so we
+// defensively re-validate it before the first read to catch symlink
+// redirection or paths that escape the session's artifacts root.
+export interface SteeringFileValidation {
+	valid: boolean;
+	reason?: string;
+	resolvedPath?: string;
+}
+
+/**
+ * Validate `PI_CREW_STEERING_FILE` before first read. FIX-03:
+ *   1. `lstatSync` rejects a symlink at the steering file itself.
+ *   2. `resolveRealContainedPath` walks the ancestor chain with O_NOFOLLOW
+ *      to reject any symlinked parent (e.g. a redirected `artifactsRoot`)
+ *      and to verify the resolved path stays inside the derived artifacts
+ *      root (`<artifactsRoot>/steering/<taskId>.jsonl` → `<artifactsRoot>`).
+ *
+ * Returns `{ valid: false }` with a reason on any violation. Callers must
+ * log + skip steering on failure rather than abort the worker.
+ */
+export function validateSteeringFile(steeringFile: string): SteeringFileValidation {
+	try {
+		const lst = fs.lstatSync(steeringFile);
+		if (lst.isSymbolicLink()) {
+			return { valid: false, reason: "steering-file-is-symlink" };
+		}
+	} catch (error) {
+		const errCode = (error as NodeJS.ErrnoException).code;
+		if (errCode && errCode !== "ENOENT") {
+			return { valid: false, reason: `lstat-failed:${errCode}` };
+		}
+	}
+	// Layout invariant from task-runner.ts: `steeringFile` is built as
+	// `<artifactsRoot>/steering/<taskId>.jsonl`. We don't trust the caller
+	// to pass `artifactsRoot`, so derive it as 2 levels up. `resolveRealContainedPath`
+	// then enforces both containment AND ancestor-symlink safety in one shot.
+	const artifactsRoot = path.resolve(steeringFile, "..", "..");
+	try {
+		const resolved = resolveRealContainedPath(artifactsRoot, steeringFile);
+		return { valid: true, resolvedPath: resolved };
+	} catch (error) {
+		return {
+			valid: false,
+			reason: `path-validation-failed:${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+}
+
 function readBooleanEnv(name: string): boolean | undefined {
 	const value = process.env[name];
 	if (value === undefined) return undefined;
@@ -83,43 +179,67 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 	// the active session via pi.sendMessage with deliverAs:"steer".
 	const steeringFile = process.env[PI_CREW_STEERING_FILE_ENV];
 	if (steeringFile) {
-		let lastOffset = 0;
-		const pollSteering = (): void => {
-			try {
-				const stat = fs.statSync(steeringFile, { throwIfNoEntry: false });
-				if (!stat || stat.size <= lastOffset) return;
-				const fd = fs.openSync(steeringFile, "r");
+		// FIX-03: validate the steering file path once before first read.
+		const validation = validateSteeringFile(steeringFile);
+		if (!validation.valid) {
+			logInternalError(
+				"prompt-runtime.steering-file-rejected",
+				new Error(validation.reason ?? "steering-file-validation-failed"),
+				`path=${steeringFile}`,
+				"warn",
+			);
+		} else {
+			const safeSteeringFile = validation.resolvedPath ?? steeringFile;
+			let lastOffset = 0;
+			const pollSteering = (): void => {
 				try {
-					const buf = Buffer.alloc(stat.size - lastOffset);
-					fs.readSync(fd, buf, 0, buf.length, lastOffset);
-					lastOffset = stat.size;
-					const lines = buf.toString("utf8").split("\n").filter(Boolean);
-					for (const line of lines) {
-						try {
-							const entry = JSON.parse(line) as { type?: string; message?: string };
-							if (entry.type === "steer" && entry.message) {
+					const stat = fs.statSync(safeSteeringFile, { throwIfNoEntry: false });
+					if (!stat || stat.size <= lastOffset) return;
+					const fd = fs.openSync(safeSteeringFile, "r");
+					try {
+						const buf = Buffer.alloc(stat.size - lastOffset);
+						fs.readSync(fd, buf, 0, buf.length, lastOffset);
+						lastOffset = stat.size;
+						const lines = buf.toString("utf8").split("\n").filter(Boolean);
+						for (const line of lines) {
+							try {
+								const entry = JSON.parse(line) as SteerEntry;
+								if (entry.type !== "steer") continue;
+								// FIX-02: sanitize each steer entry before forwarding
+								// to pi.sendMessage. Reject oversized payloads,
+								// excessive newlines, and control characters.
+								const sanitized = sanitizeSteerMessage(entry);
+								if (!sanitized.valid || sanitized.message === undefined) {
+									logInternalError(
+										"prompt-runtime.steer-rejected",
+										new Error(sanitized.reason ?? "steer-sanitization-failed"),
+										`line-preview=${line.slice(0, 64)}`,
+										"warn",
+									);
+									continue;
+								}
 								pi.sendMessage(
-									{ customType: "crew-steer", content: entry.message, display: false },
+									{ customType: "crew-steer", content: sanitized.message, display: false },
 									{ deliverAs: "steer" },
 								);
+							} catch {
+								// Malformed line — skip
 							}
+						}
+					} finally {
+						try {
+							fs.closeSync(fd);
 						} catch {
-							// Malformed line — skip
+							/* already closed */
 						}
 					}
-				} finally {
-					try {
-						fs.closeSync(fd);
-					} catch {
-						/* already closed */
-					}
+				} catch {
+					// File doesn't exist yet or read error — will retry next tick
 				}
-			} catch {
-				// File doesn't exist yet or read error — will retry next tick
-			}
-		};
-		const timer = setInterval(pollSteering, 500);
-		timer.unref?.();
+			};
+			const timer = setInterval(pollSteering, 500);
+			timer.unref?.();
+		}
 	}
 
 	// ── Prompt rewriting (existing) ────────────────────────────────────────

package/src/runtime/async-runner.ts

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { appendEvent } from "../state/event-log.ts";
+import { appendEvent, appendEventAsync } from "../state/event-log.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
@@ -257,7 +257,8 @@ export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise
 	const loader = resolveTypeScriptLoader();
 	if (!loader) {
 		const message = buildLoaderUnavailableMessage(packageRootFromRuntime());
-		appendEvent(manifest.eventsPath, {
+		// FIX-08: use async event append to avoid sleepSync event-loop blocking.
+		await appendEventAsync(manifest.eventsPath, {
 			type: "async.failed",
 			runId: manifest.runId,
 			message,

package/src/runtime/child-pi.ts

@@ -112,6 +112,7 @@ export function killProcessPid(pid: number): void {
 						"child-pi.taskkill-stuck",
 						new Error(`process ${pid} still alive 2s after taskkill /T /F; retrying`),
 						`pid=${pid}`,
+						"error",
 					);
 					try {
 						spawnTaskkillSafe(pid);

package/src/runtime/crash-recovery.ts

@@ -244,7 +244,7 @@ export function cancelOrphanedRuns(
 		});
 		if (cancelledRun)
 			void terminateLiveAgentsForRun(manifest.runId, "cancelled", appendEvent, loaded.manifest.eventsPath).catch((error) =>
-				logInternalError("crash-recovery.orphan.terminate", error, `runId=${manifest.runId}`),
+				logInternalError("crash-recovery.orphan.terminate", error, `runId=${manifest.runId}`, "warn"),
 			);
 	}
 
@@ -428,7 +428,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 							appendEvent,
 							fullLoaded.manifest.eventsPath,
 						).catch((error) =>
-							logInternalError("crash-recovery.pid-dead.terminate", error, `runId=${fullLoaded.manifest.runId}`),
+							logInternalError("crash-recovery.pid-dead.terminate", error, `runId=${fullLoaded.manifest.runId}`, "warn"),
 						);
 					}
 				} catch {
@@ -482,7 +482,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 							appendEvent,
 							fullLoaded.manifest.eventsPath,
 						).catch((error) =>
-							logInternalError("crash-recovery.pid-dead.terminate", error, `runId=${fullLoaded.manifest.runId}`),
+							logInternalError("crash-recovery.pid-dead.terminate", error, `runId=${fullLoaded.manifest.runId}`, "warn"),
 						);
 					}
 				} catch {
@@ -543,7 +543,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}`),
+					logInternalError("crash-recovery.reconcile.terminate", error, `runId=${fresh.manifest.runId}`, "warn"),
 				);
 				appendEvent(fresh.manifest.eventsPath, {
 					type: "crew.run.reconciled_stale",

package/src/runtime/skill-instructions.ts

@@ -29,13 +29,9 @@ const DEFAULT_ROLE_SKILLS: Record<string, string[]> = {
 	critic: ["read-only-explorer", "multi-perspective-review"],
 	executor: ["state-mutation-locking", "safe-bash", "verification-before-done"],
 	reviewer: ["read-only-explorer", "multi-perspective-review"],
-	// SECURITY NOTE: The following skill names are trusted package-level skills.
-	// If a project has a skills/ directory containing subdirectories with these names,
-	// those project-level SKILL.md files will be FOUND FIRST (readSkillMarkdown checks
-	// project dir before package dir) and their content injected verbatim into prompts.
-	// The "Applicable Skills" block will add an untrusted-content warning for project skills,
-	// but be aware this is a potential supply-chain risk in multi-contributor projects.
 	"security-reviewer": ["secure-agent-orchestration-review", "ownership-session-security"],
+	// SECURITY NOTE: Package skills are checked FIRST (SEC-003). Project-level
+	// skills with the same name will NOT override the trusted package version.
 	"test-engineer": ["verification-before-done", "safe-bash"],
 	verifier: ["verification-before-done", "runtime-state-reader"],
 	writer: ["context-artifact-hygiene", "verification-before-done"],

package/src/runtime/task-runner/state-helpers.ts

@@ -32,6 +32,7 @@ export function persistSingleTaskUpdate(
 	updated: TeamTaskState,
 	checkpointPhase?: TaskCheckpointState["phase"],
 ): TeamTaskState[] {
+	const MAX_CAS_ATTEMPTS = 100;
 	let baseMtime = 0;
 	try {
 		baseMtime = fs.statSync(manifest.tasksPath).mtimeMs;
@@ -55,7 +56,7 @@ export function persistSingleTaskUpdate(
 
 	try {
 		return withRunLockSync(manifest, () => {
-			for (let attempt = 0; attempt < 100; attempt++) {
+			for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
 				// F4: persistSingleTaskUpdate now uses saveRunTasksCoalesced below
 				// (50ms debounce window). Read-modify-write loops are unsafe under
 				// coalescing — a parallel writer's buffered write is invisible to
@@ -93,8 +94,13 @@ export function persistSingleTaskUpdate(
 			}
 
 			if (merged === undefined) {
-				logInternalError("persistSingleTaskUpdate", new Error("failed to converge after 50 attempts"));
-				throw new Error("persistSingleTaskUpdate: failed to converge after 50 attempts");
+				logInternalError(
+					"persistSingleTaskUpdate",
+					new Error(`failed to converge after ${MAX_CAS_ATTEMPTS} attempts`),
+					undefined,
+					"error",
+				);
+				throw new Error(`persistSingleTaskUpdate: failed to converge after ${MAX_CAS_ATTEMPTS} attempts`);
 			}
 
 			try {
@@ -105,14 +111,14 @@ export function persistSingleTaskUpdate(
 				// writer's flushed-before-this-call state.
 				saveRunTasksCoalesced(manifest, merged);
 			} catch (err) {
-				logInternalError("persistSingleTaskUpdate", err);
+				logInternalError("persistSingleTaskUpdate", err, undefined, "error");
 				throw err;
 			}
 			return merged;
 		});
 	} catch (err) {
 		if (merged === undefined) {
-			logInternalError("persistSingleTaskUpdate", err);
+			logInternalError("persistSingleTaskUpdate", err, undefined, "error");
 		}
 		throw err;
 	}

package/src/runtime/team-runner.ts

@@ -2,13 +2,14 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig } from "../agents/agent-config.ts";
 import type { CrewLimitsConfig, CrewReliabilityConfig, CrewRuntimeConfig } from "../config/config.ts";
+import { CrewError, ErrorCode } from "../errors.ts";
 import { appendHookEvent, executeHook } from "../hooks/registry.ts";
 import { childCorrelation, withCorrelation } from "../observability/correlation.ts";
 import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { PluginRegistry } from "../plugins/plugin-registry.ts";
 import { NextJsPlugin, VitePlugin, VitestPlugin } from "../plugins/plugins/index.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
-import { appendEvent, appendEventAsync, appendEventBuffered, flushEventLogBuffer } from "../state/event-log.ts";
+import { appendEvent, appendEventAsync, appendEventBuffered, appendEventFireAndForget, flushEventLogBuffer } from "../state/event-log.ts";
 import { HealthStore } from "../state/health-store.ts";
 import { withRunLock } from "../state/locks.ts";
 import { loadRunManifestById, saveRunManifest, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/state-store.ts";
@@ -190,13 +191,19 @@ export function checkPerTaskBudget(
 
 function findStep(workflow: WorkflowConfig, task: TeamTaskState): WorkflowStep {
 	const step = workflow.steps.find((candidate) => candidate.id === task.stepId);
-	if (!step) throw new Error(`Workflow step '${task.stepId}' not found for task '${task.id}'.`);
+	if (!step)
+		throw new CrewError(ErrorCode.ResourceNotFound, `Workflow step '${task.stepId}' not found for task '${task.id}'.`).withContext(
+			`workflow step lookup (task=${task.id})`,
+		);
 	return step;
 }
 
 function findAgent(agents: AgentConfig[], task: TeamTaskState): AgentConfig {
 	const agent = agents.find((candidate) => candidate.name === task.agent);
-	if (!agent) throw new Error(`Agent '${task.agent}' not found for task '${task.id}'.`);
+	if (!agent)
+		throw new CrewError(ErrorCode.ResourceNotFound, `Agent '${task.agent}' not found for task '${task.id}'.`).withContext(
+			`agent lookup (task=${task.id})`,
+		);
 	return agent;
 }
 
@@ -704,6 +711,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 				"team-runner.goalAchievement.falseGreen",
 				new Error(gaApplied.manifest.goalAchievementNote ?? "false-green detected"),
 				`runId=${manifest.runId}`,
+				"error",
 			);
 		stopTeamHeartbeat();
 		resolveRunPromise(manifest.runId, result);
@@ -1300,7 +1308,9 @@ async function executeTeamRunCore(
 						};
 						if (failed) {
 							lastFailed = enriched;
-							throw new Error(failed.error ?? `Task ${task.id} failed.`);
+							throw new CrewError(ErrorCode.TaskNotFound, failed.error ?? `Task ${task.id} failed.`).withContext(
+								`retry evaluation (run=${manifest.runId})`,
+							);
 						}
 						input.metricRegistry?.histogram("crew.task.retry_count", "Retries per task", [0, 1, 2, 3, 5, 10]).observe(
 							{
@@ -1651,6 +1661,29 @@ async function executeTeamRunCore(
 	const waiting = tasks.find((task) => task.status === "waiting");
 	const running = tasks.find((task) => task.status === "running");
 	manifest = applyPolicy(manifest, tasks, input.limits);
+
+	// S02: Verify workflow-declared output files exist before marking completed
+	if (input.workflow?.steps) {
+		const missingOutputs: string[] = [];
+		for (const step of input.workflow.steps) {
+			if (step.output && typeof step.output === "string") {
+				const outputPath = path.join(manifest.artifactsRoot, step.output);
+				if (!fs.existsSync(outputPath)) {
+					missingOutputs.push(step.output);
+				}
+			}
+		}
+		if (missingOutputs.length > 0) {
+			// Emit warning event — run still completes normally to avoid hanging
+			appendEventFireAndForget(manifest.eventsPath, {
+				type: "run.deliverable_warning",
+				runId: manifest.runId,
+				message: `Missing workflow output files: ${missingOutputs.join(", ")}`,
+				data: { missingFiles: missingOutputs },
+			});
+		}
+	}
+
 	const effectiveness = evaluateRunEffectiveness({
 		manifest,
 		tasks,

package/src/state/atomic-write.ts

@@ -166,12 +166,12 @@ export function isSymlinkSafePath(filePath: string): boolean {
 // parent dirs of `.crew/state/runs/{runId}/` are stable within a run, so we
 // cache the ancestor-walk verdict keyed by `dirname(filePath)`.
 //
-// SECURITY: the *target file* itself is still checked every call (no cache).
-// Caching is per-dir at a short TTL. If a dir is mutated mid-window, the cache
-// is invalidated explicitly via `invalidateSymlinkSafeCache(dir)` from any
-// file-create / rename hook, plus a TTL failsafe. The cache is best-effort
-// speed-up — when in doubt the next call's statSync re-verifies.
-const SYMLINK_SAFE_TTL_MS = 30_000;
+// SECURITY: TTL-only invalidation. The `.crew/` state directory is trusted
+// (single-user, non-shared). Symlink attacks require write access to the state
+// dir, which would already compromise the system. The short TTL provides
+// defense-in-depth. The target file itself is still checked every call (no
+// cache) — when in doubt the next call's statSync re-verifies.
+const SYMLINK_SAFE_TTL_MS = 10_000;
 const SYMLINK_SAFE_MAX_ENTRIES = 128;
 // NOTE: This cache is process-local and assumes single-threaded access.
 // If worker-thread usage expands (e.g., worker-atomic-writer.ts), this cache
@@ -731,7 +731,7 @@ function flushOnePendingAtomicWrite(filePath: string): void {
 			pendingAtomicWrites.delete(filePath);
 		}
 	} catch (error) {
-		logInternalError("atomic-write.coalesced-flush", error, filePath);
+		logInternalError("atomic-write.coalesced-flush", error, filePath, "error");
 		// Issue 1 fix: set a fresh timer for failed entries before returning.
 		// This ensures failed entries are retried without waiting for another
 		// write to arrive. Only set timer if this entry is still current

package/src/state/state-store.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 import { DEFAULT_CACHE, DEFAULT_PATHS } from "../config/defaults.ts";
 import { errors } from "../errors.ts";
@@ -83,7 +84,7 @@ function genOf(stateRoot: string): number {
 	return manifestCacheGeneration.get(stateRoot) ?? 0;
 }
 
-const MANIFEST_CACHE_TTL_MS = 15 * 1000; // 15 seconds (FIX: increased from 5s for read-heavy workloads; 5s was too short causing unnecessary cache invalidation)
+const MANIFEST_CACHE_TTL_MS = 60 * 1000; // 60 seconds (FIX: increased from 15s for read-heavy workloads; render tick 160ms caused frequent misses)
 const LOAD_MANIFEST_RETRY_LIMIT = 5; // Configurable retry limit for mtime/size stability checks under contention
 const manifestCache = new Map<string, ManifestCacheEntry>();
 
@@ -475,7 +476,7 @@ export async function saveRunTasksAsync(manifest: TeamRunManifest, tasks: TeamTa
 	// FIX: Invalidate cache BEFORE atomic write to prevent stale cache serving.
 	invalidateRunCache(manifest.stateRoot);
 	try {
-		fs.statSync(manifest.stateRoot);
+		await fsp.access(manifest.stateRoot);
 	} catch {
 		return;
 	}
@@ -800,7 +801,12 @@ export async function loadRunManifestByIdAsync(
 		} else if (!validateRunManifestPaths(cwd, runId, cached.manifest, stateRoot, tasksPath)) {
 			manifestCache.delete(stateRoot);
 			return undefined;
-		} else if (!fs.existsSync(tasksPath)) {
+		} else if (
+			!(await fsp.access(tasksPath).then(
+				() => true,
+				() => false,
+			))
+		) {
 			// Tasks file was deleted after cache was populated — do not serve stale cache.
 			manifestCache.delete(stateRoot);
 			return undefined;

package/src/ui/run-dashboard.ts

@@ -28,6 +28,17 @@ import { applyStatusColor, colorizeStatusGlyphs, iconForStatus, type RunStatus }
 import type { CrewTheme } from "./theme-adapter.ts";
 import { asCrewTheme, subscribeThemeChange } from "./theme-adapter.ts";
 
+/** S05 — wrap a pane render in try/catch so a single pane crash does not bring down the whole dashboard. */
+function safeRenderPane(name: string, fn: () => string[]): string[] {
+	try {
+		return fn();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logInternalError("run-dashboard", new Error(`Dashboard pane '${name}' render failed: ${message}`));
+		return [`<error: ${name}>`];
+	}
+}
+
 interface DashboardComponent {
 	invalidate(): void;
 	render(width: number): string[];
@@ -615,20 +626,24 @@ export class RunDashboard implements DashboardComponent {
 						// Pane content (max 8 lines) — F-2: colorize embedded status glyphs.
 						const paneLines = snap
 							? this.activePane === "agents"
-								? renderAgentsPane(snap, this.options)
+								? safeRenderPane("agents", () => renderAgentsPane(snap, this.options))
 								: this.activePane === "progress"
-									? renderProgressPane(snap)
+									? safeRenderPane("progress", () => renderProgressPane(snap))
 									: this.activePane === "mailbox"
-										? renderMailboxPane(snap)
+										? safeRenderPane("mailbox", () => renderMailboxPane(snap))
 										: this.activePane === "health"
-											? renderHealthPane(snap, {
-													isForeground: !r.async,
-												})
+											? safeRenderPane("health", () =>
+													renderHealthPane(snap, {
+														isForeground: !r.async,
+													}),
+												)
 											: this.activePane === "metrics"
-												? renderMetricsPane(snap, {
-														registry: this.options.registry,
-													})
-												: renderTranscriptPane(snap)
+												? safeRenderPane("metrics", () =>
+														renderMetricsPane(snap, {
+															registry: this.options.registry,
+														}),
+													)
+												: safeRenderPane("transcript", () => renderTranscriptPane(snap))
 							: [...readAgentPreview(r, 4, this.options), ...readProgressPreview(r, 2)];
 						const filteredPane = paneLines.filter((l) => l && !l.includes("(none)") && l.trim() !== "");
 						if (filteredPane.length > 0) {

package/src/utils/internal-error.ts

@@ -1,5 +1,8 @@
-export function logInternalError(scope: string, error: unknown, details?: string): void {
-	if (!process.env.PI_TEAMS_DEBUG) return;
+export function logInternalError(scope: string, error: unknown, details?: string, severity?: "error" | "warn" | "debug"): void {
+	// "error" and "warn" always emit; "debug" (default) is gated behind PI_TEAMS_DEBUG
+	if (!severity || severity === "debug") {
+		if (!process.env.PI_TEAMS_DEBUG) return;
+	}
 	const message =
 		error instanceof Error ? error.message : typeof error === "object" && error !== null ? JSON.stringify(error) : String(error);
 	const suffix = details ? `: ${details}` : "";

package/src/workflows/cost-estimator.ts

@@ -0,0 +1,34 @@
+import type { WorkflowConfig } from "./workflow-config.ts";
+
+// Rough token estimates per role (input + output combined)
+const ROLE_TOKEN_ESTIMATES: Record<string, number> = {
+	explorer: 15000,
+	planner: 20000,
+	executor: 25000,
+	reviewer: 12000,
+	"security-reviewer": 12000,
+	"test-engineer": 15000,
+	analyst: 18000,
+	writer: 15000,
+	verifier: 10000,
+	critic: 12000,
+};
+
+// Rough cost per 1K tokens (USD) — using a mid-range model price
+const COST_PER_1K_TOKENS = 0.003;
+
+export interface CostEstimate {
+	totalTokens: number;
+	estimatedCostUSD: number;
+	perStep: Array<{ stepId: string; role: string; tokens: number }>;
+}
+
+export function estimateWorkflowCost(workflow: WorkflowConfig): CostEstimate {
+	const perStep = workflow.steps.map((step) => {
+		const tokens = ROLE_TOKEN_ESTIMATES[step.role] ?? 15000; // default 15K
+		return { stepId: step.id, role: step.role, tokens };
+	});
+	const totalTokens = perStep.reduce((sum, s) => sum + s.tokens, 0);
+	const estimatedCostUSD = (totalTokens / 1000) * COST_PER_1K_TOKENS;
+	return { totalTokens, estimatedCostUSD, perStep };
+}

package/src/workflows/validate-workflow.ts

@@ -18,6 +18,16 @@ export function validateWorkflowForTeam(workflow: WorkflowConfig, team: TeamConf
 		}
 	}
 
+	// Validate output field types
+	for (const step of workflow.steps) {
+		if (step.output !== undefined && step.output !== false && typeof step.output !== "string") {
+			errors.push(`Step '${step.id}' has invalid 'output' field: expected string or false, got ${typeof step.output}.`);
+		}
+		if (typeof step.output === "string" && step.output.trim() === "") {
+			errors.push(`Step '${step.id}' has empty 'output' string.`);
+		}
+	}
+
 	const visiting = new Set<string>();
 	const visited = new Set<string>();
 	const byId = new Map(workflow.steps.map((step) => [step.id, step]));