@boardwalk-labs/runner 0.2.16 → 0.3.0-alpha.1

package/dist/runtime/runner_control_client.js

@@ -72,6 +72,43 @@ export class RunnerControlClient {
     bulkFetch(url, init) {
         return this.retryingFetch(url, init, this.bulkTimeoutMs);
     }
+    // The three shapes every UNIFORM control endpoint reduces to. Endpoints where a specific
+    // status is a meaningful answer (claim/renew 409, version/child 404, mcp/token 403, the
+    // no-body hydrate-url POST, and the streaming inference call) keep their own fetch logic.
+    // `op` is the error/log label passed to {@link brokerError} (it sometimes differs from the path).
+    /** GET a run-scoped control path; any status but 200 throws. The `as T` is the client's one
+     *  trust-boundary cast: the broker is the platform's own API and each caller names the
+     *  handler's documented reply shape. */
+    async getJson(op, suffix) {
+        const res = await this.controlFetch(this.url(suffix), {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, op);
+        return (await res.json());
+    }
+    /** POST a JSON body to a run-scoped control path; any status but `expect` throws. */
+    async postJson(op, suffix, body, expect = 200) {
+        const res = await this.controlFetch(this.url(suffix), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(body),
+        });
+        if (res.status !== expect)
+            throw await brokerError(res, op);
+        return (await res.json());
+    }
+    /** POST a JSON body to a run-scoped control path expecting an empty 204 reply. */
+    async postVoid(op, suffix, body) {
+        const res = await this.controlFetch(this.url(suffix), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(body),
+        });
+        if (res.status !== 204)
+            throw await brokerError(res, op);
+    }
     /**
      * One attempt per entry in the backoff schedule (+1): retry thrown network failures (connection
      * reset/refused mid-rollover, our own per-attempt timeout on a dead socket) and the
@@ -127,6 +164,8 @@ export class RunnerControlClient {
         return {
             run: body.run,
             lastEventCursor: body.lastEventCursor ?? 0,
+            ...(body.workflowVersion !== undefined ? { workflowVersion: body.workflowVersion } : {}),
+            ...(body.environment !== undefined ? { environment: body.environment } : {}),
         };
     }
     /** Heartbeat: extend our lease so a long run isn't reclaimed mid-flight. Returns the new
@@ -149,13 +188,7 @@ export class RunnerControlClient {
      *  whose lease expired and whose run was reclaimed + re-dispatched to a new owner), so a
      *  hung/partitioned worker that later recovers can't clobber the live run or revive a terminal one. */
     async finalize(status, output, workerId) {
-        const res = await this.controlFetch(this.url("finalize"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ status, output, workerId }),
-        });
-        if (res.status !== 204)
-            throw await brokerError(res, "finalize");
+        await this.postVoid("finalize", "finalize", { status, output, workerId });
     }
     /** Fetch the run's pinned manifest + program source, or null when the version is missing (404). */
     async getVersion() {
@@ -172,71 +205,40 @@ export class RunnerControlClient {
     /** Book a runtime-seconds DELTA (the worker's RuntimeFlusher → broker). `identifier` makes a
      *  retried/duplicate flush idempotent; distinct per-flush ids sum into the run's runtime total. */
     async reportUsage(runtimeSeconds, identifier) {
-        const res = await this.controlFetch(this.url("usage"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ runtimeSeconds, identifier }),
-        });
-        if (res.status !== 204)
-            throw await brokerError(res, "usage");
+        await this.postVoid("usage", "usage", { runtimeSeconds, identifier });
     }
     /** 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 usage to the
      *  platform; `identifier` makes a retried/duplicate flush idempotent. Satisfies {@link TokenUsageReporter}. */
     async meterTokens(input) {
-        const res = await this.controlFetch(this.url("usage/tokens"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify(input),
-        });
-        if (res.status !== 204)
-            throw await brokerError(res, "usage/tokens");
+        await this.postVoid("usage/tokens", "usage/tokens", input);
     }
     /** Check whether the run's org is still funded (the CreditWatcher → broker). The broker reads the
      *  live billing balance server-side; `false` means out of credit (the watcher then aborts the run). */
     async checkCredit() {
-        const res = await this.controlFetch(this.url("credit"), {
-            method: "GET",
-            headers: this.headers(false),
-        });
-        if (res.status !== 200)
-            throw await brokerError(res, "credit");
-        return (await res.json()).funded;
+        return (await this.getJson("credit", "credit")).funded;
     }
     /** 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. */
     async checkCancelled() {
-        const res = await this.controlFetch(this.url("cancel"), {
-            method: "GET",
-            headers: this.headers(false),
-        });
-        if (res.status !== 200)
-            throw await brokerError(res, "cancel");
-        return (await res.json()).cancelRequested;
+        return (await this.getJson("cancel", "cancel")).cancelRequested;
     }
     /** 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. */
     async registerInput(seq, gate) {
-        const res = await this.controlFetch(this.url("inputs"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ seq, humanInput: gate }),
+        const body = await this.postJson("register-input", "inputs", {
+            seq,
+            humanInput: gate,
         });
-        if (res.status !== 200)
-            throw await brokerError(res, "register-input");
-        return (await res.json()).registered;
+        return body.registered;
     }
     /** Poll the resolved answers for a held gate at `seq` (empty until a human responds). */
     async pollInputAnswers(seq) {
-        const res = await this.controlFetch(this.url(`inputs/${encodeURIComponent(String(seq))}`), {
-            method: "GET",
-            headers: this.headers(false),
-        });
-        if (res.status !== 200)
-            throw await brokerError(res, "poll-inputs");
-        return (await res.json()).answers;
+        const suffix = `inputs/${encodeURIComponent(String(seq))}`;
+        return (await this.getJson("poll-inputs", suffix))
+            .answers;
     }
     /** Mint a presigned GET URL to restore this workflow's last `/workspace` snapshot (workspace
      *  persistence). `null` when the run isn't eligible (not opted-in, or self-hosted). */
