@h-rig/isolation-plugin 0.0.6-alpha.157 → 0.0.6-alpha.159

package/dist/src/sandbox/backend-bwrap.js

@@ -0,0 +1,268 @@
+// @bun
+var __require = import.meta.require;
+
+// packages/isolation-plugin/src/sandbox/backend-bwrap.ts
+import { mkdirSync } from "fs";
+import { resolve as resolve2 } from "path";
+
+// packages/isolation-plugin/src/sandbox/utils.ts
+import { existsSync, readdirSync, realpathSync } from "fs";
+import { resolve } from "path";
+import { resolveMonorepoRoot } from "@rig/core/layout";
+function toRealPath(path) {
+  if (!existsSync(path)) {
+    return resolve(path);
+  }
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return resolve(path);
+  }
+}
+function resolveHostGitMetadataPaths(projectRoot, workspaceDir) {
+  const candidates = new Set;
+  const addPath = (candidate) => {
+    if (existsSync(candidate)) {
+      candidates.add(toRealPath(candidate));
+    }
+  };
+  addPath(resolve(projectRoot, ".git"));
+  addPath(resolve(workspaceDir, "..", "..", ".git"));
+  for (const repoRoot of resolveHostRepoRootPaths(projectRoot)) {
+    addPath(resolve(repoRoot, ".git"));
+  }
+  const workspaceGit = resolve(workspaceDir, ".git");
+  if (existsSync(workspaceGit)) {
+    addPath(workspaceGit);
+  }
+  return [...candidates];
+}
+function resolveHostRepoRootPaths(projectRoot) {
+  const candidates = new Set;
+  const addPath = (candidate) => {
+    if (existsSync(candidate)) {
+      candidates.add(toRealPath(candidate));
+    }
+  };
+  try {
+    const monorepoRoot = resolveMonorepoRoot(projectRoot);
+    if (toRealPath(monorepoRoot) !== toRealPath(projectRoot)) {
+      addPath(monorepoRoot);
+    }
+  } catch {}
+  const reposDir = resolve(projectRoot, "repos");
+  if (existsSync(reposDir)) {
+    for (const entry of readdirSync(reposDir, { withFileTypes: true })) {
+      if (entry.isDirectory() || entry.isSymbolicLink()) {
+        addPath(resolve(reposDir, entry.name));
+      }
+    }
+  }
+  return [...candidates];
+}
+function resolveNetworkWithPolicy(sandboxConfig, envOverride) {
+  if (envOverride) {
+    const envValue = parseBooleanEnv(envOverride, sandboxConfig.network);
+    if (envValue !== sandboxConfig.network) {
+      console.warn(`[sandbox] RIG_RUNTIME_SANDBOX_NETWORK=${envOverride} overrides policy sandbox.network=${sandboxConfig.network}`);
+    }
+    return envValue;
+  }
+  return sandboxConfig.network;
+}
+function parseBooleanEnv(raw, fallback) {
+  if (!raw) {
+    return fallback;
+  }
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
+    return true;
+  }
+  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
+    return false;
+  }
+  return fallback;
+}
+function uniq(values) {
+  return [...new Set(values)];
+}
+
+// packages/isolation-plugin/src/sandbox/backend-bwrap.ts
+class BwrapBackend {
+  kind = "linux-bwrap";
+  binaryPath;
+  config;
+  ctx;
+  resolvedPaths;
+  which;
+  constructor(binaryPath, config, ctx, resolvedPaths, which) {
+    this.binaryPath = binaryPath;
+    this.config = config;
+    this.ctx = ctx;
+    this.resolvedPaths = resolvedPaths;
+    this.which = which ?? ((bin) => Bun.which(bin));
+  }
+  wrap(options) {
+    const command = this.buildCommand(options);
+    return {
+      command,
+      enabled: true,
+      backend: "linux-bwrap"
+    };
+  }
+  buildCommand(options) {
+    const { runtime, projectRoot, command } = options;
+    const { ctx, resolvedPaths, config } = this;
+    const workspaceReal = ctx.realPath(runtime.workspaceDir);
+    const runtimeRootReal = ctx.realPath(runtime.rootDir);
+    const homeReal = ctx.realPath(runtime.homeDir);
+    const tmpReal = ctx.realPath(runtime.tmpDir);
+    const cacheReal = ctx.realPath(runtime.cacheDir);
+    const hostGitDirs = resolveHostGitMetadataPaths(projectRoot, runtime.workspaceDir);
+    const hostRepoRoots = resolveHostRepoRootPaths(projectRoot).map((repoRoot) => ctx.realPath(repoRoot));
+    const bunDir = ctx.realPath(resolvedPaths.bunDir);
+    const claudeDir = resolvedPaths.claudeDir ? ctx.realPath(resolvedPaths.claudeDir) : null;
+    const allowNetwork = resolveNetworkWithPolicy(config, process.env.RIG_RUNTIME_SANDBOX_NETWORK);
+    const args = [
+      this.binaryPath,
+      "--die-with-parent",
+      "--new-session",
+      "--unshare-pid",
+      "--tmpfs",
+      "/",
+      "--ro-bind",
+      "/usr",
+      "/usr",
+      "--ro-bind",
+      "/bin",
+      "/bin",
+      "--ro-bind",
+      "/sbin",
+      "/sbin"
+    ];
+    for (const libPath of ["/lib", "/lib64"]) {
+      if (ctx.pathExists(libPath)) {
+        args.push("--ro-bind", libPath, libPath);
+      }
+    }
+    for (const etcEntry of [
+      "/etc/ld.so.cache",
+      "/etc/ld.so.conf",
+      "/etc/ld.so.conf.d",
+      "/etc/resolv.conf",
+      "/etc/hosts",
+      "/etc/nsswitch.conf",
+      "/etc/gai.conf",
+      "/etc/host.conf",
+      "/etc/ssl",
+      "/etc/ca-certificates",
+      "/etc/pki",
+      "/etc/passwd",
+      "/etc/group",
+      "/etc/localtime",
+      "/etc/timezone",
+      "/etc/locale.conf",
+      "/etc/default/locale"
+    ]) {
+      if (ctx.pathExists(etcEntry)) {
+        args.push("--ro-bind", etcEntry, etcEntry);
+      }
+    }
+    if (ctx.pathExists("/run/systemd/resolve")) {
+      args.push("--ro-bind", "/run/systemd/resolve", "/run/systemd/resolve");
+    }
+    if (ctx.pathExists("/run/nscd")) {
+      args.push("--ro-bind", "/run/nscd", "/run/nscd");
+    }
+    args.push("--ro-bind", bunDir, bunDir);
+    if (claudeDir) {
+      args.push("--ro-bind", claudeDir, claudeDir);
+    }
+    if (resolvedPaths.nodeDir && ctx.pathExists(resolvedPaths.nodeDir)) {
+      args.push("--ro-bind", resolvedPaths.nodeDir, resolvedPaths.nodeDir);
+    }
+    for (const depPath of resolvedPaths.depRoots) {
+      if (ctx.pathExists(depPath)) {
+        args.push("--ro-bind", depPath, depPath);
+      }
+    }
+    const projectRootReal = ctx.realPath(projectRoot);
+    if (projectRootReal !== workspaceReal && !projectRootReal.startsWith(workspaceReal + "/") && ctx.pathExists(projectRootReal)) {
+      args.push("--ro-bind", projectRootReal, projectRootReal);
+    }
+    for (const repoRoot of hostRepoRoots) {
+      if (!ctx.pathExists(repoRoot) || repoRoot === workspaceReal || repoRoot.startsWith(workspaceReal + "/") || repoRoot === projectRootReal || repoRoot.startsWith(projectRootReal + "/")) {
+        continue;
+      }
+      args.push("--ro-bind", repoRoot, repoRoot);
+    }
+    args.push("--bind", workspaceReal, workspaceReal);
+    args.push("--bind", runtimeRootReal, runtimeRootReal);
+    for (const rwPath of uniq([homeReal, tmpReal, cacheReal])) {
+      if (rwPath !== runtimeRootReal && !rwPath.startsWith(runtimeRootReal + "/")) {
+        args.push("--bind", rwPath, rwPath);
+      }
+    }
+    for (const gitPath of hostGitDirs) {
+      if (!ctx.pathExists(gitPath))
+        continue;
+      if (gitPath === runtimeRootReal || gitPath.startsWith(runtimeRootReal + "/"))
+        continue;
+      if (gitPath === workspaceReal || gitPath.startsWith(workspaceReal + "/"))
+        continue;
+      args.push("--bind", gitPath, gitPath);
+    }
+    const realHome = process.env.HOME?.trim();
+    if (realHome) {
+      for (const binSubdir of [".local/bin", ".local/lib", ".cargo/bin"]) {
+        const binPath = ctx.realPath(resolve2(realHome, binSubdir));
+        if (ctx.pathExists(binPath)) {
+          args.push("--ro-bind", binPath, binPath);
+        }
+      }
+      const agentSshDir = resolve2(homeReal, ".ssh");
+      if (ctx.pathExists(agentSshDir)) {
+        args.push("--ro-bind", agentSshDir, agentSshDir);
+      } else {
+        const hostSshDir = resolve2(realHome, ".ssh");
+        if (ctx.pathExists(hostSshDir)) {
+          mkdirSync(agentSshDir, { recursive: true });
+          args.push("--ro-bind", hostSshDir, agentSshDir);
+          args.push("--ro-bind", hostSshDir, hostSshDir);
+        }
+      }
+    }
+    args.push("--proc", "/proc");
+    args.push("--dev", "/dev");
+    args.push("--tmpfs", "/tmp");
+    args.push("--unsetenv", "CLAUDECODE");
+    args.push("--setenv", "HOME", homeReal);
+    args.push("--setenv", "TMPDIR", "/tmp");
+    args.push("--chdir", workspaceReal);
+    if (!allowNetwork) {
+      args.push("--unshare-net");
+    }
+    args.push("--", ...this.resolveCommandBinary(command));
+    return args;
+  }
+  resolveCommandBinary(command) {
+    if (command.length === 0)
+      return command;
+    const [bin, ...rest] = command;
+    if (!bin)
+      return command;
+    const resolved = this.which(bin);
+    if (!resolved)
+      return command;
+    try {
+      const { realpathSync: realpathSync2 } = __require("fs");
+      const resolvedBinary = realpathSync2(resolved);
+      return [resolvedBinary, ...rest];
+    } catch {
+      return [resolved, ...rest];
+    }
+  }
+}
+export {
+  BwrapBackend
+};

