@boardwalk-labs/runner 0.2.16 → 0.2.17

package/dist/bin.js

@@ -156,6 +156,10 @@ const USAGE = `boardwalk-runner <register|start|deregister> [flags]
 async function mainCli() {
     // --verbose: debug-level daemon logs (poll cycles, heartbeats). --debug: the same, PLUS the
     // spawned run processes log debug too (the env below is forwarded to children by realSpawn).
+    // Sanctioned OPERATOR write of the runner log env, BEFORE any worker boots — the worker's
+    // `configureLogging` snapshots it from the trusted boot env, so this operator flag wins while a
+    // run's author `meta.env` (applied later, over the relay) does not.
+    /* eslint-disable no-restricted-syntax -- operator sets the runner log env pre-boot; not author-reachable */
     if (hasFlag("debug")) {
         process.env.BOARDWALK_RUNNER_LOG_LEVEL = "debug";
         process.env.BOARDWALK_RUNNER_DEBUG = "1";
@@ -163,6 +167,7 @@ async function mainCli() {
     else if (hasFlag("verbose")) {
         process.env.BOARDWALK_RUNNER_LOG_LEVEL = "debug";
     }
+    /* eslint-enable no-restricted-syntax */
     const cmd = process.argv[2];
     if (cmd === "register")
         return await cmdRegister();

package/dist/runtime/identity_relay.js

@@ -75,18 +75,28 @@ export function applyIdentityToEnv(identity, env) {
     for (const [key, value] of Object.entries(identity.env ?? {})) {
         env[key] = value;
     }
+    // The platform transport keys OWN their names: assert the trusted value, or DELETE the key when the
+    // identity omits it — so an author's `meta.env` (applied just above) can NEVER survive on a platform
+    // key. RUN_ID / control-plane URL / run token are always present; the api token, task size, and BYO
+    // registry are optional, so they set-or-clear (a conditional-only overwrite would leave an
+    // author-supplied `BOARDWALK_TASK_CPU_UNITS` / `BOARDWALK_API_KEY` / `BOARDWALK_BYO_PROVIDERS` in
+    // place for a run whose identity happens not to carry that field — e.g. an org with no BYO providers).
     env.RUN_ID = identity.run_id;
     env.BOARDWALK_CONTROL_PLANE_URL = identity.control_plane_url;
     env.BOARDWALK_RUN_TOKEN = identity.run_token;
-    if (identity.api_token !== undefined && identity.api_token.length > 0) {
-        env.BOARDWALK_API_KEY = identity.api_token;
-    }
-    if (identity.task_cpu_units !== undefined) {
-        env.BOARDWALK_TASK_CPU_UNITS = String(identity.task_cpu_units);
-    }
-    if (identity.byo_providers !== undefined) {
-        env.BOARDWALK_BYO_PROVIDERS = JSON.stringify(identity.byo_providers);
-    }
+    setOrClear(env, "BOARDWALK_API_KEY", identity.api_token !== undefined && identity.api_token.length > 0
+        ? identity.api_token
+        : undefined);
+    setOrClear(env, "BOARDWALK_TASK_CPU_UNITS", identity.task_cpu_units !== undefined ? String(identity.task_cpu_units) : undefined);
+    setOrClear(env, "BOARDWALK_BYO_PROVIDERS", identity.byo_providers !== undefined ? JSON.stringify(identity.byo_providers) : undefined);
+}
+/** Assert a trusted value on a platform transport key, or DELETE the key when absent — so an
+ *  author-overlaid value on that reserved-by-transport name never survives into the run env. */
+function setOrClear(env, key, value) {
+    if (value !== undefined)
+        env[key] = value;
+    else
+        Reflect.deleteProperty(env, key);
 }
 /** Collect the worker_ready diagnostics. Version lookups are best-effort: the runner's own
  *  package.json sits two levels above this module in both the src and published dist

package/dist/runtime/index.d.ts

@@ -3,7 +3,9 @@ import type { Run } from "./wire/run.js";
 import { type IdentityRelay } from "./identity_relay.js";
 import type { ByoInferenceProvider } from "../contract.js";
 import { type BrowserBackend } from "./browser_session.js";
+import { type GuestBrowserConfig } from "./browser_session_backend.js";
 import { type CaptureBackend } from "./screen_capture.js";
+import { type CaptureConfig } from "./screen_capture_backend.js";
 import { type ProgramWorkerDeps } from "./program_worker.js";
 /** Constructed primitives the pure assembly consumes (real ones in main(), fakes in tests). The
  *  runner holds NO platform credential — only the per-run control-plane handle (run token + broker
@@ -54,6 +56,10 @@ export interface WorkerRuntime {
     /** Screen-capture backend (session recording + live-view frames), present ONLY when the runner IMAGE
      *  ships the desktop stack (ffmpeg + an X display) and recording isn't disabled. Absent ⇒ no capture. */
     captureBackend?: CaptureBackend;
+    /** Path for the on-screen run-log mirror an xterm in the ambient desktop tails (BOARDWALK_RUN_LOG_FILE,
+     *  set by the desktop guest image). Resolved by `main` from the trusted platform BOOT env so a run's
+     *  author `meta.env` can't repoint it; absent off the desktop tier ⇒ no local sink. */
+    runLogFilePath?: string;
 }
 /** 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
@@ -109,4 +115,36 @@ export declare function publicApiOrigin(controlPlaneBaseUrl: string): string;
  * `env` (called once on `process.env` at the very top of `main`, before any run code can read it).
  */
 export declare function capturePlatformContext(env: NodeJS.ProcessEnv): PlatformContext;
+/**
+ * The platform-owned config the worker reads for ITSELF: the browser/desktop tier, screen capture, and
+ * the run's sandbox roots / worker id / run-log mirror. All resolved from the passed env — which `main`
+ * captures from the trusted BOOT env (image-baked `/etc/bwimage.env`) BEFORE the identity relay overlays
+ * the run's author env onto process.env. Consumers use these TYPED fields, never process.env, so a
+ * workflow author's `meta.env` can't shadow platform behavior while the author still owns process.env
+ * outright (docs/RUN_ENV_AND_CREDS.md). Distinct from {@link capturePlatformContext}, which resolves the
+ * per-run CREDENTIALS the relay injects (read post-overlay, then scrubbed).
+ */
+export interface PlatformConfig {
+    /** Browser/desktop tier backend config, or null when the image ships no browser stack. */
+    browser: GuestBrowserConfig | null;
+    /** Screen-capture config, or null when the image ships no desktop stack / recording is off. */
+    capture: CaptureConfig | null;
+    /** Stable worker id (WORKER_ID); absent ⇒ the caller derives one from the run id. */
+    workerId?: string;
+    /** Sandbox workspace root (WORKSPACE_ROOT), default `/workspace`. */
+    workspaceRoot: string;
+    /** Program-extraction root (PROGRAM_ROOT), default `<tmpdir>/bw-programs`. */
+    programRoot: string;
+    /** Self-hosted durable-workspace scope (PERSIST_SCOPE_DIR); set by the daemon only. */
+    persistScopeDir?: string;
+    /** Ambient-desktop run-log mirror path (BOARDWALK_RUN_LOG_FILE); set by the desktop image only. */
+    runLogFilePath?: string;
+}
+/**
+ * Resolve {@link PlatformConfig} from the trusted BOOT env. This is the ONE place env is read for the
+ * worker's own platform config — every other module consumes the typed result — so platform behavior
+ * never depends on the author-mutable process.env. Pure (unit-tested). MUST be called on the boot-env
+ * snapshot taken BEFORE the identity relay overlays the author env (see `main`).
+ */
+export declare function capturePlatformConfig(bootEnv: NodeJS.ProcessEnv): PlatformConfig;
 export declare function main(): Promise<void>;

package/dist/runtime/index.js

@@ -26,7 +26,7 @@
 //
 // 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 { createLogger, configureLogging, newId, AppError, ErrorCode, DEFAULT_LEASE_MS, } from "./support/index.js";
 import { LspService } from "@boardwalk-labs/engine/core";
 import { BudgetMeter } from "./agent/budget.js";
 import { WorkerRunEventEmitter } from "./run_event_emitter.js";
@@ -44,7 +44,7 @@ import { WorkerWorkflowHost } from "./workflow_host.js";
 import { BrowserSessionManager } from "./browser_session.js";
 import { loadGuestBrowserConfig, makeGuestBrowserBackend, connectSessionMcp, } from "./browser_session_backend.js";
 import { ScreenCapture } from "./screen_capture.js";
-import { loadCaptureConfig, makeCaptureBackend } from "./screen_capture_backend.js";
+import { loadCaptureConfig, makeCaptureBackend, } from "./screen_capture_backend.js";
 import { runProgramWorker, } from "./program_worker.js";
 import { RunnerControlClient } from "./runner_control_client.js";
 import { BrokerChildDispatcher } from "./broker_child_dispatcher.js";
@@ -131,9 +131,10 @@ export function assembleWorkerDeps(runtime) {
     // monotonic with no separate program band. Frames publish as `{cursor, event}` rows via the
     // broker telemetry path. The claim wrapper below bumps it past a previous session's frames.
     // Optional on-screen mirror: append the (already-redacted) event stream to a local file an xterm in
-    // the ambient desktop tails, so the live-view/recording shows the run working. Opt-in via the env the
-    // desktop guest image sets (BOARDWALK_RUN_LOG_FILE); absent everywhere else, so no cost off-desktop.
-    const runLogFilePath = process.env.BOARDWALK_RUN_LOG_FILE?.trim();
+    // the ambient desktop tails, so the live-view/recording shows the run working. The path is injected
+    // (resolved by `main` from the trusted platform BOOT env), so env-reading stays out of this pure
+    // wiring and a run's author env can't repoint the mirror. Absent off the desktop tier ⇒ no sink.
+    const runLogFilePath = runtime.runLogFilePath?.trim();
     const runLogLocalSink = runLogFilePath !== undefined && runLogFilePath !== ""
         ? makeRunLogFileSink(runLogFilePath)
         : undefined;
@@ -660,7 +661,44 @@ export function capturePlatformContext(env) {
         Reflect.deleteProperty(env, key);
     return { runId, controlPlane, vcpus };
 }
+/**
+ * Resolve {@link PlatformConfig} from the trusted BOOT env. This is the ONE place env is read for the
+ * worker's own platform config — every other module consumes the typed result — so platform behavior
+ * never depends on the author-mutable process.env. Pure (unit-tested). MUST be called on the boot-env
+ * snapshot taken BEFORE the identity relay overlays the author env (see `main`).
+ */
+export function capturePlatformConfig(bootEnv) {
+    return {
+        browser: loadGuestBrowserConfig(bootEnv),
+        capture: loadCaptureConfig(bootEnv),
+        ...(bootEnv.WORKER_ID !== undefined ? { workerId: bootEnv.WORKER_ID } : {}),
+        workspaceRoot: bootEnv.WORKSPACE_ROOT ?? "/workspace",
+        // Never inside the workspace, and never `process.cwd()` (WORKSPACE_PERSISTENCE.md I2). `tmpdir()`
+        // honors TMPDIR, which the self-hosted daemon points at the per-run dir — so concurrent daemons on
+        // one machine don't collide, and the hosted lanes get the VM's own /tmp.
+        programRoot: bootEnv.PROGRAM_ROOT ?? join(tmpdir(), "bw-programs"),
+        ...(bootEnv.PERSIST_SCOPE_DIR !== undefined
+            ? { persistScopeDir: bootEnv.PERSIST_SCOPE_DIR }
+            : {}),
+        ...(bootEnv.BOARDWALK_RUN_LOG_FILE !== undefined
+            ? { runLogFilePath: bootEnv.BOARDWALK_RUN_LOG_FILE }
+            : {}),
+    };
+}
 export async function main() {
+    // Snapshot the platform-owned BOOT env (image-baked `/etc/bwimage.env`, plus anything the
+    // launcher/daemon set) BEFORE the identity relay overlays the run's AUTHOR env onto process.env below,
+    // and resolve the worker's OWN config from it up front. The worker reads platform behavior only from
+    // these trusted values — never the author-mutable process.env — so a workflow's `meta.env` can't
+    // shadow it (`BOARDWALK_RECORDING_ENABLED=0`, `BOARDWALK_BROWSER_TIER=0`, `BOARDWALK_RUNNER_LOG_LEVEL`,
+    // repointing `WORKSPACE_ROOT`, ...). The author still owns process.env outright — no reserved keys
+    // (docs/RUN_ENV_AND_CREDS.md); an eslint rule bans `process.env.BOARDWALK_*` reads to keep it that way.
+    // Per-run values the relay ITSELF delivers (run token, api token, task size, BYO providers) are a
+    // separate channel: `applyIdentityToEnv` set-or-clears them over the author env, so they stay trusted
+    // in process.env. On env-boot substrates (Fargate/self-hosted, no relay) this equals the boot env.
+    const platformBootEnv = { ...process.env };
+    configureLogging(platformBootEnv);
+    const platformConfig = capturePlatformConfig(platformBootEnv);
     // Relay-mode bootstrap (the snapshot-based microVM substrate): when the guest init handed
     // us an identity relay fd, park here — warm, generic, pre-identity; this await is what the
     // base snapshot freezes — until the run's identity arrives, then map it onto process.env
@@ -690,27 +728,30 @@ export async function main() {
     // API token (the run env/credential rules). WORKER_ID / WORKSPACE_ROOT are non-secret infra knobs.
     const platform = capturePlatformContext(process.env);
     const runId = platform.runId;
+    // BYO providers are a per-run value the relay delivers, NOT image-baked config — read post-overlay.
+    // `applyIdentityToEnv` set-or-clears this key over the author env, so the value here is the org's
+    // registry (or empty), never an author's `meta.env`. (Sanctioned platform-key read; the general ban
+    // on `process.env.BOARDWALK_*` is what routes image config through `platformBootEnv` above.)
+    // eslint-disable-next-line no-restricted-syntax -- relay-asserted per-run key, trusted post-overlay
     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;
-    // Screen capture (recording + live-view): present only when the image ships the desktop stack
-    // (ffmpeg + a display) and recording isn't disabled. Read here so env-reading stays out of the wiring.
-    const captureConfig = loadCaptureConfig(process.env);
-    const captureBackend = captureConfig !== null ? makeCaptureBackend(captureConfig) : undefined;
+    // Construct the image-tier backends from the typed platform config (env already read once, above).
+    // Browser tier: present only when the image declares the browser stack (BOARDWALK_BROWSER_TIER=1 + a
+    // Chrome path); absent ⇒ `computer.openBrowser()` fails clearly. Screen capture: present only when the
+    // image ships the desktop stack (ffmpeg + a display) and recording isn't disabled.
+    const browserBackend = platformConfig.browser !== null ? makeGuestBrowserBackend(platformConfig.browser) : undefined;
+    const captureBackend = platformConfig.capture !== null ? makeCaptureBackend(platformConfig.capture) : undefined;
     const deps = assembleWorkerDeps({
-        workerId: process.env.WORKER_ID ?? `worker-${runId}`,
-        workspaceRoot: process.env.WORKSPACE_ROOT ?? "/workspace",
-        // Never inside the workspace, and never `process.cwd()` (WORKSPACE_PERSISTENCE.md I2). `tmpdir()`
-        // honors TMPDIR, which the self-hosted daemon points at the per-run dir — so concurrent daemons on
-        // one machine don't collide, and the hosted lanes get the VM's own /tmp.
-        programRoot: process.env.PROGRAM_ROOT ?? join(tmpdir(), "bw-programs"),
-        // Set by the self-hosted daemon only (both isolation lanes); hosted images never set it.
-        ...(process.env.PERSIST_SCOPE_DIR !== undefined
-            ? { persistScopeDir: process.env.PERSIST_SCOPE_DIR }
+        // Worker-self config from the typed platform config (trusted boot env), never process.env — so a
+        // run's `meta.env` can't repoint its own workspace/program roots, worker id, or run-log mirror.
+        workerId: platformConfig.workerId ?? `worker-${runId}`,
+        workspaceRoot: platformConfig.workspaceRoot,
+        programRoot: platformConfig.programRoot,
+        ...(platformConfig.persistScopeDir !== undefined
+            ? { persistScopeDir: platformConfig.persistScopeDir }
+            : {}),
+        ...(platformConfig.runLogFilePath !== undefined
+            ? { runLogFilePath: platformConfig.runLogFilePath }
             : {}),
         runId,
         controlPlane: platform.controlPlane,

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/support/index.d.ts

@@ -37,6 +37,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

@@ -71,15 +71,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {