@selesai/code 0.13.39 → 0.14.0

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

@@ -1,12 +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 type { AcceptanceRecoveryMetadata, HostStepNode, SingleResult } from "../shared/types.ts";
+import { describeGateAcceptanceConflict, parseGateInput } from "../runs/shared/acceptance.ts";
+import type { AcceptanceRecoveryMetadata, HostStepNode, SingleResult, WorkflowScriptFailureKind } from "../shared/types.ts";
 import { normalizeWorkflowHostCommandParams, type WorkflowHostCommandParams, type WorkflowHostCommandResult } from "./host-command.ts";
 
 const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -24,11 +23,24 @@ export interface WorkflowScriptValidationError {
 	message: string;
 	line?: number;
 	column?: number;
+	kind?: "spawn-budget" | "agent";
+}
+
+export interface WorkflowScriptValidationWarning {
+	message: string;
+	kind: "dynamic-spawn-count";
 }
 
 export interface WorkflowScriptValidationResult {
 	ok: boolean;
 	errors: WorkflowScriptValidationError[];
+	warnings?: WorkflowScriptValidationWarning[];
+}
+
+export interface WorkflowScriptValidationOptions {
+	maxSubagentSpawnsPerRun?: number;
+	/** Returns why launch-time resolution would reject this literal child agent name. */
+	agentNameError?: (name: string) => string | undefined;
 }
 
 const WORKER_SOURCE = String.raw`
@@ -57,6 +69,7 @@ let topLevelWorkflowPromise;
 let suppressNativePromiseConsumption = 0;
 const activeNativePromises = [];
 const pending = new Map();
+const workflowErrorKinds = new WeakMap();
 const runKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 function validGitRef(ref) {
   if (typeof ref !== "string" || !ref || ref === "@" || new TextEncoder().encode(ref).length > 1024 || ref.startsWith("/") || ref.endsWith("/") || ref.includes("//") || ref.includes("..") || ref.includes("@{")) return false;
@@ -373,8 +386,8 @@ function laneStageRecord(stageKey, child, forcedState) {
   const ok = result?.ok === true;
   const verdict = laneStageVerdict(result);
   const blocked = laneStageIsBlocked(result);
-  const state = forcedState ?? (result?.stopped ? "stopped" : result?.detached ? "detached" : ok ? blocked ? "blocked" : "completed" : "failed");
-  const error = state !== "completed"
+  const state = forcedState ?? (result?.state === "running" ? "running" : result?.stopped ? "stopped" : result?.detached ? "detached" : ok ? blocked ? "blocked" : "completed" : "failed");
+  const error = state !== "completed" && state !== "running"
     ? state === "blocked" && blocked
       ? "Stage returned a blocked verdict."
       : typeof result?.error === "string"
@@ -539,7 +552,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) => {
@@ -622,6 +635,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;
@@ -647,7 +678,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.");
@@ -696,8 +730,26 @@ function validateHostCommand(key, params) {
   hostKeys.add(key);
 }
 
+const RUNS_ALL_PERMISSIVE_WARNING = "runs.all received runs.run(...) launch promise(s) or thenable(s). Those children were already launched individually, so runs.all cannot apply batch fingerprint validation, batch grouping in the fleet view, or collectFailure semantics; a failed child will throw at the runs.all boundary instead of returning as { ok: false }. To get full runs.all semantics, pass config objects: runs.all(items.map((item) => ({ key: item.key, agent: item.agent, task: item.task }))).";
+
+function runsAllItemThenableInfo(item, index) {
+  if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+  if (typeof item.then !== "function") return null;
+  const tracker = promiseObservationTracker(item);
+  const observation = tracker && Array.isArray(tracker.observations) ? tracker.observations.find((entry) => entry && entry.operation === "run") : undefined;
+  return {
+    key: observation && typeof observation.key === "string" ? observation.key : ("runs.all[" + index + "]"),
+    callId: observation && typeof observation.callId === "number" ? observation.callId : null,
+    promise: item,
+  };
+}
+
+let warnedPermissiveRunsAll = false;
+
 function launchRunsAll(items, generatedLaneKeys) {
   if (!Array.isArray(items)) throw new Error("runs.all(items) requires an array.");
+  const anyThenable = items.some((item, index) => runsAllItemThenableInfo(item, index) !== null);
+  if (anyThenable) return launchRunsAllPermissive(items);
   const fingerprints = new Map(runFingerprints);
   const calls = [];
   for (let index = 0; index < items.length; index++) {
@@ -714,6 +766,33 @@ function launchRunsAll(items, generatedLaneKeys) {
   return { calls, launched };
 }
 
+function launchRunsAllPermissive(items) {
+  if (!warnedPermissiveRunsAll) {
+    warnedPermissiveRunsAll = true;
+    try { capturedConsole.warn(RUNS_ALL_PERMISSIVE_WARNING); } catch { /* console emission is best-effort */ }
+  }
+  const fingerprints = new Map(runFingerprints);
+  const calls = [];
+  const launched = [];
+  for (let index = 0; index < items.length; index++) {
+    if (!Object.prototype.hasOwnProperty.call(items, index)) throw new Error("runs.all items must not contain sparse entries.");
+    const item = items[index];
+    if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("runs.all item " + index + " must be an object or a runs.run(...) launch promise.");
+    const thenable = runsAllItemThenableInfo(item, index);
+    if (thenable) {
+      calls.push({ key: thenable.key, params: {} });
+      launched.push(thenable);
+      continue;
+    }
+    const { key, ...params } = item;
+    validateRunCall(key, params, "runs.all item " + index, fingerprints);
+    calls.push({ key, params });
+    launched.push(null);
+  }
+  runFingerprints = fingerprints;
+  return { calls, launched: launched.map((entry, index) => entry ?? runHostCall(calls[index].key, calls[index].params, false, undefined)) };
+}
+
 const runs = Object.freeze({
   run(key, params) {
     validateRunCall(key, params, "runs.run", runFingerprints);
@@ -722,7 +801,7 @@ const runs = Object.freeze({
   },
   all(items) {
     const { calls, launched } = launchRunsAll(items);
-    return trackRunObservation(launched.map(({ key, callId }) => ({ key, operation: "run", callId })), Promise.all(launched.map(({ promise }) => promise)).then((results) => wrapRunsAllResults(results.map(decorateWorkflowChildResult), calls.map(({ key }) => key))));
+    return trackRunObservation(launched.map(({ key, callId }) => ({ key, operation: "run", callId })), trackPromiseCombinator(launched.map(({ promise }) => promise), (values) => Promise.all(values).then((results) => wrapRunsAllResults(results.map(decorateWorkflowChildResult), calls.map(({ key }) => key)))));
   },
   lanes(laneSpecs) {
     return runLanes(laneSpecs);
@@ -794,6 +873,15 @@ function isSyntaxError(error) {
   return error instanceof SyntaxError || error?.name === "SyntaxError";
 }
 
+function postWorkflowError(error) {
+  // Pre-run syntax and portability errors are tagged "validation" where the script is compiled;
+  // anything reaching here was thrown while the script ran, including a runtime SyntaxError.
+  const taggedKind = error && (typeof error === "object" || typeof error === "function") ? workflowErrorKinds.get(error) : undefined;
+  parentPort.postMessage({ type: "error", error: isSyntaxError(error) ? formatWorkflowScriptSyntaxError(error) : formatWorkflowScriptError(error), errorKind: taggedKind ?? "script" });
+}
+
+process.on("unhandledRejection", postWorkflowError);
+
 const NESTED_ASYNC_WORKFLOW_ERROR = "workflowScript validation failed before child launch; no children launched. workflowScript does not support nested async functions. Use top-level await, plain helper functions that return runs.run(...), or explicit Promise chains so workflows stay portable across Node and Bun. Parallel plus sequential rewrite: const a = runs.run(\"a\", { agent: \"worker\", task: \"A\" }); const writer = await runs.run(\"writer\", { agent: \"worker\", task: \"Write\" }); const review = await runs.run(\"review\", { agent: \"reviewer\", task: writer.output }); const [aResult] = await Promise.all([a]); return { a: aResult.output, issue: { writerRunId: writer.runId, reviewRunId: review.runId } };";
 const AST_SCALAR_KEYS = new Set(["type", "start", "end"]);
 
@@ -896,6 +984,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);
@@ -904,7 +998,7 @@ parentPort.on("message", async (message) => {
     if (message.ok) entry.resolve(message.value);
     else {
       const error = new Error(message.error);
-      if (message.errorKind === "detached-child") error.workflowErrorKind = "detached-child";
+      if (message.errorKind === "child" || message.errorKind === "detached-child") workflowErrorKinds.set(error, message.errorKind);
       entry.reject(error);
     }
     return;
@@ -915,12 +1009,15 @@ 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);
       compiled = new vm.Script("(async () => {\n" + message.script + "\n})()", { filename: "workflow-script.js" });
     } catch (error) {
-      parentPort.postMessage({ type: "error", error: isSyntaxError(error) ? formatWorkflowScriptSyntaxError(error) : formatWorkflowScriptError(error) });
+      parentPort.postMessage({ type: "error", errorKind: "validation", error: isSyntaxError(error) ? formatWorkflowScriptSyntaxError(error) : formatWorkflowScriptError(error) });
       return;
     }
     const nativePromisePrototype = vm.runInContext("(async () => {})().constructor.prototype", context);
@@ -984,19 +1081,23 @@ parentPort.on("message", async (message) => {
     try {
       assertJsonValue(persistedValue, "return");
     } catch (error) {
-      parentPort.postMessage({ type: "error", errorPhase: "return-serialization", error: formatWorkflowScriptError(error) });
+      parentPort.postMessage({ type: "error", errorKind: "return-serialization", errorPhase: "return-serialization", error: formatWorkflowScriptError(error) });
       return;
     }
     parentPort.postMessage({ type: "complete", value: persistedValue });
   } catch (error) {
-    parentPort.postMessage({ type: "error", error: isSyntaxError(error) ? formatWorkflowScriptSyntaxError(error) : formatWorkflowScriptError(error), ...(error && error.workflowErrorKind === "detached-child" ? { errorKind: "detached-child" } : {}) });
+    postWorkflowError(error);
   }
 });
 `;
 
 export interface WorkflowScriptChildResult {
 	key: string;
+	/** True only for successfully completed child work, never for a launch receipt. */
 	ok: boolean;
+	/** An explicit async launch returned before a final child result was available. */
+	state?: "running";
+	asyncDir?: string;
 	lane?: import("../shared/types.ts").WorkflowLaneMetadata;
 	terminalOutcome?: import("../shared/types.ts").WorkflowTerminalOutcome;
 	stopped?: boolean;
@@ -1011,6 +1112,8 @@ export interface WorkflowScriptChildResult {
 	requestedContext?: "fresh" | "fork";
 	resolvedContext?: "fresh" | "fork" | "mixed";
 	outputReference?: string;
+	/** A file produced by the child runtime (output or worktree handoff), not its job directory. */
+	outputArtifactPath?: string;
 	recovery?: AcceptanceRecoveryMetadata;
 	outputPathMapping?: { requestedPath: string; savedPath: string };
 	externalAdapter?: import("../shared/types.ts").ExternalCliReceiptMetadata;
@@ -1018,6 +1121,8 @@ export interface WorkflowScriptChildResult {
 	continuation?: { runIds: string[] };
 	artifactPaths: string[];
 	results?: SingleResult[];
+	/** Came from a runtime-replaced run of the same script and args (its saved result, or its still-running child re-attached); this run launched nothing. */
+	reused?: boolean;
 }
 
 export interface WorkflowScriptTraceEntry {
@@ -1035,6 +1140,8 @@ export interface WorkflowScriptTraceEntry {
 	generatedLaneKey?: string;
 	lane?: import("../shared/types.ts").WorkflowLaneMetadata;
 	warning?: string;
+	/** The settled result came from a previous run of the same script and args; no child was launched. */
+	reused?: boolean;
 }
 
 /** Bounded plan metadata emitted when a workflow materializes a runs.lanes graph. */
@@ -1087,20 +1194,48 @@ export interface WorkflowScriptResult {
 	children: WorkflowScriptChildResult[];
 }
 
+function isWorkflowScriptFailureKind(value: unknown): value is WorkflowScriptFailureKind {
+	return value === "validation" || value === "script" || value === "child" || value === "return-serialization" || value === "timeout" || value === "detached-child" || value === "runtime";
+}
+
+function taggedWorkflowError(message: string, kind: WorkflowScriptFailureKind): Error & { workflowErrorKind: WorkflowScriptFailureKind } {
+	return Object.assign(new Error(message), { workflowErrorKind: kind });
+}
+
 export class WorkflowScriptError extends Error {
 	readonly partial: Omit<WorkflowScriptResult, "value">;
-	readonly errorKind?: "detached-child" | "timeout";
+	readonly errorKind?: WorkflowScriptFailureKind;
 
-	constructor(message: string, partial: Omit<WorkflowScriptResult, "value">, errorKind?: "detached-child" | "timeout") {
-		super(message);
+	constructor(message: string, partial: Omit<WorkflowScriptResult, "value">, errorKind?: WorkflowScriptFailureKind, options?: ErrorOptions) {
+		super(message, options);
 		this.name = "WorkflowScriptError";
 		this.partial = partial;
 		this.errorKind = errorKind;
 	}
 }
 
+export type WorkflowChildSettledOutcome = "completed" | "failed" | "paused" | "stopped";
+
+export interface WorkflowChildSettledNotification {
+	workflowRunId: string;
+	childKey: string;
+	childRunId?: string;
+	outcome: WorkflowChildSettledOutcome;
+	outputReference?: string;
+	error?: string;
+	workflowRunning: boolean;
+	/** The script-visible result, exactly as returned to the script. */
+	result: WorkflowScriptChildResult;
+}
+
 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. */
 	oneUsePermit?: { claim: (key: string) => string | undefined };
 	timeoutMs?: number;
@@ -1109,7 +1244,7 @@ export interface RunWorkflowScriptOptions {
 	continueAfterAbortWhenChildrenSettled?: (abortError: Error) => boolean;
 	/** Maximum children executing concurrently within this workflow. Defaults to 20. */
 	globalConcurrencyLimit?: number;
-	admit?: (calls: Array<{ key: string; params: Record<string, unknown> }>) => void | Promise<void>;
+	admit?: (calls: Array<{ key: string; params: Record<string, unknown> }>, signal: AbortSignal) => void | Promise<void>;
 	launch: (key: string, params: Record<string, unknown>, signal: AbortSignal, admission: { admitted: boolean; batch: boolean }) => Promise<WorkflowScriptChildResult>;
 	resolveResume?: (reference: WorkflowReceiptResumeReference | string, signal: AbortSignal, index?: number) => string | WorkflowResolvedResumeReference | Promise<string | WorkflowResolvedResumeReference>;
 	status: (keyOrRunId: string, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
@@ -1124,6 +1259,7 @@ export interface RunWorkflowScriptOptions {
 	onTrace?: (trace: WorkflowScriptTraceEntry[]) => void;
 	onLanePlan?: (lanes: WorkflowLanePlan[]) => void;
 	onEmit?: (emits: unknown[]) => void;
+	onChildSettled?: (notification: WorkflowChildSettledNotification) => void;
 }
 
 function combinedAbortSignal(signals: AbortSignal[]): AbortSignal {
@@ -1270,8 +1406,7 @@ function isExplicitReadOnlyRecoveryReview(params: Record<string, unknown>): bool
 		&& !RECOVERY_REVIEW_DELEGATION_PATTERN.test(taskMutationText)
 		&& !RECOVERY_REVIEW_ANAPHORIC_MUTATION_PATTERN.test(taskMutationText)
 		&& !RECOVERY_REVIEW_DESTRUCTIVE_COMMAND_PATTERN.test(taskMutationText)
-		&& !RECOVERY_REVIEW_DASH_LIVE_ACTION_PATTERN.test(taskDashLiveActionText)
-		&& classifyTaskMutationIntent(agent, task).kind === "read-only";
+		&& !RECOVERY_REVIEW_DASH_LIVE_ACTION_PATTERN.test(taskDashLiveActionText);
 }
 
 function recoveryBarrierMessage(sourceKey: string, target: string): string {
@@ -1346,7 +1481,9 @@ export function formatWorkflowJsonPreview(value: unknown, maxLength: number): st
 	try {
 		assertWorkflowJsonValue(value);
 		const serialized = JSON.stringify(value);
-		return typeof serialized === "string" ? serialized.slice(0, maxLength) : undefined;
+		if (typeof serialized !== "string") return undefined;
+		// Serialized JSON never ends in "…", so the suffix always means the preview was cut.
+		return serialized.length > maxLength ? `${serialized.slice(0, maxLength)}…` : serialized;
 	} catch {
 		return undefined;
 	}
@@ -1358,7 +1495,7 @@ function workflowReturnRecoveryHint(children: WorkflowScriptChildResult[]): stri
 		const fields = [child.runId ? `runId=${child.runId.slice(0, 500)}` : undefined, child.outputReference ? `outputReference=${child.outputReference.slice(0, 500)}` : undefined, child.artifactPaths[0] ? `artifact=${child.artifactPaths[0].slice(0, 500)}` : undefined].filter((field): field is string => field !== undefined);
 		return `'${child.key}'${fields.length > 0 ? ` (${fields.join(", ")})` : ""}`;
 	});
-	return ` Child work completed before return serialization failed. Recover outputs from: ${references.join(", ")}${children.length > references.length ? `, and ${children.length - references.length} more` : ""}. Return a plain projection such as { runId: child.runId, ok: child.ok, outputReference: child.outputReference }.`;
+	return ` ${children.some((child) => child.state === "running") ? "Child calls returned before return serialization failed; launch receipts do not prove completion." : "Child work completed before return serialization failed."} Recover outputs from: ${references.join(", ")}${children.length > references.length ? `, and ${children.length - references.length} more` : ""}. Return a plain projection such as { runId: child.runId, ok: child.ok, outputReference: child.outputReference }.`;
 }
 
 export interface SimpleWorkflowRunPreview {
@@ -1397,6 +1534,11 @@ function canonicalRunParams(params: Record<string, unknown>): Record<string, unk
 	return withoutAcceptance;
 }
 
+/** Canonical launch-params identity; matches the worker's stableRunJson(canonicalRunParams(params)). */
+export function workflowRunParamsFingerprint(params: Record<string, unknown>): string {
+	return stableJson(canonicalRunParams(params));
+}
+
 function validateKey(value: unknown, owner = "runs.run"): string {
 	if (typeof value !== "string" || !KEY_PATTERN.test(value)) {
 		throw new Error(`${owner} key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.`);
@@ -1426,7 +1568,7 @@ function literalString(node: unknown): string | undefined {
 	return undefined;
 }
 
-function directRunsCall(node: unknown, method: "run" | "all" | "host"): node is AstNode {
+function directRunsCall(node: unknown, method: "run" | "all" | "host" | "lanes"): boolean {
 	if (!astNode(node) || node.type !== "CallExpression" || !astNode(node.callee) || node.callee.type !== "MemberExpression") return false;
 	const property = node.callee.computed === true ? literalString(node.callee.property) : astNode(node.callee.property) && node.callee.property.type === "Identifier" ? node.callee.property.name : undefined;
 	return property === method && astNode(node.callee.object) && node.callee.object.type === "Identifier" && node.callee.object.name === "runs";
@@ -1484,6 +1626,62 @@ function walkAst(node: unknown, visit: (node: AstNode) => void, includeNestedFun
 	}
 }
 
+function bindingPatternContainsName(node: unknown, name: string): boolean {
+	if (!astNode(node)) return false;
+	if (node.type === "Identifier") return node.name === name;
+	if (node.type === "RestElement") return bindingPatternContainsName(node.argument, name);
+	if (node.type === "AssignmentPattern") return bindingPatternContainsName(node.left, name);
+	if (node.type === "ArrayPattern" && Array.isArray(node.elements)) return node.elements.some((element) => bindingPatternContainsName(element, name));
+	if (node.type === "ObjectPattern" && Array.isArray(node.properties)) return node.properties.some((property) => {
+		if (!astNode(property)) return false;
+		return property.type === "RestElement"
+			? bindingPatternContainsName(property.argument, name)
+			: property.type === "Property" && bindingPatternContainsName(property.value, name);
+	});
+	return false;
+}
+
+function definitelyReassignsBinding(node: unknown, name: string): boolean {
+	let assignment = node;
+	while (astNode(assignment) && assignment.type === "AssignmentExpression" && assignment.operator !== "&&=" && assignment.operator !== "||=" && assignment.operator !== "??=") {
+		if (bindingPatternContainsName(assignment.left, name)) return true;
+		assignment = assignment.right;
+	}
+	return false;
+}
+
+function lexicalDeclarationContainsName(node: unknown, name: string): boolean {
+	if (!astNode(node)) return false;
+	if (node.type === "VariableDeclaration" && node.kind !== "var" && Array.isArray(node.declarations)) {
+		return node.declarations.some((declaration) => astNode(declaration) && bindingPatternContainsName(declaration.id, name));
+	}
+	return (node.type === "FunctionDeclaration" || node.type === "ClassDeclaration") && bindingPatternContainsName(node.id, name);
+}
+
+function scopeShadowsIdentifier(node: AstNode, name: string): boolean {
+	if (node.type === "BlockStatement" && Array.isArray(node.body)) return node.body.some((statement) => lexicalDeclarationContainsName(statement, name));
+	if (node.type === "CatchClause") return bindingPatternContainsName(node.param, name);
+	if (node.type === "ForStatement") return lexicalDeclarationContainsName(node.init, name);
+	if (node.type === "ForInStatement" || node.type === "ForOfStatement") return lexicalDeclarationContainsName(node.left, name);
+	if (node.type === "SwitchStatement" && Array.isArray(node.cases)) {
+		return node.cases.some((entry) => astNode(entry) && Array.isArray(entry.consequent) && entry.consequent.some((statement) => lexicalDeclarationContainsName(statement, name)));
+	}
+	return false;
+}
+
+function walkAstWithoutShadowedIdentifier(node: unknown, name: string, visit: (node: AstNode) => void): void {
+	if (Array.isArray(node)) {
+		for (const item of node) walkAstWithoutShadowedIdentifier(item, name, visit);
+		return;
+	}
+	if (!astNode(node) || scopeShadowsIdentifier(node, name)) return;
+	visit(node);
+	if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") return;
+	for (const [key, child] of Object.entries(node)) {
+		if (!AST_LOCATION_KEYS.has(key)) walkAstWithoutShadowedIdentifier(child, name, visit);
+	}
+}
+
 function definitelyNonJson(node: AstNode, normalizeUndefined = false): string | undefined {
 	if (node.type === "Literal") {
 		if (typeof node.bigint === "string") return "BigInt values are not JSON-representable";
@@ -1552,6 +1750,43 @@ function validateStaticBaseRef(params: AstNode, owner: string): WorkflowScriptVa
 	return [];
 }
 
+// Children with their own cwd, agentScope, or resume resolve agents elsewhere, and a
+// spread or computed key can replace `agent`; leave those to launch-time resolution.
+function staticChildAgentNode(params: unknown): AstNode | undefined {
+	if (!astNode(params) || params.type !== "ObjectExpression" || !Array.isArray(params.properties)) return undefined;
+	let agent: AstNode | undefined;
+	for (const property of params.properties) {
+		if (!astNode(property) || property.type !== "Property") return undefined;
+		const key = staticPropertyKey(property);
+		if (key === undefined || key === "cwd" || key === "agentScope" || key === "resume") return undefined;
+		if (key === "agent") agent = property.kind === "init" && astNode(property.value) ? property.value : undefined;
+	}
+	return literalString(agent) === undefined ? undefined : agent;
+}
+
+function validateStaticChildAgents(call: AstNode, agentNameError: (name: string) => string | undefined): WorkflowScriptValidationError[] {
+	const args = Array.isArray(call.arguments) ? call.arguments : [];
+	const elements = (node: unknown): unknown[] => astNode(node) && node.type === "ArrayExpression" && Array.isArray(node.elements) ? node.elements : [];
+	// A spread or unknown computed key on the lane can replace `stages`.
+	const staticLane = (lane: unknown): lane is AstNode => astNode(lane) && lane.type === "ObjectExpression" && Array.isArray(lane.properties)
+		&& lane.properties.every((property) => astNode(property) && property.type === "Property" && staticPropertyKey(property) !== undefined);
+	const children: Array<{ owner: string; params: unknown }> = directRunsCall(call, "run")
+		? [{ owner: "runs.run", params: args[1] }]
+		: directRunsCall(call, "all")
+			? elements(args[0]).map((params) => ({ owner: "runs.all item", params }))
+			: directRunsCall(call, "lanes")
+				? elements(args[0]).flatMap((lane) => staticLane(lane) ? elements(directObjectPropertyValue(lane, "stages")).map((params) => ({ owner: "runs.lanes stage", params })) : [])
+				: [];
+	const errors: WorkflowScriptValidationError[] = [];
+	for (const child of children) {
+		const agentNode = staticChildAgentNode(child.params);
+		const agentName = literalString(agentNode);
+		const error = agentName === undefined ? undefined : agentNameError(agentName);
+		if (agentNode && error) errors.push({ kind: "agent", message: `${child.owner}: ${error}`, ...nodeLocation(agentNode) });
+	}
+	return errors;
+}
+
 function directRunsAllKeys(call: AstNode): Array<{ key: string; node: AstNode }> {
 	const args = Array.isArray(call.arguments) ? call.arguments : [];
 	const items = astNode(args[0]) && args[0].type === "ArrayExpression" && Array.isArray(args[0].elements) ? args[0].elements : [];
@@ -1563,8 +1798,121 @@ function directRunsAllKeys(call: AstNode): Array<{ key: string; node: AstNode }>
 	});
 }
 
+function containsWorkflowLaunch(node: unknown): boolean {
+	let found = false;
+	walkAst(node, (candidate) => {
+		if (directRunsCall(candidate, "run") || directRunsCall(candidate, "all") || directRunsCall(candidate, "lanes")) found = true;
+	});
+	return found;
+}
+
+function containsRunsIdentifier(node: unknown): boolean {
+	let found = false;
+	walkAst(node, (candidate) => {
+		if (candidate.type === "Identifier" && candidate.name === "runs") found = true;
+	});
+	return found;
+}
+
+function invalidatesRunsBinding(workflowBody: AstNode): boolean {
+	let invalidated = false;
+	walkAst(workflowBody, (node) => {
+		if ((node.type === "VariableDeclarator" || node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ClassDeclaration" || node.type === "ClassExpression")
+			&& containsRunsIdentifier(node.id)) invalidated = true;
+		if ((node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") && Array.isArray(node.params)
+			&& node.params.some(containsRunsIdentifier)) invalidated = true;
+		if (node.type === "CatchClause" && containsRunsIdentifier(node.param)) invalidated = true;
+		if ((node.type === "AssignmentExpression" || node.type === "UpdateExpression") && containsRunsIdentifier(node.left ?? node.argument)) invalidated = true;
+	});
+	return invalidated;
+}
+
+function containsAbruptControl(node: AstNode): boolean {
+	let found = false;
+	walkAst(node, (candidate) => {
+		if (candidate !== node && (candidate.type === "ReturnStatement" || candidate.type === "ThrowStatement" || candidate.type === "BreakStatement" || candidate.type === "ContinueStatement")) found = true;
+	}, false);
+	return found;
+}
+
+function directLaunchCall(expression: unknown): AstNode | undefined {
+	if (!astNode(expression)) return undefined;
+	const candidate = expression.type === "AwaitExpression" && astNode(expression.argument) ? expression.argument : expression;
+	return directRunsCall(candidate, "run") || directRunsCall(candidate, "all") ? candidate : undefined;
+}
+
+function staticWorkflowLaunchPlan(workflowBody: AstNode): { keys: string[]; dynamic: boolean } {
+	if (workflowBody.type !== "BlockStatement" || !Array.isArray(workflowBody.body) || invalidatesRunsBinding(workflowBody)) {
+		return { keys: [], dynamic: containsWorkflowLaunch(workflowBody) };
+	}
+	const keys = new Set<string>();
+	let dynamic = false;
+	let remainderUncertain = false;
+	const addCall = (call: AstNode): void => {
+		const args = Array.isArray(call.arguments) ? call.arguments : [];
+		let nestedLaunch = false;
+		for (const argument of args) walkAst(argument, (node) => {
+			if (node !== call && (directRunsCall(node, "run") || directRunsCall(node, "all") || directRunsCall(node, "lanes"))) nestedLaunch = true;
+		});
+		if (nestedLaunch) {
+			dynamic = true;
+			return;
+		}
+		if (directRunsCall(call, "run")) {
+			const key = literalString(args[0]);
+			if (key === undefined) dynamic = true;
+			else keys.add(key);
+			return;
+		}
+		const array = astNode(args[0]) && args[0].type === "ArrayExpression" && Array.isArray(args[0].elements) ? args[0] : undefined;
+		if (!array) {
+			dynamic = true;
+			return;
+		}
+		const batchKeys: string[] = [];
+		for (const item of array.elements as unknown[]) {
+			if (!astNode(item) || item.type !== "ObjectExpression" || !Array.isArray(item.properties)
+				|| item.properties.some((property) => !astNode(property) || property.type !== "Property" || staticPropertyKey(property) === undefined)) {
+				dynamic = true;
+				return;
+			}
+			const key = literalString(directObjectPropertyValue(item, "key"));
+			if (key === undefined) {
+				dynamic = true;
+				return;
+			}
+			batchKeys.push(key);
+		}
+		for (const key of batchKeys) keys.add(key);
+	};
+	for (const statement of workflowBody.body) {
+		if (!astNode(statement)) continue;
+		if (remainderUncertain) {
+			if (containsWorkflowLaunch(statement)) dynamic = true;
+			continue;
+		}
+		const expressions: unknown[] = [];
+		if (statement.type === "VariableDeclaration" && Array.isArray(statement.declarations)) {
+			for (const declaration of statement.declarations) if (astNode(declaration)) expressions.push(declaration.init);
+		} else if (statement.type === "ExpressionStatement") expressions.push(statement.expression);
+		else if (statement.type === "ReturnStatement" || statement.type === "ThrowStatement") expressions.push(statement.argument);
+		let handledLaunch = false;
+		for (const expression of expressions) {
+			const call = directLaunchCall(expression);
+			if (call) {
+				addCall(call);
+				handledLaunch = true;
+			} else if (containsWorkflowLaunch(expression)) dynamic = true;
+		}
+		if (!handledLaunch && expressions.length === 0 && containsWorkflowLaunch(statement)) dynamic = true;
+		if (statement.type === "ReturnStatement" || statement.type === "ThrowStatement") remainderUncertain = true;
+		else if (containsAbruptControl(statement)) remainderUncertain = true;
+	}
+	return { keys: [...keys], dynamic };
+}
+
 /** Parse a workflowScript and apply only rules that are decidable from its local syntax. */
-export function validateWorkflowScript(script: string): WorkflowScriptValidationResult {
+export function validateWorkflowScript(script: string, options: WorkflowScriptValidationOptions = {}): WorkflowScriptValidationResult {
 	const errors: WorkflowScriptValidationError[] = [];
 	if (!script.trim()) return { ok: false, errors: [{ message: "workflowScript must not be empty." }] };
 	let root: AstNode;
@@ -1583,6 +1931,8 @@ export function validateWorkflowScript(script: string): WorkflowScriptValidation
 		? root.body[0].expression.callee
 		: undefined;
 	const workflowBody = wrapper && astNode(wrapper.body) ? wrapper.body : root;
+	// A rebound `runs` may not be the workflow API, so its calls prove nothing about child launches.
+	const agentNameError = options.agentNameError && !invalidatesRunsBinding(workflowBody) ? options.agentNameError : undefined;
 	walkAst(workflowBody, (node) => {
 		if (node !== wrapper && node.async === true && (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression")) {
 			errors.push({ message: "workflowScript does not support nested async functions. Use top-level await, plain helper functions that return runs.run(...), or explicit Promise chains.", ...nodeLocation(node) });
@@ -1610,6 +1960,7 @@ export function validateWorkflowScript(script: string): WorkflowScriptValidation
 			}
 		}
 		if (directRunsCall(node, "host")) errors.push(...validateStaticHostCall(node));
+		if (agentNameError) errors.push(...validateStaticChildAgents(node, agentNameError));
 		const boundaryValue = node.type === "CallExpression" && astNode(node.callee) && node.callee.type === "Identifier" && node.callee.name === "emit" && Array.isArray(node.arguments) && astNode(node.arguments[0])
 			? node.arguments[0]
 			: node.type === "CallExpression" && astNode(node.callee) && node.callee.type === "MemberExpression" && astNode(node.callee.object) && node.callee.object.type === "Identifier" && node.callee.object.name === "state" && astNode(node.callee.property) && node.callee.property.type === "Identifier" && node.callee.property.name === "set" && Array.isArray(node.arguments) && astNode(node.arguments[1])
@@ -1631,24 +1982,44 @@ export function validateWorkflowScript(script: string): WorkflowScriptValidation
 			const statement = workflowBody.body[statementIndex];
 			if (!astNode(statement) || statement.type !== "VariableDeclaration" || !Array.isArray(statement.declarations)) continue;
 			for (const declaration of statement.declarations) {
-				if (!astNode(declaration) || !astNode(declaration.id) || declaration.id.type !== "Identifier" || !astNode(declaration.init) || declaration.init.type !== "AwaitExpression" || !directRunsCall(declaration.init.argument, "all")) continue;
+				if (!astNode(declaration) || !astNode(declaration.id) || declaration.id.type !== "Identifier" || !astNode(declaration.init) || declaration.init.type !== "AwaitExpression" || !astNode(declaration.init.argument) || !directRunsCall(declaration.init.argument, "all")) continue;
 				const name = declaration.id.name as string;
+				const laterStatements = workflowBody.body.slice(statementIndex + 1);
 				const keys = new Set(directRunsAllKeys(declaration.init.argument).map((entry) => entry.key));
 				if (keys.size === 0) continue;
 				const args = Array.isArray(declaration.init.argument.arguments) ? declaration.init.argument.arguments : [];
 				const itemCount = astNode(args[0]) && args[0].type === "ArrayExpression" && Array.isArray(args[0].elements) ? args[0].elements.length : 0;
 				const arrayResultShape = Array.from({ length: itemCount });
-				for (const later of workflowBody.body.slice(statementIndex + 1)) walkAst(later, (node) => {
-					if (node.type !== "MemberExpression" || !astNode(node.object) || node.object.type !== "Identifier" || node.object.name !== name) return;
-					const property = node.computed === true ? literalString(node.property) : astNode(node.property) && node.property.type === "Identifier" ? node.property.name as string : undefined;
-					if (property && keys.has(property) && !(property in arrayResultShape)) errors.push({ message: `runs.all returns an ordered array; '${name}.${property}' is keyed access. Use an index, destructuring, or map(...).`, ...nodeLocation(node) });
-				}, false);
+				for (const later of laterStatements) {
+					walkAstWithoutShadowedIdentifier(later, name, (node) => {
+						if (node.type !== "MemberExpression" || !astNode(node.object) || node.object.type !== "Identifier" || node.object.name !== name) return;
+						const property = node.computed === true ? literalString(node.property) : astNode(node.property) && node.property.type === "Identifier" ? node.property.name as string : undefined;
+						if (property && keys.has(property) && !(property in arrayResultShape)) errors.push({ message: `runs.all returns an ordered array; '${name}.${property}' is keyed access. Use an index, destructuring, or map(...).`, ...nodeLocation(node) });
+					});
+					if (statement.kind !== "const" && astNode(later) && later.type === "ExpressionStatement" && definitelyReassignsBinding(later.expression, name)) break;
+				}
 			}
 		}
 	}
 
+	const warnings: WorkflowScriptValidationWarning[] = [];
+	if (options.maxSubagentSpawnsPerRun !== undefined) {
+		const plan = staticWorkflowLaunchPlan(workflowBody);
+		if (plan.keys.length > options.maxSubagentSpawnsPerRun) {
+			errors.push({
+				kind: "spawn-budget",
+				message: `workflowScript statically requires child launches ${plan.keys.map((key) => `'${key}'`).join(", ")}; minimum required: ${plan.keys.length}; configured: ${options.maxSubagentSpawnsPerRun}.`,
+			});
+		}
+		if (plan.dynamic) {
+			warnings.push({
+				kind: "dynamic-spawn-count",
+				message: `workflowScript contains dynamic child launches; static validation proved ${plan.keys.length} launch(es), so runtime fan-out enforcement remains authoritative for the configured budget of ${options.maxSubagentSpawnsPerRun}.`,
+			});
+		}
+	}
 	const unique = errors.filter((error, index) => errors.findIndex((candidate) => candidate.message === error.message && candidate.line === error.line && candidate.column === error.column) === index);
-	return { ok: unique.length === 0, errors: unique };
+	return { ok: unique.length === 0, errors: unique, ...(warnings.length > 0 ? { warnings } : {}) };
 }
 function workflowStringMetadata(params: Record<string, unknown>): Pick<WorkflowScriptTraceEntry, "phase" | "label" | "agent"> {
 	return {
@@ -1692,11 +2063,11 @@ function isZeroUsage(usage: unknown): boolean {
 }
 
 function setupAbortResumeParams(params: Record<string, unknown>, result: WorkflowScriptChildResult, signal: AbortSignal): Record<string, unknown> | undefined {
-	if (signal.aborted || result.ok || result.stopped || result.interrupted || !result.runId) return undefined;
+	if (signal.aborted || result.state === "running" || result.ok || result.stopped || result.interrupted || !result.runId) return undefined;
 	const childResult = Array.isArray(result.results) && result.results.length === 1 && isRecord(result.results[0]) ? result.results[0] : undefined;
 	const error = typeof childResult?.error === "string" ? childResult.error : result.error;
 	if (error !== "This operation was aborted" || !isZeroUsage(childResult?.usage)) return undefined;
-	const messages = Array.isArray(childResult?.messages) ? childResult.messages : [];
+	const messages: unknown[] = Array.isArray(childResult?.messages) ? childResult.messages : [];
 	const message = messages.findLast((entry) => isRecord(entry) && entry.role === "assistant");
 	if (message !== undefined) {
 		if (!isRecord(message)) return undefined;
@@ -1715,20 +2086,52 @@ function setupAbortResumeParams(params: Record<string, unknown>, result: Workflo
 }
 
 export async function runWorkflowScript(options: RunWorkflowScriptOptions): Promise<WorkflowScriptResult> {
-	if (!options.script.trim()) throw new Error("workflowScript must not be empty.");
-	if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1)) throw new Error("workflow script timeout must be a positive integer.");
+	const emptyPartial = (): Omit<WorkflowScriptResult, "value"> => ({ emits: [], console: [], trace: [], children: [] });
+	if (!options.script.trim()) throw new WorkflowScriptError("workflowScript must not be empty.", emptyPartial(), "validation");
+	if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1)) throw new WorkflowScriptError("workflow script timeout must be a positive integer.", emptyPartial(), "runtime");
 	if (options.globalConcurrencyLimit !== undefined && (!Number.isSafeInteger(options.globalConcurrencyLimit) || options.globalConcurrencyLimit < 1)) {
-		throw new Error("workflow script global concurrency limit must be a positive integer.");
+		throw new WorkflowScriptError("workflow script global concurrency limit must be a positive integer.", emptyPartial(), "runtime");
 	}
 	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 WorkflowScriptError("Workflow current cwd could not be validated.", emptyPartial(), "runtime", { 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 WorkflowScriptError(`Workflow process cwd is unavailable: ${options.processCwd}: ${detail}`, emptyPartial(), "runtime", { cause: error });
+		}
+	}
+
 	let acornPath: string;
 	try {
 		acornPath = resolveWorkflowParserEntry();
 	} catch (error) {
-		throw new Error("Workflow parser dependency 'acorn' is unavailable from pi-subagents. Reinstall pi-subagents dependencies before launching workflowScript.", { cause: error });
+		throw new WorkflowScriptError("Workflow parser dependency 'acorn' is unavailable from pi-subagents. Reinstall pi-subagents dependencies before launching workflowScript.", emptyPartial(), "runtime", { cause: error });
+	}
+	let worker: Worker;
+	try {
+		worker = new Worker(WORKER_SOURCE, { eval: true, workerData: { acornPath } });
+	} catch (error) {
+		throw new WorkflowScriptError(`Workflow worker could not start: ${error instanceof Error ? error.message : String(error)}`, emptyPartial(), "runtime", { cause: error });
 	}
-	const worker = new Worker(WORKER_SOURCE, { eval: true, workerData: { acornPath } });
 	const emits: unknown[] = [];
 	const consoleEntries: WorkflowScriptResult["console"] = [];
 	const trace: WorkflowScriptTraceEntry[] = [];
@@ -1812,6 +2215,31 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 		traceChanged();
 		return true;
 	};
+	const notifyChildSettled = (key: string, result: WorkflowScriptChildResult): void => {
+		if (result.state === "running" || !options.onChildSettled || !options.workflowRunId) return;
+		const outcome: WorkflowChildSettledOutcome = result.ok
+			? "completed"
+			: result.stopped
+				? "stopped"
+				: result.detached
+					? "paused"
+					: "failed";
+		const outputReference = result.outputReference ?? result.outputArtifactPath;
+		try {
+			options.onChildSettled({
+				workflowRunId: options.workflowRunId,
+				childKey: key,
+				...(result.runId ? { childRunId: result.runId } : {}),
+				outcome,
+				...(outputReference ? { outputReference } : {}),
+				...(!result.ok && result.error ? { error: result.error } : {}),
+				workflowRunning: !settled && !finishing,
+				result,
+			});
+		} catch (error) {
+			console.error("Workflow onChildSettled callback failed:", error);
+		}
+	};
 	options.registerStopChild?.(stopChild);
 
 	return await new Promise<WorkflowScriptResult>((resolve, reject) => {
@@ -1841,8 +2269,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 							return unobservedHosts.length > 0 ? new Error(`workflowScript completed with unawaited runs.host call(s): ${unobservedHosts.map((key) => `'${key}'`).join(", ")}. Await or return each call.`) : undefined;
 						})()
 						: undefined;
-				if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial(), outcome.error.workflowErrorKind === "detached-child" || outcome.error.workflowErrorKind === "timeout" ? outcome.error.workflowErrorKind : undefined));
-				else if (completionError) reject(new WorkflowScriptError(completionError.message, partial()));
+				// Stops and reloads end through the abort paths untagged: they are not failures.
+				if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial(), isWorkflowScriptFailureKind(outcome.error.workflowErrorKind) ? outcome.error.workflowErrorKind : undefined));
+				else if (completionError) reject(new WorkflowScriptError(completionError.message, partial(), "validation"));
 				else resolve({ value: outcome.value, ...partial() });
 			});
 		};
@@ -1862,7 +2291,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				mayFlushAssembly = options.continueAfterAbortWhenChildrenSettled?.(error) === true;
 			} catch (callbackError) {
 				const callbackMessage = callbackError instanceof Error ? callbackError.message : String(callbackError);
-				return finish({ error: new Error(`Workflow assembly flush eligibility failed: ${callbackMessage}`) });
+				return finish({ error: taggedWorkflowError(`Workflow assembly flush eligibility failed: ${callbackMessage}`, "runtime") });
 			}
 			if (mayFlushAssembly && allChildrenSettled) {
 				// A reloaded async workflow may already be past its last child launch.
@@ -1894,16 +2323,14 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 		const timer = options.timeoutMs === undefined
 			? undefined
 			: setTimeout(() => {
-				const error = new Error(`Workflow script timed out after ${options.timeoutMs}ms.`) as Error & { workflowErrorKind: "timeout" };
-				error.workflowErrorKind = "timeout";
-				finish({ error });
+				finish({ error: taggedWorkflowError(`Workflow script timed out after ${options.timeoutMs}ms.`, "timeout") });
 			}, options.timeoutMs);
 		options.signal?.addEventListener("abort", onAbort, { once: true });
 		if (options.signal?.aborted) return onAbort();
 
-		worker.on("error", (error) => finish({ error: new Error(`Workflow worker failed: ${error instanceof Error ? error.message : String(error)}`) }));
+		worker.on("error", (error) => finish({ error: taggedWorkflowError(`Workflow worker failed: ${error instanceof Error ? error.message : String(error)}`, "runtime") }));
 		worker.on("exit", (code) => {
-			if (!settled && code !== 0) finish({ error: new Error(`Workflow worker exited with code ${code}.`) });
+			if (!settled && code !== 0) finish({ error: taggedWorkflowError(`Workflow worker exited with code ${code}.`, "runtime") });
 		});
 		worker.on("message", (message: Record<string, unknown>) => {
 			if (settled) return;
@@ -1915,7 +2342,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				try {
 					assertWorkflowJsonValue(message.value, "emit");
 				} catch (error) {
-					finish({ error: new Error(`Workflow emit could not be persisted: ${error instanceof Error ? error.message : String(error)}`) });
+					finish({ error: taggedWorkflowError(`Workflow emit could not be persisted: ${error instanceof Error ? error.message : String(error)}`, "runtime") });
 					return;
 				}
 				emits.push(message.value);
@@ -1923,7 +2350,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 					options.onEmit?.([...emits]);
 				} catch (error) {
 					emits.pop();
-					finish({ error: new Error(`Workflow emit could not be persisted: ${error instanceof Error ? error.message : String(error)}`) });
+					finish({ error: taggedWorkflowError(`Workflow emit could not be persisted: ${error instanceof Error ? error.message : String(error)}`, "runtime") });
 				}
 				return;
 			}
@@ -1936,16 +2363,14 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				try {
 					assertWorkflowJsonValue(message.value, "return");
 				} catch (error) {
-					return finish({ error: new Error(`Workflow return could not be persisted: ${error instanceof Error ? error.message : String(error)}`) });
+					return finish({ error: taggedWorkflowError(`Workflow return could not be persisted: ${error instanceof Error ? error.message : String(error)}`, "return-serialization") });
 				}
 				return finish({ value: message.value });
 			}
 			if (message.type === "error") {
 				const rawError = typeof message.error === "string" ? message.error : "Workflow script failed.";
 				const text = message.errorPhase === "return-serialization" ? `${rawError}${workflowReturnRecoveryHint(partial().children)}` : rawError;
-				const workflowError = new Error(text) as Error & { workflowErrorKind?: "detached-child" };
-				if (message.errorKind === "detached-child") workflowError.workflowErrorKind = "detached-child";
-				return finish({ error: workflowError });
+				return finish({ error: isWorkflowScriptFailureKind(message.errorKind) ? taggedWorkflowError(text, message.errorKind) : new Error(text) });
 			}
 			if (message.type === "callObserved" && typeof message.callId === "number") {
 				const key = typeof message.key === "string" ? message.key : undefined;
@@ -1985,7 +2410,10 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 						}
 					},
 					(error: unknown) => {
-						if (!settled) worker.postMessage({ type: "response", callId: message.callId, ok: false, error: error instanceof Error ? error.message : String(error), ...(error instanceof Error && (error as { workflowErrorKind?: unknown }).workflowErrorKind === "detached-child" ? { errorKind: "detached-child" } : {}) });
+						if (!settled) {
+							const errorKind = error instanceof Error ? (error as { workflowErrorKind?: unknown }).workflowErrorKind : undefined;
+							worker.postMessage({ type: "response", callId: message.callId, ok: false, error: error instanceof Error ? error.message : String(error), ...(isWorkflowScriptFailureKind(errorKind) ? { errorKind } : {}) });
+						}
 					},
 				);
 			};
