pi-crew 0.2.2 → 0.2.4

package/src/runtime/auto-resume.ts

@@ -1,100 +1,100 @@
-/**
- * Auto-resume controller with settle window — prevents premature context injection
- * by waiting for Pi's setTimeout(0) + setTimeout(100) to drain before resuming.
- *
- * Distilled from pi-autoresearch's auto-resume / settle-window pattern.
- */
-
-/** Time to wait before auto-resuming (ms). Outlasts Pi's setTimeout(0) + setTimeout(100). */
-export const SETTLE_WINDOW_MS = 800;
-
-/** Maximum number of auto-resume turns before forcing a stop. */
-export const MAX_AUTORESUME_TURNS = 20;
-
-/**
- * Controller for scheduling auto-resume actions with a settle window.
- *
- * The settle window ensures that pending async operations (e.g., Pi's
- * internal setTimeout(0) and setTimeout(100) callbacks) have completed
- * before the resume callback fires.
- */
-export class AutoResumeController {
-	private timerId: ReturnType<typeof setTimeout> | null = null;
-	private turnCount = 0;
-	private cancelled = false;
-
-	/**
-	 * Get the current auto-resume turn count.
-	 */
-	get currentTurnCount(): number {
-		return this.turnCount;
-	}
-
-	/**
-	 * Get the maximum allowed auto-resume turns.
-	 */
-	get maxTurns(): number {
-		return MAX_AUTORESUME_TURNS;
-	}
-
-	/**
-	 * Schedule an auto-resume callback after the settle window elapses.
-	 *
-	 * If a resume is already pending, it is cancelled first (debounce behavior).
-	 * If the turn limit has been reached, the callback is not scheduled.
-	 *
-	 * @param message - Description of why the resume is being scheduled
-	 * @param callback - Function to call after the settle window
-	 */
-	scheduleResume(message: string, callback: () => void): void {
-		// Cancel any existing pending resume
-		this.cancelResume();
-
-		// Enforce turn limit
-		if (this.turnCount >= MAX_AUTORESUME_TURNS) {
-			return;
-		}
-
-		this.cancelled = false;
-		this.turnCount++;
-
-		this.timerId = setTimeout(() => {
-			if (!this.cancelled) {
-				this.timerId = null;
-				callback();
-			}
-		}, SETTLE_WINDOW_MS);
-
-		// Prevent the timer from keeping the process alive
-		if (this.timerId && typeof this.timerId === "object" && "unref" in this.timerId) {
-			this.timerId.unref();
-		}
-	}
-
-	/**
-	 * Cancel any pending auto-resume.
-	 */
-	cancelResume(): void {
-		if (this.timerId !== null) {
-			clearTimeout(this.timerId);
-			this.timerId = null;
-		}
-		this.cancelled = true;
-	}
-
-	/**
-	 * Check whether an auto-resume is currently pending.
-	 */
-	hasPendingResume(): boolean {
-		return this.timerId !== null;
-	}
-
-	/**
-	 * Reset the turn counter. Called when a new agent starts processing
-	 * to allow a fresh set of auto-resume turns.
-	 */
-	resetTurnCount(): void {
-		this.turnCount = 0;
-		this.cancelled = false;
-	}
-}
+/**
+ * Auto-resume controller with settle window — prevents premature context injection
+ * by waiting for Pi's setTimeout(0) + setTimeout(100) to drain before resuming.
+ *
+ * Distilled from pi-autoresearch's auto-resume / settle-window pattern.
+ */
+
+/** Time to wait before auto-resuming (ms). Outlasts Pi's setTimeout(0) + setTimeout(100). */
+export const SETTLE_WINDOW_MS = 800;
+
+/** Maximum number of auto-resume turns before forcing a stop. */
+export const MAX_AUTORESUME_TURNS = 20;
+
+/**
+ * Controller for scheduling auto-resume actions with a settle window.
+ *
+ * The settle window ensures that pending async operations (e.g., Pi's
+ * internal setTimeout(0) and setTimeout(100) callbacks) have completed
+ * before the resume callback fires.
+ */
+export class AutoResumeController {
+	private timerId: ReturnType<typeof setTimeout> | null = null;
+	private turnCount = 0;
+	private cancelled = false;
+
+	/**
+	 * Get the current auto-resume turn count.
+	 */
+	get currentTurnCount(): number {
+		return this.turnCount;
+	}
+
+	/**
+	 * Get the maximum allowed auto-resume turns.
+	 */
+	get maxTurns(): number {
+		return MAX_AUTORESUME_TURNS;
+	}
+
+	/**
+	 * Schedule an auto-resume callback after the settle window elapses.
+	 *
+	 * If a resume is already pending, it is cancelled first (debounce behavior).
+	 * If the turn limit has been reached, the callback is not scheduled.
+	 *
+	 * @param message - Description of why the resume is being scheduled
+	 * @param callback - Function to call after the settle window
+	 */
+	scheduleResume(message: string, callback: () => void): void {
+		// Cancel any existing pending resume
+		this.cancelResume();
+
+		// Enforce turn limit
+		if (this.turnCount >= MAX_AUTORESUME_TURNS) {
+			return;
+		}
+
+		this.cancelled = false;
+		this.turnCount++;
+
+		this.timerId = setTimeout(() => {
+			if (!this.cancelled) {
+				this.timerId = null;
+				callback();
+			}
+		}, SETTLE_WINDOW_MS);
+
+		// Prevent the timer from keeping the process alive
+		if (this.timerId && typeof this.timerId === "object" && "unref" in this.timerId) {
+			this.timerId.unref();
+		}
+	}
+
+	/**
+	 * Cancel any pending auto-resume.
+	 */
+	cancelResume(): void {
+		if (this.timerId !== null) {
+			clearTimeout(this.timerId);
+			this.timerId = null;
+		}
+		this.cancelled = true;
+	}
+
+	/**
+	 * Check whether an auto-resume is currently pending.
+	 */
+	hasPendingResume(): boolean {
+		return this.timerId !== null;
+	}
+
+	/**
+	 * Reset the turn counter. Called when a new agent starts processing
+	 * to allow a fresh set of auto-resume turns.
+	 */
+	resetTurnCount(): void {
+		this.turnCount = 0;
+		this.cancelled = false;
+	}
+}

