@boardwalk-labs/runner 0.1.9 → 0.1.11

package/dist/runtime/freeze_coordinator.d.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import type { RelayChannel } from "./identity_relay.js";
+import type { SuspendSignal } from "./suspension.js";
+/** First retry delay after a suspend_abort (doubles per attempt, capped below). */
+export declare const ABORT_RETRY_INITIAL_MS = 30000;
+export declare const ABORT_RETRY_MAX_MS: number;
+/** The wake value inside a wake injection — `kind` echoes the parked seam's reason; the
+ *  per-kind fields are opaque to the coordinator and interpreted by the seam. */
+export declare const wakeValueSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        sleep: "sleep";
+        human_input: "human_input";
+        workflow_call: "workflow_call";
+    }>;
+    answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    child: z.ZodOptional<z.ZodObject<{
+        run_id: z.ZodString;
+        status: z.ZodString;
+        output: z.ZodUnknown;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type WakeValue = z.infer<typeof wakeValueSchema>;
+/** The wake-injection payload as init relays it (snake_case, the platform env contract's
+ *  sibling): fresh tokens — the frozen ones expired while suspended — plus the
+ *  authoritative wall clock (the guest's own clock was stopped) and the wake value. */
+export declare const wakePayloadSchema: z.ZodObject<{
+    run_token: z.ZodString;
+    api_token: z.ZodOptional<z.ZodString>;
+    wall_clock_ms: z.ZodNumber;
+    wake: z.ZodObject<{
+        kind: z.ZodEnum<{
+            sleep: "sleep";
+            human_input: "human_input";
+            workflow_call: "workflow_call";
+        }>;
+        answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        child: z.ZodOptional<z.ZodObject<{
+            run_id: z.ZodString;
+            status: z.ZodString;
+            output: z.ZodUnknown;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type WakePayload = z.infer<typeof wakePayloadSchema>;
+/** What a suspending wait resolves to: the wake (the normal path), or — for a `sleep` seam
+ *  only — the abort that tells it to hold its remainder in-process (other reasons retry the
+ *  freeze internally and never surface an abort). */
+export type FreezeOutcome = {
+    kind: "wake";
+    wake: WakeValue;
+} | {
+    kind: "aborted";
+    reason: string;
+};
+export interface FreezeCoordinatorHooks {
+    /** Runs at quiescence, immediately before the freeze is requested: flush billable runtime
+     *  (suspended time must never appear billed) and persist the workspace. Its own failure
+     *  aborts THIS freeze attempt (the seam holds/retries) — never the run. */
+    onBeforeFreeze?: () => Promise<void>;
+    /** Runs when a wake lands, before the seam resolves: swap the run/api tokens onto the
+     *  broker client and rebase the runtime meter past the frozen window. */
+    onAfterWake?: (wake: WakePayload) => void | Promise<void>;
+}
+export interface FreezeCoordinatorDeps {
+    channel: RelayChannel;
+    now?: () => number;
+    /** Injected delay (tests). Defaults to a real timer. */
+    delay?: (ms: number) => Promise<void>;
+}
+export declare class FreezeCoordinator {
+    private readonly deps;
+    private readonly now;
+    private readonly delay;
+    private hooks;
+    /** Non-suspending runtime work in flight (the quiescence gate's count). */
+    private inFlight;
+    private quiescenceWaiters;
+    /** True from freeze request until wake/abort — new runtime work queues behind it. */
+    private freezePending;
+    private gateWaiters;
+    /** The parked suspending wait (at most one — waits serialize). */
+    private parked;
+    /** Serializes suspending waits. */
+    private chain;
+    constructor(deps: FreezeCoordinatorDeps);
+    /** Late-bound per-run hooks (the flusher/broker/redactor exist only once a run is claimed). */
+    setHooks(hooks: FreezeCoordinatorHooks): void;
+    /**
+     * Run one unit of non-suspending runtime work under the gate: queue while a freeze is
+     * pending (the work never starts, so nothing can be torn by the pause), then count it
+     * in-flight so a suspending wait holds until it drains. The gate check and the count
+     * increment share one synchronous segment — a freeze requested in between cannot miss us.
+     */
+    trackWork<T>(fn: () => Promise<T>): Promise<T>;
+    /** A suspending seam's own wait is NOT "work" — it decrements around its park so the gate
+     *  sees true quiescence. (The host wraps every hook in trackWork; the suspending seams
+     *  call these around their freeze wait.) */
+    beginWork(): void;
+    endWork(): void;
+    /**
+     * The suspending wait: hold until quiescence, run the pre-freeze hook, request the
+     * freeze, and park. The next thing this promise sees is a wake (possibly epochs later,
+     * through a restored heap) or a suspend_abort. Returns the wake, or — for `sleep` only —
+     * the abort (the seam then holds in-process); other reasons retry the freeze after a
+     * backoff. Concurrent suspending waits serialize through an internal chain.
+     */
+    suspendingWait(signal: SuspendSignal): Promise<FreezeOutcome>;
+    /** Relay handler: a wake injection landed. Validates, runs the after-wake hook (token
+     *  swap + meter rebase), confirms to init, and resolves the parked seam. A wake with no
+     *  parked seam is a duplicate delivery — re-confirm (idempotent), never crash. */
+    onWake(payload: unknown): void;
+    /** Relay handler: the snapshot attempt failed; the parked seam falls back to holding. */
+    onSuspendAbort(payload: unknown): void;
+    private awaitQuiescence;
+    private releaseGate;
+    /** The host-readable wake summary on the wire (logs/metrics/placement) — the opaque
+     *  broker_signal beside it carries the full condition. */
+    private wakeConditionOf;
+}

package/dist/runtime/freeze_coordinator.js

@@ -0,0 +1,262 @@
+// FreezeCoordinator — the runtime's half of snapshot suspension on the microVM substrate.
+//
+// On this substrate the worker process NEVER exits to suspend: a suspending seam (a long
+// sleep, a human-input gate, a child-run wait) BLOCKS on a real promise, the platform
+// freezes the whole VM into a snapshot, and a later restore resolves that same promise with
+// the wake value — the heap is the literal heap, nothing replays. This coordinator owns the
+// two policies that make freezing safe and predictable:
+//
+// 1. THE QUIESCENCE GATE: never freeze while non-suspending runtime work (an agent leaf, a
+//    tool call, an artifact write) is in flight — a snapshot must not capture a live
+//    platform stream that would be dead on restore. A suspending wait created during such
+//    work HOLDS until the work drains; new runtime work that arrives while a freeze is
+//    pending QUEUES (it never started, so nothing is torn) and runs after the wake.
+// 2. SNAPSHOT-FIRST FALLBACK: a `suspend_abort` from the platform (snapshot/store/broker
+//    failure) means the seam falls back to HOLDING — a sleep waits in-process for its
+//    remainder; a human-input or child wait retries the freeze after a backoff (the host
+//    may throttle repeated attempts).
+//
+// Concurrent suspending waits SERIALIZE: the first to reach quiescence freezes with its own
+// wake condition; after its wake, the next takes its turn. (A compound wake condition —
+// one freeze covering several waits — is a future optimization, not a correctness need:
+// the heap survives every cycle.)
+//
+// The wire below this is the guest init's relay (identity_relay `openChannel`); the policy
+// above it is decided platform-side. The coordinator never interprets the wake VALUE — it
+// validates the envelope and hands `wake` to the seam that parked.
+import { z } from "zod";
+import { createLogger } from "./support/index.js";
+const log = createLogger("FreezeCoordinator");
+/** First retry delay after a suspend_abort (doubles per attempt, capped below). */
+export const ABORT_RETRY_INITIAL_MS = 30_000;
+export const ABORT_RETRY_MAX_MS = 5 * 60_000;
+/** The wake value inside a wake injection — `kind` echoes the parked seam's reason; the
+ *  per-kind fields are opaque to the coordinator and interpreted by the seam. */
+export const wakeValueSchema = z.object({
+    kind: z.enum(["sleep", "human_input", "workflow_call"]),
+    /** human_input: EVERY gate this suspension raised, keyed by gate key / tool-call id. */
+    answers: z.record(z.string(), z.unknown()).optional(),
+    /** workflow_call: the finalized child. */
+    child: z
+        .object({
+        run_id: z.string().min(1),
+        status: z.string().min(1),
+        output: z.unknown(),
+    })
+        .optional(),
+});
+/** The wake-injection payload as init relays it (snake_case, the platform env contract's
+ *  sibling): fresh tokens — the frozen ones expired while suspended — plus the
+ *  authoritative wall clock (the guest's own clock was stopped) and the wake value. */
+export const wakePayloadSchema = z.object({
+    run_token: z.string().min(1),
+    api_token: z.string().optional(),
+    wall_clock_ms: z.number(),
+    wake: wakeValueSchema,
+});
+const suspendAbortSchema = z.object({ reason: z.string().optional() });
+export class FreezeCoordinator {
+    deps;
+    now;
+    delay;
+    hooks = {};
+    /** Non-suspending runtime work in flight (the quiescence gate's count). */
+    inFlight = 0;
+    quiescenceWaiters = [];
+    /** True from freeze request until wake/abort — new runtime work queues behind it. */
+    freezePending = false;
+    gateWaiters = [];
+    /** The parked suspending wait (at most one — waits serialize). */
+    parked = null;
+    /** Serializes suspending waits. */
+    chain = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        // A pending retry delay legitimately keeps the process alive — the run isn't done.
+        this.delay =
+            deps.delay ??
+                ((ms) => new Promise((resolve) => {
+                    setTimeout(resolve, ms);
+                }));
+    }
+    /** Late-bound per-run hooks (the flusher/broker/redactor exist only once a run is claimed). */
+    setHooks(hooks) {
+        this.hooks = hooks;
+    }
+    /**
+     * Run one unit of non-suspending runtime work under the gate: queue while a freeze is
+     * pending (the work never starts, so nothing can be torn by the pause), then count it
+     * in-flight so a suspending wait holds until it drains. The gate check and the count
+     * increment share one synchronous segment — a freeze requested in between cannot miss us.
+     */
+    async trackWork(fn) {
+        while (this.freezePending) {
+            await new Promise((resolve) => {
+                this.gateWaiters.push(resolve);
+            });
+        }
+        this.beginWork();
+        try {
+            return await fn();
+        }
+        finally {
+            this.endWork();
+        }
+    }
+    /** A suspending seam's own wait is NOT "work" — it decrements around its park so the gate
+     *  sees true quiescence. (The host wraps every hook in trackWork; the suspending seams
+     *  call these around their freeze wait.) */
+    beginWork() {
+        this.inFlight += 1;
+    }
+    endWork() {
+        this.inFlight -= 1;
+        if (this.inFlight === 0) {
+            const waiters = this.quiescenceWaiters;
+            this.quiescenceWaiters = [];
+            for (const w of waiters)
+                w();
+        }
+    }
+    /**
+     * The suspending wait: hold until quiescence, run the pre-freeze hook, request the
+     * freeze, and park. The next thing this promise sees is a wake (possibly epochs later,
+     * through a restored heap) or a suspend_abort. Returns the wake, or — for `sleep` only —
+     * the abort (the seam then holds in-process); other reasons retry the freeze after a
+     * backoff. Concurrent suspending waits serialize through an internal chain.
+     */
+    suspendingWait(signal) {
+        const turn = this.chain;
+        let release = () => undefined;
+        this.chain = new Promise((resolve) => {
+            release = resolve;
+        });
+        return (async () => {
+            await turn;
+            try {
+                let backoff = ABORT_RETRY_INITIAL_MS;
+                for (;;) {
+                    await this.awaitQuiescence();
+                    try {
+                        await this.hooks.onBeforeFreeze?.();
+                    }
+                    catch (err) {
+                        // A failed pre-freeze flush must not strand the seam: treat it like an abort.
+                        log.warn("freeze_prepare_failed", {
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                        if (signal.reason === "sleep")
+                            return { kind: "aborted", reason: "prepare_failed" };
+                        await this.delay(backoff);
+                        backoff = Math.min(backoff * 2, ABORT_RETRY_MAX_MS);
+                        continue;
+                    }
+                    this.freezePending = true;
+                    const outcome = await new Promise((resolve) => {
+                        this.parked = resolve;
+                        this.deps.channel.sendSuspendRequest({
+                            reason: signal.reason,
+                            wake: this.wakeConditionOf(signal),
+                            broker_signal: signal,
+                        });
+                        // ← the VM freezes while this promise is pending; the wake resolves it with the
+                        //   heap (and this very closure) restored.
+                    });
+                    this.freezePending = false;
+                    this.releaseGate();
+                    if (outcome.kind === "wake")
+                        return outcome;
+                    if (signal.reason === "sleep")
+                        return outcome;
+                    log.warn("suspend_aborted_retrying", {
+                        reason: outcome.reason,
+                        seamReason: signal.reason,
+                        backoffMs: backoff,
+                    });
+                    await this.delay(backoff);
+                    backoff = Math.min(backoff * 2, ABORT_RETRY_MAX_MS);
+                }
+            }
+            finally {
+                release();
+            }
+        })();
+    }
+    /** Relay handler: a wake injection landed. Validates, runs the after-wake hook (token
+     *  swap + meter rebase), confirms to init, and resolves the parked seam. A wake with no
+     *  parked seam is a duplicate delivery — re-confirm (idempotent), never crash. */
+    onWake(payload) {
+        const parsed = wakePayloadSchema.safeParse(payload);
+        if (!parsed.success) {
+            // Unanswerable garbage: init will retry, time out, and the platform's crash path owns
+            // recovery. Log loudly — this is a control-plane/init bug, not author code.
+            log.error("wake_payload_invalid", { issues: parsed.error.message });
+            return;
+        }
+        if (this.parked === null) {
+            log.warn("duplicate_wake_ignored", {});
+            this.deps.channel.sendWakeAccepted();
+            return;
+        }
+        const resolve = this.parked;
+        this.parked = null;
+        void (async () => {
+            try {
+                await this.hooks.onAfterWake?.(parsed.data);
+            }
+            catch (err) {
+                // Token swap / meter rebase failing is survivable only loudly — the run continues
+                // on the old token and fails fast if it truly expired.
+                log.error("after_wake_hook_failed", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            this.deps.channel.sendWakeAccepted();
+            resolve({ kind: "wake", wake: parsed.data.wake });
+        })();
+    }
+    /** Relay handler: the snapshot attempt failed; the parked seam falls back to holding. */
+    onSuspendAbort(payload) {
+        const parsed = suspendAbortSchema.safeParse(payload);
+        const reason = parsed.success ? (parsed.data.reason ?? "unknown") : "unknown";
+        if (this.parked === null) {
+            log.warn("suspend_abort_without_parked_seam", { reason });
+            return;
+        }
+        const resolve = this.parked;
+        this.parked = null;
+        resolve({ kind: "aborted", reason });
+    }
+    awaitQuiescence() {
+        if (this.inFlight === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.quiescenceWaiters.push(resolve);
+        });
+    }
+    releaseGate() {
+        const waiters = this.gateWaiters;
+        this.gateWaiters = [];
+        for (const w of waiters)
+            w();
+    }
+    /** The host-readable wake summary on the wire (logs/metrics/placement) — the opaque
+     *  broker_signal beside it carries the full condition. */
+    wakeConditionOf(signal) {
+        switch (signal.reason) {
+            case "sleep":
+                return { kind: "sleep", wake_at_ms: this.now() + (signal.durationMs ?? 0) };
+            case "human_input":
+                return {
+                    kind: "human_input",
+                    ...(signal.humanInput !== undefined ? { request_keys: [signal.humanInput.key] } : {}),
+                };
+            case "workflow_call":
+                return {
+                    kind: "workflow_call",
+                    ...(signal.childRunId !== undefined ? { child_run_id: signal.childRunId } : {}),
+                };
+        }
+    }
+}

package/dist/runtime/identity_relay.d.ts

@@ -0,0 +1,97 @@
+import type { Duplex } from "node:stream";
+import { z } from "zod";
+/** 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 declare 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 declare const MAX_RELAY_LINE_BYTES: number;
+/** The identity payload — the env contract's fields, as JSON instead of env vars. */
+export declare const relayIdentitySchema: z.ZodObject<{
+    run_id: z.ZodString;
+    control_plane_url: z.ZodString;
+    run_token: z.ZodString;
+    api_token: z.ZodOptional<z.ZodString>;
+    task_cpu_units: z.ZodOptional<z.ZodNumber>;
+    byo_providers: z.ZodOptional<z.ZodUnknown>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type RelayIdentity = z.infer<typeof relayIdentitySchema>;
+/** The init→worker halves of the post-identity relay: `wake` resolves a frozen suspending
+ *  seam (payload: the wake-inject body, verbatim), `suspend_abort` tells a parked seam the
+ *  snapshot attempt failed and it should fall back to holding. */
+export interface RelayChannelHandlers {
+    onWake(payload: unknown): void;
+    onSuspendAbort(payload: unknown): void;
+}
+/** The worker→init halves: ask to be frozen (payload: the suspend-request body — reason,
+ *  wake summary, opaque broker signal), and confirm a wake landed (init then acks its host). */
+export interface RelayChannel {
+    sendSuspendRequest(payload: unknown): void;
+    sendWakeAccepted(): void;
+}
+/**
+ * Read the relay fd from `env`, deleting the key (bootstrap-only plumbing; run code has no
+ * business seeing it). Returns null when unset — the normal env-boot path.
+ */
+export declare function relayFdFromEnv(env: NodeJS.ProcessEnv): number | null;
+/**
+ * Map a relayed identity onto `env` for `capturePlatformContext`. User env lands FIRST and
+ * the platform keys LAST, so nothing user-supplied can shadow a platform value.
+ */
+export declare function applyIdentityToEnv(identity: RelayIdentity, env: NodeJS.ProcessEnv): void;
+/** The worker_ready diagnostics — supplied by the worker (init cannot know these),
+ *  forwarded verbatim by the guest init. Best-effort, never load-bearing. */
+export interface WorkerDiagnostics {
+    worker_version?: string;
+    node_version: string;
+    sdk_version?: string;
+}
+/** 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 declare function workerDiagnostics(): WorkerDiagnostics;
+/** One end of the init↔worker relay. Wraps any Duplex so tests run over in-memory streams. */
+export declare class IdentityRelay {
+    private readonly stream;
+    private buffer;
+    private closed;
+    private failure;
+    private wake;
+    private readonly onData;
+    constructor(stream: Duplex);
+    private fail;
+    /** Announce the pre-identity park (with the diagnostics payload when provided).
+     *  Init forwards this as the base-snapshot gate. */
+    announceReady(diagnostics?: WorkerDiagnostics): void;
+    /**
+     * Block until init relays the run identity. THIS is the point the base snapshot freezes:
+     * everything before it is generic warm-up shared by every run; everything after belongs
+     * to one run. Unknown message types are ignored (forward-compatible), malformed lines are
+     * logged and skipped (init is trusted; a torn line must not kill PID 1's only worker), but
+     * a malformed IDENTITY payload is a hard error — same as a missing env var today.
+     */
+    awaitIdentity(): Promise<RelayIdentity>;
+    /** Confirm capture. Init acks its host only after this arrives. */
+    acceptIdentity(): void;
+    /**
+     * 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: RelayChannelHandlers): RelayChannel;
+    private pumpChannel;
+    private writeLine;
+    private readLine;
+}
+/**
+ * Open the relay over the inherited fd. Wrapping the fd in a net.Socket also marks it
+ * close-on-exec (libuv does this on adoption), so subprocesses the run later spawns cannot
+ * inherit the relay and speak to init.
+ */
+export declare function connectIdentityRelayFd(fd: number): IdentityRelay;

package/dist/runtime/identity_relay.js

@@ -0,0 +1,291 @@
+// Identity relay — the microVM bootstrap boundary.
+//
+// On Boardwalk's snapshot-based microVM substrate the worker starts BEFORE it has a run: the
+// guest init (PID 1) spawns it warm (Node up, this code loaded, parked pre-identity), the
+// platform snapshots the whole VM, and every run restores from that snapshot and INJECTS the
+// run identity over an in-guest relay instead of container env. The relay is an inherited
+// AF_UNIX socketpair; init tells us its fd via `BOARDWALK_IDENTITY_RELAY_FD`. Wire: one JSON
+// object per LF-terminated line —
+//
+//	{"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 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: `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";
+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),
+    control_plane_url: z.string().min(1),
+    run_token: z.string().min(1),
+    api_token: z.string().optional(),
+    task_cpu_units: z.number().int().positive().optional(),
+    /** The BYO inference provider registry, verbatim (stringified into BOARDWALK_BYO_PROVIDERS). */
+    byo_providers: z.unknown().optional(),
+    /** Resolved NON-secret user env. Platform keys always win over these (applied last). */
+    env: z.record(z.string(), z.string()).optional(),
+});
+const relayMessageSchema = z.object({
+    type: z.string(),
+    payload: z.unknown().optional(),
+});
+/**
+ * Read the relay fd from `env`, deleting the key (bootstrap-only plumbing; run code has no
+ * business seeing it). Returns null when unset — the normal env-boot path.
+ */
+export function relayFdFromEnv(env) {
+    const raw = env[RELAY_FD_ENV];
+    Reflect.deleteProperty(env, RELAY_FD_ENV);
+    if (raw === undefined || raw.trim().length === 0)
+        return null;
+    const fd = Number(raw);
+    if (!Number.isInteger(fd) || fd < 3) {
+        throw new Error(`${RELAY_FD_ENV} must name an inherited fd (>= 3), got ${raw}`);
+    }
+    return fd;
+}
+/**
+ * Map a relayed identity onto `env` for `capturePlatformContext`. User env lands FIRST and
+ * the platform keys LAST, so nothing user-supplied can shadow a platform value.
+ */
+export function applyIdentityToEnv(identity, env) {
+    for (const [key, value] of Object.entries(identity.env ?? {})) {
+        env[key] = value;
+    }
+    env.RUN_ID = identity.run_id;
+    env.BOARDWALK_CONTROL_PLANE_URL = identity.control_plane_url;
+    env.BOARDWALK_RUN_TOKEN = identity.run_token;
+    if (identity.api_token !== undefined && identity.api_token.length > 0) {
+        env.BOARDWALK_API_KEY = identity.api_token;
+    }
+    if (identity.task_cpu_units !== undefined) {
+        env.BOARDWALK_TASK_CPU_UNITS = String(identity.task_cpu_units);
+    }
+    if (identity.byo_providers !== undefined) {
+        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.
+        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?.();
+        };
+        stream.on("data", this.onData);
+        stream.on("end", () => {
+            this.closed = true;
+            this.wake?.();
+        });
+        stream.on("error", (err) => {
+            // Keep the error's detail — "closed" alone hides why the socket died.
+            this.fail(err);
+        });
+    }
+    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:
+     * everything before it is generic warm-up shared by every run; everything after belongs
+     * to one run. Unknown message types are ignored (forward-compatible), malformed lines are
+     * logged and skipped (init is trusted; a torn line must not kill PID 1's only worker), but
+     * a malformed IDENTITY payload is a hard error — same as a missing env var today.
+     */
+    async awaitIdentity() {
+        for (;;) {
+            const line = await this.readLine();
+            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;
+            }
+            if (message.data.type !== "identity") {
+                log.warn("relay_unexpected_type_ignored", { type: message.data.type });
+                continue;
+            }
+            const identity = relayIdentitySchema.safeParse(message.data.payload);
+            if (!identity.success) {
+                throw new Error(`Relayed identity payload is invalid: ${identity.error.message}`);
+            }
+            return identity.data;
+        }
+    }
+    /** Confirm capture. Init acks its host only after this arrives. */
+    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");
+    }
+    async readLine() {
+        for (;;) {
+            const newline = this.buffer.indexOf("\n");
+            if (newline >= 0) {
+                const line = this.buffer.slice(0, newline);
+                this.buffer = this.buffer.slice(newline + 1);
+                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");
+            }
+            await new Promise((resolve) => {
+                this.wake = resolve;
+            });
+            this.wake = null;
+        }
+    }
+}
+/**
+ * Open the relay over the inherited fd. Wrapping the fd in a net.Socket also marks it
+ * close-on-exec (libuv does this on adoption), so subprocesses the run later spawns cannot
+ * inherit the relay and speak to init.
+ */
+export function connectIdentityRelayFd(fd) {
+    return new IdentityRelay(new Socket({ fd, readable: true, writable: true }));
+}

package/dist/runtime/index.d.ts

@@ -1,5 +1,6 @@
 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
@@ -27,6 +28,10 @@ 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. */
 /** Synthesize the run's AuthContext. The run was already authorized at trigger time; the

package/dist/runtime/index.js

@@ -35,6 +35,8 @@ 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, workerDiagnostics, } from "./identity_relay.js";
+import { FreezeCoordinator } from "./freeze_coordinator.js";
 import { WorkerWorkflowHost } from "./workflow_host.js";
 import { runProgramWorker, } from "./program_worker.js";
 import { RunnerControlClient } from "./runner_control_client.js";
@@ -94,6 +96,24 @@ 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;
+    // 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 publishes to Redis server-side). Inference,
     // web_search, artifacts, and the model call are all brokered — no Redis / model creds / Tavily / S3.
     const eventPublisher = new BrokerEventPublisher({
@@ -110,7 +130,8 @@ export function assembleWorkerDeps(runtime) {
     // 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;
+    // 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) 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`.
     const apiUrl = publicApiOrigin(runtime.controlPlane.baseUrl);
@@ -287,8 +308,39 @@ 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 } : {}),
             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 — SUSPEND_POLICY) 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: 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
+                // guest's own clock was stopped).
+                onAfterWake: (wake) => {
+                    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({
@@ -375,6 +427,9 @@ 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() };
         },
@@ -484,6 +539,24 @@ export function capturePlatformContext(env) {
     return { runId, controlPlane, vcpus };
 }
 export async function main() {
+    // Relay-mode bootstrap (the snapshot-based microVM substrate): when the guest init handed
+    // us an identity relay fd, park here — warm, generic, pre-identity; this await is what the
+    // base snapshot freezes — until the run's identity arrives, then map it onto process.env
+    // so the capture below is transport-agnostic. Everywhere else (Fargate, self-hosted
+    // 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(workerDiagnostics());
+        const identity = await relay.awaitIdentity();
+        applyIdentityToEnv(identity, process.env);
+        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
     // API token (the run env/credential rules). WORKER_ID / WORKSPACE_ROOT are non-secret infra knobs.
@@ -498,6 +571,7 @@ 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.
     const cleanup = async () => {

package/dist/runtime/runner_control_client.d.ts

@@ -44,7 +44,12 @@ export declare class RunnerControlClient {
     private readonly cfg;
     private readonly base;
     private readonly fetchImpl;
+    /** The live bearer. Mutable: on the snapshot substrate a wake carries a FRESH run token (the
+     *  frozen one expired while suspended) and the worker swaps it at runtime. */
+    private runToken;
     constructor(cfg: RunnerControlClientConfig);
+    /** Swap the bearer for a fresh run token (the wake path). Every subsequent call uses it. */
+    swapRunToken(token: string): void;
     /** Claim the run's lease. Returns the run on success, or null when it isn't claimable (409 —
      *  another worker has it, or it isn't pending), which the worker treats as "claim lost". */
     claim(workerId: string, leaseSeconds: number): Promise<{

package/dist/runtime/runner_control_client.js

@@ -16,10 +16,18 @@ export class RunnerControlClient {
     cfg;
     base;
     fetchImpl;
+    /** The live bearer. Mutable: on the snapshot substrate a wake carries a FRESH run token (the
+     *  frozen one expired while suspended) and the worker swaps it at runtime. */
+    runToken;
     constructor(cfg) {
         this.cfg = cfg;
         this.base = cfg.baseUrl.replace(/\/+$/, "");
         this.fetchImpl = cfg.fetchImpl ?? fetch;
+        this.runToken = cfg.runToken;
+    }
+    /** Swap the bearer for a fresh run token (the wake path). Every subsequent call uses it. */
+    swapRunToken(token) {
+        this.runToken = token;
     }
     /** Claim the run's lease. Returns the run on success, or null when it isn't claimable (409 —
      *  another worker has it, or it isn't pending), which the worker treats as "claim lost". */
@@ -409,7 +417,7 @@ export class RunnerControlClient {
     }
     headers(json) {
         const h = {
-            authorization: `Bearer ${this.cfg.runToken}`,
+            authorization: `Bearer ${this.runToken}`,
             accept: "application/json",
         };
         if (json)

package/dist/runtime/runtime_flusher.d.ts

@@ -26,7 +26,16 @@ export declare class RuntimeFlusher {
     private flushedSeconds;
     /** Per-flush sequence — advances only on a successful flush, so a retry reuses the same id. */
     private seq;
+    /** Wall-clock ms excluded from billing — frozen (suspended) time on the snapshot substrate. */
+    private excludedMs;
     constructor(deps: RuntimeFlusherDeps);
+    /** Book everything unbilled right now (the pre-freeze flush: suspended time must never appear as
+     *  billed runtime, so the tail is booked BEFORE the snapshot — SUSPEND_POLICY billing rule). */
+    flushNow(): Promise<void>;
+    /** Exclude `ms` of wall-clock from billing — the frozen window on a wake (computed from the wake's
+     *  authoritative wall clock, since the guest's own clock was stopped). Never lets elapsed go
+     *  negative. */
+    excludeIdle(ms: number): void;
     /** Begin periodic delta flushing. */
     start(): void;
     /** Stop the periodic timer and drain any in-flight flush. Does NOT book the final tail — call

package/dist/runtime/runtime_flusher.js

@@ -30,9 +30,23 @@ export class RuntimeFlusher {
     flushedSeconds = 0;
     /** Per-flush sequence — advances only on a successful flush, so a retry reuses the same id. */
     seq = 0;
+    /** Wall-clock ms excluded from billing — frozen (suspended) time on the snapshot substrate. */
+    excludedMs = 0;
     constructor(deps) {
         this.deps = deps;
     }
+    /** Book everything unbilled right now (the pre-freeze flush: suspended time must never appear as
+     *  billed runtime, so the tail is booked BEFORE the snapshot — SUSPEND_POLICY billing rule). */
+    async flushNow() {
+        await this.flush(false);
+    }
+    /** Exclude `ms` of wall-clock from billing — the frozen window on a wake (computed from the wake's
+     *  authoritative wall clock, since the guest's own clock was stopped). Never lets elapsed go
+     *  negative. */
+    excludeIdle(ms) {
+        if (ms > 0)
+            this.excludedMs += ms;
+    }
     /** Begin periodic delta flushing. */
     start() {
         if (this.timer !== null)
@@ -67,7 +81,7 @@ export class RuntimeFlusher {
         // vCPU-seconds = wall-clock seconds × vCPUs (billed per vCPU-second). Rounding the cumulative
         // product (not per-delta) keeps the booked total aligned with wall-clock×vcpus over many flushes.
         const vcpus = this.deps.vcpus ?? 1;
-        const total = Math.max(0, Math.round(((this.deps.now() - this.deps.startedAtMs) / 1000) * vcpus));
+        const total = Math.max(0, Math.round(((this.deps.now() - this.deps.startedAtMs - this.excludedMs) / 1000) * vcpus));
         const delta = total - this.flushedSeconds;
         if (delta < 1)
             return;

package/dist/runtime/workflow_host.d.ts

@@ -1,6 +1,7 @@
 import type { WorkflowHost, AgentOptions, ArtifactBody, ArtifactRef, CallOptions, HumanInputOptions, HumanInputResult, PhaseOptions, SleepArg } from "@boardwalk-labs/workflow/runtime";
 import { type LeafResume } from "@boardwalk-labs/engine/core";
 import { type JournalSeam, type SuspendSignal } from "./suspension.js";
+import type { FreezeCoordinator } from "./freeze_coordinator.js";
 /** Parse a `humanInput({ timeout })` string (`"48h"`, `"30m"`, `"90s"`, `"7d"`) to milliseconds, or
  *  null when absent/unparseable (the gate then waits indefinitely). */
 export declare function parseTimeoutMs(timeout: string | undefined): number | null;
@@ -126,6 +127,14 @@ export interface WorkerWorkflowHostDeps {
      * rejects with {@link SuspendError} instead (the local/test path).
      */
     onSuspend?: (signal: SuspendSignal) => void;
+    /**
+     * Snapshot-substrate suspension (the microVM freeze model): when present, a suspending seam
+     * BLOCKS on the coordinator instead of raising `onSuspend` — the platform freezes the whole VM
+     * and a wake resolves the seam in place, heap intact (no exit, no journal replay). Every hook
+     * also runs under the coordinator's quiescence gate: a freeze never captures a live platform
+     * stream, and work arriving while a freeze is pending queues until the wake.
+     */
+    freeze?: FreezeCoordinator;
     /**
      * The highest journaled seq at claim (0 on a fresh run). While re-running seams up to this
      * frontier on a resume, the host is REPLAYING and observability (phase markers, program logs) is
@@ -152,8 +161,16 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     private suspend;
     /** Run `fn` only if the run isn't aborted; otherwise REJECT (never throw synchronously) with the
      *  signal's RunAbortedError — every Promise-returning hook funnels through this so callers always
-     *  get a rejected promise on abort, not a sync throw. */
+     *  get a rejected promise on abort, not a sync throw. On the snapshot substrate the body also runs
+     *  under the freeze coordinator's quiescence gate (see {@link WorkerWorkflowHostDeps.freeze}). */
     private guarded;
+    /** A suspending seam's freeze wait: step out of the "work" count around the park (the wait itself
+     *  is what the gate waits FOR, not work that blocks it), then rejoin on resume. */
+    private freezeWait;
+    /** The wake's answer for one gate key. A wake whose value is missing the parked gate means the
+     *  control plane and the snapshot disagree about what this run was waiting for — a platform bug,
+     *  failed loudly, never a retry. */
+    private gateAnswer;
     setPhase(name: string, opts: PhaseOptions | undefined): void;
     agent(prompt: string, opts: AgentOptions | undefined): Promise<unknown>;
     /** The `agent()` durable seam: a journal hit returns the memoized result (never re-runs the LLM); a

package/dist/runtime/workflow_host.js

@@ -97,7 +97,8 @@ export class WorkerWorkflowHost {
     }
     /** Run `fn` only if the run isn't aborted; otherwise REJECT (never throw synchronously) with the
      *  signal's RunAbortedError — every Promise-returning hook funnels through this so callers always
-     *  get a rejected promise on abort, not a sync throw. */
+     *  get a rejected promise on abort, not a sync throw. On the snapshot substrate the body also runs
+     *  under the freeze coordinator's quiescence gate (see {@link WorkerWorkflowHostDeps.freeze}). */
     guarded(fn) {
         try {
             throwIfAborted(this.deps.signal);
@@ -106,10 +107,35 @@ export class WorkerWorkflowHost {
             return Promise.reject(err instanceof Error ? err : new Error(String(err)));
         }
         const phases = this.deps.phases;
-        if (phases === undefined)
-            return fn();
-        const phaseId = phases.capture();
-        return phases.runInPhase(phaseId, fn);
+        // Capture the phase at CALL time — BEFORE any gate queueing — so a hook that queued across a
+        // freeze still lands in the phase its call site was in.
+        const phaseId = phases?.capture() ?? null;
+        const body = phases === undefined ? fn : () => phases.runInPhase(phaseId, fn);
+        const freeze = this.deps.freeze;
+        if (freeze === undefined)
+            return body();
+        return freeze.trackWork(body);
+    }
+    /** A suspending seam's freeze wait: step out of the "work" count around the park (the wait itself
+     *  is what the gate waits FOR, not work that blocks it), then rejoin on resume. */
+    async freezeWait(freeze, signal) {
+        freeze.endWork();
+        try {
+            return await freeze.suspendingWait(signal);
+        }
+        finally {
+            freeze.beginWork();
+        }
+    }
+    /** The wake's answer for one gate key. A wake whose value is missing the parked gate means the
+     *  control plane and the snapshot disagree about what this run was waiting for — a platform bug,
+     *  failed loudly, never a retry. */
+    gateAnswer(wake, key) {
+        const answer = wake.answers?.[key];
+        if (wake.kind !== "human_input" || answer === undefined) {
+            throw new AppError(ErrorCode.INTERNAL_ERROR, `Wake value does not answer the parked gate "${key}" (got kind "${wake.kind}")`, { kind: "wake_mismatch", key });
+        }
+        return answer;
     }
     setPhase(name, opts) {
         throwIfAborted(this.deps.signal);
@@ -146,21 +172,23 @@ export class WorkerWorkflowHost {
                 resume = leafResumeSchema.parse(existing.result);
             }
         }
-        try {
-            const result = await this.deps.leaf.run(prompt, opts, this.deps.signal, resume);
-            await this.deps.journal?.put({
-                seq,
-                kind: "agent",
-                fingerprint,
-                label: prompt.slice(0, 120),
-                result,
-            });
-            return result;
-        }
-        catch (err) {
-            if (err instanceof LeafParked) {
-                // The model paused for a person: suspend with the leaf's checkpoint + the gate.
-                return this.suspend({
+        for (;;) {
+            try {
+                const result = await this.deps.leaf.run(prompt, opts, this.deps.signal, resume);
+                await this.deps.journal?.put({
+                    seq,
+                    kind: "agent",
+                    fingerprint,
+                    label: prompt.slice(0, 120),
+                    result,
+                });
+                return result;
+            }
+            catch (err) {
+                if (!(err instanceof LeafParked))
+                    throw err;
+                // The model paused for a person (the in-leaf `human_input` tool).
+                const signal = {
                     reason: "human_input",
                     seq,
                     fingerprint,
@@ -170,9 +198,25 @@ export class WorkerWorkflowHost {
                         prompt: err.request.prompt,
                         inputSpec: err.request.inputSpec,
                     },
-                });
+                };
+                const freeze = this.deps.freeze;
+                if (freeze === undefined)
+                    return this.suspend(signal);
+                // Snapshot substrate: freeze in place; the wake carries the answers and the leaf
+                // re-enters from its checkpoint — heap intact, no journal round-trip. A leaf may park
+                // again on a later turn, so this loops.
+                if (err.checkpoint === undefined) {
+                    throw new AppError(ErrorCode.INTERNAL_ERROR, "Parked agent leaf has no checkpoint to resume from", { kind: "leaf_parked_no_checkpoint", seq });
+                }
+                const outcome = await this.freezeWait(freeze, signal);
+                if (outcome.kind !== "wake") {
+                    throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a human-input seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
+                }
+                // Validate OUR gate is answered, but hand the leaf the whole batch (spec: a wake
+                // carries every answer the suspension raised, keyed by tool-call id).
+                this.gateAnswer(outcome.wake, err.request.toolCallId);
+                resume = { checkpoint: err.checkpoint, answers: { ...(outcome.wake.answers ?? {}) } };
             }
-            throw err;
         }
     }
     /** Program-level `humanInput()`: suspend the run on a gate, resume with the validated answer. The
@@ -197,7 +241,7 @@ export class WorkerWorkflowHost {
             }
         }
         const expiresAt = this.timeoutExpiry(opts.timeout);
-        return this.suspend({
+        const signal = {
             reason: "human_input",
             seq,
             fingerprint,
@@ -209,7 +253,17 @@ export class WorkerWorkflowHost {
                 // A timeout only matters with a wake to fire at; carry onTimeout alongside expiresAt.
                 ...(expiresAt !== null ? { expiresAt, onTimeout: opts.onTimeout ?? "fail" } : {}),
             },
-        });
+        };
+        const freeze = this.deps.freeze;
+        if (freeze !== undefined) {
+            // Snapshot substrate: park in place; the wake carries the validated answer.
+            const outcome = await this.freezeWait(freeze, signal);
+            if (outcome.kind !== "wake") {
+                throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a human-input seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
+            }
+            return normalizeHumanInputResult(this.gateAnswer(outcome.wake, key));
+        }
+        return this.suspend(signal);
     }
     /** Absolute wake time for a `humanInput({ timeout })`, or null when there is none / it's unparseable. */
     timeoutExpiry(timeout) {
@@ -290,13 +344,30 @@ export class WorkerWorkflowHost {
         if (child.status === "failed" || child.status === "cancelled") {
             throw new AppError(ErrorCode.VALIDATION_FAILED, `Called workflow "${slug}" ${child.status} (run ${child.childRunId})`, { childRunId: child.childRunId, status: child.status });
         }
-        // Still running → suspend (release the task); the child's finalize wakes us.
-        return this.suspend({
+        // Still running → suspend; the child's finalize wakes us.
+        const signal = {
             reason: "workflow_call",
             seq,
             fingerprint,
             childRunId: child.childRunId,
-        });
+        };
+        const freeze = this.deps.freeze;
+        if (freeze !== undefined) {
+            // Snapshot substrate: park in place; the wake carries the finalized child directly (no
+            // journal write for the wake-derived value — the heap holds it and nothing replays).
+            const outcome = await this.freezeWait(freeze, signal);
+            if (outcome.kind !== "wake") {
+                throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a child-wait seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
+            }
+            const woken = outcome.wake.child;
+            if (outcome.wake.kind !== "workflow_call" || woken === undefined) {
+                throw new AppError(ErrorCode.INTERNAL_ERROR, `Wake value does not carry the awaited child run (got kind "${outcome.wake.kind}")`, { kind: "wake_mismatch", childRunId: child.childRunId });
+            }
+            if (woken.status === "completed")
+                return woken.output;
+            throw new AppError(ErrorCode.VALIDATION_FAILED, `Called workflow "${slug}" ${woken.status} (run ${woken.run_id})`, { childRunId: woken.run_id, status: woken.status });
+        }
+        return this.suspend(signal);
     }
     /** Fire-and-forget trigger of another workflow; resolves to the new run's id (no hold/poll). */
     runWorkflow(slug, input, opts) {
@@ -355,9 +426,32 @@ export class WorkerWorkflowHost {
         const holdMs = Math.max(0, ms);
         if (holdMs === 0)
             return;
-        // Long wait: SUSPEND (release the task). The broker records the (resolved) sleep journal entry +
-        // the wake time transactionally, so on wake this seam replays past it (the journal hit above).
-        // Only when a journal is wired — without it there is no resume, so fall back to holding.
+        const freeze = this.deps.freeze;
+        if (holdMs >= SUSPEND_THRESHOLD_MS && freeze !== undefined) {
+            // Snapshot substrate: freeze in place; the wake (when the sleep is due) resolves this very
+            // await, heap intact. An abort falls back to holding the REMAINDER in-process — the
+            // two-ways rule: snapshot or hold, never replay.
+            const requestedAt = this.now();
+            const outcome = await this.freezeWait(freeze, {
+                reason: "sleep",
+                seq,
+                fingerprint,
+                durationMs: holdMs,
+            });
+            if (outcome.kind === "wake")
+                return;
+            const remaining = holdMs - (this.now() - requestedAt);
+            if (remaining <= 0)
+                return;
+            if (this.deps.onBeforeSleep !== undefined)
+                await this.deps.onBeforeSleep();
+            await this.sleeper.hold(remaining, this.deps.signal);
+            return;
+        }
+        // Long wait (transitional substrate): SUSPEND (release the task). The broker records the
+        // (resolved) sleep journal entry + the wake time transactionally, so on wake this seam replays
+        // past it (the journal hit above). Only when a journal is wired — without it there is no
+        // resume, so fall back to holding.
         if (holdMs >= SUSPEND_THRESHOLD_MS && this.deps.journal !== undefined) {
             return this.suspend({ reason: "sleep", seq, fingerprint, durationMs: holdMs });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {