@boardwalk-labs/runner 0.2.0 → 0.2.1

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,12 +1,14 @@
 import type { WorkflowHost } from "@boardwalk-labs/workflow/runtime";
 /**
- * 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.
@@ -14,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;
@@ -30,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
@@ -42,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

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,15 +13,19 @@
 // `@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";
@@ -31,13 +35,15 @@ 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
@@ -82,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);
@@ -145,14 +163,42 @@ export async function runWorkflowProgram(args, deps) {
  * 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

@@ -128,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. */

package/dist/runtime/program_worker.js

@@ -190,6 +190,8 @@ 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 } : {}),

package/dist/runtime/suspension.d.ts

@@ -5,8 +5,14 @@ import type { LeafCheckpoint } from "@boardwalk-labs/engine/core";
  * costs more than it saves. Without a freeze substrate every sleep holds, whatever its length.
  */
 export declare const SUSPEND_THRESHOLD_MS = 30000;
-/** 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/derived key, or the model's tool-call id). */

package/dist/runtime/workflow_host.d.ts

@@ -45,8 +45,6 @@ export interface ChildDispatcher {
     call(slug: string, input: unknown, opts: CallOptions | undefined, signal?: AbortSignal): Promise<unknown>;
     /** Start (or idempotently re-attach to) a child run; resolves its current state. */
     start(slug: string, input: unknown, opts: CallOptions | undefined, signal?: AbortSignal): Promise<ChildResult>;
-    /** Poll a child run's current state by id, or null when it isn't this run's child. */
-    poll(childRunId: string): Promise<ChildResult | null>;
     run(slug: string, input: unknown, opts: CallOptions | undefined): Promise<string>;
     schedule(slug: string, input: unknown, opts: ScheduleOptions): Promise<string>;
 }
@@ -209,6 +207,29 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
      *  host always implements it. */
     humanInput(opts: HumanInputOptions): Promise<HumanInputResult>;
     private humanInputSeam;
+    /**
+     * Park the run at a BUDGET gate and resolve with the responder's answer (docs/SUSPEND_POLICY.md
+     * Decision 3). Called by the leaf executor's `streamModel` seam when the run's `max_usd` cap is
+     * breached, i.e. from INSIDE an in-flight `agent()` — which drives two deliberate differences from
+     * {@link humanInputSeam}:
+     *
+     *  - **No `guarded()` wrapper.** The enclosing `agent()` seam already counted this leaf as work via
+     *    `trackWork`. Wrapping again would double-count it, and the extra count would never be released
+     *    — quiescence would never be reached and the freeze would hang forever. `freezeHumanInput` →
+     *    `freezeWait` does the right thing here: it `endWork`s for the duration of the park (this leaf
+     *    is waiting, not working, which is exactly what lets the run reach quiescence and freeze) and
+     *    rejoins on resume.
+     *  - **Abort is not re-checked up front.** `streamModel` has just done it; a park is not a new
+     *    entry point.
+     *
+     * The gate itself is an ordinary {@link HumanInputGate} keyed `budget`, so it persists, surfaces in
+     * the inbox, and is answered by the same machinery as any other gate. No timeout: an unanswered
+     * budget gate is aged out by the control plane's inactive-cancel reaper, not by a wake we schedule.
+     */
+    budgetClearance(gate: {
+        prompt: string;
+        inputSpec: unknown;
+    }): Promise<HumanInputResult>;
     /** Absolute wake time for a `humanInput({ timeout })`, or null when there is none / it's unparseable. */
     private timeoutExpiry;
     callWorkflow(slug: string, input: unknown, opts: CallOptions | undefined): Promise<unknown>;

package/dist/runtime/workflow_host.js

@@ -12,6 +12,7 @@
 import { AppError, ErrorCode } from "./support/index.js";
 import { LeafParked } from "@boardwalk-labs/engine/core";
 import { normalizeHumanInputResult } from "./wire/human_input.js";
