@vzn/vx 0.0.639 → 0.0.641

package/docs/security.md

@@ -45,9 +45,10 @@ vulnerability), never in a public issue.
   choosing is trusted as a writer, as it is in every action cache. Use a
   store only your builds write to, or `turboCache()`'s signature key,
   which refuses an artifact a keyholder did not sign. A job you do not
-  trust (a fork's pull request) reads at most: `--cache-policy=local:rw,remote:r`,
-  or the tools' own `TURBO_REMOTE_CACHE_READ_ONLY`, `TURBO_CACHE` and
-  `NX_SKIP_REMOTE_CACHE`, which the cache plugins honour (L-34).
+  trust (a fork's pull request) reads at most: `--cache-policy=local:rw,remote:r`
+  or `cache.policy`. Core's policy alone decides; a cache plugin reads no
+  tool's own switch (`TURBO_CACHE`, `NX_SKIP_REMOTE_CACHE`) and cannot
+  narrow it.
 
 ## Cache poisoning
 
@@ -217,7 +218,7 @@ executor's error, telemetry,
 `vx show` (L-26). Values in the run history are digests under a per-store
 salt, and what follows `--` on the command line reaches telemetry as a
 count, not a quote, a secret before it masked (L-44). A remote executor (`@vzn/vx-reapi`) receives a
-task's `exec.env.define` values and the `cache.inputs.env` values its
+task's `exec.env.define` values and the `inputs.env` values its
 local child gets, never `passThrough`; those values sit unmasked in the
 action's Command, which the remote stores in its CAS, as Bazel's
 `--action_env` does, so a secret a remote task needs is trusted to that

package/launcher.sh

@@ -35,8 +35,15 @@ scope=${scope##*/}
 # directory up to the git top-level (handoff.ts workspaceFile, the same
 # rule). One hop (VX_HANDED_OFF, which also names this launcher), never to
 # this package itself (`-ef`: same inode, so a pnpm symlink counts as
-# itself). Shell tests and builtins only, no fork per level.
-if [ -z "${VX_HANDED_OFF-}" ]; then
+# itself). Shell tests and builtins only, no fork per level. `vx upgrade -g`
+# moves only this global vx, so it never hands off (owner, 2026-10-16).
+stay=
+if [ "${1-}" = upgrade ]; then
+  for a in "$@"; do
+    case $a in -g | --global) stay=1 ;; esac
+  done
+fi
+if [ -z "${VX_HANDED_OFF-}" ] && [ -z "$stay" ]; then
   d=$PWD
   while :; do
     root=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.639",
+  "version": "0.0.641",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.639",
-    "@vzn/vx-linux-arm64": "0.0.639",
-    "@vzn/vx-darwin-x64": "0.0.639",
-    "@vzn/vx-darwin-arm64": "0.0.639"
+    "@vzn/vx-linux-x64": "0.0.641",
+    "@vzn/vx-linux-arm64": "0.0.641",
+    "@vzn/vx-darwin-x64": "0.0.641",
+    "@vzn/vx-darwin-arm64": "0.0.641"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/show.json

@@ -90,24 +90,24 @@
             }
           }
         },
+        "inputs": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["files"],
+          "properties": {
+            "files": { "$ref": "#/$defs/stringList" },
+            "workspaceFiles": { "$ref": "#/$defs/stringList" },
+            "env": { "$ref": "#/$defs/stringList" },
+            "tasks": { "$ref": "#/$defs/stringList" },
+            "runtime": { "$ref": "#/$defs/stringList" },
+            "workspaceRuntime": { "$ref": "#/$defs/stringList" }
+          }
+        },
         "cache": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["inputs", "outputs"],
