@vzn/vx 0.0.635 → 0.0.636

package/README.md

@@ -138,17 +138,17 @@ Every gap, and when another tool is the better pick:
 
 <!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
 
-| 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 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; vx N% or N× faster means that tool adds N% more or N times as much as vx.
+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-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.
+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/).
 

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
@@ -707,10 +711,12 @@ names a file other than `package.json` (TanStack Router's committed
 `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
+`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_REWRITTEN_INPUTS=compare`
-makes that the default (owner, 2026-10-12). A file ADDED under an
+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

@@ -480,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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
@@ -571,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).
@@ -3023,32 +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_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`).                             |
+| 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,16 +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/)
-- **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
+- **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/)

package/docs/patterns.md

@@ -183,17 +183,15 @@ 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 | 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) |
+| 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).
 
-vx N% faster: that tool takes N% longer than vx; N× faster: N times as long.
-
 Full breakdown + methodology in [`benchmarks.md`](./benchmarks.md).
 
 ## Where the lineage diverges

package/docs/schema.md

@@ -704,19 +704,47 @@ Semantics:
 interface CacheConfig {
   inputs: CacheInputs // required when `cache` is provided
   outputs: CacheOutputs // required when `cache` is provided
-  rewrittenInputs?: 'withhold' | 'compare' // optional, default 'withhold'
+  inputStability?: InputStability // optional
+}
+
+interface InputStability {
+  strategy?: 'immutable' | 'mutable' | 'unchecked' // default 'immutable'
+  severity?: 'warn' | 'error' // default 'warn'
 }
 ```
 
-`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).
+`inputStability` says what a write to an input while the command runs
+means. `strategy` says which writes count:
+
+- `'immutable'` (the default, on CI too): any write. An edit undone
+  mid-run, or another task changing the file and putting it back, cannot
+  be told from no edit.
+- `'mutable'`: a file rewritten to the bytes the key folded counts as
+  unchanged, for a task that rewrites its own input identically
+  (tsdown's `package.json`); different bytes still count.
+- `'unchecked'`: none. The entry is saved under the key taken before the
+  command, whatever the command did to its inputs; `severity` is ignored.
+  A key that no longer held before the command started still withholds
+  it.
+
+A write that counts withholds the entry, and `severity` says what else
+happens: `'warn'` (the default) keeps the result, says why on the status
+line, and the run goes on; `'error'` fails the task, so the run fails.
+Either way, every task that ran over the task's outputs, down the graph,
+withholds its save too, and a task of any project that declares the
+moved file as an input withholds its own.
+
+Each field is resolved on its own, highest first:
+
+1. `VX_INPUT_STABILITY` (`immutable`, `mutable`, `unchecked`) and
+   `VX_INPUT_STABILITY_SEVERITY` (`warn`, `error`), for the whole run
+   (a CI job that wants `error` sets it without editing configs); any
+   other value is refused before a task runs;
+2. the task's own `cache.inputStability`;
+3. the workspace's `inputStability` (`vx.workspace.ts`);
+4. the default, `'immutable'` and `'warn'`.
+
+Never folded into a cache key.
 
 ```ts
 import { defineProject } from '@vzn/vx/config'
@@ -724,12 +752,13 @@ import { defineProject } from '@vzn/vx/config'
 export default defineProject({
   tasks: {
     build: {
-      // tsdown rewrites package.json with the same bytes on every build.
+      // tsdown rewrites package.json with the same bytes on every build;
+      // different bytes fail the run rather than rebuild next time.
       exec: { command: 'tsdown' },
       cache: {
         inputs: { files: ['src/**', 'package.json'] },
         outputs: { files: ['dist/**'] },
-        rewrittenInputs: 'compare',
+        inputStability: { strategy: 'mutable', severity: 'error' },
       },
     },
   },
@@ -1564,6 +1593,7 @@ export default defineWorkspace({
   cacheScope: 'trusted',
   rules: { exclusiveOutputs: true, upfrontKeys: true },
   schedule: 'most-work',
+  inputStability: { strategy: 'immutable', severity: 'warn' },
   plugins: [otel()],
 })
 ```
@@ -1586,6 +1616,8 @@ interface WorkspaceConfig {
   rules?: WorkspaceRules
   /** 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'
+  /** Every task's cache.inputStability default: { strategy, severity }. */
+  inputStability?: InputStability
   /** Run-level plugins (cache / executor / telemetry capabilities). */
   plugins?: readonly (Plugin | undefined | null | false)[]
 }
@@ -1659,7 +1691,7 @@ run` takes `'read-only'` off CI (`CI` unset, `0` or `false`) and
   each other. A scope's key is derived from the task key, so every
   remote wire stores it unchanged. A clamp on `--cache`, never a
   widening. `github()` sets it on Actions: `pr-<n>`, `ref-<name>` off
-  the default branch. `VX_CACHE_SCOPE` beats both. A client-side convention, not a security
+  the default branch. `VX_CACHE_SCOPE` beats both, and `vx run --cache-scope` beats all three. A client-side convention, not a security
   boundary: a run holding a write credential can write any key, so only
   a cache server that scopes writes by token can refuse one
   (`docs/security.md` § Cache poisoning). Not folded into any cache key.
@@ -1674,6 +1706,10 @@ run` takes `'read-only'` off CI (`CI` unset, `0` or `false`) and
   their ties. The default costs what it did; another strategy is
   computed only when named. Any other value is refused. Never folded
   into a cache key.
+- **`inputStability`** — the `cache.inputStability` of every task that
+  does not set its own field, same shape (`{ strategy, severity }`, §
+  `cache`). The env vars still override it for the run. Never folded
+  into a cache key.
 - **`rules`** — checks on the task graph, each on unless set to
   `false`. Turning one off allows a shape vx runs correctly but more
   slowly; never folded into a cache key. A value that is not a boolean,
@@ -2088,7 +2124,9 @@ 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.inputStability must be an object`                                                                                              | A bare string (`inputStability: 'mutable'`).                                                                                                                                                                                   |
+| `cache.inputStability.strategy must be 'immutable', 'mutable' or 'unchecked'`                                                         | Any other value (`'content'`, `false`).                                                                                                                                                                                        |
+| `cache.inputStability.severity must be 'warn' or 'error'`                                                                             | Any other value (`'fail'`, `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

@@ -42,7 +42,7 @@ namespace), or none.
 `cacheScope` is the client half. `'pr-123'` reads its own keys,
 then the trusted ones, and writes only its own, which `github()` sets on
 Actions (`pr-<n>`, `ref-<name>`; the default branch stays trusted)
