@vzn/vx 0.0.634 → 0.0.636

package/README.md

@@ -5,8 +5,9 @@
 <h1 align="center">vx</h1>
 
 <p align="center">
-  <strong>The fastest task runner for JS monorepos.</strong><br>
-  Measured against Turborepo and Nx, each in its own native config.
+  <strong>Task orchestration you own.</strong><br>
+  Correct, sandboxed, extensible. No cloud, no account, no paywall.<br>
+  <a href="https://vznjs.github.io/vx/"><strong>vznjs.github.io/vx</strong></a>
 </p>
 
 <p align="center">
@@ -16,29 +17,9 @@
   <a href="https://vznjs.github.io/vx/"><img src="https://img.shields.io/badge/docs-vznjs.github.io%2Fvx-c6f84e" alt="Documentation"></a>
 </p>
 
-<!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
-
-| 1,090 packages, 3,270 tasks                     | vx             | Turborepo                  | Nx                        | Vite Task                  |
-| ----------------------------------------------- | -------------- | -------------------------- | ------------------------- | -------------------------- |
-| Cold build: total time                          | **3 min 40 s** | 4 min 59 s (vx 36% faster) | 3 min 49 s (vx 4% faster) | 4 min 49 s (vx 31% faster) |
-| Cold build: CPU burned                          | **17 s**       | 21 s (vx 22% faster)       | 52 s (vx 3× faster)       | 12 s (vx 39% slower)       |
-| Fully cached run (restored)                     | **650 ms**     | 997 ms (vx 53% faster)     | 6.25 s (vx 9.6× faster)   | 2.64 s (vx 4.1× faster)    |
-| Fully cached run (up-to-date)                   | **393 ms**     | 463 ms (vx 18% faster)     | 6.45 s (vx 16× faster)    | 2.49 s (vx 6.3× faster)    |
-| Secondary: time the runner adds to a cold build | **2 s**        | 1 min 21 s                 | 11 s                      | 1 min 11 s                 |
-
-vx N% or N× faster: that tool takes N% longer or N times as long as vx.
-
-Benchmark workload: a synthetic monorepo of 1,090 packages and 3,270 tasks in 100 dependency layers, every build and test taking 1 s; real repos with uneven task times will differ.
-Run 2026-10-04 on linux x64, 4 cores: vx from source, Turborepo 2.11.7, Nx 23.2.1, Vite Task (vite-plus) 1.0.0.
-
-The secondary row is the wall time over the tasks' own ideal schedule (3 min 38 s).
-Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).
-
-<!-- bench:end -->
-
 ## What vx is
 
-A task runner and build cache for JavaScript monorepos.
+Task orchestration with a cache you can trust, on a core you can extend.
 Each task is one shell command with declared inputs and outputs; vx runs
 them in dependency order and replays results from a content-addressed cache.
 
