@boardwalk-labs/runner 0.2.0 → 0.2.1

package/README.md

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

package/dist/contract.d.ts

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

package/dist/contract.js

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

package/dist/daemon/container.d.ts

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

package/dist/daemon/container.js

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

package/dist/daemon/daemon.d.ts

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

package/dist/daemon/daemon.js

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

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

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

package/dist/runtime/agent/budget.js

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

package/dist/runtime/broker_child_dispatcher.d.ts

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

package/dist/runtime/broker_child_dispatcher.js

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

package/dist/runtime/budget_gate.d.ts

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

package/dist/runtime/budget_gate.js

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

package/dist/runtime/freeze_coordinator.js

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

package/dist/runtime/index.d.ts

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

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
@@ -235,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
@@ -248,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.
@@ -289,17 +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;
+                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
@@ -348,13 +387,9 @@ 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();
-                    },
-                }
-                : {}),
+            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 } : {}),
@@ -369,6 +404,8 @@ export function assembleWorkerDeps(runtime) {
             ...(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;
@@ -380,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();
@@ -441,7 +478,10 @@ export function assembleWorkerDeps(runtime) {
             setProgramDir: (dir) => {
                 programDir = dir;
             },
-            ...(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 } : {}),
@@ -450,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) => {
@@ -657,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,