pi-improve-interation 0.0.1

package/node_modules/pi-subagents/src/runs/foreground/workflow-detach-reconcile.ts

@@ -0,0 +1,299 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { getSingleResultOutput, readStatus } from "../../shared/utils.ts";
+import {
+	DIRS,
+	SUBAGENT_ASYNC_COMPLETE_EVENT,
+	type AsyncStatus,
+	type IntercomEventBus,
+	type SingleResult,
+	type SubagentState,
+	type WorkflowTerminalResolution,
+} from "../../shared/types.ts";
+import { updateActiveRunIndex } from "../background/active-run-index.ts";
+import { resultFilePath, writeAsyncResultFile } from "../background/result-files.ts";
+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 {
+	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" | "sessionName" | "stopped">; workflowKey?: string },
+): AsyncStatus | undefined {
+	return applyDetachedChildSettlement(status, input);
+}
+
+export function promotePausedWorkflowIfSettled(status: AsyncStatus): AsyncStatus | undefined {
+	return promoteSettledPausedWorkflow(status);
+}
+
+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 = 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;
+			const child = entry as Record<string, unknown>;
+			if (child.runId !== childRunId) return child;
+			return {
+				...child,
+				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 } : {}),
+			};
+		});
+	}
+	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 } : {}),
+		...(step.runId === childRunId && terminalOutcome ? { terminalOutcome } : step.workflowKey && receipt?.entries[step.workflowKey]?.terminalOutcome ? { terminalOutcome: receipt.entries[step.workflowKey]!.terminalOutcome } : {}),
+		...(step.stopped ? { stopped: true } : {}),
+		...(step.error ? { error: step.error } : {}),
+	}));
+}
+
+function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, resolution: WorkflowTerminalResolution | undefined): WorkflowReceipt | undefined {
+	const receiptRoot = path.dirname(asyncDir);
+	const receiptPath = workflowReceiptPath(receiptRoot, status.runId);
+	if (!fs.existsSync(receiptPath)) return undefined;
+	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.`);
+	const entry = receipt.entries[key];
+	if (!entry) throw new Error(`Workflow receipt '${status.runId}' has no detached child key '${key}'.`);
+	let resumability: typeof entry.resumability;
+	try {
+		const target = resolveAsyncResumeTarget({ id: childRunId, dir: path.join(DIRS.async, childRunId) }, {}, { requireSessionFile: true, sessionId: status.sessionId });
+		resumability = target.kind === "revive" ? { state: "resumable" } : { state: "not-resumable", reason: "child is still running" };
+	} catch (error) {
+		resumability = { state: "not-resumable", reason: error instanceof Error ? error.message : String(error) };
+	}
+	const outputReference = result.savedOutputPath ?? result.outputReference?.path ?? entry.outputReference;
+	const childStatus = readStatus(path.join(DIRS.async, childRunId));
+	const externalStep = childStatus?.steps?.length === 1 && childStatus.steps[0]?.runner?.type === "external-cli" ? childStatus.steps[0] : undefined;
+	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 = workflowTerminalOutcomeForResult(result) ?? entry.terminalOutcome;
+	if (externalAdapter) resumability = { state: "not-resumable", reason: externalAdapter.nonResumableReason };
+	const updatedEntry: WorkflowReceipt["entries"][string] = resumability.state === "resumable"
+		? {
+			...entry,
+			...(step.agent ? { agent: step.agent } : {}),
+			...(step.context ? { resolvedContext: step.context } : {}),
+			latestRunId: entry.latestRunId ?? childRunId,
+			resumability,
+			...(outputReference ? { outputReference } : {}),
+			...(childTerminalOutcome ? { terminalOutcome: childTerminalOutcome } : {}),
+			...(externalAdapter ? { externalAdapter } : {}),
+		}
+		: {
+			...entry,
+			...(step.agent ? { agent: step.agent } : {}),
+			...(step.context ? { resolvedContext: step.context } : {}),
+			resumability,
+			...(outputReference ? { outputReference } : {}),
+			...(childTerminalOutcome ? { terminalOutcome: childTerminalOutcome } : {}),
+			...(externalAdapter ? { externalAdapter } : {}),
+		};
+	const next: WorkflowReceipt = {
+		...receipt,
+		state: status.state === "complete" ? "complete" : status.state === "stopped" ? "stopped" : status.state === "paused" ? "paused" : "failed",
+		entries: {
+			...receipt.entries,
+			[key]: updatedEntry,
+		},
+		workflowChildren: status.workflowChildren,
+		...(receipt.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
+		...(resolution ? { workflowResolution: resolution } : {}),
+	};
+	if (resolution) next.recovery = workflowRecoveryActions(next);
+	else {
+		delete next.workflowResolution;
+		delete next.recovery;
+	}
+	writeWorkflowReceipt(asyncDir, next);
+	return next;
+}
+
+function appendDetachedWorkflowEvent(asyncDir: string, event: Record<string, unknown>): void {
+	const eventsPath = path.join(asyncDir, "events.jsonl");
+	try {
+		fs.appendFileSync(eventsPath, `${JSON.stringify(event)}\n`, "utf-8");
+	} catch (error) {
+		console.error(`Failed to append detached workflow event '${eventsPath}':`, error);
+	}
+}
+
+export function reconcileDetachedWorkflowChildCompletion(input: {
+	state: SubagentState;
+	workflowRunId: string;
+	childRunId: string;
+	result: SingleResult;
+	events?: IntercomEventBus;
+	workflowKey?: string;
+}): boolean {
+	const job = input.state.asyncJobs.get(input.workflowRunId);
+	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,
+		workflowKey: input.workflowKey,
+	});
+	if (!next) return false;
+	const outputReference = input.result.savedOutputPath ?? input.result.outputReference?.path;
+	const outputPathMapping = outputPathMappingFromTask(input.result.task, outputReference);
+	const settledStep = findWorkflowSettlementStep(next, input.childRunId);
+	if (settledStep && outputPathMapping) settledStep.outputPathMapping = outputPathMapping;
+	const resultPath = resultFilePath(DIRS.results, input.workflowRunId);
+	let existing: Record<string, unknown> | undefined;
+	try {
+		const parsed: unknown = JSON.parse(fs.readFileSync(resultPath, "utf-8"));
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) existing = parsed as Record<string, unknown>;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	let receipt: WorkflowReceipt | undefined;
+	let receiptError: string | undefined;
+	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 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(),
+			runId: input.workflowRunId,
+			type: "subagent.workflow.receipt_write_failed",
+			error: receiptError,
+			reconciledFromDetachedChild: input.childRunId,
+		});
+	}
+	if (plan.completionEvent) {
+		appendDetachedWorkflowEvent(asyncDir, {
+			ts: Date.now(),
+			runId: input.workflowRunId,
+			...plan.completionEvent,
+			recovery: plan.recovery,
+		});
+		input.events?.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+			id: input.workflowRunId,
+			runId: input.workflowRunId,
+			source: "async",
+			mode: "workflow",
+			agent: "workflow",
+			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,
+			results,
+			sessionId: plan.status.sessionId,
+			completionOwnerId: plan.status.completionOwnerId,
+			timestamp: Date.now(),
+			triggerTurn: true,
+		});
+	}
+	return true;
+}

package/node_modules/pi-subagents/src/runs/foreground/workflow-foreground-steering.ts

@@ -0,0 +1,188 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Details, ForegroundRunControl, SubagentState } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+import { steeringReceipt } from "../background/steering.ts";
+import {
+	consumeSteerAckFromDir,
+	readSteerCapability,
+	steerAcksDir,
+	steerCapabilityPath,
+	stepSteerInboxDir,
+	writeSteerRequestToExistingDir,
+	type SteerDeliveryMode,
+	type SteerRequest,
+} from "../background/control-channel.ts";
+
+export interface WorkflowForegroundSteeringTarget {
+	control: ForegroundRunControl;
+	workflowRunId: string;
+	sourceRunId: string;
+}
+
+export type WorkflowForegroundSteeringResolution =
+	| { ok: true; target: WorkflowForegroundSteeringTarget }
+	| { ok: false; message: string };
+
+function activeWorkflowError(state: SubagentState, workflowRunId: string, asyncDirRoot: string): string | undefined {
+	if (!state.currentSessionId) return "Workflow steering requires an active parent session.";
+	if (!state.workflowControllers?.has(workflowRunId)) return `Workflow '${workflowRunId}' has no live foreground child.`;
+	const status = readStatus(path.join(asyncDirRoot, workflowRunId));
+	if (!status || status.mode !== "workflow" || (status.state !== "running" && status.state !== "queued")) {
+		return `Workflow '${workflowRunId}' has no live foreground child.`;
+	}
+	if (status.sessionId !== state.currentSessionId) return `Workflow '${workflowRunId}' was not found in the active session.`;
+	return undefined;
+}
+
+function controlIsLiveInWorkflow(control: ForegroundRunControl, workflowRunId: string, sessionId: string): boolean {
+	return control.parentWorkflowRunId === workflowRunId
+		&& control.sessionId === sessionId
+		&& Boolean(control.workflowSteeringDir)
+		&& (control.activeChildren?.size ?? 0) > 0;
+}
+
+export function resolveWorkflowForegroundSteeringTarget(input: {
+	state: SubagentState;
+	childRunId?: string;
+	workflowRunId?: string;
+	asyncDirRoot: string;
+}): WorkflowForegroundSteeringResolution {
+	const { state, childRunId, asyncDirRoot } = input;
+	if (childRunId) {
+		const control = state.foregroundControls.get(childRunId);
+		if (!control?.parentWorkflowRunId) return { ok: false, message: `Foreground run '${childRunId}' is not a live workflow-owned child.` };
+		const workflowRunId = control.parentWorkflowRunId;
+		const workflowError = activeWorkflowError(state, workflowRunId, asyncDirRoot);
+		if (workflowError) return { ok: false, message: workflowError };
+		if (!controlIsLiveInWorkflow(control, workflowRunId, state.currentSessionId!)) {
+			return { ok: false, message: `Foreground run '${childRunId}' is not a live workflow-owned child in the active session.` };
+		}
+		return { ok: true, target: { control, workflowRunId, sourceRunId: childRunId } };
+	}
+
+	const workflowRunId = input.workflowRunId;
+	if (!workflowRunId) return { ok: false, message: "Workflow steering requires a workflow or child run id." };
+	const workflowError = activeWorkflowError(state, workflowRunId, asyncDirRoot);
+	if (workflowError) return { ok: false, message: workflowError };
+	const controls = [...state.foregroundControls.values()].filter((control) => controlIsLiveInWorkflow(control, workflowRunId, state.currentSessionId!));
+	if (controls.length === 0) return { ok: false, message: `Workflow '${workflowRunId}' has no live foreground child.` };
+	if (controls.length > 1) return { ok: false, message: `Workflow '${workflowRunId}' has ${controls.length} live foreground children; steer a child run id instead.` };
+	return { ok: true, target: { control: controls[0]!, workflowRunId, sourceRunId: workflowRunId } };
+}
+
+function managementError(message: string): AgentToolResult<Details> {
+	return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
+}
+
+export async function steerWorkflowForegroundTarget(input: {
+	target: WorkflowForegroundSteeringTarget;
+	message: string;
+	mode?: SteerDeliveryMode;
+	index?: number;
+	signal?: AbortSignal;
+	ackTimeoutMs?: number;
+}): Promise<AgentToolResult<Details>> {
+	const { control, sourceRunId } = input.target;
+	const routeDir = control.workflowSteeringDir;
+	if (!routeDir || !fs.existsSync(routeDir)) return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
+	const activeIndexes = [...(control.activeChildren?.keys() ?? [])].sort((left, right) => left - right);
+	const index = input.index ?? (activeIndexes.length === 1 ? activeIndexes[0] : undefined);
+	if (index === undefined) {
+		return managementError(activeIndexes.length === 0
+			? `Foreground run '${control.runId}' has no live child session.`
+			: `Foreground run '${control.runId}' has ${activeIndexes.length} live child sessions; provide index.`);
+	}
+	if (!activeIndexes.includes(index)) return managementError(`Foreground run '${control.runId}' child ${index} is not live.`);
+	const capability = readSteerCapability(routeDir, index);
+	if (capability?.supported === false) return managementError(`Foreground run '${control.runId}' child ${index} does not support steering.`);
+
+	const request: SteerRequest = {
+		type: "steer",
+		id: randomUUID(),
+		ts: Date.now(),
+		message: input.message.trim(),
+		...(input.mode && input.mode !== "steer" ? { mode: input.mode } : {}),
+		targetIndex: index,
+		source: "steer-action",
+	};
+	try {
+		writeSteerRequestToExistingDir(stepSteerInboxDir(routeDir, index), request);
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+			return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
+		}
+		return managementError(`Failed to queue steering for foreground run ${control.runId}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+
+	const deadline = Date.now() + (input.ackTimeoutMs ?? 3_000);
+	let ack;
+	let routeRemoved = false;
+	while (Date.now() <= deadline) {
+		ack = consumeSteerAckFromDir(steerAcksDir(routeDir, index), request.id);
+		if (ack || input.signal?.aborted) break;
+		if (!fs.existsSync(routeDir)) {
+			routeRemoved = true;
+			break;
+		}
+		await new Promise<void>((resolve) => setTimeout(resolve, Math.min(50, Math.max(1, deadline - Date.now()))));
+	}
+	if (routeRemoved || (!ack && !input.signal?.aborted && !fs.existsSync(routeDir))) {
+		return managementError(`Foreground run '${control.runId}' has no live child session.`);
+	}
+	const target = ack?.state === "delivered"
+		? { index, state: "delivered" as const, deliveredAt: ack.ts }
+		: ack?.state === "queued"
+			? { index, state: "queued" as const }
+			: ack?.state === "failed"
+				? { index, state: "failed" as const, reason: ack.message }
+				: { index, state: "pending" as const };
+	const steering = {
+		requestId: request.id,
+		state: ack?.state === "delivered" ? "delivered" as const : ack?.state === "failed" ? "failed" as const : "pending" as const,
+		deliveryStatus: ack?.state === "delivered" ? "delivered" as const : "queued" as const,
+		sourceRunId,
+		targets: [target],
+	};
+	if (input.signal?.aborted) {
+		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering pending for foreground run ${control.runId} (request ${request.id}); caller aborted before acknowledgment.`) }], details: { mode: "management", results: [], steering } };
+	}
+	if (ack?.state === "delivered") {
+		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering delivered for foreground run ${control.runId} (request ${request.id}).`) }], details: { mode: "management", results: [], steering } };
+	}
+	if (ack?.state === "queued") {
+		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering queued for foreground run ${control.runId} (request ${request.id}).`) }], details: { mode: "management", results: [], steering } };
+	}
+	if (ack?.state === "failed") {
+		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering failed for foreground run ${control.runId} (request ${request.id}): ${ack.message}`) }], isError: true, details: { mode: "management", results: [], steering } };
+	}
+	return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering pending for foreground run ${control.runId} (request ${request.id}); no acknowledgment was received.`) }], details: { mode: "management", results: [], steering } };
+}
+
+export function workflowForegroundSteeringDir(asyncDirRoot: string, workflowRunId: string, childRunId: string): string {
+	return path.join(asyncDirRoot, workflowRunId, "control", "workflow-foreground", childRunId);
+}
+
+export function removeWorkflowForegroundSteeringRoute(control: ForegroundRunControl): void {
+	if (!control.workflowSteeringDir) return;
+	try {
+		fs.rmSync(control.workflowSteeringDir, { recursive: true, force: true });
+	} catch (error) {
+		console.warn(`[pi-subagents] Failed to remove workflow foreground steering route '${control.workflowSteeringDir}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export function workflowForegroundSteeringLaunchOptions(control: ForegroundRunControl | undefined, index: number): Pick<import("../../shared/types.ts").RunSyncOptions, "steerInboxDir" | "steerCapabilityPath" | "steerAckDir"> {
+	if (!control?.workflowSteeringDir) return {};
+	const steerInboxDir = stepSteerInboxDir(control.workflowSteeringDir, index);
+	const steerAckDir = steerAcksDir(control.workflowSteeringDir, index);
+	fs.mkdirSync(steerInboxDir, { recursive: true });
+	fs.mkdirSync(steerAckDir, { recursive: true });
+	return {
+		steerInboxDir,
+		steerCapabilityPath: steerCapabilityPath(control.workflowSteeringDir, index),
+		steerAckDir,
+	};
+}

package/node_modules/pi-subagents/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 };
+}