pi-subagents 0.67.0 → 0.69.0

package/src/watchdog/runtime.ts

@@ -14,6 +14,7 @@ import { WatchdogScopeArtifact } from "./scope.ts";
 import { resolveWatchdogConfig } from "./settings.ts";
 import { formatWatchdogOrchestrationActivity, formatWatchdogTurnDelta } from "./turn-delta.ts";
 import {
+	WATCHDOG_WARNING_IMPORTANCES,
 	type ResolvedWatchdogConfig,
 	type WatchdogEndpointConfig,
 	type WatchdogLspRuntimeSnapshot,
@@ -31,6 +32,8 @@ type ReviewStopReason = "stop" | "error" | "aborted" | "length";
 export interface WatchdogReviewResult {
 	warnings?: WatchdogWarning[];
 	stopReason?: ReviewStopReason;
+	/** Provider error text for a failed review, surfaced in status `Last error`. */
+	errorMessage?: string;
 	clarification?: { question: string; evidence: string };
 }
 
@@ -83,6 +86,7 @@ interface MainWatchdogRuntimeOptions {
 	review?: WatchdogReviewFunction;
 	reviewDescription?: string;
 	displayWarning?: (warning: WatchdogWarningDetails, options?: WatchdogWarningSendOptions) => void;
+	displayUserWarning?: (warning: WatchdogWarningDetails) => void;
 	/** Supplying this main-session delivery capability gates clarification (children omit it). */
 	displayClarification?: (content: string) => void;
 	reviewChangesOnly?: boolean;
@@ -130,6 +134,7 @@ export class MainWatchdogRuntime {
 	private readonly reviewConnected: boolean;
 	private readonly reviewDescription: string;
 	private readonly displayWarning: ((warning: WatchdogWarningDetails, options?: WatchdogWarningSendOptions) => void) | undefined;
+	private readonly displayUserWarning: ((warning: WatchdogWarningDetails) => void) | undefined;
 	private readonly reviewChangesOnly: boolean;
 	private readonly lspDiagnostics: WatchdogLspDiagnosticsFunction;
 	private readonly repoChangeSignature: typeof computeWatchdogRepoChangeSignature;
@@ -187,6 +192,7 @@ export class MainWatchdogRuntime {
 		this.reviewConnected = Boolean(options.review);
 		this.reviewDescription = options.reviewDescription ?? (options.review ? "injected seam" : "not wired");
 		this.displayWarning = options.displayWarning;
+		this.displayUserWarning = options.displayUserWarning;
 		this.displayClarification = options.displayClarification;
 		this.reviewChangesOnly = options.reviewChangesOnly === true;
 		this.lspDiagnostics = options.lspDiagnostics ?? collectWatchdogLspDiagnostics;
@@ -268,7 +274,7 @@ export class MainWatchdogRuntime {
 		return this.getSnapshot();
 	}
 
-	reset(_reason = "reset", options: { clearReviewInputSignature?: boolean; resetChangeSignature?: boolean; clearLspLedger?: boolean; clearScope?: boolean } = {}): void {
+	reset(_reason = "reset", options: { clearReviewInputSignature?: boolean; resetChangeSignature?: boolean; clearLspLedger?: boolean; clearScope?: boolean; clearActivity?: boolean } = {}): void {
 		this.activeReviewAbortController?.abort();
 		this.abortActiveAgentEnd();
 		this.epoch++;
@@ -290,10 +296,8 @@ export class MainWatchdogRuntime {
 			this.lspLedger.reset();
 			this.lastLspSnapshot = undefined;
 		}
-		if (options.clearScope) {
-			this.scope.reset();
-			this.clearActivity();
-		}
+		if (options.clearScope) this.scope.reset();
+		if (options.clearScope || options.clearActivity) this.clearActivity();
 		if (options.clearReviewInputSignature) this.lastReviewInputSignature = undefined;
 		if (options.resetChangeSignature) this.resetRepoChangeBaseline({ reviewed: true });
 		this.guard.reset();
@@ -467,13 +471,13 @@ export class MainWatchdogRuntime {
 		this.ruleWarningsThisRun.add(violation.summary);
 		const details = normalizeWatchdogWarningDetails(ruleViolationWarning(violation), { state: "displayed", displayedAt: new Date().toISOString() });
 		this.lastWarning = details;
-		this.displayWarning?.(details, { deliverAs: "steer" });
+		this.routeWarning(details, { deliverAs: "steer" });
 	}
 
-	recordDisplayedWarning(warning: WatchdogWarning): WatchdogWarningDetails {
+	displayRecordedWarning(warning: WatchdogWarning): void {
 		const details = normalizeWatchdogWarningDetails(warning, { state: "displayed", source: warning.source ?? "main" });
 		this.lastWarning = details;
-		return details;
+		this.routeWarning(details);
 	}
 
 	getSnapshot(cwd?: string): WatchdogRuntimeSnapshot {
@@ -536,7 +540,13 @@ export class MainWatchdogRuntime {
 	}
 
 	private warningMeetsThreshold(warning: WatchdogWarning): boolean {
-		return this.configResult.config.severityThreshold === "concern" || warning.severity === "blocker";
+		return (WATCHDOG_WARNING_IMPORTANCES as readonly string[]).includes(warning.importance)
+			&& (this.configResult.config.severityThreshold === "concern" || warning.severity === "blocker");
+	}
+
+	private routeWarning(details: WatchdogWarningDetails, options?: WatchdogWarningSendOptions): void {
+		if (details.importance === "high") this.displayWarning?.(details, options);
+		else this.displayUserWarning?.(details);
 	}
 
 	private acceptWarning(epoch: number, reviewId: number, warning: WatchdogWarning): boolean {
@@ -658,7 +668,8 @@ export class MainWatchdogRuntime {
 			}
 			for (const warning of result.warnings ?? []) this.acceptWarning(reviewEpoch, reviewId, warning);
 			if (result.stopReason && result.stopReason !== "stop") {
-				this.fail(`Watchdog review ended with stop reason '${result.stopReason}'.`);
+				const detail = result.errorMessage?.trim() ? ` ${boundWatchdogReviewText(result.errorMessage.trim(), 600)}` : "";
+				this.fail(`Watchdog review ended with stop reason '${result.stopReason}'.${detail}`);
 				return "completed";
 			}
 			this.displayAcceptedReviewWarning(options.correction);
@@ -690,7 +701,7 @@ export class MainWatchdogRuntime {
 		};
 		if (correction) {
 			this.lastWarning = details;
-			this.displayWarning?.(details, { deliverAs: "steer" });
+			this.routeWarning(details, { deliverAs: "steer" });
 			return;
 		}
 		this.deliverBoundaryWarning(details);
@@ -711,7 +722,7 @@ export class MainWatchdogRuntime {
 			: details;
 		this.stalemate = stalemate;
 		this.lastWarning = delivered;
-		this.displayWarning?.(delivered, stalemate ? { triggerTurn: false } : undefined);
+		this.routeWarning(delivered, stalemate ? { triggerTurn: false } : undefined);
 	}
 
 	// The previous boundary finding is a repeat to count, not a duplicate, until stalemate.

package/src/watchdog/settings.ts

@@ -111,9 +111,9 @@ const ROLE_MODEL_RULE_FIELDS = new Set(["allow", "deny", "note"]);
 const GUIDANCE_FIELDS = new Set(["watchdogMd"]);
 const SCOPE_FIELDS = new Set(["enabled"]);
 const CADENCE_FIELDS = new Set(["everyNTools"]);
-const ENDPOINT_FIELDS = new Set(["enabled", "model", "fallbackModels", "thinking"]);
-const CHILDREN_FIELDS = new Set(["enabled", "model", "fallbackModels", "thinking", "watchdogTailTimeoutMs", "cadence", "overrides"]);
-const CHILD_OVERRIDE_FIELDS = new Set(["enabled", "model", "fallbackModels", "thinking", "cadence"]);
+const ENDPOINT_FIELDS = new Set(["enabled", "model", "thinking"]);
+const CHILDREN_FIELDS = new Set(["enabled", "model", "thinking", "watchdogTailTimeoutMs", "cadence", "overrides"]);
+const CHILD_OVERRIDE_FIELDS = new Set(["enabled", "model", "thinking", "cadence"]);
 const LSP_FIELDS = new Set(["enabled", "timeoutMs", "maxFiles", "maxDiagnostics"]);
 
 function cloneDefaultConfig(): ResolvedWatchdogConfig {
@@ -221,7 +221,6 @@ function parseEndpointPatch(value: unknown, field: string, meta: ParseMeta): Wat
 	const input = parseObject(value, field, meta);
 	assertKnownFields(input, ENDPOINT_FIELDS, field, meta);
 	const patch: WatchdogEndpointPatch = {};
-	if ("fallbackModels" in input) patch.fallbackModels = parseStringList(input.fallbackModels, `${field}.fallbackModels`, meta);
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
 	if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
 	if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);
@@ -232,7 +231,6 @@ function parseChildOverridePatch(value: unknown, field: string, meta: ParseMeta)
 	const input = parseObject(value, field, meta);
 	assertKnownFields(input, CHILD_OVERRIDE_FIELDS, field, meta);
 	const patch: WatchdogChildOverridePatch = {};
-	if ("fallbackModels" in input) patch.fallbackModels = parseStringList(input.fallbackModels, `${field}.fallbackModels`, meta);
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
 	if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
 	if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);
@@ -244,7 +242,6 @@ function parseChildrenPatch(value: unknown, field: string, meta: ParseMeta): Wat
 	const input = parseObject(value, field, meta);
 	assertKnownFields(input, CHILDREN_FIELDS, field, meta);
 	const patch: WatchdogChildrenPatch = {};
-	if ("fallbackModels" in input) patch.fallbackModels = parseStringList(input.fallbackModels, `${field}.fallbackModels`, meta);
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
 	if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
 	if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);

package/src/watchdog/types.ts

@@ -15,8 +15,8 @@ export const WATCHDOG_WARNING_CATEGORIES = [
 ] as const;
 export type WatchdogCategory = typeof WATCHDOG_WARNING_CATEGORIES[number];
 
-export const WATCHDOG_WARNING_CONFIDENCES = ["medium", "high"] as const;
-export type WatchdogConfidence = typeof WATCHDOG_WARNING_CONFIDENCES[number];
+export const WATCHDOG_WARNING_IMPORTANCES = ["low", "medium", "high"] as const;
+export type WatchdogImportance = typeof WATCHDOG_WARNING_IMPORTANCES[number];
 
 export const WATCHDOG_WARNING_SOURCES = ["main", "child", "lsp"] as const;
 export type WatchdogWarningSource = typeof WATCHDOG_WARNING_SOURCES[number];
@@ -44,11 +44,11 @@ export type WatchdogWarningState = typeof WATCHDOG_WARNING_STATES[number];
 
 export interface WatchdogWarning {
 	severity: WatchdogSeverity;
+	importance: WatchdogImportance;
 	summary: string;
 	evidence: string;
 	recommendedAction: string;
 	category?: WatchdogCategory;
-	confidence?: WatchdogConfidence;
 	source?: WatchdogWarningSource;
 	agent?: string;
 	runId?: string;
@@ -87,14 +87,12 @@ export interface WatchdogCadenceConfig {
 export interface WatchdogEndpointConfig {
 	enabled: boolean;
 	model?: string;
-	fallbackModels?: string[];
 	thinking?: string | false;
 }
 
 export interface WatchdogChildOverrideConfig {
 	enabled?: boolean;
 	model?: string;
-	fallbackModels?: string[];
 	thinking?: string | false;
 	cadence?: Partial<WatchdogCadenceConfig>;
 }

package/src/watchdog/warning-format.ts

@@ -34,12 +34,12 @@ export function formatWatchdogWarningContent(warning: WatchdogWarning): string {
 	const details = normalizeWatchdogWarningDetails(warning);
 	const attrs = [
 		`severity="${escapeXmlAttribute(details.severity)}"`,
+		`importance="${escapeXmlAttribute(details.importance)}"`,
 		`category="${escapeXmlAttribute(details.category)}"`,
 		`source="${escapeXmlAttribute(details.source)}"`,
 		`guidance="weigh, don't blindly obey"`,
 	];
 	const optionalTags = [
-		tag("confidence", details.confidence),
 		tag("agent", details.agent),
 		tag("run_id", details.runId),
 		tag("state", details.state),

package/src/workflows/scripted-workflow.ts

@@ -1,11 +1,11 @@
-import { readFileSync } from "node:fs";
+import { accessSync, constants, readFileSync, realpathSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve as resolvePath } from "node:path";
 import { Worker } from "node:worker_threads";
 import { DEFAULT_GLOBAL_CONCURRENCY_LIMIT, Semaphore } from "../runs/shared/parallel-utils.ts";
 import { HOST_STEP_MAX_COUNT } from "../runs/shared/host-step-status.ts";
 import { classifyTaskMutationIntent } from "../runs/shared/task-intent.ts";
-import { describeGateAcceptanceConflict } from "../runs/shared/acceptance.ts";
+import { describeGateAcceptanceConflict, parseGateInput } from "../runs/shared/acceptance.ts";
 import type { AcceptanceRecoveryMetadata, HostStepNode, SingleResult } from "../shared/types.ts";
 import { normalizeWorkflowHostCommandParams, type WorkflowHostCommandParams, type WorkflowHostCommandResult } from "./host-command.ts";
 
@@ -550,7 +550,7 @@ function runLanes(laneSpecs) {
       generatedKey: stage.generatedKey,
       ...workflowPlanStringMetadata(stage.params),
       ...(typeof stage.params.as === "string" && stage.params.as.trim() ? { outputName: stage.params.as.trim() } : {}),
-      ...(stage.params.outputSchema !== undefined ? { structured: true } : {}),
+      ...(stage.params.outputSchema ? { structured: true } : {}),
     })),
   })) });
   const firstItems = lanes.map((lane) => {
@@ -633,6 +633,24 @@ function validateLaneMetadata(value, label, workflowKey) {
   }
 }
 
+// Mirrors parseGateInput in src/runs/shared/acceptance.ts; the sandbox cannot import it.
+function describeGateShapeError(gate) {
+  const shape = "gate must be a non-empty command string or { command, output?: \"json\", schema?, timeoutMs? }.";
+  if (typeof gate === "string") return gate.trim() ? undefined : shape;
+  if (!gate || typeof gate !== "object" || Array.isArray(gate)) return shape;
+  for (const key of Object.keys(gate)) {
+    if (!["command", "output", "schema", "timeoutMs"].includes(key)) return "gate." + key + " is not supported.";
+  }
+  if (typeof gate.command !== "string" || !gate.command.trim()) return shape;
+  if (gate.output !== undefined && gate.output !== "json") return "gate.output must be \"json\" when present.";
+  if (gate.schema !== undefined) {
+    if (gate.output !== "json") return "gate.schema requires gate.output: \"json\".";
+    if (!gate.schema || typeof gate.schema !== "object" || Array.isArray(gate.schema)) return "gate.schema must be a JSON Schema object.";
+  }
+  if (gate.timeoutMs !== undefined && (!Number.isInteger(gate.timeoutMs) || gate.timeoutMs < 1)) return "gate.timeoutMs must be an integer >= 1.";
+  return undefined;
+}
+
 function describeGateAcceptanceConflict(gate, acceptance) {
   const render = (value) => {
     let encoded;
@@ -658,7 +676,10 @@ function validateRunCall(key, params, label, fingerprints) {
   if (params.worktree !== undefined && typeof params.worktree !== "boolean") throw new Error(label + " worktree must be true or false.");
   if (params.baseRef !== undefined && (typeof params.baseRef !== "string" || !validGitRef(params.baseRef))) throw new Error(label + " baseRef must be a valid Git ref: use HEAD or a supported named ref (for example, refs/heads/main). Full 40/64-character commit IDs and revision expressions are unsupported.");
   validateLaneMetadata(params.lane, label + " lane", key);
-  if (params.gate !== undefined && (typeof params.gate !== "string" || !params.gate.trim())) throw new Error(label + " gate must be a non-empty command string.");
+  if (params.gate !== undefined) {
+    const gateError = describeGateShapeError(params.gate);
+    if (gateError) throw new Error(label + " " + gateError);
+  }
   if (params.gate !== undefined && params.acceptance !== undefined && params.acceptance !== false) throw new Error(label + " gate cannot be combined with acceptance; use one gate command or acceptance.verify." + describeGateAcceptanceConflict(params.gate, params.acceptance));
   if (params.gate !== undefined && params.resume !== undefined) throw new Error(label + " gate is not supported with retained resume.");
   if (params.extensionBindings !== undefined && params.resume !== undefined) throw new Error(label + " extensionBindings is not supported with retained resume; resume uses the original retained child binding.");
@@ -952,6 +973,12 @@ function omitUndefinedWorkflowValues(value, seen = new Set()) {
   return normalized;
 }
 
+function deepFreezeWorkflowArgs(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const entry of Object.values(value)) deepFreezeWorkflowArgs(entry);
+  return Object.freeze(value);
+}
+
 parentPort.on("message", async (message) => {
   if (message.type === "response") {
     const entry = pending.get(message.callId);
@@ -971,6 +998,9 @@ parentPort.on("message", async (message) => {
     if (message.stateEnabled) sandbox.state = state;
     const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
     contextObjectPrototype = vm.runInContext("Object.prototype", context);
+    // Rebuild args inside the VM realm: a worker-realm object would expose the worker's unrestricted
+    // Function through args.constructor.constructor, bypassing codeGeneration.strings: false.
+    sandbox.args = deepFreezeWorkflowArgs(vm.runInContext("JSON.parse", context)(JSON.stringify(message.args ?? {})));
     let compiled;
     try {
       assertPortableWorkflowScript(message.script);
@@ -1169,6 +1199,10 @@ export interface WorkflowChildSettledNotification {
 
 export interface RunWorkflowScriptOptions {
 	script: string;
+	/** Normalized raw-script input exposed as the deeply frozen sandbox global `args`. */
+	args?: Readonly<Record<string, unknown>>;
+	/** Parent-session cwd used to recover a stale process cwd. */
+	processCwd?: string;
 	/** Workflow run ID for notifications. Required when onChildSettled is provided. */
 	workflowRunId?: string;
 	/** Host-only first-slice admission context. It is never sent to the workflow worker. */
@@ -1922,6 +1956,32 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 	}
 	const launchSemaphore = new Semaphore(options.globalConcurrencyLimit ?? DEFAULT_GLOBAL_CONCURRENCY_LIMIT);
 
+	if (options.processCwd !== undefined) {
+		let staleCwd = false;
+		try {
+			realpathSync(process.cwd());
+		} catch (error) {
+			const code = typeof error === "object" && error !== null && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
+			if (code !== "ENOENT") throw new Error("Workflow current cwd could not be validated.", { cause: error });
+			staleCwd = true;
+		}
+		try {
+			if (staleCwd) process.chdir(options.processCwd);
+			else {
+				const target = realpathSync(options.processCwd);
+				if (!statSync(target).isDirectory()) {
+					const error = new Error(`ENOTDIR: not a directory, access '${target}'`) as NodeJS.ErrnoException;
+					error.code = "ENOTDIR";
+					throw error;
+				}
+				accessSync(target, constants.X_OK);
+			}
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			throw new Error(`Workflow process cwd is unavailable: ${options.processCwd}: ${detail}`, { cause: error });
+		}
+	}
+
 	let acornPath: string;
 	try {
 		acornPath = resolveWorkflowParserEntry();
@@ -2379,8 +2439,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			if (params.baseRef !== undefined && (typeof params.baseRef !== "string" || !validGitRef(params.baseRef))) {
 				return respond(Promise.reject(new Error(`runs.run('${key}') ${BASE_REF_VALIDATION_ERROR}`)));
 			}
-			if (params.gate !== undefined && (typeof params.gate !== "string" || !params.gate.trim())) {
-				return respond(Promise.reject(new Error(`runs.run('${key}') gate must be a non-empty command string.`)));
+			if (params.gate !== undefined) {
+				const parsedGate = parseGateInput(params.gate);
+				if (!parsedGate.ok) return respond(Promise.reject(new Error(`runs.run('${key}') ${parsedGate.error}`)));
 			}
 			if (params.gate !== undefined && params.acceptance !== undefined && params.acceptance !== false) {
 				return respond(Promise.reject(new Error(`runs.run('${key}') gate cannot be combined with acceptance; use one gate command or acceptance.verify.` + describeGateAcceptanceConflict(params.gate, params.acceptance))));
@@ -2509,6 +2570,6 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			respond(deliver(promise), `runs.run('${key}') result`, (error) => children.set(key, responseBoundaryFailure(key, error)));
 		});
 
-		worker.postMessage({ type: "start", script: options.script, stateEnabled: options.state !== undefined });
+		worker.postMessage({ type: "start", script: options.script, ...(options.args ? { args: options.args } : {}), stateEnabled: options.state !== undefined });
 	});
 }

package/src/workflows/workflow-receipt.ts

@@ -37,6 +37,7 @@ export function buildWorkflowReceipt(input: {
 	workflowRunId: string;
 	state: WorkflowReceiptState;
 	children: WorkflowScriptChildResult[];
+	argsDigest?: string;
 	hostSteps?: WorkflowReceipt["hostSteps"];
 	workflowChildren?: WorkflowReceipt["workflowChildren"];
 	resource?: WorkflowResourceProvenance;
@@ -44,6 +45,7 @@ export function buildWorkflowReceipt(input: {
 	createdAt?: number;
 }): WorkflowReceipt {
 	const workflowRunId = assertSafeRunId(input.workflowRunId, "workflowRunId");
+	if (input.argsDigest !== undefined && !/^[a-f0-9]{64}$/u.test(input.argsDigest)) throw new Error("workflow receipt argsDigest must be a lowercase SHA-256 digest.");
 	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) {
@@ -75,7 +77,7 @@ export function buildWorkflowReceipt(input: {
 	const hostSteps = input.hostSteps?.map((hostStep, index) => parseHostStepNode(hostStep, `workflow receipt hostSteps[${index}]`));
 	if (hostSteps) assertUniqueHostStepIds(hostSteps, "workflow receipt");
 	const resource = parseWorkflowResource(input.resource, "workflow receipt");
-	return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}), ...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}) };
+	return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...(input.argsDigest ? { argsDigest: input.argsDigest } : {}), ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}), ...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}) };
 }
 
 export function writeWorkflowReceipt(asyncDir: string, receipt: WorkflowReceipt): string {
@@ -115,12 +117,26 @@ const EXTERNAL_CLI_CAPABILITIES = {
 	extensionBindings: false,
 } as const;
 
+function parseExternalCliMachine(value: unknown, label: string): void {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}.machine must be an object.`);
+	const machine = value as Record<string, unknown>;
+	const unknownMachine = Object.keys(machine).filter((field) => !["provider", "id", "label", "target", "session", "cwd", "remoteGit"].includes(field));
+	if (unknownMachine.length > 0) throw new Error(`${label}.machine has unsupported fields: ${unknownMachine.join(", ")}.`);
+	if (machine.provider !== "herdr" || typeof machine.id !== "string" || !machine.id.trim() || typeof machine.target !== "string" || !machine.target.trim() || typeof machine.cwd !== "string" || !machine.cwd.trim()) throw new Error(`${label}.machine is invalid.`);
+	for (const field of ["label", "session"] as const) if (machine[field] !== undefined && (typeof machine[field] !== "string" || !machine[field].trim())) throw new Error(`${label}.machine.${field} is invalid.`);
+	if (machine.remoteGit === undefined) return;
+	if (!machine.remoteGit || typeof machine.remoteGit !== "object" || Array.isArray(machine.remoteGit)) throw new Error(`${label}.machine.remoteGit must be an object.`);
+	const remoteGit = machine.remoteGit as Record<string, unknown>;
+	const unknownRemoteGit = Object.keys(remoteGit).filter((field) => !["head", "branch", "dirty"].includes(field));
+	if (unknownRemoteGit.length > 0 || (remoteGit.head !== undefined && (typeof remoteGit.head !== "string" || !remoteGit.head.trim())) || (remoteGit.branch !== undefined && (typeof remoteGit.branch !== "string" || !remoteGit.branch.trim())) || (remoteGit.dirty !== undefined && typeof remoteGit.dirty !== "boolean")) throw new Error(`${label}.machine.remoteGit is invalid.`);
+}
+
 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));
+	const unknownMetadata = Object.keys(metadata).filter((field) => !["adapter", "capabilities", "machine", "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.`);
@@ -136,6 +152,7 @@ function parseExternalCliReceiptMetadata(value: unknown, key: string, source: st
 	for (const [capability, expected] of Object.entries(EXTERNAL_CLI_CAPABILITIES)) {
 		if (capabilityRecord[capability] !== expected) throw new Error(`${label}.capabilities.${capability} is invalid.`);
 	}
+	if (metadata.machine !== undefined) parseExternalCliMachine(metadata.machine, label);
 	const safety = metadata.safety;
 	if (adapterRecord.id === "codex-exec") {
 		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
@@ -330,10 +347,11 @@ export function readWorkflowReceipt(asyncDirRoot: string, workflowRunId: string)
 		assertUniqueHostStepIds(hostSteps, receiptPath);
 	}
 	const workflowResolution = parseWorkflowResolution(receipt.workflowResolution, receiptPath);
+	if (receipt.argsDigest !== undefined && (typeof receipt.argsDigest !== "string" || !/^[a-f0-9]{64}$/u.test(receipt.argsDigest))) throw new Error(`Invalid workflow receipt '${receiptPath}': argsDigest is invalid.`);
 	const resource = parseWorkflowResource(receipt.resource, 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, ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(workflowResolution ? { workflowResolution } : {}), ...(terminalOutcome ? { terminalOutcome } : {}), ...(recovery ? { recovery } : {}) };
+	return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries, ...(receipt.argsDigest ? { argsDigest: receipt.argsDigest } : {}), ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(workflowResolution ? { workflowResolution } : {}), ...(terminalOutcome ? { terminalOutcome } : {}), ...(recovery ? { recovery } : {}) };
 }
 
 export function resolveWorkflowReceiptResumeEntry(input: {

package/src/workflows/workflow-resources.ts

@@ -125,7 +125,7 @@ function validatePlainJson(value: unknown, path: string, depth = 0): void {
 	}
 }
 
-function normalizeArgs(value: unknown): { args: Record<string, unknown> } | { error: string } {
+export function normalizeWorkflowArgs(value: unknown): { args: Record<string, unknown> } | { error: string } {
 	if (value === undefined) return { args: {} };
 	if (!isPlainRecord(value)) return { error: "workflow args must be a plain JSON object." };
 	try {
@@ -137,6 +137,17 @@ function normalizeArgs(value: unknown): { args: Record<string, unknown> } | { er
 	}
 }
 
+export function deepFreezeWorkflowArgs<T extends Record<string, unknown>>(args: T): Readonly<T> {
+	deepFreezeWorkflowValue(args);
+	return args;
+}
+
+function deepFreezeWorkflowValue(value: unknown): void {
+	if (!Array.isArray(value) && !isPlainRecord(value)) return;
+	for (const entry of Object.values(value)) deepFreezeWorkflowValue(entry);
+	Object.freeze(value);
+}
+
 function resolveRunCi(args: Readonly<Record<string, unknown>>): ReturnType<WorkflowResourceDefinition["resolve"]> {
 	const allowed = new Set(["command", "timeoutMs"]);
 	const unsupported = Object.keys(args).filter((key) => !allowed.has(key));
@@ -191,7 +202,7 @@ function resolveResource(nameValue: unknown, argsValue?: unknown, sessionId?: st
 	if (!RESOURCE_NAME_PATTERN.test(name)) return { ok: false, error: "workflow must use a safe resource name." };
 	const resource = findWorkflowResource(name) ?? (sessionId ? registry().bySession.get(sessionId)?.get(name) : undefined);
 	if (!resource) return { ok: false, error: `Unknown workflow resource '${name}'. Available resources: ${listWorkflowResourceNames().join(", ")}.` };
-	const normalizedArgs = normalizeArgs(argsValue);
+	const normalizedArgs = normalizeWorkflowArgs(argsValue);
 	if ("error" in normalizedArgs) return { ok: false, error: normalizedArgs.error };
 	const resolved = resource.resolve(normalizedArgs.args);
 	if (resolved && typeof (resolved as unknown as { then?: unknown }).then === "function") {