@signalridge/pi-workflows 1.2.1 → 1.3.2

package/src/runtime.ts

@@ -0,0 +1,1708 @@
+/**
+ * runtime.ts — JS orchestration runtime for pi-workflows.
+ *
+ * A workflow is a raw JavaScript module. The runtime parses it under an acorn
+ * gate (deterministic literal `export const meta` first, no nondeterministic
+ * builtins), then executes the body inside a `node:vm` realm with a bounded set
+ * of orchestration globals (`agent`, `parallel`, `pipeline`, `workflow`,
+ * quality/control helpers, `phase`, `log`, `args`, `cwd`, restricted
+ * `process`, `budget`). The vm is a determinism guardrail, not a security
+ * boundary: scripts are generated by the user's own LLM and run on the user's
+ * own machine.
+ *
+ * Dispatch goes through the injected `WorkflowAgentRunner`, which the engine
+ * wires to the `subagents:rpc:spawn-managed` protocol — this file never talks
+ * to pi-subagents directly. Everything upstream of the actual subagent session
+ * (call sequencing, hashing, resume replay, concurrency limiting, budget,
+ * fan-out cancellation, journaling hooks) lives here and is unit-testable with
+ * a fake runner.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+import vm from "node:vm";
+import { parse } from "acorn";
+import { checkRuntimeBindings } from "./capabilities.js";
+import { WorkflowError, WorkflowErrorCode, wrapError } from "./errors.js";
+import { SharedStore } from "./shared-store.js";
+
+// ── Meta contract ────────────────────────────────────────────────────────────
+
+export interface WorkflowMetaPhase {
+  title: string;
+  detail?: string;
+  /**
+   * Phase-level model preference — currently validated but not routed.
+   * Per-call model routing requires a protocol extension (see README
+   * "Intentional divergences"); use agent({ tier }) instead.
+   */
+  model?: string;
+}
+
+export interface WorkflowMeta {
+  name: string;
+  description: string;
+  phases?: WorkflowMetaPhase[];
+  /**
+   * Run-level model preference — currently validated but not routed.
+   * Per-call model routing requires a protocol extension (see README
+   * "Intentional divergences"); use agent({ tier }) instead.
+   */
+  model?: string;
+}
+
+/** A resolved, journaled agent() call. */
+export interface JournalEntry {
+  /** The top-level run id; missing on entries persisted before namespacing. */
+  runId?: string;
+  index: number;
+  hash: string;
+  result: unknown;
+  storeDelta?: Record<string, unknown>;
+}
+
+export interface AgentUsage {
+  input: number;
+  output: number;
+  total: number;
+  cost: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+export interface SharedRuntime {
+  limiter: Limiter;
+  agentCount: number;
+  spent: number;
+  tokenUsage: AgentUsage;
+  depth: number;
+  nestedCallSeq: number;
+  runFatalController: AbortController;
+  inFlight: Set<Promise<unknown>>;
+  activeThreads: Set<string>;
+}
+
+/** Counting semaphore with a FIFO resolve queue. */
+export type Limiter = <T>(fn: () => Promise<T>) => Promise<T>;
+
+/** The dispatch boundary the engine implements over spawn-managed RPC. */
+export interface WorkflowAgentRunner {
+  run(prompt: string, options?: AgentRunOptions): Promise<unknown>;
+}
+
+export interface AgentRunOptions {
+  label?: string;
+  sessionName?: string;
+  /** Plain JSON Schema the result must satisfy; the runtime parses+validates client-side. */
+  schema?: unknown;
+  signal?: AbortSignal;
+  instructions?: string;
+  model?: string;
+  tier?: string;
+  cwd?: string;
+  /** Named subagent type; resolved by pi-subagents at dispatch. */
+  agentType?: string;
+  /** Lexical call index — engine-side spawnKey identity (A4). */
+  callIndex?: number;
+  /** Stable hash of the call inputs — engine-side resume comparison (A4). */
+  callHash?: string;
+  /** One-based attempt number within this call's retry loop. */
+  attempt?: number;
+  thread?: string;
+  /** Per-call worktree request forwarded to pi-subagents. */
+  isolation?: "worktree";
+  /** Named toolset hint forwarded to pi-subagents. */
+  toolset?: string;
+  /** Additional tool names denied for this call. */
+  excludeTools?: string[];
+  onModelResolved?: (id: string) => void;
+  onModelFallback?: (info: { tier: string; requestedSpec: string }) => void;
+  onUsage?: (usage: AgentUsage) => void;
+  onHistory?: (history: unknown[]) => void;
+}
+
+export interface AgentOptions {
+  label?: string;
+  phase?: string;
+  schema?: unknown;
+  model?: string;
+  tier?: string;
+  isolation?: "worktree";
+  agentType?: string;
+  timeoutMs?: number | null;
+  retries?: number;
+  thread?: string;
+  toolset?: string;
+  excludeTools?: string[];
+}
+
+export interface CheckpointOptions {
+  default?: unknown;
+  headless?: "default" | "abort";
+  kind?: "confirm" | "input" | "select";
+  choices?: string[];
+  timeoutMs?: number;
+}
+
+export interface WorkflowRuntimeEvent {
+  type: "phase" | "workflow" | "quality" | "control-attempt";
+  [key: string]: unknown;
+}
+
+export interface WorkflowRunOptions {
+  args?: unknown;
+  agent?: WorkflowAgentRunner;
+  /** The session's main model (provider/id), shown for default agents. */
+  mainModel?: string;
+  cwd?: string;
+  concurrency?: number;
+  agentRetries?: number;
+  tokenBudget?: number | null;
+  signal?: AbortSignal;
+  maxAgents?: number;
+  agentTimeoutMs?: number | null;
+  runId?: string;
+  resumeJournal?: Map<string, JournalEntry>;
+  resumeFromRunId?: string;
+  toolset?: string;
+  excludeTools?: string[];
+  onAgentJournal?: (entry: JournalEntry) => void;
+  onRetrySpend?: (tokens: number) => void;
+  sharedRuntime?: SharedRuntime;
+  initialTokenUsage?: AgentUsage;
+  sharedStore?: SharedStore;
+  loadSavedWorkflow?: (name: string) => string | undefined;
+  confirm?: (promptText: string, options: CheckpointOptions) => Promise<unknown>;
+  onLog?: (message: string) => void;
+  onPhase?: (title: string) => void;
+  onRuntimeEvent?: (event: WorkflowRuntimeEvent) => void;
+  onAgentStart?: (event: { id: string; label: string; phase?: string; prompt: string; model?: string }) => void;
+  onAgentEnd?: (event: {
+    id: string;
+    label: string;
+    phase?: string;
+    result: unknown;
+    tokens?: number;
+    tokenUsage?: AgentUsage;
+    worktree?: string;
+    model?: string;
+    error?: string;
+    errorCode?: WorkflowErrorCode;
+    recoverable?: boolean;
+  }) => void;
+  onAgentHistory?: (event: { id: string; label: string; phase?: string; history: unknown[] }) => void;
+  onTokenUsage?: (usage: AgentUsage) => void;
+}
+
+export interface WorkflowRunResult<T = unknown> {
+  meta: WorkflowMeta;
+  result: T;
+  logs: string[];
+  phases: string[];
+  agentCount: number;
+  durationMs: number;
+  runId?: string;
+  tokenUsage?: AgentUsage;
+}
+
+/** How agent() results that are plain text vs schema-structured are journaled. */
+export interface RuntimeState {
+  logs: string[];
+  phases: string[];
+  currentPhase?: string;
+  phaseBudgets: Map<string, { budget: number; startSpent: number; warned: boolean }>;
+  callSeq: number;
+  firstMiss: number;
+}
+
+export const MAX_AGENTS_PER_RUN = 1000;
+export const MAX_CONCURRENCY = 16;
+export const MAX_AGENT_RETRIES = 3;
+export const DEFAULT_AGENT_TIMEOUT_MS: number | null = 300_000;
+export const MAX_SCRIPT_SYNC_MS = 1_000;
+
+// ── Determinism guardrail ────────────────────────────────────────────────────
+
+const DETERMINISM_BLOCKLIST = /\bDate\s*\.\s*now\b|\bMath\s*\.\s*random\b|\bnew\s+Date\s*\(\s*\)/;
+
+/**
+ * Run inside the vm realm BEFORE the user script. Neutered builtins would break
+ * resume (a re-run would produce different values than the cached journal):
+ *   - Math.random()        -> throws
+ *   - Date.now()           -> throws
+ *   - Date() / new Date()  -> throws (no-arg); new Date(arg) still works
+ * Using the vm realm's own Math/Date/Reflect (not host objects) adds no
+ * host-`Function` escape. vm is not a security sandbox — best-effort guard
+ * against ACCIDENTAL nondeterminism from trusted scripts, not a security wall.
+ */
+const DETERMINISM_PRELUDE = [
+  '"use strict";',
+  'Math.random = () => { throw new Error("Math.random() is unavailable in a workflow (it breaks resume); pass randomness via args or vary by index"); };',
+  "{",
+  "  const RealDate = Date;",
+  '  const fail = (w) => { throw new Error(w + " is unavailable in a workflow (it breaks resume); pass a timestamp via args"); };',
+  "  const SafeDate = function (...a) {",
+  '    if (!new.target) fail("Date()");',
+  '    if (a.length === 0) fail("new Date()");',
+  "    return Reflect.construct(RealDate, a, SafeDate);",
+  "  };",
+  "  SafeDate.UTC = RealDate.UTC;",
+  "  SafeDate.parse = RealDate.parse;",
+  '  SafeDate.now = () => fail("Date.now()");',
+  "  SafeDate.prototype = RealDate.prototype;",
+  "  globalThis.Date = SafeDate;",
+  "}",
+].join("\n");
+
+// ── Script parsing gate ──────────────────────────────────────────────────────
+
+/**
+ * Parse the meta contract out of a workflow script and return the executable
+ * body (the script with the meta statement removed). The meta statement must
+ * be the first statement and must be a literal-only object; anything
+ * non-literal (spread, computed keys, methods, interpolation, reserved keys)
+ * is rejected so the meta is fully static and deterministic.
+ */
+export function parseWorkflowScript(script: string): { meta: WorkflowMeta; body: string } {
+  if (DETERMINISM_BLOCKLIST.test(script)) {
+    throw new WorkflowError(
+      "Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable",
+      WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+      { recoverable: false },
+    );
+  }
+
+  const ast = parse(script, {
+    ecmaVersion: "latest",
+    sourceType: "module",
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+    ranges: false,
+  });
+
+  const first = ast.body?.[0] as { type?: string } | undefined;
+  if (first?.type !== "ExportNamedDeclaration") {
+    throw new WorkflowError(
+      "`export const meta = { name, description, phases }` must be the first statement in the script",
+      WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+      { recoverable: false },
+    );
+  }
+
+  const declaration = (first as { declaration?: unknown }).declaration as
+    | { type?: string; kind?: string; declarations?: unknown[] }
+    | null
+    | undefined;
+  if (declaration?.type !== "VariableDeclaration" || declaration.kind !== "const") {
+    throw new WorkflowError(
+      "meta export must be `export const meta = ...`",
+      WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+      {
+        recoverable: false,
+      },
+    );
+  }
+  if (declaration.declarations?.length !== 1) {
+    throw new WorkflowError("meta export must declare only `meta`", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+      recoverable: false,
+    });
+  }
+
+  const declarator = declaration.declarations[0] as {
+    id?: { type?: string; name?: string } | null;
+    init?: unknown;
+  };
+  if (declarator.id?.type !== "Identifier" || declarator.id.name !== "meta") {
+    throw new WorkflowError("meta export must declare `meta`", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+      recoverable: false,
+    });
+  }
+  if (!declarator.init) {
+    throw new WorkflowError("meta must have a literal value", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+      recoverable: false,
+    });
+  }
+
+  const meta = evaluateLiteral(declarator.init, "meta");
+  validateMeta(meta);
+  const start = (first as { start?: number }).start ?? 0;
+  const end = (first as { end?: number }).end ?? 0;
+  return { meta, body: script.slice(0, start) + script.slice(end) };
+}
+
+interface LiteralNode {
+  type: string;
+  value?: unknown;
+  properties?: unknown[];
+  elements?: Array<unknown | null>;
+  expressions?: unknown[];
+  quasis?: Array<{ value?: { cooked?: string; raw?: string } }>;
+  argument?: unknown;
+  operator?: string;
+  key?: unknown;
+  computed?: boolean;
+  kind?: string;
+  method?: boolean;
+  name?: string;
+}
+
+function evaluateLiteral(node: unknown, path: string): unknown {
+  const n = node as LiteralNode;
+  switch (n.type) {
+    case "ObjectExpression": {
+      const out: Record<string, unknown> = {};
+      for (const rawProp of n.properties as unknown[]) {
+        const prop = rawProp as LiteralNode;
+        if (prop.type === "SpreadElement") throw new Error(`spread not allowed in ${path}`);
+        if (prop.type !== "Property") throw new Error(`only plain properties allowed in ${path}`);
+        if (prop.computed) throw new Error(`computed keys not allowed in ${path}`);
+        if (prop.kind !== "init" || prop.method) throw new Error(`methods/accessors not allowed in ${path}`);
+        const key = propertyKey(prop.key, path);
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+          throw new Error(`reserved key name not allowed in ${path}: ${key}`);
+        }
+        out[key] = evaluateLiteral((prop as { value?: unknown }).value, `${path}.${key}`);
+      }
+      return out;
+    }
+    case "ArrayExpression":
+      return (n.elements as Array<unknown | null>).map((element, index) => {
+        if (!element) throw new Error(`sparse arrays not allowed in ${path}`);
+        if ((element as LiteralNode).type === "SpreadElement") throw new Error(`spread not allowed in ${path}`);
+        return evaluateLiteral(element, `${path}[${index}]`);
+      });
+    case "Literal":
+      return n.value;
+    case "TemplateLiteral":
+      if ((n.expressions?.length ?? 0) > 0) throw new Error(`template interpolation not allowed in ${path}`);
+      return (n.quasis ?? [])
+        .map((quasi: { value?: { cooked?: string; raw?: string } }) => quasi.value?.cooked ?? quasi.value?.raw ?? "")
+        .join("");
+    case "UnaryExpression":
+      if (
+        n.operator === "-" &&
+        (n.argument as LiteralNode)?.type === "Literal" &&
+        typeof (n.argument as LiteralNode).value === "number"
+      ) {
+        return (n.argument as { value: number }).value * -1;
+      }
+      throw new Error(`only negative-number unary allowed in ${path}`);
+    default:
+      throw new Error(`non-literal node type in ${path}: ${n.type}`);
+  }
+}
+
+function propertyKey(node: unknown, path: string): string {
+  const n = node as LiteralNode;
+  if (n.type === "Identifier") return n.name as string;
+  if (n.type === "Literal" && (typeof n.value === "string" || typeof n.value === "number")) return String(n.value);
+  throw new Error(`unsupported key type in ${path}: ${n.type}`);
+}
+
+function validateMeta(meta: unknown): asserts meta is WorkflowMeta {
+  if (!meta || typeof meta !== "object") throw new Error("meta must be an object");
+  const value = meta as WorkflowMeta;
+  if (typeof value.name !== "string" || !value.name.trim() || value.name.length > 512)
+    throw new Error("meta.name must be a non-empty string of at most 512 characters");
+  if (typeof value.description !== "string" || !value.description.trim() || value.description.length > 100_000)
+    throw new Error("meta.description must be a non-empty string of at most 100000 characters");
+  if (value.model !== undefined && typeof value.model !== "string") throw new Error("meta.model must be a string");
+  if (value.phases !== undefined) {
+    if (!Array.isArray(value.phases)) throw new Error("meta.phases must be an array");
+    for (const phase of value.phases) {
+      if (
+        !phase ||
+        typeof phase !== "object" ||
+        typeof phase.title !== "string" ||
+        !phase.title.trim() ||
+        phase.title.length > 512
+      ) {
+        throw new Error("each meta phase must have a title string");
+      }
+      if ((phase as WorkflowMetaPhase).model !== undefined && typeof (phase as WorkflowMetaPhase).model !== "string") {
+        throw new Error("each meta phase model must be a string when present");
+      }
+    }
+  }
+}
+
+// ── Concurrency limiter ──────────────────────────────────────────────────────
+
+function createLimiter(limit: number): Limiter {
+  let active = 0;
+  const queue: Array<() => void> = [];
+  const next = () => {
+    active--;
+    queue.shift()?.();
+  };
+  return async <T>(fn: () => Promise<T>): Promise<T> => {
+    if (active >= limit) await new Promise<void>((resolve) => queue.push(resolve));
+    active++;
+    try {
+      return await fn();
+    } finally {
+      next();
+    }
+  };
+}
+
+// ── Hashing ──────────────────────────────────────────────────────────────────
+
+function hashIdentity(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+/**
+ * Stable identity hash for an agent() call. Must cover every input that can
+ * change the outcome so a cache-miss is never served on resume. The agent
+ * definition is represented by the agentType name (the definition itself lives
+ * in pi-subagents; a name-only key is the honest observable).
+ */
+function hashAgentCall(
+  prompt: string,
+  model: string | undefined,
+  phase: string | undefined,
+  options: AgentOptions,
+  agentDefKey: string | null,
+): string {
+  return hashIdentity({
+    prompt,
+    model: model ?? null,
+    tier: options.tier ?? null,
+    phase: phase ?? null,
+    agentType: options.agentType ?? null,
+    thread: options.thread ?? null,
+    agentDef: agentDefKey,
+    schema: options.schema ?? null,
+    isolation: options.isolation ?? null,
+    toolset: options.toolset ?? null,
+    excludeTools: options.excludeTools ?? null,
+  });
+}
+
+/**
+ * Stable identity hash for a checkpoint() call. Must cover every
+ * CheckpointOptions field that participates in the outcome, not just
+ * promptText/kind/choices: `default`/`headless` decide the reply in the
+ * headless path, and `timeoutMs` bounds the interactive prompt.
+ */
+function hashCheckpoint(promptText: string, options: CheckpointOptions): string {
+  return hashIdentity({
+    promptText,
+    kind: options.kind ?? "confirm",
+    choices: options.choices ?? null,
+    default: options.default ?? null,
+    headless: options.headless ?? "default",
+    timeoutMs: options.timeoutMs ?? null,
+  });
+}
+
+// ── Small helpers ────────────────────────────────────────────────────────────
+
+function defaultAgentLabel(phase: string | undefined, index: number): string {
+  return phase ? `${phase} agent ${index}` : `agent ${index}`;
+}
+
+function buildAgentInstructions(
+  phase: string | undefined,
+  options: AgentOptions,
+  resolvedIsolation?: "worktree",
+): string | undefined {
+  const lines: string[] = [];
+  if (options.agentType) lines.push(`Act as workflow subagent type: ${options.agentType}`);
+  if (phase) lines.push(`Workflow phase: ${phase}`);
+  // Per-call isolation is not routable through spawn-managed (see README,
+  // "worktree isolation"); the annotation is best-effort and the actual
+  // isolation comes from the agent definition pi-subagents resolves.
+  if (resolvedIsolation) lines.push(`Requested isolation: ${resolvedIsolation}`);
+  return lines.length ? lines.join("\n\n") : undefined;
+}
+
+function isEmptyTextAgentResult(result: unknown, schema: unknown): boolean {
+  return schema === undefined && typeof result === "string" && result.trim().length === 0;
+}
+
+function estimateTokens(value: unknown): number {
+  return Math.ceil(JSON.stringify(value ?? "").length / 4);
+}
+
+function normalizeConcurrency(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return 1;
+  return Math.min(MAX_CONCURRENCY, Math.floor(value));
+}
+
+function normalizeMaxAgents(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return MAX_AGENTS_PER_RUN;
+  return Math.min(MAX_AGENTS_PER_RUN, Math.floor(value));
+}
+
+function normalizeAgentTimeout(value: unknown): number | null {
+  if (value === null) return null;
+  if (value === undefined) return DEFAULT_AGENT_TIMEOUT_MS;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return DEFAULT_AGENT_TIMEOUT_MS;
+  return Math.floor(value);
+}
+
+function normalizeTokenBudget(value: unknown): number | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return null;
+  return Math.floor(value);
+}
+
+function normalizeAgentRetries(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return 0;
+  return Math.min(MAX_AGENT_RETRIES, Math.floor(value));
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number | null,
+  label: string,
+  onTimeout?: () => void,
+): Promise<T> {
+  if (ms === null) return promise;
+
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      try {
+        onTimeout?.();
+      } catch {
+        // Best-effort cleanup; never mask the timeout error.
+      }
+      reject(
+        new WorkflowError(
+          `Agent "${label}" timed out after ${ms}ms; raise or omit timeoutMs/agentTimeoutMs to allow longer runs`,
+          WorkflowErrorCode.AGENT_TIMEOUT,
+          { recoverable: true },
+        ),
+      );
+    }, ms);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}
+
+/** Extract the first balanced JSON value ({...} or [...]) from text. */
+export function findJsonBlock(text: string): string | undefined {
+  for (let start = 0; start < text.length; start += 1) {
+    if (text[start] !== "{" && text[start] !== "[") continue;
+    const stack: string[] = [];
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i += 1) {
+      const char = text[i];
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (char === "\\") escaped = true;
+        else if (char === '"') inString = false;
+        continue;
+      }
+      if (char === '"') {
+        inString = true;
+        continue;
+      }
+      if (char === "{" || char === "[") stack.push(char === "{" ? "}" : "]");
+      else if (char === "}" || char === "]") {
+        if (stack.pop() !== char) break;
+        if (stack.length === 0) return text.slice(start, i + 1);
+      }
+    }
+  }
+  return undefined;
+}
+
+// ── Minimal plain-JSON-Schema validator ──────────────────────────────────────
+// The `schema` agent option is a plain JSON Schema. The runtime validates the
+// agent's JSON reply against the bounded subset scripts actually use:
+// type/properties/required/items/enum/min/max/minLength/maxLength/const. A
+// schema outside the subset is rejected at call time rather than mis-validated.
+
+type SchemaNode = { [key: string]: unknown };
+
+function validateValue(value: unknown, schema: SchemaNode, path: string): string[] {
+  const errors: string[] = [];
+  if (schema.const !== undefined) {
+    if (JSON.stringify(value) !== JSON.stringify(schema.const))
+      errors.push(`${path}: expected const ${JSON.stringify(schema.const)}`);
+    return errors;
+  }
+  if (schema.enum !== undefined) {
+    if (!(schema.enum as unknown[]).some((e) => JSON.stringify(e) === JSON.stringify(value))) {
+      errors.push(`${path}: value not in enum`);
+    }
+    return errors;
+  }
+  const type = schema.type;
+  if (type !== undefined) {
+    const types = Array.isArray(type) ? type : [type];
+    const typeOf = (v: unknown): string => (v === null ? "null" : Array.isArray(v) ? "array" : typeof v);
+    if (!types.includes(typeOf(value))) {
+      errors.push(`${path}: expected type ${types.join("/")}, got ${typeOf(value)}`);
+      return errors;
+    }
+  }
+  if (type === "object" || (typeof value === "object" && value !== null && !Array.isArray(value))) {
+    const obj = value as Record<string, unknown>;
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required as string[]) {
+        if (!(key in obj)) errors.push(`${path}: missing required property "${key}"`);
+      }
+    }
+    const props = (schema.properties ?? {}) as Record<string, unknown>;
+    for (const [key, propSchema] of Object.entries(props)) {
+      if (!(key in obj)) continue;
+      errors.push(...validateValue(obj[key], propSchema as SchemaNode, `${path}.${key}`));
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(obj)) {
+        if (!Object.hasOwn(props, key)) errors.push(`${path}: unexpected property "${key}"`);
+      }
+    }
+  } else if (type === "array" || Array.isArray(value)) {
+    const arr = value as unknown[];
+    if (typeof schema.minItems === "number" && arr.length < schema.minItems) {
+      errors.push(`${path}: fewer than ${schema.minItems} items`);
+    }
+    if (typeof schema.maxItems === "number" && arr.length > schema.maxItems) {
+      errors.push(`${path}: more than ${schema.maxItems} items`);
+    }
+    const items = schema.items as SchemaNode | undefined;
+    if (items) {
+      for (let i = 0; i < arr.length; i++) {
+        errors.push(...validateValue(arr[i], items, `${path}[${i}]`));
+      }
+    }
+  } else if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength)
+      errors.push(`${path}: shorter than ${schema.minLength}`);
+    if (typeof schema.maxLength === "number" && value.length > schema.maxLength)
+      errors.push(`${path}: longer than ${schema.maxLength}`);
+  } else if (typeof value === "number") {
+    if (typeof schema.minimum === "number" && value < schema.minimum)
+      errors.push(`${path}: below minimum ${schema.minimum}`);
+    if (typeof schema.maximum === "number" && value > schema.maximum)
+      errors.push(`${path}: above maximum ${schema.maximum}`);
+  }
+  return errors;
+}
+
+/** Validate a value against a plain JSON Schema; returns the error list. */
+export function validateJsonSchema(value: unknown, schema: unknown): string[] {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new WorkflowError(
+      "agent({ schema }) must be a plain JSON Schema object",
+      WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+      { recoverable: false },
+    );
+  }
+  validateSchemaShape(schema, "$schema");
+  const allowed = new Set([
+    "type",
+    "properties",
+    "required",
+    "items",
+    "enum",
+    "const",
+    "minItems",
+    "maxItems",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "description",
+    "title",
+    "additionalProperties",
+  ]);
+  for (const key of Object.keys(schema)) {
+    if (!allowed.has(key)) {
+      throw new WorkflowError(
+        `agent({ schema }) uses unsupported JSON Schema keyword "${key}"`,
+        WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+        { recoverable: false },
+      );
+    }
+  }
+  return validateValue(value, schema as SchemaNode, "$");
+}
+
+function validateSchemaShape(schema: unknown, path: string, seen = new WeakSet<object>()): void {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema))
+    throw new WorkflowError(`invalid JSON Schema at ${path}`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+      recoverable: false,
+    });
+  if (seen.has(schema))
+    throw new WorkflowError(`cyclic JSON Schema at ${path}`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+      recoverable: false,
+    });
+  seen.add(schema);
+  const node = schema as SchemaNode;
+  const allowed = new Set([
+    "type",
+    "properties",
+    "required",
+    "items",
+    "enum",
+    "const",
+    "minItems",
+    "maxItems",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "description",
+    "title",
+    "additionalProperties",
+  ]);
+  for (const key of Object.keys(node))
+    if (!allowed.has(key))
+      throw new WorkflowError(
+        `agent({ schema }) uses unsupported JSON Schema keyword "${key}" at ${path}`,
+        WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+        { recoverable: false },
+      );
+  if (node.additionalProperties !== undefined && typeof node.additionalProperties !== "boolean")
+    throw new WorkflowError(
+      `additionalProperties must be boolean at ${path}`,
+      WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+      { recoverable: false },
+    );
+  if (
+    node.required !== undefined &&
+    (!Array.isArray(node.required) || !node.required.every((key) => typeof key === "string"))
+  )
+    throw new WorkflowError(
+      `required must be an array of strings at ${path}`,
+      WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+      { recoverable: false },
+    );
+  if (node.properties !== undefined) {
+    if (!node.properties || typeof node.properties !== "object" || Array.isArray(node.properties))
+      throw new WorkflowError(`properties must be an object at ${path}`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+        recoverable: false,
+      });
+    for (const [key, child] of Object.entries(node.properties as Record<string, unknown>))
+      validateSchemaShape(child, `${path}.${key}`, seen);
+  }
+  if (node.items !== undefined) validateSchemaShape(node.items, `${path}[]`, seen);
+  seen.delete(schema);
+}
+
+// ── Runtime globals shape ────────────────────────────────────────────────────
+
+export interface WorkflowRuntimeBindings {
+  agent: (prompt: string, options?: AgentOptions) => Promise<unknown>;
+  parallel: (thunks: Array<() => Promise<unknown>>) => Promise<Array<unknown | null>>;
+  pipeline: (
+    items: unknown[],
+    ...stages: Array<(prev: unknown, original: unknown, index: number) => unknown>
+  ) => Promise<Array<unknown | null>>;
+  workflow: (savedName: string, childArgs?: unknown) => Promise<unknown>;
+  verify: (
+    item: unknown,
+    options?: { reviewers?: number; threshold?: number; lens?: string | string[] },
+  ) => Promise<{ real: boolean; realCount: number; total: number; votes: Array<{ real: boolean; reason?: string }> }>;
+  judgePanel: (
+    attempts: unknown[],
+    options?: { judges?: number; rubric?: string },
+  ) => Promise<
+    { index: number; attempt: unknown; score: number; judgments: Array<{ score: number; reason?: string }> } | undefined
+  >;
+  loopUntilDry: (options: {
+    round: (roundIndex: number) => unknown[] | Promise<unknown[]>;
+    key?: (item: unknown) => string;
+    consecutiveEmpty?: number;
+    maxRounds?: number;
+  }) => Promise<unknown[]>;
+  completenessCheck: (taskArgs: unknown, results: unknown) => Promise<{ complete: boolean; missing?: string[] } | null>;
+  retry: (
+    thunk: (attempt: number) => unknown | Promise<unknown>,
+    options?: { attempts?: number; until?: (result: unknown) => boolean },
+  ) => Promise<unknown>;
+  gate: (
+    thunk: (feedback: string | undefined, attempt: number) => unknown | Promise<unknown>,
+    validator: (value: unknown) => { ok: boolean; feedback?: string } | Promise<{ ok: boolean; feedback?: string }>,
+    options?: { attempts?: number },
+  ) => Promise<{ ok: boolean; value: unknown; attempts: number }>;
+  checkpoint: (prompt: string, options?: CheckpointOptions) => Promise<unknown>;
+  log: (message: unknown) => void;
+  phase: (title: string, options?: { budget?: number }) => void;
+  args: unknown;
+  cwd: string;
+  process: { cwd(): string };
+  budget: { total: number | null; spent(): number; remaining(): number };
+}
+
+/** Fan-out cancellation scope: parallel()/pipeline() batches mark themselves. */
+const fanoutScope = new AsyncLocalStorage<{ cancelled: boolean }>();
+
+// ── The run ──────────────────────────────────────────────────────────────────
+
+export async function runWorkflow<T = unknown>(
+  script: string,
+  options: WorkflowRunOptions = {},
+): Promise<WorkflowRunResult<T>> {
+  const started = Date.now();
+  const { meta, body } = parseWorkflowScript(script);
+  const maxAgents = normalizeMaxAgents(options.maxAgents ?? MAX_AGENTS_PER_RUN);
+  const agentTimeoutMs = normalizeAgentTimeout(options.agentTimeoutMs);
+  const runId = options.runId ?? `run-${started.toString(36)}`;
+  const baseCwd = options.cwd ?? process.cwd();
+
+  const state: RuntimeState = {
+    logs: [],
+    // When the script declares meta.phases, default the current phase to the
+    // first one so agents created before any explicit phase() call still group
+    // under a declared phase instead of an orphan bucket.
+    phases: meta.phases?.[0]?.title ? [meta.phases[0].title] : [],
+    currentPhase: meta.phases?.[0]?.title,
+    phaseBudgets: new Map(),
+    callSeq: 0,
+    firstMiss: Number.POSITIVE_INFINITY,
+  };
+
+  const agentRunner = options.agent;
+  const concurrency = normalizeConcurrency(
+    options.concurrency ??
+      Math.max(
+        1,
+        (globalThis as { navigator?: { hardwareConcurrency?: number } }).navigator?.hardwareConcurrency ?? 8,
+      ) - 2,
+  );
+
+  // Global caps + budget shared with any nested workflow() so they hold across nesting.
+  const shared: SharedRuntime = options.sharedRuntime ?? {
+    limiter: createLimiter(concurrency),
+    agentCount: 0,
+    spent: options.initialTokenUsage?.total ?? 0,
+    tokenUsage: options.initialTokenUsage
+      ? { ...options.initialTokenUsage }
+      : { input: 0, output: 0, total: 0, cost: 0, cacheRead: 0, cacheWrite: 0 },
+    depth: 0,
+    nestedCallSeq: 0,
+    runFatalController: new AbortController(),
+    inFlight: new Set<Promise<unknown>>(),
+    activeThreads: new Set<string>(),
+  };
+  const limiter = shared.limiter;
+  const isTopLevelRun = !options.sharedRuntime;
+  const store: SharedStore = options.sharedStore ?? new SharedStore();
+
+  const log = (message: unknown) => {
+    const text = String(message);
+    state.logs.push(text);
+    options.onLog?.(text);
+  };
+
+  const phase = (title: string, phaseOptions?: { budget?: number }) => {
+    state.currentPhase = title;
+    if (!state.phases.includes(title)) state.phases.push(title);
+    // Soft sub-budget carved from the run total; re-declaring re-bases from the
+    // current spent (idempotent across resume).
+    if (typeof phaseOptions?.budget === "number" && phaseOptions.budget > 0) {
+      state.phaseBudgets.set(title, { budget: phaseOptions.budget, startSpent: shared.spent, warned: false });
+    }
+    options.onPhase?.(title);
+    options.onRuntimeEvent?.({
+      type: "phase",
+      title,
+      budget: typeof phaseOptions?.budget === "number" && phaseOptions.budget > 0 ? phaseOptions.budget : null,
+    });
+  };
+
+  const budget = Object.freeze({
+    total: normalizeTokenBudget(options.tokenBudget),
+    spent: () => shared.spent,
+    remaining: () => (budget.total == null ? Infinity : Math.max(0, budget.total - shared.spent)),
+  });
+
+  const agentLimitError = () =>
+    new WorkflowError(
+      `Agent limit exceeded (${shared.agentCount}/${maxAgents}). Re-call workflow with resumeFromRunId="${runId}", the same script, and maxAgents: N (N>${maxAgents}) — journaled prefix replays free. /workflows resume alone cannot raise the cap.`,
+      WorkflowErrorCode.AGENT_LIMIT_EXCEEDED,
+      { recoverable: false },
+    );
+
+  const isAborted = () => Boolean(options.signal?.aborted || shared.runFatalController.signal.aborted);
+
+  const throwIfAborted = () => {
+    if (isAborted()) {
+      throw new WorkflowError("workflow aborted", WorkflowErrorCode.WORKFLOW_ABORTED, { recoverable: true });
+    }
+  };
+
+  const agent = (promptText: string, agentOptions: AgentOptions = {}): Promise<unknown> => {
+    const rawThread = agentOptions.thread;
+    const thread = rawThread === undefined ? undefined : typeof rawThread === "string" ? rawThread.trim() : "";
+    if (rawThread !== undefined && !thread) {
+      throw new WorkflowError("agent() thread must be a non-empty string", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+        recoverable: false,
+      });
+    }
+    if (thread && agentOptions.isolation === "worktree") {
+      throw new WorkflowError(
+        `agent thread "${thread}" cannot use worktree isolation because worktrees are removed after each call`,
+        WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+        { recoverable: false },
+      );
+    }
+    if (thread && shared.activeThreads.has(thread)) {
+      throw new WorkflowError(
+        `agent thread "${thread}" is already running; same-thread calls must be sequential`,
+        WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+        { recoverable: false },
+      );
+    }
+    if (thread) shared.activeThreads.add(thread);
+    const normalizedOptions = thread && thread !== rawThread ? { ...agentOptions, thread } : agentOptions;
+    let call = agentImpl(promptText, normalizedOptions);
+    if (thread) call = call.finally(() => shared.activeThreads.delete(thread));
+    // Track every call (awaited or not) so the top-level run can drain
+    // outstanding calls before completing — a forgotten `await` cannot let an
+    // agent mutate state after the run is torn down.
+    shared.inFlight.add(call);
+    call.catch(() => {}).finally(() => shared.inFlight.delete(call));
+    return call;
+  };
+
+  const agentImpl = async (promptText: string, agentOptions: AgentOptions = {}) => {
+    throwIfAborted();
+
+    // Capture the enclosing parallel()/pipeline() fan-out's cancellation batch
+    // synchronously, before suspending on the limiter below.
+    const batch = fanoutScope.getStore();
+
+    // Check agent limit. A fan-out that overshoots the cap has already reserved
+    // and queued up to `maxAgents` agents; the breaching call throws here, and
+    // parallel()/pipeline() mark their own batch cancelled so the already-queued
+    // agents short-circuit before their real API call (see the limiter body).
+    if (shared.agentCount >= maxAgents) {
+      throw agentLimitError();
+    }
+
+    if (budget.total !== null && budget.remaining() <= 0) {
+      throw new WorkflowError("workflow token budget exhausted", WorkflowErrorCode.TOKEN_BUDGET_EXHAUSTED, {
+        recoverable: false,
+      });
+    }
+
+    const assignedPhase = agentOptions.phase ?? state.currentPhase;
+
+    // Per-phase soft sub-budget gate: warns once at ~80%, throws at 100%.
+    if (assignedPhase) {
+      const pb = state.phaseBudgets.get(assignedPhase);
+      if (pb) {
+        const phaseSpent = shared.spent - pb.startSpent;
+        if (phaseSpent >= pb.budget) {
+          throw new WorkflowError(
+            `phase "${assignedPhase}" token sub-budget exhausted (${pb.budget})`,
+            WorkflowErrorCode.TOKEN_BUDGET_EXHAUSTED,
+            { recoverable: false },
+          );
+        }
+        if (!pb.warned && phaseSpent >= pb.budget * 0.8) {
+          pb.warned = true;
+          log(`phase "${assignedPhase}" at ${Math.round((phaseSpent / pb.budget) * 100)}% of its token sub-budget`);
+        }
+      }
+    }
+
+    const requestedLabel = agentOptions.label?.trim();
+    // agentType resolution lives in pi-subagents; the name is the observable key.
+    if (agentOptions.agentType) {
+      log(`agentType "${agentOptions.agentType}" resolves in pi-subagents at dispatch`);
+    }
+
+    // Model precedence: explicit per-call model > phase/run model. A tier is
+    // deliberately left to pi-subagents so its configured profile wins over the
+    // phase default. The model string may carry a `:thinking` suffix understood by
+    // the managed protocol.
+    const phaseModel = meta.phases?.find((candidate) => candidate.title === assignedPhase)?.model ?? meta.model;
+    const modelSpec = agentOptions.model ?? (agentOptions.tier === undefined ? phaseModel : undefined);
+
+    // Deterministic resume key: assigned at lexical call time, before the limiter.
+    const callIndex = state.callSeq++;
+    const callHash = hashAgentCall(promptText, modelSpec, assignedPhase, agentOptions, agentOptions.agentType ?? null);
+    // Store delta key: runId-namespaced so a nested workflow() call's
+    // callIndex-0 can never collide with the parent's (see SharedStore doc).
+    const deltaKey = `${runId}:${callIndex}`;
+
+    // Reserve the agent slot synchronously — atomic with the limit/budget gate
+    // above (no await in between) so a parallel() fan-out cannot all observe the
+    // same agentCount and overshoot maxAgents.
+    shared.agentCount++;
+    const label = requestedLabel || defaultAgentLabel(assignedPhase, shared.agentCount);
+
+    // Longest-unchanged-prefix resume: replay a cached result only while the
+    // prefix is still intact. Once any call misses, it AND everything after it
+    // run live, so an edited upstream call never leaves stale downstream
+    // results served from the journal.
+    const cached = agentOptions.thread ? undefined : options.resumeJournal?.get(deltaKey);
+    const hashMatches = cached != null && cached.hash === callHash;
+    const cachedEmptyOutput = hashMatches && isEmptyTextAgentResult(cached.result, agentOptions.schema);
+    if (hashMatches && !cachedEmptyOutput && callIndex < state.firstMiss) {
+      options.onAgentStart?.({ id: deltaKey, label, phase: assignedPhase, prompt: promptText });
+      options.onAgentEnd?.({
+        id: deltaKey,
+        label,
+        phase: assignedPhase,
+        result: cached.result,
+        tokens: 0,
+      });
+      if (cached.storeDelta) store.applyDelta(cached.storeDelta);
+      return cached.result;
+    }
+    if (!hashMatches || cachedEmptyOutput || agentOptions.thread)
+      state.firstMiss = Math.min(state.firstMiss, callIndex);
+
+    return limiter(async () => {
+      const timeout = agentOptions.timeoutMs !== undefined ? agentOptions.timeoutMs : agentTimeoutMs;
+      const retryAttempts = normalizeAgentRetries(agentOptions.retries ?? options.agentRetries ?? 0);
+      const maxAttempts = retryAttempts + 1;
+
+      options.onAgentStart?.({ id: deltaKey, label, phase: assignedPhase, prompt: promptText });
+
+      // Worktree creation and cleanup remain owned by pi-subagents; the request
+      // carries the explicit per-call policy without touching the host filesystem here.
+      const resolvedIsolation = agentOptions.isolation;
+
+      // Captured from the subagent's real session usage; falls back to an
+      // estimate when the provider reports none. Reset per retry attempt so a
+      // failed attempt does not double-count the next one.
+      let usage: AgentUsage | undefined;
+      const recordTokens = (result: unknown): number => {
+        const tokens = usage && usage.total > 0 ? usage.total : estimateTokens(result) + estimateTokens(promptText);
+        if (usage) {
+          shared.tokenUsage.input += usage.input;
+          shared.tokenUsage.output += usage.output;
+          shared.tokenUsage.cost += usage.cost;
+          shared.tokenUsage.cacheRead += usage.cacheRead;
+          shared.tokenUsage.cacheWrite += usage.cacheWrite;
+        }
+        shared.tokenUsage.total += tokens;
+        shared.spent += tokens;
+        return tokens;
+      };
+
+      // Schema agents: the runner's text reply is parsed as JSON and validated.
+      // Bounded repair: an invalid reply is fed back into the next attempt as
+      // retry feedback; exhaustion throws SCHEMA_NONCOMPLIANCE (non-recoverable).
+      const schema = agentOptions.schema;
+      const schemaInstruction =
+        schema !== undefined
+          ? `\n\nReply with a single raw JSON value (object or array) matching exactly this JSON Schema:\n${JSON.stringify(schema)}\nDo not wrap it in prose or markdown fences.`
+          : "";
+
+      try {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+          usage = undefined;
+          const externalSignal = options.signal;
+          let onExternalAbort: (() => void) | undefined;
+          let onRunFatal: (() => void) | undefined;
+          try {
+            throwIfAborted();
+            if (batch?.cancelled) throw agentLimitError();
+
+            const agentController = new AbortController();
+            if (isAborted()) {
+              agentController.abort();
+            } else {
+              if (externalSignal) {
+                onExternalAbort = () => agentController.abort();
+                externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+              }
+              onRunFatal = () => agentController.abort();
+              shared.runFatalController.signal.addEventListener("abort", onRunFatal, { once: true });
+            }
+
+            if (!agentRunner) {
+              throw new WorkflowError(
+                "workflow dispatch is unavailable: no agent runner is wired to this run",
+                WorkflowErrorCode.AGENT_EXECUTION_ERROR,
+                { recoverable: false },
+              );
+            }
+
+            const runPromise = agentRunner.run(promptText + schemaInstruction, {
+              label,
+              sessionName: agentOptions.thread
+                ? `workflow:${runId} thread:${agentOptions.thread}`
+                : `workflow:${runId} ${label}`,
+              schema,
+              signal: agentController.signal,
+              instructions: buildAgentInstructions(assignedPhase, agentOptions, resolvedIsolation),
+              model: modelSpec,
+              tier: agentOptions.tier,
+              agentType: agentOptions.agentType,
+              isolation: resolvedIsolation,
+              toolset: options.toolset ?? agentOptions.toolset,
+              excludeTools: options.excludeTools ?? agentOptions.excludeTools,
+              callIndex,
+              callHash,
+              attempt,
+              thread: agentOptions.thread,
+              onModelResolved: (id: string) => {
+                void id; // display model tracking is engine-side
+              },
+              onUsage: (u: AgentUsage) => {
+                usage = u;
+              },
+              onHistory: (history: unknown[]) => {
+                options.onAgentHistory?.({ id: deltaKey, label, phase: assignedPhase, history });
+              },
+            });
+            runPromise.catch(() => {});
+            let result = await withTimeout(runPromise, timeout, label, () => agentController.abort());
+
+            throwIfAborted();
+            if (isEmptyTextAgentResult(result, schema)) {
+              throw new WorkflowError("Subagent produced no assistant output", WorkflowErrorCode.AGENT_EMPTY_OUTPUT, {
+                recoverable: true,
+                agentLabel: label,
+              });
+            }
+
+            // Client-side schema validation with bounded repair across attempts.
+            if (schema !== undefined) {
+              const text = typeof result === "string" ? result : JSON.stringify(result);
+              const json = findJsonBlock(text);
+              let parsed: unknown;
+              if (json === undefined) {
+                parsed = undefined;
+              } else {
+                try {
+                  parsed = JSON.parse(json);
+                } catch {
+                  parsed = undefined;
+                }
+              }
+              const errors =
+                parsed === undefined ? ["no JSON value found in the reply"] : validateJsonSchema(parsed, schema);
+              if (errors.length > 0) {
+                const detail = errors.join("; ");
+                if (attempt < maxAttempts) {
+                  // Repair: re-dispatch with the validation errors as feedback.
+                  throw new WorkflowError(
+                    `Subagent reply did not match the schema: ${detail}`,
+                    WorkflowErrorCode.AGENT_EXECUTION_ERROR,
+                    { recoverable: true, agentLabel: label },
+                  );
+                }
+                throw new WorkflowError(
+                  `Subagent did not produce a schema-valid result after ${maxAttempts} attempt(s): ${detail}`,
+                  WorkflowErrorCode.SCHEMA_NONCOMPLIANCE,
+                  { recoverable: false, agentLabel: label },
+                );
+              }
+              result = parsed;
+            }
+
+            const tokens = recordTokens(result);
+            options.onAgentJournal?.({
+              index: callIndex,
+              runId,
+              hash: callHash,
+              result,
+              storeDelta: store.commitDelta(deltaKey),
+            });
+            options.onAgentEnd?.({
+              id: deltaKey,
+              label,
+              phase: assignedPhase,
+              result,
+              tokens,
+              tokenUsage: usage,
+              model: modelSpec,
+            });
+            return result;
+          } catch (error) {
+            if (isAborted()) throw error;
+
+            const workflowError = wrapError(error, { agentLabel: label });
+            const tokens = recordTokens(null);
+            // This attempt's store writes must not survive it — a failed attempt
+            // shares this call's deltaKey with every other attempt, so without
+            // rolling back here its writes would stay live in the store and merge
+            // into whatever a later, successful attempt commits.
+            store.discardDelta(deltaKey);
+            if (workflowError.code === WorkflowErrorCode.PROVIDER_USAGE_LIMIT) throw workflowError;
+
+            if (workflowError.recoverable && attempt < maxAttempts) {
+              log(
+                `agent "${label}" attempt ${attempt}/${maxAttempts} failed: ${workflowError.code} ${workflowError.message}; retrying`,
+              );
+              options.onRetrySpend?.(tokens);
+              continue;
+            }
+
+            options.onAgentEnd?.({
+              id: deltaKey,
+              label,
+              phase: assignedPhase,
+              result: null,
+              tokens,
+              tokenUsage: usage,
+              model: modelSpec,
+              error: workflowError.message,
+              errorCode: workflowError.code,
+              recoverable: workflowError.recoverable,
+            });
+
+            if (workflowError.recoverable) {
+              log(
+                `agent "${label}" exhausted ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"}: ${workflowError.code} ${workflowError.message}`,
+              );
+              return null;
+            }
+            throw workflowError;
+          } finally {
+            if (onExternalAbort) externalSignal?.removeEventListener("abort", onExternalAbort);
+            if (onRunFatal) shared.runFatalController.signal.removeEventListener("abort", onRunFatal);
+          }
+        }
+        return null;
+      } finally {
+        // No per-call worktree to tear down under spawn-managed.
+      }
+    });
+  };
+
+  const parallel = async (thunks: Array<() => Promise<unknown>>) => {
+    throwIfAborted();
+    if (!Array.isArray(thunks)) throw new TypeError("parallel() expects an array of functions");
+    if (thunks.some((thunk) => typeof thunk !== "function")) {
+      throw new TypeError("parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)");
+    }
+    // Batch-scoped cancellation: a breach in THIS fan-out flips `cancelled` so
+    // its own still-queued agents bail, without touching a sibling or enclosing
+    // fan-out.
+    const batch = { cancelled: false };
+    return fanoutScope.run(batch, () =>
+      Promise.all(
+        thunks.map(async (thunk, index) => {
+          try {
+            return await thunk();
+          } catch (error) {
+            if (isAborted()) throw error;
+            const workflowError = wrapError(error);
+            if (!workflowError.recoverable || workflowError.code === WorkflowErrorCode.PROVIDER_USAGE_LIMIT) {
+              if (workflowError.code === WorkflowErrorCode.AGENT_LIMIT_EXCEEDED) batch.cancelled = true;
+              throw workflowError;
+            }
+            log(`parallel[${index}] failed: ${workflowError.message}`);
+            return null;
+          }
+        }),
+      ),
+    );
+  };
+
+  const pipeline = async (
+    items: unknown[],
+    ...stages: Array<(prev: unknown, original: unknown, index: number) => unknown>
+  ) => {
+    throwIfAborted();
+    if (!Array.isArray(items)) throw new TypeError("pipeline() expects an array as the first argument");
+    if (stages.some((stage) => typeof stage !== "function")) {
+      throw new TypeError("pipeline() stages must be functions: pipeline(items, item => ..., result => ...)");
+    }
+    const batch = { cancelled: false };
+    return fanoutScope.run(batch, () =>
+      Promise.all(
+        items.map(async (item, index) => {
+          let value: unknown = item;
+          for (const stage of stages) {
+            try {
+              throwIfAborted();
+              value = await stage(value, item, index);
+              throwIfAborted();
+            } catch (error) {
+              if (isAborted()) throw error;
+              const workflowError = wrapError(error);
+              if (!workflowError.recoverable || workflowError.code === WorkflowErrorCode.PROVIDER_USAGE_LIMIT) {
+                if (workflowError.code === WorkflowErrorCode.AGENT_LIMIT_EXCEEDED) batch.cancelled = true;
+                throw workflowError;
+              }
+              log(`pipeline[${index}] failed: ${workflowError.message}`);
+              return null;
+            }
+          }
+          return value;
+        }),
+      ),
+    );
+  };
+
+  // Nested workflow(): run a saved workflow (or raw script) inline, sharing this
+  // run's limiter/counters/budget. One level deep only.
+  const workflowFn = async (nameOrScript: string, childArgs?: unknown) => {
+    throwIfAborted();
+    if (shared.depth >= 1) {
+      throw new WorkflowError("workflow() can nest only one level deep", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+        recoverable: false,
+      });
+    }
+    const resolved = options.loadSavedWorkflow?.(String(nameOrScript));
+    const childScript = resolved ?? String(nameOrScript);
+    const workflowName = String(nameOrScript);
+    options.onRuntimeEvent?.({ type: "workflow", stage: "start", name: workflowName, args: childArgs });
+    shared.depth++;
+    try {
+      // Propagate the resume journal into the child frame ONLY while the
+      // parent's own prefix is still intact (state.firstMiss === Infinity).
+      // SharedStore content is not part of any call's hash, so a cached child
+      // result computed against OLD store state would be stale once an upstream
+      // parent call misses and re-runs live with different store writes.
+      const prefixIntact = state.firstMiss === Number.POSITIVE_INFINITY;
+      const child = await runWorkflow(childScript, {
+        ...options,
+        args: childArgs,
+        sharedRuntime: shared,
+        sharedStore: store,
+        resumeJournal: prefixIntact ? options.resumeJournal : undefined,
+        resumeFromRunId: undefined,
+        // shared.nestedCallSeq, not depth: depth returns to 0 between sequential
+        // sibling calls, which would otherwise mint colliding child runIds.
+        runId: `${runId}-nested${++shared.nestedCallSeq}`,
+      });
+      return child.result;
+    } finally {
+      shared.depth--;
+      options.onRuntimeEvent?.({ type: "workflow", stage: "end", name: workflowName, args: childArgs });
+    }
+  };
+
+  // ── Quality-pattern stdlib ──────────────────────────────────────────────────
+
+  const VERIFY_SCHEMA = {
+    type: "object",
+    properties: { real: { type: "boolean" }, reason: { type: "string" } },
+    required: ["real"],
+  };
+  const verify = async (
+    item: unknown,
+    opts: { reviewers?: number; threshold?: number; lens?: string | string[] } = {},
+  ): Promise<{
+    real: boolean;
+    realCount: number;
+    total: number;
+    votes: Array<{ real: boolean; reason?: string }>;
+  }> => {
+    options.onRuntimeEvent?.({ type: "quality", stage: "start", helper: "verify" });
+    const reviewers = Math.max(1, opts.reviewers ?? 2);
+    const threshold = opts.threshold ?? 0.5;
+    const lenses = opts.lens ? (Array.isArray(opts.lens) ? opts.lens : [opts.lens]) : [];
+    const claim = typeof item === "string" ? item : JSON.stringify(item);
+    const votes = (
+      await parallel(
+        Array.from(
+          { length: reviewers },
+          (_v, i) => () =>
+            agent(
+              `Adversarially review whether the following is REAL/correct. Try to refute it; default to real=false if unsure.${lenses.length ? ` Focus lens: ${lenses[i % lenses.length]}.` : ""}\n\n${claim}`,
+              { label: `verify ${i + 1}`, schema: VERIFY_SCHEMA },
+            ),
+        ),
+      )
+    ).filter(Boolean) as Array<{ real?: boolean; reason?: string }>;
+    const realCount = votes.filter((v) => v?.real).length;
+    return {
+      real: votes.length > 0 && realCount / votes.length >= threshold,
+      realCount,
+      total: votes.length,
+      votes: votes.map((v) => ({ real: Boolean(v?.real), reason: v?.reason })),
+    };
+  };
+
+  const JUDGE_SCHEMA = {
+    type: "object",
+    properties: { score: { type: "number" }, reason: { type: "string" } },
+    required: ["score"],
+  };
+  const judgePanel = async (
+    attempts: unknown[],
+    opts: { judges?: number; rubric?: string } = {},
+  ): Promise<
+    { index: number; attempt: unknown; score: number; judgments: Array<{ score: number; reason?: string }> } | undefined
+  > => {
+    options.onRuntimeEvent?.({ type: "quality", stage: "start", helper: "judgePanel" });
+    if (!Array.isArray(attempts) || attempts.length === 0) {
+      options.onRuntimeEvent?.({ type: "quality", stage: "end", helper: "judgePanel" });
+      return undefined;
+    }
+    const judges = Math.min(16, Math.max(1, Math.floor(opts.judges ?? 3)));
+    const rubric = opts.rubric ?? "overall quality and correctness";
+    const scored = (
+      await parallel(
+        (Array.isArray(attempts) ? attempts : []).map((att, idx) => async () => {
+          const text = typeof att === "string" ? att : JSON.stringify(att);
+          const js = (
+            await parallel(
+              Array.from(
+                { length: judges },
+                (_v, j) => () =>
+                  agent(
+                    `Score this candidate from 0 to 1 on: ${rubric}. Reply with the score.\n\nCandidate:\n${text}`,
+                    {
+                      label: `judge ${idx + 1}.${j + 1}`,
+                      schema: JUDGE_SCHEMA,
+                    },
+                  ),
+              ),
+            )
+          ).filter(Boolean) as Array<{ score?: number }>;
+          const score = js.length ? js.reduce((s, v) => s + (Number(v?.score) || 0), 0) / js.length : 0;
+          return { index: idx, attempt: att, score, judgments: js };
+        }),
+      )
+    ).filter(Boolean) as Array<{
+      index: number;
+      attempt: unknown;
+      score: number;
+      judgments: Array<{ score?: number; reason?: string }>;
+    }>;
+    const normalized = scored.map((s) => ({
+      index: s.index,
+      attempt: s.attempt,
+      score: s.score,
+      judgments: s.judgments.map((j) => ({ score: Number(j?.score) || 0, reason: j?.reason })),
+    }));
+    if (normalized.length === 0) {
+      options.onRuntimeEvent?.({ type: "quality", stage: "end", helper: "judgePanel" });
+      return undefined;
+    }
+    let best = normalized[0];
+    for (const s of normalized) if (s.score > best.score || (s.score === best.score && s.index < best.index)) best = s;
+    options.onRuntimeEvent?.({ type: "quality", stage: "end", helper: "judgePanel" });
+    return best;
+  };
+
+  const loopUntilDry = async (opts: {
+    round: (roundIndex: number) => Promise<unknown[]> | unknown[];
+    key?: (item: unknown) => string;
+    consecutiveEmpty?: number;
+    maxRounds?: number;
+  }) => {
+    if (!opts || typeof opts.round !== "function")
+      throw new TypeError("loopUntilDry requires { round: (i) => items[] }");
+    const key = opts.key ?? ((x: unknown) => JSON.stringify(x));
+    const consecutiveEmpty = Math.max(1, opts.consecutiveEmpty ?? 2);
+    const maxRounds = opts.maxRounds ?? 50;
+    const seen = new Set<string>();
+    const all: unknown[] = [];
+    let dry = 0;
+    for (let r = 0; r < maxRounds && dry < consecutiveEmpty; r++) {
+      throwIfAborted();
+      let items: unknown[];
+      try {
+        items = (await opts.round(r)) ?? [];
+      } catch (error) {
+        // Budget / agent-limit exhaustion: return the partial result, don't abort.
+        const code = (error as { code?: string })?.code;
+        if (code === WorkflowErrorCode.TOKEN_BUDGET_EXHAUSTED || code === WorkflowErrorCode.AGENT_LIMIT_EXCEEDED) break;
+        throw error;
+      }
+      const fresh = (Array.isArray(items) ? items : []).filter((x) => x != null && !seen.has(key(x)));
+      if (!fresh.length) {
+        dry++;
+        continue;
+      }
+      dry = 0;
+      for (const x of fresh) {
+        seen.add(key(x));
+        all.push(x);
+      }
+    }
+    return all;
+  };
+
+  const COMPLETENESS_SCHEMA = {
+    type: "object",
+    properties: { complete: { type: "boolean" }, missing: { type: "array", items: { type: "string" } } },
+    required: ["complete"],
+  };
+  const completenessCheck = async (
+    taskArgs: unknown,
+    results: unknown,
+  ): Promise<{ complete: boolean; missing?: string[] } | null> => {
+    options.onRuntimeEvent?.({ type: "quality", stage: "start", helper: "completenessCheck" });
+    const verdict = await agent(
+      `Given the task and the results gathered so far, list what is still MISSING (modalities not covered, claims unverified, gaps). Be specific and concise.\n\nTask:\n${JSON.stringify(taskArgs)}\n\nResults so far:\n${JSON.stringify(results).slice(0, 4000)}`,
+      { label: "completeness critic", schema: COMPLETENESS_SCHEMA },
+    );
+    options.onRuntimeEvent?.({ type: "quality", stage: "end", helper: "completenessCheck" });
+    return verdict as { complete: boolean; missing?: string[] } | null;
+  };
+
+  const retry = async (
+    thunk: (attempt: number) => Promise<unknown> | unknown,
+    opts: { attempts?: number; until?: (r: unknown) => boolean } = {},
+  ) => {
+    const attempts = Math.max(1, opts.attempts ?? 3);
+    let last: unknown;
+    for (let i = 0; i < attempts; i++) {
+      throwIfAborted();
+      last = await thunk(i);
+      const accepted = !opts.until || opts.until(last);
+      options.onRuntimeEvent?.({ type: "control-attempt", helper: "retry", attempt: i + 1, accepted });
+      if (accepted) return last;
+    }
+    return last;
+  };
+
+  const gate = async (
+    thunk: (feedback: string | undefined, attempt: number) => Promise<unknown> | unknown,
+    validator: (r: unknown) => Promise<{ ok: boolean; feedback?: string }> | { ok: boolean; feedback?: string },
+    opts: { attempts?: number } = {},
+  ) => {
+    const attempts = Math.max(1, opts.attempts ?? 3);
+    let feedback: string | undefined;
+    let last: unknown;
+    for (let i = 0; i < attempts; i++) {
+      throwIfAborted();
+      last = await thunk(feedback, i);
+      const verdict = await validator(last);
+      const accepted = Boolean(verdict?.ok);
+      options.onRuntimeEvent?.({ type: "control-attempt", helper: "gate", attempt: i + 1, accepted });
+      if (accepted) return { ok: true, value: last, attempts: i + 1 };
+      feedback = verdict?.feedback;
+    }
+    return { ok: false, value: last, attempts };
+  };
+
+  // Deterministic, journaled, replayable human checkpoint. Spends no tokens, so
+  // it is gated on the agent counter + abort (not budget). On resume the
+  // human's reply replays by callIndex exactly like a cached agent().
+  const checkpoint = async (promptText: string, checkpointOptions: CheckpointOptions = {}) => {
+    throwIfAborted();
+    if (typeof promptText !== "string") throw new TypeError("checkpoint(promptText, options?) needs a prompt string");
+    if (shared.agentCount >= maxAgents) {
+      throw agentLimitError();
+    }
+    const callIndex = state.callSeq++;
+    const callHash = hashCheckpoint(promptText, checkpointOptions);
+    const journalKey = `${runId}:${callIndex}`;
+    const cached = options.resumeJournal?.get(journalKey);
+    if (cached != null && cached.hash === callHash && callIndex < state.firstMiss) {
+      shared.agentCount++;
+      return cached.result; // replay the journaled human reply
+    }
+    if (cached == null || cached.hash !== callHash) state.firstMiss = Math.min(state.firstMiss, callIndex);
+    shared.agentCount++;
+
+    let reply: unknown;
+    if (options.confirm) {
+      reply = await options.confirm(promptText, checkpointOptions);
+    } else if (checkpointOptions.headless === "abort") {
+      throw new WorkflowError(
+        `checkpoint "${promptText}" needs human input but none is available (headless run)`,
+        WorkflowErrorCode.WORKFLOW_ABORTED,
+        { recoverable: false },
+      );
+    } else {
+      reply = checkpointOptions.default ?? true;
+    }
+    throwIfAborted();
+    options.onAgentJournal?.({ index: callIndex, runId, hash: callHash, result: reply });
+    return reply;
+  };
+
+  const runtimeBindings: WorkflowRuntimeBindings & { console: Record<string, (m: unknown) => void> } = {
+    agent,
+    parallel,
+    pipeline,
+    workflow: workflowFn,
+    verify,
+    judgePanel,
+    loopUntilDry,
+    completenessCheck,
+    retry,
+    gate,
+    checkpoint,
+    log,
+    phase,
+    args: options.args,
+    cwd: baseCwd,
+    process: Object.freeze({ cwd: () => baseCwd }),
+    budget,
+    console: {
+      log,
+      info: log,
+      warn: (m: unknown) => log(`[warn] ${String(m)}`),
+      error: (m: unknown) => log(`[error] ${String(m)}`),
+    },
+  };
+
+  // Capability contract (A11): the runtime face must match the machine-readable
+  // declaration so docs and reality cannot drift. A mismatch fails loudly at
+  // run start rather than surfacing as a mystery ReferenceError in the vm.
+  const bindingProblems = checkRuntimeBindings(runtimeBindings);
+  if (bindingProblems.length > 0) {
+    throw new WorkflowError(
+      `workflow capability contract violated: ${bindingProblems.join("; ")}`,
+      WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+      { recoverable: false },
+    );
+  }
+
+  const context = vm.createContext({
+    ...runtimeBindings,
+    // Object/Array/JSON/Math/Date/Promise/Set/Map/etc. come from the vm realm
+    // itself — we deliberately do NOT inject host built-ins, whose
+    // .constructor would be the host Function (a determinism-guard bypass).
+    // Math/Date are neutered in-realm by DETERMINISM_PRELUDE below.
+  });
+
+  const wrapped = `${DETERMINISM_PRELUDE}\n(async () => {\n${body}\n})()`;
+  try {
+    const result = await new vm.Script(wrapped, { filename: `${meta.name || "workflow"}.js` }).runInContext(context, {
+      timeout: MAX_SCRIPT_SYNC_MS,
+    });
+    try {
+      const serialized = JSON.stringify(result);
+      if (result !== undefined && serialized === undefined) throw new Error("workflow result is not JSON-serializable");
+    } catch (error: unknown) {
+      throw new WorkflowError(
+        `workflow result is not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`,
+        WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+        { recoverable: false },
+      );
+    }
+
+    options.onTokenUsage?.(shared.tokenUsage);
+
+    return {
+      meta,
+      result: result as T,
+      logs: state.logs,
+      phases: state.phases,
+      agentCount: shared.agentCount,
+      durationMs: Date.now() - started,
+      runId,
+      tokenUsage: shared.tokenUsage,
+    };
+  } catch (error) {
+    // This error escaped THIS frame's vm execution uncaught. For the top-level
+    // frame that means the run's fate is genuinely sealed — a nested frame
+    // reaching here does NOT seal anything (the parent may still catch
+    // workflow()'s rejection). Idempotent: aborting an already-aborted
+    // controller is a no-op.
+    if (isTopLevelRun) shared.runFatalController.abort();
+    throw error;
+  } finally {
+    if (isTopLevelRun) {
+      if (shared.inFlight.size > 0) {
+        log(`waiting for ${shared.inFlight.size} outstanding agent() call(s) to settle before this run completes`);
+      }
+      while (shared.inFlight.size > 0) {
+        await Promise.allSettled(Array.from(shared.inFlight));
+      }
+      store.dispose();
+    }
+  }
+}