@boardwalk-labs/runner 0.1.21 → 0.2.1

package/dist/runtime/program_runner.js

@@ -3,8 +3,8 @@
 // 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
-// node_modules-reachable root, and dynamic-imports the entry so the program's body runs. The
+// `@boardwalk-labs/workflow` singleton, extracts the artifact into a unique temp dir under the
+// program root, chdirs to the workspace, and dynamic-imports the entry so the program's body runs. The
 // program's `import { agent, sleep, … } from "@boardwalk-labs/workflow"` resolves to the SAME package
 // instance the host was installed on (one instance per process), so the hooks reach our adapter.
 //
@@ -13,32 +13,37 @@
 // `@boardwalk-labs/workflow` is left external in the bundle, so the imported program resolves it to the SDK
 // package present in the worker image (giving up its own copy would break the dual-adapter).
 //
-// Why a temp dir under a node_modules-reachable root (not os.tmpdir): the program imports the bare
-// specifier `@boardwalk-labs/workflow`, which Node resolves by walking up from the module's location to
-// `node_modules`. The extracted tree must therefore live inside the app tree (/app/.bw-runs/*).
+// Two places, both explicit, neither derived from `process.cwd()` (docs/WORKSPACE_PERSISTENCE.md I1/I2):
+//   - `workspaceRoot` — the run's `/workspace`. The working directory + HOME for AUTHOR code, so a
+//     relative write is the correct write and lands in what `workspace.persist` archives.
+//   - `programRoot`   — where the artifact extracts (`<programRoot>/.bw-runs/<runId>-<uuid>`). Must be
+//     OUTSIDE the workspace, or the bundle rides into every snapshot and accumulates across runs.
+// The extracted tree needs no node_modules-reachable ancestor: `ensureSdkLink` (below) links the SDK
+// into the exec dir, so the bare `@boardwalk-labs/workflow` import resolves from any root.
 //
 // Durability: the body runs once, in-process. `sleep`/`workflows.call` hold in-process via the host
 // (no checkpoint, no exit). A crash mid-run restarts the run from the top (handled by the
 // worker/scheduler-sweep, not here). Output capture is deferred (v0 returns null).
 import { mkdir, writeFile, rm, symlink, lstat } from "node:fs/promises";
-import { dirname, join, isAbsolute, relative, sep } from "node:path";
+import { dirname, join, isAbsolute, relative, resolve, sep } from "node:path";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
 import { installHost, installInput, installConfig, takeDeclaredOutput, resetRuntime, } from "@boardwalk-labs/workflow/runtime";
 import { AppError, ErrorCode, createLogger } from "./support/index.js";
