@vzn/vx 0.0.633 → 0.0.635

package/README.md

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

package/docs/caching.md

@@ -465,7 +465,10 @@ fold, and runtime probes after a writer still leave a key preliminary.
 The
 short-circuit never runs under a `LayeredCache` (remote prefetch owns
 those runs — an up-front `get` there would put remote GETs on the
-critical path), never fires with local reads off, and never throws —
+critical path), never fires with local reads off or on a local cache
+that holds no artifact (`Cache.holdsNothing`: every probe would miss,
+and a cold 1,090-package run started its first task ~90 ms sooner
+without it), and never throws —
 any error degrades to the normal lazy schedule. Measured: −6.6% on a
 mixed slow-upstream/warm-downstream workload; parity on all-hit warm
 runs.
@@ -701,7 +704,13 @@ is not saved either: its write cannot be told from an edit reverted
 mid-run, so it pays a re-run each time rather than risk a stale entry;
 declare what it writes as an output, which the status line says when it
 names a file other than `package.json` (TanStack Router's committed
-`routeTree.gen.ts`, rewritten by every build). A file ADDED under an
+`routeTree.gen.ts`, rewritten by every build). That holds on CI too: a
+task of the same project running alongside can change an input and put
+it back. A task that rewrites its own input to identical bytes (tsdown's
+`package.json`) sets `cache.rewrittenInputs: 'compare'`, and a write
+during its command is then judged by its bytes, as an earlier write is;
+different bytes still withhold the entry. `VX_REWRITTEN_INPUTS=compare`
+makes that the default (owner, 2026-10-12). A file ADDED under an
 input glob since the listing the key filtered (`addedInput`) withholds
 the save the same way, named on the same line: the listing's
 directories a glob reaches are `lstat`ed, one whose ctime moved since

package/docs/cli.md

@@ -137,9 +137,12 @@ Exit codes:
 A task runs in its own session, so a terminal's Ctrl-C reaches vx alone,
 and each task hears it once: from vx, as SIGINT.
 
-Installed from npm, `vx` is a Node launcher. On Node 22.15 or later it
-replaces itself with the binary (`process.execve`), so every signal
-reaches vx directly. On older Node it runs the binary and waits for it:
+Installed from npm, `vx` is a sh launcher that execs the platform
+binary, so every signal reaches vx directly and no Node starts first
+(a `vx --version` through npm: 14 ms, was 56 ms with the Node launcher, 2026-10-12). Where it
+finds no binary beside it (musl, Yarn PnP, a platform with none) it
+hands off to a Node launcher. On Node 22.15 or later that one
+replaces itself with the binary (`process.execve`) too. On older Node it runs the binary and waits for it:
 a signal sent to the launcher alone (`kill`, a process manager) is
 passed to the binary, and a terminal's Ctrl-C already reaches both, so
 the launcher does not send it twice.
@@ -957,8 +960,10 @@ readable. Its `criticalPath` names the would-run tasks with history on
 the chain `wallMs` measures, dependencies first: the tasks to speed up
 to shorten the run.
 
