@boardwalk-labs/runner 0.1.21 → 0.2.1

package/README.md

@@ -81,6 +81,17 @@ pnpm test
 pnpm lint && pnpm typecheck && pnpm build
 ```
 
+## The Boardwalk repos
+
+- [`boardwalk`](https://github.com/boardwalk-labs/boardwalk) — the open-source single-node engine: cron scheduling, webhooks, durable runs, run history
+- [`sdk`](https://github.com/boardwalk-labs/sdk) — `@boardwalk-labs/workflow`, the TypeScript API a workflow program imports
+- [`cli`](https://github.com/boardwalk-labs/cli) — `boardwalk`: scaffold, validate, run locally, deploy
+- [`examples`](https://github.com/boardwalk-labs/examples) — copyable workflow templates (`boardwalk init --template`)
+- [`plugins`](https://github.com/boardwalk-labs/plugins) — skills + MCP server for Claude Code, Codex, Cursor, OpenClaw, OpenCode
+- [`runner-images`](https://github.com/boardwalk-labs/runner-images) — reproducible base images hosted runners execute in
+
+Hosted platform and docs: [boardwalk.sh](https://boardwalk.sh).
+
 ## License
 
 Apache-2.0

package/dist/contract.d.ts

@@ -102,6 +102,8 @@ export type ByoInferenceProvider = z.infer<typeof byoInferenceProviderSchema>;
 export declare const claimResponseSchema: z.ZodObject<{
     lease_id: z.ZodString;
     run_id: z.ZodString;
+    workflow_id: z.ZodString;
+    environment_id: z.ZodNullable<z.ZodString>;
     lease_expires_at: z.ZodNumber;
     control_plane: z.ZodObject<{
         base_url: z.ZodString;

package/dist/contract.js

@@ -127,6 +127,20 @@ export const byoInferenceProviderSchema = z.strictObject({
 export const claimResponseSchema = z.strictObject({
     lease_id: id,
     run_id: id,
+    /**
+     * The run's persistence SCOPE — the daemon needs it to lay out its own disk BEFORE the run starts.
+     *
+     * A self-hosted runner keeps persistent workspaces on its own disk (never our S3), keyed per
+     * (workflow, environment) exactly like the hosted S3 key — one workflow program runs against N
+     * environments (docs/WORKSPACE_PERSISTENCE.md §4/I3). The daemon must know the scope up front,
+     * because in container isolation the scope dir is a BIND MOUNT chosen at `docker run` time: mount
+     * only this run's scope, and a program can't read another workflow's state; mount the whole persist
+     * root and it can. `run_id` alone can't express that, which is why these ride the claim.
+     *
+     * `environment_id` is null for a run with no environment — the BASE scope.
+     */
+    workflow_id: id,
+    environment_id: id.nullable(),
     /** Heartbeat before this or the lease expires and the run is recovered elsewhere. */
     lease_expires_at: epochMs,
     /**

package/dist/daemon/container.d.ts

@@ -24,8 +24,9 @@ export declare function containerEnv(runEnv: Record<string, string>): Record<str
 export declare function runIdFromCwd(cwd: string): string;
 /**
  * Build the `docker run` argv. PURE + exported so the isolation guarantees are unit-asserted:
- *  - the ONLY bind mount is the per-run workspace (+ any explicit user mounts) — the identity dir,
- *    the user's home, and the rest of the host FS are never mounted;
+ *  - the only bind mounts are the per-run workspace, this run's OWN persistence scope (+ any explicit
+ *    user mounts) — the identity dir, the user's home, OTHER workflows' persisted workspaces, and the
+ *    rest of the host FS are never mounted;
  *  - per-run credentials are passed by NAME (`-e BOARDWALK_RUN_TOKEN`), so their VALUES come from the
  *    docker client's env and never appear in the argv (which `ps` exposes);
  *  - `--rm` (no leftover container), `--init` (proper signal handling / zombie reaping).

package/dist/daemon/container.js

@@ -39,6 +39,9 @@ export function containerEnv(runEnv) {
         WORKSPACE_ROOT: "/workspace",
         HOME: "/workspace",
         TMPDIR: "/tmp",
+        // The host's per-scope durable dir is bind-mounted at /persist (buildContainerArgs), so the
+        // in-container path replaces the host one — which is meaningless inside the container.
+        ...(runEnv.PERSIST_SCOPE_DIR !== undefined ? { PERSIST_SCOPE_DIR: "/persist" } : {}),
     };
     return env;
 }
@@ -59,8 +62,9 @@ export function runIdFromCwd(cwd) {
 }
 /**
  * Build the `docker run` argv. PURE + exported so the isolation guarantees are unit-asserted:
- *  - the ONLY bind mount is the per-run workspace (+ any explicit user mounts) — the identity dir,
- *    the user's home, and the rest of the host FS are never mounted;
+ *  - the only bind mounts are the per-run workspace, this run's OWN persistence scope (+ any explicit
+ *    user mounts) — the identity dir, the user's home, OTHER workflows' persisted workspaces, and the
+ *    rest of the host FS are never mounted;
  *  - per-run credentials are passed by NAME (`-e BOARDWALK_RUN_TOKEN`), so their VALUES come from the
  *    docker client's env and never appear in the argv (which `ps` exposes);
  *  - `--rm` (no leftover container), `--init` (proper signal handling / zombie reaping).
@@ -80,6 +84,15 @@ export function buildContainerArgs(cfg, opts) {
         "-w",
         "/workspace",
     ];
+    // This run's durable workspace, when the daemon resolved one. THIS RUN'S SCOPE ONLY — never the
+    // whole persist root: the run's program is arbitrary code with raw fs access, so mounting the root
+    // would let any workflow read every other workflow's persisted state on this machine. Hosted
+    // isolates per workflow via the token-derived S3 key; self-hosted must not be weaker
+    // (docs/WORKSPACE_PERSISTENCE.md I3). The daemon pre-creates it, so docker can't make it root-owned.
+    const persistScopeDir = opts.env.PERSIST_SCOPE_DIR;
+    if (persistScopeDir !== undefined) {
+        args.push("-v", `${persistScopeDir}:/persist`);
+    }
     // Run as the invoking host user (Linux) so the bind-mounted workspace is writable — the image's
     // `node` (uid 1000) otherwise can't write a host dir it doesn't own.
     if (cfg.user !== undefined) {

package/dist/daemon/daemon.d.ts

@@ -41,5 +41,6 @@ export interface DaemonController {
 export declare function runProcessEnv(claim: ClaimResponse, opts: {
     runnerId: string;
     workspaceRoot: string;
+    persistScopeDir: string;
 }): Record<string, string>;
 export declare function startDaemon(deps: DaemonDeps): DaemonController;

package/dist/daemon/daemon.js

@@ -7,6 +7,7 @@
 // per-run workspace, then tears the workspace down (contract: cleanup "always").
 import { mkdir, rm } from "node:fs/promises";
 import * as path from "node:path";
+import { localScopeDir } from "../runtime/local_workspace_store.js";
 import { createLogger } from "../runtime/support/index.js";
 /** Assignment-lease heartbeat cadence — comfortably beats the 300s lease. */
 const HEARTBEAT_MS = 60_000;
@@ -31,6 +32,15 @@ export function runProcessEnv(claim, opts) {
         BOARDWALK_BYO_PROVIDERS: JSON.stringify(claim.byo_providers),
         WORKER_ID: opts.runnerId,
         WORKSPACE_ROOT: opts.workspaceRoot,
+        // This run's durable workspace directory — its (workflow, environment) SCOPE, already resolved
+        // (docs/WORKSPACE_PERSISTENCE.md I3). A self-hosted runner owns a disk that outlives a run, so
+        // `workspace.persist` and `agent({ memory })` compound HERE, never in our S3 (which never sees a
+        // self-hosted workspace). Without it the runtime has no durable root and falls back to the
+        // broker, which correctly refuses self-hosted runs — so persistence was a silent no-op.
+        //
+        // The DAEMON resolves the scope, not the runtime: it owns this disk, and in container isolation
+        // the scope dir is a bind mount chosen before the container starts. One owner, one layout.
+        PERSIST_SCOPE_DIR: opts.persistScopeDir,
         // The machine's own PATH/HOME etc. deliberately do NOT flow here: the run gets exactly the
         // resolved env + platform contract, mirroring the hosted container. The spawner overlays the
         // minimal process necessities (PATH, HOME=workspace).
@@ -44,9 +54,14 @@ export function startDaemon(deps) {
         const runDir = path.join(deps.workDir, "runs", claim.run_id);
         const workspaceRoot = path.join(runDir, "workspace");
         await mkdir(workspaceRoot, { recursive: true });
+        // This run's durable workspace, keyed per (workflow, environment) and living OUTSIDE the per-run
+        // dir (which is scratch, removed with the run). Created up front because the container lane binds
+        // it as a mount, and docker would otherwise create it root-owned.
+        const persistScopeDir = localScopeDir(path.join(deps.workDir, "persist"), claim.workflow_id, claim.environment_id);
+        await mkdir(persistScopeDir, { recursive: true });
         const child = deps.spawn({
             entry: deps.runtimeEntry,
-            env: runProcessEnv(claim, { runnerId: deps.runnerId, workspaceRoot }),
+            env: runProcessEnv(claim, { runnerId: deps.runnerId, workspaceRoot, persistScopeDir }),
             cwd: workspaceRoot,
         });
         log.info("run_started", { runId: claim.run_id, assignmentId: offer.assignment_id });

package/dist/runtime/agent/budget.d.ts

@@ -60,7 +60,10 @@ export interface BudgetSnapshot {
     elapsedMs: number;
 }
 export declare class BudgetMeter {
-    private readonly budget;
+    /** NOT readonly: a budget gate (docs/SUSPEND_POLICY.md Decision 3) raises `max_usd` in place when a
+     *  responder approves more spend. The meter lives in the frozen heap, so the wake mutates this
+     *  instance and the blocked model call proceeds against the new cap. */
+    private budget;
     private readonly rate;
     private readonly startedAt;
     private readonly deadlineStartedAt;
@@ -106,6 +109,16 @@ export declare class BudgetMeter {
      * inline (e.g., the sleep tool rejects a sleep that would breach the
      * duration cap). Returns the first breach reason or null.
      */
+    /**
+     * Raise the `max_usd` cap to `usd` — the budget gate's approval path (docs/SUSPEND_POLICY.md
+     * Decision 3). Only ever RAISES: a value at or below the current cap is ignored, so an approval
+     * can't silently tighten a cap and re-park the run on the very next call. A no-op when the
+     * workflow declared no budget (nothing to breach). Returns the cap now in force, or null when
+     * there is no budget.
+     */
+    raiseUsdCap(usd: number): number | null;
+    /** The `max_usd` cap in force, or null when unset. The gate prompt reports it alongside spend. */
+    usdCap(): number | null;
     capBreachReason(): "tokens" | "usd" | "duration" | "deadline" | null;
     /**
      * The declared `max_duration_seconds` cap, or null when unset. Lets callers that

package/dist/runtime/agent/budget.js

@@ -22,6 +22,9 @@ const ZERO_PRIOR = {
     activeMs: 0,
 };
 export class BudgetMeter {
+    /** NOT readonly: a budget gate (docs/SUSPEND_POLICY.md Decision 3) raises `max_usd` in place when a
+     *  responder approves more spend. The meter lives in the frozen heap, so the wake mutates this
+     *  instance and the blocked model call proceeds against the new cap. */
     budget;
     rate;
     startedAt;
@@ -133,6 +136,26 @@ export class BudgetMeter {
      * inline (e.g., the sleep tool rejects a sleep that would breach the
      * duration cap). Returns the first breach reason or null.
      */
+    /**
+     * Raise the `max_usd` cap to `usd` — the budget gate's approval path (docs/SUSPEND_POLICY.md
+     * Decision 3). Only ever RAISES: a value at or below the current cap is ignored, so an approval
+     * can't silently tighten a cap and re-park the run on the very next call. A no-op when the
+     * workflow declared no budget (nothing to breach). Returns the cap now in force, or null when
+     * there is no budget.
+     */
+    raiseUsdCap(usd) {
+        if (this.budget === undefined)
+            return null;
+        const current = this.budget.max_usd;
+        if (current !== undefined && usd <= current)
+            return current;
+        this.budget = { ...this.budget, max_usd: usd };
+        return usd;
+    }
+    /** The `max_usd` cap in force, or null when unset. The gate prompt reports it alongside spend. */
+    usdCap() {
+        return this.budget?.max_usd ?? null;
+    }
     capBreachReason() {
         try {
             this.assertWithinCaps();

package/dist/runtime/broker_child_dispatcher.d.ts

@@ -18,8 +18,6 @@ export declare class BrokerChildDispatcher implements ChildDispatcher {
     /** Start (or idempotently re-attach to) the child and resolve its CURRENT state — no hold. The
      *  durable callWorkflow seam decides whether to suspend (non-terminal) or return (terminal). */
     start(slug: string, input: unknown, _opts: CallOptions | undefined, signal?: AbortSignal): Promise<ChildResult>;
-    /** Poll a child's current state by id (the resume path), or null when it isn't this run's child. */
-    poll(childRunId: string): Promise<ChildResult | null>;
     /** Fire-and-forget: create (or re-attach to) the child and return its id without holding. */
     run(slug: string, input: unknown, _opts: CallOptions | undefined): Promise<string>;
     /** Provision a durable schedule via the broker; returns the new schedule's id. A `Date` `at` is

package/dist/runtime/broker_child_dispatcher.js

@@ -35,13 +35,6 @@ export class BrokerChildDispatcher {
         const child = await this.deps.client.startChild(slug, input);
         return { childRunId: child.childRunId, status: child.status, output: child.output };
     }
-    /** Poll a child's current state by id (the resume path), or null when it isn't this run's child. */
-    async poll(childRunId) {
-        const child = await this.deps.client.getChild(childRunId);
-        return child === null
-            ? null
-            : { childRunId: child.id, status: child.status, output: child.output };
-    }
     /** Fire-and-forget: create (or re-attach to) the child and return its id without holding. */
     async run(slug, input, _opts) {
         const child = await this.deps.client.startChild(slug, input);

package/dist/runtime/budget_gate.d.ts

@@ -0,0 +1,51 @@
+import type { BudgetMeter } from "./agent/budget.js";
+import type { HumanInputResult } from "@boardwalk-labs/workflow";
+/** The stable key a responder answers a budget gate by (`boardwalk respond <runId> budget …`). */
+export declare const BUDGET_GATE_KEY = "budget";
+/** Preset approvals, plus the two open-ended answers. Kept small: the point is a fast decision. */
+export declare const BUDGET_CHOICE_ADD_10 = "+$10";
+export declare const BUDGET_CHOICE_ADD_25 = "+$25";
+export declare const BUDGET_CHOICE_ADD_100 = "+$100";
+export declare const BUDGET_CHOICE_CANCEL = "cancel";
+/** The port the gate needs from the host — narrowed so tests don't build a whole WorkflowHost. */
+export interface BudgetClearancePort {
+    budgetClearance(gate: {
+        prompt: string;
+        inputSpec: unknown;
+    }): Promise<HumanInputResult>;
+}
+/** Raised when a responder answers `cancel`: the run stops, deliberately, at the user's word. */
+export declare class BudgetGateCancelled extends Error {
+    constructor();
+}
+/**
+ * The gate's question. It states the two numbers that matter (spent vs. cap) so the responder can
+ * decide without opening the dashboard, and names the run's own `max_usd` so it's obvious WHICH cap
+ * was hit (not the org's credit balance — a different failure with a different fix).
+ */
+export declare function budgetGatePrompt(spentUsd: number, capUsd: number): string;
+/** The gate's response form — a choice, so the common answers are one click / one word. */
+export declare function budgetGateInputSpec(): unknown;
+/**
+ * Interpret an answer as the NEW absolute `max_usd`, or null to cancel the run.
+ *
+ * `+$N` is an INCREMENT on the current cap (the presets); a bare number is an ABSOLUTE new cap (the
+ * "set a cap" escape hatch, via the choice's `other` entry). Anything unrecognized is treated as
+ * cancel rather than guessed at — silently resuming a run on a misread answer spends real money.
+ */
+export declare function resolveBudgetAnswer(answer: string, currentCapUsd: number): number | null;
+/**
+ * Budget clearance, awaited before every model call. Fast path: no breach ⇒ resolve immediately (the
+ * overwhelming majority of calls). On a `usd` breach: park at a gate, then apply the answer to the
+ * live meter and let the call proceed.
+ *
+ * Scope (slice 1): ONLY the `usd` cap parks. A `tokens` / `duration` / `deadline` breach still fails
+ * the run through the leaf executor's existing throw — those dimensions have no "approve more" story
+ * yet, and `deadline` is wall-clock, which a park cannot pause by definition.
+ */
+export declare class BudgetGate {
+    private readonly meter;
+    private readonly host;
+    constructor(meter: BudgetMeter, host: BudgetClearancePort);
+    clear(): Promise<void>;
+}

package/dist/runtime/budget_gate.js

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: MIT
+/** The stable key a responder answers a budget gate by (`boardwalk respond <runId> budget …`). */
+export const BUDGET_GATE_KEY = "budget";
+/** Preset approvals, plus the two open-ended answers. Kept small: the point is a fast decision. */
+export const BUDGET_CHOICE_ADD_10 = "+$10";
+export const BUDGET_CHOICE_ADD_25 = "+$25";
+export const BUDGET_CHOICE_ADD_100 = "+$100";
+export const BUDGET_CHOICE_CANCEL = "cancel";
+/** Raised when a responder answers `cancel`: the run stops, deliberately, at the user's word. */
+export class BudgetGateCancelled extends Error {
+    constructor() {
+        super("Run cancelled at the budget gate.");
+        this.name = "BudgetGateCancelled";
+    }
+}
+/** Money in a prompt: 2dp is right for a cap, which is always a human-chosen round-ish number. */
+function usd(n) {
+    return `$${n.toFixed(2)}`;
+}
+/**
+ * The gate's question. It states the two numbers that matter (spent vs. cap) so the responder can
+ * decide without opening the dashboard, and names the run's own `max_usd` so it's obvious WHICH cap
+ * was hit (not the org's credit balance — a different failure with a different fix).
+ */
+export function budgetGatePrompt(spentUsd, capUsd) {
+    return (`Budget cap reached: this run has spent ${usd(spentUsd)} of its ${usd(capUsd)} ` +
+        `max_usd cap. Approve more spend to continue, or cancel the run.`);
+}
+/** The gate's response form — a choice, so the common answers are one click / one word. */
+export function budgetGateInputSpec() {
+    return {
+        kind: "choice",
+        options: [
+            BUDGET_CHOICE_ADD_10,
+            BUDGET_CHOICE_ADD_25,
+            BUDGET_CHOICE_ADD_100,
+            BUDGET_CHOICE_CANCEL,
+        ],
+        // `other` lets a responder type an absolute cap ("50") instead of taking a preset increment.
+        other: true,
+    };
+}
+/**
+ * Interpret an answer as the NEW absolute `max_usd`, or null to cancel the run.
+ *
+ * `+$N` is an INCREMENT on the current cap (the presets); a bare number is an ABSOLUTE new cap (the
+ * "set a cap" escape hatch, via the choice's `other` entry). Anything unrecognized is treated as
+ * cancel rather than guessed at — silently resuming a run on a misread answer spends real money.
+ */
+export function resolveBudgetAnswer(answer, currentCapUsd) {
+    const raw = answer.trim();
+    if (raw === "" || raw.toLowerCase() === BUDGET_CHOICE_CANCEL)
+        return null;
+    const increment = /^\+\s*\$?\s*(\d+(?:\.\d+)?)$/.exec(raw);
+    if (increment?.[1] !== undefined)
+        return currentCapUsd + Number(increment[1]);
+    const absolute = /^\$?\s*(\d+(?:\.\d+)?)$/.exec(raw);
+    if (absolute?.[1] !== undefined) {
+        const value = Number(absolute[1]);
+        // An "absolute" cap at or below what's already spent would re-park instantly — read it as a
+        // refusal to fund more, which is a cancel.
+        return value > currentCapUsd ? value : null;
+    }
+    return null;
+}
+/** Pull the answer's text out of the SDK's result union (text | choice | multiselect). */
+function answerText(result) {
+    if (typeof result === "string")
+        return result;
+    if (typeof result === "object" && result !== null && "value" in result) {
+        const value = result.value;
+        if (typeof value === "string")
+            return value;
+    }
+    return "";
+}
+/**
+ * Budget clearance, awaited before every model call. Fast path: no breach ⇒ resolve immediately (the
+ * overwhelming majority of calls). On a `usd` breach: park at a gate, then apply the answer to the
+ * live meter and let the call proceed.
+ *
+ * Scope (slice 1): ONLY the `usd` cap parks. A `tokens` / `duration` / `deadline` breach still fails
+ * the run through the leaf executor's existing throw — those dimensions have no "approve more" story
+ * yet, and `deadline` is wall-clock, which a park cannot pause by definition.
+ */
+export class BudgetGate {
+    meter;
+    host;
+    constructor(meter, host) {
+        this.meter = meter;
+        this.host = host;
+    }
+    async clear() {
+        // Loop, don't `if`: a responder can approve an increment too small to clear the breach (spend
+        // already exceeds it), in which case we ask again rather than resume into an instant re-park.
+        while (this.meter.capBreachReason() === "usd") {
+            const cap = this.meter.usdCap();
+            if (cap === null)
+                return; // no cap ⇒ nothing to breach (defensive; capBreachReason implies one)
+            const spent = this.meter.snapshot().totalUsd;
+            // The park needs no bespoke event: registering the gate moves the run to `awaiting_input` and
+            // the prompt below rides the gate row, so the live tail + `boardwalk inputs` explain the pause
+            // through exactly the same path a humanInput() gate uses.
+            const answer = await this.host.budgetClearance({
+                prompt: budgetGatePrompt(spent, cap),
+                inputSpec: budgetGateInputSpec(),
+            });
+            const newCap = resolveBudgetAnswer(answerText(answer), cap);
+            if (newCap === null)
+                throw new BudgetGateCancelled();
+            this.meter.raiseUsdCap(newCap);
+        }
+    }
+}

package/dist/runtime/freeze_coordinator.js

@@ -269,6 +269,14 @@ export class FreezeCoordinator {
                     kind: "human_input",
                     ...(signal.humanInput !== undefined ? { request_keys: [signal.humanInput.key] } : {}),
                 };
+            // A budget park waits on the same gate machinery as human_input, but reports its own kind so
+            // the control plane can say "paused on budget" rather than "waiting on a human" — a different
+            // thing to a person triaging the run list (SUSPEND_POLICY Decision 3).
+            case "budget":
+                return {
+                    kind: "budget",
+                    ...(signal.humanInput !== undefined ? { request_keys: [signal.humanInput.key] } : {}),
+                };
             case "workflow_call":
                 return {
                     kind: "workflow_call",

package/dist/runtime/index.d.ts

@@ -11,8 +11,21 @@ import { type ProgramWorkerDeps } from "./program_worker.js";
 export interface WorkerRuntime {
     /** Stable worker identity stamped onto the lease (task ARN / hostname / run-derived). */
     workerId: string;
-    /** Sandbox workspace root for filesystem/shell/git tools. */
+    /** Sandbox workspace root for filesystem/shell/git tools — and the working directory + HOME for
+     *  author code (docs/WORKSPACE_PERSISTENCE.md I1). */
     workspaceRoot: string;
+    /** Where the program artifact is extracted. Deliberately OUTSIDE {@link workspaceRoot} (I2): a
+     *  bundle inside the workspace rides into every pre-sleep snapshot and, because each run's dir is
+     *  uniquely named, accumulates there forever. */
+    programRoot: string;
+    /** This run's durable workspace directory — its (workflow, environment) scope, ALREADY RESOLVED by
+     *  the daemon (PERSIST_SCOPE_DIR). Set only by a SELF-HOSTED runner, which owns a disk that
+     *  outlives a run. Present ⇒ persistence is a plain directory tree here (never our S3: a
+     *  self-hosted workspace is the customer's data on the customer's disk). Absent ⇒ the hosted lane,
+     *  which has no disk outliving the VM and persists through the broker. The daemon resolves the
+     *  scope because it owns the disk and, under container isolation, binds this exact dir as a mount.
+     *  See docs/WORKSPACE_PERSISTENCE.md I3. */
+    persistScopeDir?: string;
     /** The run this worker task is executing (RUN_ID) — binds the Runner Control API client. */
     runId: string;
     /** The org's BYO inference providers (claim-delivered, BOARDWALK_BYO_PROVIDERS) for the
@@ -32,7 +45,7 @@ export interface WorkerRuntime {
     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. */
+     *  relay's suspend/wake channel — the whole VM freezes and the wake resolves seams in place. */
     freezeRelay?: IdentityRelay;
     /** The browser tier's process backend, present ONLY when the runner IMAGE ships the browser stack
      *  (Chromium + a pre-installed Playwright MCP + an X display; gated by BOARDWALK_BROWSER_TIER).