@vzn/vx 0.0.634 → 0.0.635

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                                            | **1.07 s**  | 898 ms (vx 19% slower)    | 25.45 s (vx 24× faster)    | 11.75 s (vx 11× faster)  |
+| Nothing changed, outputs restored                          | **1.27 s**  | 844 ms (vx 51% slower)    | 23.82 s (vx 19× faster)    | 11.83 s (vx 9.3× faster) |
+| Cold build                                                 | **7.07 s**  | 9.15 s (vx 29% faster)    | 3 min 48 s (vx 32× faster) | 8.16 s (vx 15% faster)   |
+| Cold build: CPU the runner burns                           | **32.28 s** | 1 min 3 s (vx 94% faster) | 6 min 6 s (vx 11× faster)  | 24.82 s (vx 30% slower)  |
+
+Time each tool adds over the ideal run; vx N% or N× faster means that tool adds N% more or N times as much as vx.
+
+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-09 on linux x64, 4 cores: vx at commit 3d48a981d, 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

@@ -704,7 +704,13 @@ 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.rewrittenInputs: 'compare'`, and a write
+during its command is then judged by its bytes, as an earlier write is;
+different bytes still withhold the entry. `VX_REWRITTEN_INPUTS=compare`
+makes that the default (owner, 2026-10-12). 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.
@@ -957,8 +960,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 +986,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 +1290,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 +1980,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 +2136,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 +2393,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 +2866,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 +3023,32 @@ 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_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_REWRITTEN_INPUTS`             | `withhold`, `compare` | `withhold` | What a write to an input during the command means for a task that does not set `cache.rewrittenInputs`: `compare` saves the entry when the file holds the bytes the key folded, anything else withholds it (`docs/schema.md`).                                                                                    |
+| `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_REWRITTEN_INPUTS`             | `withhold`, `compare` | `withhold` | What a write to an input during the command means for a task that does not set `cache.rewrittenInputs`: `compare` saves the entry when the file holds the bytes the key folded, anything else withholds it (`docs/schema.md`).                                                                                    |
+| `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`).                             |
 
 Colors are the two conventions in § Output format › Colors (`NO_COLOR`,
 `FORCE_COLOR`). A truthy `CI` picks the CI output flow and

package/docs/features.md

@@ -81,6 +81,7 @@ 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/)
+- **Rewritten inputs** (`cache.rewrittenInputs`, `VX_REWRITTEN_INPUTS`) — an input written while the command runs withholds the save, on CI too; `compare` accepts a task's identical rewrite of its own input. 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/)
@@ -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,11 +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) |
+| Runner | Warm (no restore)       | Warm (restore)          |
+| ------ | ----------------------- | ----------------------- |
+| **vx** | **297 ms**              | **416 ms**              |
+| Turbo  | 342 ms (vx 15% faster)  | 612 ms (vx 47% faster)  |
+| Nx     | 1.38 s (vx 4.6× faster) | 1.33 s (vx 3.2× faster) |
+
+A cached run is all runner overhead. Cold builds are compared by the
+time the runner adds, on [`benchmarks.md`](./benchmarks.md).
 
 vx N% faster: that tool takes N% longer than vx; N× faster: N times as long.
 

package/docs/schema.md

@@ -704,9 +704,38 @@ Semantics:
 interface CacheConfig {
   inputs: CacheInputs // required when `cache` is provided
   outputs: CacheOutputs // required when `cache` is provided
+  rewrittenInputs?: 'withhold' | 'compare' // optional, default 'withhold'
 }
 ```
 
+`rewrittenInputs` says what a write to an input while the command runs
+means. `'withhold'` (the default, on CI too): the result stands but the
+entry is not saved, since an edit undone mid-run, or another task
+changing the file and putting it back, cannot be told from no edit.
+`'compare'`: a file rewritten to the bytes the key folded counts as
+unchanged and the entry is saved, for a task that rewrites its own input
+identically (tsdown's `package.json`); different bytes still withhold
+it. `VX_REWRITTEN_INPUTS=compare` sets the default for every task that
+does not say (owner, 2026-10-12).
+
+```ts
+import { defineProject } from '@vzn/vx/config'
+
+export default defineProject({
+  tasks: {
+    build: {
+      // tsdown rewrites package.json with the same bytes on every build.
+      exec: { command: 'tsdown' },
+      cache: {
+        inputs: { files: ['src/**', 'package.json'] },
+        outputs: { files: ['dist/**'] },
+        rewrittenInputs: 'compare',
+      },
+    },
+  },
+})
+```
+
 **Caching is opt-in.** Omit `cache` and the task always runs (no read,
 no write). Provide it and caching is active for that task. The
 project loader requires _both_ `inputs` and `outputs` when `cache` is
@@ -1558,7 +1587,7 @@ interface WorkspaceConfig {
   /** Which ready task starts first with no timings: 'most-work' (default), 'critical-path', 'direct-dependents', 'ready-order'. */
   schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
   /** Run-level plugins (cache / executor / telemetry capabilities). */
-  plugins?: readonly Plugin[]
+  plugins?: readonly (Plugin | undefined | null | false)[]
 }
 
 interface WorkspaceRules {
@@ -1682,7 +1711,9 @@ false } in vx.workspace.ts to let it wait for its producer.` Such a key
   Declaration order is precedence: every `executor` is consulted in
   order per task (first to accept runs it; what all decline runs
   locally); every `cache` layer is chained (lookup walks, save reaches
-  all, the local store last). Each entry is a `VxPlugin` contributing
+  all, the local store last). An `undefined`, `null` or `false` entry
+  is skipped, as Vite skips one: a factory that declines (`github()` off
+  Actions) or `cond && plugin()` needs no filter. Each entry is a `VxPlugin` contributing
   any subset of the fourteen hooks, in pipeline order: `config` (edit
   the workspace config before anything derives from it), `discover`
   (name directories to make projects beyond the members), `project`