-import { SuspendError } from "./suspension.js";
 const log = createLogger("ProgramRunner");
 /** Subdirectory (under the work root) that holds transient extracted program trees. */
 const RUN_DIR = ".bw-runs";
 /**
- * Link THIS runtime's `@boardwalk-labs/workflow` into the exec dir's `node_modules` so the
- * program's bare import resolves anywhere (a self-hosted daemon workspace has no ancestor
- * `node_modules`; hosted images do, making the link a harmless no-op there). A symlink — not a
- * copy — is load-bearing: Node resolves it to the REAL path, so the program gets the same
- * module instance the host adapter was installed on (the singleton contract). `junction` covers
- * Windows without elevation; a failed link is only logged, since a resolvable ancestor may
- * still exist.
+ * Link THIS runtime's `@boardwalk-labs/workflow` into the exec dir's `node_modules` so the program's
+ * bare import resolves from ANY program root — this link, not an ancestor `node_modules`, is what
+ * makes resolution work. (Worth stating plainly: a stale comment claiming the extraction dir had to
+ * sit under `/app` so the import could walk up to `/app/node_modules` outlived this function by
+ * several versions and sent a later reader chasing a dependency that no longer exists. The live
+ * fleet has no `/app` at all and resolves fine.) A symlink — not a copy — is load-bearing: Node
+ * resolves it to the REAL path, so the program gets the same module instance the host adapter was
+ * installed on (the singleton contract). `junction` covers Windows without elevation; a failed link
+ * is only logged, since a resolvable ancestor may still exist.
  */
 export async function ensureSdkLink(execDir) {
     // A program tarball that ships its own `node_modules/@boardwalk-labs/workflow` would shadow the
@@ -83,19 +88,31 @@ export function resolveEntryPath(dir, entry) {
 }
 /** Scratch filename for the in-flight artifact tarball inside a run's dir. */
 const ARTIFACT_FILE = "__program.tgz";
+/**
+ * Enforce I2: the extracted program must not live inside the run's workspace. Incidental separation
+ * is what broke before — the extraction root used to be `process.cwd()`, so it landed inside the
+ * workspace on exactly the lanes whose cwd was already correct. Compares RESOLVED paths, and treats
+ * "the workspace itself" as inside.
+ */
+export function assertProgramRootOutsideWorkspace(programRoot, workspaceRoot) {
+    const rel = relative(resolve(workspaceRoot), resolve(programRoot));
+    if (rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel))) {
+        throw new AppError(ErrorCode.VALIDATION_FAILED, `The program root "${programRoot}" is inside the workspace "${workspaceRoot}"; the extracted program must live outside it.`);
+    }
+}
 /**
  * Run a workflow program to completion. Installs the host + input, extracts the VERIFIED artifact +
  * dynamic-imports its entry (which runs the body), and returns the terminal result. Always tears the
  * runtime state down and removes the temp tree afterward.
  */
 export async function runWorkflowProgram(args, deps) {
-    const workRoot = deps.workRoot ?? process.cwd();
-    const dir = join(workRoot, RUN_DIR, `${args.runId}-${randomUUID()}`);
+    const dir = join(deps.programRoot, RUN_DIR, `${args.runId}-${randomUUID()}`);
     installHost(deps.host);
     installInput(args.input);
     // The run row's config is arbitrary JSON (jsonb); it IS valid JSON, so narrow to the SDK's JsonValue.
     installConfig(args.config);
     try {
+        assertProgramRootOutsideWorkspace(deps.programRoot, deps.workspaceRoot);
         await mkdir(dir, { recursive: true });
         const tgzPath = join(dir, ARTIFACT_FILE);
         await writeFile(tgzPath, args.tarball);
@@ -112,25 +129,11 @@ export async function runWorkflowProgram(args, deps) {
         // runner may point at an arbitrary control plane, so refuse an entry that could escape the
         // extraction dir (absolute path or `..` segment) before importing it.
         const entryPath = resolveEntryPath(dir, args.entry);
-        // Run the program body. A SUSPEND is surfaced two ways and both land here as a `suspended`
-        // result: (a) out of band via `suspendSignal` — racing the body, immune to a program's own
-        // try/catch (the suspending seam never resolves); (b) a thrown {@link SuspendError} on the
-        // no-`onSuspend` path. Everything else is the program's natural completion / failure.
-        const body = runProgramBody(entryPath, deps);
-        const result = deps.suspendSignal === undefined
-            ? await body
-            : await Promise.race([
-                body,
-                deps.suspendSignal.then((signal) => ({ kind: "suspended", signal })),
-            ]);
-        // If the suspend won the race, the body promise is abandoned (its suspending seam never settles);
-        // swallow any late settle so it can't surface as an unhandled rejection before the process exits.
-        void body.catch(() => undefined);
-        return result;
+        // Run the program body to its natural completion / failure. A waiting seam freezes with the
+        // VM (snapshot substrate) or holds the process — either way the body's own await continues.
+        return await runProgramBody(entryPath, deps);
     }
     catch (err) {
-        if (err instanceof SuspendError)
-            return { kind: "suspended", signal: err.signal };
         const redactText = deps.redactText ?? ((s) => s);
         // Redact BEFORE both sinks: the message can carry a secret the program resolved then threw.
         const message = redactText(err instanceof Error ? err.message : String(err));
@@ -157,17 +160,45 @@ export async function runWorkflowProgram(args, deps) {
 }
 /**
  * Import (= run) the program entry and capture its declared output. Resolves to a `completed`
- * result; a program failure (or a {@link SuspendError} on the no-`onSuspend` path) THROWS and is
- * handled by the caller. A unique dir per run gives a fresh URL so the module cache never returns an
- * already-run program; `@vite-ignore` keeps vitest/vite from statically analyzing the runtime URL.
+ * result; a program failure THROWS and is handled by the caller. A unique dir per run gives a
+ * fresh URL so the module cache never returns an already-run program; `@vite-ignore` keeps
+ * vitest/vite from statically analyzing the runtime URL.
+ *
+ * The chdir to the workspace (I1) happens HERE, at the boundary where author code starts, and only
+ * after the artifact is extracted from {@link ProgramRunnerDeps.programRoot} — so the program's
+ * files land in the workspace while the bundle stays out of it. Module resolution is unaffected:
+ * Node resolves file-relative (the entry is imported by absolute URL, the SDK via `ensureSdkLink`),
+ * never cwd-relative. The engine's local path has run exactly this shape since dev-on-engine
+ * (`boardwalk/src/run/child.ts`), and the self-hosted daemon spawns with the same cwd.
  */
 async function runProgramBody(entryPath, deps) {
-    await import(/* @vite-ignore */ pathToFileURL(entryPath).href);
-    // The program declares its result via `output(value)` (top-level code can't `return`); null when it
-    // never called it. This becomes the run's persisted output + a `workflows.call` parent's value, and
-    // (when actually declared) an `output` entry in the run's activity log.
-    const declared = takeDeclaredOutput();
-    if (declared !== null)
-        deps.onOutput?.(declared.value);
-    return { kind: "completed", output: declared !== null ? declared.value : null };
+    const callerCwd = process.cwd();
+    try {
+        process.chdir(deps.workspaceRoot);
+    }
+    catch (err) {
+        // Fail loud. Running author code from an arbitrary cwd is what silently threw writes away.
+        throw new AppError(ErrorCode.VALIDATION_FAILED, `The run's workspace "${deps.workspaceRoot}" is not usable as the working directory: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        await import(/* @vite-ignore */ pathToFileURL(entryPath).href);
+        // The program declares its result via `output(value)` (top-level code can't `return`); null when it
+        // never called it. This becomes the run's persisted output + a `workflows.call` parent's value, and
+        // (when actually declared) an `output` entry in the run's activity log.
+        const declared = takeDeclaredOutput();
+        if (declared !== null)
+            deps.onOutput?.(declared.value);
+        return { kind: "completed", output: declared !== null ? declared.value : null };
+    }
+    finally {
+        // One run per process in production, so this matters for tests + the local/dev path — but a
+        // function that permanently moves its caller's cwd is a trap either way. Best-effort: the caller's
+        // dir may itself be gone, and that must not mask the run's real outcome.
+        try {
+            process.chdir(callerCwd);
+        }
+        catch {
+            /* the caller's cwd vanished mid-run; nothing useful to do */
+        }
+    }
 }

package/dist/runtime/program_worker.d.ts

@@ -3,7 +3,6 @@ import { type WorkflowManifest } from "./wire/manifest.js";
 import type { WorkflowHost } from "@boardwalk-labs/workflow/runtime";
 import type { SecretRedactor } from "./agent/secret_redactor.js";
 import { type LogStream } from "./program_log_capture.js";
-import type { SuspendSignal } from "./suspension.js";
 /** Default 5-minute lease (matches the engine spec). */
 export declare const DEFAULT_LEASE_MS: number;
 /** Race-safe claim surface — RunRepository satisfies it. */
@@ -44,13 +43,6 @@ export type RuntimeMeterStarter = (args: {
 export interface RunFinalizer {
     finalize(runId: string, status: "completed" | "failed", output: unknown): Promise<void>;
 }
-/** Persists a durable SUSPENSION (the durable-suspension design): the broker records the wake condition (a
- *  pending/suspended journal entry + a human-input request row for HITL, or the wake time for a long
- *  sleep), flips the run to its suspended status, and releases the lease — all transactionally. The
- *  run is NOT finalized; a wake (an answer, a child finalize, or a timer) re-dispatches it. */
-export interface RunSuspender {
-    suspend(signal: SuspendSignal, workerId: string): Promise<void>;
-}
 /** Restores/snapshots the workflow's persistent `/workspace`. Best-effort — both no-op when the
  *  run isn't eligible (not opted-in / self-hosted), and neither throws. */
 export interface WorkspaceHandle {
@@ -93,10 +85,6 @@ export type ProgramHostBuilder = (run: Run, manifest: WorkflowManifest, signal:
      *  leaf can resolve this run's bundled skill files (`<dir>/skills/<name>.md`). The orchestrator wires
      *  it to the runner's `onExtracted`. Optional — absent on paths that don't surface bundled files. */
     setProgramDir?: (dir: string) => void;
-    /** Resolves when a host seam SUSPENDS the run — wired to the host's `onSuspend`, threaded into the
-     *  program runner so a suspend short-circuits the body out of band (the durable-suspension design). Absent ⇒
-     *  no durable suspension on this path (a suspend then surfaces as a thrown SuspendError). */
-    suspendSignal?: Promise<SuspendSignal>;
     /** The run's browser-session manager (browser tier). The orchestrator reaps every still-open session
      *  on EVERY terminal path so no Chromium / Playwright MCP process leaks past the run. `closeAll` is
      *  best-effort + never throws. Absent on images without the browser stack. */
@@ -140,6 +128,11 @@ export type LeaseWatchStarter = (args: {
 export interface ProgramWorkerDeps {
     runs: RunClaimer;
     versions: ProgramVersionReader;
+    /** The run's `/workspace` — cwd + HOME for author code (docs/WORKSPACE_PERSISTENCE.md I1), and the
+     *  tree `workspace.persist` archives. Passed through to the program runner. */
+    workspaceRoot: string;
+    /** Where the program artifact extracts — OUTSIDE the workspace (I2). Passed through to the runner. */
+    programRoot: string;
     /** Download the program artifact bytes from the broker's presigned URL (broker.downloadBytes). */
     fetchProgram: (downloadUrl: string) => Promise<Uint8Array>;
     /** Extract a gzipped tar into a dir (system `tar`); passed through to the program runner. */
@@ -154,9 +147,6 @@ export interface ProgramWorkerDeps {
     /** Periodic runtime metering (optional — absent disables it, e.g. the local/test path). */
     startRuntimeFlush?: RuntimeMeterStarter;
     finalizer: RunFinalizer;
-    /** Persists a durable suspension (the durable-suspension design). Absent ⇒ no suspension support: a run that
-     *  reaches a suspend fails cleanly rather than stranding (the brokered worker always wires it). */
-    suspender?: RunSuspender;
     buildHost: ProgramHostBuilder;
     /** Starts mid-run credit watching for the session (optional — absent disables it). */
     startCreditWatch?: CreditWatchStarter;
@@ -183,8 +173,5 @@ export type ProgramWorkerOutcome = {
 } | {
     kind: "failed";
     reason: string;
-} | {
-    kind: "suspended";
-    reason: string;
 };
 export declare function runProgramWorker(runId: string, deps: ProgramWorkerDeps): Promise<ProgramWorkerOutcome>;

package/dist/runtime/program_worker.js

@@ -110,7 +110,7 @@ export async function runProgramWorker(runId, deps) {
         log.error("worker_host_build_failed", { runId, error: message });
         return { kind: "failed", reason: "host_build_failed" };
     }
-    const { host, redactor, workspace, phases, activity, setProgramDir, lsp, suspendSignal } = built;
+    const { host, redactor, workspace, phases, activity, setProgramDir, lsp } = built;
     const browserSessions = built.browserSessions;
     const capture = built.capture;
     // Guarantee the /workspace sandbox dir exists for EVERY run (persist or not) so a program can write
@@ -190,10 +190,11 @@ export async function runProgramWorker(runId, deps) {
         // onOutput emits the `output` activity entry into the run's log when the program declared one.
         {
             host,
+            workspaceRoot: deps.workspaceRoot,
+            programRoot: deps.programRoot,
             redactText: (text) => redactor.redactText(text),
             extract: deps.extractArchive,
             ...(setProgramDir !== undefined ? { onExtracted: setProgramDir } : {}),
-            ...(suspendSignal !== undefined ? { suspendSignal } : {}),
             ...(activity !== undefined
                 ? {
                     onOutput: (value) => {
@@ -268,24 +269,6 @@ export async function runProgramWorker(runId, deps) {
         log.info("worker_run_aborted", { runId, reason });
         return { kind: "failed", reason };
     }
-    // Suspended: a host seam released the task (a long `sleep`, a `humanInput()` gate, or the in-leaf
-    // `human_input` tool). Persist the wake condition through the broker — NO finalize — and exit
-    // cleanly; a wake (an answer or a timer) re-dispatches the run, which restarts from the top and
-    // replays the journal past the already-done seams. The runtime tail for THIS session was booked
-    // above, so idle time while suspended is not billed. Phases stay open (the run is non-terminal).
-    if (result.kind === "suspended") {
-        if (deps.suspender === undefined) {
-            phases?.close("failed");
-            await deps.finalizer.finalize(runId, "failed", {
-                error: { code: "SUSPEND_UNSUPPORTED", message: "This runtime cannot suspend a run." },
-            });
-            log.error("worker_suspend_unsupported", { runId });
-            return { kind: "failed", reason: "suspend_unsupported" };
-        }
-        await deps.suspender.suspend(result.signal, deps.workerId);
-        log.info("worker_suspended", { runId, reason: result.signal.reason });
-        return { kind: "suspended", reason: result.signal.reason };
-    }
     if (result.kind === "completed") {
         phases?.close("completed");
         await deps.finalizer.finalize(runId, "completed", result.output);

package/dist/runtime/runner_control_client.d.ts

@@ -1,6 +1,5 @@
 import type { McpTokenResult } from "@boardwalk-labs/engine/core";
 import type { Run } from "./wire/run.js";
-import { type JournalKind, type JournalLookup, type JournalSeam, type SuspendSignal } from "./suspension.js";
 import type { WebSearchOutput } from "./tools/web_search.js";
 import type { ArtifactCommitInput, ArtifactPresignInput, ArtifactPresignResult, ArtifactSignResult, ArtifactSummary, ArtifactWriteInput, ArtifactWriteResult } from "./tools/artifacts.js";
 import { type InferenceFrame, type InferenceProxyRequest } from "./wire/inference_proxy.js";
@@ -61,7 +60,7 @@ export declare class RunnerControlClient {
     /** Swap the bearer for a fresh run token (the wake path). Every subsequent call uses it. */
     swapRunToken(token: string): void;
     /**
-     * Every SHORT control call (claim / renew / cancel / credit / journal / …) goes through here so
+     * Every SHORT control call (claim / renew / cancel / credit / inputs / …) goes through here so
      * it carries a hard timeout. Without one, a poll frozen mid-flight on the snapshot substrate
      * hangs FOREVER on restore (the socket is dead but never reset), and since a watcher serializes
      * its ticks, one hung tick wedges that watcher — the dead-connections gotcha for the
@@ -78,7 +77,7 @@ export declare class RunnerControlClient {
      * reset/refused mid-rollover, our own per-attempt timeout on a dead socket) and the
      * load-balancer's {@link RETRYABLE_STATUSES}. Safe to re-send because every caller's body is a
      * reusable string/byte-array (the streaming inference call bypasses this entirely), and the
-     * broker's mutating endpoints are idempotent per worker/identifier (journal seq, usage
+     * broker's mutating endpoints are idempotent per worker/identifier (gate seq, usage
      * identifier, lease per workerId). Before this, ONE blip during an api-server deploy rollover
      * crashed the worker hard mid-suspend/finalize and only crash-reclaim recovered the run.
      */
@@ -88,7 +87,6 @@ export declare class RunnerControlClient {
     claim(workerId: string, leaseSeconds: number): Promise<{
         run: Run;
         lastEventCursor: number;
-        lastJournalSeq: number;
     } | null>;
     /** Heartbeat: extend our lease so a long run isn't reclaimed mid-flight. Returns the new
      *  `leaseUntil`, or null when the lease was lost (409 — another worker reclaimed the run), which
@@ -98,24 +96,6 @@ export declare class RunnerControlClient {
      *  whose lease expired and whose run was reclaimed + re-dispatched to a new owner), so a
      *  hung/partitioned worker that later recovers can't clobber the live run or revive a terminal one. */
     finalize(status: "completed" | "failed", output: unknown, workerId: string): Promise<void>;
-    /** Look up a durable-seam journal entry by its seq (the durable-suspension design), or null on a replay miss
-     *  (404). The broker joins a parked agent leaf's answers into the result server-side. */
-    journalGet(seq: number): Promise<JournalLookup | null>;
-    /** Record a RESOLVED seam result (idempotent on the run + seq server-side; a resolved entry is
-     *  immutable). The broker writes the memoized value the next replay returns. */
-    journalPut(entry: {
-        seq: number;
-        kind: JournalKind;
-        fingerprint: string;
-        label: string;
-        result: unknown;
-    }): Promise<void>;
-    /** Persist a durable SUSPENSION: the broker records the wake condition (a pending/suspended journal
-     *  entry + a human-input request row for HITL, or the wake time for a long sleep), flips the run to
-     *  its suspended status, and releases the lease — transactionally. No finalize; a wake re-dispatches. */
-    suspend(signal: SuspendSignal, workerId: string): Promise<void>;
-    /** The {@link JournalSeam} the worker host reads/writes — a thin adapter over the broker methods. */
-    journalSeam(): JournalSeam;
     /** Fetch the run's pinned manifest + program source, or null when the version is missing (404). */
     getVersion(): Promise<BrokerVersion | null>;
     /** Book a runtime-seconds DELTA (the worker's RuntimeFlusher → broker). `identifier` makes a

package/dist/runtime/runner_control_client.js

@@ -11,7 +11,6 @@
 // failures (thrown network errors, LB 502/503/504 — a control-plane deploy rollover) are retried
 // with backoff first, so a blip heals in place instead of crashing the run.
 import { createLogger } from "./support/index.js";
-import { journalLookupSchema, } from "./suspension.js";
 import { INFERENCE_NDJSON_CONTENT_TYPE, parseInferenceFrame, serializeInferenceRequest, } from "./wire/inference_proxy.js";
 const log = createLogger("RunnerControlClient");
 /**
@@ -49,7 +48,7 @@ export class RunnerControlClient {
         this.runToken = token;
     }
     /**
-     * Every SHORT control call (claim / renew / cancel / credit / journal / …) goes through here so
+     * Every SHORT control call (claim / renew / cancel / credit / inputs / …) goes through here so
      * it carries a hard timeout. Without one, a poll frozen mid-flight on the snapshot substrate
      * hangs FOREVER on restore (the socket is dead but never reset), and since a watcher serializes
      * its ticks, one hung tick wedges that watcher — the dead-connections gotcha for the
@@ -70,7 +69,7 @@ export class RunnerControlClient {
      * reset/refused mid-rollover, our own per-attempt timeout on a dead socket) and the
      * load-balancer's {@link RETRYABLE_STATUSES}. Safe to re-send because every caller's body is a
      * reusable string/byte-array (the streaming inference call bypasses this entirely), and the
-     * broker's mutating endpoints are idempotent per worker/identifier (journal seq, usage
+     * broker's mutating endpoints are idempotent per worker/identifier (gate seq, usage
      * identifier, lease per workerId). Before this, ONE blip during an api-server deploy rollover
      * crashed the worker hard mid-suspend/finalize and only crash-reclaim recovered the run.
      */
@@ -120,9 +119,6 @@ export class RunnerControlClient {
         return {
             run: body.run,
             lastEventCursor: body.lastEventCursor ?? 0,
-            // The replay frontier for silent replay (the durable-suspension design): the highest journaled seq, so a
-            // resumed run knows which seams already ran (suppress their re-emitted observability).
-            lastJournalSeq: body.lastJournalSeq ?? 0,
         };
     }
     /** Heartbeat: extend our lease so a long run isn't reclaimed mid-flight. Returns the new
@@ -153,49 +149,6 @@ export class RunnerControlClient {
         if (res.status !== 204)
             throw await brokerError(res, "finalize");
     }
-    /** Look up a durable-seam journal entry by its seq (the durable-suspension design), or null on a replay miss
-     *  (404). The broker joins a parked agent leaf's answers into the result server-side. */
-    async journalGet(seq) {
-        const res = await this.controlFetch(this.url(`journal/${encodeURIComponent(String(seq))}`), {
-            method: "GET",
-            headers: this.headers(false),
-        });
-        if (res.status === 404)
-            return null;
-        if (res.status !== 200)
-            throw await brokerError(res, "journal-get");
-        return journalLookupSchema.parse(await res.json());
-    }
-    /** Record a RESOLVED seam result (idempotent on the run + seq server-side; a resolved entry is
-     *  immutable). The broker writes the memoized value the next replay returns. */
-    async journalPut(entry) {
-        const res = await this.controlFetch(this.url("journal"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify(entry),
-        });
-        if (res.status !== 204)
-            throw await brokerError(res, "journal-put");
-    }
-    /** Persist a durable SUSPENSION: the broker records the wake condition (a pending/suspended journal
-     *  entry + a human-input request row for HITL, or the wake time for a long sleep), flips the run to
-     *  its suspended status, and releases the lease — transactionally. No finalize; a wake re-dispatches. */
-    async suspend(signal, workerId) {
-        const res = await this.controlFetch(this.url("suspend"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ ...signal, workerId }),
-        });
-        if (res.status !== 204)
-            throw await brokerError(res, "suspend");
-    }
-    /** The {@link JournalSeam} the worker host reads/writes — a thin adapter over the broker methods. */
-    journalSeam() {
-        return {
-            get: (seq) => this.journalGet(seq),
-            put: (entry) => this.journalPut(entry),
-        };
-    }
     /** Fetch the run's pinned manifest + program source, or null when the version is missing (404). */
     async getVersion() {
         const res = await this.controlFetch(this.url("version"), {

package/dist/runtime/suspension.d.ts

@@ -1,20 +1,21 @@
-import { z } from "zod";
-import type { LeafCheckpoint, LeafResume } from "@boardwalk-labs/engine/core";
-import { AppError } from "./support/index.js";
+import type { LeafCheckpoint } from "@boardwalk-labs/engine/core";
 /**
- * Sleeps at/above this hold-vs-release boundary SUSPEND (release the task; a timer re-dispatches the
- * run when due); shorter ones HOLD the process in-memory, where a release + replay round-trip costs
- * more than it saves. Mirrors the engine's `SUSPEND_THRESHOLD_MS` so the two runtimes draw the line
- * in the same place.
+ * Sleeps at/above this boundary SUSPEND on the snapshot substrate (freeze the VM; the wake fires
+ * when the sleep is due); shorter ones HOLD the process in-memory, where a snapshot round-trip
+ * costs more than it saves. Without a freeze substrate every sleep holds, whatever its length.
  */
 export declare const SUSPEND_THRESHOLD_MS = 30000;
-/** The durable-seam kinds the journal memoizes (mirrors `run_journal.kind` + the engine's IPC). */
-export type JournalKind = "agent" | "step" | "human_input" | "sleep" | "workflow_call";
-/** Why a seam suspended the run. */
-export type SuspendReason = "human_input" | "sleep" | "workflow_call";
+/**
+ * Why a seam suspended the run. `budget` is the odd one out: it is NOT a seam the program called but
+ * an involuntary park — the run hit its `max_usd` cap and is waiting for a person to approve more
+ * spend (docs/SUSPEND_POLICY.md Decision 3). It still carries a `humanInput` gate (key `budget`), so
+ * the control plane persists, surfaces, and answers it exactly like any other gate; only the reason
+ * differs, which is what lets the UI say "budget" instead of "waiting on a human".
+ */
+export type SuspendReason = "human_input" | "sleep" | "workflow_call" | "budget";
 /** A human-in-the-loop gate carried out of a suspending seam (program-level or the in-leaf tool). */
 export interface HumanInputGate {
-    /** The stable key the responder answers by (an author/seq key, or the model's tool-call id). */
+    /** The stable key the responder answers by (an author/derived key, or the model's tool-call id). */
     key: string;
     prompt: string;
     /** The response form ({@link import("@boardwalk-labs/workflow").HumanInputSpec}); validated on submit. */
@@ -29,13 +30,14 @@ export interface HumanInputGate {
 /** Everything the broker needs to persist a suspension + the wake condition. */
 export interface SuspendSignal {
     reason: SuspendReason;
-    /** The journal seq of the suspending seam. */
+    /** The suspension's within-run key (a monotonic per-run counter): it keys the HITL gate rows the
+     *  wake joins answers from. Not a journal seq — there is no journal. */
     seq: number;
-    /** The seam's determinism fingerprint (recorded on the pending journal entry). */
-    fingerprint: string;
     /** Present for `reason: "human_input"` — the gate to register a request row for. */
     humanInput?: HumanInputGate;
-    /** A tool-level gate's leaf transcript checkpoint, stored so the leaf resumes where it paused. */
+    /** A tool-level gate's leaf transcript checkpoint. On the snapshot substrate the transcript
+     *  rides in the frozen heap — this field is informational for the control plane, not a resume
+     *  source. */
     leafCheckpoint?: LeafCheckpoint;
     /** Relative wait (ms) for `reason: "sleep"`; the broker computes the absolute wake time. */
     durationMs?: number;
@@ -43,99 +45,8 @@ export interface SuspendSignal {
      *  woken when this child finalizes (the sweep wakes a parent whose child is terminal). */
     childRunId?: string;
 }
-/**
- * The control signal a host seam raises to suspend the run. Unlike the engine (a child process the
- * supervisor kills out-of-band), the backend worker runs the program IN-PROCESS, so a suspend is
- * surfaced by the host calling `onSuspend(signal)` and returning a NEVER-resolving promise; the
- * worker races that against the program body and tears down. This class exists so a seam that has no
- * `onSuspend` wired (the local/test path) can still raise a typed, catchable signal.
- */
-export declare class SuspendError extends Error {
-    readonly signal: SuspendSignal;
-    constructor(signal: SuspendSignal);
-}
-/** Journal-entry states (mirrors `run_journal.state` + the engine's IPC). */
-export declare const JOURNAL_STATES: readonly ["pending", "suspended", "resolved"];
-export type JournalEntryState = (typeof JOURNAL_STATES)[number];
-/** A memoized journal entry, as the host reads it back on replay (mirrors the engine's IPC shape). */
-export interface JournalLookup {
-    seq: number;
-    kind: JournalKind;
-    fingerprint: string;
-    /** `resolved` ⇒ `result` is the memoized value; `suspended` ⇒ a parked agent leaf (result is the
-     *  {@link LeafResume} the host re-enters with); `pending` ⇒ awaiting an external event (re-suspend). */
-    state: JournalEntryState;
-    result: unknown;
-}
-/** Validate the broker's journal_get response (the worker's run token doesn't exempt the channel from
- *  validation). The result is genuinely heterogeneous JSON (an agent return / a LeafResume / a
- *  HumanInputResult), parsed per-kind downstream — so it stays `unknown` here, the validation seam. */
-export declare const journalLookupSchema: z.ZodObject<{
-    seq: z.ZodNumber;
-    kind: z.ZodEnum<{
-        sleep: "sleep";
-        agent: "agent";
-        step: "step";
-        human_input: "human_input";
-        workflow_call: "workflow_call";
-    }>;
-    fingerprint: z.ZodString;
-    state: z.ZodEnum<{
-        pending: "pending";
-        suspended: "suspended";
-        resolved: "resolved";
-    }>;
-    result: z.ZodUnknown;
-}, z.core.$strip>;
-/** The journal the host reads (replay lookup) + writes (resolved seam results). Backed by the broker
- *  over the run token on hosted runs; absent on the local/test path (no durable suspension). */
-export interface JournalSeam {
-    /** The memoized entry for a seam, or null on a replay miss. */
-    get(seq: number): Promise<JournalLookup | null>;
-    /** Record a RESOLVED seam result (idempotent on the run + seq; a resolved entry is immutable). */
-    put(entry: {
-        seq: number;
-        kind: JournalKind;
-        fingerprint: string;
-        label: string;
-        result: unknown;
-    }): Promise<void>;
-}
-/**
- * The synchronous, monotonic durable-seam counter. Incremented at each journaled seam's ENTRY:
- * because a program's synchronous call order is deterministic (even under `Promise.all`, whose
- * `.map(...)` runs left-to-right synchronously), the same logical call gets the same `seq` on every
- * execution — the journal key that lets a resumed run return a memoized result.
- *
- * It also drives SILENT REPLAY: a resume starts suppressed (observability — console output, phase
- * markers — was already emitted last segment) and goes `live` the moment it reaches the suspending
- * seam (the frontier = the highest journaled seq). A fresh run (frontier 0) is live immediately.
- */
-export declare class SeamSequencer {
-    private readonly replayFrontier;
+/** A monotonic per-run counter for suspension/gate keys (the `seq` on {@link SuspendSignal}). */
+export declare class SuspensionCounter {
     private count;
-    private liveFlag;
-    constructor(replayFrontier?: number);
     next(): number;
-    /** True once execution has crossed the replay frontier — output after this point is NEW. */
-    get isLive(): boolean;
-    /** True while re-running already-journaled seams on a resume (observability suppressed). */
-    isReplaying(): boolean;
 }
-/** The child run id a `workflow_call` seam journals while it waits (parsed back on resume). */
-export declare const childRunIdSchema: z.ZodString;
-/** A stable content hash of a seam's salient args — the determinism check on replay. Identical
- *  construction to the engine's `seamFingerprint` so a journal written by one runtime validates in
- *  the other (the conformance promise). */
-export declare function seamFingerprint(parts: readonly unknown[]): string;
-/** A seam reached on replay didn't match what the journal recorded at that seq — the workflow's code
- *  on the path to a suspend changed (a different prompt/model/step name, or a different seam kind).
- *  Fails the run loudly rather than returning a stale memoized result for the wrong call. */
-export declare function determinismError(seq: number, got: JournalKind, recorded: JournalKind): AppError;
-/**
- * The shape of a SUSPENDED agent leaf's journal result on resume: the transcript checkpoint plus the
- * answers the broker joined from the resolved request rows, keyed by tool-call id. `messages` is the
- * engine's own serialized transcript round-tripping through JSON — handed straight back to the leaf,
- * not re-validated field-by-field. Structurally a {@link LeafResume}.
- */
-export declare const leafResumeSchema: z.ZodType<LeafResume>;