-**Why a task is affected.** Under `--affected`, each requested task the
-diff kept gets a line, and its JSON object an `affected` reason:
+### Why a task is affected (`affected.kind`)
+
+Under `--affected`, each requested task the diff kept gets a line, and
+its JSON object an `affected` reason:
 
 ```
 $ vx run build lint --affected=main --dry
@@ -976,6 +981,12 @@ single `file` for a lockfile claim, a manifest edge or a config import),
 selected its project). `via` is the `dependsOn` chain, nearest first, to
 the task the change reached. A dependency the kept tasks pull in carries
 none. The reasons are gathered only for a plan; a run pays nothing.
+`--dry=json` also states `affectedBase`, the ref the diff was taken
+against: a bare `--affected` guesses it (`origin/HEAD`, a trunk branch,
+else `HEAD~1`), so a reason that names no file may come from a commit
+the base reaches, a root `package.json` edit among them.
+
+### Task graph (`--graph`)
 
 `--graph` prints Graphviz DOT (stdout by default; `--graph=path`
 writes a file):
@@ -1279,7 +1290,19 @@ package, are reported.
 Policy: **fail on violation.** Any task that touches a path it didn't
 declare either fails naturally (Linux: `ENOENT` from bwrap's
 mount-namespace hide) or is flagged via the macOS violation store
-and forced to exit non-zero. No cache is written for a failed task.
+and forced to exit non-zero. No cache is written for a failed task. The
+task's `SANDBOX VIOLATIONS` section ends with a dimmed `fix:` line,
+the grants that would have allowed each denial, project-relative:
+`fix: exec.sandbox.allow: { read: ['tsconfig.json'], write: ['dist/'] }`.
+A write grants the top directory it landed in, so the next file there
+passes too, unless `cache.inputs.files` reads that directory: then it
+grants the file alone, so the task cannot write its own inputs; a read the output depends on is a key input as well, and
+the line says so, since a grant never adds one. A credential path
+(`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.kube`, `~/.config/gh`,
+`~/.config/gcloud`, `~/.netrc`, `~/.npmrc`, `~/.pypirc`,
+`~/.git-credentials`, `~/.docker/config.json`, a `.env` file) is never put in the
+line: an agent applies it as given, so it is named apart as one to
+grant only on purpose.
 "Didn't declare" means the grants, which on Linux are wider than they
 read: a file-shaped write grant is bound as its whole directory, so
 every file beside it is readable without a violation — `schema.md`
@@ -1957,13 +1980,17 @@ install its dependencies. `--mjs` writes the same objects as `vx.config.mjs` and
 own `tsconfig` includes every `.ts` under it compiles a `vx.config.ts`
 into its dist (TanStack/query's `tsc --build`, 2026-09-11), and an
 `.mjs` is outside that include. `@vzn/vx-migrate` takes the same flag.
+A file it writes that `.gitignore` drops (vueuse ignores
+`packages/**/*.mjs`) gets a `note:` naming it and the `!vx.config.mjs`
+line that keeps it, since a commit would leave it behind unnoticed.
 
 Each script becomes a task with its command verbatim. `build` gets
 `dependsOn: ['^build']` (a `build` that only delegates, `pnpm run
 compile`, is a group, and the edge goes on the script that does the
 work) and **no cache block** — under a
 `TODO(vx-migrate)` showing the block to add with the package's real
-inputs and outputs. A task without a cache block always runs; a block
+inputs and outputs, and the same block commented as the task's first
+line: set the real globs and delete the `// `. A task without a cache block always runs; a block
 with EMPTY outputs is not "uncached" but a no-output task that hits on
 unchanged inputs and skips the build with nothing to restore (a deleted
 `dist` stays deleted under a green `up-to-date` run — what `init`
@@ -2109,8 +2136,8 @@ order may matter, so it is not made a group.
 
 The report lists each TODO once per reason: tasks that share one are
 named together (the first five, then a count; the files carry each),
-and when no task caches it says a cache block from a TODO makes the
-second run a hit. Its `next:` line is a command the user can type: the
+and when no task caches it says uncommenting a TODO task's cache line
+makes the second run a hit. Its `next:` line is a command the user can type: the
 runner that started vx (`npx`, `pnpm`, `yarn`, `bunx`, read from
 `npm_config_user_agent`) with the installed `vx` bin, else the
 `@vzn/vx` package (`npx` under Yarn 1, which has no `dlx`); with no
@@ -2287,26 +2314,125 @@ refuses `--dry` (use `--dry=json`), a bare `--graph` and
 
 A verb asked for JSON (`--format json`, `--format=json`, `--dry=json`,
 before any `--`) answers a refusal on stdout too, as one line that
-`schemas/error.json` describes: `{"ok":false,"error":{"code","message"}}`.
-The exit code (1) and the prose on stderr do not change. Branch on the
-code; the message may change.
-
-| Code                   | When                                                                  |
-| ---------------------- | --------------------------------------------------------------------- |
-| `VX_E_USAGE`           | A flag, argument or selection the verb does not take.                 |
-| `VX_E_UNKNOWN_COMMAND` | No verb of that name here, core's or a declared plugin's.             |
-| `VX_E_UNKNOWN_TASK`    | No project in scope declares a requested task.                        |
-| `VX_E_UNKNOWN_PROJECT` | `vx show` names a project the workspace does not have.                |
-| `VX_E_NO_HISTORY`      | `vx why` / `vx last` find no recorded run for what they were asked.   |
-| `VX_E_AMBIGUOUS`       | `vx why <task>` matches the task in several projects; name one.       |
-| `VX_E_CONFIG`          | A `vx.config.*` or `vx.workspace.*` that does not load or is refused. |
-| `VX_E_CYCLE`           | The task graph has a cycle.                                           |
-| `VX_E_NO_WORKSPACE`    | No workspace root above the working directory.                        |
-| `VX_E_CACHE_VERSION`   | A reading verb met a cache index from another vx version.             |
-| `VX_E_REFUSED`         | Any other refusal (a plugin's, a check's) with no code of its own.    |
-| `VX_E_FS`              | The file system refused a write: permissions, a full disk.            |
-| `VX_E_FDS`             | Out of file descriptors.                                              |
-| `VX_E_INTERNAL`        | A defect in vx; stderr carries the stack.                             |
+`schemas/error.json` describes: `{"ok":false,"error":{"code","message","docs"}}`.
+`docs` links the code's section below, which says what to do;
+`vx docs <code>` prints that section offline. The exit code (1) and the
+prose on stderr do not change. Branch on the code; the message may change.
+
+#### `VX_E_USAGE`
+
+A flag, argument or selection the verb does not take. The message names
+it, and a close spelling the verb does take when there is one;
+`vx <verb> --help` lists every flag.
+
+#### `VX_E_UNKNOWN_COMMAND`
+
+No verb of that name here, core's or a declared plugin's. `vx --help`
+lists core's verbs. A plugin's verb exists once its plugin is in
+`vx.workspace.ts` `plugins`; a task runs as `vx run <task>`.
+
+#### `VX_E_UNKNOWN_TASK`
+
+No project in scope declares a requested task. The message lists the
+tasks it found; `vx show --format json` lists each project's. Check the
+spelling, and the scope: `--filter`, `--all`, or the project the working
+directory is in.
+
+#### `VX_E_UNKNOWN_PROJECT`
+
+`vx show` names a project the workspace does not have. A project is named
+by its `package.json` `name`; `vx show --format json` lists them.
+
+#### `VX_E_NO_HISTORY`
+
+`vx why` / `vx last` find no recorded run for what they were asked. Run
+the task once (`vx run <task>`); history is this checkout's own.
+
+#### `VX_E_AMBIGUOUS`
+
+`vx why <task>` matches the task in several projects. Name one:
+`vx why <project>#<task>`.
+
+#### `VX_E_CONFIG`
+
+A `vx.config.*` or `vx.workspace.*` that does not load or is refused. The
+message names the file and the field; fix that field
+(`vx docs <field>` prints its reference). `vx info --format json` lists
+every config error at once.
+
+#### `VX_E_CYCLE`
+
+The task graph has a cycle. The message names the loop; drop one of its
+`dependsOn` edges.
+
+#### `VX_E_NO_WORKSPACE`
+
+No workspace root above the working directory. Run vx inside the repo,
+or create a `package.json` and run `vx init`.
+
+#### `VX_E_CACHE_VERSION`
+
+A reading verb met a cache index from another vx version. It reads
+nothing from it and leaves it be; the next `vx run` resets it. Or run the
+vx version that wrote it.
+
+#### `VX_E_REFUSED`
+
+Any other refusal (a plugin's, a check's) with no code of its own. The
+message is that plugin's or check's: do what it says.
+`vx info --format json` lists the plugins.
+
+#### `VX_E_FS`
+
+The file system refused a write: permissions, a full disk. The message
+names the path. Free space (`vx cache prune --max-size <size>` trims the
+cache) or grant the write, then re-run.
+
+#### `VX_E_FDS`
+
+Out of file descriptors. Raise the limit (`ulimit -n 4096`), or run fewer
+tasks at once (`--concurrency`), then re-run.
+
+#### `VX_E_AFFECTED_BASE`
+
+`--affected` (or `--affected=<ref>`) has no base to diff against: the
+ref does not resolve, is a range (`A..B`) or an exclusion (`^A`), names
+a path inside a commit, or the repository has no history to compare
+with. Pass a branch or commit you have locally, alone:
+`--affected=origin/main`. On CI, fetch the history the base needs
+(`fetch-depth: 0` on actions/checkout, or `git fetch --unshallow`).
+
+#### `VX_E_GIT`
+
+A git command vx runs to read the diff failed; the message carries
+git's exit and its own words. Run that command in the workspace to see
+why (a broken index, a missing object in a partial clone).
+
+#### `VX_E_DEPENDS_ON`
+
+A task's `dependsOn` names a task or project that is not declared, or uses
+a form vx does not take (a bare wildcard, a negation, a pattern in
+`pkg#task`). The message names the task and the entry: declare the
+target, fix its spelling, or drop the entry.
+
+#### `VX_E_OUTPUT_OVERLAP`
+
+Two tasks declare overlapping outputs with no `dependsOn` edge between
+them, so whichever runs second deletes the other's files. Give each task
+its own output path, or make one depend on the other.
+
+#### `VX_E_INPUT_IS_OUTPUT`
+
+A task's `cache.inputs` match outputs: its own (vx cleans outputs before
+a run, so it would delete its sources) or another task's (its key must
+not read them; `dependsOn` already cascades). Exclude the outputs from
+the inputs with a `!` glob, as the message shows, or declare no outputs
+for a task that rewrites files in place.
+
+#### `VX_E_INTERNAL`
+
+A defect in vx; stderr carries the stack. Report it with that stack at
+https://github.com/vznjs/vx/issues.
 
 A plugin can give its refusal a code: `new UserError(message, 'MY_CODE')`.
 
