@vzn/vx 0.0.640 → 0.0.641

package/docs/caching.md

@@ -399,12 +399,26 @@ On a hit:
    clock (4 ms at HZ=250), so a same-size rewrite inside the tick of
    vx's own write, in place or as a new file that took the same inode,
    with its mtime forged back, still matches.
-3. Otherwise the task's declared outputs are wiped from the project
-   dir (`cleanOutputs`) — see
-   [§ Strict output ownership](#strict-output-ownership) — and the
-   `outputs/<rel>` (+ `workspace-outputs/<rel>`) entries are extracted
-   from the artifact into place: its bytes inline in the index, read in
-   one read transaction with the entry's rows, or `<cacheDir>/<hash>.tar.zst`.
+3. Otherwise the `outputs/<rel>` (+ `workspace-outputs/<rel>`) entries
+   are extracted from the artifact (its bytes inline in the index, read
+   in one read transaction with the entry's rows, or
+   `<cacheDir>/<hash>.tar.zst`) **in place**: every entry is staged in
+   the workspace's `.vx/tmp/` (never an output folder), and only once the
+   whole archive has staged is each renamed over the file it replaces. A
+   file that already holds the entry's bytes (compared byte for byte, up
+   to 4 MiB) is left in place, only its mode and mtime set. A
+   target on another filesystem goes through a temp beside it; a file
+   takes the group its directory gives new files (setgid on Linux, any
+   directory on macOS), ACLs are not copied. The next run removes
+   the staging a killed run left. A process reading the output tree during the
+   restore never finds a declared output missing or half-written, and a
+   restore that fails first (a full disk, a damaged entry) leaves the
+   outputs as they were. Then the declared outputs the entry does not
+   hold are removed — see
+   [§ Strict output ownership](#strict-output-ownership). Only a found
+   output that blocks a rename (a file where the entry needs a directory,
+   or the reverse) goes before. Turbo also restores in place; Nx deletes
+   and copies each file, and a reader meets a missing or short file.
 4. Captured stdout is replayed to the live terminal via the logger —
    the framed block looks like a fresh run. (stderr is not cached —
    only successful runs are cached and their stderr is near-always
@@ -483,10 +497,11 @@ the glob matches (a tracked output, a directory a `!` rule takes back);
 anything git cannot answer keeps the key late. Undeclared writes, an
 `outputs.workspaceFiles` producer upstream, a rewriter the key does not
 fold, and runtime probes after a writer still leave a key preliminary.
-The
-short-circuit never runs under a `LayeredCache` (remote prefetch owns
-those runs — an up-front `get` there would put remote GETs on the
-critical path), never fires with local reads off or on a local cache
+With a
+remote declared the short-circuit probes the local store alone, so a
+local hit still restores ahead of its dependencies and no remote GET
+sits on the critical path (remote prefetch asks the remote for the
+rest). It never fires with local reads off or on a local cache
 that holds no artifact (`Cache.holdsNothing`: every probe would miss,
 and a cold 1,090-package run started its first task ~90 ms sooner
 without it), and never throws —
@@ -822,7 +837,7 @@ the run (`tests/runner.test.ts`) — and the save resolves the output
 globs at once. A descendant the command detached (`setsid … &`, a
 daemon) that writes after that is not in the artifact: the entry saves
 what was there, often nothing (with the `cache.outputs matched no
-files` line), and the next hit's clean-before-restore removes what the
+files` line), and the next hit's restore removes what the
 descendant wrote and restores the saved entry in its place (upstream
 survey, turborepo#12786). vx does not wait for it and cannot see it: a
 process that left the task's session is outside the process group vx
@@ -849,14 +864,15 @@ Declared `cache.outputs.files` are wiped in two distinct places:
 - **Before exec on a cache miss.** A leftover `dist/old.js` from a
   prior build can't survive into a fresh build that doesn't rewrite
   it.
-- **Before restore on a cache hit.** The post-restore tree is the
-  cached snapshot byte-for-byte. Hand-edits to output files don't
-  persist through a cache replay. When the hit's own check walked the
-  output globs to find the tree stale, the clean deletes from that walk's
-  list instead of walking again: nothing is awaited between them (X-161).
-
-Both branches use the same `cleanOutputs` helper (`src/cache/inputs.ts`)
-with the same boundary rules, and vx's own paths stay off the wipe
+- **After restore on a cache hit.** The post-restore tree is the
+  cached snapshot byte-for-byte: the restore renames the entry's files
+  over the ones it finds, then removes what the entry does not hold.
+  Hand-edits to output files don't persist through a cache replay. When
+  the hit's own check walked the output globs to find the tree stale,
+  the removal uses that walk's list instead of walking again (X-161).
+
+Both use the same helpers (`cleanOutputs`, `cleanOutputPaths` in
+`src/cache/inputs.ts`) with the same boundary rules, and vx's own paths stay off the wipe
 whatever the glob: `.git`, `.vx` and each `vx.lock.json` (`OUTPUT_NEVER`;
 `.vx` holds the workspace config and the lock, which a clean deleted and a
 hit restored stale while `.vx/cache` alone was listed). `node_modules` is
@@ -889,7 +905,7 @@ Skipped when:
   `.tsbuildinfo`). You opt out of the clean-tree guarantee: the save
   stores every file the outputs match after the run, so a leftover from
   an older build is cached and restored everywhere. A retry cleans as
-  usual; a hit still cleans before its restore.
+  usual; a hit's restore still removes what its entry does not hold.
 
 A declared output the process cannot remove (a `dist/` another user
 wrote, a read-only checkout) fails the task with `cannot remove declared
@@ -1333,8 +1349,9 @@ pax `path`/`size`, GNU long names, header checksums, truncation; an
 extended header (read whole) past 1 MiB or a pax `size` that is not a
 whole number is refused as corrupt, since a 1 GiB pax header costs 2 GiB
 of memory from a ~32 KB artifact — and
-every regular entry is written beside its target as a short `.vx-tmp-*` sibling (never a suffix on the target's name, which pushed a legal 242–255-byte name past NAME_MAX) and
-renamed into place only after the whole archive has ended cleanly and
+every regular entry is written to the workspace's `.vx/tmp/<pid>-0/`
+(vx's own, ignored by git, never an output folder) and renamed over its
+target only after the whole archive has ended cleanly and
 the index's recorded outputs are all present. vx itself holds one
 chunk of the tar at a time (measured 2026-09-03, incompressible
 artifacts, fresh process: 150 MiB peaked at +644 MiB through
@@ -1413,7 +1430,14 @@ them, `CacheGetContext.outputs`), and never when it holds one path as a
 file and a directory at once. Either used to reach the tree, an input
 overwritten or a `.git/hooks` file planted under a green
 `cache-hit-remote`, or a restore that failed every later run from the
-local copy (item 942); now the read is a miss and the task runs. On the save side a
+local copy (item 942); now the read is a miss and the task runs. Every
+restore asks the same of the local copy, whatever route it reached the
+store by: an entry outside the declared outputs, one a `!` entry takes
+back, one under `.git`, `.vx` or a `vx.lock.json`, or one under a
+`node_modules` no output glob names fails the whole restore before
+anything is written; the entry is dropped and the task runs. Remote
+execution (`@vzn/vx-reapi`) writes a remote action's outputs through the
+same gate (`restorableOutput`). On the save side a
 **symlinked output** is captured as its target's bytes and comes back
 as a regular file (a hit that finds the task's own link still current
 leaves it); a link to a directory, or a dangling one, has no bytes to

package/docs/cli.md

@@ -37,7 +37,7 @@ vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--for
 vx info [--format pretty|json] [--cache-dir <path>]
 vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]
 vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--stats [<task>] [--branch <name>]] [--format pretty|json] [--cache-dir <path>]
-vx upgrade [TAG]      # upgrade vx the way it was installed
+vx upgrade [TAG] [-g|--global]
 vx docs <query> [--limit N] [--format pretty|json]
 vx completions bash|zsh|fish
 
@@ -1243,8 +1243,7 @@ run...` precedes it.
    which reads what it likes, item 947, outside any project nested
    in it; a write the last cycle made is not, read off the later of
    its mtime and ctime, so an output a cache hit restores with its
-   saved mtime is the run's, and so is the restore's own `.vx-tmp-*`
-   file, `watch-restored-output.test.ts`) — or declared an
+   saved mtime is the run's, `watch-restored-output.test.ts`) — or declared an
    output, or the loop re-runs on it; after three such cycles in a row
    watch names the path and the remedy, once, and keeps going. A dev
    server the last cycle left running counts as that cycle for as long
@@ -1305,8 +1304,8 @@ Always ignored (no re-trigger):
   tracked + untracked-not-ignored — so a cycle it started could change
   nothing. A tracked file that matches a pattern is not ignored, by
   git's own rule; outside a repository nothing is.
-- Files ending in `~` (editor swap files), and a restore's own
-  `.vx-tmp-*` file.
+- Files ending in `~` (editor swap files), and `.vx/tmp/`, where
+  restores stage.
 - The run's **resolved cache directory**, wherever it is. `.vx/cache/` covers the
   default, but `defineWorkspace({ cache: { dir } })` and `--cache-dir` can put it
   anywhere; watching it would let vx's own cache writes trigger the next
@@ -1906,6 +1905,12 @@ project that fails leaves the global as it was. The project's vx run
 directly (a package script, `node_modules/.bin/vx`) has no global behind it, so only
 the project moves.
 
+**`vx upgrade -g`** (`--global`) moves only the global vx, wherever it
+runs: it never hands the call to a project's vx, and it never touches a
+`package.json` or a plugin. Run as the project's own vx, it refuses:
+`vx upgrade -g: no global vx ran — <path> is the project's own. Install
+one (npm install -g @vzn/vx), or run \`vx upgrade\` to move the project's`.
+
 ```
 › vx upgrade  project 0.0.1 → 0.0.2
 

package/docs/execution.md

@@ -174,12 +174,13 @@ terminal and a task succeeding or failing. Read it alongside
  │      overlap is the point); drained before cache.close(). At most
  │      one remote GET per key (shared in-flight map with the lazy
  │      read-through).
- │    • LOCAL SHORT-CIRCUIT (no remote layer, local reads on, ≥1
- │      task) — derive the same stable keys and probe them in ONE
- │      batched cache.getMany (a layer without getMany: cache.get once
- │      per task under a bounded pool) → a `preProbed` map (hits AND
- │      stable misses; execute reuses these probes) + a `restoreTier`
- │      set (confirmed hits). Awaited before scheduling; never throws
+ │    • LOCAL SHORT-CIRCUIT (local reads on, ≥1 task) — derive the
+ │      same stable keys and probe the LOCAL store in ONE batched
+ │      getMany (a layer without getMany: get once per task under a
+ │      bounded pool) → a `preProbed` map (hits AND stable misses;
+ │      with a remote declared, hits only: a local miss may be a
+ │      remote hit) + a `restoreTier` set (confirmed hits). Awaited
+ │      before scheduling; never asks a remote; never throws
  │      (degrades to the normal schedule).
  │
  ├─ Scheduling (src/graph/scheduler.ts:runGraph — two-tier)

package/docs/features.md

@@ -121,7 +121,7 @@ config key or an environment variable is missing here.
 - **Interactive tasks** (`exec.interactive`) — a task that owns the terminal. [page](https://vznjs.github.io/vx/features/interactive-tasks/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
 - **Shell completions** (`vx completions`) — bash, zsh, fish. [page](https://vznjs.github.io/vx/features/completions/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Project-local vx** (`VX_HANDED_OFF`) — a global vx hands every call to the project's own `@vzn/vx`. [page](https://vznjs.github.io/vx/cli/#which-vx-runs)
-- **vx upgrade** (`vx upgrade`) — upgrade vx the way it was installed: a verified binary, or its package manager. Inside a project, the project's vx, its `@vzn/vx-*` plugins (one install, one release) and the global vx that ran it move together. [page](https://vznjs.github.io/vx/features/upgrade/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
+- **vx upgrade** (`vx upgrade`) — upgrade vx the way it was installed: a verified binary, or its package manager. Inside a project, the project's vx, its `@vzn/vx-*` plugins (one install, one release) and the global vx that ran it move together; `vx upgrade -g` moves only the global. [page](https://vznjs.github.io/vx/features/upgrade/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
 - **Help and version** (`vx help`, `vx version`) — every verb's reference. [page](https://vznjs.github.io/vx/features/help-and-version/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
 - **Did-you-mean** — a mistyped flag or verb gets the nearest valid spelling. [page](https://vznjs.github.io/vx/features/did-you-mean/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Task typed as a verb** — `vx build app` answers with the exact `vx run` command that does it. [page](https://vznjs.github.io/vx/features/task-as-verb/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)

package/docs/schema.md

@@ -822,19 +822,25 @@ Always applied to every glob pass (regardless of what you wrote):
   `.cache/gen/**`), which is then walked on disk under that prefix only.
   Such a file is hashed from disk and never stored or restored; a
   missing one is not an input until it exists. A broad glob (`**`,
-  `src/**` over a listed `src`) still skips ignored files, so
-  `node_modules` is never walked, and an install stays out either way.
+  `src/**` over a listed `src`) still skips ignored files, so it never
+  walks `node_modules`.
   Its bytes differ per machine, so machines with different files miss
   each other's shared entries. An ignored file never selects a task
   under `--affected` on its own, as in Nx (only what git sees does); `vx
 watch` re-runs it on an edit there.
 - **Always-ignored** — `.git/**`, `.vx/cache/**`,
-  `.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, and Bun's cross-compile extraction
-  directory `.<16 hex>-<8 hex>.tmp/**`, and vx's own restore temp
-  `.vx-tmp-*`, at any depth.
-- **Installs** — an untracked file under any `node_modules/` (ignored or
-  not). A file git TRACKS there, such as a committed test fixture, is an
-  input like any other.
+  `.vx/projects.lock.json`, `vx.lock.json`, and `.vx/tmp/**`, where vx's
+  restores stage, at any depth. Nothing else: a tool's temp files are the
+  task's to exclude. A broad glob on a `bun build --compile` task, or on
+  one that runs beside it, excludes Bun's intermediate and its
+  cross-compile extraction directory itself:
+  `['**/*', '!**/*.bun-build', '!**/.????????????????-????????.tmp/**']`.
+- **Installs** — an untracked file under any `node_modules/` that git
+  does not ignore. An ignored one follows the gitignore filter above
+  like any other ignored path: named outright, it is an input
+  (`node_modules/.prisma/client/**`, a generated client); a broad glob
+  skips it because it is ignored. A file git TRACKS there, such as a committed test fixture, is an input
+  like any other.
 - **Declared `outputs.files`** are excluded — a task never invalidates
   itself via its own output. A path an output `!` entry takes back is
   no output, so it stays an input (A-44). Another task's outputs are
@@ -887,7 +893,7 @@ backslash separator (`src\**`, `src\*.ts`) or a drive (`C:\src\**`,
 backslash stays an escape.
 
 Still applied: the always-ignored set (`.git/**`, `.vx/cache/**`,
-`.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, `.<16 hex>-<8 hex>.tmp/**`, `.vx-tmp-*`),
+`.vx/projects.lock.json`, `vx.lock.json`, `.vx/tmp/**`),
 untracked files under `node_modules/`, and the task's own declared
 outputs, `outputs.workspaceFiles` and the `outputs.files` its globs reach
 in its own project (a task never invalidates itself).
@@ -1666,8 +1672,9 @@ The loader rejects:
 
 Loaded from `.vx/workspace.{ts,mts,js,mjs,cts,cjs}`: the directory holding
 `.vx` is the workspace root. `.vx` also holds the lock (`.vx/projects.lock.json`)
-and `.vx/cache`, the machine-local state (the cache, the workspace id),
-which is the only part git ignores: `.vx/.gitignore` says `/cache`. Every field falls back to its
+`.vx/cache`, the machine-local state (the cache, the workspace id), and
+`.vx/tmp`, where a restore stages files; git ignores only those two:
+`.vx/.gitignore` says `/cache` and `/tmp`. Every field falls back to its
 built-in default.
 
 ```ts
@@ -1827,7 +1834,7 @@ interface CacheSettings {
   workspace (`'..'`, `'/'`) is refused before anything is written, since its `*`
   `.gitignore` would hide the sources from git and the cache keys. A
   directory other than the default `.vx/cache` gets that `*` `.gitignore`;
-  the default is ignored by `.vx/.gitignore` (`/cache`) instead, written
+  the default is ignored by `.vx/.gitignore` (`/cache`, `/tmp`) instead, written
   when missing and never edited.
 - **`cache.retention`** — the `vx cache clean` policy, applied at the
   end of every run: entries unused for

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
 

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.640",
+  "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.640",
-    "@vzn/vx-linux-arm64": "0.0.640",
-    "@vzn/vx-darwin-x64": "0.0.640",
-    "@vzn/vx-darwin-arm64": "0.0.640"
+    "@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/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).