pi-crew 0.1.45 → 0.1.49

package/src/hooks/registry.ts

@@ -0,0 +1,61 @@
+import type { HookDefinition, HookName, HookContext, HookResult, HookExecutionReport } from "./types.ts";
+import { appendEvent } from "../state/event-log.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+import { runEventBus } from "../ui/run-event-bus.ts";
+
+const registry = new Map<HookName, HookDefinition[]>();
+
+export function registerHook(definition: HookDefinition): void {
+	const hooks = registry.get(definition.name) ?? [];
+	hooks.push(definition);
+	registry.set(definition.name, hooks);
+}
+
+export function clearHooks(): void {
+	registry.clear();
+}
+
+export function getHooks(name: HookName): HookDefinition[] {
+	return registry.get(name) ?? [];
+}
+
+export async function executeHook(name: HookName, ctx: HookContext): Promise<HookExecutionReport> {
+	const hooks = getHooks(name);
+	if (hooks.length === 0) return { hookName: name, outcome: "allow", durationMs: 0 };
+	const start = Date.now();
+	const diagnostics: string[] = [];
+	let capturedModifications: Record<string, unknown> | undefined;
+	for (const hook of hooks) {
+		try {
+			const result: HookResult = await hook.handler(ctx);
+			if (hook.mode === "blocking" && result.outcome === "block") {
+				return { hookName: name, outcome: "block", durationMs: Date.now() - start, reason: result.reason };
+			}
+			if (result.outcome === "modify" && result.data) {
+				Object.assign(ctx, result.data);
+				capturedModifications = { ...result.data };
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			if (hook.mode === "blocking") {
+				return { hookName: name, outcome: "block", durationMs: Date.now() - start, reason: `Hook error: ${message}` };
+			}
+			// Non-blocking hook errors are accumulated as diagnostics; continue to next hook
+			diagnostics.push(message);
+			}
+	}
+	if (diagnostics.length > 0) {
+		return { hookName: name, outcome: "diagnostic", durationMs: Date.now() - start, reason: diagnostics.join("; "), modifiedData: capturedModifications };
+	}
+	return { hookName: name, outcome: "allow", durationMs: Date.now() - start, modifiedData: capturedModifications };
+}
+
+export function appendHookEvent(manifest: TeamRunManifest, report: HookExecutionReport): void {
+	appendEvent(manifest.eventsPath, {
+		type: "hook.executed",
+		runId: manifest.runId,
+		message: `Hook ${report.hookName} completed with outcome=${report.outcome}${report.reason ? `: ${report.reason}` : ""}`,
+		data: { hookName: report.hookName, outcome: report.outcome, durationMs: report.durationMs, reason: report.reason },
+	});
+	runEventBus.emit({ type: "effectiveness_changed", runId: manifest.runId, data: { hookName: report.hookName, outcome: report.outcome } });
+}

package/src/hooks/types.ts

@@ -0,0 +1,41 @@
+export type HookName =
+	| "before_run_start"
+	| "before_task_start"
+	| "task_result"
+	| "before_cancel"
+	| "before_retry"
+	| "before_forget"
+	| "before_cleanup"
+	| "before_publish"
+	| "session_before_switch"
+	| "run_recovery";
+
+export type HookMode = "blocking" | "non_blocking";
+export type HookOutcome = "allow" | "block" | "modify" | "diagnostic";
+
+export interface HookContext {
+	runId: string;
+	taskId?: string;
+	cwd: string;
+	[key: string]: unknown;
+}
+
+export interface HookResult {
+	outcome: HookOutcome;
+	reason?: string;
+	data?: Record<string, unknown>;
+}
+
+export interface HookDefinition {
+	name: HookName;
+	mode: HookMode;
+	handler: (ctx: HookContext) => HookResult | Promise<HookResult>;
+}
+
+export interface HookExecutionReport {
+	hookName: HookName;
+	outcome: HookOutcome;
+	durationMs: number;
+	reason?: string;
+	modifiedData?: Record<string, unknown>;
+}

package/src/observability/event-to-metric.ts

@@ -13,6 +13,13 @@ function numberValue(value: unknown, fallback = 0): number {
 	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 
+const CANCELLATION_REASON_LABELS = new Set(["caller_cancelled", "leader_interrupted", "provider_timeout", "worker_timeout", "tool_timeout", "shutdown", "unknown"]);
+
+function cancellationReasonLabel(value: unknown): string {
+	const raw = stringValue(value, "unknown");
+	return CANCELLATION_REASON_LABELS.has(raw) ? raw : "unknown";
+}
+
 export interface EventToMetricSubscription {
 	dispose(): void;
 }
@@ -36,7 +43,7 @@ export function wireEventToMetrics(events: ExtensionAPI["events"] | undefined, r
 	const handlers: Array<[string, (data: unknown) => void]> = [
 		["crew.run.completed", (data) => { const item = recordValue(data); runCount.inc({ status: "completed" }); runDuration.observe({ team: stringValue(item.team, "unknown") }, numberValue(item.durationMs)); }],
 		["crew.run.failed", () => runCount.inc({ status: "failed" })],
-		["crew.run.cancelled", () => runCount.inc({ status: "cancelled" })],
+		["crew.run.cancelled", (data) => { const item = recordValue(data); runCount.inc({ status: "cancelled", reason: cancellationReasonLabel(item.reason) }); }],
 		["crew.task.completed", (data) => { const item = recordValue(data); taskCount.inc({ status: "completed" }); taskDuration.observe({ role: stringValue(item.role, "unknown") }, numberValue(item.durationMs)); tokenUsage.observe({ role: stringValue(item.role, "unknown") }, numberValue(item.tokens)); }],
 		["crew.task.failed", () => taskCount.inc({ status: "failed" })],
 		["crew.task.retry_attempt", (data) => { const item = recordValue(data); taskCount.inc({ status: "retry" }); retryAttemptCount.inc({ runId: stringValue(item.runId, "unknown"), taskId: stringValue(item.taskId, "unknown") }); }],

package/src/runtime/agent-control.ts

@@ -1,63 +1,169 @@
-import type { PiTeamsConfig } from "../config/config.ts";
-import type { TeamRunManifest } from "../state/types.ts";
-import { appendTaskAttentionEvent } from "./attention-events.ts";
-import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
-import { upsertCrewAgent } from "./crew-agent-records.ts";
-
-export interface CrewControlConfig {
-	enabled: boolean;
-	needsAttentionAfterMs: number;
-}
-
-const DEFAULT_NEEDS_ATTENTION_MS = 60_000;
-
-function positiveInt(value: unknown): number | undefined {
-	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
-}
-
-export function resolveCrewControlConfig(config: PiTeamsConfig | undefined): CrewControlConfig {
-	const raw = config as PiTeamsConfig & { control?: { enabled?: unknown; needsAttentionAfterMs?: unknown } } | undefined;
-	return {
-		enabled: raw?.control?.enabled === false ? false : true,
-		needsAttentionAfterMs: positiveInt(raw?.control?.needsAttentionAfterMs) ?? DEFAULT_NEEDS_ATTENTION_MS,
-	};
-}
-
-export function activityAgeMs(agent: CrewAgentRecord, now = Date.now()): number | undefined {
-	const timestamp = agent.progress?.lastActivityAt ?? agent.startedAt;
-	if (!timestamp) return undefined;
-	const ms = now - new Date(timestamp).getTime();
-	return Number.isFinite(ms) ? Math.max(0, ms) : undefined;
-}
-
-export function formatActivityAge(agent: CrewAgentRecord, now = Date.now()): string | undefined {
-	const age = activityAgeMs(agent, now);
-	if (age === undefined) return undefined;
-	if (age < 1000) return "active now";
-	const seconds = Math.floor(age / 1000);
-	if (seconds < 60) return agent.progress?.activityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
-	const minutes = Math.floor(seconds / 60);
-	return agent.progress?.activityState === "needs_attention" ? `no activity for ${minutes}m` : `active ${minutes}m ago`;
-}
-
-export function applyAttentionState(manifest: TeamRunManifest, agent: CrewAgentRecord, config: CrewControlConfig, now = Date.now()): CrewAgentRecord {
-	if (!config.enabled || agent.status !== "running") return agent;
-	const age = activityAgeMs(agent, now);
-	if (age === undefined || age <= config.needsAttentionAfterMs) return agent;
-	if (agent.progress?.activityState === "needs_attention") return agent;
-	const updated: CrewAgentRecord = {
-		...agent,
-		progress: {
-			...(agent.progress ?? { recentTools: [], recentOutput: [], toolCount: agent.toolUses ?? 0 }),
-			activityState: "needs_attention",
-		},
-	};
-	upsertCrewAgent(manifest, updated);
-	appendTaskAttentionEvent({
-		manifest,
-		taskId: agent.taskId,
-		message: `${agent.agent} needs attention (no observed activity for ${Math.floor(age / 1000)}s).`,
-		data: { activityState: "needs_attention", reason: "idle", elapsedMs: age, taskId: agent.taskId, agentName: agent.agent, suggestedAction: "Check worker status, wait, steer, or cancel if needed." },
-	});
-	return updated;
-}
+import type { PiTeamsConfig } from "../config/config.ts";
+import type { TeamRunManifest, ControlReservation } from "../state/types.ts";
+import { appendTaskAttentionEvent } from "./attention-events.ts";
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+import { upsertCrewAgent } from "./crew-agent-records.ts";
+import { randomUUID } from "node:crypto";
+
+export interface CrewControlConfig {
+	enabled: boolean;
+	needsAttentionAfterMs: number;
+	consecutiveFailureThreshold: number;
+	longRunningMinutes: number;
+}
+
+const DEFAULT_NEEDS_ATTENTION_MS = 60_000;
+const DEFAULT_CONSECUTIVE_FAILURE_THRESHOLD = 3;
+const DEFAULT_LONG_RUNNING_MINUTES = 10;
+
+function positiveInt(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+export function resolveCrewControlConfig(config: PiTeamsConfig | undefined): CrewControlConfig {
+	const raw = config as PiTeamsConfig & { control?: { enabled?: unknown; needsAttentionAfterMs?: unknown; consecutiveFailureThreshold?: unknown; longRunningMinutes?: unknown } } | undefined;
+	return {
+		enabled: raw?.control?.enabled === false ? false : true,
+		needsAttentionAfterMs: positiveInt(raw?.control?.needsAttentionAfterMs) ?? DEFAULT_NEEDS_ATTENTION_MS,
+		consecutiveFailureThreshold: positiveInt(raw?.control?.consecutiveFailureThreshold) ?? DEFAULT_CONSECUTIVE_FAILURE_THRESHOLD,
+		longRunningMinutes: positiveInt(raw?.control?.longRunningMinutes) ?? DEFAULT_LONG_RUNNING_MINUTES,
+	};
+}
+
+export function activityAgeMs(agent: CrewAgentRecord, now = Date.now()): number | undefined {
+	const timestamp = agent.progress?.lastActivityAt ?? agent.startedAt;
+	if (!timestamp) return undefined;
+	const ms = now - new Date(timestamp).getTime();
+	return Number.isFinite(ms) ? Math.max(0, ms) : undefined;
+}
+
+export function formatActivityAge(agent: CrewAgentRecord, now = Date.now()): string | undefined {
+	const age = activityAgeMs(agent, now);
+	if (age === undefined) return undefined;
+	if (age < 1000) return "active now";
+	const seconds = Math.floor(age / 1000);
+	if (seconds < 60) return agent.progress?.activityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	return agent.progress?.activityState === "needs_attention" ? `no activity for ${minutes}m` : `active ${minutes}m ago`;
+}
+
+export function applyAttentionState(manifest: TeamRunManifest, agent: CrewAgentRecord, config: CrewControlConfig, now = Date.now()): CrewAgentRecord {
+	if (!config.enabled || agent.status !== "running") return agent;
+	const age = activityAgeMs(agent, now);
+	if (age === undefined || age <= config.needsAttentionAfterMs) return agent;
+	if (agent.progress?.activityState === "needs_attention") return agent;
+	const updated: CrewAgentRecord = {
+		...agent,
+		progress: {
+			...(agent.progress ?? { recentTools: [], recentOutput: [], toolCount: agent.toolUses ?? 0 }),
+			activityState: "needs_attention",
+		},
+	};
+	upsertCrewAgent(manifest, updated);
+	appendTaskAttentionEvent({
+		manifest,
+		taskId: agent.taskId,
+		message: `${agent.agent} needs attention (no observed activity for ${Math.floor(age / 1000)}s).`,
+		data: { activityState: "needs_attention", reason: "idle", elapsedMs: age, taskId: agent.taskId, agentName: agent.agent, suggestedAction: "Check worker status, wait, steer, or cancel if needed." },
+	});
+	return updated;
+}
+
+export function applyLongRunningCheck(
+	manifest: TeamRunManifest,
+	agent: CrewAgentRecord,
+	config: CrewControlConfig,
+	now = Date.now(),
+): CrewAgentRecord {
+	if (!config.enabled || agent.status !== "running") return agent;
+	if (agent.progress?.activityState === "needs_attention") return agent;
+
+	const startedAt = agent.startedAt ? new Date(agent.startedAt).getTime() : undefined;
+	if (!startedAt) return agent;
+
+	const runtimeMs = now - startedAt;
+	const thresholdMs = config.longRunningMinutes * 60 * 1000;
+	if (runtimeMs <= thresholdMs) return agent;
+
+	// Already flagged as long_running
+	if (agent.progress?.activityState === "active_long_running") return agent;
+
+	const updated: CrewAgentRecord = {
+		...agent,
+		progress: {
+			...(agent.progress ?? { recentTools: [], recentOutput: [], toolCount: agent.toolUses ?? 0 }),
+			activityState: "active_long_running",
+		},
+	};
+	upsertCrewAgent(manifest, updated);
+	appendTaskAttentionEvent({
+		manifest,
+		taskId: agent.taskId,
+		message: `${agent.agent} has been running for ${Math.floor(runtimeMs / 60000)}m (threshold: ${config.longRunningMinutes}m).`,
+		data: { activityState: "active_long_running", reason: "idle", elapsedMs: runtimeMs, taskId: agent.taskId, agentName: agent.agent, suggestedAction: "Check worker progress, steer, or cancel if needed." },
+	});
+	return updated;
+}
+
+export function trackConsecutiveToolFailure(
+	manifest: TeamRunManifest,
+	agent: CrewAgentRecord,
+	toolName: string,
+	error: string | undefined,
+	config: CrewControlConfig,
+): CrewAgentRecord {
+	if (!config.enabled || agent.status !== "running") return agent;
+
+	const failures = agent.progress?.consecutiveFailures ?? 0;
+	const newFailures = failures + 1;
+
+	const updated: CrewAgentRecord = {
+		...agent,
+		progress: {
+			...(agent.progress ?? { recentTools: [], recentOutput: [], toolCount: agent.toolUses ?? 0 }),
+			consecutiveFailures: newFailures,
+		},
+	};
+
+	if (newFailures >= config.consecutiveFailureThreshold) {
+		upsertCrewAgent(manifest, updated);
+		appendTaskAttentionEvent({
+			manifest,
+			taskId: agent.taskId,
+			message: `${agent.agent} has ${newFailures} consecutive tool failures (threshold: ${config.consecutiveFailureThreshold}). Last: ${toolName}${error ? ` - ${error.slice(0, 100)}` : ""}`,
+			data: { activityState: "needs_attention", reason: "tool_failures", taskId: agent.taskId, agentName: agent.agent, suggestedAction: "Investigate tool failures, steer, or cancel if needed." },
+		});
+	} else {
+		upsertCrewAgent(manifest, updated);
+	}
+
+	return updated;
+}
+
+export function resetConsecutiveToolFailures(
+	manifest: TeamRunManifest,
+	agent: CrewAgentRecord,
+): void {
+	if (!agent.progress?.consecutiveFailures) return;
+	const updated: CrewAgentRecord = {
+		...agent,
+		progress: {
+			...agent.progress,
+			consecutiveFailures: 0,
+		},
+	};
+	upsertCrewAgent(manifest, updated);
+}
+
+/**
+ * Reserve a control channel for a task before spawning its worker.
+ * This ensures cancel/steer requests can be queued immediately
+ * while the worker is still starting up.
+ */
+export function reserveControlChannel(taskId: string, runId: string): ControlReservation {
+	return {
+		reservedAt: new Date().toISOString(),
+		controllerId: `ctrl:${taskId}:${randomUUID()}`,
+		acceptsControlEvents: true,
+	};
+}

package/src/runtime/async-runner.ts

@@ -6,6 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { appendEvent } from "../state/event-log.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 
+
 export type FileExists = (filePath: string) => boolean;
 
 const requireFromHere = createRequire(import.meta.url);
@@ -49,7 +50,7 @@ export function buildBackgroundSpawnOptions(manifest: TeamRunManifest, logFd: nu
 		cwd: manifest.cwd,
 		detached: true,
 		stdio: ["ignore", logFd, logFd],
-		env: { ...process.env },
+		env: { ...process.env, PI_CREW_PARENT_PID: String(process.pid) },
 		windowsHide: true,
 	};
 }
@@ -70,6 +71,7 @@ export function spawnBackgroundTeamRun(manifest: TeamRunManifest): SpawnBackgrou
 		fs.appendFileSync(logPath, `[pi-crew] background loader=${command.loader}\n`, "utf-8");
 		const child = spawn(process.execPath, command.args, buildBackgroundSpawnOptions(manifest, logFd));
 		child.unref();
+
 		return { pid: child.pid, logPath };
 	} finally {
 		fs.closeSync(logFd);

package/src/runtime/background-runner.ts

@@ -1,53 +1,78 @@
-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, updateRunStatus } from "../state/state-store.ts";
-import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
-import { loadConfig } from "../config/config.ts";
-import { executeTeamRun } from "./team-runner.ts";
-import { resolveCrewRuntime } from "./runtime-resolver.ts";
-import { directTeamAndWorkflowFromRun } from "./direct-run.ts";
-import { expandParallelResearchWorkflow } from "./parallel-research.ts";
-import { writeAsyncStartMarker } from "./async-marker.ts";
-
-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> {
-	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 runtime = await resolveCrewRuntime(loadedConfig.config);
-		const executeWorkers = runtime.kind !== "scaffold";
-		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits, runtime, runtimeConfig: loadedConfig.config.runtime });
-		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;
-	}
-}
-
-await main();
+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";
+import { executeTeamRun } from "./team-runner.ts";
+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();

