pi-crew 0.1.51 → 0.2.1

package/src/runtime/crash-recovery.ts

@@ -11,6 +11,8 @@ import { checkProcessLiveness } from "./process-status.ts";
 import { reconcileStaleRun, type ReconcileResult } from "./stale-reconciler.ts";
 import { executeHook, appendHookEvent } from "../hooks/registry.ts";
 import { activeRunEntries, unregisterActiveRun, readActiveRunRegistry } from "../state/active-run-registry.ts";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
 
 export interface RecoveryPlan {
 	runId: string;
@@ -168,6 +170,32 @@ export function cancelOrphanedRuns(
  * This is the **global** cleanup that cancelOrphanedRuns (project-scoped)
  * cannot reach.
  */
+/**
+ * Best-effort removal of stateRoot and artifactsRoot directories for a purged run.
+ * Uses resolveRealContainedPath to ensure we only delete paths that are safely
+ * contained within a known crew root (project or user level).
+ */
+function tryRemoveRunDirectories(entry: { stateRoot: string; cwd: string }): void {
+	const roots = [projectCrewRoot(entry.cwd), userCrewRoot()];
+	for (const root of roots) {
+		try {
+			resolveRealContainedPath(root, entry.stateRoot);
+			// If we get here, stateRoot is safely contained — remove it
+			fs.rmSync(entry.stateRoot, { recursive: true, force: true });
+			break;
+		} catch {
+			// Not contained in this root, try next
+		}
+	}
+	// NOTE: artifactsRoot is shared across runs and cleaned up by pruneFinishedRuns/pruneUserLevelRuns — not deleted here.
+}
+
+/**
+ * Purge the global active-run-index of entries whose manifest is no longer active.
+ *
+ * Note: This function only cleans user-level active run entries.
+ * Project-level stale runs are handled by session_start auto-prune triggered during run creation.
+ */
 export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.now()): { purged: string[]; kept: string[] } {
 	const purged: string[] = [];
 	const kept: string[] = [];
@@ -177,6 +205,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 		// 1. Manifest file gone → definitely stale
 		if (!fs.existsSync(entry.manifestPath)) {
 			unregisterActiveRun(entry.runId);
+			tryRemoveRunDirectories(entry);
 			purged.push(entry.runId);
 			continue;
 		}
@@ -184,6 +213,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 		// 2. CWD gone → temp dir cleaned up
 		if (!fs.existsSync(entry.cwd)) {
 			unregisterActiveRun(entry.runId);
+			tryRemoveRunDirectories(entry);
 			purged.push(entry.runId);
 			continue;
 		}
@@ -194,11 +224,12 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 			manifest = JSON.parse(fs.readFileSync(entry.manifestPath, "utf-8"));
 		} catch {
 			unregisterActiveRun(entry.runId);
+			tryRemoveRunDirectories(entry);
 			purged.push(entry.runId);
 			continue;
 		}
 
-		// 4. Terminal status → no longer active
+		// 4. Terminal status → no longer active (just unregister, don't delete files)
 		const terminalStatuses = new Set(["completed", "failed", "cancelled", "blocked"]);
 		if (manifest && terminalStatuses.has(manifest.status ?? "")) {
 			unregisterActiveRun(entry.runId);
@@ -231,6 +262,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 						// Best-effort manifest cleanup
 					}
 					unregisterActiveRun(entry.runId);
+					tryRemoveRunDirectories(entry);
 					purged.push(entry.runId);
 					continue;
 				}

package/src/runtime/delta-conflict.ts

