@semalt-ai/code 1.8.5 → 1.19.0

package/lib/sandbox.js

@@ -0,0 +1,568 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// OS-level filesystem sandbox for shell commands (Task 4.4)
+// ---------------------------------------------------------------------------
+//
+// Wraps every shell command (and its child processes) in a kernel-enforced
+// filesystem jail so confinement is the OS's job, not trust or pattern-matching.
+// This is an ADDITIONAL boundary UNDER the existing deny-list (lib/deny.js),
+// per-pattern permissions (lib/permissions.js), --readonly, and isPathSafe
+// (lib/tools.js) — defense in depth. All of those still run; the sandbox catches
+// what they miss.
+//
+//   Policy model (what's allowed / denied):
+//     * Reads are allowed broadly (the whole filesystem is readable).
+//     * Writes are confined to the working directory (and a writable temp dir).
+//       With --allow-anywhere the whole filesystem becomes writable EXCEPT the
+//       protected paths below, which stay read-only regardless.
+//     * Network is BINARY (Task 4.4b): a sandboxed command has either normal
+//       network (the default — otherwise `npm install`/`pip` are unusable) or
+//       NONE, enforced by the kernel: bwrap `--unshare-net` (a fresh network
+//       namespace with no real interfaces) on Linux, a Seatbelt `(deny network*)`
+//       clause on macOS. There is deliberately NO host proxy, NO domain
+//       allowlist, and NO TLS interception — see the rationale below.
+//
+//   Why binary, not a domain allowlist (the state-of-the-art lesson):
+//     The reference implementation (Claude Code) shipped a domain-allowlist
+//     network sandbox via a host-side SOCKS/HTTP proxy. It was bypassed COMPLETELY,
+//     twice, by two independent researchers, over 5.5 months — because OS
+//     enforcement correctly pins the agent to localhost, but the egress decision is
+//     delegated to a host-side proxy with full network privileges, and fooling the
+//     proxy makes the HOST dial out. The documented failures: (a) `allowedDomains:
+//     []` (the most-restrictive INTENT) was read as "allow all" via an
+//     `allowedDomains.length > 0` check — a FAIL-OPEN (CVE-2025-66479);
+//     (b) a JS-vs-libc hostname-parser differential (`endsWith()`); (c) TLS MITM in
+//     the proxy broke Go binaries (`gh`, `gcloud`). The proxy also rode on an
+//     abandoned dependency in the security path.
+//     We choose BINARY isolation to remove that entire class of bypass by
+//     construction: network is on (normal TLS, Go binaries work) or off
+//     (kernel-level), with no proxy, no allowlist, no interception, and no new
+//     dependency. Domain-granularity is out of scope (deferred), with the rationale
+//     recorded in CLAUDE.md.
+//
+//   Anti-fail-open (the allowedDomains:[] lesson, constraint #2): network defaults
+//     ON for sandboxed commands, but once a human TOUCHES the network setting
+//     (`sandbox.network` in config, or the `--no-network` flag) that is an
+//     "isolation-requested" context — and there, anything we do not explicitly
+//     recognize as "on" (empty/missing/malformed) resolves to the SAFE isolated
+//     state (no-network), NEVER silently back to network. See normalizeSandbox.
+//
+//   Platforms:
+//     * macOS            → Seatbelt via `sandbox-exec` (built-in, nothing to
+//                          install). An SBPL policy string is generated per call.
+//     * Linux / WSL2     → `bwrap` (bubblewrap, unprivileged user namespaces).
+//     * Windows / WSL1   → no OS primitive (bwrap needs namespaces WSL1 lacks;
+//                          native Windows has none). The sandbox is UNAVAILABLE;
+//                          see the fallback rules in agentExecShell.
+//
+//   The three real-CVE constraints this enforces:
+//     1. The agent can NEVER disable the sandbox. There is no tool/flag/config
+//        the MODEL can reach that turns it off — `sandbox.mode` lives in the
+//        user/project config files (human-edited) and the only runtime opt-out
+//        is a human-typed CLI flag. (A blocked agent must not be able to "finish
+//        the task" by escaping its jail.)
+//     2. config / hooks / secrets are READ-ONLY inside the jail, INCLUDING files
+//        that do not yet exist (CVE-2026-25725): the whole ~/.semalt-ai dir, the
+//        secret-file dirs, and system config are bind-mounted read-only, so the
+//        sandboxed process cannot create a missing config.json to inject hooks.
+//     3. procfs / symlink / .. rewrites are confined on the RESOLVED real path,
+//        not the textual one (the /proc/self/root bypass): bwrap mounts a fresh
+//        /proc and the kernel enforces every bind on the resolved path; the
+//        protected paths are realpath()-canonicalized before they are bound.
+//
+//   Fallback (fail-safe, defaults safe): if the sandbox can't start (missing
+//   bwrap, unsupported platform) we do NOT silently run unsandboxed. By default
+//   the command falls back to a human approval (`onUnsandboxed`); with no
+//   approver (non-TTY/headless) it is REFUSED. `sandbox.failIfUnavailable: true`
+//   turns the fallback into a hard error for teams that want a strict gate.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { protectedConfigDirs } = require('./constants');
+
+const SANDBOX_MODES = ['auto', 'off'];
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+// Validate + canonicalize `config.sandbox`. Pure; consumed by lib/config.js
+// normalizeConfig. `mode` is `auto` (use the sandbox when available) or `off`
+// (a deliberate human opt-out). `failIfUnavailable` makes an unavailable sandbox
+// a hard error instead of an approval fallback. `network` is `on` (the default —
+// the sandbox must stay usable for `npm install`/`pip`) or `off` (kernel-level
+// no-network for sandboxed commands). Unknown input → safe defaults.
+//
+// Anti-fail-open (constraint #2, the allowedDomains:[] → "allow all" CVE-2025-66479
+// lesson): `network` defaults ON only when the human has NOT touched it (the key is
+// absent). The moment the `network` key is PRESENT — an isolation-requested context
+// — anything that is not EXACTLY the string 'on' (empty, malformed, an object, a
+// typo, `false`, `null`, …) resolves to the SAFE isolated state 'off', never
+// silently back to network. So the intended-most-restrictive input is the
+// most-restrictive outcome, and a broken config fails toward isolation.
+function normalizeSandbox(raw) {
+  const out = { mode: 'auto', failIfUnavailable: false, network: 'on' };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;
+  if (raw.mode === 'off') out.mode = 'off';
+  if (raw.failIfUnavailable === true) out.failIfUnavailable = true;
+  // PRESENT-but-not-exactly-'on' ⇒ 'off' (fail-safe toward isolation). Absent ⇒
+  // the default 'on'.
+  if ('network' in raw) out.network = raw.network === 'on' ? 'on' : 'off';
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Protected paths (constraint #2)
+// ---------------------------------------------------------------------------
+
+// The paths that must be READ-ONLY inside the jail no matter what — including
+// when they do not yet exist (a not-yet-present config.json cannot be created
+// because its whole parent dir is bound read-only). Resolved real paths so a
+// symlink/.. rewrite cannot dodge them (constraint #3).
+function protectedPaths({ home = os.homedir(), cwd = process.cwd() } = {}) {
+  const raw = [
+    // The protected-CONFIG set, single-sourced (Pre-Task 5.0b): the whole
+    // ~/.semalt-ai dir AND every project .semalt dir from cwd up to the repo
+    // root. Binding the project .semalt dir read-only is what stops a sandboxed
+    // shell command from creating/modifying .semalt/config.json (or agents/hooks)
+    // even though .semalt sits inside the writable CWD — the project equivalent
+    // of the not-yet-existing-config CVE-2026-25725 guard for ~/.semalt-ai.
+    ...protectedConfigDirs({ home, cwd }),
+    path.join(home, '.ssh'),
+    path.join(home, '.aws'),
+    path.join(home, '.gnupg'),
+    '/etc',
+  ];
+  const out = [];
+  const seen = new Set();
+  for (const p of raw) {
+    let real = p;
+    try { real = fs.realpathSync(p); } catch { real = path.resolve(p); }
+    if (!seen.has(real)) { seen.add(real); out.push(real); }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Policy generation
+// ---------------------------------------------------------------------------
+
+function _sbplQuote(p) {
+  // SBPL string literal — escape backslashes and double quotes.
+  return '"' + String(p).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+// macOS Seatbelt (SBPL) policy. Rule precedence in SBPL is LAST-MATCH-WINS, so
+// the order is: allow everything (keeps reads + network working) → deny all
+// writes → re-allow writes under the writable roots → re-deny the protected
+// paths (last, so they win even if nested under a writable root). With
+// rootWritable (--allow-anywhere) we skip the blanket write-deny but STILL
+// re-deny the protected paths.
+function buildSeatbeltPolicy({ writableRoots = [], protectedPaths: protectedList = [], rootWritable = false, network = 'on' } = {}) {
+  const lines = [
+    '(version 1)',
+    '; semalt-code OS sandbox — filesystem confinement + binary network isolation (Task 4.4/4.4b)',
+    '(allow default)',
+  ];
+  // Binary network isolation (Task 4.4b): deny ALL network operations. Placed
+  // right after `(allow default)` so last-match-wins keeps it denied (nothing
+  // below re-allows network — the write rules touch only file-write*). This is a
+  // kernel/Seatbelt deny, NOT a host proxy: no TLS interception, so it never
+  // breaks Go binaries the way a MITM proxy does — it simply removes the network.
+  if (network === 'off') lines.push('(deny network*)');
+  if (!rootWritable) {
+    lines.push('(deny file-write* (subpath "/"))');
+    // Standard pseudo-devices must stay writable or shells break (/dev/null, tty).
+    lines.push('(allow file-write* (subpath "/dev"))');
+    for (const w of writableRoots) {
+      if (w) lines.push(`(allow file-write* (subpath ${_sbplQuote(w)}))`);
+    }
+  }
+  for (const p of protectedList) {
+    if (p) lines.push(`(deny file-write* (subpath ${_sbplQuote(p)}))`);
+  }
+  return lines.join('\n');
+}
+
+// Linux bubblewrap argument vector. bwrap applies binds IN ORDER and a later
+// bind over an overlapping path WINS, so: bind the whole fs (read-only by
+// default, read-write under --allow-anywhere) → fresh /proc + /dev → re-bind the
+// writable roots read-write → re-bind the protected paths read-only LAST (so
+// they win over a writable root they sit inside, e.g. cwd == $HOME) → chdir.
+function buildBwrapArgs({ writableRoots = [], protectedPaths: protectedList = [], rootWritable = false, chdir, fsExists, network = 'on' } = {}) {
+  const exists = typeof fsExists === 'function'
+    ? fsExists
+    : (p) => { try { return fs.existsSync(p); } catch { return false; } };
+  const args = [];
+  // Binary network isolation (Task 4.4b): a fresh, unconnected network namespace.
+  // `--unshare-net` gives the jail no real interfaces — kernel-enforced no-network,
+  // no host proxy, no TLS interception. Placed first so it is unambiguous; bwrap
+  // applies unshare flags independent of bind order. Omitted entirely when network
+  // is 'on' (the default) so normal egress + TLS work.
+  if (network === 'off') args.push('--unshare-net');
+  args.push(rootWritable ? '--bind' : '--ro-bind', '/', '/');
+  // Fresh procfs is load-bearing: it makes /proc/self/root resolve to the jail
+  // root, so a /proc/self/root/<path> rewrite is confined on the resolved path
+  // exactly like the textual path (constraint #3).
+  args.push('--proc', '/proc');
+  args.push('--dev', '/dev');
+  for (const w of writableRoots) {
+    if (w && exists(w)) args.push('--bind', w, w);
+  }
+  for (const p of protectedList) {
+    if (p && exists(p)) args.push('--ro-bind', p, p);
+  }
+  if (chdir) args.push('--chdir', chdir);
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Detection (cached)
+// ---------------------------------------------------------------------------
+
+let _detectionCache = null;
+
+function _defaultWhich(name) {
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const extras = ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin', '/opt/homebrew/bin'];
+  for (const d of dirs.concat(extras)) {
+    const p = path.join(d, name);
+    try { fs.accessSync(p, fs.constants.X_OK); return p; } catch { /* keep looking */ }
+  }
+  return null;
+}
+
+// Functional probe: bwrap can be installed yet unusable (WSL1, or a kernel with
+// unprivileged user namespaces disabled). Actually launch a trivial jail and
+// require a clean exit before we trust it.
+function _defaultBwrapProbe(bwrapPath) {
+  try {
+    const r = spawnSync(bwrapPath, ['--ro-bind', '/', '/', '--proc', '/proc', '--dev', '/dev', '/bin/true'], {
+      timeout: 5000,
+      stdio: 'ignore',
+    });
+    return r && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// Detect the platform + tool availability ONCE and cache it. Injectable deps
+// (`platform`, `which`, `probe`, `readFile`) make every platform path unit
+// testable without the real tools. `force: true` bypasses the cache.
+//
+// Returns: { platform, supported, tool, available, reason, installHint }
+//   supported  — is this a platform we have a sandbox strategy for at all?
+//   available  — is the tool present AND functional right now?
+//   reason     — why unavailable (when !available)
+//   installHint— actionable remediation for the user
+function detectSandbox(opts = {}) {
+  if (_detectionCache && !opts.force) return _detectionCache;
+  const platform = opts.platform || process.platform;
+  const which = opts.which || _defaultWhich;
+  const probe = opts.probe || _defaultBwrapProbe;
+  const readFile = opts.readFile || ((p) => fs.readFileSync(p, 'utf8'));
+
+  let result;
+  if (platform === 'darwin') {
+    const binPath = which('sandbox-exec');
+    result = binPath
+      ? { platform, supported: true, tool: 'sandbox-exec', available: true, reason: null, installHint: null, binPath }
+      : { platform, supported: true, tool: 'sandbox-exec', available: false, reason: 'sandbox-exec not found (it ships with macOS; PATH may be stripped)', installHint: 'Ensure /usr/bin is on PATH.' };
+  } else if (platform === 'linux') {
+    // WSL1 lacks the user/mount namespaces bwrap needs. WSL2 has them. We don't
+    // hard-fail on the WSL1 string — the functional probe is the source of truth
+    // — but we surface a clearer reason when we can tell it's WSL1.
+    let isWsl1 = false;
+    try {
+      const ver = readFile('/proc/version');
+      if (/microsoft/i.test(ver) && !/WSL2/i.test(ver)) isWsl1 = true;
+    } catch { /* /proc/version unreadable — fall through to the probe */ }
+    const binPath = which('bwrap');
+    if (!binPath) {
+      result = {
+        platform, supported: true, tool: 'bwrap', available: false,
+        reason: isWsl1 ? 'bubblewrap not found (and WSL1 cannot run it)' : 'bubblewrap (bwrap) not found',
+        installHint: 'Install bubblewrap: `apt install bubblewrap` (Debian/Ubuntu) or `dnf install bubblewrap` (Fedora/RHEL).',
+      };
+    } else if (!probe(binPath)) {
+      result = {
+        platform, supported: true, tool: 'bwrap', available: false,
+        reason: isWsl1
+          ? 'bubblewrap is installed but WSL1 lacks the user/mount namespaces it needs'
+          : 'bubblewrap is installed but could not start a jail (unprivileged user namespaces may be disabled)',
+        installHint: isWsl1
+          ? 'Use WSL2 (`wsl --set-version <distro> 2`) for kernel-level sandboxing.'
+          : 'Enable unprivileged user namespaces: `sysctl -w kernel.unprivileged_userns_clone=1`.',
+        binPath,
+      };
+    } else {
+      result = { platform, supported: true, tool: 'bwrap', available: true, reason: null, installHint: null, binPath };
+    }
+  } else if (platform === 'win32') {
+    result = {
+      platform, supported: false, tool: null, available: false,
+      reason: 'native Windows has no OS sandbox primitive for this',
+      installHint: 'Run inside WSL2 with bubblewrap installed for kernel-level sandboxing.',
+    };
+  } else {
+    result = {
+      platform, supported: false, tool: null, available: false,
+      reason: `no sandbox strategy for platform "${platform}"`,
+      installHint: null,
+    };
+  }
+
+  if (!opts.noCache) _detectionCache = result;
+  return result;
+}
+
+// Test seam — drop the cached detection.
+function _resetSandboxDetection() { _detectionCache = null; }
+
+// ---------------------------------------------------------------------------
+// Command wrapping
+// ---------------------------------------------------------------------------
+
+// Wrap a shell command string into a sandboxed argv for the detected tool.
+// Returns { file, args } to hand to spawn (NO shell:true — the inner /bin/sh
+// runs the command), or null when the tool can't be wrapped.
+//
+//   tool          'bwrap' | 'sandbox-exec'
+//   command       the raw shell command string
+//   cwd           working dir (the writable root + chdir target)
+//   allowAnywhere mirror of --allow-anywhere: make the whole fs writable EXCEPT
+//                 the protected paths (which stay read-only regardless)
+//   network       'on' (default, normal egress) | 'off' (kernel-level no-network:
+//                 --unshare-net / Seatbelt (deny network*))
+function wrapCommand(command, { tool, cwd = process.cwd(), allowAnywhere = false, home = os.homedir(), tmpDir = os.tmpdir(), binPath, network = 'on' } = {}) {
+  if (typeof command !== 'string' || !command) return null;
+  let realCwd = cwd;
+  try { realCwd = fs.realpathSync(cwd); } catch { realCwd = path.resolve(cwd); }
+  const protectedList = protectedPaths({ home, cwd: realCwd });
+  // Default: cwd + temp are the only writable roots. --allow-anywhere makes the
+  // whole fs writable (rootWritable) so explicit writable roots are redundant.
+  const writableRoots = allowAnywhere ? [] : [realCwd, tmpDir].filter(Boolean);
+
+  if (tool === 'bwrap') {
+    const bwrapArgs = buildBwrapArgs({
+      writableRoots,
+      protectedPaths: protectedList,
+      rootWritable: allowAnywhere,
+      chdir: realCwd,
+      network,
+    });
+    return { file: binPath || 'bwrap', args: [...bwrapArgs, '/bin/sh', '-c', command] };
+  }
+  if (tool === 'sandbox-exec') {
+    const policy = buildSeatbeltPolicy({
+      writableRoots,
+      protectedPaths: protectedList,
+      rootWritable: allowAnywhere,
+      network,
+    });
+    return { file: binPath || 'sandbox-exec', args: ['-p', policy, '/bin/sh', '-c', command] };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Decision (config × detection)
+// ---------------------------------------------------------------------------
+
+// Resolve the effective network mode from config + the human-typed CLI flag.
+// 'off' when EITHER the human set `sandbox.network` to anything-not-'on' (handled
+// by normalizeSandbox's anti-fail-open) OR `--no-network` is present. `noNetwork`
+// defaults to the argv flag — a human-only signal the model can never reach (the
+// model controls only the command string). Pure given its inputs.
+function resolveNetworkMode(s, noNetwork) {
+  const nn = noNetwork !== undefined ? noNetwork : _argvHasFlag('--no-network');
+  return (nn || s.network === 'off') ? 'off' : 'on';
+}
+
+// Combine the normalized config with detection into a per-command decision.
+//   status 'on'          — wrap + run sandboxed (decision.network carries the
+//                          kernel-enforced network mode 'on'|'off')
+//   status 'off'         — mode is `off` (a deliberate human opt-out); run plain.
+//                          Network isolation needs the jail, so an unsandboxed run
+//                          has the host network (reported as net 'on' downstream).
+//   status 'unavailable' — wanted but the tool isn't usable; the caller applies
+//                          the fallback (failIfUnavailable → hard error; else a
+//                          human approval; no approver → refuse)
+function decideSandbox({ getConfig, detection, noNetwork } = {}) {
+  let cfg = {};
+  try { cfg = (getConfig ? getConfig() : {}) || {}; } catch { cfg = {}; }
+  const s = normalizeSandbox(cfg.sandbox);
+  const network = resolveNetworkMode(s, noNetwork);
+  const det = detection || detectSandbox();
+  if (s.mode === 'off') {
+    return { status: 'off', tool: null, reason: 'mode is off (human opt-out)', failIfUnavailable: s.failIfUnavailable, network };
+  }
+  if (det.available) {
+    return { status: 'on', tool: det.tool, binPath: det.binPath, reason: null, failIfUnavailable: s.failIfUnavailable, network };
+  }
+  return {
+    status: 'unavailable',
+    tool: det.tool,
+    reason: det.reason,
+    installHint: det.installHint,
+    supported: det.supported,
+    failIfUnavailable: s.failIfUnavailable,
+    network,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shared sandbox-wrapping shim (Pre-Task 5.0a)
+// ---------------------------------------------------------------------------
+//
+// THE universal shell chokepoint. Every shell-executing path in the codebase —
+// the agent's exec/shell tools (agentExecShell, async spawn), self-verification
+// (lib/verify.js, spawnSync), and command-type lifecycle hooks (lib/hooks.js,
+// spawnSync) — resolves its spawn through THIS function, so the OS sandbox is
+// applied identically everywhere and the model has no path that runs a command
+// outside it.
+//
+// It folds the config×detection decision (decideSandbox), the command wrapping
+// (wrapCommand), and the fail-safe fallback (failIfUnavailable hard error / human
+// approval / refuse) into a single async resolution the caller spawns:
+//
+//   { run: true,  file, args, useShell, sandbox: 'on'|'off'|'unavailable' }
+//       Spawn `file`. When `useShell` is true there are no args and the caller
+//       passes { shell: true } (a deliberate UNsandboxed run — mode is off, the
+//       human approved an unavailable run, or --dangerously-skip-permissions).
+//       When false, spawn `file` with `args` and NO shell (the inner /bin/sh in
+//       the wrapped argv runs the command jailed).
+//   { run: false, sandbox: 'unavailable', hard, reason, installHint, message }
+//       REFUSED — the caller must NOT run the command. `hard` true ⇒
+//       failIfUnavailable strict gate; false ⇒ no/declined human approval. Never
+//       a silent unsandboxed run.
+//
+// `onUnsandboxed` (the human-approval callback) lives in the executor owner
+// (index.js), never anywhere the model can reach, so the agent can never approve
+// its own escape. `allowAnywhere`/`skipPermissions` default to the human-typed
+// CLI flags — call-level options the model might influence cannot flip them.
+function _argvHasFlag(flag) {
+  try { return Array.isArray(process.argv) && process.argv.includes(flag); }
+  catch { return false; }
+}
+
+async function resolveSandboxedSpawn({
+  command,
+  getConfig,
+  detection,
+  onUnsandboxed = null,
+  cwd = process.cwd(),
+  allowAnywhere,
+  skipPermissions,
+  noNetwork,
+} = {}) {
+  const aa = allowAnywhere !== undefined ? allowAnywhere : _argvHasFlag('--allow-anywhere');
+  const sp = skipPermissions !== undefined ? skipPermissions : _argvHasFlag('--dangerously-skip-permissions');
+
+  // --dangerously-skip-permissions opts out of ALL safety, sandbox included — so
+  // there is no jail and the command keeps the host network (net 'on', honest).
+  if (sp) return { run: true, file: command, args: [], useShell: true, sandbox: 'off', network: 'on' };
+
+  const decision = decideSandbox({ getConfig, detection, noNetwork });
+  if (decision.status === 'on') {
+    const wrapped = wrapCommand(command, {
+      tool: decision.tool,
+      binPath: decision.binPath,
+      cwd,
+      allowAnywhere: aa,
+      network: decision.network,
+    });
+    if (wrapped) {
+      return { run: true, file: wrapped.file, args: wrapped.args, useShell: false, sandbox: 'on', network: decision.network };
+    }
+    // Could not build a wrapper — treat as unavailable rather than silently
+    // dropping the jail.
+    decision.status = 'unavailable';
+    decision.reason = decision.reason || 'could not build a sandbox wrapper for this command';
+  }
+
+  if (decision.status === 'unavailable') {
+    const why = decision.reason || 'unavailable';
+    if (decision.failIfUnavailable) {
+      return {
+        run: false, sandbox: 'unavailable', hard: true, reason: why, installHint: decision.installHint,
+        message: `OS sandbox unavailable (${why}) and sandbox.failIfUnavailable is set — refusing to run: ${command}.`,
+      };
+    }
+    let approved = false;
+    if (onUnsandboxed) {
+      try { approved = await onUnsandboxed({ command, reason: why, installHint: decision.installHint }); }
+      catch { approved = false; }
+    }
+    if (!approved) {
+      const hint = decision.installHint ? ` ${decision.installHint}` : '';
+      return {
+        run: false, sandbox: 'unavailable', hard: false, reason: why, installHint: decision.installHint,
+        message: `OS sandbox unavailable (${why}); refused to run unsandboxed without human approval: ${command}.${hint} To run without a sandbox, a human can set sandbox.mode "off" in config or pass --dangerously-skip-permissions.`,
+      };
+    }
+    // Human approved an unsandboxed run — proceed with a plain shell. No jail ⇒
+    // network isolation cannot be enforced, so the command has the host network
+    // (net 'on', reported honestly even if --no-network was requested).
+    return { run: true, file: command, args: [], useShell: true, sandbox: 'unavailable', network: 'on' };
+  }
+
+  // status 'off' — a deliberate human opt-out; run plain (host network).
+  return { run: true, file: command, args: [], useShell: true, sandbox: 'off', network: 'on' };
+}
+
+// ---------------------------------------------------------------------------
+// Status report (/sandbox and `semalt-code sandbox`)
+// ---------------------------------------------------------------------------
+
+function sandboxStatusReport({ getConfig, detection, noNetwork } = {}) {
+  let cfg = {};
+  try { cfg = (getConfig ? getConfig() : {}) || {}; } catch { cfg = {}; }
+  const s = normalizeSandbox(cfg.sandbox);
+  const det = detection || detectSandbox();
+  const network = resolveNetworkMode(s, noNetwork); // 'on' | 'off' (config + --no-network)
+  const lines = ['OS Sandbox (filesystem + binary network isolation for shell commands):'];
+  lines.push(`  mode:               ${s.mode}${s.mode === 'off' ? '  (sandbox disabled by config)' : ''}`);
+  lines.push(`  failIfUnavailable:  ${s.failIfUnavailable}`);
+  lines.push(`  network:            ${network}${network === 'off' ? '  (kernel-level no-network for sandboxed commands)' : ''}`);
+  lines.push(`  platform:           ${det.platform}`);
+  lines.push(`  tool:               ${det.tool || '(none)'}`);
+  lines.push(`  supported:          ${det.supported}`);
+  lines.push(`  available:          ${det.available}`);
+
+  let effective;
+  if (s.mode === 'off') effective = 'OFF (disabled by config)';
+  else if (det.available) effective = `ON (net:${network})`;
+  else effective = s.failIfUnavailable ? 'UNAVAILABLE → shell commands are HARD-BLOCKED (failIfUnavailable)' : 'UNAVAILABLE → shell commands require human approval to run unsandboxed';
+  lines.push(`  effective:          ${effective}`);
+
+  if (network === 'off' && (s.mode === 'off' || !det.available)) {
+    // Honest caveat: no-network is enforced BY the jail; with no active jail there
+    // is nothing to enforce it, so the command would have the host network.
+    lines.push('  note:               no-network requires an active sandbox; with the sandbox off/unavailable the command is NOT network-isolated.');
+  }
+
+  if (!det.available && det.reason) lines.push(`  reason:             ${det.reason}`);
+  if (!det.available && det.installHint) lines.push(`  install:            ${det.installHint}`);
+  lines.push('  scope:              writes confined to the working dir; ~/.semalt-ai, secrets & /etc read-only; network is BINARY (on or kernel-level none) — no host proxy, no domain allowlist, no TLS interception.');
+  return lines.join('\n');
+}
+
+module.exports = {
+  SANDBOX_MODES,
+  normalizeSandbox,
+  protectedPaths,
+  buildSeatbeltPolicy,
+  buildBwrapArgs,
+  detectSandbox,
+  _resetSandboxDetection,
+  wrapCommand,
+  decideSandbox,
+  resolveSandboxedSpawn,
+  sandboxStatusReport,
+};