@vzn/vx 0.0.18 → 0.0.21

package/src/exec/executor.ts

@@ -1,9 +1,9 @@
 // The per-task execution contract. `execute-task.ts` decides WHAT to run
 // (command, env, sandbox baselines, capture) and hands a fully-resolved
-// request here; an executor decides WHERE/HOW the process runs. Core ships
-// no executor of its own: `@vzn/vx/plugins/local-executor` is the
-// in-process spawn, declared in vx.workspace.ts like any other. Persistent
-// tasks (`exec.persistent`) never reach an executor: they are local by
+// request here; an executor decides WHERE/HOW the process runs. Core's own
+// `local-executor.ts` is the in-process spawn, and it sits at the TAIL of
+// every executor list — what a plugin executor declines runs here.
+// Persistent tasks (`exec.persistent`) never reach an executor: they are local by
 // construction (a worker cannot hand the submitter a listening port) and
 // stay on `runPersistent`.
 //
@@ -19,23 +19,20 @@ export interface ExecuteSandbox {
   readonly baseAllowRead: readonly string[]
   readonly baseAllowWrite: readonly string[]
   readonly baseDenyRead: readonly string[]
-  readonly config: ResolvedSandboxConfig
   /**
-   * True when an EMPTY violation store on a CLEAN exit will be read as
-   * PROOF (`--verify=inputs` treats zero violations as `proven-complete`).
-   * On macOS the store is fed asynchronously from the unified log, so the
-   * runtime must pay the bounded settle window even for a 0-exit — a leaky
-   * task that swallows its own read error exits 0, and without the wait a
-   * merely-late violation record turns into a false pass of the verify.
+   * 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 settleOnCleanExit: boolean
+  readonly reportWithin: string
+  readonly config: ResolvedSandboxConfig
 }
 
 /** One declared input file, as the cache key saw it. */
 export interface InputFile {
   /** Workspace-relative POSIX path. */
   readonly path: string
-  /** Git blob OID of the WORKTREE bytes (the same digest the key folds). */
+  /** Git blob OID of the WORKTREE bytes — for a symlink, of its target string — the same digest the key folds. */
   readonly digest: string
 }
 
@@ -175,18 +172,6 @@ export interface TaskPlacement {
   readonly pinnedLocal: boolean
   /** Declares `cache` — the only tasks whose input set is described, and so the only ones that can ship. */
   readonly cacheable: boolean
-  /**
-   * `exec.resources` VERBATIM — CPU cores, megabytes, and the image a
-   * worker must be running for this task to be routed to it. All three are
-   * requirements MATCHED against what an executor has, never instructions
-   * to build a machine: a distributed executor's workers belong to whoever
-   * runs the fleet.
-   *
-   * Placement is where this belongs: `exec.resources` is stripped from the
-   * cache key precisely because it decides WHERE a task fits, never what
-   * it produces.
-   */
-  readonly resources?: Readonly<{ cpus?: number; memory?: number; image?: string }>
 }
 
 export interface TaskExecutor {
@@ -234,6 +219,6 @@ export function selectExecutor(
     if (executor.accepts === undefined || executor.accepts(task)) return executor
   }
   throw new Error(
-    `no executor accepted ${task.taskId} (declared: ${executors.map((e) => e.name).join(', ')}). Declare localExecutorPlugin() after the executor that declined to run such tasks locally.`,
+    `no executor accepted ${task.taskId} (declared: ${executors.map((e) => e.name).join(', ')}). Core's local executor accepts every task, so this means it is missing from the list.`,
   )
 }

package/src/exec/index.ts

@@ -1,7 +1,7 @@
 // Module contract. Cross-module imports must come through here; see
 // docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
 
-export { buildIsolatedEnv } from './env.js'
+export { buildIsolatedEnv, VX_RUN_TASK_ENV, VX_RUN_WORKSPACE_ENV } from './env.js'
 export {
   runCommand,
   runPersistent,
@@ -12,13 +12,17 @@ export {
 export {
   initSandbox,
   probeSandbox,
+  unavailableReason,
   resetSandbox,
   resolveSandboxConfig,
   runSandboxed,
-  type DeniedCall,
+  releaseBridges,
+  wrapSandboxedCommand,
   type ResolvedSandboxConfig,
   type SandboxViolation,
 } from './sandbox-runtime.js'
+export { type DeniedCall } from './sandbox-violations.js'
+export { localExecutor } from './local-executor.js'
 export {
   selectExecutor,
   type ExecuteRequest,

package/src/{plugins/local-executor/index.ts → exec/local-executor.ts}

@@ -1,13 +1,14 @@
-// Core's executor as a plugin: spawn the task's command in-process, exactly
-// the `runCommand` / `runSandboxed` call the orchestrator used to make
-// directly. Imports core only through the public `@vzn/vx` surface so this
-// directory can become its own package unchanged.
+// Core's own local executor: spawn the task's command here, in this
+// process. Not a plugin — "run it on this machine" is not a capability
+// someone else supplies differently, it is what running MEANS when no
+// plugin claims the task, so it sits at the TAIL of every executor list
+// (owner, 2026-09-05). An executor plugin places work ELSEWHERE; its
+// absence is "here".
+import { runCommand } from './runner.js'
+import { runSandboxed } from './sandbox-runtime.js'
+import type { TaskExecutor } from './executor.js'
 
-import { runCommand, runSandboxed, type TaskExecutor, type VxPlugin } from '@vzn/vx'
-
-export const LOCAL_EXECUTOR_PLUGIN = 'vx/local-executor'
-
-/** The executor itself — for tests and for plugins that wrap local execution. */
+/** The local executor. Accepts every task. */
 export function localExecutor(): TaskExecutor {
   return {
     name: 'local',
@@ -27,19 +28,14 @@ export function localExecutor(): TaskExecutor {
         const res = await runCommand(common)
         return { ...res, violations: [] }
       }
-      return await runSandboxed({
+      return runSandboxed({
         ...common,
         baseAllowRead: req.sandbox.baseAllowRead,
         baseAllowWrite: req.sandbox.baseAllowWrite,
         baseDenyRead: req.sandbox.baseDenyRead,
+        reportWithin: req.sandbox.reportWithin,
         config: req.sandbox.config,
-        settleOnCleanExit: req.sandbox.settleOnCleanExit,
       })
     },
   }
 }
-
-/** Declare in vx.workspace.ts: `plugins: [localExecutorPlugin(), …]`. Accepts every task. */
-export function localExecutorPlugin(): VxPlugin {
-  return { name: LOCAL_EXECUTOR_PLUGIN, executor: () => localExecutor() }
-}

package/src/exec/runner.ts

@@ -4,7 +4,9 @@
 // process exits. cpuMs / peakRssBytes are then surfaced on RunResult and
 // folded into the v11 `runs` table by the orchestrator.
 
+import { readFileSync } from 'node:fs'
 import { constants as osConstants } from 'node:os'
+import { killGraceMs } from '../util/index.js'
 
 export interface RunResult {
   exitCode: number
@@ -152,6 +154,12 @@ export function signalExitCode(signal: string): number {
   return num === undefined ? 130 : 128 + num
 }
 
+/**
+ * Grace after a timeout SIGTERM before escalating to SIGKILL — a child that
+ * ignores SIGTERM must still be bounded. Matches the persistent-shutdown grace.
+ */
+const TIMEOUT_SIGKILL_GRACE_MS = 2000
+
 /**
  * Arm a SIGTERM timeout on a spawned child. Returns a handle whose
  * `timedOut()` reports whether the timer fired — so the caller can
@@ -160,12 +168,6 @@ export function signalExitCode(signal: string): number {
  * on its own. A no-op (never fires, nothing to clear) when `timeoutMs`
  * is undefined.
  */
-/**
- * Grace after a timeout SIGTERM before escalating to SIGKILL — a child that
- * ignores SIGTERM must still be bounded. Matches the persistent-shutdown grace.
- */
-const TIMEOUT_SIGKILL_GRACE_MS = 2000
-
 export function armTimeout(
   proc: ReturnType<typeof Bun.spawn>,
   timeoutMs: number | undefined,
@@ -182,7 +184,7 @@ export function armTimeout(
     // timeout, so a wedged child hangs the whole run forever. Mirrors the
     // end-of-run persistent-shutdown escalation. Unref'd so it never keeps
     // the CLI alive.
-    killTimer = setTimeout(() => proc.kill('SIGKILL'), TIMEOUT_SIGKILL_GRACE_MS)
+    killTimer = setTimeout(() => proc.kill('SIGKILL'), killGraceMs(TIMEOUT_SIGKILL_GRACE_MS))
     killTimer.unref?.()
   }, timeoutMs)
   return {
@@ -395,6 +397,14 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
           ),
         )
         child.kill('SIGTERM')
+        // Same escalation as `armTimeout`: a server that traps TERM and
+        // never became ready is not in the persistent registry, so nothing
+        // else would ever kill it — it outlived the run under init.
+        const killTimer = setTimeout(
+          () => child.kill('SIGKILL'),
+          killGraceMs(TIMEOUT_SIGKILL_GRACE_MS),
+        )
+        killTimer.unref?.()
       }
     }, opts.timeoutMs)
   }
@@ -478,8 +488,32 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
     stderr,
     ...(proc.signalCode ? { signal: proc.signalCode } : {}),
     ...(timeout.timedOut() ? { timedOut: true } : {}),
-    ...resourceUsageToCpuRss(proc.resourceUsage()),
+    ...resourceUsageToCpuRss(proc.resourceUsage(), ownRssHighWater()),
+  }
+}
+
+/**
+ * This process's own RSS high-water mark, in bytes: the floor under which
+ * a child's `ru_maxrss` says nothing about the child. Linux folds the
+ * forking parent's high-water mark into the child's figure at exec (a
+ * forked child starts with its parent's pages; `exec_mmap` keeps the old
+ * mm's peak), so a task lighter than vx itself reads vx's footprint —
+ * `true` read 44 MB through vx while its shell's `VmHWM` was 1.9 MB, and
+ * 300 MB allocated in the parent made `true` read 328 MB (2026-09-12).
+ * Read after the child exits so it covers the whole task's span (the mark
+ * is monotonic). Linux reads `VmHWM`; elsewhere the current RSS is the
+ * bound in hand.
+ */
+export function ownRssHighWater(): number {
+  if (process.platform === 'linux') {
+    try {
+      const m = /VmHWM:\s+(\d+) kB/.exec(readFileSync('/proc/self/status', 'utf8'))
+      if (m !== null) return Number(m[1]) * 1024
+    } catch {
+      // /proc unreadable: fall through to the current RSS.
+    }
   }
+  return process.memoryUsage.rss()
 }
 
 /**
@@ -540,18 +574,23 @@ export async function streamToString(
  */
 export function resourceUsageToCpuRss(
   usage: ReturnType<ReturnType<typeof Bun.spawn>['resourceUsage']>,
-  platform: NodeJS.Platform = process.platform,
+  /** The parent's own high-water mark (`ownRssHighWater`); a peak at or under it is inherited, not the child's, and is not reported. */
+  floorBytes = 0,
 ): { cpuMs?: number; peakRssBytes?: number } {
   if (!usage) return {}
   // cpuTime.total is microseconds as a bigint → ms.
   const cpuMs = Number(usage.cpuTime.total) / 1000
-  // maxRSS is the raw kernel `ru_maxrss`, whose UNIT IS PLATFORM-SPECIFIC and
-  // Bun does NOT normalize it:
-  //   • Linux   → kilobytes  (multiply by 1024 for bytes)
-  //   • macOS / BSD → bytes  (already bytes; do NOT multiply)
-  //   • Windows → bytes (PeakWorkingSetSize)
-  // Treating macOS's byte value as KB inflates peak RSS by 1024× — e.g. a
-  // real 460 MB showed up as 460 GB. Convert per platform.
-  const peakRssBytes = platform === 'linux' ? usage.maxRSS * 1024 : usage.maxRSS
-  return { cpuMs, peakRssBytes }
+  // `maxRSS` is BYTES on every platform: Bun normalizes the kernel's
+  // `ru_maxrss` (kilobytes on Linux, bytes on macOS) before handing it
+  // over, as its typing says. This used to multiply by 1024 on Linux on
+  // the belief that Bun passed the raw value through, and every Linux
+  // peak was 1024× too big — a 64 MB `bun test` recorded as 64 GB in
+  // telemetry, `--summarize` and the run history, and once reservations
+  // were learned from that history (2026-09-12) every task with a
+  // recorded peak was over any budget and ran alone. Measured, not
+  // assumed: `tests/runner.test.ts` allocates a known number of bytes
+  // and reads the peak back within a bounded factor of it.
+  // A reading at or under the parent's own mark is the parent's (see
+  // `ownRssHighWater`): the child's peak is unknown, bounded by it.
+  return usage.maxRSS > floorBytes ? { cpuMs, peakRssBytes: usage.maxRSS } : { cpuMs }
 }

