@boardwalk-labs/runner 0.1.21 → 0.2.1

package/dist/runtime/workflow_host.js

@@ -12,7 +12,8 @@
 import { AppError, ErrorCode } from "./support/index.js";
 import { LeafParked } from "@boardwalk-labs/engine/core";
 import { normalizeHumanInputResult } from "./wire/human_input.js";
-import { SeamSequencer, SuspendError, childRunIdSchema, determinismError, leafResumeSchema, seamFingerprint, SUSPEND_THRESHOLD_MS, } from "./suspension.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
  *  null when absent/unparseable (the gate then waits indefinitely). */
@@ -68,7 +69,7 @@ export class WorkerWorkflowHost {
     now;
     maxSleepMs;
     heldPollIntervalMs;
-    /** Synchronous durable-seam counter + silent-replay live flag (the durable-suspension design). */
+    /** Monotonic per-run counter keying suspensions + their HITL gate rows. */
     seq;
     /** Run context + on-demand public-API bearer the SDK `runtime` accessor reads off the host. */
     runtime;
@@ -78,25 +79,9 @@ export class WorkerWorkflowHost {
         this.now = deps.now ?? Date.now;
         this.maxSleepMs = deps.maxSleepMs ?? MAX_SLEEP_MS;
         this.heldPollIntervalMs = deps.heldPollIntervalMs ?? 3_000;
-        this.seq = new SeamSequencer(deps.replayFrontier ?? 0);
+        this.seq = new SuspensionCounter();
         this.runtime = deps.runtime;
     }
-    /** True while re-running already-journaled seams on a resume (the worker suppresses program-log +
-     *  phase observability during this window — those lines were emitted in the prior segment). */
-    isReplaying() {
-        return this.seq.isReplaying();
-    }
-    /** Raise a durable suspension. With `onSuspend` wired (the real worker) the host signals out-of-band
-     *  and returns a never-resolving promise, so the program's own try/catch can't swallow it; without
-     *  it (the local/test path) it rejects with {@link SuspendError}. */
-    suspend(signal) {
-        if (this.deps.onSuspend === undefined)
-            return Promise.reject(new SuspendError(signal));
-        this.deps.onSuspend(signal);
-        return new Promise(() => {
-            /* never settles: the worker races this against the body and tears the task down */
-        });
-    }
     /** Run `fn` only if the run isn't aborted; otherwise REJECT (never throw synchronously) with the
      *  signal's RunAbortedError — every Promise-returning hook funnels through this so callers always
      *  get a rejected promise on abort, not a sync throw. On the snapshot substrate the body also runs
@@ -185,6 +170,31 @@ export class WorkerWorkflowHost {
             });
         }
     }
+    /**
+     * The no-freeze HOLD for a human-input gate: register it with the broker (it surfaces in the
+     * inbox/API at once), then poll until the answer arrives — the process stays alive and pays
+     * for the wait. Rejects promptly when the run's abort signal fires (cancel / credit stop),
+     * which is also how a server-side gate expiry that fails the run unwinds this loop.
+     */
+    async holdForAnswer(seq, gate) {
+        const held = this.deps.heldInput;
+        if (held === undefined || gate === undefined) {
+            throw new AppError(ErrorCode.VALIDATION_FAILED, "humanInput is not available in this runtime (no control-plane connection to register the gate)", { kind: "human_input_unavailable" });
+        }
+        await held.register(seq, gate);
+        for (;;) {
+            throwIfAborted(this.deps.signal);
+            try {
+                const answers = await held.poll(seq);
+                if (gate.key in answers)
+                    return answers[gate.key];
+            }
+            catch {
+                /* transient — retry next tick */
+            }
+            await this.sleeper.hold(this.heldPollIntervalMs, this.deps.signal);
+        }
+    }
     /** Map a froze/aborted freeze outcome to the gate's answer (or throw on an unexpected abort). */
     resolveFreezeAnswer(outcome, key) {
         if (outcome.kind !== "wake") {
@@ -204,64 +214,40 @@ export class WorkerWorkflowHost {
     }
     setPhase(name, opts) {
         throwIfAborted(this.deps.signal);
-        // Suppressed during replay: the marker was already emitted in the prior segment.
-        if (this.seq.isReplaying())
-            return;
         this.deps.phases?.set(name, opts);
     }
     agent(prompt, opts) {
         return this.guarded(() => this.agentSeam(prompt, opts));
     }
-    /** The `agent()` durable seam: a journal hit returns the memoized result (never re-runs the LLM); a
-     *  `suspended` hit resumes a parked leaf from its checkpoint + answers; a miss runs the leaf and
-     *  journals the result. A leaf that PARKS (the model called `human_input`) suspends the run. */
+    /** The `agent()` seam: run the leaf to completion. A leaf that PARKS (the model called the
+     *  `human_input` tool) waits for the answer — a freeze on the snapshot substrate, a held poll
+     *  otherwise — and re-enters from its in-memory checkpoint. Nothing is memoized: a crash-restart
+     *  re-runs the leaf (restart-from-top semantics). */
     async agentSeam(prompt, opts) {
+        // One suspension key for the whole leaf: every gate this leaf raises registers under it, and
+        // a wake joins ALL of its answered rows, so answers accumulate server-side across parks.
         const seq = this.seq.next();
-        const fingerprint = seamFingerprint([
-            "agent",
-            opts?.provider ?? null,
-            opts?.model ?? null,
-            prompt,
-            opts?.schema ?? null,
-        ]);
-        let resume;
-        if (this.deps.journal !== undefined) {
-            const existing = await this.deps.journal.get(seq);
-            if (existing !== null) {
-                if (existing.fingerprint !== fingerprint)
-                    throw determinismError(seq, "agent", existing.kind);
-                if (existing.state === "resolved")
-                    return existing.result;
-                // A `suspended` entry is a parked leaf (tool-level human_input): re-enter it from the stored
-                // checkpoint + the answers the broker joined in.
-                resume = leafResumeSchema.parse(existing.result);
-            }
-        }
         // Bind a computer-use session's tools (browser tier ⇒ its in-VM Playwright MCP) if one was passed.
-        // Done AFTER the fingerprint so the injected MCP never perturbs determinism (the fingerprint keys
-        // on provider/model/prompt/schema only — an mcp/session change must not invalidate a journal hit).
         const effectiveOpts = this.bindBrowserSession(opts);
+        // Held-path answers accumulate locally too: a turn with several human_input calls parks once
+        // per unanswered gate, and each re-entry must still see every earlier answer.
+        const heldAnswers = {};
+        let resume;
         for (;;) {
             try {
-                const result = await this.deps.leaf.run(prompt, effectiveOpts, this.deps.signal, resume);
-                await this.deps.journal?.put({
-                    seq,
-                    kind: "agent",
-                    fingerprint,
-                    label: prompt.slice(0, 120),
-                    result,
-                });
-                return result;
+                return await this.deps.leaf.run(prompt, effectiveOpts, this.deps.signal, resume);
             }
             catch (err) {
                 if (!(err instanceof LeafParked))
                     throw err;
                 // The model paused for a person (the in-leaf `human_input` tool).
+                if (err.checkpoint === undefined) {
+                    throw new AppError(ErrorCode.INTERNAL_ERROR, "Parked agent leaf has no checkpoint to resume from", { kind: "leaf_parked_no_checkpoint", seq });
+                }
                 const signal = {
                     reason: "human_input",
                     seq,
-                    fingerprint,
-                    ...(err.checkpoint !== undefined ? { leafCheckpoint: err.checkpoint } : {}),
+                    leafCheckpoint: err.checkpoint,
                     humanInput: {
                         key: err.request.toolCallId,
                         prompt: err.request.prompt,
@@ -269,14 +255,15 @@ export class WorkerWorkflowHost {
                     },
                 };
                 const freeze = this.deps.freeze;
-                if (freeze === undefined)
-                    return this.suspend(signal);
-                // Snapshot substrate: freeze in place; the wake carries the answers and the leaf
-                // re-enters from its checkpoint — heap intact, no journal round-trip. A leaf may park
-                // again on a later turn, so this loops.
-                if (err.checkpoint === undefined) {
-                    throw new AppError(ErrorCode.INTERNAL_ERROR, "Parked agent leaf has no checkpoint to resume from", { kind: "leaf_parked_no_checkpoint", seq });
+                if (freeze === undefined) {
+                    // Hold path: register the gate and poll until answered; the transcript stays in memory.
+                    heldAnswers[err.request.toolCallId] = await this.holdForAnswer(seq, signal.humanInput);
+                    resume = { checkpoint: err.checkpoint, answers: { ...heldAnswers } };
+                    continue;
                 }
+                // Snapshot substrate: freeze in place; the wake carries the answers and the leaf
+                // re-enters from its checkpoint — heap intact. A leaf may park again on a later turn,
+                // so this loops.
                 const outcome = await this.freezeWait(freeze, signal);
                 if (outcome.kind !== "wake") {
                     throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a human-input seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
@@ -288,32 +275,19 @@ export class WorkerWorkflowHost {
             }
         }
     }
-    /** Program-level `humanInput()`: suspend the run on a gate, resume with the validated answer. The
-     *  SDK marks this optional; the hosted host always implements it. */
+    /** Program-level `humanInput()`: wait on a gate — a freeze on the snapshot substrate, a held
+     *  poll otherwise — and return the validated answer. The SDK marks this optional; the hosted
+     *  host always implements it. */
     humanInput(opts) {
         return this.guarded(() => this.humanInputSeam(opts));
     }
     async humanInputSeam(opts) {
         const seq = this.seq.next();
         const key = opts.key ?? `seam-${String(seq)}`;
-        const fingerprint = seamFingerprint(["human_input", key, opts.prompt, opts.input]);
-        if (this.deps.journal !== undefined) {
-            const existing = await this.deps.journal.get(seq);
-            if (existing !== null) {
-                if (existing.fingerprint !== fingerprint) {
-                    throw determinismError(seq, "human_input", existing.kind);
-                }
-                // A resolved entry is the human's validated response; a still-pending entry is a spurious
-                // wake without an answer, so fall through and re-suspend.
-                if (existing.state === "resolved")
-                    return normalizeHumanInputResult(existing.result);
-            }
-        }
         const expiresAt = this.timeoutExpiry(opts.timeout);
         const signal = {
             reason: "human_input",
             seq,
-            fingerprint,
             humanInput: {
                 key,
                 prompt: opts.prompt,
@@ -327,111 +301,85 @@ export class WorkerWorkflowHost {
         if (freeze !== undefined) {
             return await this.freezeHumanInput(freeze, signal, key);
         }
-        return this.suspend(signal);
+        // 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);
         return ms === null ? null : this.now() + ms;
     }
-    /** `step.run(name, fn)`: run `fn` exactly once across restarts, memoizing its result in the journal
-     *  (the escape hatch for nondeterministic work on a suspend/resume path). */
-    step(name, fn) {
-        return this.guarded(() => this.stepSeam(name, fn));
-    }
-    async stepSeam(name, fn) {
-        const seq = this.seq.next();
-        const fingerprint = seamFingerprint(["step", name]);
-        if (this.deps.journal !== undefined) {
-            const existing = await this.deps.journal.get(seq);
-            if (existing !== null) {
-                if (existing.fingerprint !== fingerprint)
-                    throw determinismError(seq, "step", existing.kind);
-                if (existing.state === "resolved")
-                    return existing.result;
-            }
-        }
-        const result = await fn();
-        await this.deps.journal?.put({ seq, kind: "step", fingerprint, label: name, result });
-        return result;
-    }
     callWorkflow(slug, input, opts) {
         return this.guarded(() => this.callWorkflowSeam(slug, input, opts));
     }
-    /** The `workflows.call` durable seam (the durable-suspension design): start the child once + memoize its
-     *  output; a non-terminal child SUSPENDS the parent (`waiting_for_child`, the child's id journaled)
-     *  — the parent releases its task and is woken when the child finalizes. On resume the seam polls
-     *  the journaled child and returns its output (or throws on a failed child). Without a journal (the
-     *  local/test path) it falls back to the in-process hold-and-poll. */
+    /** The `workflows.call` seam: start the child once (idempotently — the child's run row is the
+     *  durable memo, so a crash-restarted parent re-attaches instead of re-spawning). A non-terminal
+     *  child suspends the parent `waiting_for_child` on the snapshot substrate (the wake carries the
+     *  finalized child, heap intact); without one the parent HOLDS in-process and polls. */
     async callWorkflowSeam(slug, input, opts) {
-        if (this.deps.journal === undefined) {
+        const freeze = this.deps.freeze;
+        if (freeze === undefined) {
+            // Hold path: the dispatcher's in-process hold-and-poll until the child is terminal.
             return this.deps.children.call(slug, input, opts, this.deps.signal);
         }
-        const seq = this.seq.next();
-        const fingerprint = seamFingerprint([
-            "workflow_call",
-            slug,
-            input ?? null,
-            opts?.idempotencyKey ?? null,
-        ]);
-        let knownChildId;
-        const existing = await this.deps.journal.get(seq);
-        if (existing !== null) {
-            if (existing.fingerprint !== fingerprint) {
-                throw determinismError(seq, "workflow_call", existing.kind);
-            }
-            if (existing.state === "resolved")
-                return existing.result;
-            // A pending entry holds the child run id we suspended waiting on (resume polls it).
-            knownChildId = childRunIdSchema.parse(existing.result);
-        }
-        // First execution starts (idempotently) the child; a resume polls the journaled one.
-        const child = knownChildId === undefined
-            ? await this.deps.children.start(slug, input, opts, this.deps.signal)
-            : await this.deps.children.poll(knownChildId);
-        if (child === null) {
-            throw new AppError(ErrorCode.INTERNAL_ERROR, `Called workflow's child run vanished`, {
-                slug,
-                childRunId: knownChildId,
-            });
-        }
-        if (child.status === "completed") {
-            await this.deps.journal.put({
-                seq,
-                kind: "workflow_call",
-                fingerprint,
-                label: slug,
-                result: child.output,
-            });
+        const child = await this.deps.children.start(slug, input, opts, this.deps.signal);
+        if (child.status === "completed")
             return child.output;
-        }
         if (child.status === "failed" || child.status === "cancelled") {
             throw new AppError(ErrorCode.VALIDATION_FAILED, `Called workflow "${slug}" ${child.status} (run ${child.childRunId})`, { childRunId: child.childRunId, status: child.status });
         }
-        // Still running → suspend; the child's finalize wakes us.
-        const signal = {
+        // Still running → park in place; the wake carries the finalized child directly (the heap
+        // holds this whole frame across the freeze).
+        const seq = this.seq.next();
+        const outcome = await this.freezeWait(freeze, {
             reason: "workflow_call",
             seq,
-            fingerprint,
             childRunId: child.childRunId,
-        };
-        const freeze = this.deps.freeze;
-        if (freeze !== undefined) {
-            // Snapshot substrate: park in place; the wake carries the finalized child directly (no
-            // journal write for the wake-derived value — the heap holds it and nothing replays).
-            const outcome = await this.freezeWait(freeze, signal);
-            if (outcome.kind !== "wake") {
-                throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a child-wait seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
-            }
-            const woken = outcome.wake.child;
-            if (outcome.wake.kind !== "workflow_call" || woken === undefined) {
-                throw new AppError(ErrorCode.INTERNAL_ERROR, `Wake value does not carry the awaited child run (got kind "${outcome.wake.kind}")`, { kind: "wake_mismatch", childRunId: child.childRunId });
-            }
-            if (woken.status === "completed")
-                return woken.output;
-            throw new AppError(ErrorCode.VALIDATION_FAILED, `Called workflow "${slug}" ${woken.status} (run ${woken.run_id})`, { childRunId: woken.run_id, status: woken.status });
+        });
+        if (outcome.kind !== "wake") {
+            throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a child-wait seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
+        }
+        const woken = outcome.wake.child;
+        if (outcome.wake.kind !== "workflow_call" || woken === undefined) {
+            throw new AppError(ErrorCode.INTERNAL_ERROR, `Wake value does not carry the awaited child run (got kind "${outcome.wake.kind}")`, { kind: "wake_mismatch", childRunId: child.childRunId });
         }
-        return this.suspend(signal);
+        if (woken.status === "completed")
+            return woken.output;
+        throw new AppError(ErrorCode.VALIDATION_FAILED, `Called workflow "${slug}" ${woken.status} (run ${woken.run_id})`, { childRunId: woken.run_id, status: woken.status });
     }
     /** Fire-and-forget trigger of another workflow; resolves to the new run's id (no hold/poll). */
     runWorkflow(slug, input, opts) {
@@ -465,7 +413,7 @@ export class WorkerWorkflowHost {
     }
     /** `computer.openBrowser()`: open a program-owned, in-VM browser session (the browser tier of
      *  computer use). Not a durable seam — a session is a live resource, reaped at run end, never
-     *  journaled/replayed. Absent backend ⇒ a clear "not available" error. */
+     *  persisted. Absent backend ⇒ a clear "not available" error. */
     openBrowserSession(opts) {
         return this.guarded(async () => {
             if (this.deps.browserSessions === undefined) {
@@ -492,42 +440,26 @@ export class WorkerWorkflowHost {
     sleep(arg) {
         return this.guarded(() => this.sleepSeam(arg));
     }
-    /** A short sleep HOLDS the task in-process (cheaper than a release + replay round-trip); a long one
-     *  (≥ {@link SUSPEND_THRESHOLD_MS}) SUSPENDS — releases the task, and a timer re-dispatches the run
-     *  when due. Journaled so a resumed run replays past an already-elapsed sleep instantly. */
+    /** A short sleep HOLDS the task in-process (cheaper than a snapshot round-trip); a long one
+     *  (≥ {@link SUSPEND_THRESHOLD_MS}) SUSPENDS on the snapshot substrate — the VM freezes and the
+     *  wake resolves this very await, heap intact. Without a freeze substrate EVERY sleep holds,
+     *  whatever its length (the no-substrate rule: snapshot or hold, never replay). */
     async sleepSeam(arg) {
         const ms = this.resolveSleepMs(arg);
         if (ms > this.maxSleepMs) {
             throw new AppError(ErrorCode.VALIDATION_FAILED, `Sleep exceeds the ${String(this.maxSleepMs)}ms (7-day) maximum`, { kind: "sleep_cap" });
         }
-        const seq = this.seq.next();
-        const fingerprint = seamFingerprint(["sleep"]);
-        if (this.deps.journal !== undefined) {
-            const existing = await this.deps.journal.get(seq);
-            if (existing !== null) {
-                if (existing.fingerprint !== fingerprint)
-                    throw determinismError(seq, "sleep", existing.kind);
-                // A journaled sleep already elapsed in a prior segment — a resumed run only progresses past a
-                // sleep once it is due, so on replay this returns immediately.
-                return;
-            }
-        }
         // A non-positive duration (incl. an `until` already in the past) is a no-op hold, not an error.
         const holdMs = Math.max(0, ms);
         if (holdMs === 0)
             return;
         const freeze = this.deps.freeze;
         if (holdMs >= SUSPEND_THRESHOLD_MS && freeze !== undefined) {
-            // Snapshot substrate: freeze in place; the wake (when the sleep is due) resolves this very
-            // await, heap intact. An abort falls back to holding the REMAINDER in-process — the
-            // two-ways rule: snapshot or hold, never replay.
+            // Snapshot substrate: freeze in place. An abort falls back to holding the REMAINDER
+            // in-process.
             const requestedAt = this.now();
-            const outcome = await this.freezeWait(freeze, {
-                reason: "sleep",
-                seq,
-                fingerprint,
-                durationMs: holdMs,
-            });
+            const seq = this.seq.next();
+            const outcome = await this.freezeWait(freeze, { reason: "sleep", seq, durationMs: holdMs });
             if (outcome.kind === "wake")
                 return;
             const remaining = holdMs - (this.now() - requestedAt);
@@ -538,14 +470,7 @@ export class WorkerWorkflowHost {
             await this.sleeper.hold(remaining, this.deps.signal);
             return;
         }
-        // Long wait (transitional substrate): SUSPEND (release the task). The broker records the
-        // (resolved) sleep journal entry + the wake time transactionally, so on wake this seam replays
-        // past it (the journal hit above). Only when a journal is wired — without it there is no
-        // resume, so fall back to holding.
-        if (holdMs >= SUSPEND_THRESHOLD_MS && this.deps.journal !== undefined) {
-            return this.suspend({ reason: "sleep", seq, fingerprint, durationMs: holdMs });
-        }
-        // Short wait: HOLD the process (no journal — a crash-restart simply re-holds). Snapshot the
+        // Hold: the process sleeps in place (a crash-restart simply re-holds). Snapshot the
         // persistent workspace first so a crash during the hold can restore it. An abort mid-hold rejects.
         if (this.deps.onBeforeSleep !== undefined)
             await this.deps.onBeforeSleep();

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>;
 }

package/dist/runtime/workspace_store.js

@@ -27,6 +27,24 @@ const exec = promisify(execFile);
  *  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 const WORKSPACE_SNAPSHOT_MAX_BYTES = 512 * 1024 * 1024;
+/**
+ * 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 function resolvePersistSelection(declared, memoryDirs) {
+    if (declared === true)
+        return true;
+    const list = declared === undefined || declared === false ? [] : declared;
+    return [...new Set([...list, ...memoryDirs])];
+}
 export class WorkspaceStore {
     deps;
     tmpPath;
@@ -71,8 +89,15 @@ export class WorkspaceStore {
      *  only redundant archive is a self-hosted+persist run, where the broker returns a null URL. */
     async persist() {
         try {
+            // What this run actually compounds: the manifest's declaration ∪ the memory dirs it used.
+            // Nothing selected is the common case (a workflow that opted into neither) — return before any
+            // fs or broker work, so persistence costs a run that doesn't use it precisely nothing.
+            const selection = this.deps.selection();
+            const paths = selection === true ? undefined : await this.presentPaths(selection);
+            if (paths !== undefined && paths.length === 0)
+                return 0;
             await mkdir(dirname(this.tmpPath), { recursive: true }); // per-run TMPDIR may not exist yet
-            const size = await this.deps.archiver.archive(this.deps.workspaceRoot, this.tmpPath);
+            const size = await this.deps.archiver.archive(this.deps.workspaceRoot, this.tmpPath, paths);
             // Guardrail: an oversized snapshot is dropped (logged), never read into memory or uploaded — the
             // workflow re-does filesystem work next run, as it would without persistence. Checked on the
             // on-disk archive size so the big tarball never hits the worker's heap.
@@ -98,12 +123,23 @@ export class WorkspaceStore {
             return 0;
         }
     }
+    /** 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"]`). */
+    async presentPaths(selection) {
+        const checked = await Promise.all(selection.map(async (p) => (await this.deps.fs.exists(join(this.deps.workspaceRoot, p))) ? p : null));
+        return checked.filter((p) => p !== null);
+    }
 }
 /** Production archiver — shells out to the runner image's `tar` (the runner has full shell tooling). */
 export class TarWorkspaceArchiver {
-    async archive(dir, destPath) {
-        // `-C dir .` archives the CONTENTS of dir (not the dir itself), so extract restores it in place.
-        await exec("tar", ["czf", destPath, "-C", dir, "."]);
+    async archive(dir, destPath, paths) {
+        // `-C dir <members>` archives relative to dir, so extract restores in place either way: `.` for
+        // the whole tree (`persist: true`), or exactly the named dirs (`persist: [...]` ∪ memory dirs).
+        // Members are workspace-relative and schema-validated (no `..`, no absolute, no backslashes —
+        // sdk/src/manifest.ts `persistPath`) and pre-filtered to those that exist; `--` keeps a name
+        // that starts with `-` from being read as a flag.
+        const members = paths === undefined ? ["."] : [...paths];
+        await exec("tar", ["czf", destPath, "-C", dir, "--", ...members]);
         return (await stat(destPath)).size;
     }
     async extract(srcPath, dir) {
@@ -128,6 +164,9 @@ export class NodeWorkspaceFs {
     rm(path) {
         return rm(path, { force: true });
     }
+    async exists(path) {
+        return (await stat(path).catch(() => null)) !== null;
+    }
 }
 function errMsg(err) {
     return err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.1.21",
+  "version": "0.2.1",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {
@@ -53,8 +53,8 @@
     "prebuild": "prebuildify --napi --strip -t 24.0.0"
   },
   "dependencies": {
-    "@boardwalk-labs/engine": "^0.1.35",
-    "@boardwalk-labs/workflow": "^0.1.29",
+    "@boardwalk-labs/engine": "^0.2.0",
+    "@boardwalk-labs/workflow": "^0.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "node-gyp-build": "^4.8.4",
     "tar": "^7.5.16",