@@ -2124,14 +2552,12 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				: promise.then((result) => {
 					const recoverableAcceptanceMetadata = result.recovery?.status === "available-for-review"
 						&& result.recovery.reason === "acceptance-metadata-rejected";
-					if (!result.ok && !result.stopped && !recoverableAcceptanceMetadata) {
-						const childError = new Error(result.detached ? `Run '${key}' detached: ${result.error ?? result.output}` : `Run '${key}' failed: ${result.error ?? result.output}`) as Error & { workflowErrorKind?: "detached-child" };
-						if (result.detached) childError.workflowErrorKind = "detached-child";
-						throw childError;
+					if (!result.ok && result.state !== "running" && !result.stopped && !recoverableAcceptanceMetadata) {
+						throw taggedWorkflowError(`Run '${key}' ${result.detached ? "detached" : "failed"}: ${result.error ?? result.output}`, result.detached ? "detached-child" : "child");
 					}
 					return result;
 				});
-			const fingerprint = stableJson(canonicalRunParams(params));
+			const fingerprint = workflowRunParamsFingerprint(params);
 			const existing = launches.get(key);
 			if (existing) {
 				if (existing.fingerprint !== fingerprint) return respond(Promise.reject(new Error(`Duplicate workflow key '${key}' used with incompatible launch params.`)));
@@ -2155,8 +2581,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))));
@@ -2192,7 +2619,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				admission = Promise.resolve().then(() => {
 					if (settled || finishing) return;
 					for (const call of calls) assertRecoveryBarrierAllowsRun(call.key, call.params);
-					return options.admit?.(calls);
+					return options.admit?.(calls, childController.signal);
 				});
 				if (batch) batchAdmissions.set(batch.id, admission);
 			}