package/src/exec/sandbox-binds.ts

@@ -0,0 +1,182 @@
+// Write grants as bwrap can honour them, and the SRT custom config built
+// from the resolved policy: a file-shaped grant widened to its directory,
+// a read grant punched around the write grants inside it, the network
+// lists SRT insists on receiving in full.
+
+import { lstatSync, readdirSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { localBindingOn, unique } from './sandbox-paths.js'
+import type { SandboxedRunArgs } from './sandbox-runtime.js'
+
+type SrtModule = typeof import('@anthropic-ai/sandbox-runtime')
+
+/**
+ * Write grants as bwrap can actually honour them.
+ *
+ * A grant naming a FILE becomes a bwrap file bind, and you cannot rename
+ * onto an active mount point: any tool that writes its output by staging
+ * beside it and renaming — `bun build --compile`, most compilers, every
+ * atomic writer — dies with EBUSY. Minimal repro, 2026-09-05: under
+ * `bwrap --bind /w/dist/out.bin /w/dist/out.bin`, `mv /w/s /w/dist/out.bin`
+ * is "Device or resource busy"; binding `/w/dist` instead succeeds.
+ *
+ * So on Linux a file-shaped grant is widened to its directory. That IS a
+ * widening — the task may write its siblings — and it is the narrowest
+ * grant the mechanism can express: the alternative is a declared output
+ * the task cannot produce. macOS needs none of this (seatbelt matches
+ * paths, it does not mount), so the grant stays exact there.
+ */
+function bindableWrites(paths: readonly string[]): string[] {
+  if (process.platform !== 'linux') return [...paths]
+  return unique(
+    paths.map((p) => {
+      if (/[*?[\]]/.test(p)) return p
+      try {
+        if (statSync(p).isDirectory()) return p
+      } catch {
+        // Does not exist yet: `prepareOutputsForBind` creates a file for a
+        // file-shaped grant, so treat it as one.
+      }
+      return path.dirname(p)
+    }),
+  )
+}
+
+/** Directories already warned about below — once per process, not per spawn. */
+const warnedSymlinkPunch = new Set<string>()
+
+/**
+ * Expand a read grant so it is never an ANCESTOR of a write grant.
+ *
+ * bwrap builds the sandbox out of mounts, and SRT emits them write-first:
+ * `--bind <out>` then `--ro-bind <readPath>`. When the read path is an
+ * ancestor of the write path the read-only mount lands ON TOP of the
+ * writable one and every write fails with `Read-only file system`
+ * (`pushReadDenyDirMounts`, SRT 0.0.75 — its skip only covers the reverse
+ * nesting). Verified in a Linux container 2026-09-05:
+ *
+ *   read=[proj]     write=[proj/dist]  → mkdir: Read-only file system
+ *   read=[proj/src] write=[proj/dist]  → ok
+ *   read=[proj]     no writes          → ok
+ *
+ * So punch the write paths out: grant the ancestor's children instead,
+ * recursing only along the branches that actually contain one. Same probe,
+ * same command: `read=[src, lib, package.json] write=[dist]` → ok. macOS
+ * never needed this (seatbelt is precedence-based, not mounts), and it is
+ * harmless there, so both platforms take the same path.
+ *
+ * A grant with no write path under it is returned untouched — the common
+ * case costs nothing, not even a readdir.
+ */
+export function punchWritePaths(readPath: string, writePaths: readonly string[]): string[] {
+  // Linux only. The shadowing is a property of bwrap MOUNTS; macOS seatbelt
+  // evaluates rules by precedence, so a read grant on a directory and a
+  // write grant inside it coexist. Punching there costs the directory
+  // ENTRY: granting every child is not granting the dir, so a command that
+  // stats its own cwd — `bun build` — is denied it and dies with
+  // `error: An unknown error occurred (Unexpected)` (2026-09-05).
+  if (process.platform !== 'linux') return [readPath]
+  const under = writePaths.filter((w) => w !== readPath && w.startsWith(readPath + path.sep))
+  if (under.length === 0) return [readPath]
+  let entries: string[]
+  try {
+    entries = readdirSync(readPath)
+  } catch {
+    // Unreadable or not a directory: nothing to expand, hand it over as is.
+    return [readPath]
+  }
+  const out: string[] = []
+  const linked: string[] = []
+  for (const entry of entries) {
+    const child = path.join(readPath, entry)
+    // A write path is already bound read-write, which is readable.
+    if (under.includes(child)) continue
+    // bwrap resolves a bind SOURCE, so a symlinked child is mounted as the
+    // directory it points at: inside the sandbox the link is gone. For a
+    // package in Bun's isolated node_modules layout that severs it from
+    // the `.bun/` siblings its own dependencies resolve through — astro
+    // could not find `yargs-parser` for four days of red CI (2026-09-09).
+    // SRT's config carries no `--symlink`, so the only fix is the grant:
+    // say which one, loudly.
+    try {
+      if (lstatSync(child).isSymbolicLink()) linked.push(child)
+    } catch {
+      // vanished between readdir and lstat: nothing to bind either way
+    }
+    out.push(...punchWritePaths(child, under))
+  }
+  if (linked.length > 0 && !warnedSymlinkPunch.has(readPath)) {
+    warnedSymlinkPunch.add(readPath)
+    process.stderr.write(
+      `[vx] sandbox: a write grant under ${readPath} makes its ${linked.length} symlinked ` +
+        `entr${linked.length === 1 ? 'y' : 'ies'} (${linked
+          .slice(0, 3)
+          .map((l) => path.basename(l))
+          .join(', ')}${linked.length > 3 ? ', …' : ''}) plain directories inside the sandbox — ` +
+        `a package resolved through one loses its siblings. Move the write grant (${under
+          .map((w) => path.relative(readPath, w))
+          .join(', ')}) out of it.\n`,
+    )
+  }
+  return out
+}
+
+/**
+ * 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; every
+ * read grant is punched around the write grants (`punchWritePaths`).
+ *
+ * Network: `allow.network` missing → block all (allowedDomains: []);
+ * `true` → allow all (['*']); a domain list → exactly that list.
+ * `deny.network` is always passed as deniedDomains.
+ */
+export function buildCustomConfig(
+  args: Pick<SandboxedRunArgs, 'config'>,
+  baselines: {
+    allowRead: readonly string[]
+    allowWrite: readonly string[]
+    denyRead: readonly string[]
+  },
+): Parameters<SrtModule['SandboxManager']['wrapWithSandbox']>[2] {
+  const c = args.config
+  const denyRead = unique([...baselines.denyRead])
+  const allowWrite = bindableWrites(unique([...baselines.allowWrite, ...c.allowWrite]))
+  const allowRead = unique(
+    [...baselines.allowRead, ...c.allowRead].flatMap((r) => punchWritePaths(r, allowWrite)),
+  )
+
+  const custom: Parameters<SrtModule['SandboxManager']['wrapWithSandbox']>[2] = {
+    filesystem: {
+      denyRead,
+      allowRead,
+      allowWrite,
+      denyWrite: [],
+      ...(c.gitConfig !== undefined ? { allowGitConfig: c.gitConfig } : {}),
+    },
+  }
+
+  // `allow.network` / `deny.network` become SRT's domain lists. SRT requires
+  // both to be present on any network config, so we always supply both;
+  // omitted means no network at all.
+  custom.network = {
+    allowedDomains: c.network === true ? ['*'] : [...(c.network ?? [])],
+    deniedDomains: [...(c.denyNetwork ?? [])],
+    ...(c.unixSockets === true
+      ? { allowAllUnixSockets: true }
+      : c.unixSockets !== undefined
+        ? { allowUnixSockets: [...c.unixSockets] }
+        : {}),
+    ...(c.localBinding !== undefined ? { allowLocalBinding: localBindingOn(c) } : {}),
+    ...(c.machLookup !== undefined ? { allowMachLookup: [...c.machLookup] } : {}),
+  }
+
+  if (c.pty !== undefined) custom.allowPty = c.pty
+  if (c.weakerWhenNested !== undefined) {
+    custom.enableWeakerNestedSandbox = c.weakerWhenNested
+  }
+  if (c.weakerNetworkIsolation !== undefined) {
+    custom.enableWeakerNetworkIsolation = c.weakerNetworkIsolation
+  }
+  return custom
+}

package/src/exec/sandbox-paths.ts

@@ -0,0 +1,50 @@
+// Path helpers the sandbox modules share: canonical forms (the policy
+// matches real paths), the task-relative absolutizer the strace pass uses,
+// and the prefix test.
+
+import { realpathSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * 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.
+ */
+export 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))
+  }
+}
+
+export 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)
+}
+
+export 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
+  }
+  return false
+}
+
+export function unique(arr: readonly string[]): string[] {
+  return [...new Set(arr)]
+}
+
+/** `allow.localBinding` grants loopback: `true`, or a non-empty port list. */
+export function localBindingOn(c: { localBinding?: boolean | readonly number[] }): boolean {
+  return c.localBinding === true || (Array.isArray(c.localBinding) && c.localBinding.length > 0)
+}