@selesai/code 0.13.0 → 0.13.1

package/dist/extensions/pi-subagents/src/workflows/workflow-receipt.ts

@@ -1,13 +1,17 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
-import type { WorkflowReceipt, WorkflowReceiptEntry, WorkflowReceiptState } from "../shared/types.ts";
+import type { ExternalCliReceiptMetadata, WorkflowReceipt, WorkflowReceiptEntry, WorkflowReceiptState, WorkflowRecoveryAction, WorkflowTerminalOutcome, WorkflowTerminalResolution } from "../shared/types.ts";
 import type { WorkflowReceiptResumeReference, WorkflowScriptChildResult } from "./scripted-workflow.ts";
+import { parseWorkflowChildSummary } from "./workflow-child-summary.ts";
+import { HOST_STEP_MAX_COUNT, assertUniqueHostStepIds, parseHostStepNode } from "../runs/shared/host-step-status.ts";
+import { assertWorkflowLaneKey, normalizeWorkflowLaneMetadata } from "../runs/shared/lane-metadata.ts";
 
 export type { WorkflowReceipt, WorkflowReceiptEntry, WorkflowReceiptState } from "../shared/types.ts";
 
 export const WORKFLOW_RECEIPT_VERSION = 1;
 export const WORKFLOW_RECEIPT_FILE = "workflow-receipt.json";
+const MAX_WORKFLOW_RECEIPT_BYTES = 2 * 1024 * 1024;
 
 const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 
@@ -32,30 +36,42 @@ export function buildWorkflowReceipt(input: {
 	workflowRunId: string;
 	state: WorkflowReceiptState;
 	children: WorkflowScriptChildResult[];
+	hostSteps?: WorkflowReceipt["hostSteps"];
+	workflowChildren?: WorkflowReceipt["workflowChildren"];
+	terminalOutcome?: WorkflowTerminalOutcome;
 	createdAt?: number;
 }): WorkflowReceipt {
 	const workflowRunId = assertSafeRunId(input.workflowRunId, "workflowRunId");
+	if (input.workflowChildren?.workflowRunId !== undefined && input.workflowChildren.workflowRunId !== workflowRunId) throw new Error("workflowChildren workflowRunId does not match its receipt.");
 	const entries: Record<string, WorkflowReceiptEntry> = Object.create(null) as Record<string, WorkflowReceiptEntry>;
 	for (const child of input.children) {
 		const key = assertKey(child.key, "workflow receipt child key");
 		if (entries[key]) throw new Error(`Workflow receipt has duplicate child key '${key}'.`);
+		const lane = normalizeWorkflowLaneMetadata(child.lane, `workflow receipt child '${key}'.lane`);
+		assertWorkflowLaneKey(lane, key, `workflow receipt child '${key}'.lane`);
 		const runIds = [...new Set((child.continuation?.runIds ?? (child.runId ? [child.runId] : [])).filter((runId) => typeof runId === "string" && runId.trim()).map((runId) => runId.trim()))];
 		const latestRunId = runIds.at(-1);
 		const resumability = child.resumability ?? { state: "not-resumable", reason: child.runId ? "resumability was not recorded" : "child produced no run id" };
 		if (resumability.state === "resumable" && !latestRunId) throw new Error(`Workflow receipt child '${key}' is resumable but has no retained run id.`);
 		const base = {
 			key,
+			...(lane ? { lane } : {}),
+			...(child.terminalOutcome ? { terminalOutcome: child.terminalOutcome } : {}),
 			...(child.agent ? { agent: child.agent } : {}),
 			...(child.requestedContext ? { requestedContext: child.requestedContext } : {}),
 			...(child.resolvedContext ? { resolvedContext: child.resolvedContext } : {}),
 			...(child.outputReference ? { outputReference: child.outputReference } : {}),
+			...(child.externalAdapter ? { externalAdapter: child.externalAdapter } : {}),
 			continuation: { runIds },
 		};
 		entries[key] = resumability.state === "resumable"
 			? { ...base, latestRunId: latestRunId!, resumability }
 			: { ...base, ...(latestRunId ? { latestRunId } : {}), resumability };
 	}
-	return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries };
+	if (input.hostSteps && input.hostSteps.length > HOST_STEP_MAX_COUNT) throw new Error(`Workflow receipt has more than ${HOST_STEP_MAX_COUNT} host steps.`);
+	const hostSteps = input.hostSteps?.map((hostStep, index) => parseHostStepNode(hostStep, `workflow receipt hostSteps[${index}]`));
+	if (hostSteps) assertUniqueHostStepIds(hostSteps, "workflow receipt");
+	return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...(hostSteps?.length ? { hostSteps } : {}), ...(input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}), ...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}) };
 }
 
 export function writeWorkflowReceipt(asyncDir: string, receipt: WorkflowReceipt): string {
@@ -64,6 +80,136 @@ export function writeWorkflowReceipt(asyncDir: string, receipt: WorkflowReceipt)
 	return receiptPath;
 }
 
