pi-subagents 0.57.0 → 0.59.0

package/src/workflows/workflow-child-summary.ts

@@ -3,6 +3,7 @@ import type { WorkflowScriptChildResult, WorkflowScriptTraceEntry } from "./scri
 
 const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const TERMINAL_STATES = new Set(["completed", "failed", "paused", "stopped", "rejected", "detached"]);
+const MAX_REQUIRED_ID_BYTES = 4_096;
 
 function bounded(value: unknown, maxBytes: number): string | undefined {
 	if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value, "utf8") > maxBytes) return undefined;
@@ -10,8 +11,8 @@ function bounded(value: unknown, maxBytes: number): string | undefined {
 }
 
 function requiredId(value: string, label: string): string {
-	const id = bounded(value, 256);
-	if (!id) throw new Error(`${label} must be a non-empty identifier of at most 256 UTF-8 bytes.`);
+	const id = bounded(value, MAX_REQUIRED_ID_BYTES);
+	if (!id) throw new Error(`${label} must be a non-empty identifier of at most ${MAX_REQUIRED_ID_BYTES} UTF-8 bytes.`);
 	return id;
 }
 
@@ -38,6 +39,7 @@ export function workflowChildSummary(input: {
 			state,
 			...(bounded(entry.runId, 256) ? { runId: bounded(entry.runId, 256) } : {}),
 			...(previous?.agent ? { agent: previous.agent } : {}),
+			...(previous?.sessionName ? { sessionName: previous.sessionName } : {}),
 			...(previous?.model ? { model: previous.model } : {}),
 			...(previous?.thinking ? { thinking: previous.thinking } : {}),
 		});
@@ -57,6 +59,7 @@ export function workflowChildSummary(input: {
 			state,
 			...(bounded(step.runId, 256) ? { runId: bounded(step.runId, 256) } : {}),
 			...(launchResolved && bounded(step.agent, 256) ? { agent: bounded(step.agent, 256) } : {}),
+			...(bounded(step.sessionName, 256) ? { sessionName: bounded(step.sessionName, 256) } : {}),
 			...(bounded(step.model, 256) ? { model: bounded(step.model, 256) } : {}),
 			...(bounded(step.thinking, 32) ? { thinking: bounded(step.thinking, 32) } : {}),
 		});
@@ -70,6 +73,7 @@ export function workflowChildSummary(input: {
 			state,
 			...(bounded(child.runId, 256) ? { runId: bounded(child.runId, 256) } : {}),
 			...(bounded(child.agent, 256) ? { agent: bounded(child.agent, 256) } : {}),
+			...(bounded(result?.sessionName, 256) ? { sessionName: bounded(result?.sessionName, 256) } : {}),
 			...(bounded(result?.model, 256) ? { model: bounded(result?.model, 256) } : {}),
 			...(bounded(result?.thinking, 32) ? { thinking: bounded(result?.thinking, 32) } : {}),
 		});
