@boardwalk-labs/runner 0.1.10 → 0.1.12

package/dist/runtime/identity_relay.js

@@ -7,14 +7,23 @@
 // AF_UNIX socketpair; init tells us its fd via `BOARDWALK_IDENTITY_RELAY_FD`. Wire: one JSON
 // object per LF-terminated line —
 //
-//	{"type":"worker_ready"}                    worker → init   the pre-identity park is reached
+//	{"type":"worker_ready","payload":{...}}    worker → init   the pre-identity park is reached
+//	                                                           (payload: optional version diagnostics,
+//	                                                           forwarded verbatim by init)
 //	{"type":"identity","payload":{...}}        init → worker   the run identity (see schema below)
 //	{"type":"identity_accepted"}               worker → init   captured; init acks its host
+//	{"type":"suspend_request","payload":{...}} worker → init   a quiescent seam asks to be frozen
+//	{"type":"suspend_abort","payload":{...}}   init → worker   snapshot failed; the seam holds instead
+//	{"type":"wake","payload":{...}}            init → worker   resolve the frozen seam (fresh tokens
+//	                                                           + the wake value, verbatim)
+//	{"type":"wake_accepted"}                   worker → init   tokens swapped, seam resolved; init acks
 //
-// The payload carries exactly the platform env contract (snake_case) plus the resolved user
-// env; `applyIdentityToEnv` maps it onto `process.env` so `capturePlatformContext` runs
+// The identity payload carries exactly the platform env contract (snake_case) plus the resolved
+// user env; `applyIdentityToEnv` maps it onto `process.env` so `capturePlatformContext` runs
 // UNCHANGED afterward — same fields, same capture-and-delete discipline, two transports.
-// The stream stays open after identity: later platform phases speak suspend/wake over it.
+// The stream stays open after identity: `openChannel` attaches the suspend/wake consumer
+// (the FreezeCoordinator drives the choreography above it).
+import { createRequire } from "node:module";
 import { Socket } from "node:net";
 import { z } from "zod";
 import { createLogger } from "./support/index.js";
@@ -22,6 +31,11 @@ const log = createLogger("identity_relay");
 /** Env var naming the inherited relay fd. Set by the guest init; absent everywhere else
  *  (Fargate, self-hosted daemon), where the worker env-boots as always. */
 export const RELAY_FD_ENV = "BOARDWALK_IDENTITY_RELAY_FD";