+function readWorkflowReceiptFile(receiptPath: string): unknown {
+	let fd: number | undefined;
+	try {
+		fd = fs.openSync(receiptPath, "r");
+		const stat = fs.fstatSync(fd);
+		if (!stat.isFile()) throw new Error("workflow receipt is not a regular file.");
+		if (stat.size > MAX_WORKFLOW_RECEIPT_BYTES) throw new Error(`workflow receipt exceeds the ${MAX_WORKFLOW_RECEIPT_BYTES}-byte limit.`);
+		const buffer = Buffer.allocUnsafe(stat.size);
+		let offset = 0;
+		while (offset < buffer.length) {
+			const bytesRead = fs.readSync(fd, buffer, offset, buffer.length - offset, null);
+			if (bytesRead <= 0) throw new Error("workflow receipt ended before its declared size.");
+			offset += bytesRead;
+		}
+		return JSON.parse(buffer.toString("utf-8")) as unknown;
+	} finally {
+		if (fd !== undefined) fs.closeSync(fd);
+	}
+}
+
+const EXTERNAL_CLI_CAPABILITIES = {
+	stop: true,
+	steer: false,
+	resume: false,
+	structuredOutput: false,
+	toolEvents: false,
+	supervisor: "unsupported",
+	forkContext: false,
+	extensionBindings: false,
+} as const;
+
+function parseExternalCliReceiptMetadata(value: unknown, key: string, source: string): ExternalCliReceiptMetadata | undefined {
+	if (value === undefined) return undefined;
+	const label = `Invalid workflow receipt '${source}': entry '${key}' externalAdapter`;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+	const metadata = value as Record<string, unknown>;
+	const unknownMetadata = Object.keys(metadata).filter((field) => !["adapter", "capabilities", "safety", "outputArtifacts", "handoff", "supervisor", "nonResumableReason"].includes(field));
+	if (unknownMetadata.length > 0) throw new Error(`${label} has unsupported fields: ${unknownMetadata.join(", ")}.`);
+	const adapter = metadata.adapter;
+	if (!adapter || typeof adapter !== "object" || Array.isArray(adapter)) throw new Error(`${label}.adapter must be an object.`);
+	const adapterRecord = adapter as Record<string, unknown>;
+	const unknownAdapter = Object.keys(adapterRecord).filter((field) => !["id", "version", "executionMode"].includes(field));
+	if (unknownAdapter.length > 0) throw new Error(`${label}.adapter has unsupported fields: ${unknownAdapter.join(", ")}.`);
+	if ((adapterRecord.id !== "external-cli" && adapterRecord.id !== "codex-exec" && adapterRecord.id !== "codex-exec-writer" && adapterRecord.id !== "claude-code" && adapterRecord.id !== "claude-code-writer" && adapterRecord.id !== "cursor-agent" && adapterRecord.id !== "cursor-agent-writer" && adapterRecord.id !== "grok-build") || adapterRecord.version !== 1 || adapterRecord.executionMode !== (adapterRecord.id === "cursor-agent" || adapterRecord.id === "cursor-agent-writer" || adapterRecord.id === "grok-build" ? "one-shot-prompt-file" : "one-shot-stdin")) throw new Error(`${label}.adapter is invalid.`);
+	const capabilities = metadata.capabilities;
+	if (!capabilities || typeof capabilities !== "object" || Array.isArray(capabilities)) throw new Error(`${label}.capabilities must be an object.`);
+	const capabilityRecord = capabilities as Record<string, unknown>;
+	const unknownCapabilities = Object.keys(capabilityRecord).filter((field) => !(field in EXTERNAL_CLI_CAPABILITIES));
+	if (unknownCapabilities.length > 0) throw new Error(`${label}.capabilities has unsupported fields: ${unknownCapabilities.join(", ")}.`);
+	for (const [capability, expected] of Object.entries(EXTERNAL_CLI_CAPABILITIES)) {
+		if (capabilityRecord[capability] !== expected) throw new Error(`${label}.capabilities.${capability} is invalid.`);
+	}
+	const safety = metadata.safety;
+	if (adapterRecord.id === "codex-exec") {
+		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
+		const safetyRecord = safety as Record<string, unknown>;
+		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["sandbox", "approvalPolicy", "ephemeral"].includes(field));
+		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+		if (safetyRecord.sandbox !== "read-only" || safetyRecord.approvalPolicy !== "never" || safetyRecord.ephemeral !== true) throw new Error(`${label}.safety is invalid.`);
+	} else if (adapterRecord.id === "codex-exec-writer") {
+		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
+		const safetyRecord = safety as Record<string, unknown>;
+		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "sandbox", "approvalPolicy", "ephemeral"].includes(field));
+		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+		if (safetyRecord.access !== "workspace-write" || safetyRecord.sandbox !== "workspace-write" || safetyRecord.approvalPolicy !== "never" || safetyRecord.ephemeral !== true) throw new Error(`${label}.safety is invalid.`);
+	} else if (adapterRecord.id === "claude-code") {
+		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
+		const safetyRecord = safety as Record<string, unknown>;
+		const legacy = safetyRecord.authentication === undefined;
+		const unknownSafety = Object.keys(safetyRecord).filter((field) => !(legacy
+			? ["permissionMode", "tools", "mcp", "settingSources", "sessionPersistence"]
+			: ["access", "authentication", "permissionMode", "tools", "mcp", "settingSources", "userSettingsTrust", "sessionPersistence"]).includes(field));
+		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+		if (legacy) {
+			if (safetyRecord.permissionMode !== "plan" || safetyRecord.tools !== "none" || safetyRecord.mcp !== "empty-strict" || safetyRecord.settingSources !== "none" || safetyRecord.sessionPersistence !== false) throw new Error(`${label}.safety is invalid.`);
+		} else if (safetyRecord.access !== "read-only" || safetyRecord.authentication !== "existing-cli-required" || safetyRecord.permissionMode !== "plan" || safetyRecord.tools !== "none" || safetyRecord.mcp !== "empty-strict" || safetyRecord.settingSources !== "user" || safetyRecord.userSettingsTrust !== "required" || safetyRecord.sessionPersistence !== false) throw new Error(`${label}.safety is invalid.`);
+	} else if (adapterRecord.id === "claude-code-writer") {
+		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
+		const safetyRecord = safety as Record<string, unknown>;
+		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "authentication", "permissionMode", "tools", "mcp", "settingSources", "userSettingsTrust", "sessionPersistence"].includes(field));
+		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+		if (safetyRecord.access !== "workspace-write" || safetyRecord.authentication !== "existing-cli-required" || safetyRecord.permissionMode !== "acceptEdits" || safetyRecord.tools !== "Read,Write,Edit,Glob,Grep" || safetyRecord.mcp !== "empty-strict" || safetyRecord.settingSources !== "user" || safetyRecord.userSettingsTrust !== "required" || safetyRecord.sessionPersistence !== false) throw new Error(`${label}.safety is invalid.`);
+	} else if (adapterRecord.id === "cursor-agent" || adapterRecord.id === "cursor-agent-writer") {
+		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
+		const safetyRecord = safety as Record<string, unknown>;
+		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "authentication", "mode", "sandbox", "workspaceTrust", "sessionReuse"].includes(field));
+		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+		const writer = adapterRecord.id === "cursor-agent-writer";
+		if (safetyRecord.access !== (writer ? "workspace-write" : "read-only") || safetyRecord.authentication !== "cursor-api-key-or-existing-login" || safetyRecord.mode !== (writer ? "print" : "ask") || safetyRecord.sandbox !== "enabled" || safetyRecord.workspaceTrust !== "existing-required" || safetyRecord.sessionReuse !== false) throw new Error(`${label}.safety is invalid.`);
+	} else if (adapterRecord.id === "grok-build") {
+		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
+		const safetyRecord = safety as Record<string, unknown>;
+		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "authentication", "permissionMode", "tools", "deniedTools", "sandbox", "webSearch", "subagents", "config", "updates", "sessionPersistence"].includes(field));
+		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+		if (safetyRecord.access !== "read-only" || safetyRecord.authentication !== "xai-api-key-required" || safetyRecord.permissionMode !== "plan" || safetyRecord.tools !== "read_file,grep,list_dir" || safetyRecord.deniedTools !== "run_terminal_cmd,search_replace,Agent,Bash,Edit,Write,MCPTool" || safetyRecord.sandbox !== "read-only" || safetyRecord.webSearch !== false || safetyRecord.subagents !== false || safetyRecord.config !== "temporary-home" || safetyRecord.updates !== "disabled" || safetyRecord.sessionPersistence !== false) throw new Error(`${label}.safety is invalid.`);
+	} else if (safety !== undefined) throw new Error(`${label}.safety is invalid for the generic adapter.`);
+	const handoff = metadata.handoff;
+	if (!handoff || typeof handoff !== "object" || Array.isArray(handoff)) throw new Error(`${label}.handoff must be an object.`);
+	const handoffRecord = handoff as Record<string, unknown>;
+	const unknownHandoff = Object.keys(handoffRecord).filter((field) => field !== "mode");
+	if (unknownHandoff.length > 0) throw new Error(`${label}.handoff has unsupported fields: ${unknownHandoff.join(", ")}.`);
+	if (handoffRecord.mode !== "fresh") throw new Error(`${label}.handoff is invalid.`);
+	const supervisor = metadata.supervisor;
+	if (!supervisor || typeof supervisor !== "object" || Array.isArray(supervisor)) throw new Error(`${label}.supervisor must be an object.`);
+	const supervisorRecord = supervisor as Record<string, unknown>;
+	const unknownSupervisor = Object.keys(supervisorRecord).filter((field) => !["mode", "reason"].includes(field));
+	if (unknownSupervisor.length > 0) throw new Error(`${label}.supervisor has unsupported fields: ${unknownSupervisor.join(", ")}.`);
+	if (supervisorRecord.mode !== "unsupported" || typeof supervisorRecord.reason !== "string" || !supervisorRecord.reason.trim()) throw new Error(`${label}.supervisor is invalid.`);
+	if (typeof metadata.nonResumableReason !== "string" || !metadata.nonResumableReason.trim()) throw new Error(`${label}.nonResumableReason is missing.`);
+	const outputArtifacts = metadata.outputArtifacts;
+	if (outputArtifacts !== undefined) {
+		if (!outputArtifacts || typeof outputArtifacts !== "object" || Array.isArray(outputArtifacts)) throw new Error(`${label}.outputArtifacts must be an object.`);
+		const unknownArtifacts = Object.keys(outputArtifacts).filter((field) => !["stdoutPath", "stderrPath", "finalOutputPath"].includes(field));
+		if (unknownArtifacts.length > 0) throw new Error(`${label}.outputArtifacts has unsupported fields: ${unknownArtifacts.join(", ")}.`);
+		for (const field of ["stdoutPath", "stderrPath", "finalOutputPath"] as const) {
+			const artifactPath = (outputArtifacts as Record<string, unknown>)[field];
+			if (artifactPath !== undefined && (typeof artifactPath !== "string" || !artifactPath.trim())) throw new Error(`${label}.outputArtifacts.${field} must be a non-empty string.`);
+		}
+	}
+	return value as ExternalCliReceiptMetadata;
+}
+
+function parseTerminalOutcome(value: unknown, label: string): WorkflowTerminalOutcome | undefined {
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+	const outcome = value as Record<string, unknown>;
+	if (outcome.state !== "partial" || (outcome.reason !== "budget_exhausted" && outcome.reason !== "timeout")) throw new Error(`${label} is invalid.`);
+	return { state: "partial", reason: outcome.reason };
+}
+
 function parseEntry(value: unknown, key: string, source: string): WorkflowReceiptEntry {
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' must be an object.`);
 	const entry = value as Record<string, unknown>;
@@ -84,16 +230,47 @@ function parseEntry(value: unknown, key: string, source: string): WorkflowReceip
 	const reason = (resumability as Record<string, unknown>).reason;
 	if (state === "resumable" && latestRunId === undefined) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' resumable entry has no retained run id.`);
 	if (state === "not-resumable" && (typeof reason !== "string" || !reason.trim())) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' non-resumable reason is missing.`);
-	return value as WorkflowReceiptEntry;
+	const terminalOutcome = parseTerminalOutcome(entry.terminalOutcome, `Invalid workflow receipt '${source}': entry '${key}' terminalOutcome`);
+	parseExternalCliReceiptMetadata(entry.externalAdapter, key, source);
+	const lane = normalizeWorkflowLaneMetadata(entry.lane, `Invalid workflow receipt '${source}': entry '${key}'.lane`);
+	assertWorkflowLaneKey(lane, key, `Invalid workflow receipt '${source}': entry '${key}'.lane`);
+	return { ...(value as WorkflowReceiptEntry), ...(lane ? { lane } : {}), ...(terminalOutcome ? { terminalOutcome } : {}) };
+}
+
+function parseWorkflowResolution(value: unknown, source: string): WorkflowTerminalResolution | undefined {
+	if (value === undefined) return undefined;
+	if (value !== "settled-awaiting-resume" && value !== "failed-child" && value !== "interrupted-child") throw new Error(`Invalid workflow receipt '${source}': workflowResolution is invalid.`);
+	return value;
+}
+
+function parseRecovery(value: unknown, workflowRunId: string, entries: Record<string, WorkflowReceiptEntry>, source: string): WorkflowRecoveryAction[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) throw new Error(`Invalid workflow receipt '${source}': recovery must be an array.`);
+	return value.map((item, index) => {
+		if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error(`Invalid workflow receipt '${source}': recovery[${index}] must be an object.`);
+		const action = item as Record<string, unknown>;
+		const key = action.key;
+		const resume = action.resume;
+		if (typeof key !== "string" || !entries[key] || action.call !== "runs.run" || action.taskRequired !== true || !resume || typeof resume !== "object" || Array.isArray(resume)) throw new Error(`Invalid workflow receipt '${source}': recovery[${index}] is invalid.`);
+		const reference = resume as Record<string, unknown>;
+		if (reference.workflowRunId !== workflowRunId || reference.key !== key || reference.latest !== true || entries[key].resumability.state !== "resumable") throw new Error(`Invalid workflow receipt '${source}': recovery[${index}] does not identify a resumable entry.`);
+		return { key, call: "runs.run", resume: { workflowRunId, key, latest: true }, taskRequired: true };
+	});
 }
 
 export function readWorkflowReceipt(asyncDirRoot: string, workflowRunId: string): WorkflowReceipt {
 	const receiptPath = workflowReceiptPath(asyncDirRoot, workflowRunId);
 	let value: unknown;
 	try {
-		value = JSON.parse(fs.readFileSync(receiptPath, "utf-8")) as unknown;
+		value = readWorkflowReceiptFile(receiptPath);
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new Error(`Workflow receipt '${workflowRunId}' was not found.`);
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			const workflowDir = path.dirname(receiptPath);
+			if (fs.existsSync(path.join(workflowDir, "status.json")) || fs.existsSync(path.join(workflowDir, "events.jsonl"))) {
+				throw new Error(`Workflow receipt '${workflowRunId}' is not available because the workflow may still be active or terminal receipt writing failed. Use direct child run IDs from status/events for direct resume after the normal retained-child checks.`);
+			}
+			throw new Error(`Workflow receipt '${workflowRunId}' was not found.`);
+		}
 		throw new Error(`Workflow receipt '${workflowRunId}' could not be read: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
 	}
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid workflow receipt '${receiptPath}': expected an object.`);
@@ -107,7 +284,19 @@ export function readWorkflowReceipt(asyncDirRoot: string, workflowRunId: string)
 	if (!receipt.entries || typeof receipt.entries !== "object" || Array.isArray(receipt.entries)) throw new Error(`Invalid workflow receipt '${receiptPath}': entries must be an object.`);
 	const entries: Record<string, WorkflowReceiptEntry> = Object.create(null) as Record<string, WorkflowReceiptEntry>;
 	for (const [key, entry] of Object.entries(receipt.entries as Record<string, unknown>)) entries[assertKey(key, "workflow receipt key")] = parseEntry(entry, key, receiptPath);
-	return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries };
+	const workflowChildren = parseWorkflowChildSummary(receipt.workflowChildren);
+	if (workflowChildren && workflowChildren.workflowRunId !== workflowRunId) throw new Error(`Workflow receipt '${receiptPath}' is stale: workflowChildren.workflowRunId does not match.`);
+	let hostSteps: NonNullable<WorkflowReceipt["hostSteps"]> | undefined;
+	if (receipt.hostSteps !== undefined) {
+		if (!Array.isArray(receipt.hostSteps)) throw new Error(`Invalid workflow receipt '${receiptPath}': hostSteps must be an array.`);
+		if (receipt.hostSteps.length > HOST_STEP_MAX_COUNT) throw new Error(`Invalid workflow receipt '${receiptPath}': hostSteps exceeds ${HOST_STEP_MAX_COUNT} entries.`);
+		hostSteps = receipt.hostSteps.map((hostStep, index) => parseHostStepNode(hostStep, `${receiptPath} hostSteps[${index}]`));
+		assertUniqueHostStepIds(hostSteps, receiptPath);
+	}
+	const workflowResolution = parseWorkflowResolution(receipt.workflowResolution, receiptPath);
+	const terminalOutcome = parseTerminalOutcome(receipt.terminalOutcome, `Invalid workflow receipt '${receiptPath}': terminalOutcome`);
+	const recovery = parseRecovery(receipt.recovery, workflowRunId, entries, receiptPath);
+	return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries, ...(hostSteps?.length ? { hostSteps } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(workflowResolution ? { workflowResolution } : {}), ...(terminalOutcome ? { terminalOutcome } : {}), ...(recovery ? { recovery } : {}) };
 }
 
 export function resolveWorkflowReceiptResumeEntry(input: {

package/dist/extensions/pi-subagents/src/workflows/workflow-settlement.ts

@@ -0,0 +1,246 @@
+import type {
+	AsyncStatus,
+	WorkflowRecoveryAction,
+	WorkflowTerminalOutcome,
+	WorkflowTerminalResolution,
+	Usage,
+} from "../shared/types.ts";
+import type { WorkflowReceipt } from "./workflow-receipt.ts";
+import { workflowChildSummary } from "./workflow-child-summary.ts";
+
+export 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.";
+export const INTERRUPTED_DETACHED_CHILD = "Interrupted. Waiting for explicit next action.";
+export const EVIDENCE_PERSISTENCE_FAILED = "evidence-persistence-failed";
+
+export type WorkflowStatusStep = NonNullable<AsyncStatus["steps"]>[number] & {
+	outputPathMapping?: { requestedPath: string; savedPath: string };
+	interrupted?: boolean;
+};
+
+export interface WorkflowPublicChild {
+	workflowKey?: string;
+	agent?: string;
+	/** Human-readable display name for the child session, when derived at launch. */
+	sessionName?: string;
+	runId?: string;
+	usage?: Usage;
+	sessionFile?: string;
+	output: string;
+	outputState: "present" | "absent";
+	structuredOutput?: unknown;
+	success: boolean;
+	terminalOutcome?: WorkflowTerminalOutcome;
+	outputReference?: string;
+	outputPathMapping?: { requestedPath: string; savedPath: string };
+	stopped?: boolean;
+	interrupted?: boolean;
+	detached?: boolean;
+	error?: string;
+	artifactPaths?: { outputPath: string };
+}
+
+export interface WorkflowSettlementPlan {
+	status: AsyncStatus;
+	publicResult: Record<string, unknown>;
+	receipt?: WorkflowReceipt;
+	recovery: WorkflowRecoveryAction[];
+	completionEvent?: Record<string, unknown>;
+}
+
+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 workflowState(status: AsyncStatus): "completed" | "failed" | "paused" | "stopped" {
+	return status.state === "complete" ? "completed" : status.state === "paused" ? "paused" : status.state === "stopped" ? "stopped" : "failed";
+}
+
+function withWorkflowChildren(status: AsyncStatus): AsyncStatus {
+	return {
+		...status,
+		workflowChildren: workflowChildSummary({
+			parentToolCallId: status.toolCallId ?? status.runId,
+			workflowRunId: status.runId,
+			workflowState: workflowState(status),
+			inventoryComplete: true,
+			trace: status.workflow?.trace,
+			steps: status.steps,
+		}),
+	};
+}
+
+export function findWorkflowSettlementStep(status: AsyncStatus, childRunId: string, workflowKey?: string, sessionFile?: string): WorkflowStatusStep | undefined {
+	const exact = status.steps?.find((candidate) => candidate.runId === childRunId);
+	if (exact || !workflowKey || !sessionFile) return exact;
+	const candidates = status.steps?.filter((candidate) => candidate.runId === undefined
+		&& candidate.workflowKey === workflowKey
+		&& candidate.sessionFile === sessionFile) ?? [];
+	return candidates.length === 1 ? candidates[0] : undefined;
+}
+
+export function promoteSettledPausedWorkflow(status: AsyncStatus, now = Date.now()): 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");
+	next.lastUpdate = now;
+	next.state = "failed";
+	next.endedAt = now;
+	delete next.activityState;
+	if (!failed) next.error = UNSUPPORTED_DETACHED_WORKFLOW_CONTINUATION;
+	return withWorkflowChildren(next);
+}
+
+export function applyDetachedChildSettlement(
+	status: AsyncStatus,
+	input: { childRunId: string; result: { exitCode: number | null; error?: string; interrupted?: boolean; sessionFile?: string; sessionName?: string; stopped?: boolean }; workflowKey?: string; now?: number },
+): AsyncStatus | undefined {
+	if (status.mode !== "workflow" || status.state !== "paused") return undefined;
+	const next = cloneWorkflowStatus(status);
+	const step = findWorkflowSettlementStep(next, input.childRunId, input.workflowKey, input.result.sessionFile);
+	if (!step) return undefined;
+	step.runId ??= input.childRunId;
+	const succeeded = input.result.exitCode === 0 && !input.result.error && !input.result.interrupted;
+	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 now = input.now ?? Date.now();
+	step.status = succeeded ? "completed" : "failed";
+	step.endedAt = now;
+	delete step.activityState;
+	delete step.currentTool;
+	delete step.currentToolStartedAt;
+	if (input.result.sessionFile) step.sessionFile = input.result.sessionFile;
+	if (input.result.sessionName) step.sessionName = input.result.sessionName;
+	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 = now;
+	const promoted = promoteSettledPausedWorkflow(next, now);
+	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;
+	return withWorkflowChildren(promoted ?? next);
+}
+
+export function classifyWorkflowSettlement(status: AsyncStatus, interrupted = false): 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 (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";
+}
+
+export function workflowRecoveryActions(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 }]
+		: []);
+}
+
+export function workflowTerminalOutcomeForResult(result: { timedOut?: boolean; turnBudgetExceeded?: boolean; toolBudgetBlocked?: boolean }): WorkflowTerminalOutcome | undefined {
+	if (result.timedOut) return { state: "partial", reason: "timeout" };
+	if (result.turnBudgetExceeded || result.toolBudgetBlocked) return { state: "partial", reason: "budget_exhausted" };
+	return undefined;
+}
+
+export function workflowOutputPathMappingSummary(children: readonly unknown[]): string {
+	const mappings = children.flatMap((entry) => {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+		const child = entry as Partial<WorkflowPublicChild>;
+		return child.outputPathMapping
+			? [`'${child.workflowKey ?? "child"}': requested ${child.outputPathMapping.requestedPath} -> saved ${child.outputPathMapping.savedPath}`]
+			: [];
+	});
+	return mappings.length > 0 ? ` Output path mappings: ${mappings.join("; ")}.` : "";
+}
+
+export function planWorkflowSettlement(input: {
+	status: AsyncStatus;
+	summary: string;
+	children: WorkflowPublicChild[];
+	baseResult: Record<string, unknown>;
+	receipt?: WorkflowReceipt;
+	receiptPath?: string;
+	receiptPersistenceError?: string;
+	resolution?: WorkflowTerminalResolution;
+	terminalOutcome?: WorkflowTerminalOutcome;
+	now?: number;
+	eventMetadata?: Record<string, unknown>;
+}): WorkflowSettlementPlan {
+	const now = input.now ?? Date.now();
+	let status = withWorkflowChildren(cloneWorkflowStatus(input.status));
+	let summary = input.summary;
+	let receipt = input.receipt;
+	let resolution = input.resolution;
+	if (input.receiptPersistenceError) {
+		const diagnostic = `${EVIDENCE_PERSISTENCE_FAILED}: ${input.receiptPersistenceError}`;
+		status = withWorkflowChildren({ ...status, state: "failed", error: diagnostic, activityState: undefined, endedAt: now, lastUpdate: now });
+		summary = `${diagnostic} Available child evidence was preserved, but workflow completion was not accepted.`;
+		receipt = undefined;
+		if (!resolution) resolution = classifyWorkflowSettlement(status);
+	}
+	const recovery = workflowRecoveryActions(receipt);
+	if (receipt) {
+		receipt = {
+			...receipt,
+			state: status.state === "complete" ? "complete" : status.state === "paused" ? "paused" : status.state === "stopped" ? "stopped" : "failed",
+			workflowChildren: status.workflowChildren,
+			...(resolution ? { workflowResolution: resolution, recovery } : {}),
+		};
+	}
+	const publicResult: Record<string, unknown> = {
+		...input.baseResult,
+		success: status.state === "complete",
+		state: status.state,
+		summary,
+		error: status.state === "complete" ? undefined : status.error ?? summary,
+		stopped: status.stopped ? true : undefined,
+		activityState: status.activityState,
+		workflowChildren: status.workflowChildren,
+		results: input.children,
+		...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}),
+		...(resolution ? { workflowResolution: resolution, recovery } : {}),
+		...(receipt && input.receiptPath ? { workflowReceipt: { path: input.receiptPath, receipt } } : {}),
+		timestamp: now,
+	};
+	const terminal = status.state === "complete" || status.state === "failed" || status.state === "partial" || status.state === "stopped";
+	const completionEvent = terminal ? {
+		type: "subagent.workflow.completed",
+		state: status.state,
+		...(resolution ? { workflowResolution: resolution } : {}),
+		...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}),
+		...(status.error ? { error: status.error } : {}),
+		...(status.activityState ? { activityState: status.activityState } : {}),
+		...input.eventMetadata,
+	} : undefined;
+	return { status, publicResult, receipt, recovery, completionEvent };
+}