@@ -2740,8 +2866,14 @@ failed runs. `--format json`
 emits `{ invocation, tasks }` for scripting; a failed task's row adds
 `output` (its output as plain text, the first 8 KiB and last 56 KiB,
 secrets masked) and `locations` (the existing files it names,
-`{ file, line?, col? }`, file absolute), so an agent reads why without
-the terminal. They live in `<cacheDir>/failures/<runId>.json`, the
+`{ file, line?, col? }`, file absolute; a file also named with a line
+drops its bare mention, such as bun test's `app.test.js:` header), so an
+agent reads why without the terminal. `fixedIn` names the first later run where that task
+passed, so a replayed failure that is already fixed says so. A
+sandboxed task's row adds `sandboxFix`, the `exec.sandbox.allow`
+entries (`read`, `write`, `network`, `systemInfo`) that would have
+granted its denials, the same grants the terminal prints as `fix:`;
+`withheld` lists the credential paths it denied and left out. They live in `<cacheDir>/failures/<runId>.json`, the
 newest 50 failed runs; past those, or when the write was refused, a
 failed row reads `output: ''` and `locations: []`. `--log <task>`
 prints one task's output instead of the summary: in the latest run that
@@ -2786,7 +2918,9 @@ parse error.
 `schema`, `caching`, `execution`, `patterns`, `security` and `features`,
 which ship inside the package and the compiled binary. Each page is cut
 at its headings; a section that holds every word of the query matches,