@@ -95,22 +76,7 @@ More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 [CLI](packages/vx/docs/cli.md) · [every config field](packages/vx/docs/schema.md) ·
 [playground](https://vznjs.github.io/vx/playground/) (the planner, in your browser).
 
-## Coming from Turbo or Nx
-
-Beside `turbo.json` or `nx.json`, `npx vx init` runs `@vzn/vx-migrate`:
-it writes a `vx.config.ts` per package from `turbo.json` or the Nx graph,
-and you keep those and delete the old config. `vx init --keep` writes only
-a `vx.workspace.ts` that maps the old config instead: a temporary start,
-not a way to run the repo. The numbers above are native vx config.
-[Migration guide](https://vznjs.github.io/vx/guides/migrate/).
-
-## Why it is faster
-
-- **Nothing boots per task:** no daemon, no Node process; vx spawns your command.
-- **No source-file reads to hash:** on a clean tree, keys come from git's index; each project's `package.json` and the lockfile are still read.
-- **One pass:** one git walk per run; each stat and lookup happens once.
-
-## More than speed
+## A foundation you own
 
 - **A cache you can trust:** TypeScript configs are evaluated before
   hashing, so imports and computed values are in the key. Outputs are
@@ -122,6 +88,32 @@ not a way to run the repo. The numbers above are native vx config.
   CLI verbs. Core ships none and needs none.
 - **Free:** MIT. No paywall, no cloud, no account.
 
+## Plugins
+
+What vx can do, not what it is limited to. Declared in `vx.workspace.ts`; without any, vx runs and caches locally.
+
+| Package                                                    | What it adds                                                                  |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| [`@vzn/vx-migrate`](packages/vx-migrate)                   | Migrate from Turbo or Nx: write native configs, keep its remote cache         |
+| [`@vzn/vx-reapi`](packages/vx-reapi)                       | Remote cache and remote execution over Bazel's REAPI (NativeLink, BuildBuddy) |
+| [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn              |
+| [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                |
+| [`@vzn/vx-ci`](packages/vx-ci)                             | GitHub Actions job summary and Checks API                                     |
+| [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: an MCP server for AI coding agents that also runs tasks             |
+| [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                          |
+
+Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
+[architecture](packages/vx/docs/architecture.md).
+
+## Coming from Turbo or Nx
+
+Beside `turbo.json` or `nx.json`, `npx vx init` runs `@vzn/vx-migrate`:
+it writes a `vx.config.ts` per package from `turbo.json` or the Nx graph,
+and you keep those and delete the old config. `vx init --keep` writes only
+a `vx.workspace.ts` that maps the old config instead: a temporary start,
+not a way to run the repo. The benchmark below uses native vx config.
+[Migration guide](https://vznjs.github.io/vx/guides/migrate/).
+
 ## How it compares
 
 |                    | vx                                        | Turborepo                      | Nx               |
@@ -138,22 +130,29 @@ Every gap, and when another tool is the better pick:
 [comparison](packages/vx/docs/comparison.md) ·
 [vx, Turborepo, Nx, Bazel](https://vznjs.github.io/vx/compare/).
 
-## Plugins
+## Fast, without trading correctness
 
-Declared in `vx.workspace.ts`; without any, vx runs and caches locally.
+- **Nothing boots per task:** no daemon, no Node process; vx spawns your command.
+- **No source-file reads to hash:** on a clean tree, keys come from git's index; each project's `package.json` and the lockfile are still read.
+- **One pass:** one git walk per run; each stat and lookup happens once.
 
-| Package                                                    | What it adds                                                                  |
-| ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [`@vzn/vx-migrate`](packages/vx-migrate)                   | Migrate from Turbo or Nx: write native configs, keep its remote cache         |
-| [`@vzn/vx-reapi`](packages/vx-reapi)                       | Remote cache and remote execution over Bazel's REAPI (NativeLink, BuildBuddy) |
-| [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn              |
-| [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                |
-| [`@vzn/vx-ci`](packages/vx-ci)                             | GitHub Actions job summary and Checks API                                     |
-| [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: an MCP server for AI coding agents that also runs tasks             |
-| [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                          |
+<!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
 
-Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
-[architecture](packages/vx/docs/architecture.md).
+| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx          | Turborepo | Nx         | Vite Task |
+| ---------------------------------------------------------- | ----------- | --------- | ---------- | --------- |
+| Nothing changed                                            | **856 ms**  | 855 ms    | 23.22 s    | 11.24 s   |
+| Nothing changed, outputs restored                          | **1.45 s**  | 1.50 s    | 21.64 s    | 11.21 s   |
+| Cold build                                                 | **7.73 s**  | 10.32 s   | 3 min 23 s | 9.44 s    |
+| Cold build: CPU the runner burns                           | **36.42 s** | 1 min 3 s | 5 min 35 s | 25.64 s   |
+
+Time each tool adds over the ideal run; lower is better.
+
+Benchmark workload: a synthetic monorepo of 1,601 projects and 9,603 tasks in 30 dependency levels, five core libraries a quarter of the projects use; build 300 ms, test and typecheck 150 ms, lint 75 ms, publish 30 ms; real repos with uneven task times will differ.
+Run 2026-10-12 on linux x64, 4 cores: vx at commit 126d60a93, Turborepo 2.11.7, Nx 23.3.0, Vite Task (vite-plus) 1.1.0.
+
+Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).
+
+<!-- bench:end -->
 
 ## Status
 

package/docs/caching.md

@@ -200,7 +200,11 @@ add` under a clean filter (`core.autocrlf=true`, a `text` rule)
 
     Ref storage is not a key input: every ref vx reads comes from a git
     command, so a repository in reftable storage (git 2.45) keys every
-    task as its files-backend twin (`tests/git-reftable.unsafe.test.ts`).
+    task as its files-backend twin. A sha256 repository keys from its
+    64-hex index OIDs, and a dirty file is hashed in-process as sha256,
+    so Git 3's defaults (reftable and sha256 together) run, hit and
+    select `--affected` as a sha1 repository does
+    (`tests/git-reftable.unsafe.test.ts`).
 
     A **submodule or an embedded repository** is enumerated by its own
     git: the workspace repository lists the nested one as a single entry
@@ -704,7 +708,15 @@ is not saved either: its write cannot be told from an edit reverted
 mid-run, so it pays a re-run each time rather than risk a stale entry;
 declare what it writes as an output, which the status line says when it
 names a file other than `package.json` (TanStack Router's committed
-`routeTree.gen.ts`, rewritten by every build). A file ADDED under an
+`routeTree.gen.ts`, rewritten by every build). That holds on CI too: a
+task of the same project running alongside can change an input and put
+it back. A task that rewrites its own input to identical bytes (tsdown's
+`package.json`) sets `cache.inputStability: { strategy: 'mutable' }`, and a write
+during its command is then judged by its bytes, as an earlier write is;
+different bytes still withhold the entry. `VX_INPUT_STABILITY=mutable`
+makes that the default (owner, 2026-10-12); `'unchecked'` skips the
+check, and `severity: 'error'` fails the task instead of warning
+(`docs/schema.md`). A file ADDED under an
 input glob since the listing the key filtered (`addedInput`) withholds
 the save the same way, named on the same line: the listing's
 directories a glob reaches are `lstat`ed, one whose ctime moved since

package/docs/cli.md

@@ -137,9 +137,12 @@ Exit codes:
 A task runs in its own session, so a terminal's Ctrl-C reaches vx alone,
 and each task hears it once: from vx, as SIGINT.
 
-Installed from npm, `vx` is a Node launcher. On Node 22.15 or later it
-replaces itself with the binary (`process.execve`), so every signal
-reaches vx directly. On older Node it runs the binary and waits for it:
+Installed from npm, `vx` is a sh launcher that execs the platform
+binary, so every signal reaches vx directly and no Node starts first
+(a `vx --version` through npm: 14 ms, was 56 ms with the Node launcher, 2026-10-12). Where it
+finds no binary beside it (musl, Yarn PnP, a platform with none) it
+hands off to a Node launcher. On Node 22.15 or later that one
+replaces itself with the binary (`process.execve`) too. On older Node it runs the binary and waits for it:
 a signal sent to the launcher alone (`kill`, a process manager) is
 passed to the binary, and a terminal's Ctrl-C already reaches both, so
 the launcher does not send it twice.
@@ -477,6 +480,7 @@ than run with the args unheard.
 | `--no-cache`                       | boolean        | off                                       | Disable caching entirely (no reads, no writes); output globs are NOT cleaned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `--force`                          | boolean        | off                                       | Re-execute everything (skip cache reads) but still REFRESH the cache (writes stay on). Output globs are cleaned (so the saved snapshot is clean).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `--cache <spec>`                   | value          | all axes on                               | Per-layer read/write control. See below. An EMPTY spec (`--cache=`) is a parse error — it applied nothing and left every axis on; pass `--no-cache` to disable them all.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `--cache-scope <name>`             | value          | `VX_CACHE_SCOPE` / workspace `cacheScope` | This run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `VX_CACHE_SCOPE`, `vx.workspace`'s and `github()`'s. A name `cacheScope` would refuse is refused. `--cache-scope=<name>` form too. Never folded into a cache key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `--cache-dir <path>`               | value          | workspace `cacheDir` / `~/.vx/<id>/cache` | Cache directory override, resolved relative to cwd (absolute paths used as-is). Beats the `defineWorkspace({ cacheDir })` field, `VX_CACHE_DIR` and the default; like them, the directory then holds the whole cache, shared through no store, for every cache the run opens — the config-evaluation cache that `--affected` owners, the picker and the watch sweep read included, so the workspace's default dir is not created beside it. A per-run knob — never folded into a cache key. `--cache-dir=<path>` form too; the space form rejects a value starting with `-`. A directory this user cannot write into fails the run before any task with `cache directory <path> is not writable (EACCES: …)` — every run records its history there. |
 | `--retry <n>`                      | value          | `0`                                       | Re-run a failed task up to `n` more times; never a persistent one. Run-level default only: a task's own `exec.retries` wins (even an explicit `0`). Never affects cache keys. `--retry=<n>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `--continue[=<mode>]`              | value          | `deps-ok`                                 | What a failed task takes down with it. `never` stops dispatch on the first failure; `deps-ok` (default) skips only its dependents; `always` (bare `--continue`) runs dependents anyway. See § Failure propagation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
@@ -568,7 +572,8 @@ The cache has four independent axes — **localRead**, **localWrite**,
 them in this precedence order:
 
 1. Start with every axis **on** (the default).
-2. Apply each `--cache=<spec>` segment (the base).
+2. Apply each `--cache=<spec>` segment (the base), or, with no
+   `--cache`, the `VX_CACHE` environment variable's spec.
 3. If `--no-cache` was passed, force **all four off**.
 4. If `--force` was passed, force **both reads off** (writes stay
    whatever the base / `--cache` left them).
@@ -957,8 +962,10 @@ readable. Its `criticalPath` names the would-run tasks with history on
 the chain `wallMs` measures, dependencies first: the tasks to speed up
 to shorten the run.
 
-**Why a task is affected.** Under `--affected`, each requested task the
-diff kept gets a line, and its JSON object an `affected` reason:
+### Why a task is affected (`affected.kind`)
+
+Under `--affected`, each requested task the diff kept gets a line, and
+its JSON object an `affected` reason:
 
 ```
 $ vx run build lint --affected=main --dry
@@ -981,6 +988,8 @@ against: a bare `--affected` guesses it (`origin/HEAD`, a trunk branch,
 else `HEAD~1`), so a reason that names no file may come from a commit
 the base reaches, a root `package.json` edit among them.
 
+### Task graph (`--graph`)
+
 `--graph` prints Graphviz DOT (stdout by default; `--graph=path`
 writes a file):
 
@@ -1283,7 +1292,19 @@ package, are reported.
 Policy: **fail on violation.** Any task that touches a path it didn't
 declare either fails naturally (Linux: `ENOENT` from bwrap's
 mount-namespace hide) or is flagged via the macOS violation store
-and forced to exit non-zero. No cache is written for a failed task.
+and forced to exit non-zero. No cache is written for a failed task. The
+task's `SANDBOX VIOLATIONS` section ends with a dimmed `fix:` line,
+the grants that would have allowed each denial, project-relative:
+`fix: exec.sandbox.allow: { read: ['tsconfig.json'], write: ['dist/'] }`.
+A write grants the top directory it landed in, so the next file there
+passes too, unless `cache.inputs.files` reads that directory: then it
+grants the file alone, so the task cannot write its own inputs; a read the output depends on is a key input as well, and
+the line says so, since a grant never adds one. A credential path
+(`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.kube`, `~/.config/gh`,
+`~/.config/gcloud`, `~/.netrc`, `~/.npmrc`, `~/.pypirc`,
+`~/.git-credentials`, `~/.docker/config.json`, a `.env` file) is never put in the
+line: an agent applies it as given, so it is named apart as one to
+grant only on purpose.
 "Didn't declare" means the grants, which on Linux are wider than they
 read: a file-shaped write grant is bound as its whole directory, so
 every file beside it is readable without a violation — `schema.md`
@@ -1961,13 +1982,17 @@ install its dependencies. `--mjs` writes the same objects as `vx.config.mjs` and
 own `tsconfig` includes every `.ts` under it compiles a `vx.config.ts`
 into its dist (TanStack/query's `tsc --build`, 2026-09-11), and an
 `.mjs` is outside that include. `@vzn/vx-migrate` takes the same flag.
+A file it writes that `.gitignore` drops (vueuse ignores
+`packages/**/*.mjs`) gets a `note:` naming it and the `!vx.config.mjs`
+line that keeps it, since a commit would leave it behind unnoticed.
 
 Each script becomes a task with its command verbatim. `build` gets
 `dependsOn: ['^build']` (a `build` that only delegates, `pnpm run
 compile`, is a group, and the edge goes on the script that does the
 work) and **no cache block** — under a
 `TODO(vx-migrate)` showing the block to add with the package's real
-inputs and outputs. A task without a cache block always runs; a block
+inputs and outputs, and the same block commented as the task's first
+line: set the real globs and delete the `// `. A task without a cache block always runs; a block
 with EMPTY outputs is not "uncached" but a no-output task that hits on
 unchanged inputs and skips the build with nothing to restore (a deleted
 `dist` stays deleted under a green `up-to-date` run — what `init`
@@ -2113,8 +2138,8 @@ order may matter, so it is not made a group.
 
 The report lists each TODO once per reason: tasks that share one are
 named together (the first five, then a count; the files carry each),
-and when no task caches it says a cache block from a TODO makes the
-second run a hit. Its `next:` line is a command the user can type: the
+and when no task caches it says uncommenting a TODO task's cache line
+makes the second run a hit. Its `next:` line is a command the user can type: the
 runner that started vx (`npx`, `pnpm`, `yarn`, `bunx`, read from
 `npm_config_user_agent`) with the installed `vx` bin, else the
 `@vzn/vx` package (`npx` under Yarn 1, which has no `dlx`); with no
@@ -2370,6 +2395,42 @@ cache) or grant the write, then re-run.
 Out of file descriptors. Raise the limit (`ulimit -n 4096`), or run fewer
 tasks at once (`--concurrency`), then re-run.
 
+#### `VX_E_AFFECTED_BASE`
+
+`--affected` (or `--affected=<ref>`) has no base to diff against: the
+ref does not resolve, is a range (`A..B`) or an exclusion (`^A`), names
+a path inside a commit, or the repository has no history to compare
+with. Pass a branch or commit you have locally, alone:
+`--affected=origin/main`. On CI, fetch the history the base needs
+(`fetch-depth: 0` on actions/checkout, or `git fetch --unshallow`).
+
+#### `VX_E_GIT`
+
+A git command vx runs to read the diff failed; the message carries
+git's exit and its own words. Run that command in the workspace to see
+why (a broken index, a missing object in a partial clone).
+
+#### `VX_E_DEPENDS_ON`
+
+A task's `dependsOn` names a task or project that is not declared, or uses
+a form vx does not take (a bare wildcard, a negation, a pattern in
+`pkg#task`). The message names the task and the entry: declare the
+target, fix its spelling, or drop the entry.
+
+#### `VX_E_OUTPUT_OVERLAP`
+
+Two tasks declare overlapping outputs with no `dependsOn` edge between
+them, so whichever runs second deletes the other's files. Give each task
+its own output path, or make one depend on the other.
+
+#### `VX_E_INPUT_IS_OUTPUT`
+
+A task's `cache.inputs` match outputs: its own (vx cleans outputs before
+a run, so it would delete its sources) or another task's (its key must
+not read them; `dependsOn` already cascades). Exclude the outputs from
+the inputs with a `!` glob, as the message shows, or declare no outputs
+for a task that rewrites files in place.
+
 #### `VX_E_INTERNAL`
 
 A defect in vx; stderr carries the stack. Report it with that stack at
@@ -2807,8 +2868,14 @@ failed runs. `--format json`
 emits `{ invocation, tasks }` for scripting; a failed task's row adds
 `output` (its output as plain text, the first 8 KiB and last 56 KiB,
 secrets masked) and `locations` (the existing files it names,
-`{ file, line?, col? }`, file absolute), so an agent reads why without
-the terminal. They live in `<cacheDir>/failures/<runId>.json`, the
+`{ file, line?, col? }`, file absolute; a file also named with a line
+drops its bare mention, such as bun test's `app.test.js:` header), so an
+agent reads why without the terminal. `fixedIn` names the first later run where that task
+passed, so a replayed failure that is already fixed says so. A
+sandboxed task's row adds `sandboxFix`, the `exec.sandbox.allow`
+entries (`read`, `write`, `network`, `systemInfo`) that would have
+granted its denials, the same grants the terminal prints as `fix:`;
+`withheld` lists the credential paths it denied and left out. They live in `<cacheDir>/failures/<runId>.json`, the
 newest 50 failed runs; past those, or when the write was refused, a
 failed row reads `output: ''` and `locations: []`. `--log <task>`
 prints one task's output instead of the summary: in the latest run that
@@ -2958,30 +3025,21 @@ REAPI endpoints, the GitHub token) are in its README; what a TASK sees
 is `exec.env` in `docs/schema.md`, and the two markers vx sets on every
 task are the last row.
 
-| Var                               | Value                 | Default | Effect                                                                                                                                                                                                                                                                                                            |
-| --------------------------------- | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `VX_TIMING`                       | any non-empty         | off     | Print the stage table to stderr after a run, a `--dry`, or each `vx watch` cycle (`docs/modules/timing.md`).                                                                                                                                                                                                      |
-| `VX_TASK_TIMEOUT`                 | positive integer (ms) | none    | The default timeout for tasks without their own `exec.timeout`, one rung below `--timeout` / `RunOptions.timeout` and one above the workspace `timeout`. Empty, non-integer or non-positive is ignored; a value past the largest timer (~24.8 days) is clamped to it, never refused.                              |
-| `VX_CACHE_DIR`                    | a path                | none    | The workspace's cache dir, relative to the workspace root, below `--cache-dir` and `vx.workspace`'s `cacheDir`. A named cache dir holds the whole cache and shares nothing; unset, entries live in the user's shared store (`docs/caching.md`). Empty is ignored; whitespace alone is refused, as `cacheDir` is.  |
-| `VX_CACHE_SCOPE`                  | a `cacheScope` value  | none    | The run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `vx.workspace`'s and `github()`'s. Empty is ignored; a value `cacheScope` would refuse is refused before any task.                                                                                                                               |
-| `VX_KILL_GRACE_MS`                | positive integer (ms) | 2000    | The SIGTERM → SIGKILL grace a child that ignores SIGTERM gets: on a timeout, on a signal, and at the end-of-run shutdown of persistent tasks. Out of range falls back to the default.                                                                                                                             |
-| `VX_READY_NOTICE_MS`              | positive integer (ms) | 10000   | How long a persistent task may take to match `readyWhen` before vx says once what it waits for. Out of range falls back to the default.                                                                                                                                                                           |
-| `VX_TEARDOWN_TIMEOUT_MS`          | integer (ms)          | 3000    | The bound on one plugin's end-of-run flush or teardown, and on its `telemetry()` setup, so a third party's I/O cannot hold the run. Out of range falls back to the default, never clamps: a bound of 24.8 days is no bound.                                                                                       |
-| `VX_CONFIG_WORKER_TIMEOUT_MS`     | integer (ms)          | 30000   | How long one `vx.config.ts` evaluation may take, in process or in its worker, before the load fails naming the config (a real evaluation is ~10 ms). A synchronous loop on a first load holds the thread the deadline needs, so it hangs until killed. Out of range falls back to the default.                    |
-| `VX_WATCH_POLL`                   | any non-empty         | off     | `vx watch` polls every 250 ms from the start instead of probing the OS watcher (§ `vx watch` › How changes are seen).                                                                                                                                                                                             |
-| `VX_RUN_WORKSPACE`, `VX_RUN_TASK` | set by vx             | —       | Set on every task's environment (the workspace root; `project#task`). Read back by a `vx run` a task starts: one in the same workspace is refused, since a nested run is invisible to the outer graph and a loop back to its own task forks without bound (`docs/schema.md` § `env`).                             |
-| Var                               | Value                 | Default | Effect                                                                                                                                                                                                                                                                                                            |
-| --------------------------------- | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `VX_TIMING`                       | any non-empty         | off     | Print the stage table to stderr after a run, a `--dry`, or each `vx watch` cycle (`docs/modules/timing.md`).                                                                                                                                                                                                      |
-| `VX_TASK_TIMEOUT`                 | positive integer (ms) | none    | The default timeout for tasks without their own `exec.timeout`, one rung below `--timeout` / `RunOptions.timeout` and one above the workspace `timeout`. Empty, non-integer or non-positive is ignored; a value past the largest timer (~24.8 days) is clamped to it, never refused.                              |
-| `VX_CACHE_DIR`                    | a path                | none    | The workspace's cache dir, relative to the workspace root, below `--cache-dir` and `vx.workspace`'s `cacheDir`. A named cache dir holds the whole cache and shares nothing; unset, entries live in the user's shared store (`docs/caching.md`). Empty is ignored.                                                 |
-| `VX_CACHE_SCOPE`                  | a `cacheScope` value  | none    | The run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `vx.workspace`'s and `github()`'s. Empty is ignored; a value `cacheScope` would refuse is refused before any task.                                                                                                                               |
-| `VX_KILL_GRACE_MS`                | positive integer (ms) | 2000    | The SIGTERM → SIGKILL grace a child that ignores SIGTERM gets: on a timeout, on a signal, and at the end-of-run shutdown of persistent tasks. Out of range falls back to the default.                                                                                                                             |
-| `VX_READY_NOTICE_MS`              | positive integer (ms) | 10000   | How long a persistent task may take to match `readyWhen` before vx says once what it waits for. Out of range falls back to the default.                                                                                                                                                                           |
-| `VX_TEARDOWN_TIMEOUT_MS`          | integer (ms)          | 3000    | The bound on one plugin's end-of-run flush or teardown, and on its `telemetry()` setup, so a third party's I/O cannot hold the run. Out of range falls back to the default, never clamps: a bound of 24.8 days is no bound.                                                                                       |
-| `VX_CONFIG_WORKER_TIMEOUT_MS`     | integer (ms)          | 30000   | How long one `vx.config.ts` evaluation may take, in process or in its worker, before the load fails naming the config (a real evaluation is ~10 ms). A synchronous loop on a first load holds the thread the deadline needs, so it hangs until killed. Out of range (0, or past 2³¹−1) falls back to the default. |
-| `VX_WATCH_POLL`                   | any non-empty         | off     | `vx watch` polls every 250 ms from the start instead of probing the OS watcher (§ `vx watch` › How changes are seen).                                                                                                                                                                                             |
-| `VX_RUN_WORKSPACE`, `VX_RUN_TASK` | set by vx             | —       | Set on every task's environment (the workspace root; `project#task`). Read back by a `vx run` a task starts: one in the same workspace is refused, since a nested run is invisible to the outer graph and a loop back to its own task forks without bound (`docs/schema.md` § `env`).                             |
+| Var                               | Value                               | Default     | Effect                                                                                                                                                                                                                                                                                                                  |
+| --------------------------------- | ----------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VX_TIMING`                       | any non-empty                       | off         | Print the stage table to stderr after a run, a `--dry`, or each `vx watch` cycle (`docs/modules/timing.md`).                                                                                                                                                                                                            |
+| `VX_TASK_TIMEOUT`                 | positive integer (ms)               | none        | The default timeout for tasks without their own `exec.timeout`, one rung below `--timeout` / `RunOptions.timeout` and one above the workspace `timeout`. Empty, non-integer or non-positive is ignored; a value past the largest timer (~24.8 days) is clamped to it, never refused.                                    |
+| `VX_CACHE_DIR`                    | a path                              | none        | The workspace's cache dir, relative to the workspace root, below `--cache-dir` and `vx.workspace`'s `cacheDir`. A named cache dir holds the whole cache and shares nothing; unset, entries live in the user's shared store (`docs/caching.md`). Empty is ignored; whitespace alone is refused, as `cacheDir` is.        |
+| `VX_CACHE`                        | a `--cache` spec                    | all axes on | The run's cache policy when no `--cache` is passed (`local:rw,remote:r`); `--no-cache` and `--force` still apply on top. Empty is ignored; a bad spec is refused before any task.                                                                                                                                       |
+| `VX_CACHE_SCOPE`                  | a `cacheScope` value                | none        | The run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `vx.workspace`'s and `github()`'s; `--cache-scope` beats it. Empty is ignored; a value `cacheScope` would refuse is refused before any task.                                                                                                           |
+| `VX_INPUT_STABILITY`              | `immutable`, `mutable`, `unchecked` | `immutable` | The `inputStability.strategy` of every task, over its own and the workspace's, for the run: which writes to an input during the command withhold the save. `mutable` lets a rewrite to the bytes the key folded through, `unchecked` skips the check. Any other value is refused before a task runs (`docs/schema.md`). |
+| `VX_INPUT_STABILITY_SEVERITY`     | `warn`, `error`                     | `warn`      | The `inputStability.severity` of every task, over its own and the workspace's, for the run: `error` fails a task whose save a moved input withheld, so the run fails. Any other value is refused before a task runs.                                                                                                    |
+| `VX_KILL_GRACE_MS`                | positive integer (ms)               | 2000        | The SIGTERM → SIGKILL grace a child that ignores SIGTERM gets: on a timeout, on a signal, and at the end-of-run shutdown of persistent tasks. Out of range falls back to the default.                                                                                                                                   |
+| `VX_READY_NOTICE_MS`              | positive integer (ms)               | 10000       | How long a persistent task may take to match `readyWhen` before vx says once what it waits for. Out of range falls back to the default.                                                                                                                                                                                 |
+| `VX_TEARDOWN_TIMEOUT_MS`          | integer (ms)                        | 3000        | The bound on one plugin's end-of-run flush or teardown, and on its `telemetry()` setup, so a third party's I/O cannot hold the run. Out of range falls back to the default, never clamps: a bound of 24.8 days is no bound.                                                                                             |
+| `VX_CONFIG_WORKER_TIMEOUT_MS`     | integer (ms)                        | 30000       | How long one `vx.config.ts` evaluation may take, in process or in its worker, before the load fails naming the config (a real evaluation is ~10 ms). A synchronous loop on a first load holds the thread the deadline needs, so it hangs until killed. Out of range falls back to the default.                          |
+| `VX_WATCH_POLL`                   | any non-empty                       | off         | `vx watch` polls every 250 ms from the start instead of probing the OS watcher (§ `vx watch` › How changes are seen).                                                                                                                                                                                                   |
+| `VX_RUN_WORKSPACE`, `VX_RUN_TASK` | set by vx                           | —           | Set on every task's environment (the workspace root; `project#task`). Read back by a `vx run` a task starts: one in the same workspace is refused, since a nested run is invisible to the outer graph and a loop back to its own task forks without bound (`docs/schema.md` § `env`).                                   |
 
 Colors are the two conventions in § Output format › Colors (`NO_COLOR`,
 `FORCE_COLOR`). A truthy `CI` picks the CI output flow and

package/docs/execution.md

@@ -45,7 +45,7 @@ terminal and a task succeeding or failing. Read it alongside
  │    3. loadWorkspacePlugins — loadWorkspaceConfig reads the optional
  │       vx.workspace.{ts,mts,js,mjs,cts,cjs} at the root (concurrency /
  │       cacheDir / timeout / cacheRetention / affectedBase / cacheScope /
- │       rules / schedule / plugins),
+ │       rules / schedule / inputStability / plugins),
  │       then the plugin `config` stage runs on it.
  │    4. listProjects — globs every workspace member's package.json,
  │       finds sibling vx.config.* files, detects duplicate package

package/docs/features.md

@@ -81,15 +81,16 @@ config key or an environment variable is missing here.
 - **Opt-in, explicit inputs** (`cache.inputs.files`) — a task caches only when it names its inputs. [page](https://vznjs.github.io/vx/features/explicit-inputs/) · post: [Explicit over magical](https://vznjs.github.io/vx/blog/explicit-over-magical/)
 - **Inputs** (`cache.inputs.env`, `cache.inputs.runtime`, `cache.inputs.tasks`, `cache.inputs.workspaceFiles`, `cache.inputs.workspaceRuntime`) — env vars, tool versions, upstream tasks and workspace files in the key. [page](https://vznjs.github.io/vx/features/key-inputs/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Outputs** (`cache.outputs.files`, `cache.outputs.workspaceFiles`) — what a hit restores. [page](https://vznjs.github.io/vx/features/cache-outputs/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
+- **Input stability** (`cache.inputStability`, workspace `inputStability`, `VX_INPUT_STABILITY`, `VX_INPUT_STABILITY_SEVERITY`) — an input written while the command runs withholds the save, on CI too, and the saves of every task that ran over its outputs; `strategy: 'mutable'` accepts a task's identical rewrite of its own input, `'unchecked'` skips the check; `severity: 'error'` fails the run instead of warning. no post
 - **Outputs are exactly the snapshot** (`exclusiveOutputs`) — a hit leaves the tree as the run did; two tasks may not own one output without an edge. [page](https://vznjs.github.io/vx/features/strict-outputs/) · post: [The tree is exactly the snapshot](https://vznjs.github.io/vx/blog/strict-output-ownership/)
 - **Keys from git's index** — tracked clean files hash by their blob id, no read. [page](https://vznjs.github.io/vx/features/keys-from-git/) · post: [Your cache key is already in git's index](https://vznjs.github.io/vx/blog/keys-from-git/)
 - **Config keyed as evaluated** — the key sees the resolved config object. [page](https://vznjs.github.io/vx/features/typescript-config/) · post: [Configs are programs](https://vznjs.github.io/vx/blog/resolved-config-hashing/)
 - **Cascade through inputs** — a task's key folds its upstream input keys, never outputs. [page](https://vznjs.github.io/vx/features/cascade/) · post: [Cascade through dependencies](https://vznjs.github.io/vx/blog/cascade-through-inputs/)
 - **Lockfile-aware keys** (`@vzn/vx-lockfile`: `pnpm()`, `bun()`, `npm()`, `yarn()`) — a bump re-keys only the projects whose closure changed. [page](https://vznjs.github.io/vx/features/lockfile-keys/) · post: [A lockfile bump should re-key two tasks](https://vznjs.github.io/vx/blog/lockfile-aware-keys/)
 - **Upfront keys** (`upfrontKeys`) — refuses an input glob a same-project task's outputs could match, so every key is known before anything runs. [page](https://vznjs.github.io/vx/features/upfront-keys/) · post: [Cascade through dependencies by folding input keys, never outputs](https://vznjs.github.io/vx/blog/cascade-through-inputs/)
-- **Cache controls** (`--no-cache`, `--force`, `--cache`) — off, refresh, or per-layer read/write. [page](https://vznjs.github.io/vx/features/cache-controls/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
+- **Cache controls** (`--no-cache`, `--force`, `--cache`, `VX_CACHE`) — off, refresh, or per-layer read/write. [page](https://vznjs.github.io/vx/features/cache-controls/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache location** (`--cache-dir`, `cacheDir`, `VX_CACHE_DIR`) — where the cache lives. [page](https://vznjs.github.io/vx/features/cache-location/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
-- **Cache scope** (`cacheScope`, `VX_CACHE_SCOPE`) — trusted CI writes the remote cache; a laptop reads it. [page](https://vznjs.github.io/vx/features/cache-scope/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
+- **Cache scope** (`cacheScope`, `VX_CACHE_SCOPE`, `--cache-scope`) — trusted CI writes the remote cache; a laptop reads it. [page](https://vznjs.github.io/vx/features/cache-scope/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache pruning** (`vx cache prune`, `--older-than`, `--max-size`, `--dry-run`, `cacheRetention`, `maxSize`, `olderThan`) — evict by age or size, LRU. [page](https://vznjs.github.io/vx/features/cache-prune/) · post: [One command to know your workspace](https://vznjs.github.io/vx/blog/know-your-workspace/)
 - **Remote outputs** (`--download`) — all, top-level only, or none. [page](https://vznjs.github.io/vx/features/remote-downloads/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
 - **One store for every checkout** (`~/.vx/<id>/cache`) — clones and worktrees of a repo share cache entries. [page](https://vznjs.github.io/vx/features/shared-store/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
@@ -156,7 +157,7 @@ config key or an environment variable is missing here.
 
 ## Plugins
 
-- **A pipeline with seams** (`plugins`, `definePlugin`; stages `config` `discover` `project` `graph` `key` `fingerprint` `schedule` `admit` `executor` `cache` `telemetry` `commands`) — every stage is a plugin seam. [page](https://vznjs.github.io/vx/features/plugins/) · post: [A pipeline with seams](https://vznjs.github.io/vx/blog/pipeline-with-seams/)
+- **A pipeline with seams** (`plugins`, `definePlugin`; stages `config` `discover` `project` `graph` `key` `fingerprint` `schedule` `admit` `executor` `cache` `telemetry` `commands`) — every stage is a plugin seam; an `undefined`, `null` or `false` entry is skipped. [page](https://vznjs.github.io/vx/features/plugins/) · post: [A pipeline with seams](https://vznjs.github.io/vx/blog/pipeline-with-seams/)
 - **Write a plugin** (`vx init --plugin`) — scaffold a runnable plugin for a seam. [page](https://vznjs.github.io/vx/features/plugins/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)
 - **The local floor** — running and caching here are core's, not plugins. [page](https://vznjs.github.io/vx/features/local-floor/) · post: [The local floor](https://vznjs.github.io/vx/blog/the-local-floor/)
 - **Remote cache and execution** (`@vzn/vx-reapi`, `exec.remote`) — Bazel REAPI cache and workers; the scheduler stays here. [page](https://vznjs.github.io/vx/features/remote-execution/) · post: [Remote execution without moving the scheduler](https://vznjs.github.io/vx/blog/remote-execution/)

package/docs/patterns.md

@@ -183,13 +183,14 @@ Sharing the patterns doesn't mean sharing the overhead. On the
 476-package / 1,428-node synthetic workspace
 (`packages/vx-bench/compare.ts 20 25 1`, 2026-09-02):
 
-| Runner | Fresh (cold)          | Warm (no restore)       | Warm (restore)          |
-| ------ | --------------------- | ----------------------- | ----------------------- |
-| **vx** | 1m 40s                | **297 ms**              | **416 ms**              |
-| Turbo  | 1m 40s (vx same)      | 342 ms (vx 15% faster)  | 612 ms (vx 47% faster)  |
-| Nx     | 3m 23s (vx 2× faster) | 1.38 s (vx 4.6× faster) | 1.33 s (vx 3.2× faster) |
-
-vx N% faster: that tool takes N% longer than vx; N× faster: N times as long.
+| Runner | Warm (no restore) | Warm (restore) |
+| ------ | ----------------- | -------------- |
+| **vx** | **297 ms**        | **416 ms**     |
+| Turbo  | 342 ms            | 612 ms         |
+| Nx     | 1.38 s            | 1.33 s         |
+
+A cached run is all runner overhead. Cold builds are compared by the
+time the runner adds, on [`benchmarks.md`](./benchmarks.md).
 
 Full breakdown + methodology in [`benchmarks.md`](./benchmarks.md).