@boardwalk-labs/runner 0.1.11 → 0.1.13

package/dist/runtime/index.js

@@ -1,5 +1,5 @@
-// Worker composition root (the workflow runtime design). The Boardwalk-hosted
-// worker container runs `node dist/fargate/worker/index.js`; the dispatcher launches it per run with
+// Worker composition root (the workflow runtime design). The hosted worker container runs the
+// compiled worker entrypoint; the dispatcher launches it per run with
 // RUN_ID + the per-run control-plane handle. This file assembles real implementations behind every
 // seam `runProgramWorker(runId, deps)` injects, then runs the one workflow program to terminal.
 //
@@ -11,21 +11,21 @@
 //   - secrets.get()   → broker /secrets/resolve (allowlist enforced server-side).
 //   - workflows.call()→ broker /children (durable child run, hold + poll).
 //   - events.emit()   → broker /events (fan-out server-side).
-//   - artifacts / web_search → broker /artifacts + /tools/web_search (no S3 / Tavily creds here).
+//   - artifacts / web_search → broker /artifacts + /tools/web_search (no storage or search-provider creds here).
 //   - lifecycle / usage / telemetry → broker /claim,/version,/finalize,/usage,/telemetry.
-// There is no DB / Redis / Stripe / Bedrock client on the runner — so its task role is near-zero and
-// the metadata-endpoint escape has nothing to steal. The legacy direct (pre-broker) path is removed.
+// There is no database, cache, billing, or model-provider client on the runner — so its task role is
+// near-zero and the metadata-endpoint escape has nothing to steal. The legacy direct (pre-broker) path is removed.
 //
 // Split: `assembleWorkerDeps(runtime)` is pure wiring (unit-tested with a fake fetch); `main()` is the
 // bootstrap shell (read the control-plane env, install signal handlers).
 //
-// Per-session loops wired here (all brokered): a UsageFlusher meters token deltas (§10.7 →
-// /usage/tokens), a CreditWatcher polls funding (§15 → /credit, aborting the run on exhaustion), and a
-// CancelWatcher polls for a user cancel (§6 → /cancel, aborting the run when the user cancels — the
-// brokered worker holds no Redis, so it can't receive the api-server's cancel publish directly).
+// Per-session loops wired here (all brokered): a UsageFlusher meters token deltas (→ /usage/tokens), a
+// CreditWatcher polls funding (→ /credit, aborting the run on exhaustion), and a CancelWatcher polls
+// for a user cancel (→ /cancel, aborting the run when the user cancels — the brokered worker holds no
+// cache client, so it can't receive the platform's cancel publish directly).
 //
-// Documented v0 deferral (a clear seam): durable events — a no-op AgentEventStore (live Redis fan-out
-// via the broker only) until the run_step_events table lands.
+// Documented v0 deferral (a clear seam): durable events — a no-op AgentEventStore (live fan-out
+// via the broker only) until durable event storage lands.
 import { createLogger, newId, AppError, ErrorCode, DEFAULT_LEASE_MS } from "./support/index.js";
 import { LspService } from "@boardwalk-labs/engine/core";
 import { BudgetMeter } from "./agent/budget.js";
@@ -37,7 +37,10 @@ import { EngineLeafExecutor } from "./leaf_executor.js";
 import { parseByoProviders } from "./direct_inference.js";
 import { applyIdentityToEnv, connectIdentityRelayFd, relayFdFromEnv, workerDiagnostics, } from "./identity_relay.js";
 import { FreezeCoordinator } from "./freeze_coordinator.js";
+import { reseedUserspaceCsprng } from "./uniqueness_reseed.js";
 import { WorkerWorkflowHost } from "./workflow_host.js";
+import { BrowserSessionManager } from "./browser_session.js";
+import { loadGuestBrowserConfig, makeGuestBrowserBackend, connectSessionMcp, } from "./browser_session_backend.js";
 import { runProgramWorker, } from "./program_worker.js";
 import { RunnerControlClient } from "./runner_control_client.js";
 import { BrokerChildDispatcher } from "./broker_child_dispatcher.js";
