@vzn/vx 0.0.18 → 0.0.22

package/src/exec/sandbox-runtime.ts

@@ -2,12 +2,12 @@
 // per-task filesystem + network isolation.
 //
 // Design contract:
-//   The caller (executeCachedTask) computes the exact allowRead /
-//   allowWrite paths from the task's declared inputs + outputs + sandbox
-//   block. This module adds nothing implicit — no /tmp, no node_modules,
-//   no project dir. If a task needs them, the user declares them in
-//   their sandbox config. That gives users a complete view of what each
-//   task can touch from a single vx.config.ts file.
+//   The caller (sandbox-request.ts) hands over the task's own
+//   `sandbox.allow` block plus two baselines: the `node_modules` reads a
+//   task's dependencies need, and the workspace-root deny anchor. Writes
+//   are the task's `allow.write` alone — nothing is derived from `cache`.
+//   This module adds nothing implicit on top — no /tmp, no project dir —
+//   so what a task may touch is its vx.config.ts plus those baselines.
 //
 // Network is opt-in per task. By default the sandbox blocks all outbound
 // traffic; tasks that need it set `sandbox.network: true`.
@@ -25,20 +25,45 @@
 
 import path from 'node:path'
 import os from 'node:os'
-import { realpathSync } from 'node:fs'
-import { unlink } from 'node:fs/promises'
-import type { SandboxConfig, SandboxNetworkConfig } from '../config.js'
+import { mkdirSync, readlinkSync, realpathSync, rmSync, unlinkSync } from 'node:fs'
+import { mkdir, unlink } from 'node:fs/promises'
+import type { SandboxConfig } from '../config.js'
 import {
   armTimeout,
   drainOrAbort,
+  POST_EXIT_CUT_LINE,
   shellQuote,
   signalExitCode,
+  spawnFailureText,
   streamToString,
   resourceUsageToCpuRss,
   type CaptureConfig,
   type RunResult,
 } from './runner.js'
-import { xxh3hex } from '../util/index.js'
+import {
+  executablePath,
+  grantPrefix,
+  isTmpdirRefusal,
+  TMPDIR_HINT,
+  UserError,
+  xxh3hex,
+} from '../util/index.js'
+import { buildCustomConfig } from './sandbox-binds.js'
+import {
+  isMountableLiteral,
+  localBindingOn,
+  MOUNT_WILDCARDS,
+  toRealPath,
+  unique,
+} from './sandbox-paths.js'
+import { parseStraceViolations, reportableViolations } from './sandbox-violations.js'
+import {
+  closeSignalChannel,
+  killTree,
+  releaseGroup,
+  signalThrough,
+  spawnGuarded,
+} from './kill-tree.js'
 
 type SrtModule = typeof import('@anthropic-ai/sandbox-runtime')
 let srtPromise: Promise<SrtModule> | undefined
@@ -54,65 +79,180 @@ export interface SandboxAvailability {
   reason: string
 }
 
