@vzn/vx 0.0.18 → 0.0.21

package/src/orchestrator/sandbox-request.ts

@@ -0,0 +1,243 @@
+// The sandbox half of an `ExecuteRequest`: what a task may read and write,
+// where denials are reported, and the filesystem groundwork a bind needs
+// (bwrap cannot bind a path that does not exist). Shared by the cached path
+// (through the executor) and the persistent path (spawned in execute-task).
+
+import { mkdir, readdir, realpath, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import path from 'node:path'
+import type { ExecConfig } from '../config.js'
+import {
+  initSandbox,
+  probeSandbox,
+  resolveSandboxConfig,
+  type ExecuteRequest,
+} from '../exec/index.js'
+import type { TaskNode } from '../graph/index.js'
+import { staticPrefix, UserError } from '../util/index.js'
+
+/**
+ * Arm the sandbox runtime for a run, lazily: only when at least one task
+ * opts in through its `sandbox: {...}` block. A task that needs sandboxing
+ * on a platform without one is a hard error, so it never silently runs
+ * unsandboxed. Returns whether the runtime was armed — the run resets it
+ * at the end (`resetSandbox`), or the next run inits on top of stale
+ * proxy state.
+ */
+export interface SandboxArmer {
+  /**
+   * Probe availability and start the runtime, once; every later call
+   * shares the same promise. Throws the `sandbox not available` UserError
+   * when the platform cannot host it.
+   */
+  arm(): Promise<void>
+  /** True once `arm()` has completed — the run then owns a runtime to reset. */
+  readonly armed: boolean
+}
+
+/**
+ * Prepare the sandbox for a run WITHOUT starting it. Starting is
+ * `arm()`, and it happens on the first task that actually executes inside
+ * a sandbox — not up front. Up front, every run of a sandboxed workspace
+ * paid the probe (a sandboxed `true` through the runtime, ~300–400 ms on
+ * Linux, the runtime module's own load included) even when every task was
+ * a cache hit and nothing executed; measured 2026-09-10 on this repo's
+ * own warm gate: `classify + probe` 288 ms of a 798 ms run. A hit needs
+ * no sandbox, so a hit pays nothing.
+ *
+ * The domain union is computed here from every sandboxed node, because
+ * SRT runs ONE filtering proxy per run and checks every request against
+ * the allowlist given to `initialize()` — never the per-call one
+ * (`sandbox-manager.js` 0.0.75). A task that declares no domains still
+ * reaches nothing: its profile is not given the proxy's port at all.
+ * The unix-socket allowance is per run the same way: SRT's Linux seccomp
+ * filter on `socket(AF_UNIX)` is all-or-nothing and read at
+ * `initialize()`, so a task declaring `unixSockets`, or a `localBinding`
+ * port list (its bridge is a unix socket the task's side creates), lifts
+ * it for the run. macOS keeps per-task precision through vx's own rules.
+ */
+export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
+  const sandboxed = [...nodes].filter((n) => n.config.exec?.sandbox !== undefined)
+  if (sandboxed.length === 0) return null
+  const weakerNested = sandboxed.every((n) => n.config.exec?.sandbox?.weakerWhenNested === true)
+  const domains = new Set<string>()
+  let unixSockets = false
+  for (const n of sandboxed) {
+    const allow = n.config.exec?.sandbox?.allow
+    const net = allow?.network
+    if (Array.isArray(net)) for (const d of net) domains.add(d)
+    const sockets = allow?.unixSockets
+    if (sockets === true || (Array.isArray(sockets) && sockets.length > 0)) unixSockets = true
+    const lb = allow?.localBinding
+    if (Array.isArray(lb) && lb.length > 0 && process.platform === 'linux') unixSockets = true
+  }
+  let pending: Promise<void> | undefined
+  let armed = false
+  return {
+    get armed() {
+      return armed
+    },
+    arm() {
+      pending ??= (async () => {
+        try {
+          const avail = await probeSandbox({ weakerNested })
+          if (!avail.available) throw new UserError(`sandbox not available: ${avail.reason}`)
+          await initSandbox({
+            allowedDomains: [...domains],
+            ...(unixSockets ? { allowAllUnixSockets: true } : {}),
+          })
+        } catch (err) {
+          // A throw from the runtime itself (its bridge needs socat, which
+          // the dependency check does not cover) gets the same one-line
+          // verdict as a refused probe, not an internal error with a stack.
+          if (err instanceof UserError) throw err
+          throw new UserError(
+            `sandbox not available: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+        armed = true
+      })()
+      return pending
+    },
+  }
+}
+
+/**
+ * The sandbox half of an `ExecuteRequest` for one task, shared by the
+ * cached path (through the executor) and the persistent path (spawned here).
+ *
+ * The sandbox derives NOTHING from `cache` (owner, 2026-09-05). Those are
+ * two different questions: `cache.inputs` says what INVALIDATES the task,
+ * `sandbox.allow` says what it may TOUCH. Deriving one from the other
+ * coupled them in both directions — a declaration added for caching
+ * silently widened the sandbox, and a path the task needed had to be
+ * laundered through the cache key to get it. A sandboxed task declares
+ * its own reads and writes.
+ *
+ * `node_modules` is the one grant core still makes, and it is not
+ * cache-derived: it is where the task's own PATH gets its `.bin` entries,
+ * and denying it made the sandbox unusable for anything that imports a
+ * dependency (`bun build --compile` died with only `error: An unknown
+ * error occurred (Unexpected)`; owner call 2026-09-04).
+ */
+export async function sandboxRequestFor(
+  node: TaskNode,
+  sandbox: NonNullable<ExecConfig['sandbox']>,
+  workspaceRoot: string,
+): Promise<NonNullable<ExecuteRequest['sandbox']>> {
+  const depDirs = [
+    path.join(node.projectDir, 'node_modules'),
+    path.join(workspaceRoot, 'node_modules'),
+  ]
+  // A workspace dependency is a SYMLINK in `node_modules` pointing at a
+  // sibling project, so granting `node_modules` grants a link whose
+  // target is outside it. That target is a dependency, not a reach-out:
+  // no project config should have to name a sibling to import what its
+  // own `package.json` depends on (owner, 2026-09-05).
+  depDirs.push(...(await linkedDeps(depDirs)))
+  // bwrap cannot --bind a path that does not exist: the bind silently
+  // becomes a no-op and writes to it appear to succeed but never land.
+  // Pre-create what the task said it will write.
+  await prepareOutputsForBind(node.projectDir, sandbox.allow?.write ?? [])
+  return {
+    // Only what the task declared, plus node_modules. Write paths are
+    // readable too: a task that writes `dist/x` expects to read it back
+    // (`tsc --incremental` re-reads .tsbuildinfo).
+    baseAllowRead: depDirs,
+    baseAllowWrite: [],
+    // Enforcement anchors at the WORKSPACE ROOT: a task may not leave
+    // its project, so every sibling and every root file is denied.
+    // Reporting is a different question — see `reportWithin` below.
+    baseDenyRead: [workspaceRoot],
+    // …but only denials INSIDE the project are worth reporting. A task
+    // bumping into the wall is the sandbox working, not a finding: the
+    // walk `bun build --compile` makes from `/` down to its cwd lists
+    // every directory on the way (traced 2026-09-05) and no config can
+    // declare that away. What DOES matter is an undeclared touch of the
+    // project's own files — that is the one that breaks the cache key,
+    // because the key folds this project's inputs.
+    reportWithin: node.projectDir,
+    config: resolveSandboxConfig(sandbox, node.projectDir),
+  }
+}
+
+/**
+ * Where the workspace links in `dirs` actually point.
+ *
+ * One level deep, plus one level inside a `@scope/` directory — the shape
+ * a package manager writes. Anything already inside a granted directory
+ * is dropped; what is left is a sibling project's real path.
+ */
+async function linkedDeps(dirs: readonly string[]): Promise<string[]> {
+  const out = new Set<string>()
+  const scan = async (dir: string, depth: number): Promise<void> => {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+    for (const e of entries) {
+      const full = path.join(dir, e.name)
+      if (e.isSymbolicLink()) {
+        const target = await realpath(full).catch(() => undefined)
+        if (
+          target !== undefined &&
+          !dirs.some((d) => target === d || target.startsWith(d + path.sep))
+        ) {
+          out.add(target)
+        }
+      } else if (depth === 0 && e.isDirectory() && e.name.startsWith('@')) {
+        await scan(full, 1)
+      }
+    }
+  }
+  await Promise.all(dirs.map((d) => scan(d, 0)))
+  return [...out]
+}
+
+/**
+ * Ensure each declared output path exists on the host as either an
+ * empty file (for literal output specs) or a directory (for globbed
+ * specs) so bwrap's --bind can find a real fs entry to mount. Without
+ * this, writes inside the sandbox to a non-existent allowWrite path
+ * silently disappear (bwrap creates a tmpfs that evaporates on exit).
+ *
+ * `cleanOutputs` ran just before this in the cache-enabled path, so
+ * we know any stale content was wiped; what's left is to materialize
+ * the empty skeleton.
+ */
+async function prepareOutputsForBind(
+  projectDir: string,
+  outputs: readonly string[],
+): Promise<void> {
+  for (const g of outputs) {
+    const hasWildcard = /[*?[\]]/.test(g)
+    // A grant OUTSIDE the project is the user's own path — never joined
+    // onto the project dir, which would create a literal `~` there. Its
+    // directory is still created when the grant is a glob, because then
+    // the static prefix is unambiguously a directory and bwrap cannot
+    // bind one that does not exist: `~/.bun/install/cache/**` on a runner
+    // that has never populated it silently granted nothing, and the task
+    // failed with the tool's own confusing message (`bun build --compile`
+    // reported a network error for an unwritable cache; 2026-09-05).
+    if (path.isAbsolute(g) || g.startsWith('~')) {
+      if (!hasWildcard) continue
+      const abs = expandHome(staticPrefix(g))
+      await mkdir(abs, { recursive: true }).catch(() => undefined)
+      continue
+    }
+    if (hasWildcard) {
+      const abs = path.join(projectDir, staticPrefix(g))
+      await mkdir(abs, { recursive: true })
+    } else {
+      const abs = path.join(projectDir, g)
+      // Whatever is already there is what the task meant — a grant on the
+      // project dir itself is a directory, and touching it as a file is
+      // an EISDIR, not a missing bind.
+      if (await stat(abs).catch(() => undefined)) continue
+      await mkdir(path.dirname(abs), { recursive: true })
+      await Bun.write(abs, '')
+    }
+  }
+}
+
+/** `~/x` against the user's home; anything else unchanged. */
+function expandHome(p: string): string {
+  return p.startsWith('~') ? path.join(homedir(), p.slice(1)) : p
+}

package/src/orchestrator/save-lane.ts

@@ -0,0 +1,47 @@
+// The save lane: a miss's cache save runs OFF the execution slot. The
+// slot is CPU-shaped (`--concurrency`) and the save is not — pack, write,
+// rename and one index transaction, ~2.5 ms of mostly I/O per one-file
+// artifact against ~5 ms of execution on the 1,000-project bench
+// (2026-09-10) — so holding the slot for it serialized I/O behind CPU.
+// A bounded number run at once (memory: each pack holds an artifact's
+// bytes), the run drains them before the upload drain, and a save that
+// fails degrades to a miss next time, said once — the task's work ran.
+
+export interface SaveLane {
+  /**
+   * Start `save` now if the lane has room, else when one finishes. Resolves
+   * once the save has settled — a failure is reported and resolves too —
+   * for the one reader that must wait for the entry: a duplicate of the
+   * same task in another run (admission's in-flight join).
+   */
+  defer(save: () => Promise<void>): Promise<void>
+  /** Settle every deferred save, started or queued. */
+  drain(): Promise<void>
+}
+
+export function createSaveLane(cap: number, onError: (err: unknown) => void): SaveLane {
+  const queue: Array<{ save: () => Promise<void>; settle: () => void }> = []
+  const running = new Set<Promise<void>>()
+  const start = (save: () => Promise<void>, settle: () => void): void => {
+    const p = save()
+      .catch(onError)
+      .then(() => {
+        running.delete(p)
+        settle()
+        const next = queue.shift()
+        if (next !== undefined) start(next.save, next.settle)
+      })
+    running.add(p)
+  }
+  return {
+    defer(save) {
+      return new Promise<void>((settle) => {
+        if (running.size < cap) start(save, settle)
+        else queue.push({ save, settle })
+      })
+    },
+    async drain() {
+      while (running.size > 0) await Promise.all([...running])
+    },
+  }
+}

package/src/orchestrator/signals.ts

@@ -0,0 +1,111 @@
+// A SIGINT/SIGTERM mid-run forwards SIGTERM to everything live, waits a
+// bounded grace for it to go, SIGKILLs what is still there, closes the
+// cache handle, and exits 128+signo (130/143). Without the forward, a
+// programmatic signal to the vx process alone (CI cancellation,
+// `kill <pid>`) orphans every running child — terminal Ctrl-C only worked
+// via process-group propagation. Without the escalation (added
+// 2026-09-10) a child that traps TERM — a dev server mid-cleanup, a test
+// runner that ignores it — outlived the run that owned it: vx exited
+// 143 and left it running under init. Split from run.ts on 2026-09-10
+// (pure motion); the registries it reads stay with `run()`, which hands
+// them to the runner around every spawn.
+
+import { signalExitCode } from '../exec/index.js'
+import { killGraceMs } from '../util/index.js'
+import type { Logger } from './logger.js'
+
+/**
+ * How long a SIGTERMed child gets before SIGKILL on the way out. The
+ * end-of-run persistent shutdown grants the same two seconds; both read
+ * `VX_KILL_GRACE_MS` (util/settle.ts) so the suites that prove the
+ * escalation do not wait the full grace.
+ */
+export const SIGNAL_SHUTDOWN_GRACE_MS = 2000
+
+type Child = ReturnType<typeof Bun.spawn>
+
+/**
+ * SIGTERM every child `live()` returns, wait the grace for them to go,
+ * then SIGKILL whatever `live()` returns NOW — re-read, because the run
+ * loop may still be dispatching during the grace and a child spawned
+ * after the first sweep must not survive the second. Resolves once the
+ * survivors are reaped. The one teardown behind the process-signal
+ * handler below, `RunOptions.signal`, and the foreground keep-alive.
+ */
+export async function terminateChildren(
+  live: () => Child[],
+  graceMs: number = killGraceMs(SIGNAL_SHUTDOWN_GRACE_MS),
+): Promise<void> {
+  const children = live()
+  for (const child of children) child.kill('SIGTERM')
+  const allExited = Promise.allSettled(children.map((c) => c.exited))
+  let graceTimer: ReturnType<typeof setTimeout> | undefined
+  // Not unref'd: it is what guarantees progress when every other handle
+  // has drained, and the grace is bounded either way.
+  await Promise.race([
+    allExited,
+    new Promise<void>((resolve) => {
+      graceTimer = setTimeout(resolve, graceMs)
+    }),
+  ])
+  if (graceTimer !== undefined) clearTimeout(graceTimer)
+  const survivors = live()
+  for (const child of survivors) child.kill('SIGKILL')
+  await Promise.allSettled(survivors.map((c) => c.exited))
+}
+
+export interface SignalForwarding {
+  /** Detach the handlers — in `run()`'s finally, so repeated runs never stack listeners. */
+  remove(): void
+}
+
+export function forwardSignals(args: {
+  /** `RunOptions.handleSignals` — an embedder that owns the process's signals opts out. */
+  enabled: boolean
+  log: Logger
+  cache: { close(): void }
+  /** In-flight children; the runner adds and removes each around its spawn. */
+  liveChildren: ReadonlySet<Child>
+  /** Ready persistent tasks the orchestrator owns until the graph finishes. */
+  persistentRegistry: ReadonlyMap<string, Child>
+}): SignalForwarding {
+  const everyChild = (): Child[] => [...args.liveChildren, ...args.persistentRegistry.values()]
+  const exit = (signal: 'SIGINT' | 'SIGTERM'): never => {
+    for (const child of everyChild()) child.kill('SIGKILL')
+    try {
+      args.cache.close()
+    } catch {
+      // double-close race with the normal path; we're exiting anyway
+    }
+    process.exit(signalExitCode(signal))
+  }
+  let stopping: 'SIGINT' | 'SIGTERM' | undefined
+  const onSignal = (signal: 'SIGINT' | 'SIGTERM'): void => {
+    // A second signal during the grace is the user saying "now": SIGKILL
+    // and go. The exit code stays the first signal's — that is the one
+    // that ended the run.
+    if (stopping !== undefined) exit(stopping)
+    stopping = signal
+    // Clear the live worker/status region BEFORE exiting so a TTY isn't
+    // left with a frozen region in the scrollback. runEnd is idempotent
+    // and a no-op for non-TTY loggers.
+    try {
+      args.log.runEnd?.()
+    } catch {
+      // teardown must not throw on the way out
+    }
+    void terminateChildren(everyChild).then(() => exit(signal))
+  }
+  const onSigint = (): void => onSignal('SIGINT')
+  const onSigterm = (): void => onSignal('SIGTERM')
+  if (args.enabled) {
+    process.on('SIGINT', onSigint)
+    process.on('SIGTERM', onSigterm)
+  }
+  return {
+    remove: () => {
+      process.off('SIGINT', onSigint)
+      process.off('SIGTERM', onSigterm)
+    },
+  }
+}

package/src/orchestrator/stable-keys.ts

@@ -13,6 +13,7 @@
 
 import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import type { CacheLayer, GitFilesCache } from '../cache/index.js'
+import { normalizeGlob, relPosix } from '../util/index.js'
 import { computeGroupHash, computeTaskHash, type HashCache } from './task-hash.js'
 
 export interface DeriveStableKeysArgs {
@@ -60,6 +61,14 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   const outputProjectsById = new Map<string, ReadonlySet<string>>()
   const wsOutputUpstreamById = new Map<string, boolean>()
   const stableKeys: StableKey[] = []
+  // Workspace-relative project dirs, for the reach test of a
+  // `workspaceFiles` reader against its upstream producers.
+  const dirByProject = new Map<string, string>()
+  for (const node of args.nodes.values()) {
+    if (!dirByProject.has(node.projectName)) {
+      dirByProject.set(node.projectName, relPosix(args.workspaceRoot, node.projectDir))
+    }
+  }
 
   for (const id of order) {
     const node = args.nodes.get(id)!
@@ -106,7 +115,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
 
     const unstable =
       node.deps.some((d) => unstableById.has(d)) ||
-      dependsOnSiblingOutputs(node, outputProjects, wsOutputUpstream)
+      dependsOnSiblingOutputs(node, outputProjects, wsOutputUpstream, dirByProject)
     if (unstable) unstableById.add(id)
 
     const cacheEnabled = node.config.cache !== undefined
@@ -169,6 +178,7 @@ export function dependsOnSiblingOutputs(
   node: TaskNode,
   upstreamOutputProjects: ReadonlySet<string>,
   hasWsOutputUpstream: boolean,
+  dirByProject?: ReadonlyMap<string, string>,
 ): boolean {
   const cache = node.config.cache
   // A cache-disabled task has no key to prefetch anyway; treat as
@@ -184,8 +194,55 @@ export function dependsOnSiblingOutputs(
   // `app` read `gen/**` project-relative), so the mere presence of a
   // workspace-output producer upstream makes the key preliminary.
   if (hasWsOutputUpstream) return true
-  const readsWorkspaceFiles = (cache.inputs?.workspaceFiles?.length ?? 0) > 0
-  if (readsWorkspaceFiles && upstreamOutputProjects.size > 0) return true
+  const wsInputs = cache.inputs?.workspaceFiles ?? []
+  if (wsInputs.length > 0 && upstreamOutputProjects.size > 0) {
+    // Without the dirs the old answer stands: a workspace reader over any
+    // producer is preliminary. With them, only a reader whose globs can
+    // reach a producer's directory is. A Turbo-mapped workspace gives every
+    // task its `globalDependencies` as root literals (`turbo.json`), which
+    // reach no package — classing those as unstable hashed medusa's 83
+    // tasks twice and probed 76 of them lazily (2026-09-11).
+    if (dirByProject === undefined) return true
+    const dirs: string[] = []
+    for (const p of upstreamOutputProjects) {
+      const d = dirByProject.get(p)
+      if (d === undefined) return true
+      dirs.push(d)
+    }
+    return workspaceInputsReach(wsInputs, dirs)
+  }
+  return false
+}
+
+/**
+ * Can any positive `workspaceFiles` entry match a path inside one of
+ * `dirs` (workspace-relative project dirs)? An entry's reach is its
+ * literal prefix — the segments before the first one holding a glob
+ * metacharacter — and it reaches a dir when either is the other's
+ * ancestor or equal. An entry with no literal prefix (`**\/*`) reaches
+ * everything. Conservative on every unknown spelling.
+ */
+export function workspaceInputsReach(
+  workspaceFiles: readonly string[],
+  dirs: readonly string[],
+): boolean {
+  for (const raw of workspaceFiles) {
+    if (raw.startsWith('!')) continue
+    const entry = normalizeGlob(raw)
+    const segments = entry.split('/')
+    const literal: string[] = []
+    for (const seg of segments) {
+      if (/[*?[\]{}]/.test(seg)) break
+      literal.push(seg)
+    }
+    if (literal.length === 0) return true
+    const prefix = literal.join('/')
+    for (const dir of dirs) {
+      if (dir === '' || dir === '.') return true
+      if (prefix === dir || prefix.startsWith(`${dir}/`) || dir.startsWith(`${prefix}/`))
+        return true
+    }
+  }
   return false
 }
 

package/src/orchestrator/status-line.ts

@@ -248,13 +248,14 @@ export function formatFailureLine(
   id: string,
   durationMs: number | null,
   colors: ColorSupport = NO_COLOR,
+  cacheWord: 'miss' | 'no-cache' = 'miss',
 ): string {
   return formatTaskRow(
     paint(ERROR, '◼\uFE0E', colors),
     durationMs,
     'failed',
     ERROR,
-    'miss',
+    cacheWord,
     '',
     paintPinnedId(id, colors),
     colors,