-and `VX_CACHE_SCOPE` sets on any CI.
+and `VX_CACHE_SCOPE` or `--cache-scope` sets on any CI.
 It keeps honest runs apart and stops a non-hermetic PR build from
 landing where main reads; it is not a boundary, since the PR's own
 config decides it and any run holding a write credential can write any

package/package.json

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

package/schemas/show.json

@@ -116,7 +116,14 @@
                 "workspaceFiles": { "$ref": "#/$defs/stringList" }
               }
             },
-            "rewrittenInputs": { "enum": ["withhold", "compare"] }
+            "inputStability": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "strategy": { "enum": ["immutable", "mutable", "unchecked"] },
+                "severity": { "enum": ["warn", "error"] }
+              }
+            }
           }
         }
       }

package/src/cli/help.ts

@@ -140,7 +140,9 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                                  (layer = local|remote, flags ⊆ rw). A named layer is set EXACTLY',
     '                                  to its flags; unnamed layers keep their value. Examples:',
     '                                  local:rw,remote:r (remote read-only), remote: (remote off),',
-    '                                  local:r (local read-only).',
+    '                                  local:r (local read-only). Without it, VX_CACHE holds the spec.',
+    "      --cache-scope <name>        This run's cacheScope: trusted | read-only | a scope (pr-123).",
+    '                                  Beats VX_CACHE_SCOPE and the workspace cacheScope.',
     '      --cache-dir <path>          Cache directory override (cwd-relative). Beats VX_CACHE_DIR,',
     '                                  the workspace cacheDir field and the ~/.vx/<id>/cache default.',
     '      --retry <n>                 Re-run a failed task up to <n> more times (default for tasks',

package/src/cli/run.ts

@@ -1,7 +1,7 @@
 import { appendFileSync, mkdirSync } from 'node:fs'
 import path from 'node:path'
 import { isatty } from 'node:tty'