package/src/runtime/background-runner.ts

@@ -1,88 +1,122 @@
-import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
-import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
-import { appendEvent } from "../state/event-log.ts";
-import { loadRunManifestById, saveRunManifest, updateRunStatus } from "../state/state-store.ts";
-import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
-import { loadConfig } from "../config/config.ts";
-// Heavy runtime — lazy-loaded to avoid pulling team-runner into background-runner
-// at module load time. Only needed when a background run actually starts.
-import type { executeTeamRun as ExecuteTeamRunFn } from "./team-runner.ts";
-let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
-async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
-	if (!_cachedExecuteTeamRun) {
-		const mod = await import("./team-runner.ts");
-		_cachedExecuteTeamRun = mod.executeTeamRun;
-	}
-	return _cachedExecuteTeamRun(...args);
-}
-import { resolveCrewRuntime, runtimeResolutionState } from "./runtime-resolver.ts";
-import { directTeamAndWorkflowFromRun } from "./direct-run.ts";
-import { expandParallelResearchWorkflow } from "./parallel-research.ts";
-import { writeAsyncStartMarker } from "./async-marker.ts";
-import { startParentGuard, stopParentGuard } from "./parent-guard.ts";
-
-/**
- * Remove macOS malloc-stack-logging vars that get inherited by child shells.
- * Without this, every subprocess prints "MallocStackLogging: can't turn off..." to stderr.
- */
-function scrubProcessEnv(): void {
-	delete process.env.MallocStackLogging;
-	delete process.env.MallocStackLoggingNoCompact;
-}
-
-function argValue(name: string): string | undefined {
-	const index = process.argv.indexOf(name);
-	if (index === -1) return undefined;
-	return process.argv[index + 1];
-}
-
-async function main(): Promise<void> {
-	// Scrub macOS malloc vars BEFORE anything else — must be clean for all child processes
-	scrubProcessEnv();
-
-	// Start parent guard FIRST — if parent is already dead, exit immediately
-	const parentPid = Number(process.env.PI_CREW_PARENT_PID);
-	if (parentPid > 0) startParentGuard(parentPid);
-
-	const cwd = argValue("--cwd");
-	const runId = argValue("--run-id");
-	if (!cwd || !runId) throw new Error("Usage: background-runner.ts --cwd <cwd> --run-id <runId>");
-
-	const loaded = loadRunManifestById(cwd, runId);
-	if (!loaded) throw new Error(`Run '${runId}' not found.`);
-	let { manifest, tasks } = loaded;
-	appendEvent(manifest.eventsPath, { type: "async.started", runId: manifest.runId, data: { pid: process.pid } });
-	writeAsyncStartMarker(manifest, { pid: process.pid, startedAt: new Date().toISOString() });
-
-	try {
-		const agents = allAgents(discoverAgents(cwd));
-		const direct = directTeamAndWorkflowFromRun(manifest, tasks, agents);
-		const team = direct?.team ?? allTeams(discoverTeams(cwd)).find((candidate) => candidate.name === manifest.team);
-		if (!team) throw new Error(`Team '${manifest.team}' not found.`);
-		const baseWorkflow = direct?.workflow ?? allWorkflows(discoverWorkflows(cwd)).find((candidate) => candidate.name === manifest.workflow);
-		if (!baseWorkflow) throw new Error(`Workflow '${manifest.workflow ?? ""}' not found.`);
-		const workflow = expandParallelResearchWorkflow(baseWorkflow, cwd);
-		const loadedConfig = loadConfig(cwd);
-		const runConfig = manifest.runConfig && typeof manifest.runConfig === "object" && !Array.isArray(manifest.runConfig) ? manifest.runConfig as typeof loadedConfig.config : loadedConfig.config;
-		const runtime = manifest.runtimeResolution ? { kind: manifest.runtimeResolution.kind, requestedMode: manifest.runtimeResolution.requestedMode, available: manifest.runtimeResolution.available, fallback: manifest.runtimeResolution.fallback, steer: manifest.runtimeResolution.kind === "live-session", resume: manifest.runtimeResolution.kind === "live-session", liveToolActivity: manifest.runtimeResolution.kind === "live-session", transcript: manifest.runtimeResolution.kind !== "scaffold", reason: manifest.runtimeResolution.reason, safety: manifest.runtimeResolution.safety } : await resolveCrewRuntime(runConfig);
-		const runtimeResolution = manifest.runtimeResolution ?? runtimeResolutionState(runtime);
-		manifest = { ...manifest, runtimeResolution, runConfig, updatedAt: new Date().toISOString() };
-		saveRunManifest(manifest);
-		appendEvent(manifest.eventsPath, { type: "runtime.resolved", runId: manifest.runId, message: `Runtime resolved: ${runtime.kind} safety=${runtime.safety}`, data: { runtimeResolution, async: true } });
-		if (runtime.safety === "blocked") throw new Error(runtime.reason ?? "Child worker execution is disabled; refusing to create no-op scaffold subagents.");
-		const executeWorkers = runtime.kind !== "scaffold";
-		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers, limits: runConfig.limits, runtime, runtimeConfig: runConfig.runtime, skillOverride: manifest.skillOverride, reliability: runConfig.reliability });
-		manifest = result.manifest;
-		tasks = result.tasks;
-		appendEvent(manifest.eventsPath, { type: "async.completed", runId: manifest.runId, data: { status: manifest.status, tasks: tasks.length } });
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		manifest = updateRunStatus(manifest, "failed", message);
-		appendEvent(manifest.eventsPath, { type: "async.failed", runId: manifest.runId, message });
-		process.exitCode = 1;
-	} finally {
-		stopParentGuard();
-	}
-}
-
-await main();
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
+import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { loadRunManifestById, saveRunManifest, updateRunStatus } from "../state/state-store.ts";
+import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
+import { loadConfig } from "../config/config.ts";
+// Heavy runtime — lazy-loaded to avoid pulling team-runner into background-runner
+// at module load time. Only needed when a background run actually starts.
+import type { executeTeamRun as ExecuteTeamRunFn } from "./team-runner.ts";
+let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
+async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
+	if (!_cachedExecuteTeamRun) {
+		// LAZY: avoid pulling team-runner into background-runner at module load time.
+		const mod = await import("./team-runner.ts");
+		_cachedExecuteTeamRun = mod.executeTeamRun;
+	}
+	return _cachedExecuteTeamRun(...args);
+}
+import { resolveCrewRuntime, runtimeResolutionState } from "./runtime-resolver.ts";
+import { directTeamAndWorkflowFromRun } from "./direct-run.ts";
+import { expandParallelResearchWorkflow } from "./parallel-research.ts";
+import { writeAsyncStartMarker } from "./async-marker.ts";
+import { startParentGuard, stopParentGuard } from "./parent-guard.ts";
+
+/**
+ * Remove macOS malloc-stack-logging vars that get inherited by child shells.
+ * Without this, every subprocess prints "MallocStackLogging: can't turn off..." to stderr.
+ */
+function scrubProcessEnv(): void {
+	delete process.env.MallocStackLogging;
+	delete process.env.MallocStackLoggingNoCompact;
+}
+
+function argValue(name: string): string | undefined {
+	const index = process.argv.indexOf(name);
+	if (index === -1) return undefined;
+	return process.argv[index + 1];
+}
+
+function startInterruptGuard(manifest: { runId: string; stateRoot: string; eventsPath: string }): () => void {
+	const controlPath = path.join(manifest.stateRoot, "foreground-control.json");
+	const interval = setInterval(() => {
+		try {
+			if (!fs.existsSync(controlPath)) return;
+			const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: Array<{ type: string; acknowledged?: boolean }> };
+			const last = parsed.requests?.at(-1);
+			if (last?.type === "interrupt" && last?.acknowledged !== true) {
+				appendEvent(manifest.eventsPath, { type: "async.interrupt_detected", runId: manifest.runId, message: "Background runner detected foreground interrupt request — exiting." });
+				process.exit(130);
+			}
+		} catch {
+			/* ignore read/parse errors */
+		}
+	}, 3_000);
+	interval.unref();
+	return () => clearInterval(interval);
+}
+
+async function main(): Promise<void> {
+	// Scrub macOS malloc vars BEFORE anything else — must be clean for all child processes
+	scrubProcessEnv();
+
+	// Start parent guard FIRST — if parent is already dead, exit immediately
+	const parentPid = Number(process.env.PI_CREW_PARENT_PID);
+	if (parentPid > 0) startParentGuard(parentPid);
+
+	const cwd = argValue("--cwd");
+	const runId = argValue("--run-id");
+	if (!cwd || !runId) throw new Error("Usage: background-runner.ts --cwd <cwd> --run-id <runId>");
+
+	const loaded = loadRunManifestById(cwd, runId);
+	if (!loaded) throw new Error(`Run '${runId}' not found.`);
+	let { manifest, tasks } = loaded;
+	appendEvent(manifest.eventsPath, { type: "async.started", runId: manifest.runId, data: { pid: process.pid } });
+	writeAsyncStartMarker(manifest, { pid: process.pid, startedAt: new Date().toISOString() });
+	const stopInterruptGuard = startInterruptGuard(manifest);
+
+	try {
+		const agents = allAgents(discoverAgents(cwd));
+		const direct = directTeamAndWorkflowFromRun(manifest, tasks, agents);
+		const team = direct?.team ?? allTeams(discoverTeams(cwd)).find((candidate) => candidate.name === manifest.team);
+		if (!team) throw new Error(`Team '${manifest.team}' not found.`);
+		const baseWorkflow = direct?.workflow ?? allWorkflows(discoverWorkflows(cwd)).find((candidate) => candidate.name === manifest.workflow);
+		if (!baseWorkflow) throw new Error(`Workflow '${manifest.workflow ?? ""}' not found.`);
+		const workflow = expandParallelResearchWorkflow(baseWorkflow, cwd);
+		const loadedConfig = loadConfig(cwd);
+		const runConfig = manifest.runConfig && typeof manifest.runConfig === "object" && !Array.isArray(manifest.runConfig) ? manifest.runConfig as typeof loadedConfig.config : loadedConfig.config;
+		const runtime = manifest.runtimeResolution ? { kind: manifest.runtimeResolution.kind, requestedMode: manifest.runtimeResolution.requestedMode, available: manifest.runtimeResolution.available, fallback: manifest.runtimeResolution.fallback, steer: manifest.runtimeResolution.kind === "live-session", resume: manifest.runtimeResolution.kind === "live-session", liveToolActivity: manifest.runtimeResolution.kind === "live-session", transcript: manifest.runtimeResolution.kind !== "scaffold", reason: manifest.runtimeResolution.reason, safety: manifest.runtimeResolution.safety } : await resolveCrewRuntime(runConfig);
+		const runtimeResolution = manifest.runtimeResolution ?? runtimeResolutionState(runtime);
+		manifest = { ...manifest, runtimeResolution, runConfig, updatedAt: new Date().toISOString() };
+		saveRunManifest(manifest);
+		appendEvent(manifest.eventsPath, { type: "runtime.resolved", runId: manifest.runId, message: `Runtime resolved: ${runtime.kind} safety=${runtime.safety}`, data: { runtimeResolution, async: true } });
+		if (runtime.safety === "blocked") throw new Error(runtime.reason ?? "Child worker execution is disabled; refusing to create no-op scaffold subagents.");
+		const executeWorkers = runtime.kind !== "scaffold";
+		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers, limits: runConfig.limits, runtime, runtimeConfig: runConfig.runtime, skillOverride: manifest.skillOverride, reliability: runConfig.reliability, workspaceId: manifest.cwd });
+		manifest = result.manifest;
+		tasks = result.tasks;
+		appendEvent(manifest.eventsPath, { type: "async.completed", runId: manifest.runId, data: { status: manifest.status, tasks: tasks.length } });
+		if (manifest.status === "failed" || manifest.status === "cancelled" || manifest.status === "blocked") process.exitCode = 1;
+	} catch (error) {
+		// Terminate live agents on failure too — agents are done when the run fails
+		try {
+			const loaded = loadRunManifestById(cwd, runId);
+			if (loaded) {
+				// LAZY: live-agent-manager only needed on failure cleanup path; avoid module load at hot path.
+				const { terminateLiveAgentsForRun } = await import("./live-agent-manager.ts");
+				void terminateLiveAgentsForRun(loaded.manifest.runId, "failed", appendEvent, loaded.manifest.eventsPath).catch(() => {});
+			}
+		} catch { /* best-effort */ }
+		const message = error instanceof Error ? error.message : String(error);
+		manifest = updateRunStatus(manifest, "failed", message);
+		appendEvent(manifest.eventsPath, { type: "async.failed", runId: manifest.runId, message });
+		process.exitCode = 1;
+	} finally {
+		stopInterruptGuard();
+		stopParentGuard();
+	}
+}
+
+await main();