@@ -2057,6 +2088,7 @@ a user meets most:
 | `cache.inputs.tasks must be an array of non-empty strings`                                                                            | Non-string / empty entry, or a bare string.                                                                                                                                                                                    |
 | `cache.inputs.tasks: "<name>" names no task in <task>.dependsOn`                                                                      | An exact entry no `dependsOn` entry of its form names.                                                                                                                                                                         |
 | `cache.outputs is required when cache is set`                                                                                         | Forgot `outputs`.                                                                                                                                                                                                              |
+| `cache.rewrittenInputs must be 'withhold' or 'compare'`                                                                               | Any other value (`'bytes'`, `true`).                                                                                                                                                                                           |
 | `cache.outputs must be an object`                                                                                                     | Present but not an object: a string (`outputs: 'dist'`). An array is the row above.                                                                                                                                            |
 | `cache.outputs.files must be an array`                                                                                                | Wrong shape.                                                                                                                                                                                                                   |
 | `cache.inputs.files: every entry is a negation, which selects NOTHING`                                                                | Only `!` globs — nothing to subtract from.                                                                                                                                                                                     |

package/docs/security.md

@@ -89,6 +89,12 @@ writes whatever its config says. Never give the write secret to a
 out a pull request's code: it runs with main's ref and secrets, and
 `github()` scopes it `pr-<n>` only on the client side.
 
+A boundary that holds whoever can write the store is a signing cache
+plugin: main's CI signs each upload, and a reader refuses, as it streams,
+a download no trusted key signed, so the hit is a miss. Core needs no
+change for it; the plugins guide (§ Your own cache › Signed artifacts) has a
+complete one, run by `tests/signed-cache-guide.unsafe.test.ts`.
+
 ## What vx checks on bytes it did not write
 
 Every artifact that arrives from a remote, and every one read back from

package/launcher.sh

@@ -0,0 +1,50 @@
+#!/bin/sh
+# npm launcher for a vx command: the published package's `bin`. It execs the
+# platform package's prebuilt binary straight from the shell, since Node's
+# own start was ~40 ms of every `vx` call made through node_modules/.bin
+# (45-53 ms against 12-14 ms for `vx --version`, 2026-10-12). Anything it
+# cannot settle (no sibling platform package, musl, Yarn PnP, an unknown
+# platform) goes to launcher.cjs beside it, which resolves through Node and
+# owns the fallbacks and the error messages.
+
+# The real file: npm's .bin entry is a symlink to it. Parameter expansion,
+# not dirname/basename, and no `cd`: each fork is a millisecond, and the
+# kernel resolves `<dir>/..` through a symlinked directory (pnpm's
+# node_modules/@vzn/vx) to its real parent on its own.
+self=$0
+hops=0
+while [ -L "$self" ] && [ "$hops" -lt 40 ]; do
+  hops=$((hops + 1))
+  target=$(readlink "$self")
+  case $target in
+    /*) self=$target ;;
+    *) self=${self%/*}/$target ;;
+  esac
+done
+case $self in
+  */*) here=${self%/*} ;;
+  *) here=. ;;
+esac
+base=${here##*/}
+scope=${here%/*}
+scope=${scope##*/}
+
+key=
+loader=
+case $(uname -sm) in
+  'Linux x86_64') key=linux-x64 loader=/lib64/ld-linux-x86-64.so.2 ;;
+  'Linux aarch64' | 'Linux arm64') key=linux-arm64 loader=/lib/ld-linux-aarch64.so.1 ;;
+  'Darwin x86_64') key=darwin-x64 ;;
+  'Darwin arm64') key=darwin-arm64 ;;
+esac
+
+# The platform package sits beside this one under npm, pnpm and Bun
+# (node_modules/@vzn/vx-<key>), or under this package's own node_modules
+# when npm could not hoist it. The glibc binary needs its loader (musl
+# has none); launcher.cjs names that cause.
+if [ -n "$key" ] && { [ -z "$loader" ] || [ -e "$loader" ]; }; then
+  for bin in "$here/../$base-$key/$base" "$here/node_modules/$scope/$base-$key/$base"; do
+    if [ -x "$bin" ]; then exec "$bin" "$@"; fi
+  done
+fi
+exec node "$here/launcher.cjs" "$@"