@sema-agent/server 1.322.0 → 2.0.0

package/dist/orchestration/hardened-vm-runner.js

@@ -7,7 +7,17 @@ const DEFAULTS = {
     concurrency: 12,
     maxHeapMb: 128,
 };
+/** Own keys that carry a prototype-tampering gadget across the JSON membrane. */
 const PROTO_TAMPER_KEYS = ["__proto__", "constructor", "prototype"];
+/**
+ * Recursively delete own `__proto__` / `constructor` / `prototype` keys from JSON-parsed data. Closes the
+ * tampering gadget a script passes across the membrane: `Reflect.defineProperty(o, "__proto__",
+ * {enumerable:true, value:{...}})` (Reflect is reachable; `codeGeneration:{strings:false}` does NOT block it)
+ * makes `__proto__` an OWN ENUMERABLE key, which in-context `JSON.stringify` emits and host `JSON.parse`
+ * re-materializes as a real own data property — feeding a host fn (or the returned result) a crafted
+ * prototype a downstream deep-merge / key-assignment sink splats onto the HOST realm's `Object.prototype`
+ * (process-wide, cross-tenant). Caught by the s8-sandbox-robustness marshal-bridge lens (core's battery + the
+ * result-path probes both miss it). Apply ONLY to JSON.parse output (plain, acyclic, getter-free). */
 function scrubProtoDeep(value) {
     if (value === null || typeof value !== "object")
         return;
@@ -24,8 +34,22 @@ function scrubProtoDeep(value) {
         scrubProtoDeep(value[key]);
     }
 }
+/**
+ * [1818]§二邻位 — script-realm rejection guard. The vm context shares the HOST isolate's unhandledRejection
+ * machinery, and Node's default posture is CRASH: an untrusted script's un-awaited rejection (a bare
+ * `(async () => { throw ... })()`, an un-awaited `agent()`/`phase()` whose body fails) would take the whole
+ * server process down — a resource/availability hole, not a data-boundary one (clay's live incident hit the
+ * sibling shape that HANGS instead of rejecting, which is the only reason it didn't crash). There is no
+ * per-context hook in Node, so the guard is a process listener that tells realms apart by intrinsic:
+ * a promise minted INSIDE the context fails `instanceof` against the HOST `Promise`. Context-realm rejections
+ * are contained (logged, never fatal); host-realm rejections keep Node's fail-loud default (rethrown as an
+ * uncaughtException) UNLESS the deployment installed its own handler — then we defer to it entirely.
+ * Installed lazily on the first hardened run: only processes that actually execute untrusted scripts change
+ * their global posture, and only then is the hazard live. Idempotent.
+ */
 let rejectionGuardInstalled = false;
 let onScriptRealmRejection;
+/** Optional observability hook for contained script-realm rejections (e.g. wire to the deployment logger). */
 export function setScriptRealmRejectionObserver(observer) {
     onScriptRealmRejection = observer;
 }
@@ -35,24 +59,32 @@ export function installScriptRealmRejectionGuard() {
     rejectionGuardInstalled = true;
     process.on("unhandledRejection", (reason, promise) => {
         if (!(promise instanceof Promise)) {
+            // cross-realm ⇒ minted in a vm context ⇒ an un-awaited rejection inside an untrusted script. Contain.
             const summary = reason instanceof Error ? `${reason.name}: ${reason.message}` : String(reason);
             try {
                 (onScriptRealmRejection ?? ((s) => console.warn(`hardened-vm: un-awaited script rejection contained: ${s}`)))(summary);
             }
             catch {
+                /* the guard must never become a crash source itself */
             }
             return;
         }
+        // Host-realm: preserve fail-loud unless another handler exists (a deployment that installed one chose
+        // its own posture — a rethrow here would override that choice).
         if (process.listenerCount("unhandledRejection") > 1)
             return;
         throw reason;
     });
 }
+/** Host-side parse that strips the tampering gadget from data crossing INTO a host fn. */
 function sterilizingParse(json) {
     const parsed = JSON.parse(json);
     scrubProtoDeep(parsed);
     return parsed;
 }
