@boardwalk-labs/runner 0.1.21 → 0.2.1

package/dist/runtime/index.js

@@ -34,6 +34,7 @@ import { BUDGET_GUARDRAIL_RATE } from "./agent/model_rates.js";
 import { SecretRedactor } from "./agent/secret_redactor.js";
 import { RecordingSecretResolver } from "./recording_secret_resolver.js";
 import { EngineLeafExecutor } from "./leaf_executor.js";
+import { BudgetGate } from "./budget_gate.js";
 import { parseByoProviders } from "./direct_inference.js";
 import { applyIdentityToEnv, connectIdentityRelayFd, relayFdFromEnv, workerDiagnostics, } from "./identity_relay.js";
 import { FreezeCoordinator } from "./freeze_coordinator.js";
@@ -56,10 +57,12 @@ import { CreditWatcher } from "./credit_watcher.js";
 import { CancelWatcher } from "./cancel_watcher.js";
 import { LeaseRenewer } from "./lease_renewer.js";
 import { RuntimeFlusher } from "./runtime_flusher.js";
-import { WorkspaceStore, TarWorkspaceArchiver, NodeWorkspaceFs } from "./workspace_store.js";
+import { WorkspaceStore, TarWorkspaceArchiver, NodeWorkspaceFs, resolvePersistSelection, } from "./workspace_store.js";
+import { LocalWorkspaceStore } from "./local_workspace_store.js";
 import { PhaseTracker } from "./phase_tracker.js";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { tmpdir } from "node:os";
 const log = createLogger("worker_entrypoint");
 /** Durable events are deferred (durable event storage) — live fan-out via the broker only. */
 /** Synthesize the run's AuthContext. The run was already authorized at trigger time; the
@@ -99,10 +102,6 @@ export function assembleWorkerDeps(runtime) {
         runId: runtime.runId,
     });
     log.info("runner_control_enabled", { runId: runtime.runId });
-    // The replay frontier (the highest journaled seq at claim) drives SILENT REPLAY (the durable-suspension design):
-    // 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
@@ -239,6 +238,20 @@ export function assembleWorkerDeps(runtime) {
         // it). Workspace-rooted at the same `/workspace` the leaf + tools use. Closed on the run's teardown
         // (returned below as `lsp` → program_worker's finally) so no language-server process leaks.
         const lspService = new LspService({ workspaceDir: runtime.workspaceRoot });
+        // Budget gate (docs/SUSPEND_POLICY.md Decision 3): a `max_usd` breach PARKS the run for approval
+        // instead of failing it. The gate needs the HOST (to park) but the host is constructed below with
+        // `leaf` — a genuine cycle, broken with a late-bound ref: `clear()` only ever runs mid-run, long
+        // after both exist. Wired to `budgetHost` immediately after the host is built.
+        let budgetHost = null;
+        const budgetGate = new BudgetGate(budget, {
+            budgetClearance: (gate) => {
+                if (budgetHost === null) {
+                    // Unreachable in a real run; a loud error beats parking against a null host.
+                    return Promise.reject(new Error("budget gate reached before the workflow host was wired"));
+                }
+                return budgetHost.budgetClearance(gate);
+            },
+        });
         const leaf = new EngineLeafExecutor({
             inference: broker,
             // Direct BYO (D7): the claim's registry + the run's RECORDING resolver, so a provider key
@@ -252,10 +265,14 @@ export function assembleWorkerDeps(runtime) {
                 }
                 : {}),
             budget,
+            budgetGate,
             redactor,
             toolHost,
             lspService,
             workspaceRoot: runtime.workspaceRoot,
+            // Register every memory dir the run uses, so the workspace store persists it with no manifest
+            // declaration (WORKSPACE_PERSISTENCE.md §3). Read back by the store's `selection` thunk.
+            onMemoryUsed: (dir) => memoryDirs.add(dir),
             // Resolve this run's deployed `skills/` dir for `agent({ skills })` — the engine reads
             // `<skillsDir>/<name>.md`, so it's the `skills` subdir of the extracted program tree (filled
             // once the artifact extracts). Null until then / when no program dir is known.
@@ -293,24 +310,35 @@ export function assembleWorkerDeps(runtime) {
             // comes from the org's connection vault via the Runner Control API — never stored on the worker.
             brokerMcpToken: (serverUrl, invalidateToken) => broker.mcpToken(serverUrl, invalidateToken),
         });
-        // Per-workflow persistent /workspace: only when the manifest opts in. The BROKER additionally
-        // gates on hosted (self-hosted runs get null URLs), and snapshots are keyed per-workflow + scoped
-        // by the run token — so even the untrusted in-process program can't reach another tenant's data.
-        const workspaceStore = manifest.workspace?.persist === true
-            ? new WorkspaceStore({
+        // Per-workflow persistent /workspace (docs/WORKSPACE_PERSISTENCE.md §3). Constructed on EVERY
+        // run, NOT gated on the manifest: `agent({ memory })` persists with no declaration at all, and a
+        // memory dir is only known once the run has made the call — so a construction-time manifest gate
+        // (the old `persist === true`) silently dropped BOTH the list form and every memory dir. What to
+        // write is decided at persist time by `resolvePersistSelection`; a run that selects nothing does
+        // no fs or broker work. The BROKER still gates eligibility (hosted-only; self-hosted gets null
+        // URLs), and snapshots are keyed per workflow + environment and scoped by the run token — so even
+        // the untrusted in-process program can't reach another tenant's, or another environment's, data.
+        const memoryDirs = new Set();
+        const selection = () => resolvePersistSelection(manifest.workspace?.persist, memoryDirs);
+        // TWO stores, ONE contract (WORKSPACE_PERSISTENCE.md I3): `runs_on` decides WHERE the bytes live,
+        // never WHETHER persistence happens. A runner with its OWN durable root (a self-hosted daemon,
+        // which sets PERSIST_ROOT) keeps state on the customer's disk and never touches our S3 — the
+        // broker returns null URLs for self-hosted runs by design. Hosted runners have no local disk that
+        // outlives the VM, so they push a tarball through the broker. Before this, "don't upload it" was
+        // implemented as "don't persist it", so self-hosted runs silently forgot everything.
+        const workspaceStore = runtime.persistScopeDir !== undefined
+            ? new LocalWorkspaceStore({
+                scopeDir: runtime.persistScopeDir,
+                workspaceRoot: runtime.workspaceRoot,
+                selection,
+            })
+            : new WorkspaceStore({
                 broker,
                 archiver: new TarWorkspaceArchiver(),
                 fs: new NodeWorkspaceFs(),
                 workspaceRoot: runtime.workspaceRoot,
-            })
-            : undefined;
-        // Durable suspension (the durable-suspension design): the host raises a suspend OUT OF BAND (onSuspend +
-        // a never-resolving seam), so a program's own try/catch can't swallow it; the program runner
-        // races `suspendSignal` against the body. One deferred per run — the first seam to suspend wins.
-        let resolveSuspend = () => undefined;
-        const suspendSignal = new Promise((resolve) => {
-            resolveSuspend = resolve;
-        });
+                selection,
+            });
         // The run's identity + on-demand public-API bearer, surfaced to the program via `import { runtime }`.
         // ids come from the claimed run; the bearer is the captured (scrubbed-from-env) api token, already
         // recorded in this run's redactor above — so threading it into an MCP header keeps it out of LLM
@@ -341,13 +369,6 @@ export function assembleWorkerDeps(runtime) {
             runtime: runtimeContext,
             // workflows.call → broker /children (resolve + callable_by gate server-side), bound to THIS run.
             children: new BrokerChildDispatcher({ client: broker }),
-            // The durable-seam journal (memoization + replay) over the broker; the replay frontier drives
-            // silent replay; onSuspend resolves the deferred the program runner races.
-            journal: broker.journalSeam(),
-            replayFrontier,
-            onSuspend: (signal) => {
-                resolveSuspend(signal);
-            },
             // The program's secrets.get(name) → the run's fail-closed RECORDING resolver.
             secrets: { get: (name) => secretResolver.resolve({ name }) },
             // events.emit → broker /events (fan-out server-side).
@@ -366,31 +387,25 @@ export function assembleWorkerDeps(runtime) {
             signal,
             // Snapshot the workspace before a long sleep (crash-during-hold recovery). The byte count
             // is only logged by the store itself.
-            ...(workspaceStore !== undefined
-                ? {
-                    onBeforeSleep: async () => {
-                        await workspaceStore.persist();
-                    },
-                }
-                : {}),
-            // 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).
+            onBeforeSleep: async () => {
+                await workspaceStore.persist();
+            },
+            // Snapshot-substrate suspension: seams freeze in place under the quiescence gate. Absent
+            // (a self-hosted daemon / the Fargate break-glass), waiting seams HOLD the live process.
             ...(freeze !== undefined ? { freeze } : {}),
-            // Register-without-release for held HITL gates — only on the
-            // freeze substrate, backed by the broker's inputs endpoints.
-            ...(freeze !== undefined
-                ? {
-                    heldInput: {
-                        register: (seq, gate) => broker.registerInput(seq, gate),
-                        poll: (seq) => broker.pollInputAnswers(seq),
-                    },
-                }
-                : {}),
+            // Held HITL gates, backed by the broker's inputs endpoints: register-without-release on the
+            // freeze substrate, and the WHOLE gate mechanism (register + poll) on the hold path.
+            heldInput: {
+                register: (seq, gate) => broker.registerInput(seq, gate),
+                poll: (seq) => broker.pollInputAnswers(seq),
+            },
             // Browser tier: `computer.openBrowser()` + `agent({ session })` resolve through this manager
             // (absent ⇒ the host throws "not available on this runner image").
             ...(browserSessions !== undefined ? { browserSessions } : {}),
             phases: phaseTracker,
         });
+        // Close the budget gate's cycle: the leaf (built above) parks THROUGH the host (built just now).
+        budgetHost = host;
         // Late-bind the coordinator's per-run hooks now that the run-scoped objects exist.
         if (freeze !== undefined) {
             const coordinator = freeze;
@@ -402,7 +417,7 @@ export function assembleWorkerDeps(runtime) {
                 onBeforeFreeze: async () => {
                     freezeWallMs = Date.now();
                     await activeFlusher?.flushNow();
-                    await workspaceStore?.persist();
+                    await workspaceStore.persist();
                     // The recorder never spans a snapshot: finalize + upload the in-flight segment before the
                     // freeze (SCREEN_CAPTURE §4.3). Bounded internally, so a slow upload delays, not blocks, it.
                     await capture?.stopAndFlush();
@@ -463,9 +478,10 @@ export function assembleWorkerDeps(runtime) {
             setProgramDir: (dir) => {
                 programDir = dir;
             },
-            // Resolves when a host seam suspends the run; the program runner races it against the body.
-            suspendSignal,
-            ...(workspaceStore !== undefined ? { workspace: workspaceStore } : {}),
+            // Always present now: hydrate must run BEFORE the program, but whether anything compounds
+            // isn't known until the run's agent() calls have registered their memory dirs. A run that
+            // selects nothing persists nothing and pays for nothing (WorkspaceStore.persist returns early).
+            workspace: workspaceStore,
             // The orchestrator reaps every still-open browser session on terminal (kill Chromium + its
             // Playwright MCP) so no browser process leaks past the run.
             ...(browserSessions !== undefined ? { browserSessions } : {}),
@@ -474,6 +490,13 @@ export function assembleWorkerDeps(runtime) {
         });
     };
     return {
+        // The two filesystem coordinates, both explicit (docs/WORKSPACE_PERSISTENCE.md I1/I2). The
+        // workspace is cwd + HOME for author code; the program extracts OUTSIDE it, so no snapshot ever
+        // captures the bundle. Neither is `process.cwd()` — deriving them from it is exactly how the
+        // hosted lanes drifted (the fleet boots bwinit as PID 1 with cwd `/`; Fargate's image left cwd
+        // at `/app`), and how a bundle would land inside a persisted workspace on the lanes that hadn't.
+        workspaceRoot: runtime.workspaceRoot,
+        programRoot: runtime.programRoot,
         runs: {
             // The broker owns the lease duration server-side; convert the absolute lease back to seconds.
             claimForWorker: async (_runId, workerId, leaseUntil, nowMs) => {
@@ -483,8 +506,6 @@ export function assembleWorkerDeps(runtime) {
                 // Order this session's frames after a previous (crashed) session's, then announce the
                 // lifecycle transition the claim IS — the wire's `running` frame.
                 runEvents.resumeAfter(claimed.lastEventCursor);
-                // The replay frontier for a resumed run (0 on a fresh run); buildHost reads it next.
-                replayFrontier = claimed.lastJournalSeq;
                 runEvents.emit({ kind: "run_status", status: "running" });
                 return claimed.run;
             },
@@ -513,12 +534,6 @@ export function assembleWorkerDeps(runtime) {
         finalizer: {
             finalize: (_id, status, output) => broker.finalize(status, output, runtime.workerId),
         },
-        // Durable suspension (the durable-suspension design): persist the wake condition through the broker (journal
-        // entry + a HITL request row, or the wake time for a long sleep) and release the lease — no
-        // finalize. A wake (an answer or a timer) re-dispatches the run.
-        suspender: {
-            suspend: (signal, workerId) => broker.suspend(signal, workerId),
-        },
         // Runtime metering: flush runtime as periodic deltas (+ a terminal tail) through the broker,
         // idempotent per flush, so a long/perpetual run bills as it burns and the credit watcher sees it —
         // not a single charge at terminal (which a never-terminating run never reached). A fresh per-session
@@ -689,6 +704,14 @@ export async function main() {
     const deps = assembleWorkerDeps({
         workerId: process.env.WORKER_ID ?? `worker-${runId}`,
         workspaceRoot: process.env.WORKSPACE_ROOT ?? "/workspace",
+        // Never inside the workspace, and never `process.cwd()` (WORKSPACE_PERSISTENCE.md I2). `tmpdir()`
+        // honors TMPDIR, which the self-hosted daemon points at the per-run dir — so concurrent daemons on
+        // one machine don't collide, and the hosted lanes get the VM's own /tmp.
+        programRoot: process.env.PROGRAM_ROOT ?? join(tmpdir(), "bw-programs"),
+        // Set by the self-hosted daemon only (both isolation lanes); hosted images never set it.
+        ...(process.env.PERSIST_SCOPE_DIR !== undefined
+            ? { persistScopeDir: process.env.PERSIST_SCOPE_DIR }
+            : {}),
         runId,
         controlPlane: platform.controlPlane,
         vcpus: platform.vcpus,

package/dist/runtime/leaf_executor.d.ts

@@ -30,6 +30,21 @@ export interface EngineLeafExecutorDeps {
      *  reports usage after EVERY model call via `reportUsage`; we feed it here and throw on a cap
      *  breach so the loop terminates mid-flight (the budget authority). */
     budget: BudgetMeter;