package/src/runtime/cancellation-token.ts

@@ -0,0 +1,89 @@
+import { CrewCancellationError, type CancellationReason, cancellationReasonFromUnknown } from "./cancellation.ts";
+
+export interface CancellationTokenState {
+	aborted: boolean;
+	reason?: CancellationReason;
+	lastHeartbeatAt?: string;
+	lastHeartbeatStage?: string;
+}
+
+export interface CancellationTokenOptions {
+	signal?: AbortSignal;
+	onHeartbeat?: (state: CancellationTokenState) => void;
+	now?: () => Date;
+}
+
+export class CancellationToken {
+	readonly #controller = new AbortController();
+	readonly #onHeartbeat?: (state: CancellationTokenState) => void;
+	readonly #now: () => Date;
+	#reason?: CancellationReason;
+	#lastHeartbeatAt?: string;
+	#lastHeartbeatStage?: string;
+
+	constructor(options: CancellationTokenOptions = {}) {
+		this.#onHeartbeat = options.onHeartbeat;
+		this.#now = options.now ?? (() => new Date());
+		if (options.signal?.aborted) this.abort(options.signal.reason);
+		else if (options.signal) options.signal.addEventListener("abort", () => this.abort(options.signal?.reason), { once: true });
+	}
+
+	get signal(): AbortSignal { return this.#controller.signal; }
+	get aborted(): boolean { return this.#controller.signal.aborted; }
+	get reason(): CancellationReason | undefined { return this.#reason; }
+	get lastHeartbeatAt(): string | undefined { return this.#lastHeartbeatAt; }
+	get lastHeartbeatStage(): string | undefined { return this.#lastHeartbeatStage; }
+
+	heartbeat(stage?: string): CancellationTokenState {
+		this.throwIfCancelled();
+		this.#lastHeartbeatAt = this.#now().toISOString();
+		this.#lastHeartbeatStage = stage;
+		const state = this.state();
+		this.#onHeartbeat?.(state);
+		return state;
+	}
+
+	throwIfCancelled(): void {
+		if (this.aborted) throw new CrewCancellationError(this.#reason ?? cancellationReasonFromUnknown(this.#controller.signal.reason));
+	}
+
+	abort(reason?: unknown): void {
+		if (this.aborted) return;
+		this.#reason = cancellationReasonFromUnknown(reason);
+		this.#controller.abort(this.#reason);
+	}
+
+	wait(ms: number): Promise<void> {
+		this.throwIfCancelled();
+		if (ms <= 0) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			let timeout: NodeJS.Timeout | undefined;
+			const cleanup = (): void => {
+				if (timeout) clearTimeout(timeout);
+				this.signal.removeEventListener("abort", onAbort);
+			};
+			const onAbort = (): void => {
+				cleanup();
+				reject(new CrewCancellationError(this.#reason ?? cancellationReasonFromUnknown(this.signal.reason)));
+			};
+			timeout = setTimeout(() => {
+				cleanup();
+				resolve();
+			}, ms);
+			this.signal.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+
+	state(): CancellationTokenState {
+		return {
+			aborted: this.aborted,
+			...(this.#reason ? { reason: this.#reason } : {}),
+			...(this.#lastHeartbeatAt ? { lastHeartbeatAt: this.#lastHeartbeatAt } : {}),
+			...(this.#lastHeartbeatStage ? { lastHeartbeatStage: this.#lastHeartbeatStage } : {}),
+		};
+	}
+}
+
+export function createCancellationToken(options: CancellationTokenOptions = {}): CancellationToken {
+	return new CancellationToken(options);
+}