pi-crew 0.2.3 → 0.2.5

package/src/runtime/diagnostic-export.ts

@@ -1,102 +1,102 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import type { MetricRegistry } from "../observability/metric-registry.ts";
-import type { MetricSnapshot } from "../observability/metrics-primitives.ts";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { readCrewAgents } from "./crew-agent-records.ts";
-import { readEvents, type TeamEvent } from "../state/event-log.ts";
-import { loadRunManifestById } from "../state/state-store.ts";
-import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { summarizeHeartbeats, type HeartbeatSummary } from "../ui/heartbeat-aggregator.ts";
-import type { RunUiSnapshot } from "../ui/snapshot-types.ts";
-import { redactSecrets } from "../utils/redaction.ts";
-export { redactSecrets } from "../utils/redaction.ts";
-
-export interface DiagnosticReport {
-	schemaVersion?: number;
-	runId: string;
-	exportedAt: string;
-	manifest: TeamRunManifest;
-	tasks: TeamTaskState[];
-	recentEvents: TeamEvent[];
-	heartbeat: HeartbeatSummary;
-	agents: unknown[];
-	envRedacted: Record<string, string>;
-	metricsSnapshot?: MetricSnapshot[];
-}
-
-const SECRET_KEY_PATTERN = /(token|key|password|secret|credential|auth)/i;
-const ENV_DEBUG_ALLOWLIST = /^(PI_CREW_|PI_TEAMS_|PI_.*HOME|NODE_ENV|NODE_VERSION|OS|PROCESSOR|TERM|LANG|HOME|USERPROFILE|APPDATA|PLATFORM|ARCH|WIN32|DOCKER|CI|VERBOSE|DEBUG|NO_COLOR|FORCE_COLOR|NPM_CONFIG|npm_)/i;
-
-function envRedacted(): Record<string, string> {
-	const output: Record<string, string> = {};
-	for (const [key, value] of Object.entries(process.env)) {
-		if (SECRET_KEY_PATTERN.test(key)) output[key] = "***";
-		else if (typeof value === "string" && ENV_DEBUG_ALLOWLIST.test(key)) output[key] = value;
-		// All other env vars are omitted to prevent leaking sensitive paths or system topology.
-	}
-	return output;
-}
-
-function buildSnapshot(manifest: TeamRunManifest, tasks: TeamTaskState[]): RunUiSnapshot {
-	const agents = readCrewAgents(manifest);
-	return {
-		runId: manifest.runId,
-		cwd: manifest.cwd,
-		fetchedAt: Date.now(),
-		signature: `${manifest.runId}:${manifest.updatedAt}`,
-		manifest,
-		tasks,
-		agents,
-		progress: {
-			total: tasks.length,
-			completed: tasks.filter((task) => task.status === "completed").length,
-			running: tasks.filter((task) => task.status === "running").length,
-			failed: tasks.filter((task) => task.status === "failed").length,
-			queued: tasks.filter((task) => task.status === "queued").length,
-		},
-		usage: { tokensIn: 0, tokensOut: 0, toolUses: 0 },
-		mailbox: { inboxUnread: 0, outboxPending: 0, needsAttention: 0 },
-		recentEvents: [],
-		recentOutputLines: [],
-	};
-}
-
-export async function exportDiagnostic(ctx: Pick<ExtensionContext, "cwd">, runId: string, options: { registry?: MetricRegistry } = {}): Promise<{ path: string; report: DiagnosticReport }> {
-	const loaded = loadRunManifestById(ctx.cwd, runId);
-	if (!loaded) throw new Error(`Run '${runId}' not found.`);
-	const exportedAt = new Date().toISOString();
-	const safeTimestamp = exportedAt.replace(/[:.]/g, "-");
-	const recentEvents = readEvents(loaded.manifest.eventsPath).slice(-200);
-	const metricsSnapshot = options.registry?.snapshot();
-	const report: DiagnosticReport = {
-		...(metricsSnapshot ? { schemaVersion: 2 } : {}),
-		runId,
-		exportedAt,
-		manifest: redactSecrets(loaded.manifest) as TeamRunManifest,
-		tasks: redactSecrets(loaded.tasks) as TeamTaskState[],
-		recentEvents: redactSecrets(recentEvents) as TeamEvent[],
-		heartbeat: summarizeHeartbeats(buildSnapshot(loaded.manifest, loaded.tasks)),
-		agents: redactSecrets(readCrewAgents(loaded.manifest)) as unknown[],
-		envRedacted: envRedacted(),
-		...(metricsSnapshot ? { metricsSnapshot: redactSecrets(metricsSnapshot) as MetricSnapshot[] } : {}),
-	};
-	const dir = path.join(loaded.manifest.artifactsRoot, "diagnostic");
-	fs.mkdirSync(dir, { recursive: true });
-	const filePath = path.join(dir, `diagnostic-${safeTimestamp}.json`);
-	fs.writeFileSync(filePath, `${JSON.stringify(report, null, 2)}\n`, "utf-8");
-	return { path: filePath, report };
-}
-
-export function listRecentDiagnostic(dir: string, windowMs: number, now = Date.now()): string | undefined {
-	try {
-		if (!fs.existsSync(dir)) return undefined;
-		return fs.readdirSync(dir)
-			.filter((file) => file.startsWith("diagnostic-") && file.endsWith(".json"))
-			.map((file) => ({ file, mtimeMs: fs.statSync(path.join(dir, file)).mtimeMs }))
-			.filter((entry) => now - entry.mtimeMs < windowMs)
-			.sort((a, b) => b.mtimeMs - a.mtimeMs)[0]?.file;
-	} catch {
-		return undefined;
-	}
-}
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { MetricRegistry } from "../observability/metric-registry.ts";
+import type { MetricSnapshot } from "../observability/metrics-primitives.ts";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readCrewAgents } from "./crew-agent-records.ts";
+import { readEvents, type TeamEvent } from "../state/event-log.ts";
+import { loadRunManifestById } from "../state/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { summarizeHeartbeats, type HeartbeatSummary } from "../ui/heartbeat-aggregator.ts";
+import type { RunUiSnapshot } from "../ui/snapshot-types.ts";
+import { redactSecrets } from "../utils/redaction.ts";
+export { redactSecrets } from "../utils/redaction.ts";
+
+export interface DiagnosticReport {
+	schemaVersion?: number;
+	runId: string;
+	exportedAt: string;
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	recentEvents: TeamEvent[];
+	heartbeat: HeartbeatSummary;
+	agents: unknown[];
+	envRedacted: Record<string, string>;
+	metricsSnapshot?: MetricSnapshot[];
+}
+
+const SECRET_KEY_PATTERN = /(token|key|password|secret|credential|auth)/i;
+const ENV_DEBUG_ALLOWLIST = /^(PI_CREW_|PI_TEAMS_|PI_.*HOME|NODE_ENV|NODE_VERSION|OS|PROCESSOR|TERM|LANG|HOME|USERPROFILE|APPDATA|PLATFORM|ARCH|WIN32|DOCKER|CI|VERBOSE|DEBUG|NO_COLOR|FORCE_COLOR|NPM_CONFIG|npm_)/i;
+
+function envRedacted(): Record<string, string> {
+	const output: Record<string, string> = {};
+	for (const [key, value] of Object.entries(process.env)) {
+		if (SECRET_KEY_PATTERN.test(key)) output[key] = "***";
+		else if (typeof value === "string" && ENV_DEBUG_ALLOWLIST.test(key)) output[key] = value;
+		// All other env vars are omitted to prevent leaking sensitive paths or system topology.
+	}
+	return output;
+}
+
+function buildSnapshot(manifest: TeamRunManifest, tasks: TeamTaskState[]): RunUiSnapshot {
+	const agents = readCrewAgents(manifest);
+	return {
+		runId: manifest.runId,
+		cwd: manifest.cwd,
+		fetchedAt: Date.now(),
+		signature: `${manifest.runId}:${manifest.updatedAt}`,
+		manifest,
+		tasks,
+		agents,
+		progress: {
+			total: tasks.length,
+			completed: tasks.filter((task) => task.status === "completed").length,
+			running: tasks.filter((task) => task.status === "running").length,
+			failed: tasks.filter((task) => task.status === "failed").length,
+			queued: tasks.filter((task) => task.status === "queued").length,
+		},
+		usage: { tokensIn: 0, tokensOut: 0, toolUses: 0 },
+		mailbox: { inboxUnread: 0, outboxPending: 0, needsAttention: 0 },
+		recentEvents: [],
+		recentOutputLines: [],
+	};
+}
+
+export async function exportDiagnostic(ctx: Pick<ExtensionContext, "cwd">, runId: string, options: { registry?: MetricRegistry } = {}): Promise<{ path: string; report: DiagnosticReport }> {
+	const loaded = loadRunManifestById(ctx.cwd, runId);
+	if (!loaded) throw new Error(`Run '${runId}' not found.`);
+	const exportedAt = new Date().toISOString();
+	const safeTimestamp = exportedAt.replace(/[:.]/g, "-");
+	const recentEvents = readEvents(loaded.manifest.eventsPath).slice(-200);
+	const metricsSnapshot = options.registry?.snapshot();
+	const report: DiagnosticReport = {
+		...(metricsSnapshot ? { schemaVersion: 2 } : {}),
+		runId,
+		exportedAt,
+		manifest: redactSecrets(loaded.manifest) as TeamRunManifest,
+		tasks: redactSecrets(loaded.tasks) as TeamTaskState[],
+		recentEvents: redactSecrets(recentEvents) as TeamEvent[],
+		heartbeat: summarizeHeartbeats(buildSnapshot(loaded.manifest, loaded.tasks)),
+		agents: redactSecrets(readCrewAgents(loaded.manifest)) as unknown[],
+		envRedacted: envRedacted(),
+		...(metricsSnapshot ? { metricsSnapshot: redactSecrets(metricsSnapshot) as MetricSnapshot[] } : {}),
+	};
+	const dir = path.join(loaded.manifest.artifactsRoot, "diagnostic");
+	fs.mkdirSync(dir, { recursive: true });
+	const filePath = path.join(dir, `diagnostic-${safeTimestamp}.json`);
+	fs.writeFileSync(filePath, `${JSON.stringify(report, null, 2)}\n`, "utf-8");
+	return { path: filePath, report };
+}
+
+export function listRecentDiagnostic(dir: string, windowMs: number, now = Date.now()): string | undefined {
+	try {
+		if (!fs.existsSync(dir)) return undefined;
+		return fs.readdirSync(dir)
+			.filter((file) => file.startsWith("diagnostic-") && file.endsWith(".json"))
+			.map((file) => ({ file, mtimeMs: fs.statSync(path.join(dir, file)).mtimeMs }))
+			.filter((entry) => now - entry.mtimeMs < windowMs)
+			.sort((a, b) => b.mtimeMs - a.mtimeMs)[0]?.file;
+	} catch {
+		return undefined;
+	}
+}

