@sema-agent/server 1.322.0 → 2.0.0

package/dist/observability/prompt-manifest.d.ts

@@ -1,3 +1,8 @@
+/** The whitelisted projection of core's `prompt.assembled` trace event ([998]② web observability slice A:
+ *  the manifest reaches the durable run event log + turns/stream). Built FIELD-BY-FIELD at record time
+ *  (never a spread — the 1.72 task_progress lesson: a future core field must not ride the durable wire raw).
+ *  Carries ONLY ids/digests/counts by core's manifest contract (no prompt bodies; hashes are core-salted) —
+ *  so the projection legs have zero redact burden. */
 export interface PromptManifestRecord {
     constitution: string;
     blocks: Array<{
@@ -5,6 +10,8 @@ export interface PromptManifestRecord {
         chars: number;
         hash: string;
     }>;
+    /** `contentHash`(core 1.315 [1062]①):operator 声明 section 的**非盐化**对账锚(core 已对 text 校验
+     *  后透传)——盐化 `hash` 恒在旁;端到端对账链(center 发布→manifest)经本投影,必须透传不可吞。 */
     sections?: Array<{
         id: string;
         slot: string;
@@ -26,6 +33,8 @@ export interface PromptManifestRecord {
     }>;
     totalChars: number;
 }
+/** Whitelist one `prompt.assembled` trace event into a {@link PromptManifestRecord} (v1 face required,
+ *  v2 `sections`/`tools` additive — absent stays absent). */
 export declare function promptManifestRecordOf(e: {
     constitution: string;
     blocks: Array<{
@@ -54,6 +63,23 @@ export declare function promptManifestRecordOf(e: {
     }>;
     totalChars: number;
 }): PromptManifestRecord;
+/**
+ * [998]② per-task prompt-manifest accumulator — the `ModelUsageTracker`(budget.ts)pattern: the
+ * `prompt.assembled` tracer hook is SYNC/no-IO, so it cannot persist; it RECORDS here (registered
+ * top-level runs only — the same leak fence: sub-task manifests are never registered, never leak), and
+ * the durable run lifecycle DRAINS the pending records into `prompt_assembled` events. Two departures
+ * from the ModelUsage shape (release-review findings):
+ *  - The pending value is an ordered QUEUE, not a single slot: a cascade/verify leg re-prepares under
+ *    ONE taskId (core's runCascade passes the same spec taskId to every rung), and each prepare's
+ *    manifest must persist — latest-wins would hide the prompt actually used by earlier billed rungs.
+ *  - {@link register} returns a per-leg LEASE and {@link clear} requires it: after setSuspended makes
+ *    the row claimable, a fast sibling resume can re-register the same taskId before the parked leg's
+ *    finally runs (the codebase's documented B-3 window) — an unconditional clear there would silently
+ *    delete the NEW leg's registration/pending manifest. Identity-guarded like the sibling
+ *    inflight/steerable teardowns.
+ */
+/** [1301]③ — `config.assembled` 的白名单投影(core 1.346 trace:catalogVersion/fields[来源标注]/
+ *  overrideReasons)。fields 已是 core 精选的观测形(digest-free、有界);32KiB 罩防未来膨胀。 */
 export declare function configAssembledRecordOf(e: {
     catalogVersion?: unknown;
     fields?: unknown;
@@ -62,14 +88,25 @@ export declare function configAssembledRecordOf(e: {
 }): Record<string, unknown> | undefined;
 export declare class PromptManifestTracker {
     private readonly byTask;
+    /** [1301]③:config.assembled 的同生命周期伴随记录(register 同门、drainConfig 同拍)。队列形
+     *  (codex F2):cascade 每 rung 独立解析配置,后到覆盖会把先前已计费 rung 的生效配置抹掉——与
+     *  prompt manifests 同姿势逐条保序。 */
     private readonly configByTask;
     private readonly active;
     private leaseCounter;
+    /** Mark a TOP-LEVEL run active (same fence as `ModelUsageTracker.register`, budget.ts). Returns this leg's
+     *  lease — pass it to {@link clear} so only the CURRENT owner can tear the slot down. */
     register(taskId: string): number;
+    /** Queue this prepare's manifest — ONLY for a registered top-level run (else a no-op). Sync, never throws. */
     record(taskId: string, m: PromptManifestRecord): void;
+    /** [1301]③:队一条 config.assembled 投影(同 register 门;逐条保序——cascade 每 rung 各留其形)。 */
     recordConfig(taskId: string, rec: Record<string, unknown>): void;
+    /** Return-and-clear ALL pending config records in emission order; `undefined` when none. */
     drainConfig(taskId: string): Array<Record<string, unknown>> | undefined;
+    /** Return-and-clear ALL pending manifests in emission order; `undefined` when none. */
     drain(taskId: string): PromptManifestRecord[] | undefined;
+    /** Drop pending + unregister (run end / abandoned leg) — but ONLY while `lease` still owns the slot;
+     *  a stale leg's teardown after a fast re-register is a no-op (the new leg owns it now). */
     clear(taskId: string, lease: number): void;
 }
 //# sourceMappingURL=prompt-manifest.d.ts.map

package/dist/observability/prompt-manifest.js

@@ -1,3 +1,9 @@
+// design/158 N18: the prompt-manifest / config-assembled observability face moved VERBATIM out of budget.ts
+// (lens4 §4.1 — budget.ts's name says cost/budget, but this half is wire-observability projection of core's
+// `prompt.assembled`/`config.assembled` trace events, unrelated to spend). budget.ts re-exports all four for
+// compat (its own createTracer still consumes promptManifestRecordOf/configAssembledRecordOf/PromptManifestTracker).
+/** Whitelist one `prompt.assembled` trace event into a {@link PromptManifestRecord} (v1 face required,
+ *  v2 `sections`/`tools` additive — absent stays absent). */
 export function promptManifestRecordOf(e) {
     return {
         constitution: String(e.constitution),
@@ -11,6 +17,23 @@ export function promptManifestRecordOf(e) {
         totalChars: e.totalChars,
     };
 }
+/**
+ * [998]② per-task prompt-manifest accumulator — the `ModelUsageTracker`(budget.ts)pattern: the
+ * `prompt.assembled` tracer hook is SYNC/no-IO, so it cannot persist; it RECORDS here (registered
+ * top-level runs only — the same leak fence: sub-task manifests are never registered, never leak), and
+ * the durable run lifecycle DRAINS the pending records into `prompt_assembled` events. Two departures
+ * from the ModelUsage shape (release-review findings):
+ *  - The pending value is an ordered QUEUE, not a single slot: a cascade/verify leg re-prepares under
+ *    ONE taskId (core's runCascade passes the same spec taskId to every rung), and each prepare's
+ *    manifest must persist — latest-wins would hide the prompt actually used by earlier billed rungs.
+ *  - {@link register} returns a per-leg LEASE and {@link clear} requires it: after setSuspended makes
+ *    the row claimable, a fast sibling resume can re-register the same taskId before the parked leg's
+ *    finally runs (the codebase's documented B-3 window) — an unconditional clear there would silently
+ *    delete the NEW leg's registration/pending manifest. Identity-guarded like the sibling
+ *    inflight/steerable teardowns.
+ */
+/** [1301]③ — `config.assembled` 的白名单投影(core 1.346 trace:catalogVersion/fields[来源标注]/
+ *  overrideReasons)。fields 已是 core 精选的观测形(digest-free、有界);32KiB 罩防未来膨胀。 */
 export function configAssembledRecordOf(e) {
     const rec = {
         catalogVersion: e.catalogVersion,
@@ -20,7 +43,7 @@ export function configAssembledRecordOf(e) {
     };
     try {
         if (JSON.stringify(rec).length > 32_768)
-            return undefined;
+            return undefined; // bounded frame — oversize dropped, never truncated半形
     }
     catch {
         return undefined;
@@ -29,9 +52,14 @@ export function configAssembledRecordOf(e) {
 }
 export class PromptManifestTracker {
     byTask = new Map();
+    /** [1301]③:config.assembled 的同生命周期伴随记录(register 同门、drainConfig 同拍)。队列形
+     *  (codex F2):cascade 每 rung 独立解析配置,后到覆盖会把先前已计费 rung 的生效配置抹掉——与
+     *  prompt manifests 同姿势逐条保序。 */
     configByTask = new Map();
     active = new Map();
     leaseCounter = 0;
+    /** Mark a TOP-LEVEL run active (same fence as `ModelUsageTracker.register`, budget.ts). Returns this leg's
+     *  lease — pass it to {@link clear} so only the CURRENT owner can tear the slot down. */
     register(taskId) {
         if (!taskId)
             return 0;
@@ -39,6 +67,7 @@ export class PromptManifestTracker {
         this.active.set(taskId, lease);
         return lease;
     }
+    /** Queue this prepare's manifest — ONLY for a registered top-level run (else a no-op). Sync, never throws. */
     record(taskId, m) {
         if (!taskId || !this.active.has(taskId))
             return;
@@ -48,6 +77,7 @@ export class PromptManifestTracker {
         else
             this.byTask.set(taskId, [m]);
     }
+    /** [1301]③:队一条 config.assembled 投影(同 register 门;逐条保序——cascade 每 rung 各留其形)。 */
     recordConfig(taskId, rec) {
         if (!taskId || !this.active.has(taskId))
             return;
@@ -57,6 +87,7 @@ export class PromptManifestTracker {
         else
             this.configByTask.set(taskId, [rec]);
     }
+    /** Return-and-clear ALL pending config records in emission order; `undefined` when none. */
     drainConfig(taskId) {
         const q = this.configByTask.get(taskId);
         if (!q || q.length === 0)
@@ -64,6 +95,7 @@ export class PromptManifestTracker {
         this.configByTask.delete(taskId);
         return q;
     }
+    /** Return-and-clear ALL pending manifests in emission order; `undefined` when none. */
     drain(taskId) {
         const q = this.byTask.get(taskId);
         if (!q || q.length === 0)
@@ -71,6 +103,8 @@ export class PromptManifestTracker {
         this.byTask.delete(taskId);
         return q;
     }
+    /** Drop pending + unregister (run end / abandoned leg) — but ONLY while `lease` still owns the slot;
+     *  a stale leg's teardown after a fast re-register is a no-op (the new leg owns it now). */
     clear(taskId, lease) {
         if (this.active.get(taskId) !== lease)
             return;

package/dist/observability/rate-limit.d.ts

@@ -1,8 +1,17 @@
+/**
+ * Fixed-window rate limiter, keyed by principal (falls back to client IP).
+ *
+ * In-memory and per-instance: the effective global limit is `limit × #instances`. For a hard global
+ * cap, back this with a shared store (Redis); for protecting one instance from a hot caller this is
+ * enough. `limit <= 0` disables it.
+ */
 export interface RateDecision {
     allowed: boolean;
     retryAfterSec: number;
     remaining: number;
 }
+/** The surface the HTTP layer uses — satisfied by the in-memory {@link RateLimiter} (single replica)
+ *  and the cross-replica {@link import("../plugins/tidb-rate-limiter.js").TiDBRateLimiter}. */
 export interface RateGate {
     check(key: string): RateDecision;
     sweep(now?: number): void;
@@ -13,6 +22,7 @@ export declare class RateLimiter implements RateGate {
     private readonly windows;
     constructor(limit: number, windowMs?: number);
     check(key: string): RateDecision;
+    /** Drop expired windows (call periodically). */
     sweep(now?: number): void;
 }
 //# sourceMappingURL=rate-limit.d.ts.map

package/dist/observability/rate-limit.js

@@ -21,6 +21,7 @@ export class RateLimiter {
         }
         return { allowed: true, retryAfterSec: 0, remaining: this.limit - w.count };
     }
+    /** Drop expired windows (call periodically). */
     sweep(now = Date.now()) {
         for (const [k, w] of this.windows)
             if (w.resetAt <= now)

package/dist/observability/tool-trace.d.ts

@@ -1,6 +1,30 @@
 import type { Hooks } from "@sema-agent/core";
 import type { Logger } from "./logger.js";
 import type { Metrics } from "./metrics.js";
+/**
+ * ALWAYS-ON gate-deny meter (goal B4, 2026-07-08): `permission_denied_total{source}` — how often the
+ * adjudicate chain DENIES a tool call, by gate source. Deliberately SEPARATE from {@link createToolTracer}:
+ * the tracer is a default-OFF diagnostic (TOOL_TRACE=true), but deny frequency is an operational/security
+ * signal that must reach /metrics on every deployment — a spike in `source="policy"` means a task keeps
+ * asking for something the operator forbids; `source="safety"`/`"shellGate"` spikes flag risky-command
+ * pressure. main.ts composes this UNDER the tracer via composeHooks (both are void observers on the
+ * permissionDenied slot, which composeHooks double-runs deployment-first).
+ */
 export declare function createPermissionDeniedMeter(metrics: Pick<Metrics, "inc">): Hooks;
+/**
+ * prove-before-scale stopgap (design/50): a no-op observer hook that logs every tool call (pre + post)
+ * to the worker log — INCLUDING resumed legs that `GET /v1/runs/:id/events` does NOT surface (the
+ * streaming-resume observability gap, service[15] API request #2). Gated by `TOOL_TRACE=true`; OFF by
+ * default (no prod noise).
+ *
+ * Why: a durable-HITL-gated coding task that keeps re-suspending is ambiguous from /events alone —
+ * could be a model restart-on-resume loop (the SAME tool re-issued each resume) or slow legit iteration.
+ * The pre-hook logs `{tool, id, arg:{path,contentLen,…}}` per call, so grepping `tool_trace` reconstructs
+ * the full sequence: a repeated `write_file path=X contentLen=Y` across resumes ⇒ restart-loop;
+ * write X → write Y → bash ⇒ iteration.
+ *
+ * Pure observation: every hook returns `undefined`, so it never rewrites args, never gates, never alters
+ * the result (and per core's hooks invariant a hook's `allow` can't bypass the policy gate anyway).
+ */
 export declare function createToolTracer(logger: Logger): Hooks;
 //# sourceMappingURL=tool-trace.d.ts.map

package/dist/observability/tool-trace.js

@@ -1,5 +1,17 @@
 import { redactSecrets } from "../trace/redact.js";
+/** The gate sources core's `PermissionDeniedPayload.source` documents today. It is an OPEN enum by
+ *  contract (a future "timeout" etc. must not break consumers) — unknown values fold to "other" so the
+ *  Prometheus label set stays bounded no matter what core adds. */
 const KNOWN_DENY_SOURCES = new Set(["policy", "hook", "safety", "shellGate", "planMode"]);
+/**
+ * ALWAYS-ON gate-deny meter (goal B4, 2026-07-08): `permission_denied_total{source}` — how often the
+ * adjudicate chain DENIES a tool call, by gate source. Deliberately SEPARATE from {@link createToolTracer}:
+ * the tracer is a default-OFF diagnostic (TOOL_TRACE=true), but deny frequency is an operational/security
+ * signal that must reach /metrics on every deployment — a spike in `source="policy"` means a task keeps
+ * asking for something the operator forbids; `source="safety"`/`"shellGate"` spikes flag risky-command
+ * pressure. main.ts composes this UNDER the tracer via composeHooks (both are void observers on the
+ * permissionDenied slot, which composeHooks double-runs deployment-first).
+ */
 export function createPermissionDeniedMeter(metrics) {
     return {
         permissionDenied(payload) {
@@ -7,6 +19,21 @@ export function createPermissionDeniedMeter(metrics) {
         },
     };
 }
+/**
+ * prove-before-scale stopgap (design/50): a no-op observer hook that logs every tool call (pre + post)
+ * to the worker log — INCLUDING resumed legs that `GET /v1/runs/:id/events` does NOT surface (the
+ * streaming-resume observability gap, service[15] API request #2). Gated by `TOOL_TRACE=true`; OFF by
+ * default (no prod noise).
+ *
+ * Why: a durable-HITL-gated coding task that keeps re-suspending is ambiguous from /events alone —
+ * could be a model restart-on-resume loop (the SAME tool re-issued each resume) or slow legit iteration.
+ * The pre-hook logs `{tool, id, arg:{path,contentLen,…}}` per call, so grepping `tool_trace` reconstructs
+ * the full sequence: a repeated `write_file path=X contentLen=Y` across resumes ⇒ restart-loop;
+ * write X → write Y → bash ⇒ iteration.
+ *
+ * Pure observation: every hook returns `undefined`, so it never rewrites args, never gates, never alters
+ * the result (and per core's hooks invariant a hook's `allow` can't bypass the policy gate anyway).
+ */
 export function createToolTracer(logger) {
     return {
         preToolUse(toolName, input, ctx) {
@@ -23,6 +50,10 @@ export function createToolTracer(logger) {
             });
             return undefined;
         },
+        // core 1.252 (design/134) BREAKING: postToolUse and postToolUseFailure are MUTUALLY EXCLUSIVE — an
+        // isError result now fires ONLY this callback. Without it, every failed tool call silently vanished
+        // from the trace (the exact silent-fallback class this log exists to catch). Same line shape as the
+        // success path (phase "post", isError true) so existing `tool_trace` grep workflows keep working.
         postToolUseFailure(toolName, _input, failure, ctx) {
             logger.info("tool_trace", {
                 phase: "post",
@@ -35,6 +66,11 @@ export function createToolTracer(logger) {
             });
             return undefined;
         },
+        // core 1.257: the gate's DENY short-circuit never reaches postToolUse* (the call
+        // doesn't execute), so denied calls were INVISIBLE to this trace — the exact observability hole
+        // asked about. `source` = core's adjudicate-chain enum (policy/hook/safety/shellGate/planMode); the
+        // deny `reason` can quote the adjudicated args (an approver's text, a policy message), so redact+clip
+        // like every other line. Same `tool_trace` key so existing grep workflows see denies in sequence.
         permissionDenied(payload) {
             logger.info("tool_trace", {
                 phase: "denied",
@@ -47,11 +83,15 @@ export function createToolTracer(logger) {
         },
     };
 }
+/** Compact, restart-diagnosable summary: key path/command fields + content length (not full content). */
 function summarize(input) {
     if (!input || typeof input !== "object")
         return { v: clip(String(input), 120) };
     const o = input;
     const s = {};
+    // Redact secrets BEFORE clipping: a traced `command`/`old_string` (e.g. `curl -H "Authorization: Bearer …"`,
+    // an edited .env line) can carry credentials into the worker log → its aggregation pipeline. TOOL_TRACE is a
+    // default-off diagnostic, but 120 chars is enough to hold a full token, so mask it.
     for (const k of ["path", "file_path", "command", "cmd", "pattern", "glob", "old_string", "new_string"]) {
         if (typeof o[k] === "string")
             s[k] = clip(redactSecrets(o[k]), 120);
@@ -65,7 +105,7 @@ function textOf(content) {
         .map((c) => (c && typeof c === "object" && typeof c.text === "string" ? c.text : ""))
         .join("")
         .trim();
-    return clip(redactSecrets(text), 200);
+    return clip(redactSecrets(text), 200); // tool output can echo a cat'd secret/credential — mask before logging
 }
 function clip(s, n) {
     return s.length > n ? `${s.slice(0, n)}…(${s.length})` : s;

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

@@ -1,24 +1,131 @@
 import { type WorkflowScriptRunner, type WorkflowPrimitives } from "@sema-agent/core";
+/**
+ * Hardened Node `vm` MEMBRANE for executing UNTRUSTED (LLM-authored / user-supplied) JavaScript, ported from
+ * the reference shell-host implementation's workflow sandbox and validated against core's
+ * `assertWorkflowSandboxConformance` battery + a beyond-battery boundary probe set + a 7-lens robustness suite
+ * (s8-sandbox-robustness: ctor/proto · error/stack · async/iter · reflect/proxy/symbol · marshal-bridge ·
+ * determinism · closure/cap). Two surfaces share ONE core ({@link runHardened}) so there is a single place to
+ * audit/fix:
+ *   - {@link createHardenedVmRunner} — the S8 `WorkflowScriptRunner` (TOC+TOB workflow orchestration).
+ *   - {@link runInHardenedVm}        — general untrusted-code exec (TOC ephemeral execution sandbox).
+ *
+ * 🔴 Why a plain `vm` is NOT a boundary (and what makes THIS one):
+ *   core's `devWorkflowScriptRunner` passes host primitives DIRECTLY into the context, so
+ *   `agent.constructor.constructor("return process")()` reaches the HOST `Function` (host realm = code-gen
+ *   unrestricted) → boundary crossing. The membrane closes that:
+ *     1. `createContext({__proto__:null}, {codeGeneration:{strings:false,wasm:false}})` — null-proto global,
+ *        no eval / new Function / wasm INSIDE the context.
+ *     2. EVERY value the script touches is CONTEXT-LOCAL — each binding is re-wrapped by a function COMPILED
+ *        IN THE CONTEXT (its `.constructor.constructor` is the context's inert `Function`); a raw host
+ *        function/object/error NEVER reaches the script.
+ *     3. Data crossing INTO the script (args, bridged results) is marshalled context-local via JSON-in-context.
+ *     4. ERRORS from host fns are marshalled to a CONTEXT-LOCAL `Error` (the beyond-battery leak core's
+ *        battery misses).
+ *     5. Data crossing INTO a host fn (bridged args) and OUT to the host caller (the result + meta) is
+ *        sterilized of the `__proto__`/`constructor`/`prototype` tampering gadget ({@link scrubProtoDeep}) —
+ *        the marshal-bridge boundary-crossing case — and marshalled to plain data (never a live cross-realm object
+ *        carrying getter/toJSON/then traps).
+ *
+ * 🔴 SCOPE (v1, clay 2026-06-23): this is BOUNDARY isolation (no host-code readout / unintended host execution / cross-tenant credential
+ *   reach / host prototype tampering) — VALIDATED. It is NOT full RESOURCE isolation: an in-process `vm`
+ *   cannot hard-cap heap, so a runaway-allocation script can OOM the shared process (a resource-exhaustion issue, NOT a data-boundary issue). v1
+ *   mitigates with caps (maxAgents + a wall-clock timeout + a per-sync-chunk vm timeout) + monitoring. For HARD
+ *   heap/CPU isolation use {@link import("./hardened-vm-worker-runner.js").createWorkerHardenedVmRunner} — the
+ *   SAME membrane in a worker_thread (resourceLimits + terminate). Single-tenant callers (e.g. a TOC run-local)
+ *   can treat the in-process model as final, like the reference shell-host implementation does.
+ *
+ * 🔴 Known IN-PROCESS cap gap (resource-exhaustion, not boundary): the sync `vm` timeout kills a SYNCHRONOUS infinite loop, and
+ *   the wall-clock race kills a script that yields to the MACROTASK queue (or awaits a stuck host fn). A pure
+ *   MICROTASK-starvation loop (`while (true) { await null }`) starves the host event loop, so neither the host
+ *   timer nor the abort listener fires → it hangs the process. The worker-isolated runner (`terminate()`)
+ *   pre-empts that — use it for genuinely-untrusted multi-tenant scripts where resource isolation matters.
+ *
+ * 🔴 Silent-hang class ([1818]§二, clay live incident 2026-07-26): a script whose promise graph can NEVER settle
+ *   (an un-awaited `phase(...)` whose body returns its own promise) used to burn the full totalTimeoutMs blind
+ *   and then blame the timeout. The quiescence detector in {@link runHardened} fail-fasts it with a diagnosis:
+ *   inside the membrane the bridge is the ONLY async host seam, so bridge-quiescent + both queues drained +
+ *   scriptPromise pending is a PROOF of deadlock, not a heuristic. Sibling hazard, same incident review: an
+ *   un-awaited IN-CONTEXT rejection shares the host isolate's unhandledRejection machinery (Node default =
+ *   crash the process) — contained by {@link installScriptRealmRejectionGuard} (realm-keyed: script rejections
+ *   are logged, host rejections keep fail-loud).
+ */
 export interface HardenedVmLimits {
+    /** Wall-clock cap on the whole run (covers async loops the sync `vm` timeout can't). Default 600_000. */
     totalTimeoutMs?: number;
+    /** Per-synchronous-chunk `vm` timeout — bounds a synchronous infinite loop before the first await. Default 5_000. */
     syncTimeoutMs?: number;
+    /** Hard cap on `agent()` spawns across a workflow run (runaway-fan-out backstop). Default 1000. */
     maxAgents?: number;
+    /** Max concurrent in-flight calls the in-context parallel/pipeline pools allow. Default 12. */
     concurrency?: number;
+    /** worker_thread heap cap in MB (only honored by the worker-isolated runner — see hardened-vm-worker-runner.ts).
+     *  A script exceeding it OOMs the WORKER (killed), never the shared main process. Default 128. */
     maxHeapMb?: number;
 }
+/** Optional observability hook for contained script-realm rejections (e.g. wire to the deployment logger). */
 export declare function setScriptRealmRejectionObserver(observer: (summary: string) => void): void;
 export declare function installScriptRealmRejectionGuard(): void;
+/**
+ * The membrane handed to a surface's `buildGlobals` callback to construct the CONTEXT-LOCAL bindings the
+ * untrusted body will see. NEVER expose a raw host function/object to the script — route it through here.
+ */
 export interface HardenedMembrane {
+    /** Wrap a host async fn as a CONTEXT-LOCAL fn: args are sterilized in, the result is marshalled back
+     *  context-local, a host throw becomes a context-local Error. This is the only safe way to give the script
+     *  a host capability. */
     bridge(hostFn: (...args: unknown[]) => unknown): (...a: unknown[]) => Promise<unknown>;
+    /** Marshal a host DATA value into a sterilized context-local value (for non-function bindings / args). */
     dataIn(value: unknown): unknown;
+    /** Compile + evaluate a TRUSTED expression IN the context (e.g. to define in-context orchestration sugar).
+     *  The source MUST be developer-authored, never untrusted input. */
     ctxEval(trustedSource: string): unknown;
 }
+/**
+ * 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 declare function scopedPhaseGate(phase: WorkflowPrimitives["phase"]): {
     enter(title: string): Promise<number>;
     exit(token: number, ok: boolean, err?: string): Promise<void>;
 };
+/** 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 declare function orchestrationGlobals(primitives: WorkflowPrimitives, scriptArgs: unknown, limits?: HardenedVmLimits): (m: HardenedMembrane) => Record<string, unknown>;
+/** 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 declare function createHardenedVmRunner(limits?: HardenedVmLimits): WorkflowScriptRunner;
+/**
+ * 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 declare function runInHardenedVm(opts: {
     code: string;
     bindings?: (m: HardenedMembrane) => Record<string, unknown>;