@@ -54,13 +57,13 @@ import { PhaseTracker } from "./phase_tracker.js";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 const log = createLogger("worker_entrypoint");
-/** Durable events are deferred (run_step_events table) — live fan-out via the broker only. */
+/** 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
  *  worker acts on the org's behalf, so it carries the org + an owner role. Tool-level
  *  boundaries (the broker's server-side manifest allowlist) are the real guard.
  *
  *  source='workflow' (NOT 'session_jwt'): the program must never perform SESSION_JWT_ONLY
- *  credential mutations (§12.11), so a tool that ever exposed such a service is denied by
+ *  credential mutations, so a tool that ever exposed such a service is denied by
  *  construction regardless of the owner role. */
 export function workerAuthContext(run) {
     const userId = run.actor.type === "user" ? run.actor.user_id : `workflow:${run.workflowId}`;
@@ -84,7 +87,7 @@ export function tokenMeterIdentifiers(runId, sessionId) {
     return (leafIndex) => `${runId}:${sessionId}:${String(leafIndex)}:${String(seq++)}`;
 }
 /** Pure wiring: build the full ProgramWorkerDeps from the control-plane handle. The runner reaches
- *  every privileged seam through the broker over its run token — no DB / Redis / Stripe / model creds. */
+ *  every privileged seam through the broker over its run token — no database, cache, billing, or model creds. */
 export function assembleWorkerDeps(runtime) {
     const broker = new RunnerControlClient({
         baseUrl: runtime.controlPlane.baseUrl,
@@ -114,8 +117,9 @@ export function assembleWorkerDeps(runtime) {
         freeze = new FreezeCoordinator({ channel });
         log.info("freeze_mode_enabled", { runId: runtime.runId });
     }
-    // Live agent-event stream → /telemetry (broker publishes to Redis server-side). Inference,
-    // web_search, artifacts, and the model call are all brokered — no Redis / model creds / Tavily / S3.
+    // Live agent-event stream → /telemetry (broker fans out server-side). Inference,
+    // web_search, artifacts, and the model call are all brokered — no cache client, model creds,
+    // search-provider creds, or object-storage creds here.
     const eventPublisher = new BrokerEventPublisher({
         send: (frames) => broker.publishTelemetry(frames),
     });
@@ -129,11 +133,11 @@ export function assembleWorkerDeps(runtime) {
     // bootstrap captured + scrubbed it (capturePlatformContext) so the agent's bash / subprocesses
     // can't read it. The program reaches it ONLY via `runtime.apiToken()` (built below); we still
     // record it in each run's redactor so a value the program threads into a tool can't echo back out
-    // of a tool result. Absent in the dev no-signing-key path. (the run env/credential rules)
+    // of a tool result. Absent in the dev no-signing-key path.
     // MUTABLE: on the snapshot substrate a wake carries a fresh token (the frozen one expired).
     let runApiKey = runtime.controlPlane.apiToken;
-    // The broker (Runner Control API) is hosted on the api-server, so the public API shares its
-    // origin; `runtime.apiUrl` exposes it and the program appends `/v1` or `/mcp/v1`.
+    // The broker (Runner Control API) shares an origin with the public API;
+    // `runtime.apiUrl` exposes it and the program appends `/v1` or `/mcp/v1`.
     const apiUrl = publicApiOrigin(runtime.controlPlane.baseUrl);
     // Per-run host: agent() leaf + sleep-hold + secrets + children + events, all brokered. `signal`
     // carries cooperative cancellation (credit exhaustion) into every host hook.
@@ -143,7 +147,7 @@ export function assembleWorkerDeps(runtime) {
             // Fallback budget-cap rate. A managed turn caps on the broker's EXACT upstream cost (forwarded on
             // the inference result frame → BudgetMeter `realCostUsd`); this representative sonnet-class rate
             // applies only to a turn with no upstream cost (BYO / unavailable). `max_usd` is a guardrail, not
-            // the bill — that's per-leaf cost pass-through at the broker.
+            // the bill — the platform meters the actual per-leaf usage.
             rate: BUDGET_GUARDRAIL_RATE,
             startedAt: Date.now(),
             // deadline_seconds is WALL-CLOCK from the run's ORIGINAL start (incl. suspended idle), so a run
@@ -160,7 +164,7 @@ export function assembleWorkerDeps(runtime) {
         const nextMeterIdentifier = tokenMeterIdentifiers(run.id, meteringSessionId);
         // Per-run secret boundary: every value resolved (program `secrets.get` OR a tool's
         // ctx.secrets.resolve) is recorded into one shared redactor; the leaf seeds a fresh engine
-        // Redactor from it so the loop scrubs those values out of all model-bound content. the platform spec
+        // Redactor from it so the loop scrubs those values out of all model-bound content.
         const redactor = new SecretRedactor();
         // Record the run's own API key so a prompt-injected agent can't echo it back to the model.
         if (runApiKey !== undefined && runApiKey !== "")
@@ -172,6 +176,26 @@ export function assembleWorkerDeps(runtime) {
         // Broker-backed artifact store (shared by the program's artifacts.write hook AND the engine's
         // host-backed `artifacts` tool). Presigned for large bodies; the runner holds no S3 creds.
         const artifactStore = new BrokerArtifactStore(broker);
+        // Browser tier (browser-session computer use): a per-run manager over the image's process backend.
+        // Only present when the runner image ships the browser stack (runtime.browserBackend set); else
+        // `computer.openBrowser()` throws "not available". A captured screenshot is stored as a run artifact
+        // through the SAME broker store — decoded from the MCP image block's base64 as binary bytes.
+        const browserSessions = runtime.browserBackend !== undefined
+            ? new BrowserSessionManager({
+                backend: runtime.browserBackend,
+                connect: connectSessionMcp,
+                writeArtifact: (name, contentType, base64, metadata) => artifactStore
+                    .write({
+                    name,
+                    contentType,
+                    body: base64,
+                    encoding: "base64",
+                    ...(metadata !== undefined ? { metadata } : {}),
+                })
+                    .then((res) => ({ id: res.id, name: res.name, url: res.signedUrl })),
+                nextId: () => newId(),
+            })
+            : undefined;
         // Backend for the engine's host-backed built-in tools (webfetch/web_search/artifacts): web_search
         // + artifact read-back go through the broker (no Tavily/S3 creds here); webfetch is an in-process
         // fetch already gated by the worker's egress proxy.
@@ -210,9 +234,9 @@ export function assembleWorkerDeps(runtime) {
             // until the artifact extracts. The empty `/workspace` and this dir are SEPARATE dirs on hosted,
             // exactly the two-tier case the engine's AGENTS.md loader is built for.
             programDir: () => programDir,
-            // Per-leaf, per-model token metering — reported THROUGH the broker (the worker holds no Stripe
-            // credential); the broker decides `billed_by_boardwalk` per model + meters to Stripe (BYO models
-            // no-op there). Fire-and-forget: a metering hiccup must never fail the run.
+            // Per-leaf, per-model token metering — reported THROUGH the broker (the worker holds no billing
+            // credential); the broker decides `billed_by_boardwalk` per model + meters usage to the platform
+            // (BYO models no-op there). Fire-and-forget: a metering hiccup must never fail the run.
             meterUsage: ({ model, inputTokens, outputTokens, cachedReadTokens, cachedWriteTokens, leafIndex, }) => {
                 void broker
                     .meterTokens({
@@ -237,7 +261,7 @@ 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 (§5): only when the manifest opts in. The BROKER additionally
+        // 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
@@ -311,6 +335,19 @@ export function assembleWorkerDeps(runtime) {
             // Snapshot-substrate suspension: seams freeze in place under the quiescence gate instead of
             // raising onSuspend (which stays wired as the transitional/local path's fallback).
             ...(freeze !== undefined ? { freeze } : {}),
+            // Register-without-release for held HITL gates — only on the
+            // freeze substrate, backed by the broker's inputs endpoints.
+            ...(freeze !== undefined
+                ? {
+                    heldInput: {
+                        register: (seq, gate) => broker.registerInput(seq, gate),
+                        poll: (seq) => broker.pollInputAnswers(seq),
+                    },
+                }
+                : {}),
+            // Browser tier: `computer.openBrowser()` + `agent({ session })` resolve through this manager
+            // (absent ⇒ the host throws "not available on this runner image").
+            ...(browserSessions !== undefined ? { browserSessions } : {}),
             phases: phaseTracker,
         });
         // Late-bind the coordinator's per-run hooks now that the run-scoped objects exist.
@@ -319,18 +356,21 @@ export function assembleWorkerDeps(runtime) {
             let freezeWallMs = 0;
             coordinator.setHooks({
                 // At quiescence, immediately before the freeze: book the runtime tail (suspended time must
-                // never appear billed — SUSPEND_POLICY) and persist the workspace (crash-during-suspension
+                // never appear billed) and persist the workspace (crash-during-suspension
                 // recovery parity with the sleep-hold path). The wall stamp anchors the idle rebase below.
                 onBeforeFreeze: async () => {
                     freezeWallMs = Date.now();
                     await activeFlusher?.flushNow();
                     await workspaceStore?.persist();
                 },
-                // On wake: swap the fresh tokens onto the broker client + the program-facing apiToken()
-                // (recording the new values in the run's redactor, same discipline as boot), and exclude
-                // the frozen window from billed runtime using the wake's authoritative wall clock (the
-                // guest's own clock was stopped).
+                // On wake: reseed the userspace CSPRNG (clause 3 — a suspend snapshot restored more than
+                // once, e.g. a re-dispatch retry, would otherwise repeat its post-wake `crypto.*` draws),
+                // swap the fresh tokens onto the broker client + the program-facing apiToken() (recording
+                // the new values in the run's redactor, same discipline as boot), and exclude the frozen
+                // window from billed runtime using the wake's authoritative wall clock. The reseed runs
+                // BEFORE the seam resolves, so no woken author code draws from the stale (pre-suspend) DRBG.
                 onAfterWake: (wake) => {
+                    reseedUserspaceCsprng();
                     broker.swapRunToken(wake.run_token);
                     redactor.record(wake.run_token);
                     if (wake.api_token !== undefined && wake.api_token !== "") {
@@ -364,6 +404,9 @@ export function assembleWorkerDeps(runtime) {
             // Resolves when a host seam suspends the run; the program runner races it against the body.
             suspendSignal,
             ...(workspaceStore !== undefined ? { 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 } : {}),
         });
     };
     return {
@@ -412,7 +455,7 @@ export function assembleWorkerDeps(runtime) {
         suspender: {
             suspend: (signal, workerId) => broker.suspend(signal, workerId),
         },
-        // Runtime metering (§15): flush runtime as periodic deltas (+ a terminal tail) through the broker,
+        // Runtime metering: flush runtime as periodic deltas (+ a terminal tail) through the broker,
         // idempotent per flush, so a long/perpetual run bills as it burns and the credit watcher sees it —
         // not a single charge at terminal (which a never-terminating run never reached). A fresh per-session
         // id keeps a restarted run's sessions distinct in the idempotency key (distinct ids sum).
@@ -434,7 +477,7 @@ export function assembleWorkerDeps(runtime) {
             return { stop: () => flusher.stop(), flushFinal: () => flusher.flushFinal() };
         },
         buildHost,
-        // Mid-run credit watching (§15): a CreditWatcher polls the broker's GET /credit on a timer; when
+        // Mid-run credit watching: a CreditWatcher polls the broker's GET /credit on a timer; when
         // the org runs out, onExhausted aborts the run (the orchestrator wires it to AbortController).
         startCreditWatch: ({ run, onExhausted }) => {
             const watcher = new CreditWatcher({
@@ -445,10 +488,10 @@ export function assembleWorkerDeps(runtime) {
             watcher.start();
             return { stop: () => watcher.stop() };
         },
-        // Mid-run user-cancel watching (§6): a CancelWatcher polls the broker's GET /cancel on a timer;
+        // Mid-run user-cancel watching: a CancelWatcher polls the broker's GET /cancel on a timer;
         // when the user cancels (the run is flipped to `cancelling`), onCancelled aborts the run. This is
-        // how the brokered (Redis-less) worker learns of a cancel — the api-server's Redis publish can't
-        // reach it.
+        // how the brokered (cache-less) worker learns of a cancel — the platform's cancel publish can't
+        // reach it directly.
         startCancelWatch: ({ run, onCancelled }) => {
             const watcher = new CancelWatcher({
                 runId: run.id,
@@ -458,7 +501,7 @@ export function assembleWorkerDeps(runtime) {
             watcher.start();
             return { stop: () => watcher.stop() };
         },
-        // Lease renewal (§6): a LeaseRenewer extends the lease through the broker's POST /renew on a timer
+        // Lease renewal: a LeaseRenewer extends the lease through the broker's POST /renew on a timer
         // (well under the lease), so a run longer than the 5-min lease isn't reclaimed mid-flight by the
         // recovery sweep. `renew` re-extends with the SAME workerId that claimed it; a null result (the
         // run is no longer ours) fires onLost → the run aborts `lease_lost` without finalizing.
@@ -481,7 +524,7 @@ export function assembleWorkerDeps(runtime) {
 }
 // ---- Bootstrap (real container only) -------------------------------------------------
 /**
- * The per-run platform values the dispatcher injects as container env (ecs_run_task_client.ts). They
+ * The per-run platform values the dispatcher injects as container env. They
  * are captured into private worker state at bootstrap and DELETED from `process.env` before any user
  * program / agent leaf / subprocess can run — the run token + API token are credentials, and nothing
  * untrusted run code touches should inherit them (the run env/credential rules). The user owns the rest
@@ -495,7 +538,7 @@ export const PLATFORM_ENV_KEYS = [
     "BOARDWALK_TASK_CPU_UNITS",
 ];
 /** The public-API origin a run uses for raw API / MCP / CLI calls. The broker (Runner Control API)
- *  is hosted on the api-server, so the public API shares its origin; the program appends `/v1` or
+ *  shares an origin with the public API, so the program appends `/v1` or
  *  `/mcp/v1`. Falls back to the broker URL unchanged if it can't be parsed. */
 export function publicApiOrigin(controlPlaneBaseUrl) {
     try {
@@ -519,7 +562,7 @@ export function capturePlatformContext(env) {
         return value.trim();
     };
     // The dispatcher always injects the control-plane handle (the Runner Credential Broker model). The runner is
-    // brokered-only — there is no DB/Redis/Stripe fallback — so a missing handle is a hard config error.
+    // brokered-only — there is no database, cache, or billing fallback — so a missing handle is a hard config error.
     const runId = read("RUN_ID");
     const apiToken = env.BOARDWALK_API_KEY?.trim();
     const controlPlane = {
@@ -552,6 +595,12 @@ export async function main() {
         relay.announceReady(workerDiagnostics());
         const identity = await relay.awaitIdentity();
         applyIdentityToEnv(identity, process.env);
+        // Clause 3 (SNAPSHOT_UNIQUENESS_CONTRACT): this run was restored from the SHARED base
+        // snapshot, so its OpenSSL DRBG is identical to every other run's. Reseed it from the
+        // (VMGenID-diverged) OS entropy BEFORE `acceptIdentity` releases the worker into the brokered
+        // lifecycle — so no `crypto.*` draw by the SDK, the agent, or author code can collide across
+        // clones. Every wake reseeds again (the after-wake hook).
+        reseedUserspaceCsprng();
         relay.acceptIdentity();
         // The relay now becomes the suspend/wake channel: assembleWorkerDeps opens it into the
         // FreezeCoordinator, and the host's suspending seams freeze in place instead of exiting.
@@ -564,6 +613,11 @@ export async function main() {
     const runId = platform.runId;
     const byoProviders = parseByoProviders(process.env.BOARDWALK_BYO_PROVIDERS);
     Reflect.deleteProperty(process.env, "BOARDWALK_BYO_PROVIDERS");
+    // Browser tier: only when the runner IMAGE declares the browser stack (BOARDWALK_BROWSER_TIER=1 +
+    // a Chrome path). The backend is run-independent (buildHost builds the per-run manager over it);
+    // absent ⇒ `computer.openBrowser()` fails clearly. Read here so env-reading stays out of the pure wiring.
+    const guestBrowserConfig = loadGuestBrowserConfig(process.env);
+    const browserBackend = guestBrowserConfig !== null ? makeGuestBrowserBackend(guestBrowserConfig) : undefined;
     const deps = assembleWorkerDeps({
         workerId: process.env.WORKER_ID ?? `worker-${runId}`,
         workspaceRoot: process.env.WORKSPACE_ROOT ?? "/workspace",
@@ -572,12 +626,13 @@ export async function main() {
         vcpus: platform.vcpus,
         ...(byoProviders.length > 0 ? { byoProviders } : {}),
         ...(freezeRelay !== undefined ? { freezeRelay } : {}),
+        ...(browserBackend !== undefined ? { browserBackend } : {}),
     });
-    // The only thing to drain is the batched telemetry buffer — the runner opens no DB/Redis/SQS.
+    // The only thing to drain is the batched telemetry buffer — the runner opens no database, cache, or queue.
     const cleanup = async () => {
         await deps.flushTelemetry?.().catch(() => undefined);
     };
-    // SIGTERM: ECS is stopping the task. Hold-and-pay has no mid-run checkpoint; we exit and let the
+    // SIGTERM: the orchestrator is stopping the task. Hold-and-pay has no mid-run checkpoint; we exit and let the
     // lease expire → the scheduler-sweep reclaims it and a fresh worker RESTARTS the run from the
     // top (Lambda/GHA semantics; durable children re-attach via idempotency). Crash-safe by design.
     let shuttingDown = false;

package/dist/runtime/leaf_executor.d.ts

@@ -32,7 +32,7 @@ export interface EngineLeafExecutorDeps {
     budget: BudgetMeter;
     /** RUN-level redactor (shared with the secret resolver): every resolved secret value is recorded
      *  here. We seed a fresh engine `Redactor` from it per leaf so the loop scrubs known values out of
-     *  the prompt, tool args/results, and transcript before they reach the model (the platform spec). */
+     *  the prompt, tool args/results, and transcript before they reach the model. */
     redactor: SecretRedactor;
     /** Builds this leaf's event sink; `leafIndex` (1-based) is only a metering identifier — the sink
      *  owns the run-global cursor. `identity` names the leaf on its turn frames. */
@@ -51,7 +51,7 @@ export interface EngineLeafExecutorDeps {
      *  omitted ⇒ no bundled tier (only the workspace AGENTS.md applies). */
     programDir?: () => string | null;
     /** Per-leaf token metering seam (fire-and-forget). Reports THIS leaf's tokens + its model to the
-     *  broker, which decides `billed_by_boardwalk` per model + meters to Stripe. Omitted in tests. */
+     *  broker, which decides `billed_by_boardwalk` per model + meters usage to the platform. Omitted in tests. */
     meterUsage?: (input: MeterUsageInput) => void;
     /** Backend for the engine's host-backed built-in tools (`webfetch` / `web_search` / `artifacts`):
      *  set as the leaf's `capabilities.host` so the engine registers them. Broker-backed on hosted runs

package/dist/runtime/program_runner.d.ts

@@ -53,7 +53,7 @@ export interface ProgramRunnerDeps {
      * Scrubs known secret values out of a string (the run's `SecretRedactor.redactText`). Applied to a
      * top-level throw's message before it is logged AND before it is returned to the worker — a program
      * that resolves a secret and then throws it in an error message must NOT land that secret raw in the
-     * logs or the finalized run output (the platform spec). Defaults to identity (tests/local).
+     * logs or the finalized run output. Defaults to identity (tests/local).
      */
     redactText?: (text: string) => string;
     /**

package/dist/runtime/program_runner.js

@@ -1,6 +1,6 @@
 // WorkflowProgramRunner — executes a workflow program (the JS-body model, the workflow runtime design).
 //
-// A run is the execution of a built program ARTIFACT (§3.9): the worker is handed the VERIFIED tarball
+// A run is the execution of a built program ARTIFACT: the worker is handed the VERIFIED tarball
 // (its sha256 already checked against the pinned digest by the orchestrator) plus the entry module
 // name. This module is the mechanism: it installs the host adapter + trigger payload onto the
 // `@boardwalk-labs/workflow` singleton, extracts the artifact into a unique temp dir under a

package/dist/runtime/program_worker.d.ts

@@ -24,7 +24,7 @@ export interface ProgramVersionReader {
         program: ProgramRef;
     } | null>;
 }
-/** Books the run's RUNTIME usage as periodic deltas (the worker's RuntimeFlusher; §10.7 + §15). The
+/** Books the run's RUNTIME usage as periodic deltas (the worker's RuntimeFlusher). The
  *  orchestrator drives the lifecycle: the timer flushes mid-run, `stop()` halts it at the body's end,
  *  and `flushFinal()` books the tail on a clean terminal (skipped on a `lease_lost` handoff — the new
  *  owner books its own runtime). Replaces the old single terminal runtime charge. */
@@ -51,7 +51,7 @@ export interface RunFinalizer {
 export interface RunSuspender {
     suspend(signal: SuspendSignal, workerId: string): Promise<void>;
 }
-/** Restores/snapshots the workflow's persistent `/workspace` (§5). Best-effort — both no-op when the
+/** Restores/snapshots the workflow's persistent `/workspace`. Best-effort — both no-op when the
  *  run isn't eligible (not opted-in / self-hosted), and neither throws. */
 export interface WorkspaceHandle {
     hydrate(): Promise<void>;
@@ -97,6 +97,12 @@ export type ProgramHostBuilder = (run: Run, manifest: WorkflowManifest, signal:
      *  program runner so a suspend short-circuits the body out of band (the durable-suspension design). Absent ⇒
      *  no durable suspension on this path (a suspend then surfaces as a thrown SuspendError). */
     suspendSignal?: Promise<SuspendSignal>;
+    /** The run's browser-session manager (browser tier). The orchestrator reaps every still-open session
+     *  on EVERY terminal path so no Chromium / Playwright MCP process leaks past the run. `closeAll` is
+     *  best-effort + never throws. Absent on images without the browser stack. */
+    browserSessions?: {
+        closeAll(): Promise<void>;
+    };
 }>;
 /** Handle to a running per-session loop (metering or credit watch); `stop()` ends + drains it. */
 export interface RunSessionHandle {
@@ -155,7 +161,7 @@ export interface ProgramWorkerDeps {
     /** Emit the program's `console.*` output as `log` run-events while the body runs (optional —
      *  absent disables capture). Wired by the entrypoint to the batched telemetry publisher. */
     onProgramLog?: (stream: LogStream, text: string) => void;
-    /** ECS task ARN (or any stable worker identity). */
+    /** Task ARN (or any stable worker identity). */
     workerId: string;
     /** Drain any buffered telemetry before the worker exits (brokered path's BrokerEventPublisher).
      *  Called by the worker entrypoint's cleanup; the orchestrator itself never invokes it. */

package/dist/runtime/program_worker.js

@@ -11,12 +11,12 @@
 //      aborted mid-flight — credit exhaustion — finalize failed with the abort reason).
 //
 // While the program runs, two per-session loops watch it (both brokered): a UsageFlusher meters token
-// deltas (§10.7) and a CreditWatcher polls the org's funding (§15). When credit hits zero the watcher
+// deltas and a CreditWatcher polls the org's funding. When credit hits zero the watcher
 // aborts the run's AbortSignal, which the WorkflowHost honors at every hook (cooperative
 // cancellation, run_abort.ts) — `signal.aborted` is authoritative for the terminal status.
 //
 // What's gone vs. the old worker: no checkpoint load/pause, no resume, no sleep/wait_for_child
-// pause outcomes (the program holds), no per-turn transcript. The Strands loop now lives one
+// pause outcomes (the program holds), no per-turn transcript. The agent loop now lives one
 // level down, behind the host's agent() leaf.
 //
 // v0 deferral (a clear seam): run-level outcome validation (needs program output capture).
@@ -111,6 +111,7 @@ export async function runProgramWorker(runId, deps) {
         return { kind: "failed", reason: "host_build_failed" };
     }
     const { host, redactor, workspace, phases, activity, setProgramDir, lsp, suspendSignal } = built;
+    const browserSessions = built.browserSessions;
     // Guarantee the /workspace sandbox dir exists for EVERY run (persist or not) so a program can write
     // to /workspace without a defensive mkdir. Runs before hydrate (whose extract targets the dir).
     // Best-effort — the image pre-creates the dir; a failure here would resurface at the program's write.
@@ -130,16 +131,16 @@ export async function runProgramWorker(runId, deps) {
     if (workspace !== undefined)
         await workspace.hydrate();
     // Token metering is PER-LEAF: each agent() leaf reports its own tokens + model to the broker, which
-    // decides `billed_by_boardwalk` per model + meters to Stripe (see leaf_executor `meterUsage`). A
+    // decides `billed_by_boardwalk` per model + meters usage to the platform (see leaf_executor `meterUsage`). A
     // workflow has no run-level model, so there is no run-level token metering here.
-    // Mid-run credit watching (§15): when the org runs out of credit, abort the run cooperatively.
+    // Mid-run credit watching: when the org runs out of credit, abort the run cooperatively.
     const credit = deps.startCreditWatch?.({
         run: claimed,
         onExhausted: () => {
             controller.abort(new RunAbortedError("credit_exhausted"));
         },
     });
-    // Mid-run user-cancel watching (§6): when the user cancels, abort the run cooperatively. The host
+    // Mid-run user-cancel watching: when the user cancels, abort the run cooperatively. The host
     // honors the abort at the next hook boundary (a `sleep` hold wakes immediately); the broker then
     // upgrades the terminal write to `cancelled` because the run was flipped to `cancelling`.
     const cancel = deps.startCancelWatch?.({
@@ -148,7 +149,7 @@ export async function runProgramWorker(runId, deps) {
             controller.abort(new RunAbortedError("cancelled"));
         },
     });
-    // Lease renewal (§6): heartbeat the lease so a long run isn't reclaimed mid-flight. If the lease is
+    // Lease renewal: heartbeat the lease so a long run isn't reclaimed mid-flight. If the lease is
     // definitively lost (another worker reclaimed it), abort `lease_lost` — the run stops without
     // finalizing (the new owner owns the terminal write; see the lease_lost guard after the body).
     const lease = deps.startLeaseRenew?.({
@@ -157,7 +158,7 @@ export async function runProgramWorker(runId, deps) {
             controller.abort(new RunAbortedError("lease_lost"));
         },
     });
-    // Runtime metering (§15): flush runtime as periodic deltas from the claim, so a long/perpetual run
+    // Runtime metering: flush runtime as periodic deltas from the claim, so a long/perpetual run
     // bills as it burns (and the credit watcher sees it) instead of only at terminal. The tail is booked
     // by `flushFinal()` after the body (on every path except a lease_lost handoff).
     const runtimeFlush = deps.startRuntimeFlush?.({ run: claimed, startedAtMs: sessionStartMs });
@@ -208,6 +209,16 @@ export async function runProgramWorker(runId, deps) {
         // is safe (it runs before the workspace snapshot, which is the slowest step).
         if (lsp !== undefined)
             await lsp.close();
+        // Reap every still-open browser session (kill Chromium + its Playwright MCP) on EVERY terminal
+        // path, before the workspace snapshot. Best-effort — a dead session must not mask the run's outcome.
+        if (browserSessions !== undefined) {
+            await browserSessions.closeAll().catch((err) => {
+                log.warn("browser_sessions_close_failed", {
+                    runId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
         // Snapshot the final /workspace so the workflow's NEXT run hydrates it. Best-effort.
         if (workspace !== undefined) {
             await workspace.persist();

package/dist/runtime/recording_secret_resolver.js

@@ -1,4 +1,4 @@
-// RecordingSecretResolver — the redaction feeder (the platform spec).
+// RecordingSecretResolver — the redaction feeder.
 //
 // Decorates any SecretResolver so EVERY value a run resolves — whether the workflow program asked
 // via `secrets.get(name)` or a tool asked via `ctx.secrets.resolve(ref)` — is recorded into the

package/dist/runtime/run_abort.js

@@ -1,11 +1,11 @@
 // run_abort — the provider-agnostic cooperative-cancellation substrate for a run (the Runner Credential Broker model).
 //
-// The cancellation primitive is a Web-standard `AbortSignal` — NOT a Strands/model concept. The worker
+// The cancellation primitive is a Web-standard `AbortSignal` — NOT a framework/model concept. The worker
 // owns one `AbortController` per run session; a watcher (credit, later user-cancel) calls
 // `controller.abort(new RunAbortedError(reason))`. The WorkflowHost honors that signal at every hook
 // boundary (`agent`/`sleep`/`workflows.call`/…), unwinding the program. The ONLY place that translates
-// the signal into a model-specific stop is the Strands leaf (signal → `agent.cancel()`); a future
-// non-Strands leaf honors the SAME `AbortSignal` its own way. So nothing here, in the host, or in the
+// the signal into a model-specific stop is the agent leaf (signal → the leaf's cancel path); a different
+// leaf implementation honors the SAME `AbortSignal` its own way. So nothing here, in the host, or in the
 // program-facing SDK depends on the model backend.
 //
 // `signal.aborted` is AUTHORITATIVE at the orchestrator: a program that catches RunAbortedError and

package/dist/runtime/runner_control_client.d.ts

@@ -13,6 +13,10 @@ export interface RunnerControlClientConfig {
     runId: string;
     /** Injected fetch (defaults to global fetch). */
     fetchImpl?: typeof fetch;
+    /** Per-call ceiling for short control calls (default 30s) — bounds a poll frozen mid-flight. */
+    controlTimeoutMs?: number;
+    /** Per-call ceiling for bulk artifact/workspace transfers (default 5 min). */
+    bulkTimeoutMs?: number;
 }
 /** The pinned program's download reference (the worker fetches + verifies + extracts it). */
 export interface BrokerProgram {
@@ -47,9 +51,24 @@ export declare class RunnerControlClient {
     /** The live bearer. Mutable: on the snapshot substrate a wake carries a FRESH run token (the
      *  frozen one expired while suspended) and the worker swaps it at runtime. */
     private runToken;
+    private readonly controlTimeoutMs;
+    private readonly bulkTimeoutMs;
     constructor(cfg: RunnerControlClientConfig);
     /** Swap the bearer for a fresh run token (the wake path). Every subsequent call uses it. */
     swapRunToken(token: string): void;
+    /**
+     * Every SHORT control call (claim / renew / cancel / credit / journal / …) goes through here so
+     * it carries a hard timeout. Without one, a poll frozen mid-flight on the snapshot substrate
+     * hangs FOREVER on restore (the socket is dead but never reset), and since a watcher serializes
+     * its ticks, one hung tick wedges that watcher — the dead-connections gotcha for the
+     * background pollers (lease/cancel/credit), which run on untracked timers the quiescence gate
+     * doesn't cover. Also plain robustness: no broker call should hang on a network blip. The
+     * streaming inference call is the ONE exception (long-lived NDJSON) and bypasses this.
+     */
+    private controlFetch;
+    /** Bulk transfers (artifact + workspace up/download over presigned S3) — a much larger ceiling
+     *  than a control call, but still bounded so a dead socket can't hang the run. */
+    private bulkFetch;
     /** Claim the run's lease. Returns the run on success, or null when it isn't claimable (409 —
      *  another worker has it, or it isn't pending), which the worker treats as "claim lost". */
     claim(workerId: string, leaseSeconds: number): Promise<{
@@ -89,8 +108,8 @@ export declare class RunnerControlClient {
      *  retried/duplicate flush idempotent; distinct per-flush ids sum into the run's runtime total. */
     reportUsage(runtimeSeconds: number, identifier: string): Promise<void>;
     /** Report a token-usage delta for incremental in-run metering (the usage flusher → broker). The
-     *  broker gates on the run's per-connection `billed_by_boardwalk` server-side + meters to Stripe;
-     *  `identifier` makes a retried/duplicate flush idempotent. Satisfies {@link TokenUsageReporter}. */
+     *  broker gates on the run's per-connection `billed_by_boardwalk` server-side + meters usage to the
+     *  platform; `identifier` makes a retried/duplicate flush idempotent. Satisfies {@link TokenUsageReporter}. */
     meterTokens(input: {
         inputTokens: number;
         outputTokens: number;
@@ -101,14 +120,20 @@ export declare class RunnerControlClient {
         cachedWriteTokens?: number;
     }): Promise<void>;
     /** Check whether the run's org is still funded (the CreditWatcher → broker). The broker reads the
-     *  live Stripe balance server-side; `false` means out of credit (the watcher then aborts the run). */
+     *  live billing balance server-side; `false` means out of credit (the watcher then aborts the run). */
     checkCredit(): Promise<boolean>;
     /** Check whether the run has been asked to cancel (the CancelWatcher → broker). `true` once the user
      *  cancelled the run (the broker flipped it to `cancelling`/`cancelled`); the watcher then aborts the
      *  run. Brokered because the runner holds no DB/Redis — this replaces the unreachable Redis channel. */
     checkCancelled(): Promise<boolean>;
+    /** Register-without-release: register a HELD HITL gate's request row
+     *  so it is answerable while the run keeps running — no suspend. Idempotent. Returns whether a new
+     *  gate was registered. */
+    registerInput(seq: number, gate: unknown): Promise<boolean>;
+    /** Poll the resolved answers for a held gate at `seq` (empty until a human responds). */
+    pollInputAnswers(seq: number): Promise<Record<string, unknown>>;
     /** Mint a presigned GET URL to restore this workflow's last `/workspace` snapshot (workspace
-     *  persistence, §5). `null` when the run isn't eligible (not opted-in, or self-hosted). */
+     *  persistence). `null` when the run isn't eligible (not opted-in, or self-hosted). */
     workspaceHydrateUrl(): Promise<string | null>;
     /** Mint a presigned PUT URL to snapshot this workflow's `/workspace` (the worker uploads the tarball
      *  straight to S3). `null` when the run isn't eligible. `sizeBytes` is the archive's on-disk size