@@ -2249,8 +2676,12 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				} finally {
 					launchSemaphore.release();
 				}
+			}, (error: unknown) => {
+				if (!childController.signal.aborted) throw error;
+				const reason = childController.signal.reason;
+				return stoppedChildResult(key, reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "Workflow script aborted.");
 			}).then((result) => {
-				let normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
+				let normalized = !result.ok && result.state !== "running" && !result.error ? { ...result, error: result.output } : result;
 				if (resolvedResumeLineage?.length && normalized.runId) {
 					normalized = { ...normalized, continuation: { runIds: [...new Set([...resolvedResumeLineage, normalized.runId])] } };
 				}
@@ -2258,9 +2689,12 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				if (stoppedLaunches.has(key)) return children.get(key) ?? normalized;
 				children.set(key, normalized);
 				recordAcceptanceRecoveryBarrier(key, normalized);
-				const state = normalized.ok ? "completed" : normalized.stopped ? "stopped" : normalized.detached ? "detached" : "failed";
-				trace.push({ operation: "run", key, state, durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(generatedLaneKey ? { generatedLaneKey } : {}), ...(normalized.agent ? { agent: normalized.agent } : {}), ...(normalized.runId ? { runId: normalized.runId } : {}), ...(!normalized.ok ? { error: normalized.error ?? normalized.output } : {}) });
+				const state = normalized.state === "running" ? "started" : normalized.ok ? "completed" : normalized.stopped ? "stopped" : normalized.detached ? "detached" : "failed";
+				const settledEntry: WorkflowScriptTraceEntry = { operation: "run", key, state, durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(generatedLaneKey ? { generatedLaneKey } : {}), ...(normalized.agent ? { agent: normalized.agent } : {}), ...(normalized.runId ? { runId: normalized.runId } : {}), ...(!normalized.ok && normalized.state !== "running" ? { error: normalized.error ?? normalized.output } : {}) };
+				if (normalized.reused) settledEntry.reused = true;
+				trace.push(settledEntry);
 				traceChanged();
+				notifyChildSettled(key, normalized);
 				return normalized;
 			}, (error: unknown) => {
 				const text = error instanceof Error ? error.message : String(error);
@@ -2270,6 +2704,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				children.set(key, failure);
 				trace.push({ operation: "run", key, state: "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(generatedLaneKey ? { generatedLaneKey } : {}), error: text });
 				traceChanged();
+				notifyChildSettled(key, failure);
 				return failure;
 			});
 			launches.set(key, { fingerprint, promise, observed: callObserved, ...(generatedLaneKey ? { generatedLaneKey } : {}) });
@@ -2279,6 +2714,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 });
 	});
-}
+}