@boardwalk-labs/runner 0.1.7 → 0.1.9

package/dist/bin.d.ts

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-export {};
+import { type IsolationConfig } from "./daemon/index.js";
+/** Build the isolation config from CLI flags: containerized by default; `--host` is the escape hatch. */
+export declare function isolationFromFlags(): IsolationConfig;

package/dist/bin.js

@@ -14,14 +14,12 @@
 //
 // Corporate proxies: launch with NODE_USE_ENV_PROXY=1 and HTTPS_PROXY set — Node's fetch (the
 // daemon) and the spawned run processes both honor it.
-import { spawn as nodeSpawn } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import * as os from "node:os";
 import { createLogger } from "./runtime/support/index.js";
 import { runnerOsSchema, runnerArchSchema } from "./contract.js";
-import { PoolClient, defaultIdentityDir, loadIdentity, removeIdentity, saveIdentity, startDaemon, } from "./daemon/index.js";
+import { PoolClient, defaultIdentityDir, loadIdentity, removeIdentity, saveIdentity, startRunner, } from "./daemon/index.js";
 const log = createLogger("boardwalk-runner");
 function flag(name) {
     const i = process.argv.indexOf(`--${name}`);
@@ -48,47 +46,6 @@ function machineArch() {
     const parsed = runnerArchSchema.safeParse(process.arch);
     return parsed.success ? parsed.data : undefined;
 }
-/** Real spawner: one Node process per run, executing the SAME runtime a hosted worker boots.
- *  Env is exactly the platform contract + the claim's resolved vars, over a minimal base
- *  (PATH + proxy knobs from the daemon's own environment; HOME = the run's workspace). */
-function realSpawn(opts) {
-    const base = {};
-    for (const key of [
-        "PATH",
-        "LANG",
-        "NODE_USE_ENV_PROXY",
-        "HTTPS_PROXY",
-        "https_proxy",
-        "HTTP_PROXY",
-        "http_proxy",
-        "NO_PROXY",
-        "no_proxy",
-        "BOARDWALK_RUNNER_DEBUG",
-    ]) {
-        const v = process.env[key];
-        if (v !== undefined)
-            base[key] = v;
-    }
-    const child = nodeSpawn(process.execPath, [opts.entry], {
-        cwd: opts.cwd,
-        env: { ...base, HOME: opts.cwd, TMPDIR: path.join(opts.cwd, "..", "tmp"), ...opts.env },
-        stdio: "inherit",
-    });
-    const exit = new Promise((resolve) => {
-        child.on("exit", (code, signal) => {
-            resolve(code ?? (signal !== null ? 143 : 1));
-        });
-        child.on("error", () => {
-            resolve(1);
-        });
-    });
-    return {
-        wait: () => exit,
-        kill: () => {
-            child.kill("SIGTERM");
-        },
-    };
-}
 async function cmdRegister() {
     const baseUrl = requireFlag("url");
     const token = requireFlag("token");
@@ -114,6 +71,23 @@ async function cmdRegister() {
     log.info("registered", { runnerId: res.runner_id, pool: res.pool, identity: file });
     process.stdout.write(`Registered runner ${res.runner_id} in pool '${res.pool}'.\nStart it with: boardwalk-runner start --url ${baseUrl} --pool ${res.pool}\n`);
 }
+/** Build the isolation config from CLI flags: containerized by default; `--host` is the escape hatch. */
+export function isolationFromFlags() {
+    if (hasFlag("host"))
+        return { mode: "host" };
+    const image = flag("image");
+    const network = flag("network");
+    const mounts = (flag("mount") ?? "")
+        .split(",")
+        .map((m) => m.trim())
+        .filter((m) => m.length > 0);
+    return {
+        mode: "container",
+        ...(image !== undefined ? { image } : {}),
+        ...(network !== undefined ? { network } : {}),
+        ...(mounts.length > 0 ? { mounts } : {}),
+    };
+}
 async function cmdStart() {
     const baseUrl = requireFlag("url");
     const pool = flag("pool") ?? "default";
@@ -123,32 +97,15 @@ async function cmdStart() {
         process.stderr.write(`No saved identity for ${baseUrl} pool '${pool}'. Run boardwalk-runner register first.\n`);
         process.exit(1);
     }
-    const workDir = flag("work-dir") ?? path.join(identityDir, "work");
-    const runtimeEntry = fileURLToPath(new URL("./runtime/main.js", import.meta.url));
-    const client = new PoolClient({ baseUrl, runnerToken: identity.runner_token });
-    const daemon = startDaemon({
-        client,
-        runtimeEntry,
-        workDir,
-        runnerId: identity.runner_id,
-        spawn: realSpawn,
+    // The daemon lifecycle + isolation decision live in the shared startRunner — this binary and the
+    // main CLI both call it, so their behavior can't drift.
+    await startRunner({
+        baseUrl,
+        identity,
+        isolation: isolationFromFlags(),
+        workDir: flag("work-dir") ?? path.join(identityDir, "work"),
         ...(hasFlag("once") ? { once: true } : {}),
     });
-    let interrupts = 0;
-    for (const signal of ["SIGINT", "SIGTERM"]) {
-        process.on(signal, () => {
-            interrupts += 1;
-            if (interrupts === 1) {
-                process.stderr.write("\nDraining: finishing the current run, claiming nothing new. Ctrl-C again to force-quit.\n");
-                daemon.drain();
-            }
-            else {
-                process.exit(130);
-            }
-        });
-    }
-    process.stdout.write(`Runner ${identity.name} online in pool '${pool}'. Waiting for runs...\n`);
-    await daemon.done;
 }
 async function cmdDeregister() {
     const baseUrl = requireFlag("url");
@@ -183,8 +140,16 @@ const USAGE = `boardwalk-runner <register|start|deregister> [flags]
 
   register    --url <control-plane> --token <bwkreg_…> [--name] [--labels a,b] [--identity-dir]
   start       --url <control-plane> [--pool default] [--work-dir] [--once] [--identity-dir]
+              [--host] [--image <ref>] [--network <mode>] [--mount host:container[:ro],…]
   deregister  --url <control-plane> [--pool default] [--identity-dir]
 
+  Isolation (start): runs are CONTAINERIZED by default (docker/podman) — each run sees only its
+  workspace + the machine's network, not your home dir, creds, or the rest of the machine.
+    --host              raw process mode: full machine access (trusted workflows only / no runtime)
+    --image <ref>       runner image to run (default: the version-pinned ghcr.io image)
+    --network <mode>    container network (default: host — preserves LAN/VPN/localhost reach)
+    --mount a:b[:ro]    extra host paths to expose to the run (comma-separated)
+
   --verbose   debug-level daemon logs (poll cycles, heartbeats)
   --debug     --verbose, plus debug logging inside each spawned run process
 `;

package/dist/daemon/container.d.ts

@@ -0,0 +1,46 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import type { RunProcessHandle } from "./daemon.js";
+export interface ContainerSpawnConfig {
+    /** Container runtime binary: `docker` or `podman`. */
+    runtime: string;
+    /** Fully-qualified runner image ref (e.g. `ghcr.io/boardwalk-labs/runner:0.1.9`). */
+    image: string;
+    /** Docker network mode. Default `host` — preserves the machine's LAN/VPN/localhost reach. */
+    network?: string;
+    /** Extra host bind mounts (`hostPath:containerPath[:ro]`) the user opted into for this fleet. */
+    mounts?: readonly string[];
+    /** Run the container as this `uid:gid` — the invoking host user — so writes to the bind-mounted
+     *  workspace match host ownership instead of the image's `node` (uid 1000). Set on Linux; omit on
+     *  Docker Desktop (macOS/Windows), which maps ownership through its file sharing. */
+    user?: string;
+    /** Test seam. */
+    spawn?: typeof nodeSpawn;
+}
+/** The env the container receives: the claim's env + platform contract, with the in-container
+ *  filesystem coordinates overridden (the host paths are meaningless inside the container). */
+export declare function containerEnv(runEnv: Record<string, string>): Record<string, string>;
+/** Derive the run id from the per-run workspace path (`<workDir>/runs/<runId>/workspace`). Used only
+ *  for a human-readable container name; a fallback keeps a non-standard cwd from throwing. */
+export declare function runIdFromCwd(cwd: string): string;
+/**
+ * Build the `docker run` argv. PURE + exported so the isolation guarantees are unit-asserted:
+ *  - the ONLY bind mount is the per-run workspace (+ any explicit user mounts) — the identity dir,
+ *    the user's home, and the rest of the host FS are never mounted;
+ *  - per-run credentials are passed by NAME (`-e BOARDWALK_RUN_TOKEN`), so their VALUES come from the
+ *    docker client's env and never appear in the argv (which `ps` exposes);
+ *  - `--rm` (no leftover container), `--init` (proper signal handling / zombie reaping).
+ */
+export declare function buildContainerArgs(cfg: ContainerSpawnConfig, opts: {
+    env: Record<string, string>;
+    cwd: string;
+}): string[];
+/** A `RunSpawner` that runs each run in a throwaway container. */
+export declare function createContainerSpawner(cfg: ContainerSpawnConfig): (opts: {
+    entry: string;
+    env: Record<string, string>;
+    cwd: string;
+}) => RunProcessHandle;
+/** Probe that a container runtime is installed AND its daemon is reachable. Returns the runtime
+ *  binary name on success, or null (so `start` can hard-fail with a clear message rather than
+ *  failing every run later). `docker info` / `podman info` exits non-zero when the daemon is down. */
+export declare function detectContainerRuntime(candidates?: readonly string[], run?: (bin: string) => Promise<void>): Promise<string | null>;

package/dist/daemon/container.js

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: Apache-2.0
+// Container run spawner — the DEFAULT isolation model for a self-hosted runner. Each run executes
+// inside a throwaway container (Docker/Podman) instead of as a same-UID child process, so the run
+// (and the LLM-decided `agent()` tool calls inside it) sees ONLY its own workspace, never the
+// user's home dir, the runner's identity file, SSH/cloud creds, or the rest of the machine. The
+// machine's network IS preserved (`--network host`) so a run still reaches the org's LAN, VPN, and
+// localhost services — the reason to self-host. Full host access stays possible, but only as an
+// EXPLICIT mount, never the silent default. `--host` (a separate spawner) is the escape hatch.
+//
+// Security-critical surface: `buildContainerArgs` is a pure function so the argv can be asserted
+// exhaustively — the identity dir is NEVER bind-mounted, and per-run credentials ride the docker
+// client's ENV (name-only `-e KEY`), never the argv (which `ps` would expose).
+import { spawn as nodeSpawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import * as path from "node:path";
+const exec = promisify(execFile);
+/** Env keys forwarded from the daemon's OWN environment into the container (proxy + locale only —
+ *  NOT the machine's PATH/HOME, which would leak host layout; the image provides its own). */
+const FORWARDED_ENV_KEYS = [
+    "LANG",
+    "NODE_USE_ENV_PROXY",
+    "HTTPS_PROXY",
+    "https_proxy",
+    "HTTP_PROXY",
+    "http_proxy",
+    "NO_PROXY",
+    "no_proxy",
+    "BOARDWALK_RUNNER_DEBUG",
+];
+/** The env the container receives: the claim's env + platform contract, with the in-container
+ *  filesystem coordinates overridden (the host paths are meaningless inside the container). */
+export function containerEnv(runEnv) {
+    const env = {
+        // Forward the daemon's proxy/locale knobs so egress + a corporate proxy still work.
+        ...forwardedEnv(),
+        // The claim's resolved non-secret vars + platform contract (RUN_ID, BOARDWALK_RUN_TOKEN, …).
+        ...runEnv,
+        // In-container coordinates — the bind mount lands the workspace at /workspace.
+        WORKSPACE_ROOT: "/workspace",
+        HOME: "/workspace",
+        TMPDIR: "/tmp",
+    };
+    return env;
+}
+function forwardedEnv() {
+    const out = {};
+    for (const key of FORWARDED_ENV_KEYS) {
+        const v = process.env[key];
+        if (v !== undefined)
+            out[key] = v;
+    }
+    return out;
+}
+/** Derive the run id from the per-run workspace path (`<workDir>/runs/<runId>/workspace`). Used only
+ *  for a human-readable container name; a fallback keeps a non-standard cwd from throwing. */
+export function runIdFromCwd(cwd) {
+    const runId = path.basename(path.dirname(cwd));
+    return /^[A-Za-z0-9_-]{1,64}$/.test(runId) ? runId : "run";
+}
+/**
+ * Build the `docker run` argv. PURE + exported so the isolation guarantees are unit-asserted:
+ *  - the ONLY bind mount is the per-run workspace (+ any explicit user mounts) — the identity dir,
+ *    the user's home, and the rest of the host FS are never mounted;
+ *  - per-run credentials are passed by NAME (`-e BOARDWALK_RUN_TOKEN`), so their VALUES come from the
+ *    docker client's env and never appear in the argv (which `ps` exposes);
+ *  - `--rm` (no leftover container), `--init` (proper signal handling / zombie reaping).
+ */
+export function buildContainerArgs(cfg, opts) {
+    const args = [
+        "run",
+        "--rm",
+        "--init",
+        "--name",
+        `bw-run-${runIdFromCwd(opts.cwd)}`,
+        "--network",
+        cfg.network ?? "host",
+        // The per-run workspace — the ONLY host path the run can see by default.
+        "-v",
+        `${opts.cwd}:/workspace`,
+        "-w",
+        "/workspace",
+    ];
+    // Run as the invoking host user (Linux) so the bind-mounted workspace is writable — the image's
+    // `node` (uid 1000) otherwise can't write a host dir it doesn't own.
+    if (cfg.user !== undefined) {
+        args.push("--user", cfg.user);
+    }
+    // Explicit, user-opted-in host mounts (fleet config) — the honest way to say "I grant this path".
+    for (const m of cfg.mounts ?? []) {
+        args.push("-v", m);
+    }
+    // Env by NAME only — values are read from the docker client's environment, never the argv.
+    for (const key of Object.keys(containerEnv(opts.env))) {
+        args.push("-e", key);
+    }
+    args.push(cfg.image);
+    return args;
+}
+/** A `RunSpawner` that runs each run in a throwaway container. */
+export function createContainerSpawner(cfg) {
+    const spawnImpl = cfg.spawn ?? nodeSpawn;
+    return (opts) => {
+        const args = buildContainerArgs(cfg, opts);
+        const child = spawnImpl(cfg.runtime, args, {
+            // The docker client reads the name-only `-e KEY` values from ITS environment — set them here so
+            // they never touch the argv. The daemon's own secrets are NOT here (only forwarded + claim env).
+            env: { ...process.env, ...containerEnv(opts.env) },
+            stdio: "inherit",
+        });
+        const exit = new Promise((resolve) => {
+            child.on("exit", (code, signal) => {
+                resolve(code ?? (signal !== null ? 143 : 1));
+            });
+            child.on("error", () => {
+                resolve(1);
+            });
+        });
+        return {
+            wait: () => exit,
+            kill: () => {
+                // `docker run` proxies SIGTERM to the container; also best-effort `docker kill` by name in
+                // case signal proxying is off, so a lost lease / drain actually stops the container.
+                child.kill("SIGTERM");
+                void exec(cfg.runtime, ["kill", `bw-run-${runIdFromCwd(opts.cwd)}`]).catch(() => undefined);
+            },
+        };
+    };
+}
+/** Probe that a container runtime is installed AND its daemon is reachable. Returns the runtime
+ *  binary name on success, or null (so `start` can hard-fail with a clear message rather than
+ *  failing every run later). `docker info` / `podman info` exits non-zero when the daemon is down. */
+export async function detectContainerRuntime(candidates = ["docker", "podman"], run = async (bin) => {
+    await exec(bin, ["info"], { timeout: 10_000 });
+}) {
+    for (const bin of candidates) {
+        try {
+            await run(bin);
+            return bin;
+        }
+        catch {
+            // not installed, or the daemon isn't running — try the next candidate
+        }
+    }
+    return null;
+}

package/dist/daemon/identity.js

@@ -2,10 +2,20 @@
 // Persisted runner identity — the standing credential + coordinates a machine keeps between
 // restarts (`runner start` after a reboot skips registration). One JSON file per
 // (control plane, pool), mode 0600: the runner token is a credential.
-import { mkdir, readFile, writeFile, unlink } from "node:fs/promises";
+import { mkdir, readFile, writeFile, unlink, chmod } from "node:fs/promises";
 import * as path from "node:path";
 import * as os from "node:os";
 import { z } from "zod";
+/** Re-assert restrictive perms on a path (POSIX only). `mkdir`/`writeFile` set mode only when they
+ *  CREATE, so a pre-existing dir/file could be group/world-readable; this makes the credential
+ *  fail-safe regardless. No-op on Windows (no POSIX mode bits). Best-effort — a chmod failure must
+ *  not break enrollment. NOTE: this hardens the file at rest; it does NOT stop a same-UID process
+ *  (an in-process run program) from reading it — that requires per-run UID/container isolation. */
+async function hardenPerms(target, mode) {
+    if (process.platform === "win32")
+        return;
+    await chmod(target, mode).catch(() => undefined);
+}
 export const runnerIdentitySchema = z.strictObject({
     runner_id: z.string().min(1),
     runner_token: z.string().min(1),
@@ -25,15 +35,21 @@ function identityFile(dir, controlPlaneUrl, pool) {
 }
 export async function saveIdentity(dir, identity) {
     await mkdir(dir, { recursive: true, mode: 0o700 });
+    await hardenPerms(dir, 0o700); // re-assert: mkdir's mode only applies when it CREATES the dir
     const file = identityFile(dir, identity.control_plane_url, identity.pool);
     await writeFile(file, `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 });
+    await hardenPerms(file, 0o600); // re-assert: writeFile's mode only applies to a NEW file
     return file;
 }
 export async function loadIdentity(dir, controlPlaneUrl, pool) {
     try {
-        const raw = await readFile(identityFile(dir, controlPlaneUrl, pool), "utf8");
+        const file = identityFile(dir, controlPlaneUrl, pool);
+        const raw = await readFile(file, "utf8");
         const parsed = runnerIdentitySchema.safeParse(JSON.parse(raw));
-        return parsed.success ? parsed.data : null;
+        if (!parsed.success)
+            return null;
+        await hardenPerms(file, 0o600); // repair perms if something loosened them since save
+        return parsed.data;
     }
     catch {
         return null;

package/dist/daemon/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./pool_client.js";
 export * from "./identity.js";
 export * from "./daemon.js";
+export * from "./container.js";
+export * from "./start.js";

package/dist/daemon/index.js

@@ -2,3 +2,5 @@
 export * from "./pool_client.js";
 export * from "./identity.js";
 export * from "./daemon.js";
+export * from "./container.js";
+export * from "./start.js";

package/dist/daemon/start.d.ts

@@ -0,0 +1,52 @@
+import { type RunProcessHandle, type RunSpawner } from "./daemon.js";
+import { detectContainerRuntime } from "./container.js";
+import type { RunnerIdentity } from "./identity.js";
+export type IsolationMode = "container" | "host";
+export interface IsolationConfig {
+    /** `container` (default) = throwaway container per run; `host` = raw process, full machine access. */
+    mode: IsolationMode;
+    /** Container image ref (container mode). Defaults to the version-pinned ghcr.io/boardwalk-labs image. */
+    image?: string;
+    /** Container network mode (container mode). Defaults to `host` — preserves LAN/VPN/localhost reach. */
+    network?: string;
+    /** Extra host bind mounts to expose to the run (container mode). */
+    mounts?: readonly string[];
+}
+/** This package's version (the runner image tag is pinned to it). Read from package.json so a
+ *  release bump is one file. */
+export declare function packageVersion(): string;
+/** Default runner image ref — the version-pinned public image (base + this runtime). */
+export declare function defaultImage(): string;
+/** Raw-process spawner (the `--host` escape hatch): one Node process per run, full machine access.
+ *  Env = the platform contract + the claim's resolved vars over a minimal base (PATH + proxy knobs;
+ *  HOME = the run's workspace). */
+export declare function processSpawn(opts: {
+    entry: string;
+    env: Record<string, string>;
+    cwd: string;
+}): RunProcessHandle;
+/** Error thrown when container isolation is requested but no runtime is available — the caller
+ *  surfaces the message and exits (never silently drop to the unisolated path). */
+export declare class NoContainerRuntimeError extends Error {
+    constructor();
+}
+/** Pick the run spawner from the isolation config. Container is default; `host` is the escape hatch;
+ *  container-with-no-runtime throws {@link NoContainerRuntimeError}. */
+export declare function resolveSpawner(iso: IsolationConfig, log: (line: string) => void, detect?: typeof detectContainerRuntime): Promise<RunSpawner>;
+export interface StartRunnerOptions {
+    baseUrl: string;
+    identity: RunnerIdentity;
+    isolation: IsolationConfig;
+    workDir: string;
+    once?: boolean;
+    /** Progress line sink (stdout by default). */
+    log?: (line: string) => void;
+    /** Wire SIGINT/SIGTERM → drain (Ctrl-C finishes the current run; a second forces quit). Default on. */
+    handleSignals?: boolean;
+}
+/**
+ * Run the daemon to completion: resolve the spawner (isolation), poll → claim → execute → heartbeat,
+ * and drain cleanly on Ctrl-C. Both entry points call this after obtaining an identity, so there is
+ * exactly one implementation of the run loop + isolation decision.
+ */
+export declare function startRunner(opts: StartRunnerOptions): Promise<void>;

package/dist/daemon/start.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: Apache-2.0
+// startRunner — the ONE implementation of "run this machine as a runner". Both entry points
+// (`boardwalk-runner start` and the CLI's `boardwalk runner start`) obtain an identity their own
+// way (two-step token vs one-step management-API enrollment) and then call THIS. There is no second
+// copy of the daemon lifecycle, the isolation decision, or the drain handling to drift out of sync.
+//
+// Isolation is a `RunSpawner` choice: `container` (default) runs each run in a throwaway container;
+// `host` (the `--host` escape hatch) runs it as a raw child process with full machine access. A
+// future macOS/Windows native sandbox is simply a third RunSpawner behind this same seam.
+import { spawn as nodeSpawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+import { PoolClient } from "./pool_client.js";
+import { startDaemon } from "./daemon.js";
+import { createContainerSpawner, detectContainerRuntime } from "./container.js";
+/** This package's version (the runner image tag is pinned to it). Read from package.json so a
+ *  release bump is one file. */
+export function packageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+        if (typeof pkg === "object" && pkg !== null && "version" in pkg) {
+            const v = pkg.version;
+            if (typeof v === "string")
+                return v;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0";
+}
+/** Default runner image ref — the version-pinned public image (base + this runtime). */
+export function defaultImage() {
+    return `ghcr.io/boardwalk-labs/runner:${packageVersion()}`;
+}
+/** Raw-process spawner (the `--host` escape hatch): one Node process per run, full machine access.
+ *  Env = the platform contract + the claim's resolved vars over a minimal base (PATH + proxy knobs;
+ *  HOME = the run's workspace). */
+export function processSpawn(opts) {
+    const base = {};
+    for (const key of [
+        "PATH",
+        "LANG",
+        "NODE_USE_ENV_PROXY",
+        "HTTPS_PROXY",
+        "https_proxy",
+        "HTTP_PROXY",
+        "http_proxy",
+        "NO_PROXY",
+        "no_proxy",
+        "BOARDWALK_RUNNER_DEBUG",
+    ]) {
+        const v = process.env[key];
+        if (v !== undefined)
+            base[key] = v;
+    }
+    const child = nodeSpawn(process.execPath, [opts.entry], {
+        cwd: opts.cwd,
+        env: { ...base, HOME: opts.cwd, TMPDIR: path.join(opts.cwd, "..", "tmp"), ...opts.env },
+        stdio: "inherit",
+    });
+    const exit = new Promise((resolve) => {
+        child.on("exit", (code, signal) => {
+            resolve(code ?? (signal !== null ? 143 : 1));
+        });
+        child.on("error", () => {
+            resolve(1);
+        });
+    });
+    return {
+        wait: () => exit,
+        kill: () => {
+            child.kill("SIGTERM");
+        },
+    };
+}
+/** Error thrown when container isolation is requested but no runtime is available — the caller
+ *  surfaces the message and exits (never silently drop to the unisolated path). */
+export class NoContainerRuntimeError extends Error {
+    constructor() {
+        super("No container runtime found (looked for docker, podman). Self-hosted runs are containerized " +
+            "by default for isolation.\n" +
+            "  • Install Docker or Podman and make sure it's running, or\n" +
+            "  • pass --host to run without isolation (full machine access; trusted workflows only).");
+        this.name = "NoContainerRuntimeError";
+    }
+}
+/** Pick the run spawner from the isolation config. Container is default; `host` is the escape hatch;
+ *  container-with-no-runtime throws {@link NoContainerRuntimeError}. */
+export async function resolveSpawner(iso, log, detect = detectContainerRuntime) {
+    if (iso.mode === "host") {
+        log("Running WITHOUT isolation (--host): runs get full access to this machine as your user. " +
+            "Only run workflows you trust.\n");
+        return processSpawn;
+    }
+    const runtime = await detect();
+    if (runtime === null)
+        throw new NoContainerRuntimeError();
+    const image = iso.image ?? defaultImage();
+    // Linux: run as the invoking user so the bind-mounted workspace is writable. Docker Desktop
+    // (macOS/Windows) maps ownership via file sharing, so leave the image's user in place there.
+    const user = process.platform === "linux" && process.getuid !== undefined && process.getgid !== undefined
+        ? `${String(process.getuid())}:${String(process.getgid())}`
+        : undefined;
+    log(`Isolation: ${runtime} container (${image}); workspace-only + ${iso.network ?? "host"} network.\n`);
+    return createContainerSpawner({
+        runtime,
+        image,
+        ...(iso.network !== undefined ? { network: iso.network } : {}),
+        ...(iso.mounts !== undefined && iso.mounts.length > 0 ? { mounts: iso.mounts } : {}),
+        ...(user !== undefined ? { user } : {}),
+    });
+}
+/**
+ * Run the daemon to completion: resolve the spawner (isolation), poll → claim → execute → heartbeat,
+ * and drain cleanly on Ctrl-C. Both entry points call this after obtaining an identity, so there is
+ * exactly one implementation of the run loop + isolation decision.
+ */
+export async function startRunner(opts) {
+    const log = opts.log ?? ((line) => void process.stdout.write(line));
+    const spawn = await resolveSpawner(opts.isolation, log);
+    // Process mode imports this entry directly; container mode ignores it (the image's entrypoint runs
+    // the runtime), but the daemon still passes it through the spawner interface.
+    const runtimeEntry = fileURLToPath(new URL("../runtime/main.js", import.meta.url));
+    const client = new PoolClient({ baseUrl: opts.baseUrl, runnerToken: opts.identity.runner_token });
+    const daemon = startDaemon({
+        client,
+        runtimeEntry,
+        workDir: opts.workDir,
+        runnerId: opts.identity.runner_id,
+        spawn,
+        ...(opts.once === true ? { once: true } : {}),
+    });
+    if (opts.handleSignals !== false) {
+        let interrupts = 0;
+        for (const signal of ["SIGINT", "SIGTERM"]) {
+            process.on(signal, () => {
+                interrupts += 1;
+                if (interrupts === 1) {
+                    log("\nDraining: finishing the current run, claiming nothing new. Ctrl-C again to force-quit.\n");
+                    daemon.drain();
+                }
+                else {
+                    process.exit(130);
+                }
+            });
+        }
+    }
+    log(`Runner ${opts.identity.name} online in pool '${opts.identity.pool}'. Waiting for runs...\n`);
+    await daemon.done;
+}

package/dist/runtime/workspace_store.js

@@ -15,6 +15,7 @@ import { promisify } from "node:util";
 import { stat, mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { extract as tarExtract } from "tar";
 import { createLogger } from "./support/index.js";
 const log = createLogger("WorkspaceStore");
 const exec = promisify(execFile);
@@ -107,7 +108,13 @@ export class TarWorkspaceArchiver {
     }
     async extract(srcPath, dir) {
         await mkdir(dir, { recursive: true });
-        await exec("tar", ["xzf", srcPath, "-C", dir]);
+        // Extract via node-tar, NOT `tar xzf`: extraction reads UNTRUSTED input (a program artifact
+        // from an arbitrary control plane on a self-hosted runner, or a prior run's workspace snapshot),
+        // and node-tar is hardened + portable — with default `preservePaths: false` it strips absolute
+        // paths and `..` members, and refuses to write THROUGH a symlink (unlinking it first), closing
+        // the traversal/symlink-escape gaps that differ between GNU tar and bsdtar. Same behavior on
+        // macOS and Linux, no dependency on which `tar` the OS ships.
+        await tarExtract({ file: srcPath, cwd: dir });
     }
 }
 /** Production fs — node's fs/promises. */

package/package.json

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