package/src/runtime/cancellation.ts

@@ -1,61 +1,61 @@
-import type { OperationTerminalEvidence } from "../state/types.ts";
-
-export type CancellationReasonCode = "caller_cancelled" | "leader_interrupted" | "provider_timeout" | "worker_timeout" | "tool_timeout" | "shutdown" | "unknown";
-
-export interface CancellationReason {
-	code: CancellationReasonCode;
-	message: string;
-	cause?: unknown;
-}
-
-export function buildSyntheticTerminalEvidence(
-	operation: "worker" | "tool" | "model",
-	reason: CancellationReason,
-	startedAt?: string,
-): OperationTerminalEvidence {
-	return { operation, status: "cancelled", startedAt, finishedAt: new Date().toISOString(), reason };
-}
-
-const KNOWN_CODES: ReadonlySet<string> = new Set(["caller_cancelled", "leader_interrupted", "provider_timeout", "worker_timeout", "tool_timeout", "shutdown", "unknown"]);
-
-export class CrewCancellationError extends Error {
-	readonly reason: CancellationReason;
-
-	constructor(reason: CancellationReason) {
-		super(reason.message);
-		this.name = "CrewCancellationError";
-		this.reason = reason;
-	}
-}
-
-function reasonFromString(value: string): CancellationReason {
-	const trimmed = value.trim();
-	if (KNOWN_CODES.has(trimmed)) return { code: trimmed as CancellationReasonCode, message: `Cancelled: ${trimmed}` };
-	return { code: "caller_cancelled", message: trimmed || "Cancelled by caller." };
-}
-
-export function cancellationReasonFromUnknown(value: unknown): CancellationReason {
-	if (value instanceof CrewCancellationError) return value.reason;
-	if (value instanceof Error) return { code: "caller_cancelled", message: value.message || "Cancelled by caller.", cause: value };
-	if (typeof value === "string") return reasonFromString(value);
-	if (value && typeof value === "object" && !Array.isArray(value)) {
-		const record = value as { code?: unknown; reason?: unknown; message?: unknown; cause?: unknown };
-		const rawCode = typeof record.code === "string" ? record.code : typeof record.reason === "string" ? record.reason : undefined;
-		const code = rawCode && KNOWN_CODES.has(rawCode) ? rawCode as CancellationReasonCode : "caller_cancelled";
-		const message = typeof record.message === "string" && record.message.trim() ? record.message.trim() : `Cancelled: ${code}`;
-		return { code, message, cause: record.cause ?? value };
-	}
-	return { code: "caller_cancelled", message: "Cancelled by caller." };
-}
-
-export function cancellationReasonFromSignal(signal: AbortSignal | undefined): CancellationReason {
-	return cancellationReasonFromUnknown(signal?.reason);
-}
-
-export function cancellationErrorFromSignal(signal: AbortSignal | undefined): CrewCancellationError {
-	return new CrewCancellationError(cancellationReasonFromSignal(signal));
-}
-
-export function throwIfCancelled(signal: AbortSignal | undefined): void {
-	if (signal?.aborted) throw cancellationErrorFromSignal(signal);
-}
+import type { OperationTerminalEvidence } from "../state/types.ts";
+
+export type CancellationReasonCode = "caller_cancelled" | "leader_interrupted" | "provider_timeout" | "worker_timeout" | "tool_timeout" | "shutdown" | "unknown";
+
+export interface CancellationReason {
+	code: CancellationReasonCode;
+	message: string;
+	cause?: unknown;
+}
+
+export function buildSyntheticTerminalEvidence(
+	operation: "worker" | "tool" | "model",
+	reason: CancellationReason,
+	startedAt?: string,
+): OperationTerminalEvidence {
+	return { operation, status: "cancelled", startedAt, finishedAt: new Date().toISOString(), reason };
+}
+
+const KNOWN_CODES: ReadonlySet<string> = new Set(["caller_cancelled", "leader_interrupted", "provider_timeout", "worker_timeout", "tool_timeout", "shutdown", "unknown"]);
+
+export class CrewCancellationError extends Error {
+	readonly reason: CancellationReason;
+
+	constructor(reason: CancellationReason) {
+		super(reason.message);
+		this.name = "CrewCancellationError";
+		this.reason = reason;
+	}
+}
+
+function reasonFromString(value: string): CancellationReason {
+	const trimmed = value.trim();
+	if (KNOWN_CODES.has(trimmed)) return { code: trimmed as CancellationReasonCode, message: `Cancelled: ${trimmed}` };
+	return { code: "caller_cancelled", message: trimmed || "Cancelled by caller." };
+}
+
+export function cancellationReasonFromUnknown(value: unknown): CancellationReason {
+	if (value instanceof CrewCancellationError) return value.reason;
+	if (value instanceof Error) return { code: "caller_cancelled", message: value.message || "Cancelled by caller.", cause: value };
+	if (typeof value === "string") return reasonFromString(value);
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const record = value as { code?: unknown; reason?: unknown; message?: unknown; cause?: unknown };
+		const rawCode = typeof record.code === "string" ? record.code : typeof record.reason === "string" ? record.reason : undefined;
+		const code = rawCode && KNOWN_CODES.has(rawCode) ? rawCode as CancellationReasonCode : "caller_cancelled";
+		const message = typeof record.message === "string" && record.message.trim() ? record.message.trim() : `Cancelled: ${code}`;
+		return { code, message, cause: record.cause ?? value };
+	}
+	return { code: "caller_cancelled", message: "Cancelled by caller." };
+}
+
+export function cancellationReasonFromSignal(signal: AbortSignal | undefined): CancellationReason {
+	return cancellationReasonFromUnknown(signal?.reason);
+}
+
+export function cancellationErrorFromSignal(signal: AbortSignal | undefined): CrewCancellationError {
+	return new CrewCancellationError(cancellationReasonFromSignal(signal));
+}
+
+export function throwIfCancelled(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw cancellationErrorFromSignal(signal);
+}