package/dist/src/sandbox/backend-none.d.ts

@@ -0,0 +1,11 @@
+/**
+ * NoSandboxBackend — trivial passthrough that disables sandboxing.
+ * Implements SandboxWrapper with no-op wrapping.
+ */
+import type { SandboxWrapper, SandboxWrapOptions, RuntimeSandboxPlan, SandboxBackendKind } from "./backend";
+export declare class NoSandboxBackend implements SandboxWrapper {
+    readonly kind: SandboxBackendKind;
+    private readonly reason;
+    constructor(reason?: string);
+    wrap(options: SandboxWrapOptions): RuntimeSandboxPlan;
+}

package/dist/src/sandbox/backend-none.js

@@ -0,0 +1,20 @@
+// @bun
+// packages/isolation-plugin/src/sandbox/backend-none.ts
+class NoSandboxBackend {
+  kind = "none";
+  reason;
+  constructor(reason) {
+    this.reason = reason;
+  }
+  wrap(options) {
+    return {
+      command: options.command,
+      enabled: false,
+      backend: "none",
+      ...this.reason !== undefined ? { reason: this.reason } : {}
+    };
+  }
+}
+export {
+  NoSandboxBackend
+};

package/dist/src/sandbox/backend-seatbelt.d.ts

@@ -0,0 +1,13 @@
+import type { SandboxConfig } from "@rig/contracts";
+import type { FilesystemContext, ResolvedPaths, RuntimeSandboxPlan, SandboxBackendKind, SandboxWrapOptions, SandboxWrapper } from "./backend";
+export declare class SeatbeltBackend implements SandboxWrapper {
+    readonly kind: SandboxBackendKind;
+    private readonly binaryPath;
+    private readonly config;
+    private readonly ctx;
+    private readonly resolvedPaths;
+    constructor(binaryPath: string, config: SandboxConfig, ctx: FilesystemContext, resolvedPaths: ResolvedPaths);
+    wrap(options: SandboxWrapOptions): RuntimeSandboxPlan;
+    private writeSeatbeltProfile;
+    private renderProfile;
+}

