@vzn/vx 0.0.594 → 0.0.596

package/src/config.ts

@@ -292,10 +292,10 @@ export interface SandboxConfig {
 
 /** The denials `sandbox.ignore` can leave out of the report: patterns per class. */
 export interface SandboxIgnore {
-  read?: string[]
-  write?: string[]
-  systemInfo?: string[]
-  network?: string[]
+  read?: readonly string[]
+  write?: readonly string[]
+  systemInfo?: readonly string[]
+  network?: readonly string[]
 }
 
 export interface SandboxGrants {
@@ -304,29 +304,29 @@ export interface SandboxGrants {
    * `node_modules`, NOT `cache.inputs.files`. A task that reads its own
    * source in the sandbox says so here.
    */
-  read?: string[]
+  read?: readonly string[]
   /**
    * Writable paths or globs. The task can write NOTHING without these:
    * declaring `cache.outputs.files` grants no write, and a task whose
    * only declaration is its outputs writes into a tmpfs that evaporates
    * (vx then warns that `cache.outputs` matched no files).
    */
-  write?: string[]
+  write?: readonly string[]
   /**
    * Reachable domains, `['*.example.com']` a pattern. The proxy is the
    * run's: it filters every sandboxed task against the union of the lists
    * the run's tasks declare, so `true` adds no domain and reaches only
    * those (none in a run with no list). Omitted adds none either.
    */
-  network?: true | string[]
+  network?: true | readonly string[]
   /**
    * Kernel information the task may query, by info type — the name that
    * appears in a denial, e.g. `vfs.disk-space` (every Bun and git process
    * probes free space at startup).
    */
-  systemInfo?: string[]
+  systemInfo?: readonly string[]
   /** Unix socket paths the task may connect to. `true` allows any. */
-  unixSockets?: true | string[]
+  unixSockets?: true | readonly string[]
   /**
    * Bind and reach localhost ports — a test that boots a server for
    * itself. A port LIST additionally makes those ports reachable from
@@ -335,9 +335,9 @@ export interface SandboxGrants {
    * namespace, each listed port is bridged out to the host's loopback;
    * on macOS the host already sees them and the list means `true`.
    */
-  localBinding?: boolean | number[]
+  localBinding?: boolean | readonly number[]
   /** macOS: Mach service names the task may look up. */
-  machLookup?: string[]
+  machLookup?: readonly string[]
   /** Acquire a TTY. Rare outside interactive tools. */
   pty?: boolean
   /** Write to `.git/config`. Most build tools should not. */
@@ -346,7 +346,7 @@ export interface SandboxGrants {
 
 export interface SandboxDenials {
   /** Domains blocked even if `allow.network` would admit them. */
-  network?: string[]
+  network?: readonly string[]
 }
 
 export interface ExecConfig {
@@ -458,7 +458,7 @@ export interface ExecEnv {
    * folded into the cache key — for things like CI flags, regional
    * vars, secrets that change between machines without affecting output.
    */
-  passThrough?: string[]
+  passThrough?: readonly string[]
   /**
    * Explicit `name: value` pairs. The values are set on the child AND
    * folded into the cache key (they are literal in your config, captured
@@ -471,7 +471,7 @@ export interface ExecEnv {
    * hold `TOKEN`, `SECRET`, `KEY`, `PASSWORD`, `PASSWD` or `CREDENTIAL`
    * are masked without it; this reaches `GH_PAT`, `NPM_AUTH`.
    */
-  secret?: string[]
+  secret?: readonly string[]
 }
 
 export interface CacheConfig {
@@ -488,7 +488,7 @@ export interface CacheOutputs {
    * Outputs are not filtered through gitignore — typical artifact dirs
    * like `dist/` and `coverage/` are captured normally even when ignored.
    */
-  files: string[]
+  files: readonly string[]
   /**
    * Files produced OUTSIDE the project dir, as workspace-root-relative
    * globs (the Turbo `$TURBO_ROOT$` / Nx `{workspaceRoot}` escape
@@ -500,7 +500,7 @@ export interface CacheOutputs {
    * like overlapping `files` (vx cleans declared outputs before a run
    * and before a restore, so the second would delete the first's).
    */
-  workspaceFiles?: string[]
+  workspaceFiles?: readonly string[]
 }
 
 export interface CacheInputs {
@@ -510,11 +510,11 @@ export interface CacheInputs {
    * project files" (gitignore-aware), or narrow as needed. An empty
    * array means no file inputs at all.
    *
-   * Declared outputs and any nested-project files are excluded
-   * automatically — a task cannot invalidate itself, and cannot read
-   * across project boundaries.
+   * Declared outputs (both `outputs` fields) and any nested-project
+   * files are excluded automatically — a task cannot invalidate itself,
+   * and cannot read across project boundaries.
    */
-  files: string[]
+  files: readonly string[]
   /**
    * Workspace-root-relative globs (the Turbo `$TURBO_ROOT$` / Nx
    * `{workspaceRoot}` equivalent), for inputs that live outside the
@@ -525,10 +525,10 @@ export interface CacheInputs {
    * NO project-boundary rule applies: these globs may match files
    * inside other projects' directories. Deliberate escape hatch —
    * prefer project-relative `files` declarations where possible.
-   * Declared `outputs.workspaceFiles` are excluded automatically (a
-   * task cannot invalidate itself).
+   * Declared outputs (both `outputs` fields) are excluded
+   * automatically (a task cannot invalidate itself).
    */
-  workspaceFiles?: string[]
+  workspaceFiles?: readonly string[]
   /**
    * Env var names whose runtime values from parent `process.env` are
    * folded into the cache key. **Independent of `exec.env`** — declaring
@@ -536,7 +536,7 @@ export interface CacheInputs {
    * invalidation. To both forward AND track, list the name in both
    * `exec.env.passThrough` and here.
    */
-  env?: string[]
+  env?: readonly string[]
   /**
    * Which upstream tasks' cache keys participate in this task's key.
    * Uses the same Turbo/Nx micro-syntax as `dependsOn`, plus
@@ -565,7 +565,7 @@ export interface CacheInputs {
    * lock, the OUTPUT is resolved live every run — correct under
    * `--frozen`. Use for project-specific runtime probes.
    */
-  runtime?: string[]
+  runtime?: readonly string[]
   /**
    * Like `runtime`, but commands run at the WORKSPACE ROOT and are
    * deduped GLOBALLY per command across the whole run — a `node -v`
@@ -573,7 +573,7 @@ export interface CacheInputs {
    * analog of `workspaceFiles`: per-task, root-anchored. Use for global
    * tool versions, OS info, etc.
    */
-  workspaceRuntime?: string[]
+  workspaceRuntime?: readonly string[]
 }
 
 /**

package/src/exec/env.ts

@@ -33,6 +33,11 @@ export const ESSENTIAL_ENV: readonly string[] = [
   'NO_COLOR',
   'CI',
   'NODE_OPTIONS',
+  // Where corepack and pnpm keep their own binaries, as HOME is: a machine
+  // path, never task output. Without them a corepack shim re-downloads its
+  // manager (offline or sandboxed: fails) and pnpm loses its global dir.
+  'COREPACK_HOME',
+  'PNPM_HOME',
 ]
 
 /**

package/src/exec/index.ts

@@ -18,6 +18,7 @@ export {
   exitSignal,
   type CaptureConfig,
   execWord,
+  maskCaptured,
 } from './runner.js'
 export {
   initSandbox,

package/src/exec/proc-sample.ts

@@ -26,7 +26,7 @@ interface Proc {
 
 /**
  * Linux's `/proc/<pid>/stat` counts CPU in USER_HZ ticks, fixed at 100 by
- * the ABI on every architecture; `tests/proc-sample.test.ts` pins it by
+ * the ABI on every architecture; `tests/proc-sample.unsafe.test.ts` pins it by
  * burning a known span and reading it back.
  */
 const TICK_MS = 10
@@ -134,12 +134,16 @@ async function psTable(): Promise<Map<number, Proc> | undefined> {
   return table
 }
 
-/** `ps`'s `time`: `[[dd-]hh:]mm:ss[.cc]`, macOS printing hundredths. */
+/**
+ * `ps`'s `time`: `[[dd-]hh:]mm:ss[.cc]`, macOS printing hundredths after
+ * the locale's decimal point — `0:01,50` under a German or French locale.
+ */
 export function psTimeMs(s: string): number | undefined {
   const dash = s.indexOf('-')
   const days = dash === -1 ? 0 : Number(s.slice(0, dash))
   const parts = s
     .slice(dash + 1)
+    .replace(',', '.')
     .split(':')
     .map(Number)
   if (parts.length < 2 || parts.some((n) => !Number.isFinite(n)) || !Number.isFinite(days)) {

package/src/exec/runner.ts

@@ -12,6 +12,7 @@ import {
   isOutOfFds,
   killGraceMs,
   OUT_OF_FDS_HINT,
+  type SecretMask,
 } from '../util/index.js'
 import {
   closeSignalChannel,
@@ -112,30 +113,49 @@ export function shellQuote(arg: string): string {
 }
 
 /**
- * Where a shell comment still open at the end of `command` starts, or -1.
- * A `#` opens one only unquoted and at the start of a word (`a#b`, `$#` and
- * `${#x}` are words), and a newline closes it.
+ * One pass over `command` as sh reads it. `comment`: where a comment still
+ * open at the end starts, or -1 — a `#` opens one only unquoted and at the
+ * start of a word (`a#b`, `$#` and `${#x}` are words), and a newline closes
+ * it. `body`: per line, is it a heredoc's body or terminator (`<<X` /
+ * `<<-'X'` / `<<\X` … `X`). One scan, because each needs the other: a
+ * `<<X` in a comment or quotes opens no heredoc, and a quote in a body
+ * opens nothing (X-110).
  */
-function trailingCommentStart(command: string): number {
+function shellShape(command: string): { comment: number; body: boolean[] } {
+  const lines = command.split('\n')
+  const body = lines.map(() => false)
+  const pending: Array<{ delim: string; tabs: boolean }> = []
   let quote = ''
   let comment = -1
   let atWordStart = true
+  let line = 0
   for (let i = 0; i < command.length; i++) {
     const c = command[i]!
-    if (comment >= 0) {
-      if (c === '\n') {
-        comment = -1
-        atWordStart = true
+    if (c === '\n') {
+      line++
+      comment = -1
+      if (quote !== '') continue
+      atWordStart = true
+      // A heredoc's body starts on the line after its `<<`.
+      while (pending.length > 0 && line < lines.length) {
+        const text = lines[line]!
+        body[line] = true
+        const open = pending[0]!
+        if ((open.tabs ? text.replace(/^\t+/, '') : text) === open.delim) pending.shift()
+        i += text.length + 1
+        line++
       }
       continue
     }
+    if (comment >= 0) continue
     if (quote === "'") {
       if (c === "'") quote = ''
       continue
     }
     if (c === '\\') {
+      if (command[i + 1] === '\n') line++
+      else atWordStart = false
       i++
-      atWordStart = false
       continue
     }
     if (quote === '"') {
@@ -151,25 +171,18 @@ function trailingCommentStart(command: string): number {
       comment = i
       continue
     }
+    if (c === '<' && command[i - 1] !== '<') {
+      const m = /^<<(-?)[ \t]*\\?(['"]?)([A-Za-z_]\w*)\2/.exec(command.slice(i, i + 256))
+      if (m !== null) {
+        pending.push({ delim: m[3]!, tabs: m[1] === '-' })
+        i += m[0].length - 1
+        atWordStart = false
+        continue
+      }
+    }
     atWordStart = /[\s;&|()<>]/.test(c)
   }
-  return comment
-}
-
-/** Per line: is it a heredoc's body or terminator (`<<X` / `<<-'X'` … `X`)? */
-function heredocLines(lines: readonly string[]): boolean[] {
-  const pending: Array<{ delim: string; tabs: boolean }> = []
-  return lines.map((line) => {
-    const open = pending[0]
-    if (open !== undefined) {
-      if ((open.tabs ? line.replace(/^\t+/, '') : line) === open.delim) pending.shift()
-      return true
-    }
-    for (const m of line.matchAll(/(?<!<)<<(?!<)(-?)\s*(['"]?)([A-Za-z_]\w*)\2/g)) {
-      pending.push({ delim: m[3]!, tabs: m[1] === '-' })
-    }
-    return false
-  })
+  return { comment, body }
 }
 
 /**
@@ -183,27 +196,34 @@ export function withForwardArgs(command: string, args: readonly string[] | undef
   // `X FWD` closed nothing and the args never reached the command (X-12).
   // They go on the last line that is a command, where `cat <<X FWD` is
   // still `cat FWD` reading the heredoc.
-  const lines = command.trimEnd().split('\n')
-  const body = heredocLines(lines)
-  if (body[lines.length - 1] === true) {
-    const last = body.lastIndexOf(false)
+  const trimmed = command.trimEnd()
+  const lines = trimmed.split('\n')
+  const shape = shellShape(trimmed)
+  if (shape.body[lines.length - 1] === true) {
+    const last = shape.body.lastIndexOf(false)
     const tail = lines.slice(last + 1).join('\n')
     return `${withForwardArgs(lines.slice(0, last + 1).join('\n'), args)}\n${tail}`
   }
   const quoted = args.map(shellQuote).join(' ')
-  let comment = trailingCommentStart(command)
+  // Of the trimmed command: the newline closing a template literal's last
+  // line closed its comment too, and `echo args: # c\n` took the args into
+  // the comment (X-110).
+  let comment = shape.comment
   if (comment < 0) {
     // A command that ends in a newline (a template literal's closing line)
     // ran the args as a command of their own: `--watch: not found`. Kept
     // when an odd run of backslashes ends it: that escapes what follows.
-    const body = command.trimEnd()
-    const escaped = (/\\+$/.exec(body)?.[0].length ?? 0) % 2 === 1
-    return `${escaped ? command : body} ${quoted}`
+    const escaped = (/\\+$/.exec(trimmed)?.[0].length ?? 0) % 2 === 1
+    return `${escaped ? command : trimmed} ${quoted}`
   }
   // A comment-only last line after a commented line: the args go before
   // the earliest comment, or they land inside it (`echo one # c\n# two`).
-  for (let c = comment; c >= 0; c = trailingCommentStart(command.slice(0, c).trimEnd())) comment = c
-  return `${command.slice(0, comment).trimEnd()} ${quoted} ${command.slice(comment)}`
+  for (let c = comment; c >= 0; c = shellShape(trimmed.slice(0, c).trimEnd()).comment) comment = c
+  // What precedes the comment may end in a heredoc: the args go where they
+  // would with no comment, never on its terminator.
+  const head = trimmed.slice(0, comment).trimEnd()
+  const gap = trimmed.slice(head.length, comment) || ' '
+  return `${withForwardArgs(head, args)}${gap}${trimmed.slice(comment)}`
 }
 
 // Any shell control/expansion character means the wrapping `sh` has real
@@ -348,6 +368,18 @@ const SIGNAL_ALIASES = new Set(['SIGIOT', 'SIGPOLL', 'SIGCLD'])
  */
 const TIMEOUT_SIGKILL_GRACE_MS = 2000
 
+/**
+ * Run `fn` one loop turn later, once the child exits already pending are
+ * read. A deadline due in the same turn as a child's exit fires BEFORE Bun
+ * reaps it: a task that exited 0 inside its timeout, seen late by a busy vx,
+ * was SIGTERMed as a zombie and failed as timed out, and a server that died
+ * before ready read as a readiness timeout (2026-10-08). A turn later the
+ * exit has settled the caller, which clears the returned timer.
+ */
+function afterPendingExits(fn: () => void): ReturnType<typeof setTimeout> {
+  return setTimeout(fn, 0)
+}
+
 /**
  * Arm a SIGTERM timeout on a spawned child. Returns a handle whose
  * `timedOut()` reports whether the timer fired — so the caller can
@@ -368,7 +400,10 @@ export function armTimeout(
   let firedAt: number | undefined
   let killTimer: ReturnType<typeof setTimeout> | undefined
   const graceMs = killGraceMs(TIMEOUT_SIGKILL_GRACE_MS)
-  const timer = setTimeout(() => {
+  let timer = setTimeout(() => {
+    timer = afterPendingExits(fire)
+  }, timeoutMs)
+  function fire(): void {
     firedAt = Date.now()
     killTree(proc, 'SIGTERM')
     // Escalate to SIGKILL after a grace: a child that TRAPS+IGNORES SIGTERM
@@ -379,7 +414,7 @@ export function armTimeout(
     // the CLI alive.
     killTimer = setTimeout(() => killTree(proc, 'SIGKILL'), graceMs)
     killTimer.unref?.()
-  }, timeoutMs)
+  }
   return {
     timedOut: () => firedAt !== undefined,
     settle: async () => {
@@ -680,7 +715,7 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   // a healthy server is never killed by a stale timer.
   let readyTimer: ReturnType<typeof setTimeout> | undefined
   if (readyRe && opts.timeoutMs !== undefined) {
-    readyTimer = setTimeout(() => {
+    const giveUp = (): void => {
       if (readyAt === undefined) {
         gaveUpAt = Date.now()
         rejectReady(
@@ -705,6 +740,9 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
         }, killGraceMs(TIMEOUT_SIGKILL_GRACE_MS))
         killTimer.unref?.()
       }
+    }
+    readyTimer = setTimeout(() => {
+      readyTimer = afterPendingExits(giveUp)
     }, opts.timeoutMs)
   }
 
@@ -883,6 +921,23 @@ export function droppedOutputLine(dropped: number): string {
   )
 }
 
+/**
+ * A captured `text` with `secrets` masked. A value the dropped middle cut
+ * left a piece at the head's end and one at the tail's start, which the
+ * whole-value mask missed, and the cache entry stored and replayed both.
+ */
+export function maskCaptured(text: string, secrets: SecretMask): string {
+  const at = text.indexOf('\n[vx] ', CAPTURE_HEAD_CHARS - 1)
+  const end = at === -1 ? -1 : text.indexOf('\n', at + 1) + 1
+  if (at === -1 || at > CAPTURE_HEAD_CHARS || !DROPPED_LINE.test(text.slice(at, end))) {
+    return secrets.mask(text)
+  }
+  const [head, tail] = secrets.maskCut(text.slice(0, at), text.slice(end))
+  return head + text.slice(at, end) + tail
+}
+
+const DROPPED_LINE = /^\n\[vx\] [\d.]+ MiB of output not kept — /
+
 const isHighSurrogate = (code: number): boolean => code >= 0xd800 && code <= 0xdbff
 
 /**
@@ -897,7 +952,10 @@ class BoundedCapture {
   private dropped = 0
 
   push(chunk: string): void {
-    if (this.head.length < CAPTURE_HEAD_CHARS) {
+    // Once the tail has begun the head is closed, even a unit short of its
+    // bound (the surrogate case below): a later short chunk fit there and
+    // was retained ahead of the chunk before it.
+    if (this.tailLen === 0 && this.head.length < CAPTURE_HEAD_CHARS) {
       let room = CAPTURE_HEAD_CHARS - this.head.length
       if (chunk.length <= room) {
         this.head += chunk

package/src/exec/sandbox-paths.ts

@@ -78,14 +78,16 @@ export function localBindingOn(c: { localBinding?: boolean | readonly number[] }
 }
 
 /**
- * Whether a sandboxed task may read `file`: it lies under a read grant,
- * a write grant or a baseline read, by its canonical path. A path no
- * grant holds is not there inside the sandbox, which the shell reports
- * as "not found" with no denial a trace can see (an `execve`).
+ * Whether a sandboxed task may read `file`: it lies under no denial (the
+ * rest of the host is mounted read-only), or under a read grant, a write
+ * grant or a baseline read, by its canonical path. A path no grant holds
+ * under a denial is not there inside the sandbox, which the shell reports
+ * as "not found": a PATH search is a stat, which the trace does not stop on.
  */
 export function sandboxReads(
   sandbox: {
     readonly baseAllowRead: readonly string[]
+    readonly baseDenyRead: readonly string[]
     readonly config: {
       readonly allowRead: readonly string[]
       readonly allowWrite: readonly string[]
@@ -94,7 +96,11 @@ export function sandboxReads(
   file: string,
 ): boolean {
   const real = toRealPath(file)
-  return [...sandbox.baseAllowRead, ...sandbox.config.allowRead, ...sandbox.config.allowWrite].some(
-    (g) => atOrUnder(real, toRealPath(g)),
+  const under = (g: string): boolean => atOrUnder(real, toRealPath(g))
+  return (
+    !sandbox.baseDenyRead.some(under) ||
+    [...sandbox.baseAllowRead, ...sandbox.config.allowRead, ...sandbox.config.allowWrite].some(
+      under,
+    )
   )
 }