-and a word in its heading ranks it above any count in its text. The best
+and a word in its heading ranks it above any count in its text; a
+one-word query that titles a section, an error code
+(`vx docs VX_E_CYCLE`), prints that section alone. The best
 `--limit` sections (default 3) print whole, each under its page,
 heading and URL on the site. `--format json` prints
 `{query, hits: [{page, heading, url, text}]}` (`schemas/docs.json`).
@@ -2889,30 +3023,32 @@ REAPI endpoints, the GitHub token) are in its README; what a TASK sees
 is `exec.env` in `docs/schema.md`, and the two markers vx sets on every
 task are the last row.
 
-| Var                               | Value                 | Default | Effect                                                                                                                                                                                                                                                                                                            |
-| --------------------------------- | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `VX_TIMING`                       | any non-empty         | off     | Print the stage table to stderr after a run, a `--dry`, or each `vx watch` cycle (`docs/modules/timing.md`).                                                                                                                                                                                                      |
-| `VX_TASK_TIMEOUT`                 | positive integer (ms) | none    | The default timeout for tasks without their own `exec.timeout`, one rung below `--timeout` / `RunOptions.timeout` and one above the workspace `timeout`. Empty, non-integer or non-positive is ignored; a value past the largest timer (~24.8 days) is clamped to it, never refused.                              |
-| `VX_CACHE_DIR`                    | a path                | none    | The workspace's cache dir, relative to the workspace root, below `--cache-dir` and `vx.workspace`'s `cacheDir`. A named cache dir holds the whole cache and shares nothing; unset, entries live in the user's shared store (`docs/caching.md`). Empty is ignored; whitespace alone is refused, as `cacheDir` is.  |
-| `VX_CACHE_SCOPE`                  | a `cacheScope` value  | none    | The run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `vx.workspace`'s and `github()`'s. Empty is ignored; a value `cacheScope` would refuse is refused before any task.                                                                                                                               |
-| `VX_KILL_GRACE_MS`                | positive integer (ms) | 2000    | The SIGTERM → SIGKILL grace a child that ignores SIGTERM gets: on a timeout, on a signal, and at the end-of-run shutdown of persistent tasks. Out of range falls back to the default.                                                                                                                             |
-| `VX_READY_NOTICE_MS`              | positive integer (ms) | 10000   | How long a persistent task may take to match `readyWhen` before vx says once what it waits for. Out of range falls back to the default.                                                                                                                                                                           |
-| `VX_TEARDOWN_TIMEOUT_MS`          | integer (ms)          | 3000    | The bound on one plugin's end-of-run flush or teardown, and on its `telemetry()` setup, so a third party's I/O cannot hold the run. Out of range falls back to the default, never clamps: a bound of 24.8 days is no bound.                                                                                       |
-| `VX_CONFIG_WORKER_TIMEOUT_MS`     | integer (ms)          | 30000   | How long one `vx.config.ts` evaluation may take, in process or in its worker, before the load fails naming the config (a real evaluation is ~10 ms). A synchronous loop on a first load holds the thread the deadline needs, so it hangs until killed. Out of range falls back to the default.                    |
-| `VX_WATCH_POLL`                   | any non-empty         | off     | `vx watch` polls every 250 ms from the start instead of probing the OS watcher (§ `vx watch` › How changes are seen).                                                                                                                                                                                             |
-| `VX_RUN_WORKSPACE`, `VX_RUN_TASK` | set by vx             | —       | Set on every task's environment (the workspace root; `project#task`). Read back by a `vx run` a task starts: one in the same workspace is refused, since a nested run is invisible to the outer graph and a loop back to its own task forks without bound (`docs/schema.md` § `env`).                             |
-| Var                               | Value                 | Default | Effect                                                                                                                                                                                                                                                                                                            |
-| --------------------------------- | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `VX_TIMING`                       | any non-empty         | off     | Print the stage table to stderr after a run, a `--dry`, or each `vx watch` cycle (`docs/modules/timing.md`).                                                                                                                                                                                                      |
-| `VX_TASK_TIMEOUT`                 | positive integer (ms) | none    | The default timeout for tasks without their own `exec.timeout`, one rung below `--timeout` / `RunOptions.timeout` and one above the workspace `timeout`. Empty, non-integer or non-positive is ignored; a value past the largest timer (~24.8 days) is clamped to it, never refused.                              |
-| `VX_CACHE_DIR`                    | a path                | none    | The workspace's cache dir, relative to the workspace root, below `--cache-dir` and `vx.workspace`'s `cacheDir`. A named cache dir holds the whole cache and shares nothing; unset, entries live in the user's shared store (`docs/caching.md`). Empty is ignored.                                                 |
-| `VX_CACHE_SCOPE`                  | a `cacheScope` value  | none    | The run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `vx.workspace`'s and `github()`'s. Empty is ignored; a value `cacheScope` would refuse is refused before any task.                                                                                                                               |
-| `VX_KILL_GRACE_MS`                | positive integer (ms) | 2000    | The SIGTERM → SIGKILL grace a child that ignores SIGTERM gets: on a timeout, on a signal, and at the end-of-run shutdown of persistent tasks. Out of range falls back to the default.                                                                                                                             |
-| `VX_READY_NOTICE_MS`              | positive integer (ms) | 10000   | How long a persistent task may take to match `readyWhen` before vx says once what it waits for. Out of range falls back to the default.                                                                                                                                                                           |
-| `VX_TEARDOWN_TIMEOUT_MS`          | integer (ms)          | 3000    | The bound on one plugin's end-of-run flush or teardown, and on its `telemetry()` setup, so a third party's I/O cannot hold the run. Out of range falls back to the default, never clamps: a bound of 24.8 days is no bound.                                                                                       |
-| `VX_CONFIG_WORKER_TIMEOUT_MS`     | integer (ms)          | 30000   | How long one `vx.config.ts` evaluation may take, in process or in its worker, before the load fails naming the config (a real evaluation is ~10 ms). A synchronous loop on a first load holds the thread the deadline needs, so it hangs until killed. Out of range (0, or past 2³¹−1) falls back to the default. |
-| `VX_WATCH_POLL`                   | any non-empty         | off     | `vx watch` polls every 250 ms from the start instead of probing the OS watcher (§ `vx watch` › How changes are seen).                                                                                                                                                                                             |
-| `VX_RUN_WORKSPACE`, `VX_RUN_TASK` | set by vx             | —       | Set on every task's environment (the workspace root; `project#task`). Read back by a `vx run` a task starts: one in the same workspace is refused, since a nested run is invisible to the outer graph and a loop back to its own task forks without bound (`docs/schema.md` § `env`).                             |
+| Var                               | Value                 | Default    | Effect                                                                                                                                                                                                                                                                                                            |
+| --------------------------------- | --------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VX_TIMING`                       | any non-empty         | off        | Print the stage table to stderr after a run, a `--dry`, or each `vx watch` cycle (`docs/modules/timing.md`).                                                                                                                                                                                                      |
+| `VX_TASK_TIMEOUT`                 | positive integer (ms) | none       | The default timeout for tasks without their own `exec.timeout`, one rung below `--timeout` / `RunOptions.timeout` and one above the workspace `timeout`. Empty, non-integer or non-positive is ignored; a value past the largest timer (~24.8 days) is clamped to it, never refused.                              |
+| `VX_CACHE_DIR`                    | a path                | none       | The workspace's cache dir, relative to the workspace root, below `--cache-dir` and `vx.workspace`'s `cacheDir`. A named cache dir holds the whole cache and shares nothing; unset, entries live in the user's shared store (`docs/caching.md`). Empty is ignored; whitespace alone is refused, as `cacheDir` is.  |
+| `VX_CACHE_SCOPE`                  | a `cacheScope` value  | none       | The run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `vx.workspace`'s and `github()`'s. Empty is ignored; a value `cacheScope` would refuse is refused before any task.                                                                                                                               |
+| `VX_REWRITTEN_INPUTS`             | `withhold`, `compare` | `withhold` | What a write to an input during the command means for a task that does not set `cache.rewrittenInputs`: `compare` saves the entry when the file holds the bytes the key folded, anything else withholds it (`docs/schema.md`).                                                                                    |
+| `VX_KILL_GRACE_MS`                | positive integer (ms) | 2000       | The SIGTERM → SIGKILL grace a child that ignores SIGTERM gets: on a timeout, on a signal, and at the end-of-run shutdown of persistent tasks. Out of range falls back to the default.                                                                                                                             |
+| `VX_READY_NOTICE_MS`              | positive integer (ms) | 10000      | How long a persistent task may take to match `readyWhen` before vx says once what it waits for. Out of range falls back to the default.                                                                                                                                                                           |
+| `VX_TEARDOWN_TIMEOUT_MS`          | integer (ms)          | 3000       | The bound on one plugin's end-of-run flush or teardown, and on its `telemetry()` setup, so a third party's I/O cannot hold the run. Out of range falls back to the default, never clamps: a bound of 24.8 days is no bound.                                                                                       |
+| `VX_CONFIG_WORKER_TIMEOUT_MS`     | integer (ms)          | 30000      | How long one `vx.config.ts` evaluation may take, in process or in its worker, before the load fails naming the config (a real evaluation is ~10 ms). A synchronous loop on a first load holds the thread the deadline needs, so it hangs until killed. Out of range falls back to the default.                    |
+| `VX_WATCH_POLL`                   | any non-empty         | off        | `vx watch` polls every 250 ms from the start instead of probing the OS watcher (§ `vx watch` › How changes are seen).                                                                                                                                                                                             |
+| `VX_RUN_WORKSPACE`, `VX_RUN_TASK` | set by vx             | —          | Set on every task's environment (the workspace root; `project#task`). Read back by a `vx run` a task starts: one in the same workspace is refused, since a nested run is invisible to the outer graph and a loop back to its own task forks without bound (`docs/schema.md` § `env`).                             |
+| Var                               | Value                 | Default    | Effect                                                                                                                                                                                                                                                                                                            |
+| --------------------------------- | --------------------- | -------    | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VX_TIMING`                       | any non-empty         | off        | Print the stage table to stderr after a run, a `--dry`, or each `vx watch` cycle (`docs/modules/timing.md`).                                                                                                                                                                                                      |
+| `VX_TASK_TIMEOUT`                 | positive integer (ms) | none       | The default timeout for tasks without their own `exec.timeout`, one rung below `--timeout` / `RunOptions.timeout` and one above the workspace `timeout`. Empty, non-integer or non-positive is ignored; a value past the largest timer (~24.8 days) is clamped to it, never refused.                              |
+| `VX_CACHE_DIR`                    | a path                | none       | The workspace's cache dir, relative to the workspace root, below `--cache-dir` and `vx.workspace`'s `cacheDir`. A named cache dir holds the whole cache and shares nothing; unset, entries live in the user's shared store (`docs/caching.md`). Empty is ignored.                                                 |
+| `VX_CACHE_SCOPE`                  | a `cacheScope` value  | none       | The run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `vx.workspace`'s and `github()`'s. Empty is ignored; a value `cacheScope` would refuse is refused before any task.                                                                                                                               |
+| `VX_REWRITTEN_INPUTS`             | `withhold`, `compare` | `withhold` | What a write to an input during the command means for a task that does not set `cache.rewrittenInputs`: `compare` saves the entry when the file holds the bytes the key folded, anything else withholds it (`docs/schema.md`).                                                                                    |
+| `VX_KILL_GRACE_MS`                | positive integer (ms) | 2000       | The SIGTERM → SIGKILL grace a child that ignores SIGTERM gets: on a timeout, on a signal, and at the end-of-run shutdown of persistent tasks. Out of range falls back to the default.                                                                                                                             |
+| `VX_READY_NOTICE_MS`              | positive integer (ms) | 10000      | How long a persistent task may take to match `readyWhen` before vx says once what it waits for. Out of range falls back to the default.                                                                                                                                                                           |
+| `VX_TEARDOWN_TIMEOUT_MS`          | integer (ms)          | 3000       | The bound on one plugin's end-of-run flush or teardown, and on its `telemetry()` setup, so a third party's I/O cannot hold the run. Out of range falls back to the default, never clamps: a bound of 24.8 days is no bound.                                                                                       |
+| `VX_CONFIG_WORKER_TIMEOUT_MS`     | integer (ms)          | 30000      | How long one `vx.config.ts` evaluation may take, in process or in its worker, before the load fails naming the config (a real evaluation is ~10 ms). A synchronous loop on a first load holds the thread the deadline needs, so it hangs until killed. Out of range (0, or past 2³¹−1) falls back to the default. |
+| `VX_WATCH_POLL`                   | any non-empty         | off        | `vx watch` polls every 250 ms from the start instead of probing the OS watcher (§ `vx watch` › How changes are seen).                                                                                                                                                                                             |
+| `VX_RUN_WORKSPACE`, `VX_RUN_TASK` | set by vx             | —          | Set on every task's environment (the workspace root; `project#task`). Read back by a `vx run` a task starts: one in the same workspace is refused, since a nested run is invisible to the outer graph and a loop back to its own task forks without bound (`docs/schema.md` § `env`).                             |
 
 Colors are the two conventions in § Output format › Colors (`NO_COLOR`,
 `FORCE_COLOR`). A truthy `CI` picks the CI output flow and