+import { BUDGET_GATE_KEY } from "./budget_gate.js";
 import { SuspensionCounter, SUSPEND_THRESHOLD_MS } from "./suspension.js";
 import { throwIfAborted } from "./run_abort.js";
 /** Parse a `humanInput({ timeout })` string (`"48h"`, `"30m"`, `"90s"`, `"7d"`) to milliseconds, or
@@ -303,6 +304,40 @@ export class WorkerWorkflowHost {
         // Hold path: register the gate and poll until a person answers.
         return normalizeHumanInputResult(await this.holdForAnswer(seq, signal.humanInput));
     }
+    /**
+     * Park the run at a BUDGET gate and resolve with the responder's answer (docs/SUSPEND_POLICY.md
+     * Decision 3). Called by the leaf executor's `streamModel` seam when the run's `max_usd` cap is
+     * breached, i.e. from INSIDE an in-flight `agent()` — which drives two deliberate differences from
+     * {@link humanInputSeam}:
+     *
+     *  - **No `guarded()` wrapper.** The enclosing `agent()` seam already counted this leaf as work via
+     *    `trackWork`. Wrapping again would double-count it, and the extra count would never be released
+     *    — quiescence would never be reached and the freeze would hang forever. `freezeHumanInput` →
+     *    `freezeWait` does the right thing here: it `endWork`s for the duration of the park (this leaf
+     *    is waiting, not working, which is exactly what lets the run reach quiescence and freeze) and
+     *    rejoins on resume.
+     *  - **Abort is not re-checked up front.** `streamModel` has just done it; a park is not a new
+     *    entry point.
+     *
+     * The gate itself is an ordinary {@link HumanInputGate} keyed `budget`, so it persists, surfaces in
+     * the inbox, and is answered by the same machinery as any other gate. No timeout: an unanswered
+     * budget gate is aged out by the control plane's inactive-cancel reaper, not by a wake we schedule.
+     */
+    async budgetClearance(gate) {
+        const seq = this.seq.next();
+        const key = BUDGET_GATE_KEY;
+        const signal = {
+            reason: "budget",
+            seq,
+            humanInput: { key, prompt: gate.prompt, inputSpec: gate.inputSpec },
+        };
+        const freeze = this.deps.freeze;
+        if (freeze !== undefined) {
+            return await this.freezeHumanInput(freeze, signal, key);
+        }
+        // No freeze substrate (self-hosted runner / local dev): hold the live process until answered.
+        return normalizeHumanInputResult(await this.holdForAnswer(seq, signal.humanInput));
+    }
     /** Absolute wake time for a `humanInput({ timeout })`, or null when there is none / it's unparseable. */
     timeoutExpiry(timeout) {
         const ms = parseTimeoutMs(timeout);

package/dist/runtime/workspace_store.d.ts

@@ -6,10 +6,27 @@
  *  workspace never enters memory. NOT a security boundary (tenant isolation is the per-workflow key);
  *  purely a guardrail, like the run budget's `max_usd`. */
 export declare const WORKSPACE_SNAPSHOT_MAX_BYTES: number;
+/** What a run persists: the WHOLE workspace, or exactly these workspace-relative dirs (possibly none). */
+export type PersistSelection = true | readonly string[];
+/**
+ * Resolve what this run persists (docs/WORKSPACE_PERSISTENCE.md §3): the manifest's declaration
+ * UNIONED with every `agent({ memory })` dir the run actually used.
+ *
+ * The union is why this is resolved at PERSIST time, not construction time: memory dirs are
+ * undeclared by design (`sdk/src/types.ts` — "`mcp` servers, `skills`, and `memory` — the manifest
+ * declares none of them"), so they are only known once the run has made the agent calls. A workflow
+ * whose manifest says nothing at all still persists, iff it used memory.
+ *
+ * `true` swallows the list: the whole workspace already contains every memory dir. An empty array
+ * means persist nothing, which is the common case and must stay cheap.
+ */
+export declare function resolvePersistSelection(declared: boolean | readonly string[] | undefined, memoryDirs: ReadonlySet<string>): PersistSelection;
 /** tar+gzip a directory to a file / extract one. Shells out to `tar` in production; injected in tests. */
 export interface WorkspaceArchiver {
-    /** Create a gzipped tar of `dir`'s CONTENTS at `destPath`; resolve to the archive's byte size. */
-    archive(dir: string, destPath: string): Promise<number>;
+    /** Create a gzipped tar of `dir`'s CONTENTS at `destPath`; resolve to the archive's byte size.
+     *  `paths` (workspace-relative, already filtered to those that exist) narrows the archive to
+     *  exactly those entries — the `persist: [...]` form. Omitted ⇒ the whole tree (`persist: true`). */
+    archive(dir: string, destPath: string, paths?: readonly string[]): Promise<number>;
     /** Extract a gzipped tar `srcPath` into `dir` (created if absent). */
     extract(srcPath: string, dir: string): Promise<void>;
 }
@@ -30,6 +47,10 @@ export interface WorkspaceFs {
     readFile(path: string): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array): Promise<void>;
     rm(path: string): Promise<void>;
+    /** Does this path exist? Used to narrow a `persist: [...]` selection to the dirs the run actually
+     *  created — `tar` fails the whole archive on one missing member, and a declared-but-unused dir is
+     *  normal (a workflow declares `["cache", "index"]` and only writes `cache` on its first run). */
+    exists(path: string): Promise<boolean>;
 }
 export interface WorkspaceStoreDeps {
     broker: WorkspaceBrokerTransport;
@@ -37,6 +58,9 @@ export interface WorkspaceStoreDeps {
     fs: WorkspaceFs;
     /** The `/workspace` root to snapshot/restore. */
     workspaceRoot: string;
+    /** What to persist, read AT PERSIST TIME (see {@link resolvePersistSelection}) — the run's memory
+     *  dirs aren't known until its agent calls have run, so this cannot be a construction-time value. */
+    selection: () => PersistSelection;
     /** Scratch path for the in-flight tarball. */
     tmpPath?: string;
     /** Snapshot tarballs larger than this are skipped (logged). Defaults to {@link WORKSPACE_SNAPSHOT_MAX_BYTES}. */
@@ -59,10 +83,13 @@ export declare class WorkspaceStore {
      *  manifest opts into persistence, so archiving-first never runs for a non-persist workflow; the
      *  only redundant archive is a self-hosted+persist run, where the broker returns a null URL. */
     persist(): Promise<number>;
+    /** Narrow a selection to the dirs that exist: `tar` fails the whole archive on one missing member,
+     *  and declaring a dir the run hasn't written yet is ordinary (first run of `persist: ["cache"]`). */
+    private presentPaths;
 }
 /** Production archiver — shells out to the runner image's `tar` (the runner has full shell tooling). */
 export declare class TarWorkspaceArchiver implements WorkspaceArchiver {
-    archive(dir: string, destPath: string): Promise<number>;
+    archive(dir: string, destPath: string, paths?: readonly string[]): Promise<number>;
     extract(srcPath: string, dir: string): Promise<void>;
 }
 /** Production fs — node's fs/promises. */
@@ -70,4 +97,5 @@ export declare class NodeWorkspaceFs implements WorkspaceFs {
     readFile(path: string): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array): Promise<void>;
     rm(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
 }