package/dist/src/sandbox/backend-seatbelt.js

@@ -0,0 +1,225 @@
+// @bun
+// packages/isolation-plugin/src/sandbox/backend-seatbelt.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+
+// packages/isolation-plugin/src/sandbox/utils.ts
+import { existsSync, readdirSync, realpathSync } from "fs";
+import { resolve } from "path";
+import { resolveMonorepoRoot } from "@rig/core/layout";
+function toRealPath(path) {
+  if (!existsSync(path)) {
+    return resolve(path);
+  }
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return resolve(path);
+  }
+}
+function resolveHostGitMetadataPaths(projectRoot, workspaceDir) {
+  const candidates = new Set;
+  const addPath = (candidate) => {
+    if (existsSync(candidate)) {
+      candidates.add(toRealPath(candidate));
+    }
+  };
+  addPath(resolve(projectRoot, ".git"));
+  addPath(resolve(workspaceDir, "..", "..", ".git"));
+  for (const repoRoot of resolveHostRepoRootPaths(projectRoot)) {
+    addPath(resolve(repoRoot, ".git"));
+  }
+  const workspaceGit = resolve(workspaceDir, ".git");
+  if (existsSync(workspaceGit)) {
+    addPath(workspaceGit);
+  }
+  return [...candidates];
+}
+function resolveHostRepoRootPaths(projectRoot) {
+  const candidates = new Set;
+  const addPath = (candidate) => {
+    if (existsSync(candidate)) {
+      candidates.add(toRealPath(candidate));
+    }
+  };
+  try {
+    const monorepoRoot = resolveMonorepoRoot(projectRoot);
+    if (toRealPath(monorepoRoot) !== toRealPath(projectRoot)) {
+      addPath(monorepoRoot);
+    }
+  } catch {}
+  const reposDir = resolve(projectRoot, "repos");
+  if (existsSync(reposDir)) {
+    for (const entry of readdirSync(reposDir, { withFileTypes: true })) {
+      if (entry.isDirectory() || entry.isSymbolicLink()) {
+        addPath(resolve(reposDir, entry.name));
+      }
+    }
+  }
+  return [...candidates];
+}
+function resolveNetworkWithPolicy(sandboxConfig, envOverride) {
+  if (envOverride) {
+    const envValue = parseBooleanEnv(envOverride, sandboxConfig.network);
+    if (envValue !== sandboxConfig.network) {
+      console.warn(`[sandbox] RIG_RUNTIME_SANDBOX_NETWORK=${envOverride} overrides policy sandbox.network=${sandboxConfig.network}`);
+    }
+    return envValue;
+  }
+  return sandboxConfig.network;
+}
+function parseBooleanEnv(raw, fallback) {
+  if (!raw) {
+    return fallback;
+  }
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
+    return true;
+  }
+  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
+    return false;
+  }
+  return fallback;
+}
+function uniq(values) {
+  return [...new Set(values)];
+}
+function seatbeltString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+
+// packages/isolation-plugin/src/sandbox/backend-seatbelt.ts
+class SeatbeltBackend {
+  kind = "macos-seatbelt";
+  binaryPath;
+  config;
+  ctx;
+  resolvedPaths;
+  constructor(binaryPath, config, ctx, resolvedPaths) {
+    this.binaryPath = binaryPath;
+    this.config = config;
+    this.ctx = ctx;
+    this.resolvedPaths = resolvedPaths;
+  }
+  wrap(options) {
+    const profilePath = this.writeSeatbeltProfile(options);
+    return {
+      command: [this.binaryPath, "-f", profilePath, ...options.command],
+      enabled: true,
+      backend: "macos-seatbelt",
+      profilePath
+    };
+  }
+  writeSeatbeltProfile(options) {
+    const sandboxDir = resolve2(options.runtime.rootDir, "sandbox");
+    mkdirSync(sandboxDir, { recursive: true });
+    const profilePath = resolve2(sandboxDir, "seatbelt.sb");
+    const profile = this.renderProfile(options);
+    writeFileSync(profilePath, `${profile}
+`, "utf-8");
+    return profilePath;
+  }
+  renderProfile(options) {
+    const { runtime, projectRoot } = options;
+    const { ctx, resolvedPaths, config } = this;
+    const workspaceReal = ctx.realPath(runtime.workspaceDir);
+    const runtimeRootReal = ctx.realPath(runtime.rootDir);
+    const homeReal = ctx.realPath(runtime.homeDir);
+    const tmpReal = ctx.realPath(runtime.tmpDir);
+    const cacheReal = ctx.realPath(runtime.cacheDir);
+    const hostGitDirs = resolveHostGitMetadataPaths(projectRoot, runtime.workspaceDir);
+    const hostRepoRoots = resolveHostRepoRootPaths(projectRoot).map((repoRoot) => ctx.realPath(repoRoot));
+    const bunDir = ctx.realPath(resolvedPaths.bunDir);
+    const claudeDir = resolvedPaths.claudeDir ? ctx.realPath(resolvedPaths.claudeDir) : null;
+    const allowNetwork = resolveNetworkWithPolicy(config, process.env.RIG_RUNTIME_SANDBOX_NETWORK);
+    const lines = [
+      "(version 1)",
+      "(deny default)",
+      '(import "system.sb")',
+      "(allow process*)",
+      "(allow process-info*)",
+      "(allow signal)",
+      "(allow sysctl-read)",
+      "(allow file-read-metadata)"
+    ];
+    if (allowNetwork) {
+      lines.push("(allow network*)");
+    }
+    for (const sysPath of [
+      "/usr/lib",
+      "/usr/bin",
+      "/usr/sbin",
+      "/usr/share",
+      "/bin",
+      "/sbin",
+      "/System",
+      "/Library",
+      "/Library/Frameworks",
+      "/Library/Developer",
+      "/Library/Apple",
+      "/Applications",
+      "/private/var/db",
+      "/opt/homebrew"
+    ]) {
+      lines.push(`(allow file-read* (subpath ${seatbeltString(sysPath)}))`);
+    }
+    lines.push(`(allow file-read* (subpath ${seatbeltString(bunDir)}))`);
+    if (claudeDir) {
+      lines.push(`(allow file-read* (subpath ${seatbeltString(claudeDir)}))`);
+    }
+    if (resolvedPaths.nodeDir) {
+      lines.push(`(allow file-read* (subpath ${seatbeltString(resolvedPaths.nodeDir)}))`);
+    }
+    for (const depPath of resolvedPaths.depRoots) {
+      lines.push(`(allow file-read* (subpath ${seatbeltString(depPath)}))`);
+    }
+    for (const rwPath of uniq([
+      workspaceReal,
+      runtimeRootReal,
+      homeReal,
+      tmpReal,
+      cacheReal
+    ])) {
+      lines.push(`(allow file-read* (subpath ${seatbeltString(rwPath)}))`);
+      lines.push(`(allow file-write* (subpath ${seatbeltString(rwPath)}))`);
+    }
+    for (const gitPath of hostGitDirs) {
+      lines.push(`(allow file-read* (subpath ${seatbeltString(gitPath)}))`);
+      lines.push(`(allow file-write* (subpath ${seatbeltString(gitPath)}))`);
+    }
+    const projectRootReal = ctx.realPath(projectRoot);
+    if (projectRootReal !== workspaceReal && !projectRootReal.startsWith(workspaceReal + "/")) {
+      lines.push(`(allow file-read* (subpath ${seatbeltString(projectRootReal)}))`);
+    }
+    for (const repoRoot of hostRepoRoots) {
+      if (!ctx.pathExists(repoRoot) || repoRoot === workspaceReal || repoRoot.startsWith(workspaceReal + "/") || repoRoot === projectRootReal || repoRoot.startsWith(projectRootReal + "/")) {
+        continue;
+      }
+      lines.push(`(allow file-read* (subpath ${seatbeltString(repoRoot)}))`);
+    }
+    const realHome = process.env.HOME?.trim();
+    if (realHome) {
+      for (const binSubdir of [".local/bin", ".cargo/bin"]) {
+        const binPath = resolve2(realHome, binSubdir);
+        if (ctx.pathExists(binPath)) {
+          lines.push(`(allow file-read* (subpath ${seatbeltString(ctx.realPath(binPath))}))`);
+        }
+      }
+    }
+    for (const tempPath of [
+      "/dev",
+      "/tmp",
+      "/private/tmp",
+      "/var/folders",
+      "/private/var/folders"
+    ]) {
+      lines.push(`(allow file-read* (subpath ${seatbeltString(tempPath)}))`);
+      lines.push(`(allow file-write* (subpath ${seatbeltString(tempPath)}))`);
+    }
+    return lines.join(`
+`);
+  }
+}
+export {
+  SeatbeltBackend
+};