package/dist/extensions/pi-subagents/test/e2e/real-session-subagent.test.ts

@@ -36,7 +36,7 @@ const ISOLATED_ENV_KEYS = [
 	"SELESAI_SUBAGENT_MAX_DEPTH",
 	"SELESAI_SUBAGENT_EXTRA_AGENT_DIRS",
 	"SELESAI_SUBAGENT_PARENT_SESSION",
-	"SELESAI_SUBAGENT_PI_BINARY",
+	"SELESAI_SUBAGENT_SELESAI_BINARY",
 	"SELESAI_SUBAGENTS_CODING_AGENT_PACKAGE_ROOT",
 ] as const;
 
@@ -186,7 +186,7 @@ Report active tools.`;
 		process.env.SELESAI_SUBAGENT_MAX_DEPTH = "1";
 		process.env.SELESAI_SUBAGENT_EXTRA_AGENT_DIRS = BOGUS_EXTRA_DIRS;
 		process.env.SELESAI_SUBAGENT_PARENT_SESSION = "polluted-parent";
-		process.env.SELESAI_SUBAGENT_PI_BINARY = BOGUS_PI_BINARY;
+		process.env.SELESAI_SUBAGENT_SELESAI_BINARY = BOGUS_PI_BINARY;
 		process.env.SELESAI_SUBAGENTS_CODING_AGENT_PACKAGE_ROOT = BOGUS_PI_PACKAGE_ROOT;
 
 		try {