-let availabilityCache: SandboxAvailability | undefined
+/** One verdict per mode: the wrapper the probe runs differs by mode. */
+const availabilityCache = new Map<'secure' | 'weaker', SandboxAvailability>()
 
 /**
- * Probe whether SRT can sandbox on this host. Memoized — the binary
- * presence + platform check doesn't change within a process.
+ * Probe whether SRT can sandbox on this host. Memoized per mode — the
+ * binary presence + platform check doesn't change within a process.
  *
  * In addition to SRT's own `checkDependencies` (which only verifies
- * binary presence on PATH), this runs a minimal bwrap invocation on
- * Linux to catch the "bwrap installed but unprivileged user namespaces
- * blocked by AppArmor / sysctl" case that's the default on stock
- * Ubuntu 24.04. Without this real-execution probe, the unavailability
- * surfaces only at the first task spawn, deep inside the orchestrator.
- */
-export async function probeSandbox(): Promise<SandboxAvailability> {
-  if (availabilityCache) return availabilityCache
+ * binary presence on PATH), this runs ONE sandboxed `true` on Linux
+ * through SRT's own wrapper: bwrap with the runtime's namespace flags
+ * plus its vendored seccomp helper, which creates a NESTED user
+ * namespace. A bare `bwrap … /bin/true` (the probe until 2026-09-04)
+ * passed on hosts where every task then failed — as root inside a
+ * container, the helper's `write /proc/self/uid_map` is EPERM under
+ * `--cap-drop ALL`. Without this real-execution probe the
+ * unavailability surfaces only at the first task spawn, deep inside the
+ * orchestrator, as exit 1 with the helper's line in the task's stderr.
+ *
+ * `weakerNested` probes with `enableWeakerNestedSandbox`; the caller
+ * passes it only when EVERY sandboxed task opts in, since the secure
+ * wrapper is what any other task will run under.
+ *
+ * On Linux the probe INITIALIZES SRT (idempotent — `run()` initializes
+ * right after anyway), and SRT's proxy sockets then keep the event loop
+ * alive: a standalone caller must `resetSandbox()` or exit. CI's
+ * diagnostic `bun -e` step sat on this for its whole 10-minute timeout
+ * (2026-09-04).
+ */
+export async function probeSandbox(opts?: {
+  weakerNested?: boolean
+}): Promise<SandboxAvailability> {
+  const mode = opts?.weakerNested === true ? 'weaker' : 'secure'
+  const cached = availabilityCache.get(mode)
+  if (cached) return cached
+  const verdict = await probeUncached(mode === 'weaker')
+  availabilityCache.set(mode, verdict)
+  return verdict
+}
+
+async function probeUncached(weakerNested: boolean): Promise<SandboxAvailability> {
   const { SandboxManager } = await loadSrt()
   if (!SandboxManager.isSupportedPlatform()) {
-    availabilityCache = { available: false, reason: `platform ${process.platform} not supported` }
-    return availabilityCache
+    return { available: false, reason: `platform ${process.platform} not supported` }
   }
   const deps = SandboxManager.checkDependencies()
-  if (deps.errors.length > 0) {
-    availabilityCache = { available: false, reason: deps.errors.join('; ') }
-    return availabilityCache
-  }
-  // Linux only: real-execution probe. Run `bwrap` with the minimal
-  // user-namespace invocation it'd attempt for a sandboxed task; if
-  // the kernel rejects (AppArmor / sysctl), surface that here.
+  if (deps.errors.length > 0) return { available: false, reason: dependencyReason(deps.errors) }
+  const long = socketPathRefusal()
+  if (long !== undefined) return { available: false, reason: long }
   if (process.platform === 'linux') {
-    const ok = await tryBwrapOnce()
-    if (!ok.available) {
-      availabilityCache = ok
-      return availabilityCache
+    await initSandbox()
+    return trySandboxedTrue(SandboxManager, weakerNested)
+  }
+  return applyPolicyHere()
+}
+
+/**
+ * Can a seatbelt policy be applied in THIS process at all?
+ *
+ * Not if one already is: macOS refuses `sandbox_apply` inside a sandbox,
+ * at any permission level — an inner profile of `(allow default)` still
+ * dies `sandbox_apply: Operation not permitted` (exit 71, measured
+ * 2026-09-05). No grant fixes it, so the honest verdict is "unavailable",
+ * which is what stops a sandboxed task from spawning tasks that report
+ * a sandbox they never got. Answering `available: true` here is how a
+ * suite that exercises the sandbox came to fail sixteen ways at once.
+ *
+ * The probe costs one `/usr/bin/true` and is memoized with the rest.
+ */
+function applyPolicyHere(): SandboxAvailability {
+  const proc = Bun.spawnSync({
+    cmd: ['sandbox-exec', '-p', '(version 1)(allow default)', '/usr/bin/true'],
+    stdout: 'ignore',
+    stderr: 'pipe',
+  })
+  if (proc.exitCode === 0) return { available: true, reason: '' }
+  const stderr = proc.stderr.toString().trim()
+  if (stderr.includes('sandbox_apply')) {
+    return {
+      available: false,
+      reason:
+        'this process is already sandboxed and macOS cannot nest one — a task that ' +
+        'itself sandboxes has to run without `exec.sandbox` of its own',
     }
   }
-  availabilityCache = { available: true, reason: '' }
-  return availabilityCache
+  return { available: false, reason: `sandbox-exec failed: ${stderr || `exit ${proc.exitCode}`}` }
 }
 
-async function tryBwrapOnce(): Promise<SandboxAvailability> {
+/**
+ * Why the probe's sandboxed `true` failed, in the user's terms. The hint
+ * names the CONFIG field (`exec.sandbox.weakerWhenNested`), not the
+ * runtime option it maps to — a user who followed the runtime's name into
+ * their config met the loader's unknown-field refusal instead of a fix
+ * (`tests/sandbox-hint.test.ts` pins every field the hint names against
+ * the loader).
+ */
+export function unavailableReason(exitCode: number | null, stderr: string): string {
+  const hint = stderr.includes('uid_map')
+    ? " — the runtime's seccomp helper cannot create its nested user namespace here (root inside a container, or a kernel that forbids nested user namespaces): run as a non-root user, or set `sandbox.weakerWhenNested: true` on every sandboxed task"
+    : ''
+  return `a sandboxed \`true\` failed (exit ${exitCode}): ${stderr.slice(0, 200)}${hint}`
+}
+
+async function trySandboxedTrue(
+  SandboxManager: SrtModule['SandboxManager'],
+  weakerNested: boolean,
+): Promise<SandboxAvailability> {
   try {
-    const proc = Bun.spawn(
-      ['bwrap', '--ro-bind', '/', '/', '--proc', '/proc', '--dev', '/dev', '/bin/true'],
-      { stdout: 'pipe', stderr: 'pipe', stdin: 'ignore' },
+    const wrapped = await SandboxManager.wrapWithSandbox(
+      'true',
+      undefined,
+      weakerNested ? { enableWeakerNestedSandbox: true } : undefined,
     )
-    const stderr = await new Response(proc.stderr).text()
+    const proc = Bun.spawn([executablePath('sh'), '-c', wrapped], {
+      argv0: 'sh',
+      stdout: 'ignore',
+      stderr: 'pipe',
+      stdin: 'ignore',
+    })
+    const stderr = (await new Response(proc.stderr).text()).trim()
     await proc.exited
-    if (proc.exitCode !== 0) {
-      return {
-        available: false,
-        reason: `bwrap probe failed (exit ${proc.exitCode}): ${stderr.trim().slice(0, 200)}`,
-      }
-    }
-    return { available: true, reason: '' }
+    if (proc.exitCode === 0) return { available: true, reason: '' }
+    return { available: false, reason: unavailableReason(proc.exitCode, stderr) }
   } catch (err) {
-    return { available: false, reason: `bwrap probe threw: ${(err as Error).message}` }
+    return { available: false, reason: thrownReason(err, 'sandbox probe threw') }
   }
 }
 
+/**
+ * The runtime's own dependency check names what is missing ("ripgrep (rg)
+ * not found") and nothing else. On Linux it needs three binaries — bwrap
+ * for the namespaces, socat for the network bridge, ripgrep to expand its
+ * mandatory deny globs — and the docs named two of them until a minimal
+ * image with the two failed on the third (2026-09-16). Name the set and
+ * the install.
+ */
+export function dependencyReason(errors: readonly string[]): string {
+  const need =
+    process.platform === 'linux'
+      ? 'the sandbox runtime needs bubblewrap (bwrap), socat and ripgrep (rg) on PATH'
+      : 'the sandbox runtime is missing a dependency'
+  return `${need}: ${errors.join('; ')} — install it (Linux: apt install bubblewrap socat ripgrep, or the same names in your package manager) and re-run`
+}
+
+/**
+ * The runtime listens on `<tmpdir>/srt-mux-<pid>-<seq>.sock`, and a unix
+ * socket path has a hard length (`sun_path`: 108 bytes on Linux, 104 on
+ * macOS, one of them the NUL). Past it the runtime says "ENAMETOOLONG …
+ * listen" on macOS and "Failed to create bridge sockets after 5 attempts"
+ * on Linux (its retry loop swallows the code), neither naming the
+ * directory (2026-09-16). Checked up front, with room for the sequence.
+ */
+export function socketPathRefusal(tmpdir = os.tmpdir()): string | undefined {
+  const sample = path.join(tmpdir, `srt-mux-${process.pid}-zzz.sock`)
+  const limit = process.platform === 'darwin' ? 103 : 107
+  const length = Buffer.byteLength(sample)
+  if (length <= limit) return undefined
+  return `the sandbox runtime listens on a unix socket under the temp directory, and ${sample} is ${length} bytes where the OS allows ${limit} — point TMPDIR at a shorter path`
+}
+
+/**
+ * A throw from the runtime itself, in the user's terms. Its own temp files
+ * (the observer directory, the bridge sockets, the strace log) live under
+ * `os.tmpdir()`, so a temp directory that is missing or not writable
+ * failed a sandboxed task with a path and no knob ("EACCES … mkdtemp
+ * '/tmp/probe-ro/srt-obs-…'", a minimal image, 2026-09-16).
+ */
+export function thrownReason(err: unknown, what = ''): string {
+  const message = err instanceof Error ? err.message : String(err)
+  if (isTmpdirRefusal(err)) {
+    return `the sandbox runtime needs a writable temp directory and ${os.tmpdir()} is not one (${message}) — ${TMPDIR_HINT}`
+  }
+  return what === '' ? message : `${what}: ${message}`
+}
+
 /**
  * Default `ignoreViolations` we install in the SRT global config.
  * These are well-known macOS shell-startup probes that SRT's own
@@ -123,7 +263,7 @@ async function tryBwrapOnce(): Promise<SandboxAvailability> {
  *
  * Format mirrors SRT's: `'*'` is a wildcard pattern; entries in the
  * array are substring-matched against the violation details line.
- * Users can ADD to this via per-task `sandbox.ignoreViolations`;
+ * Users can ADD to this via per-task `sandbox.ignore`;
  * those are applied at violation read-back time, on top of the
  * defaults installed here.
  */
@@ -133,6 +273,100 @@ const DEFAULT_IGNORE_VIOLATIONS: Record<string, string[]> = {
   ],
 }
 
+/**
+ * The temp directory SRT hands every sandboxed task. It overrides `TMPDIR`
+ * so temp-file writers land somewhere its filesystem policy already allows,
+ * and it deliberately does NOT create the directory — its own comment says
+ * "/tmp/claude may not exist". Nobody else does either, so on any machine
+ * that is not Claude Code's own, every sandboxed task that writes a temp
+ * file died with ENOENT: this repo's `bun build --compile` under
+ * a sandboxed `bun build --compile` reported only `error: An unknown error occurred
+ * (Unexpected)` (2026-09-04). Resolution mirrors SRT's exactly.
+ */
+function sandboxTmpdir(): string {
+  // `process.env`, not `Bun.env`: a caller that REPLACES the env object
+  // (two tests here do, and an embedder may) leaves `Bun.env` pointing at
+  // the original, so a late assignment would be invisible.
+  const named = process.env['CLAUDE_CODE_TMPDIR'] ?? process.env['CLAUDE_TMPDIR']
+  return named !== undefined && named !== '' ? named : '/tmp/claude'
+}
+
+/**
+ * The temp files of tasks still running: strace logs and port-bridge
+ * sockets. A signal exit is `process.exit` (orchestrator/signals.ts),
+ * which never reaches a task's own unlink, so a Ctrl-C left one log per
+ * sandboxed task in the temp dir (item 848); the process's `exit` event
+ * removes what is still listed.
+ */
+const liveTempFiles = new Set<string>()
+let tempExitHooked = false
+function unlinkOnExit(file: string): void {
+  liveTempFiles.add(file)
+  if (tempExitHooked) return
+  tempExitHooked = true
+  process.on('exit', () => {
+    for (const f of liveTempFiles) {
+      try {
+        unlinkSync(f)
+      } catch {
+        // never written, or gone
+      }
+    }
+  })
+}
+
+/**
+ * A task's own temp directory, `TMPDIR` inside its sandbox. SRT points
+ * every sandboxed task at ONE host directory (`sandboxTmpdir`), bound
+ * read-write and kept across runs, so a file one task wrote there was
+ * another's undeclared input: a cached reader replayed the first value it
+ * saw after the writer changed it (item 965). Created for the task, removed
+ * with its bridges at its end (and at exit, as the logs are); a `kill -9`
+ * leaves it. No sweep by the owner's pid: a nested vx sees another pid
+ * namespace, where the outer vx's pid reads as dead, and a sweep there
+ * removed the outer task's own TMPDIR mid-run (the gate, item 965). The shared
+ * directory itself stays writable, since SRT's policy grants it: a command
+ * that names it outright still reaches it.
+ */
+function taskTmpdir(tag: string): string {
+  return path.join(sandboxTmpdir(), `vx-task-${process.pid}-${tag}`)
+}
+
+const liveTaskTmpdirs = new Set<string>()
+let tmpdirExitHooked = false
+function trackTaskTmpdir(dir: string): void {
+  liveTaskTmpdirs.add(dir)
+  if (tmpdirExitHooked) return
+  tmpdirExitHooked = true
+  process.on('exit', () => {
+    for (const d of liveTaskTmpdirs) rmSync(d, { recursive: true, force: true })
+  })
+}
+
+/** Whether SRT is up in this process — set by `initSandbox`, cleared by `resetSandbox`. */
+let srtUp = false
+
+/**
+ * SRT listens on `<tmpdir>/srt-mux-<pid>-<seq>.sock`, seq from 0, and a
+ * killed run leaves those files behind; when the kernel hands the pid to a
+ * later vx, its first listen meets EADDRINUSE and every sandboxed task
+ * fails (255 of them after a stopped gate, 2026-09-16). A file carrying
+ * OUR pid before SRT is up can only be a dead process's, so unlink the
+ * contiguous run from seq 0 — a stat per file, no directory scan (a 7,000
+ * entry /tmp reads in 9 ms; this is microseconds).
+ */
+async function unlinkStaleMuxSockets(): Promise<void> {
+  for (let seq = 0; seq < 64; seq++) {
+    const stale = path.join(os.tmpdir(), `srt-mux-${process.pid}-${seq.toString(36)}.sock`)
+    try {
+      await unlink(stale)
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return
+      throw err
+    }
+  }
+}
+
 /**
  * One-time SRT initialization per orchestrator run. Starts the proxy
  * servers + (on macOS) the violation log monitor. Safe to call repeatedly
@@ -141,26 +375,95 @@ const DEFAULT_IGNORE_VIOLATIONS: Record<string, string[]> = {
  * The base config sets network to "block everything" (empty allowedDomains).
  * Per-task wrapping passes a customConfig that re-enables network for
  * tasks with `sandbox.network: true`.
+ *
+ * @param opts.allowedDomains every domain any sandboxed task in this run
+ * declared. SRT's filtering proxy is per-RUN and reads its allowlist from
+ * this call, never from the per-task config, so the union is the only
+ * place a domain list can take effect. Per-task precision survives where
+ * it matters: a task that declared none is never handed the proxy port.
  */
-export async function initSandbox(): Promise<void> {
+export async function initSandbox(opts?: {
+  allowedDomains?: readonly string[]
+  /**
+   * Lift SRT's seccomp block on `socket(AF_UNIX)` for every sandboxed
+   * task of the run (Linux; per-run like the proxy allowlist, since SRT
+   * reads it at `initialize()` only). Armed when any task declares
+   * `unixSockets` or a `localBinding` port list — the port bridge is a
+   * unix socket the task's side has to create.
+   */
+  allowAllUnixSockets?: boolean
+}): Promise<void> {
+  // A reset a server's exit started unawaited: a watch cycle stops its
+  // server and starts its run at once, and an init under that reset
+  // found SRT up, hot-reloaded it, and had it torn down after (item 884).
+  await resetting
+  // Before SRT starts, so the very first task already has one.
+  await mkdir(sandboxTmpdir(), { recursive: true })
   const { SandboxManager } = await loadSrt()
-  await SandboxManager.initialize(
-    {
-      network: { allowedDomains: [], deniedDomains: [] },
-      filesystem: { denyRead: [], allowWrite: [], denyWrite: [] },
-      ignoreViolations: DEFAULT_IGNORE_VIOLATIONS,
+  const config: Parameters<typeof SandboxManager.initialize>[0] = {
+    network: {
+      allowedDomains: [...(opts?.allowedDomains ?? [])],
+      deniedDomains: [],
+      ...(opts?.allowAllUnixSockets === true ? { allowAllUnixSockets: true } : {}),
     },
+    filesystem: { denyRead: [], allowWrite: [], denyWrite: [] },
+    ignoreViolations: DEFAULT_IGNORE_VIOLATIONS,
+  }
+  if (!srtUp) await unlinkStaleMuxSockets()
+  await SandboxManager.initialize(
+    config,
     undefined,
     // enableLogMonitor — macOS-only; populates the SandboxViolationStore.
     true,
   )
+  srtUp = true
+  // `initialize()` returns early once SRT is up, and on Linux the
+  // availability probe brought it up with an EMPTY config before the run's
+  // own call — so the run's allowlist and unix-socket allowance never
+  // reached it (found 2026-09-10 by the port bridge: the task's side died
+  // on `socket(AF_UNIX)` with the flag set). `updateConfig` is SRT's hot
+  // reload of exactly these fields; the proxy and the wrapper read them
+  // through getters, so the run's config is what every task sees.
+  SandboxManager.updateConfig(config)
 }
 
+/**
+ * The tags of sandboxed servers still running (`wrapSandboxedCommand`'s
+ * `server`). A run resets the sandbox at its end, and a foreground
+ * `vx run dev` or a `vx watch` holds its servers past that: the reset
+ * released their host bridges and SRT's proxies, and a server's port went
+ * dark ~40 ms after the summary (item 882). While one runs, the reset
+ * releases only the bridges no server owns and waits for the last
+ * server's `releaseBridges`.
+ */
+const liveServers = new Set<string>()
+let resetDeferred = false
+/** The reset in flight, settled either way; `initSandbox` waits for it. */
+let resetting: Promise<void> | undefined
+
 export async function resetSandbox(): Promise<void> {
-  const { SandboxManager } = await loadSrt()
-  await SandboxManager.reset()
-  availabilityCache = undefined
-  straceAvailableCache = undefined
+  for (const tag of [...hostBridges.keys()]) if (!liveServers.has(tag)) releaseBridges(tag)
+  if (liveServers.size > 0) {
+    resetDeferred = true
+    return
+  }
+  resetDeferred = false
+  const reset = (async () => {
+    const { SandboxManager } = await loadSrt()
+    await SandboxManager.reset()
+    srtUp = false
+    availabilityCache.clear()
+    straceAvailableCache = undefined
+  })()
+  const settled = reset.then(
+    () => {},
+    () => {},
+  )
+  resetting = settled
+  void settled.then(() => {
+    if (resetting === settled) resetting = undefined
+  })
+  await reset
 }
 
 export interface SandboxedRunArgs {
@@ -176,25 +479,27 @@ export interface SandboxedRunArgs {
   timeoutMs?: number
   /** See `CaptureConfig` — which streams are retained on the result. */
   capture?: CaptureConfig
-  /** See `ExecuteSandbox.settleOnCleanExit` — pay the macOS settle window
-   *  even on a 0-exit, because an empty store will be read as proof. */
-  settleOnCleanExit?: boolean
   /**
-   * Baseline reads — paths the sandbox unconditionally allows. The
-   * caller builds this from resolved `cache.inputs.files`.
+   * Baseline reads — paths the sandbox allows beside the task's own
+   * `allow.read`. Core passes the project's and the root's
+   * `node_modules` and the workspace dependencies linked from them
+   * (sandbox-request.ts); nothing is derived from `cache`.
    */
   baseAllowRead: readonly string[]
-  /**
-   * Baseline writes — paths the sandbox unconditionally allows for
-   * writes. Built from the static prefix of `cache.outputs.files`.
-   */
-  baseAllowWrite: readonly string[]
   /**
    * Read-deny anchor. Combined with allowRead it produces the effective
    * deny set: anything under one of these paths that isn't in allowRead
    * is forbidden. Pass `[workspaceRoot]` to enforce project boundaries.
    */
   baseDenyRead: readonly string[]
+  /**
+   * Only denials on a path under this directory are reported. A denial
+   * outside it is still ENFORCED — the task cannot leave its project — but
+   * that is the wall doing its job, not a finding to fail a run over.
+   */
+  readonly reportWithin: string
+  /** Canonical directories whose denials are reported too (`ExecuteSandbox.reportLinked`). */
+  readonly reportLinked: readonly string[]
   /**
    * User-declared sandbox block (after path-resolution). Path lists are
    * unioned with the baselines; bool/object fields fall through to SRT.
@@ -208,33 +513,25 @@ export interface SandboxedRunArgs {
  * but every string in a path list is guaranteed absolute.
  */
 export interface ResolvedSandboxConfig {
+  /** Readable path prefixes, absolute. */
   allowRead: readonly string[]
+  /** Writable path prefixes, absolute. */
   allowWrite: readonly string[]
-  allowGitConfig?: boolean
-  network?: boolean | SandboxNetworkConfig
-  allowPty?: boolean
-  enableWeakerNestedSandbox?: boolean
-  enableWeakerNetworkIsolation?: boolean
-  ignoreViolations?: Record<string, string[]>
-}
-
-/**
- * Canonicalize a path with realpath, tolerating paths that don't exist
- * yet: resolve the longest existing ancestor and re-append the rest.
- *
- * Why: the sandbox policy matches on canonical paths (macOS seatbelt
- * evaluates real vnode paths), and SRT's own normalization refuses to
- * canonicalize bare symlinked roots like `/tmp` → `/private/tmp` (its
- * boundary check only whitelists `/tmp/<child>` forms). Without this,
- * `allowWrite: ['/tmp']` silently never matches on macOS.
- */
-function toRealPath(p: string): string {
-  try {
-    return realpathSync(p)
-  } catch {
-    const parent = path.dirname(p)
-    if (parent === p) return p
-    return path.join(toRealPath(parent), path.basename(p))
+  network?: true | readonly string[]
+  denyNetwork?: readonly string[]
+  systemInfo?: readonly string[]
+  unixSockets?: true | readonly string[]
+  localBinding?: boolean | readonly number[]
+  machLookup?: readonly string[]
+  pty?: boolean
+  gitConfig?: boolean
+  weakerWhenNested?: boolean
+  weakerNetworkIsolation?: boolean
+  ignore?: {
+    read?: readonly string[]
+    write?: readonly string[]
+    systemInfo?: readonly string[]
+    network?: readonly string[]
   }
 }
 
@@ -242,7 +539,7 @@ function toRealPath(p: string): string {
  * Canonical form of every path the sandbox policy is expressed in.
  *
  * `resolveSandboxConfig` already canonicalizes the USER's paths; the
- * orchestrator-supplied baselines (resolved inputs, output prefixes, the
+ * orchestrator-supplied baselines (the `node_modules` reads and the
  * workspace-root deny anchor) arrived raw, so a workspace reached through a
  * symlink expressed HALF its policy in real paths and half in link paths.
  * bwrap then died mounting the link path inside its new root
@@ -250,20 +547,63 @@ function toRealPath(p: string): string {
  * whatever the config, with an error naming an internal path the user has no
  * way to act on. Canonicalizing here is what makes the two halves agree.
  */
-function canonicalBaselines(args: SandboxedRunArgs): {
+interface CanonicalBaselines {
   allowRead: string[]
-  allowWrite: string[]
   denyRead: string[]
   cwd: string
-} {
+}
+
+function canonicalBaselines(
+  args: Pick<SandboxedRunArgs, 'baseAllowRead' | 'baseDenyRead' | 'cwd'>,
+): CanonicalBaselines {
   return {
     allowRead: args.baseAllowRead.map(toRealPath),
-    allowWrite: args.baseAllowWrite.map(toRealPath),
     denyRead: args.baseDenyRead.map(toRealPath),
     cwd: toRealPath(args.cwd),
   }
 }
 
+/**
+ * A write grant that names a path in the project must BIND one there. The
+ * grant was realpath'd, so `out.txt -> ../b/src/x` (committed, or planted
+ * by the task's own previous run) bound project b's directory writable,
+ * and the task wrote into a sibling with exit 0 (item 1003). A read grant
+ * may resolve out through a link (`node_modules` into the store) and is
+ * not judged here; a grant spelled outside the project is the user's own.
+ */
+function assertWriteStaysHome(grant: string, real: string, projectDir: string): void {
+  if (grant.startsWith('~') || path.isAbsolute(grant)) return
+  const lexical = path.resolve(projectDir, grant)
+  const inside = (p: string, dir: string): boolean =>
+    p === dir || p.startsWith(dir.endsWith(path.sep) ? dir : dir + path.sep)
+  if (!inside(lexical, projectDir)) return
+  const home = toRealPath(projectDir)
+  // `toRealPath` stops at a DANGLING link and keeps its own path, which is
+  // inside; the link's target is where a write through it would land.
+  const target = throughLinks(real)
+  if (inside(real, home) && inside(target, home)) return
+  throw new UserError(
+    `exec.sandbox.allow.write: "${grant}" resolves through a symlink to ${inside(real, home) ? target : real}, outside the ` +
+      `project — a write grant binds the path it names in the project, and vx does not follow a ` +
+      `link out of it. Remove the link, or grant the target by its own path.`,
+  )
+}
+
+/** Where `p` lands through every link on it, a dangling last one included. */
+function throughLinks(p: string, hops = 0): string {
+  if (hops > 40) return p
+  try {
+    return realpathSync(p)
+  } catch {
+    try {
+      return throughLinks(path.resolve(path.dirname(p), readlinkSync(p)), hops + 1)
+    } catch {
+      const parent = path.dirname(p)
+      return parent === p ? p : path.join(throughLinks(parent, hops + 1), path.basename(p))
+    }
+  }
+}
+
 /**
  * Convert a user-facing `SandboxConfig` (paths may be relative / tilde)
  * into a `ResolvedSandboxConfig` (all paths absolute + canonical) for a
@@ -279,20 +619,42 @@ export function resolveSandboxConfig(
     if (path.isAbsolute(p)) return toRealPath(p)
     return toRealPath(path.resolve(projectDir, p))
   }
+  const a = cfg.allow ?? {}
   const r: ResolvedSandboxConfig = {
-    allowRead: (cfg.allowRead ?? []).map(resolve),
-    allowWrite: (cfg.allowWrite ?? []).map(resolve),
+    allowRead: expandGrants((a.read ?? []).map(resolve), 'read'),
+    allowWrite: expandGrants(
+      (a.write ?? []).map((p) => {
+        const real = resolve(p)
+        assertWriteStaysHome(p, real, projectDir)
+        return real
+      }),
+      'write',
+    ),
   }
-  if (cfg.allowGitConfig !== undefined) r.allowGitConfig = cfg.allowGitConfig
-  if (cfg.network !== undefined) r.network = cfg.network
-  if (cfg.allowPty !== undefined) r.allowPty = cfg.allowPty
-  if (cfg.enableWeakerNestedSandbox !== undefined) {
-    r.enableWeakerNestedSandbox = cfg.enableWeakerNestedSandbox
+  if (a.network !== undefined) r.network = a.network
+  if (cfg.deny?.network !== undefined) r.denyNetwork = cfg.deny.network
+  if (a.systemInfo !== undefined) r.systemInfo = a.systemInfo
+  if (a.unixSockets !== undefined) r.unixSockets = a.unixSockets
+  if (a.localBinding !== undefined) r.localBinding = a.localBinding
+  if (a.machLookup !== undefined) r.machLookup = a.machLookup
+  if (a.pty !== undefined) r.pty = a.pty
+  if (a.gitConfig !== undefined) r.gitConfig = a.gitConfig
+  if (cfg.weakerWhenNested !== undefined) r.weakerWhenNested = cfg.weakerWhenNested
+  if (cfg.weakerNetworkIsolation !== undefined) {
+    r.weakerNetworkIsolation = cfg.weakerNetworkIsolation
   }
-  if (cfg.enableWeakerNetworkIsolation !== undefined) {
-    r.enableWeakerNetworkIsolation = cfg.enableWeakerNetworkIsolation
+  if (cfg.ignore !== undefined) {
+    // Relative patterns anchor at the project dir; absolute and `~` ones
+    // are taken as written. NOT realpath'd — a pattern is not a path.
+    const anchor = (pat: string): string =>
+      pat.startsWith('~') || path.isAbsolute(pat) ? pat : path.join(projectDir, pat)
+    r.ignore = {
+      ...(cfg.ignore.read ? { read: cfg.ignore.read.map(anchor) } : {}),
+      ...(cfg.ignore.write ? { write: cfg.ignore.write.map(anchor) } : {}),
+      ...(cfg.ignore.systemInfo ? { systemInfo: [...cfg.ignore.systemInfo] } : {}),
+      ...(cfg.ignore.network ? { network: [...(cfg.ignore.network as string[])] } : {}),
+    }
   }
-  if (cfg.ignoreViolations !== undefined) r.ignoreViolations = cfg.ignoreViolations
   return r
 }
 
@@ -300,6 +662,17 @@ export interface SandboxViolation {
   /** Raw log line from SRT. Format differs between macOS / Linux. */
   line: string
   timestamp: Date
+  /**
+   * What the denial named, and which `ignore` lists could silence it —
+   * filled in by whichever platform produced the record. The filters read
+   * these instead of re-parsing a line whose shape depends on the OS: a
+   * seatbelt `deny(1) file-read-data /x` and a strace
+   * `openat(../x) = -1 ENOENT  [/x]` say the same thing.
+   */
+  target?: string
+  /** Absolute, when `target` is a path at all. */
+  path?: string
+  ignorable?: readonly ('read' | 'write' | 'network' | 'systemInfo')[]
 }
 
 export interface SandboxedRunResult extends RunResult {
@@ -308,29 +681,306 @@ export interface SandboxedRunResult extends RunResult {
 }
 
 /**
- * Run a single task wrapped in the sandbox. Caller must have called
- * `initSandbox()` first.
- *
- * Violations are matched by a unique per-task command prefix — SRT's
- * `getViolationsForCommand` keys by base64 of the first 100 chars, so
- * two tasks running the same underlying command (e.g. parallel `tsc`
- * across packages) would otherwise collide. We prepend `: '<tag>';`
- * (shell no-op) to make every command's first 100 chars unique.
+ * The shell that gives a sandboxed task its OWN `JAVA_TOOL_OPTIONS`. When
+ * SRT restricts the network it sets the variable to its proxy agent's flag
+ * composed with VX'S value (`process.env`, read inside the wrap), over the
+ * one vx gave the task: a host value no layer passes reached the task, out
+ * of its key, and a changed host value replayed the old output; a task's
+ * own `define` never arrived (item 995). Where SRT left the variable alone
+ * it already holds the task's value and this is a no-op; elsewhere the
+ * host's value is cut out and the task's appended to what SRT added.
  */
-export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRunResult> {
+function javaToolOptionsFix(host: string | undefined, task: string | undefined): string {
+  // The same value both sides (a task that passes the host's through, or
+  // neither has one): SRT's composition is already the task's own, and a
+  // prefix quoting the value twice would only lengthen every command
+  // (item 1007).
+  if ((host ?? '') === (task ?? '')) return ''
+  const cut = host
+    ? `__vx_h=${shellQuote(host)}; case "$__vx_j" in *"$__vx_h"*) __vx_j="\${__vx_j%%"$__vx_h"*}\${__vx_j#*"$__vx_h"}";; esac; `
+    : ''
+  const add = task ? `__vx_j="$__vx_j $__vx_t"; ` : ''
+  return (
+    `__vx_t=${shellQuote(task ?? '')}; __vx_j=\${JAVA_TOOL_OPTIONS-}; ` +
+    `if [ "$__vx_j" != "$__vx_t" ]; then ${cut}${add}` +
+    `case "$__vx_j" in *[![:space:]]*) export JAVA_TOOL_OPTIONS="$__vx_j";; *) unset JAVA_TOOL_OPTIONS;; esac; fi; ` +
+    `unset __vx_j __vx_h __vx_t; `
+  )
+}
+
+/**
+ * The sandboxed form of a command: SRT's wrapper over the tagged command,
+ * with vx's own seatbelt rules appended on macOS. This is the ENFORCEMENT
+ * half of `runSandboxed`, shared with persistent tasks — a dev server is
+ * spawned through it and never exits while the run watches, so it gets
+ * the same walls and no violation report (reporting reads the trace after
+ * exit). Returns the wrapped command and the tag the store keys by.
+ */
+export async function wrapSandboxedCommand(
+  args: Pick<SandboxedRunArgs, 'command' | 'cwd' | 'forwardArgs' | 'config' | 'env'> &
+    Pick<SandboxedRunArgs, 'baseAllowRead' | 'baseDenyRead'> & {
+      /** A persistent server: the sandbox outlives a run's reset until `releaseBridges(tag)`. */
+      server?: boolean
+    },
+): Promise<{
+  wrapped: string
+  tag: string
+  taggedCommand: string
+  baselines: CanonicalBaselines
+  /** The command reads its polite signals off fd 3: spawn it with one and `signalThrough` it. */
+  forwardsSignals: boolean
+}> {
   const { SandboxManager } = await loadSrt()
-  const start = Date.now()
   const userCommand =
     args.forwardArgs && args.forwardArgs.length > 0
       ? args.command + ' ' + args.forwardArgs.map(shellQuote).join(' ')
       : args.command
 
   const tag = xxh3hex(`${args.cwd}|${userCommand}|${process.hrtime.bigint()}`).slice(0, 16)
-  const taggedCommand = `: 'vx-${tag}'; ${userCommand}`
+  const tmp = taskTmpdir(tag)
+  mkdirSync(tmp, { recursive: true })
+  trackTaskTmpdir(tmp)
+  // After the tag: SRT keys violations by the command's first 100 chars.
+  const inTmp = `export TMPDIR=${shellQuote(tmp)}; ${javaToolOptionsFix(
+    process.env['JAVA_TOOL_OPTIONS'],
+    args.env['JAVA_TOOL_OPTIONS'],
+  )}${userCommand}`
+  const taggedCommand = `: 'vx-${tag}'; ${inTmp}`
 
   const baselines = canonicalBaselines(args)
   const customConfig = buildCustomConfig(args, baselines)
-  const wrapped = await SandboxManager.wrapWithSandbox(taggedCommand, undefined, customConfig)
+  // Linux: the ports a list grants are bridged out of the task's network
+  // namespace. The task's side of each bridge is a socat in front of the
+  // user command, so it goes INTO the sandboxed command; the host side is
+  // spawned here and released when the task's process ends.
+  const ports = process.platform === 'linux' ? bridgedPorts(args.config) : []
+  const grouped =
+    process.platform === 'linux'
+      ? ownGroupCommand(tag, inTmp)
+      : { command: taggedCommand, forwards: false }
+  const inner =
+    ports.length > 0 ? `${portBridgeInner(ports, tag)} ${grouped.command}` : grouped.command
+  let wrapped = await SandboxManager.wrapWithSandbox(inner, undefined, customConfig)
+  if (process.platform === 'darwin') {
+    const rules = macProfileRules(args.config)
+    if (rules.length > 0) wrapped = injectProfileRules(wrapped, rules)
+  }
+  // Linux: the shell execs bwrap, so bwrap is the spawn itself and its
+  // `--die-with-parent` is keyed to vx. Behind a shell that waited on it,
+  // a `kill -9` of vx left the shell alive, bwrap never heard, and a
+  // sandboxed server and all it forked outlived vx (turborepo#9666). Now
+  // the namespace goes with vx, a `setsid` daemon inside included. A
+  // strace-traced spawn keeps strace as bwrap's parent: that residual is
+  // a one-shot task's, and a persistent one is never traced.
+  if (process.platform === 'linux' && wrapped.startsWith('bwrap ')) wrapped = `exec ${wrapped}`
+  if (args.server === true) liveServers.add(tag)
+  if (ports.length > 0) spawnHostBridges(ports, tag)
+  return { wrapped, tag, taggedCommand, baselines, forwardsSignals: grouped.forwards }
+}
+
+/**
+ * Linux: the user command in a session, and so a process group, of its
+ * own. bwrap's `--new-session` puts the runtime's shells (the proxy
+ * bridges' script, the seccomp step's) in ONE group with the command, and
+ * `kill 0` reaches a group's members across the nested pid namespace: a
+ * command that signalled its own group ended the runtime's shell, bwrap
+ * exited 143 and the namespace's teardown SIGKILLed the rest mid-trap
+ * (item 751). The shell `exec`s `setsid`, which is no group leader here,
+ * so it calls setsid() and execs without a fork: the command keeps the
+ * shell's pid, and its status, a signal death included, is the one the
+ * runtime waits on.
+ *
+ * The same group is where a cancellation lands. vx's group signal reaches
+ * bwrap's monitor, which dies of it, and the namespace goes with SIGKILL,
+ * so vx sends a polite signal's name down fd 3 instead (`signalThrough`)
+ * and a watcher forked before the `exec` signals the group, `$$`, with it
+ * (item 752). The command runs in the foreground because an `&` command
+ * starts with SIGINT ignored, and a shell cannot trap what it inherited
+ * ignored. The command does not get fd 3; a caller that passed none
+ * forwards nothing, silently.
+ *
+ * Tools resolve on vx's own PATH; without `setsid` the command keeps the
+ * shared group, as before, and `forwards` says the channel is not there.
+ */
+function ownGroupCommand(tag: string, userCommand: string): { command: string; forwards: boolean } {
+  // `sh`, as an unsandboxed task runs (`runner.ts`): the command ran under
+  // bash here, so `[[ … ]]`, brace expansion and `echo 'a\tb'` read one
+  // way sandboxed and another unsandboxed or on a remote executor, where
+  // `/bin/sh` is dash (item 964).
+  let sh: string
+  try {
+    sh = executablePath('sh')
+  } catch {
+    return { command: `: 'vx-${tag}'; ${userCommand}`, forwards: false }
+  }
+  let setsid: string
+  try {
+    setsid = executablePath('setsid')
+  } catch {
+    return {
+      command: `: 'vx-${tag}'; exec ${shellQuote(sh)} -c ${shellQuote(userCommand)}`,
+      forwards: false,
+    }
+  }
+  const watch = `{ IFS= read -r s && kill -s "$s" -- "-$$"; } 2>/dev/null <&3 3<&- &`
+  const run = `exec ${shellQuote(setsid)} ${shellQuote(sh)} -c ${shellQuote(userCommand)} 3<&-`
+  return { command: `: 'vx-${tag}'; ${watch} ${run}`, forwards: true }
+}
+
+/** The ports a list grants, deduped; `true` bridges nothing (the host sees no port on Linux). */
+export function bridgedPorts(c: Pick<ResolvedSandboxConfig, 'localBinding'>): number[] {
+  return Array.isArray(c.localBinding) ? [...new Set(c.localBinding)] : []
+}
+
+/** Where a bridge's unix socket lives: the sandbox tmpdir, bound read-write on both sides. */
+export function portBridgeSocket(tag: string, port: number): string {
+  return path.join(sandboxTmpdir(), `vx-port-${tag}-${port}.sock`)
+}
+
+/**
+ * The task's side of the bridge, in front of the user command inside the
+ * sandbox: one socat per port, listening on the unix socket and relaying
+ * into the namespace's loopback. Backgrounded and reaped with the shell,
+ * exactly as SRT starts its own proxy bridges. `unlink-early` clears a
+ * socket a killed task left behind; `>/dev/null` keeps its chatter out
+ * of the task's frame.
+ */
+export function portBridgeInner(ports: readonly number[], tag: string): string {
+  const cmds = ports.map(
+    (p) =>
+      `socat UNIX-LISTEN:${shellQuote(portBridgeSocket(tag, p))},fork,unlink-early TCP:127.0.0.1:${p} >/dev/null 2>&1 &`,
+  )
+  return `${cmds.join(' ')} trap 'kill $(jobs -p) 2>/dev/null' EXIT;`
+}
+
+/**
+ * The host's side: one socat per port, listening on the host's loopback
+ * and connecting into the unix socket per client — with a retry, since a
+ * client can arrive before the task's side has bound the socket.
+ */
+export function portBridgeHostArgv(tag: string, port: number): string[] {
+  return [
+    'socat',
+    `TCP-LISTEN:${port},bind=127.0.0.1,fork,reuseaddr`,
+    `UNIX-CONNECT:${portBridgeSocket(tag, port)},retry=40,interval=0.25`,
+  ]
+}
+
+const hostBridges = new Map<
+  string,
+  { ports: readonly number[]; procs: Array<ReturnType<typeof Bun.spawn>> }
+>()
+
+function spawnHostBridges(ports: readonly number[], tag: string): void {
+  const procs: Array<ReturnType<typeof Bun.spawn>> = []
+  for (const p of ports) {
+    // A spawn failure (no socat on the host) is the task's to report:
+    // its own side dies the same way, in its frame.
+    try {
+      // Guarded, in a group of its own (kill-tree.ts): a plain child of vx
+      // was in no group the guard lists, and a `kill -9` of vx left it
+      // listening on the port under init, where the next run's bridge
+      // could not bind it (item 873).
+      procs.push(
+        spawnGuarded(() =>
+          Bun.spawn(portBridgeHostArgv(tag, p), {
+            stdin: 'ignore',
+            stdout: 'ignore',
+            stderr: 'ignore',
+            detached: true,
+          }),
+        ),
+      )
+    } catch {
+      // see above
+    }
+  }
+  if (procs.length > 0) {
+    hostBridges.set(tag, { ports, procs })
+    for (const p of ports) unlinkOnExit(portBridgeSocket(tag, p))
+  }
+}
+
+/**
+ * Stop the host side of a task's port bridges and remove their sockets;
+ * idempotent. Called once the task's process has exited, so the socat
+ * that listened on each socket is gone with the namespace, and never
+ * unlinked it: one socket per bridged run stayed in the temp dir (item
+ * 877).
+ */
+export function releaseBridges(tag: string): void {
+  const tmp = taskTmpdir(tag)
+  if (liveTaskTmpdirs.delete(tmp)) rmSync(tmp, { recursive: true, force: true })
+  if (liveServers.delete(tag) && liveServers.size === 0 && resetDeferred) {
+    void resetSandbox().catch(() => {})
+  }
+  const bridges = hostBridges.get(tag)
+  if (bridges === undefined) return
+  hostBridges.delete(tag)
+  for (const port of bridges.ports) {
+    const sock = portBridgeSocket(tag, port)
+    try {
+      unlinkSync(sock)
+    } catch {
+      // never bound, or gone
+    }
+    liveTempFiles.delete(sock)
+  }
+  for (const p of bridges.procs) {
+    // The group: a socat forks one child per connection. Listed on the
+    // guard until it has gone (item 867's order).
+    killTree(p, 'SIGTERM')
+    void p.exited.then(() => releaseGroup(p))
+  }
+}
+
+/** What a task's output says when strace, not the task, ended its first attempt. */
+const TRACER_RETRY_LINE =
+  "[vx] the sandbox's tracer (strace) failed on its own; running the task again\n"
+
+/**
+ * Run a single task wrapped in the sandbox. Caller must have called
+ * `initSandbox()` first.
+ *
+ * On Linux the task runs under strace, which only REPORTS what the sandbox
+ * denied, and a traced task's exit is strace's. strace failing on its own
+ * (`ptrace(PTRACE_LISTEN,…): Input/output error`, after a build that had
+ * finished) turned green work red on CI five times (STATUS Next 24). Such an
+ * attempt, its last word strace's own, is run once more: the sandbox kept
+ * its writes to what it declared, so a second run redoes, not doubles, it.
+ */
+export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRunResult> {
+  const { tracerFailed, ...first } = await runSandboxedOnce(args)
+  if (!tracerFailed) return first
+  args.onStderr?.(TRACER_RETRY_LINE)
+  const { tracerFailed: _again, ...second } = await runSandboxedOnce(args)
+  return {
+    ...second,
+    durationMs: first.durationMs + second.durationMs,
+    stdout: first.stdout + second.stdout,
+    stderr: first.stderr + TRACER_RETRY_LINE + second.stderr,
+  }
+}
+
+/** strace's own message, as the last line a failed traced task printed. */
+const STRACE_OWN_ERROR = /^strace: /
+
+/**
+ * One attempt of `runSandboxed`.
+ *
+ * Violations are matched by a unique per-task command prefix — SRT's
+ * `getViolationsForCommand` keys by base64 of the first 100 chars, so
+ * two tasks running the same underlying command (e.g. parallel `tsc`
+ * across packages) would otherwise collide. We prepend `: '<tag>';`
+ * (shell no-op) to make every command's first 100 chars unique.
+ */
+async function runSandboxedOnce(
+  args: SandboxedRunArgs,
+): Promise<SandboxedRunResult & { tracerFailed: boolean }> {
+  const start = Date.now()
+  const { SandboxManager } = await loadSrt()
+  const { wrapped, tag, taggedCommand, baselines, forwardsSignals } =
+    await wrapSandboxedCommand(args)
 
   // Linux: SRT's SandboxViolationStore is macOS-only, so structured
   // detection on Linux requires us to wrap the spawn with strace and
@@ -340,51 +990,103 @@ export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRun
   // structurally; we just lose the structured violation list.
   const useStrace = await wantsStraceDetection()
   const straceLog = useStrace ? path.join(os.tmpdir(), `vx-strace-${tag}.log`) : undefined
+  if (straceLog) unlinkOnExit(straceLog)
   // We trace only `openat` — it's the actual file-read attempt, the
   // signal the user cares about. `statx` / `newfstatat` / `access`
   // are mostly shell PATH-walking and stat probes that aren't
   // actionable (we'd report every node_modules/.bin entry the shell
   // checks before resolving a command).
-  const spawnArgv = straceLog
-    ? ['strace', '-f', '-e', 'trace=openat', '-o', straceLog, '--', 'sh', '-c', wrapped]
-    : ['sh', '-c', wrapped]
-
+  //
+  // `--seccomp-bpf` is what makes that filter cheap: without it strace
+  // ptrace-stops the tracee on EVERY syscall and discards the untraced
+  // ones in userspace, so a stat-heavy task ran many times slower under
+  // the sandbox than outside it. That is what failed the cache perf
+  // baselines on the Linux job (reproduced 2026-09-09: plain `bun test`
+  // 24/24; under `strace -f -e trace=openat` the same four fail with
+  // medians 2.5–7× over budget; with `--seccomp-bpf` 24/24 again), and
+  // it taxed every other sandboxed task the same way. With the flag the
+  // kernel filter stops only on `openat`. strace ≥ 5.3 (2019); an older
+  // one gets the slow form rather than no detection.
   let proc: ReturnType<typeof Bun.spawn>
   try {
-    proc = Bun.spawn(spawnArgv, {
-      cwd: args.cwd,
-      env: args.env as Record<string, string>,
-      stdin: 'ignore',
-      stdout: 'pipe',
-      stderr: 'pipe',
-    })
+    // Both tools resolved on vx's own PATH (util/which.ts): strace would
+    // otherwise walk the task's PATH for `sh`, where a project's
+    // node_modules/.bin comes first.
+    const sh = executablePath('sh')
+    const spawnArgv = straceLog
+      ? [
+          executablePath('strace'),
+          '-f',
+          ...(useStrace === 'seccomp' ? ['--seccomp-bpf'] : []),
+          '-e',
+          'trace=openat',
+          '-o',
+          straceLog,
+          '--',
+          sh,
+          '-c',
+          wrapped,
+        ]
+      : [sh, '-c', wrapped]
+    proc = spawnGuarded(() =>
+      Bun.spawn(spawnArgv, {
+        argv0: straceLog ? 'strace' : 'sh',
+        cwd: args.cwd,
+        env: args.env as Record<string, string>,
+        // fd 3 is the signal channel the in-sandbox watcher reads.
+        stdio: forwardsSignals ? ['ignore', 'pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+        // As the unsandboxed spawn: its own process group (kill-tree.ts).
+        detached: true,
+      }),
+    )
+    if (forwardsSignals) signalThrough(proc, proc.stdio[3] as number)
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err)
+    const stderr = spawnFailureText(err, args.cwd, 'sandboxed task')
+    args.onStderr?.(stderr)
+    releaseBridges(tag)
     return {
       exitCode: 127,
       durationMs: Date.now() - start,
       stdout: '',
-      stderr: `\n[vx] failed to spawn sandboxed task: ${message}\n`,
+      stderr,
       violations: [],
+      tracerFailed: false,
     }
   }
 
   args.liveChildren?.add(proc)
   const timeout = armTimeout(proc, args.timeoutMs)
   const ac = new AbortController()
+  let stderrTail = ''
   const streams = Promise.all([
     streamToString(proc.stdout, args.onStdout, ac.signal, args.capture?.stdout ?? true),
-    streamToString(proc.stderr, args.onStderr, ac.signal, args.capture?.stderr ?? true),
+    streamToString(
+      proc.stderr,
+      (chunk) => {
+        // Kept whatever the capture setting: the last line says whether
+        // strace, not the task, ended the attempt.
+        stderrTail = (stderrTail + chunk).slice(-1024)
+        args.onStderr?.(chunk)
+      },
+      ac.signal,
+      args.capture?.stderr ?? true,
+    ),
   ])
   // See runCommand: gate on child exit; a lingering grandchild pipe (timeout
   // OR a clean exit that backgrounds a process) can't hang the run — timeout
   // aborts at once, otherwise drainOrAbort bounds the post-exit drain.
   await proc.exited
-  timeout.clear()
+  await timeout.settle()
+  let cut = false
   if (timeout.timedOut()) ac.abort()
-  else await drainOrAbort(streams, ac)
-  const [stdout, stderr] = await streams
+  else cut = await drainOrAbort(streams, ac)
+  const [stdout, streamed] = await streams
+  if (cut) args.onStderr?.(POST_EXIT_CUT_LINE)
+  const stderr = cut ? streamed + POST_EXIT_CUT_LINE : streamed
   args.liveChildren?.delete(proc)
+  releaseGroup(proc)
+  closeSignalChannel(proc)
+  releaseBridges(tag)
   const exitCode = proc.exitCode ?? (proc.signalCode ? signalExitCode(proc.signalCode) : 1)
 
   // macOS: read the violation store keyed by our tagged command.
@@ -405,54 +1107,34 @@ export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRun
   // macOS is therefore lossy-by-OS under load; ENFORCEMENT is unaffected
   // (every observed loss still denied the read and failed the child).
   const store = SandboxManager.getSandboxViolationStore()
-  // Ancestor-directory traversal is NOT an input (owner call, 2026-08-24,
-  // closing the recorded false-`undeclared-inputs` item): to reach its cwd
-  // at all, a process stats/opens every directory on the path — macOS
-  // reports those as `deny(1) file-read-data <ancestor-dir>` for dirs the
-  // baseline doesn't list, node survives them, and no file CONTENT flowed.
-  // Dropping them is scoped to exact ancestor-or-self DIRECTORY paths of
-  // the task's cwd — a denied read of any file INSIDE an ancestor still
-  // reports. (These records usually arrived too late to be seen at all;
-  // the settle window made the pre-existing class visible on every clean
-  // verify exit.)
-  const cwdReal = toRealPath(args.cwd)
-  const ancestorDirs = new Set<string>()
-  for (let d = cwdReal; ; d = path.dirname(d)) {
-    ancestorDirs.add(d)
-    if (d === path.dirname(d)) break
-  }
-  const isAncestorTraversal = (line: string): boolean => {
-    const m = /deny\(\d+\)\s+file-read-(?:data|metadata)\s+(\/\S+)\s*$/.exec(line)
-    if (m === null) return false
-    return ancestorDirs.has(toRealPath(m[1]!))
-  }
+  // EVERY record the store holds for this command, unfiltered (owner,
+  // 2026-09-05). A sandboxed task that fails must say what it was denied;
+  // deciding on the user's behalf that a record was "just traversal" is how
+  // a failure ends up with an empty violations section and no explanation.
   const readMacViolations = (): SandboxViolation[] =>
-    store
-      .getViolationsForCommand(taggedCommand)
-      .filter((v) => !isAncestorTraversal(v.line))
-      .map((v) => ({
-        line: v.line,
-        timestamp: v.timestamp,
-      }))
-  let macViolations = readMacViolations()
-  // The fail-exit gate keeps the warm path free — EXCEPT when the caller
-  // says a clean exit + empty store will be read as PROOF (verify=inputs):
-  // a leaky task that swallows its own read error exits 0, so without the
-  // settle window a late unified-log record becomes a FALSE PASS of the
-  // verify (measured locally 2026-08-24: 1/30 at idle, the same lossy
-  // channel as the fail-exit case).
-  const emptyStoreIsProof = args.settleOnCleanExit === true
-  if (
-    process.platform === 'darwin' &&
-    (exitCode !== 0 || emptyStoreIsProof) &&
-    macViolations.length === 0
-  ) {
-    for (let i = 0; i < 10 && macViolations.length === 0; i++) {
-      await Bun.sleep(100)
-      macViolations = readMacViolations()
-    }
-  }
-
+    store.getViolationsForCommand(taggedCommand).map((v) => ({
+      line: v.line,
+      timestamp: v.timestamp,
+    }))
+  // Darwin only. Since SRT 0.0.75 the store is fed on Linux too, by the
+  // seccomp helper's write observer — but SRT judges those reports against
+  // the GLOBAL `filesystem.allowWrite` from `initialize` (empty here; the
+  // per-task list travels in `customConfig`, which the monitor never sees),
+  // so every write a task makes to its own declared output arrived as
+  // `deny openat <output>` and failed the task (reproduced 2026-09-04 in a
+  // Linux container: exit 1, empty stderr). Linux detection is the strace
+  // pass below, judged against the task's own baselines.
+  let macViolations = process.platform === 'darwin' ? readMacViolations() : []
+  // No settle window: the store is read once, right after the child exits
+  // (owner, 2026-09-05). It cost 300ms on EVERY clean sandboxed task — the
+  // full budget, since a task with nothing to report can only prove that by
+  // waiting — against 26ms for one that reports something and breaks out
+  // early. Measured: clean `echo` 331ms sandboxed vs 16ms plain.
+  //
+  // The price is that macOS feeds this store asynchronously, so a record
+  // that has not arrived yet is not reported. Enforcement is unaffected —
+  // the OS denied the operation either way, and a command that could not
+  // proceed still fails on its own exit code.
   // Linux: parse the strace log and emit one violation per denied
   // syscall on a path inside denyRead that wasn't unconditionally
   // allowed. Best-effort — if parsing fails we surface no Linux
@@ -460,19 +1142,45 @@ export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRun
   const linuxViolations: SandboxViolation[] = straceLog
     ? await parseStraceViolations(straceLog, args, baselines).catch(() => [])
     : []
-  if (straceLog) await unlink(straceLog).catch(() => undefined)
+  if (straceLog) {
+    // Listed until the unlink lands, as the run lock's taking (item 868).
+    await unlink(straceLog).catch(() => undefined)
+    liveTempFiles.delete(straceLog)
+  }
 
   // Apply the task's own ignoreViolations on top of the global defaults.
   // SRT's wrapCommandWithSandboxMacOS doesn't actually thread customConfig.
   // ignoreViolations through to the log monitor — that filter is set
   // once globally at initSandbox time. So per-task user overrides have
   // to be applied here, after read-back.
-  const userIgnore = args.config.ignoreViolations
-  const violations: SandboxViolation[] = filterIgnored(
-    [...macViolations, ...linuxViolations],
-    userIgnore,
-    userCommand,
-  )
+  const violations = reportableViolations([...macViolations, ...linuxViolations], {
+    within: args.reportWithin,
+    linked: args.reportLinked,
+    config: args.config,
+  })
+
+  // The one denial macOS never logs. MEASURED 2026-09-05, same machine, two
+  // runs differing only in the grant: with the cwd granted a failing task
+  // reports its denials normally; WITHOUT it the store stays empty across
+  // the whole settle window (11 reads, 0 records) and the child reports
+  // whatever it likes — `bun test` says only `error: An unknown error
+  // occurred (Unexpected)`. The process dies before macOS logs anything, so
+  // no amount of un-filtering can surface it.
+  //
+  // Not a guess about the cause: the cwd lying outside every allowRead
+  // prefix is a fact of the resolved baselines. Added only when the task
+  // ALREADY failed with nothing to show, so it can never redden a pass.
+  const grantedRead = [...baselines.allowRead, ...args.config.allowRead]
+  if (exitCode !== 0 && violations.length === 0 && !readableUnder(args.cwd, grantedRead)) {
+    violations.push({
+      timestamp: new Date(),
+      line:
+        `vx: this sandbox grants no read access to the task's own working directory ` +
+        `(${args.cwd}), so a command that reads or lists it fails with whatever error it ` +
+        `reports for that — macOS logs no violation record. Add ` +
+        "`sandbox: { allow: { read: ['.'] } }`.",
+    })
+  }
 
   try {
     SandboxManager.cleanupAfterCommand()
@@ -480,6 +1188,7 @@ export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRun
     // ignore; bwrap mount-point cleanup is best-effort
   }
 
+  const lastLine = stderrTail.trimEnd().split('\n').pop() ?? ''
   return {
     exitCode,
     durationMs: Date.now() - start,
@@ -489,260 +1198,288 @@ export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRun
     ...(proc.signalCode ? { signal: proc.signalCode } : {}),
     ...(timeout.timedOut() ? { timedOut: true } : {}),
     ...resourceUsageToCpuRss(proc.resourceUsage()),
+    tracerFailed:
+      straceLog !== undefined &&
+      exitCode !== 0 &&
+      !timeout.timedOut() &&
+      STRACE_OWN_ERROR.test(lastLine),
   }
 }
 
-/** Memoized check: is `strace` on PATH on a Linux host? */
-let straceAvailableCache: boolean | undefined
-async function wantsStraceDetection(): Promise<boolean> {
-  if (process.platform !== 'linux') return false
-  if (straceAvailableCache !== undefined) return straceAvailableCache
-  try {
-    const p = Bun.spawn(['strace', '--version'], { stdout: 'ignore', stderr: 'ignore' })
-    await p.exited
-    straceAvailableCache = p.exitCode === 0
-  } catch {
-    straceAvailableCache = false
-  }
-  return straceAvailableCache
+/**
+ * Is `dir` inside a path the sandbox granted for reading? bwrap binds and
+ * seatbelt rules are both prefix-based, so a grant covers the subtree.
+ */
+function readableUnder(dir: string, granted: readonly string[]): boolean {
+  const target = toRealPath(dir)
+  return granted.some((p) => {
+    const g = toRealPath(p)
+    return target === g || target.startsWith(g.endsWith(path.sep) ? g : g + path.sep)
+  })
 }
 
 /**
- * Parse a strace log for denied filesystem syscalls and convert each
- * one inside the workspace deny anchor (and not in allowRead) into a
- * SandboxViolation. Dedups by (syscall, abs-path) so a tool that
- * statx's the same missing path 10 times in a row produces one line.
- *
- * strace line shape (with -f):
- *   <pid> openat(AT_FDCWD, "<path>", <flags>) = -1 ENOENT (...)
- *   <pid> access("<path>", <mode>) = -1 EACCES (...)
- *   <pid> statx(AT_FDCWD, "<path>", <flags>, <mask>, ...) = -1 ENOENT (...)
- *
- * …but ONLY when the syscall completes without another traced process
- * interleaving. Under `-f` strace splits an interrupted call across two
- * lines and the result never appears next to the path:
- *   <pid> openat(AT_FDCWD, "<path>", <flags> <unfinished ...>
- *   <pid> <... openat resumed>)             = -1 ENOENT (...)
- * A single-line regex silently drops every one of those, so a task that
- * forks concurrent children reading undeclared files reported an
- * INCOMPLETE violation list — which for `--verify=inputs` reads as
- * `proven-complete`. We pair them by pid instead (a process has at most
- * one syscall in flight, so the pid is a sufficient key).
- *
- * We capture the first quoted-string argument as the path. paths that
- * are relative resolve against the task's cwd (set by Bun.spawn).
+ * A token safe to interpolate into a seatbelt profile. The profile travels
+ * inside a shell-quoted `sandbox-exec -p '…'` argument, so a value carrying
+ * a quote, paren or backslash could rewrite the policy or escape the
+ * argument. Refuse rather than escape — every real info type is a plain
+ * dotted name.
  */
-const SYSCALLS = 'openat|access|statx|newfstatat'
-const STRACE_DONE_RE = new RegExp(
-  `^(\\d+)\\s+(${SYSCALLS})\\([^"]*"([^"]+)"[^)]*\\)\\s*=\\s*-1\\s+(ENOENT|EACCES|EPERM)`,
-)
-const STRACE_UNFINISHED_RE = new RegExp(`^(\\d+)\\s+(${SYSCALLS})\\([^"]*"([^"]+)"[^)]*<unfinished`)
-const STRACE_RESUMED_RE = new RegExp(
-  `^(\\d+)\\s+<\\.\\.\\. (${SYSCALLS}) resumed>.*?=\\s*-1\\s+(ENOENT|EACCES|EPERM)`,
-)
-/** A resumed call that SUCCEEDED — clears the pending entry, emits nothing. */
-const STRACE_RESUMED_OK_RE = new RegExp(`^(\\d+)\\s+<\\.\\.\\. (${SYSCALLS}) resumed>`)
-
-/** One denied syscall, however strace chose to lay it out. */
-export interface DeniedCall {
-  syscall: string
-  rawPath: string
-  errno: string
+function sbplToken(value: string, field: string): string {
+  if (!/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new UserError(`${field}: '${value}' is not a valid name`)
+  }
+  return value
 }
 
 /**
- * Walk the trace, pairing `<unfinished ...>` with its `<... resumed>` line.
+ * The capabilities that reach the macOS profile as rules rather than
+ * through SRT's config.
  *
- * Exported for testing: this is the security-relevant half of the Linux
- * detector, and a synthetic trace pins the split-line shapes deterministically
- * where an end-to-end run only produces them when strace happens to interleave.
- */
-export function deniedCalls(text: string): DeniedCall[] {
-  const pending = new Map<string, { syscall: string; rawPath: string }>()
-  const out: DeniedCall[] = []
-  for (const line of text.split('\n')) {
-    const done = STRACE_DONE_RE.exec(line)
-    if (done?.[2] !== undefined && done[3] !== undefined && done[4] !== undefined) {
-      out.push({ syscall: done[2], rawPath: done[3], errno: done[4] })
-      continue
-    }
-    const unfinished = STRACE_UNFINISHED_RE.exec(line)
-    if (
-      unfinished?.[1] !== undefined &&
-      unfinished[2] !== undefined &&
-      unfinished[3] !== undefined
-    ) {
-      pending.set(unfinished[1], { syscall: unfinished[2], rawPath: unfinished[3] })
-      continue
-    }
-    const resumedOk = STRACE_RESUMED_OK_RE.exec(line)
-    if (resumedOk?.[1] === undefined) continue
-    const held = pending.get(resumedOk[1])
-    pending.delete(resumedOk[1])
-    const resumed = STRACE_RESUMED_RE.exec(line)
-    // Only a resume that carries a DENIAL is a violation; a successful
-    // resume just retires the pending entry.
-    if (held !== undefined && resumed?.[3] !== undefined) {
-      out.push({ syscall: held.syscall, rawPath: held.rawPath, errno: resumed[3] })
+ * `systemInfo` has no SRT field at any level. The rest DO have fields,
+ * but SRT reads `network.allowLocalBinding` / `allowUnixSockets` /
+ * `allowMachLookup` off the config given to `initialize()` and never off
+ * the per-call one (`sandbox-manager.js` getters, 0.0.75) — so a per-task
+ * grant passed there is silently dropped. vx is per-task by definition,
+ * so it emits them itself. The rule text mirrors SRT's own.
+ */
+export function macProfileRules(c: ResolvedSandboxConfig): string[] {
+  const rules: string[] = []
+  for (const t of c.systemInfo ?? []) {
+    rules.push(`(allow system-info (info-type "${sbplToken(t, 'allow.systemInfo')}"))`)
+  }
+  if (localBindingOn(c)) {
+    // `*:*`, not `localhost:*`: a dual-stack socket bound to 127.0.0.1 is
+    // ::ffff:127.0.0.1 in the kernel, which seatbelt's `localhost` does
+    // not match. bind and inbound carry no remote endpoint, so this is
+    // not egress. Egress stays pinned to loopback.
+    rules.push('(allow network-bind (local ip "*:*"))')
+    rules.push('(allow network-inbound (local ip "*:*"))')
+    rules.push('(allow network-outbound (remote ip "localhost:*"))')
+  }
+  if (c.unixSockets === true) {
+    rules.push('(allow system-socket (socket-domain AF_UNIX))')
+    rules.push('(allow network-bind (local unix-socket (path-regex #"^/")))')
+    rules.push('(allow network-outbound (remote unix-socket (path-regex #"^/")))')
+  } else if (c.unixSockets !== undefined && c.unixSockets.length > 0) {
+    rules.push('(allow system-socket (socket-domain AF_UNIX))')
+    for (const sock of c.unixSockets) {
+      // Both the declared path and what it resolves to: seatbelt matches the
+      // path the kernel sees, and on macOS `/tmp` is a symlink to
+      // `/private/tmp` — a grant on the former alone never matches.
+      for (const p of unique([
+        sbplPath(sock, 'allow.unixSockets'),
+        sbplResolvedPath(toRealPath(sock), 'allow.unixSockets'),
+      ])) {
+        rules.push(`(allow network-bind (local unix-socket (subpath "${p}")))`)
+        rules.push(`(allow network-outbound (remote unix-socket (subpath "${p}")))`)
+      }
     }
   }
-  return out
-}
-
-async function parseStraceViolations(
-  logPath: string,
-  args: SandboxedRunArgs,
-  baselines: { allowRead: readonly string[]; denyRead: readonly string[]; cwd: string },
-): Promise<SandboxViolation[]> {
-  const text = await Bun.file(logPath).text()
-  if (text.length === 0) return []
-
-  // Treat every baseAllow + sandbox.allowRead path as "this was
-  // explicitly permitted; any -ENOENT here is the user's own missing
-  // file, not a sandbox-induced denial". Same for absolute denyRead
-  // checks below. Canonical on BOTH sides — the policy is expressed in
-  // real paths (see `canonicalBaselines`), so comparing a link-path here
-  // would report an explicitly-allowed read as a violation.
-  const allowAbs = new Set<string>(
-    [...baselines.allowRead, ...args.config.allowRead].map((p) => toRealPath(absolutize(p))),
-  )
-  const denyAnchors = baselines.denyRead.map((p) => toRealPath(absolutize(p)))
-
-  const seen = new Set<string>()
-  const out: SandboxViolation[] = []
-  for (const { syscall, rawPath, errno } of deniedCalls(text)) {
-    const abs = toRealPath(absolutize(rawPath, baselines.cwd))
-    // Only report paths under the workspace-root deny anchor — system
-    // libs / /proc / /sys / etc. probes are not interesting violations.
-    if (!denyAnchors.some((root) => abs === root || abs.startsWith(root + path.sep))) continue
-    // Skip paths the user explicitly allowed (and their descendants).
-    if (isUnderAny(abs, allowAbs)) continue
-    const key = `${syscall}|${abs}`
-    if (seen.has(key)) continue
-    seen.add(key)
-    out.push({
-      line: `${syscall}(${rawPath}) = -1 ${errno}  [${abs}]`,
-      timestamp: new Date(),
-    })
+  for (const name of c.machLookup ?? []) {
+    rules.push(`(allow mach-lookup (global-name "${sbplToken(name, 'allow.machLookup')}"))`)
   }
-  return out
+  return rules
 }
 
-function absolutize(p: string, cwd?: string): string {
-  if (p.startsWith('~')) return path.join(os.homedir(), p.slice(1))
-  if (path.isAbsolute(p)) return p
-  return path.resolve(cwd ?? process.cwd(), p)
+/**
+ * A path safe to interpolate into a seatbelt profile. Same reasoning as
+ * {@link sbplToken}, with the separators a path needs.
+ */
+function sbplPath(value: string, field: string): string {
+  if (!/^[A-Za-z0-9._\-/@+]+$/.test(value) || value.includes('..')) {
+    throw new UserError(`${field}: '${value}' is not a valid path`)
+  }
+  return value
 }
 
-function isUnderAny(abs: string, allow: Set<string>): boolean {
-  if (allow.has(abs)) return true
-  for (const a of allow) {
-    if (abs === a || abs.startsWith(a + path.sep)) return true
+/**
+ * The check for a path the FILESYSTEM handed back (`toRealPath` of a
+ * declared socket), which the declared-value allowlist above is wrong for:
+ * a real macOS home is `/Users/Jane Smith`, and refusing the space would
+ * regress every such layout to close a hole. What can leave the quoted
+ * SBPL string, or the single-quoted `sandbox-exec -p '…'` argument it
+ * travels in, is exactly a double quote, a backslash, a single quote, or a
+ * control character — so only those are refused. Item 478 recorded the
+ * hole (a symlink whose TARGET carries a quote went into the profile
+ * unchecked, because the check was on the string the user wrote and the
+ * interpolation was of the string the kernel resolves); item 582 closed
+ * it. Refuse, never escape, as the sibling checkers do.
+ */
+export function sbplResolvedPath(value: string, field: string): string {
+  // eslint-disable-next-line no-control-regex -- the control range is the point
+  if (/["'\\\x00-\x1f\x7f]/.test(value)) {
+    throw new UserError(
+      `${field}: '${value}' (resolved from a symlink) carries a quote, a backslash or a control ` +
+        `character, which cannot go into a seatbelt profile; point the link at a plain path`,
+    )
   }
-  return false
+  return value
 }
 
 /**
- * Apply the task's user-provided `sandbox.ignoreViolations` map on top
- * of whatever the macOS log monitor + Linux strace pass produced.
- * Mirrors SRT's own substring-match semantics:
- *   - `'*'` entries match every command
- *   - other keys match commands whose userCommand string CONTAINS the key
- *   - the array of strings under each key is substring-matched against
- *     the violation line
+ * Add rules to the END of the seatbelt profile SRT generated.
  *
- * The defaults installed in `initSandbox` already filter on the macOS
- * side; this pass catches per-task additions + Linux strace results.
- */
-function filterIgnored(
-  violations: SandboxViolation[],
-  ignore: Record<string, string[]> | undefined,
-  userCommand: string,
-): SandboxViolation[] {
-  if (!ignore) return violations
-  const wildcard = ignore['*'] ?? []
-  const cmdEntries = Object.entries(ignore).filter(([k]) => k !== '*')
-  return violations.filter((v) => {
-    if (wildcard.some((s) => v.line.includes(s))) return false
-    for (const [pattern, needles] of cmdEntries) {
-      if (userCommand.includes(pattern) && needles.some((s) => v.line.includes(s))) {
-        return false
-      }
+ * SBPL is last-match-wins, so the tail is the only place a rule of ours
+ * outranks one of SRT's. Measured 2026-09-05: the same rules injected
+ * after the `(deny default …)` header were inert in both directions —
+ * SRT's own later clauses won. Filesystem capabilities still go through
+ * SRT's config, where they also work on Linux; what arrives here is what
+ * SRT's per-call config CANNOT carry.
+ *
+ * A profile that does not have the expected shape THROWS. Silently
+ * running a task without a capability it asked for is worse than not
+ * offering the capability.
+ */
+function injectProfileRules(wrapped: string, rules: readonly string[]): string {
+  const anchor = /sandbox-exec -p '\(version 1\)\n\(deny default[^\n]*\n/.exec(wrapped)
+  if (anchor === null) {
+    throw new UserError(
+      'sandbox: the OS sandbox policy did not have the expected shape, so the ' +
+        'capabilities this task declared could not be applied',
+    )
+  }
+  // The profile is a single-quoted shell argument; SRT escapes a literal
+  // quote inside it as `'"'"'` (5 chars). The first bare `'` after the
+  // header therefore closes the profile.
+  let i = anchor.index + anchor[0].length
+  for (;;) {
+    const q = wrapped.indexOf("'", i)
+    if (q === -1) {
+      throw new UserError(
+        'sandbox: the OS sandbox policy was not quoted as expected, so the ' +
+          'capabilities this task declared could not be applied',
+      )
     }
-    return true
-  })
+    if (wrapped.startsWith(`'"'"'`, q)) {
+      i = q + 5
+      continue
+    }
+    return `${wrapped.slice(0, q)}\n${rules.join('\n')}\n${wrapped.slice(q)}`
+  }
 }
 
 /**
- * Merge the orchestrator-provided baseline (declared inputs / outputs /
- * workspace-root anchor) with the user's resolved sandbox block to
- * produce the SRT customConfig. Path arrays are unioned and deduped.
+ * Grant paths, with globs handled per platform.
+ *
+ * macOS: SRT's own `pathFilter` turns a glob into `(regex …)` and a literal
+ * into `(subpath …)`, so a pattern is passed through and seatbelt matches
+ * it — including files created DURING the run.
+ *
+ * Linux: a grant is a bwrap bind mount, and you cannot mount a pattern.
+ * The glob is expanded against the filesystem here, which means it covers
+ * what exists when the task STARTS. A pattern matching a file the task
+ * creates later grants nothing there — declare its directory instead.
  *
- * Network coercion:
- *   - missing / undefined / false  → block all (allowedDomains: [])
- *   - true                          → allow all (allowedDomains: ['*'])
- *   - object                        → use as-is (no merge with shortcuts)
+ * That last sentence is the whole contract, and until item 496 a task
+ * that broke it learned so from its OWN tool. Measured, one task per
+ * spelling, each writing files it declares:
+ *
+ *   write: ['g/**']         ok — collapsed to the directory
+ *   write: ['g/a.txt']      ok — a literal is widened to its directory
+ *   write: ['g/*']          FAILED: `bash: g/a.txt: Read-only file system`
+ *   write: ['g/*.txt']      FAILED, same
+ *   write: ['g/?.txt']      FAILED, same
+ *   write: ['g/[ab].txt']   FAILED, same
+ *
+ * The failure names neither vx nor the grant, so `writeGrantMatchedNothing`
+ * below says what happened and what to write instead. A READ grant that
+ * matches nothing is ordinary (an optional file, a cache not yet
+ * populated), so only writes are reported.
+ *
+ * The classifier is `isMountableLiteral` (sandbox-paths.ts), deliberately
+ * NOT `isLiteralPattern`: its docblock says why the brace is not a wildcard
+ * to a grant.
  */
-function buildCustomConfig(
-  args: SandboxedRunArgs,
-  baselines: {
-    allowRead: readonly string[]
-    allowWrite: readonly string[]
-    denyRead: readonly string[]
-  },
-): Parameters<SrtModule['SandboxManager']['wrapWithSandbox']>[2] {
-  const c = args.config
-  const allowRead = unique([...baselines.allowRead, ...c.allowRead])
-  const denyRead = unique([...baselines.denyRead])
-  const allowWrite = unique([...baselines.allowWrite, ...c.allowWrite])
-
-  const custom: Parameters<SrtModule['SandboxManager']['wrapWithSandbox']>[2] = {
-    filesystem: {
-      denyRead,
-      allowRead,
-      allowWrite,
-      denyWrite: [],
-      ...(c.allowGitConfig !== undefined ? { allowGitConfig: c.allowGitConfig } : {}),
-    },
-  }
-
-  // Network coercion. SRT requires allowedDomains + deniedDomains to be
-  // present on any network config; we always supply both.
-  if (c.network === true) {
-    custom.network = { allowedDomains: ['*'], deniedDomains: [] }
-  } else if (c.network && typeof c.network === 'object') {
-    custom.network = {
-      allowedDomains: c.network.allowedDomains ?? [],
-      deniedDomains: c.network.deniedDomains ?? [],
-      ...(c.network.allowUnixSockets !== undefined
-        ? { allowUnixSockets: c.network.allowUnixSockets }
-        : {}),
-      ...(c.network.allowAllUnixSockets !== undefined
-        ? { allowAllUnixSockets: c.network.allowAllUnixSockets }
-        : {}),
-      ...(c.network.allowLocalBinding !== undefined
-        ? { allowLocalBinding: c.network.allowLocalBinding }
-        : {}),
-      ...(c.network.allowMachLookup !== undefined
-        ? { allowMachLookup: c.network.allowMachLookup }
-        : {}),
+function expandGrants(paths: readonly string[], kind: 'read' | 'write'): string[] {
+  // A pattern covering a directory WHOLE is that directory. `<d>/**/*` and
+  // `<d>/**` match everything UNDER `<d>` and never `<d>` itself, so a task
+  // granted `read: ['**/*']` still could not list its own cwd — the exact
+  // shape `bun test` and `oxlint` need. Collapsing is not a widening: the
+  // pattern already covered every file there; it adds the directory entry.
+  const collapsed = paths.map((p) => {
+    const m = /^(.*?)\/\*\*(?:\/\*)?$/.exec(p)
+    return m === null ? p : m[1]!
+  })
+  if (process.platform !== 'linux') return collapsed
+  const out: string[] = []
+  for (const p of collapsed) {
+    if (isMountableLiteral(p)) {
+      out.push(p)
+      continue
     }
-  } else {
-    // false / undefined → block all
-    custom.network = { allowedDomains: [], deniedDomains: [] }
+    // Anchor the scan at the longest literal prefix so a pattern does not
+    // walk the whole filesystem to find its matches.
+    const base = path.dirname(p.slice(0, p.search(MOUNT_WILDCARDS)))
+    const pattern = path.relative(base, p)
+    // A hit that leaves the scan's base through a link is not what the
+    // pattern named: bwrap binds by the link's target, so `read: ['*']`
+    // over `shared -> ../b/src` bound project b readable, a read `'.'`
+    // never gives, and a cached task replayed b's old bytes (item 1006).
+    // The boundary is the directory holding the first wildcard component,
+    // not the scan's anchor: that sits one component higher.
+    const head = p.slice(0, p.search(MOUNT_WILDCARDS))
+    const home = toRealPath(head.endsWith('/') ? head.slice(0, -1) : path.dirname(head))
+    let hits = 0
+    for (const hit of new Bun.Glob(pattern).scanSync({ cwd: base, onlyFiles: false, dot: true })) {
+      const abs = path.join(base, hit)
+      const real = toRealPath(abs)
+      if (real !== home && !real.startsWith(home + path.sep)) continue
+      out.push(abs)
+      hits++
+    }
+    if (hits === 0 && kind === 'write') writeGrantMatchedNothing(p)
   }
+  return out
+}
 
-  if (c.allowPty !== undefined) custom.allowPty = c.allowPty
-  if (c.enableWeakerNestedSandbox !== undefined) {
-    custom.enableWeakerNestedSandbox = c.enableWeakerNestedSandbox
-  }
-  if (c.enableWeakerNetworkIsolation !== undefined) {
-    custom.enableWeakerNetworkIsolation = c.enableWeakerNetworkIsolation
-  }
-  if (c.ignoreViolations !== undefined) custom.ignoreViolations = c.ignoreViolations
-  return custom
+/** Grants already reported — once per process, not per spawn. */
+const warnedEmptyWriteGrant = new Set<string>()
+
+/**
+ * A write grant that mounted nothing, said once, before the task dies on
+ * it. The remedy is the directory, which is what the grant would have been
+ * widened to anyway had it named a file — and it is named with
+ * `grantPrefix`, the shared wildcard-free head, NOT the scan's anchor
+ * above: that anchor is one component higher (`dirname` of the head, so
+ * the relative pattern keeps its wildcard component), and printing it
+ * would tell the user to grant the PARENT of the directory they meant.
+ */
+function writeGrantMatchedNothing(grant: string): void {
+  if (warnedEmptyWriteGrant.has(grant)) return
+  warnedEmptyWriteGrant.add(grant)
+  process.stderr.write(
+    `[vx] sandbox: the write grant ${grant} matches nothing yet, so it mounts nothing and ` +
+      `a file the task creates under it will fail with "Read-only file system". A bind mount ` +
+      `covers what exists when the task starts — grant the directory instead: ` +
+      `${grantPrefix(grant)}/**\n`,
+  )
 }
 
-function unique(arr: readonly string[]): string[] {
-  return [...new Set(arr)]
+/**
+ * Memoized check: is `strace` on PATH on a Linux host, and does it know
+ * `--seccomp-bpf` (5.3+)? `'seccomp'` is the fast form; `'plain'` traces
+ * every syscall through ptrace and is kept only for an old strace.
+ */
+let straceAvailableCache: false | 'plain' | 'seccomp' | undefined
+async function wantsStraceDetection(): Promise<false | 'plain' | 'seccomp'> {
+  if (process.platform !== 'linux') return false
+  if (straceAvailableCache !== undefined) return straceAvailableCache
+  try {
+    const p = Bun.spawn([executablePath('strace'), '--version'], {
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    const out = await new Response(p.stdout).text()
+    await p.exited
+    if (p.exitCode !== 0) straceAvailableCache = false
+    else {
+      const m = /version (\d+)\.(\d+)/.exec(out)
+      const [major, minor] = m ? [Number(m[1]), Number(m[2])] : [0, 0]
+      straceAvailableCache = major > 5 || (major === 5 && minor >= 3) ? 'seccomp' : 'plain'
+    }
+  } catch {
+    straceAvailableCache = false
+  }
+  return straceAvailableCache
 }