@boardwalk-labs/runner 0.1.11 → 0.1.12

package/dist/runtime/uniqueness_reseed.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reseed the userspace CSPRNG at a restore boundary (fresh-run identity injection AND every wake —
+ * clause 3), before any run code draws randomness. Idempotent and side-effect-free beyond the
+ * reseed; safe to call repeatedly. Returns whether the reseed ran (false = addon unavailable, the
+ * degraded no-op path). Never throws.
+ */
+export declare function reseedUserspaceCsprng(): boolean;

package/dist/runtime/uniqueness_reseed.js

@@ -0,0 +1,65 @@
+// Snapshot-uniqueness reseed — clause 3 of the SNAPSHOT_UNIQUENESS_CONTRACT, the one sliver of
+// the determinism contract that survives the journal's deletion.
+//
+// A memory snapshot freezes OpenSSL's DRBG, so two clones of one base snapshot hand every run
+// byte-identical `crypto.*` output (proven, contract). The kernel CSPRNG diverges across
+// clones (VMGenID) but that reseed never reaches OpenSSL, and a pure-JS monkeypatch was proven
+// insufficient (named ESM imports of `node:crypto` bypass it — measured 2026-07-09). So the robust
+// fix is a native step that reseeds OpenSSL's DRBG UNDERNEATH every caller: the `bw_reseed` addon
+// (native/reseed.c) chains EVP_RAND_reseed over the primary/public/private DRBGs from the
+// (VMGenID-diverged) OS entropy.
+//
+// This module is the platform-owned JS entry point. It loads the prebuilt addon opportunistically
+// and NO-OPS with a warning when it is unavailable (a platform with no prebuild — e.g. the ARM64
+// Fargate worker, where there is no snapshot and thus nothing to reseed; or a self-host on an
+// unsupported arch). It never throws: a reseed that cannot run must not fail a run.
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createLogger } from "./support/index.js";
+const log = createLogger("uniqueness_reseed");
+/** undefined = not yet attempted; null = unavailable (no prebuild for this platform). */
+let addon;
+function loadAddon() {
+    if (addon !== undefined)
+        return addon;
+    try {
+        const require = createRequire(import.meta.url);
+        // node-gyp-build resolves prebuilds/<platform>-<arch>/*.node (production) or build/Release
+        // (a local dev build), throwing when neither exists for this platform.
+        const nodeGypBuild = require("node-gyp-build");
+        // dist/runtime/uniqueness_reseed.js → the package root two levels up (holds prebuilds/ + build/).
+        const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+        addon = nodeGypBuild(pkgRoot);
+    }
+    catch (err) {
+        addon = null;
+        log.warn("uniqueness_reseed_addon_unavailable", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return addon;
+}
+/**
+ * Reseed the userspace CSPRNG at a restore boundary (fresh-run identity injection AND every wake —
+ * clause 3), before any run code draws randomness. Idempotent and side-effect-free beyond the
+ * reseed; safe to call repeatedly. Returns whether the reseed ran (false = addon unavailable, the
+ * degraded no-op path). Never throws.
+ */
+export function reseedUserspaceCsprng() {
+    const a = loadAddon();
+    if (a === null)
+        return false;
+    try {
+        const ok = a.reseed();
+        if (!ok)
+            log.warn("uniqueness_reseed_partial", {});
+        return ok;
+    }
+    catch (err) {
+        log.error("uniqueness_reseed_failed", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return false;
+    }
+}

package/dist/runtime/wire/artifact_storage.js

@@ -1,5 +1,5 @@
 // Artifact storage policy — the server-side rules for turning an agent's artifact-write request into
-// a stored S3 object (the platform spec). These used to live in the `artifacts` TOOL,
+// a stored S3 object. These used to live in the `artifacts` TOOL,
 // which runs on the UNTRUSTED runner; under the Runner Credential Broker (the Runner Credential Broker model) the
 // broker owns them so a malicious runner can't bypass content-type neutralization or escape its
 // run's key prefix. Pure functions — unit-tested exhaustively.
@@ -10,7 +10,7 @@ import * as nodePath from "node:path";
 export function workspaceS3Key(orgId, workflowId) {
     return `orgs/${orgId}/workflows/${workflowId}/workspace.tar.gz`;
 }
-// ---- run-artifact retention tag (Phase 18.5 S3 lifecycle safety net) ----
+// ---- run-artifact retention tag (S3 lifecycle safety net) ----
 //
 // Run artifacts share the `orgs/{org}/...` prefix with workspace snapshots (`.../workflows/...`) and
 // program artifacts (`.../program-artifacts/...`), and S3 lifecycle prefix filters can't express

package/dist/runtime/wire/inference_proxy.d.ts

@@ -57,7 +57,7 @@ export declare function parseInferenceRequest(body: string): InferenceProxyReque
 /** Serialize one streamed text delta as a single NDJSON line (trailing "\n" included). */
 export declare function serializeDeltaFrame(text: string): string;
 /** Serialize the single terminal turn result as one NDJSON line. `costMicros` is the turn's EXACT
- *  upstream cost (OpenRouter `usage.cost` × 1e6) on the managed lane — 0 for BYO or when unavailable.
+ *  upstream cost (the managed provider's per-request cost × 1e6) on the managed lane — 0 for BYO or when unavailable.
  *  The worker feeds it to the budget guardrail so `max_usd` tracks real spend, not a token estimate. */
 export declare function serializeResultFrame(turn: ChatTurn, modelRef: string, costMicros?: number): string;
 /** Serialize a terminal error as a single NDJSON line. */

package/dist/runtime/wire/inference_proxy.js

@@ -13,7 +13,7 @@
 //
 // Transport: the response is **newline-delimited JSON** (one frame per line). A model turn streams
 // many text deltas; NDJSON lets the runner consume them incrementally over the raw socket (the
-// buffered REST path can't stream — the platform spec). Each frame is one of:
+// buffered REST path can't stream). Each frame is one of:
 //   { "t": "delta",  "text": <string> }                  — a streamed assistant-text chunk
 //   { "t": "result", "turn": <ChatTurn>, "modelRef": <string>, "costMicros": <number> }  — terminal turn
 //   { "t": "error",  "error": { code, message } }         — a terminal model/broker error
@@ -77,7 +77,7 @@ export function serializeDeltaFrame(text) {
     return `${JSON.stringify({ t: "delta", text })}\n`;
 }
 /** Serialize the single terminal turn result as one NDJSON line. `costMicros` is the turn's EXACT
- *  upstream cost (OpenRouter `usage.cost` × 1e6) on the managed lane — 0 for BYO or when unavailable.
+ *  upstream cost (the managed provider's per-request cost × 1e6) on the managed lane — 0 for BYO or when unavailable.
  *  The worker feeds it to the budget guardrail so `max_usd` tracks real spend, not a token estimate. */
 export function serializeResultFrame(turn, modelRef, costMicros = 0) {
     return `${JSON.stringify({ t: "result", turn, modelRef, costMicros })}\n`;

package/dist/runtime/workflow_host.d.ts

@@ -52,6 +52,13 @@ export interface ChildDispatcher {
 export interface SecretAccessor {
     get(name: string): Promise<string>;
 }
+/** Register-without-release: register a HELD HITL gate so it is
+ *  answerable while the run keeps running, and poll for the answer. Backed by the broker's
+ *  `inputs` endpoints. Absent ⇒ a held gate is only answerable once it freezes. */
+export interface HeldInputPort {
+    register(seq: number, gate: SuspendSignal["humanInput"]): Promise<unknown>;
+    poll(seq: number): Promise<Record<string, unknown>>;
+}
 /** Holds the process for `ms` milliseconds. The seam exists so tests don't wait on real time. An
  *  abort fires the hold REJECT (with the signal's RunAbortedError) and clears the timer — so a
  *  multi-day sleep aborted early doesn't leave a live timer pinning the event loop open. */
@@ -135,6 +142,11 @@ export interface WorkerWorkflowHostDeps {
      * stream, and work arriving while a freeze is pending queues until the wake.
      */
     freeze?: FreezeCoordinator;
+    /** Register-without-release for HELD human-input gates. Only
+     *  meaningful alongside `freeze`; absent ⇒ a held gate is answerable only once it freezes. */
+    heldInput?: HeldInputPort;
+    /** Poll interval for a held gate's answer (default 3s). */
+    heldPollIntervalMs?: number;
     /**
      * The highest journaled seq at claim (0 on a fresh run). While re-running seams up to this
      * frontier on a resume, the host is REPLAYING and observability (phase markers, program logs) is
@@ -147,6 +159,7 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     private readonly sleeper;
     private readonly now;
     private readonly maxSleepMs;
+    private readonly heldPollIntervalMs;
     /** Synchronous durable-seam counter + silent-replay live flag (the durable-suspension design). */
     private readonly seq;
     /** Run context + on-demand public-API bearer the SDK `runtime` accessor reads off the host. */
@@ -167,6 +180,25 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     /** A suspending seam's freeze wait: step out of the "work" count around the park (the wait itself
      *  is what the gate waits FOR, not work that blocks it), then rejoin on resume. */
     private freezeWait;
+    /**
+     * Snapshot-substrate `humanInput()` with REGISTER-WITHOUT-RELEASE.
+     * A gate reached while a sibling seam is still in flight HOLDS (the quiescence gate won't freeze
+     * yet), but a human must still be able to answer during that hold. So: register the gate with the
+     * broker immediately (it surfaces in the inbox/API at once), then race two outcomes —
+     *   - the answer arrives (brokered poll) while holding ⇒ WITHDRAW the freeze wait and resolve
+     *     in-process (the run never froze); or
+     *   - quiescence is reached with no answer ⇒ the wait freezes, and the wake carries the answer.
+     * Once frozen the poll is frozen too (same process), so the race is only live during the hold.
+     * A register/poll failure degrades to the plain freeze wait — the gate still works, just without
+     * the answerable-while-held property.
+     */
+    private freezeHumanInput;
+    /** Poll the broker for a held gate's answer until it arrives or the wait withdraws. Resolves with
+     *  the answer value; never rejects the run (a transient poll error just retries next tick). Runs
+     *  OUTSIDE the quiescence gate (it is not run work — it must not block a freeze). */
+    private pollHeldAnswer;
+    /** Map a froze/aborted freeze outcome to the gate's answer (or throw on an unexpected abort). */
+    private resolveFreezeAnswer;
     /** The wake's answer for one gate key. A wake whose value is missing the parked gate means the
      *  control plane and the snapshot disagree about what this run was waiting for — a platform bug,
      *  failed loudly, never a retry. */

package/dist/runtime/workflow_host.js

@@ -1,7 +1,7 @@
 // WorkerWorkflowHost — the real WorkflowHost the worker installs onto @boardwalk-labs/workflow
 // before running a program (the workflow runtime design). The program's hooks delegate here:
 //
-//   agent(prompt, opts)        → an ephemeral Strands agent leaf (the demoted agent loop)
+//   agent(prompt, opts)        → an ephemeral agent leaf (the demoted agent loop)
 //   sleep(arg)                 → an IN-PROCESS hold (hold-and-pay; no checkpoint, no exit)
 //   workflows.call(slug, in)   → a durable child run (parent holds while it runs)
 //   secrets.get(name)          → the run's fail-closed secret resolver
@@ -67,6 +67,7 @@ export class WorkerWorkflowHost {
     sleeper;
     now;
     maxSleepMs;
+    heldPollIntervalMs;
     /** Synchronous durable-seam counter + silent-replay live flag (the durable-suspension design). */
     seq;
     /** Run context + on-demand public-API bearer the SDK `runtime` accessor reads off the host. */
@@ -76,6 +77,7 @@ export class WorkerWorkflowHost {
         this.sleeper = deps.sleeper ?? new TimerSleepController();
         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.runtime = deps.runtime;
     }
@@ -118,15 +120,78 @@ export class WorkerWorkflowHost {
     }
     /** A suspending seam's freeze wait: step out of the "work" count around the park (the wait itself
      *  is what the gate waits FOR, not work that blocks it), then rejoin on resume. */
-    async freezeWait(freeze, signal) {
+    async freezeWait(freeze, signal, abort) {
         freeze.endWork();
         try {
-            return await freeze.suspendingWait(signal);
+            return await freeze.suspendingWait(signal, abort);
         }
         finally {
             freeze.beginWork();
         }
     }
+    /**
+     * Snapshot-substrate `humanInput()` with REGISTER-WITHOUT-RELEASE.
+     * A gate reached while a sibling seam is still in flight HOLDS (the quiescence gate won't freeze
+     * yet), but a human must still be able to answer during that hold. So: register the gate with the
+     * broker immediately (it surfaces in the inbox/API at once), then race two outcomes —
+     *   - the answer arrives (brokered poll) while holding ⇒ WITHDRAW the freeze wait and resolve
+     *     in-process (the run never froze); or
+     *   - quiescence is reached with no answer ⇒ the wait freezes, and the wake carries the answer.
+     * Once frozen the poll is frozen too (same process), so the race is only live during the hold.
+     * A register/poll failure degrades to the plain freeze wait — the gate still works, just without
+     * the answerable-while-held property.
+     */
+    async freezeHumanInput(freeze, signal, key) {
+        const held = this.deps.heldInput;
+        if (held === undefined) {
+            // No held-input port wired: the gate can only be answered once it freezes.
+            return this.resolveFreezeAnswer(await this.freezeWait(freeze, signal), key);
+        }
+        await held.register(signal.seq, signal.humanInput);
+        const withdraw = new AbortController();
+        const poll = this.pollHeldAnswer(held, signal.seq, key, withdraw.signal);
+        const outcome = await Promise.race([
+            poll.then((answer) => ({ kind: "answered", answer })),
+            this.freezeWait(freeze, signal, withdraw.signal).then((o) => ({ kind: "froze", o })),
+        ]);
+        if (outcome.kind === "answered") {
+            withdraw.abort(); // withdraw the still-holding freeze wait (no-op if it already froze)
+            return normalizeHumanInputResult(outcome.answer);
+        }
+        withdraw.abort(); // stop the poll loop; the wake path carries the answer
+        return this.resolveFreezeAnswer(outcome.o, key);
+    }
+    /** Poll the broker for a held gate's answer until it arrives or the wait withdraws. Resolves with
+     *  the answer value; never rejects the run (a transient poll error just retries next tick). Runs
+     *  OUTSIDE the quiescence gate (it is not run work — it must not block a freeze). */
+    async pollHeldAnswer(held, seq, key, abort) {
+        for (;;) {
+            if (abort.aborted)
+                return await new Promise(() => undefined); // frozen path won: never resolve
+            try {
+                const answers = await held.poll(seq);
+                if (key in answers)
+                    return answers[key];
+            }
+            catch {
+                /* transient — retry next tick */
+            }
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, this.heldPollIntervalMs);
+                abort.addEventListener("abort", () => {
+                    clearTimeout(t);
+                    resolve();
+                }, { once: true });
+            });
+        }
+    }
+    /** Map a froze/aborted freeze outcome to the gate's answer (or throw on an unexpected abort). */
+    resolveFreezeAnswer(outcome, key) {
+        if (outcome.kind !== "wake") {
+            throw new AppError(ErrorCode.INTERNAL_ERROR, `Freeze wait for a human-input gate ended unexpectedly (${outcome.kind})`, { kind: "unexpected_freeze_outcome", key });
+        }
+        return normalizeHumanInputResult(this.gateAnswer(outcome.wake, key));
+    }
     /** The wake's answer for one gate key. A wake whose value is missing the parked gate means the
      *  control plane and the snapshot disagree about what this run was waiting for — a platform bug,
      *  failed loudly, never a retry. */
@@ -256,12 +321,7 @@ export class WorkerWorkflowHost {
         };
         const freeze = this.deps.freeze;
         if (freeze !== undefined) {
-            // Snapshot substrate: park in place; the wake carries the validated answer.
-            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 });
-            }
-            return normalizeHumanInputResult(this.gateAnswer(outcome.wake, key));
+            return await this.freezeHumanInput(freeze, signal, key);
         }
         return this.suspend(signal);
     }

package/native/reseed.c

@@ -0,0 +1,52 @@
+/*
+ * bw_reseed — the clause-3 userspace-CSPRNG reseed (SNAPSHOT_UNIQUENESS_CONTRACT).
+ *
+ * A memory snapshot freezes OpenSSL's DRBG state, so two clones of one base snapshot hand every
+ * run byte-identical `crypto.*` output. The kernel CSPRNG diverges across clones (VMGenID), but
+ * that reseed never reaches OpenSSL. A pure-JS monkeypatch was proven insufficient (named ESM
+ * imports of node:crypto bypass it), so this native step reseeds OpenSSL's DRBG UNDERNEATH every
+ * caller — the only robust fix.
+ *
+ * OpenSSL 3 DRBG chain: the primary DRBG seeds from the OS entropy source; the public + private
+ * DRBGs (what RAND_bytes / Node crypto actually draw from) seed from the primary. We reseed the
+ * primary first (pulling the now-diverged OS entropy) then the public + private so the fresh
+ * entropy propagates immediately, and call RAND_poll() as a belt. Everything is guarded on NULL so
+ * a non-default RAND provider degrades to whatever succeeded rather than crashing.
+ *
+ * Symbols (RAND_get0_*, EVP_RAND_reseed, RAND_poll) come from the OpenSSL that Node links; on a
+ * Node build that does not export them the addon fails to load and the JS layer no-ops with a warn
+ * (uniqueness_reseed.ts). Linux-only in practice (the snapshot substrate is Linux microVMs).
+ */
+#include <node_api.h>
+#include <openssl/rand.h>
+#include <openssl/evp.h>
+
+static int reseed_ctx(EVP_RAND_CTX *ctx) {
+  if (ctx == NULL) return 1; /* absent layer: nothing to do, not a failure */
+  return EVP_RAND_reseed(ctx, /*prediction_resistance=*/0, NULL, 0, NULL, 0);
+}
+
+static napi_value Reseed(napi_env env, napi_callback_info info) {
+  int ok = 1;
+  /* Reseed the primary FIRST (it pulls fresh OS entropy), then the layers that serve draws. */
+  if (!reseed_ctx(RAND_get0_primary(NULL))) ok = 0;
+  if (!reseed_ctx(RAND_get0_public(NULL))) ok = 0;
+  if (!reseed_ctx(RAND_get0_private(NULL))) ok = 0;
+  /* Legacy belt: also nudge the default method's entropy pool. */
+  RAND_poll();
+
+  napi_value result;
+  napi_get_boolean(env, ok ? true : false, &result);
+  return result;
+}
+
+static napi_value Init(napi_env env, napi_value exports) {
+  napi_value fn;
+  if (napi_create_function(env, "reseed", NAPI_AUTO_LENGTH, Reseed, NULL, &fn) != napi_ok) {
+    return exports;
+  }
+  napi_set_named_property(env, exports, "reseed", fn);
+  return exports;
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {
@@ -37,7 +37,10 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "native",
+    "binding.gyp",
+    "prebuilds"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -46,13 +49,15 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "vitest run --coverage",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prebuild": "prebuildify --napi --strip -t 24.0.0"
   },
   "dependencies": {
     "zod": "^4.0.0",
     "@boardwalk-labs/engine": "^0.1.29",
     "@boardwalk-labs/workflow": "^0.1.17",
-    "tar": "^7.5.16"
+    "tar": "^7.5.16",
+    "node-gyp-build": "^4.8.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
@@ -62,7 +67,9 @@
     "prettier": "^3.4.0",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.20.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "prebuildify": "^6.0.1",
+    "node-gyp": "^11.0.0"
   },
   "bin": {
     "boardwalk-runner": "./dist/bin.js"