pi-subagents 0.29.0 → 0.31.0

package/src/runs/background/async-job-tracker.ts

@@ -26,6 +26,10 @@ interface AsyncJobTrackerOptions {
 	now?: () => number;
 }
 
+const CONTROL_EVENT_READ_CHUNK_BYTES = 64 * 1024;
+const MAX_CONTROL_EVENT_LINE_BYTES = 1024 * 1024;
+const CONTROL_EVENT_SCAN_WINDOW_BYTES = 2 * 1024 * 1024;
+
 export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: SubagentState, asyncDirRoot: string, options: AsyncJobTrackerOptions = {}): {
 	ensurePoller: () => void;
 	handleStarted: (data: unknown) => void;
@@ -68,25 +72,24 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		}
 		try {
 			const stat = fs.fstatSync(fd);
-			const cursor = stat.size < (job.controlEventCursor ?? 0) ? 0 : (job.controlEventCursor ?? 0);
+			const savedCursor = job.controlEventCursor;
+			let cursor = stat.size < (savedCursor ?? 0) ? 0 : (savedCursor ?? 0);
+			const startedFromTail = savedCursor === undefined && stat.size > CONTROL_EVENT_SCAN_WINDOW_BYTES;
+			if (startedFromTail) cursor = stat.size - CONTROL_EVENT_SCAN_WINDOW_BYTES;
 			if (stat.size <= cursor) return;
-			const buffer = Buffer.alloc(stat.size - cursor);
-			fs.readSync(fd, buffer, 0, buffer.length, cursor);
-			const lastNewline = buffer.lastIndexOf(0x0a);
-			if (lastNewline === -1) return;
-			job.controlEventCursor = cursor + lastNewline + 1;
-			for (const line of buffer.subarray(0, lastNewline).toString("utf-8").split("\n")) {
-				if (!line.trim()) continue;
+			const scanEnd = Math.min(stat.size, cursor + CONTROL_EVENT_SCAN_WINDOW_BYTES);
+			const handleLine = (line: string) => {
+				if (!line.trim()) return;
 				let parsed: unknown;
 				try {
 					parsed = JSON.parse(line);
 				} catch (error) {
 					console.error(`Ignoring malformed async control event in '${eventsPath}':`, error);
-					continue;
+					return;
 				}
-				if (!parsed || typeof parsed !== "object" || (parsed as { type?: unknown }).type !== "subagent.control") continue;
+				if (!parsed || typeof parsed !== "object" || (parsed as { type?: unknown }).type !== "subagent.control") return;
 				const record = parsed as { event?: ControlEvent; channels?: string[]; childIntercomTarget?: string; noticeText?: string; intercom?: { to?: string; message?: string } };
-				if (!record.event || !Array.isArray(record.channels)) continue;
+				if (!record.event || !Array.isArray(record.channels)) return;
 				const payload = {
 					event: record.event,
 					source: "async" as const,
@@ -104,7 +107,48 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						message: record.intercom.message,
 					});
 				}
+			};
+			let readCursor = cursor;
+			let lastCompleteCursor = cursor;
+			let lineParts: Buffer[] = [];
+			let lineBytes = 0;
+			let skippingOversizedLine = startedFromTail;
+			const appendLineSegment = (segment: Buffer) => {
+				if (segment.length === 0 || skippingOversizedLine) return;
+				if (lineBytes + segment.length > MAX_CONTROL_EVENT_LINE_BYTES) {
+					lineParts = [];
+					lineBytes = 0;
+					skippingOversizedLine = true;
+					return;
+				}
+				lineParts.push(segment);
+				lineBytes += segment.length;
+			};
+			while (readCursor < scanEnd) {
+				const toRead = Math.min(CONTROL_EVENT_READ_CHUNK_BYTES, scanEnd - readCursor);
+				const buffer = Buffer.alloc(toRead);
+				const bytesRead = fs.readSync(fd, buffer, 0, toRead, readCursor);
+				if (bytesRead <= 0) break;
+				const chunk = bytesRead === buffer.length ? buffer : buffer.subarray(0, bytesRead);
+				let lineStart = 0;
+				for (let index = 0; index < chunk.length; index++) {
+					if (chunk[index] !== 0x0a) continue;
+					appendLineSegment(chunk.subarray(lineStart, index));
+					if (!skippingOversizedLine && lineBytes > 0) {
+						handleLine(Buffer.concat(lineParts, lineBytes).toString("utf-8"));
+					}
+					lineParts = [];
+					lineBytes = 0;
+					skippingOversizedLine = false;
+					lastCompleteCursor = readCursor + index + 1;
+					lineStart = index + 1;
+				}
+				appendLineSegment(chunk.subarray(lineStart));
+				readCursor += bytesRead;
+				if (skippingOversizedLine) job.controlEventCursor = readCursor;
 			}
