pi-subagents 0.58.0 → 0.60.0

package/src/runs/foreground/workflow-detach-reconcile.ts

@@ -9,8 +9,6 @@ import {
 	type IntercomEventBus,
 	type SingleResult,
 	type SubagentState,
-	type WorkflowRecoveryAction,
-	type WorkflowTerminalOutcome,
 	type WorkflowTerminalResolution,
 } from "../../shared/types.ts";
 import { updateActiveRunIndex } from "../background/active-run-index.ts";
@@ -19,130 +17,42 @@ import { resolveAsyncResumeTarget } from "../background/async-resume.ts";
 import { externalCliReceiptMetadata, normalizeExternalCliRunnerStatus } from "../shared/external-cli-contract.ts";
 import { outputPathMappingFromTask } from "../shared/single-output.ts";
 import { readWorkflowReceipt, workflowReceiptPath, writeWorkflowReceipt, type WorkflowReceipt } from "../../workflows/workflow-receipt.ts";
-import { workflowChildSummary } from "../../workflows/workflow-child-summary.ts";
-
-function cloneWorkflowStatus(status: AsyncStatus): AsyncStatus {
-	return {
-		...status,
-		steps: status.steps?.map((step) => ({ ...step })),
-		workflow: status.workflow ? { ...status.workflow, trace: [...(status.workflow.trace ?? [])] } : status.workflow,
-	};
-}
-
-function childSucceeded(result: Pick<SingleResult, "exitCode" | "error" | "interrupted">): boolean {
-	return result.exitCode === 0 && !result.error && !result.interrupted;
-}
-
-const UNSUPPORTED_DETACHED_WORKFLOW_CONTINUATION = "unsupported-continuation: detached workflow child settled, but JavaScript workflow continuation was not persisted. Resume the workflow explicitly instead of treating the completed child as top-level workflow completion.";
-const INTERRUPTED_DETACHED_CHILD = "Interrupted. Waiting for explicit next action.";
-type WorkflowStatusStep = NonNullable<AsyncStatus["steps"]>[number] & {
-	outputPathMapping?: { requestedPath: string; savedPath: string };
-	interrupted?: boolean;
-};
-
-function findWorkflowStep(status: AsyncStatus, childRunId: string, workflowKey?: string): WorkflowStatusStep | undefined {
-	return status.steps?.find((candidate) => candidate.runId === childRunId)
-		?? (workflowKey ? status.steps?.find((candidate) => candidate.workflowKey === workflowKey) : undefined) as WorkflowStatusStep | undefined;
-}
+import {
+	applyDetachedChildSettlement,
+	classifyWorkflowSettlement,
+	findWorkflowSettlementStep,
+	planWorkflowSettlement,
+	promoteSettledPausedWorkflow,
+	workflowOutputPathMappingSummary,
+	workflowRecoveryActions,
+	workflowTerminalOutcomeForResult,
+	type WorkflowPublicChild,
+	type WorkflowStatusStep,
+} from "../../workflows/workflow-settlement.ts";
 
 export function applyDetachedChildToPausedWorkflow(
 	status: AsyncStatus,
-	input: { childRunId: string; result: Pick<SingleResult, "exitCode" | "error" | "interrupted" | "sessionFile" | "stopped">; workflowKey?: string },
+	input: { childRunId: string; result: Pick<SingleResult, "exitCode" | "error" | "interrupted" | "sessionFile" | "sessionName" | "stopped">; workflowKey?: string },
 ): AsyncStatus | undefined {
-	if (status.mode !== "workflow" || status.state !== "paused") return undefined;
-	const next = cloneWorkflowStatus(status);
-	const step = findWorkflowStep(next, input.childRunId, input.workflowKey);
-	if (!step) return undefined;
-	const succeeded = childSucceeded(input.result);
-	const failedSiblingError = next.steps?.find((candidate) => {
-		const candidateStep = candidate as WorkflowStatusStep;
-		return candidateStep !== step && candidateStep.status === "failed" && !candidateStep.interrupted && candidateStep.error;
-	})?.error;
-	const interruptedChildError = next.steps?.find((candidate) => {
-		const candidateStep = candidate as WorkflowStatusStep;
-		return candidateStep.status === "failed" && candidateStep.interrupted && candidateStep.error;
-	})?.error;
-	const updatedAt = Date.now();
-	step.status = succeeded ? "completed" : "failed";
-	step.endedAt = updatedAt;
-	delete step.activityState;
-	delete step.currentTool;
-	delete step.currentToolStartedAt;
-	if (input.result.sessionFile) step.sessionFile = input.result.sessionFile;
-	if (succeeded) {
-		delete step.error;
-		delete step.interrupted;
-	} else if (input.result.interrupted || input.result.stopped) {
-		step.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
-		step.interrupted = true;
-		if (input.result.stopped) step.stopped = true;
-	} else {
-		delete step.interrupted;
-		delete step.stopped;
-		if (input.result.error) step.error = input.result.error;
-	}
-	next.lastUpdate = updatedAt;
-	const promoted = promotePausedWorkflowIfSettled(next);
-	if (promoted?.state === "failed" && failedSiblingError) promoted.error = failedSiblingError;
-	else if (promoted?.state === "failed" && (input.result.interrupted || input.result.stopped)) promoted.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
-	else if (promoted?.state === "failed" && input.result.error) promoted.error = input.result.error;
-	else if (promoted?.state === "failed" && interruptedChildError) promoted.error = interruptedChildError;
-	const resolved = promoted ?? next;
-	const workflowState = resolved.state === "complete" ? "completed" : resolved.state === "paused" ? "paused" : resolved.state === "stopped" ? "stopped" : "failed";
-	resolved.workflowChildren = workflowChildSummary({ parentToolCallId: resolved.toolCallId ?? resolved.runId, workflowRunId: resolved.runId, workflowState, inventoryComplete: true, trace: resolved.workflow?.trace, steps: resolved.steps });
-	return resolved;
+	return applyDetachedChildSettlement(status, input);
 }
 
 export function promotePausedWorkflowIfSettled(status: AsyncStatus): AsyncStatus | undefined {
-	if (status.mode !== "workflow" || status.state !== "paused") return undefined;
-	const next = cloneWorkflowStatus(status);
-	const stillOpen = next.steps?.some((candidate) =>
-		candidate.status === "running"
-		|| (candidate.status === "paused" && candidate.activityState === "needs_attention")
-	) === true;
-	if (stillOpen || !next.steps?.length) return undefined;
-	const failed = next.steps.some((candidate) => candidate.status === "failed");
-	const updatedAt = Date.now();
-	next.lastUpdate = updatedAt;
-	next.state = "failed";
-	next.endedAt = updatedAt;
-	delete next.activityState;
-	if (failed) return next;
-	next.error = UNSUPPORTED_DETACHED_WORKFLOW_CONTINUATION;
-	return next;
-}
-
-function workflowResolution(status: AsyncStatus, result: Pick<SingleResult, "interrupted">): WorkflowTerminalResolution | undefined {
-	if (status.state !== "complete" && status.state !== "failed") return undefined;
-	if (status.steps?.some((step) => {
-		const candidate = step as WorkflowStatusStep;
-		return candidate.status === "failed" && !candidate.interrupted;
-	})) return "failed-child";
-	if (result.interrupted || status.steps?.some((step) => {
-		const candidate = step as WorkflowStatusStep;
-		return candidate.status === "stopped" || candidate.stopped || candidate.interrupted || candidate.error === INTERRUPTED_DETACHED_CHILD;
-	})) return "interrupted-child";
-	return "settled-awaiting-resume";
-}
-
-function workflowRecovery(receipt: WorkflowReceipt | undefined): WorkflowRecoveryAction[] {
-	if (!receipt) return [];
-	return Object.values(receipt.entries).flatMap((entry) => entry.resumability.state === "resumable"
-		? [{ key: entry.key, call: "runs.run" as const, resume: { workflowRunId: receipt.workflowRunId, key: entry.key, latest: true as const }, taskRequired: true as const }]
-		: []);
+	return promoteSettledPausedWorkflow(status);
 }
 