package/dist/src/sandbox/backend.d.ts

@@ -0,0 +1,117 @@
+import type { SandboxConfig } from "@rig/contracts";
+export type RuntimeMode = "worktree";
+/** Describes the filesystem layout of an agent runtime environment. */
+export type RuntimeDescriptor = {
+    id: string;
+    mode: RuntimeMode;
+    rootDir: string;
+    workspaceDir: string;
+    homeDir: string;
+    tmpDir: string;
+    cacheDir: string;
+    stateDir: string;
+    sessionDir: string;
+    claudeHomeDir: string;
+    binDir: string;
+};
+/** All possible sandbox backend identifiers. Open union -- do not exhaustively match. */
+export type SandboxBackendKind = "none" | "macos-seatbelt" | "linux-bwrap" | "docker";
+/** Options passed to SandboxWrapper.wrap(). Config is injected at construction, not here. */
+export type SandboxWrapOptions = {
+    projectRoot: string;
+    runtime: RuntimeDescriptor;
+    command: string[];
+};
+/** The result of wrapping a command for sandboxed execution. */
+export type RuntimeSandboxPlan = {
+    command: string[];
+    enabled: boolean;
+    backend: SandboxBackendKind;
+    profilePath?: string;
+    reason?: string;
+    /** Backend-specific details for observability (mount count, network policy, image tag, etc.). */
+    metadata?: Record<string, unknown>;
+};
+/** Injectable filesystem context for testability. */
+export type FilesystemContext = {
+    pathExists: (path: string) => boolean;
+    realPath: (path: string) => string;
+};
+/** Pre-resolved tool paths. Factory resolves these, backends consume them. */
+export type ResolvedPaths = {
+    bunDir: string;
+    claudeDir: string | null;
+    nodeDir: string | null;
+    depRoots: string[];
+};
+/** Result of executing a command inside a SandboxExecutor. */
+export type ExecResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+/** Options for SandboxExecutor.exec(). */
+export type ExecOpts = {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+};
+/** Configuration passed to SandboxExecutor.init(). */
+export type SandboxInitConfig = {
+    runtime: RuntimeDescriptor;
+    sandboxConfig: SandboxConfig;
+    paths: ResolvedPaths;
+    fs: FilesystemContext;
+};
+/** Backend that wraps a command for sandboxed execution. Caller owns spawning. */
+export interface SandboxWrapper {
+    readonly kind: SandboxBackendKind;
+    wrap(options: SandboxWrapOptions): RuntimeSandboxPlan;
+}
+/** Backend that owns execution entirely. Used by future Wasm/container backends. */
+export interface SandboxExecutor {
+    readonly kind: SandboxBackendKind;
+    init(config?: SandboxInitConfig): Promise<void>;
+    exec(command: string[], opts?: ExecOpts): Promise<ExecResult>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+/**
+ * Union type. Callers discriminate via `'wrap' in backend` or `'exec' in backend`.
+ * SandboxBackendKind is an open union -- consumers must not rely on exhaustive matching.
+ */
+export type SandboxErrorCode = "backend-unavailable" | "backend-probe-failed" | "profile-write-failed" | "policy-violation";
+export declare class SandboxError extends Error {
+    readonly code: SandboxErrorCode;
+    constructor(code: SandboxErrorCode, message: string);
+}
+/** Result of the backend resolution factory. */
+export type BackendResolution = {
+    backend: SandboxWrapper;
+    selectedKind: SandboxBackendKind;
+    /** What tools/binaries were checked during probe-based detection. */
+    probed: string[];
+    /** Human-readable reason for the selection. */
+    reason: string;
+};
+type RuntimeSandboxMode = "off" | "auto" | "enforce";
+/**
+ * Map policy sandbox config to internal sandbox mode, with optional env override.
+ * Policy "observe" maps to "auto" in sandbox terms.
+ */
+export declare function resolveRuntimeSandboxModeWithPolicy(sandboxConfig: SandboxConfig, envOverride: string | undefined): RuntimeSandboxMode;
+/**
+ * Resolve which sandbox backend to use for the current platform and policy.
+ *
+ * 1. Loads SandboxConfig from policy.json via guard.ts
+ * 2. Resolves mode (off/auto/enforce) with optional env override
+ * 3. Checks for explicit backend selection (RIG_SANDBOX_BACKEND env)
+ * 4. Probes platform: darwin -> SeatbeltBackend, linux -> BwrapBackend
+ * 5. Falls back to NoSandboxBackend or throws if mode=enforce
+ */
+export declare function resolveBackend(projectRoot: string, options?: {
+    envOverride?: string;
+    backendOverride?: string;
+}): Promise<BackendResolution>;
+export {};