pi-crew 0.1.46 → 0.1.49

package/src/runtime/crash-recovery.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import * as fs from "node:fs";
 import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { appendEvent, scanSequence } from "../state/event-log.ts";
 import { withRunLockSync } from "../state/locks.ts";
@@ -8,6 +9,8 @@ import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
 import type { ManifestCache } from "./manifest-cache.ts";
 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";
 
 export interface RecoveryPlan {
 	runId: string;
@@ -43,6 +46,14 @@ export function detectInterruptedRuns(cwd: string, manifestCache: ManifestCache,
 export async function applyRecoveryPlan(plan: RecoveryPlan, ctx: Pick<ExtensionContext, "cwd">, registry?: MetricRegistry): Promise<void> {
 	const loaded = loadRunManifestById(ctx.cwd, plan.runId);
 	if (!loaded) throw new Error(`Run '${plan.runId}' not found.`);
+
+	const hookReport = await executeHook("run_recovery", { runId: plan.runId, cwd: ctx.cwd });
+	appendHookEvent(loaded.manifest, hookReport);
+	if (hookReport.outcome === "block") {
+		appendEvent(loaded.manifest.eventsPath, { type: "crew.run.recovery_blocked", runId: plan.runId, message: `Recovery blocked by hook: ${hookReport.reason ?? "run_recovery hook blocked the operation."}`, data: { hookOutcome: "block", reason: hookReport.reason } });
+		return;
+	}
+
 	const reset = new Set(plan.resumableTasks);
 	const tasks = loaded.tasks.map((task) => reset.has(task.id) ? { ...task, status: "queued" as const, startedAt: undefined, finishedAt: undefined, error: undefined, heartbeat: undefined } : task);
 	saveRunTasks(loaded.manifest, tasks);
@@ -62,6 +73,176 @@ export function declineRecoveryPlan(plan: RecoveryPlan, ctx: Pick<ExtensionConte
  * Run 3-phase stale reconciliation on all active runs.
  * Returns results for each reconciled run.
  */
+/**
+ * Auto-cancel orphaned runs whose owner session no longer exists.
+ *
+ * When a Pi session dies (crash, force-close, Ctrl+C), `session_shutdown`
+ * does not fire and child workers are not terminated. The next Pi session
+ * must detect these orphaned runs and cancel them.
+ *
+ * Criteria for orphan detection:
+ * 1. Manifest status is "running"
+ * 2. Manifest has an `ownerSessionId` that is NOT the current session
+ * 3. The owner session's process is no longer alive (PID check)
+ * 4. No recent heartbeat activity (task heartbeat or agent progress within threshold)
+ *
+ * Returns the number of runs cancelled.
+ */
+export function cancelOrphanedRuns(
+	cwd: string,
+	manifestCache: ManifestCache,
+	currentSessionId: string,
+	staleThresholdMs = 300_000,
+	now = Date.now(),
+): { cancelled: string[]; skipped: string[] } {
+	const cancelled: string[] = [];
+	const skipped: string[] = [];
+
+	// Phase 1: Scan project-level manifests via manifestCache
+	for (const manifest of manifestCache.list(50)) {
+		if (manifest.status !== "running") continue;
+
+		// Only consider runs owned by a different session
+		const ownerId = manifest.ownerSessionId;
+		if (!ownerId || ownerId === currentSessionId) continue;
+
+		// Check if the owner process is still alive
+		const ownerPid = manifest.async?.pid;
+		if (ownerPid !== undefined && checkProcessLiveness(ownerPid).alive) {
+			skipped.push(manifest.runId);
+			continue;
+		}
+
+		// Check for recent heartbeat activity
+		const loaded = loadRunManifestById(cwd, manifest.runId);
+		if (!loaded) continue;
+
+		const hasRecentActivity = loaded.tasks.some((task) => {
+			if (task.status !== "running" && task.status !== "waiting") return false;
+			const heartbeatAt = task.heartbeat?.lastSeenAt ? new Date(task.heartbeat.lastSeenAt).getTime() : Number.NaN;
+			if (task.heartbeat?.alive !== false && Number.isFinite(heartbeatAt) && now - heartbeatAt <= staleThresholdMs) return true;
+			const activityAt = task.agentProgress?.lastActivityAt ? new Date(task.agentProgress.lastActivityAt).getTime() : Number.NaN;
+			return Number.isFinite(activityAt) && now - activityAt <= staleThresholdMs;
+		});
+
+		if (hasRecentActivity) {
+			skipped.push(manifest.runId);
+			continue;
+		}
+
+		// Orphan confirmed — cancel all running tasks
+		withRunLockSync(loaded.manifest, () => {
+			const fresh = loadRunManifestById(cwd, manifest.runId);
+			if (!fresh || fresh.manifest.status !== "running") return;
+
+			const now_iso = new Date(now).toISOString();
+			const repairedTasks = fresh.tasks.map((task) => {
+				if (task.status === "running" || task.status === "queued" || task.status === "waiting") {
+					return { ...task, status: "cancelled" as const, finishedAt: now_iso, error: `Orphaned run: owner session ${ownerId} no longer exists` };
+				}
+				return task;
+			});
+
+			saveRunTasks(fresh.manifest, repairedTasks);
+			updateRunStatus(fresh.manifest, "cancelled", `Orphaned run: owner session ${ownerId} no longer exists`);
+			appendEvent(fresh.manifest.eventsPath, { type: "crew.run.orphan_cancelled", runId: manifest.runId, message: `Auto-cancelled orphaned run (owner: ${ownerId})`, data: { ownerSessionId: ownerId, cancelledTasks: repairedTasks.filter((t) => t.status === "cancelled").length } });
+			cancelled.push(manifest.runId);
+		});
+	}
+
+	return { cancelled, skipped };
+}
+
+/**
+ * Purge the global active-run-index of entries whose manifest is no longer active.
+ *
+ * This scans every entry in active-run-index.json and removes any whose:
+ * - manifest file no longer exists, OR
+ * - manifest status is terminal (completed/failed/cancelled/blocked), OR
+ * - manifest cwd directory no longer exists (e.g. temp test dirs)
+ *
+ * Also removes entries where the manifest is still "running" but:
+ * - The cwd has been deleted (temp dir cleanup)
+ * - The async worker PID is dead AND no heartbeat for > threshold
+ *
+ * This is the **global** cleanup that cancelOrphanedRuns (project-scoped)
+ * cannot reach.
+ */
+export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.now()): { purged: string[]; kept: string[] } {
+	const purged: string[] = [];
+	const kept: string[] = [];
+	const entries = readActiveRunRegistry();
+
+	for (const entry of entries) {
+		// 1. Manifest file gone → definitely stale
+		if (!fs.existsSync(entry.manifestPath)) {
+			unregisterActiveRun(entry.runId);
+			purged.push(entry.runId);
+			continue;
+		}
+
+		// 2. CWD gone → temp dir cleaned up
+		if (!fs.existsSync(entry.cwd)) {
+			unregisterActiveRun(entry.runId);
+			purged.push(entry.runId);
+			continue;
+		}
+
+		// 3. Read manifest status
+		let manifest: { status?: string; async?: { pid?: number }; ownerSessionId?: string } | undefined;
+		try {
+			manifest = JSON.parse(fs.readFileSync(entry.manifestPath, "utf-8"));
+		} catch {
+			unregisterActiveRun(entry.runId);
+			purged.push(entry.runId);
+			continue;
+		}
+
+		// 4. Terminal status → no longer active
+		const terminalStatuses = new Set(["completed", "failed", "cancelled", "blocked"]);
+		if (manifest && terminalStatuses.has(manifest.status ?? "")) {
+			unregisterActiveRun(entry.runId);
+			purged.push(entry.runId);
+			continue;
+		}
+
+		// 5. Still "running" — check if worker PID is dead and no heartbeat
+		if (manifest?.status === "running" && manifest.async?.pid !== undefined) {
+			const pidAlive = checkProcessLiveness(manifest.async.pid).alive;
+			if (!pidAlive) {
+				// Check age — if manifest hasn't been updated in > threshold, it's stale
+				const updatedAt = new Date(entry.updatedAt).getTime();
+				if (Number.isFinite(updatedAt) && now - updatedAt > staleThresholdMs) {
+					// Dead PID + stale update → cancel the manifest and unregister
+					try {
+						const fullLoaded = loadRunManifestById(entry.cwd, entry.runId);
+						if (fullLoaded) {
+							const now_iso = new Date(now).toISOString();
+							const repairedTasks = fullLoaded.tasks.map((task) => {
+								if (task.status === "running" || task.status === "queued" || task.status === "waiting") {
+									return { ...task, status: "cancelled" as const, finishedAt: now_iso, error: "Orphaned run: worker process dead and no recent activity" };
+								}
+								return task;
+							});
+							saveRunTasks(fullLoaded.manifest, repairedTasks);
+							updateRunStatus(fullLoaded.manifest, "cancelled", "Orphaned run: worker process dead and no recent activity");
+						}
+					} catch {
+						// Best-effort manifest cleanup
+					}
+					unregisterActiveRun(entry.runId);
+					purged.push(entry.runId);
+					continue;
+				}
+			}
+		}
+
+		kept.push(entry.runId);
+	}
+
+	return { purged, kept };
+}
+
 export function reconcileAllStaleRuns(cwd: string, manifestCache: ManifestCache, now = Date.now()): ReconcileResult[] {
 	const results: ReconcileResult[] = [];
 	for (const manifest of manifestCache.list(50)) {

package/src/runtime/crew-agent-records.ts

@@ -81,7 +81,20 @@ function setAsyncAgentReaderCache(filePath: string, entry: { expiresAt: number;
 
 export function readCrewAgents(manifest: TeamRunManifest): CrewAgentRecord[] {
 	try {
-		return readJsonFileCoalesced(agentsPath(manifest), AGENT_READER_TTL_MS, () => readJsonFile<CrewAgentRecord[]>(agentsPath(manifest)) ?? []);
+		const records = readJsonFileCoalesced(agentsPath(manifest), AGENT_READER_TTL_MS, () => readJsonFile<CrewAgentRecord[]>(agentsPath(manifest)) ?? []);
+		// Validate schema and deduplicate by id to handle concurrent write conflicts
+		const seen = new Set<string>();
+		const deduped = records.filter((r) => {
+			if (!r || typeof r.id !== "string" || typeof r.taskId !== "string") return false;
+			if (seen.has(r.id)) return false;
+			seen.add(r.id);
+			return true;
+		});
+		if (deduped.length !== records.length) {
+			// Schema mismatch or duplicates detected — save corrected state
+			saveCrewAgents(manifest, deduped);
+		}
+		return deduped;
 	} catch {
 		return [];
 	}
@@ -96,9 +109,20 @@ export async function readCrewAgentsAsync(manifest: TeamRunManifest): Promise<Cr
 	const inFlight = (async (): Promise<CrewAgentRecord[]> => {
 		try {
 			const parsed = JSON.parse(await fs.promises.readFile(filePath, "utf-8")) as unknown;
-			const records = Array.isArray(parsed) ? redactSecrets(parsed) as CrewAgentRecord[] : [];
-			setAsyncAgentReaderCache(filePath, { expiresAt: Date.now() + AGENT_READER_TTL_MS, records });
-			return records;
+			const raw = Array.isArray(parsed) ? redactSecrets(parsed) as CrewAgentRecord[] : [];
+			// Deduplicate by id to handle concurrent write conflicts
+			const seen = new Set<string>();
+			const deduped = raw.filter((r) => {
+				if (!r || typeof r.id !== "string" || typeof r.taskId !== "string") return false;
+				if (seen.has(r.id)) return false;
+				seen.add(r.id);
+				return true;
+			});
+			if (deduped.length !== raw.length) {
+				try { saveCrewAgents(manifest, deduped); } catch { /* best-effort */ }
+			}
+			setAsyncAgentReaderCache(filePath, { expiresAt: Date.now() + AGENT_READER_TTL_MS, records: deduped });
+			return deduped;
 		} catch {
 			setAsyncAgentReaderCache(filePath, { expiresAt: Date.now() + AGENT_READER_TTL_MS, records: [] });
 			return [];
@@ -117,9 +141,13 @@ export function saveCrewAgents(manifest: TeamRunManifest, records: CrewAgentReco
 }
 
 export function upsertCrewAgent(manifest: TeamRunManifest, record: CrewAgentRecord): void {
-	const records = readCrewAgents(manifest).filter((item) => item.id !== record.id);
-	records.push(record);
-	saveCrewAgents(manifest, records);
+	// Read current state
+	const existing = readCrewAgents(manifest);
+	// Deduplicate by id: keep newer record when same id appears
+	const idIndex = new Map(existing.map((item, i) => [item.id, i]));
+	const merged: CrewAgentRecord[] = existing.map((item) => item.id === record.id ? record : item);
+	if (!idIndex.has(record.id)) merged.push(record);
+	saveCrewAgents(manifest, merged);
 	writeCrewAgentStatus(manifest, record);
 }
 

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

@@ -23,6 +23,7 @@ export interface CrewAgentProgress {
 	lastActivityAt?: string;
 	activityState?: CrewActivityState;
 	failedTool?: string;
+	consecutiveFailures?: number;
 }
 
 export interface CrewAgentRecord {

package/src/runtime/custom-tools/irc-tool.ts

@@ -0,0 +1,201 @@
+/**
+ * G1: Custom tool — irc.
+ *
+ * Registers a real `irc` tool in the Pi SDK session so that
+ * live-session workers can send messages to other live agents.
+ *
+ * Operations:
+ * - `list`: List currently visible peer agents
+ * - `send`: Send a message to a specific agent or broadcast to all
+ *
+ * Adapted from oh-my-pi's `IrcTool` pattern. Uses the live-agent-manager
+ * for routing messages between in-process workers.
+ */
+
+import { defineTool, type ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { Type, type Static } from "@sinclair/typebox";
+import { listLiveAgents, sendIrcMessage, broadcastIrcMessage } from "../live-agent-manager.ts";
+import type { IrcMessage } from "../live-irc.ts";
+
+const IrcParams = Type.Object({
+	op: Type.Union(
+		[
+			Type.Literal("send", { description: "Send a message to one peer or to all peers." }),
+			Type.Literal("list", { description: "List currently visible peers." }),
+		],
+		{ description: "IRC operation." },
+	),
+	to: Type.Optional(
+		Type.String({
+			description: 'Recipient agent ID or "all" to broadcast.',
+		}),
+	),
+	message: Type.Optional(
+		Type.String({
+			description: "Message body to deliver.",
+		}),
+	),
+	awaitReply: Type.Optional(
+		Type.Boolean({
+			description: "Wait for a reply (default: true for DM, false for broadcast). Not yet supported — messages are fire-and-forget.",
+		}),
+	),
+});
+
+type IrcParams = Static<typeof IrcParams>;
+
+interface IrcDetails {
+	op: "send" | "list";
+	from?: string;
+	to?: string;
+	delivered?: string[];
+	notFound?: string[];
+	peers?: Array<{ id: string; status: string }>;
+	error?: string;
+}
+
+/**
+ * Create an `irc` tool definition for a specific agent.
+ *
+ * @param selfId — This agent's ID (runId:taskId format)
+ */
+export function createIrcTool(
+	selfId: string,
+): ToolDefinition<typeof IrcParams, IrcDetails> {
+	return defineTool({
+		name: "irc",
+		label: "IRC",
+		description:
+			"Send messages to other live agents in same team. " +
+			'Use `op: "list"` to see peers, `op: "send"` with `to` (agent ID or "all") and `message` to communicate.',
+		parameters: IrcParams,
+		promptSnippet: "Send messages to other live agents via the irc tool",
+		promptGuidelines: [
+			"Use irc to coordinate with other agents when you need information or want to share findings.",
+			'Use `op: "list"` first to discover available peers.',
+		],
+		async execute(
+			_toolCallId: string,
+			params: IrcParams,
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			_ctx: unknown,
+		): Promise<{ content: Array<{ type: "text"; text: string }>; details: IrcDetails }> {
+			if (params.op === "list") {
+				return executeList(selfId);
+			}
+			if (params.op === "send") {
+				return executeSend(selfId, params);
+			}
+			return {
+				content: [{ type: "text", text: "Unknown irc op." }],
+				details: { op: params.op, from: selfId, error: "Unknown operation." },
+			};
+		},
+	});
+}
+
+function executeList(selfId: string): { content: Array<{ type: "text"; text: string }>; details: IrcDetails } {
+	const agents = listLiveAgents();
+	const peers = agents
+		.filter((a) => a.agentId !== selfId && (a.status === "running" || a.status === "queued"))
+		.map((a) => ({ id: a.agentId, status: a.status }));
+
+	const lines: string[] = [];
+	if (peers.length === 0) {
+		lines.push("No other live agents.");
+	} else {
+		lines.push(`${peers.length} peer(s):`);
+		for (const peer of peers) {
+			lines.push(`- ${peer.id} (${peer.status})`);
+		}
+	}
+
+	return {
+		content: [{ type: "text", text: lines.join("\n") }],
+		details: { op: "list", from: selfId, peers },
+	};
+}
+
+function executeSend(
+	selfId: string,
+	params: IrcParams,
+): { content: Array<{ type: "text"; text: string }>; details: IrcDetails } {
+	const to = params.to?.trim();
+	const message = params.message?.trim();
+
+	if (!to) {
+		return {
+			content: [{ type: "text", text: '`to` is required for op="send".' }],
+			details: { op: "send", from: selfId, error: "Missing 'to' field." },
+		};
+	}
+	if (!message) {
+		return {
+			content: [{ type: "text", text: '`message` is required for op="send".' }],
+			details: { op: "send", from: selfId, to, error: "Missing 'message' field." },
+		};
+	}
+	if (to === selfId) {
+		return {
+			content: [{ type: "text", text: "Cannot send a message to yourself." }],
+			details: { op: "send", from: selfId, to, error: "Self-message not allowed." },
+		};
+	}
+
+	const ircMessage: IrcMessage = {
+		from: selfId,
+		to,
+		content: message,
+		timestamp: new Date().toISOString(),
+		awaitReply: params.awaitReply,
+	};
+
+	const notFound: string[] = [];
+	const delivered: string[] = [];
+
+	try {
+		if (to === "all") {
+			const recipients = broadcastIrcMessage(selfId, ircMessage);
+			delivered.push(...recipients);
+		} else {
+			// DM to specific agent
+			const agents = listLiveAgents();
+			const target = agents.find((a) => a.agentId === to);
+			if (!target || (target.status !== "running" && target.status !== "queued")) {
+				notFound.push(to);
+			} else {
+				try {
+					sendIrcMessage(to, ircMessage);
+					delivered.push(to);
+				} catch {
+					notFound.push(to);
+				}
+			}
+		}
+	} catch {
+		// Agent deregistered during routing — treat as not found
+		notFound.push(to);
+	}
+
+	const lines: string[] = [];
+	if (delivered.length > 0) {
+		lines.push(`Delivered to ${delivered.length} peer(s): ${delivered.join(", ")}`);
+	} else {
+		lines.push("No recipients received the message.");
+	}
+	if (notFound.length > 0) {
+		lines.push(`Unknown / unavailable peers: ${notFound.join(", ")}`);
+	}
+
+	return {
+		content: [{ type: "text", text: lines.join("\n") }],
+		details: {
+			op: "send",
+			from: selfId,
+			to,
+			delivered: delivered.length > 0 ? delivered : undefined,
+			notFound: notFound.length > 0 ? notFound : undefined,
+		},
+	};
+}

package/src/runtime/custom-tools/submit-result-tool.ts

@@ -0,0 +1,90 @@
+/**
+ * G1: Custom tool — submit_result.
+ *
+ * Registers a real `submit_result` tool in the Pi SDK session so that
+ * live-session workers can yield their result by calling a tool (instead of
+ * relying solely on prompt-based reminders).
+ *
+ * Adapted from oh-my-pi's `YieldTool` pattern. Uses Pi SDK's `defineTool()`
+ * and TypeBox schemas for validation.
+ */
+
+import { defineTool, type ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { Type, type Static } from "@sinclair/typebox";
+import type { YieldResult } from "../yield-handler.ts";
+
+const SubmitResultParams = Type.Object({
+	summary: Type.String({ description: "Summary of completed work." }),
+	artifacts: Type.Optional(
+		Type.Record(Type.String(), Type.String(), {
+			description: "Key-value map of artifact labels to file paths or content.",
+		}),
+	),
+	structuredData: Type.Optional(
+		Type.Record(Type.String(), Type.Unknown(), {
+			description: "Structured key-value data to pass back to the orchestrator.",
+		}),
+	),
+});
+
+type SubmitResultParams = Static<typeof SubmitResultParams>;
+
+interface SubmitResultDetails {
+	summary: string;
+	artifacts?: Record<string, string>;
+	structuredData?: Record<string, unknown>;
+}
+
+/**
+ * Create a `submit_result` tool definition that calls `onYield` when invoked.
+ *
+ * The tool is injected into the session via `createAgentSession({ customTools: [...] })`.
+ * When the model calls it, the result is captured via the `onYield` callback
+ * and the yield enforcement loop terminates.
+ */
+export function createSubmitResultTool(
+	onYield: (result: YieldResult) => void,
+): ToolDefinition<typeof SubmitResultParams, SubmitResultDetails> {
+	return defineTool({
+		name: "submit_result",
+		label: "Submit Result",
+		description:
+			"Submit final task result. Call when task complete. " +
+			"Provide summary, optional artifacts (file paths/content), optional structured data.",
+		parameters: SubmitResultParams,
+		promptSnippet: "Submit your task result when done using submit_result",
+		promptGuidelines: [
+			"Always call submit_result when your task is complete, even if you were unable to finish.",
+			"Include a clear summary of what was accomplished.",
+		],
+		async execute(
+			toolCallId: string,
+			params: SubmitResultParams,
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			_ctx: unknown,
+		): Promise<{ content: Array<{ type: "text"; text: string }>; details: SubmitResultDetails }> {
+			const result: YieldResult = {
+				summary: params.summary,
+				toolCallId,
+				...(params.artifacts ? { artifacts: params.artifacts } : {}),
+				...(params.structuredData ? { structuredData: params.structuredData } : {}),
+			};
+			// Build response first so the model always gets confirmation
+			const response: { content: Array<{ type: "text"; text: string }>; details: SubmitResultDetails } = {
+				content: [{ type: "text", text: "Result submitted successfully. Thank you." }],
+				details: {
+					summary: params.summary,
+					artifacts: params.artifacts,
+					structuredData: params.structuredData,
+				},
+			};
+			try {
+				onYield(result);
+			} catch {
+				// Yield handler failure should not prevent tool response
+			}
+			return response;
+		},
+	});
+}

package/src/runtime/delivery-coordinator.ts

@@ -102,8 +102,10 @@ export class DeliveryCoordinator {
 
 	flushQueuedResults(): void {
 		if (!this.active || this.pending.length === 0) return;
-		const batch = this.pending.splice(0);
+		// H7: Set flushing BEFORE splice to prevent re-entrancy
+		if (this.flushing) return;
 		this.flushing = true;
+		const batch = this.pending.splice(0);
 		try {
 			const retryLater: PendingDelivery[] = [];
 			for (const delivery of batch) {

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 }],
+		},
+	};
+}