@vzn/vx 0.0.505 → 0.0.507

package/README.md

@@ -149,8 +149,6 @@ Declared in `vx.workspace.ts`; without any, vx runs and caches locally.
 | [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: a read-only MCP server for AI coding agents                         |
 | [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                          |
 
-Only `@vzn/vx` is on npm today; the plugins' first publish is pending.
-
 Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
 [architecture](packages/vx/docs/architecture.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.505",
+  "version": "0.0.507",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.505",
-    "@vzn/vx-linux-arm64": "0.0.505",
-    "@vzn/vx-darwin-x64": "0.0.505",
-    "@vzn/vx-darwin-arm64": "0.0.505"
+    "@vzn/vx-linux-x64": "0.0.507",
+    "@vzn/vx-linux-arm64": "0.0.507",
+    "@vzn/vx-darwin-x64": "0.0.507",
+    "@vzn/vx-darwin-arm64": "0.0.507"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/archive.ts

@@ -37,12 +37,21 @@
 // skipped — vx's outputs are regular files, and an artifact that claims
 // otherwise silently loses the claim rather than acting on it.
 
-import { chmodSync, renameSync, statSync, utimesSync } from 'node:fs'
+import {
+  chmodSync,
+  lstatSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  utimesSync,
+} from 'node:fs'
 import { lstat, mkdir, readlink, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { UserError } from '../util/index.js'
 import { WORKSPACE_OUTPUT_PREFIX } from './layer.js'
 import { TarFormatError, type TarInput, tarEntries, tarPack, tarSize } from './tar-stream.js'
+import { ON_THREAD_MAX } from './zstd.js'
 
 /** Archive entry name carrying the per-output mode/mtime sidecar. */
 const META_ENTRY = '.vx-meta.json'
@@ -200,6 +209,9 @@ export interface PackArgs {
   within?: string
 }
 
+/** At or below this many outputs, `planArtifact` stats them on the calling thread. */
+const ON_THREAD_STATS = 32
+
 /** A packed artifact's plan: its entries with their stats, and the tar's exact size. */
 export interface ArtifactPlan {
   inputs: TarInput[]
@@ -216,6 +228,12 @@ export interface ArtifactPlan {
  */
 export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   const meta: MetaFile = { version: 1, files: {} }
+  // A few outputs are stat'ed on this thread: a pool round trip per stat
+  // cost more than the stat. Many go to the pool together, as before.
+  const few = args.outputs.size <= ON_THREAD_STATS
+  const lstatOf = few ? async (p: string) => lstatSync(p) : lstat
+  const statOf = few ? async (p: string) => statSync(p) : stat
+  const realpathOf = few ? async (p: string) => realpathSync(p) : realpath
   let withinReal: Promise<string> | undefined
   // Where this artifact's own non-link outputs really are: a link to one of
   // them packs bytes the task wrote itself. A root-anchored output tree is
@@ -225,7 +243,7 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   const ownOutputs = (): Promise<Set<string>> =>
     (ownReal ??= Promise.all(
       [...args.outputs.values()].map(async (abs) =>
-        (await lstat(abs)).isSymbolicLink() ? null : realpath(abs),
+        (await lstatOf(abs)).isSymbolicLink() ? null : realpathOf(abs),
       ),
     ).then((all) => new Set(all.filter((p): p is string => p !== null))))
   if (args.key !== undefined) meta.key = args.key
@@ -255,11 +273,11 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       // lstat, so a regular file costs no second call; only a link is
       // resolved, and its body is read from the path this check resolved.
       let src = abs
-      let st = await lstat(abs)
+      let st = await lstatOf(abs)
       if (st.isSymbolicLink()) {
-        src = await realpath(abs).catch(dangling)
+        src = await realpathOf(abs).catch(dangling)
         if (args.within !== undefined) {
-          withinReal ??= realpath(args.within)
+          withinReal ??= realpathOf(args.within)
           const root = await withinReal
           if (!src.startsWith(root + path.sep) && !(await ownOutputs()).has(src)) {
             throw new UserError(
@@ -267,7 +285,7 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
             )
           }
         }
-        st = await stat(src).catch(dangling)
+        st = await statOf(src).catch(dangling)
       }
       if (!st.isFile()) {
         throw new UserError(
@@ -340,9 +358,16 @@ async function* summed(inputs: readonly TarInput[]): AsyncGenerator<TarInput> {
  * otherwise (measured 2026-09-03: 238 → 293 ms per 1 000 saves).
  */
 export async function packArtifactBytes(plan: ArtifactPlan): Promise<Uint8Array> {
+  // A small artifact's files are read on this thread (`ON_THREAD_MAX`).
+  const onThread = plan.size <= ON_THREAD_MAX
   const inputs = await Promise.all(
     plan.inputs.map(async (i) =>
-      i.body instanceof Blob ? { ...i, body: await i.body.bytes() } : i,
+      i.body instanceof Blob
+        ? {
+            ...i,
+            body: onThread ? readFileSync((i.body as Bun.BunFile).name!) : await i.body.bytes(),
+          }
+        : i,
     ),
   )
   const out = new Uint8Array(plan.size)

package/src/cache/cache.ts

@@ -88,7 +88,9 @@ import {
   bytesOf,
   decodedTar,
   MAX_DECOMPRESSED_ARTIFACT_BYTES,
+  oneChunk,
   STREAM_DECODE_FROM,
+  zstdCompress,
   zstdEncoder,
 } from './zstd.js'
 import { ConfigEvalTable } from './config-evals.js'
@@ -1296,7 +1298,7 @@ export class Cache implements CacheLayer {
     // again in `writeArtifactAndIndex` cost every save two thread-pool
     // round trips for an EEXIST and a stat (item 630).
     const endPack = span('save: pack')
-    const compressed = await this.packArtifactToTemp(this.tempPath(args.hash), args).catch(
+    const packed = await this.packArtifactToTemp(this.tempPath(args.hash), args).catch(
       (err: unknown) => {
         // A save that could not open an output names the limit, not only
         // the file, which is fine (A-39).
@@ -1310,12 +1312,17 @@ export class Cache implements CacheLayer {
     )
     endPack()
     await this.guard(() =>
-      this.writeArtifactAndIndex(args.hash, compressed, {
-        taskId: args.entry.taskId,
-        command: args.entry.command,
-        durationMs: args.entry.durationMs,
-        ...(args.inputComponents !== undefined ? { inputComponents: args.inputComponents } : {}),
-      }),
+      this.writeArtifactAndIndex(
+        args.hash,
+        'tar' in packed ? packed.compressed : packed,
+        {
+          taskId: args.entry.taskId,
+          command: args.entry.command,
+          durationMs: args.entry.durationMs,
+          ...(args.inputComponents !== undefined ? { inputComponents: args.inputComponents } : {}),
+        },
+        'tar' in packed ? packed.tar : undefined,
+      ),
     )
   }
 
@@ -1425,8 +1432,7 @@ export class Cache implements CacheLayer {
     // layout is predictable: a successful read finds `stdout` and
     // zero-or-more `outputs/<rel>` / `workspace-outputs/<rel>` entries.
     const plan = await this.planWithin(args)
-    if (plan.size <= STREAM_DECODE_FROM)
-      return await Bun.zstdCompress(await packArtifactBytes(plan))
+    if (plan.size <= STREAM_DECODE_FROM) return await zstdCompress(await packArtifactBytes(plan))
     return bytesOf(packArtifactStream(plan).pipeThrough(zstdEncoder()))
   }
 
@@ -1466,10 +1472,12 @@ export class Cache implements CacheLayer {
   private async packArtifactToTemp(
     tmpPath: string,
     args: Parameters<Cache['packArtifact']>[0],
-  ): Promise<Uint8Array | { tmpPath: string }> {
+  ): Promise<{ compressed: Uint8Array; tar: Uint8Array } | { tmpPath: string }> {
     const plan = await this.planWithin(args)
-    if (plan.size <= STREAM_DECODE_FROM)
-      return await Bun.zstdCompress(await packArtifactBytes(plan))
+    if (plan.size <= STREAM_DECODE_FROM) {
+      const tar = await packArtifactBytes(plan)
+      return { compressed: await zstdCompress(tar), tar }
+    }
     const sink = Bun.file(tmpPath).writer()
     try {
       for await (const chunk of packArtifactStream(plan).pipeThrough(zstdEncoder())) {
@@ -1505,6 +1513,11 @@ export class Cache implements CacheLayer {
     hash: string,
     compressed: Uint8Array | { tmpPath: string },
     meta: IngestMeta,
+    /**
+     * The tar `compressed` was made from, when this process packed it: it is
+     * scanned as is rather than decoded back out of the bytes just encoded.
+     */
+    tar?: Uint8Array,
   ): Promise<void> {
     // Validate BEFORE anything touches the final path. `ingest()` feeds
     // us a temp of network bytes; a truncated/garbage body that went live first
@@ -1527,6 +1540,8 @@ export class Cache implements CacheLayer {
       const endWrite = span('save: write temp')
       // A write that fails part-way (a full disk) leaves the temp behind,
       // and a fresh one is an orphan only an hour on (A-14).
+      // Off this thread even when small: a file's creation on the main
+      // thread cost more CPU and wall than the round trip (A/B, 2026-10-04).
       await writeFile(tmpPath, compressed).catch(async (err: unknown) => {
         await unlink(tmpPath).catch(() => undefined)
         throw err
@@ -1546,7 +1561,9 @@ export class Cache implements CacheLayer {
           ? compressed
           : Bun.file(tmpPath)
       const endScan = span('save: scan')
-      scanned = await scanArtifact(await decodedTar(source, hash, this.artifactCeiling))
+      scanned = await scanArtifact(
+        tar !== undefined ? oneChunk(tar) : await decodedTar(source, hash, this.artifactCeiling),
+      )
       endScan()
       // v17 invariant: every artifact carries a `stdout` entry. Its
       // absence means the bytes decompressed but aren't a vx artifact.

package/src/cache/zstd.ts

@@ -92,8 +92,11 @@ async function zstdDecompressBounded(
   hash: string,
   cap: number = MAX_DECOMPRESSED_ARTIFACT_BYTES,
 ): Promise<Uint8Array> {
-  assertDeclaredSize(compressed, hash, cap)
-  const out = await Bun.zstdDecompress(compressed)
+  const declared = assertDeclaredSize(compressed, hash, cap)
+  const out =
+    declared !== null && declared <= BigInt(ON_THREAD_MAX)
+      ? Bun.zstdDecompressSync(compressed)
+      : await Bun.zstdDecompress(compressed)
   // UNREACHABLE as written, and kept deliberately. `assertDeclaredSize`
   // above refuses any frame DECLARING more than the cap, Bun refuses a
   // frame whose declaration disagrees with its body ("Decompression
@@ -121,6 +124,22 @@ function assertDeclaredSize(
   return declared
 }
 
+/**
+ * At or below this many bytes an artifact's one-call codec and file I/O
+ * run on the calling thread. Each async call is a thread-pool round trip
+ * (a futex wake, an eventfd write, an epoll turn) that cost more CPU than
+ * the work itself for a one-file artifact, several times per save and
+ * per restore.
+ */
+export const ON_THREAD_MAX = 256 * 1024
+
+/** `Bun.zstdCompress`, on this thread when the input is small (`ON_THREAD_MAX`). */
+export async function zstdCompress(bytes: Uint8Array): Promise<Uint8Array> {
+  return bytes.byteLength <= ON_THREAD_MAX
+    ? Bun.zstdCompressSync(bytes)
+    : await Bun.zstdCompress(bytes)
+}
+
 /** Compressed artifacts above this size are decoded as a stream, on restore and on ingest. */
 export const STREAM_DECODE_FROM = 4 * 1024 * 1024
 
@@ -137,7 +156,8 @@ export async function bytesOf(stream: ReadableStream<Uint8Array>): Promise<Uint8
 export const zstdEncoder = (): TransformStream<Uint8Array, Uint8Array> =>
   new CompressionStream('zstd') as unknown as TransformStream<Uint8Array, Uint8Array>
 
-const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
+/** Bytes in memory as a one-chunk stream, for a reader that takes a stream. */
+export const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
   new ReadableStream({
     start(c) {
       c.enqueue(bytes)

package/src/exec/kill-tree.ts

@@ -11,7 +11,7 @@
 // takes even that.
 
 import { closeSync, readdirSync, readFileSync, writeSync } from 'node:fs'
-import { executablePath, procfsIsOwn } from '../util/index.js'
+import { procfsIsOwn, taskShell } from '../util/index.js'
 
 export type Child = ReturnType<typeof Bun.spawn>
 
@@ -79,7 +79,7 @@ function startGuard(): void {
   if (guardFd !== undefined) return
   guardFd = null
   try {
-    const guard = Bun.spawn([executablePath('sh'), '-c', GUARD_SCRIPT], {
+    const guard = Bun.spawn([taskShell(), '-c', GUARD_SCRIPT], {
       argv0: 'vx-group-guard',
       stdio: ['ignore', 'ignore', 'ignore', 'pipe'],
       // Out of vx's group, so a Ctrl-C at the terminal leaves it to the

package/src/exec/sandbox-runtime.ts

@@ -60,6 +60,7 @@ import {
 import {
   BUN_GLOB_WILDCARDS,
   executablePath,
+  taskShell,
   grantPrefix,
   isTmpdirRefusal,
   procfsIsOwn,
@@ -236,7 +237,7 @@ async function trySandboxedTrue(
       undefined,
       weakerNested ? { enableWeakerNestedSandbox: true } : undefined,
     )
-    const proc = Bun.spawn([executablePath('sh'), '-c', wrapped], {
+    const proc = Bun.spawn([taskShell(), '-c', wrapped], {
       argv0: 'sh',
       stdout: 'ignore',
       stderr: 'pipe',
@@ -1299,7 +1300,7 @@ function ownGroupCommand(
   // `/bin/sh` is dash (item 964).
   let sh: string
   try {
-    sh = executablePath('sh')
+    sh = taskShell()
   } catch {
     return { command: `: 'vx-${tag}'; ${userCommand}`, forwards: false, traced: false }
   }
@@ -1433,15 +1434,19 @@ function wrapForTask(
   sockets: boolean,
   gitConfig: boolean,
 ): Promise<string> {
+  // macOS: the runtime runs the command under bash unless told, and an
+  // unsandboxed task runs under `taskShell()` (dash). Linux needs no word:
+  // `ownGroupCommand` already puts the task shell inside.
+  const shell = process.platform === 'darwin' ? taskShell() : undefined
   const run = perTaskRun
-  if (run === undefined) return SandboxManager.wrapWithSandbox(command, undefined, customConfig)
+  if (run === undefined) return SandboxManager.wrapWithSandbox(command, shell, customConfig)
   const turn = wrapTurn.then(() => {
     SandboxManager.updateConfig({
       ...run,
       network: { ...run.network, allowAllUnixSockets: sockets },
       filesystem: { ...run.filesystem, allowGitConfig: gitConfig },
     })
-    return SandboxManager.wrapWithSandbox(command, undefined, customConfig)
+    return SandboxManager.wrapWithSandbox(command, shell, customConfig)
   })
   wrapTurn = turn.catch(() => undefined)
   return turn
@@ -1588,11 +1593,7 @@ function spawnHostBridges(ports: readonly number[], tag: string): void {
                 detached: true,
               })
             : Bun.spawn(
-                [
-                  executablePath('sh'),
-                  '-c',
-                  `${guardLine(3)}exec ${argv.map(shellQuote).join(' ')}`,
-                ],
+                [taskShell(), '-c', `${guardLine(3)}exec ${argv.map(shellQuote).join(' ')}`],
                 { stdio: ['ignore', 'ignore', 'ignore', guard], detached: true },
               ),
         ),
@@ -1793,7 +1794,7 @@ async function runSandboxedOnce(
   try {
     // Resolved on vx's own PATH (util/which.ts), not the task's, where a
     // project's node_modules/.bin comes first.
-    const sh = executablePath('sh')
+    const sh = taskShell()
     if (straceLog) traceFd = openSync(straceLog, 'w')
     // Descriptors: 3 the signal channel the in-sandbox watcher reads, 4 the
     // guard's pipe (kill-tree.ts), TRACE_FD the trace log; a gap is 'ignore'.

package/src/orchestrator/deferred-outputs.ts

@@ -71,6 +71,10 @@ export class DeferredOutputs {
    * this throws and the caller fails the task naming the producer.
    */
   async materializeFor(node: TaskNode): Promise<void> {
+    // Nothing deferred, nothing to find: the closure walk is the size of
+    // the graph, and every task of a run without `--download=none` paid it
+    // (1.4 s of a 3,270-task cold run's main thread).
+    if (this.entries.size === 0) return
     const needed: string[] = []
     const seen = new Set<string>()
     // Pre-order on an explicit stack of dependency lists: a closure is as

package/src/orchestrator/execute-task.ts

@@ -801,6 +801,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       if (c.kind === 'env' && named.includes(c.name) && !secretNamed(c.name))
         c.hash = MASKED + c.hash
   const inputs: TaskInputs | undefined = described?.inputs
+  // A plugin may keep the request past the run (the cache closed): it gets
+  // the upstream outputs read now. Only the local floor leaves them unread.
+  if (inputs !== undefined && !isLocalExecutor(args.executor)) void inputs.upstream
   // A declared input set that resolves to NOTHING is the quiet stale hit:
   // the key stops moving with this project's source and every later run
   // is a hit. Almost always a glob written against the wrong directory

package/src/orchestrator/task-hash.ts

@@ -173,15 +173,21 @@ export async function describeTaskInputs(
   )
   // Output lists come from the local index — one SELECT for every upstream
   // entry. An upstream with no entry (non-cacheable) contributes an empty list.
-  const rows = args.cache.loadOutputFilesBatch(graft.map((g) => g.hash))
-  const upstream = graft.map((g) => {
-    const outputs = (rows.get(g.hash) ?? []).map((r) =>
-      r.path.startsWith(WORKSPACE_OUTPUT_PREFIX)
-        ? r.path.slice(WORKSPACE_OUTPUT_PREFIX.length)
-        : relPosix(input.workspaceRoot, path.join(g.projectDir, r.path)),
-    )
-    return { taskId: g.taskId, hash: g.hash, outputs }
-  })
+  // Read on first access: the local floor never reads it, and its every
+  // miss paid a query over the whole closure (execute-task reads it up
+  // front for a plugin executor).
+  const listUpstream = (): TaskInputs['upstream'] => {
+    const rows = args.cache.loadOutputFilesBatch(graft.map((g) => g.hash))
+    return graft.map((g) => {
+      const outputs = (rows.get(g.hash) ?? []).map((r) =>
+        r.path.startsWith(WORKSPACE_OUTPUT_PREFIX)
+          ? r.path.slice(WORKSPACE_OUTPUT_PREFIX.length)
+          : relPosix(input.workspaceRoot, path.join(g.projectDir, r.path)),
+      )
+      return { taskId: g.taskId, hash: g.hash, outputs }
+    })
+  }
+  let upstream: TaskInputs['upstream'] | undefined
   return {
     hash,
     facts,
@@ -194,7 +200,9 @@ export async function describeTaskInputs(
         command,
         output,
       })),
-      upstream,
+      get upstream() {
+        return (upstream ??= listUpstream())
+      },
       packageJsonDigest: input.projectPackageJsonHash,
       configDigest: input.taskConfigHash,
       workspaceFingerprint: input.workspaceFingerprint,

package/src/util/index.ts

@@ -52,7 +52,7 @@ export { splitTaskId } from './task-id.js'
 export { editDistance, listed, nearMatches, nearest } from './edit-distance.js'
 export { CORE_VERBS, MOVED_VERBS } from './verbs.js'
 export { isUnsupportedBun, MIN_BUN, unsupportedBunMessage } from './bun-version.js'
-export { executablePath, shellArgv } from './which.js'
+export { executablePath, shellArgv, taskShell } from './which.js'
 export { procfsIsOwn } from './procfs.js'
 export { realPath } from './real-path.js'
 export {

package/src/util/which.ts

@@ -47,9 +47,31 @@ export function executablePath(name: string): string {
   return at
 }
 
+let dashMissedOn: string | undefined
+
+/**
+ * The shell vx runs commands in: `dash` on macOS when vx's PATH has it,
+ * else `sh` on vx's PATH. macOS's `/bin/sh` is a stub that execs bash, two
+ * images for one shell, and bash where Linux runs dash, so a command read
+ * one way on a Mac and another on Linux CI (owner, 2026-10-04).
+ */
+export function taskShell(): string {
+  if (process.platform === 'darwin') {
+    const PATH = process.env['PATH'] ?? ''
+    if (dashMissedOn !== PATH) {
+      try {
+        return executablePath('dash')
+      } catch {
+        dashMissedOn = PATH
+      }
+    }
+  }
+  return executablePath('sh')
+}
+
 /**
  * The argv that runs `script` in the task shell: `sh -c`.
  */
 export function shellArgv(script: string): string[] {
-  return [executablePath('sh'), '-c', script]
+  return [taskShell(), '-c', script]
 }

package/src/workspace/project-loader.ts

@@ -738,7 +738,9 @@ const BUN_MEMBERS_VX_READS: readonly PropertyKey[] = [
   'which',
   'write',
   'zstdCompress',
+  'zstdCompressSync',
   'zstdDecompress',
+  'zstdDecompressSync',
 ]
 
 /** A descriptor the snapshot did not read. */