pum-agent 0.2.0-beta.4 → 0.2.2-beta.1

package/src/main.tsx

@@ -42,6 +42,8 @@ import {
 } from "./triggers/process";
 import type { StartupOptions } from "./cli";
 import { installSelectionClipboard } from "./clipboard";
+import { TerminalTitleController } from "./terminal-title";
+import { SandboxController } from "./sandbox";
 
 export async function start(options: StartupOptions): Promise<void> {
   mkdirSync(AGENT_DIR, { recursive: true });
@@ -53,6 +55,12 @@ export async function start(options: StartupOptions): Promise<void> {
   const loginRequired = options.login || (await modelRuntime.getAvailable()).length === 0;
 
   const settings = loadSettings();
+  const sandboxController = new SandboxController({
+    mode: settings.sandboxMode ?? "auto",
+    agentDir: AGENT_DIR,
+  });
+  const sandboxWarning = await sandboxController.startupWarning(settings.checkMode);
+  const sandboxExtension = sandboxController.extension();
   setWritingStyle(settings.writingStyle);
   setExplanationStrength(settings.explanationStrength);
   const questionnaireManager = new QuestionnaireManager();
@@ -129,6 +137,7 @@ export async function start(options: StartupOptions): Promise<void> {
     childExtensionFactories: [
       writingStyleExtension,
       explanationStrengthExtension,
+      sandboxExtension,
     ],
     childExtensionFactoriesForAgent: [(agentId) => createCheckModeExtension(modelRuntime, undefined, {
       coordinator: checkApprovalCoordinator,
@@ -154,6 +163,7 @@ export async function start(options: StartupOptions): Promise<void> {
             writingStyleExtension,
             explanationStrengthExtension,
             mainCheckModeExtension,
+            sandboxExtension,
             applyPatchExtension,
             questionnaireManager.extension({ id: "main", name: "main" }),
             subagentExtension,
@@ -189,6 +199,7 @@ export async function start(options: StartupOptions): Promise<void> {
   if (sessionRuntime.modelFallbackMessage) console.error(sessionRuntime.modelFallbackMessage);
 
   const renderer = await createCliRenderer({ exitOnCtrlC: false });
+  const terminalTitle = new TerminalTitleController((title) => renderer.setTerminalTitle(title));
   const selectionClipboard = installSelectionClipboard(renderer);
   const root = createRoot(renderer);
   const shutdown = createShutdown({
@@ -197,6 +208,7 @@ export async function start(options: StartupOptions): Promise<void> {
       root.unmount();
     },
     cleanup: () => {
+      terminalTitle.clear();
       selectionClipboard.dispose();
       cleanupPendingImages();
     },
@@ -233,6 +245,10 @@ export async function start(options: StartupOptions): Promise<void> {
       questionnaireManager={questionnaireManager}
       spawnPreviewManager={spawnPreviewManager}
       messageCacheController={messageCacheController}
+      terminalTitle={terminalTitle}
+      startupWarnings={sandboxWarning ? [sandboxWarning] : []}
+      onSandboxModeChange={(mode) => sandboxController.setMode(mode)}
+      sandboxWarningSource={sandboxController}
       loginRequired={loginRequired}
       checkApprovalCoordinator={checkApprovalCoordinator}
       checkApprovalStore={checkApprovalStore}

package/src/platform.ts

@@ -64,6 +64,23 @@ export function isPathInside(
   return relative !== "" && relative !== ".." && !relative.startsWith(`..${paths.sep}`) && !paths.isAbsolute(relative);
 }
 
+export function pathIdentity(
+  path: string,
+  platform: RuntimePlatform = process.platform,
+): string {
+  const canonical = pathApi(platform).resolve(path);
+  return platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
+export function isPathInsideOrSame(
+  parent: string,
+  candidate: string,
+  platform: RuntimePlatform = process.platform,
+): boolean {
+  return pathIdentity(parent, platform) === pathIdentity(candidate, platform)
+    || isPathInside(parent, candidate, platform);
+}
+
 export async function canonicalPathIdentity(
   path: string,
   platform: RuntimePlatform = process.platform,
@@ -74,6 +91,28 @@ export async function canonicalPathIdentity(
   return platform === "win32" ? canonical.toLowerCase() : canonical;
 }
 
+export async function canonicalPathIdentityAllowMissing(
+  path: string,
+  platform: RuntimePlatform = process.platform,
+  resolvePath: (path: string) => Promise<string> = realpath,
+): Promise<string> {
+  const paths = pathApi(platform);
+  const absolute = paths.resolve(path);
+  const missing: string[] = [];
+  let existing = absolute;
+  while (true) {
+    try {
+      const canonical = await resolvePath(existing);
+      return pathIdentity(paths.resolve(canonical, ...missing.reverse()), platform);
+    } catch (error) {
+      const parent = paths.dirname(existing);
+      if (parent === existing || existing === paths.parse(existing).root) throw error;
+      missing.push(paths.basename(existing));
+      existing = parent;
+    }
+  }
+}
+
 export async function pathsHaveSameIdentity(
   first: string,
   second: string,

package/src/sandbox/index.ts

@@ -0,0 +1,207 @@
+import {
+  createBashTool,
+  getShellConfig,
+  SettingsManager,
+  type BashOperations,
+  type InlineExtension,
+} from "@earendil-works/pi-coding-agent";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { AGENT_DIR } from "../config";
+import { analyzeCheckPolicy } from "../check-policy";
+import { getCheckModeConfig } from "../check-mode";
+import { buildSandboxPolicy, decideSandboxMode } from "../sandbox-policy";
+import type { CheckModeProfile } from "../settings";
+import type { SandboxBackend, SandboxCapability, SandboxMode } from "./types";
+import { createBubblewrapBackend } from "./linux";
+import { createWindowsSandboxBackend } from "./windows";
+
+export type SandboxControllerOptions = {
+  backend?: SandboxBackend;
+  platform?: NodeJS.Platform;
+  mode?: SandboxMode;
+  agentDir?: string;
+};
+
+function platformBackend(platform: NodeJS.Platform): SandboxBackend | undefined {
+  if (platform === "linux") return createBubblewrapBackend({ platform });
+  if (platform === "win32") return createWindowsSandboxBackend({ platform });
+  return undefined;
+}
+
+function unsupportedCapability(platform: NodeJS.Platform): SandboxCapability {
+  return {
+    state: "unavailable",
+    backend: platform === "win32" ? "mxc" : "bubblewrap",
+    reason: `Native Bash sandboxing is not supported on ${platform}`,
+  };
+}
+
+function findExecutable(executable: string, platform: NodeJS.Platform): string {
+  if (isAbsolute(executable)) return resolve(executable);
+  const command = platform === "win32" ? "where.exe" : "which";
+  const result = spawnSync(command, [executable], {
+    encoding: "utf8",
+    timeout: 5_000,
+    windowsHide: true,
+  });
+  const found = result.status === 0
+    ? result.stdout.trim().split(/\r?\n/u).find(Boolean)
+    : undefined;
+  if (!found || !isAbsolute(found)) throw new Error(`Sandbox shell executable could not be resolved: ${executable}`);
+  return resolve(found);
+}
+
+export class SandboxController {
+  readonly #backend?: SandboxBackend;
+  readonly #platform: NodeJS.Platform;
+  readonly #agentDir: string;
+  #mode: SandboxMode;
+  #probe?: Promise<SandboxCapability>;
+  readonly #settings = new Map<string, SettingsManager>();
+  readonly #warningListeners = new Set<(warning: string) => void>();
+  #warningEmitted = false;
+
+  constructor(options: SandboxControllerOptions = {}) {
+    this.#platform = options.platform ?? process.platform;
+    this.#backend = options.backend ?? platformBackend(this.#platform);
+    this.#mode = options.mode ?? "auto";
+    this.#agentDir = options.agentDir ?? AGENT_DIR;
+  }
+
+  setMode(mode: SandboxMode): void {
+    this.#mode = mode;
+  }
+
+  get mode(): SandboxMode {
+    return this.#mode;
+  }
+
+  subscribeWarnings(listener: (warning: string) => void): () => void {
+    this.#warningListeners.add(listener);
+    return () => this.#warningListeners.delete(listener);
+  }
+
+  #emitWarning(warning: string): void {
+    if (this.#warningEmitted) return;
+    this.#warningEmitted = true;
+    for (const listener of this.#warningListeners) listener(warning);
+  }
+
+  probe(): Promise<SandboxCapability> {
+    return this.#probe ??= this.#backend?.probe()
+      ?? Promise.resolve(unsupportedCapability(this.#platform));
+  }
+
+  async startupWarning(checkMode: CheckModeProfile): Promise<string | undefined> {
+    if (checkMode === "off") return undefined;
+    if (this.#mode === "off") return undefined;
+    const capability = await this.probe();
+    const decision = decideSandboxMode(this.#mode, capability);
+    if (decision.warning) {
+      this.#warningEmitted = true;
+      return decision.warning;
+    }
+    if (decision.action === "block") {
+      this.#warningEmitted = true;
+      return `${decision.reason}. Checked Bash commands will be blocked.`;
+    }
+    return undefined;
+  }
+
+  extension(): InlineExtension {
+    const base = createBashTool(process.cwd());
+    const controller = this;
+    return {
+      name: "pum-native-bash-sandbox",
+      factory: (pi) => {
+        pi.registerTool({
+          ...base,
+          description: `${base.description} PUM applies native OS sandboxing when Check mode and Sandbox settings require it.`,
+          execute: async (id, params, signal, onUpdate, ctx) => {
+            const cwd = ctx.cwd;
+            let settings = controller.#settings.get(cwd);
+            if (!settings) {
+              settings = SettingsManager.create(cwd, controller.#agentDir);
+              controller.#settings.set(cwd, settings);
+            }
+            const shellPath = settings.getShellPath();
+            const commandPrefix = settings.getShellCommandPrefix();
+            const check = getCheckModeConfig();
+            if (check.profile === "off" || controller.#mode === "off") {
+              const local = createBashTool(cwd, { shellPath, commandPrefix });
+              return (local.execute as any)(id, params, signal, onUpdate, ctx);
+            }
+
+            const capability = await controller.probe();
+            const decision = decideSandboxMode(controller.#mode, capability);
+            if (decision.action === "block") throw new Error(decision.reason);
+            if (decision.action === "direct") {
+              if (decision.warning) controller.#emitWarning(decision.warning);
+              const local = createBashTool(cwd, { shellPath, commandPrefix });
+              return (local.execute as any)(id, params, signal, onUpdate, ctx);
+            }
+            if (!controller.#backend) throw new Error("Sandbox backend is unavailable");
+
+            const shell = getShellConfig(shellPath);
+            const executable = findExecutable(shell.shell, controller.#platform);
+            const operations: BashOperations = {
+              exec: async (command, executionCwd, options) => {
+                const executionCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
+                const result = analyzeCheckPolicy({
+                  command: executionCommand,
+                  cwd: executionCwd,
+                  profile: check.profile as Exclude<typeof check.profile, "off">,
+                  allowedPaths: check.additionalPaths,
+                  protectedPaths: [controller.#agentDir],
+                });
+                if (result.decision === "block") {
+                  throw new Error(`Sandbox policy hard block: ${result.reason}`);
+                }
+
+                const privateTemp = await mkdtemp(join(tmpdir(), "pum-sandbox-"));
+                const commandFromStdin = shell.commandTransport === "stdin";
+                const args = commandFromStdin ? [...shell.args] : [...shell.args, executionCommand];
+                try {
+                  const policy = buildSandboxPolicy({
+                    command,
+                    executionCommand,
+                    cwd: executionCwd,
+                    additionalRoots: check.additionalPaths,
+                    result,
+                    executable,
+                    args,
+                    stdin: commandFromStdin,
+                    privateTemp,
+                    environment: options.env,
+                    pumConfigRoot: controller.#agentDir,
+                    platform: controller.#platform,
+                  });
+                  const handle = controller.#backend!.spawn(policy, {
+                    onStdout: options.onData,
+                    onStderr: options.onData,
+                    signal: options.signal,
+                    timeoutSeconds: options.timeout,
+                    stdin: commandFromStdin ? Buffer.from(executionCommand) : undefined,
+                  });
+                  const completed = await handle.completed;
+                  return { exitCode: completed.exitCode };
+                } finally {
+                  await rm(privateTemp, { recursive: true, force: true }).catch(() => {});
+                }
+              },
+            };
+            const sandboxed = createBashTool(cwd, { operations });
+            return (sandboxed.execute as any)(id, params, signal, onUpdate, ctx);
+          },
+        });
+      },
+    };
+  }
+}
+
+export * from "./types";
+export { createBubblewrapBackend, probeBubblewrap, buildBubblewrapArgv } from "./linux";
+export { createWindowsSandboxBackend, probeWindowsSandbox, buildWindowsMxcConfig } from "./windows";

package/src/sandbox/linux.ts

@@ -0,0 +1,362 @@
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { posix } from "node:path";
+import type {
+  SandboxBackend,
+  SandboxCapability,
+  SandboxPolicy,
+  SandboxProcessHandle,
+  SandboxProcessOptions,
+} from "./types";
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const DEFAULT_KILL_GRACE_MS = 250;
+const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
+const ENVIRONMENT_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+type BubblewrapMount = {
+  source: string;
+  target: string;
+  mode: "read-only" | "read-write";
+};
+
+export interface BubblewrapSpawnRequest {
+  executable: string;
+  args: readonly string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  stdin?: Uint8Array;
+  onStdout: (chunk: Buffer) => void;
+  onStderr: (chunk: Buffer) => void;
+}
+
+export interface BubblewrapProcessResult {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+}
+
+export interface BubblewrapProcessHandle {
+  pid?: number;
+  completed: Promise<BubblewrapProcessResult>;
+  kill: (signal: NodeJS.Signals) => void;
+}
+
+export interface BubblewrapProcessAdapter {
+  spawn: (request: BubblewrapSpawnRequest) => BubblewrapProcessHandle;
+}
+
+export interface BubblewrapProbeOptions {
+  platform?: NodeJS.Platform;
+  executable?: string;
+  timeoutMs?: number;
+  processAdapter?: BubblewrapProcessAdapter;
+}
+
+export interface BubblewrapBackendOptions {
+  executable?: string;
+  platform?: NodeJS.Platform;
+  killGraceMs?: number;
+  processAdapter?: BubblewrapProcessAdapter;
+  probeTimeoutMs?: number;
+  systemMounts?: readonly string[];
+  pathKind?: (path: string) => "file" | "directory" | undefined;
+}
+
+export class NodeBubblewrapProcessAdapter implements BubblewrapProcessAdapter {
+  spawn(request: BubblewrapSpawnRequest): BubblewrapProcessHandle {
+    const child = spawn(request.executable, [...request.args], {
+      cwd: request.cwd,
+      env: request.env,
+      detached: true,
+      shell: false,
+      windowsHide: true,
+      stdio: [request.stdin ? "pipe" : "ignore", "pipe", "pipe"],
+    });
+    if (request.stdin) {
+      child.stdin?.on("error", () => {});
+      child.stdin?.end(request.stdin);
+    }
+    child.stdout?.on("data", request.onStdout);
+    child.stderr?.on("data", request.onStderr);
+
+    const completed = new Promise<BubblewrapProcessResult>((resolvePromise, reject) => {
+      child.once("error", reject);
+      child.once("close", (exitCode, signal) => resolvePromise({ exitCode, signal }));
+    });
+
+    return {
+      pid: child.pid,
+      completed,
+      kill(signal) {
+        if (!child.pid) return;
+        try {
+          process.kill(-child.pid, signal);
+        } catch {
+          child.kill(signal);
+        }
+      },
+    };
+  }
+}
+
+function assertNoNul(label: string, value: string): void {
+  if (value.includes("\0")) throw new Error(`${label} contains NUL`);
+}
+
+function normalizeAbsolutePath(label: string, value: string): string {
+  assertNoNul(label, value);
+  if (!posix.isAbsolute(value)) throw new Error(`${label} must be an absolute path: ${value}`);
+  return posix.normalize(value);
+}
+
+function isWithin(root: string, value: string): boolean {
+  const child = posix.relative(root, value);
+  return child === "" || (!child.startsWith("../") && child !== ".." && !posix.isAbsolute(child));
+}
+
+function defaultSystemMounts(): string[] {
+  return ["/usr", "/bin", "/sbin", "/lib", "/lib64", "/etc", "/nix"].filter(existsSync);
+}
+
+function sandboxEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const result: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(environment)) {
+    if (!ENVIRONMENT_KEY.test(key)) throw new Error(`Invalid environment variable name: ${key}`);
+    if (value !== undefined) {
+      assertNoNul(`Environment variable ${key}`, value);
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function addMount(
+  mounts: BubblewrapMount[],
+  targetIndexes: Map<string, number>,
+  mount: Omit<BubblewrapMount, "target"> & { target?: string },
+): void {
+  const source = normalizeAbsolutePath("Mount source", mount.source);
+  const target = normalizeAbsolutePath("Mount target", mount.target ?? mount.source);
+  const normalized = { source, target, mode: mount.mode };
+  const prior = targetIndexes.get(target);
+  if (prior === undefined) {
+    targetIndexes.set(target, mounts.length);
+    mounts.push(normalized);
+  } else {
+    mounts[prior] = normalized;
+  }
+}
+
+function policyMounts(policy: SandboxPolicy, systemMounts?: readonly string[]): BubblewrapMount[] {
+  const mounts: BubblewrapMount[] = [];
+  const targetIndexes = new Map<string, number>();
+  for (const path of systemMounts ?? defaultSystemMounts()) {
+    addMount(mounts, targetIndexes, { source: path, mode: "read-only" });
+  }
+  for (const path of policy.readOnlyPaths) {
+    addMount(mounts, targetIndexes, { source: path, mode: "read-only" });
+  }
+  for (const path of policy.readWritePaths) {
+    addMount(mounts, targetIndexes, { source: path, mode: "read-write" });
+  }
+  return mounts;
+}
+
+function defaultPathKind(path: string): "file" | "directory" | undefined {
+  try {
+    const stat = statSync(path);
+    return stat.isDirectory() ? "directory" : "file";
+  } catch {
+    return undefined;
+  }
+}
+
+function deniedPathArgs(
+  paths: readonly string[],
+  pathKind: (path: string) => "file" | "directory" | undefined,
+): string[] {
+  const args: string[] = [];
+  const seen = new Set<string>();
+  for (const rawPath of paths) {
+    const path = normalizeAbsolutePath("Denied path", rawPath);
+    if (seen.has(path)) continue;
+    seen.add(path);
+    const kind = pathKind(path);
+    if (kind === "directory") args.push("--tmpfs", path);
+    else args.push("--ro-bind", "/dev/null", path);
+  }
+  return args;
+}
+
+/** Build the complete Bubblewrap argv from an authoritative sandbox policy. */
+export function buildBubblewrapArgv(
+  policy: SandboxPolicy,
+  options: Pick<BubblewrapBackendOptions, "systemMounts" | "pathKind"> = {},
+): string[] {
+  if (policy.version !== 1) throw new Error(`Unsupported sandbox policy version: ${policy.version}`);
+  assertNoNul("Exact command", policy.exactCommand);
+  const cwd = normalizeAbsolutePath("Working directory", policy.cwd);
+  const executable = normalizeAbsolutePath("Command executable", policy.executable);
+  for (const argument of policy.args) assertNoNul("Command argument", argument);
+  const privateTemp = normalizeAbsolutePath("Private temp", policy.privateTemp);
+  const mounts = policyMounts(policy, options.systemMounts);
+  if (!mounts.some((mount) => isWithin(mount.source, cwd))) {
+    throw new Error(`Working directory is not visible in the sandbox: ${cwd}`);
+  }
+
+  const args = [
+    "--die-with-parent",
+    "--new-session",
+    "--unshare-user",
+    "--unshare-pid",
+    "--unshare-ipc",
+    "--unshare-uts",
+    "--cap-drop", "ALL",
+    "--proc", "/proc",
+    "--dev", "/dev",
+  ];
+  if (policy.network === "deny") args.push("--unshare-net");
+  for (const mount of mounts) {
+    args.push(mount.mode === "read-only" ? "--ro-bind" : "--bind", mount.source, mount.target);
+  }
+  // Keep private and denied mounts last so earlier allow mounts cannot expose them.
+  args.push("--tmpfs", privateTemp);
+  args.push(...deniedPathArgs(policy.deniedPaths, options.pathKind ?? defaultPathKind));
+  args.push("--chdir", cwd, "--", executable, ...policy.args);
+  return args;
+}
+
+function timeoutMilliseconds(timeoutSeconds: number | undefined): number | undefined {
+  if (timeoutSeconds === undefined) return undefined;
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+    throw new Error("Invalid timeout: must be a finite number of seconds");
+  }
+  const milliseconds = timeoutSeconds * 1000;
+  if (milliseconds > MAX_TIMEOUT_MS) throw new Error("Invalid timeout: value is too large");
+  return milliseconds;
+}
+
+export async function probeBubblewrap(options: BubblewrapProbeOptions = {}): Promise<SandboxCapability> {
+  const executable = options.executable ?? "bwrap";
+  if ((options.platform ?? process.platform) !== "linux") {
+    return { state: "unavailable", backend: "bubblewrap", reason: "Bubblewrap requires Linux" };
+  }
+
+  const adapter = options.processAdapter ?? new NodeBubblewrapProcessAdapter();
+  const probeExecutable = existsSync("/bin/true") ? "/bin/true" : "/usr/bin/true";
+  const probeMountArgs = defaultSystemMounts().flatMap((path) => ["--ro-bind", path, path]);
+  const output: Buffer[] = [];
+  const child = adapter.spawn({
+    executable,
+    cwd: "/",
+    env: { PATH: process.env.PATH ?? "/usr/bin:/bin" },
+    args: [
+      "--die-with-parent",
+      "--new-session",
+      "--unshare-user",
+      "--unshare-pid",
+      "--unshare-ipc",
+      "--unshare-uts",
+      "--unshare-net",
+      "--cap-drop", "ALL",
+      "--proc", "/proc",
+      "--dev", "/dev",
+      ...probeMountArgs,
+      "--", probeExecutable,
+    ],
+    onStdout: (chunk) => output.push(chunk),
+    onStderr: (chunk) => output.push(chunk),
+  });
+  try {
+    const handle = managedSandboxHandle(child, {
+      onStdout: () => {},
+      onStderr: () => {},
+      timeoutSeconds: (options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS) / 1000,
+    }, DEFAULT_KILL_GRACE_MS);
+    const result = await handle.completed;
+    if (result.exitCode === 0) return { state: "enforced", backend: "bubblewrap" };
+    const detail = Buffer.concat(output).toString("utf8").trim();
+    return {
+      state: "unavailable",
+      backend: "bubblewrap",
+      reason: detail || `Bubblewrap probe exited with code ${result.exitCode}`,
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      state: reason.includes("ENOENT") ? "unavailable" : "error",
+      backend: "bubblewrap",
+      reason,
+    };
+  }
+}
+
+function managedSandboxHandle(
+  child: BubblewrapProcessHandle,
+  options: SandboxProcessOptions,
+  killGraceMs: number,
+): SandboxProcessHandle {
+  let stoppedBy: "abort" | "timeout" | undefined;
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  let killHandle: ReturnType<typeof setTimeout> | undefined;
+
+  const stop = (reason: "abort" | "timeout") => {
+    if (stoppedBy) return;
+    stoppedBy = reason;
+    child.kill("SIGTERM");
+    killHandle = setTimeout(() => child.kill("SIGKILL"), killGraceMs);
+  };
+  const onAbort = () => stop("abort");
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  const timeoutMs = timeoutMilliseconds(options.timeoutSeconds);
+  if (timeoutMs !== undefined) timeoutHandle = setTimeout(() => stop("timeout"), timeoutMs);
+
+  const completed = child.completed.then((result) => {
+    if (stoppedBy === "abort" || options.signal?.aborted) throw new Error("aborted");
+    if (stoppedBy === "timeout") throw new Error(`timeout:${options.timeoutSeconds}`);
+    return { exitCode: result.exitCode, signal: result.signal };
+  }).finally(() => {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+    if (killHandle) clearTimeout(killHandle);
+    options.signal?.removeEventListener("abort", onAbort);
+  });
+
+  return { completed, kill: () => stop("abort") };
+}
+
+/** Create the reusable Linux Bubblewrap backend for the native sandbox layer. */
+export function createBubblewrapBackend(options: BubblewrapBackendOptions = {}): SandboxBackend {
+  const executable = options.executable ?? "bwrap";
+  const adapter = options.processAdapter ?? new NodeBubblewrapProcessAdapter();
+  const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+  if (!Number.isFinite(killGraceMs) || killGraceMs < 0) {
+    throw new Error("Kill grace must be a non-negative number");
+  }
+
+  return {
+    id: "bubblewrap",
+    probe: () => probeBubblewrap({
+      executable,
+      platform: options.platform,
+      timeoutMs: options.probeTimeoutMs,
+      processAdapter: adapter,
+    }),
+    spawn(policy, processOptions) {
+      if (processOptions.signal?.aborted) throw new Error("aborted");
+      const args = buildBubblewrapArgv(policy, {
+        systemMounts: options.systemMounts,
+        pathKind: options.pathKind,
+      });
+      const child = adapter.spawn({
+        executable,
+        args,
+        cwd: policy.cwd,
+        env: sandboxEnvironment(policy.environment),
+        stdin: processOptions.stdin,
+        onStdout: (chunk) => processOptions.onStdout(chunk),
+        onStderr: (chunk) => processOptions.onStderr(chunk),
+      });
+      return managedSandboxHandle(child, processOptions, killGraceMs);
+    },
+  };
+}