@@ -0,0 +1,360 @@
+/**
+ * Delta conflict detection for pi-crew import and resume operations.
+ *
+ * Compares incoming bundles against existing state to surface conflicts
+ * (file overwrites, status mismatches, schema drift, deleted resources)
+ * without blocking the operation — only reporting for user awareness.
+ */
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export type ConflictKind = "file_overwrite" | "state_mismatch" | "schema_drift" | "resource_deleted";
+
+export interface Conflict {
+	kind: ConflictKind;
+	/** File or resource path that is in conflict. */
+	path: string;
+	/** Current value or summary (optional). */
+	existing?: string;
+	/** Incoming value or summary (optional). */
+	incoming?: string;
+	severity: "error" | "warning";
+	autoResolvable: boolean;
+}
+
+export interface ConflictReport {
+	hasConflicts: boolean;
+	conflicts: Conflict[];
+	summary: { errors: number; warnings: number; autoResolvable: number };
+}
+
+export type ConflictStrategy = "skip" | "overwrite" | "merge";
+
+export interface ConflictResolution {
+	resolved: boolean;
+	action: string;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+interface TaskLike {
+	id: string;
+	status: string;
+	role?: string;
+	agent?: string;
+}
+
+function buildReport(conflicts: Conflict[]): ConflictReport {
+	const errors = conflicts.filter((c) => c.severity === "error").length;
+	const warnings = conflicts.filter((c) => c.severity === "warning").length;
+	const autoResolvable = conflicts.filter((c) => c.autoResolvable).length;
+	return {
+		hasConflicts: conflicts.length > 0,
+		conflicts,
+		summary: { errors, warnings, autoResolvable },
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Extract task-like objects from an unknown array, filtering out non-records.
+ */
+function extractTaskLikes(tasks: unknown[]): TaskLike[] {
+	return tasks
+		.filter(isRecord)
+		.map((t) => ({
+			id: typeof t.id === "string" ? t.id : "",
+			status: typeof t.status === "string" ? t.status : "",
+			role: typeof t.role === "string" ? t.role : undefined,
+			agent: typeof t.agent === "string" ? t.agent : undefined,
+		}))
+		.filter((t) => t.id !== "");
+}
+
+// ── Import Conflict Detection ──────────────────────────────────────────
+
+export interface ImportBundle {
+	manifest: Record<string, unknown>;
+	tasks: unknown[];
+	events?: unknown[];
+}
+
+export interface ExistingState {
+	manifest?: Record<string, unknown>;
+	tasks?: unknown[];
+}
+
+/**
+ * Detect conflicts between an import bundle and existing run state.
+ *
+ * Checks:
+ * - **schema_drift**: manifest `schemaVersion` differs between import and existing.
+ * - **file_overwrite**: artifact paths in the import bundle that already exist
+ *   in the current manifest's artifact list.
+ * - **state_mismatch**: task statuses differ between import and existing tasks.
+ * - **resource_deleted**: referenced agent/team/workflow in import does not exist
+ *   in the current state.
+ */
+export function detectImportConflicts(
+	importBundle: ImportBundle,
+	existingState: ExistingState,
+): ConflictReport {
+	const conflicts: Conflict[] = [];
+	const { manifest: incoming, tasks: incomingTasks } = importBundle;
+	const { manifest: current, tasks: currentTasks } = existingState;
+
+	// ── Schema drift ─────────────────────────────────────────────────
+	if (current) {
+		const incomingVersion = incoming.schemaVersion;
+		const currentVersion = current.schemaVersion;
+		if (
+			typeof incomingVersion !== "undefined" &&
+			typeof currentVersion !== "undefined" &&
+			incomingVersion !== currentVersion
+		) {
+			conflicts.push({
+				kind: "schema_drift",
+				path: "manifest.schemaVersion",
+				existing: String(currentVersion),
+				incoming: String(incomingVersion),
+				severity: "warning",
+				autoResolvable: true,
+			});
+		}
+	}
+
+	// ── File overwrite (artifact collision) ──────────────────────────
+	const incomingArtifacts = Array.isArray(incoming.artifacts) ? incoming.artifacts : [];
+	const currentArtifacts = Array.isArray(current?.artifacts) ? current?.artifacts : [];
+
+	if (current && currentArtifacts.length > 0) {
+		const currentPaths = new Set(
+			currentArtifacts
+				.filter(isRecord)
+				.map((a) => (typeof a.path === "string" ? a.path : ""))
+				.filter((p) => p !== ""),
+		);
+
+		for (const artifact of incomingArtifacts) {
+			if (!isRecord(artifact)) continue;
+			const artifactPath = typeof artifact.path === "string" ? artifact.path : "";
+			if (artifactPath !== "" && currentPaths.has(artifactPath)) {
+				conflicts.push({
+					kind: "file_overwrite",
+					path: artifactPath,
+					existing: "present in current run",
+					incoming: "present in import bundle",
+					severity: "warning",
+					autoResolvable: true,
+				});
+			}
+		}
+	}
+
+	// ── State mismatch (task status differences) ─────────────────────
+	if (currentTasks && currentTasks.length > 0) {
+		const currentTaskMap = new Map(
+			extractTaskLikes(currentTasks).map((t) => [t.id, t]),
+		);
+		const incomingTaskList = extractTaskLikes(incomingTasks);
+
+		for (const inTask of incomingTaskList) {
+			const curTask = currentTaskMap.get(inTask.id);
+			if (curTask && curTask.status !== inTask.status) {
+				conflicts.push({
+					kind: "state_mismatch",
+					path: `tasks/${inTask.id}`,
+					existing: curTask.status,
+					incoming: inTask.status,
+					severity: "error",
+					autoResolvable: false,
+				});
+			}
+		}
+	}
+
+	// ── Resource deleted (agent/team/workflow no longer in current) ──
+	if (current) {
+		const currentTeam = typeof current.team === "string" ? current.team : undefined;
+		const currentWorkflow = typeof current.workflow === "string" ? current.workflow : undefined;
+		const incomingTeam = typeof incoming.team === "string" ? incoming.team : undefined;
+		const incomingWorkflow = typeof incoming.workflow === "string" ? incoming.workflow : undefined;
+
+		if (incomingTeam && currentTeam && incomingTeam !== currentTeam) {
+			conflicts.push({
+				kind: "resource_deleted",
+				path: `team/${incomingTeam}`,
+				existing: currentTeam,
+				incoming: incomingTeam,
+				severity: "warning",
+				autoResolvable: true,
+			});
+		}
+
+		if (incomingWorkflow && currentWorkflow && incomingWorkflow !== currentWorkflow) {
+			conflicts.push({
+				kind: "resource_deleted",
+				path: `workflow/${incomingWorkflow}`,
+				existing: currentWorkflow,
+				incoming: incomingWorkflow,
+				severity: "warning",
+				autoResolvable: true,
+			});
+		}
+
+		// Check agent references from tasks vs current tasks
+		if (currentTasks && currentTasks.length > 0) {
+			const currentAgents = new Set(
+				extractTaskLikes(currentTasks)
+					.map((t) => t.agent)
+					.filter((a): a is string => a !== undefined),
+			);
+			const incomingTaskList = extractTaskLikes(incomingTasks);
+			for (const inTask of incomingTaskList) {
+				if (
+					inTask.agent &&
+					inTask.id !== "" &&
+					currentAgents.size > 0 &&
+					!currentAgents.has(inTask.agent) &&
+					// Only flag if there's a matching task id (agent was reassigned)
+					extractTaskLikes(currentTasks).some((ct) => ct.id === inTask.id)
+				) {
+					conflicts.push({
+						kind: "resource_deleted",
+						path: `agent/${inTask.agent}`,
+						existing: "not in current run",
+						incoming: inTask.agent,
+						severity: "warning",
+						autoResolvable: true,
+					});
+				}
+			}
+		}
+	}
+
+	return buildReport(conflicts);
+}
+
+// ── Resume Conflict Detection ──────────────────────────────────────────
+
+export interface SuspendedState {
+	tasks: unknown[];
+	artifacts: string[];
+}
+
+export interface CurrentState {
+	changedFiles: string[];
+	taskStatuses: Record<string, string>;
+}
+
+/**
+ * Detect conflicts when resuming a suspended run against current filesystem state.
+ *
+ * Checks:
+ * - **file_overwrite**: files changed since suspension.
+ * - **state_mismatch**: task statuses changed externally.
+ */
+export function detectResumeConflicts(
+	suspendedState: SuspendedState,
+	currentState: CurrentState,
+): ConflictReport {
+	const conflicts: Conflict[] = [];
+	const { tasks: suspendedTasks, artifacts: suspendedArtifacts } = suspendedState;
+	const { changedFiles, taskStatuses } = currentState;
+
+	// ── File overwrite ───────────────────────────────────────────────
+	const changedSet = new Set(changedFiles);
+	for (const artifactPath of suspendedArtifacts) {
+		if (changedSet.has(artifactPath)) {
+			conflicts.push({
+				kind: "file_overwrite",
+				path: artifactPath,
+				existing: "modified since suspension",
+				incoming: "expected unchanged",
+				severity: "error",
+				autoResolvable: false,
+			});
+		}
+	}
+
+	// ── State mismatch ───────────────────────────────────────────────
+	const suspendedTaskList = extractTaskLikes(suspendedTasks);
+	for (const task of suspendedTaskList) {
+		const currentStatus = taskStatuses[task.id];
+		if (currentStatus !== undefined && currentStatus !== task.status) {
+			conflicts.push({
+				kind: "state_mismatch",
+				path: `tasks/${task.id}`,
+				existing: currentStatus,
+				incoming: task.status,
+				severity: "error",
+				autoResolvable: false,
+			});
+		}
+	}
+
+	return buildReport(conflicts);
+}
+
+// ── Conflict Resolution ────────────────────────────────────────────────
+
+/**
+ * Apply a resolution strategy to a conflict.
+ *
+ * - **skip**: skip the conflicting item (always resolves).
+ * - **overwrite**: replace existing with incoming (resolves for `file_overwrite`
+ *   and `schema_drift`; does not resolve `state_mismatch` or `resource_deleted`).
+ * - **merge**: attempt merge — resolves `state_mismatch` with merged status;
+ *   resolves others conditionally.
+ */
+export function resolveConflict(
+	conflict: Conflict,
+	strategy: ConflictStrategy,
+): ConflictResolution {
+	switch (strategy) {
+		case "skip":
+			return { resolved: true, action: `Skipped ${conflict.path}` };
+
+		case "overwrite":
+			if (conflict.kind === "file_overwrite" || conflict.kind === "schema_drift") {
+				return { resolved: true, action: `Overwritten ${conflict.path} with incoming value` };
+			}
+			return {
+				resolved: false,
+				action: `Cannot overwrite ${conflict.kind} at ${conflict.path}; manual resolution required`,
+			};
+
+		case "merge":
+			if (conflict.kind === "state_mismatch") {
+				return {
+					resolved: true,
+					action: `Merged ${conflict.path}: kept existing=${conflict.existing ?? "?"}, incoming=${conflict.incoming ?? "?"}`,
+				};
+			}
+			if (conflict.kind === "resource_deleted") {
+				return {
+					resolved: true,
+					action: `Merged ${conflict.path}: using incoming resource reference`,
+				};
+			}
+			if (conflict.kind === "file_overwrite") {
+				return {
+					resolved: true,
+					action: `Merged ${conflict.path}: kept both versions`,
+				};
+			}
+			if (conflict.kind === "schema_drift") {
+				return {
+					resolved: true,
+					action: `Merged ${conflict.path}: using incoming schema version`,
+				};
+			}
+			return {
+				resolved: false,
+				action: `Cannot merge ${conflict.kind} at ${conflict.path}`,
+			};
+	}
+}

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/foreground-control.ts

@@ -1,82 +1,82 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { appendEvent } from "../state/event-log.ts";
-import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { checkProcessLiveness, isActiveRunStatus } from "./process-status.ts";
-import { readCrewAgents } from "./crew-agent-records.ts";
-
-export type ForegroundControlRequestType = "interrupt" | "status";
-
-export interface ForegroundControlStatus {
-	runId: string;
-	status: TeamRunManifest["status"];
-	active: boolean;
-	asyncPid?: number;
-	asyncAlive?: boolean;
-	runningTasks: string[];
-	runningAgents: string[];
-	controlPath: string;
-	lastRequest?: ForegroundControlRequest;
-}
-
-export interface ForegroundControlRequest {
-	id: string;
-	type: ForegroundControlRequestType;
-	createdAt: string;
-	reason: string;
-	acknowledged: boolean;
-}
-
-export function foregroundControlPath(manifest: TeamRunManifest): string {
-	return path.join(manifest.stateRoot, "foreground-control.json");
-}
-
-function readLastRequest(controlPath: string): ForegroundControlRequest | undefined {
-	if (!fs.existsSync(controlPath)) return undefined;
-	try {
-		const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
-		return parsed.requests?.at(-1);
-	} catch {
-		return undefined;
-	}
-}
-
-export function readForegroundControlStatus(manifest: TeamRunManifest, tasks: TeamTaskState[]): ForegroundControlStatus {
-	const controlPath = foregroundControlPath(manifest);
-	const asyncAlive = manifest.async?.pid !== undefined ? checkProcessLiveness(manifest.async.pid).alive : undefined;
-	return {
-		runId: manifest.runId,
-		status: manifest.status,
-		active: isActiveRunStatus(manifest.status),
-		asyncPid: manifest.async?.pid,
-		asyncAlive,
-		runningTasks: tasks.filter((task) => task.status === "running").map((task) => task.id),
-		runningAgents: readCrewAgents(manifest).filter((agent) => agent.status === "running").map((agent) => agent.id),
-		controlPath,
-		lastRequest: readLastRequest(controlPath),
-	};
-}
-
-export function writeForegroundInterruptRequest(manifest: TeamRunManifest, reason = "User requested foreground interrupt."): ForegroundControlRequest {
-	const controlPath = foregroundControlPath(manifest);
-	let requests: ForegroundControlRequest[] = [];
-	if (fs.existsSync(controlPath)) {
-		try {
-			const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
-			requests = Array.isArray(parsed.requests) ? parsed.requests : [];
-		} catch {
-			requests = [];
-		}
-	}
-	const request: ForegroundControlRequest = {
-		id: `fg_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`,
-		type: "interrupt",
-		createdAt: new Date().toISOString(),
-		reason,
-		acknowledged: false,
-	};
-	fs.mkdirSync(path.dirname(controlPath), { recursive: true });
-	fs.writeFileSync(controlPath, `${JSON.stringify({ requests: [...requests, request] }, null, 2)}\n`, "utf-8");
-	appendEvent(manifest.eventsPath, { type: "foreground.interrupt_requested", runId: manifest.runId, message: reason, data: { requestId: request.id, controlPath } });
-	return request;
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { appendEvent } from "../state/event-log.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { checkProcessLiveness, isActiveRunStatus } from "./process-status.ts";
+import { readCrewAgents } from "./crew-agent-records.ts";
+
+export type ForegroundControlRequestType = "interrupt" | "status";
+
+export interface ForegroundControlStatus {
+	runId: string;
+	status: TeamRunManifest["status"];
+	active: boolean;
+	asyncPid?: number;
+	asyncAlive?: boolean;
+	runningTasks: string[];
+	runningAgents: string[];
+	controlPath: string;
+	lastRequest?: ForegroundControlRequest;
+}
+
+export interface ForegroundControlRequest {
+	id: string;
+	type: ForegroundControlRequestType;
+	createdAt: string;
+	reason: string;
+	acknowledged: boolean;
+}
+
+export function foregroundControlPath(manifest: TeamRunManifest): string {
+	return path.join(manifest.stateRoot, "foreground-control.json");
+}
+
+function readLastRequest(controlPath: string): ForegroundControlRequest | undefined {
+	if (!fs.existsSync(controlPath)) return undefined;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
+		return parsed.requests?.at(-1);
+	} catch {
+		return undefined;
+	}
+}
+
+export function readForegroundControlStatus(manifest: TeamRunManifest, tasks: TeamTaskState[]): ForegroundControlStatus {
+	const controlPath = foregroundControlPath(manifest);
+	const asyncAlive = manifest.async?.pid !== undefined ? checkProcessLiveness(manifest.async.pid).alive : undefined;
+	return {
+		runId: manifest.runId,
+		status: manifest.status,
+		active: isActiveRunStatus(manifest.status),
+		asyncPid: manifest.async?.pid,
+		asyncAlive,
+		runningTasks: tasks.filter((task) => task.status === "running").map((task) => task.id),
+		runningAgents: readCrewAgents(manifest).filter((agent) => agent.status === "running").map((agent) => agent.id),
+		controlPath,
+		lastRequest: readLastRequest(controlPath),
+	};
+}
+
+export function writeForegroundInterruptRequest(manifest: TeamRunManifest, reason = "User requested foreground interrupt."): ForegroundControlRequest {
+	const controlPath = foregroundControlPath(manifest);
+	let requests: ForegroundControlRequest[] = [];
+	if (fs.existsSync(controlPath)) {
+		try {
+			const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
+			requests = Array.isArray(parsed.requests) ? parsed.requests : [];
+		} catch {
+			requests = [];
+		}
+	}
+	const request: ForegroundControlRequest = {
+		id: `fg_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`,
+		type: "interrupt",
+		createdAt: new Date().toISOString(),
+		reason,
+		acknowledged: false,
+	};
+	fs.mkdirSync(path.dirname(controlPath), { recursive: true });
+	fs.writeFileSync(controlPath, `${JSON.stringify({ requests: [...requests, request] }, null, 2)}\n`, "utf-8");
+	appendEvent(manifest.eventsPath, { type: "foreground.interrupt_requested", runId: manifest.runId, message: reason, data: { requestId: request.id, controlPath } });
+	return request;
+}