package/src/runtime/direct-run.ts

@@ -1,35 +1,35 @@
-import type { AgentConfig } from "../agents/agent-config.ts";
-import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import type { TeamConfig } from "../teams/team-config.ts";
-import type { WorkflowConfig } from "../workflows/workflow-config.ts";
-
-export function isDirectRun(manifest: Pick<TeamRunManifest, "team" | "workflow">): boolean {
-	return manifest.workflow === "direct-agent";
-}
-
-export function directTeamAndWorkflowFromRun(manifest: TeamRunManifest, tasks: TeamTaskState[], agents: AgentConfig[]): { team: TeamConfig; workflow: WorkflowConfig } | undefined {
-	if (!isDirectRun(manifest)) return undefined;
-	const firstTask = tasks[0];
-	const agentName = firstTask?.agent ?? (manifest.team.replace(/^direct-/, "") || "executor");
-	const agent = agents.find((candidate) => candidate.name === agentName);
-	const role = firstTask?.role ?? "agent";
-	const stepId = firstTask?.stepId ?? "01_agent";
-	return {
-		team: {
-			name: manifest.team,
-			description: `Direct subagent run for ${agentName}`,
-			source: "builtin",
-			filePath: "<generated>",
-			roles: [{ name: role, agent: agentName, description: agent?.description }],
-			defaultWorkflow: "direct-agent",
-			workspaceMode: manifest.workspaceMode,
-		},
-		workflow: {
-			name: manifest.workflow ?? "direct-agent",
-			description: `Direct task for ${agentName}`,
-			source: "builtin",
-			filePath: "<generated>",
-			steps: [{ id: stepId, role, task: "{goal}", model: firstTask?.model }],
-		},
-	};
-}
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { TeamConfig } from "../teams/team-config.ts";
+import type { WorkflowConfig } from "../workflows/workflow-config.ts";
+
+export function isDirectRun(manifest: Pick<TeamRunManifest, "team" | "workflow">): boolean {
+	return manifest.workflow === "direct-agent";
+}
+
+export function directTeamAndWorkflowFromRun(manifest: TeamRunManifest, tasks: TeamTaskState[], agents: AgentConfig[]): { team: TeamConfig; workflow: WorkflowConfig } | undefined {
+	if (!isDirectRun(manifest)) return undefined;
+	const firstTask = tasks[0];
+	const agentName = firstTask?.agent ?? (manifest.team.replace(/^direct-/, "") || "executor");
+	const agent = agents.find((candidate) => candidate.name === agentName);
+	const role = firstTask?.role ?? "agent";
+	const stepId = firstTask?.stepId ?? "01_agent";
+	return {
+		team: {
+			name: manifest.team,
+			description: `Direct subagent run for ${agentName}`,
+			source: "builtin",
+			filePath: "<generated>",
+			roles: [{ name: role, agent: agentName, description: agent?.description }],
+			defaultWorkflow: "direct-agent",
+			workspaceMode: manifest.workspaceMode,
+		},
+		workflow: {
+			name: manifest.workflow ?? "direct-agent",
+			description: `Direct task for ${agentName}`,
+			source: "builtin",
+			filePath: "<generated>",
+			steps: [{ id: stepId, role, task: "{goal}", model: firstTask?.model }],
+		},
+	};
+}