-function resultTerminalOutcome(result: Pick<SingleResult, "timedOut" | "turnBudgetExceeded" | "toolBudgetBlocked">): WorkflowTerminalOutcome | undefined {
-	if (result.timedOut) return { state: "partial", reason: "timeout" };
-	if (result.turnBudgetExceeded || result.toolBudgetBlocked) return { state: "partial", reason: "budget_exhausted" };
-	return undefined;
+function usageWithValue(usage: SingleResult["usage"] | undefined): SingleResult["usage"] | undefined {
+	return usage && (usage.input !== 0 || usage.output !== 0 || usage.cacheRead !== 0 || usage.cacheWrite !== 0 || usage.cost !== 0 || usage.turns !== 0)
+		? usage
+		: undefined;
 }
 
 function workflowResultChildren(status: AsyncStatus, childRunId: string, result: SingleResult, existingResults: unknown, receipt?: WorkflowReceipt): unknown {
 	const output = getSingleResultOutput(result);
 	const outputReference = result.savedOutputPath ?? result.outputReference?.path;
 	const outputPathMapping = outputPathMappingFromTask(result.task, outputReference);
-	const terminalOutcome = resultTerminalOutcome(result);
+	const terminalOutcome = workflowTerminalOutcomeForResult(result);
+	const usage = usageWithValue(result.usage);
 	if (Array.isArray(existingResults)) {
 		return existingResults.map((entry) => {
 			if (!entry || typeof entry !== "object" || Array.isArray(entry)) return entry;
@@ -150,15 +60,18 @@ function workflowResultChildren(status: AsyncStatus, childRunId: string, result:
 			if (child.runId !== childRunId) return child;
 			return {
 				...child,
-				success: childSucceeded(result),
+				success: result.exitCode === 0 && !result.error && !result.interrupted,
 				output,
 				outputState: output.trim() ? "present" : "absent",
 				detached: undefined,
+				...(usage ? { usage } : {}),
 				...(outputReference ? { outputReference } : {}),
 				...(outputPathMapping ? { outputPathMapping } : {}),
 				...(result.interrupted || result.stopped ? { interrupted: true } : {}),
 				...(result.stopped ? { stopped: true } : {}),
 				...(terminalOutcome ? { terminalOutcome } : {}),
+				...(result.sessionName ? { sessionName: result.sessionName } : {}),
+				...(result.sessionFile ? { sessionFile: result.sessionFile } : {}),
 				...(result.error ? { error: result.error } : {}),
 			};
 		});
@@ -166,10 +79,12 @@ function workflowResultChildren(status: AsyncStatus, childRunId: string, result:
 	return status.steps?.map((step: WorkflowStatusStep) => ({
 		workflowKey: step.workflowKey,
 		agent: step.agent,
+		...(step.sessionName ? { sessionName: step.sessionName } : {}),
 		runId: step.runId,
 		success: step.status === "completed" || step.status === "complete",
 		output: step.runId === childRunId ? output : "",
 		outputState: step.runId === childRunId && output.trim() ? "present" : "absent",
+		...(step.runId === childRunId ? { ...(usage ? { usage } : {}), ...(result.sessionFile ? { sessionFile: result.sessionFile } : {}) } : {}),
 		...(step.runId === childRunId && outputReference ? { outputReference } : step.workflowKey && receipt?.entries[step.workflowKey]?.outputReference ? { outputReference: receipt.entries[step.workflowKey]!.outputReference } : {}),
 		...(step.runId === childRunId && outputPathMapping ? { outputPathMapping } : step.outputPathMapping ? { outputPathMapping: step.outputPathMapping } : {}),
 		...(step.interrupted ? { interrupted: true } : {}),
@@ -179,63 +94,11 @@ function workflowResultChildren(status: AsyncStatus, childRunId: string, result:
 	}));
 }
 
-function workflowResultOutputPathMappingSummary(results: unknown): string {
-	if (!Array.isArray(results)) return "";
-	const mappings = results.flatMap((entry) => {
-		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
-		const child = entry as Record<string, unknown>;
-		const mapping = child.outputPathMapping;
-		if (!mapping || typeof mapping !== "object" || Array.isArray(mapping)) return [];
-		const { requestedPath, savedPath } = mapping as Record<string, unknown>;
-		if (typeof requestedPath !== "string" || typeof savedPath !== "string") return [];
-		const key = typeof child.workflowKey === "string" ? child.workflowKey : "child";
-		return [`'${key}': requested ${requestedPath} -> saved ${savedPath}`];
-	});
-	return mappings.length > 0 ? ` Output path mappings: ${mappings.join("; ")}.` : "";
-}
-
-function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, existing?: Record<string, unknown>, receipt?: WorkflowReceipt): Record<string, unknown> {
-	const sessionId = status.sessionId ?? (typeof existing?.sessionId === "string" ? existing.sessionId : undefined);
-	const resolution = workflowResolution(status, result);
-	const recovery = workflowRecovery(receipt);
-	const results = workflowResultChildren(status, childRunId, result, existing?.results, receipt);
-	const summary = `${resolution === "settled-awaiting-resume"
-		? `Workflow lanes settled after detached child ${childRunId} finished. JavaScript workflow continuation was not persisted.${recovery.length ? " Use the listed keyed recovery action to continue a child." : " No retained child is resumable."}`
-		: status.state === "complete"
-		? `Workflow completed after detached child ${childRunId} finished.`
-		: status.error ?? (typeof existing?.summary === "string" ? existing.summary : "Workflow failed.")}${workflowResultOutputPathMappingSummary(results)}`;
-	return {
-		...(existing ?? {}),
-		id: status.runId,
-		runId: status.runId,
-		toolCallId: status.toolCallId,
-		agent: "workflow",
-		mode: "workflow",
-		success: status.state === "complete",
-		state: status.state,
-		summary,
-		error: status.error,
-		activityState: status.activityState,
-		endedAt: status.endedAt,
-		timestamp: Date.now(),
-		results,
-		workflow: status.workflow,
-		workflowChildren: status.workflowChildren,
-		...(receipt?.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
-		...(resolution ? { workflowResolution: resolution, recovery } : {}),
-		reconciledFromDetachedChild: childRunId,
-		...(receipt ? { workflowReceipt: { path: path.join(asyncDir, "workflow-receipt.json"), receipt } } : {}),
-		asyncDir,
-		cwd: status.cwd,
-		sessionId,
-		completionOwnerId: status.completionOwnerId,
-	};
-}
-
 function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, resolution: WorkflowTerminalResolution | undefined): WorkflowReceipt | undefined {
-	const receiptPath = workflowReceiptPath(DIRS.async, status.runId);
+	const receiptRoot = path.dirname(asyncDir);
+	const receiptPath = workflowReceiptPath(receiptRoot, status.runId);
 	if (!fs.existsSync(receiptPath)) return undefined;
-	const receipt = readWorkflowReceipt(DIRS.async, status.runId);
+	const receipt = readWorkflowReceipt(receiptRoot, status.runId);
 	const step = status.steps?.find((candidate) => candidate.runId === childRunId);
 	const key = step?.workflowKey;
 	if (!key) throw new Error(`Workflow receipt '${status.runId}' cannot identify detached child '${childRunId}' by stable key.`);
@@ -254,7 +117,7 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 	const externalRunner = normalizeExternalCliRunnerStatus(result.runner?.type === "external-cli" ? result.runner : externalStep?.runner);
 	const externalProcess = result.externalProcess ?? externalStep?.externalProcess;
 	const externalAdapter = externalRunner ? externalCliReceiptMetadata({ runner: externalRunner, externalProcess, outputReference }) : entry.externalAdapter;
-	const childTerminalOutcome = resultTerminalOutcome(result) ?? entry.terminalOutcome;
+	const childTerminalOutcome = workflowTerminalOutcomeForResult(result) ?? entry.terminalOutcome;
 	if (externalAdapter) resumability = { state: "not-resumable", reason: externalAdapter.nonResumableReason };
 	const updatedEntry: WorkflowReceipt["entries"][string] = resumability.state === "resumable"
 		? {
@@ -287,7 +150,7 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 		...(receipt.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
 		...(resolution ? { workflowResolution: resolution } : {}),
 	};
-	if (resolution) next.recovery = workflowRecovery(next);
+	if (resolution) next.recovery = workflowRecoveryActions(next);
 	else {
 		delete next.workflowResolution;
 		delete next.recovery;
@@ -317,6 +180,16 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 	const asyncDir = job?.asyncDir ?? path.join(DIRS.async, input.workflowRunId);
 	const status = readStatus(asyncDir);
 	if (!status) return false;
+	const matchingControls = input.workflowKey === undefined ? [] : [...(input.state.foregroundControls?.values() ?? [])].filter((control) =>
+		control.parentWorkflowRunId === input.workflowRunId && control.workflowKey === input.workflowKey
+	);
+	const confirmedLiveIdentity = matchingControls.length === 1 && matchingControls[0]?.runId === input.childRunId;
+	if (confirmedLiveIdentity) {
+		const candidates = status.steps?.filter((candidate) => candidate.workflowKey === input.workflowKey) ?? [];
+		const candidate = candidates.length === 1 ? candidates[0] : undefined;
+		if (candidate && candidate.runId === undefined && candidate.sessionFile === undefined
+			&& candidate.status === "paused" && candidate.activityState === "needs_attention") candidate.runId = input.childRunId;
+	}
 	const next = applyDetachedChildToPausedWorkflow(status, {
 		childRunId: input.childRunId,
 		result: input.result,
@@ -325,17 +198,8 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 	if (!next) return false;
 	const outputReference = input.result.savedOutputPath ?? input.result.outputReference?.path;
 	const outputPathMapping = outputPathMappingFromTask(input.result.task, outputReference);
-	const settledStep = findWorkflowStep(next, input.childRunId, input.workflowKey);
+	const settledStep = findWorkflowSettlementStep(next, input.childRunId);
 	if (settledStep && outputPathMapping) settledStep.outputPathMapping = outputPathMapping;
-	writeAtomicJson(path.join(asyncDir, "status.json"), next);
-	updateActiveRunIndex(asyncDir, next.state, next.toolCallId);
-	if (job) {
-		job.status = next.state;
-		job.updatedAt = next.lastUpdate;
-		job.activityState = next.activityState;
-		job.steps = next.steps?.map((step, index) => ({ ...step, index }));
-		job.workflow = next.workflow;
-	}
 	const resultPath = resultFilePath(DIRS.results, input.workflowRunId);
 	let existing: Record<string, unknown> | undefined;
 	try {
@@ -346,14 +210,55 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 	}
 	let receipt: WorkflowReceipt | undefined;
 	let receiptError: string | undefined;
-	const resolution = workflowResolution(next, input.result);
+	const resolution = classifyWorkflowSettlement(next, input.result.interrupted);
 	try {
 		receipt = reconcileWorkflowReceipt(next, input.childRunId, input.result, asyncDir, resolution);
 	} catch (error) {
 		receiptError = `Failed to reconcile async workflow receipt: ${error instanceof Error ? error.message : String(error)}`;
 	}
-	const published = publishedWorkflowResult(next, input.childRunId, input.result, asyncDir, existing, receipt);
-	writeAsyncResultFile(resultPath, published);
+	const results = workflowResultChildren(next, input.childRunId, input.result, existing?.results, receipt) as WorkflowPublicChild[];
+	const recovery = workflowRecoveryActions(receipt);
+	const summary = `${resolution === "settled-awaiting-resume"
+		? `Workflow lanes settled after detached child ${input.childRunId} finished. JavaScript workflow continuation was not persisted.${recovery.length ? " Use the listed keyed recovery action to continue a child." : " No retained child is resumable."}`
+		: next.state === "complete"
+			? `Workflow completed after detached child ${input.childRunId} finished.`
+			: next.error ?? (typeof existing?.summary === "string" ? existing.summary : "Workflow failed.")}${workflowOutputPathMappingSummary(results)}`;
+	const plan = planWorkflowSettlement({
+		status: next,
+		summary,
+		children: results,
+		baseResult: {
+			...(existing ?? {}),
+			id: next.runId,
+			runId: next.runId,
+			toolCallId: next.toolCallId,
+			agent: "workflow",
+			mode: "workflow",
+			endedAt: next.endedAt,
+			workflow: next.workflow,
+			reconciledFromDetachedChild: input.childRunId,
+			asyncDir,
+			cwd: next.cwd,
+			sessionId: next.sessionId ?? (typeof existing?.sessionId === "string" ? existing.sessionId : undefined),
+			completionOwnerId: next.completionOwnerId,
+		},
+		receipt,
+		receiptPath: path.join(asyncDir, "workflow-receipt.json"),
+		receiptPersistenceError: receiptError,
+		resolution,
+		terminalOutcome: receipt?.terminalOutcome,
+		eventMetadata: { reconciledFromDetachedChild: input.childRunId },
+	});
+	writeAtomicJson(path.join(asyncDir, "status.json"), plan.status);
+	updateActiveRunIndex(asyncDir, plan.status.state, plan.status.toolCallId);
+	if (job) {
+		job.status = plan.status.state;
+		job.updatedAt = plan.status.lastUpdate;
+		job.activityState = plan.status.activityState;
+		job.steps = plan.status.steps?.map((step, index) => ({ ...step, index }));
+		job.workflow = plan.status.workflow;
+	}
+	writeAsyncResultFile(resultPath, plan.publicResult);
 	if (receiptError) {
 		appendDetachedWorkflowEvent(asyncDir, {
 			ts: Date.now(),
@@ -363,18 +268,12 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 			reconciledFromDetachedChild: input.childRunId,
 		});
 	}
-	if (next.state === "complete" || next.state === "failed") {
-		if (!resolution) throw new Error(`Terminal detached workflow '${input.workflowRunId}' has no resolution classification.`);
+	if (plan.completionEvent) {
 		appendDetachedWorkflowEvent(asyncDir, {
 			ts: Date.now(),
 			runId: input.workflowRunId,
-			type: "subagent.workflow.completed",
-			state: next.state,
-			workflowResolution: resolution,
-			...(receipt?.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
-			recovery: workflowRecovery(receipt),
-			...(next.error ? { error: next.error } : {}),
-			reconciledFromDetachedChild: input.childRunId,
+			...plan.completionEvent,
+			recovery: plan.recovery,
 		});
 		input.events?.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
 			id: input.workflowRunId,
@@ -382,16 +281,16 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 			source: "async",
 			mode: "workflow",
 			agent: "workflow",
-			success: next.state === "complete",
-			state: next.state,
-			workflowResolution: resolution,
-			...(receipt?.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
-			recovery: workflowRecovery(receipt),
-			summary: typeof published.summary === "string" ? published.summary : (next.state === "complete" ? "Workflow completed." : next.error),
+			success: plan.status.state === "complete",
+			state: plan.status.state,
+			...(resolution ? { workflowResolution: resolution } : {}),
+			...(plan.receipt?.terminalOutcome ? { terminalOutcome: plan.receipt.terminalOutcome } : {}),
+			recovery: plan.recovery,
+			summary: typeof plan.publicResult.summary === "string" ? plan.publicResult.summary : plan.status.error,
 			reconciledFromDetachedChild: input.childRunId,
-			...(Array.isArray(published.results) ? { results: published.results } : {}),
-			sessionId: next.sessionId,
-			completionOwnerId: next.completionOwnerId,
+			results,
+			sessionId: plan.status.sessionId,
+			completionOwnerId: plan.status.completionOwnerId,
 			timestamp: Date.now(),
 			triggerTurn: true,
 		});

package/src/runs/shared/abort-recovery.ts

@@ -0,0 +1,119 @@
+import type { Message } from "@earendil-works/pi-ai";
+
+export const ABORT_RECOVERY_PROMPT = "The prior run ended from a provider/transport abort after useful progress. Continue from the current files and transcript. Do not restart. Fix any validation failure or write the required report. Finish with final output.";
+
+export type AbortRecoveryPlan =
+	| { action: "resume"; prompt: typeof ABORT_RECOVERY_PROMPT }
+	| { action: "settle"; reason: string; diagnostic?: string };
+
+const PROVIDER_ABORT_PATTERN = /(?:provider|transport|connection|stream|socket|request).*(?:abort|closed|reset|ended|terminated|error|fail)|(?:abort|closed|reset|ended|terminated|error|fail).*(?:provider|transport|connection|stream|socket|request)/i;
+const ABORT_ERROR_PATTERN = /\b(?:operation|request|response|stream|connection|transport|provider)?\s*(?:was\s+)?aborted\b/i;
+const TOOL_FAILURE_PREFIX = /^[\w.:@/-]+ failed (?:(?:\(exit \d+\):)|(?:with exit code \d+))(?:\s|$)/i;
+
+function isProviderAbortError(error: string): boolean {
+	return !TOOL_FAILURE_PREFIX.test(error.trim()) && (PROVIDER_ABORT_PATTERN.test(error) || ABORT_ERROR_PATTERN.test(error));
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: undefined;
+}
+
+function contentParts(message: Record<string, unknown>): unknown[] {
+	return Array.isArray(message.content) ? message.content : [];
+}
+
+function terminalAssistant(messages: readonly Message[]): { message?: Record<string, unknown>; index: number } {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = record(messages[index]);
+		if (message?.role === "assistant") return { message, index };
+	}
+	return { index: messages.length };
+}
+
+function zeroOutputUsage(message: Record<string, unknown>): boolean {
+	const usage = record(message.usage);
+	return usage !== undefined && (usage.output ?? usage.outputTokens ?? 0) === 0;
+}
+
+function hasUsefulProgress(messages: readonly Message[], terminalIndex: number): boolean {
+	for (let index = 0; index < terminalIndex; index++) {
+		const message = record(messages[index]);
+		if (!message) continue;
+		if (message.role === "assistant" && contentParts(message).length > 0) return true;
+		if (message.role === "toolResult" && message.isError !== true) return true;
+	}
+	return false;
+}
+
+function hasUnresolvedToolCall(messages: readonly Message[]): boolean {
+	const pending = new Set<string>();
+	for (const rawMessage of messages) {
+		const message = record(rawMessage);
+		if (!message) continue;
+		if (message.role === "assistant") {
+			for (const rawPart of contentParts(message)) {
+				const part = record(rawPart);
+				if (part?.type === "toolCall" && typeof part.id === "string" && part.id) pending.add(part.id);
+			}
+		} else if (message.role === "toolResult" && typeof message.toolCallId === "string") {
+			pending.delete(message.toolCallId);
+		}
+	}
+	return pending.size > 0;
+}
+
+export function planAbortRecovery(input: {
+	messages: readonly Message[];
+	error?: string;
+	processSignal?: string | null;
+	sessionAvailable: boolean;
+	alreadyResumed: boolean;
+	stopped?: boolean;
+	interrupted?: boolean;
+	timedOut?: boolean;
+	toolBudgetExhausted?: boolean;
+	usageBudgetExhausted?: boolean;
+	structuredOutputFailed?: boolean;
+	acceptanceFailed?: boolean;
+	currentTool?: string;
+	afterCompactionSettlement?: boolean;
+}): AbortRecoveryPlan {
+	const terminal = terminalAssistant(input.messages);
+	const message = terminal.message;
+	const terminalError = typeof message?.errorMessage === "string" ? message.errorMessage : undefined;
+	const emptyZeroUsageTerminal = message !== undefined
+		&& contentParts(message).length === 0
+		&& zeroOutputUsage(message);
+	const terminalAssistantAbort = message?.stopReason === "aborted"
+		|| (message?.stopReason === "error" && terminalError !== undefined && isProviderAbortError(terminalError));
+	const abortCandidate = emptyZeroUsageTerminal && terminalAssistantAbort;
+	const compactionAbortCandidate = input.afterCompactionSettlement === true && abortCandidate;
+	const settle = (reason: string): AbortRecoveryPlan => ({
+		action: "settle",
+		reason,
+		...(compactionAbortCandidate
+			? { diagnostic: `Compaction-induced child abort could not be resumed safely: ${reason}.` }
+			: {}),
+	});
+
+	if (input.alreadyResumed) return settle("resume already attempted");
+	if (!input.sessionAvailable) return settle("retained session unavailable");
+	if (input.stopped || input.interrupted) return settle("explicit stop or interrupt");
+	// A compaction abort can leave the child process open until the runner's
+	// terminal drain sends SIGTERM. The compaction + settlement markers make
+	// that cleanup signal non-authoritative; explicit stop/interrupt still wins.
+	if (input.processSignal && !compactionAbortCandidate) return settle("process terminated by signal");
+	if (input.timedOut) return settle("elapsed timeout");
+	if (input.toolBudgetExhausted || input.usageBudgetExhausted) return settle("budget exhausted");
+	if (input.structuredOutputFailed) return settle("structured output failure");
+	if (input.acceptanceFailed) return settle("acceptance failure");
+	if (input.currentTool) return settle(`active tool '${input.currentTool.slice(0, 128)}' remains in flight`);
+	if (hasUnresolvedToolCall(input.messages)) return settle("unresolved tool call remains in transcript");
+	if (!input.afterCompactionSettlement) return settle("compaction settlement not verified");
+	if (!abortCandidate) return settle("terminal assistant abort evidence not verified");
+	const progressLimit = emptyZeroUsageTerminal ? terminal.index : input.messages.length;
+	if (!hasUsefulProgress(input.messages, progressLimit)) return settle("no useful prior progress");
+	return { action: "resume", prompt: ABORT_RECOVERY_PROMPT };
+}