+    /**
+     * Budget clearance, awaited before EVERY model call (docs/SUSPEND_POLICY.md Decision 3). When the
+     * run's `max_usd` cap is breached this PARKS the run at a gate — the engine just sees a model call
+     * that took a long time, because the VM froze and resumed underneath it — and resolves once a
+     * responder raises the cap. Rejects with `BudgetGateCancelled` if they decline.
+     *
+     * Why here and not at the `reportUsage` breach check below: that callback is synchronous and fires
+     * mid-turn, and per SUSPEND_POLICY Decision 1 a partial turn is never discarded. The model-call
+     * boundary is the first safe place to park, which bounds overrun at one in-flight turn per leaf.
+     *
+     * Absent ⇒ the legacy behavior: a breach fails the run at `reportUsage`.
+     */
+    budgetGate?: {
+        clear(): Promise<void>;
+    };
     /** RUN-level redactor (shared with the secret resolver): every resolved secret value is recorded
      *  here. We seed a fresh engine `Redactor` from it per leaf so the loop scrubs known values out of
      *  the prompt, tool args/results, and transcript before they reach the model. */
@@ -39,6 +54,11 @@ export interface EngineLeafExecutorDeps {
     makeEventSink: EventSinkFactory;
     /** The run's persistent `/workspace` root — memory dirs (`agent({ memory })`) are relative to it. */
     workspaceRoot: string;
+    /** Register a memory dir the run actually used, so the workspace store persists it (§3 of
+     *  docs/WORKSPACE_PERSISTENCE.md). Memory is undeclared by design, so this callback is the ONLY
+     *  signal that the dir must compound — without it a `agent({ memory })`-only workflow silently
+     *  persists nothing, which is exactly what shipped. Optional: absent ⇒ validation only. */
+    onMemoryUsed?: (dir: string) => void;
     /** Resolves the directory holding this run's bundled files (the extracted program tree, where a
      *  skill lives at `skills/<name>.md`). Known only once the artifact is extracted (mid-run), so it's
      *  a thunk. Null / omitted ⇒ a leaf that names `skills` fails loud. */

package/dist/runtime/leaf_executor.js

@@ -104,6 +104,12 @@ export class EngineLeafExecutor {
             // model server-side, invokes the matching adapter, and streams text back; we surface each delta
             // through providerIo.onDelta and return the terminal turn. An aborted run rejects in-flight.
             streamModel: async (req, providerIo) => {
+                throwIfAborted(signal);
+                // Budget clearance BEFORE the spend, not after: if the cap is already breached this parks
+                // the run (freeing the host on the snapshot fleet) until someone approves more. No-op on the
+                // overwhelming majority of calls. Re-check abort afterwards — a park can span a long wait,
+                // and the run may have been cancelled while frozen.
+                await this.deps.budgetGate?.clear();
                 throwIfAborted(signal);
                 return this.streamModel(req, providerIo, signal, redactor, (costMicros) => {
                     pendingCostMicros = (pendingCostMicros ?? 0) + costMicros;
@@ -148,15 +154,18 @@ export class EngineLeafExecutor {
                     leafIndex,
                 });
             },
-            // A memory dir (`agent({ memory })`) is workspace-relative; the run's whole `/workspace` is
-            // already persisted by the worker when the manifest opts in (workspace.persist), so this only
-            // needs to validate the dir is inside the workspace (defense-in-depth) — there is no separate
-            // per-dir snapshot to register. The engine's buildToolSet already shape-validates the path.
+            // A memory dir (`agent({ memory })`) is workspace-relative and is persisted BECAUSE this hook
+            // registers it — memory carries no manifest declaration (`sdk/src/types.ts`), so this is the
+            // only signal the workspace store gets. It used to only validate, on the assumption that the
+            // whole workspace was persisted "when the manifest opts in": true for `persist: true`, and
+            // false for every other case, so memory silently evaporated on hosted runs. Validate first
+            // (defense-in-depth; the engine's buildToolSet already shape-validates), then register.
             memoryUsed: (dir) => {
                 const abs = join(this.deps.workspaceRoot, dir);
                 if (abs !== this.deps.workspaceRoot && !abs.startsWith(this.deps.workspaceRoot + "/")) {
                     throw new EngineError("VALIDATION", `agent() memory dir "${dir}" escapes the workspace.`);
                 }
+                this.deps.onMemoryUsed?.(dir);
             },
             // OAuth bearer brokering for a hosted MCP server. Called REACTIVELY by the engine — only after a
             // server 401s the static `headers` — so static-bearer / no-auth servers never reach here. When

package/dist/runtime/local_workspace_store.d.ts

@@ -0,0 +1,22 @@
+import type { PersistSelection } from "./workspace_store.js";
+/** The durable directory for one scope, under the runner's persist root. */
+export declare function localScopeDir(persistRoot: string, workflowId: string, environmentId: string | null): string;
+export interface LocalWorkspaceStoreDeps {
+    /** This scope's durable directory ({@link localScopeDir}). */
+    scopeDir: string;
+    /** The run's `/workspace` — hydrated into at start, snapshotted from at terminal. */
+    workspaceRoot: string;
+    /** What to persist, read AT PERSIST TIME: the manifest's declaration ∪ the run's memory dirs. */
+    selection: () => PersistSelection;
+}
+export declare class LocalWorkspaceStore {
+    private readonly deps;
+    constructor(deps: LocalWorkspaceStoreDeps);
+    /** Copy this scope's durable state into the run's workspace. No-op on the first run (nothing
+     *  persisted yet). Best-effort, like the hosted store: a restore miss must not fail the run — the
+     *  workflow just re-does filesystem work, exactly as it would without persistence. */
+    hydrate(): Promise<void>;
+    /** Replace this scope's durable state with the run's. Returns the bytes written for the caller's
+     *  logging — 0 on a no-op/failure, mirroring the hosted store's contract. */
+    persist(): Promise<number>;
+}

package/dist/runtime/local_workspace_store.js

@@ -0,0 +1,103 @@
+// LocalWorkspaceStore — per-(workflow, environment) persistent `/workspace` on the RUNNER's OWN disk.
+//
+// The self-hosted half of docs/WORKSPACE_PERSISTENCE.md I3: persistence has the same semantics on
+// every substrate, and only the STORE changes. `runs_on` decides WHERE the bytes live, never WHETHER
+// persistence happens.
+//
+// Hosted runs push a tarball through broker-presigned S3 URLs (workspace_store.ts). A self-hosted
+// runner must never do that — its workspace is the customer's data on the customer's disk, and we
+// don't store it (the broker returns null URLs for self-hosted runs, by design). But the answer to
+// "don't upload it" was "don't persist it at all", so `workspace.persist` and `agent({ memory })`
+// were SILENT no-ops on self-hosted: the same workflow compounded state on dev and hosted, and
+// quietly forgot everything on a self-hosted runner. This is the missing third store — a plain
+// directory tree the daemon owns, mirroring what the OSS engine does locally (boardwalk's
+// run_dir.ts), with no network and no tarball.
+//
+// Layout: <persistRoot>/<workflowId>/<environmentId ?? _base>. Same scope key as the hosted S3 key,
+// for the same reason — one workflow program runs against N environments (§4).
+import { cp, mkdir, rm, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createLogger } from "./support/index.js";
+const log = createLogger("LocalWorkspaceStore");
+/** Directory name standing in for the BASE scope (a run with no environment). An environment id is a
+ *  ULID, so it can never collide with this. */
+const BASE_SCOPE_DIR = "_base";
+/** The durable directory for one scope, under the runner's persist root. */
+export function localScopeDir(persistRoot, workflowId, environmentId) {
+    return join(persistRoot, workflowId, environmentId ?? BASE_SCOPE_DIR);
+}
+export class LocalWorkspaceStore {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Copy this scope's durable state into the run's workspace. No-op on the first run (nothing
+     *  persisted yet). Best-effort, like the hosted store: a restore miss must not fail the run — the
+     *  workflow just re-does filesystem work, exactly as it would without persistence. */
+    async hydrate() {
+        try {
+            if (!(await exists(this.deps.scopeDir)))
+                return; // first run of this scope
+            // The durable root only ever holds what a previous run persisted (declared dirs + memory
+            // dirs), so all of it belongs in the workspace.
+            await cp(this.deps.scopeDir, this.deps.workspaceRoot, { recursive: true });
+            log.info("workspace_hydrated_local", { scopeDir: this.deps.scopeDir });
+        }
+        catch (err) {
+            log.warn("workspace_hydrate_local_failed", { error: errMsg(err) });
+        }
+    }
+    /** Replace this scope's durable state with the run's. Returns the bytes written for the caller's
+     *  logging — 0 on a no-op/failure, mirroring the hosted store's contract. */
+    async persist() {
+        try {
+            const selection = this.deps.selection();
+            if (selection === true) {
+                // The whole workspace compounds: replace the scope wholesale, so a file the run DELETED is
+                // actually gone next run rather than resurrected from the old copy.
+                await rm(this.deps.scopeDir, { recursive: true, force: true });
+                await mkdir(dirname(this.deps.scopeDir), { recursive: true });
+                await cp(this.deps.workspaceRoot, this.deps.scopeDir, { recursive: true });
+                return await dirSize(this.deps.scopeDir);
+            }
+            if (selection.length === 0)
+                return 0; // nothing declared, no memory used — the common case
+            for (const dir of selection) {
+                const source = join(this.deps.workspaceRoot, dir);
+                const target = join(this.deps.scopeDir, dir);
+                // Replace per-dir (not merge) for the same reason as above: a deletion inside a persisted
+                // dir must survive. A declared dir the run never created is simply skipped.
+                await rm(target, { recursive: true, force: true });
+                if (!(await exists(source)))
+                    continue;
+                await mkdir(dirname(target), { recursive: true });
+                await cp(source, target, { recursive: true });
+            }
+            return await dirSize(this.deps.scopeDir);
+        }
+        catch (err) {
+            log.warn("workspace_persist_local_failed", { error: errMsg(err) });
+            return 0;
+        }
+    }
+}
+async function exists(path) {
+    return (await stat(path).catch(() => null)) !== null;
+}
+/** Bytes on disk under `dir` — reported for parity with the hosted store's return, never metered
+ *  (self-hosted storage is the customer's own disk, so it is not our storage counter's business). */
+async function dirSize(dir) {
+    const { readdir } = await import("node:fs/promises");
+    let total = 0;
+    const entries = await readdir(dir, { withFileTypes: true, recursive: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const s = await stat(join(entry.parentPath, entry.name)).catch(() => null);
+        total += s?.size ?? 0;
+    }
+    return total;
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/runtime/program_runner.d.ts

@@ -1,13 +1,14 @@
 import type { WorkflowHost } from "@boardwalk-labs/workflow/runtime";
-import { type SuspendSignal } from "./suspension.js";
 /**
- * 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 declare function ensureSdkLink(execDir: string): Promise<void>;
 /** Resolve the program's entry module inside the extraction dir, refusing any path that escapes it.
@@ -15,6 +16,13 @@ export declare function ensureSdkLink(execDir: string): Promise<void>;
  *  arbitrary control plane, so this is defense-in-depth: an absolute path or a `..` that resolves
  *  outside `dir` throws rather than importing code from elsewhere on the machine. */
 export declare function resolveEntryPath(dir: string, entry: string): string;
+/**
+ * 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 declare function assertProgramRootOutsideWorkspace(programRoot: string, workspaceRoot: string): void;
 export interface RunProgramArgs {
     /** Run id — used for the temp dir path + correlation. */
     runId: string;
@@ -31,6 +39,18 @@ export interface RunProgramArgs {
 export interface ProgramRunnerDeps {
     /** The host adapter the program's hooks delegate to (agent leaf, sleep hold, child calls, secrets). */
     host: WorkflowHost;
+    /**
+     * The run's `/workspace` — the working directory AND `HOME` for author code (I1). Must already
+     * exist (the orchestrator's `ensureWorkspace` guarantees it); a missing workspace fails the run
+     * loudly rather than silently running from wherever the process happened to start.
+     */
+    workspaceRoot: string;
+    /**
+     * Root the program artifact extracts under. MUST be outside {@link workspaceRoot} (I2) — enforced,
+     * because a bundle inside the workspace is tarred into every pre-sleep snapshot and, since each
+     * run's dir name is unique, accumulates there forever.
+     */
+    programRoot: string;
     /**
      * Extract a gzipped tar file into a directory (created already). System `tar` in production
      * (matches WorkspaceArchiver); injected in tests. The artifact's relative layout is preserved so
@@ -43,12 +63,6 @@ export interface ProgramRunnerDeps {
      * (`<dir>/skills/<name>.md`). Optional — the local/test path may omit it.
      */
     onExtracted?: (programDir: string) => void;
-    /**
-     * Root whose tree can resolve `@boardwalk-labs/workflow` (has `node_modules` reachable). The extracted
-     * program lives under here so its bare SDK import resolves to the same package instance the host
-     * was installed on. Defaults to `process.cwd()`.
-     */
-    workRoot?: string;
     /**
      * Scrubs known secret values out of a string (the run's `SecretRedactor.redactText`). Applied to a
      * top-level throw's message before it is logged AND before it is returned to the worker — a program
@@ -63,18 +77,11 @@ export interface ProgramRunnerDeps {
      * throw (a telemetry hiccup can't change the run's result). Absent ⇒ no output entry.
      */
     onOutput?: (value: unknown) => void;
-    /**
-     * Resolves when a host seam SUSPENDS the run (the durable-suspension design) — the worker wires it to the
-     * host's `onSuspend` so a suspend is surfaced OUT OF BAND, racing the program body. The program's
-     * own `try/catch` can't swallow a suspend this way (the suspending seam never resolves; this signal
-     * short-circuits at the runner). Absent ⇒ no suspension wired (a seam that suspends throws
-     * {@link SuspendError} instead, which is caught here just the same).
-     */
-    suspendSignal?: Promise<SuspendSignal>;
 }
-/** Terminal (or suspended) result of running a workflow program. `output` is what the program
- *  declared via `output(value)` (null when it never did); for a failure it's null and `error` is set;
- *  for a suspension the `signal` carries the wake condition (the worker persists it, no finalize). */
+/** Terminal result of running a workflow program. `output` is what the program declared via
+ *  `output(value)` (null when it never did); for a failure it's null and `error` is set. A waiting
+ *  seam (sleep / humanInput / workflows.call) never surfaces here — it freezes with the VM or
+ *  holds the process, and the body simply continues when the wait is over. */
 export type ProgramResult = {
     kind: "completed";
     output: unknown;
@@ -85,9 +92,6 @@ export type ProgramResult = {
         code: string;
         message: string;
     };
-} | {
-    kind: "suspended";
-    signal: SuspendSignal;
 };
 /**
  * Run a workflow program to completion. Installs the host + input, extracts the VERIFIED artifact +