@vzn/vx 0.0.634 → 0.0.636

package/docs/schema.md

@@ -704,7 +704,65 @@ Semantics:
 interface CacheConfig {
   inputs: CacheInputs // required when `cache` is provided
   outputs: CacheOutputs // required when `cache` is provided
+  inputStability?: InputStability // optional
 }
+
+interface InputStability {
+  strategy?: 'immutable' | 'mutable' | 'unchecked' // default 'immutable'
+  severity?: 'warn' | 'error' // default 'warn'
+}
+```
+
+`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'
+
+export default defineProject({
+  tasks: {
+    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/**'] },
+        inputStability: { strategy: 'mutable', severity: 'error' },
+      },
+    },
+  },
+})
 ```
 
 **Caching is opt-in.** Omit `cache` and the task always runs (no read,
@@ -1535,6 +1593,7 @@ export default defineWorkspace({
   cacheScope: 'trusted',
   rules: { exclusiveOutputs: true, upfrontKeys: true },
   schedule: 'most-work',
+  inputStability: { strategy: 'immutable', severity: 'warn' },
   plugins: [otel()],
 })
 ```
@@ -1557,8 +1616,10 @@ 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[]
+  plugins?: readonly (Plugin | undefined | null | false)[]
 }
 
 interface WorkspaceRules {
@@ -1630,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.
@@ -1645,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,
@@ -1682,7 +1747,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 +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.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
@@ -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" "$@"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.634",
-  "description": "The fastest task runner and build cache for JavaScript monorepos.",
+  "version": "0.0.636",
+  "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
     ".": {
@@ -15,16 +15,16 @@
   },
   "types": "./src/index.ts",
   "bin": {
-    "vx": "./launcher.cjs"
+    "vx": "./launcher.sh"
   },
   "engines": {
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.634",
-    "@vzn/vx-linux-arm64": "0.0.634",
-    "@vzn/vx-darwin-x64": "0.0.634",
-    "@vzn/vx-darwin-arm64": "0.0.634"
+    "@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"
@@ -42,6 +42,7 @@
     "docs/patterns.md",
     "docs/security.md",
     "docs/features.md",
+    "launcher.sh",
     "launcher.cjs",
     "README.md",
     "LICENSE"
@@ -64,6 +65,14 @@
     "nx",
     "bun",
     "workspaces",
-    "ci"
+    "ci",
+    "task-orchestration",
+    "turborepo-alternative",
+    "nx-alternative",
+    "remote-cache",
+    "sandbox",
+    "incremental-build",
+    "mcp",
+    "pnpm"
   ]
 }

package/schemas/last.json

@@ -170,7 +170,7 @@
         },
         "locations": {
           "type": "array",
-          "description": "on a failed row: the existing files its output names, in order of first appearance",
+          "description": "on a failed row: the existing files its output names, in order of first appearance; a file it also names with a line drops its bare mention",
           "items": {
             "type": "object",
             "additionalProperties": false,
@@ -181,6 +181,10 @@
               "col": { "type": "integer" }
             }
           }
+        },
+        "fixedIn": {
+          "type": "string",
+          "description": "on a failed row: the first later run where this task passed (ran or hit); absent while it has not"
         }
       }
     }

package/schemas/show.json

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

package/schemas/why.json

@@ -77,7 +77,10 @@
               "type": ["boolean", "null"],
               "description": "on a hit: true when outputs were restored, false when up-to-date"
             },
-            "cached": { "type": ["boolean", "null"] },
+            "cached": {
+              "type": ["boolean", "null"],
+              "description": "whether the task declares a cache; not whether this run hit it"
+            },
             "startedAt": { "type": "integer", "description": "epoch ms" }
           }
         },

package/src/cache/layered-cache.ts

@@ -76,7 +76,9 @@ export interface RemoteCacheLayer {
    * straight into the local cache — an HTTP wire returns its `fetch`
    * `Response`, a chunked wire `new Response(stream)`, bytes in hand
    * `new Blob([bytes])`. `durationMs` is the producing task's duration
-   * when the wire carries it.
+   * when the wire carries it. A body that errors before its end stores
+   * nothing and the read is a miss, so a layer can check bytes as they pass
+   * (a digest, a signature) and refuse at the end.
    */
   get(hash: string): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
   /**

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/last.ts

@@ -384,7 +384,15 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
       )
       const tasks = (detail?.tasks ?? []).map((t) => {
         const f = failures.get(`${t.project}#${t.task}`)
-        return f === undefined ? t : { ...t, output: f.output, locations: f.locations }
+        return f === undefined
+          ? t
+          : {
+              ...t,
+              output: f.output,
+              locations: f.locations,
+              ...(f.sandboxFix !== undefined ? { sandboxFix: f.sandboxFix } : {}),
+              ...(f.fixedIn !== undefined ? { fixedIn: f.fixedIn } : {}),
+            }
       })
       process.stdout.write(`${JSON.stringify({ invocation: inv, tasks })}\n`)
       return 0

package/src/cli/plugin-templates.ts

@@ -10,7 +10,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   },
   cache: {
     plugin:
-      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// `LayeredCache` puts it behind the local cache, so a remote error is a\n// miss and a warning, never a failed run.\nimport { mkdir, rename } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, LayeredCache, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<boolean> {\n    return Bun.file(path.join(this.endpoint, hash)).exists()\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then renamed: a reader never sees half an artifact.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    await rename(tmp, path.join(this.endpoint, hash))\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache(ctx) {\n      return new LayeredCache(ctx.localCache, new DirRemote(dir), {\n        policy: ctx.policy,\n        onRemoteError: (err) => ctx.warn(`dir-cache: ${err.message}`),\n      })\n    },\n  })\n}\n",
+      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// `LayeredCache` puts it behind the local cache, so a remote error is a\n// miss and a warning, never a failed run.\nimport { link, mkdir, unlink } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, LayeredCache, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<boolean> {\n    return Bun.file(path.join(this.endpoint, hash)).exists()\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then linked: on a shared directory a rename can swap\n    // the file under a reader, while a link never replaces an existing one.\n    // EEXIST is success: the same hash means the same bytes.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    try {\n      await link(tmp, path.join(this.endpoint, hash))\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err\n    } finally {\n      await unlink(tmp)\n    }\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache(ctx) {\n      return new LayeredCache(ctx.localCache, new DirRemote(dir), {\n        policy: ctx.policy,\n        onRemoteError: (err) => ctx.warn(`dir-cache: ${err.message}`),\n      })\n    },\n  })\n}\n",
     test: "// A test for the example `cache` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      cache: { inputs: { files: ['package.json'] }, outputs: { files: ['dist/**'] } },\n    } } }`,\n  )\n  await workspace(`dirCache(${JSON.stringify(path.join(root, 'remote'))})`)\n  const first = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(first.outcomes.map((o) => o.status)).toEqual(['success'])\n  await rm(path.join(root, '.vx'), { recursive: true, force: true })\n  await rm(path.join(dir, 'dist'), { recursive: true, force: true })\n  const second = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(second.outcomes.map((o) => o.status)).toEqual(['cache-hit-remote'])\n  expect(await Bun.file(path.join(dir, 'dist', 'out.txt')).text()).toBe('built\\n')\n}, 20_000)\n",
   },
   commands: {

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) {
@@ -479,7 +503,9 @@ function onCI(v: string | undefined): boolean {
 async function scopeFilters(
   parsed: RunArgs,
   cwd: string,
-): Promise<{ filterStrings: string[]; affectedFilter?: string } | { error: string }> {
+): Promise<
+  { filterStrings: string[]; affectedFilter?: string } | { error: string; code?: string }
+> {
   // `--affected[=<base>]` is sugar for `--filter '...[<base>]'`: the
   // changed projects AND their dependents — what a CI gate must run, what
   // the flag's name says, what the guides promised while the sugar was the
@@ -523,7 +549,7 @@ export async function resolveRunOptions(
   verb: 'run' | 'watch' = 'run',
   /** Given, it learns the ref `--affected` diffed from (`--dry=json` states it). */
   scopeOut?: { affectedBase?: string },
-): Promise<RunOptions | { error: string } | { nothingSelected: string }> {
+): Promise<RunOptions | { error: string; code?: string } | { nothingSelected: string }> {
   for (const t of tasks) {
     const idx = t.indexOf('#')
     if (idx >= 0) {
@@ -566,7 +592,7 @@ export async function resolveRunOptions(
           affectedFilter,
         )
       : undefined
-  if (resolved !== undefined && 'error' in resolved) return { error: resolved.error }
+  if (resolved !== undefined && 'error' in resolved) return resolved
   if (bareTasks.length === 0) {
     projects = undefined
   } else if (resolved !== undefined) {
@@ -609,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'])
@@ -696,11 +723,12 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     // `--filter` / `--affected` scope the menu, as they scope a bare task:
     // the menu listed every project and the anchored pick ran outside it.
     const scope = await scopeFilters(parsed, cwd)
-    if ('error' in scope) return refuse('run', args, scope.error, 'VX_E_USAGE')
+    if ('error' in scope) return refuse('run', args, scope.error, scope.code ?? 'VX_E_USAGE')
     let only: ReadonlySet<string> | undefined
     if (scope.filterStrings.length > 0) {
       const selected = await resolveFilters(cwd, scope.filterStrings, load, scope.affectedFilter)
-      if ('error' in selected) return refuse('run', args, selected.error, 'VX_E_USAGE')
+      if ('error' in selected)
+        return refuse('run', args, selected.error, selected.code ?? 'VX_E_USAGE')
       if ('empty' in selected) {
         process.stderr.write(`vx run: ${selected.empty}\n`)
         return 0
@@ -716,7 +744,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
 
   const scopeOut: { affectedBase?: string } = {}
   const resolved = await resolveRunOptions(parsed, cwd, tasks, 'run', scopeOut)
-  if ('error' in resolved) return refuse('run', args, resolved.error, 'VX_E_USAGE')
+  if ('error' in resolved) return refuse('run', args, resolved.error, resolved.code ?? 'VX_E_USAGE')
   if ('nothingSelected' in resolved) {
     process.stderr.write(`vx run: ${resolved.nothingSelected}\n`)
     return 0

package/src/cli/select.ts

@@ -197,7 +197,7 @@ export type FilterResolution =
       /** What the other includes selected (`RunOptions.selectedOutright`). */
       outright?: string[]
     }
-  | { error: string }
+  | Refusal
   | { empty: string }
 
 /**
@@ -239,16 +239,23 @@ export function taskEdgesFrom(staged: ReadonlyMap<string, ProjectEntry>): Map<st
   return out
 }
 
+/** A refusal a resolver returns; `code` is the thrown one's own, when it has one. */
+type Refusal = { error: string; code?: string }
+
+function refusalOf(err: unknown): Refusal {
+  if (!(err instanceof Error)) return { error: String(err) }
+  return isUserError(err) && err.code !== 'VX_E_REFUSED'
+    ? { error: err.message, code: err.code }
+    : { error: err.message }
+}
+
 /**
  * The filter `--affected[=<base>]` stands for: `...[<base>]`, the changed
  * projects and their dependents. An empty base is the workspace's
  * `affectedBase` (or a plugin's `config` stage, from nx.json's
  * `defaultBase` or `TURBO_SCM_BASE`), then the guess.
  */
-export async function affectedFilterFor(
-  cwd: string,
-  affected: string,
-): Promise<string | { error: string }> {
+export async function affectedFilterFor(cwd: string, affected: string): Promise<string | Refusal> {
   const root = await findWorkspaceRoot(cwd)
   let base = affected
   if (base === '') base = (await loadCliWorkspace(root)).workspaceConfig?.affectedBase ?? ''
@@ -257,7 +264,7 @@ export async function affectedFilterFor(
       base = await defaultAffectedBase(root)
     } catch (err) {
       if (!isUserError(err)) throw err
-      return { error: err.message }
+      return refusalOf(err)
     }
   }
   return `...[${base}]`
@@ -276,7 +283,7 @@ export async function resolveFilters(
   try {
     parsed = raw.map((r) => parseFilter(r, root))
   } catch (err) {
-    return { error: err instanceof Error ? err.message : String(err) }
+    return refusalOf(err)
   }
   // `sinceViaDeps` (`e2e...[main]`) walks the changed projects' dependents.
   const walksGraph = parsed.some(
@@ -299,7 +306,7 @@ export async function resolveFilters(
     try {
       edges = taskEdgesFrom(await stagedOnce())
     } catch (err) {
-      return { error: err instanceof Error ? err.message : String(err) }
+      return refusalOf(err)
     }
   }
   // A tag lives in the config, so a `tag:` selector needs the staged load
@@ -309,7 +316,7 @@ export async function resolveFilters(
     try {
       tags = new Map([...(await stagedOnce()).values()].map((p) => [p.name, p.config.tags ?? []]))
     } catch (err) {
-      return { error: err instanceof Error ? err.message : String(err) }
+      return refusalOf(err)
     }
   }
   const graph = buildPackageGraph(projects, edges)
@@ -353,8 +360,7 @@ export async function resolveFilters(
       }
       affectedByFilter.set(f, names)
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err)
-      return { error: msg }
+      return refusalOf(err)
     }
   }
 

package/src/cli/show.ts

@@ -145,12 +145,12 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     let affected: string | undefined
     if (parsed.affected !== undefined) {
       const f = await affectedFilterFor(process.cwd(), parsed.affected)
-      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`, 'VX_E_USAGE')
+      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`, f.code ?? 'VX_E_USAGE')
       affected = f
       raw.unshift(f)
     }
     const r = await resolveFilters(process.cwd(), raw, { noCreate: true }, affected)
-    if ('error' in r) throw new UserError(`vx show: ${r.error}`, 'VX_E_USAGE')
+    if ('error' in r) throw new UserError(`vx show: ${r.error}`, r.code ?? 'VX_E_USAGE')
     if ('empty' in r) process.stderr.write(`vx show: ${r.empty}\n`)
     selected = new Set('empty' in r ? [] : r.names)
     if ('names' in r && r.affected !== undefined)