package/src/runtime/effectiveness.ts

@@ -1,81 +1,82 @@
-import { permissionForRole } from "./role-permission.ts";
-import type { CrewRuntimeConfig } from "../config/config.ts";
-import type { PolicyDecision, TeamRunManifest, TeamTaskState } from "../state/types.ts";
-
-export type EffectivenessGuardMode = "off" | "warn" | "block" | "fail";
-export type WorkerExecutionState = "enabled" | "disabled/scaffold";
-export type RunEffectivenessSeverity = "ok" | "warning" | "blocked" | "failed";
-
-export interface RunEffectivenessSummary {
-	completed: number;
-	observable: number;
-	noObservedWorkTaskIds: string[];
-	needsAttentionTaskIds: string[];
-	workerExecution: WorkerExecutionState;
-	guardMode: EffectivenessGuardMode;
-	severity: RunEffectivenessSeverity;
-}
-
-export function taskHasObservableWorkerActivity(task: TeamTaskState): boolean {
-	return Boolean(
-		(task.agentProgress?.toolCount ?? 0) > 0
-		|| task.usage
-		|| task.transcriptArtifact
-		|| task.modelAttempts?.some((attempt) => attempt.success)
-		|| task.jsonEvents,
-	);
-}
-
-export function resolveEffectivenessGuardMode(runtimeConfig: CrewRuntimeConfig | undefined, manifest?: TeamRunManifest): EffectivenessGuardMode {
-	const configured = runtimeConfig?.effectivenessGuard;
-	if (configured === "off" || configured === "warn" || configured === "block" || configured === "fail") return configured;
-	if (manifest?.runtimeResolution?.safety === "explicit_dry_run") return "off";
-	return "warn";
-}
-
-export function evaluateRunEffectiveness(input: { manifest?: TeamRunManifest; tasks: TeamTaskState[]; executeWorkers: boolean; runtimeConfig?: CrewRuntimeConfig }): RunEffectivenessSummary {
-	const completedTasks = input.tasks.filter((task) => task.status === "completed");
-	const noObservedWorkTasks = completedTasks.filter((task) => !taskHasObservableWorkerActivity(task));
-	const needsAttentionTasks = input.tasks.filter((task) => task.agentProgress?.activityState === "needs_attention");
-	const workerExecution: WorkerExecutionState = input.executeWorkers ? "enabled" : "disabled/scaffold";
-	const guardMode = resolveEffectivenessGuardMode(input.runtimeConfig, input.manifest);
-	const observable = Math.max(0, completedTasks.length - noObservedWorkTasks.length - needsAttentionTasks.length);
-	let severity: RunEffectivenessSeverity = "ok";
-	if (input.executeWorkers && guardMode !== "off" && noObservedWorkTasks.length > 0) {
-		severity = guardMode === "fail" ? "failed" : guardMode === "block" ? "blocked" : "warning";
-		// P0.1: default warn escalates to blocked for mutating-role tasks without observed work
-		if (severity === "warning" && noObservedWorkTasks.some((task) => permissionForRole(task.role) !== "read_only")) {
-			severity = "blocked";
-		}
-	}
-	return {
-		completed: completedTasks.length,
-		observable,
-		noObservedWorkTaskIds: noObservedWorkTasks.map((task) => task.id),
-		needsAttentionTaskIds: needsAttentionTasks.map((task) => task.id),
-		workerExecution,
-		guardMode,
-		severity,
-	};
-}
-
-export function formatRunEffectivenessLines(summary: RunEffectivenessSummary): string[] {
-	return [
-		`Score: ${summary.observable}/${Math.max(1, summary.completed)} completed task(s) with observable worker activity`,
-		`Worker execution: ${summary.workerExecution}`,
-		`Guard: ${summary.guardMode} severity=${summary.severity}`,
-		`No observable worker activity: ${summary.noObservedWorkTaskIds.length ? summary.noObservedWorkTaskIds.join(", ") : "none"}`,
-		`Needs attention: ${summary.needsAttentionTaskIds.length ? summary.needsAttentionTaskIds.join(", ") : "none"}`,
-	];
-}
-
-export function effectivenessPolicyDecision(summary: RunEffectivenessSummary): PolicyDecision | undefined {
-	if (summary.severity !== "warning" && summary.severity !== "blocked" && summary.severity !== "failed") return undefined;
-	const action = summary.severity === "failed" ? "fail" : summary.severity === "blocked" ? "block" : "notify";
-	return {
-		action,
-		reason: "ineffective_worker",
-		message: `Run effectiveness guard ${summary.guardMode}: no observable worker activity for ${summary.noObservedWorkTaskIds.join(", ")}.`,
-		createdAt: new Date().toISOString(),
-	};
-}
+import { permissionForRole } from "./role-permission.ts";
+import type { CrewRuntimeConfig } from "../config/config.ts";
+import type { PolicyDecision, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+
+export type EffectivenessGuardMode = "off" | "warn" | "block" | "fail";
+export type WorkerExecutionState = "enabled" | "disabled/scaffold";
+export type RunEffectivenessSeverity = "ok" | "warning" | "blocked" | "failed";
+
+export interface RunEffectivenessSummary {
+	completed: number;
+	observable: number;
+	noObservedWorkTaskIds: string[];
+	needsAttentionTaskIds: string[];
+	workerExecution: WorkerExecutionState;
+	guardMode: EffectivenessGuardMode;
+	severity: RunEffectivenessSeverity;
+}
+
+export function taskHasObservableWorkerActivity(task: TeamTaskState): boolean {
+	return Boolean(
+		(task.agentProgress?.toolCount ?? 0) > 0
+		|| task.usage
+		|| task.transcriptArtifact
+		|| task.modelAttempts?.some((attempt) => attempt.success)
+		|| task.jsonEvents,
+	);
+}
+
+export function resolveEffectivenessGuardMode(runtimeConfig: CrewRuntimeConfig | undefined, manifest?: TeamRunManifest): EffectivenessGuardMode {
+	const configured = runtimeConfig?.effectivenessGuard;
+	if (configured === "off" || configured === "warn" || configured === "block" || configured === "fail") return configured;
+	if (manifest?.runtimeResolution?.safety === "explicit_dry_run") return "off";
+	return "warn";
+}
+
+export function evaluateRunEffectiveness(input: { manifest?: TeamRunManifest; tasks: TeamTaskState[]; executeWorkers: boolean; runtimeConfig?: CrewRuntimeConfig }): RunEffectivenessSummary {
+	const completedTasks = input.tasks.filter((task) => task.status === "completed");
+	const noObservedWorkTasks = completedTasks.filter((task) => !taskHasObservableWorkerActivity(task));
+	const needsAttentionTasks = input.tasks.filter((task) => task.agentProgress?.activityState === "needs_attention");
+	const workerExecution: WorkerExecutionState = input.executeWorkers ? "enabled" : "disabled/scaffold";
+	const guardMode = resolveEffectivenessGuardMode(input.runtimeConfig, input.manifest);
+	const completedNeedsAttention = needsAttentionTasks.filter((task) => task.status === "completed").length;
+	const observable = Math.max(0, completedTasks.length - noObservedWorkTasks.length - completedNeedsAttention);
+	let severity: RunEffectivenessSeverity = "ok";
+	if (input.executeWorkers && guardMode !== "off" && noObservedWorkTasks.length > 0) {
+		severity = guardMode === "fail" ? "failed" : guardMode === "block" ? "blocked" : "warning";
+		// P0.1: default warn escalates to blocked for mutating-role tasks without observed work
+		if (severity === "warning" && noObservedWorkTasks.some((task) => permissionForRole(task.role) !== "read_only")) {
+			severity = "blocked";
+		}
+	}
+	return {
+		completed: completedTasks.length,
+		observable,
+		noObservedWorkTaskIds: noObservedWorkTasks.map((task) => task.id),
+		needsAttentionTaskIds: needsAttentionTasks.map((task) => task.id),
+		workerExecution,
+		guardMode,
+		severity,
+	};
+}
+
+export function formatRunEffectivenessLines(summary: RunEffectivenessSummary): string[] {
+	return [
+		`Score: ${summary.observable}/${Math.max(1, summary.completed)} completed task(s) with observable worker activity`,
+		`Worker execution: ${summary.workerExecution}`,
+		`Guard: ${summary.guardMode} severity=${summary.severity}`,
+		`No observable worker activity: ${summary.noObservedWorkTaskIds.length ? summary.noObservedWorkTaskIds.join(", ") : "none"}`,
+		`Needs attention: ${summary.needsAttentionTaskIds.length ? summary.needsAttentionTaskIds.join(", ") : "none"}`,
+	];
+}
+
+export function effectivenessPolicyDecision(summary: RunEffectivenessSummary): PolicyDecision | undefined {
+	if (summary.severity !== "warning" && summary.severity !== "blocked" && summary.severity !== "failed") return undefined;
+	const action = summary.severity === "failed" ? "fail" : summary.severity === "blocked" ? "block" : "notify";
+	return {
+		action,
+		reason: "ineffective_worker",
+		message: `Run effectiveness guard ${summary.guardMode}: no observable worker activity for ${summary.noObservedWorkTaskIds.join(", ")}.`,
+		createdAt: new Date().toISOString(),
+	};
+}

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

@@ -0,0 +1,166 @@
+/**
+ * crew-errors.ts — Typed error sentinels for pi-crew operations.
+ *
+ * Based on oh-my-pi pattern from compaction/errors.ts.
+ * Uses `instanceof` discrimination instead of string matching.
+ *
+ * NOTE: Constructor parameters are explicit properties (not TypeScript
+ * parameter properties) for strip-types compatibility.
+ *
+ * The `name` property is not set on instances because JavaScript's `name`
+ * on functions is special and can't be overridden. Use `instanceof` checks
+ * or the `code` property for discrimination.
+ */
+
+/** Base class for all pi-crew errors. */
+export abstract class CrewError extends Error {
+	abstract readonly code: string;
+
+	/** Returns the class name. Use `instanceof` for discrimination. */
+toString(): string {
+		return `[${this.constructor.name}] ${this.message}`;
+	}
+}
+
+/** Raised when a crew run is explicitly cancelled by user or API. */
+export class CrewCancelledError extends CrewError {
+	readonly code = "CREW_CANCELLED";
+	constructor(message = "Crew run cancelled") {
+		super(message);
+	}
+}
+
+/** Raised when a crew run exceeds its configured maximum duration. */
+export class CrewTimeoutError extends CrewError {
+	readonly code = "CREW_TIMEOUT";
+	readonly maxDurationMs: number;
+	constructor(maxDurationMs: number, message?: string) {
+		super(message ?? `Crew run exceeded timeout of ${maxDurationMs}ms`);
+		this.maxDurationMs = maxDurationMs;
+	}
+}
+
+/**
+ * Raised when an individual agent in a crew goes deadletter — i.e. it
+ * encountered an unrecoverable error that blocks its task from completing.
+ * Common causes: crash, OOM, unhandled exception in tool execution.
+ */
+export class CrewDeadletterError extends CrewError {
+	readonly code = "CREW_DEADLETTER";
+	readonly agentId: string;
+	readonly reason: string;
+	constructor(agentId: string, reason: string, message?: string) {
+		super(message ?? `Agent ${agentId} deadlettered: ${reason}`);
+		this.agentId = agentId;
+		this.reason = reason;
+	}
+}
+
+/** Raised when a crew run is aborted — operator Esc, SIGINT, or similar. */
+export class CrewAbortError extends CrewError {
+	readonly code = "CREW_ABORT";
+	constructor(message = "Crew run aborted") {
+		super(message);
+	}
+}
+
+/** Raised when a manifest or task file is malformed or missing required fields. */
+export class CrewManifestError extends CrewError {
+	readonly code = "CREW_MANIFEST_ERROR";
+	readonly runId?: string;
+	readonly taskId?: string;
+	constructor(message: string, runId?: string, taskId?: string) {
+		super(message);
+		this.runId = runId;
+		this.taskId = taskId;
+	}
+}
+
+/** Raised when a lock cannot be acquired or is held by a stale process. */
+export class CrewLockError extends CrewError {
+	readonly code = "CREW_LOCK_ERROR";
+	readonly lockPath?: string;
+	constructor(message: string, lockPath?: string) {
+		super(message);
+		this.lockPath = lockPath;
+	}
+}
+
+/** Raised when an agent exceeds its turn limit. */
+export class CrewTurnLimitError extends CrewError {
+	readonly code = "CREW_TURN_LIMIT";
+	readonly agentId: string;
+	readonly maxTurns: number;
+	constructor(agentId: string, maxTurns: number) {
+		super(`Agent ${agentId} exceeded turn limit of ${maxTurns}`);
+		this.agentId = agentId;
+		this.maxTurns = maxTurns;
+	}
+}
+
+/** Raised when a workflow step gate condition is not met. */
+export class CrewGateError extends CrewError {
+	readonly code = "CREW_GATE_ERROR";
+	readonly gateName: string;
+	constructor(gateName: string, message: string) {
+		super(message);
+		this.gateName = gateName;
+	}
+}
+
+/** Raised when an agent session fails to initialize (e.g. model not found). */
+export class CrewSessionError extends CrewError {
+	readonly code = "CREW_SESSION_ERROR";
+	readonly agentId?: string;
+	constructor(message: string, agentId?: string) {
+		super(message);
+		this.agentId = agentId;
+	}
+}
+
+/**
+ * Outcome of a crew run attempt.
+ * Used by RunTracker and health monitoring for outcome classification.
+ */
+export type CrewRunOutcome =
+	| "ok"       // Completed successfully
+	| "cancelled" // Explicitly cancelled by user or API
+	| "deadletter" // Agent encountered unrecoverable error
+	| "failed"   // Workflow step failed (gate error, etc.)
+	| "timeout"  // Exceeded max duration
+	| "aborted"; // Operator interrupt (Esc, SIGINT)
+
+/**
+ * Classify a thrown error into a CrewRunOutcome.
+ * Useful in catch blocks that need to determine run outcome.
+ */
+export function classifyError(error: unknown): CrewRunOutcome {
+	if (error instanceof CrewCancelledError) return "cancelled";
+	if (error instanceof CrewTimeoutError) return "timeout";
+	if (error instanceof CrewDeadletterError) return "deadletter";
+	if (error instanceof CrewAbortError) return "aborted";
+	if (error instanceof CrewGateError) return "failed";
+	if (error instanceof CrewError) return "failed";
+	// Unknown errors → failed
+	return "failed";
+}
+
+/**
+ * Check if an error indicates the run was intentionally interrupted
+ * (cancelled, aborted, or timed out) vs a genuine failure.
+ */
+export function isInterruptError(error: unknown): boolean {
+	return error instanceof CrewCancelledError
+		|| error instanceof CrewAbortError
+		|| error instanceof CrewTimeoutError;
+}
+
+/**
+ * Check if an error indicates the run failed due to agent malfunction
+ * rather than workflow logic or user action.
+ */
+export function isAgentError(error: unknown): boolean {
+	return error instanceof CrewDeadletterError
+		|| error instanceof CrewTurnLimitError
+		|| error instanceof CrewSessionError;
+}