+/** Marshal a (possibly live cross-realm) script value to PLAIN, sterilized host data: JSON round-trips it
+ *  (firing in-context getters/toJSON harmlessly in-context → plain data; drops functions; no live context
+ *  object with traps reaches the host) then strips the tampering gadget. Throws on a non-serializable result. */
 function marshalOut(value) {
     let json;
     try {
@@ -63,14 +95,21 @@ function marshalOut(value) {
     }
     return sterilizingParse(json === undefined ? "null" : json);
 }
+/**
+ * The shared hardened-vm core. Builds the membrane, lets `buildGlobals` construct the context-local globals,
+ * runs the untrusted `body` as an async function under the caps, and returns the MARSHALLED (plain, sterilized)
+ * result. Both public surfaces delegate here.
+ */
 async function runHardened(opts) {
     const cfg = { ...DEFAULTS, ...opts.limits };
     const { signal } = opts;
     if (signal?.aborted)
         throw new WorkflowScriptError("hardened-vm aborted before start");
     installScriptRealmRejectionGuard();
+    // 1. hardened context
     const sandbox = { __proto__: null };
     const ctx = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
+    // 2. determinism guard (resume-safety; matches CC): nondeterministic clocks/RNG throw in-context.
     vm.runInContext(`(() => {
        const block = (l) => { throw new Error(l + " is unavailable in workflow scripts (nondeterministic — breaks resume). Pass timestamps via args; vary by index for randomness."); };
        Date.now = () => block("Date.now()");
@@ -87,17 +126,30 @@ async function runHardened(opts) {
          globalThis[n] = () => noTimer(n + "()");
        }
      })()`, ctx);
+    // 3. membrane helpers (factory bodies COMPILED IN-CONTEXT → context-rooted prototypes)
     const ctxJsonParse = vm.runInContext("(s => JSON.parse(s))", ctx);
     const dataIn = (v) => {
+        // sterilize the gadget host-side BEFORE it re-materializes in-context (a __proto__ own key would otherwise
+        // pollute the CONTEXT's Object.prototype — sandboxed, but cheap to close).
         const clean = JSON.parse(JSON.stringify(v === undefined ? null : v));
         scrubProtoDeep(clean);
         return ctxJsonParse(JSON.stringify(clean));
     };
+    // a {ok,v} | {ok:false,err,name} JSON round-trip; the IN-CONTEXT wrapper throws a CONTEXT-LOCAL Error on
+    // failure so a host error never reaches the script (beyond-battery fix).
     const mkBridge = vm.runInContext(`(hostCall => async function (...a) {
        const r = JSON.parse(await hostCall(JSON.stringify(a)));
        if (r.ok) return r.v;
        const e = new Error(r.err); e.name = r.name || "Error"; throw e;
      })`, ctx);
+    // [1818]§二 — quiescence deadlock detector. Inside the membrane the ONLY way a suspended script can ever be
+    // resumed is a bridged host call settling: timers are blocked, there is no I/O, and every other await is a
+    // microtask chain that drains on its own. So "zero bridged calls in flight + the microtask AND macrotask
+    // queues have both drained + scriptPromise still pending" is not a heuristic — it PROVES the script can never
+    // progress again (clay's live shape: an un-awaited `const r = phase(...)` whose body returns `r` → a promise
+    // cycle that neither rejects nor resolves; pre-fix it burned the full totalTimeoutMs blind and then blamed
+    // the timeout). setImmediate (a macrotask) is the drain fence: any continuation the settling host call woke
+    // runs first, and a continuation that starts a new bridged call increments the counter synchronously.
     let inFlightHostCalls = 0;
     let scriptSettled = false;
     let fireDeadlock;
@@ -113,6 +165,8 @@ async function runHardened(opts) {
     const bridge = (hostFn) => mkBridge(async (argsJson) => {
         inFlightHostCalls++;
         try {
+            // sterilizingParse (not bare JSON.parse): strip a slipped-in __proto__/constructor/prototype gadget
+            // BEFORE the args reach the host fn — the dangerous (script→host) direction.
             const out = await hostFn(...sterilizingParse(argsJson));
             return JSON.stringify({ ok: true, v: out ?? null });
         }
@@ -129,6 +183,7 @@ async function runHardened(opts) {
         }
     });
     const membrane = { bridge, dataIn, ctxEval: (src) => vm.runInContext(src, ctx) };
+    // 4. expose the surface's context-local globals + run the body under the sync vm timeout
     for (const [name, value] of Object.entries(opts.buildGlobals(membrane)))
         sandbox[name] = value;
     let invocation;
@@ -138,9 +193,14 @@ async function runHardened(opts) {
     catch (err) {
         throw new WorkflowScriptError(`script failed to compile: ${err instanceof Error ? err.message : String(err)}`);
     }
+    // `timeout` bounds the SYNCHRONOUS run up to the first await (a sync infinite loop is killed here); an async
+    // loop is bounded by the wall-clock race below.
     const scriptPromise = invocation.runInContext(ctx, { timeout: cfg.syncTimeoutMs });
     scriptPromise.then(() => (scriptSettled = true), () => (scriptSettled = true));
+    // Initial probe: a script that suspends without EVER touching the bridge (`await new Promise(() => {})`)
+    // never decrements the counter, so the settle-side probe alone would miss it.
     probeQuiescence();
+    // 5. wall-clock + external-abort + quiescence-deadlock race
     let timer;
     let onAbort;
     try {
@@ -153,14 +213,24 @@ async function runHardened(opts) {
                     onAbort = () => reject(new WorkflowScriptError("hardened-vm aborted"));
                     signal.addEventListener("abort", onAbort, { once: true });
                 }
+                // Diagnosis-first message: it reaches the model via failureSummary (bounded), so the self-correction
+                // hint has to be up front.
                 fireDeadlock = () => reject(new WorkflowScriptError("script deadlocked: no host call (agent/phase) in flight and nothing can resume the script — usually an un-awaited promise cycle, e.g. `const r = phase(...)` without await whose body reads `r`."));
             }),
         ]);
+        // hand the host PLAIN sterilized data, never a live cross-realm object (getter/toJSON/then traps) and
+        // never a slipped-in __proto__ (return-path tampering).
         return marshalOut(result);
     }
     catch (err) {
+        // Live dogfood catch 2026-07-03 ( `setTimeout` blew up as a bare "workflow failed"): a RUNTIME script-realm
+        // rejection (ReferenceError, an uncaught script throw, a bridged agent() error the script didn't catch) used
+        // to propagate UN-typed — `failureSummary` only surfaces the message for `workflow.*`-coded errors, so the model/
+        // operator got zero diagnosis. Wrap it as `workflow.script_error`; core's failureSummary already bounds (200
+        // chars) + `redactHostLeaks`-redacts the message before it reaches the notification, so a bridged host error
+        // message is safe to carry here.
         if (err instanceof WorkflowScriptError)
-            throw err;
+            throw err; // compile/timeout/abort/marshal — already typed
         throw new WorkflowScriptError(`script failed at runtime: ${err instanceof Error ? err.message : String(err)}`);
     }
     finally {
@@ -170,6 +240,23 @@ async function runHardened(opts) {
             signal.removeEventListener("abort", onAbort);
     }
 }
