@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/workflow/sandbox.mjs

@@ -0,0 +1,534 @@
+/**
+ * lib/engine/workflow/sandbox.mjs — running a workflow script in a node:vm
+ * context.
+ *
+ * What the script sees: the engine's own intrinsics of a FRESH context (no
+ * `require`, `import`, `process`, `console`, timers, `fetch` or filesystem),
+ * frozen, plus these globals (non-writable):
+ *
+ *   agent(prompt, opts?)        → Promise<string | object | null>
+ *   parallel(thunks)            → Promise<Array>   (a barrier; a failure is null)
+ *   pipeline(items, ...stages)  → Promise<Array>   (no barrier between stages)
+ *   phase(title)   log(message)   args   budget {total, spent(), remaining()}
+ *   workflow(ref, args?)        → Promise<value>   (only in a top-level run)
+ *
+ * Determinism: `Date.now()`, `Date()`, `new Date()` with no argument,
+ * `Intl.DateTimeFormat` `format()`/`formatToParts()` with no date and
+ * `Math.random()` throw; `WeakRef` and `FinalizationRegistry` (GC timing) are
+ * absent. A run's agent results are the only inputs that vary, which is what
+ * lets a journal replay a run's prefix (journal.mjs).
+ *
+ * How the boundary is kept. Every object the script can touch is created
+ * INSIDE the context: the API is built by a bootstrap script evaluated there.
+ * The one host function it holds (`bridge`) is captured in the bootstrap's
+ * closure, never exposed, takes and returns only strings, and never throws
+ * into the context (a failure becomes an in-context Error with no reference
+ * to the host's). Results come back through an in-context `deliver(id, json,
+ * error)` the host calls with primitives. Prototype-mutation tricks are shut
+ * by freezing the context's intrinsics before any script code runs (including
+ * `Error`, so `Error.prepareStackTrace` cannot be installed to collect call
+ * sites), string code generation (`eval`, `new Function`) is switched off for
+ * the context, and `import(`/`import.` is refused before compilation
+ * (meta.mjs: on Node's vm a dynamic import rejects with a host-realm error).
+ *
+ * Where it runs (W4-E2, CF-90): in a `worker_threads` Worker of its own
+ * (worker.mjs), with an empty environment, no exec arguments, a heap ceiling
+ * and its console output discarded. agent(), workflow(), phase() and log()
+ * become messages to the engine's thread, where the handlers run; answers come
+ * back as messages. So a script that never yields after an `await` blocks its
+ * worker, not the engine: the engine stays responsive, and it terminates the
+ * worker when the run is stopped (Workflow stop, TaskStop, the turn ending),
+ * when the heartbeat stops for `BUSY_TIMEOUT_MS`, or at the run's time limit.
+ * Only the heartbeat — posted from a timer, so only while the worker's event
+ * loop turns — counts as a sign of life: a script spinning on log(), phase()
+ * or agent() calls is busy, not alive. Those posts are also capped per
+ * heartbeat window (`MAX_NOTES_PER_BEAT`, `MAX_CALLS_PER_BEAT`,
+ * `MAX_POST_BYTES_PER_BEAT`), in the worker and again on the engine's side, so
+ * a spinning script cannot fill the engine's message queue before the watchdog
+ * judges it.
+ *
+ * RESIDUAL RISK — stated plainly: node:vm is still not a security boundary
+ * against a hostile script, and a worker thread shares the engine's process.
+ * A script that escaped the context (a V8 or Node bug, a future host-object
+ * leak) would reach the worker's Node APIs — the filesystem and network among
+ * them — though not the engine's environment variables, which the worker is
+ * not given. The script is written by the model under the session's own
+ * permissions, and every agent() child it starts is permission-clamped like
+ * any subagent; the sandbox keeps the script itself from touching the host and
+ * from stalling the engine, it does not make a malicious script safe. A process
+ * boundary is the follow-up if scripts ever come from anywhere else.
+ *
+ * @module lib/engine/workflow/sandbox
+ */
+
+import vm from "node:vm";
+import { performance } from "node:perf_hooks";
+import { Worker } from "node:worker_threads";
+
+/** How long the script's synchronous start (up to its first await) may run. */
+export const SYNC_TIMEOUT_MS = 2_000;
+/** The bootstrap's own limit (it freezes every intrinsic; a cold worker isolate is slower). */
+export const BOOTSTRAP_TIMEOUT_MS = 5_000;
+/** CF-90: how long the script's thread may go without its event loop turning (a busy loop after an await). */
+export const BUSY_TIMEOUT_MS = 10_000;
+/** How long a worker may take to reach its first await, beyond the synchronous limit, before it is judged stuck. */
+export const START_GRACE_MS = 15_000;
+/** The script's heap ceiling: a runaway allocation ends the worker, not the engine. */
+export const WORKER_HEAP_MB = 512;
+/**
+ * Flood limits, per heartbeat window (the worker's event loop turning resets them).
+ * phase() and log() post synchronously and never yield, so a script spinning on them
+ * would otherwise fill the engine's message queue with no bound: past a limit the
+ * worker refuses further posts and reports the flood, and the engine counts on its own
+ * side too and ends the run. `parallel()` of `MAX_ITEMS` agents stays well inside.
+ */
+export const MAX_NOTES_PER_BEAT = 1_000;
+export const MAX_CALLS_PER_BEAT = 10_000;
+export const MAX_POST_BYTES_PER_BEAT = 64 * 1024 * 1024;
+/** A phase title or log line is cut at this many characters before it leaves the worker. */
+export const MAX_NOTE_CHARS = 16_000;
+const WORKER_URL = new URL("./worker.mjs", import.meta.url);
+/** Items per parallel() / pipeline() call. */
+export const MAX_ITEMS = 4096;
+
+/**
+ * The in-context bootstrap. Evaluated once per run; returns
+ * {setMain, deliver}. Authorship: written for Cohort Engine by the Cohort team.
+ */
+export const BOOTSTRAP = String.raw`(function (bridge, argsJson, limitsJson) {
+  "use strict";
+  const g = globalThis;
+  const O = Object, P = Promise, E = Error, TE = TypeError;
+  const parse = JSON.parse, stringify = JSON.stringify, isArray = Array.isArray;
+  const limits = parse(limitsJson);
+  const pending = new Map();
+
+  function fail(message) { return new E(message); }
+  function call(op, payload) {
+    let text;
+    try { text = stringify(payload); } catch { throw new TE("workflow: the arguments must be JSON-serialisable"); }
+    let out;
+    try { out = bridge(op, text === undefined ? "null" : text); } catch { throw fail("workflow: the engine could not take the call"); }
+    if (typeof out !== "string") throw fail("workflow: the engine could not take the call");
+    const r = parse(out);
+    if (r && typeof r.error === "string") throw fail(r.error);
+    return r;
+  }
+  function viaHost(op, payload) {
+    return new P((resolve, reject) => {
+      const r = call(op, payload);
+      pending.set(r.id, { resolve, reject });
+    });
+  }
+  function deliver(id, json, error) {
+    const p = pending.get(id);
+    if (!p) return;
+    pending.delete(id);
+    if (typeof error === "string") p.reject(fail(error));
+    else p.resolve(json === null ? null : parse(json));
+  }
+  function text(v) {
+    if (typeof v === "string") return v;
+    try { const s = stringify(v); return s === undefined ? String(v) : s; } catch { return String(v); }
+  }
+  function deepFreeze(v) {
+    if (v && typeof v === "object") { for (const k of O.keys(v)) deepFreeze(v[k]); O.freeze(v); }
+    return v;
+  }
+
+  const AGENT_OPTS = ["label", "phase", "schema", "model", "effort", "isolation", "agentType"];
+  function agent(prompt, opts) {
+    if (typeof prompt !== "string" || prompt.trim() === "") return P.reject(new TE("agent(prompt, opts): prompt must be a non-empty string"));
+    if (opts !== undefined && (opts === null || typeof opts !== "object" || isArray(opts))) return P.reject(new TE("agent(prompt, opts): opts must be an object"));
+    const picked = {};
+    if (opts) {
+      for (const k of O.keys(opts)) if (!AGENT_OPTS.includes(k)) return P.reject(new TE("agent(): unknown option " + stringify(k) + " (known: " + AGENT_OPTS.join(", ") + ")"));
+      for (const k of AGENT_OPTS) if (opts[k] !== undefined) picked[k] = opts[k];
+    }
+    return viaHost("agent", { prompt, opts: picked });
+  }
+  function settle(fn, a, b, c) {
+    return new P((resolve) => {
+      try { P.resolve(typeof fn === "function" ? fn(a, b, c) : fn).then(resolve, () => resolve(null)); }
+      catch { resolve(null); }
+    });
+  }
+  function items(what, list) {
+    if (!isArray(list)) throw new TE(what + " takes an array");
+    if (list.length > limits.maxItems) throw new TE(what + ": at most " + limits.maxItems + " items per call (got " + list.length + ")");
+  }
+  function parallel(thunks) {
+    try { items("parallel()", thunks); } catch (e) { return P.reject(e); }
+    const runs = [];
+    for (let i = 0; i < thunks.length; i++) runs.push(settle(thunks[i]));
+    return P.all(runs);
+  }
+  function pipeline(list, ...stages) {
+    try {
+      items("pipeline()", list);
+      for (let i = 0; i < stages.length; i++) if (typeof stages[i] !== "function") throw new TE("pipeline(items, ...stages): stage " + (i + 1) + " is not a function");
+    } catch (e) { return P.reject(e); }
+    const runs = [];
+    for (let index = 0; index < list.length; index++) {
+      const item = list[index];
+      runs.push((async () => {
+        let prev = item;
+        for (let s = 0; s < stages.length; s++) {
+          try { prev = await stages[s](prev, item, index); } catch { return null; }
+        }
+        return prev;
+      })());
+    }
+    return P.all(runs);
+  }
+  function phase(title) { call("phase", { title: text(title) }); }
+  function log(message) { call("log", { message: text(message) }); }
+  function workflow(ref, wfArgs) {
+    if (!limits.allowNested) return P.reject(fail("workflow(): a nested workflow cannot start another workflow (one level of nesting)"));
+    if (typeof ref !== "string" || ref.trim() === "") return P.reject(new TE("workflow(ref, args): ref must be a script path or a workflow name"));
+    return viaHost("workflow", { ref, args: wfArgs === undefined ? null : wfArgs });
+  }
+  const budget = O.freeze({
+    total: limits.budgetTotal,
+    spent() { return call("budget", {}).spent; },
+    remaining() { if (limits.budgetTotal === null) return Infinity; const r = limits.budgetTotal - call("budget", {}).spent; return r > 0 ? r : 0; },
+  });
+
+  // Determinism: no clock, no randomness.
+  const RealDate = Date;
+  const refuse = (what) => { throw fail(what + " is not available in a workflow script: runs must replay identically. Pass times in args, or ask an agent."); };
+  function SafeDate(...a) {
+    if (new.target === undefined) refuse("Date()");
+    if (a.length === 0) refuse("new Date() without an argument");
+    return Reflect.construct(RealDate, a, new.target);
+  }
+  SafeDate.prototype = RealDate.prototype;
+  O.defineProperty(RealDate.prototype, "constructor", { value: SafeDate, writable: false, configurable: false });
+  SafeDate.UTC = RealDate.UTC;
+  SafeDate.parse = RealDate.parse;
+  SafeDate.now = () => refuse("Date.now()");
+  RealDate.now = SafeDate.now;
+  Math.random = () => refuse("Math.random()");
+  // Intl.DateTimeFormat formats "now" when it is given no date.
+  const DTF = Intl.DateTimeFormat.prototype;
+  const formatGetter = O.getOwnPropertyDescriptor(DTF, "format").get;
+  const formatToParts = DTF.formatToParts;
+  O.defineProperty(DTF, "format", {
+    configurable: false,
+    get() {
+      const bound = formatGetter.call(this);
+      return function format(date) {
+        if (date === undefined) refuse("Intl.DateTimeFormat format() without a date");
+        return bound(date);
+      };
+    },
+  });
+  O.defineProperty(DTF, "formatToParts", {
+    writable: false,
+    configurable: false,
+    value: function formatToParts_(date) {
+      if (date === undefined) refuse("Intl.DateTimeFormat formatToParts() without a date");
+      return formatToParts.call(this, date);
+    },
+  });
+
+  // Nothing but the language and the API (WeakRef and FinalizationRegistry expose GC timing).
+  for (const name of ["console", "WebAssembly", "SharedArrayBuffer", "Atomics", "WeakRef", "FinalizationRegistry"]) {
+    try { delete g[name]; } catch {}
+    if (name in g) O.defineProperty(g, name, { value: undefined, writable: false, configurable: false });
+  }
+  O.defineProperty(g, "Date", { value: SafeDate, writable: false, configurable: false });
+
+  // Freeze the intrinsics (and the hidden ones reachable through syntax).
+  const seen = new Set([g]); // the global itself is frozen last, once the API is on it
+  const freeze = (v) => {
+    if ((typeof v !== "object" && typeof v !== "function") || v === null || seen.has(v)) return;
+    seen.add(v);
+    O.freeze(v);
+    freeze(O.getPrototypeOf(v));
+    for (const k of Reflect.ownKeys(v)) {
+      const d = O.getOwnPropertyDescriptor(v, k);
+      if (d && "value" in d) freeze(d.value);
+      if (d && d.get) freeze(d.get);
+      if (d && d.set) freeze(d.set);
+    }
+  };
+  for (const k of Reflect.ownKeys(g)) {
+    const d = O.getOwnPropertyDescriptor(g, k);
+    if (d && "value" in d) freeze(d.value);
+  }
+  freeze(async function () {});
+  freeze(function* () {});
+  freeze(async function* () {});
+  freeze([][Symbol.iterator]());
+  freeze(new Map()[Symbol.iterator]());
+  freeze(new Set()[Symbol.iterator]());
+  freeze(""[Symbol.iterator]());
+  freeze(/x/[Symbol.matchAll](""));
+  freeze((async function* () {})());
+  freeze((function* () {})());
+
+  const api = { agent, parallel, pipeline, phase, log, workflow, budget, args: deepFreeze(parse(argsJson)) };
+  for (const k of O.keys(api)) O.defineProperty(g, k, { value: api[k], writable: false, enumerable: true, configurable: false });
+
+  let main = null;
+  O.defineProperty(g, "__cohortKick", {
+    configurable: true,
+    value: function () {
+      delete g.__cohortKick;
+      try { O.freeze(g); } catch {} // the API bindings are already non-writable and non-configurable
+      const m = main;
+      main = null;
+      let started;
+      try { started = m(); } catch (e) { started = P.reject(e); }
+      P.resolve(started).then(
+        (v) => {
+          let json;
+          try { json = stringify(v === undefined ? null : v); } catch (e) { call("done", { ok: false, error: "the workflow's return value is not JSON-serialisable (" + text(e && e.message) + ")" }); return; }
+          call("done", { ok: true, json: json === undefined ? "null" : json });
+        },
+        (e) => {
+          let message;
+          try { message = e instanceof E ? String(e.message) : text(e); } catch { message = "the workflow threw"; }
+          let stack = null;
+          try { stack = e instanceof E && typeof e.stack === "string" ? e.stack : null; } catch {}
+          call("done", { ok: false, error: message, stack });
+        },
+      );
+    },
+  });
+  return O.freeze({ setMain(fn) { main = fn; }, deliver });
+})`;
+
+/**
+ * @typedef {{code:string, filename:string}} CompiledWorkflow  what a worker compiles again and runs
+ */
+
+/**
+ * Compile a script body without running it (syntax errors surface here). The
+ * result is the wrapped source, which the worker compiles in its own isolate.
+ * @param {string} body  the source with `export` blanked (meta.mjs)
+ * @param {string} filename
+ * @returns {{ok:true, script:CompiledWorkflow}|{ok:false, error:string}}
+ */
+export function compileWorkflow(body, filename) {
+  const code = `(async function () {\n${body}\n})`;
+  try {
+    new vm.Script(code, { filename, lineOffset: -1 });
+    return { ok: true, script: Object.freeze({ code, filename }) };
+  } catch (e) {
+    return { ok: false, error: `the workflow script does not compile: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+/**
+ * @typedef {Object} SandboxHandlers
+ * @property {(payload:any) => {id:number}|{error:string}} agent     start an agent call; deliver later
+ * @property {(payload:any) => {id:number}|{error:string}} workflow  start a nested workflow; deliver later
+ * @property {(title:string) => void} phase
+ * @property {(message:string) => void} log
+ * @property {() => number} spent
+ */
+
+/**
+ * Run a compiled script in its own worker thread (W4-E2, CF-90; worker.mjs).
+ * Resolves when the script's main function settles, or when the engine ends it:
+ * `terminate()` (a stop), the heartbeat watchdog (`busyTimeoutMs` without the
+ * worker's event loop turning — a busy loop after an await), `runTimeoutMs`,
+ * or the worker failing (its heap ceiling included). However it ends, the
+ * worker is terminated. The handlers run on the engine's thread, in the order
+ * the script made its calls.
+ * @param {object} p
+ * @param {CompiledWorkflow} p.script
+ * @param {unknown} p.args
+ * @param {SandboxHandlers} p.handlers
+ * @param {{budgetTotal:number|null, allowNested:boolean, maxItems?:number}} p.limits
+ * @param {number} [p.syncTimeoutMs]
+ * @param {number} [p.busyTimeoutMs]
+ * @param {number|null} [p.runTimeoutMs]  the whole script, from its start; null = no limit
+ * @param {() => number} [p.now]          a monotonic clock in milliseconds
+ * @param {URL} [p.workerUrl]             the worker module (tests substitute a misbehaving one)
+ * @returns {{deliver:(id:number, json:string|null, error:string|null)=>void, terminate:()=>Promise<void>, done:Promise<{ok:true, json:string}|{ok:false, error:string, stack:string|null}>}}
+ */
+export function runInSandbox({ script, args, handlers, limits, syncTimeoutMs = SYNC_TIMEOUT_MS, busyTimeoutMs = BUSY_TIMEOUT_MS, runTimeoutMs = null, now = () => performance.now(), workerUrl = WORKER_URL }) {
+  const failed = (/** @type string */ error) => ({ deliver: () => {}, terminate: async () => {}, done: Promise.resolve({ ok: false, error, stack: null }) });
+  if (!script || typeof script.code !== "string" || typeof script.filename !== "string") return failed("the workflow script was not compiled for the sandbox");
+  const errorText = (/** @type unknown */ e) => (e instanceof Error ? e.message : String(e));
+  const beatMs = Math.max(5, Math.min(250, Math.floor(busyTimeoutMs / 4)));
+
+  /** @type {Worker} */
+  let worker;
+  try {
+    worker = new Worker(workerUrl, {
+      workerData: {
+        code: script.code,
+        filename: script.filename,
+        argsJson: JSON.stringify(args ?? null) ?? "null",
+        limitsJson: JSON.stringify({ maxItems: limits.maxItems ?? MAX_ITEMS, budgetTotal: limits.budgetTotal, allowNested: limits.allowNested }),
+        syncTimeoutMs,
+        beatMs,
+        flood: { notes: MAX_NOTES_PER_BEAT, calls: MAX_CALLS_PER_BEAT, bytes: MAX_POST_BYTES_PER_BEAT, noteChars: MAX_NOTE_CHARS },
+      },
+      env: {}, // the engine's environment (the seat token included) is not copied into the script's thread
+      execArgv: [],
+      stdout: true,
+      stderr: true,
+      resourceLimits: { maxOldGenerationSizeMb: WORKER_HEAP_MB },
+    });
+  } catch (e) {
+    return failed(`the workflow worker could not start: ${errorText(e)}`);
+  }
+  worker.stdout?.resume();
+  worker.stderr?.resume();
+
+  /** @type {(r:any)=>void} */
+  let finish = () => {};
+  const done = new Promise((resolve) => (finish = resolve));
+  let settled = false;
+  /** @type {Promise<void>} */
+  let terminated = Promise.resolve();
+  /** @type {Array<ReturnType<typeof setTimeout>>} */
+  const timers = [];
+  const settle = (/** @type any */ r) => {
+    if (settled) return;
+    settled = true;
+    for (const t of timers) clearTimeout(t);
+    terminated = worker.terminate().then(() => undefined, () => undefined);
+    finish(r);
+  };
+  const spawnedAt = now();
+  let lastSign = spawnedAt;
+  let started = false;
+
+  /** engine call id → worker call id, and answers that arrived before their call was mapped */
+  const widByHid = new Map();
+  const early = new Map();
+  const spentNow = () => {
+    try {
+      const s = handlers.spent();
+      return Number.isFinite(s) ? s : 0;
+    } catch {
+      return 0;
+    }
+  };
+  const answer = (/** @type number */ wid, /** @type {string|null} */ json, /** @type {string|null} */ error) => {
+    if (!settled) worker.postMessage({ t: "deliver", wid, json, error, spent: spentNow() });
+  };
+
+  // Posts since the last heartbeat: the engine's own flood count, whatever the worker claims.
+  let notesSinceBeat = 0;
+  let callsSinceBeat = 0;
+  let bytesSinceBeat = 0;
+  const flooded = (/** @type string */ what) =>
+    settle({ ok: false, error: `the workflow script sent ${what} without its event loop turning (a busy loop after an await) and was stopped`, stack: null });
+  const floodText = () => `more than ${MAX_NOTES_PER_BEAT} phase()/log() calls, ${MAX_CALLS_PER_BEAT} agent()/workflow() calls or ${MAX_POST_BYTES_PER_BEAT / (1024 * 1024)} MB`;
+
+  worker.on("message", (/** @type any */ m) => {
+    if (settled || !m || typeof m !== "object") return;
+    // Only the heartbeat (a worker timer) and the start are signs of life; a call or a note is not.
+    if (m.t === "beat" || m.t === "started") {
+      lastSign = now();
+      notesSinceBeat = 0;
+      callsSinceBeat = 0;
+      bytesSinceBeat = 0;
+    } else if (m.t === "call" || m.t === "phase" || m.t === "log") {
+      const size = String((m.t === "call" ? m.payload : m.t === "phase" ? m.title : m.message) ?? "").length;
+      bytesSinceBeat += size;
+      if (m.t === "call") callsSinceBeat++;
+      else notesSinceBeat++;
+      // A little slack over the worker's own limits, so its report (the clearer error) arrives first.
+      if (notesSinceBeat > MAX_NOTES_PER_BEAT + 16 || callsSinceBeat > MAX_CALLS_PER_BEAT + 16 || bytesSinceBeat > MAX_POST_BYTES_PER_BEAT + MAX_NOTE_CHARS * 16) {
+        flooded(floodText());
+        return;
+      }
+    }
+    switch (m.t) {
+      case "beat":
+        return;
+      case "started":
+        started = true;
+        return;
+      case "flood":
+        flooded(floodText());
+        return;
+      case "call": {
+        /** @type any */
+        let r;
+        try {
+          const data = JSON.parse(String(m.payload));
+          r = m.op === "agent" ? handlers.agent(data) : m.op === "workflow" ? handlers.workflow(data) : { error: `workflow: unknown call ${m.op}` };
+        } catch (e) {
+          r = { error: `workflow: ${errorText(e)}` };
+        }
+        if (!r || typeof r.id !== "number") {
+          answer(m.wid, null, typeof r?.error === "string" ? r.error : "workflow: the engine could not take the call");
+          return;
+        }
+        const waiting = early.get(r.id);
+        if (waiting) {
+          early.delete(r.id);
+          answer(m.wid, waiting.json, waiting.error);
+        } else widByHid.set(r.id, m.wid);
+        return;
+      }
+      case "phase":
+        try {
+          handlers.phase(String(m.title ?? ""));
+        } catch {
+          /* a progress note never fails the run */
+        }
+        return;
+      case "log":
+        try {
+          handlers.log(String(m.message ?? ""));
+        } catch {
+          /* as above */
+        }
+        return;
+      case "done": {
+        const r = m.result;
+        settle(r?.ok ? { ok: true, json: typeof r.json === "string" ? r.json : "null" } : { ok: false, error: String(r?.error ?? "the workflow failed"), stack: typeof r?.stack === "string" ? r.stack : null });
+        return;
+      }
+      default:
+        return;
+    }
+  });
+  worker.on("error", (/** @type any */ e) => settle({ ok: false, error: e?.code === "ERR_WORKER_OUT_OF_MEMORY" ? `the workflow script used more than ${WORKER_HEAP_MB} MB and was stopped` : `the workflow worker failed: ${errorText(e)}`, stack: null }));
+  worker.on("exit", (code) => settle({ ok: false, error: `the workflow worker exited (code ${code}) before the script finished`, stack: null }));
+
+  // The watchdog. It judges in a setImmediate, after the poll phase has read any messages that
+  // queued while this thread was itself busy, so a slow engine is not mistaken for a stuck script.
+  const judge = () => {
+    if (settled) return;
+    const t = now();
+    if (started && t - lastSign > busyTimeoutMs) {
+      settle({ ok: false, error: `the workflow script ran for more than ${busyTimeoutMs} ms without yielding (a busy loop after an await) and was stopped`, stack: null });
+    } else if (!started && t - spawnedAt > syncTimeoutMs + START_GRACE_MS) {
+      settle({ ok: false, error: `the workflow worker did not reach its first await within ${syncTimeoutMs + START_GRACE_MS} ms and was stopped`, stack: null });
+    }
+  };
+  timers.push(setInterval(() => setImmediate(judge), beatMs));
+  if (runTimeoutMs !== null && Number.isFinite(runTimeoutMs) && runTimeoutMs > 0) {
+    timers.push(setTimeout(() => settle({ ok: false, error: `the workflow ran for more than ${runTimeoutMs} ms and was stopped`, stack: null }), runTimeoutMs));
+  }
+
+  return {
+    deliver: (id, json, error) => {
+      if (settled) return;
+      const wid = widByHid.get(id);
+      if (wid === undefined) {
+        early.set(id, { json, error });
+        return;
+      }
+      widByHid.delete(id);
+      answer(wid, json, error);
+    },
+    /** End the script now (a stop): the worker is terminated and `done` resolves as stopped. */
+    terminate: async () => {
+      settle({ ok: false, error: "the workflow was stopped", stack: null });
+      await terminated;
+    },
+    done,
+  };
+}

package/lib/engine/workflow/worker.mjs

@@ -0,0 +1,141 @@
+/**
+ * lib/engine/workflow/worker.mjs — the worker thread a workflow script runs in
+ * (W4-E2, CF-90). Started by sandbox.mjs `runInSandbox`; never imported
+ * elsewhere.
+ *
+ * Inside the worker the script still runs in a fresh, frozen `node:vm` context
+ * built by the same bootstrap (sandbox.mjs BOOTSTRAP), with string code
+ * generation off. What the worker adds is a thread of its own: a script that
+ * never yields after an `await` blocks this thread, not the engine's, and the
+ * engine can terminate the thread at any time (a stop, a timeout, the heartbeat
+ * watchdog).
+ *
+ * Messages (structured clone, strings and numbers only):
+ *
+ *   worker → engine
+ *     {t:"started"}                          the synchronous start (up to the first await) returned
+ *     {t:"beat"}                             every `beatMs` while this thread's event loop turns
+ *     {t:"call", op:"agent"|"workflow", wid, payload}   payload: the call's JSON
+ *     {t:"phase", title}   {t:"log", message}  (cut at the note limit)
+ *     {t:"flood"}                            posts passed a per-heartbeat limit; later posts are refused
+ *     {t:"done", result:{ok:true, json} | {ok:false, error, stack}}
+ *
+ *   engine → worker
+ *     {t:"deliver", wid, json, error, spent} a call's answer (json or error) and the budget spent so far
+ *
+ * `wid` numbers the calls this worker made; the engine maps them to its own.
+ * `budget.spent()` reads the last `spent` the engine sent, which every answer
+ * carries, so a script reads what it read before: the spend of the agents that
+ * had answered.
+ *
+ * @module lib/engine/workflow/worker
+ */
+
+import vm from "node:vm";
+import { parentPort, workerData } from "node:worker_threads";
+import { BOOTSTRAP, BOOTSTRAP_TIMEOUT_MS } from "./sandbox.mjs";
+
+if (!parentPort) throw new Error("workflow/worker.mjs runs only as a worker thread");
+const port = parentPort;
+const { code, filename, argsJson, limitsJson, syncTimeoutMs, beatMs, flood } = /** @type {{code:string, filename:string, argsJson:string, limitsJson:string, syncTimeoutMs:number, beatMs:number, flood:{notes:number, calls:number, bytes:number, noteChars:number}}} */ (workerData);
+
+let spent = 0;
+let nextId = 0;
+let settled = false;
+const post = (/** @type any */ m) => port.postMessage(m);
+const errorText = (/** @type unknown */ e) => (e instanceof Error ? e.message : String(e));
+
+// Flood control (see sandbox.mjs MAX_NOTES_PER_BEAT): posts since the heartbeat last ran. The heartbeat
+// is a timer, so it runs only when this thread's event loop turns; a script spinning on log(), phase()
+// or agent() never lets it, and past a limit its posts are refused and the flood is reported once.
+let notes = 0;
+let calls = 0;
+let bytes = 0;
+let floodReported = false;
+const FLOODED = JSON.stringify({ error: "workflow: too many calls without yielding; the run is being stopped" });
+/** @param {'note'|'call'} kind @param {number} size @returns {boolean} whether the post may go */
+function admit(kind, size) {
+  if (floodReported) return false;
+  if (kind === "call") calls++;
+  else notes++;
+  bytes += size;
+  if (notes <= flood.notes && calls <= flood.calls && bytes <= flood.bytes) return true;
+  floodReported = true;
+  post({ t: "flood" });
+  return false;
+}
+/** @param {unknown} v */
+const note = (v) => {
+  const s = String(v ?? "");
+  return s.length <= flood.noteChars ? s : `${s.slice(0, flood.noteChars)}… [cut at ${flood.noteChars} characters]`;
+};
+
+/** Strings in, a string out; never throws into the context. @param {unknown} op @param {unknown} payload */
+function bridge(op, payload) {
+  try {
+    if (typeof op !== "string" || typeof payload !== "string") return JSON.stringify({ error: "workflow: bad call" });
+    switch (op) {
+      case "agent":
+      case "workflow": {
+        if (!admit("call", payload.length)) return FLOODED;
+        const wid = ++nextId;
+        post({ t: "call", op, wid, payload });
+        return JSON.stringify({ id: wid });
+      }
+      case "phase": {
+        const title = note(JSON.parse(payload)?.title);
+        if (!admit("note", title.length)) return FLOODED;
+        post({ t: "phase", title });
+        return "{}";
+      }
+      case "log": {
+        const message = note(JSON.parse(payload)?.message);
+        if (!admit("note", message.length)) return FLOODED;
+        post({ t: "log", message });
+        return "{}";
+      }
+      case "budget":
+        return JSON.stringify({ spent });
+      case "done": {
+        if (!settled) {
+          settled = true;
+          const data = JSON.parse(payload);
+          post({ t: "done", result: data?.ok ? { ok: true, json: typeof data.json === "string" ? data.json : "null" } : { ok: false, error: String(data?.error ?? "the workflow failed"), stack: typeof data?.stack === "string" ? data.stack : null } });
+        }
+        return "{}";
+      }
+      default:
+        return JSON.stringify({ error: `workflow: unknown call ${op}` });
+    }
+  } catch (e) {
+    return JSON.stringify({ error: `workflow: ${errorText(e)}` });
+  }
+}
+
+setInterval(() => {
+  notes = 0;
+  calls = 0;
+  bytes = 0;
+  post({ t: "beat" });
+}, beatMs);
+
+const context = vm.createContext(Object.create(null), { name: "cohort-workflow", codeGeneration: { strings: false, wasm: false } });
+try {
+  const boot = new vm.Script(BOOTSTRAP, { filename: "cohort-workflow-bootstrap" }).runInContext(context, { timeout: Math.max(syncTimeoutMs, BOOTSTRAP_TIMEOUT_MS) });
+  const ctl = boot(bridge, argsJson, limitsJson);
+  const main = new vm.Script(code, { filename, lineOffset: -1 }).runInContext(context, { timeout: syncTimeoutMs });
+  ctl.setMain(main);
+  port.on("message", (/** @type any */ m) => {
+    if (!m || m.t !== "deliver" || settled) return;
+    if (Number.isFinite(m.spent)) spent = m.spent;
+    ctl.deliver(m.wid, typeof m.json === "string" ? m.json : null, typeof m.error === "string" ? m.error : null);
+  });
+  vm.runInContext("__cohortKick()", context, { timeout: syncTimeoutMs });
+  post({ t: "started" });
+} catch (e) {
+  if (!settled) {
+    settled = true;
+    const timedOut = /** @type any */ (e)?.code === "ERR_SCRIPT_EXECUTION_TIMEOUT";
+    post({ t: "done", result: { ok: false, error: timedOut ? `the workflow script ran for more than ${syncTimeoutMs} ms before its first await` : `the workflow script failed to start: ${errorText(e)}`, stack: null } });
+  }
+}