+/** Max bytes of one relay line — the wire protocol's 32 MiB frame cap, mirrored in-guest.
+ *  An oversized line costs the connection (LF framing cannot resynchronize past it), which
+ *  for this relay means a hard bootstrap failure. Measured in UTF-16 code units, which for
+ *  this ASCII-JSON wire is the byte count; the cap is a guard, not exact accounting. */
+export const MAX_RELAY_LINE_BYTES = 32 * 1024 * 1024;
 /** The identity payload — the env contract's fields, as JSON instead of env vars. */
 export const relayIdentitySchema = z.object({
     run_id: z.string().min(1),
@@ -74,30 +88,73 @@ export function applyIdentityToEnv(identity, env) {
         env.BOARDWALK_BYO_PROVIDERS = JSON.stringify(identity.byo_providers);
     }
 }
+/** Collect the worker_ready diagnostics. Version lookups are best-effort: the runner's own
+ *  package.json sits two levels above this module in both the src and published dist
+ *  layouts; the SDK's is reachable only if its exports expose ./package.json. */
+export function workerDiagnostics() {
+    const require = createRequire(import.meta.url);
+    const versionOf = (spec) => {
+        try {
+            const pkg = require(spec);
+            return typeof pkg.version === "string" ? pkg.version : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const worker = versionOf("../../package.json");
+    const sdk = versionOf("@boardwalk-labs/workflow/package.json");
+    return {
+        ...(worker !== undefined ? { worker_version: worker } : {}),
+        node_version: process.version,
+        ...(sdk !== undefined ? { sdk_version: sdk } : {}),
+    };
+}
 /** One end of the init↔worker relay. Wraps any Duplex so tests run over in-memory streams. */
 export class IdentityRelay {
     stream;
     buffer = "";
     closed = false;
+    failure = null;
     wake = null;
+    onData;
     constructor(stream) {
         this.stream = stream;
         // One persistent listener for the relay's lifetime: a flowing stream DROPS chunks
         // emitted while nobody listens, so attach-per-read would lose lines between reads.
-        stream.on("data", (chunk) => {
+        this.onData = (chunk) => {
             this.buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            if (this.buffer.length > MAX_RELAY_LINE_BYTES && !this.buffer.includes("\n")) {
+                // The unterminated tail can never become a legal line — fail now instead of
+                // buffering without bound (the wire cap, mirrored; init is trusted, so this is a
+                // bug or corruption, not an attack to survive).
+                this.fail(new Error(`identity relay line exceeds ${MAX_RELAY_LINE_BYTES} bytes`));
+                return;
+            }
             this.wake?.();
-        });
-        const onClose = () => {
+        };
+        stream.on("data", this.onData);
+        stream.on("end", () => {
             this.closed = true;
             this.wake?.();
-        };
-        stream.on("end", onClose);
-        stream.on("error", onClose);
+        });
+        stream.on("error", (err) => {
+            // Keep the error's detail — "closed" alone hides why the socket died.
+            this.fail(err);
+        });
     }
-    /** Announce the pre-identity park. Init forwards this as the base-snapshot gate. */
-    announceReady() {
-        this.writeLine({ type: "worker_ready" });
+    fail(err) {
+        this.failure ??= err;
+        this.closed = true;
+        this.stream.destroy();
+        this.wake?.();
+    }
+    /** Announce the pre-identity park (with the diagnostics payload when provided).
+     *  Init forwards this as the base-snapshot gate. */
+    announceReady(diagnostics) {
+        this.writeLine(diagnostics === undefined
+            ? { type: "worker_ready" }
+            : { type: "worker_ready", payload: diagnostics });
     }
     /**
      * Block until init relays the run identity. THIS is the point the base snapshot freezes:
@@ -137,6 +194,64 @@ export class IdentityRelay {
     acceptIdentity() {
         this.writeLine({ type: "identity_accepted" });
     }
+    /**
+     * Attach the post-identity consumer: the suspend/wake channel (the same fd, the same JSON
+     * lines). From here the relay dispatches init→worker messages to the handlers —
+     * `wake` (resolve a frozen seam) and `suspend_abort` (the seam falls back to holding) —
+     * and the returned channel sends the worker→init halves (`suspend_request`,
+     * `wake_accepted`). Unknown types are ignored (forward-compatible); malformed lines are
+     * logged and skipped, exactly as pre-identity. Call once, after {@link acceptIdentity}.
+     */
+    openChannel(handlers) {
+        void this.pumpChannel(handlers);
+        return {
+            sendSuspendRequest: (payload) => {
+                this.writeLine({ type: "suspend_request", payload });
+            },
+            sendWakeAccepted: () => {
+                this.writeLine({ type: "wake_accepted" });
+            },
+        };
+    }
+    async pumpChannel(handlers) {
+        for (;;) {
+            let line;
+            try {
+                line = await this.readLine();
+            }
+            catch (err) {
+                // The relay dying mid-run means init is gone — the guest is being torn down; the
+                // worker's own exit follows. Log, don't throw into nowhere.
+                log.warn("relay_channel_closed", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                log.warn("relay_malformed_line_skipped", { length: line.length });
+                continue;
+            }
+            const message = relayMessageSchema.safeParse(parsed);
+            if (!message.success) {
+                log.warn("relay_malformed_message_skipped", {});
+                continue;
+            }
+            switch (message.data.type) {
+                case "wake":
+                    handlers.onWake(message.data.payload);
+                    break;
+                case "suspend_abort":
+                    handlers.onSuspendAbort(message.data.payload);
+                    break;
+                default:
+                    log.warn("relay_unexpected_type_ignored", { type: message.data.type });
+            }
+        }
+    }
     writeLine(message) {
         this.stream.write(JSON.stringify(message) + "\n");
     }
@@ -146,7 +261,15 @@ export class IdentityRelay {
             if (newline >= 0) {
                 const line = this.buffer.slice(0, newline);
                 this.buffer = this.buffer.slice(newline + 1);
-                return line;
+                if (line.length > MAX_RELAY_LINE_BYTES) {
+                    this.fail(new Error(`identity relay line exceeds ${MAX_RELAY_LINE_BYTES} bytes`));
+                }
+                else {
+                    return line;
+                }
+            }
+            if (this.failure !== null) {
+                throw this.failure;
             }
             if (this.closed) {
                 throw new Error("identity relay closed before the run identity arrived");

package/dist/runtime/index.d.ts

@@ -1,12 +1,13 @@
 import type { AuthContext } from "./support/index.js";
 import type { Run } from "./wire/run.js";
+import { type IdentityRelay } from "./identity_relay.js";
 import type { ByoInferenceProvider } from "../contract.js";
 import { type ProgramWorkerDeps } from "./program_worker.js";
 /** Constructed primitives the pure assembly consumes (real ones in main(), fakes in tests). The
  *  runner holds NO platform credential — only the per-run control-plane handle (run token + broker
  *  URL); everything else is reached through the Runner Control API (the Runner Credential Broker model). */
 export interface WorkerRuntime {
-    /** Stable worker identity stamped onto the lease (ECS task arn / hostname / run-derived). */
+    /** Stable worker identity stamped onto the lease (task ARN / hostname / run-derived). */
     workerId: string;
     /** Sandbox workspace root for filesystem/shell/git tools. */
     workspaceRoot: string;
@@ -27,14 +28,18 @@ export interface WorkerRuntime {
     /** vCPUs provisioned for this task (the dispatcher's resolved machine size ÷ 1024 cpu units). Runtime
      *  is billed per vCPU-SECOND, so the RuntimeFlusher scales wall-clock by this. Defaults to 1. */
     vcpus: number;
+    /** The in-guest identity relay, present ONLY on the snapshot-based microVM substrate (relay-mode
+     *  boot). When set, the worker suspends by FREEZING — the FreezeCoordinator parks seams over this
+     *  relay's suspend/wake channel — instead of the exit-and-replay path. */
+    freezeRelay?: IdentityRelay;
 }
-/** Durable events are deferred (run_step_events table) — live fan-out via the broker only. */
+/** Durable events are deferred (durable event storage) — live fan-out via the broker only. */
 /** Synthesize the run's AuthContext. The run was already authorized at trigger time; the
  *  worker acts on the org's behalf, so it carries the org + an owner role. Tool-level
  *  boundaries (the broker's server-side manifest allowlist) are the real guard.
  *
  *  source='workflow' (NOT 'session_jwt'): the program must never perform SESSION_JWT_ONLY
- *  credential mutations (§12.11), so a tool that ever exposed such a service is denied by
+ *  credential mutations, so a tool that ever exposed such a service is denied by
  *  construction regardless of the owner role. */
 export declare function workerAuthContext(run: Run): AuthContext;
 /**
@@ -52,10 +57,10 @@ export declare function workerAuthContext(run: Run): AuthContext;
  */
 export declare function tokenMeterIdentifiers(runId: string, sessionId: string): (leafIndex: number) => string;
 /** Pure wiring: build the full ProgramWorkerDeps from the control-plane handle. The runner reaches
- *  every privileged seam through the broker over its run token — no DB / Redis / Stripe / model creds. */
+ *  every privileged seam through the broker over its run token — no database, cache, billing, or model creds. */
 export declare function assembleWorkerDeps(runtime: WorkerRuntime): ProgramWorkerDeps;
 /**
- * The per-run platform values the dispatcher injects as container env (ecs_run_task_client.ts). They
+ * The per-run platform values the dispatcher injects as container env. They
  * are captured into private worker state at bootstrap and DELETED from `process.env` before any user
  * program / agent leaf / subprocess can run — the run token + API token are credentials, and nothing
  * untrusted run code touches should inherit them (the run env/credential rules). The user owns the rest
@@ -73,7 +78,7 @@ export interface PlatformContext {
     vcpus: number;
 }
 /** The public-API origin a run uses for raw API / MCP / CLI calls. The broker (Runner Control API)
- *  is hosted on the api-server, so the public API shares its origin; the program appends `/v1` or
+ *  shares an origin with the public API, so the program appends `/v1` or
  *  `/mcp/v1`. Falls back to the broker URL unchanged if it can't be parsed. */
 export declare function publicApiOrigin(controlPlaneBaseUrl: string): string;
 /**

package/dist/runtime/index.js

@@ -1,5 +1,5 @@
-// Worker composition root (the workflow runtime design). The Boardwalk-hosted
-// worker container runs `node dist/fargate/worker/index.js`; the dispatcher launches it per run with
+// Worker composition root (the workflow runtime design). The hosted worker container runs the
+// compiled worker entrypoint; the dispatcher launches it per run with
 // RUN_ID + the per-run control-plane handle. This file assembles real implementations behind every
 // seam `runProgramWorker(runId, deps)` injects, then runs the one workflow program to terminal.
 //
@@ -11,21 +11,21 @@
 //   - secrets.get()   → broker /secrets/resolve (allowlist enforced server-side).
 //   - workflows.call()→ broker /children (durable child run, hold + poll).
 //   - events.emit()   → broker /events (fan-out server-side).
-//   - artifacts / web_search → broker /artifacts + /tools/web_search (no S3 / Tavily creds here).
+//   - artifacts / web_search → broker /artifacts + /tools/web_search (no storage or search-provider creds here).
 //   - lifecycle / usage / telemetry → broker /claim,/version,/finalize,/usage,/telemetry.
-// There is no DB / Redis / Stripe / Bedrock client on the runner — so its task role is near-zero and
-// the metadata-endpoint escape has nothing to steal. The legacy direct (pre-broker) path is removed.
+// There is no database, cache, billing, or model-provider client on the runner — so its task role is
+// near-zero and the metadata-endpoint escape has nothing to steal. The legacy direct (pre-broker) path is removed.
 //
 // Split: `assembleWorkerDeps(runtime)` is pure wiring (unit-tested with a fake fetch); `main()` is the
 // bootstrap shell (read the control-plane env, install signal handlers).
 //
-// Per-session loops wired here (all brokered): a UsageFlusher meters token deltas (§10.7 →
-// /usage/tokens), a CreditWatcher polls funding (§15 → /credit, aborting the run on exhaustion), and a
-// CancelWatcher polls for a user cancel (§6 → /cancel, aborting the run when the user cancels — the
-// brokered worker holds no Redis, so it can't receive the api-server's cancel publish directly).
+// Per-session loops wired here (all brokered): a UsageFlusher meters token deltas (→ /usage/tokens), a
+// CreditWatcher polls funding (→ /credit, aborting the run on exhaustion), and a CancelWatcher polls
+// for a user cancel (→ /cancel, aborting the run when the user cancels — the brokered worker holds no
+// cache client, so it can't receive the platform's cancel publish directly).
 //
-// Documented v0 deferral (a clear seam): durable events — a no-op AgentEventStore (live Redis fan-out
-// via the broker only) until the run_step_events table lands.
+// Documented v0 deferral (a clear seam): durable events — a no-op AgentEventStore (live fan-out
+// via the broker only) until durable event storage lands.
 import { createLogger, newId, AppError, ErrorCode, DEFAULT_LEASE_MS } from "./support/index.js";
 import { LspService } from "@boardwalk-labs/engine/core";
 import { BudgetMeter } from "./agent/budget.js";
@@ -35,7 +35,9 @@ import { SecretRedactor } from "./agent/secret_redactor.js";
 import { RecordingSecretResolver } from "./recording_secret_resolver.js";
 import { EngineLeafExecutor } from "./leaf_executor.js";
 import { parseByoProviders } from "./direct_inference.js";
-import { applyIdentityToEnv, connectIdentityRelayFd, relayFdFromEnv } from "./identity_relay.js";
+import { applyIdentityToEnv, connectIdentityRelayFd, relayFdFromEnv, workerDiagnostics, } from "./identity_relay.js";
+import { FreezeCoordinator } from "./freeze_coordinator.js";
+import { reseedUserspaceCsprng } from "./uniqueness_reseed.js";
 import { WorkerWorkflowHost } from "./workflow_host.js";
 import { runProgramWorker, } from "./program_worker.js";
 import { RunnerControlClient } from "./runner_control_client.js";
@@ -53,13 +55,13 @@ import { PhaseTracker } from "./phase_tracker.js";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 const log = createLogger("worker_entrypoint");
-/** Durable events are deferred (run_step_events table) — live fan-out via the broker only. */
+/** Durable events are deferred (durable event storage) — live fan-out via the broker only. */
 /** Synthesize the run's AuthContext. The run was already authorized at trigger time; the
  *  worker acts on the org's behalf, so it carries the org + an owner role. Tool-level
  *  boundaries (the broker's server-side manifest allowlist) are the real guard.
  *
  *  source='workflow' (NOT 'session_jwt'): the program must never perform SESSION_JWT_ONLY
- *  credential mutations (§12.11), so a tool that ever exposed such a service is denied by
+ *  credential mutations, so a tool that ever exposed such a service is denied by
  *  construction regardless of the owner role. */
 export function workerAuthContext(run) {
     const userId = run.actor.type === "user" ? run.actor.user_id : `workflow:${run.workflowId}`;
@@ -83,7 +85,7 @@ export function tokenMeterIdentifiers(runId, sessionId) {
     return (leafIndex) => `${runId}:${sessionId}:${String(leafIndex)}:${String(seq++)}`;
 }
 /** Pure wiring: build the full ProgramWorkerDeps from the control-plane handle. The runner reaches
- *  every privileged seam through the broker over its run token — no DB / Redis / Stripe / model creds. */
+ *  every privileged seam through the broker over its run token — no database, cache, billing, or model creds. */
 export function assembleWorkerDeps(runtime) {
     const broker = new RunnerControlClient({
         baseUrl: runtime.controlPlane.baseUrl,
@@ -95,8 +97,27 @@ export function assembleWorkerDeps(runtime) {
     // a resumed run suppresses observability for seams it already ran. Captured at claim, read by
     // buildHost (which runs right after claim) when constructing the per-run host.
     let replayFrontier = 0;
-    // Live agent-event stream → /telemetry (broker publishes to Redis server-side). Inference,
-    // web_search, artifacts, and the model call are all brokered — no Redis / model creds / Tavily / S3.
+    // Snapshot-substrate suspension (relay-mode boot only): one coordinator for the process, wired to
+    // the relay's suspend/wake channel now; its per-run hooks (token swap, meter rebase, workspace
+    // persist) late-bind in buildHost/startRuntimeFlush once those objects exist. The circular
+    // channel↔handler reference resolves through the thunks.
+    let freeze;
+    let activeFlusher = null;
+    if (runtime.freezeRelay !== undefined) {
+        const channel = runtime.freezeRelay.openChannel({
+            onWake: (payload) => {
+                freeze?.onWake(payload);
+            },
+            onSuspendAbort: (payload) => {
+                freeze?.onSuspendAbort(payload);
+            },
+        });
+        freeze = new FreezeCoordinator({ channel });
+        log.info("freeze_mode_enabled", { runId: runtime.runId });
+    }
+    // Live agent-event stream → /telemetry (broker fans out server-side). Inference,
+    // web_search, artifacts, and the model call are all brokered — no cache client, model creds,
+    // search-provider creds, or object-storage creds here.
     const eventPublisher = new BrokerEventPublisher({
         send: (frames) => broker.publishTelemetry(frames),
     });
@@ -110,10 +131,11 @@ export function assembleWorkerDeps(runtime) {
     // bootstrap captured + scrubbed it (capturePlatformContext) so the agent's bash / subprocesses
     // can't read it. The program reaches it ONLY via `runtime.apiToken()` (built below); we still
     // record it in each run's redactor so a value the program threads into a tool can't echo back out
-    // of a tool result. Absent in the dev no-signing-key path. (the run env/credential rules)
-    const runApiKey = runtime.controlPlane.apiToken;
-    // The broker (Runner Control API) is hosted on the api-server, so the public API shares its
-    // origin; `runtime.apiUrl` exposes it and the program appends `/v1` or `/mcp/v1`.
+    // of a tool result. Absent in the dev no-signing-key path.
+    // MUTABLE: on the snapshot substrate a wake carries a fresh token (the frozen one expired).
+    let runApiKey = runtime.controlPlane.apiToken;
+    // The broker (Runner Control API) shares an origin with the public API;
+    // `runtime.apiUrl` exposes it and the program appends `/v1` or `/mcp/v1`.
     const apiUrl = publicApiOrigin(runtime.controlPlane.baseUrl);
     // Per-run host: agent() leaf + sleep-hold + secrets + children + events, all brokered. `signal`
     // carries cooperative cancellation (credit exhaustion) into every host hook.
@@ -123,7 +145,7 @@ export function assembleWorkerDeps(runtime) {
             // Fallback budget-cap rate. A managed turn caps on the broker's EXACT upstream cost (forwarded on
             // the inference result frame → BudgetMeter `realCostUsd`); this representative sonnet-class rate
             // applies only to a turn with no upstream cost (BYO / unavailable). `max_usd` is a guardrail, not
-            // the bill — that's per-leaf cost pass-through at the broker.
+            // the bill — the platform meters the actual per-leaf usage.
             rate: BUDGET_GUARDRAIL_RATE,
             startedAt: Date.now(),
             // deadline_seconds is WALL-CLOCK from the run's ORIGINAL start (incl. suspended idle), so a run
@@ -140,7 +162,7 @@ export function assembleWorkerDeps(runtime) {
         const nextMeterIdentifier = tokenMeterIdentifiers(run.id, meteringSessionId);
         // Per-run secret boundary: every value resolved (program `secrets.get` OR a tool's
         // ctx.secrets.resolve) is recorded into one shared redactor; the leaf seeds a fresh engine
-        // Redactor from it so the loop scrubs those values out of all model-bound content. the platform spec
+        // Redactor from it so the loop scrubs those values out of all model-bound content.
         const redactor = new SecretRedactor();
         // Record the run's own API key so a prompt-injected agent can't echo it back to the model.
         if (runApiKey !== undefined && runApiKey !== "")
@@ -190,9 +212,9 @@ export function assembleWorkerDeps(runtime) {
             // until the artifact extracts. The empty `/workspace` and this dir are SEPARATE dirs on hosted,
             // exactly the two-tier case the engine's AGENTS.md loader is built for.
             programDir: () => programDir,
-            // Per-leaf, per-model token metering — reported THROUGH the broker (the worker holds no Stripe
-            // credential); the broker decides `billed_by_boardwalk` per model + meters to Stripe (BYO models
-            // no-op there). Fire-and-forget: a metering hiccup must never fail the run.
+            // Per-leaf, per-model token metering — reported THROUGH the broker (the worker holds no billing
+            // credential); the broker decides `billed_by_boardwalk` per model + meters usage to the platform
+            // (BYO models no-op there). Fire-and-forget: a metering hiccup must never fail the run.
             meterUsage: ({ model, inputTokens, outputTokens, cachedReadTokens, cachedWriteTokens, leafIndex, }) => {
                 void broker
                     .meterTokens({
@@ -217,7 +239,7 @@ export function assembleWorkerDeps(runtime) {
             // comes from the org's connection vault via the Runner Control API — never stored on the worker.
             brokerMcpToken: (serverUrl, invalidateToken) => broker.mcpToken(serverUrl, invalidateToken),
         });
-        // Per-workflow persistent /workspace (§5): only when the manifest opts in. The BROKER additionally
+        // Per-workflow persistent /workspace: only when the manifest opts in. The BROKER additionally
         // gates on hosted (self-hosted runs get null URLs), and snapshots are keyed per-workflow + scoped
         // by the run token — so even the untrusted in-process program can't reach another tenant's data.
         const workspaceStore = manifest.workspace?.persist === true
@@ -288,8 +310,52 @@ export function assembleWorkerDeps(runtime) {
                     },
                 }
                 : {}),
+            // Snapshot-substrate suspension: seams freeze in place under the quiescence gate instead of
+            // raising onSuspend (which stays wired as the transitional/local path's fallback).
+            ...(freeze !== undefined ? { freeze } : {}),
+            // Register-without-release for held HITL gates — only on the
+            // freeze substrate, backed by the broker's inputs endpoints.
+            ...(freeze !== undefined
+                ? {
+                    heldInput: {
+                        register: (seq, gate) => broker.registerInput(seq, gate),
+                        poll: (seq) => broker.pollInputAnswers(seq),
+                    },
+                }
+                : {}),
             phases: phaseTracker,
         });
+        // Late-bind the coordinator's per-run hooks now that the run-scoped objects exist.
+        if (freeze !== undefined) {
+            const coordinator = freeze;
+            let freezeWallMs = 0;
+            coordinator.setHooks({
+                // At quiescence, immediately before the freeze: book the runtime tail (suspended time must
+                // never appear billed) and persist the workspace (crash-during-suspension
+                // recovery parity with the sleep-hold path). The wall stamp anchors the idle rebase below.
+                onBeforeFreeze: async () => {
+                    freezeWallMs = Date.now();
+                    await activeFlusher?.flushNow();
+                    await workspaceStore?.persist();
+                },
+                // On wake: reseed the userspace CSPRNG (clause 3 — a suspend snapshot restored more than
+                // once, e.g. a re-dispatch retry, would otherwise repeat its post-wake `crypto.*` draws),
+                // swap the fresh tokens onto the broker client + the program-facing apiToken() (recording
+                // the new values in the run's redactor, same discipline as boot), and exclude the frozen
+                // window from billed runtime using the wake's authoritative wall clock. The reseed runs
+                // BEFORE the seam resolves, so no woken author code draws from the stale (pre-suspend) DRBG.
+                onAfterWake: (wake) => {
+                    reseedUserspaceCsprng();
+                    broker.swapRunToken(wake.run_token);
+                    redactor.record(wake.run_token);
+                    if (wake.api_token !== undefined && wake.api_token !== "") {
+                        runApiKey = wake.api_token;
+                        redactor.record(wake.api_token);
+                    }
+                    activeFlusher?.excludeIdle(wake.wall_clock_ms - freezeWallMs);
+                },
+            });
+        }
         // Hand the redactor back too: the worker scrubs a terminal error's message with it;
         // workspace (when opted in) hydrates at start + persists at terminal.
         return Promise.resolve({
@@ -361,7 +427,7 @@ export function assembleWorkerDeps(runtime) {
         suspender: {
             suspend: (signal, workerId) => broker.suspend(signal, workerId),
         },
-        // Runtime metering (§15): flush runtime as periodic deltas (+ a terminal tail) through the broker,
+        // Runtime metering: flush runtime as periodic deltas (+ a terminal tail) through the broker,
         // idempotent per flush, so a long/perpetual run bills as it burns and the credit watcher sees it —
         // not a single charge at terminal (which a never-terminating run never reached). A fresh per-session
         // id keeps a restarted run's sessions distinct in the idempotency key (distinct ids sum).
@@ -376,11 +442,14 @@ export function assembleWorkerDeps(runtime) {
                 now: Date.now,
                 report: (deltaSeconds, identifier) => broker.reportUsage(deltaSeconds, identifier),
             });
+            // The freeze coordinator's hooks flush this before a snapshot + rebase it past the frozen
+            // window on wake (suspended time must never appear as billed runtime).
+            activeFlusher = flusher;
             flusher.start();
             return { stop: () => flusher.stop(), flushFinal: () => flusher.flushFinal() };
         },
         buildHost,
-        // Mid-run credit watching (§15): a CreditWatcher polls the broker's GET /credit on a timer; when
+        // Mid-run credit watching: a CreditWatcher polls the broker's GET /credit on a timer; when
         // the org runs out, onExhausted aborts the run (the orchestrator wires it to AbortController).
         startCreditWatch: ({ run, onExhausted }) => {
             const watcher = new CreditWatcher({
@@ -391,10 +460,10 @@ export function assembleWorkerDeps(runtime) {
             watcher.start();
             return { stop: () => watcher.stop() };
         },
-        // Mid-run user-cancel watching (§6): a CancelWatcher polls the broker's GET /cancel on a timer;
+        // Mid-run user-cancel watching: a CancelWatcher polls the broker's GET /cancel on a timer;
         // when the user cancels (the run is flipped to `cancelling`), onCancelled aborts the run. This is
-        // how the brokered (Redis-less) worker learns of a cancel — the api-server's Redis publish can't
-        // reach it.
+        // how the brokered (cache-less) worker learns of a cancel — the platform's cancel publish can't
+        // reach it directly.
         startCancelWatch: ({ run, onCancelled }) => {
             const watcher = new CancelWatcher({
                 runId: run.id,
@@ -404,7 +473,7 @@ export function assembleWorkerDeps(runtime) {
             watcher.start();
             return { stop: () => watcher.stop() };
         },
-        // Lease renewal (§6): a LeaseRenewer extends the lease through the broker's POST /renew on a timer
+        // Lease renewal: a LeaseRenewer extends the lease through the broker's POST /renew on a timer
         // (well under the lease), so a run longer than the 5-min lease isn't reclaimed mid-flight by the
         // recovery sweep. `renew` re-extends with the SAME workerId that claimed it; a null result (the
         // run is no longer ours) fires onLost → the run aborts `lease_lost` without finalizing.
@@ -427,7 +496,7 @@ export function assembleWorkerDeps(runtime) {
 }
 // ---- Bootstrap (real container only) -------------------------------------------------
 /**
- * The per-run platform values the dispatcher injects as container env (ecs_run_task_client.ts). They
+ * The per-run platform values the dispatcher injects as container env. They
  * are captured into private worker state at bootstrap and DELETED from `process.env` before any user
  * program / agent leaf / subprocess can run — the run token + API token are credentials, and nothing
  * untrusted run code touches should inherit them (the run env/credential rules). The user owns the rest
@@ -441,7 +510,7 @@ export const PLATFORM_ENV_KEYS = [
     "BOARDWALK_TASK_CPU_UNITS",
 ];
 /** The public-API origin a run uses for raw API / MCP / CLI calls. The broker (Runner Control API)
- *  is hosted on the api-server, so the public API shares its origin; the program appends `/v1` or
+ *  shares an origin with the public API, so the program appends `/v1` or
  *  `/mcp/v1`. Falls back to the broker URL unchanged if it can't be parsed. */
 export function publicApiOrigin(controlPlaneBaseUrl) {
     try {
@@ -465,7 +534,7 @@ export function capturePlatformContext(env) {
         return value.trim();
     };
     // The dispatcher always injects the control-plane handle (the Runner Credential Broker model). The runner is
-    // brokered-only — there is no DB/Redis/Stripe fallback — so a missing handle is a hard config error.
+    // brokered-only — there is no database, cache, or billing fallback — so a missing handle is a hard config error.
     const runId = read("RUN_ID");
     const apiToken = env.BOARDWALK_API_KEY?.trim();
     const controlPlane = {
@@ -492,12 +561,22 @@ export async function main() {
     // daemon) the fd is absent and the worker env-boots exactly as before. The post-restore
     // uniqueness reseed will hook in at this boundary, before any run code executes.
     const relayFd = relayFdFromEnv(process.env);
+    let freezeRelay;
     if (relayFd !== null) {
         const relay = connectIdentityRelayFd(relayFd);
-        relay.announceReady();
+        relay.announceReady(workerDiagnostics());
         const identity = await relay.awaitIdentity();
         applyIdentityToEnv(identity, process.env);
+        // Clause 3 (SNAPSHOT_UNIQUENESS_CONTRACT): this run was restored from the SHARED base
+        // snapshot, so its OpenSSL DRBG is identical to every other run's. Reseed it from the
+        // (VMGenID-diverged) OS entropy BEFORE `acceptIdentity` releases the worker into the brokered
+        // lifecycle — so no `crypto.*` draw by the SDK, the agent, or author code can collide across
+        // clones. Every wake reseeds again (the after-wake hook).
+        reseedUserspaceCsprng();
         relay.acceptIdentity();
+        // The relay now becomes the suspend/wake channel: assembleWorkerDeps opens it into the
+        // FreezeCoordinator, and the host's suspending seams freeze in place instead of exiting.
+        freezeRelay = relay;
     }
     // Capture the platform context into private state and remove it from process.env BEFORE anything
     // else — so no user program / agent tool / subprocess we later spawn can read the run token or
@@ -513,12 +592,13 @@ export async function main() {
         controlPlane: platform.controlPlane,
         vcpus: platform.vcpus,
         ...(byoProviders.length > 0 ? { byoProviders } : {}),
+        ...(freezeRelay !== undefined ? { freezeRelay } : {}),
     });
-    // The only thing to drain is the batched telemetry buffer — the runner opens no DB/Redis/SQS.
+    // The only thing to drain is the batched telemetry buffer — the runner opens no database, cache, or queue.
     const cleanup = async () => {
         await deps.flushTelemetry?.().catch(() => undefined);
     };
-    // SIGTERM: ECS is stopping the task. Hold-and-pay has no mid-run checkpoint; we exit and let the
+    // SIGTERM: the orchestrator is stopping the task. Hold-and-pay has no mid-run checkpoint; we exit and let the
     // lease expire → the scheduler-sweep reclaims it and a fresh worker RESTARTS the run from the
     // top (Lambda/GHA semantics; durable children re-attach via idempotency). Crash-safe by design.
     let shuttingDown = false;

package/dist/runtime/leaf_executor.d.ts

@@ -32,7 +32,7 @@ export interface EngineLeafExecutorDeps {
     budget: BudgetMeter;
     /** RUN-level redactor (shared with the secret resolver): every resolved secret value is recorded
      *  here. We seed a fresh engine `Redactor` from it per leaf so the loop scrubs known values out of
-     *  the prompt, tool args/results, and transcript before they reach the model (the platform spec). */
+     *  the prompt, tool args/results, and transcript before they reach the model. */
     redactor: SecretRedactor;
     /** Builds this leaf's event sink; `leafIndex` (1-based) is only a metering identifier — the sink
      *  owns the run-global cursor. `identity` names the leaf on its turn frames. */
@@ -51,7 +51,7 @@ export interface EngineLeafExecutorDeps {
      *  omitted ⇒ no bundled tier (only the workspace AGENTS.md applies). */
     programDir?: () => string | null;
     /** Per-leaf token metering seam (fire-and-forget). Reports THIS leaf's tokens + its model to the
-     *  broker, which decides `billed_by_boardwalk` per model + meters to Stripe. Omitted in tests. */
+     *  broker, which decides `billed_by_boardwalk` per model + meters usage to the platform. Omitted in tests. */
     meterUsage?: (input: MeterUsageInput) => void;
     /** Backend for the engine's host-backed built-in tools (`webfetch` / `web_search` / `artifacts`):
      *  set as the leaf's `capabilities.host` so the engine registers them. Broker-backed on hosted runs

package/dist/runtime/program_runner.d.ts

@@ -53,7 +53,7 @@ export interface ProgramRunnerDeps {
      * Scrubs known secret values out of a string (the run's `SecretRedactor.redactText`). Applied to a
      * top-level throw's message before it is logged AND before it is returned to the worker — a program
      * that resolves a secret and then throws it in an error message must NOT land that secret raw in the
-     * logs or the finalized run output (the platform spec). Defaults to identity (tests/local).
+     * logs or the finalized run output. Defaults to identity (tests/local).
      */
     redactText?: (text: string) => string;
     /**

package/dist/runtime/program_runner.js

@@ -1,6 +1,6 @@
 // WorkflowProgramRunner — executes a workflow program (the JS-body model, the workflow runtime design).
 //
-// A run is the execution of a built program ARTIFACT (§3.9): the worker is handed the VERIFIED tarball
+// A run is the execution of a built program ARTIFACT: the worker is handed the VERIFIED tarball
 // (its sha256 already checked against the pinned digest by the orchestrator) plus the entry module
 // name. This module is the mechanism: it installs the host adapter + trigger payload onto the
 // `@boardwalk-labs/workflow` singleton, extracts the artifact into a unique temp dir under a