+/**
+ * phases=[] ROOT CAUSE + fix — the SCOPED-PHASE GATE. The old in-context `phase` was pure sugar
+ * (log a "◆ phase" line, run the body) that NEVER called the host `primitives.phase`, so core recorded ZERO
+ * phase state: terminal rows had `phases: []` and agents carried no `phase` key (exactly the storage-row
+ * autopsy — agents fine, phase accounting gone). The membrane's JSON bridge cannot carry the script's BODY
+ * function across, so the bridge is split into three JSON-safe host calls, and the body stays IN-CONTEXT:
+ *   - `mark(title)`  → `primitives.phase(title, undefined)` (core's bare CC-marker path);
+ *   - `enter(title)` → opens core's scoped phase with a DEFERRED body (`await gate`), returns a numeric token.
+ *     core pushes the phase record + sets `currentPhase` SYNCHRONOUSLY before its first await, so by the time
+ *     `enter` returns, `agent()` calls made inside the VM body land with the right phase label;
+ *   - `exit(token, ok, err?)` → releases the gate (ok → core closes the phase `completed`; !ok → the deferred
+ *     body throws and core closes it `failed`), then awaits core's settle so the close is persisted before the
+ *     VM continues.
+ * A finalized-run `phase()` (core throws) surfaces on `enter` via the settled-race; an unknown/double `exit`
+ * is idempotent. The VM wrapper rethrows the body's own error — the gate's synthetic error never reaches the
+ * script.
+ */
 export function scopedPhaseGate(phase) {
     let seq = 0;
     const open = new Map();
@@ -182,7 +269,9 @@ export function scopedPhaseGate(phase) {
                 if (!r.ok)
                     throw new Error(r.err ?? "phase body failed");
             }));
-            settled.catch(() => undefined);
+            settled.catch(() => undefined); // the VM path rethrows the body's own error — never an unhandled rejection here
+            // Surface an IMMEDIATE rejection (core's finalized guard rejects before its first await settles) while a
+            // healthy still-pending phase resolves the race via the resolved sentinel.
             await Promise.race([settled, Promise.resolve()]);
             const token = ++seq;
             open.set(token, { release, settled });
@@ -191,13 +280,19 @@ export function scopedPhaseGate(phase) {
         async exit(token, ok, err) {
             const o = open.get(token);
             if (!o)
-                return;
+                return; // unknown/double exit — idempotent
             open.delete(token);
             o.release({ ok, ...(err !== undefined ? { err } : {}) });
-            await o.settled.catch(() => undefined);
+            await o.settled.catch(() => undefined); // core closed + persisted the phase before the VM continues
         },
     };
 }