+			if (lastCompleteCursor > cursor) job.controlEventCursor = lastCompleteCursor;
+			else if (scanEnd < stat.size || startedFromTail) job.controlEventCursor = scanEnd;
 		} catch (error) {
 			console.error(`Failed to read async control events for '${job.asyncDir}':`, error);
 		} finally {
@@ -261,6 +305,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			activeParallelGroup: Boolean(firstGroupCount && firstGroupCount > 0),
 			startedAt: now,
 			updatedAt: now,
+			controlEventCursor: 0,
 		});
 		ensurePoller();
 		if (state.lastUiContext) {

package/src/runs/background/async-resume.ts

@@ -1,9 +1,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus } from "../../shared/types.ts";
+import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type SubagentState } from "../../shared/types.ts";
 import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
 import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
 
+export const ASYNC_RESUME_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
+
 export interface AsyncResumeParams {
 	id?: string;
 	runId?: string;
@@ -18,6 +20,10 @@ export interface AsyncResumeDeps {
 	now?: () => number;
 }
 
+export interface AsyncResumeOptions {
+	requireSessionFile?: boolean;
+}
+
 export type AsyncResumeTarget = {
 	kind: "live" | "revive";
 	runId: string;
@@ -30,6 +36,47 @@ export type AsyncResumeTarget = {
 	sessionFile?: string;
 };
 
+type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+
+function readAsyncStatus(asyncDir: string): AsyncStatus | null {
+	const statusPath = path.join(asyncDir, "status.json");
+	try {
+		return JSON.parse(fs.readFileSync(statusPath, "utf-8")) as AsyncStatus;
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
+		if (code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+export function interruptLiveAsyncResumeTarget(input: {
+	target: AsyncResumeTarget & { kind: "live" };
+	state?: Pick<SubagentState, "asyncJobs">;
+	kill?: KillFn;
+	now?: () => number;
+}): { ok: true; asyncId: string } | { ok: false; message: string } {
+	const asyncId = input.target.runId;
+	if (!input.target.asyncDir) {
+		return { ok: false, message: `Async run ${asyncId} is live but does not have an async directory to interrupt.` };
+	}
+	const status = readAsyncStatus(input.target.asyncDir);
+	if (!status || status.state !== "running" || typeof status.pid !== "number") {
+		return { ok: false, message: `Async run ${asyncId} is live but no interrupt-capable runner pid was found.` };
+	}
+	try {
+		(input.kill ?? process.kill)(status.pid, ASYNC_RESUME_INTERRUPT_SIGNAL);
+		const tracked = input.state?.asyncJobs.get(asyncId);
+		if (tracked) {
+			tracked.activityState = undefined;
+			tracked.updatedAt = input.now?.() ?? Date.now();
+		}
+		return { ok: true, asyncId };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, message: `Failed to interrupt async run ${asyncId}: ${message}` };
+	}
+}
+
 interface AsyncResultFile {
 	id?: string;
 	runId?: string;
@@ -236,9 +283,10 @@ function validateResumeSessionFile(runId: string, sessionFile: string): string {
 	return resolved;
 }
 
-export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncResumeDeps = {}): AsyncResumeTarget {
+export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncResumeDeps = {}, options: AsyncResumeOptions = {}): AsyncResumeTarget {
 	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
 	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+	const requireSessionFile = options.requireSessionFile ?? true;
 	const location = resolveAsyncRunLocation(params, asyncDirRoot, resultsDir);
 	if (!location.asyncDir && !location.resultPath) {
 		throw new Error("Async run not found. Provide id or dir.");
@@ -313,8 +361,8 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 	const sessionFile = statusSteps[index]?.sessionFile
 		?? resultSteps[index]?.sessionFile
 		?? (stepCount === 1 ? status?.sessionFile ?? result?.sessionFile : undefined);
-	if (!sessionFile) throw new Error(`Async run '${runId}' child ${index} does not have a persisted session file to resume from.`);
-	const resolvedSessionFile = validateResumeSessionFile(runId, sessionFile);
+	if (!sessionFile && requireSessionFile) throw new Error(`Async run '${runId}' child ${index} does not have a persisted session file to resume from.`);
+	const resolvedSessionFile = sessionFile ? validateResumeSessionFile(runId, sessionFile) : undefined;
 
 	return {
 		kind: "revive",
@@ -325,7 +373,7 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 		index,
 		intercomTarget: resolveSubagentIntercomTarget(runId, agent, index),
 		cwd: status?.cwd ?? result?.cwd,
-		sessionFile: resolvedSessionFile,
+		...(resolvedSessionFile ? { sessionFile: resolvedSessionFile } : {}),
 	};
 }
 

package/src/runs/background/async-status.ts

@@ -56,6 +56,7 @@ export interface AsyncRunSummary {
 	endedAt?: number;
 	currentStep?: number;
 	chainStepCount?: number;
+	pendingAppends?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	steps: AsyncRunStepSummary[];
 	sessionDir?: string;
@@ -188,6 +189,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		endedAt: status.endedAt,
 		currentStep: status.currentStep,
 		...(status.chainStepCount !== undefined ? { chainStepCount: status.chainStepCount } : {}),
+		...(status.pendingAppends !== undefined ? { pendingAppends: status.pendingAppends } : {}),
 		...(parallelGroups.length ? { parallelGroups } : {}),
 		steps: summarizedSteps,
 		...(nestedChildren.length ? { nestedChildren } : {}),
@@ -309,7 +311,8 @@ function formatRunHeader(run: AsyncRunSummary): string {
 	const stepLabel = formatAsyncRunProgressLabel(run);
 	const cwd = run.cwd ? shortenPath(run.cwd) : shortenPath(run.asyncDir);
 	const activity = formatActivityFacts(run);
-	return `${run.id} | ${run.state}${activity ? ` | ${activity}` : ""} | ${run.mode} | ${stepLabel} | ${cwd}`;
+	const pending = run.pendingAppends ? ` | ${run.pendingAppends} pending append${run.pendingAppends === 1 ? "" : "s"}` : "";
+	return `${run.id} | ${run.state}${activity ? ` | ${activity}` : ""} | ${run.mode} | ${stepLabel}${pending} | ${cwd}`;
 }
 
 export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active async runs"): string {

package/src/runs/background/chain-append.ts

@@ -0,0 +1,282 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { appendJsonl } from "../../shared/artifacts.ts";
+import type { AsyncParallelGroupStatus, AsyncStatus, WorkflowGraphNode, WorkflowGraphSnapshot } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+import type { DynamicRunnerGroup, ParallelStepGroup, RunnerStep, RunnerSubagentStep } from "../shared/parallel-utils.ts";
+import { isDynamicRunnerGroup, isParallelGroup } from "../shared/parallel-utils.ts";
+
+const APPEND_REQUESTS_DIR = "append-requests";
+
+export interface ChainAppendRequest {
+	id: string;
+	createdAt: number;
+	steps: RunnerStep[];
+}
+
+export interface ChainAppendResult {
+	request: ChainAppendRequest;
+	pendingCount: number;
+}
+
+type StatusStep = NonNullable<AsyncStatus["steps"]>[number];
+
+function appendDir(asyncDir: string): string {
+	return path.join(asyncDir, APPEND_REQUESTS_DIR);
+}
+
+function appendRequestPath(asyncDir: string, request: ChainAppendRequest): string {
+	return path.join(appendDir(asyncDir), `${request.createdAt}-${request.id}.json`);
+}
+
+function listAppendRequestFiles(asyncDir: string): string[] {
+	const dir = appendDir(asyncDir);
+	try {
+		return fs.readdirSync(dir)
+			.filter((entry) => entry.endsWith(".json"))
+			.map((entry) => path.join(dir, entry))
+			.sort();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+export function countPendingChainAppendRequests(asyncDir: string): number {
+	return listAppendRequestFiles(asyncDir).length;
+}
+
+export function runnerStepOutputNames(steps: RunnerStep[]): string[] {
+	const names: string[] = [];
+	for (const step of steps) {
+		if (isParallelGroup(step)) {
+			names.push(...step.parallel.map((task) => task.outputName).filter((name): name is string => Boolean(name)));
+		} else if (isDynamicRunnerGroup(step)) {
+			if (step.collect.as) names.push(step.collect.as);
+		} else if (step.outputName) {
+			names.push(step.outputName);
+		}
+	}
+	return names;
+}
+
+export function enqueueChainAppendRequest(input: {
+	asyncDir: string;
+	runId: string;
+	steps: RunnerStep[];
+	now?: number;
+}): ChainAppendResult {
+	const status = readStatus(input.asyncDir);
+	if (!status) throw new Error(`No async run status found for '${input.runId}'.`);
+	if (status.runId !== input.runId) throw new Error(`Async run id mismatch: expected '${input.runId}', found '${status.runId}'.`);
+	if (status.mode !== "chain") throw new Error(`Run '${input.runId}' is ${status.mode}; only active chain runs accept appended steps.`);
+	if (status.state !== "running") throw new Error(`Run '${input.runId}' is ${status.state}; only running chain runs accept appended steps.`);
+	const stillInProgress = (status.steps ?? []).some((step) => step.status === "running" || step.status === "pending") || (status.pendingAppends ?? 0) > 0;
+	if (!stillInProgress) throw new Error(`Run '${input.runId}' has no running or pending chain steps left; append-step must target an in-progress chain.`);
+	if (input.steps.length === 0) throw new Error("append-step requires one chain step.");
+
+	const request: ChainAppendRequest = {
+		id: randomUUID(),
+		createdAt: input.now ?? Date.now(),
+		steps: input.steps,
+	};
+	fs.mkdirSync(appendDir(input.asyncDir), { recursive: true });
+	writeAtomicJson(appendRequestPath(input.asyncDir, request), request);
+	const pendingCount = countPendingChainAppendRequests(input.asyncDir);
+	const statusPath = path.join(input.asyncDir, "status.json");
+	const updatedStatus = { ...status, pendingAppends: pendingCount, lastUpdate: request.createdAt };
+	writeAtomicJson(statusPath, updatedStatus);
+	appendJsonl(path.join(input.asyncDir, "events.jsonl"), JSON.stringify({
+		type: "subagent.chain.append.requested",
+		ts: request.createdAt,
+		runId: input.runId,
+		requestId: request.id,
+		stepCount: input.steps.length,
+		pendingAppends: pendingCount,
+	}));
+	return { request, pendingCount };
+}
+
+function readAppendRequest(filePath: string): ChainAppendRequest | undefined {
+	const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Partial<ChainAppendRequest>;
+	if (!raw.id || typeof raw.id !== "string") return undefined;
+	if (!Number.isFinite(raw.createdAt)) return undefined;
+	if (!Array.isArray(raw.steps) || raw.steps.length === 0) return undefined;
+	return { id: raw.id, createdAt: raw.createdAt, steps: raw.steps as RunnerStep[] };
+}
+
+export function readPendingChainAppendRequests(asyncDir: string): ChainAppendRequest[] {
+	return listAppendRequestFiles(asyncDir)
+		.map((filePath) => readAppendRequest(filePath))
+		.filter((request): request is ChainAppendRequest => Boolean(request))
+		.sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id));
+}
+
+export function consumeChainAppendRequests(asyncDir: string): ChainAppendRequest[] {
+	const requests: ChainAppendRequest[] = [];
+	for (const filePath of listAppendRequestFiles(asyncDir)) {
+		const request = readAppendRequest(filePath);
+		try {
+			fs.unlinkSync(filePath);
+		} catch {
+			// The runner should not execute a consumed request twice.
+		}
+		if (request) requests.push(request);
+	}
+	return requests.sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id));
+}
+
+function statusStepForTask(task: RunnerSubagentStep): StatusStep {
+	return {
+		agent: task.agent,
+		phase: task.phase,
+		label: task.label,
+		outputName: task.outputName,
+		structured: task.structured,
+		status: "pending",
+		...(task.sessionFile ? { sessionFile: task.sessionFile } : {}),
+		skills: task.skills,
+		model: task.model,
+		thinking: task.thinking,
+		attemptedModels: task.modelCandidates && task.modelCandidates.length > 0 ? task.modelCandidates : task.model ? [task.model] : undefined,
+		recentTools: [],
+		recentOutput: [],
+	};
+}
+
+function statusStepsForRunnerStep(step: RunnerStep): StatusStep[] {
+	if (isParallelGroup(step)) return step.parallel.map(statusStepForTask);
+	if (isDynamicRunnerGroup(step)) {
+		return [{
+			agent: `expand:${step.parallel.agent}`,
+			phase: step.phase ?? step.parallel.phase,
+			label: step.label ?? step.parallel.label ?? `Dynamic fanout (${step.collect.as})`,
+			outputName: step.collect.as,
+			structured: Boolean(step.collect.outputSchema),
+			status: "pending",
+			recentTools: [],
+			recentOutput: [],
+		}];
+	}
+	return [statusStepForTask(step)];
+}
+
+function pushPhase(graph: WorkflowGraphSnapshot, phase: string | undefined, nodeId: string): void {
+	if (!phase) return;
+	let group = graph.phases.find((candidate) => candidate.title === phase);
+	if (!group) {
+		group = { title: phase, nodeIds: [] };
+		graph.phases.push(group);
+	}
+	group.nodeIds.push(nodeId);
+}
+
+function graphNodeForSequential(step: RunnerSubagentStep, stepIndex: number, flatIndex: number): WorkflowGraphNode {
+	return {
+		id: `step-${stepIndex}`,
+		kind: "step",
+		agent: step.agent,
+		phase: step.phase,
+		label: step.label?.trim() || step.agent || `Step ${stepIndex + 1}`,
+		status: "pending",
+		flatIndex,
+		stepIndex,
+		outputName: step.outputName,
+		structured: step.structured,
+	};
+}
+
+function graphNodeForParallel(step: ParallelStepGroup, stepIndex: number, flatIndex: number, graph: WorkflowGraphSnapshot): WorkflowGraphNode {
+	const children = step.parallel.map((task, taskIndex) => {
+		const childId = `step-${stepIndex}-agent-${taskIndex}`;
+		pushPhase(graph, task.phase, childId);
+		return {
+			id: childId,
+			kind: "agent" as const,
+			agent: task.agent,
+			phase: task.phase,
+			label: task.label?.trim() || task.agent || `Agent ${taskIndex + 1}`,
+			status: "pending" as const,
+			flatIndex: flatIndex + taskIndex,
+			stepIndex,
+			outputName: task.outputName,
+			structured: task.structured,
+		};
+	});
+	return {
+		id: `step-${stepIndex}`,
+		kind: "parallel-group",
+		label: step.parallel.length === 1 ? "Parallel task" : `Parallel group (${step.parallel.length})`,
+		status: "pending",
+		stepIndex,
+		children,
+	};
+}
+
+function graphNodeForDynamic(step: DynamicRunnerGroup, stepIndex: number): WorkflowGraphNode {
+	return {
+		id: `step-${stepIndex}`,
+		kind: "dynamic-parallel-group",
+		label: step.label?.trim() || step.parallel.label?.trim() || `Dynamic fanout (${step.collect.as})`,
+		status: "pending",
+		stepIndex,
+		outputName: step.collect.as,
+		structured: Boolean(step.collect.outputSchema),
+		dynamic: {
+			sourceOutput: step.expand.from.output,
+			sourcePath: step.expand.from.path,
+			itemName: step.expand.item ?? "item",
+			maxItems: step.expand.maxItems,
+			collectAs: step.collect.as,
+		},
+		children: [],
+	};
+}
+
+function appendWorkflowNode(graph: WorkflowGraphSnapshot | undefined, step: RunnerStep, stepIndex: number, flatIndex: number): void {
+	if (!graph) return;
+	if (isParallelGroup(step)) {
+		graph.nodes.push(graphNodeForParallel(step, stepIndex, flatIndex, graph));
+		return;
+	}
+	if (isDynamicRunnerGroup(step)) {
+		graph.nodes.push(graphNodeForDynamic(step, stepIndex));
+		return;
+	}
+	const node = graphNodeForSequential(step, stepIndex, flatIndex);
+	graph.nodes.push(node);
+	pushPhase(graph, step.phase, node.id);
+}
+
+export function appendRunnerStepsToStatus(input: {
+	status: AsyncStatus;
+	steps: RunnerStep[];
+	now?: number;
+	pendingAppends?: number;
+}): { addedChainSteps: number; addedFlatSteps: number } {
+	let addedChainSteps = 0;
+	let addedFlatSteps = 0;
+	for (const step of input.steps) {
+		const stepIndex = input.status.chainStepCount ?? input.status.steps?.length ?? 0;
+		const flatIndex = input.status.steps?.length ?? 0;
+		const statusSteps = statusStepsForRunnerStep(step);
+		input.status.steps ??= [];
+		input.status.steps.push(...statusSteps);
+		if (isParallelGroup(step)) {
+			input.status.parallelGroups ??= [];
+			input.status.parallelGroups.push({ start: flatIndex, count: step.parallel.length, stepIndex });
+		} else if (isDynamicRunnerGroup(step)) {
+			input.status.parallelGroups ??= [];
+			input.status.parallelGroups.push({ start: flatIndex, count: 1, stepIndex });
+		}
+		appendWorkflowNode(input.status.workflowGraph, step, stepIndex, flatIndex);
+		input.status.chainStepCount = stepIndex + 1;
+		addedChainSteps++;
+		addedFlatSteps += statusSteps.length;
+	}
+	input.status.pendingAppends = input.pendingAppends ?? 0;
+	input.status.lastUpdate = input.now ?? Date.now();
+	return { addedChainSteps, addedFlatSteps };
+}

package/src/runs/background/chain-root-attachment.ts

@@ -0,0 +1,161 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AcceptanceLedger, AsyncStatus, ModelAttempt } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+
+export interface ImportedAsyncRoot {
+	runId: string;
+	asyncDir: string;
+	resultPath: string;
+	index: number;
+}
+
+export interface ImportedAsyncRootResult {
+	agent: string;
+	output: string;
+	success: boolean;
+	exitCode: number;
+	error?: string;
+	sessionFile?: string;
+	intercomTarget?: string;
+	model?: string;
+	attemptedModels?: string[];
+	modelAttempts?: ModelAttempt[];
+	structuredOutput?: unknown;
+	structuredOutputPath?: string;
+	structuredOutputSchemaPath?: string;
+	acceptance?: AcceptanceLedger;
+}
+
+interface AsyncResultFile {
+	state?: string;
+	success?: boolean;
+	summary?: string;
+	results?: Array<{
+		agent?: string;
+		output?: string;
+		error?: string;
+		success?: boolean;
+		sessionFile?: string;
+		intercomTarget?: string;
+		model?: string;
+		attemptedModels?: string[];
+		modelAttempts?: ModelAttempt[];
+		structuredOutput?: unknown;
+		structuredOutputPath?: string;
+		structuredOutputSchemaPath?: string;
+		acceptance?: AcceptanceLedger;
+	}>;
+}
+
+const TERMINAL_STATES = new Set(["complete", "failed", "paused"]);
+const TERMINAL_STEP_STATUSES = new Set(["complete", "completed", "failed", "paused"]);
+
+function readResultFile(resultPath: string): AsyncResultFile | undefined {
+	try {
+		return JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultFile;
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+			return undefined;
+		}
+		throw error;
+	}
+}
+
+function selectedStatusStep(status: AsyncStatus | null, index: number): NonNullable<AsyncStatus["steps"]>[number] | undefined {
+	return status?.steps?.[index];
+}
+
+function isTerminalStatus(status: AsyncStatus | null, index: number): boolean {
+	if (!status) return false;
+	const step = selectedStatusStep(status, index);
+	if (step && TERMINAL_STEP_STATUSES.has(step.status)) return true;
+	return TERMINAL_STATES.has(status.state);
+}
+
+function resultState(result: AsyncResultFile | undefined, child: NonNullable<AsyncResultFile["results"]>[number] | undefined): "complete" | "failed" | "paused" | undefined {
+	if (!result) return undefined;
+	if (child?.success === true) return "complete";
+	if (child?.success === false) return result.state === "paused" ? "paused" : "failed";
+	if (result.state === "complete" || result.state === "failed" || result.state === "paused") return result.state;
+	if (result.success === true) return "complete";
+	if (result.success === false) return "failed";
+	return undefined;
+}
+
+function outputFromTerminalStatus(root: ImportedAsyncRoot, status: AsyncStatus, step: NonNullable<AsyncStatus["steps"]>[number] | undefined): ImportedAsyncRootResult {
+	const agent = step?.agent ?? status.steps?.[root.index]?.agent ?? "subagent";
+	const message = step?.error ?? status.error ?? `Attached async root ${root.runId} ended without a result file at ${root.resultPath}.`;
+	return {
+		agent,
+		output: message,
+		success: false,
+		exitCode: 1,
+		error: message,
+		...(step?.sessionFile ?? status.sessionFile ? { sessionFile: step?.sessionFile ?? status.sessionFile } : {}),
+		...(step?.model ? { model: step.model } : {}),
+		...(step?.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
+		...(step?.modelAttempts ? { modelAttempts: step.modelAttempts } : {}),
+		...(step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
+		...(step?.structuredOutputPath ? { structuredOutputPath: step.structuredOutputPath } : {}),
+		...(step?.structuredOutputSchemaPath ? { structuredOutputSchemaPath: step.structuredOutputSchemaPath } : {}),
+		...(step?.acceptance ? { acceptance: step.acceptance } : {}),
+	};
+}
+
+function buildImportedResult(root: ImportedAsyncRoot, status: AsyncStatus | null, result: AsyncResultFile): ImportedAsyncRootResult {
+	const child = result.results?.[root.index];
+	const step = selectedStatusStep(status, root.index);
+	const state = resultState(result, child);
+	const agent = child?.agent ?? step?.agent ?? status?.steps?.[root.index]?.agent ?? "subagent";
+	const output = child?.output ?? result.summary ?? "";
+	const success = state === "complete";
+	const error = child?.error ?? (success ? undefined : result.summary ?? status?.error ?? `Attached async root ${root.runId} did not complete successfully.`);
+	return {
+		agent,
+		output: success ? output : (output || error || ""),
+		success,
+		exitCode: success ? 0 : 1,
+		...(error ? { error } : {}),
+		...(child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile ? { sessionFile: child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile } : {}),
+		...(child?.intercomTarget ? { intercomTarget: child.intercomTarget } : {}),
+		...(child?.model ?? step?.model ? { model: child?.model ?? step?.model } : {}),
+		...(child?.attemptedModels ?? step?.attemptedModels ? { attemptedModels: child?.attemptedModels ?? step?.attemptedModels } : {}),
+		...(child?.modelAttempts ?? step?.modelAttempts ? { modelAttempts: child?.modelAttempts ?? step?.modelAttempts } : {}),
+		...(child?.structuredOutput !== undefined ? { structuredOutput: child.structuredOutput } : step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
+		...(child?.structuredOutputPath ?? step?.structuredOutputPath ? { structuredOutputPath: child?.structuredOutputPath ?? step?.structuredOutputPath } : {}),
+		...(child?.structuredOutputSchemaPath ?? step?.structuredOutputSchemaPath ? { structuredOutputSchemaPath: child?.structuredOutputSchemaPath ?? step?.structuredOutputSchemaPath } : {}),
+		...(child?.acceptance ?? step?.acceptance ? { acceptance: child?.acceptance ?? step?.acceptance } : {}),
+	};
+}
+
+export async function waitForImportedAsyncRoot(
+	root: ImportedAsyncRoot,
+	options: { pollIntervalMs?: number; terminalResultGraceMs?: number; now?: () => number } = {},
+): Promise<ImportedAsyncRootResult> {
+	const pollIntervalMs = options.pollIntervalMs ?? 500;
+	const terminalResultGraceMs = options.terminalResultGraceMs ?? 1_000;
+	const now = options.now ?? Date.now;
+	let terminalSince: number | undefined;
+	for (;;) {
+		const status = readStatus(root.asyncDir);
+		const result = readResultFile(root.resultPath);
+		if (result) return buildImportedResult(root, status, result);
+		if (isTerminalStatus(status, root.index)) {
+			terminalSince ??= now();
+			if (now() - terminalSince >= terminalResultGraceMs) {
+				return outputFromTerminalStatus(root, status!, selectedStatusStep(status, root.index));
+			}
+		} else {
+			terminalSince = undefined;
+		}
+		if (!status && !fs.existsSync(root.asyncDir)) {
+			throw new Error(`Attached async root '${root.runId}' directory does not exist: ${root.asyncDir}`);
+		}
+		await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+	}
+}
+
+export function resolveAsyncRootResultPath(resultsDir: string, runId: string): string {
+	return path.join(resultsDir, `${runId}.json`);
+}