@@ -254,14 +256,7 @@ export class RunnerControlClient {
      *  (the worker tars BEFORE requesting the URL) — the broker records it for the org storage counter +
      *  daily meter; the snapshot overwrites one per-workflow key, so it's the workflow's full footprint. */
     async workspacePersistUrl(sizeBytes) {
-        const res = await this.controlFetch(this.url("workspace/persist-url"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ sizeBytes }),
-        });
-        if (res.status !== 200)
-            throw await brokerError(res, "workspace/persist-url");
-        const body = (await res.json());
+        const body = await this.postJson("workspace/persist-url", "workspace/persist-url", { sizeBytes });
         return body.url === null ? null : { url: body.url, contentType: body.contentType ?? "" };
     }
     /** Download bytes from a presigned S3 URL (workspace hydrate). `null` on 404 (no snapshot yet —
@@ -278,74 +273,37 @@ export class RunnerControlClient {
      *  third-party-verifiable token (gated server-side on `permissions.id_token: "write"`) — used to
      *  federate into the org's OWN cloud (AWS/GCP). DIFFERENT from this client's run token. */
     async requestOidcToken(audience) {
-        const res = await this.controlFetch(this.url("oidc/token"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ audience }),
+        return this.postJson("oidc/token", "oidc/token", {
+            audience,
         });
-        if (res.status !== 200)
-            throw await brokerError(res, "oidc/token");
-        return (await res.json());
     }
     /** Publish a batch of live agent-event frames (the SSE live-tail source) — the broker publishes
      *  them to the run's Redis channel server-side, so the runner holds no Redis credential. */
     async publishTelemetry(frames) {
-        const res = await this.controlFetch(this.url("telemetry"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ frames }),
-        });
-        if (res.status !== 204)
-            throw await brokerError(res, "telemetry");
+        await this.postVoid("telemetry", "telemetry", { frames });
     }
     /** Push a batch of encoded desktop frames (base64 JPEG) for the live-view surface — the broker
      *  republishes them to the run's live-view channel server-side (never durably stored; the session
      *  recording is the durable copy). See docs/SCREEN_CAPTURE.md §5. */
     async publishLiveView(frames) {
-        const res = await this.controlFetch(this.url("liveview"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ frames }),
-        });
-        if (res.status !== 204)
-            throw await brokerError(res, "liveview");
+        await this.postVoid("liveview", "liveview", { frames });
     }
     /** Is a browser currently watching this run's live-view? The capture loop polls this so it only
      *  captures + pushes frames while someone is attached (capture costs guest CPU + metered egress). */
     async liveViewWanted() {
-        const res = await this.controlFetch(this.url("liveview/wanted"), {
-            method: "GET",
-            headers: this.headers(false),
-        });
-        if (res.status !== 200)
-            throw await brokerError(res, "liveview/wanted");
-        const body = (await res.json());
+        const body = await this.getJson("liveview/wanted", "liveview/wanted");
         return body.wanted === true;
     }
     /** Store a run artifact through the broker (which holds the S3 credential + neutralizes the served
      *  content type server-side). Returns the catalog id + a signed download URL. */
     async writeArtifact(input) {
-        const res = await this.controlFetch(this.url("artifacts"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify(input),
-        });
-        if (res.status !== 201)
-            throw await brokerError(res, "artifacts");
-        return (await res.json());
+        return this.postJson("artifacts", "artifacts", input, 201);
     }
     /** Phase 1 of the LARGE-artifact path (the Runner Credential Broker model): presign an S3 PUT. The
      *  broker derives the S3 key + neutralizes/pins the served content type; it returns the upload URL +
      *  required headers + the `s3Key` to echo back at commit. No catalog row exists yet. */
     async presignArtifact(input) {
-        const res = await this.controlFetch(this.url("artifacts/presign"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify(input),
-        });
-        if (res.status !== 201)
-            throw await brokerError(res, "artifacts/presign");
-        return (await res.json());
+        return this.postJson("artifacts/presign", "artifacts/presign", input, 201);
     }
     /** Upload bytes to a presigned S3 URL (the large-artifact path). The `headers` come from the
      *  presign response and MUST be sent verbatim — the content type is pinned into the signature, so
@@ -360,47 +318,24 @@ export class RunnerControlClient {
      *  broker re-validates the run prefix + re-neutralizes the content type, then returns the catalog id
      *  + a signed download URL. */
     async commitArtifact(input) {
-        const res = await this.controlFetch(this.url("artifacts/commit"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify(input),
-        });
-        if (res.status !== 201)
-            throw await brokerError(res, "artifacts/commit");
-        return (await res.json());
+        return this.postJson("artifacts/commit", "artifacts/commit", input, 201);
     }
     /** List the artifacts this run has produced. */
     async listArtifacts() {
-        const res = await this.controlFetch(this.url("artifacts"), {
-            method: "GET",
-            headers: this.headers(false),
-        });
-        if (res.status !== 200)
-            throw await brokerError(res, "artifacts-list");
-        return (await res.json()).artifacts;
+        return (await this.getJson("artifacts-list", "artifacts"))
+            .artifacts;
     }
     /** Mint a fresh signed download URL for one of this run's artifacts. */
     async signArtifactUrl(artifactId, ttlSeconds) {
-        const res = await this.controlFetch(this.url(`artifacts/${encodeURIComponent(artifactId)}/signed-url`), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ ttlSeconds }),
-        });
-        if (res.status !== 200)
-            throw await brokerError(res, "artifacts-sign");
-        return (await res.json());
+        const suffix = `artifacts/${encodeURIComponent(artifactId)}/signed-url`;
+        return this.postJson("artifacts-sign", suffix, { ttlSeconds });
     }
     /** Resolve an org secret the run's manifest allows (the program's `secrets.get`). The broker
      *  enforces the allowlist + returns the value; a forbidden/missing secret surfaces as a throw. */
     async resolveSecret(name) {
-        const res = await this.controlFetch(this.url("secrets/resolve"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ name }),
+        const body = await this.postJson("secrets/resolve", "secrets/resolve", {
+            name,
         });
-        if (res.status !== 200)
-            throw await brokerError(res, "secrets/resolve");
-        const body = (await res.json());
         return body.value;
     }
     /** Broker a short-lived OAuth bearer for a hosted MCP server (the engine's `mcpToken` hook, called
@@ -427,14 +362,7 @@ export class RunnerControlClient {
     /** Proxy a web_search through the broker (which holds the Tavily key) — the runner sends the
      *  query, the broker calls Tavily and returns the results. */
     async webSearch(input) {
-        const res = await this.controlFetch(this.url("tools/web_search"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify(input),
-        });
-        if (res.status !== 200)
-            throw await brokerError(res, "tools/web_search");
-        return (await res.json());
+        return this.postJson("tools/web_search", "tools/web_search", input);
     }
     /** Create (or idempotently re-attach to) a child run for `workflows.call`. */
     async startChild(slug, input) {
@@ -450,14 +378,8 @@ export class RunnerControlClient {
     }
     /** Provision a durable schedule for `workflows.schedule`; returns the new schedule's id. */
     async scheduleWorkflow(slug, input, spec) {
-        const res = await this.controlFetch(this.url("schedules"), {
-            method: "POST",
-            headers: this.headers(true),
-            body: JSON.stringify({ slug, input, ...spec }),
-        });
-        if (res.status !== 201)
-            throw await brokerError(res, "schedules");
-        return (await res.json()).scheduleId;
+        const body = await this.postJson("schedules", "schedules", { slug, input, ...spec }, 201);
+        return body.scheduleId;
     }
     /** Poll a child run's status/output, or null when it isn't this run's child (404). */
     async getChild(childRunId) {

package/dist/runtime/screen_capture_backend.d.ts

@@ -16,4 +16,7 @@ export interface CaptureConfig {
 }
 /** Read the capture config from env, or null when the desktop stack is absent or recording is off. */
 export declare function loadCaptureConfig(env: NodeJS.ProcessEnv): CaptureConfig | null;
+/** ffmpeg args: one x11grab input, two outputs (change-driven segmented MP4 + a single overwritten
+ *  JPEG). Exported for unit testing. */
+export declare function ffmpegArgs(cfg: CaptureConfig, dir: string): string[];
 export declare function makeCaptureBackend(cfg: CaptureConfig): CaptureBackend;

package/dist/runtime/screen_capture_backend.js

@@ -2,6 +2,11 @@
 // the X display `:0` with two outputs — rolling MP4 segments (recording) and a single low-fps JPEG that
 // is continuously overwritten (the live-view frame). See docs/SCREEN_CAPTURE.md §4.
 //
+// The recording is CHANGE-DRIVEN (mpdecimate + VFR): it stays always-on but only encodes frames that
+// differ from the previous one, so an idle/headless desktop encodes ~nothing (a blank desktop collapses
+// to ~1 frame) while a changing screen records in full. This keeps the always-on desktop cheap enough
+// to run on every VM without a "record only when watched" gate.
+//
 // Only runs where the runner IMAGE ships the desktop stack (Xvfb + ffmpeg), gated by
 // BOARDWALK_BROWSER_TIER=1 (the same "desktop present" signal the browser tier uses) + a
 // BOARDWALK_RECORDING_ENABLED kill switch (default on). Off on Fargate / self-hosted images with no
@@ -42,8 +47,9 @@ export function loadCaptureConfig(env) {
         wantedPollIntervalMs: intFromEnv(env.BOARDWALK_LIVEVIEW_WANTED_POLL_MS, 3000),
     };
 }
-/** ffmpeg args: one x11grab input, two outputs (segmented MP4 + a single overwritten JPEG). */
-function ffmpegArgs(cfg, dir) {
+/** ffmpeg args: one x11grab input, two outputs (change-driven segmented MP4 + a single overwritten
+ *  JPEG). Exported for unit testing. */
+export function ffmpegArgs(cfg, dir) {
     const liveFps = Math.max(1, Math.round(1000 / cfg.liveFrameIntervalMs));
     return [
         "-y",
@@ -58,8 +64,17 @@ function ffmpegArgs(cfg, dir) {
         "-i",
         cfg.display,
         // Recording: H.264 MP4 segments, each a standalone playable file (docs/SCREEN_CAPTURE.md §4.2).
+        // Change-driven: `mpdecimate` drops near-duplicate frames and `-fps_mode vfr` lets the muxer honor
+        // those drops, so a static/idle desktop encodes ~nothing (collapses to ~1 frame) while a changing
+        // screen still records in full. Always-on — cost tracks on-screen activity, not a flat framerate.
+        // (`-preset ultrafast` would cut per-frame CPU further on busy screens but inflates file size; kept
+        //  `veryfast` so the change is a pure win with no storage/bandwidth regression.)
         "-map",
         "0:v",
+        "-vf",
+        "mpdecimate",
+        "-fps_mode",
+        "vfr",
         "-c:v",
         "libx264",
         "-preset",

package/dist/runtime/shell_exec.d.ts

@@ -0,0 +1,17 @@
+import type { ShellResult } from "@boardwalk-labs/workflow/runtime";
+/** Default cap on captured stdout/stderr bytes (matches the SDK's documented 16 MiB). */
+export declare const SHELL_DEFAULT_MAX_BUFFER: number;
+export interface ShellExecOptions {
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+    timeoutMs?: number | undefined;
+    maxBuffer?: number | undefined;
+}
+export interface ShellExecDeps {
+    /** The run's workspace root — the default cwd, and the base a relative `cwd` resolves against. */
+    workspaceRoot: string;
+    /** The run's cooperative-cancellation signal: an abort kills the command and REJECTS. */
+    signal?: AbortSignal | undefined;
+}
+/** Run one shell command to completion (see the module header for the resolve/reject contract). */
+export declare function runShell(cmd: string, opts: ShellExecOptions | undefined, deps: ShellExecDeps): Promise<ShellResult>;

package/dist/runtime/shell_exec.js

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: Apache-2.0
+// runShell — the host-side backing for the protocol's `shell` capability.
+//
+// The old SDK ran `execSync` inside the program process; under the host protocol the program is
+// a protocol client, so the command runs HERE (same VM, same trust domain — the program layer is
+// trusted) and the completed result crosses the wire. Contract (sdk shell.ts / protocol.ts):
+// resolve `{exitCode, stdout, stderr}` — a non-zero exit RESOLVES (data to branch on, never
+// thrown); only a command that could not run at all, an exceeded output buffer, or a cancelled
+// run rejects. A command killed by the `timeoutMs` option resolves with the shell convention
+// `128 + signal number` (SIGTERM ⇒ 143), the same exit code a shell would report.
+//
+// cwd defaults to the run's workspace root (the same dir `agent({ cwd })` resolves against);
+// `env` merges OVER the process env — the author owns process.env outright, and platform
+// credentials were scrubbed from it at bootstrap, so inheriting it leaks nothing.
+import { spawn } from "node:child_process";
+import { isAbsolute, join } from "node:path";
+import { throwIfAborted } from "./run_abort.js";
+/** Default cap on captured stdout/stderr bytes (matches the SDK's documented 16 MiB). */
+export const SHELL_DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+/** SIGKILL follows this long after a kill's SIGTERM if the process ignores it. */
+const SHELL_KILL_GRACE_MS = 5_000;
+const SIGNAL_EXIT_CODES = {
+    SIGHUP: 129,
+    SIGINT: 130,
+    SIGQUIT: 131,
+    SIGKILL: 137,
+    SIGTERM: 143,
+};
+/** Run one shell command to completion (see the module header for the resolve/reject contract). */
+export function runShell(cmd, opts, deps) {
+    throwIfAborted(deps.signal);
+    const cwd = opts?.cwd === undefined
+        ? deps.workspaceRoot
+        : isAbsolute(opts.cwd)
+            ? opts.cwd
+            : join(deps.workspaceRoot, opts.cwd);
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, {
+            shell: true,
+            cwd,
+            env: opts?.env === undefined ? process.env : { ...process.env, ...opts.env },
+            stdio: ["ignore", "pipe", "pipe"],
+            // Own process GROUP: `sh -c` may not exec-optimize, leaving the real command a GRANDCHILD
+            // holding the stdio pipes — killing only the shell would leak it and `close` would not
+            // fire until the grandchild exits. Group-kill reaches the whole tree. (Lockstep with the
+            // engine's src/run/shell_exec.ts.)
+            detached: true,
+        });
+        const maxBuffer = opts?.maxBuffer ?? SHELL_DEFAULT_MAX_BUFFER;
+        let stdout = "";
+        let stderr = "";
+        let settledReason = null;
+        let killTimer = null;
+        let graceTimer = null;
+        const killTree = (signal) => {
+            // Negative pid = the process group (see `detached`); fall back to the direct child when
+            // the group is already gone.
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch {
+                child.kill(signal);
+            }
+        };
+        const kill = (reason) => {
+            if (settledReason === null)
+                settledReason = reason;
+            killTree("SIGTERM");
+            // A process ignoring SIGTERM still ends: SIGKILL after a short grace.
+            graceTimer ??= setTimeout(() => {
+                killTree("SIGKILL");
+            }, SHELL_KILL_GRACE_MS);
+            graceTimer.unref();
+        };
+        if (opts?.timeoutMs !== undefined) {
+            killTimer = setTimeout(() => {
+                kill("timeout");
+            }, opts.timeoutMs);
+        }
+        const capture = (current, chunk) => {
+            const next = current + chunk.toString("utf8");
+            if (next.length > maxBuffer)
+                kill("maxBuffer"); // cap exceeded — stop the command, then reject
+            return next.length > maxBuffer ? next.slice(0, maxBuffer) : next;
+        };
+        child.stdout?.on("data", (chunk) => {
+            stdout = capture(stdout, chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = capture(stderr, chunk);
+        });
+        const onAbort = () => {
+            kill("abort");
+        };
+        if (deps.signal !== undefined)
+            deps.signal.addEventListener("abort", onAbort, { once: true });
+        const cleanup = () => {
+            if (killTimer !== null)
+                clearTimeout(killTimer);
+            if (graceTimer !== null)
+                clearTimeout(graceTimer);
+            if (deps.signal !== undefined)
+                deps.signal.removeEventListener("abort", onAbort);
+        };
+        child.on("error", (err) => {
+            // The command could not run at all (e.g. no shell) — a rejecting case.
+            cleanup();
+            reject(err);
+        });
+        child.on("close", (code, signal) => {
+            cleanup();
+            if (settledReason === "abort") {
+                try {
+                    throwIfAborted(deps.signal);
+                    reject(new Error("shell command aborted"));
+                }
+                catch (abortErr) {
+                    reject(abortErr instanceof Error ? abortErr : new Error(String(abortErr)));
+                }
+                return;
+            }
+            if (settledReason === "maxBuffer") {
+                // The ratified contract: an exceeded output cap REJECTS (never a silently truncated
+                // success). The message keeps node's conventional wording for greppability.
+                reject(new Error(`shell output exceeded maxBuffer (${String(maxBuffer)} bytes)`));
+                return;
+            }
+            if (code !== null) {
+                resolve({ exitCode: code, stdout, stderr });
+                return;
+            }
+            // Killed by the timeout (or an external signal): resolve with the shell's 128+signum
+            // convention so a timed-out command is still data to branch on.
+            if (signal !== null) {
+                resolve({ exitCode: SIGNAL_EXIT_CODES[signal] ?? 128, stdout, stderr });
+                return;
+            }
+            resolve({ exitCode: -1, stdout, stderr }); // neither code nor signal — Node says can't happen
+        });
+    });
+}

package/dist/runtime/support/index.d.ts

@@ -25,6 +25,12 @@ export declare class AppError extends Error {
     constructor(code: ErrorCode, message: string, detail?: unknown);
 }
 export declare function isAppError(err: unknown): err is AppError;
+/**
+ * The SEMANTIC code of a thrown value, or undefined when it carries none. Duck-typed rather than
+ * `instanceof` — errors cross package boundaries (SDK/engine dual copies), where class checks fail.
+ * The SCREAMING_SNAKE shape gate keeps prose out of a field consumers render as a code.
+ */
+export declare function errorCodeOf(err: unknown): string | undefined;
 /** Run-lease heartbeat period (ported from the platform's checkpoint module — the broker's
  *  renew endpoint mirrors it). */
 export declare const DEFAULT_LEASE_MS: number;
@@ -37,6 +43,18 @@ export interface Logger {
     warn(message: string, fields?: LogFields): void;
     error(message: string, fields?: LogFields): void;
 }
+/**
+ * Freeze the runner's log level from a TRUSTED env — the platform boot env, snapshotted before the
+ * identity relay overlays a run's author env onto process.env (see `main`). Call once at bootstrap.
+ *
+ * Until it's called — in tests, and in the CLI/daemon before boot — {@link activeLevel} falls back to
+ * reading process.env live, so an operator's `--verbose`/`--debug` (which sets the env BEFORE boot,
+ * bin.ts) still applies. After it's called, a workflow author's `meta.env` (overlaid onto process.env
+ * at run time) can no longer raise the runner's own log verbosity. An author-facing verbosity control
+ * belongs in the manifest `meta` (e.g. a `logVerbosity` field), delivered over the trusted control
+ * plane — never an env knob.
+ */
+export declare function configureLogging(env: NodeJS.ProcessEnv): void;
 export declare function createLogger(module: string): Logger;
 export type OrgRole = "owner" | "admin" | "member" | "viewer";
 export type AuthSource = "session_jwt" | "oauth_jwt" | "api_key" | "workflow";

package/dist/runtime/support/index.js

@@ -61,6 +61,20 @@ export class AppError extends Error {
 export function isAppError(err) {
     return err instanceof AppError;
 }
+/** A machine-readable error code is SCREAMING_SNAKE — an engine `EngineError.code` (`VALIDATION`,
+ *  `PROVIDER_ERROR`, …), an {@link AppError} code, and a Node syscall code (`ENOENT`) all are. */
+const ERROR_CODE_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
+/**
+ * The SEMANTIC code of a thrown value, or undefined when it carries none. Duck-typed rather than
+ * `instanceof` — errors cross package boundaries (SDK/engine dual copies), where class checks fail.
+ * The SCREAMING_SNAKE shape gate keeps prose out of a field consumers render as a code.
+ */
+export function errorCodeOf(err) {
+    if (typeof err !== "object" || err === null)
+        return undefined;
+    const code = err.code;
+    return typeof code === "string" && ERROR_CODE_RE.test(code) ? code : undefined;
+}
 // ---- leases ----
 /** Run-lease heartbeat period (ported from the platform's checkpoint module — the broker's
  *  renew endpoint mirrors it). */
@@ -71,15 +85,33 @@ export function newId() {
     return randomUUID();
 }
 const LEVEL_ORDER = { DEBUG: 10, INFO: 20, WARN: 30, ERROR: 40 };
-/** Active log level: BOARDWALK_RUNNER_LOG_LEVEL (debug|info|warn|error), default info.
- *  BOARDWALK_RUNNER_DEBUG=1 is a legacy alias for debug. Read per call so a CLI flag that
- *  sets the env (e.g. `--verbose` / `--debug`) applies without logger re-creation. */
-function activeLevel() {
-    if (process.env.BOARDWALK_RUNNER_DEBUG === "1")
+/** Numeric log level from an env: BOARDWALK_RUNNER_LOG_LEVEL (debug|info|warn|error), default info;
+ *  BOARDWALK_RUNNER_DEBUG=1 is a legacy alias for debug. Reads the passed `env`, not process.env. */
+function levelFromEnv(env) {
+    if (env.BOARDWALK_RUNNER_DEBUG === "1")
         return LEVEL_ORDER.DEBUG ?? 10;
-    const name = process.env.BOARDWALK_RUNNER_LOG_LEVEL?.toUpperCase() ?? "INFO";
+    const name = env.BOARDWALK_RUNNER_LOG_LEVEL?.toUpperCase() ?? "INFO";
     return LEVEL_ORDER[name] ?? 20;
 }
+/** The level frozen at worker bootstrap from the TRUSTED boot env, or null until then. */
+let configuredLevel = null;
+/**
+ * Freeze the runner's log level from a TRUSTED env — the platform boot env, snapshotted before the
+ * identity relay overlays a run's author env onto process.env (see `main`). Call once at bootstrap.
+ *
+ * Until it's called — in tests, and in the CLI/daemon before boot — {@link activeLevel} falls back to
+ * reading process.env live, so an operator's `--verbose`/`--debug` (which sets the env BEFORE boot,
+ * bin.ts) still applies. After it's called, a workflow author's `meta.env` (overlaid onto process.env
+ * at run time) can no longer raise the runner's own log verbosity. An author-facing verbosity control
+ * belongs in the manifest `meta` (e.g. a `logVerbosity` field), delivered over the trusted control
+ * plane — never an env knob.
+ */
+export function configureLogging(env) {
+    configuredLevel = levelFromEnv(env);
+}
+function activeLevel() {
+    return configuredLevel ?? levelFromEnv(process.env);
+}
 function emit(level, module, message, fields) {
     if ((LEVEL_ORDER[level] ?? 20) < activeLevel())
         return;

package/dist/runtime/wire/inference_proxy.js

@@ -22,7 +22,7 @@
 // A well-formed stream is zero-or-more `delta` frames followed by EXACTLY ONE `result` frame, OR a
 // single terminal `error` frame. The neutral conversation shapes (ChatMessage / ChatTurn / ToolSpec)
 // are the engine's `@boardwalk-labs/engine/core` types — so the worker's loop and the broker's
-// adapters speak the same wire as `boardwalk dev` and the self-hosted server (one agent loop).
+// adapters speak the same wire as the self-hosted server (one agent loop).
 /** `POST /runner/v1/runs/{run_id}/inference` (run-token authed; the addressed run must match). */
 export const RUNNER_INFERENCE_PATH_RE = /^\/runner\/v1\/runs\/([^/]+)\/inference$/;
 /** Build the inference path for a run. */