-import { findWorkspaceRoot } from '../workspace/index.js'
+import { cacheScopeError, findWorkspaceRoot, isCacheScope } from '../workspace/index.js'
 import { translateForeign } from './foreign-flags.js'
 import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import {
@@ -52,6 +52,8 @@ export interface RunArgs {
   remoteRequested?: boolean
   /** `--cache-dir <path>`: override the cache directory (cwd-relative). */
   cacheDir: string | undefined
+  /** `--cache-scope <name>`: this run's `cacheScope`, above `VX_CACHE_SCOPE` and the workspace's. */
+  cacheScope?: string
   frozen: boolean
   /**
    * `--retry <n>` / `--retry=<n>`: run-level retry default for tasks
@@ -158,6 +160,7 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
   // beats `--force`, and `--cache` is the base both may override.
   let cachePolicy: CachePolicy = { ...FULL_CACHE_POLICY }
   let cacheSpecError: string | undefined
+  let cacheFlag = false
   let noCacheFlag = false
   let forceFlag = false
 
@@ -282,7 +285,13 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
         }
       }
       out.cacheDir = v
+    } else if (a === '--cache-scope' || a?.startsWith('--cache-scope=')) {
+      const v = a === '--cache-scope' ? before[++i] : a.slice('--cache-scope='.length)
+      if (v === undefined || !isCacheScope(v))
+        return { ...out, error: cacheScopeError('--cache-scope') }
+      out.cacheScope = v
     } else if (a === '--cache' || a?.startsWith('--cache=')) {
+      cacheFlag = true
       const v = a === '--cache' ? before[++i] : a.slice('--cache='.length)
       if (v === undefined)
         return {
@@ -407,6 +416,21 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
   if (cacheSpecError !== undefined) {
     return { ...out, error: cacheSpecError }
   }
+  // `VX_CACHE` is the spec a run takes when no `--cache` names one.
+  const envSpec = process.env['VX_CACHE'] || undefined
+  if (!cacheFlag && envSpec !== undefined) {
+    if (!envSpec.split(',').some((seg) => seg.trim().length > 0))
+      return {
+        ...out,
+        error: `VX_CACHE needs a spec like local:r, local:rw, remote:, or local:,remote:rw`,
+      }
+    try {
+      cachePolicy = parseCachePolicy(envSpec, cachePolicy)
+    } catch (err) {
+      return { ...out, error: `VX_CACHE: ${err instanceof Error ? err.message : String(err)}` }
+    }
+    if (/remote:[rw]/.test(envSpec)) out.remoteRequested = true
+  }
   // Precedence: --no-cache (all off) beats --force (reads off, writes
   // kept), both layered on top of any --cache spec.
   if (noCacheFlag) {
@@ -611,6 +635,7 @@ export async function resolveRunOptions(
     tasks: [...tasks],
     cache: parsed.cache,
     ...(parsed.remoteRequested ? { remoteRequested: true } : {}),
+    ...(parsed.cacheScope !== undefined ? { cacheScope: parsed.cacheScope } : {}),
     // A laptop reads the shared cache and never writes it (owner,
     // 2026-10-03); naming the remote in `--cache` is asking to.
     ...(!parsed.remoteRequested && !onCI(process.env['CI'])

package/src/config.ts

@@ -42,7 +42,8 @@ export interface WorkspaceConfig {
    * then the trusted ones, and writes go to the scope's only, so a PR never
    * writes what the default branch reads. A client-side convention, not a
    * security boundary: only a cache server that scopes writes by token
-   * can refuse a run that ignores it. `VX_CACHE_SCOPE` beats it. Never
+   * can refuse a run that ignores it. `VX_CACHE_SCOPE` beats it, and
+   * `vx run --cache-scope` beats both. Never
    * folded into a cache key.
    */
   cacheScope?: string
@@ -55,6 +56,12 @@ export interface WorkspaceConfig {
    * `schedule` plugin's weights still come first; this breaks their ties.
    */
   schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
+  /**
+   * The `cache.inputStability` of every task that does not set its own
+   * field. `VX_INPUT_STABILITY` / `VX_INPUT_STABILITY_SEVERITY` override
+   * both for the run.
+   */
+  inputStability?: InputStability
   /**
    * Graph rules a run checks before it schedules anything. Each is on unless
    * set to `false`; turning one off allows a shape vx handles correctly but
@@ -491,15 +498,29 @@ export interface CacheConfig {
   /** What this task produces. Captured for restore on a cache hit. */
   outputs: CacheOutputs
   /**
-   * What a write to an input while the command runs means. `'withhold'`
-   * (the default): the entry is not saved, whatever the file holds after,
-   * since an edit undone mid-run cannot be told from no edit. `'compare'`:
-   * a file rewritten to the bytes the key folded counts as unchanged, for
-   * a task that rewrites its own input identically (tsdown's
-   * `package.json`). `VX_REWRITTEN_INPUTS=compare` sets the default for
-   * every task that does not say.
+   * What a write to an input while the command runs means. Each field,
+   * highest first: its env var, this, the workspace's `inputStability`,
+   * the default (`'immutable'`, `'warn'`).
+   */
+  inputStability?: InputStability
+}
+
+export interface InputStability {
+  /**
+   * `'immutable'` (the default): any write to an input during the command
+   * withholds the entry, whatever the file holds after, since an edit
+   * undone mid-run cannot be told from no edit. `'mutable'`: a file
+   * rewritten to the bytes the key folded counts as unchanged, for a task
+   * that rewrites its own input identically (tsdown's `package.json`).
+   * `'unchecked'`: no check.
+   */
+  strategy?: 'immutable' | 'mutable' | 'unchecked'
+  /**
+   * What a withheld entry does to the run. `'warn'` (the default): the
+   * result stands, vx says why, and the run goes on. `'error'`: the task
+   * fails, so the run fails.
    */
-  rewrittenInputs?: 'withhold' | 'compare'
+  severity?: 'warn' | 'error'
 }
 
 export interface CacheOutputs {

package/src/index.ts

@@ -48,6 +48,7 @@ export type {
   CacheConfig,
   CacheInputs,
   CacheOutputs,
+  InputStability,
   SandboxConfig,
   SandboxGrants,
   SandboxDenials,

package/src/orchestrator/execute-task.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import type { ExecConfig, TaskConfig, CacheConfig } from '../config.js'
+import type { ExecConfig, TaskConfig, CacheConfig, InputStability } from '../config.js'
 import {
   ArtifactVanishedError,
   type CacheEntry,
@@ -175,6 +175,11 @@ export interface ExecuteArgs {
    * `exec.timeout` wins. Threaded as an option only — never hashed.
    */
   timeout?: number
+  /**
+   * The run's `inputStability` layers around the task's own: `run` from
+   * the env vars (above the task), `workspace` from `vx.workspace` (below).
+   */
+  inputStability?: { run: InputStability; workspace?: InputStability }
   /** Per-run memo for `git ls-files` (one entry per project dir). */
   gitFilesCache?: GitFilesCache
   /** Per-run memo for derived hashes (package.json bytes + task config). */
@@ -338,15 +343,21 @@ async function restoreOrMiss(
 }
 
 /**
- * Does a write to an input during the command count as unchanged when it
- * left the bytes the key folded (`movedInput`'s `writesByBytes`)? Only when
- * the task says `compare`, or says nothing and `VX_REWRITTEN_INPUTS` is
- * `compare`: by default any such write withholds the save, on CI too,
- * since a concurrent task can change an input and put it back (owner,
- * 2026-10-12).
+ * What a write to an input during the command means, each field highest
+ * first: the env var (`layers.run`), the task's `cache.inputStability`,
+ * the workspace's, then `'immutable'` and `'warn'` (owner, 2026-10-12), so
+ * by default any such write withholds the save, on CI too, since a
+ * concurrent task can change an input and put it back.
  */
-function rewritesByBytes(cache: CacheConfig | undefined): boolean {
-  return (cache?.rewrittenInputs ?? process.env['VX_REWRITTEN_INPUTS']) === 'compare'
+function inputStabilityOf(
+  cache: CacheConfig | undefined,
+  layers: ExecuteArgs['inputStability'],
+): Required<InputStability> {
+  const task = cache?.inputStability
+  return {
+    strategy: layers?.run.strategy ?? task?.strategy ?? layers?.workspace?.strategy ?? 'immutable',
+    severity: layers?.run.severity ?? task?.severity ?? layers?.workspace?.severity ?? 'warn',
+  }
 }
 
 /**
@@ -1462,6 +1473,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
 
   const wallclockEndNs = process.hrtime.bigint() - args.runStartHrTimeNs
 
+  const stability = inputStabilityOf(args.node.config.cache, args.inputStability)
+  let movedFails = false
   let own: Awaited<ReturnType<typeof ownOutputs>>
   if (effectiveExitCode === 0 && willSave && deferralRequested) {
     // The outputs never landed here: no artifact, no rows. A partial local
@@ -1576,7 +1589,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         described!.facts,
         cache,
         described!.describedAt,
-        rewritesByBytes(args.node.config.cache),
+        stability.strategy === 'mutable',
       )) ?? described!.added()
     )
   }
@@ -1597,6 +1610,10 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       unkeyed = true
       return false
     }
+    // `'unchecked'` skips the check of the command's own window; a key the
+    // re-derive before the command already disagreed with still withholds,
+    // since it never described the bytes the command read.
+    if (stability.strategy === 'unchecked' && described!.hash === hash) return true
     const endCheck = span('miss: recheck inputs')
     const moved = await movedSinceKey()
     endCheck()
@@ -1611,15 +1628,25 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       moved === null || path.basename(moved) === 'package.json'
         ? ''
         : '; if the task writes it, declare it in cache.outputs'
-    log.status(
-      `[vx] ${node.id}: ${what} changed after its key was taken — the result stands, ` +
-        `but is not saved under a key that no longer describes it${hint}`,
-    )
+    if (stability.severity === 'error') {
+      log.status(
+        `[vx] ${node.id}: ${what} changed after its key was taken — the result is not saved, ` +
+          `and inputStability.severity is 'error', so the task fails${hint}`,
+      )
+      movedFails = true
+    } else {
+      log.status(
+        `[vx] ${node.id}: ${what} changed after its key was taken — the result stands, ` +
+          `but is not saved under a key that no longer describes it${hint}`,
+      )
+    }
     forgetUndeclaredWrites(args, wsOutputs.length > 0 ? 'workspace' : 'project')
     unkeyed = true
     return false
   }
 
+  if (movedFails) effectiveExitCode = 1
+
   if (unkeyedUpstream !== undefined && willWrite && effectiveExitCode === 0) {
     log.status(
       `[vx] ${node.id}: ran over ${unkeyedUpstream.node.id}'s outputs, which its key no longer ` +

package/src/orchestrator/options.ts

@@ -86,6 +86,8 @@ export interface RunOptions {
    * saying it is not.
    */
   remoteRequested?: boolean
+  /** This run's `cacheScope` (the CLI's `--cache-scope`), above `VX_CACHE_SCOPE` and `vx.workspace`. */
+  cacheScope?: string
   /**
    * The `cacheScope` a run takes when `vx.workspace` names none. The CLI
    * passes `'read-only'` off CI (`CI` unset, `0` or `false`) unless

package/src/orchestrator/prepare.ts

@@ -288,13 +288,13 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
 
   // The local cache opens BEFORE the configs load: it is also where their
   // cached evaluations live.
-  // `VX_CACHE_SCOPE` wins over the workspace (and `github()`'s guess):
+  // `--cache-scope`, then `VX_CACHE_SCOPE`, win over the workspace (and `github()`'s guess):
   // a CI job that knows its trust level says so without editing config.
   const envScope = process.env['VX_CACHE_SCOPE'] || undefined
   if (envScope !== undefined && !isCacheScope(envScope)) throw cacheScopeEnvError()
   const policy: CachePolicy = scopeCachePolicy(
     options.cache ?? FULL_CACHE_POLICY,
-    envScope ?? workspaceConfig?.cacheScope ?? options.defaultCacheScope,
+    options.cacheScope ?? envScope ?? workspaceConfig?.cacheScope ?? options.defaultCacheScope,
   )
   const localCache = new Cache(
     cacheDir,

package/src/orchestrator/run.ts

@@ -3,7 +3,12 @@
 // so the layers can be swapped without touching the others.
 
 import type { ProjectEntry } from '../workspace/index.js'
-import { loadWorkspace, unreachedHint, unreachedPackages } from '../workspace/index.js'
+import {
+  inputStabilityEnv,
+  loadWorkspace,
+  unreachedHint,
+  unreachedPackages,
+} from '../workspace/index.js'
 import { realpathSync } from 'node:fs'
 import path from 'node:path'
 import {
@@ -610,6 +615,13 @@ async function runOnBus(
   // ignored (a bad timeout must not silently disable a task's own limit).
   const taskTimeoutDefault =
     options.timeout ?? readTaskTimeoutEnv() ?? workspaceConfig?.timeout ?? undefined
+  // Read once, before any task: a bad value is refused here, not mid-run.
+  const inputStability = {
+    run: inputStabilityEnv(),
+    ...(workspaceConfig?.inputStability !== undefined
+      ? { workspace: workspaceConfig.inputStability }
+      : {}),
+  }
 
   // Run-scoped registries of live subprocesses:
   //   - `liveChildren`: in-flight children. The runner adds/removes
@@ -1056,6 +1068,7 @@ async function runOnBus(
       }
       if (options.retries !== undefined) a.retries = options.retries
       if (taskTimeoutDefault !== undefined) a.timeout = taskTimeoutDefault
+      a.inputStability = inputStability
       if (download.modeOf.get(node.id) === 'deferred') a.download = 'deferred'
       if (placements.remoteOnlyNoop.has(node.id)) a.remoteOnlyNoop = true
       if (placements.remoteOnly.has(node.id)) a.remoteOnly = true

package/src/orchestrator/task-hash.ts

@@ -238,7 +238,7 @@ export async function describeTaskInputs(args: ComputeHashArgs): Promise<{
  * input changed and changed BACK while the command ran matched its digest
  * again, and the entry saved the other content's output under the key (item
  * 1015). A write before it — an upstream's — is judged by content, as before.
- * `writesByBytes` (`cache.rewrittenInputs: 'compare'`) judges a write
+ * `writesByBytes` (`inputStability.strategy: 'mutable'`) judges a write
  * during the command by content too: the task says the same bytes are its
  * own identical rewrite (tsdown's package.json), not an edit undone.
  */

package/src/workspace/config-schema.ts

@@ -10,6 +10,7 @@ import {
   PLUGIN_FUNCTION_HOOKS,
   PLUGIN_HOOKS,
   PLUGIN_PACKAGE,
+  type InputStability,
   type Plugin,
   type ProjectConfig,
   type WorkspaceConfig,
@@ -43,9 +44,65 @@ export function isCacheScope(v: unknown): v is string {
   return typeof v === 'string' && /^[\w.@/-]{1,128}$/.test(v)
 }
 
-/** Why `VX_CACHE_SCOPE` is refused, in `cacheScope`'s words. */
+/** Why a `VX_CACHE_SCOPE` or `--cache-scope` value is refused, in `cacheScope`'s words. */
+export function cacheScopeError(source = 'VX_CACHE_SCOPE'): string {
+  return `${source} ${CACHE_SCOPE_RULE}`
+}
+
+/** Why `VX_CACHE_SCOPE` is refused, as the run's error. */
 export function cacheScopeEnvError(): UserError {
-  return new UserError(`VX_CACHE_SCOPE ${CACHE_SCOPE_RULE}`)
+  return new UserError(cacheScopeError())
+}
+
+const STRATEGIES = ['immutable', 'mutable', 'unchecked'] as const
+const SEVERITIES = ['warn', 'error'] as const
+const INPUT_STABILITY_FIELDS = new Set(['strategy', 'severity'])
+const oneOf = (values: readonly string[]): string =>
+  `must be ${values
+    .map((v) => `'${v}'`)
+    .join(', ')
+    .replace(/, ([^,]*)$/, ' or $1')}`
+
+function envOneOf<T extends string>(
+  name: string,
+  raw: string | undefined,
+  values: readonly T[],
+): T | undefined {
+  if (raw === undefined || raw === '') return undefined
+  if (!(values as readonly string[]).includes(raw)) throw new UserError(`${name} ${oneOf(values)}`)
+  return raw as T
+}
+
+function validateInputStability(stability: unknown, at: string): void {
+  if (typeof stability !== 'object' || stability === null || Array.isArray(stability)) {
+    throw new UserError(`${at} must be an object — \`inputStability: { strategy: 'mutable' }\``)
+  }
+  assertKnownFields(stability, INPUT_STABILITY_FIELDS, at)
+  const { strategy, severity } = stability as Record<string, unknown>
+  if (strategy !== undefined && !STRATEGIES.includes(strategy as never)) {
+    throw new UserError(`${at}.strategy ${oneOf(STRATEGIES)}`)
+  }
+  if (severity !== undefined && !SEVERITIES.includes(severity as never)) {
+    throw new UserError(`${at}.severity ${oneOf(SEVERITIES)}`)
+  }
+}
+
+/**
+ * `VX_INPUT_STABILITY` and `VX_INPUT_STABILITY_SEVERITY`, which override
+ * every task's `cache.inputStability` for the run: each undefined when
+ * unset or empty, refused when it names no value.
+ */
+export function inputStabilityEnv(): InputStability {
+  const strategy = envOneOf('VX_INPUT_STABILITY', process.env['VX_INPUT_STABILITY'], STRATEGIES)
+  const severity = envOneOf(
+    'VX_INPUT_STABILITY_SEVERITY',
+    process.env['VX_INPUT_STABILITY_SEVERITY'],
+    SEVERITIES,
+  )
+  return {
+    ...(strategy !== undefined ? { strategy } : {}),
+    ...(severity !== undefined ? { severity } : {}),
+  }
 }
 
 const WORKSPACE_FIELDS = new Set([
@@ -57,6 +114,7 @@ const WORKSPACE_FIELDS = new Set([
   'cacheScope',
   'rules',
   'schedule',
+  'inputStability',
   'plugins',
 ])
 
@@ -198,6 +256,9 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
     throw new UserError(`${configPath}: \`cacheScope\` ${CACHE_SCOPE_RULE}`)
   }
   if (config.rules !== undefined) validateRules(config.rules, configPath)
+  if (config.inputStability !== undefined) {
+    validateInputStability(config.inputStability, `${configPath}: \`inputStability\``)
+  }
   if (config.schedule !== undefined && !Object.hasOwn(SCHEDULES, config.schedule)) {
     throw new UserError(
       `${configPath}: \`schedule\` must be one of ${Object.keys(SCHEDULES)
@@ -668,10 +729,9 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         )
       }
       assertKnownFields(cache, CACHE_FIELDS, `${where}.cache`)
-      const rewritten = (cache as { rewrittenInputs?: unknown }).rewrittenInputs
-      if (rewritten !== undefined && rewritten !== 'withhold' && rewritten !== 'compare') {
-        throw new UserError(`${where}.cache.rewrittenInputs must be 'withhold' or 'compare'`)
-      }
+      const stability = (cache as { inputStability?: unknown }).inputStability
+      if (stability !== undefined)
+        validateInputStability(stability, `${where}.cache.inputStability`)
       const inputs = (cache as { inputs?: unknown }).inputs
       const outputs = (cache as { outputs?: unknown }).outputs
       // A present field of the wrong shape (`outputs: 'dist'`) was told it
@@ -908,7 +968,7 @@ const EXEC_FIELDS = new Set([
 ])
 const PERSISTENT_FIELDS = new Set(['readyWhen'])
 const ENV_FIELDS = new Set(['passThrough', 'define', 'secret'])
-const CACHE_FIELDS = new Set(['inputs', 'outputs', 'rewrittenInputs'])
+const CACHE_FIELDS = new Set(['inputs', 'outputs', 'inputStability'])
 const CACHE_INPUT_FIELDS = new Set([
   'files',
   'workspaceFiles',
@@ -951,6 +1011,15 @@ export const REMOVED_FIELDS: ReadonlyMap<
       },
     },
   ],
+  [
+    CACHE_FIELDS,
+    {
+      rewrittenInputs: {
+        removedIn: '0.0.636',
+        use: "`inputStability: { strategy: 'immutable' | 'mutable' }` ('withhold', 'compare')",
+      },
+    },
+  ],
 ])
 
 /**

package/src/workspace/index.ts

@@ -37,6 +37,8 @@ export {
 } from './project-loader.js'
 export {
   cacheScopeEnvError,
+  cacheScopeError,
+  inputStabilityEnv,
   isCacheScope,
   validateProjectConfig,
   validateWorkspace,