+/** Build the orchestration context-local globals (agent/parallel/pipeline/phase/log/budget/args) from the
+ *  host {@link WorkflowPrimitives}. agent/log/phase are host-bridged (phase via the three-verb
+ *  {@link scopedPhaseGate} — the body function itself never crosses the membrane); parallel/pipeline are
+ *  in-context sugar; budget is a frozen null-proto object over host accessors.
+ *  Exported so the worker-isolated runner (hardened-vm-worker.ts) reuses the EXACT same surface with
+ *  IPC-backed primitives — one definition of the orchestration globals, no drift. */
 export function orchestrationGlobals(primitives, scriptArgs, limits = {}) {
     const cfg = { ...DEFAULTS, ...limits };
     return (m) => {
@@ -222,6 +317,8 @@ export function orchestrationGlobals(primitives, scriptArgs, limits = {}) {
            await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
            return out;
          })`)(cfg.concurrency);
+        // Phase-gate fix: REAL phase bridging via the three-verb gate (see scopedPhaseGate) — the old in-context sugar
+        // never told core a phase existed (phases:[] / label-less agents in every hardened-runner deployment).
         const gate = scopedPhaseGate((t, b) => primitives.phase(t, b));
         const phaseMark = m.bridge(async (title) => void (await primitives.phase(String(title), undefined)));
         const phaseEnter = m.bridge(async (title) => gate.enter(String(title)));
@@ -235,6 +332,9 @@ export function orchestrationGlobals(primitives, scriptArgs, limits = {}) {
         return { agent, parallel, pipeline, phase, log, budget, args: m.dataIn(scriptArgs) };
     };
 }
+/** Build the hardened-vm S8 `WorkflowScriptRunner` (TOC+TOB workflow orchestration). `safeForUntrustedScripts`
+ *  is `true` — it has passed the conformance battery + robustness suite; the S8 gate mounts `run_workflow` only for
+ *  a runner that asserts this. */
 export function createHardenedVmRunner(limits = {}) {
     const cfg = { ...DEFAULTS, ...limits };
     return {
@@ -247,10 +347,25 @@ export function createHardenedVmRunner(limits = {}) {
                 ...(signal ? { signal } : {}),
                 buildGlobals: orchestrationGlobals(primitives, scriptArgs, cfg),
             });
+            // `meta` is core-parsed (AST, not eval) but its values are LLM-controlled — sterilize it too.
             return { result, meta: marshalOut(meta) };
         },
     };
 }
+/**
+ * General untrusted-code exec on the SAME hardened membrane — the TOC ephemeral execution sandbox. Runs
+ * `code` (an async function body that may `return`) with ONLY the safe built-ins plus whatever host
+ * capabilities the caller bridges via `bindings` (each MUST go through `m.bridge` / `m.dataIn` — never a raw
+ * host reference). Returns the marshalled (plain, sterilized) result. With no `bindings`, the code is pure
+ * computation (no host reach at all).
+ *
+ * @example
+ *   const out = await runInHardenedVm({
+ *     code: "return await fetchJson(args.url)",
+ *     bindings: (m) => ({ fetchJson: m.bridge((u) => safeFetch(String(u))), args: m.dataIn({ url }) }),
+ *     limits: { totalTimeoutMs: 5000 },
+ *   });
+ */
 export async function runInHardenedVm(opts) {
     return runHardened({
         body: opts.code,

package/dist/orchestration/hardened-vm-worker-runner.d.ts

@@ -1,4 +1,18 @@
 import { type WorkflowScriptRunner } from "@sema-agent/core";
 import { type HardenedVmLimits } from "./hardened-vm-runner.js";
+/**
+ * Worker-isolated S8 hard runner (design/98 v2). Runs the hardened-vm membrane inside a `worker_thread`, adding
+ * RESOURCE isolation on top of the in-process {@link import("./hardened-vm-runner.js").createHardenedVmRunner}'s
+ * BOUNDARY isolation:
+ *   - HEAP cap (`resourceLimits.maxOldGenerationSizeMb`): a runaway-allocation script OOMs the WORKER (an `error`
+ *     event), never the shared main process — closes the in-process resource-exhaustion gap.
+ *   - `terminate()` on wall-clock timeout / abort: kills a MICROTASK-starvation loop (`while(true){await null}`)
+ *     the in-process wall-clock race cannot pre-empt (it starves its own event loop).
+ *   - credential isolation: the worker gets only the script + args; `agent`/`log` IPC to the main thread (which
+ *     holds the real Runner/DB/keys); a (validated-impossible) boundary crossing lands in a credential-free isolate.
+ *
+ * `safeForUntrustedScripts: true` — the membrane it runs is the conformance-validated + robustness-tested one. Use
+ * this (over the in-process runner) for genuinely-untrusted multi-tenant scripts where resource isolation matters.
+ */
 export declare function createWorkerHardenedVmRunner(limits?: HardenedVmLimits): WorkflowScriptRunner;
 //# sourceMappingURL=hardened-vm-worker-runner.d.ts.map

package/dist/orchestration/hardened-vm-worker-runner.js

@@ -2,9 +2,26 @@ import { Worker } from "node:worker_threads";
 import { WorkflowScriptError } from "@sema-agent/core";
 import { scopedPhaseGate } from "./hardened-vm-runner.js";
 const DEFAULTS = { totalTimeoutMs: 600_000, syncTimeoutMs: 5_000, maxAgents: 1000, concurrency: 12, maxHeapMb: 128 };
+// Resolve the worker bootstrap next to this module. In a tsc build it's the sibling `.js`; under vitest/tsx
+// (this module's URL ends in `.ts`) point at the `.ts` and register tsx as the worker's loader so the worker
+// can import TypeScript. Prod (node dist/) never needs tsx.
 const IS_TS = import.meta.url.endsWith(".ts");
 const WORKER_URL = new URL(IS_TS ? "./hardened-vm-worker.ts" : "./hardened-vm-worker.js", import.meta.url);
 const WORKER_EXEC_ARGV = IS_TS ? ["--import", "tsx/esm"] : undefined;
+/**
+ * Worker-isolated S8 hard runner (design/98 v2). Runs the hardened-vm membrane inside a `worker_thread`, adding
+ * RESOURCE isolation on top of the in-process {@link import("./hardened-vm-runner.js").createHardenedVmRunner}'s
+ * BOUNDARY isolation:
+ *   - HEAP cap (`resourceLimits.maxOldGenerationSizeMb`): a runaway-allocation script OOMs the WORKER (an `error`
+ *     event), never the shared main process — closes the in-process resource-exhaustion gap.
+ *   - `terminate()` on wall-clock timeout / abort: kills a MICROTASK-starvation loop (`while(true){await null}`)
+ *     the in-process wall-clock race cannot pre-empt (it starves its own event loop).
+ *   - credential isolation: the worker gets only the script + args; `agent`/`log` IPC to the main thread (which
+ *     holds the real Runner/DB/keys); a (validated-impossible) boundary crossing lands in a credential-free isolate.
+ *
+ * `safeForUntrustedScripts: true` — the membrane it runs is the conformance-validated + robustness-tested one. Use
+ * this (over the in-process runner) for genuinely-untrusted multi-tenant scripts where resource isolation matters.
+ */
 export function createWorkerHardenedVmRunner(limits = {}) {
     const cfg = { ...DEFAULTS, ...limits };
     return {
@@ -14,6 +31,8 @@ export function createWorkerHardenedVmRunner(limits = {}) {
                 return Promise.reject(new WorkflowScriptError("worker hardened-vm aborted before start"));
             return new Promise((resolve, reject) => {
                 const worker = new Worker(WORKER_URL, {
+                    // budgetSpent seeds the worker's cache with the CURRENT spend (core 1.238 wiring battery caught the
+                    // cold-start gap: a cache seeded 0 made remaining() read total until the first agent reply refreshed it).
                     workerData: { scriptSource, scriptArgs, limits: cfg, budgetTotal: primitives.budget.total, budgetSpent: primitives.budget.spent() },
                     resourceLimits: { maxOldGenerationSizeMb: cfg.maxHeapMb },
                     ...(WORKER_EXEC_ARGV ? { execArgv: WORKER_EXEC_ARGV } : {}),
@@ -26,7 +45,7 @@ export function createWorkerHardenedVmRunner(limits = {}) {
                         clearTimeout(timer);
                     if (signal)
                         signal.removeEventListener("abort", onAbort);
-                    void worker.terminate();
+                    void worker.terminate(); // hard-stops a starved/runaway worker; no-op if it already exited
                 };
                 const finish = (settle) => {
                     if (settled)
@@ -35,10 +54,15 @@ export function createWorkerHardenedVmRunner(limits = {}) {
                     cleanup();
                     settle();
                 };
+                // Wall-clock backstop (terminate). Grace over the in-worker totalTimeoutMs so the worker's CLEAN error
+                // (stuck host primitive) wins normally; terminate is the backstop for microtask-starvation.
                 timer = setTimeout(() => finish(() => reject(new WorkflowScriptError(`worker hardened-vm exceeded totalTimeoutMs (${cfg.totalTimeoutMs})`))), cfg.totalTimeoutMs + 1500);
                 timer.unref?.();
                 if (signal)
                     signal.addEventListener("abort", onAbort, { once: true });
+                // Phase-gate fix: the worker's phase IPC verbs land on the REAL primitives.phase via the same three-verb gate
+                // the in-process runner uses (the body function stays in the worker; only mark/enter/exit cross). Replies
+                // reuse the worker's id-keyed "agentResult" resolver (same shape — no second pending map in the worker).
                 const phaseGate = scopedPhaseGate((t, b) => primitives.phase(t, b));
                 const reply = (id, p) => void p.then((value) => worker.postMessage({ type: "agentResult", id, ok: true, value: value ?? null, budgetSpent: primitives.budget.spent() }), (e) => worker.postMessage({ type: "agentResult", id, ok: false, error: e instanceof Error ? e.message : String(e), name: e instanceof Error ? e.name : "Error", budgetSpent: primitives.budget.spent() }));
                 worker.on("message", (msg) => {
@@ -67,6 +91,7 @@ export function createWorkerHardenedVmRunner(limits = {}) {
                         finish(() => reject(new WorkflowScriptError(msg.message ?? "worker hardened-vm script failed")));
                     }
                 });
+                // An `error` event = an UNCAUGHT worker exception, most often the heap-cap OOM ("Reached heap limit").
                 worker.on("error", (err) => finish(() => reject(new WorkflowScriptError(`worker hardened-vm crashed (likely heap/OOM): ${err.message}`))));
                 worker.on("exit", (code) => {
                     if (!settled)

package/dist/orchestration/hardened-vm-worker.js

@@ -1,13 +1,30 @@
+/**
+ * S8 hardened-vm WORKER bootstrap (design/98 v2 resource isolation). Runs inside a `worker_thread` spawned by
+ * {@link import("./hardened-vm-worker-runner.js").createWorkerHardenedVmRunner}. The SAME hardened-vm membrane
+ * ({@link runInHardenedVm} + {@link orchestrationGlobals}) executes the untrusted script HERE — so on top of
+ * the membrane's BOUNDARY isolation we get the worker's RESOURCE isolation: a separate V8 isolate + heap (capped
+ * by `resourceLimits.maxOldGenerationSizeMb` → a memory bomb OOMs the WORKER, not the shared main process) and
+ * `terminate()` (the main thread kills a microtask-starvation / runaway loop the in-process wall-clock cannot).
+ *
+ * The worker holds NO credentials: `agent`/`log` are STUBS that IPC to the main thread (which runs the real
+ * primitives with the real Runner/DB/model keys); `budget` reads a worker-local cache the main thread refreshes
+ * on each agent reply. So even a (validated-impossible) membrane boundary crossing lands in a credential-free isolate.
+ */
 import { parentPort, workerData } from "node:worker_threads";
 import { splitWorkflowMeta } from "@sema-agent/core";
+// Resolve the sibling membrane module with an EXPLICIT extension so it loads under both a tsc build (`.js`) and
+// tsx (`.ts`) — tsx does not map a `.js` specifier to `.ts` for a worker's static import. The template literal
+// keeps tsc from rejecting a literal `.ts` specifier; the cast restores the types.
 const ext = import.meta.url.endsWith(".ts") ? "ts" : "js";
 const { runInHardenedVm, orchestrationGlobals } = (await import(`./hardened-vm-runner.${ext}`));
 const port = parentPort;
 if (!port)
     throw new Error("hardened-vm-worker must run inside a worker_thread");
 const input = workerData;
+// agent: async IPC (request/response keyed by id) to the main thread's real primitive.
 let nextId = 0;
 const pending = new Map();
+// budget: worker-local cache the main thread refreshes (piggybacked on every agentResult).
 const budgetCache = { total: input.budgetTotal, spent: input.budgetSpent ?? 0 };
 port.on("message", (msg) => {
     if (msg.type !== "agentResult" || msg.id === undefined)
@@ -26,6 +43,8 @@ port.on("message", (msg) => {
         p.rej(e);
     }
 });
+// IPC-backed WorkflowPrimitives handed to orchestrationGlobals — agent/log/phase cross to the main thread;
+// budget is the live cache; parallel/pipeline are built in-context by orchestrationGlobals.
 const ipcCall = (type, extra) => new Promise((res, rej) => {
     const id = nextId++;
     pending.set(id, { res, rej });
@@ -39,8 +58,14 @@ const ipcPrimitives = {
         spent: () => budgetCache.spent,
         remaining: () => (budgetCache.total === null ? Infinity : budgetCache.total - budgetCache.spent),
     },
+    // never invoked (orchestrationGlobals builds parallel/pipeline in-context), but required by the type.
     parallel: async () => [],
     pipeline: async () => [],
+    // Phase-gate fix: phase accounting must reach the MAIN thread's real primitives (the old stub ran the body and told
+    // core nothing — phases:[] on every worker-isolated run). The body function cannot cross the IPC boundary, so
+    // the same three-verb protocol as the in-process gate: mark (bare) / enter→token / exit(token, ok, err).
+    // orchestrationGlobals' own gate wraps THIS phase — its deferred body resolves when the in-VM body settles,
+    // which chains 1:1 onto these IPC verbs (enter here ⇒ the main-side gate's enter; exit ⇒ its exit).
     phase: async (t, b) => {
         if (b === undefined) {
             await ipcCall("phaseMark", { title: String(t) });
@@ -57,6 +82,7 @@ const ipcPrimitives = {
                 await ipcCall("phaseExit", { token, ok: false, err: e instanceof Error ? e.message : String(e) });
             }
             catch {
+                /* exit is best-effort — the body's own error wins */
             }
             throw e;
         }
@@ -70,6 +96,7 @@ void (async () => {
             bindings: orchestrationGlobals(ipcPrimitives, input.scriptArgs, input.limits),
             limits: input.limits,
         });
+        // meta is core-parsed; JSON round-trip strips any slipped-in gadget before it crosses back via structuredClone.
         const safeMeta = JSON.parse(JSON.stringify(meta));
         port.postMessage({ type: "done", result, meta: safeMeta });
     }

package/dist/orchestration/subagent-steer.d.ts

@@ -1,12 +1,56 @@
 import type { SubagentSteerHandle } from "@sema-agent/core";
+/**
+ * C2 (core 1.219) + design/122 (core 1.225) — the SERVICE-side registry for
+ * STEERING and RESUMING a Task SUB-AGENT (a sync delegation spawned by the `Agent` tool), the sibling of
+ * {@link import("./workflow-agent-steer.js").WorkflowAgentRegistry} for workflow agents.
+ *
+ * core emits a {@link SubagentSteerHandle} to the deployment's `RunInternals.onSubagentSpawn` sink the
+ * moment a SYNC child spawns (the handle NEVER reaches the model). The service registers it under the
+ * PARENT RUN's taskId so `POST /v1/runs/:runId/subagents/:target/{steer,resume}` can route into it.
+ * Delivery is replica-local (the handle is an in-memory bridge, like `steerableRuns`); a cross-replica
+ * steer/resume is an honest 409, never a silent drop.
+ *
+ * 🔴 LIFECYCLE (design/122 item ③ — the "不改必踩" change): handles are NO LONGER evicted on child settle.
+ * `resume` is only legal AFTER the child settled (core rejects `steering.still_running` before), so a
+ * settle-evicted registry would make resume structurally unreachable. Instead:
+ *   - one handle PER parentToolCallId, NEWEST WINS (core D2: each resume re-emits a FRESH handle under the
+ *     same id whose `settled` tracks the revived run — `Map.set` replace is exactly that contract);
+ *   - handles live until the OWNING LEG ends (each run leg collects its `register()` unregister thunks and
+ *     runs them in its finally — identity-guarded, so a suspend→fast-resume sibling leg's fresh handles are
+ *     never clobbered by the old leg's teardown, mirroring the `steerableRuns` identity guard);
+ *   - a per-run cap (oldest-evicted) bounds the map for a delegation-heavy parent (handles now outlive
+ *     settle, so an unbounded list would grow for the whole run).
+ * After the parent run ends core disposes the retain ledger anyway (abort in-flight resumes + release all),
+ * so a post-teardown resume would only ever 409 — the eviction just keeps the map honest.
+ *
+ * Addressing: `target` matches `parentToolCallId` FIRST (spawn-time identity, unique per delegation), then
+ * falls back to `agentName` (display name; two children of the same agent type collide → the route 409s
+ * rather than steering/resuming an arbitrary sibling). Steer-in redaction is shared with the workflow route
+ * (`redactSteerIn`) — one owner of the trust gate. 🔐 `handle.childSessionId` is a continuation
+ * CAPABILITY: control-plane only — no route response may include it.
+ *
+ * SCOPE (core r1-M3): only SYNC delegations emit a handle — `run_in_background` children have neither steer
+ * nor resume (poll/stop via TaskOutput/TaskStop; durable bg revival is a separate core item).
+ */
+/** Per-run handle cap — handles now live until the leg ends (not settle), so bound the map. Oldest-evicted;
+ *  256 mirrors the ToolDetachHub bound (a run with >256 live-or-resumable delegations is pathological). */
 export declare const SUBAGENT_HANDLES_PER_RUN_CAP = 256;
 export declare class SubagentSteerRegistry {
+    /** parent run taskId → (parentToolCallId → NEWEST handle). Map iteration order = insertion = age. */
     private readonly byRun;
+    /** Register a child handle under its parent run. SAME parentToolCallId replaces (core D2: a resume
+     *  re-emits a fresh handle for the revived run — newest wins). Returns an IDENTITY-GUARDED unregister
+     *  thunk: it removes the entry only while it still holds THIS handle (a fresh sibling-leg registration
+     *  under the same id survives the old leg's teardown). Call it at LEG END, not on settle (design/122 ③). */
     register(runId: string, handle: SubagentSteerHandle): () => void;
+    /** Resolve `runId` + `target` to its handle on this replica. Exact `parentToolCallId` match wins (unique —
+     *  newest-per-id by construction → count is 0|1); otherwise match by `agentName` (count may be >1 →
+     *  ambiguous, `handle` undefined → the route 409s). count=0 → no such child here. */
     resolve(runId: string, target: string): {
         handle?: SubagentSteerHandle;
         count: number;
     };
+    /** Total registered handles (test/observability). */
     get size(): number;
 }
 //# sourceMappingURL=subagent-steer.d.ts.map

package/dist/orchestration/subagent-steer.js

@@ -1,13 +1,53 @@
+/**
+ * C2 (core 1.219) + design/122 (core 1.225) — the SERVICE-side registry for
+ * STEERING and RESUMING a Task SUB-AGENT (a sync delegation spawned by the `Agent` tool), the sibling of
+ * {@link import("./workflow-agent-steer.js").WorkflowAgentRegistry} for workflow agents.
+ *
+ * core emits a {@link SubagentSteerHandle} to the deployment's `RunInternals.onSubagentSpawn` sink the
+ * moment a SYNC child spawns (the handle NEVER reaches the model). The service registers it under the
+ * PARENT RUN's taskId so `POST /v1/runs/:runId/subagents/:target/{steer,resume}` can route into it.
+ * Delivery is replica-local (the handle is an in-memory bridge, like `steerableRuns`); a cross-replica
+ * steer/resume is an honest 409, never a silent drop.
+ *
+ * 🔴 LIFECYCLE (design/122 item ③ — the "不改必踩" change): handles are NO LONGER evicted on child settle.
+ * `resume` is only legal AFTER the child settled (core rejects `steering.still_running` before), so a
+ * settle-evicted registry would make resume structurally unreachable. Instead:
+ *   - one handle PER parentToolCallId, NEWEST WINS (core D2: each resume re-emits a FRESH handle under the
+ *     same id whose `settled` tracks the revived run — `Map.set` replace is exactly that contract);
+ *   - handles live until the OWNING LEG ends (each run leg collects its `register()` unregister thunks and
+ *     runs them in its finally — identity-guarded, so a suspend→fast-resume sibling leg's fresh handles are
+ *     never clobbered by the old leg's teardown, mirroring the `steerableRuns` identity guard);
+ *   - a per-run cap (oldest-evicted) bounds the map for a delegation-heavy parent (handles now outlive
+ *     settle, so an unbounded list would grow for the whole run).
+ * After the parent run ends core disposes the retain ledger anyway (abort in-flight resumes + release all),
+ * so a post-teardown resume would only ever 409 — the eviction just keeps the map honest.
+ *
+ * Addressing: `target` matches `parentToolCallId` FIRST (spawn-time identity, unique per delegation), then
+ * falls back to `agentName` (display name; two children of the same agent type collide → the route 409s
+ * rather than steering/resuming an arbitrary sibling). Steer-in redaction is shared with the workflow route
+ * (`redactSteerIn`) — one owner of the trust gate. 🔐 `handle.childSessionId` is a continuation
+ * CAPABILITY: control-plane only — no route response may include it.
+ *
+ * SCOPE (core r1-M3): only SYNC delegations emit a handle — `run_in_background` children have neither steer
+ * nor resume (poll/stop via TaskOutput/TaskStop; durable bg revival is a separate core item).
+ */
+/** Per-run handle cap — handles now live until the leg ends (not settle), so bound the map. Oldest-evicted;
+ *  256 mirrors the ToolDetachHub bound (a run with >256 live-or-resumable delegations is pathological). */
 export const SUBAGENT_HANDLES_PER_RUN_CAP = 256;
 export class SubagentSteerRegistry {
+    /** parent run taskId → (parentToolCallId → NEWEST handle). Map iteration order = insertion = age. */
     byRun = new Map();
+    /** Register a child handle under its parent run. SAME parentToolCallId replaces (core D2: a resume
+     *  re-emits a fresh handle for the revived run — newest wins). Returns an IDENTITY-GUARDED unregister
+     *  thunk: it removes the entry only while it still holds THIS handle (a fresh sibling-leg registration
+     *  under the same id survives the old leg's teardown). Call it at LEG END, not on settle (design/122 ③). */
     register(runId, handle) {
         let handles = this.byRun.get(runId);
         if (!handles) {
             handles = new Map();
             this.byRun.set(runId, handles);
         }
-        handles.delete(handle.parentToolCallId);
+        handles.delete(handle.parentToolCallId); // re-insert → moves to newest position (age = last registration)
         handles.set(handle.parentToolCallId, handle);
         if (handles.size > SUBAGENT_HANDLES_PER_RUN_CAP) {
             const oldest = handles.keys().next().value;
@@ -25,6 +65,9 @@ export class SubagentSteerRegistry {
             }
         };
     }
+    /** Resolve `runId` + `target` to its handle on this replica. Exact `parentToolCallId` match wins (unique —
+     *  newest-per-id by construction → count is 0|1); otherwise match by `agentName` (count may be >1 →
+     *  ambiguous, `handle` undefined → the route 409s). count=0 → no such child here. */
     resolve(runId, target) {
         const handles = this.byRun.get(runId);
         if (!handles || handles.size === 0)
@@ -35,6 +78,7 @@ export class SubagentSteerRegistry {
         const byName = [...handles.values()].filter((h) => h.agentName === target);
         return byName.length === 1 ? { handle: byName[0], count: 1 } : { count: byName.length };
     }
+    /** Total registered handles (test/observability). */
     get size() {
         let n = 0;
         for (const handles of this.byRun.values())

package/dist/orchestration/workflow-agent-steer.d.ts

@@ -1,15 +1,69 @@
 import { type WorkflowAgentHandle } from "@sema-agent/core";
+/** The result of resolving a steer target. core does NOT enforce label uniqueness within a run (a script may
+ *  spawn two steerable agents with the same explicit `label`), so a (runId,label) can address MORE THAN ONE live
+ *  agent — steering then has no well-defined target and must be refused, not sent to an arbitrary one. */
 export interface SteerResolution {
+    /** The live handle iff EXACTLY ONE matches; undefined when none (not here) or when ambiguous (>1). */
     handle?: WorkflowAgentHandle;
+    /** Live handles matching (0 = none on this replica, 1 = unique target, >1 = ambiguous → the route 409s). */
     count: number;
 }
+/** A process-local registry of the steerable workflow-agent handles live on THIS replica. Mirrors the
+ *  `steerableRuns` / `preemptableRuns` pattern (a live in-memory handle is replica-local — a cross-replica steer
+ *  is a structured 409, never a silent drop). Stores a LIST per (runId,label): core does not enforce label
+ *  uniqueness, so a duplicate-label collision must NOT silently last-writer-wins (that would steer the WRONG
+ *  agent + strand the sibling) — {@link resolve} reports the count so the route can 409-on-ambiguous instead. */
 export declare class WorkflowAgentRegistry {
     private readonly handles;
+    /** Register a handle when its `agentStream` starts on this replica. Returns an unregister thunk to call when
+     *  the agent settles (keeps the map from leaking). APPENDS (does not overwrite) so a duplicate-label sibling is
+     *  also tracked → {@link resolve} sees count>1 and the route refuses rather than steering an arbitrary one. */
     register(handle: WorkflowAgentHandle): () => void;
+    /** Resolve `runId`+`label` to its UNIQUE live handle on this replica. count=0 → not here (terminal /
+     *  cross-replica); count=1 → `handle` set; count>1 → ambiguous (`handle` undefined → the route 409s rather
+     *  than steering an arbitrary one of the colliding same-label agents). */
     resolve(runId: string, label: string): SteerResolution;
+    /** Total live handles (test/observability). */
     get size(): number;
 }
+/** Max steer-in length fed to a worker (chars). A steer is a short redirection, not a payload; core's
+ *  `untrustedEgressForHuman` bounds + truncates beyond this.
+ *
+ *  ⚠️ 纠正(2026-07-26,core 1.414 + 亲测):这里原本写的是「truncates with an **honest marker**」,现在只有
+ *  一半成立 —— 实测(`test/svc5-steer-live.test.ts` 里已钉):
+ *   · **「被截断过」仍有信号**:超界时正文段尾出现 `…`(未超界时不出现)⇒ 消费方能判断"这不是全文";
+ *   · **「截了多少」不再披露**:`[+N chars]` 在**所有**档位都没有了(实测 +1 / +10 / +100 / +5000 / +50000
+ *     全部无披露,输出长度恒 4103)。所以一个超出 5 万字符的输入与只超 1 个字符的输入,**外观完全相同**。
+ *  ⚠️ core [1707]⑤ 的措辞是「**刚过界**的输入现在是裸 `…` 结尾」,而实测是**全档位**都没有披露 —— 范围比
+ *  它描述的宽。已带实测数据上黑板问 core 这是否是有意的(可能只是描述省略,也可能是它没注意到)。
+ *  在得到答复前**不改行为**:core 的截断器是它那侧的安全件,server 不该自己在外面补一层"+N chars"去顶
+ *  ——那会变成两处各说一套。 */
 export declare const STEER_IN_MAX_CHARS = 4000;
+/**
+ * **入参**上限(与 {@link STEER_IN_MAX_CHARS} 是两件事:那个限的是**输出**,这个限的是**请求带进来的**)。
+ *
+ * ── 为什么需要它 ───────────────────────────────────────────────────────────────────────────────
+ * 脱敏门是**同步**函数,烧的是**事件循环** ⇒ 一次大 steer 卡住的是**整个副本**,不只是那个请求。
+ * 此前这里没有上限:`body.content` 只校验类型与非空,而 JSON 请求体上限是 8 MiB。
+ *
+ * ── 数是怎么定的(实测,不是拍的)────────────────────────────────────────────────────────────────
+ * core 1.421.0 起该函数对输入是**线性**的(此前对「最长不间断词字符段」二次,已修)。
+ * 本机实测最坏形状(纯词字符段):64 KiB ≈ 17ms ⇒ **256 KiB ≈ 68ms**、8 MiB ≈ 2.2s。
+ * ⇒ 取 **256 KiB**:最坏一拍 ~70ms(可接受的事件循环占用),而它是输出上限的 **64 倍** ——
+ *   任何正当的粘贴都装得下,而超出部分**本来就会被丢弃**(只保留 4000 字符 + 一个"丢了多少"的披露)。
+ *
+ * ── 为什么是**拒**而不是**服务端先截** ──────────────────────────────────────────────────────────
+ * 先截会让 core 的 `[+N chars]` 披露**低报**(N 会变成相对截断后输入的),
+ * 而"诚实标记不得低报"是本仓另一条钉守着的性质。**为一个已经不紧迫的成本去改一条正确性性质,不划算。**
+ * ⇒ 拒 + 在错误里说清上限,调用方自己决定发什么。
+ */
 export declare const STEER_IN_MAX_REQUEST_CHARS: number;
+/**
+ * The steer-in REDACTION gate (SVC-5 信任门). Treat the human/leader steer content as UNTRUSTED before it
+ * reaches the worker: redact host-internal leaks (URLs / tokens / named secrets / absolute paths), size-bound,
+ * and FENCE it so it can't pose as authority / forge a `</system-reminder>`. `label` tags the fenced block for
+ * the worker's reader. This is the service's half of the depth — `handle.steer` fences again inside its trusted
+ * marker framing.
+ */
 export declare function redactSteerIn(content: string, label: string): string;
 //# sourceMappingURL=workflow-agent-steer.d.ts.map