@vzn/vx 0.0.21 → 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,22 +25,45 @@
 
 import path from 'node:path'
 import os from 'node:os'
+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 { UserError, xxh3hex } from '../util/index.js'
+import {
+  executablePath,
+  grantPrefix,
+  isTmpdirRefusal,
+  TMPDIR_HINT,
+  UserError,
+  xxh3hex,
+} from '../util/index.js'
 import { buildCustomConfig } from './sandbox-binds.js'
-import { localBindingOn, toRealPath, unique } from './sandbox-paths.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
@@ -101,7 +124,9 @@ async function probeUncached(weakerNested: boolean): Promise<SandboxAvailability
     return { available: false, reason: `platform ${process.platform} not supported` }
   }
   const deps = SandboxManager.checkDependencies()
-  if (deps.errors.length > 0) return { available: false, reason: deps.errors.join('; ') }
+  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') {
     await initSandbox()
     return trySandboxedTrue(SandboxManager, weakerNested)
@@ -166,7 +191,8 @@ async function trySandboxedTrue(
       undefined,
       weakerNested ? { enableWeakerNestedSandbox: true } : undefined,
     )
-    const proc = Bun.spawn(['sh', '-c', wrapped], {
+    const proc = Bun.spawn([executablePath('sh'), '-c', wrapped], {
+      argv0: 'sh',
       stdout: 'ignore',
       stderr: 'pipe',
       stdin: 'ignore',
@@ -176,8 +202,55 @@ async function trySandboxedTrue(
     if (proc.exitCode === 0) return { available: true, reason: '' }
     return { available: false, reason: unavailableReason(proc.exitCode, stderr) }
   } catch (err) {
-    return { available: false, reason: `sandbox 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}`
 }
 
 /**
@@ -200,15 +273,6 @@ const DEFAULT_IGNORE_VIOLATIONS: Record<string, string[]> = {
   ],
 }
 
-/**
- * One-time SRT initialization per orchestrator run. Starts the proxy
- * servers + (on macOS) the violation log monitor. Safe to call repeatedly
- * — SRT itself returns early on the second call.
- *
- * 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`.
- */
 /**
  * The temp directory SRT hands every sandboxed task. It overrides `TMPDIR`
  * so temp-file writers land somewhere its filesystem policy already allows,
@@ -228,6 +292,90 @@ function sandboxTmpdir(): string {
 }
 
 /**
+ * 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
+ * — SRT itself returns early on the second call.
+ *
+ * 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
@@ -245,6 +393,10 @@ export async function initSandbox(opts?: {
    */
   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()
@@ -257,12 +409,14 @@ export async function initSandbox(opts?: {
     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
@@ -273,12 +427,43 @@ export async function initSandbox(opts?: {
   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> {
-  for (const tag of [...hostBridges.keys()]) releaseBridges(tag)
-  const { SandboxManager } = await loadSrt()
-  await SandboxManager.reset()
-  availabilityCache.clear()
-  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 {
@@ -295,15 +480,12 @@ export interface SandboxedRunArgs {
   /** See `CaptureConfig` — which streams are retained on the result. */
   capture?: CaptureConfig
   /**
-   * 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
@@ -316,6 +498,8 @@ export interface SandboxedRunArgs {
    * 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.
@@ -355,7 +539,7 @@ export interface ResolvedSandboxConfig {
  * 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
@@ -365,22 +549,61 @@ export interface ResolvedSandboxConfig {
  */
 interface CanonicalBaselines {
   allowRead: string[]
-  allowWrite: string[]
   denyRead: string[]
   cwd: string
 }
 
 function canonicalBaselines(
-  args: Pick<SandboxedRunArgs, 'baseAllowRead' | 'baseAllowWrite' | 'baseDenyRead' | 'cwd'>,
+  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
@@ -398,8 +621,15 @@ export function resolveSandboxConfig(
   }
   const a = cfg.allow ?? {}
   const r: ResolvedSandboxConfig = {
-    allowRead: expandGrants((a.read ?? []).map(resolve)),
-    allowWrite: expandGrants((a.write ?? []).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 (a.network !== undefined) r.network = a.network
   if (cfg.deny?.network !== undefined) r.denyNetwork = cfg.deny.network
@@ -451,15 +681,33 @@ 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.
  */
+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
@@ -469,13 +717,18 @@ export interface SandboxedRunResult extends RunResult {
  * exit). Returns the wrapped command and the tag the store keys by.
  */
 export async function wrapSandboxedCommand(
-  args: Pick<SandboxedRunArgs, 'command' | 'cwd' | 'forwardArgs' | 'config'> &
-    Pick<SandboxedRunArgs, 'baseAllowRead' | 'baseAllowWrite' | 'baseDenyRead'>,
+  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 userCommand =
@@ -484,7 +737,15 @@ export async function wrapSandboxedCommand(
       : 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)
@@ -493,14 +754,77 @@ export async function wrapSandboxedCommand(
   // 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 inner = ports.length > 0 ? `${portBridgeInner(ports, tag)} ${taggedCommand}` : taggedCommand
+  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 }
+  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). */
@@ -542,7 +866,10 @@ export function portBridgeHostArgv(tag: string, port: number): string[] {
   ]
 }
 
-const hostBridges = new Map<string, Array<ReturnType<typeof Bun.spawn>>>()
+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>> = []
@@ -550,38 +877,110 @@ function spawnHostBridges(ports: readonly number[], tag: string): void {
     // 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(
-        Bun.spawn(portBridgeHostArgv(tag, p), {
-          stdin: 'ignore',
-          stdout: 'ignore',
-          stderr: 'ignore',
-        }),
+        spawnGuarded(() =>
+          Bun.spawn(portBridgeHostArgv(tag, p), {
+            stdin: 'ignore',
+            stdout: 'ignore',
+            stderr: 'ignore',
+            detached: true,
+          }),
+        ),
       )
     } catch {
       // see above
     }
   }
-  if (procs.length > 0) hostBridges.set(tag, procs)
+  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; idempotent. */
+/**
+ * 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 procs = hostBridges.get(tag)
-  if (procs === undefined) return
+  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 p of procs) {
+  for (const port of bridges.ports) {
+    const sock = portBridgeSocket(tag, port)
     try {
-      p.kill('SIGTERM')
+      unlinkSync(sock)
     } catch {
-      // already gone
+      // 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 } = await wrapSandboxedCommand(args)
+  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
@@ -591,6 +990,7 @@ 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
@@ -607,58 +1007,85 @@ export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRun
   // 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.
-  const spawnArgv = straceLog
-    ? [
-        'strace',
-        '-f',
-        ...(useStrace === 'seccomp' ? ['--seccomp-bpf'] : []),
-        '-e',
-        'trace=openat',
-        '-o',
-        straceLog,
-        '--',
-        'sh',
-        '-c',
-        wrapped,
-      ]
-    : ['sh', '-c', wrapped]
-
   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)
 
@@ -715,7 +1142,11 @@ 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.
@@ -724,6 +1155,7 @@ export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRun
   // to be applied here, after read-back.
   const violations = reportableViolations([...macViolations, ...linuxViolations], {
     within: args.reportWithin,
+    linked: args.reportLinked,
     config: args.config,
   })
 
@@ -756,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,
@@ -765,6 +1198,11 @@ 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),
   }
 }
 
@@ -805,7 +1243,7 @@ function sbplToken(value: string, field: string): string {
  * grant passed there is silently dropped. vx is per-task by definition,
  * so it emits them itself. The rule text mirrors SRT's own.
  */
-function macProfileRules(c: ResolvedSandboxConfig): string[] {
+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')}"))`)
@@ -829,7 +1267,10 @@ function macProfileRules(c: ResolvedSandboxConfig): string[] {
       // 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'), toRealPath(sock)])) {
+      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}")))`)
       }
@@ -852,6 +1293,30 @@ function sbplPath(value: string, field: string): string {
   return value
 }
 
+/**
+ * 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 value
+}
+
 /**
  * Add rules to the END of the seatbelt profile SRT generated.
  *
@@ -905,8 +1370,28 @@ function injectProfileRules(wrapped: string, rules: readonly string[]): string {
  * 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.
+ *
+ * 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 expandGrants(paths: readonly string[]): string[] {
+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
@@ -919,21 +1404,58 @@ function expandGrants(paths: readonly string[]): string[] {
   if (process.platform !== 'linux') return collapsed
   const out: string[] = []
   for (const p of collapsed) {
-    if (!/[*?[\]]/.test(p)) {
+    if (isMountableLiteral(p)) {
       out.push(p)
       continue
     }
     // 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(/[*?[\]]/)))
+    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 })) {
-      out.push(path.join(base, hit))
+      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
 }
 
+/** 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`,
+  )
+}
+
 /**
  * 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
@@ -944,7 +1466,10 @@ async function wantsStraceDetection(): Promise<false | 'plain' | 'seccomp'> {
   if (process.platform !== 'linux') return false
   if (straceAvailableCache !== undefined) return straceAvailableCache
   try {
-    const p = Bun.spawn(['strace', '--version'], { stdout: 'pipe', stderr: 'ignore' })
+    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