package/docs/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 / plugins),
+ │       rules / schedule / 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

@@ -28,6 +28,7 @@ config key or an environment variable is missing here.
 - **Turbo and Nx spellings** (`-t`, `-p`, `--exclude`, `--parallel`, `--base`, `--dry-run`, `--skip-nx-cache`) — accepted, or refused naming the vx spelling. [page](https://vznjs.github.io/vx/features/turbo-nx-flags/) · post: [Flags you already know](https://vznjs.github.io/vx/blog/flags-you-already-know/)
 - **Ctrl-C leaves nothing running** (`VX_KILL_GRACE_MS`, `VX_TEARDOWN_TIMEOUT_MS`) — the whole process tree stops, then teardown runs. [page](https://vznjs.github.io/vx/features/ctrl-c/) · post: [Ctrl-C leaves nothing running](https://vznjs.github.io/vx/blog/ctrl-c/)
 - **Longest chain first** — the scheduler starts the critical path first; `@vzn/vx-schedule-history` learns it from past runs. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Bitsets, popcount, and a scheduler tick](https://vznjs.github.io/vx/blog/bitsets-and-the-scheduler/)
+- **Schedule strategy** (`schedule`) — pick the order with no timings: most work waiting (default), longest chain, most direct dependents, or ready order; plugins still lead. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Pick the order your graph wants](https://vznjs.github.io/vx/blog/schedule-strategy/)
 - **No daemon** — every run starts cold and still answers in milliseconds. [page](https://vznjs.github.io/vx/features/no-daemon/) · post: [No daemon, on purpose](https://vznjs.github.io/vx/blog/no-daemon/)
 - **Group tasks** (`dependsOn` with no `exec`) — a task that only runs its dependencies; `dependsOn: []` is a named no-op. [page](https://vznjs.github.io/vx/features/group-tasks/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
 - **Keyed groups** (`cache` with no `exec`) — a key a dependant folds: it re-runs on those inputs, and nothing spawns or counts for the group. [page](https://vznjs.github.io/vx/features/group-tasks/) · post: [A key with nothing to run](https://vznjs.github.io/vx/blog/keyed-groups/)
@@ -68,10 +69,10 @@ config key or an environment variable is missing here.
 - **vx info** (`vx info`) — workspace doctor: versions, projects, cache size against `cacheRetention.maxSize`. [page](https://vznjs.github.io/vx/features/vx-info/) · post: [One command to know your workspace](https://vznjs.github.io/vx/blog/know-your-workspace/)
 - **JSON everywhere** (`--format`) — `show`, `info`, `why`, `last` and `cache` print JSON for agents. [page](https://vznjs.github.io/vx/features/json-everywhere/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 - **Run analytics in SQLite** — every task's time, CPU, peak memory and cache result, queryable with `sqlite3`. [page](https://vznjs.github.io/vx/features/run-analytics/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
-- **Stable error codes** (`VX_E_…`) — under `--format json` a refusal is a JSON line on stdout with a code an agent branches on. [page](https://vznjs.github.io/vx/features/error-codes/) · post: [A refusal an agent can read](https://vznjs.github.io/vx/blog/error-codes/)
+- **Stable error codes** (`VX_E_…`) — under `--format json` a refusal is a JSON line on stdout with a code an agent branches on and a `docs` link to its fix (`vx docs <code>` offline). [page](https://vznjs.github.io/vx/features/error-codes/) · post: [A refusal an agent can read](https://vznjs.github.io/vx/blog/error-codes/)
 - **Shipped JSON Schemas** (`@vzn/vx/schemas/`) — every `--format json` shape has a schema, and stdout always parses. [page](https://vznjs.github.io/vx/features/json-schemas/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 - **Docs for agents** (`llms.txt`, `llms-full.txt`) — the whole site as markdown for coding agents. [page](https://vznjs.github.io/vx/features/llms-txt/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
-- **vx docs** (`vx docs`, `--limit`) — search the CLI, config and cache reference offline; it ships inside vx. [page](https://vznjs.github.io/vx/cli/#vx-docs) · post: [The reference, offline](https://vznjs.github.io/vx/blog/vx-docs-offline/)
+- **vx docs** (`vx docs`, `--limit`) — search the CLI, config and cache reference offline; it ships inside vx. [page](https://vznjs.github.io/vx/features/vx-docs/) · post: [The reference, offline](https://vznjs.github.io/vx/blog/vx-docs-offline/)
 - **Affected reasons** (`--affected --dry`) — each kept task says the changed file or the dependency chain that reached it, text or JSON. [page](https://vznjs.github.io/vx/features/affected-reasons/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **Agent skill** (`skills/vx/SKILL.md`) — an installable skill that teaches a coding agent to run, debug and query vx. [page](https://vznjs.github.io/vx/features/agent-skill/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 
@@ -80,6 +81,7 @@ config key or an environment variable is missing here.
 - **Opt-in, explicit inputs** (`cache.inputs.files`) — a task caches only when it names its inputs. [page](https://vznjs.github.io/vx/features/explicit-inputs/) · post: [Explicit over magical](https://vznjs.github.io/vx/blog/explicit-over-magical/)
 - **Inputs** (`cache.inputs.env`, `cache.inputs.runtime`, `cache.inputs.tasks`, `cache.inputs.workspaceFiles`, `cache.inputs.workspaceRuntime`) — env vars, tool versions, upstream tasks and workspace files in the key. [page](https://vznjs.github.io/vx/features/key-inputs/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Outputs** (`cache.outputs.files`, `cache.outputs.workspaceFiles`) — what a hit restores. [page](https://vznjs.github.io/vx/features/cache-outputs/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
+- **Rewritten inputs** (`cache.rewrittenInputs`, `VX_REWRITTEN_INPUTS`) — an input written while the command runs withholds the save, on CI too; `compare` accepts a task's identical rewrite of its own input. no post
 - **Outputs are exactly the snapshot** (`exclusiveOutputs`) — a hit leaves the tree as the run did; two tasks may not own one output without an edge. [page](https://vznjs.github.io/vx/features/strict-outputs/) · post: [The tree is exactly the snapshot](https://vznjs.github.io/vx/blog/strict-output-ownership/)
 - **Keys from git's index** — tracked clean files hash by their blob id, no read. [page](https://vznjs.github.io/vx/features/keys-from-git/) · post: [Your cache key is already in git's index](https://vznjs.github.io/vx/blog/keys-from-git/)
 - **Config keyed as evaluated** — the key sees the resolved config object. [page](https://vznjs.github.io/vx/features/typescript-config/) · post: [Configs are programs](https://vznjs.github.io/vx/blog/resolved-config-hashing/)
@@ -155,7 +157,7 @@ config key or an environment variable is missing here.
 
 ## Plugins
 
-- **A pipeline with seams** (`plugins`, `definePlugin`; stages `config` `discover` `project` `graph` `key` `fingerprint` `schedule` `admit` `executor` `cache` `telemetry` `commands`) — every stage is a plugin seam. [page](https://vznjs.github.io/vx/features/plugins/) · post: [A pipeline with seams](https://vznjs.github.io/vx/blog/pipeline-with-seams/)
+- **A pipeline with seams** (`plugins`, `definePlugin`; stages `config` `discover` `project` `graph` `key` `fingerprint` `schedule` `admit` `executor` `cache` `telemetry` `commands`) — every stage is a plugin seam; an `undefined`, `null` or `false` entry is skipped. [page](https://vznjs.github.io/vx/features/plugins/) · post: [A pipeline with seams](https://vznjs.github.io/vx/blog/pipeline-with-seams/)
 - **Write a plugin** (`vx init --plugin`) — scaffold a runnable plugin for a seam. [page](https://vznjs.github.io/vx/features/plugins/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)
 - **The local floor** — running and caching here are core's, not plugins. [page](https://vznjs.github.io/vx/features/local-floor/) · post: [The local floor](https://vznjs.github.io/vx/blog/the-local-floor/)
 - **Remote cache and execution** (`@vzn/vx-reapi`, `exec.remote`) — Bazel REAPI cache and workers; the scheduler stays here. [page](https://vznjs.github.io/vx/features/remote-execution/) · post: [Remote execution without moving the scheduler](https://vznjs.github.io/vx/blog/remote-execution/)
@@ -170,3 +172,4 @@ config key or an environment variable is missing here.
 - **Install as a remote action** (`exec.remote: 'only'`) — `node_modules` is built by an action, so stateless workers have it. [page](https://vznjs.github.io/vx/features/remote-install/) · post: [Remote execution without moving the scheduler](https://vznjs.github.io/vx/blog/remote-execution/)
 - **OTel live export** (`otel({ live })`) — spans and metrics stream as tasks end, so a dashboard follows a CI run live. [page](https://vznjs.github.io/vx/features/otel-live/) · post: [Watch a CI run while it runs](https://vznjs.github.io/vx/blog/otel-live/)
 - **Memory-aware admission** (`@vzn/vx-schedule-history`) — tasks are packed by the peak memory learned from past runs. [page](https://vznjs.github.io/vx/features/memory-admission/) · post: [A scheduler that learns from your runs](https://vznjs.github.io/vx/blog/a-scheduler-that-learns/)
+- **CI timings file** (`@vzn/vx-schedule-history`, `file`) — one JSON file of learned task times a CI cache carries between runners, so a fresh runner orders by real times. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Carry the scheduler's memory between CI runners](https://vznjs.github.io/vx/blog/ci-timings-file/)