+          "required": ["outputs"],
           "properties": {
-            "inputs": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["files"],
-              "properties": {
-                "files": { "$ref": "#/$defs/stringList" },
-                "workspaceFiles": { "$ref": "#/$defs/stringList" },
-                "env": { "$ref": "#/$defs/stringList" },
-                "tasks": { "$ref": "#/$defs/stringList" },
-                "runtime": { "$ref": "#/$defs/stringList" },
-                "workspaceRuntime": { "$ref": "#/$defs/stringList" }
-              }
-            },
             "outputs": {
               "type": "object",
               "additionalProperties": false,

package/skills/vx/SKILL.md

@@ -90,9 +90,10 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 - Never delete or edit the cache by hand; vx repairs it itself.
 - A sandboxed task that fails on a denied path: grant that one path in
   `exec.sandbox.allow`. Never remove `sandbox` or widen it further.
-- A cached task declares its inputs (`cache.inputs.files`); if a change
-  does not re-run a task, the file is not one of its inputs. Fix the
-  config, do not force.
+- A task declares its inputs (`inputs.files`), cached or not; if a
+  change does not re-run a task, the file is not one of its inputs. Fix
+  the config, do not force. A task with no `inputs` has no key, so every
+  cached task behind it misses: give it `inputs`.
 - Every JSON shape is a JSON Schema in `node_modules/@vzn/vx/schemas/`.
 - Offline reference: `vx docs <words> --format json` searches the CLI, config
   and cache pages that ship with vx; the sections holding every word print

package/src/bin.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S bun --no-env-file --no-install
 // Wrapped in an explicit async main so `bun build --compile` accepts
 // the file. The compile target doesn't allow top-level await.
-import { handOff, localVx, vxPath } from './handoff.js'
+import { handOff, localVx, upgradesOnlyItself, vxPath } from './handoff.js'
 
 let settled = false
 
@@ -10,11 +10,13 @@ async function main(): Promise<void> {
   try {
     // Inside the try: `process.cwd()` throws EMFILE when out of descriptors,
     // and that is a one-line UserError below, not a stack.
-    const local = await localVx(
-      process.cwd(),
-      process.execPath,
-      Bun.main.startsWith('/$bunfs') || (process.argv[1] ?? '').startsWith('/$bunfs'),
-    )
+    const local = upgradesOnlyItself(argv)
+      ? null
+      : await localVx(
+          process.cwd(),
+          process.execPath,
+          Bun.main.startsWith('/$bunfs') || (process.argv[1] ?? '').startsWith('/$bunfs'),
+        )
     if (local !== null) await handOff(local, argv)
     // `vx --version` needs one leaf module; the dispatcher and the util
     // barrel it pulled in were 20 ms of its 28 (2026-10-01).

package/src/cache/archive.ts

@@ -20,11 +20,13 @@
 // holding more than a chunk. `Bun.Archive` used to do all three and
 // needed the whole tar in memory on every side — restoring a 150 MiB
 // artifact peaked at 3.2× its size, saving one at 4.7× (measured
-// 2026-09-03). Every regular entry is written beside its target under a
-// `.vx-tmp-*` name and renamed into place only once the WHOLE archive has
-// been read and every name proven safe, so a poisoned entry anywhere —
-// even the last one — leaves nothing behind but the empty directories it
-// needed, which are pruned too.
+// 2026-09-03). Every regular entry is written to the workspace's staging
+// directory (`.vx/tmp/<pid>-0/`, vx's own, never an output folder) and
+// renamed over its target only once the WHOLE archive has been read and
+// every name proven safe, so a poisoned entry anywhere — even the last
+// one — leaves nothing behind but the empty directories it needed, which
+// are pruned too, and a killed restore leaves its temps where the next
+// run sweeps them (`sweepStaging`).
 //
 // What stays here is the part no tar reader can decide for us: WHERE an
 // entry may land on disk. Every name is validated and every destination
@@ -39,14 +41,33 @@
 
 import {
   chmodSync,
+  chownSync,
+  closeSync,
+  constants,
+  existsSync,
+  fchmodSync,
+  fstatSync,
+  futimesSync,
   lstatSync,
+  openSync,
   readFileSync,
   realpathSync,
-  renameSync,
   statSync,
   utimesSync,
+  writeFileSync,
 } from 'node:fs'
-import { lstat, mkdir, readlink, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  readlink,
+  realpath,
+  rename,
+  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'
@@ -595,12 +616,15 @@ export async function extractArtifactStream(
   destDir: string,
   workspaceDest: string | undefined,
   verify?: (provided: ReadonlySet<string>) => void,
+  accept?: (name: string) => boolean,
+  /** The workspace root whose `.vx/tmp/` stages the entries; absent, each stages beside its target. */
+  stageRoot?: string,
 ): Promise<Set<string>> {
   // No `mkdir -p` of the destination here: `stage` creates each entry's
   // directory chain, the destination included, and the cache restores
   // into a project directory that exists. The eager one cost every
   // restore a thread-pool round trip for an EEXIST and a stat (item 627).
-  const x = new Extractor(destDir, workspaceDest)
+  const x = new Extractor(destDir, workspaceDest, stageRoot)
   const provided = new Set<string>()
   const headerMtime = new Map<string, number>()
   let meta: MetaFile['files'] = {}
@@ -615,6 +639,13 @@ export async function extractArtifactStream(
         continue
       }
       assertSafeName(e.name)
+      // Before anything is staged: an entry the task never declared is not
+      // this task's save, and none of the archive lands.
+      if (accept !== undefined && !accept(e.name)) {
+        throw new ArchiveSecurityError(
+          `archive entry is not one of the task's declared outputs: ${e.name}`,
+        )
+      }
       const dest = x.destFor(e.name)
       if (dest === null || dest.rel.length === 0) {
         await drain(body)
@@ -644,6 +675,9 @@ export async function extractArtifactStream(
   return provided
 }
 
+/** BSD gives every new file its directory's group, setgid or not. */
+const INHERITS_GROUP = process.platform === 'darwin'
+
 /**
  * Entries up to this size are buffered and written without waiting, so a
  * thousand tiny outputs restore in parallel; larger ones stream chunk by
@@ -674,8 +708,32 @@ async function bytesOf(body: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
 const textOf = async (body: AsyncIterable<Uint8Array>): Promise<string> =>
   utf8.decode(await bytesOf(body))
 
+/**
+ * Bring a target that already held the entry's bytes to its mode and
+ * mtime, through a descriptor opened without following a link: one
+ * planted since the compare is refused, never written through.
+ */
+function keep(s: Staged, ino: number, mode: number, mtimeMs: number | undefined): void {
+  const fd = openSync(s.target, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const st = fstatSync(fd)
+    if (st.ino !== ino || st.nlink !== 1) {
+      throw new Error(`${s.target} changed while it was restored`)
+    }
+    if ((st.mode & 0o7777) !== (mode & 0o777)) fchmodSync(fd, mode & 0o777)
+    if (mtimeMs !== undefined && Math.floor(st.mtimeMs) !== mtimeMs) {
+      const t = new Date(mtimeMs)
+      futimesSync(fd, t, t)
+    }
+  } finally {
+    closeSync(fd)
+  }
+}
+
 /** One staged entry: written at `tmp`, renamed to `target` on commit. */
 interface Staged {
+  /** `tmp` is in the staging directory, not beside `target`. */
+  staged: boolean
   name: string
   tmp: string
   target: string
@@ -683,6 +741,10 @@ interface Staged {
   created: string | undefined
   /** Written by Bun's file writer, which creates with 0664 where `writeFile` uses 0666 (before the umask). */
   streamed: boolean
+  /** The destination it is contained in. */
+  base: string
+  /** The target already holds the entry's bytes: nothing was written, and only its mode and mtime may change. */
+  same?: number
 }
 
 /**
@@ -709,6 +771,7 @@ class Extractor {
   constructor(
     private readonly destDir: string,
     private readonly workspaceDest: string | undefined,
+    private readonly stageRoot: string | undefined,
   ) {}
 
   /** Each namespace anchors at its own destination dir. */
@@ -865,7 +928,33 @@ class Extractor {
       }
       this.ensuredDirs.add(dir)
     }
-    // Write beside the target and RENAME into place. rename(2) replaces
+    // A target that already holds these bytes stays: renaming over a live
+    // file costs ~0.4 ms on ext4 (auto_da_alloc), and a hit that changed
+    // one of 2,000 outputs paid it 2,000 times. Bytes, not a stat stamp: a
+    // reproducible build gives every output one mtime (item 886).
+    if (body instanceof Uint8Array && created === undefined) {
+      const st = lstatSync(target, { throwIfNoEntry: false })
+      if (
+        st !== undefined &&
+        st.isFile() &&
+        st.nlink === 1 &&
+        st.size === body.byteLength &&
+        readFileSync(target).equals(body)
+      ) {
+        this.staged.push({
+          staged: false,
+          name,
+          tmp: '',
+          target,
+          created,
+          streamed: false,
+          base,
+          same: st.ino,
+        })
+        return
+      }
+    }
+    // Write apart from the target and RENAME into place. rename(2) replaces
     // the destination's directory ENTRY without following it, which is
     // what makes this both link-safe and concurrency-safe:
     //
@@ -882,15 +971,15 @@ class Extractor {
     //
     // A directory at the target makes the rename fail — the same
     // fail-closed outcome the plain write had.
-    // The temp is a sibling with its own short name, never `<target>.suffix`:
-    // a suffix pushed a legal name of 242–255 bytes past NAME_MAX, and the
-    // restore of a valid artifact failed with ENAMETOOLONG (item 666).
-    const tmp = path.join(
-      path.dirname(target),
-      `.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`,
-    )
+    // Staged under `.vx/tmp/`, so no output folder ever holds a temp: a
+    // reader or a key taken meanwhile saw `.vx-tmp-*` files beside the
+    // outputs, and a killed restore left them there (M, 2026-10-16).
+    const staged = this.stageRoot !== undefined
+    const tmp = staged
+      ? path.join(await stagingDir(this.stageRoot!), (tmpSeq++).toString(36))
+      : siblingTemp(target)
     const streamed = !(body instanceof Uint8Array)
-    this.staged.push({ name, tmp, target, created, streamed })
+    this.staged.push({ staged, name, tmp, target, created, streamed, base })
     if (body instanceof Uint8Array) {
       this.inflightBytes += body.byteLength
       // `writeFile`, not `Bun.write`: for a buffer this size `Bun.write`
@@ -926,12 +1015,11 @@ class Extractor {
 
   /**
    * Apply each entry's mode and mtime, then rename everything into place.
-   * Synchronous calls in batches: the three metadata calls per file are a
-   * few microseconds each on the calling thread and ~40 µs each as
-   * thread-pool round trips, and a large artifact has thousands of them
-   * (measured 2026-09-11 on payload's ui, 4,069 files: 892 ms → see the
-   * archive bench). A yield every `COMMIT_BATCH` files keeps the other
-   * restores' round trips flowing. The chmod is skipped when the mode is
+   * The metadata calls are synchronous: a few microseconds each on the
+   * calling thread and ~40 µs each as thread-pool round trips, and a large
+   * artifact has thousands of them (measured 2026-09-11 on payload's ui,
+   * 4,069 files: 892 ms → see the archive bench). The renames go to the
+   * pool, `RENAME_BATCH` at a time: each replaces a live file. The chmod is skipped when the mode is
    * the one the temp file was created with — the common case. The two
    * writers create with different modes (under umask 000: 0666 and 0664),
    * so each is stat'ed once.
@@ -940,38 +1028,107 @@ class Extractor {
     metaFor: (name: string) => [mode: number, mtimeMs: number | undefined],
   ): Promise<void> {
     await this.drain()
-    const createdModes = new Map<boolean, number>()
+    const created = new Map<boolean, { mode: number; uid: number; gid: number }>()
+    // The group a file written in place would take, by directory: a setgid
+    // directory's on Linux, every directory's on BSD/macOS. A file staged
+    // elsewhere took the staging directory's.
+    const setgid = new Map<string, number | null>()
     let n = 0
+    let renames: Promise<void>[] = []
+    const checked = new Set<string>()
     for (const s of this.staged) {
+      await this.assertStillContained(s, checked)
       const [mode, mtimeMs] = metaFor(s.name)
-      let createdMode = createdModes.get(s.streamed)
-      if (createdMode === undefined) {
-        createdMode = statSync(s.tmp).mode & 0o777
-        createdModes.set(s.streamed, createdMode)
+      if (s.same !== undefined) {
+        keep(s, s.same, mode, mtimeMs)
+        continue
+      }
+      let made = created.get(s.streamed)
+      if (made === undefined) {
+        const st = statSync(s.tmp)
+        made = { mode: st.mode & 0o777, uid: st.uid, gid: st.gid }
+        created.set(s.streamed, made)
+      }
+      if ((mode & 0o777) !== made.mode) chmodSync(s.tmp, mode & 0o777)
+      // A Date, not seconds: Bun reads a negative number of seconds as
+      // "now", and a Date before 1970 as itself (Bun 1.4.2).
+      const t = mtimeMs === undefined ? undefined : new Date(mtimeMs)
+      if (t !== undefined) utimesSync(s.tmp, t, t)
+      if (s.staged) {
+        const dir = path.dirname(s.target)
+        let gid = setgid.get(dir)
+        if (gid === undefined) {
+          const st = statSync(dir)
+          gid = INHERITS_GROUP || (st.mode & 0o2000) !== 0 ? st.gid : null
+          setgid.set(dir, gid)
+        }
+        if (gid !== null && gid !== made.gid) chownSync(s.tmp, made.uid, gid)
       }
-      if ((mode & 0o777) !== createdMode) chmodSync(s.tmp, mode & 0o777)
-      if (mtimeMs !== undefined) {
-        // A Date, not seconds: Bun reads a negative number of seconds as
-        // "now", and a Date before 1970 as itself (Bun 1.4.2).
-        const t = new Date(mtimeMs)
-        utimesSync(s.tmp, t, t)
+      renames.push(this.place(s, mode, t))
+      if (++n % RENAME_BATCH === 0) {
+        await settle(renames)
+        renames = []
       }
-      renameSync(s.tmp, s.target)
-      if (++n % COMMIT_BATCH === 0) await new Promise<void>((r) => setImmediate(r))
     }
+    await settle(renames)
     this.staged.length = 0
   }
 
   /**
-   * Never leave a stray `.vx-tmp-*` behind: the declared output globs would
-   * sweep it into the next artifact. Directories this extraction created
+   * Rename `s` over its target. A target on another filesystem than
+   * `.vx/tmp/` (EXDEV) is reached through a temp beside it, for that file
+   * only: the rename that replaces the live file stays atomic.
+   */
+  private async place(s: Staged, mode: number, t: Date | undefined): Promise<void> {
+    try {
+      await rename(s.tmp, s.target)
+    } catch (err) {
+      if (!s.staged || (err as NodeJS.ErrnoException).code !== 'EXDEV') throw err
+      const side = siblingTemp(s.target)
+      try {
+        await copyFile(s.tmp, side)
+        chmodSync(side, mode & 0o777)
+        if (t !== undefined) utimesSync(side, t, t)
+        await rename(side, s.target)
+      } catch (e) {
+        await unlink(side).catch(() => undefined)
+        throw e
+      }
+      await unlink(s.tmp).catch(() => undefined)
+    }
+  }
+
+  /**
+   * The staging check, again at the rename: a directory on the way swapped
+   * for a link out of the base since then would carry the rename with it.
+   * Bun has no `renameat` against a held directory fd, so this is by path,
+   * once per directory per commit.
+   */
+  private async assertStillContained(s: Staged, checked: Set<string>): Promise<void> {
+    const dir = path.dirname(s.target)
+    if (checked.has(dir)) return
+    checked.add(dir)
+    const realBase = await this.realBaseOf(s.base)
+    const real = await realOf(dir, true)
+    if (real !== realBase && !real.startsWith(realBase + path.sep)) {
+      throw await linkOutError(path.resolve(s.base), dir, realBase)
+    }
+  }
+
+  /**
+   * Never leave a temp behind: beside a target, the declared output globs
+   * would sweep it into the next artifact. Directories this extraction created
    * are removed bottom-up while empty; one a concurrent writer has since
    * filled is left alone.
    */
   async abort(): Promise<void> {
     await Promise.allSettled(this.inflight)
     this.inflight = []
-    await Promise.all(this.staged.map((s) => unlink(s.tmp).catch(() => undefined)))
+    await Promise.all(
+      this.staged.map((s) =>
+        s.same === undefined ? unlink(s.tmp).catch(() => undefined) : undefined,
+      ),
+    )
     // Newest first: a later entry's chain can sit inside an earlier one's
     // (`dist/` then `dist/sub/`), never the reverse.
     for (const s of this.staged.toReversed()) {
@@ -997,12 +1154,62 @@ class Extractor {
   }
 }
 
-/** Files renamed into place between two yields of a commit. */
-const COMMIT_BATCH = 256
+/**
+ * Renames in flight at once. A rename over a live file is not the few
+ * microseconds of one into an empty directory: on ext4 replacing a file
+ * starts writeback of the new one's data (`auto_da_alloc`), ~250 µs each,
+ * and synchronous ones stalled the main thread. 300 one-file restores
+ * took 25% longer than delete-then-restore (2026-10-16); on the thread
+ * pool they tie it, and 2,000 files in one restore are faster.
+ */
+const RENAME_BATCH = 64
+
+/** Wait for every rename, then throw the first failure: none is left in flight for `abort`. */
+async function settle(renames: readonly Promise<void>[]): Promise<void> {
+  for (const r of await Promise.allSettled(renames)) if (r.status === 'rejected') throw r.reason
+}
 
 /** Per-process counter for extract temp names; uniqueness only. */
 let tmpSeq = 0
 
+/** `.vx/<STAGING>/`: where restores stage, each process in its own `<pid>-0` directory. */
+export const STAGING = 'tmp'
+
+const stagingMade = new Set<string>()
+
+/**
+ * This process's staging directory under `root`'s `.vx/tmp/`, made on its
+ * first restore and again only if something removed it: one per restore
+ * cost 300 restores 12% (2026-10-16). Every restore's renames empty it;
+ * the next run's `sweepStaging` removes it once this process is gone.
+ */
+async function stagingDir(root: string): Promise<string> {
+  const top = path.join(root, '.vx', STAGING)
+  const own = path.join(top, `${process.pid.toString(36)}-0`)
+  if (stagingMade.has(own) && existsSync(own)) return own
+  await mkdir(own, { recursive: true })
+  // Ignored by git whatever `.vx/.gitignore` an older init committed.
+  try {
+    writeFileSync(path.join(top, '.gitignore'), '*\n', { flag: 'wx' })
+  } catch {
+    // there already, or the restore fails on its first write anyway
+  }
+  stagingMade.add(own)
+  return own
+}
+
+/**
+ * A temp beside `target`, with its own short name, never `<target>.suffix`:
+ * a suffix pushed a legal name of 242–255 bytes past NAME_MAX, and the
+ * restore of a valid artifact failed with ENAMETOOLONG (item 666).
+ */
+function siblingTemp(target: string): string {
+  return path.join(
+    path.dirname(target),
+    `.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`,
+  )
+}
+
 const WORKSPACE_PREFIX = 'workspace-outputs/'
 
 /**