@@ -101,14 +105,14 @@ export function parseWorkflowChildSummary(value: unknown): WorkflowChildSummaryV
 	const children = input.children.map((row): WorkflowChildSummaryV1["children"][number] => {
 		if (!row || typeof row !== "object" || Array.isArray(row)) throw new Error("workflowChildren child row is invalid.");
 		const child = row as Record<string, unknown>;
-		if (Object.keys(child).some((key) => !["childId", "runId", "agent", "model", "thinking", "state"].includes(key))) throw new Error("workflowChildren child row has unsupported fields.");
+		if (Object.keys(child).some((key) => !["childId", "runId", "agent", "sessionName", "model", "thinking", "state"].includes(key))) throw new Error("workflowChildren child row has unsupported fields.");
 		if (typeof child.childId !== "string" || !KEY_PATTERN.test(child.childId)) throw new Error("workflowChildren childId is invalid.");
 		const state = child.state;
 		if (state !== "pending" && state !== "running" && state !== "completed" && state !== "failed" && state !== "paused" && state !== "stopped" && state !== "rejected" && state !== "detached") throw new Error("workflowChildren child state is invalid.");
-		for (const [field, maxBytes] of [["runId", 256], ["agent", 256], ["model", 256], ["thinking", 32]] as const) {
+		for (const [field, maxBytes] of [["runId", 256], ["agent", 256], ["sessionName", 256], ["model", 256], ["thinking", 32]] as const) {
 			if (child[field] !== undefined && bounded(child[field], maxBytes) === undefined) throw new Error(`workflowChildren child ${field} is invalid.`);
 		}
-		return { childId: child.childId, state, ...(child.runId ? { runId: child.runId as string } : {}), ...(child.agent ? { agent: child.agent as string } : {}), ...(child.model ? { model: child.model as string } : {}), ...(child.thinking ? { thinking: child.thinking as string } : {}) };
+		return { childId: child.childId, state, ...(child.runId ? { runId: child.runId as string } : {}), ...(child.agent ? { agent: child.agent as string } : {}), ...(child.sessionName ? { sessionName: child.sessionName as string } : {}), ...(child.model ? { model: child.model as string } : {}), ...(child.thinking ? { thinking: child.thinking as string } : {}) };
 	});
 	if (new Set(children.map((child) => child.childId)).size !== children.length) throw new Error("workflowChildren has duplicate childId values.");
 	if (typeof input.parentToolCallId !== "string") throw new Error("workflowChildren.parentToolCallId is invalid.");

package/src/workflows/workflow-preflight.ts

@@ -0,0 +1,270 @@
+import type { WorkflowPreflightLaneV1, WorkflowPreflightV1 } from "../shared/types.ts";
+
+export const WORKFLOW_PREFLIGHT_VERSION = 1 as const;
+export const WORKFLOW_PREFLIGHT_MAX_LANES = 64;
+export const WORKFLOW_PREFLIGHT_MAX_STRING_LENGTH = 256;
+export const WORKFLOW_PREFLIGHT_MAX_CLAIMS = 16;
+export const WORKFLOW_PREFLIGHT_MAX_DEPTH = 3;
+export const WORKFLOW_PREFLIGHT_MAX_BYTES = 16 * 1024;
+export const WORKFLOW_PREFLIGHT_MAX_WARNINGS = 16;
+
+const WORKFLOW_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const PREFLIGHT_FIELDS = new Set(["version", "coverage", "lanes"]);
+const LANE_FIELDS = new Set(["key", "mode", "decision", "claims", "expectedOutput", "independence"]);
+const PREFLIGHT_MODES = new Set<WorkflowPreflightLaneV1["mode"]>(["mutation", "review", "scout", "gate"]);
+
+type WorkflowTraceLike = {
+	operation: string;
+	key: string;
+	phase?: string;
+	generatedLaneKey?: string;
+	warning?: string;
+};
+
+export interface WorkflowPreflightValidationResult {
+	ok: boolean;
+	preflight?: WorkflowPreflightV1;
+	error?: string;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+function assertPlainObject(value: unknown, path: string): asserts value is Record<string, unknown> {
+	if (!isPlainObject(value)) throw new Error(`${path} must be a plain JSON object.`);
+	if (Object.getOwnPropertySymbols(value).length > 0) throw new Error(`${path} must not contain symbol keys.`);
+	for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+		if (!descriptor.enumerable || !("value" in descriptor)) throw new Error(`${path}.${key} must be an enumerable data property.`);
+	}
+}
+
+function assertKnownFields(value: Record<string, unknown>, allowed: ReadonlySet<string>, path: string): void {
+	for (const key of Object.keys(value)) {
+		if (!allowed.has(key)) throw new Error(`${path} contains unsupported field '${key}'.`);
+	}
+}
+
+function normalizeDisplayString(value: unknown, path: string): string {
+	if (typeof value !== "string") throw new Error(`${path} must be a string.`);
+	const normalized = value
+		.replace(/[\u0000-\u001f\u007f]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	if (!normalized) throw new Error(`${path} must be a non-empty string.`);
+	if (normalized.length > WORKFLOW_PREFLIGHT_MAX_STRING_LENGTH) {
+		throw new Error(`${path} exceeds the maximum length of ${WORKFLOW_PREFLIGHT_MAX_STRING_LENGTH}.`);
+	}
+	return normalized;
+}
+
+function normalizeLane(value: unknown, index: number): WorkflowPreflightLaneV1 {
+	const path = `preflight.lanes[${index}]`;
+	assertPlainObject(value, path);
+	assertKnownFields(value, LANE_FIELDS, path);
+	const key = normalizeDisplayString(value.key, `${path}.key`);
+	if (!WORKFLOW_KEY_PATTERN.test(key)) throw new Error(`${path}.key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.`);
+	let mode: WorkflowPreflightLaneV1["mode"];
+	if (value.mode !== undefined) {
+		if (typeof value.mode !== "string" || !PREFLIGHT_MODES.has(value.mode as WorkflowPreflightLaneV1["mode"])) {
+			throw new Error(`${path}.mode must be one of: mutation, review, scout, gate.`);
+		}
+		mode = value.mode as WorkflowPreflightLaneV1["mode"];
+	}
+	let claims: string[] | undefined;
+	if (value.claims !== undefined) {
+		if (!Array.isArray(value.claims)) throw new Error(`${path}.claims must be an array of strings.`);
+		if (value.claims.length > WORKFLOW_PREFLIGHT_MAX_CLAIMS) throw new Error(`${path}.claims supports at most ${WORKFLOW_PREFLIGHT_MAX_CLAIMS} entries.`);
+		claims = value.claims.map((claim, claimIndex) => normalizeDisplayString(claim, `${path}.claims[${claimIndex}]`));
+		for (let claimIndex = 0; claimIndex < value.claims.length; claimIndex += 1) {
+			if (!Object.prototype.hasOwnProperty.call(value.claims, claimIndex)) throw new Error(`${path}.claims must not contain sparse arrays.`);
+		}
+	}
+	return {
+		key,
+		...(mode ? { mode } : {}),
+		...(value.decision !== undefined ? { decision: normalizeDisplayString(value.decision, `${path}.decision`) } : {}),
+		...(claims ? { claims } : {}),
+		...(value.expectedOutput !== undefined ? { expectedOutput: normalizeDisplayString(value.expectedOutput, `${path}.expectedOutput`) } : {}),
+		...(value.independence !== undefined ? { independence: normalizeDisplayString(value.independence, `${path}.independence`) } : {}),
+	};
+}
+
+/**
+ * Validate and canonicalize the explicit preflight input. This is intentionally
+ * independent of workflowScript parsing: callers may describe dynamic fanout
+ * without making the metadata a second execution graph.
+ */
+export function normalizeWorkflowPreflight(input: unknown): WorkflowPreflightV1 | undefined {
+	if (input === undefined) return undefined;
+	assertPlainObject(input, "preflight");
+	assertKnownFields(input, PREFLIGHT_FIELDS, "preflight");
+	if (input.version !== WORKFLOW_PREFLIGHT_VERSION) throw new Error(`preflight.version must be ${WORKFLOW_PREFLIGHT_VERSION}.`);
+	const coverage = input.coverage === undefined ? "partial" : input.coverage;
+	if (coverage !== "complete" && coverage !== "partial") throw new Error("preflight.coverage must be 'complete' or 'partial'.");
+	if (!Array.isArray(input.lanes)) throw new Error("preflight.lanes must be an array.");
+	if (input.lanes.length > WORKFLOW_PREFLIGHT_MAX_LANES) throw new Error(`preflight.lanes supports at most ${WORKFLOW_PREFLIGHT_MAX_LANES} lanes.`);
+	for (let index = 0; index < input.lanes.length; index += 1) {
+		if (!Object.prototype.hasOwnProperty.call(input.lanes, index)) throw new Error("preflight.lanes must not contain sparse arrays.");
+	}
+	const lanes = input.lanes.map(normalizeLane);
+	const seenKeys = new Set<string>();
+	for (const lane of lanes) {
+		if (seenKeys.has(lane.key)) throw new Error(`preflight.lanes contains duplicate key '${lane.key}'.`);
+		seenKeys.add(lane.key);
+	}
+	const normalized = { version: WORKFLOW_PREFLIGHT_VERSION, coverage, lanes } satisfies WorkflowPreflightV1;
+	const depth = 1 + (lanes.length > 0 ? 1 : 0) + (lanes.some((lane) => lane.claims !== undefined) ? 1 : 0);
+	if (depth > WORKFLOW_PREFLIGHT_MAX_DEPTH) throw new Error(`preflight exceeds the maximum nesting depth of ${WORKFLOW_PREFLIGHT_MAX_DEPTH}.`);
+	const bytes = Buffer.byteLength(JSON.stringify(normalized), "utf8");
+	if (bytes > WORKFLOW_PREFLIGHT_MAX_BYTES) throw new Error(`preflight canonical JSON is ${bytes} bytes; maximum is ${WORKFLOW_PREFLIGHT_MAX_BYTES}.`);
+	return normalized;
+}
+
+export function validateWorkflowPreflight(input: unknown): WorkflowPreflightValidationResult {
+	try {
+		const preflight = normalizeWorkflowPreflight(input);
+		return { ok: true, ...(preflight ? { preflight } : {}) };
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function warningLimit(messages: string[]): string[] {
+	if (messages.length <= WORKFLOW_PREFLIGHT_MAX_WARNINGS) return messages;
+	const omitted = messages.length - WORKFLOW_PREFLIGHT_MAX_WARNINGS + 1;
+	return [...messages.slice(0, WORKFLOW_PREFLIGHT_MAX_WARNINGS - 1), `Preflight advisory: ${omitted} additional mismatch warning(s) omitted.`];
+}
+
+function declaredKeys(preflight: WorkflowPreflightV1): Set<string> {
+	return new Set(preflight.lanes.map((lane) => lane.key));
+}
+
+/**
+ * Treat declared lane keys as plan roots: `lane` is the lane itself and
+ * `lane.stage` is a stage by convention, even without generated provenance.
+ */
+function declaredLaneCoversWorkflowKey(entry: WorkflowTraceLike, laneKey: string): boolean {
+	return entry.key === laneKey || entry.key.startsWith(`${laneKey}.`);
+}
+
+function keyCoveredByDeclaredLane(entry: WorkflowTraceLike, declared: ReadonlySet<string>): boolean {
+	for (const laneKey of declared) if (declaredLaneCoversWorkflowKey(entry, laneKey)) return true;
+	return false;
+}
+
+function launchedEntries(trace: readonly WorkflowTraceLike[]): WorkflowTraceLike[] {
+	const entries: WorkflowTraceLike[] = [];
+	const seen = new Set<string>();
+	for (const entry of trace) {
+		if (entry.operation !== "run" || entry.phase === "auto-resume" || seen.has(entry.key)) continue;
+		seen.add(entry.key);
+		entries.push(entry);
+	}
+	return entries;
+}
+
+function undeclaredWarning(key: string): string {
+	return `Preflight advisory: workflow key '${key}' launched without a declared lane.`;
+}
+
+function unlaunchedWarning(key: string): string {
+	return `Preflight advisory: declared lane '${key}' was not launched.`;
+}
+
+/** Return bounded advisory mismatch warnings; these never reject a child launch. */
+export function workflowPreflightWarnings(
+	preflight: WorkflowPreflightV1 | undefined,
+	trace: readonly WorkflowTraceLike[],
+	options: { settled?: boolean } = {},
+): string[] {
+	if (!preflight) return [];
+	const declared = declaredKeys(preflight);
+	const launched = launchedEntries(trace);
+	const messages = launched.filter((entry) => !keyCoveredByDeclaredLane(entry, declared)).map((entry) => undeclaredWarning(entry.key));
+	if (options.settled === true) {
+		for (const lane of preflight.lanes) if (!launched.some((entry) => declaredLaneCoversWorkflowKey(entry, lane.key))) messages.push(unlaunchedWarning(lane.key));
+	}
+	return warningLimit(messages);
+}
+
+/** Attach the first undeclared-key warning to its first trace row for status/debug views. */
+export function annotateWorkflowPreflightTrace<T extends WorkflowTraceLike>(trace: readonly T[], preflight: WorkflowPreflightV1 | undefined): T[] {
+	if (!preflight) return [...trace];
+	const declared = declaredKeys(preflight);
+	const warned = new Set<string>();
+	return trace.map((entry) => {
+		if (entry.operation !== "run" || entry.phase === "auto-resume" || keyCoveredByDeclaredLane(entry, declared) || warned.has(entry.key)) return entry;
+		warned.add(entry.key);
+		return { ...entry, warning: entry.warning ?? undeclaredWarning(entry.key) };
+	});
+}
+
+function laneCell(value: string | undefined): string {
+	return value ?? "—";
+}
+
+const WORKFLOW_PREFLIGHT_PLAN_LABEL_LENGTH = 96;
+
+function planLaneLabel(lane: WorkflowPreflightLaneV1): string {
+	const value = lane.decision?.trim() || lane.key;
+	if (value.length <= WORKFLOW_PREFLIGHT_PLAN_LABEL_LENGTH) return value;
+	return `${value.slice(0, WORKFLOW_PREFLIGHT_PLAN_LABEL_LENGTH - 1).trimEnd()}…`;
+}
+
+/** Render the detailed bounded table reserved for tool output and expanded/debug views. */
+export function formatWorkflowPreflight(preflight: WorkflowPreflightV1 | undefined, options: { indent?: string } = {}): string {
+	if (!preflight) return "";
+	const indent = options.indent ?? "";
+	const count = preflight.lanes.length;
+	const lines = [
+		`${indent}Preflight: v${preflight.version} · ${preflight.coverage} · ${count} lane${count === 1 ? "" : "s"}`,
+		`${indent}  key | mode | decision | claims | expected output | independence`,
+	];
+	for (const lane of preflight.lanes) {
+		lines.push(`${indent}  ${[
+			lane.key,
+			laneCell(lane.mode),
+			laneCell(lane.decision),
+			lane.claims?.join(", ") ?? "—",
+			laneCell(lane.expectedOutput),
+			laneCell(lane.independence),
+		].join(" | ")}`);
+	}
+	return lines.join("\n");
+}
+
+export function formatWorkflowPreflightSummary(preflight: WorkflowPreflightV1 | undefined): string {
+	if (!preflight) return "";
+	const keys = preflight.lanes.slice(0, 4).map((lane) => lane.key).join(", ");
+	const remainder = preflight.lanes.length > 4 ? `, +${preflight.lanes.length - 4}` : "";
+	return `preflight · ${preflight.coverage} · ${preflight.lanes.length} lane${preflight.lanes.length === 1 ? "" : "s"}${keys ? `: ${keys}${remainder}` : ""}`;
+}
+
+/** Render the operator-facing one-line plan shown in routine status views. */
+export function formatWorkflowPreflightPlanSummary(preflight: WorkflowPreflightV1 | undefined, options: { indent?: string } = {}): string {
+	if (!preflight) return "";
+	const indent = options.indent ?? "";
+	const count = preflight.lanes.length;
+	const labels = count === 1
+		? planLaneLabel(preflight.lanes[0]!)
+		: preflight.lanes.slice(0, 4).map((lane) => lane.key).join(", ") + (count > 4 ? `, +${count - 4}` : "");
+	return `${indent}Plan: ${count} lane${count === 1 ? "" : "s"}${labels ? ` · ${labels}` : ""}`;
+}
+
+/** Render a bounded, non-alarming warning for routine status views. */
+export function formatWorkflowPreflightWarningSummary(warnings: readonly string[] | undefined, options: { indent?: string; hint?: string } = {}): string {
+	if (!warnings?.length) return "";
+	const indent = options.indent ?? "";
+	const hint = options.hint ?? "details available for debug";
+	const count = warnings.length;
+	return `${indent}Plan note: ${count} preflight mismatch${count === 1 ? "" : "es"} · ${hint}.`;
+}
+
+export function formatWorkflowPreflightWarnings(warnings: readonly string[] | undefined, options: { indent?: string } = {}): string {
+	if (!warnings?.length) return "";
+	const indent = options.indent ?? "";
+	return [`${indent}Preflight warnings:`, ...warnings.map((warning) => `${indent}  - ${warning.replace(/\s+/g, " ").trim()}`)].join("\n");
+}

package/src/workflows/workflow-receipt.ts

@@ -1,14 +1,17 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
-import type { ExternalCliReceiptMetadata, 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}$/;
 
@@ -33,7 +36,9 @@ 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");
@@ -42,12 +47,16 @@ export function buildWorkflowReceipt(input: {
 	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 } : {}),
@@ -59,7 +68,10 @@ export function buildWorkflowReceipt(input: {
 			? { ...base, latestRunId: latestRunId!, resumability }
 			: { ...base, ...(latestRunId ? { latestRunId } : {}), resumability };
 	}
-	return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...(input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}) };
+	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 {
@@ -68,6 +80,26 @@ 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,
@@ -170,6 +202,14 @@ function parseExternalCliReceiptMetadata(value: unknown, key: string, source: st
 	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>;
@@ -190,15 +230,39 @@ 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.`);
+	const terminalOutcome = parseTerminalOutcome(entry.terminalOutcome, `Invalid workflow receipt '${source}': entry '${key}' terminalOutcome`);
 	parseExternalCliReceiptMetadata(entry.externalAdapter, key, source);
-	return value as WorkflowReceiptEntry;
+	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") {
 			const workflowDir = path.dirname(receiptPath);
@@ -222,7 +286,17 @@ export function readWorkflowReceipt(asyncDirRoot: string, workflowRunId: string)
 	for (const [key, entry] of Object.entries(receipt.entries as Record<string, unknown>)) entries[assertKey(key, "workflow receipt key")] = parseEntry(entry, key, receiptPath);
 	const workflowChildren = parseWorkflowChildSummary(receipt.workflowChildren);
 	if (workflowChildren && workflowChildren.workflowRunId !== workflowRunId) throw new Error(`Workflow receipt '${receiptPath}' is stale: workflowChildren.workflowRunId does not match.`);
-	return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries, ...(workflowChildren ? { workflowChildren } : {}) };
+	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: {