# Every feature

> Every user-facing feature of vx, one line each, grouped by what it is

Every user-facing feature of vx, one line each, grouped by what it is
for. Each line names its surface (verb, flag, config key, plugin), links
its page on the site's [Features](https://vznjs.github.io/vx/features/) hub when it has one, and
its blog post, or says "no post" when the story is still owed.

**Rule:** a change that adds or changes a user-facing feature updates
this file, and its post, in the same commit (`CLAUDE.md`).
`tests/features-inventory.unsafe.test.ts` fails when a CLI verb, a flag, a
config key or an environment variable is missing here.

## Run

- **Run a task** (`vx run`) — run a task in the cwd's project, `pkg#task` directly, or several at once. [page](https://vznjs.github.io/vx/features/quickstart/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
- **Every project** (`--all`) — run the task in every project that declares it. [page](https://vznjs.github.io/vx/features/quickstart/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
- **pnpm-style filters** (`--filter`) — select projects by name, glob, path, dependencies (`foo...`), dependents (`...foo`), negation or a git range. [page](https://vznjs.github.io/vx/features/affected/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
- **Affected only** (`--affected`, `affectedBase`) — run what a change reaches, following task edges from a git base. [page](https://vznjs.github.io/vx/features/affected/) · post: [Run only what a change reaches](https://vznjs.github.io/vx/blog/affected/)
- **Concurrency** (`--concurrency`, `concurrency`) — a count or a share of the CPUs this process may use (`50%`). [page](https://vznjs.github.io/vx/features/concurrency/) · post: [One failure, and exactly what it takes down](https://vznjs.github.io/vx/blog/when-a-build-fails/)
- **Skip dependencies** (`--exclude-dependencies`) — skip all `dependsOn` edges, or named ones. [page](https://vznjs.github.io/vx/features/skip-dependencies/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
- **Failure policy** (`--continue`) — never, deps-ok (default: dependents skip) or always. [page](https://vznjs.github.io/vx/features/skipped-blockers/) · post: [One failure, and exactly what it takes down](https://vznjs.github.io/vx/blog/when-a-build-fails/)
- **Every skip names its blocker** — a skipped task says which failure blocked it. [page](https://vznjs.github.io/vx/features/skipped-blockers/) · post: [One failure, and exactly what it takes down](https://vznjs.github.io/vx/blog/when-a-build-fails/)
- **Retries** (`--retry`, `exec.retries`) — re-run a failed task; a pass after a failure marks it flaky. [page](https://vznjs.github.io/vx/features/flaky-detection/) · post: [Flaky is a claim only declared inputs can back](https://vznjs.github.io/vx/blog/flaky-tasks/)
- **Timeouts** (`--timeout`, `exec.timeout`, `timeout`, `VX_TASK_TIMEOUT`) — kill and fail a runaway task. [page](https://vznjs.github.io/vx/features/timeouts/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
- **Argument forwarding** (`--`) — args after `--` reach the task's command and fold into its key. [page](https://vznjs.github.io/vx/features/forward-args/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
- **Task picker** — `vx run` with no task in a terminal lists tasks to pick. [page](https://vznjs.github.io/vx/features/task-picker/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
- **Typo hints** — an unknown task, project or filter suggests the nearest name. [page](https://vznjs.github.io/vx/features/filter-hints/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
- **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/)
- **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/)
- **Implicit keyed `build`** — a project with no `build` gets a `^build` group keyed on its files, so source-only packages still move their dependants' keys. [page](https://vznjs.github.io/vx/features/implicit-build/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
- **dependsOn syntax** (`^name`, `pkg#name`, `name.*`, `^name.*`) — upstream, cross-project and pattern edges. [page](https://vznjs.github.io/vx/features/depends-on-syntax/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
- **Every name must resolve** — `vx run lint test typecheck` refuses to start if one name matches no project. [page](https://vznjs.github.io/vx/features/names-must-resolve/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
- **Tag filters** (`--filter tag:<pattern>`) — select projects by their config `tags`. [page](https://vznjs.github.io/vx/features/tag-filters/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
- **Directory and root filters** (`./<dir>`, `{<dir>}`, `.`, `//`) — select projects by path, or the root project. [page](https://vznjs.github.io/vx/features/dir-filters/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
- **Executor pools** (executor `capacity`) — a remote pool is admitted against its own width, not the laptop's cores. [page](https://vznjs.github.io/vx/features/executor-pools/) · post: [Remote execution without moving the scheduler](https://vznjs.github.io/vx/blog/remote-execution/)
- **Runs take turns** — two vx runs on one workspace wait on a lock and name who they wait for. [page](https://vznjs.github.io/vx/features/run-lock/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)

## Output

- **Framed output** — each task's log in its own frame, never interleaved. [page](https://vznjs.github.io/vx/features/framed-output/) · post: [A run you can read](https://vznjs.github.io/vx/blog/a-run-you-can-read/)
- **Output modes** (`--output-logs`) — full, errors-only, hash-only or none; the default follows the flow. [page](https://vznjs.github.io/vx/features/output-modes/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
- **Run summary** — one block: projects, tasks, cache, time; nothing prints below it. [page](https://vznjs.github.io/vx/features/run-summary/) · post: [A run you can read](https://vznjs.github.io/vx/blog/a-run-you-can-read/)
- **Per-task table** (`--verbosity`) — a per-task summary after the run. [page](https://vznjs.github.io/vx/features/per-task-table/) · post: [One failure, and exactly what it takes down](https://vznjs.github.io/vx/blog/when-a-build-fails/)
- **Failed output kept for agents** — a failure's full log is saved and pointed to. [page](https://vznjs.github.io/vx/features/failed-output-kept/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
- **Markdown report** (`--report`, `--report-file`) — a run report for a PR or `$GITHUB_STEP_SUMMARY`. [page](https://vznjs.github.io/vx/features/markdown-report/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
- **Run JSON** (`--summarize`) — per-run JSON for scripts, with the time the cache saved (`savedMs`). [page](https://vznjs.github.io/vx/features/run-json/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
- **Trace profile** (`--profile`) — Chrome-trace JSON of the run. [page](https://vznjs.github.io/vx/features/profile/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
- **Run tags** (`--tag`) — label a run; recorded in history. [page](https://vznjs.github.io/vx/features/run-tags/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
- **Stage timing** (`VX_TIMING`) — vx's own stage table, for performance work. [page](https://vznjs.github.io/vx/features/stage-timing/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
- **Output flows** — what is printed follows the run's intent (focused, broad or CI); a truthy `CI` wins. [page](https://vznjs.github.io/vx/features/output-flows/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
- **Cache-aware glyphs** — each task line's glyph shows ran, fresh, restored locally or remotely, failed, skipped or persistent. [page](https://vznjs.github.io/vx/features/cache-glyphs/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
- **GitHub Actions log groups** — on Actions, each task's block folds in a `::group::` with its outcome and time. [page](https://vznjs.github.io/vx/features/actions-log-groups/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
- **Colors** (`NO_COLOR`, `FORCE_COLOR`) — truecolor output, forced on or off by env. [page](https://vznjs.github.io/vx/features/colors/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
- **Signal-named exits** — a failure reads `exit 137, 128 + SIGKILL`. [page](https://vznjs.github.io/vx/features/signal-exits/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
- **Plain output off a TTY** — no live region, and a missing task lists tasks instead of opening the picker. [page](https://vznjs.github.io/vx/features/plain-off-tty/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)

## Plan and explain

- **Dry run** (`--dry`) — the task graph and the predicted hits and misses, text or JSON (with the predicted wall time and its critical path), nothing runs. [page](https://vznjs.github.io/vx/features/dry-run/) · post: [See the plan before you run it](https://vznjs.github.io/vx/blog/dry-run/)
- **Graph** (`--graph`) — the task graph as Graphviz DOT. [page](https://vznjs.github.io/vx/features/task-graph/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
- **vx why** (`vx why`, `--run`) — why a task re-ran, down to the file, env var or config that changed. [page](https://vznjs.github.io/vx/features/vx-why/) · post: [Why did this re-run?](https://vznjs.github.io/vx/blog/why-did-this-rerun/)
- **vx show** (`vx show`) — every project, a project's or a task's live resolved config. [page](https://vznjs.github.io/vx/features/vx-show/) · post: [See what a task really is](https://vznjs.github.io/vx/blog/vx-show/)
- **vx last** (`vx last`, `--list`, `--failed`, `--log`) — replay a recorded run's summary, list recent runs, or print one task's output. [page](https://vznjs.github.io/vx/features/vx-last/) · post: [The last run, on request](https://vznjs.github.io/vx/blog/vx-last/)
- **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 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/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/)

## Cache

- **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/)
- **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 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 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/)
- **Warm hits restore nothing** — when outputs on disk already match, a hit costs a few stats. [page](https://vznjs.github.io/vx/features/warm-hits/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
- **Hits replay both streams** — stdout and stderr come back in the order the run printed them. [page](https://vznjs.github.io/vx/features/both-streams/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
- **Restore lane** — cache restores run on their own lane, up to twice `--concurrency`. [page](https://vznjs.github.io/vx/features/restore-lane/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
- **Config evaluation cache** — provably pure `vx.config.ts` files are read back as data, not evaluated again. [page](https://vznjs.github.io/vx/features/config-cache/) · post: [Guard rails that tell you the fix](https://vznjs.github.io/vx/blog/guard-rails/)
- **Line-ending-correct keys** — files git filters (`eol`, `core.autocrlf`) key on the bytes the build sees. [page](https://vznjs.github.io/vx/features/line-endings/) · post: [Your cache key is already in git's index](https://vznjs.github.io/vx/blog/keys-from-git/)
- **Background remote uploads** — remote writes drain at the end of the run and never fail the build. [page](https://vznjs.github.io/vx/features/background-uploads/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
- **Bring your own remote cache** (plugin `cache`) — plug any cache server in through one interface. [page](https://vznjs.github.io/vx/features/custom-remote-cache/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)

## Correctness

- **Sandboxed tasks** (`exec.sandbox`: `allow`, `deny`, `ignore`, `weakerNetworkIsolation`, `weakerWhenNested`) — a task reads and writes only what it declares; `allow` names `read`, `write`, `network`, `unixSockets`, `localBinding`, `pty`, `systemInfo`, `gitConfig`, `machLookup`. [page](https://vznjs.github.io/vx/features/sandbox/) · post: [The sandbox](https://vznjs.github.io/vx/blog/the-sandbox/)
- **Env isolation** (`exec.env`: `define`, `passThrough`, `secret`) — a task sees only the env it names; secrets are masked. [page](https://vznjs.github.io/vx/features/env-isolation/) · post: [A task sees only the env it names](https://vznjs.github.io/vx/blog/env-isolation/)
- **vx lock** (`vx lock`, `--check`, `--format json`, `--frozen`) — freeze what configs evaluate to; CI and agents check it. [page](https://vznjs.github.io/vx/features/vx-lock/) · post: [vx lock: freezing what the key sees](https://vznjs.github.io/vx/blog/lock-and-frozen/)
- **Flaky detection** — a task that fails then passes is reported flaky. [page](https://vznjs.github.io/vx/features/flaky-detection/) · post: [Flaky is a claim](https://vznjs.github.io/vx/blog/flaky-tasks/)
- **Project boundaries** — globs never cross into another project. [page](https://vznjs.github.io/vx/features/project-boundaries/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
- **Artifact integrity checks** — a CRC-32, a key match and an outputs-only check on every artifact; damage is a miss. [page](https://vznjs.github.io/vx/features/artifact-integrity/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
- **Sandbox names what to grant** — a refused write is named beside the failed task with the path to allow. [page](https://vznjs.github.io/vx/features/sandbox-grants/) · post: [Guard rails that tell you the fix](https://vznjs.github.io/vx/blog/guard-rails/)
- **Strict numeric flags** — `0x10`, `1e3` and `2.7` are refused, never reinterpreted. [page](https://vznjs.github.io/vx/features/strict-numbers/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
- **Verified releases** — binaries carry provenance, `vx upgrade` checks SHA-256, npm publishes with provenance. [page](https://vznjs.github.io/vx/features/verified-releases/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)

## Daily work

- **Watch mode** (`vx watch`, `VX_WATCH_POLL`) — re-run what a change affects, on content, not events. [page](https://vznjs.github.io/vx/features/watch/) · post: [Watch: a content gate](https://vznjs.github.io/vx/blog/watch-mode/)
- **Dev servers in the graph** (`exec.persistent`, `readyWhen`, `VX_READY_NOTICE_MS`) — a server is a node; dependents start when it is ready. [page](https://vznjs.github.io/vx/features/dev-servers/) · post: [Dev servers as graph nodes](https://vznjs.github.io/vx/blog/dev-servers-in-the-graph/)
- **Interactive tasks** (`exec.interactive`) — a task that owns the terminal. [page](https://vznjs.github.io/vx/features/interactive-tasks/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
- **Shell completions** (`vx completions`) — bash, zsh, fish. [page](https://vznjs.github.io/vx/features/completions/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
- **vx upgrade** (`vx upgrade`) — replace the binary with a release. [page](https://vznjs.github.io/vx/features/upgrade/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
- **Help and version** (`vx help`, `vx version`) — every verb's reference. [page](https://vznjs.github.io/vx/features/help-and-version/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
- **Did-you-mean** — a mistyped flag or verb gets the nearest valid spelling. [page](https://vznjs.github.io/vx/features/did-you-mean/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
- **Task typed as a verb** — `vx build app` answers with the exact `vx run` command that does it. [page](https://vznjs.github.io/vx/features/task-as-verb/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)

## Config

- **Config in TypeScript** (`vx.config.ts`, `defineProject`, `vx.workspace.ts`, `defineWorkspace`) — typed, composable; no named inputs. [page](https://vznjs.github.io/vx/features/typescript-config/) · post: [Config in TypeScript](https://vznjs.github.io/vx/blog/config-in-typescript/)
- **Tasks** (`tasks`, `exec.command`, `dependsOn`, `description`, `tags`) — one command per task; the shell is the API. [page](https://vznjs.github.io/vx/features/one-command-tasks/) · post: [One command per task](https://vznjs.github.io/vx/blog/one-command-per-task/)
- **Workspace rules** (`rules`) — speed-only checks, on by default, configurable. [page](https://vznjs.github.io/vx/features/workspace-rules/) · post: [Guard rails that tell you the fix](https://vznjs.github.io/vx/blog/guard-rails/)
- **Config worker timeout** (`VX_CONFIG_WORKER_TIMEOUT_MS`) — bound a config's evaluation. [page](https://vznjs.github.io/vx/features/config-timeout/) · post: [Guard rails that tell you the fix](https://vznjs.github.io/vx/blog/guard-rails/)
- **No nested runs** (`VX_RUN_TASK`, `VX_RUN_WORKSPACE`) — set on every task; a `vx run` inside a task of the same workspace is refused. [page](https://vznjs.github.io/vx/features/no-nested-runs/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
- **Typed config helpers** (`defineProject`) — autocomplete for task names in `dependsOn`, errors while you edit. [page](https://vznjs.github.io/vx/features/typed-helpers/) · post: [Config in TypeScript, and why there are no named inputs](https://vznjs.github.io/vx/blog/config-in-typescript/)
- **Presets** — a TypeScript function returning a task config, shared across projects. [page](https://vznjs.github.io/vx/features/presets/) · post: [Config in TypeScript, and why there are no named inputs](https://vznjs.github.io/vx/blog/config-in-typescript/)
- **Clean config errors** — a bad config fails at load naming the key, with no stack trace. [page](https://vznjs.github.io/vx/features/config-errors/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)

## CI

- **Results on GitHub** (`@vzn/vx-ci`: `github()`) — job summary and Checks API annotations. [page](https://vznjs.github.io/vx/features/github-ci/) · post: [Your run, on the pull request](https://vznjs.github.io/vx/blog/results-on-github/)
- **PR check run** (`github({ checks })`) — a check run on the commit with the run summary as its output. [page](https://vznjs.github.io/vx/features/pr-check-run/) · post: [Your run, on the pull request](https://vznjs.github.io/vx/blog/results-on-github/)
- **Cache scope from the ref** (`github({ cacheScope })`) — main writes trusted keys; a PR writes only its own scope. [page](https://vznjs.github.io/vx/features/ref-cache-scope/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)

## Adoption

- **Start in a minute** (`vx init`, `--dry`, `--format json`, `--force`, `--mjs`) — write `vx.workspace.ts` and one `vx.config.ts` per package; `--dry --format json` hands an agent the plan as data. [page](https://vznjs.github.io/vx/features/quickstart/) · post: [Hello, vx](https://vznjs.github.io/vx/blog/hello-vx/)
- **Migrate from Turborepo or Nx** (`vx init`, `--native`, `--keep`, `@vzn/vx-migrate`) — native config, or keep `turbo()` / `nx()` as a start. [page](https://vznjs.github.io/vx/features/migrate/) · posts: [From Turborepo](https://vznjs.github.io/vx/blog/from-turborepo/), [From Nx](https://vznjs.github.io/vx/blog/from-nx/)
- **Keep a Turbo or Nx remote cache** (`turboCache()`, `nxCache()`) — reuse the cache server you have. [page](https://vznjs.github.io/vx/features/keep-remote-cache/) · post: [From Nx: keep the graph, drop the platform](https://vznjs.github.io/vx/blog/from-nx/)
- **One binary** — one file, nothing to install underneath. [page](https://vznjs.github.io/vx/features/one-binary/) · post: [One binary](https://vznjs.github.io/vx/blog/one-binary/)
- **The playground** — vx's planner in the browser. [page](https://vznjs.github.io/vx/features/playground/) · post: [Try the planner in your browser](https://vznjs.github.io/vx/blog/the-playground/)
- **Benchmarks you can re-run** (`@vzn/vx-bench`) — vx against Turborepo and Nx. [page](https://vznjs.github.io/vx/features/fastest/) · posts: [Benchmarks you can re-run](https://vznjs.github.io/vx/blog/honest-benchmarks/), [Why vx is fast](https://vznjs.github.io/vx/blog/why-vx-is-fast/)
- **npm pre/post scripts** — `pre<x>` and `post<x>` hooks fold into `x`'s command when `vx init` maps scripts. [page](https://vznjs.github.io/vx/features/npm-hooks/) · post: [From npm scripts or Vite Task](https://vznjs.github.io/vx/blog/from-scripts-and-vite-task/)
- **Vite Task adoption** (`bunx @vzn/vx-migrate`) — writes configs from vite-plus `run.tasks` as well as Turbo and Nx. [page](https://vznjs.github.io/vx/features/vite-task-adoption/) · post: [From npm scripts or Vite Task](https://vznjs.github.io/vx/blog/from-scripts-and-vite-task/)
- **Nx executors as one process** (`nx-exec`) — any Nx executor runs as one vx task with its Nx env set. [page](https://vznjs.github.io/vx/features/nx-exec/) · post: [From Nx: keep the graph, drop the platform](https://vznjs.github.io/vx/blog/from-nx/)
- **Programmatic API** (`run`, `planRun`) — run or plan from your own scripts via `@vzn/vx`. [page](https://vznjs.github.io/vx/features/programmatic-api/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)

## 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/)
- **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/)
- **OpenTelemetry** (`@vzn/vx-otel`) — each run exported to your OpenTelemetry backend, never breaking it. [page](https://vznjs.github.io/vx/features/opentelemetry/) · post: [Observability that cannot break a run](https://vznjs.github.io/vx/blog/telemetry-never-breaks-a-run/)
- **vx mcp** (`@vzn/vx-mcp`, `vx mcp`) — cache stats, run history, `vx why`'s full answer, a run tool (`mcp({ run })` limits it to named tasks or turns it off), a plan tool, a task's resolved config, the lock audit, cache pruning, the `vx init` plan, an offline docs search and a task list narrowed by `--filter` / `--affected` for coding agents. [page](https://vznjs.github.io/vx/features/mcp/) · post: [Give your coding agent the build's memory](https://vznjs.github.io/vx/blog/agents-and-mcp/)
- **vx prune** (`@vzn/vx-lockfile`, `vx prune`, `--production`) — copy projects and their deps, lockfile pruned, for a Docker build; `--production` leaves out what only dev dependencies need. [page](https://vznjs.github.io/vx/features/vx-prune/) · post: [Ship one app, not the whole monorepo](https://vznjs.github.io/vx/blog/vx-prune/), [A runtime image without the dev tools](https://vznjs.github.io/vx/blog/prune-production/)
- **vx history** (`@vzn/vx-schedule-history`, `vx history`) — what the scheduler learned per task. [page](https://vznjs.github.io/vx/features/vx-history/) · post: [A scheduler that learns from your runs](https://vznjs.github.io/vx/blog/a-scheduler-that-learns/)
- **Setup and teardown hooks** (`setup`, `teardown`) — plugin code around the run, bounded by a timeout. [page](https://vznjs.github.io/vx/features/setup-teardown/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)
- **REAPI TLS, mTLS and headers** — connect to hosted servers such as BuildBuddy the way Bazel does. [page](https://vznjs.github.io/vx/features/reapi-tls/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
- **REAPI execution records** — a repeat remote execution skips the worker and replays outputs and stdout. [page](https://vznjs.github.io/vx/features/reapi-action-cache/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
- **REAPI verified downloads and deadlines** — a corrupt blob or a wedged server degrades to a miss, never a hang. [page](https://vznjs.github.io/vx/features/reapi-safety/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
- **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/)

---

# API reference

> Every export of @vzn/vx, generated from src/index.ts by

Every export of `@vzn/vx`, generated from `src/index.ts` by
`tests/api-reference.test.ts`: the declaration (comments dropped, a
function to its signature, a class to its public members) and the doc
comment above it. [The public surface](../modules/public-surface/) groups the
same names by what they are for; the plugins guide shows them in use.

## `AdmitContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface AdmitContext {
  readonly running: readonly TaskNode[]
  readonly concurrency: number
}
```

## `AffectedChanges`

type · `src/workspace/affected.ts`

What `--affected` seeds its tasks from (owner, 2026-10-04): the changed
projects, each one's changed paths relative to it, and the projects a
change reaches as a whole — every task in one is affected whatever its
inputs say, because the reason was no path of its own (a lockfile claim,
a manifest edge at the base, a config import, a nested repository, a
workspace-wide file).

```ts
export interface AffectedChanges {
  projects: Set<string>
  changed: readonly string[]
  paths: ReadonlyMap<string, readonly string[]>
  whole: ReadonlySet<string>
  nested?: readonly string[]
}
```

## `applyMigration`

function · `src/workspace/migration.ts`

Render a plan to files, refuse to overwrite without `force`, write (or
print, under `dry`), and report. Returns the process exit code.

```ts
export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
```

## `ApplyMigrationArgs`

type · `src/workspace/migration.ts`

```ts
export interface ApplyMigrationArgs {
  root: string
  metas: readonly ProjectMeta[]
  plan: MigrationPlan
  source: string
  verb: string
  dry: boolean
  force: boolean
  init?: boolean
  notes?: readonly string[]
  unmapped?: boolean
  format?: MigrationFormat
  json?: boolean
}
```

## `buildPackageGraph`

function · `src/workspace/package-graph.ts`

`taskEdges`: project → the projects its tasks name in a cross-project
`dependsOn` (`e2e` → `app` from `dependsOn: ['app#build']`). A dependent
the manifest does not know but the task graph does; without it
`--filter '...app'` never selected `e2e`, and a CI that runs "what
changed and everything depending on it" silently left it out
(2026-09-10). The `^task` walk still reads `directDeps`, which carries
both — a task edge IS a dependency.

```ts
export function buildPackageGraph(
  projects: ProjectMeta[],
  taskEdges?: ReadonlyMap<string, readonly string[]>,
): PackageGraph
```

## `Cache`

class · `src/cache/cache.ts`

```ts
export class Cache implements CacheLayer {
  readonly hasRemote
  readonly uploads: UploadTally
  readonly storeDir: string | undefined
  readonly schemaReset: SchemaReset | null
  readonly formatChange: SchemaReset | null
  readonly storeReset: SchemaReset | null
  static inspect(cacheDir: string): Cache
  constructor(
    private readonly cacheDir: string,
    localPolicy: { read: boolean; write: boolean } = { read: true, write: true },
    repoDir?: string,
    private readonly artifactCeiling: number = MAX_DECOMPRESSED_ARTIFACT_BYTES,
    mode: 'open' | 'inspect' | 'preview' = 'open',
    storeRoot?: string | null,
  )
  getConfigEval(key: string): string | null
  getConfigClosures(configPaths: readonly string[]): Map<string, string[]>
  putConfigClosure(configPath: string, files: readonly string[]): void
  getConfigEvals(keys: readonly string[]): Map<string, string>
  putConfigEval(key: string, json: string): void
  putConfigEvals(entries: ReadonlyArray<readonly [string, string]>): void
  putConfigClosures(entries: ReadonlyArray<readonly [string, readonly string[]]>): void
  hashFile(filePath: string): Promise<string>
  hashBytes(bytes: Uint8Array, nearPath: string): string
  hashFiles(paths: readonly string[]): Promise<Map<string, string>>
  knownBlobSizes(oids: readonly string[]): Map<string, number>
  rememberBlobSizes(sizes: ReadonlyMap<string, number>): void
  blobVerdict(digest: string): string[] | undefined
  rememberBlobVerdict(digest: string, paths: readonly string[]): void
  key(input: CacheKeyInput): Promise<string>
  async get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null>
  getIngested(hash: string): Promise<CacheEntry | null>
  async getMany(
    hashes: readonly string[],
    ctx?: (hash: string) => CacheGetContext,
  ): Promise<Map<string, CacheEntry>>
  async has(hash: string): Promise<'local' | 'remote' | null>
  async prefetch(_hash: string, _ctx?: CacheGetContext): Promise<boolean>
  loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]>
  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean>
  outputsPath(hash: string): string
  artifactSize(hash: string): number | undefined
  async recordOutputDirs(
    hash: string,
    projectDir: string,
    prefixes: readonly string[],
    holds?: (files: readonly string[]) => boolean,
  ): Promise<void>
  recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void
  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]>
  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean>
  async restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void>
  assertWritable(): void
  async save(args: {
    hash: string
    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
    projectDir: string
    outputFiles: string[]
    skipLocalWrite?: boolean
    workspaceOutputFiles?: string[]
    workspaceRoot?: string
    inputComponents?: readonly TaskInputRow[]
  }): Promise<void>
  get localWritesEnabled(): boolean
  packArtifactBytes(args: SaveArgs): Promise<Uint8Array>
  pinArtifact(hash: string): { body: Blob; release: () => Promise<void> }
  async ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void>
  dbHandle(): Database
  recordRun(run: RunRecord): void
  recordRuns(runs: readonly RunRecord[]): void
  recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void
  stats(opts: CacheStatsOptions = {}): CacheStats
  async evictIfDue(
    policy: { maxAgeMs?: number; maxBytes?: number },
    now: number = Date.now(),
  ): Promise<PruneResult | null>
  async prune(options: PruneOptions): Promise<PruneResult>
  async orphanStats(): Promise<{ orphans: number; orphanBytes: number }>
  close(): void
}
```

## `CacheConfig`

type · `src/config.ts`

```ts
export interface CacheConfig {
  inputs: CacheInputs
  outputs: CacheOutputs
}
```

## `CacheContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface CacheContext extends BaseContext {
  readonly localCache: Cache
  readonly policy: CachePolicy
}
```

## `CacheInputs`

type · `src/config.ts`

```ts
export interface CacheInputs {
  files: readonly string[]
  workspaceFiles?: readonly string[]
  env?: readonly string[]
  tasks?: readonly string[]
  runtime?: readonly string[]
  workspaceRuntime?: readonly string[]
}
```

## `cacheKeyDiff`

function · `src/orchestrator/metrics.ts`

The moat: name the exact cache-key components (files / env / runtime /
upstream …) that differ between this run of a task and its immediately-
previous run. Resolves each run to its task hash via `runs.hash`, then
full-outer-joins the two runs' `entry_inputs` rows (keyed by the entry
hash) over `(kind, name)`:

- present in both with a different hash → `changed`
- only in this run → `added`
- only in the previous run → `removed`
- equal → counted as unchanged

Pure SQL + an app-side set join (`diffKeyComponents`) — no config
re-evaluation, no re-hash.
Always returns a value (never throws); `found:false` when the run/task pair
has no row, `entries:[]` for the first run of a task.

```ts
export function cacheKeyDiff(db: Database, runId: string, taskId: string): CacheKeyDiff
```

## `CacheKeyDiff`

type · `src/orchestrator/metrics.ts`

```ts
export interface CacheKeyDiff {
  runId: string
  taskId: string
  found: boolean
  previousRunId: string | null
  entries: InputDiffEntry[]
  unchangedCount: number
  note: string
}
```

## `CacheLayer`

type · `src/cache/layer.ts`

The shape every cache implementation honors. `Cache` (the local store)
and `LayeredCache` both `implements` this so the
orchestrator's `executeTask` can take either without a discriminated
union and we get a compile-time guarantee the surfaces stay congruent.

```ts
export interface CacheLayer {
  readonly local?: Cache | undefined
  readonly hasRemote?: boolean
  remoteHasMany?(hashes: readonly string[]): Promise<Set<string> | null>
  markRemoteAbsent?(hashes: Iterable<string>): void
  drainUploads?(): Promise<void>
  key(input: CacheKeyInput): Promise<string>
  get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null>
  getMany?(
    hashes: readonly string[],
    ctx?: (hash: string) => CacheGetContext,
  ): Promise<Map<string, CacheEntry>>
  has(hash: string): Promise<'local' | 'remote' | null>
  prefetch(hash: string, ctx?: CacheGetContext): Promise<boolean>
  loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]>
  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean>
  recordOutputDirs?(
    hash: string,
    projectDir: string,
    prefixes: readonly string[],
    holds?: (files: readonly string[]) => boolean,
  ): Promise<void>
  recordOutputStamps?(hash: string, projectDir: string, workspaceRoot: string): void
  loadOutputDirsBatch?(hashes: readonly string[]): Map<string, OutputDirRow[]>
  outputDirsCurrent?(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean>
  restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void>
  save(args: {
    hash: string
    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
    projectDir: string
    outputFiles: string[]
    skipLocalWrite?: boolean
    workspaceOutputFiles?: string[]
    workspaceRoot?: string
    inputComponents?: readonly TaskInputRow[]
  }): Promise<void>
  ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void>
  recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void
  stats(opts?: CacheStatsOptions): CacheStats
  hashFile(filePath: string): Promise<string>
  outputsPath(hash: string): string
  artifactSize?(hash: string): number | undefined
  prune(options: PruneOptions): Promise<PruneResult>
  close(): void
}
```

## `CacheOutputs`

type · `src/config.ts`

```ts
export interface CacheOutputs {
  files: readonly string[]
  workspaceFiles?: readonly string[]
}
```

## `CachePolicy`

type · `src/cache/policy.ts`

Independent read/write control over the two cache layers (local +
remote). Replaces the old single `noCache` boolean: each axis can be
toggled on its own so `--force` (re-execute but still refresh the
cache) is distinct from `--no-cache` (disable everything).

The task-artifact get/save path is gated, and the local axes also gate
the local store's config-evaluation reads and writes and its file-hash
writes (`cache.ts`). `recordRun`, `stats`, `prune`, key derivation, and
prefetch-ingest are never affected — they are bookkeeping/analytics
that a run policy has no business disabling.

```ts
export interface CachePolicy {
  localRead: boolean
  localWrite: boolean
  remoteRead: boolean
  remoteWrite: boolean
  remoteScope?: string
}
```

## `CacheSource`

type · `src/orchestrator/telemetry.ts`

Where a task's result came from, derived ONCE in core from the status.

```ts
export type CacheSource = 'miss' | 'local' | 'remote' | 'none'
```

## `CiContext`

type · `src/orchestrator/run-context.ts`

```ts
export interface CiContext {
  ci: boolean
  provider: string | null
  runUrl?: string
  change?: string
  pipeline?: string
  job?: string
  attempt?: number
}
```

## `clampInt`

function · `src/util/num.ts`

Clamp to an INTEGER in `[min, max]`; a non-finite value collapses to `min`.

The floor is load-bearing wherever the result reaches SQL: a fractional
`LIMIT` is a `datatype mismatch` error, not a smaller page.

```ts
export function clampInt(n: number, min: number, max: number): number
```

## `collectInfo`

function · `src/orchestrator/doctor.ts`

```ts
export async function collectInfo(cwd: string, opts: CollectInfoOptions = {}): Promise<InfoFacts>
```

## `CollectInfoOptions`

type · `src/orchestrator/doctor.ts`

```ts
export interface CollectInfoOptions {
  readonly cacheDir?: string
  readonly warn?: (message: string) => void
}
```

## `CommandContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface CommandContext extends BaseContext {
  readonly concurrency: number
  readonly vx: readonly string[]
}
```

## `definePlugin`

function · `src/orchestrator/plugin.ts`

The one way to make a plugin: `definePlugin(import.meta, { ...hooks })`.
The name is read from the package the calling module belongs to — the
nearest `package.json` above it — and stamped where the workspace loader
checks for it, so a plugin cannot be named anything but its package.

```ts
export function definePlugin(origin: PluginOrigin, hooks: PluginHooks): VxPlugin
```

## `defineProject`

function · `src/config.ts`

Identity function — exists only so TypeScript narrows literal types
and, crucially, **validates `dependsOn` against this project's own
task names**. A bare entry that isn't a declared task key is a compile
error; `^name` / `pkg#name` forms reference other projects and stay
free strings. Runtime behavior is unchanged (it returns its input).

```ts
export function defineProject<const T extends ProjectConfig>(
  config: T &
    KnownExecs<T> &
    Known<T, ProjectConfig> & {
      tasks?: {
        [K in keyof NonNullable<T['tasks']>]?: Known<NonNullable<T['tasks']>[K], TaskConfig> & {
          dependsOn?: readonly DependsOnEntry<Extract<keyof NonNullable<T['tasks']>, string>>[]
          exec?: Known<At<NonNullable<T['tasks']>[K], 'exec'>, ExecConfig>
          cache?: Known<At<NonNullable<T['tasks']>[K], 'cache'>, CacheConfig> & {
            inputs?: Known<At<At<NonNullable<T['tasks']>[K], 'cache'>, 'inputs'>, CacheInputs>
            outputs?: Known<At<At<NonNullable<T['tasks']>[K], 'cache'>, 'outputs'>, CacheOutputs>
          }
        }
      }
    },
): T
```

## `defineWorkspace`

function · `src/config.ts`

```ts
export function defineWorkspace<T extends WorkspaceConfig>(
  config: T &
    Known<T, WorkspaceConfig> & {
      cacheRetention?: Known<
        At<T, 'cacheRetention'>,
        NonNullable<WorkspaceConfig['cacheRetention']>
      >
      rules?: Known<At<T, 'rules'>, WorkspaceRules>
    },
): T
```

## `DiscoverContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface DiscoverContext extends WorkspaceHookContext {
  readonly cacheDir: string
  readonly projects: readonly ProjectMeta[]
  worktreeChanges(): Promise<readonly string[] | null>
}
```

## `escapeMarkdownCell`

function · `src/orchestrator/run-report.ts`

Make a value safe inside a GFM table cell. Task names are arbitrary TS
object keys and the loader accepts `|` and newlines, either of which
silently breaks the table on the consumer (`>> $GITHUB_STEP_SUMMARY`):
a bare pipe adds a column, a newline splits the row.

Exported because this file is not the only markdown table describing a run:
the cloud plugin's GitHub job summary renders the same data from the same
unvalidated names and shipped WITHOUT this escape, so a `|` in a task name
or an output path shifted its columns. One definition, so the two
cannot disagree about what a cell may contain.

A pipe splits the row unless an ODD run of backslashes precedes it (GFM
reads `\\` as one escaped backslash), so a pipe after an odd run is already
escaped and one more backslash would free it: `a\|b` became `a\\|b`, two
cells. A lone `\r` ends a line too.

```ts
export function escapeMarkdownCell(value: string): string
```

## `ExecConfig`

type · `src/config.ts`

```ts
export interface ExecConfig {
  command: string
  remote?: boolean | 'only'
  env?: ExecEnv
  timeout?: number
  retries?: number
  persistent?: PersistentConfig
  interactive?: boolean
  sandbox?: SandboxConfig
}
```

## `ExecEnv`

type · `src/config.ts`

```ts
export interface ExecEnv {
  passThrough?: readonly string[]
  define?: Record<string, string>
  secret?: readonly string[]
}
```

## `ExecuteRequest`

type · `src/exec/executor.ts`

```ts
export interface ExecuteRequest {
  readonly taskId: string
  readonly workspaceRoot: string
  readonly inputs?: TaskInputs
  readonly cacheKey?: string
  readonly refresh?: boolean
  readonly remoteOnly?: boolean
  readonly download?: 'eager' | 'deferred'
  readonly outputs: {
    readonly files: readonly string[]
    readonly workspaceFiles: readonly string[]
  }
  readonly command: string
  readonly forwardArgs: readonly string[]
  readonly cwd: string
  readonly env: NodeJS.ProcessEnv
  readonly envDefine: Readonly<Record<string, string>>
  readonly capture: CaptureConfig
  readonly timeoutMs?: number
  readonly onStdout: (chunk: string) => void
  readonly onStderr: (chunk: string) => void
  readonly signal?: AbortSignal
  readonly liveChildren?: Set<ReturnType<typeof Bun.spawn>>
  readonly onSpawn?: (pid: number) => void
  readonly sandbox?: ExecuteSandbox
  readonly terminal?: true
}
```

## `ExecuteResult`

type · `src/exec/executor.ts`

```ts
export interface ExecuteResult extends RunResult {
  readonly violations: readonly SandboxViolation[]
  readonly outputs?: { kind: 'disk' } | { kind: 'deferred'; materialize: () => Promise<void> }
  readonly where?: string
}
```

## `ExecuteSandbox`

type · `src/exec/executor.ts`

Sandbox baselines + the user's resolved sandbox block, when the task is sandboxed.

```ts
export interface ExecuteSandbox {
  readonly baseAllowRead: readonly string[]
  readonly baseDenyRead: readonly string[]
  readonly reportWithin: string
  readonly reportLinked: readonly string[]
  readonly config: ResolvedSandboxConfig
}
```

## `ExecutorContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface ExecutorContext extends BaseContext {
  readonly concurrency: number
}
```

## `executorFallback`

function · `src/exec/executor.ts`

What a remote executor rejects with when it gives a task back: core runs
the same request on the local floor and says `reason` once (a remote that
never started it, B-100). A task placed `remote: 'only'` must not run
here, so it fails naming `reason` instead. Matched by name, as
`isUserError` is: a plugin's `@vzn/vx` can be another copy of this class.

```ts
export function executorFallback(reason: string): Error
```

## `exitSignal`

function · `src/exec/runner.ts`

The reverse: the signal an exit above 128 stands for (137 → SIGKILL),
by the platform's numbering; undefined for a plain exit. The shell
reports 128 + n for a death by signal n, so the read is the shell's
convention, not proof — a command may exit 137 on its own.

```ts
export function exitSignal(code: number): string | undefined
```

## `findWorkspaceRoot`

function · `src/workspace/workspace.ts`

Walk up from `start` to find the workspace root. A directory is a root
CANDIDATE when it contains `pnpm-workspace.yaml` or a `package.json`.

The nearest candidate that CLAIMS `start` wins — one of the directories
between it and `start` matches one of its package globs. Every workspace
member has its own `package.json`, so stopping at the first candidate would
make a run from inside a package treat that package as the whole workspace:
`^task` edges vanish, upstream hashes drop out of the cache key (stale
hits), and a second cache dir appears under the member. Claiming is decided
with the same globs `loadWorkspace` applies, so "the root that claims me"
and "the root that lists me as a project" cannot diverge. An outer root
that lists both the claimer and the claimed member outranks the claimer:
from the claimer's own directory the walk reaches the outer root too.

When no candidate claims `start` — a standalone package, or a subdirectory
of a single-project repo — the nearest candidate wins (the root itself IS
the project). Throws a `UserError` when there is no candidate before `/`.
A load that goes on to `loadWorkspace` passes its `reads`, so the
root's manifest is read once for both.

```ts
export async function findWorkspaceRoot(
  start: string,
  reads: LoadReads = new Map(),
): Promise<string>
```

## `FingerprintChange`

type · `src/orchestrator/plugin.ts`

```ts
export interface FingerprintChange {
  readonly file: string
  readonly before: Uint8Array | null
  readonly after: Uint8Array | null
}
```

## `FingerprintClaim`

type · `src/orchestrator/plugin.ts`

A plugin's claim on workspace fingerprint files — see `VxPlugin.fingerprint`.

```ts
export interface FingerprintClaim {
  readonly files: readonly string[]
  affected(
    change: FingerprintChange,
    ctx: FingerprintContext,
  ): Iterable<string> | undefined | Promise<Iterable<string> | undefined>
}
```

## `FingerprintContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface FingerprintContext extends BaseContext {
  readonly projects: ReadonlyArray<{ readonly name: string; readonly dir: string }>
}
```

## `foldScriptHooks`

function · `src/workspace/migration.ts`

A package.json script with the `pre<name>` / `post<name>` hooks npm runs
around it, as ONE sh command. Each part runs in its own subshell, so a
`;` or an `exit` in one ends that part alone, and the chain stops at the
first that fails, as npm stops. The parts sit in a function the
forwarded `--` args are appended to, and only the body takes them, as
npm appends them to the script and never to its hooks. A plain ` && `
join handed them to the post hook, and `test -f x && echo A; echo B` ran
`echo B` after a failed pre hook and went green (item 905). npm appends
them as TEXT: no part sees them as `$1`…, so the function quotes them
into `vx_a`, clears its positional parameters, and evals the body with
`vx_a` after it; `"$@"` on the body made a script's `$1` the first
forwarded arg and its `$*` print them twice. Each part ends on its own
line, so a trailing `# comment` cannot swallow the paren. A script with
no hooks is its body, verbatim.

```ts
export function foldScriptHooks(
  pre: string | undefined,
  body: string,
  post: string | undefined,
): string
```

## `GeneratedProject`

type · `src/workspace/migration.ts`

```ts
export interface GeneratedProject {
  name: string
  dir: string
  importLines: string[]
  tags?: readonly string[]
  tasks: GeneratedTask[]
}
```

## `GeneratedTask`

type · `src/workspace/migration.ts`

```ts
export interface GeneratedTask {
  name: string
  todos: string[]
  task: Record<string, unknown> | null
}
```

## `GitContext`

type · `src/orchestrator/run-context.ts`

```ts
export interface GitContext {
  commitSha: string | null
  branch: string | null
  dirty: boolean | null
}
```

## `GraphHookContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface GraphHookContext extends BaseContext {
  readonly requested: readonly string[]
}
```

## `HistoryProvider`

type · `src/orchestrator/history.ts`

```ts
export interface HistoryProvider {
  loadFor(taskIds: readonly string[]): Promise<HistoryTable>
  p50sFor?(taskIds: readonly string[]): Promise<ReadonlyMap<string, number>>
}
```

## `HistoryTable`

type · `src/orchestrator/history.ts`

Map keyed by `project#task`.

```ts
export type HistoryTable = ReadonlyMap<string, TaskHistory>
```

## `HostContext`

type · `src/orchestrator/run-context.ts`

```ts
export interface HostContext {
  host: string | null
  os: string
  arch: string
}
```

## `InfoFacts`

type · `src/orchestrator/doctor.ts`

The doctor's facts, typed: what `--format json` prints and the pretty rows render.

```ts
export interface InfoFacts {
  vx: string
  bun: string
  bunSupported: boolean
  git: string | null
  gitStatusCache: { fsmonitor: boolean; untrackedCache: boolean } | null
  workspaceRoot: string
  projects: number
  tasks: number
  configErrors: Array<{ path: string; message: string }>
  plugins: Array<{ name: string; seams: string[] }>
  workers: {
    count: number
    source: 'workspace' | 'cgroup' | 'cores'
    cores: number
    cpuQuota: number | null
  }
  memory: { usableBytes: number; totalBytes: number; cgroupLimitBytes: number | null }
  cacheDir: string
  cacheStore: string | null
  cacheVersion: string
  schemaVersion: string
  cacheEntries: number
  cacheBytes: number
  cacheRetention: { olderThan?: string; maxSize?: string; maxBytes?: number } | null
  orphans: { artifacts: number; bytes: number }
  runs24h: number
  hits24h: number
  restored24h: number
  flakyTasks: FlakyTask[]
  lockfile: boolean
  sandbox: { available: boolean; reason: string; declared: number; untraced: string | null }
}
```

## `InvocationRecord`

type · `src/cache/layer.ts`

One header row per `vx run` invocation (the `invocations` table). All
fields mirror the columns; nullable VCS/host columns are `null` when
the probe failed (not a git repo, hostname unavailable). Recorded
once per run inside the same transaction as the per-task `runs` rows.

```ts
export interface InvocationRecord {
  runId: string
  command: string
  requestedTasks: string
  cachePolicy: string
  concurrency: number
  flow: 'focused' | 'broad' | null
  startedAt: number
  endedAt: number
  totalDurationMs: number
  taskCount: number
  failedCount: number
  hitCount: number
  hitLocalCount: number
  hitRemoteCount: number
  upToDateCount: number
  restoredLocalCount: number
  restoredRemoteCount: number
  exitOk: boolean
  commitSha: string | null
  branch: string | null
  dirty: boolean | null
  ci: boolean
  ciProvider: string | null
  host: string | null
  os: string | null
  arch: string | null
  vxVersion: string
  tags: string
}
```

## `isCacheHit`

function · `src/orchestrator/telemetry.ts`

Did the task's result come out of the cache (either layer)? Derived from
`deriveCacheSource` rather than re-listing the two hit statuses, so the two
cannot disagree about what a hit is. Unknown strings read as not-a-hit.

```ts
export function isCacheHit(status: string): boolean
```

## `isLiteralPattern`

function · `src/util/paths.ts`

True when a pattern carries no wildcard — it names exactly one path.

The character SET is the whole content: in a task glob `*`, `?` and a
brace alternation are wildcards, so a pattern holding any of them must
be MATCHED, never compared as a string. It lives here, exported, because
four places asked the same question and one of them asked it with a
smaller set: `graph/task-graph.ts` omitted `{}`, so `dist/{a,b}.txt`
counted as a literal and the overlapping-output refusal compared it to
`dist/a.txt` as two unequal strings — the two tasks were accepted and
then deleted each other's outputs, green, every run (item 495). That is
the same divergence `asTrees` was moved here to end in item 442, and the
same one that removed `@vzn/vx-migrate`'s copy of `outputsOverlap` in
item 445.

```ts
export function isLiteralPattern(glob: string): boolean
```

## `isPassStatus`

function · `src/orchestrator/telemetry.ts`

Did the task pass? A cache hit counts — it produced the same result without
spending the time, which is the whole point. `skipped` and `aborted` do NOT:
neither finished on its own terms, so neither can vouch for anything.

Takes `string`, not `TaskStatus`, because most callers hold a status that
arrived over a wire or out of a database column. An unrecognised string
reads as NOT passing — the safe direction, since the alternative is calling
a run green on a status this build has never heard of.

```ts
export function isPassStatus(status: string): boolean
```

## `isUserError`

function · `src/util/errors.ts`

`instanceof UserError`, plus the same class arriving from ANOTHER COPY of
core. A compiled `vx` binary carries core inside it while a plugin in the
workspace imports `@vzn/vx` from node_modules, so a plugin's `UserError`
is a different class object and `instanceof` is false — a plugin verb's
"bad flag --x" printed as `UserError: bad flag --x` with a stack, and a
REAPI refusal would have read as an "internal error" (reproduced through
the real binary, 2026-09-03). The name is the contract that survives the
copy boundary.

```ts
export function isUserError(err: unknown): err is UserError
```

## `KeyHookContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface KeyHookContext extends BaseContext {}
```

## `latestRunId`

function · `src/orchestrator/metrics.ts`

The latest recorded run of a task (run_id may be NULL on very old rows).
One query for `vx why` and `vx mcp`: the CLI defaulted to it while the
tool demanded a run id an agent had to fetch first (2026-09-16).

```ts
export function latestRunId(db: Database, taskId: string): string | null
```

## `LayeredCache`

class · `src/cache/layered-cache.ts`

```ts
export class LayeredCache implements CacheLayer {
  readonly hasRemote
  constructor(
    readonly local: Cache,
    private readonly remote: RemoteCacheLayer,
    private readonly options: LayeredCacheOptions = {},
  )
  key(input: CacheKeyInput): Promise<string>
  async prefetch(hash: string, ctx?: CacheGetContext): Promise<boolean>
  async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null>
  markRemoteAbsent(hashes: Iterable<string>): void
  async get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null>
  async has(hash: string): Promise<'local' | 'remote' | null>
  outputsPath(hash: string): string
  artifactSize(hash: string): number | undefined
  hashFile(filePath: string): Promise<string>
  async restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void>
  async save(args: SaveArgs): Promise<void>
  async drainUploads(): Promise<void>
  async ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void>
  loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]>
  async isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean>
  recordOutputDirs(
    hash: string,
    projectDir: string,
    prefixes: readonly string[],
    holds?: (files: readonly string[]) => boolean,
  ): Promise<void>
  recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void
  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]>
  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean>
  recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void
  stats(opts?: CacheStatsOptions): CacheStats
  prune(options: PruneOptions): Promise<PruneResult>
  close(): void
}
```

## `listProjectMetas`

function · `src/workspace/workspace.ts`

```ts
export async function listProjects(workspace: Workspace): Promise<ProjectMeta[]>
```

## `loadProjectConfig`

function · `src/workspace/project-loader.ts`

```ts
export async function loadProjectConfig(
  configPath: string,
  opts?: LoadProjectConfigOptions,
): Promise<ProjectConfig>
```

## `loadResolvedProjects`

function · `src/orchestrator/projects.ts`

The run path's view of a workspace's projects for a reader — `vx show`,
the MCP server, an embedder: discovery, the plugin `config` and
`project` stages, and the local cache opened only to serve cached
evaluations, so a pure config costs a stat, not an evaluation. `scope`
is every project or a list of names; no closure, no lock (a reader
reads live, as a default run does). Plugin warnings go to `warn`.

```ts
export async function loadResolvedProjects(
  workspaceRoot: string,
  opts: { scope?: 'all' | readonly string[]; warn?: (message: string) => void } = {},
): Promise<Map<string, ProjectEntry>>
```

## `loadWorkspace`

function · `src/workspace/workspace.ts`

Read the workspace's package-glob list, supporting all common
package managers:
  - `pnpm-workspace.yaml` (pnpm)
  - `package.json` `workspaces` array (npm / yarn / bun)
  - `package.json` `workspaces.packages` array (yarn legacy)

If a `package.json` exists with no `workspaces` field, the root
itself is treated as a single-project workspace.

```ts
export async function loadWorkspace(root: string, reads?: LoadReads): Promise<Workspace>
```

## `LocalHistoryProvider`

class · `src/orchestrator/history.ts`

Reads from the orchestrator's local SQLite cache.db.

```ts
export class LocalHistoryProvider implements HistoryProvider {
  constructor(
    private readonly db: Database,
    private readonly recent: number = DEFAULT_RECENT,
  ) {}
  async loadFor(taskIds: readonly string[]): Promise<HistoryTable>
  async p50sFor(taskIds: readonly string[]): Promise<ReadonlyMap<string, number>>
}
```

## `lockfileClaim`

function · `src/orchestrator/lockfile-claim.ts`

```ts
export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
```

## `LockfileClaimHooks`

type · `src/orchestrator/lockfile-claim.ts`

The two hooks a lockfile plugin spreads into `definePlugin`.

```ts
export interface LockfileClaimHooks {
  readonly fingerprint: FingerprintClaim
  key(task: TaskNode, ctx: KeyHookContext): Promise<Readonly<Record<string, string>> | undefined>
}
```

## `LockfileClaimOptions`

type · `src/orchestrator/lockfile-claim.ts`

```ts
export interface LockfileClaimOptions {
  readonly file: string
  readonly digest: (text: string, files: ReadonlyMap<string, string>) => ReadonlyMap<string, string>
  readonly extraFiles?: (text: string) => readonly string[]
  readonly version: number
  readonly scope?: 'project' | 'workspace'
  readonly part?: string
}
```

## `LOG_WIRE_VERSION`

const · `src/orchestrator/task-log-buffer.ts`

Version of the drained-bundle shape below. It is the canonical drained
 logs format, not one transport's: every sink ships the same object.

```ts
export const LOG_WIRE_VERSION = 1
```

## `Logger`

type · `src/orchestrator/logger.ts`

```ts
export interface Logger {
  status(line: string): void
  taskStdout(node: TaskNode, chunk: string): void
  taskStderr(node: TaskNode, chunk: string): void
  taskComplete(node: TaskNode, outcome: TaskOutcome): void
  runStart?(info: {
    total: number
    concurrency?: number
    requestedCount?: number
    context?: RunContext
    startedAtMs?: number
  }): void
  taskStart?(node: TaskNode): void
  runEnd?(): void
}
```

## `machineMemoryBytes`

function · `src/util/cgroup.ts`

The machine's total memory, capped by its cgroup limit.

```ts
export function machineMemoryBytes(probe: CgroupProbe = {}): number
```

## `machineParallelism`

function · `src/util/cgroup.ts`

The cores this process may run on, capped by its cgroup CPU quota,
rounded up (a 1.5-core quota is two workers, not one) and never below
one. The default worker count.

```ts
export function machineParallelism(probe: CgroupProbe = {}): number
```

## `maskedCommand`

function · `src/util/secret-mask.ts`

A task's command as vx shows it: its secret values masked.

```ts
export function maskedCommand(command: string, env?: TaskEnvSecrets): string
```

## `maskedLine`

function · `src/util/secret-mask.ts`

A line vx prints for no one task (a plugin's warning): this process's secrets masked.

```ts
export function maskedLine(line: string): string
```

## `MigrationFormat`

type · `src/workspace/migration.ts`

```ts
export type MigrationFormat = 'ts' | 'mjs'
```

## `MigrationPlan`

type · `src/workspace/migration.ts`

```ts
export interface MigrationPlan {
  headerNotes: string[]
  projects: GeneratedProject[]
  extraFiles: { relPath: string; contents: string }[]
  notes: string[]
}
```

## `NamedProject`

type · `src/orchestrator/plugin.ts`

```ts
export interface NamedProject {
  readonly dir: string
  readonly name: string
}
```

## `normalizeGlob`

function · `src/util/paths.ts`

The spellings a reader, Turbo and `.gitignore` all accept but a matcher
fed the raw string turns into NOTHING — and a task keyed on nothing
replays old outputs as a green hit (2026-09-10, probed one by one):
a leading `./`, an inner `/./` segment, a doubled `//`, and a trailing
`/` on a pattern (`src/*\/` means the trees under `src`, so it becomes
`src/*\/**`; a trailing slash on a LITERAL is `asTrees`' job). Applied
after an optional `!`; a bare `.` is the empty entry the schema refuses.

```ts
export function normalizeGlob(glob: string): string
```

## `OutcomeView`

type · `src/orchestrator/events.ts`

Serializable projection of a TaskOutcome (no node ref, ns as strings).

```ts
export interface OutcomeView {
  taskId: string
  status: TaskOutcome['status']
  exitCode: number
  durationMs: number
  isGroup?: boolean
  noCache?: boolean
  storedDurationMs?: number
  storedCpuMs?: number
  storedPeakRssBytes?: number
  hash?: string
  cpuMs?: number
  peakRssBytes?: number
  timedOut?: true
  notReady?: 'timeout' | 'exited' | 'spawn'
  blockedBy?: string
  admissionHeldMs?: number
  queuedMs?: number
  inputFiles?: number
  inputChanges?: InputChanges
  artifactBytes?: number
  fetchMs?: number
  saveMs?: number
  restored?: boolean
  sandboxViolations?: number
  sandboxViolationLines?: string[]
  wallclockStartNs?: string
  wallclockEndNs?: string
}
```

## `OutputLocation`

type · `src/orchestrator/path-links.ts`

A file a task's output names; `file` absolute.

```ts
export interface OutputLocation {
  file: string
  line?: number
  col?: number
}
```

## `outputsOverlap`

function · `src/graph/task-graph.ts`

True only when two output globs PROVABLY select an overlapping set.

Deliberately conservative, because the caller REFUSES the run: a false
positive breaks a build that works today, which is worse than the defect
being caught. So the three cases are exactly the ones that can be decided
without a general glob-intersection algorithm:

  both literal    — equal paths
  literal vs glob — ask the glob whether it matches the literal (exact)
  both globs      — identical strings, or one a whole subtree `P/**`
                    and the other's literal prefix P or under it: every
                    path the second matches is under P, so the first
                    covers it (item 941). Anything else is undecided
                    here and deliberately allowed through

The rejected alternative was comparing each glob's static prefix. It is
cheaper and catches more, but it is UNSOUND for a refusal — measured:
`dist/vx-*` and `dist/other.txt` share the prefix `dist` while matching
disjoint sets, so a prefix check refuses a legitimate config. (vx's own
`build.bun.*` tasks escape only because they declare distinct literals.)

All three cases compare SPELLINGS, so each side is run through
`asTrees` first — the same rule the resolver and `cleanOutputs` read,
and `cleanOutputs` is what actually does the deleting. That folds two
things this check used to miss, both of them the data loss it exists to
prevent:

  - the SPELLING: `./dist/**` and `dist/**` are one tree to every
    matcher in vx, and `Bun.Glob('dist/**')` does not match the literal
    `./dist/app.js` either (item 441, probed one spelling at a time);
  - the literal DIRECTORY: `outputs: ['dist']` means everything under
    `dist` — `asTrees` compiles it to `dist` + `dist/**` — while this
    compared it to `dist/app.js` as two unequal literals. Measured end
    to end: the task declaring `dist` wiped the other's `dist/app.js`
    and the run reported success (item 442).

Neither is a widening. Both read the declaration the way the code that
deletes reads it, which is the only reading that decides the hazard.

Exported through the façade because `@vzn/vx-migrate` asks the same
question at MIGRATION time — it uncaches the losers so the generated
config loads — and it used to ask it with a copy of this function. The
copy did not get items 441 and 442, so it reported clean on configs
core then refused, including `outputs: ['dist']` against
`dist/app.js`, which is the commonest turbo.json shape there is (item
445). One rule, one place: the copy is gone.

```ts
export function outputsOverlap(rawA: string, rawB: string): boolean
```

## `OutputView`

type · `src/orchestrator/logger.ts`

The default logger's per-task output policy. Resolved once per run
from (in priority order) the explicit `--output-logs` override, a
truthy `CI` env, and the CLI-detected flow:

  full        — frames for executed work, one-liners for quiet hits.
                Today's CI behavior; also the programmatic default.
  errors-only — only failed tasks print.
  none        — no per-task output at all.
  hash-only   — one line per task: outcome word, task id, cache key.
                No frames, no log replay (Turbo `--output-logs
                hash-only` parity); the end-of-run summary still
                renders. The line is the run's audit trail: which key
                each task resolved to, without any build output.
  focused     — requested nodes stream raw output live (running the
                task should feel like running the command directly);
                dependency-pulled nodes are silent unless they fail.
  broad       — news only: one `success` line per executed task,
                full frames for failures, silence for cache hits.

`gha` (on GitHub Actions, any mode): task output is fenced from
workflow commands. In full mode each task's block is also wrapped in
`::group::` / `::endgroup::` so tasks collapse in the log viewer —
except failed tasks, which stay pre-expanded and emit an `::error`
annotation instead.

`ci`: a truthy CI env was detected. Suppresses the dynamic status
line even if stdout happens to be a TTY.

```ts
export interface OutputView {
  mode: 'full' | 'errors-only' | 'none' | 'focused' | 'broad' | 'hash-only'
  gha?: boolean
  ci?: boolean
}
```

## `PERSISTENT_TODO`

const · `src/workspace/migration.ts`

The one wording every mapper emits for a task it made persistent.

```ts
export const PERSISTENT_TODO =
  'persistent task — set persistent.readyWhen (regex matched against output) so ' +
  'dependents unblock on readiness, and consider exec.timeout to bound the wait'
```

## `PlannedTask`

type · `src/orchestrator/plan.ts`

```ts
export interface PlannedTask {
  node: TaskNode
  hash: string
  cacheStatus: CacheStatus
  deps: readonly string[]
  p50Ms?: number
  executor?: string
  download?: 'deferred'
  affected?: AffectedReason
}
```

## `planRun`

function · `src/orchestrator/run.ts`

Planning mode. Same setup as `run()` — workspace discovery, config
load, package graph, task graph — but stops short of execution.
Returns a `RunPlan` predicting the cache hit/miss outcome of every
task. Used by `--dry-run` and `--graph`.

Side-effects are limited to opening + closing the local Cache handle
(and running `cache.inputs.runtime` probe commands, which key
derivation requires). Cache probing is the byte-free `cache.has()`
existence check — no artifact download, no ingest, no accessed_at bump.

```ts
export async function planRun(options: RunOptions): Promise<RunPlan>
```

## `PLUGIN_HOOKS`

const · `src/config.ts`

Every hook a plugin may fill, in pipeline order — THE list. The loader's
"must be a function" and "at least one of" checks, the host's stage gate
and `vx info`'s seam column all read it, so a stage added here is a stage
everywhere: `admit` reached `vx info` a day late (2026-09-12) because
that column kept its own copy, and the loader kept a third. The type
pin below refuses a list that drifts from `Plugin`'s keys either way.

```ts
export const PLUGIN_HOOKS = [
  'config',
  'discover',
  'project',
  'graph',
  'key',
  'fingerprint',
  'schedule',
  'admit',
  'executor',
  'cache',
  'telemetry',
  'setup',
  'commands',
  'teardown',
] as const
```

## `PluginCommand`

type · `src/orchestrator/plugin.ts`

One CLI verb contributed by a plugin.

```ts
export interface PluginCommand {
  readonly description: string
  run(argv: readonly string[], ctx: CommandContext): number | Promise<number>
}
```

## `PluginHook`

type · `src/config.ts`

```ts
export type PluginHook = (typeof PLUGIN_HOOKS)[number]
```

## `PluginHookHandlers`

type · `src/orchestrator/plugin.ts`

```ts
export interface PluginHookHandlers {
  onRunStart: (info: RunStartInfo) => void | Promise<void>
  onTaskStart: (node: TaskNode) => void | Promise<void>
  onTaskStdout: (node: TaskNode, chunk: string) => void | Promise<void>
  onTaskStderr: (node: TaskNode, chunk: string) => void | Promise<void>
  onTaskComplete: (node: TaskNode, outcome: TaskOutcome) => void | Promise<void>
  onRunStatus: (line: string) => void | Promise<void>
  onRunEnd: () => void | Promise<void>
}
```

## `PluginHookName`

type · `src/orchestrator/plugin.ts`

```ts
export type PluginHookName =
  | 'onRunStart'
  | 'onTaskStart'
  | 'onTaskStdout'
  | 'onTaskStderr'
  | 'onTaskComplete'
  | 'onRunStatus'
  | 'onRunEnd'
```

## `PluginHooks`

type · `src/orchestrator/plugin.ts`

What a plugin author writes: every hook, and no name.

```ts
export type PluginHooks = Omit<VxPlugin, 'name'>
```

## `PluginOptionKinds`

type · `src/orchestrator/plugin.ts`

Every option a factory takes, each with the one kind its type allows
(`'any'` for a union of kinds, such as `false | { … }`). Derived from
the options interface, so the type checker refuses a missing option, an
extra one or a wrong kind.

```ts
export type PluginOptionKinds<T> = {
  readonly [K in keyof Required<T>]-?: OptionKind<Required<T>[K]>
}
```

## `PluginOrigin`

type · `src/orchestrator/plugin.ts`

Where a plugin is defined — `import.meta` of its module. `dir` is Bun's
field; `url` is the standard one, for a module evaluated elsewhere.

```ts
export interface PluginOrigin {
  readonly dir?: string
  readonly url?: string
}
```

## `PluginSetupContext`

type · `src/orchestrator/plugin.ts`

What `setup` receives: the run's lifecycle, observe-only.

```ts
export interface PluginSetupContext extends BaseContext {
  on<K extends PluginHookName>(hook: K, handler: PluginHookHandlers[K]): void
}
```

## `PreparedRun`

type · `src/orchestrator/prepare.ts`

```ts
export interface PreparedRun {
  workspaceRoot: string
  workspaceConfig: WorkspaceConfig | null
  plugins: readonly VxPlugin[]
  cacheDir: string
  cache: CacheLayer
  localCache: Cache
  hasRemoteLayer: boolean
  cachePolicy: CachePolicy
  priorities: ReadonlyMap<string, number>
  nodes: Map<string, TaskNode>
  keyOnly: ReadonlyMap<string, TaskNode>
  unresolvedTasks: readonly string[]
  declaredElsewhere: readonly string[]
  projects: ReadonlyMap<string, ProjectEntry>
  hintProjects: ReadonlyMap<string, ProjectEntry>
  anyProjectConfig: boolean
  workspaceFingerprint: string
  fingerprintWatch: FingerprintWatch
  nestedDirsByProject: Map<string, string[]>
  gitFilesCache: GitFilesCache
  workspaceProjectCount: number
  hashCache: HashCache
  empty: null | 'no-tasks-declared' | 'none-affected' | 'empty-graph'
}
```

## `prepareRun`

function · `src/orchestrator/prepare.ts`

Build the prepared-run context: workspace discovery, project-config
load, package + task graph, cache handle (local, optionally wrapped
in a remote layer). Caller owns `cache.close()`.

Returns even when nothing can run — the `empty` field tells the
caller why. We never throw on "no tasks"; behavior on that case is
caller-specific (run logs + returns NOT-ok; planRun returns an
empty plan).

```ts
export async function prepareRun(options: RunOptions, log: Logger): Promise<PreparedRun>
```

## `ProjectConfig`

type · `src/config.ts`

```ts
export interface ProjectConfig {
  tags?: readonly string[]
  tasks?: Record<string, TaskConfig>
}
```

## `ProjectEntry`

type · `src/workspace/workspace.ts`

A discovered project joined with its loaded vx config.

```ts
export interface ProjectEntry {
  name: string
  dir: string
  config: ProjectConfig
}
```

## `ProjectHookContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface ProjectHookContext extends BaseContext {
  readonly name: string
  readonly dir: string
  readonly packageJson: Readonly<Record<string, unknown>>
  readonly projects: readonly ProjectMeta[]
}
```

## `ProjectMeta`

type · `src/workspace/workspace.ts`

```ts
export interface ProjectMeta {
  name: string
  dir: string
  packageJson: PackageJson
  configPath: string | null
  catalogs?: Catalogs
}
```

## `pruneOrphanPersistentNotes`

function · `src/workspace/migration.ts`

Strips the note from every persistent task no `dependsOn` in the mapping names.

```ts
export function pruneOrphanPersistentNotes(
  projects: readonly {
    readonly tasks: readonly {
      readonly name: string
      readonly todos: string[]
      readonly task: Record<string, unknown> | null
    }[]
  }[],
  note: string,
): void
```

## `quoteTsLiteral`

function · `src/workspace/migration.ts`

Escape an arbitrary string into a single-quoted TS literal. Escapes
backslash + quote AND raw newlines/CR — a value with an embedded newline
(legal JSON, e.g. a script `"echo a\necho b"`, or a glob with a `'`) would
otherwise splice into a single-quoted literal as an unterminated / malformed
string that fails to load (generated files must round-trip through the
loader).

```ts
export function quoteTsLiteral(s: string): string
```

## `RawExpr`

type · `src/workspace/migration.ts`

Verbatim TS expression spliced into a generated array (preset spreads).

```ts
export interface RawExpr {
  readonly raw: string
}
```

## `reachDigests`

function · `src/orchestrator/lockfile-claim.ts`

One digest per node over everything the node reaches, Merkle-style: a
change anywhere in a node's reach moves its digest, a change elsewhere
does not. Lockfiles carry dependency cycles, so the unit is the
strongly connected component: Tarjan's walk (iterative — a dependency
chain can be thousands deep) emits components children-first, and each
folds its members (sorted), each as its material and the materials its
edges land on, and its child components' digests (sorted). O(nodes + edges): 1000 importers over 3000 packages digest in
~20 ms where one traversal per importer took 400.

```ts
export function reachDigests(g: ReachGraph): string[]
```

## `ReachGraph`

type · `src/orchestrator/lockfile-claim.ts`

A dependency graph: one material string per node and its out-edges by index.

```ts
export interface ReachGraph {
  readonly material: readonly string[]
  readonly edges: ReadonlyArray<readonly number[]>
}
```

## `refuseUnknownOptions`

function · `src/orchestrator/plugin.ts`

Refuse an option a plugin factory does not take, or a value of the wrong
kind, as core refuses an unknown config field. Bun strips a config's
types, so a misspelt option (`reapi({ endpont })`) reached the factory,
which read it as unset and quietly declined, and a string where a number
or a boolean belongs (`process.env.X`) was misread or threw a bare
TypeError. `factory` names the call in the message (`reapi()`).

```ts
export function refuseUnknownOptions<T>(
  factory: string,
  options: unknown,
  kinds: PluginOptionKinds<T>,
): void
```

## `RemoteCacheLayer`

type · `src/cache/layered-cache.ts`

What a remote cache layer must provide — THE plugin seam for remote
caching. Core ships no wire client; a plugin's `cache` capability (or an
embedder via `RunOptions.remoteCache`) supplies an implementation speaking
whatever protocol it wants, and `LayeredCache` owns everything else:
policy gating, in-flight dedup, remote provenance, and the never-fail
contract (implementations THROW on failure; LayeredCache degrades every
throw to a cache miss via `onRemoteError`). The artifact bytes are the
local `<hash>.tar.zst` verbatim. The wires live in plugin packages
(`@vzn/vx-migrate`'s `turboCache()` and `nxCache()`, `@vzn/vx-reapi`); see
docs/modules/layered-cache.md.

Core awaits every call and bounds none: a `get` that never settles
holds its task and a `put` the run's upload drain, so each request
carries the layer's own deadline (every first-party layer has one; the
plugin guide's example shows it).

```ts
export interface RemoteCacheLayer {
  readonly endpoint?: string
  has(hash: string): Promise<boolean>
  hasMany?(hashes: readonly string[]): Promise<Set<string> | null>
  get(hash: string): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
  put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void>
}
```

## `ResolvedSandboxConfig`

type · `src/exec/sandbox-runtime.ts`

Sandbox config with all path fields resolved to absolute paths.
Produced by `resolveSandboxConfig`. The shape mirrors `SandboxConfig`
but every string in a path list is guaranteed absolute.

```ts
export interface ResolvedSandboxConfig {
  allowRead: readonly string[]
  allowWrite: readonly string[]
  pendingWrites?: readonly string[]
  network?: true | readonly string[]
  denyNetwork?: readonly string[]
  systemInfo?: readonly string[]
  unixSockets?: true | readonly string[]
  localBinding?: boolean | readonly number[]
  machLookup?: readonly string[]
  pty?: boolean
  gitConfig?: boolean
  weakerWhenNested?: boolean
  weakerNetworkIsolation?: boolean
  wallsReached?: { read: readonly string[]; write: readonly string[] }
  ignore?: {
    read?: readonly string[]
    write?: readonly string[]
    systemInfo?: readonly string[]
    network?: readonly string[]
  }
}
```

## `resolveRunId`

function · `src/orchestrator/run-id.ts`

The recorded run `raw` names: itself when recorded, else the one run
whose id starts with it. Null when none does; a prefix several runs share
is refused with those runs, since picking one would replay the wrong run.

```ts
export function resolveRunId(db: Database, raw: string, verb: string): string | null
```

## `RootCause`

type · `src/orchestrator/metrics.ts`

```ts
export interface RootCause {
  chain: string[]
  entries: CacheKeyDiff['entries']
}
```

## `rootCauses`

function · `src/orchestrator/metrics.ts`

The tasks under `taskId`'s moved upstreams whose OWN key components
moved in the same run, each with the chain that carried it up. A task
visited once is not walked again (a diamond names its root once).

```ts
export function rootCauses(
  db: Database,
  runId: string,
  taskId: string,
  entries: CacheKeyDiff['entries'],
): RootCause[]
```

## `run`

function · `src/orchestrator/run.ts`

```ts
export async function run(options: RunOptions): Promise<RunSummary>
```

## `RunContextRecord`

type · `src/orchestrator/telemetry.ts`

Identifies which run a record belongs to + its captured context. Maps
 cleanly onto OTel CI/CD + VCS resource attributes.

```ts
export interface RunContextRecord {
  runId: string
  vxVersion: string
  command: string
  requestedTasks: readonly string[]
  cachePolicy: string
  concurrency: number
  flow: 'focused' | 'broad' | null
  workspaceId: string
  workspaceName: string
  repository?: string
  workspacePath?: string
  commitSha: string | null
  branch: string | null
  defaultBranch: string | null
  dirty: boolean | null
  ci: boolean
  ciProvider: string | null
  ciRunUrl?: string
  ciChange?: string
  ciPipeline?: string
  ciJob?: string
  ciAttempt?: number
  host: string | null
  os: string
  arch: string
  tags: Readonly<Record<string, string>>
}
```

## `runFailures`

function · `src/orchestrator/run-failures.ts`

The failed tasks of `runId`, or of the latest failed run when omitted;
null when there is no such run. A failed task the file lacks (an older
run, a write the disk refused) reads `output: ''`, `locations: []`.

```ts
export function runFailures(cacheDir: string, db: Database, runId?: string): RunFailures | null
```

## `RunFailures`

type · `src/orchestrator/run-failures.ts`

```ts
export interface RunFailures {
  runId: string
  tasks: TaskFailure[]
}
```

## `RunOptions`

type · `src/orchestrator/options.ts`

```ts
export interface RunOptions {
  cwd: string
  tasks: readonly string[]
  projects?: string[]
  selectedByDiff?: boolean
  affected?: AffectedChanges
  selectedOutright?: readonly string[]
  affectedReasons?: Map<string, AffectedReason>
  staged?: ReadonlyMap<string, ProjectEntry>
  discovered?: { root: string; projects: ProjectMeta[] }
  concurrency?: number
  cacheDir?: string
  cache?: CachePolicy
  remoteRequested?: boolean
  defaultCacheScope?: string
  frozen?: boolean
  outputLogs?: 'full' | 'errors-only' | 'none' | 'hash-only'
  download?: 'all' | 'toplevel' | 'none'
  flow?: 'focused' | 'broad'
  retries?: number
  timeout?: number
  continueMode?: ContinueMode
  excludeDependencies?: 'all' | readonly string[]
  forwardArgs?: readonly string[]
  summarize?: string
  json?: boolean
  beforeFooter?: (outcomes: readonly TaskOutcome[], ok: boolean) => string
  profile?: string
  handleSignals?: boolean
  signal?: AbortSignal
  holdPersistent?: boolean
  keep?: HeldPersistent
  summaryTable?: boolean
  tty?: boolean
  log?: Logger
  bus?: EventBus
  inflight?: Map<string, Promise<void>>
  tags?: Record<string, string>
  telemetrySinks?: readonly TelemetrySink[]
  command?: string
  remoteCache?: RemoteCacheLayer
  artifactCeiling?: number
}
```

## `RunPlan`

type · `src/orchestrator/plan.ts`

```ts
export interface RunPlan {
  tasks: PlannedTask[]
  predicted?: PlanPrediction
  unresolvedTasks?: readonly string[]
  unresolvedHint?: string
  noneAffected?: string
  downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
}
```

## `RunRecord`

type · `src/cache/layer.ts`

```ts
export interface RunRecord {
  hash?: string
  project: string
  task: string
  status: 'success' | 'failed' | 'cache-hit' | 'cache-hit-remote' | 'skipped'
  exitCode: number
  durationMs: number
  forwardArgs?: readonly string[]
  startedAt: number
  endedAt: number
  runId?: string
  cpuMs?: number
  peakRssBytes?: number
  wallclockStartNs?: bigint
  wallclockEndNs?: bigint
  cacheHit?: boolean
  restored?: boolean
  attempts?: number
  cached?: boolean
  blockedBy?: string
  timedOut?: true
  sandboxViolations?: number
  notReady?: 'timeout' | 'exited' | 'spawn'
}
```

## `RunResult`

type · `src/orchestrator/run-report.ts`

One finished run, reduced to what a report needs. Used to live in
`protocol.ts` as the return type of the whole-run `backend` seam; that
seam is gone (a run always executes in-process — see
`docs/modules/executor.md`), so the shape lives with its only consumer.

```ts
export interface RunResult {
  ok: boolean
  outcomes: OutcomeView[]
}
```

## `RunStartInfo`

type · `src/orchestrator/events.ts`

Payload of the `run:start` event — mirrors the Logger.runStart hook.

```ts
export interface RunStartInfo {
  total: number
  concurrency?: number
  requestedCount?: number
  context?: RunContext
  startedAtMs?: number
}
```

## `RunSummary`

type · `src/orchestrator/options.ts`

```ts
export interface RunSummary {
  ok: boolean
  outcomes: TaskOutcome[]
  persistent?: HeldPersistent
  refused?: string
  json?: RunSummaryJson
}
```

## `RunSummaryRecord`

type · `src/orchestrator/telemetry.ts`

A per-run SUMMARY record — the denormalized invocation header plus the
per-task outcome list, emitted once at run:end. An ingesting store can
persist a whole run in one write without replaying the stream. The
manual-API exporter + a service's ingest endpoint primarily speak this shape.

```ts
export interface RunSummaryRecord {
  v: number
  run: RunContextRecord
  startedAt: number
  endedAt: number
  totalDurationMs: number
  taskCount: number
  failedCount: number
  abortedCount: number
  hitCount: number
  hitLocalCount: number
  hitRemoteCount: number
  upToDateCount: number
  restoredLocalCount: number
  restoredRemoteCount: number
  exitOk: boolean
  tasks: readonly TaskTelemetry[]
  stages?: readonly RunStage[]
  uploads?: { count: number; bytes: number; ms: number; failed: number }
}
```

## `SandboxConfig`

type · `src/config.ts`

What a sandboxed task may do, declared as CAPABILITIES.

One shape for the whole policy. You say what the task is allowed to
touch; vx decides how each capability is realised — some become sandbox
runtime config, some become rules in the OS policy, and one the platform
cannot express is an error rather than a silent no-op. None of that
reaches the config.

The baseline (`sandbox: {}`) grants almost nothing: the task reads
nothing, writes nothing and reaches no network — NOT EVEN ITS OWN
PROJECT DIRECTORY, which is why `allow: { read: ['.'] }` opens almost
every real block. The one grant vx makes for you is dependencies:
`node_modules`, and through it the real path of every workspace
package linked there.

`cache` grants no access in either direction: `cache.inputs` says what
INVALIDATES a task, `allow` says what it may TOUCH, and deriving one
from the other coupled them both ways — a declaration added for
caching silently widened the sandbox, and a path the task needed had
to be laundered through the cache key to get it (owner, 2026-09-05).
A declared `cache.outputs` is NOT a write grant; the request
`sandbox-request.ts` builds carries no write of its own and binds
`allow.write` alone. This comment claimed the opposite — here and on
both grant fields — while the file beside it and `schema.md` both said
the truth, and no test read the bare baseline it described (item 443).
That case has a test of its own now.

Enforcement anchors at the WORKSPACE ROOT, so a task cannot leave its
project whatever it declares here. The full account, including what a
write grant costs on Linux, is in `docs/schema.md` under
`exec.sandbox`.

Paths are project-relative, absolute, or `~`-expanded, and may be
globs: macOS matches the pattern in the policy, Linux expands it when
the task starts (a mount cannot hold a pattern), so a file created
later is not covered there — grant its directory.

```ts
export interface SandboxConfig {
  allow?: SandboxGrants
  deny?: SandboxDenials
  ignore?: SandboxIgnore
  weakerWhenNested?: boolean
  weakerNetworkIsolation?: boolean
}
```

## `SandboxDenials`

type · `src/config.ts`

```ts
export interface SandboxDenials {
  network?: readonly string[]
}
```

## `SandboxGrants`

type · `src/config.ts`

```ts
export interface SandboxGrants {
  read?: readonly string[]
  write?: readonly string[]
  network?: true | readonly string[]
  systemInfo?: readonly string[]
  unixSockets?: true | readonly string[]
  localBinding?: boolean | readonly number[]
  machLookup?: readonly string[]
  pty?: boolean
  gitConfig?: boolean
}
```

## `ScheduleHookContext`

type · `src/orchestrator/plugin.ts`

```ts
export interface ScheduleHookContext extends BaseContext {
  readonly localCache: Cache
}
```

## `splitTaskId`

function · `src/util/task-id.ts`

The inverse of `taskId` (`graph/task-graph.ts`). Splits on the FIRST
`#`, so a task name that itself contains one round-trips: `taskId('a', 'b#c')` → `'a#b#c'` → `['a', 'b#c']`.

This exists because it kept being written by hand as `id.split('#', 2)`,
which is NOT the inverse — it discards everything after the second segment,
so `'a#b#c'` reads back as task `'b'`. Six call sites had that form while
`parseDependencySpec` (the surface that decides what actually runs) has
always split on the first `#`, so the query layer and the graph disagreed
about the identity of the same task: a lookup either found nothing or, worse,
answered with a different task's history.

A config's task name may not hold `#` (`taskNameProblem`), but an id also
arrives from run history and plugins, so the first-`#` rule is the one
the graph uses. The cache's run history read the same rule from a
private copy until item 646; one rule, one place.

```ts
export function splitTaskId(id: string): [project: string, task: string]
```

## `TaskConfig`

type · `src/config.ts`

```ts
export interface TaskConfig {
  description?: string
  exec?: ExecConfig
  dependsOn?: readonly string[]
  cache?: CacheConfig
}
```

## `TaskExecutor`

type · `src/exec/executor.ts`

```ts
export interface TaskExecutor {
  readonly name: string
  readonly remote?: boolean
  readonly capacity?: number
  accepts?(task: TaskPlacement): boolean
  demand?(remaining: ReadonlySet<string>): void
  execute(req: ExecuteRequest): Promise<ExecuteResult>
}
```

## `TaskFailure`

type · `src/orchestrator/run-failures.ts`

A failed task of a run and what it said.

```ts
export interface TaskFailure {
  taskId: string
  exitCode: number
  timedOut?: true
  output: string
  locations: OutputLocation[]
}
```

## `TaskHistory`

type · `src/orchestrator/history.ts`

Per (project#task) — last RECENT runs collapsed into a summary.

```ts
export interface TaskHistory {
  runs: number
  p50DurationMs: number | undefined
  p99DurationMs: number | undefined
  successRate: number
  hitRate: number
  failureMode: FailureMode
  maxPeakRssBytes?: number
  maxCpuParallelism?: number
}
```

## `taskLog`

function · `src/orchestrator/run-failures.ts`

`taskId`'s output in `runId`, or in the latest run that recorded the
task when omitted; null when no such run recorded it.

```ts
export function taskLog(
  cacheDir: string,
  db: Database,
  taskId: string,
  runId?: string,
): TaskLog | null
```

## `TaskLog`

type · `src/orchestrator/run-failures.ts`

One task's output in a recorded run, as `vx last --log` and getTaskLog read it.

```ts
export interface TaskLog {
  runId: string
  taskId: string
  status: string
  source: 'failure' | 'cache' | null
  output: string
}
```

## `TaskLogBuffer`

class · `src/orchestrator/task-log-buffer.ts`

Bounded per-run capture. `append` keeps a chunk LIST + running char count per
task, evicting whole chunks from the head past `TASK_LOG_TAIL_CHARS` — no
string concatenation until `drain`, so a cache-hit replay (one big chunk) is
one array push, zero copies. `finish` decides retention; `drain` emits the
bundle, failures first.

```ts
export class TaskLogBuffer {
  append(taskId: string, chunk: string): void
  finish(taskId: string, status: TaskStatus, cacheSource: CacheSource, hash?: string): void
  takeEntry(taskId: string): TaskLogEntry | undefined
  drain(runId: string, workspaceId: string): TaskLogBundle
  size(): number
  budgetUsed(): number
}
```

## `TaskLogBundle`

type · `src/orchestrator/task-log-buffer.ts`

```ts
export interface TaskLogBundle {
  v: typeof LOG_WIRE_VERSION
  runId: string
  workspaceId: string
  tasks: TaskLogEntry[]
}
```

## `TaskLogEntry`

type · `src/orchestrator/task-log-buffer.ts`

```ts
export interface TaskLogEntry {
  taskId: string
  hash?: string
  status: 'success' | 'failed'
  content: string
  charsFull: number
  truncatedHeadChars: number
}
```

## `TaskNode`

type · `src/graph/task-graph.ts`

```ts
export interface TaskNode {
  id: string
  projectName: string
  projectDir: string
  taskName: string
  config: TaskConfig
  deps: string[]
  orderOnly?: string[]
  requested: boolean
  surfaced?: boolean
  keyParts?: ReadonlyArray<readonly [name: string, value: string]>
  addsToOutputsOf?: string[]
  outputsAddedToBy?: string[]
  excludedUpstream?: TaskOutcome[]
}
```

## `TaskOutcome`

type · `src/graph/scheduler.ts`

```ts
export interface TaskOutcome {
  node: TaskNode
  status: TaskStatus
  exitCode: number
  durationMs: number
  hash?: string
  storedDurationMs?: number
  storedCpuMs?: number
  storedPeakRssBytes?: number
  admissionHeldMs?: number
  queuedMs?: number
  inputFiles?: number
  artifactBytes?: number
  fetchMs?: number
  saveMs?: number
  inputChanges?: InputChanges
  cpuMs?: number
  peakRssBytes?: number
  groupUpstream?: readonly TaskOutcome[]
  unkeyed?: true
  cacheOff?: true
  blockedBy?: string
  timedOut?: true
  failedOutput?: string
  notReady?: 'timeout' | 'exited' | 'spawn'
  where?: string
  outputs?: 'deferred'
  wallclockStartNs?: bigint
  wallclockEndNs?: bigint
  restored?: boolean
  attempts?: number
  failedAttempts?: readonly { endedAt: number; exitCode: number; timedOut?: true }[]
  flaky?: { passes: number; failures: number }
  sandboxViolations?: number
  sandboxViolationLines?: string[]
}
```

## `TaskPlacement`

type · `src/exec/executor.ts`

What an executor sees when a task is PLACED — once per task, before scheduling.

```ts
export interface TaskPlacement {
  readonly taskId: string
  readonly projectName: string
  readonly projectDir: string
  readonly command: string
  readonly pinnedLocal: boolean
  readonly cacheable: boolean
}
```

## `TaskStatus`

type · `src/graph/scheduler.ts`

```ts
export type TaskStatus =
  | 'success'
  | 'cache-hit'
  | 'cache-hit-remote'
  | 'failed'
  | 'skipped'
  | 'aborted'
```

## `TaskTelemetry`

type · `src/orchestrator/telemetry.ts`

Denormalized per-task analytics — shared by the streaming `task.end`
 record and the per-run summary's `tasks[]`.

```ts
export interface TaskTelemetry {
  taskId: string
  project: string
  task: string
  status: TaskStatus
  cacheSource: CacheSource
  exitCode: number
  durationMs: number
  hash?: string
  cpuMs?: number
  peakRssBytes?: number
  where?: string
  outputs?: 'deferred'
  attempts?: number
  blockedBy?: string
  timedOut?: true
  sandboxViolations?: number
  notReady?: 'timeout' | 'exited' | 'spawn'
  failedAttempts?: readonly FailedAttempt[]
  flaky?: { passes: number; failures: number }
  sandboxViolationLines?: readonly string[]
  storedDurationMs?: number
  storedCpuMs?: number
  storedPeakRssBytes?: number
  admissionHeldMs?: number
  queuedMs?: number
  inputFiles?: number
  inputChanges?: InputChanges
  artifactBytes?: number
  fetchMs?: number
  saveMs?: number
  restored?: boolean
  wallclockStartNs?: string
  wallclockEndNs?: string
}
```

## `TaskView`

type · `src/orchestrator/events.ts`

Display projection of a TaskNode — exactly the fields renderers read.

```ts
export interface TaskView {
  id: string
  project: string
  task: string
  isGroup: boolean
  requested: boolean
  surfaced: boolean
  persistent: boolean
  command?: string
}
```

## `TELEMETRY_SCHEMA_VERSION`

const · `src/orchestrator/telemetry.ts`

Bumped when the record shape changes. Readers MUST check `v`.

```ts
export const TELEMETRY_SCHEMA_VERSION = 3
```

## `TelemetryContext`

type · `src/orchestrator/telemetry.ts`

Read-only context a sink is created with. No mutable run handle — the
 isolation guarantee is structural.

```ts
export interface TelemetryContext {
  readonly workspaceRoot: string
  readonly cacheDir: string
  warn(message: string): void
}
```

## `TelemetryRecord`

type · `src/orchestrator/telemetry.ts`

A streaming telemetry record — one per lifecycle event. A superset of the
rendering-oriented `WireEvent`: it carries the run context + the per-task
analytics fields a consumer needs WITHOUT re-deriving from the stream.
`task.log` records are large and OPT-IN (see `TelemetrySink.wants`).

```ts
export type TelemetryRecord =
  | {
      v: number
      kind: 'run.start'
      run: RunContextRecord
      total: number
      ts: number
      startedAt: number
    }
  | {
      v: number
      kind: 'task.start'
      runId: string
      taskId: string
      project: string
      task: string
      command?: string
      dependsOn?: readonly string[]
      ts: number
    }
  | {
      v: number
      kind: 'task.log'
      runId: string
      taskId: string
      stream: 'stdout' | 'stderr'
      chunk: string
      ts: number
    }
  | {
      v: number
      kind: 'task.sample'
      runId: string
      taskId: string
      ts: number
      cpuMs: number
      rssBytes: number
    }
  | ({ v: number; kind: 'task.end'; runId: string; ts: number } & TaskTelemetry)
  | { v: number; kind: 'run.end'; runId: string; ts: number }
```

## `TelemetrySink`

type · `src/orchestrator/telemetry.ts`

A telemetry consumer. Observe-only: receives records, holds no run handle.

```ts
export interface TelemetrySink {
  readonly name?: string
  readonly wants?: ReadonlyArray<TelemetryRecord['kind']>
  onRecord?(record: TelemetryRecord): void
  onRunSummary?(summary: RunSummaryRecord): void
  flush?(signal: AbortSignal): Promise<void>
}
```

## `UserError`

class · `src/util/errors.ts`

```ts
export class UserError extends Error {
  readonly code: string
  constructor(message: string)
  constructor(message: string, code: string)
  constructor(message: string, code = 'VX_E_REFUSED')
}
```

## `VERSION`

const · `src/version.ts`

```ts
export const VERSION: string = pkg.version
```

## `VxPlugin`

type · `src/orchestrator/plugin.ts`

A vx plugin. Contributes any subset of the run-level capabilities —
where work runs (executor), which cache is used (cache), who
observes the run (telemetry). It never changes WHAT a task is (the
command string — principle #3), only where and how that command is
executed. Registered explicitly in vx.workspace.ts via
defineWorkspace({ plugins: [...] }). No auto-discovery.

Made by `definePlugin(import.meta, hooks)` only: the loader refuses a
plain object. The capabilities are consulted by `plugin-host.ts`. Core
names no plugin; the local executor and the local cache are the floor
under the list, taking what every plugin declines.

```ts
export interface VxPlugin {
  readonly name: string
  config?(workspace: WorkspaceConfig, ctx: WorkspaceHookContext): void | Promise<void>
  discover?(ctx: DiscoverContext): readonly NamedProject[] | Promise<readonly NamedProject[]>
  project?(config: ProjectConfig, ctx: ProjectHookContext): void | Promise<void>
  graph?(nodes: Map<string, TaskNode>, ctx: GraphHookContext): void | Promise<void>
  key?(
    task: TaskNode,
    ctx: KeyHookContext,
  ):
    | Readonly<Record<string, string>>
    | undefined
    | Promise<Readonly<Record<string, string>> | undefined>
  readonly fingerprint?: FingerprintClaim
  schedule?(
    nodes: ReadonlyMap<string, TaskNode>,
    ctx: ScheduleHookContext,
  ): ReadonlyMap<string, number> | undefined | Promise<ReadonlyMap<string, number> | undefined>
  admit?(task: TaskNode, ctx: AdmitContext): boolean
  readonly commands?: Readonly<Record<string, PluginCommand>>
  cache?(ctx: CacheContext): CacheLayer | undefined | Promise<CacheLayer | undefined>
  executor?(ctx: ExecutorContext): TaskExecutor | undefined | Promise<TaskExecutor | undefined>
  telemetry?(
    ctx: TelemetryContext,
  ):
    | TelemetrySink
    | TelemetrySink[]
    | undefined
    | Promise<TelemetrySink | TelemetrySink[] | undefined>
  setup?(ctx: PluginSetupContext): void | Promise<void>
  teardown?(): void | Promise<void>
}
```

## `whyDidThisRerunQuery`

function · `src/orchestrator/metrics.ts`

```ts
export function whyDidThisRerun(db: Database, runId: string, taskId: string): WhyDidThisRerun
```

## `withForwardArgs`

function · `src/exec/runner.ts`

The command a task runs with the args after `--` appended, shell-quoted.
They go before a trailing comment: appended after it, `echo args: # show`
ran without them and said nothing (item 1060). Trailing blanks go first.

```ts
export function withForwardArgs(command: string, args: readonly string[] | undefined): string
```

## `WorkspaceConfig`

type · `src/config.ts`

```ts
export interface WorkspaceConfig {
  concurrency?: number
  cacheDir?: string
  timeout?: number
  cacheRetention?: { olderThan?: string; maxSize?: string }
  affectedBase?: string
  cacheScope?: string
  rules?: WorkspaceRules
  plugins?: readonly Plugin[]
}
```

## `WorkspaceHookContext`

type · `src/orchestrator/plugin.ts`

`config` runs before the cache dir is known — it may be what the hook changes.

```ts
export interface WorkspaceHookContext {
  readonly workspaceRoot: string
  warn(message: string): void
}
```

## `WorkspaceIdentity`

type · `src/orchestrator/run-context.ts`

```ts
export interface WorkspaceIdentity {
  id: string
  name: string
  repository?: string
  path?: string
}
```

---

# Benchmarks

> Empirical overhead numbers vs. Turborepo and Nx on synthetic workspaces.

Empirical overhead numbers vs. Turborepo and Nx on synthetic workspaces.
Updated as the runners evolve.

Every harness (`compare.ts`, `run.ts`, `ab.ts`, `real/turbo-repo.sh`,
`real/nx-repo.sh`) runs vx from a `vx lock` snapshot (`--frozen`), the
lock taken once per workspace before the timed reps, as CI runs vx
(2026-09-29). A section dated before that ran vx without a lock,
evaluating every config per run, except rows marked `(frozen)`; the
2026-09-03 stress run measured both, and its frozen row is now the
headline `vx`. The harness never re-locks: a config edited after the
lock is re-locked by running `vx lock` again, and `vx lock --check` is
what fails loudly on a stale lock (a `--frozen` run trusts it, owner
2026-06-13, `docs/design/config-lock-2026-06.md`); only a project the
lock lacks fails the frozen run itself.

Only the native-config runs (each runner on the same graph from its own
config: the stress run, the head-to-heads, the scaling table) measure
vx. The real-repo runs went through `turbo()` or `nx()` on the repo's
own `turbo.json` or Nx graph, a migration bridge rather than a claim
(owner, 2026-10-02), and are removed (§ Real repos). Those repos are to
be rerun on the native config `bunx @vzn/vx-migrate` writes.

## Warm-run overhead (2026-09-02)

The number that matters most to a developer is the warm no-op run: every
task a cache hit, nothing to restore. `packages/vx-bench/generate.ts` workspaces,
`vx run build --all`, this machine (macOS arm64, Bun 1.4.0), best of 5:

| Projects | Before (2026-09-02 morning) | Wave 1 | Wave 2 | Wave 5 | Wave 6 | Wave 7 | What changed                                                                                               |
| -------- | --------------------------- | ------ | ------ | ------ | ------ | ------ | ---------------------------------------------------------------------------------------------------------- |
| 100      | 105 ms                      | 92 ms  | 79 ms  | 78 ms  | 77 ms  | 74 ms  | git overlaps config load; `.git/HEAD` read replaces a git spawn; batched probe; no output walk; git first  |
| 1000     | 380–450 ms                  | 270 ms | 242 ms | 237 ms | 204 ms | 172 ms | + cached pure-config evals; one worktree walk; readdir discovery; batched probe; no output walk; git first |

Wave 7 (2026-09-03) starts the unscoped git enumeration the moment the
workspace root is known — ahead of the workspace config, discovery and
the cache open, ~25 ms earlier than before — so the `status` walk that is
the warm run's wall floor overlaps everything. Interleaved A/B against a
worktree at the previous commit, three rounds of three: 1000 projects
min 195 → 172 ms.

Wave 6 (2026-09-03) removed the per-hit output walk: for `dist/**`-shaped
globs, the mtimes of every directory under the prefix, recorded at the
last save or restore, prove the output set unchanged (`docs/caching.md`
§ A current tree). Interleaved A/B against a worktree at the previous
commit, three rounds of three: 1000 projects min 224 → 204 ms.

Wave 3 (batched short-circuit probe, output rows carried on the entry,
memoised `Bun.Glob`s) measured on the graph WITH dependencies —
`vx run test --all`, 2000 tasks, interleaved arms against an immutable
worktree of the previous commit: 327–329 ms → 308–314 ms.

Where Wave 2's 242 ms at 1000 projects went (`VX_TIMING=1`, see
below; Waves 6 and 7 took 70 ms off it, mostly the run-graph phase and
the git overlap): discovery 22 ms, config load 31 ms (all cache hits) overlapped
with git's one worktree walk (`status -uall`, ~57 ms, the critical
path), the run-graph phase 78 ms (1000 hits: probe, output glob, stat
check), history recording 12 ms, cache open 9 ms, and ~50 ms of process
start + module load + exit outside the table. The 1.7 s cold run is the
1000 `cp` commands.

Reproduce: `bun packages/vx-bench/run.ts 1000 5` (it prints the median
and every rep; the best is the min). Its last row, `one edited`, changes
one package's source per rep: one miss, every other task a hit.

### A second machine, same shape (2026-09-20)

The table above is one machine's. A four-core Linux container — sharing
nothing with it — reads, medians with the full spread:

| Projects | Warm             | Restore             | Cold                      |
| -------- | ---------------- | ------------------- | ------------------------- |
| 1000     | 271 ms (243–315) | 1031 ms (1023–1051) | 3147 ms (2905–3388)       |
| 5000     | 807 ms (760–809) | 3931 ms (3462–4172) | 14 181 ms (13 798–14 986) |

Slower in absolute terms, as a shared container should be, and those
numbers are **not** comparable to the ones above — different hardware.
What does compare is the SCALING: 5× the projects costs **2.98×** the
warm run here against **2.97×** on the other machine (restore 3.81×
against 3.97×, cold 4.51× against 4.99×). The sub-linear warm curve is
the code's, not one box's.

One number to take from this before optimising against the harness: the
warm arm spreads ±13 % about its median on identical code, because every
rep is a whole CLI invocation. An A/B here needs an effect bigger than
that, and a control arm beside it.

The same container class on 2026-09-23, after the cold-path work of
items 615 (a config round's evaluations written once per table) and 622
(output-directory snapshots landed in one transaction), medians with the
full spread, five reps at 1,000 and three at 5,000:

| Projects | Warm             | Restore             | Cold                      |
| -------- | ---------------- | ------------------- | ------------------------- |
| 1000     | 239 ms (231–265) | 906 ms (831–1009)   | 2634 ms (2418–2814)       |
| 5000     | 711 ms (702–733) | 3253 ms (2993–3630) | 10 950 ms (10 896–11 547) |

Against the 2026-09-20 rows: cold −16 % at 1,000 and −23 % at 5,000,
restore −12 % and −17 %; the warm rows moved within the ±13 % spread
and claim nothing — the warm path is unchanged since item 589. Scaling
5× the projects: warm 2.97×, restore 3.59×, cold 4.16×.

### Profiling a run

Two tools, and they answer different questions:

- **`VX_TIMING=1 vx run …`** prints a stage table to stderr at the end of
  the run — `startup`, `workspace config`, `discover projects`,
  `package graph`, `open cache`, `load configs`, `build graph`,
  `git enumeration`, `plugin stages`, `classify + probe`, `run graph`,
  `record history`, `output dir snapshots`, `close`, and
  in a dry run `plan` — with
  each stage's own and cumulative time, plus accumulated per-task spans (`cache.get`,
  `output glob`, `output stat` and `task hash` among them;
  [`modules/timing.md`](../modules/timing/) lists every one). This is the first thing to
  read: it says WHICH stage moved. The per-task spans run under the
  scheduler's concurrency, so they over-count (a span's wall includes
  time yielded to other tasks); compare them to each other, not to the
  stage total.
- **`bun --cpu-prof --cpu-prof-dir=/tmp/prof packages/vx/src/bin.ts run …`**
  then `bun packages/vx-bench/profile-summary.ts /tmp/prof/*.cpuprofile` gives self
  time by function and by file. Good for finding a hot loop; unreliable
  about where an `await` waited (it attributes the wait to whatever frame
  was on the stack).
- **`strace -f -o <file>`** around a run, then
  `bun packages/vx-bench/strace-vx.ts <file> [<before-file>]`: the count of
  vx's OWN syscalls (the tasks' shells are told apart by PID), as a diff
  against the same run on a `git worktree` of the base. A syscall count
  is deterministic where this container's wall time is not: the restore
  path's three spare round trips per artifact (item 627) were three rows
  of that table — `readlink` 1,003 → 3, `mkdir` 2,002 → 1,002,
  `newfstatat` −2,000 — and the save's two `mkdir`s of the cache
  directory (630) one row, before either was a number. A `write` per
  round trip is the thread pool's wake, so that row counts round trips.
  `bun --preload ./packages/vx-bench/sqlite-tally.ts …` is the same idea
  for SQLite statements; `restore-bench.ts` and `save-bench.ts` in the
  same package restore or save every artifact sequentially, where a
  per-artifact change of tens of microseconds shows above the
  four-worker run's noise (and one of a few microseconds does not: 630).

Three measurement lessons from this wave, recorded so they are not
re-learned. A compiled Bun 1.4.0 binary resolves on-disk packages by
`<pkg>/index.ts` only and ignores `exports`, so `packages/vx-bench/compare.ts`
measured nothing ("vx skipped") until the packages gained root shims —
if the vx row ever reads `n/a` again, read the skip line first. A micro-benchmark of a sync call in isolation (`statSync`
2 µs vs `stat` 13 µs) does not predict the run — the async forms run in
parallel on the thread pool under the scheduler's concurrency, and
switching the warm-hit path to sync calls made the 1000-project run
40 ms SLOWER. And Bun 1.4.0's `--compile` binaries carry a signature this
macOS rejects (SIGKILL on launch); an ad-hoc `codesign -s - --force`
repairs it, which the release workflow now does on a macOS runner.

### A/B two builds

`packages/vx-bench/ab.ts` is the method the numbers here use: one
workspace copy per arm, warmed by that arm, rounds that run every arm
once in a rotated order, min and median per arm, and an A/A arm (the
same vx twice) as the noise floor. Every arm after the first prints its
min against the first arm's as a signed percent. An arm is a compiled binary or a
checkout; the runs see git's defaults and no `BUN_OPTIONS`. A `run` is
timed `--frozen`: each arm runs `vx lock` in its own copy with its own
vx once, before the warm-up.

```bash
bun packages/vx-bench/ab.ts 15 base=/tmp/vx-old@/tmp/w1 main=/tmp/vx-new@/tmp/w2 \
  aa=/tmp/vx-new2@/tmp/w3 -- run build --all
```

A real repo's copies each link `node_modules/@vzn/vx-migrate` (or the
plugin under test) to their arm's checkout, so a plugin change is
measured with its own core.

### The per-PR guard

`packages/vx-bench/perf-guard.ts` runs in every PR's gate as
`@vzn/vx-bench#check.perf`. It builds a 25- and a 100-package workspace
and drives core in-process through five phases: cold run, up-to-date
run, restore run, plan, one-edit run. Two kinds of number, against
`packages/vx-bench/perf-baseline.json`:

- **Counts**: processes spawned, xxh3 calls, blob-hash updates, SQLite
  statements. The same code does the same work on any box, so a count
  that grows fails; one that shrinks passes. Statements gated by the
  50 ms racy-mtime windows (the directory snapshots) are left out; they
  move with load.
- **`--frozen` never does more**: every phase also runs `--frozen` from
  a `vx lock` (`<phase> --frozen @n`), and any count of it above the
  same phase's with no lock fails, whatever the baseline says. Time is
  not held, so the work is the pin of the rule that the lock is never
  slower. Measured on the 1,090-package bench (2026-10-09): first task
  cold 320 against 460 ms, warm 337 against 365, restore 745 against
  761 (min of 5 to 15 interleaved).
- **Time**, printed only: each timed phase's min over 7 reps at 100
  packages, divided by a calibration loop run between reps, flagged past
  1.5× the baseline, and each `--frozen` phase's ratio to no lock. It
  fails nothing: beside the test shards it read 1.97× on a PR that
  slowed no phase.

Each measure runs in a child with a hermetic environment, since vx
hashes `BUN_OPTIONS`, a HOME bunfig and its parent run's variables.
A change meant to grow a count records it (on a conflict in the file,
take main's and run it again):

```bash
vx run @vzn/vx-bench#perf.update   # then commit perf-baseline.json
```

Run it through `vx run`: the baseline's times are taken under the task
sandbox, as the check is.

## Head-to-head, 2026-09-03 (46 packages, `packages/vx-bench/compare.ts 10 5 1`)

Same workspace, identical commands, every runner pinned to concurrency
10, Turbo with no daemon (it uses none for `turbo run` since 2.8.11), vx as
its compiled binary. Median of 1,
this machine (macOS arm64, Bun 1.4.0). The harness then gave Nx npm
where Turbo had bun (§ Why Nx is slower), so the Nx row is slower than a
fair one. Every runner runs as in CI (`CI=1`), so Nx's daemon is off:

| Runner      | Version | Fresh (cold)            | Warm (no restore)        | Warm (restore)          |
| ----------- | ------- | ----------------------- | ------------------------ | ----------------------- |
| vx          | 0.0.0   | 10.45 s                 | 76 ms                    | 83 ms                   |
| vx (frozen) | 0.0.0   | 10.49 s                 | 83 ms                    | 88 ms                   |
| turbo       | 2.10.12 | 10.58 s (vx 1% faster)  | **71 ms** (vx 7% slower) | 97 ms (vx 17% faster)   |
| nx          | 23.2.0  | 19.66 s (vx 88% faster) | 540 ms (vx 7.1× faster)  | 531 ms (vx 6.4× faster) |

Read it honestly: at 46 packages Turborepo 2.10 and vx are within a few
milliseconds of each other on a fully-cached run, and neither keeps a
process between runs: Turbo 2.10 uses no daemon for `turbo run` (its docs
say so from 2.9), so both work out what changed on every invocation. vx wins
the restore case and ties the cold one; vx is 7.1× faster than Nx warm. The remaining
fixed cost at this size is process start + git, not the pipeline.

The same 46-package run on the four-core Linux container (2026-09-24,
item 735, the fixed harness: Nx runs its scripts with bun as Turbo does;
`CI=1`, so Nx's daemon is off; a different machine, so only the ratios compare
with the table above). Turbo 2.11.3 (no daemon for `turbo run`) and Nx
23.2.1, vx as its compiled binary, median of 3. The CPU column is user +
system of the invocation and every child it waited for; a daemon that
outlives the invocation would not be counted, and none runs here:

| Runner      | Version | Fresh (cold)             | Warm (no restore)      | Warm (restore)          | CPU, cold               |
| ----------- | ------- | ------------------------ | ---------------------- | ----------------------- | ----------------------- |
| vx          | 0.0.0   | 10.29 s                  | 79 ms                  | 104 ms                  | 846 ms                  |
| vx (frozen) | 0.0.0   | 10.27 s                  | **74 ms**              | **95 ms**               | 826 ms                  |
| turbo       | 2.11.3  | 10.43 s (vx 1% faster)   | 86 ms (vx 9% faster)   | 136 ms (vx 31% faster)  | 1.33 s (vx 57% faster)  |
| nx          | 23.2.1  | 22.08 s (vx 2.1× faster) | 844 ms (vx 11× faster) | 862 ms (vx 8.3× faster) | 43.79 s (vx 52× faster) |

The ideal schedule is 10.00 s, so vx and Turbo both sit on the critical
path cold, and warm they are within a few milliseconds at this size (the
2026-09-23 run of the old harness read Turbo at 112 ms). The same box
under the old harness read Nx at 27.21 s cold and 1m 2s of CPU.

The same harness at **476 packages / 1,428 graph nodes**
(`packages/vx-bench/compare.ts 20 25 1`, 2026-09-02, same machine; a mid-size data
point — the committed `packages/vx-bench/RESULTS.md` is the 3,270-task run below):

| Runner      | Fresh (cold)          | Warm (no restore)       | Warm (restore)          |
| ----------- | --------------------- | ----------------------- | ----------------------- |
| vx          | 1m 40s                | **297 ms**              | **416 ms**              |
| vx (frozen) | 1m 40s                | 285 ms                  | 399 ms                  |
| turbo       | 1m 40s (vx same)      | 342 ms (vx 15% faster)  | 612 ms (vx 47% faster)  |
| nx          | 3m 23s (vx 2× faster) | 1.38 s (vx 4.6× faster) | 1.33 s (vx 3.2× faster) |

The same size on the four-core Linux container (2026-09-25, after items
744, 753 and 754, the fixed harness, median of 1; ideal schedule 1m 36s):

| Runner      | Fresh (cold)           | Warm (no restore)       | Warm (restore)          | CPU, cold               |
| ----------- | ---------------------- | ----------------------- | ----------------------- | ----------------------- |
| vx          | 1m 37s                 | **225 ms**              | **367 ms**              | 7.06 s                  |
| vx (frozen) | 1m 37s                 | 209 ms                  | 377 ms                  | 6.94 s                  |
| turbo       | 1m 39s (vx 2% faster)  | 247 ms (vx 10% faster)  | 392 ms (vx 7% faster)   | 13.84 s (vx 96% faster) |
| nx          | 2m 27s (vx 52% faster) | 1.84 s (vx 8.2× faster) | 1.89 s (vx 5.1× faster) | 7m 23s (vx 63× faster)  |

Read it honestly: the 2026-09-24 run on this box had Turbo 2.11 winning
both warm columns (303 and 446 ms against vx's 376 and 478). Item 744
found the cost in vx's stable-key pass (a string set copied per task per
dep, now a bitset), item 753 coalesced the 952 task lines into a write
per turn of the event loop, and item 754 ranked a warm run's tasks over
the work that actually waits; vx now leads both warm columns, by 10%
and 7% in one rep each, which this container's noise can close. The
min-of-N interleaved read of the warm no-op on the same workspace, with
compiled binaries, is vx 165–175 ms against Turbo 226 ms (item 753's
profile).

### Why Nx is slower

Two things, both per task, and both measured on the 46-package workspace
(cold, 138 tasks, min of 3 interleaved arms, 2026-09-24, item 735):

| Arm                                             | Wall    | CPU     |
| ----------------------------------------------- | ------- | ------- |
| the old harness: `nx:run-script`, Nx picked npm | 28.82 s | 69.80 s |
| `nx:run-script` with bun (the fixed harness)    | 21.37 s | 41.18 s |
| `nx:run-commands`: the same commands, no fork   | 11.65 s | 3.05 s  |

1. **A Node process per task.** `nx:run-script` runs every task in a
   freshly forked Node process (`nx/bin/run-executor.js`: 138 of them in
   one cold run, counted with `strace -f -e execve`) that loads Nx before
   it runs the script. That is ~270 ms of CPU per task. On four cores at
   concurrency 10 it saturates the CPU, so every task on the 20-task
   critical path waits for a core: 9.7 s of wall and 38 s of CPU, the
   gap between the last two rows. `nx:run-commands` runs its command
   from the Nx process itself (`NX_RUN_COMMANDS_DIRECTLY`), and with it
   Nx lands at 11.65 s against an ideal of 10.00. A package-based Nx repo
   gets `nx:run-script` for every inferred `package.json` script. Since
   2026-10-04 (owner: "use run commands") the harness gives Nx
   `nx:run-commands` targets, the command line vx runs; the 46-package
   shape then read Nx 11.17 s cold and 3.26 s of CPU against vx's 10.40 s
   and 0.91 s (median of 3). The two hand-written Linux tables on this page predate it. `installDeps`, vx's
   group task, is a cached `nx:noop` for Nx and a script-less task for
   Turbo: on one 1,090-package workspace (no sleeps, min of 3) an
   uncached `nx:noop`, or a target with no executor (Nx makes it
   `nx:noop`), held Nx's warm run at 16.5 s against 5.9 s cached.
2. **npm, which the harness chose by accident.** `nx:run-script` runs
   the script through the package manager Nx detects from a lockfile.
   The generated workspace had none, so Nx fell back to npm, while Turbo
   read `packageManager` and ran `bun run`. `npm run` costs 202 ms of
   CPU per task against `bun run`'s 4 ms (min of 10, one task alone):
   7.5 s of wall and 29 s of CPU, the gap between the first two rows.
   This one was the harness's fault, not Nx's. `nx.json` now says
   `cli.packageManager: 'bun'`.

Warm is spread thin, with no single cause. With no daemon (CI), each
invocation starts three plugin workers to build the project graph
(~280 ms each, in parallel; `nx show projects` alone is 0.56 s), then
hashes and replays the cached tasks. Turning the daemon on moves the
graph into it and saves 40–160 ms (0.81 s against 0.85, min of 5, in a
probe; 682 ms against 844, median of 3, in the harness), a fifth of the
warm gap at most.

The npm share grows with the graph. At 1,090 packages (3,270 tasks,
`compare.ts 100 11`, same box, one cold run each) Nx took 20m 39s and
76 min of CPU with npm, and 7m 22s and 23 min of CPU with bun: npm was
two thirds of the old harness's Nx number there, which is the run the
site quoted (34m 44s cold, on the macOS machine). § A real monorepo
is now this box's run with `nx:run-commands`. The whole 3,270-task shape
on this box with `nx:run-script` and bun (2026-09-25, after items 744, 753 and
754, median of 1; ideal schedule 3m 38s):

| Runner      | Fresh (cold)           | Warm (no restore)      | Warm (restore)         | CPU, cold                |
| ----------- | ---------------------- | ---------------------- | ---------------------- | ------------------------ |
| vx          | **3m 40s**             | **359 ms**             | **653 ms**             | **16.05 s**              |
| vx (frozen) | 3m 41s                 | 292 ms                 | 651 ms                 | 16.46 s                  |
| turbo       | 5m 4s (vx 38% faster)  | 431 ms (vx 20% faster) | 722 ms (vx 11% faster) | 33.27 s (vx 2.1× faster) |
| nx          | 6m 59s (vx 90% faster) | 4.50 s (vx 13× faster) | 4.60 s (vx 7× faster)  | 20m 55s (vx 78× faster)  |

The day before, Turbo 2.11 won both warm columns here (496 and 856 ms
against vx's 678 and 971). Item 744 found why: vx's stable-key pass
copied a string set per task per dep, now a bitset; items 753 and 754
then took the per-line stdout writes and the whole-graph priority
closure off the warm path. vx now leads every column at this size, in
one rep each.

Refuted, each within ±0.3 s of the fixed harness's 21.2 s cold: the
per-task pseudo-terminal (`NX_NATIVE_COMMAND_RUNNER=false`) and the
output style (`NX_TUI=false`, `--outputStyle=stream`). So is the daemon:
the fixed harness read Nx cold at 22.25 s with `NX_DAEMON=true` and
22.08 s without. Parallelism is honoured: with cheap tasks, the
`nx:run-commands` arm sits 1.65 s over the ideal schedule. The ~4 git
probes each forked task runs cost ~8 ms of it. These tables used to say
Nx's daemon was on; `CI=1` had always turned it off, and the harness
keeps it off on purpose: it simulates CI.

### Why Turborepo is slower cold

The order it starts ready tasks in, not its CPU (21 s cold against vx's
17 s at 3,270 tasks). Turborepo has no ranking: its walker hands out
tasks as they become ready and each waits for a semaphore slot
(`crates/turborepo-engine/src/execute.rs`). When a layer's builds finish,
the next layer's builds become ready together with that layer's tests,
and in ready order the tests go first, so every build on the 100-layer
critical path waits about a second. `listSchedule(nodes, 10, 'fifo')`
replays that order on the benchmark's graph: 4m 58s, against Turborepo's
measured 4m 59s and 3m 38s ranked (`packages/vx-bench/tests/ideal.test.ts`).
No `turbo.json` key changes the order. vx ranks ready tasks by remaining
critical path, Nx by how many tasks wait on each.

## A real monorepo: 3,270 tasks, 100 layers (2026-10-04)

The shape that actually stresses a task runner: **100 dependency layers**,
~11 packages per layer, ~30 deps per package, three tasks each
(`build` + `installDeps` + `test`, `sleep 1` for build and test) — **3,270
task nodes**, 1,090 packages. Same repo, same hardware, same task commands;
every runner pinned to concurrency 10. `bun packages/vx-bench/compare.ts 100 11 1`,
this machine (linux x64, 4 cores), Turbo 2.11.7, Nx 23.2.1, every Nx task an `nx:run-commands` target,
Vite Task (`vp run`, vite-plus 1.0.0), its tasks in each package's `vite.config.ts`.
vx runs from a `vx lock` snapshot (`--frozen`), taken once before the reps,
as a CI pipeline runs it; _vx, no lock_ is the same run evaluating every
config per run.
The committed `packages/vx-bench/RESULTS.md` / `packages/vx-bench/results.json` are this run.

|                                 | vx                                                       | vx, no lock | Turborepo              | Nx                     | Vite Task              |
| ------------------------------- | -------------------------------------------------------- | ----------- | ---------------------- | ---------------------- | ---------------------- |
| **Cold** (nothing cached)       | **3m 40s**                                               | 3m 41s      | 4m 59s (vx 36% faster) | 3m 49s (vx 4% faster)  | 4m 49s (vx 31% faster) |
| **Warm**, nothing to rebuild    | **393ms**                                                | 473ms       | 463ms (vx 18% faster)  | 6.45s (vx 16× faster)  | 2.49s (vx 6.3× faster) |
| **Warm**, restore outputs       | **650ms**                                                | 780ms       | 997ms (vx 53% faster)  | 6.25s (vx 9.6× faster) | 2.64s (vx 4.1× faster) |
| **CPU burned**, cold (user+sys) | **17.27s**                                               | 18.79s      | 21.04s (vx 22% faster) | 52.19s (vx 3× faster)  | 12.46s (vx 39% slower) |
| **CPU burned**, warm (user+sys) | **745ms**                                                | 894ms       | 897ms (vx 21% faster)  | 7.52s (vx 10× faster)  | 2.48s (vx 3.3× faster) |
| _Baseline_ (theoretical best)   | 3m 38s cold; 0 warm, restore, CPU                        | —           | —                      | —                      | —                      |
| _Measured floors_ (context)     | git walk 24ms · walk + raw copy 93ms · task shells 9.09s | —           | —                      | —                      | —                      |

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.

**Baseline** is the theoretical best case, so each row shows its overhead:
cold is the tasks' own durations list-scheduled on 10 workers along the
exact dependency graph (critical path 1m 40s, total work ÷
workers 3m 38s); a cached run, a restore and the CPU a
runner burns are 0 in theory, so every measured number in those rows is
the runner. The cold row's total time is the headline. Secondary, the cold
overhead over the ideal schedule: vx's is
2.33s on 3,270 tasks (2 ms per package), 2.52s
with no lock; Turborepo's is
1m 21s (74 ms per package), Nx's 10.98s
(10 ms per package) and Vite Task's 1m 11s
(65 ms per package), in one unit for every runner. For context, the
**measured floors** row gives what the cheapest possible implementation
of each step costs on this machine: one `git status -uall` walk (the
cost of asking what changed), that walk plus a raw copy of every output
file, and the task shells themselves under `xargs -P 10` (which vary by
about two seconds between runs).

**CPU** is user + system time of the invocation and every child it
waited for. The tasks are `sleep`, so this is the runner's own work; a
daemon that outlives the invocation (Nx's) is not counted, so Nx's CPU
is a floor.

> Methodology note: a synthetic graph with `sleep`-based tasks isolates
> _runner_ overhead from real compilation. All four runners are
> configured **identically** — same commands, the same `src/**` inputs and
> `dist/**` outputs, the same concurrency. (Hashing `**/*` instead would
> include each task's own output in its inputs and break caching for
> everyone.) An earlier run of this shape (June 2026, a 4-core Linux box)
> read cold 3m 48s / 8m 18s / 8m 27s and CPU 22.7 s / 1,250 s / 2,038 s;
> cold wall time depends on how many cores the runners' overhead competes
> with the tasks for, which is why the CPU row is the one that travels.

## Reproducible head-to-head (vx vs Turborepo vs Nx)

`packages/vx-bench/compare.ts` scaffolds **one** shared monorepo matching the shape
above — `layers` × `perLayer` packages, ~30 deps each, three tasks
(`build` + `installDeps` + `test`) with the **identical** shell command,
`src/**` inputs, and `dist/**` outputs for every runner — then runs vx,
Turbo, and Nx across three cache states, then times one edit to the top
package (its `build` and `test` run, every other task hits). Fairness is deliberate: vx runs
as the **compiled binary** real users install (not TS source), from a
`vx lock` taken once before the reps (`--frozen`, as CI runs it); the
workspace is git-committed with `node_modules`/`.turbo`/`.nx` ignored;
**every runner is pinned to the same concurrency**; and runners are
measured **strictly one at a time**, daemons stopped between them, so they
never fight for CPU. `build`/`test` `sleep 1 s` so a warm hit visibly
skips the work.

```bash
bun packages/vx-bench/compare.ts                 # 100 layers × 11 (3,270 nodes) — the full shape (slow)
bun packages/vx-bench/compare.ts 10 5 1          # 46 packages, 10 layers — quick
BASELINE_ONLY=1 bun packages/vx-bench/compare.ts # recompute only the baseline floors against the committed rows (~9 min)
bun packages/vx-bench/update-site.ts             # rewrite the landing page, the README's bench sentence and chart, and this doc's stress section from results.json (--check to verify)
BUILD_SLEEP=0 bun packages/vx-bench/compare.ts 20 11 2   # deep graph, pure framework overhead
```

It writes [`packages/vx-bench/RESULTS.md`](https://github.com/vznjs/vx/blob/main/packages/vx-bench/RESULTS.md)
(committed, so the numbers can be referenced from a commit). On the same
workspace shape as the committed run, it then prints every re-measured
timing more than 10% slower than the committed one.

Since 2026-09-03 the table also carries **CPU** columns and a **baseline**
row — the theoretical best case (an ideal schedule of the tasks, one git
walk, a raw copy of the outputs, the commands under `xargs`), so each
runner's row reads as overhead above it. The definitions live in the
generated `packages/vx-bench/RESULTS.md`. The 46-package quick run is
the head-to-head table above (2026-09-03); an earlier run of that shape
used to sit here with a different verdict on the warm row, and one page
carrying both was a contradiction, so it is gone.

**`vx lock` + `--frozen`** is the headline `vx` row (since 2026-09-29;
before, it was its own `vx (frozen)` row): it executes the frozen
`vx-lock.json` graph with **zero per-run config evaluation**, and
`vx (no lock)` keeps the per-run evaluation's cost in view. Read the
difference as a tie, not a win: since the config-evaluation cache
(2026-09-02) the plain warm run evaluates nothing either for a config
the purity gate can prove pure, and it serves the same validated object
from `cache.db` without re-validating it, while `--frozen` parses the
whole lock and reads one remembered verdict for it (the lock is
hand-editable, so it is a boundary; X-181). What frozen still skips is the per-config identity
stat; what it still pays is the lock's own parse. Measured 2026-09-12
on the 1,000-project bench, compiled binary, 12 interleaved reps:
plain min 154 / median 177 ms, frozen 148 / 165 — ~5%, the identity
stats; the `load configs` stage reads 20–25 ms plain against 6–10 ms
of lock read plus 12–14 ms of load frozen. The 83 vs 76 ms above
(2026-09-03, median of 1) is the same tie under a laptop's noise.
`--frozen` is for what it guarantees — what runs is what was locked,
whatever a config would read from the environment — and for configs
the gate cannot prove pure, which evaluate live on every plain run and
come from the lock under `--frozen`. In your repo: `vx lock`, then
commit `vx-lock.json`.

## How the overhead scales with the workspace (2026-09-10)

The per-package figure above is one size. This is vx alone at three
sizes of the same synthetic shape (`packages/vx-bench/run.ts`, the
generator's workspace, one `build` per package whose command is a
`mkdir` and a `cp`, so the clock is the runner and almost nothing else),
the compiled Linux binary at commit 1a35ec3, median of 3 on a 4-core
Intel Xeon container:

| Packages | Cold (nothing cached) | per package | Warm, nothing to rebuild | per package | Warm, restore outputs | per package |
| -------- | --------------------- | ----------- | ------------------------ | ----------- | --------------------- | ----------- |
| 100      | 310 ms                | 3.1 ms      | 56 ms                    | 0.56 ms     | 126 ms                | 1.26 ms     |
| 300      | 762 ms                | 2.5 ms      | 100 ms                   | 0.33 ms     | 269 ms                | 0.90 ms     |
| 1,000    | 2,091 ms              | 2.1 ms      | 178 ms                   | 0.18 ms     | 808 ms                | 0.81 ms     |

Ten times the packages costs 6.7× the cold time and 3.2× the warm time:
the per-package cost falls as the fixed cost (process start, the
workspace read, the cache open) is spread over more of them, and nothing
in the run grows faster than the graph. A cold run at 1,000 packages is
two seconds; a warm one is under two hundred milliseconds. These are the
runner's own costs on a trivial task; the 3,270-task table at the top,
where each task sleeps a second and every runner is scheduled the same
way, is where the same shape is compared against Turborepo and Nx.

## Scheduling order (2026-10-09)

Which ready task starts first, measured inside vx: the default order
(most transitive dependents), the `@vzn/vx-schedule-history` plugin, and
three other rules written as measurement-only `schedule` plugins. One
cold run per row (`--force`), linux x64, 4 cores, Bun 1.4.2, vx from
source at `main` a85223a. Every task is a `sleep`. Each history arm
starts from an empty history in its own copy of the workspace. The
post: [Which task runs first?](https://vznjs.github.io/vx/blog/scheduling-strategies/).

A slow task with nothing after it: one 60 s task, two chains of a
29.75 s parent and a 0.25 s child, 2 workers.

| Rule                                      | Wall time |
| ----------------------------------------- | --------- |
| Ready order                               | 60.2 s    |
| Most transitive dependents (vx's default) | 90.0 s    |
| Critical path by step count               | 89.9 s    |
| Recorded time, run 1 (no history yet)     | 90.0 s    |

Most direct dependents ties and falls back to ready order (60.2 s);
recorded time runs 2 and 3 take 60.2 s each.

The mirror: 100 independent tasks and a chain A then B, 2 s each, 10
workers.

| Rule                                      | Wall time |
| ----------------------------------------- | --------- |
| Ready order                               | 24.3 s    |
| Most transitive dependents (vx's default) | 22.3 s    |
| Critical path by step count               | 22.4 s    |

Most direct dependents ties and falls back to ready order (24.3 s);
recorded time runs 1 to 3 take 22.3 s, 22.2 s and 22.3 s.

The headline graph: 1,090 packages, 3,270 tasks, 100 layers, 1 s
tasks, 10 workers. The best possible run is 218 s.

| Rule                                      | Wall time |
| ----------------------------------------- | --------- |
| Ready order                               | 301.7 s   |
| Most direct dependents                    | 220.5 s   |
| Most transitive dependents (vx's default) | 220.4 s   |
| Critical path by step count               | 220.6 s   |

Recorded time runs 1 to 3 take 220.6 s, 220.5 s and 220.5 s.

## Real repos

Public repos, each moved to native vx config with `vx init --native`
and timed against the tool it ships with, through
`packages/vx-bench/real/nx-repo.sh` (Nx) or `turbo-repo.sh` (Turbo):
both tools run the same tasks with the same worker count, three
interleaved reps per case, best of three. `restore` wipes the outputs
and keeps both caches; `noop` wipes nothing. Nx runs with
`NX_DAEMON=false` and no Nx Cloud.

### TanStack/query (2026-10-09)

Commit `817bd02`, scope `build` without examples and integrations: 25
tasks each, 5 workers. vx 0.0.633, Nx 23.2.1, pnpm 12.4.2, linux x64,
4 cores.

| Case        | vx     | Nx     | vx is       |
| ----------- | ------ | ------ | ----------- |
| Cold build  | 34.6 s | 39.4 s | 14% faster  |
| Restore     | 0.39 s | 1.26 s | 3.2× faster |
| Nothing new | 0.22 s | 1.43 s | 6.5× faster |

Each rep in order: vx cold 40.2 / 35.0 / 34.6 s, Nx cold 41.0 / 39.4 /
39.7 s; vx restore 0.39 / 0.50 / 0.50 s, Nx 1.26 / 1.49 / 1.57 s; vx
noop 0.22 / 0.24 / 0.23 s, Nx 1.43 / 1.59 / 1.49 s. "N% faster" means
the other tool takes N% longer.

## Performance history

Where vx's own headroom went, on the same 1090-package / 3,270-node graph,
fully cached (`vx run build test --all`):

| Milestone                                            | No-restore | Restore |
| ---------------------------------------------------- | ---------- | ------- |
| Set-closure scheduler priority (before)              | 10.2 s     | —       |
| + bitset scheduler closure                           | 1.27 s     | 1.59 s  |
| + discovery / package-graph fixes                    | 1.03 s     | 1.34 s  |
| + frontier `^task` expansion (v19, 8.5× fewer edges) | 0.62 s     | 0.87 s  |

Input hashing then moved to git blob OIDs (v20, `git ls-files -s`): clean
files cost zero reads/stats, dropping the warm run-phase from ~245 ms to
**~76 ms (3.2×)** at 500 projects × 30 files, and cold runs never read
committed file contents at all. The decision history lives in git (the log was retired 2026-09-02);
the shipped-optimization catalog with invariants is
[`optimizations.md`](../optimizations/), and the engineering tour is
[`comparison.md` § Where vx is ahead](../comparison/#where-vx-is-ahead).

## Known headroom

Config evaluation was the largest fixed cost of a warm run
(`loadProjectConfig` ~199 ms of a ~517 ms warm wall at 1,000 projects,
2026-09-02, before the day's work). The resolved-config evaluation cache
that was first rejected here shipped the same day behind the static
purity gate it needed (`caching.md` § Config evaluation cache): a config
whose import closure is provably pure is served validated from
`cache.db`, keyed on the blob id of every file in the closure; anything
the gate cannot prove evaluates live. `load configs` is 16–25 ms per
1,000 configs since. `vx run --frozen` is not a faster version of that
path (see the head-to-head above, 2026-09-12): it is the env-independent
one, and the eval-free one for impure configs.

**Source vs binary.** The runner invokes `bun packages/vx/src/bin.ts` by default, which pays ~40 ms of transpile per run that the `--bytecode` release binary does not (2026-09-09: 114 vs 71 ms on a two-package workspace; 20 projects warm 109 vs 64 ms). Set `VX_BIN=<path>` to time the shipped binary instead.

---

# Caching

> cascade through the dependency graph the same way Turborepo's does.

`@vzn/vx`'s cache is content-addressed, opt-in per task, and shaped to
cascade through the dependency graph the same way Turborepo's does.
This page explains _what's in the cache key_, _what triggers
invalidation_, _what's actually stored_, and _why_.

## Why caching is opt-in

A task is cached iff its `TaskConfig` provides a `cache` block, with
**both** `inputs.files` and `outputs.files`. Omit `cache` and the
task always runs; no read, no write.

The reasoning:

- **Defaulting caching ON with implicit globs leads to silently stale
  builds.** The first time a user forgets to revisit their config to
  add an input, the cache returns a hit for an out-of-date snapshot.
  Stale hits are the worst failure mode of a task runner — they erode
  trust in the cache itself.
- **Forcing declaration makes "what does this task read?" and "what
  does it produce?" conscious choices.** The user pays a one-time
  cost (write the globs) for a permanent gain (the cache key actually
  reflects reality).
- **The cost of a forgotten cache miss is small.** A task re-runs.
  The cost of a stale cache hit is large. Asymmetric risk justifies
  asymmetric defaults.

Turbo defaults caching ON for `outputs: []` tasks; Nx requires you to
opt _out_ via `cache: false`. We chose the strictest of the three.

## Cache key derivation

The cache key for one task is a **16-hex xxHash3 digest**, seed-chained
over (in order):

1. **`CACHE_VERSION`** — the key-derivation sentinel
   (currently `'vx-cache-v42'`, in `src/cache/key-fold.ts`). Bumped when
   the key derivation or the artifact container changes, or stored bytes
   are wrong under an unchanged key. See
   [§ Bumping CACHE_VERSION](#bumping-cache_version).
2. **`taskId`** — `${projectName}#${taskName}`. Two tasks with
   identical everything else still produce distinct keys — protects
   against e.g. `pkg-a#build` accidentally cache-hitting on a
   `pkg-b#build` entry.
3. **Workspace fingerprint** — xxh3 of every supported workspace
   marker found at the root (see
   [`modules/fingerprint.md`](../modules/fingerprint/)):
   `pnpm-lock.yaml`, `package-lock.json`, `npm-shrinkwrap.json`,
   `yarn.lock`, `bun.lock`, `bun.lockb`, `pnpm-workspace.yaml`,
   `.yarnrc.yml` (Yarn 4 catalogs, which `yarn.lock` does not record),
   `.npmrc` and `bunfig.toml` (install settings no lockfile records),
   and the content of each patch the Bun lockfile names under
   patchedDependencies (it records a patch by path alone). Any
   install-resolved change (a `bun install` that bumps `bun.lock`) or
   any workspace-shape change invalidates _every_ cache entry. This is
   the single global "the world changed" lever — and a plugin can take
   one file off it: `VxPlugin.fingerprint` claims a lockfile, core
   leaves it out of this digest, and the plugin's `key` hook folds what
   the file means for each project instead (`@vzn/vx-lockfile`'s `pnpm()`
   folds the project's own resolved dependency closure and the root
   package's, so `pnpm update foo` re-keys only the projects that depend
   on `foo` — every project when the root does, since the root's tools
   run from the root `node_modules/.bin` on every task's PATH; its `bun()` is the same
   for `bun.lock`, and this repo declares that one). The
   config-evaluation cache still keys on every file: a config may import
   a dependency the lockfile resolved.

   The fingerprint is read once per run, before any task. A task in the
   root project may rewrite one of these files — `pnpm install` without
   `--frozen-lockfile` updates the lockfile and the installed tree — and
   every key taken before it names the old one. So a task that may
   (unsandboxed in the root project, or granted a write over one) tells
   the run when its command ran, the run re-checks the files then (one
   `stat` each, following a symlink as both reads do — an `lstat` missed
   a lockfile rewritten through a link, item 760 — the bytes compared
   for any written since the read), and
   once one moved nothing keyed on the old digest is probed or saved for
   the rest of the run, with one status line naming the file. Every
   reader after such a task is keyed late, not up front. Without it the
   run after a lockfile rewrite restored a build made against the old
   install, and a save filed a build against the new install under the
   old lockfile's key, replayed whenever the tree went back (item 750,
   [`modules/fingerprint-watch.md`](../modules/fingerprint-watch/)).

4. **Project `package.json` hash** — the git blob OID of the project's
   `package.json`: the index OID when the file is tracked and clean,
   else `cache.hashFile`'s blob OID of the worktree bytes (empty when
   there is none). Folded in implicitly (Turbo / Nx parity).
   Covers the case where `cache.inputs.files: ['src/**']` is narrow
   and a `package.json` dep change would otherwise leak undetected.
   (Added at v12; rationale in [§ History](#history).)
5. **Task config hash** — `xxh3(JSON.stringify(hashableConfig(node.config)))`
   of the _evaluated_ task config. The projection is one field wide:
   `exec.remote` is dropped, because it says WHERE a task runs and not
   what it does (§ What's NOT in the key). Captures:
   - `exec` block (command, env declarations, timeout, persistent).
   - `dependsOn` and `cache.inputs.tasks` declarations.
   - `cache.outputs.files`, `cache.inputs.files`, `cache.inputs.env`,
     `cache.inputs.runtime` / `workspaceRuntime` declarations (the
     strings themselves; their resolved file content / env values /
     command output contribute separately).
   - `description` (because it's part of the resolved object — even
     though it has no behavioural effect; a description change isn't a
     correctness change but the cost of a re-run is low).
   - **Imported / computed values** — anything a preset or
     `process.env`-read at config-load time injected. Bun's native
     `await import()` evaluates the module and bakes those values into
     the object before we serialize.
6. **`forwardArgs`** — CLI args passed after `--`. Folded into the
   key so `vx run test -- --watch` doesn't cache-hit a previous
   `vx run test`. Scoped to the user-requested tasks only — dependsOn-
   pulled deps don't see them (their cache identity stays clean) — and
   to a command: a requested default `build` runs none and folds none
   (X-119).
7. **`cache.inputs.env` resolved values** — `[name, value]` pairs
   read from host `process.env` at hash time (delimited `name\0value`
   so boundaries are unambiguous). Listed names get their current
   values; an unset name folds its bare name, with no `\0`, so unset
   and set-to-empty are two keys (the child tells them apart:
   `passThrough` leaves an unset name out). A name holding a NUL is
   refused at load.
8. **`cache.inputs.runtime` resolved output** — `[command, output]`
   pairs, where `output` is the trimmed stdout of each command run via
   `sh -c` in the **project dir** at hash time; a command with stderr
   (or a NUL in stdout) folds `\0<stdout length>\0<stdout><stderr>`,
   so bytes moved between the streams move the key.
   The runtime-output analog of step 7: the command _strings_ are in
   the resolved config (step 5), their _output_ is resolved live every
   run. Folded with the command count + each `command\0output` pair.
9. **`cache.inputs.workspaceRuntime` resolved output** — same as step
   8 but commands run at the **workspace root**, and the pairs fold
   into a **distinct namespace** (`ws-runtime-values:`) so an identical
   `(command, output)` never aliases the project-cwd `runtime` values.
10. **Filtered upstream task cache hashes** — every upstream task's
    own cache key, filtered by `cache.inputs.tasks` (default: all of
    them). Sorted by hash before folding so the ordering of `dependsOn`
    doesn't change the key. This is the cascade mechanism: if anything
    beneath you changes, your hash changes too. The set is `dependsOn`'s,
    never the run's selection: a dependency `--exclude-dependencies`
    keeps from running is still folded, with the key a full run would
    derive for it (nx#35234), so the flag moves no key. Its outputs are
    whatever is on disk, which nothing proves current, so a task whose
    key folds one, and everything built on it, may hit but does not
    save (`orchestrator/excluded-keys.ts`); a task with
    `cache.inputs.tasks: []` folds none and saves as usual.
11. **Plugin key material** — the `{ name: value }` pairs a plugin's
    `key(task, ctx)` stage returned for this task, stored on the node as
    sorted `plugin/name` pairs and folded after the upstream keys and BEFORE the input files,
    ONLY when non-empty — so a workspace with no `key` plugin derives
    byte-identical keys to one before the stage existed (no
    `CACHE_VERSION` bump when it shipped). `vx why` names a changed pair
    as `plugin <plugin>/<name>`. Two plugins of one package (a plugin's
    name is its package's) that return one name are told apart as
    `<name>`, `<name>#2`, … in value order, so declaration order still
    keys nothing (item 1028).

12. **Input files' content hashes** — `cache.inputs.files` resolved to
    a concrete list of project-relative paths (gitignore-aware,
    declared-outputs-excluded, nested-projects-excluded), each file
    contributing its **git blob OID** (v20). On a clean tree the OID
    comes straight from the index — the run's up-front enumeration is
    three concurrent spawns, `git ls-files -s -v -z` (every tracked
    path, its OID and its cache-state flag),
    `git status --porcelain -z -uall --ignored=matching --no-renames`
    (dirty tracked paths, the untracked files and the ignored ones) and
    `git var -l` (the clean-filter gate's config) — so deriving these hashes
    costs zero file reads and zero per-file stats. Each trusted OID's
    blob must be the size the index recorded for the file (A-60): `git
add` under a clean filter (`core.autocrlf=true`, a `text` rule)
    stores the LF blob of a CRLF file, and once the filter is gone git
    holds that stat-clean entry clean without re-reading it, so status
    and the filter gate (today's config) both let the LF blob key the
    CRLF bytes. Which paths an index distrusts is a function of its
    entries, so the verdict is kept in `blob_verdicts` by a hash of
    the index file and the pathspecs: a warm run reads the file and
    one row (the `--debug` listing and a lookup per entry cost 550 ms
    at 100,000 files). The key stands only for an index written before
    the run began and still in place after its listing, so a `git add`
    between the two cannot pair one index's verdict with the other's
    entries; any other run checks every blob. A changed index spawns
    `git ls-files -s -v -z --debug` for the recorded sizes, takes each
    blob's size from `blob_sizes` (fixed for its OID), and asks one
    `git cat-file --batch-check` for the ones not yet known (65 ms
    over 3,000 loose objects, 10 ms packed). The check is by size,
    so a filter that keeps the size (a `filter` driver such as
    `tr a-z A-Z`), removed after an add, still leaves a blob that
    stands for other bytes: probed, the run hit the build of the
    filtered bytes. Only a read of every trusted file would catch it,
    the cost the index OIDs exist to avoid. After changing a filter,
    `git add --renormalize .` makes the index describe the worktree
    again. A
    re-listing mid-run, or a nested repository's project, spawns
    `git ls-files -s --others --exclude-standard -z .` in the project
    dir instead, and its OIDs are not trusted: those files hash by
    content. `--no-renames`, because status pairs a deleted file with a
    similar unmerged path (a conflict mid-resolve) as its rename source
    and prints only `UU <path>`: the deletion went unsaid, the file kept
    its index OID, and the run hit the output built with it (A-59).

    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`).

    A **submodule or an embedded repository** is enumerated by its own
    git: the workspace repository lists the nested one as a single entry
    (a gitlink, or `dir/` when untracked) and none of its files, so vx
    replaces that entry with the files `git ls-files` lists inside it
    (one spawn per nested repository per run, nested ones recursively),
    and those files hash by content rather than by index OID. That holds
    for a nested repository inside a project (`vendor/lib` under a
    `**` glob — until 2026-09-27 its files never reached the key, and an
    edit there was a hit on the old output), for a project inside one,
    and for a `workspaceFiles` glob. A gitlink whose directory has no
    `.git` (a submodule never initialised, or one whose `.git` was
    removed to vendor its files, the gitlink left in the index) has no
    repository to ask and `git status` says nothing of it: its files
    are listed by a walk and hash by content (A-61), so an empty one
    folds nothing. `--affected` follows the
    same shape — git reports the nested repository as one changed path,
    and every project under it is selected.

    A task with **no `cache` block** derives a key too — its dependents
    fold it (step 10) — and, declaring nothing, folds **every file in
    its project**: `**/*`, gitignore-aware, untracked files included,
    and its own outputs not excluded, since it declared none. So its
    key moves whenever it writes a file git does not ignore: a cached
    dependent misses once more after the upstream's first run and hits
    from the third. `vx why` on the dependent names the upstream as
    the moved component; on the upstream it says the file set moved
    and that no fingerprints say which. Ignore the outputs in git, or
    declare the block (`tests/uncached-upstream-key.test.ts` pins both
    arms).

    Declaring nothing, such a task may also have **written** anywhere
    in its project, so what the run learned about that project at its
    start — the git listing, the index OIDs, the `package.json` digest
    — is dropped once its command exits, pass or fail, and a later key
    re-lists and hashes by content. For the same reason a task after it
    in the same project (`dependsOn`, even with `tasks: []`) is never
    keyed up front by the local short-circuit or the remote prefetch.
    Without both, an uncached `gen` that copies a seed into a `build`'s
    declared `config.json` replayed seed B's build under seed A
    (turborepo#13788, item 743). A sandbox narrows the reach to its
    write grants: none reaches nothing, and a grant elsewhere in the
    workspace reaches every project. An unsandboxed write into another
    project crosses a project boundary and is not tracked, as for a
    cached task's undeclared write (`tests/undeclared-writes.test.ts`).

    A task **with** a `cache` block may still rewrite its own inputs in
    place — a formatter declaring `outputs: []` — and a same-project
    reader after it whose key does not fold its key (`tasks: []`, or a
    filter that leaves it out, on every path) is not keyed up front
    either: its key would be taken over the bytes before the rewrite, and
    seeds A,B,B,A replayed B on the fourth run (item 750). A reader that
    folds the rewriter's key keeps its up-front probe — that key names
    the rewriter's inputs, which are what it may rewrite. A cached task
    writing a file that is neither a declared output nor its own input
    is out of contract: a hit restores only what it declared.

    A file whose name is **not valid UTF-8** (Linux allows any byte
    but `/` and NUL) cannot be opened from a string, so it cannot be
    hashed: a task whose globs select one is refused by name, and so
    is a task whose declared outputs hold one, rather than the file
    dropping out of the key or the artifact without a word
    (turborepo#9345). Rename it, or exclude it with a negated glob.

    Your globs are a **filter over the set git reports**, so a filter
    can only ever remove — a gitignored file can never be filtered back
    in, however explicitly you name it. Naming one by hand is therefore
    a **hard error** rather than a silent nothing: it would leave the
    task ignoring a file its own config claims as an input, reporting
    `up-to-date` while that file changed. Turbo lets an explicit entry
    override gitignore; vx cannot, because the key would then depend on
    a change `git diff` cannot see and `--affected` would stop selecting
    the task. If the file is generated, depend on the task that produces
    it via `cache.inputs.tasks`. A **glob** matching nothing stays
    silent — that is legitimate — and so does a literal naming a file
    that does not exist. A literal naming a **directory** is judged the
    same way: an ignored one, or an empty one, has no file git lists
    under it, folds nothing, and is refused (item 576).

    A **bracket is literal** in a task glob, and there are no character
    classes (item 667): `app/[id]/**` folds the route directory
    `app/[id]`, and `app/\[id\]/**` is the same path. Read as a class
    — what `Bun.Glob`, Turbo and Nx do — it matched `app/i/…` and never
    the route, so the route's files keyed nothing (an edit replayed the
    old output, green) and an output declared under it cleaned an
    unrelated `app/i/page.js` before every run while the artifact
    saved nothing.

    An index OID is only trusted where git stores the worktree bytes
    **verbatim**, so the enumeration prunes it three ways:
    `git status --porcelain` drops paths whose working tree diverges;
    the `-v` flag on the same `ls-files` spawn drops `skip-worktree` /
    `assume-unchanged` entries, whose OID says nothing about what is
    (or isn't) on disk; and, once those spawns return, a clean-filter
    gate (a `git check-attr` spawn only when the gate needs one) drops paths where `text` / `eol` / `ident`,
    a `filter` driver, `working-tree-encoding`
    or `core.autocrlf` can rewrite bytes between index and worktree
    (the blob would be the LF-normalized form while the task reads the
    CRLF file). The gate costs nothing in a repo with no attributes
    and no `core.autocrlf` — see "Clean filters" below. And when the
    repository's config weakens the stat `git status` judges by —
    `core.trustctime=false`, or `core.checkStat=minimal` (whole-second
    mtime and size) — no index OID is trusted at all: a same-size
    rewrite that keeps its mtime (`cp -p`, `tar -x`) reads clean to
    git, and until 2026-09-27 (A-6) kept the old bytes' key. Every file
    is then hashed through the memo below, which keys on ctime and
    inode.

    Every pruned path, plus untracked files, falls back to an
    in-process `HASH("blob " + len + "\0" + content)` over the
    **worktree bytes** (sha1, or sha256 in `--object-format=sha256`
    repos), memoized in `file_hashes` on `(mtime, size, ctime, ino)`.
    A file changed within `FILE_HASH_RACY_MS` (50 ms) of its stat is
    hashed but not memoised; a ctime with no sub-second part, as a
    file system that keeps whole seconds writes it (ext3, HFS+,
    FAT/exFAT, some NFS), widens that window by a second, and an even
    second by two, since FAT32 keeps even seconds; a rewrite later in
    the same stamp keeps it (`racyWindowMs`; until 2026-09-27, A-2 and
    A-38, such a rewrite of the same size was a hit on the first bytes'
    output). That is the same value the index holds whenever no filter applies,
    so a file's contribution doesn't flip across dirty↔clean
    transitions. Folded as `(relPath, identity)` pairs, sorted for
    stability across OSes and walk orders. The identity is the OID
    prefixed by the file's git mode unless that mode is a plain
    file's: `100755:<oid>` for an executable, `120000:<oid>` for a
    symlink, the bare OID for 100644. The index gives the mode for a
    clean file, and the stat gives it for any other file (owner
    execute bit). A blob OID holds no mode, so until item 887 a
    `chmod +x`, or a symlink swapped for a file holding its target
    string, kept the key that `git status` and `--affected` saw move.
    Under `core.fileMode=false` (WSL's DrvFs) git reports no chmod, so
    there a clean file's mode comes from an lstat too, and its OID
    from the index (item 1076).

    A **symlink** folds as git folds it: the blob of its target
    _string_ (its mode-120000 index OID), whether it points at a file,
    a directory, or nothing. Retargeting a link changes the key; the
    bytes behind a link to a directory, or to a file outside the
    project, do not — `git diff` and `--affected` cannot see them
    either, so declare them with `workspaceFiles`. A link to a file
    inside the project tracks that file's content only when the file
    matches the task's input globs too: it is then an input of its own.
    A link under `src/**` to `other/data.txt` folds the link, not
    `other/data.txt`; name the target in the globs to track it.
    (Before 2026-09-09 a file link folded the
    bytes behind it and a directory or dangling link fell out of the
    input set entirely, so retargeting one was a stale hit.)

The composition is seed-chained (`xxh3(part, prevDigest)`) with a
label prefix per field, so two different field layouts can't collide.
Bun's xxHash3 reads only the low 32 bits of a seed, so `xxh3` feeds the
seed forward (`xxHash3(part, seed) ^ seed`) and the chain carries all 64
bits of state from step to step (item 682; `tests/hash-chain.test.ts`).
xxHash3 is non-cryptographic by design — cache keys need uniqueness
across honest inputs, not adversarial collision resistance.

## Cache lookup → restore

On a hit:

1. `cache.get(hash)` is **pure SQL**: the `entries` row carries the
   metadata and the captured stdout; the `output_files` rows carry the
   output fingerprints. The tar artifact is not touched by the probe
   (its existence is verified with one stat), so hit cost doesn't
   scale with artifact size.
2. If the on-disk output tree already matches the cached snapshot
   (size + mode + **millisecond**-mtime check against `output_files`),
   extraction is skipped entirely — the outcome reports **up-to-date**
   (`restored: false`). Mode and millisecond mtime ride the artifact's
   own `.vx-meta.json` sidecar — recorded from a stat while packing —
   so the index rows and the restored tree carry the identical values
   whether the entry was saved locally or ingested from a remote, and
   the comparison is exact in steady state. The check also requires the
   file's inode and ctime to equal the ones this machine recorded after
   the save or restore that last wrote it (`recordOutputStamps`). Size,
   mode and mtime alone cannot tell two entries apart when their
   outputs carry one fixed mtime (`tar -x`, `cp -p`, `SOURCE_DATE_EPOCH`)
   and one size: a v1 → v2 → v1 round trip reported up-to-date with v2's
   bytes on disk (item 886). No task can set a ctime, and a forged mtime
   (`touch -r`) moves the ctime too. The inode proves less than it
   seems: a restore unlinks the file and renames a new one in, and ext4
   hands the new one the freed inode (measured, item 941), so ctime is
   the guard. A row with no stamp (an ingest from a remote, or a file
   that had changed when the stamp was taken) is never current: the hit
   restores and stamps. The residual: ctime ticks on the kernel's coarse
   clock (4 ms at HZ=250), so a same-size rewrite inside the tick of
   vx's own write, in place or as a new file that took the same inode,
   with its mtime forged back, still matches.
3. Otherwise the task's declared outputs are wiped from the project
   dir (`cleanOutputs`) — see
   [§ Strict output ownership](#strict-output-ownership) — and the
   `outputs/<rel>` (+ `workspace-outputs/<rel>`) entries are extracted
   from the artifact into place: its bytes inline in the index, read in
   one read transaction with the entry's rows, or `<cacheDir>/<hash>.tar.zst`.
4. Captured stdout is replayed to the live terminal via the logger —
   the framed block looks like a fresh run. (stderr is not cached —
   only successful runs are cached and their stderr is near-always
   empty; live runs still stream stderr normally.)
5. The task is marked `cache-hit` (or `cache-hit-remote` when the
   `LayeredCache` hydrated from the remote layer this run);
   `durationMs` is the wallclock for the restore op, not the original
   exec time.

The cached `exitCode` is preserved. A cached non-zero exit is
impossible by construction — see [§ Cache write](#cache-write) — and
"by construction" is literal: neither `save` nor `ingest` accepts an
`exitCode` at all, so the stored value is pinned to `0` rather than
supplied. The restore path still checks it, because the column outlives
this process: a row from a hand-edited or foreign `cache.db` with a
non-zero exit classifies the hit `failed` instead of restoring a broken
build's outputs under a green run.

### Local restore tier (two-tier scheduler)

`dependsOn` is an ordering gate, so a dependent normally can't even
probe the cache until its upstream finishes running. But a
**stable-key** task's key is provably independent of any upstream's
_outputs_ — its hit/miss status is knowable up front, and restoring
it needs none of its deps' output. So on local-only runs, `run()`
performs an up-front CLASSIFY (`orchestrator/local-shortcircuit.ts`):

1. Derive every stable, cacheable, local-read task's key (reusing the
   run's `hashCache` memo) and probe local `cache.get` **once**,
   building a `preProbed` map covering stable hits AND stable misses.
2. Confirmed hits become the **restore tier**: the scheduler makes
   them ready immediately (no dep gate, and no failed-dep→skip check —
   their key is dep-success-independent) but at LOW priority, so cache
   **misses own the worker pool and restores only backfill idle
   capacity**.
3. `execute-task` consumes `preProbed`, so the up-front probes ARE the
   probes it would have done, hoisted — no double work, and every task
   still flows through `execute()` so output is unchanged.

Stability gate (shared with remote prefetch via
`stable-keys.ts:deriveStableKeys`): a task whose input globs could
match a same-project upstream's declared `outputs.files` (compared by
literal prefix, less what its own `!` inputs take back whole; one with
undeclared writes reaches every input), whose
own `outputs.files` meet another same-project task's (it would restore
into that tree beside the producer's restore), or whose
`inputs.workspaceFiles` could reach any upstream's outputs, has a
_preliminary_ key and stays exec-tier / dep-gated. **Any**
`outputs.workspaceFiles` producer upstream also makes a dependent's key
preliminary, whatever that dependent reads: a root-anchored output is
boundary-ignoring by design, so it can land inside the dependent's own
project dir, where an ordinary project-relative glob reads it. Such a
dependent is therefore in NEITHER tier — it is excluded from probe
reuse as well as from the restore tier, because `execute-task` reuses a
`preProbed` hash verbatim, so probe reuse is itself a stale-hit path
when the key is preliminary. On top of that, an `outputs.workspaceFiles`
declaration keeps every task whose project directory its static prefix
can reach out of the restore tier — edge or no edge, because a
root-anchored output can land in any project's directory — and every
transitive dependant of one with it (their up-front keys fold a
preliminary key); a glob with no literal prefix reaches every project.
Before item 584 one such declaration emptied the tier graph-wide.
`rules.upfrontKeys` (on by default, X-54) refuses at load a task whose
input globs can match another task's declared outputs, so the clauses
on declared outputs fire only with the rule off; undeclared writes, an
`outputs.workspaceFiles` producer upstream, a rewriter the key does not
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 —
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.

### Remote prefetch (async, remote-only)

When a run is backed by a remote cache — a plugin's `cache` capability
or an injected `RunOptions.remoteCache` layer — the network latency of
every remote GET
would otherwise sit on the critical path of the task that needs it.
So before execution starts, `run()` kicks off **background prefetches**:

1. Every cacheable task's key is derived once, up front, in
   topological order (reusing the run's `hashCache` memo, so
   `execute-task`'s later `computeTaskHash` for the same task hits the
   memo — no double hashing). This derivation touches **no cache layer**
   — keys only.
2. Each **stable-key** task's remote GET is fired concurrently under a
   bounded pool (the run's concurrency). The prefetch ingests a hit
   into the _local_ cache; misses/errors degrade to `false`.
3. Execution starts immediately — the prefetches race alongside it, so
   remote latency overlaps real work instead of blocking it.
4. When `execute-task` later calls `cache.get(hash)`, the `LayeredCache`
   **awaits the already-in-flight (resolved-or-pending) prefetch** for
   that key rather than starting a fresh round-trip: **at most ONE
   remote GET per key**, whether it was served by the prefetch, the
   lazy read-through, or both.

## A current tree: when a warm hit restores nothing

A hit whose outputs are already on disk should cost a few stats, not an
extraction. Two checks decide, both against rows the cache recorded when
the tree last matched the entry (`output_files`, and since 2026-09-03
`output_dirs`):

1. **The set.** The files under the declared output globs must be exactly
   the entry's files — no strays, nothing missing — because a restore
   wipes and rewrites the declared outputs, and a stray left in place
   would be a stale file the hit silently kept. Until Wave 6 this was a
   glob walk on every hit (0.36 ms each; 365 ms of CPU on a warm
   1000-project run). Now, for globs of the shape `<dir>/**` or a bare
   literal `<dir>` (a whole subtree — `wholeSubtreePrefixes`; a literal
   that names a file is recorded as a file, `mtime_ms` -2, and holds while
   a regular file stands there, its bytes being the per-file check's),
   the cache records every directory
   under `<dir>` with its mtime after each save and restore; on the next
   hit, unchanged mtimes on all of them prove the set unchanged, since a
   file added or removed anywhere the glob could see bumps its parent
   directory, and a new directory bumps the recorded directory that
   contains it. The rows are taken per task and written together — one
   transaction at the first read, at prune, at stats or at close, since
   item 622; a thousand commits at run end were the whole snapshot stage
   before — and a reader in the same process flushes them first. A
   save's or restore's snapshot is taken at run end, once the directories
   are past the racy window, and by then a later task or another process
   may have written into them: the walk collects the files it passes and
   records nothing unless they are the entry's rows (item 1087). Any other glob shape (`**/*.js`, `dist/*`), a missing
   row set (a remote ingest records none), a moved directory, or more
   than 8,192 directories (`OUTPUT_DIRS_CAP`) keeps the walk — and a walk that proves the tree
   current records the directories so the following hit can skip it.
2. **The files.** Every recorded file's `(size, mode, mtime-ms)` must
   match. This never left: the directory rule only replaces the
   enumeration, not the fingerprint.

The trade is the one every mtime-based skip accepts, already documented
for files: a deliberately forged directory mtime (`touch -r`) hides a
stray. Both directions are pinned in `tests/output-dirs.test.ts`.

Hard invariants of the remote prefetch:

- **Remote-only.** This entire path is gated on a `LayeredCache` being
  configured. A local-only run never prefetches; its up-front keys and
  local probes are the short-circuit's (§ Local restore tier). The
  prefetch never adds an upfront _local_ `get` / `isOutputsCurrent` /
  stat pass.
- **Stable keys only.** A task with a _preliminary_ key (§ Local
  restore tier's stability gate: undeclared writes, an
  `outputs.workspaceFiles` producer upstream, or, with
  `rules.upfrontKeys: false`, input globs that match an upstream's
  declared outputs) is not prefetched: its key would name the wrong
  artifact, and it resolves via the lazy read-through in `execute-task`. Instability propagates: a task that folds an
  unstable upstream is itself unstable. When in doubt, skip.
- **At most once.** The `LayeredCache` keeps an in-flight map keyed by
  hash; `prefetch` and `get` share it, and a settled `false` (remote
  miss) prevents a second lazy probe of the same dead key.
- **Provenance preserved.** A hash pulled from remote — even when a
  later `get` finds it as a now-local hit — still reports
  `source: 'remote'`, so the outcome is `cache-hit-remote`.
- **A remote-read-off policy** (`--no-cache`, `--force`, or
  `--cache=remote:`) fires no prefetch.
- **Never fail.** Every remote path (get / put / ingest / prefetch)
  catches all errors and degrades to a cache miss. A remote 500, a
  network drop, a corrupt artifact, or a failed integrity check can
  never fail a run.
- **Said once, and said whole.** The warning names the operation
  (`probe`, `download`, `upload`), the artifact and the layer's
  `endpoint`, with a URL's credentials, query and fragment dropped:
  `upload <hash> to <endpoint> failed: HTTP 413`. One failure class
  (the error's `code` when it has one, else its message with the hash
  taken out) is said once per run, and the repeats are counted at
  close: `2 more requests failed the same way: <cause>`.

### Remote uploads (background, drained at run end)

Writes go to the local cache synchronously; the **remote PUT is a
fire-and-forget background upload**. The task's outcome (and its
dependents) never wait on upload latency — the uploads race alongside
the rest of the run and are drained before `cache.close()`, so a
short run still ships every artifact before the process exits. Upload
failures log via `onRemoteError` and are otherwise ignored (the task
already succeeded; the only loss is the remote entry).

An upload is the outputs as the task wrote them; secret masking does
not reach file contents, so a task whose outputs embed a secret is one
to leave uncached ([security](../security/)).

### Planning probes (`--dry` / `--graph`)

The planning paths (`vx run --dry`, `--graph`) predict hits without
side effects: against a remote cache they use a **lightweight
existence probe** — no artifact download, no local ingest. A predicted
`hit-remote` means the artifact exists remotely; the bytes move only
when a real run needs them. Locally the probe reads whether the entry's
row is there and stats the artifact, never the row itself: the whole
row, its stored stdout included, made a 200-task plan over 1 MB outputs
230 ms against 28 (min of 11, 2026-10-02).

## Cache policy (read/write axes)

Caching is controlled by a four-axis `CachePolicy` — **localRead**,
**localWrite**, **remoteRead**, **remoteWrite** — independent toggles,
each enforced inside the matching cache layer at construction time. The
local `Cache` gets a `{ read, write }` slice gating its task artifact
get/save, the config-evaluation cache's reads and writes, and the
file-hash memo's writes (never `recordRun` / `stats` / `prune` / ingest
/ key derivation); the `LayeredCache` additionally gates its own remote
read-through (`remoteRead`), upload (`remoteWrite`), and prefetch
(`remoteRead`). The orchestrator derives two booleans per task:

- `willRead = task has a cache block AND it is not remote-only AND (localRead || remoteRead)`
- `willWrite = task has a cache block AND it is not remote-only AND (localWrite || remoteWrite)`

A task reads the cache only when `willRead`, saves only when
`willWrite`, and cleans its declared outputs before exec only when
`willWrite`. Remote-only is an `exec.remote: 'only'` task placed on a
remote executor: it never touches this machine's disk (no probe, no
restore, no output clean, no local save), and its result lives in the
remote executor's own store.

The CLI maps three flags to a policy (precedence: start all-on → apply
`--cache` → `--no-cache` forces all off → `--force` forces both reads
off): `--no-cache` = everything off (no read, no write, no output
clean); `--force` = reads off / writes on (re-execute and refresh the
cache, outputs cleaned); `--cache=<spec>` = explicit per-layer control.
See `docs/cli.md` § Cache control.

One subtlety: when `localWrite` is off but `remoteWrite` is on
(`--cache=local:,remote:rw`), there's no on-disk artifact for the
`LayeredCache` to read before uploading — so it packs the tar.zst bytes
in memory (`Cache.packArtifactBytes`) and uploads those.

## Cache write

A miss runs the task. If the final exit code is `0` and the task's
`willWrite` is true (it has a `cache` block AND at least one write axis
is on):

1. `cache.outputs.files` (and `outputs.workspaceFiles`) are resolved
   against the project dir / workspace root.
2. The per-component input fingerprint is the one captured before the
   command ran: on a miss `describeTaskInputs` fills `captureInto` once
   (the same call yields the key re-checked below), so no second
   `computeTaskHash` runs.
3. The artifact — one `stdout` entry (bounded: the first and last 8 Mi
   characters of the task's output, the dropped middle named where it was), the `outputs/<rel>` (+
   `workspace-outputs/<rel>`) entries, the `.vx-meta.json` sidecar and
   the `.vx-sum` checksum — is packed in-process (no staging dir, no subprocess) into a
   single `<hash>.tar.zst` and validated. One of at most 32 KiB
   compressed (`INLINE_MAX`, almost every artifact: a one-file `dist/`
   is a few hundred bytes) stays in memory; a larger one is written to a
   temp name.
4. One `BEGIN IMMEDIATE` SQLite transaction upserts a small artifact's
   bytes into `artifacts` (v33), or renames a large one into place and
   deletes the key's inline bytes, and upserts the `entries` row (taskId, command, exit code,
   duration, size, stdout, timestamps), the `output_files` fingerprint
   rows, and the entry's one `entry_inputs` row (`INSERT OR IGNORE`).
   Concurrent readers see either no entry or a complete entry — never a
   partial one — and bytes and rows go live together: the rename waits
   for the write lock, so no other writer's rows land beside it, and a
   commit that fails takes the artifact back out (the key then misses).
   Until 2026-09-27 (A-3) the rename came first, and a commit refused
   past the busy timeout left the new bytes beside the old rows: every
   later hit on the key failed the task as a corrupt artifact.
   A re-save (`--force`) first moves the previous artifact aside under
   a temp name and unlinks it after the commit: ext4 flushes the
   incoming file when a rename replaces one, 0.55 ms a save on the main
   thread against 0.04 (a forced 1,000-task run 4.01 s → 3.46 s,
   2026-10-02). A reader probing between the two renames misses.
   An inline save moves aside whatever file its key has, the same way
   (a rename that finds nothing on a first save, in place of a statement
   asking the index). As of every commit a key's bytes are in one place,
   and a reader takes the inline bytes first, so a file an older vx
   wrote beside them is never read and the sweep takes it. An inline save writes no file at all: no temp, no rename,
   and a crash leaves nothing behind (the bytes and the rows are one
   transaction in one database file).

**The key is re-checked before the save** (item 743). It was taken
before the command ran — at the task's start, or up front by the local
short-circuit — and the save files the outputs under it, so the inputs
must still be what it describes. Two checks, in order. The key
re-derived just before the command (`describeTaskInputs`, which the
executor seam needs anyway) must equal it. Then each input file and the
project's `package.json` is `lstat`ed once: a file whose ctime falls
after, or within `FILE_HASH_RACY_MS` before, the moment its digest was
learned — the enumeration's start for an index OID, the describe for a
hashed file — is hashed again and compared, and a file that is gone has
moved. A file written at or after the describe (just before the command)
has moved whatever it holds (a whole-second stamp counts as any moment
of its second, an even one of two, in both checks): an input changed and changed BACK while the
command ran matched its digest again, and its output, built from the
edit, was filed under the key and restored over the original (item
1015). When one moved, the task's result stands but no entry is saved,
one status line names the file (``[vx] app#format: `packages/app/a.ts`
changed after its key was taken — …``), and the run forgets what it
knew about the project, as after an uncached task (§ Cache key
derivation, step 12). This covers a formatter rewriting its own input
(turborepo#10111) and a user's edit mid-run (turborepo#1146). A task
left remote (`--download=none`) is held to the same checks: a moved
key still lets a local consumer fetch its outputs, but the fetch saves
no entry; until X-123 it saved them under the old key. A task
that rewrites its own input to the SAME bytes (`sed -i` always writes)
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
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
the listing is read, and a new name the declaration matches (or an
unlisted directory) is asked of git, which alone knows what is ignored;
a literal input absent then and present now is asked too. Not seen: a
file added inside a directory that held no listed file before (only
ignored ones, or none) and was not itself created mid-run. Cost: one
`lstat` per input and per reached directory on a miss that saves, a
`readdir` per directory that changed, and a `git ls-files` only when a
candidate turned up; a hit runs no command and checks nothing.
A file listed but gone before the key hashes it (an upstream that
deletes a file its dependant's globs match) is keyed as absent, not
read: the dependant failed as `internal error … ENOENT` on every run
until A-55. Absent stays unmoved while it stays gone.
Its dependants whose keys fold its key save nothing either,
transitively: that key does not name the bytes they built from (`[vx] app#use: ran
over app#gen's outputs, which its key no longer describes — …`). Until
2026-09-27 (A-12) they saved, and once the input was put back they hit
the edit's output.
A workspace fingerprint a task rewrote since the run read it (§ Cache
key derivation, step 3) withholds the save the same way, and no key
taken before it is probed or restored: a hit the up-front probe found
goes back to the scheduler and runs once its deps are done. Until X-124
that hit restored the old install's bytes.

A miss that ran here and saves **nothing** — it failed, the cache
policy writes nothing (`--cache=local:r,remote:r`), an upstream failed
under `--continue` — runs the same input re-check and, when an input
moved, forgets the project as above; otherwise its declared outputs are
resolved and marked in the git snapshot exactly as a save marks them.
Before item 750 only a save marked them, so a same-run reader keyed
from the snapshot's index OID for an output (or for an input the task
rewrote) restored the bytes from before the command.

A declared set that resolves to **nothing** is said on the run's
status line. `cache.inputs matched no files (lib/**)` — the key would
not change when the source does — is said on every miss of a cacheable
task, right after `describeTaskInputs` and before the command, whether
or not it saves. `cache.outputs matched no files (build/**)` — an empty
artifact was saved and a later hit restores nothing — is said on the
save path. Both are almost always a glob
against the wrong directory; the output line names one other cause when
it applies: a sandboxed task with no `exec.sandbox.allow.write`, whose
writes never reached disk, or a `workspaceFiles` directory that is a
symlink out of the workspace, whose files vx drops as outside (a project
output directory linked out of the project refuses the task instead, X-88). `outputs.files: []` is a deliberate cached
no-op and says nothing; a task with no `cache` block is never checked.

**The outputs are what exists when the task's command exits.** The run
waits for the command's own process, not for everything it started — a
backgrounded grandchild that still holds the output pipe does not hold
the run (`tests/runner.test.ts`) — and the save resolves the output
globs at once. A descendant the command detached (`setsid … &`, a
daemon) that writes after that is not in the artifact: the entry saves
what was there, often nothing (with the `cache.outputs matched no
files` line), and the next hit's clean-before-restore removes what the
descendant wrote and restores the saved entry in its place (upstream
survey, turborepo#12786). vx does not wait for it and cannot see it: a
process that left the task's session is outside the process group vx
tracks and signals ([kill-tree](../modules/kill-tree/)). So a command
finishes writing its outputs before it exits — `wait` for what it
backgrounds, or do not detach it.

If the task exits non-zero, **nothing is cached.** This is deliberate:

- Caching a failure prevents retry flows. The next run gets the same
  failure even after the user fixes the underlying cause (the inputs
  haven't changed, so the cache key matches).
- Failures should be transient by default — flaky tests, network
  blips, transient resource exhaustion shouldn't bake into the cache.

Failed-task stdout / stderr still reach the user via the live stream
and the framed failure block replayed at run end. The `runs` table
records the failure (status + exit code) for analytics.

## Strict output ownership

Declared `cache.outputs.files` are wiped in two distinct places:

- **Before exec on a cache miss.** A leftover `dist/old.js` from a
  prior build can't survive into a fresh build that doesn't rewrite
  it.
- **Before restore on a cache hit.** The post-restore tree is the
  cached snapshot byte-for-byte. Hand-edits to output files don't
  persist through a cache replay. When the hit's own check walked the
  output globs to find the tree stale, the clean deletes from that walk's
  list instead of walking again: nothing is awaited between them (X-161).

Both branches use the same `cleanOutputs` helper (`src/cache/inputs.ts`)
with the same boundary rules, and two directories stay off the wipe
whatever the glob: `.git` and `.vx` (`OUTPUT_NEVER`). `node_modules` is
off it too unless a glob names it (`node_modules/**`, an install task's
legitimate output); until 2026-09-27 (A-13) `**/*.js` cleaned every
installed `.js`, and a `workspaceFiles` output glob reached even `.git`.
A task that fails while a git-tracked file another task's clean removed
is still missing gets one line naming the file and that task: vx cleans
before a run where Turbo does not, so a reader with no edge to the
producer of a committed output fails naming only the file (A-48,
vueuse's `metadata/index.json`).
Workspace outputs take the same rules, and a path an output `!` entry
takes back (A-44) is off the wipe, the artifact and the restore alike.
Skipped when:

- `cache.outputs.files` is empty (nothing declared as output).
- The task's `willWrite` is false — no write axis is enabled (e.g.
  `--no-cache`, or a read-only `--cache=local:r`). The user is debugging
  and managing the tree, so vx leaves it alone. `--force` keeps writes
  on, so it DOES clean (the saved snapshot must be clean).

A declared output the process cannot remove (a `dist/` another user
wrote, a read-only checkout) fails the task with `cannot remove declared
output &lt;path&gt;: EACCES — …`, and a restore that cannot write into such a
directory with `restore of &lt;hash&gt; into &lt;dir&gt; could not write its outputs
(EACCES: …)`: the environment's failure, reported plainly, never as an
internal error or a corrupt artifact.

Why so strict? Turbo and Nx restore additively — files from a prior
state can survive. We've seen this cause:

- Wrong test runs (a deleted-but-resurrected snapshot file from a
  cache miss survives a hit and now your test passes against the
  wrong baseline).
- Wrong shipped artifacts (a deleted source-mapped file from a prior
  build sits in `dist/` alongside the new bundle).

The strict-ownership behavior makes the project dir post-run a pure
function of the cache key.

### Additive outputs: two tasks, one tree, an edge between them

Two cached tasks whose declared outputs overlap are refused at graph
build. By default that holds even when one depends on the other: the
workspace rule `rules.exclusiveOutputs` (on unless set to `false` in
`vx.workspace.ts`, X-53) keeps one path to one task, and its refusal says
how to turn it off. The shape below is correct, only slower: a stamp
before every run, a diff after, and a clean by rows. Give each task its
own output path where you can (`dist-individual` beside `dist`).

With the rule off, an edge fixes the order, and the dependant is
**additive** (item 588): twenty's
`build` fills `dist` and `build:individual` depends on it and writes
`dist/individual`; strapi's `build:types` runs `tsc` into the same
`dist` as `build`. For the dependant:

- its **own output set** is what its run added or changed under its
  declared outputs — the outputs are stamped (size, mtime, inode, ctime) before the
  run and diffed after, the same proof a hit's "already current" check
  trusts — and only that set is saved; `outputs.workspaceFiles` are
  stamped the same way (until A-43 its miss cleaned them by glob, deleting
  a same-tree upstream's root-anchored files before it read them);
- a run that **removes** a file it found (a bundler deleting the
  upstream's intermediate) saves nothing: an artifact holds what a run
  wrote, never what it took away, and the upstream's restore puts the
  file back, so the dependant runs again on every warm run (X-32);
- it **cleans by recorded rows**, never by glob, before a run (nothing:
  stale files of its own are its command's to clean, as under Turbo) and
  before a restore (its rows only, pruning emptied directories only
  inside its declared trees, so a sibling's fresh directory stays);
- its "already current" check requires its rows present and current and
  ignores everything else under the glob;
- it is **never restore-tier**: it restores or runs after its upstream,
  by the edge.

The upstream keeps strict ownership of its glob — a miss or a restore
wipes the whole tree, the dependant's additions included, and the
dependant restores or runs after — and its "already current" check
ignores strays a dependant's glob could have added, so a warm run stays
a no-op for both. A file the dependant rewrites in place (refine's
`types` regenerating `build`'s `.d.ts`) counts as the dependant's own
(its ctime moved, even where a tool stamps the size and mtime back; X-33),
which is correct and costs the upstream a restore on
the next warm run; the design note keeps that shape out of scope.

## Invalidation paths

A task's cache becomes invalid when any of these change:

| Trigger                                                                                                                                  | Mechanism                                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Edit a file in the task's `inputs.files` set                                                                                             | step 12 of key derivation                                                                                                                                                                       |
| Edit a file in the task's `inputs.workspaceFiles` set (root-anchored; may live in ANY project's dir — the documented boundary exception) | step 12 — resolved workspace files join the same input-file list                                                                                                                                |
| Any package manager updates a lockfile (`pnpm`, `npm`, `yarn`, `bun`)                                                                    | step 3 (workspace fingerprint) — or, for a lockfile a plugin claims, that plugin's `key` material (`@vzn/vx-lockfile`: only the projects whose dependency closure moved)                        |
| Edit `pnpm-workspace.yaml`                                                                                                               | step 3                                                                                                                                                                                          |
| Edit `package.json`'s `workspaces` field                                                                                                 | not step 3 — membership: a project that joins or leaves changes which projects exist and which nested dirs its parent's globs exclude (step 12); the file itself is hashed per project (step 4) |
| Edit the project's `package.json` (dep / version / scripts change)                                                                       | step 4 (project package.json hash)                                                                                                                                                              |
| Edit the task's `vx.config.ts`                                                                                                           | step 5 (task config hash)                                                                                                                                                                       |
| Edit a config file that the task config imports                                                                                          | step 5 (configHash sees the resolved object after Bun evaluates imports)                                                                                                                        |
| Change CLI `forwardArgs` (after `--`)                                                                                                    | step 6                                                                                                                                                                                          |
| Change a `cache.inputs.env` host value                                                                                                   | step 7                                                                                                                                                                                          |
| Change the combined stdout+stderr of a `cache.inputs.runtime` command (resolved at hash time)                                            | step 8                                                                                                                                                                                          |
| Change the combined stdout+stderr of a `cache.inputs.workspaceRuntime` command (resolved at hash time)                                   | step 9                                                                                                                                                                                          |
| Upstream task's cache key changes (because its inputs changed)                                                                           | step 10                                                                                                                                                                                         |
| Bump `CACHE_VERSION`                                                                                                                     | step 1 — orphans every entry                                                                                                                                                                    |
| Change `exec.env.passThrough` _values_ alone                                                                                             | **NOT a trigger** by design — passThrough values are host-specific                                                                                                                              |
| Change a file not in `inputs.files` / `inputs.workspaceFiles`                                                                            | **NOT a trigger** by design — declare it explicitly                                                                                                                                             |
| Edit `vx-lock.json`                                                                                                                      | **NOT a trigger** — globally excluded from inputs (v24); it's vx's own metadata, never a task input                                                                                             |
| Change a file in a nested project's dir                                                                                                  | **NOT a trigger** for the parent's `files` globs — project boundaries are hard (workspaceFiles is the explicit exception)                                                                       |

The cascade in step 10 is what makes monorepo caching work: edit a
file in `lib/`, and every package that depends on `lib`'s `build` task
re-runs automatically.

## Cross-project boundaries

A project's `cache.inputs.files` globs **never** reach into another
project's directory, even if a `**/*` pattern would otherwise match.

`workspace/nested-dirs.ts` computes the set of nested project
directories (projects rooted inside this one) once per `vx run`. A
workspace package counts whether or not it has a vx config: it is the
project `--affected` gives its files to, and its default `build` keys
them (X-57). The same set fences the output clean, so a root
`outputs.files: ['**/*.js']` never removes a member's source. Every
glob pass drops a path under one of them (an ancestor lookup,
A-11). The only way
for project A to depend on project B's state via project-relative
globs is `dependsOn` + upstream-hash propagation (step 10).

For a task with `exec.sandbox` and `cache`, the sandbox enforces that
"only". A workspace package reached through a `node_modules` link is
granted only when the task's key folds a task of that package, walking
the same selection `cache.inputs.tasks` applies at hash time
(`orchestrator/keyed-projects.ts`, over `upstream.ts`'s
`selectFoldedDeps`); every other link target inside the root is
withheld, so an import of a sibling the key never sees fails and is
reported instead of caching a result an edit there would not re-run.
Any exec task counts, cached or not: a task with no `cache` declares no
`inputs.files`, so its key folds every file of its project. A persistent
task counts the same way: its key folds its whole project, so a cached
e2e behind a dev server re-runs when the server's sources change.
The coverage is per package, not per file: an edge to `ui#source`
(inputs `src/**`) also admits a read of `ui/README.md`, whose edit moves
no key — the same limit a grant wider than a task's own inputs already
has. A task with no `cache` keeps every link, having no key to be stale.

**Exception:** `cache.inputs.workspaceFiles` /
`cache.outputs.workspaceFiles` are workspace-root-anchored and apply
NO boundary rule — a deliberate escape hatch (owner call: "they don't
care about boundaries; it is bad practice but is there"). Prefer
project-relative declarations; reach for workspaceFiles only for
genuinely root-anchored files.

## Clean filters (`text` / `eol` / `ident`, `core.autocrlf`)

Git can store a file's blob in a different form than the bytes in your
working tree. Under a `text`, `eol` or `ident` attribute — or with
`core.autocrlf` set to `true`/`input` — the index holds the
LF-normalized (or ident-collapsed) blob while your editor and your
build see the CRLF (or expanded) file.

That matters because `git status` compares **after** applying the
filter, so such a file reports _clean_: git considers it unmodified
even though the blob and the worktree file are different byte
sequences. Trusting the index OID as the file's content hash would
then let two genuinely different worktree contents fold the **same**
cache key, and a real change would be invisible.

So vx does not trust an index OID where a filter can apply. The check
is gated in three steps, and the common case pays nothing:

1. `core.autocrlf` is `true`/`input` — conversion applies to every
   auto-detected text file with no attribute needed, so no OID is
   trusted.
2. Otherwise, if no attributes source exists anywhere (no in-tree
   `.gitattributes`, an ignored one included, which `git status
--ignored=matching` names from the walk it already does, no `$GIT_DIR/info/attributes`, and none of the
   files git reads outside the tree: the global one, which is
   `core.attributesFile` or by default `$XDG_CONFIG_HOME/git/attributes`
   or `~/.config/git/attributes`, and the system one), no rule can name
   a filter and vx does **no** extra work. This is the default
   `git init` repo. The gate reads `git var -l`, one spawn, which from
   git 2.42 names the global and system files itself
   (`GIT_ATTR_GLOBAL`, `GIT_ATTR_SYSTEM`); for an older git the global
   lookup is mirrored and the system file is looked for at
   `/etc/gitattributes` and `<prefix>/etc/gitattributes` beside the
   binary, where a standard build puts it. Before 2026-09-24 the gate
   missed the default global file, so `* text` there left a CRLF file
   keyed on its LF blob: a CRLF→LF edit was a stale hit.
3. Otherwise `git check-attr` resolves `text`, `eol`, `ident`, `filter`
   and `working-tree-encoding` from the index — without reading worktree
   content — and only the paths actually carrying one lose their OID. A
   `filter` driver was missing from the list until item 978: a clean
   driver that drops comment lines (`sed '/^#/d'`, nbstripout's shape)
   stores one blob for two worktree files, so an edit git calls clean
   replayed the old output. Git LFS files are a `filter` too, and are
   hashed from disk.

`-text` (explicitly unset) and unspecified paths keep their OIDs:
both leave the blob byte-identical to the worktree file.

Losing an OID is not over-invalidation. It routes that path to the
content hasher, which hashes the worktree bytes — the correct source
either way. The only cost is reading the file, which is exactly what
the gate exists to avoid paying needlessly.

## Runtime inputs and the lock (the env parallel)

`cache.inputs.runtime` / `cache.inputs.workspaceRuntime` are modeled
exactly on `cache.inputs.env`, and they share its asymmetry with the
lockfile:

- **The command _strings_ live in the resolved config**, so `vx lock`
  freezes them into `vx-lock.json` (just as it freezes the env _names_
  a task declares).
- **The command _output_ is resolved live at hash time on every run**
  — inside `resolveInputs`, the same place env _values_ are read from
  the host `process.env`. The lock never stores it.

A runtime command executes **once per run, per project** (memoized by
`projectDir + command`), at key-derivation time — which, with the
up-front classify/prefetch pass, is before any task runs. It is a
run-level reading of the ENVIRONMENT (toolchain versions, resolved
config), not a per-task probe: it is not asked again before a save, as
input files are, because that would be one spawn per command per miss
where a file costs one `lstat`. A command that reads another task's
OUTPUT reads whatever is on disk when it is asked. When the reader's key
folds that task's key, the upstream key covers it: an answer taken before
the upstream ran costs a spurious miss on the run after the output
changes, never a stale hit, and the answer stays shared. When it does
not (`tasks: []`, a filter that leaves it out, transitively), nothing
covered it until X-34: the save filed bytes built from the new state
under the old answer, and a later run that started from the old state
hit them. Now such a task (`probesAfterWrites`, stable-keys.ts) takes no
key up front and is never restore-tier, and its probes run for it alone,
after its upstream finished — one spawn per such task per run, not one
per project (`tests/in-run-writes.test.ts`). Declaring the producing
task's output as an input (`dependsOn` + files) is still the cheaper
spelling: files are re-checked, answers are not.

A probe runs in its own process group. One still running when vx exits
— a Ctrl-C, or a refusal, while a hung `git` or `node -e …` answers — is
SIGKILLed with its whole tree; until 2026-09-27 (A-9) it ran on under
init. A `kill -9` of vx runs no exit hook, and leaves it.

So `vx run --frozen` loads the frozen command strings but still spawns
them and folds their current output into the key. A `node -v` that goes
from `v20` to `v22` after the lock was written busts the cache under
`--frozen`, exactly as a changed `NODE_ENV` value would — the TypeScript
escape hatch (`define: { TSC_VERSION: execSync(...) }`) goes stale here
because its value was baked into the config object at lock time, whereas
a runtime input re-resolves.

Consequently **`vx lock --check` does not — and need not — flag
runtime-output drift.** `lock --check` audits that the frozen config
object still matches a fresh evaluation; the command output was never
part of that object (only the strings are), so a changed probe output
is correct, expected, live behavior rather than lock drift. This is the
same reason `lock --check` ignores `inputs.env` value changes.

## Concurrent runs

Two vx processes on one workspace (a `vx watch` beside a `vx run`, two
CI jobs on one checkout) take turns: a run takes the workspace's run
lock before it schedules and releases it with its cache handle — before
a persistent task's wait, so a dev server never holds it — and the
second run waits, saying after a second whom it waits for:

```
[vx] waiting for another vx run (pid 4821) on this workspace to finish…
```

The cache itself was always safe (SQLite waits on its lock, artifacts
land by rename; a transaction that reads before it writes takes the
lock at BEGIN, since SQLite answers its later write `database is locked`
at once: a run's history was lost so in 13 of 48 runs on one shared
cache dir, X-105); a task's OUTPUT TREE was not — both runs cleaned and
restored the same `dist/`, and a clean landing while the other run's
restore was staging took its files out from under it. The lock is an
atomic directory under the temp directory, keyed by the workspace root
(`--cache-dir` does not make two runs strangers) and holding the
holder's pid, so a lock a killed run left behind is reclaimed once its
pid is gone. The temp directory is the one each process sees, `TMPDIR`
included: two shells that set different ones (a `nix develop` shell
sets its own, as can direnv or `sudo`) hold two locks and do not take
turns (item 970). Run them under one `TMPDIR`. A lock under the
workspace would survive a reboot that `/tmp` does not, and where a
holder's start time is not readable (off Linux) a pid reused since
would read as a live holder forever. Where the directory cannot be made at all (another user's
lock, a temp directory this user cannot write) the run says so once and
proceeds unlocked — a courtesy between cooperating runs, never a
refusal — and a restore that then loses its staged files to the other
run's clean fails with `restore of &lt;hash&gt; into &lt;dir&gt; was interrupted: a
file it had just written vanished (ENOENT: …). Another vx run is using
this workspace — re-run once it is done.`; the artifact is intact
either way (a restore renames into place only once the whole archive
has staged). Machines sharing a workspace over a network file system
do not share a temp directory, so they do not share the lock.

An eviction can still land between a hit's probe and its restore: a
`vx cache prune` in another shell, or the `cacheRetention` of another
workspace that shares the `--cache-dir` (a different workspace, so a
different lock), which cannot see this run's pending `accessed_at`
bumps and reads its fresh hits as old. The restore then finds no
artifact, and that entry is a **miss**: the run says `[vx] &lt;id&gt;: its
cache artifact &lt;hash&gt; vanished before the restore … — running it`,
runs the task, and saves it again. It failed every such task as an
internal error until 2026-09-24 (upstream survey: nx#36688, nx#34032).
A hit the local short-circuit was restoring ahead of its dependencies
goes back to the schedule and runs once they are done, never in the
restore's slot: built before them, its bytes would be saved under the
healthy key (`tests/vanished-artifact.test.ts`).

A local artifact whose bytes are wrong (a failed checksum, a torn
write, one past the artifact ceiling, an entry missing a recorded
output, a name that now reads unsafe, X-115) is a miss the same way: `[vx] &lt;id&gt;: cache: corrupt artifact
for &lt;hash&gt;: …; dropped it — running it`. The entry is dropped, so the
task's save stores the key again; it failed the task as an internal
error on every run until `--force` before A-52. A cache the run may
only read keeps the entry (`…; left it (this cache is read-only)`).

## Storage layout

The run must be able to write here — it records its history at the
end of every run, hit or miss — so a directory this user cannot write
into (another user's `.vx`, a read-only checkout) fails the run before
any task: `cache directory <path> is not writable (EACCES: …)`, with
`--cache-dir <path>` as the way out. `vx cache prune` is refused the
same way (its `--dry-run` only reads, and reads). The readers (`vx show`, `why`,
`last`, `info`) open such a directory read-only and go on: a config
that misses the evaluation cache is evaluated live and not stored.
Where the directory cannot be created at all (a read-only checkout with
no cache yet) a run says `cannot create cache directory &lt;path&gt;
(EACCES: …)`, naming the workspace `cacheDir` field and `--cache-dir`;
the readers and `vx cache prune` find no cache and go on.
A full disk is the same kind of failure and is reported the same way,
never as a corrupt artifact and never as a stack: a save that runs out
of room is `[vx] cache save failed: ENOSPC …` (the task's work ran, the
next run misses), a restore that does is the task's failure line
`could not write its outputs (ENOSPC: …). Free space on that disk and
re-run.`, and a run record that does is `[vx] run history not recorded:
… — the verdict above stands` (the run exits by its tasks; `vx last`
will not know that one). A full index (`SQLITE_FULL`) gives way where the
write is only a memo: the file-hash memo, the output stamps and the
access times are skipped and the run goes on; a prune unlinks the
artifacts first, so the rows it then deletes have room to go, and a
save's temp file is removed when its write fails.
A process out of file descriptors (`EMFILE`, `ENFILE`) is named the
same way: a save is `[vx] cache save failed: save of &lt;hash&gt; could not
open a file (EMFILE: …) — … raise the limit (ulimit -n 4096) and
re-run`, and a restore fails the task with that hint, never as a
corrupt artifact (A-39). Opening the index is named the same way: SQLite reports a
descriptor it could not get as `unable to open database file`, and vx
says `the cache index <path> could not be opened (…) — …raise the limit`
(A-56).
A restore that cannot READ its artifact (a cache directory another
user owns) names the cache, not the outputs: `restore of &lt;hash&gt; could
not read its artifact (EACCES: …). Make the cache directory readable
by this user, or point cacheDir / --cache-dir at one that is.` (A-40).
An input the key must hash that this user cannot read fails its task
naming the read: `&lt;path&gt; is not readable by this user (EACCES), and vx
reads it to derive a cache key. Make it readable, or, for a task input,
take it out of cache.inputs.files.` (A-50).

By default the entries and their artifacts live in a **shared store**
in `~/.vx/<id>/cache`, and each workspace keeps only its own index in
its `.vx/cache`: every checkout of the repository hits what another
saved (a second clone, a worktree), and none reads another's history.
The id is Nx 23's: 16 hex of a sha256 of the remote (`origin`, then
`upstream`, `base`, the first; `host/owner/repo` in lower case, so ssh
and https agree) and the workspace's path in the repository; with no
remote, the first commit. A repository with neither (no commit yet, a
shallow clone with no remote) shares nothing. Each level of `~/.vx` is
owner-only; vx closes one of yours that others can read (chmod 700), and one others can write, or owned by another user, is not used. Design: [`design/shared-store-2026-10.md`](../design/shared-store-2026-10/).

```
~/.vx/<id>/cache/                           the shared store
├── store.db                                entries, entry_stdout, output_files,
│                                           entry_inputs, store_meta; artifacts
│                                           of at most 32 KiB compressed (v33)
└── <hash>.tar.zst                          the larger artifacts (below)

<workspaceRoot>/.vx/cache/                  this workspace's own index
└── cache.db                                run history, memos, output stamps;
                                            attaches store.db as `store`
```

The store's directory carries no version: every key is seeded with
`CACHE_VERSION`, which moves when hashing or the artifact layout does, so
two vx versions never read each other's artifacts. `store.db` is the
artifacts' inventory and records its schema (`store_meta.schema`): a vx
of another `SCHEMA_VERSION` drops its tables, prints nothing (the
cache is vx's to keep), and keeps every artifact, each indexed again
when its task next hits. The check, drop, re-create and stamp are one
write transaction, so another version's open waits rather than landing
between them. A home this user cannot write keeps the store
in `<workspaceRoot>/.vx/cache/` instead, silently. Name a
cache directory (`cacheDir` in vx.workspace.ts, `--cache-dir`, or
`VX_CACHE_DIR`, in that order of precedence, relative to the workspace
root) and it holds everything, shared with no other workspace:

```
<cacheDir>/                                 (default .vx/cache when one is named)
├── .gitignore                              `*` — written when the dir is created, or into an
│                                           existing dir that lacks one, so the cache is
│                                           never committed and never enumerated as an
│                                           input (a user's own file is left alone)
├── cache.db                                SQLite metadata + run history, and the
│                                           artifacts of at most 32 KiB compressed,
│                                           the same bytes as a file below (v33)
├── cache.db-wal                            write-ahead log
├── cache.db-shm                            shared memory
├── failures/<runId>.json                   a failed run's task output and the files it
│                                           names (`vx last --format json`, getFailures);
│                                           the newest 50 kept
└── <hash>.tar.zst                          one artifact per cache entry, the larger ones:
    ├── stdout                              captured stdout (always present, may be empty)
    ├── outputs/<rel>                       declared output files, project-relative (when any)
    ├── workspace-outputs/<rel>             declared outputs.workspaceFiles,
    │                                       WORKSPACE-ROOT-relative (when any)
    ├── .vx-meta.json                       per-output [mode, mtimeMs], the key it was
    │                                       packed under (v35), the miss's CPU and RSS
    └── .vx-sum                             CRC-32 of every entry above (v36)
```

`failures/` sits outside `cache.db` so the index layout, and every
shared store under it, stays as it was. Each file is
`{ runId, tasks: [{ taskId, project, task, exitCode, timedOut?, output, locations }] }`,
written at run end (temp file + rename) only when a task failed with
output; `output` is plain text (ANSI stripped, secrets masked, the first
8 KiB and last 56 KiB). A refused write (`EACCES`, `ENOSPC`) costs only
that output, never the run's verdict.

`<hash>` is the 16-hex xxh3 key. The `workspace-outputs/` namespace is
additive: tasks that don't declare `outputs.workspaceFiles` produce
byte-identical artifacts to the plain v17 format (which is why the
field needed no `CACHE_VERSION` bump). `output_files` rows mirror the
two namespaces — project rows store the bare rel, workspace rows store
the full `workspace-outputs/<rel>` name as the discriminator.

The container is written and read by vx's own streaming tar code
(`src/cache/tar-stream.ts`): ustar with the name/prefix split and a pax
`path` record past it, header checksums, and nothing else — there is no
`tar` subprocess, no libarchive, and no staging copy. **Save streams
it**: each output is stat'd once, then read from disk as it is written
and compressed straight into the temp file (measured 2026-09-03 on a
150 MiB output: peak +705 MiB → +241–269 MiB; the streamed compressor
is ~2.4× the one-call cost per byte, so a small artifact is packed in
memory and compressed in one call — tiny saves unchanged within
noise). Ingest lists entries through the reader without materialising
a byte, and **restore streams it**: the zstd
frame is decoded and the tar read as it arrives — ustar name/prefix
(the prefix under POSIX `ustar\0` magic only: old GNU's `ustar  ` keeps
atime there, A-29),
pax `path`/`size`, GNU long names, header checksums, truncation; an
extended header (read whole) past 1 MiB or a pax `size` that is not a
whole number is refused as corrupt, since a 1 GiB pax header costs 2 GiB
of memory from a ~32 KB artifact — and
every regular entry is written beside its target as a short `.vx-tmp-*` sibling (never a suffix on the target's name, which pushed a legal 242–255-byte name past NAME_MAX) and
renamed into place only after the whole archive has ended cleanly and
the index's recorded outputs are all present. vx itself holds one
chunk of the tar at a time (measured 2026-09-03, incompressible
artifacts, fresh process: 150 MiB peaked at +644 MiB through
`Bun.Archive` and +49 MiB streamed at the same wall time; a single
400 MiB entry restores at +30 MiB, the same as a 150 MiB one), while
the per-entry buffers of many mid-sized entries are garbage the
collector reclaims at its own pace (200 × 2 MiB measured +90–180 MiB,
never the artifact's size). An artifact up to 4 MiB compressed is decoded in one call
first — the stream setup costs ~35 µs each, 4% of the headline
restore row when every artifact is a one-file `dist/` — and then fed
to the same reader and extractor, so there is one extraction path.
The reader reads a header in place when it lies within one chunk and
its numeric fields off the bytes when they are plain octal (anything
else takes the full parse): a 4-entry artifact's read 50–57 µs → 22–23
(min of 15), and a 300-artifact, 20-file restore run's reader 224 → 92
ms of main thread (2026-10-02).
The 2 GiB decompression ceiling applies to both: declared size and
output length for the one-call decode, a running count for the stream.
An ingest bounds the compressed body first: a remote body past the
ceiling's zstd bound (a length header, a Blob's size, or a running count
on a chunked stream) is refused before it can fill the disk.
A frame that declares no content size (what a streaming compressor
writes — vx's own saves above 4 MiB) is always decoded as a stream, so
a sizeless bomb has nowhere to expand and vx's artifacts ingest
anywhere. So is a body that is not exactly one frame: the declaration is
the first frame's alone, while the one-call decoder decodes every frame,
so until 2026-09-27 (A-5) a 100-byte frame with a large one appended
expanded whole in memory (2 GiB from a 32 KB body) before its length was
checked. The frame's blocks are walked by their own sizes to tell. A save meets the same ceiling first: the pack plans the tar
from one stat per output, and a tar past 2 GiB is refused before a byte
is compressed — the run stays green, one status line names the task
(`[vx] cache save failed: &lt;task&gt; is not cached: its outputs pack to …,
past the 2.0 GB artifact ceiling a restore enforces`), and nothing is
stored for a later run to hit and fail to restore. Left to the scan, a
2.2 GB output paid the whole compress and a decode (6 to 14 s) to learn
the same thing and called the task's outputs a corrupt artifact.

The last entry, `.vx-sum`, is a CRC-32 over every entry before it (each
its name, a NUL, then its body) as 8 hex digits. Tar sums its headers
only and neither zstd writer asks for a frame checksum, so a byte flipped
in a raw zstd block (incompressible output: an image, a wasm, a tarball)
decoded clean and a hit replayed the wrong bytes: 1,141 of 1,141 flips in
a random 8 KB body went unseen (L-19). Scan and restore hash every entry
as they read it and refuse an artifact whose sum is absent, wrong, or
followed by another entry, before anything it holds lands; the refusal
is a corrupt artifact, so a restore degrades to a miss and an ingest
stores nothing. It catches damage in transit or at rest, not a store that
forges artifacts: nothing a key carries can tell those from honest ones.
Its cost is the CRC's (~10 GB/s): a 32 MB restore 11.3 → 14.4 ms and
1,000 small files 16.2 → 18.9 ms on tmpfs, min of 15.

Tar headers carry mode and second mtimes. vx needs both permission bits (a lost executable bit builds cold
and breaks warm) and millisecond mtimes (the skip-restore probe compares
them) exactly, so the pack stats each output once and writes
`.vx-meta.json` — `{ version, key, files: { <entry>: [mode, mtimeMs] }, exec? }` —
into the archive. Restore applies both, at their edges too: a mode of
000, an mtime of 0 (`SOURCE_DATE_EPOCH=0`), one before 1970, whose
tar header carries 0 since ustar's field holds no sign, and one past
March 2242, whose header carries the field's 11-digit maximum (X-114:
the save failed `value … does not fit a 12-byte field`). Until 2026-09-27
(A-4) the first two were skipped, so the file came back 0644 and
stamped now and every later hit restored it again, and the third wrote
a header the reader refused, so its task never saved. `exec` (`{ cpuMs?, peakRssBytes? }`,
2026-09-12) is what the PRODUCING execution used: it rides the artifact
so a machine that never ran the task — a fresh runner on a remote hit —
still learns what the task needs (`@vzn/vx-schedule-history` packs on
it), every wire ships the bytes verbatim, and an artifact without it
reads as before. The ingest side takes the numbers only as plain
non-negative numbers; anything else in a foreign sidecar is dropped. Entries that are not regular
files (symlinks, hardlinks, devices) are never materialised — the
reader reports them only to be skipped — so a
poisoned artifact cannot smuggle one onto disk. Nor can it name a file
the task did not declare: a remote artifact is ingested only when every
file it carries matches the task's `cache.outputs` (the lookup passes
them, `CacheGetContext.outputs`), and never when it holds one path as a
file and a directory at once. Either used to reach the tree, an input
overwritten or a `.git/hooks` file planted under a green
`cache-hit-remote`, or a restore that failed every later run from the
local copy (item 942); now the read is a miss and the task runs. On the save side a
**symlinked output** is captured as its target's bytes and comes back
as a regular file (a hit that finds the task's own link still current
leaves it); a link to a directory, or a dangling one, has no bytes to
store, so the save refuses it by name rather than cache an entry that
restores to nothing. So does a link whose target is outside the
project: vx reads outputs outside the task's sandbox, and a planted
link packed a file the task could not read (L-23). Each refusal names
the path as the config spells it (`workspaceFiles output gen/latest`). The clean before exec and restore removes every
file AND symlink the output globs cover (a link is unlinked, never
followed). An output directory that is a symlink (`dist -> real-out`) is
followed by the clean as by the save and restore, so its target is the
output and an entry holds only what its run wrote (X-88); one that
resolves outside the project refuses the task, naming the link, and
nothing is deleted through it (X-5). The clean prunes the directories it emptied (before a miss it keeps
the directory a wildcard glob is rooted at, `dist` for `dist/**`, as the
task writes there), so a task whose
output changed shape — `dist/out` a directory one run and a file the
next — restores either entry over the other's tree; a stray the globs
do not cover, or an empty directory where the entry holds a file, that
stands in an entry's way fails the restore naming it, not as a corrupt
artifact (item 1094). A directory on the way that is a
symbolic link OUT of the project (a `dist` made a link after the entry
was saved) is never written through and never replaced — the link is
the user's, and replacing it is the bug nx#37061 reports — so the
restore refuses, naming it: `&lt;dir&gt;/dist is a symbolic link to
&lt;target&gt;, outside &lt;dir&gt; — a cache restore never writes through a link
that leaves its directory. Remove the link and re-run (the restore
puts a real directory there), or stop declaring outputs under it.` A
link that stays inside the project is written through, and so is one
whose target is gone: the restore creates the directory it names —
following a chain of links to its end — and writes through it, the
link kept. Whether a link stays inside is decided on where it resolves,
so a dangling link to `../elsewhere` or to an absolute path out of the
project is the same refusal, nothing created outside, and a cycle of
links is refused by name. (A link the output globs themselves cover,
`dist/sub` under `dist/**`, is an output: the clean unlinks it.) Entry NAMES are
validated by vx before anything decides where to write, and a bad
entry anywhere, even the last, rejects the WHOLE archive: the temps
are unlinked and the empty directories the extraction created are
pruned (`tests/archive-security.test.ts`). A backslash in a name is a
name character (vx runs on Linux and macOS; Windows through WSL), so an
output like `dist/back\slash` caches and restores as written.

**Key properties:** one entry is one artifact — a row of `artifacts`
when small, else one file, so eviction is one delete in the rows'
transaction or a single unlink; no per-entry manifest, no separate
`logs/` tree; and local + remote layers transport the exact same
tar.zst bytes end-to-end, wherever the local copy lives.
The artifact is the record and the index its inventory (owner,
2026-10-06): a lookup reads the row first, and a key with no row whose
`<hash>.tar.zst` is on disk (a `SCHEMA_VERSION` drop, a deleted
`cache.db` or `store.db`) has the artifact indexed again from its own
bytes, checked as a remote's are (its recorded key, its names against
the task's declared outputs), and hits; one that fails the check is a
miss, and the save that follows replaces it. An inline artifact with no
row is indexed the same way, from its bytes, in one transaction; a reset
keeps the `artifacts` table, but deleting `store.db` or `cache.db` by
hand takes the inline artifacts with it. A `.tmp-*` a crashed save
left is never a hit. `vx cache prune` sweeps row-less files, and so does a run whose workspace declares `cacheRetention`, at
most once an hour (the sweep's clock is `schema_meta.orphans_swept_at`;
the policy sums index rows, so orphans alone never make it due). A
row-less artifact may be in use: two vx versions share one store, and
each open drops the other's rows. So the policy judges it as it judges a
row, its file time standing for `accessed_at`: past `olderThan` it goes,
and under `maxSize` it counts, oldest use first with the rows. A hit
renews a file time over an hour old, so the last use is read as the file
time plus an hour. An inline artifact with no row is judged the same
way, its `at` standing for the file time, and `vx info` counts it with
the files. A temp a crashed save left goes once it is an hour
old, and so does a file an inline artifact of its key shadows; nothing
younger than an hour is taken. Re-indexing touches the
artifact's mtime before it links its temp, so the sweep sees that one
fresh too.

A row's `accessed_at` is renewed the same way: a hit renews it only once
it is over an hour old (owner, 2026-10-08). Renewing every hit rewrote
2,180 rows at a warm 1,090-package run's close, ~30 ms. So the policy
reads a row's last use as `accessed_at` plus an hour too: an entry used
within `olderThan` is never pruned, and one may stay up to an hour past
it (`tests/cache.test.ts` › "an entry used within the age limit is never
pruned").
Captured stdout is stored twice on purpose: in the artifact (so it
survives the remote round-trip) and in the `entries` row (so a local
hit replays it with pure SQL, never decompressing the artifact).

### SQLite tables

`schema_meta.version` is the gate: an index written by any other
`SCHEMA_VERSION`, earlier or newer, is reset by the first run that opens
it (pre-alpha: no migrations; the index is an inventory, owner
2026-10-06): every table but `schema_meta` is dropped and recreated,
so each comes back in its current shape (A-54: `config_closures` and
`output_dirs` kept an earlier vx's columns). The check, drop, re-create
and stamp are one write transaction, so another version's open waits
rather than landing between them; an index already current is opened
without the lock.
A reading verb (`vx why`, `vx last`, `vx info`) leaves it untouched and
says why (item 896; `vx cache prune --dry-run` previews the reset
instead, item 1083).
That open prints nothing (owner, 2026-10-06: the cache is vx's to
keep). The artifacts stay: each is indexed again from its own bytes
when its task next asks for its key (below).

```sql
-- src/cache/schema.ts (SCHEMA_VERSION = 'v34', in cache.ts)
-- With a shared store, entries, entry_stdout, output_files, entry_inputs
-- and store_meta live in its store.db, attached as `store`; the rest is
-- the workspace's cache.db. A named cache dir holds all of them.

CREATE TABLE schema_meta (
  key   TEXT PRIMARY KEY,  -- 'version', 'cache_version', 'orphans_swept_at', 'file_hashes_swept_at', 'config_evals_swept_at', 'store_dir'
  value TEXT NOT NULL
);

-- The config-evaluation cache (§ Config evaluation cache): the validated,
-- JSON-serialised result of a provably pure config, keyed by everything
-- the evaluation could have observed. Machine-local. Rows not written in
-- 30 days are swept at most once a day (`config_evals_swept_at`).
CREATE TABLE config_evals (
  key        TEXT PRIMARY KEY,
  json       TEXT NOT NULL,
  created_at INTEGER NOT NULL
);

CREATE TABLE entries (
  hash         TEXT PRIMARY KEY,  -- the 16-hex xxh3 cache key
  project      TEXT NOT NULL,
  task         TEXT NOT NULL,
  command      TEXT NOT NULL,
  exit_code    INTEGER NOT NULL,
  duration_ms  INTEGER NOT NULL,
  size_bytes   INTEGER NOT NULL,  -- artifact size
  created_at   INTEGER NOT NULL,  -- ms-epoch
  accessed_at  INTEGER NOT NULL,  -- ms-epoch; a hit renews it once over an hour old (LRU)
  cpu_ms         INTEGER,         -- v26: the producing execution's usage, from
  peak_rss_bytes INTEGER          --      the artifact's sidecar (save + ingest)
);

-- v29: stdout apart from its entry. An UPDATE rewrites a whole record, so
-- the accessed_at bump rewrote each hit's stdout (up to 16 MB): 200 hits
-- of 1 MB cost the run's close 125-150 ms.
CREATE TABLE entry_stdout (
  hash   TEXT PRIMARY KEY,         -- FK entries(hash) ON DELETE CASCADE
  stdout TEXT NOT NULL             -- captured stdout (pure-SQL hit replay); no row = ''
);

CREATE TABLE runs (
  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
  hash                TEXT NOT NULL,   -- '' when the outcome derived no key (see below)
  project             TEXT NOT NULL,
  task                TEXT NOT NULL,
  status              TEXT NOT NULL,   -- success | failed | cache-hit | cache-hit-remote | skipped
  exit_code           INTEGER NOT NULL,
  duration_ms         INTEGER NOT NULL,
  forward_args        TEXT,             -- salted xxh3 of the JSON-encoded `--` args; null when none
  started_at          INTEGER NOT NULL, -- ms-epoch
  ended_at            INTEGER NOT NULL,
  run_id              TEXT,             -- UUIDv7 shared across all tasks in one invocation
  cpu_ms              INTEGER,
  peak_rss_bytes      INTEGER,
  wallclock_start_ns  INTEGER,          -- bigint; serialized as SQLite INTEGER (signed 64-bit)
  wallclock_end_ns    INTEGER,
  cache_hit           INTEGER,          -- 0/1; convenience for flamegraph color
  attempts            INTEGER,          -- v23: attempts a retried task took (>1)
  cached              INTEGER,          -- v25: 1 = declared a cache block; 0 = runs every time
  -- v27: why the task failed or was skipped, as the run's footer said it
  -- (items 267–270); NULL where the reason does not apply
  blocked_by          TEXT,             -- a skip's root blocker, or what a task ran behind (a task id)
  timed_out           INTEGER,          -- 1 when vx's own timeout killed it
  sandbox_violations  INTEGER,          -- the sandbox's violation count
  not_ready           TEXT,             -- 'timeout' | 'exited' | 'spawn' (persistent task)
  restored            INTEGER           -- v31, on a hit: 1 = outputs restored, 0 = up to date
);

-- Two indexes, both append-only under a run's inserts: every row of a run
-- carries the same run_id and a started_at newer than everything before it.
-- There is deliberately NO (project, task) index — it scattered every run's
-- rows over one B-tree leaf per pair (a 1,000-hit warm run's record stage
-- went 57–79 ms → 14–19 ms without it) while its readers gained nothing;
-- the history reader bounds its scan by rowid instead (see history.md).
CREATE INDEX runs_started_at ON runs(started_at);
CREATE INDEX runs_run_id     ON runs(run_id);
-- The one keyed index, PARTIAL over failed rows: a green run's inserts only
-- evaluate its predicate, and the flakiness probe after a miss
-- (failure-mode.ts, "did this key ever fail?") reads a few leaves.
CREATE INDEX runs_failed ON runs(hash) WHERE status = 'failed';

-- Every non-group, non-aborted outcome of a run gets a row, so
-- `invocations.task_count` always equals `COUNT(*)` here for that run_id
-- and the terminal summary's "N total". Two of those outcomes never derive
-- a cache key — a `skipped` task (its upstream failed, so it never probed)
-- and a `persistent` one (a dev server is not cacheable) — and they store
-- `hash = ''`. `''` is impossible for a real key (16 hex chars), so it reads
-- unambiguously as "no key recorded"; the key-diff surfaces (`vx why`'s
-- whyDidThisRerun, the cache-key diff) guard it rather than reporting
-- "inputs unchanged" from two rows that never had inputs to compare.
--
-- A `skipped` row is a task of the run but NOT an execution, so the rate and
-- average aggregates in metrics.ts exclude it: counting a zero-duration
-- non-event would dilute success rate, hit rate and mean duration. The
-- completeness reads (listRuns / getRun / the run-detail timeline) include it.

-- The file-hash memo: a content hash per input file that git could not
-- answer (untracked or dirty), keyed by the stat identity that proves
-- the bytes unchanged. Machine-local; § Cache key derivation step 12.
-- A writing close drops rows unwritten for 30 days, at most once a day
-- (a memo miss is the whole cost of a dropped row; item 1082).
CREATE TABLE file_hashes (
  path         TEXT PRIMARY KEY,
  mtime_ms     INTEGER NOT NULL,
  size_bytes   INTEGER NOT NULL,
  ctime_ms     INTEGER NOT NULL,
  ino          INTEGER NOT NULL,
  content_hash TEXT NOT NULL,
  seen_at      INTEGER NOT NULL
);

-- The size of each index blob the enumeration checked against the
-- worktree size git recorded (§ Cache key derivation, A-60): fixed for
-- its OID, so a warm run asks git for none. Swept with file_hashes by
-- seen_at, the time the row was written.
CREATE TABLE blob_sizes (
  oid     TEXT PRIMARY KEY,
  size    INTEGER NOT NULL,
  seen_at INTEGER NOT NULL
);

-- v30: the paths an index distrusts, by a hash of the index file and the
-- pathspecs (A-60): a warm run reads one row, not one per blob. Swept
-- with file_hashes.
CREATE TABLE blob_verdicts (
  digest  TEXT PRIMARY KEY,
  paths   TEXT NOT NULL,
  seen_at INTEGER NOT NULL
);

-- v16: per-output-file fingerprints, scoped by the entry that produced
-- them — what a hit stats to skip the restore when the tree is already
-- current (§ A current tree). ON DELETE CASCADE follows a prune.
CREATE TABLE output_files (
  entry_hash  TEXT NOT NULL,
  path        TEXT NOT NULL,
  size_bytes  INTEGER NOT NULL,
  mode        INTEGER NOT NULL,
  mtime_ms    INTEGER NOT NULL,
  PRIMARY KEY (entry_hash, path),
  FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
);

-- v28, its own table since v32: inode + ctime THIS workspace saw after
-- the save/restore that last wrote the file (item 886); no row is never
-- current. Apart from the shared entry: two worktrees overwrote each
-- other's stamps and every switch restored. No foreign key (the entry
-- may be the store's); prune and re-save delete what they orphan.
CREATE TABLE output_stamps (
  entry_hash  TEXT NOT NULL,
  path        TEXT NOT NULL,
  ino         INTEGER NOT NULL,
  ctime_ms    INTEGER NOT NULL,
  PRIMARY KEY (entry_hash, path)
);

-- Each config's ORDERED import closure (the config first), so a warm
-- load keys it by stat-hashing the list through file_hashes instead of
-- reading every file. Machine-local; pruned with config_evals.
CREATE TABLE config_closures (
  config_path TEXT PRIMARY KEY,
  files_json  TEXT NOT NULL,
  created_at  INTEGER NOT NULL
);

-- Every directory under a whole-subtree output glob, with its mtime as
-- of the last save or restore on THIS machine: unchanged mtimes prove
-- the output SET unchanged without a glob walk. Machine-local — a remote
-- ingest writes none, and the first hit after it walks and records.
CREATE TABLE output_dirs (
  entry_hash  TEXT NOT NULL,
  path        TEXT NOT NULL,
  mtime_ms    INTEGER NOT NULL,
  PRIMARY KEY (entry_hash, path)       -- no foreign key since v32, as output_stamps
);

-- v22 (Tier 3): one header row per `vx run` invocation. The `runs`
-- table is per-task; this is the per-invocation record carrying the
-- command, git/CI/host context, tags, and run-level counts. Recorded
-- atomically alongside `runs` via recordRunBundle (one transaction).
CREATE TABLE invocations (
  run_id            TEXT PRIMARY KEY,         -- UUIDv7, == runs.run_id
  command           TEXT NOT NULL,            -- full argv, e.g. "vx run build --all"
  requested_tasks   TEXT NOT NULL,            -- JSON string[] of options.tasks
  cache_policy      TEXT NOT NULL,            -- compact flags, e.g. "lR,lW,rR,rW"
  concurrency       INTEGER NOT NULL,
  flow              TEXT,                     -- 'focused' | 'broad' | NULL (programmatic)
  started_at        INTEGER NOT NULL,         -- ms-epoch
  ended_at          INTEGER NOT NULL,
  total_duration_ms INTEGER NOT NULL,         -- wall clock of the whole run
  task_count        INTEGER NOT NULL,         -- non-group, non-aborted tasks recorded
  failed_count      INTEGER NOT NULL,
  hit_count         INTEGER NOT NULL,         -- cache-hit + cache-hit-remote
  hit_local_count   INTEGER NOT NULL,         -- cache-hit
  hit_remote_count  INTEGER NOT NULL,         -- cache-hit-remote
  up_to_date_count       INTEGER NOT NULL DEFAULT 0, -- v31: hits that restored nothing
  restored_local_count   INTEGER NOT NULL DEFAULT 0, -- v31: hits that restored, local layer
  restored_remote_count  INTEGER NOT NULL DEFAULT 0, -- v31: hits that restored, remote layer
  exit_ok           INTEGER NOT NULL,         -- 1 if the run's `ok`
  commit_sha        TEXT,                     -- nullable: not a git repo / probe failed
  branch            TEXT,
  dirty             INTEGER,                  -- 1 if worktree had uncommitted changes
  ci                INTEGER NOT NULL,         -- 1 if a CI env was detected
  ci_provider       TEXT,                     -- 'github' | 'gitlab' | 'buildkite' | 'circleci' | 'generic'
  host              TEXT,                     -- os.hostname()
  os                TEXT,                     -- process.platform
  arch              TEXT,                     -- process.arch
  vx_version        TEXT NOT NULL,
  tags              TEXT NOT NULL DEFAULT '{}' -- JSON object {k:v} from --tag
);
CREATE INDEX invocations_started ON invocations(started_at);
CREATE INDEX invocations_branch  ON invocations(branch);
CREATE INDEX invocations_ci      ON invocations(ci);

-- v22 (Tier 3): the input-fingerprint moat. One row per cache-key
-- component, keyed by the cache-ENTRY hash it belongs to (NOT a run
-- id). Written INSIDE the entry-save transaction — only on a cache
-- MISS, never on a hit — via INSERT OR IGNORE. A warm all-cache-hit
-- run writes nothing here. The "why did this re-run?" diff resolves a
-- run to its task hash (runs.hash), then joins two entries' components
-- over (kind, name), no recompute. v34: one row per entry, the
-- components one JSON array (a row per component cost a b-tree insert
-- each: ~0.5 ms a save at 50 input files). ON DELETE CASCADE sweeps the
-- row when a prune drops the entry.
CREATE TABLE entry_inputs (
  entry_hash TEXT PRIMARY KEY,       -- == entries.hash / runs.hash
  components TEXT NOT NULL,          -- JSON [[kind, name, hash], …] in (kind, name) code-unit order
  FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
);
-- kind: file|env|runtime|ws-runtime|upstream|package|config|forward|workspace|plugin|format
-- name: file: workspace-rel path; env: var name; upstream: task id; …
-- hash: env|runtime|ws-runtime|forward|plugin: xxh3hex(salt + value); an unset env var: 'unset'

-- v32: what belongs to the entries, not to one workspace: 'value_salt',
-- the salt entry_inputs digests are taken under, so they compare with
-- another workspace's run.
CREATE TABLE store_meta (
  key   TEXT PRIMARY KEY,
  value TEXT NOT NULL
);

-- v33: an artifact of at most 32 KiB compressed, its exact <hash>.tar.zst
-- bytes, written in the transaction that writes its entry rows. In the
-- store (or a named cache dir's cache.db), and outside every drop a
-- SCHEMA_VERSION reset makes: the artifact is the record.
CREATE TABLE artifacts (
  hash  TEXT PRIMARY KEY,
  at    INTEGER NOT NULL,              -- last use (ms): a row-less sweep's file time
  bytes BLOB NOT NULL
) WITHOUT ROWID;

-- 'layout' = 'a1': the artifacts table's own version; another value
-- drops the table, silently. Nothing else drops it. Read only where
-- the schema was not this vx's, so a layout change bumps the schema.
CREATE TABLE artifacts_meta (
  key   TEXT PRIMARY KEY,
  value TEXT NOT NULL
);
```

WAL mode is on; readers don't block writers. `PRAGMA busy_timeout =
5000` makes concurrent `vx run` invocations queue instead of failing
with `SQLITE_BUSY`.

> **Trust boundary (Tier 3):** `entry_inputs` stores a digest of each
> value-bearing component — `env`, `runtime`, `ws-runtime`, `forward`
> and `plugin` rows hold `xxh3hex(salt + value)`, an unset env var the
> literal `'unset'` — never the value, so a secret read as a cache input
> does not land in `cache.db` as plaintext. The salt is 128 random bits
> the store draws once (`store_meta` key `value_salt`): `vx why` prints
> these digests, and an unkeyed xxh3 in a public CI log let anyone
> confirm or brute-force a short secret. The "why did this re-run?" diff
> only needs to know a component changed, which the digest tells it.
> `cache.db` still records commands and captured stdout; it is a local,
> gitignored, single-user file.

The Tier-3 tables persist components that were **already fed to
`Cache.key()`** — the cache key derivation is unchanged, so the
`CACHE_VERSION` is NOT bumped (only `SCHEMA_VERSION` rolls to `v22`).
Capture happens as a pure side-channel inside the existing `key()` fold
(`CacheKeyInput.captureInto`), **only on a cache miss** (the warm path
captures nothing), and the rows are persisted with the entry — so a
warm all-cache-hit run does no extra hashing, I/O, or DB writes for the
moat.

### Why SQLite + a single artifact per entry

- **Index queries are fast.** Stats (`SELECT COUNT(*) FROM entries`),
  TTL pruning (`WHERE accessed_at < ?`), per-task lookup
  (`WHERE hash = ?`) all hit a B-tree.
- **A hit costs SQL, not decompression.** Metadata + stdout live in
  the row; the artifact is only opened when outputs actually restore.
- **One artifact = one wire payload.** The same tar.zst bytes serve
  local storage and the remote round-trip — no repacking.
- **One handle, one schema-meta sentinel.** An older schema drops
  and recreates every table but `schema_meta` (pre-alpha) — there's no migration code to maintain.

## Config evaluation cache

Evaluating configs is the largest fixed cost of a warm run on a big
workspace (~80 ms for 1000 synthetic configs; reading them as data is
~12 ms). A config that is **provably pure** — every import relative or
`@vzn/vx`, and no mention of `process`, `Bun`, `Date`, `fetch`,
`import.meta`, `require`, a dynamic `import()`, `await`, … outside string
literals and comments — is served from `cache.db`'s `config_evals` table,
keyed by the git blob id of the config and of every file in its
relative import closure, the workspace fingerprint (lockfiles) and Bun's
version. Editing a shared preset moves the key. On a warm run the
closure is remembered per config, so the key comes from a stat-backed
identity per file — no read, no scan — for every config whose relative
imports name their files outright: an explicit extension, the file
itself, no symlink on the way (an extensionless import, a `.js` Bun
answers with a `.ts`, or a link could be re-resolved without touching a
listed file, so such a config keeps the scan). Anything the static check cannot prove
pure evaluates live, exactly as before, so the cache can be slower but
not wrong for a config written in good faith (the check is syntactic; one
built to defeat it can). Details and the deny-list:
[`modules/config-cache.md`](../modules/config-cache/).

## Performance characteristics

- **Hashing cost** on a clean tree is near-zero per file: git index
  OIDs come from the bulk enumeration spawn, so key derivation does no
  file reads. Dirty/untracked files — and any path whose OID is not
  trustworthy (see "Clean filters") — hash in-process (whole-file
  read, behind a `(mtime, size, ctime, ino)` memo). Narrow
  `inputs.files` still helps on heavily dirty trees.
- **Cache read** is three indexed `SELECT`s (the `entries` row, which
  joins whether the artifact is inline, its `output_files` and its
  `output_dirs`), plus a `stat` of the artifact when it is a file.
  Restore is a tar.zst extract, skipped entirely when the on-disk
  tree already matches. `accessed_at` bumps (only rows over an hour
  old) are batched into one UPDATE at flush time.
- **Cache write** is one in-process tar.zst pack + one SQLite
  transaction, which holds a small artifact's bytes itself; a large one
  adds a temp write and an atomic rename. Hashing dominates the run; storage itself
  is cheap. The remote upload (if any) is backgrounded.
- **Workspace fingerprint** is computed once per `vx run` invocation
  and reused for every task in that run; after a task that may rewrite
  one of its files ran, one `stat` per file re-checks it (item 750).

## What's NOT in the key (and why)

- **`exec.env.passThrough` _values_.** Would force cache misses across
  machines with different CI flags, regions, or shell prompts. The
  _names_ are in the config hash (step 5) so adding/removing a
  passthrough still bumps the key for affected tasks.
- **Files outside the project directory that aren't declared.**
  Workspace-root configs (`tsconfig.base.json`, etc.) are not
  auto-included — declare them via `cache.inputs.workspaceFiles`
  (root-anchored globs).
- **Node / Bun / OS / build-tool versions — unless you declare them.**
  The canonical mechanism is `cache.inputs.runtime` /
  `workspaceRuntime` (e.g. `workspaceRuntime: ['node -v']`): the
  command output is resolved live at hash time, so it stays correct
  under `--frozen`. Avoid baking versions via
  `define: { X: execSync(...) }` — that value freezes into the config
  object at lock time and goes stale.
- **`vx-lock.json`** — globally excluded (v24); also filtered out of
  `--affected` change sets.
- **`exec.remote`.** Pure PLACEMENT: it decides _where_ a task runs,
  never what it produces, so pinning a task to this machine does not
  bust its cache. It must not — the
  whole contract of a remote executor is that the same command over the
  same inputs yields the same outputs, so a key that moved with
  placement would split your laptop from the worker pool over nothing.

  **`exec.timeout` and `exec.retries` are the deliberate exception** —
  they stay in the key. That asymmetry is easy to misread as an
  oversight, so: a timeout or a retry budget can change _whether the
  task completes at all_, which is a different question from where it
  ran. They were folded in before the placement fields existed, and
  stripping them now would be a `CACHE_VERSION` bump for no correctness
  gain.

## Bumping `CACHE_VERSION`

The cache records the version it was written under
(`schema_meta.cache_version`). After an upgrade every cached task
misses once and re-saves, with nothing printed (owner, 2026-10-06: the
cache is vx's to keep). The index survives, so the old entries stay
until they age out under `vx cache prune --older-than` or
`cacheRetention`; no key derives to them again.

Required when:

- A new field is added to the cache key derivation (step list above).
- The order or framing of existing key fields changes.
- The on-disk layout changes (artifact format, entry naming).
- The `CacheEntry` shape changes in a way that affects restore.
- The SQLite schema changes in a way that affects existing rows
  (`SCHEMA_VERSION` also bumps in that case).

Not required when:

- Behavioural changes that adjust _which_ values flow into existing
  key components — those naturally produce different keys for
  affected tasks.
- Changes to WHEN reads/writes fire (policy, prefetch, restore tier,
  background uploads) — key derivation and artifact bytes untouched.
- Doc-only updates.
- Refactors that don't change the bytes fed into the hash.

`tests/contract-stored-format.test.ts` holds the layout rows: it
records the index's DDL beside `SCHEMA_VERSION` and a fixture
artifact's entries, sidecar and digest beside `CACHE_VERSION`
(`tests/contract/stored-format.json`), and fails when either layout
moves under its recorded version. Every bump of either version
regenerates the record
(`VX_UPDATE_CONTRACT=1 bun test tests/contract-stored-format.test.ts`),
which refuses a layout that moved without one.

The bump procedure has a dedicated skill at
`.claude/skills/bump-cache-version/` (used as `/bump-cache-version`).
Files touched, in the skill's order: `src/cache/key-fold.ts` (the constant),
this doc (history), `docs/modules/cache.md` (the quoted version, and the
key/entry shape if it changed), `CLAUDE.md` § Live invariants (the quoted
version — the decision log it once named was retired 2026-09-02),
`docs/STATUS.md` (the entry that says why the bump was needed, or why it
was not), the cache tests, `tests/contract/stored-format.json`
(regenerated, above), and
`packages/vx-docs/src/content/docs/guides/upgrading.md` (the bump's
breaking footer).

### History

- **v41 → v42**: the stored output became both streams in the order
  the run printed them (`orchestrator/output-log.ts`), so a hit replays
  stderr too. A v41 entry holds stdout alone.
- **v40 → v41**: stored bytes wrong under an unchanged key (X-88). An
  output directory linked inside its project was never cleaned, so an
  entry could hold files a run of another key left there. The fix
  cannot reach an entry already saved that way.
- **v39 → v40**: stored bytes wrong under an unchanged key (X-32, X-33,
  X-34). An additive task's entry a hit replayed over a file the task
  had removed, one that missed a same-size rewrite, and a runtime probe
  answered before its upstream wrote.
- **v38 → v39**: stored bytes wrong under an unchanged key (A-61). A
  gitlink whose directory had lost its `.git` but held files listed
  none of them, so an entry built from them sits under the key the
  same directory empty derives.
- **v37 → v38**: stored bytes wrong under an unchanged key (A-60). A
  file added under a clean filter that was later removed kept its LF
  index blob, git held it clean by its stat, and the key folded that
  blob while the task read the CRLF bytes. The blob-size check cannot
  reach an entry already saved that way.
- **v36 → v37**: stored bytes wrong under an unchanged key (A-59).
  `git status` paired a deleted file with a similar unmerged path as its
  rename source and printed only `UU <path>`, so the file kept its index
  OID and the key folded it while the task ran without it. The fix
  (`--no-renames`) cannot reach an entry already saved that way.
- **v35 → v36**: the container changes (L-19). Every artifact ends in a
  `.vx-sum` entry, a CRC-32 over the entries before it, and scan and
  restore refuse one whose sum is absent or wrong: a byte flipped in a
  raw zstd block restored as a hit, undetected. A v35 artifact carries no
  sum, so the bump retires them rather than refusing each on read.
- **v34 → v35**: the container changes (item 943). The sidecar records
  the cache key the artifact was packed under, and ingest refuses bytes
  whose key is not the one it asked for, or that record none. Nothing
  tied an artifact to its key before: a remote layer that answered one
  key with another's bytes (a truncated or colliding key mapping, two
  namespaces mixed) replayed the other task's outputs under a green
  `cache-hit-remote`, probed with project `b` restoring project `a`'s
  `out.txt`. An artifact from v34 records no key, so the bump retires
  them rather than refusing each one on read.
- **v33 → v34**: stored bytes wrong under a key a CORRECT derivation now
  produces (item 750). A root task that rewrote the lockfile mid-run
  (`pnpm install` without `--frozen-lockfile`) let a reader after it save
  a build made against the new install under the key of the lockfile the
  run started with, and that key is exactly what the fixed code derives
  when the tree is back on that lockfile. The fix stops new entries, not
  old ones. Probed, not argued: seeds A then B through the previous
  commit, then A twice through the fixed code under v33 — the last run
  started on lockfile A, installed A, and restored the build made against
  B; under v34 it built A. The item's other two edges poisoned nothing:
  their stale restores happened in runs that saved nothing (a read-only
  policy, a tainted upstream) or saved under a key the 743 re-check
  already guarded.
- **v32 → v33**: stored bytes wrong under a key a CORRECT derivation now
  produces (item 743). The three stale-hit fixes of that item stop new
  poisoned entries, but not the ones already saved: a formatter's entry
  sits under the key of its unformatted input, an uncached `gen`'s
  consumer's under the key of the seed before `gen` ran, an edit-mid-run's
  under the key of the file before the edit — and each of those keys is
  exactly what the fixed code derives when the tree is back in that
  state. Not self-healing, unlike a fix whose old key no correct run
  derives. Probed, not argued: an entry saved by the previous commit's
  formatter, the input checked out unformatted, and the fixed code under
  v32 reported `up-to-date` and left it unformatted; under v33 it runs.
- **v31 → v32**: stored bytes wrong under a key the fix does not change
  (item 739). A declared output whose name is not UTF-8 (`x\xffy`) came
  back from `Bun.Glob` decoded lossily as `x�y`, which names no file, so
  the save packed the tree without it and every hit restored a tree
  missing that file under an unchanged key. vx now refuses such a name
  by name; an artifact saved before the fix is the wrong bytes, so v31
  entries are not trusted.
- **v30 → v31**: stored bytes wrong under a key the fix does not change
  (item 726), v30's shape for a sibling. A sandboxed task that declared
  `cache` was granted every workspace package linked in its
  `node_modules`, so it could import a sibling its key never folded and
  save what it built. The fix withholds that link unless the key answers
  for the package (§ Cross-project boundaries), so the next miss fails
  on the read; but an entry saved before it still hits when only the
  sibling changes. Probed, not argued: an entry saved by the previous
  commit, `@x/ui` edited, then this commit's run under v30 reported
  `up-to-date` and left the old `ui` in `dist/`; under v31 the same run
  misses and fails on the read, with the hint.

- **v29 → v30**: stored bytes wrong under a key the fix does not change
  (item 720). npm and Yarn link every workspace package at the root, the
  task's own included, and the sandbox granted every link target whole,
  so a sandboxed task was handed its own project back whatever its
  `allow.read` said. An undeclared read of its own file ran unreported
  and the result was saved under a key that never saw that file. The fix
  withholds the self-link, so the next miss fails on the read; but an
  entry saved before it hits for as long as only that file changes.

- **v28 → v29**: every key moves, and the bump is for the notice, not
  for wrong bytes (item 682). The key is a seed-chained xxHash3 fold,
  one step per field and per input file, and Bun's xxHash3 reads only
  the low 32 bits of its seed: a bare chain carried 32 bits of state, so
  two input sets whose running digests shared their low halves merged at
  the next step, a stale hit at about 2^-32 per step rather than 2^-64.
  A birthday search over 2^17 values of one env variable found two that
  gave one `Cache.key` in under a second. `xxh3` now feeds the seed
  forward (`xxHash3(part, seed) ^ seed`): states that share their low
  half keep their high-half difference through every later step. The
  old keys were wrong but their stored bytes are not, so the fix alone
  is self-healing; without the bump every entry would miss silently.

- **v27 → v28**: stored bytes wrong under a key the fix does not change —
  the v25/v26 shape (item 667). A bracket in a task glob became a literal
  character; before, `Bun.Glob` read it as a character class. An INPUT
  glob over a route directory folded the wrong files, and that fix is
  self-healing: the file set, and so the key, moves. An OUTPUT glob is
  not: `outputs: ['app/[id]/page.js']` folds as its text, which the fix
  leaves unchanged, and the entries under it hold nothing (or the class's
  namesake `app/i/page.js`). Proven through a real run: an entry written
  by v27 code, read by the fixed code, was a `cache-hit` that cleaned
  `app/[id]/page.js` and restored nothing; under v28 it is a miss, and
  the next hit restores the route.

- **v26 → v27**: the artifact CONTAINER changed, so the stored bytes
  under an unchanged key are no longer readable the same way — the
  layout case, not the wrong-bytes case. Packing moved from a `tar`
  subprocess (with a staged copy of every output and a per-host
  `--format=gnu` / `--format=gnutar` probe) to `Bun.Archive`, and the
  per-entry mode + millisecond mtime that tar headers carried natively
  now ride a `.vx-meta.json` sidecar. Measured on the real `Cache.save`
  path (300 outputs / 12 MB, min-of-5, interleaved arms against a
  `git worktree` of the previous commit): **158 ms → 11 ms** to pack,
  the artifact grows ~7 compressed bytes per output for the sidecar.
  Restore is indistinguishable up to ~12 MB, but on a 150 MB
  incompressible artifact it costs +28% time and +19% peak RSS
  (74 → 95 ms, 575 → 683 MB peak, fresh process per arm): `files()`
  returns entries that OWN their bytes, so they coexist with the
  decompressed tar where the old reader returned views into it. Peak is
  ~4.5× artifact size, up from ~3.8×. The bump is mandatory rather than
  self-healing: a v26 artifact has no sidecar, so a v27 reader would
  restore its outputs mode-0644 and mtime-now — silently wrong on disk
  rather than a miss. Since 2026-09-03 the same layout is written and
  read by vx's own streaming tar code (no bump: the bytes are readable
  either way), and the peak above is history — save, ingest and restore
  hold one chunk now; see § Storage layout.

- **v25 → v26**: the same shape as v25 — stored bytes that are wrong
  under a key nothing about the fix changes — reached by a different
  producer. A task whose child was killed by a shutdown signal reports
  `aborted`, but `aborted` did not propagate to dependents the way
  `failed` and `skipped` do. So a dependent ran against the aborted
  task's PARTIAL outputs, succeeded, and cached what it had built.
  Because a dependent's key folds its upstream's INPUT key — and a
  signal changes no input — that entry sits under exactly the key a
  healthy run derives, and the next run replays it as a green hit with
  exit 0. Reproduced end to end: run 1 killed mid-write leaves
  `PARTIAL`, run 2 is fully healthy and still serves `PARTIAL` from
  cache.

  Making `aborted` propagate stops new poison but cannot reach entries
  already written, and a `LayeredCache` uploads them — so the reach is
  a whole team's shared cache, not one developer's disk. That is what
  makes the trade worth it: one cold rebuild against a class of
  silently-wrong output. The interactive Ctrl-C path was never the
  vector (vx's handler exits before a dependent can cache); the
  reachable ones are an external `kill`, a supervisor, `docker stop`, a
  self-terminating script, and every `handleSignals: false` embedder —
  which includes `vx watch` and the distributed agent loop.

- **v24 → v25**: the ARTIFACT BYTES in every existing entry are wrong
  while the key addressing them is unchanged — the one situation a
  version bump exists for, and the opposite of the recent self-healing
  no-bump cases. Two defects on the pack/restore path, both silent data
  loss on an ordinary cache hit with no attacker involved:
  - **The executable bit was stripped from every cached output.**
    `packArtifact` staged each output with `Bun.write`, which creates
    the destination under the process umask and does NOT carry the
    source's mode, so the tar header recorded 0644 and the restore
    faithfully reproduced 0644. Any build emitting a CLI shim, a
    compiled binary or a generated script worked cold and broke warm —
    including this repo's own `build.bun.*` release binaries. Fixed by
    chmod-ing each staged copy to the source's mode.
  - **Outputs whose archive entry name exceeded 100 bytes were dropped
    on every restore.** POSIX ustar splits such a name into
    `prefix` + `name`; the reader read only `name`, which no longer
    starts with `outputs/`, so the file was neither restored nor
    indexed. Not self-healing: with no `output_files` row, the
    skip-restore check compared a truncated expectation against a
    truncated tree and agreed forever. Threshold is a
    project-relative output path of ~93 chars — ordinary for a modern
    bundler. Fixed by reading `prefix` (gated on the POSIX magic, since
    GNU headers reuse those bytes for atime) AND by packing
    `--format=gnu`, which carries long names in an `L` record.

  The format switch also fixes a working build being reported as
  FAILED: ustar cannot split a single path COMPONENT over 100 bytes and
  exits non-zero ("file name is too long (cannot be split)"), which
  `packArtifact` raised _after_ the task had already succeeded. 120-char
  filenames are legal everywhere and routine in snapshot/fixture trees.

  Shipped with three defence-in-depth fixes that needed no bump of their
  own: `restoreOutputs` now throws instead of returning quietly when the
  artifact is gone or cannot produce an output the index recorded (the
  caller has already wiped the declared outputs by then, so a quiet
  return reported a green hit over an emptied tree — reachable via a
  concurrent `vx cache prune`); the tar reader rejects an entry whose
  declared size runs past the end of the archive (`subarray` clamps, so
  it used to install short, NUL-padded content as a cache hit instead of
  degrading to a miss); and directory entries now get the same
  containment + realpath checks as file entries (`mkdir` follows a
  pre-existing symlink, so directories could be created outside the
  destination). No `SCHEMA_VERSION` bump — no table changed.

- **SCHEMA v23 → v24 (no `CACHE_VERSION` bump)**: `file_hashes` gains
  `ctime_ms` + `ino`. The memo keyed on `(mtime, size)` alone, and its
  row persists across runs, so any producer that preserves mtime —
  `tar -x`, `unzip`, `cp -p`, `rsync --times`, a `SOURCE_DATE_EPOCH`
  generator — got the previous run's digest for genuinely different
  bytes: a stale cache hit. `utimes` cannot suppress ctime
  unprivileged and an atomic write-then-rename changes the inode, so
  the two together close it (git's index keys on ctime+ino+dev for the
  same reason); both come free from the stat already taken. The key
  DERIVATION is unchanged — the memo simply stops answering wrongly —
  so an affected task's key moves from a wrong value to the right one:
  it misses once, re-runs, re-caches. Self-healing, never a wrong hit.
  Landed alongside two other stale-hit fixes that needed no schema
  change: the cache-miss path now marks the outputs `cleanOutputs`
  wiped (it was the only one of four sibling call sites that dropped
  the return, so a deleted output kept a live index OID and stayed in
  a consumer's input set), and `skip-worktree` / `assume-unchanged`
  entries no longer keep a trusted OID (they sit at stage 0 and
  `git status` reports nothing for them, so a sparse-checkout path
  that was absent from disk still counted as an input). The schema
  gate drops + recreates on the version mismatch (pre-alpha, no
  migration), so this costs one cold rebuild.
- **SCHEMA v21 → v22 (no `CACHE_VERSION` bump)**: Tier-3 dashboard
  tables — `invocations` (one header row per `vx run` with command,
  git/CI/host context, tags, and run-level counts, recorded with `runs`
  via `Cache.recordRunBundle`) and `entry_inputs` (one row per cache-key
  component, keyed by the cache-ENTRY hash — the input-fingerprint
  moat). `entry_inputs` is written **inside the entry-save transaction,
  only on a cache miss** (`INSERT OR IGNORE`), so a warm all-cache-hit
  run writes nothing for the moat — Tier 3 has **zero warm-run cost**.
  The cache KEY derivation is unchanged: these tables persist components
  already fed to `Cache.key()` (captured via a pure side-channel,
  `CacheKeyInput.captureInto`, at the same fold sites — only on a miss),
  so existing artifacts stay valid and `CACHE_VERSION` stays `v24`. The
  schema gate drops + recreates on the version mismatch (pre-alpha, no
  migration).
- **v23 → v24**: exclude `vx-lock.json` from the input file set
  globally (`ALWAYS_IGNORE` in `cache/inputs.ts`). The lockfile is
  committed, so git enumerates it, but it's vx's own frozen-config
  metadata — never a task input. Without this, a `vx lock` re-write
  busts every key on a project that globs the root lockfile (a broad
  `**/*` on the root project). Tasks whose `cache.inputs.files` never
  matched it derive byte-identical keys. No SCHEMA bump — only the
  hashed file set changed, not the key layout or on-disk format.

- **v22 → v23**: fold `cache.inputs.runtime` / `workspaceRuntime`
  command output into the key (two namespaced sections after
  env-values). The command _strings_ stay in the config hash (step 5);
  their combined trimmed stdout+stderr is resolved live at hash time
  and folded as `runtime-values:` (project-cwd) and `ws-runtime-values:`
  (root-cwd) sections, each `command\0output`. No SCHEMA bump — only
  `Cache.key` derivation gained two sections; the on-disk format is
  unchanged. Tasks declaring neither field fold a `:0` count for both
  and derive byte-identical keys to before the bump.

- **v21 → v22: pure-input transitive** (+ SCHEMA v21): reverted the v21
  output-fold. Downstream keys fold the upstream's **input key** (its
  own task hash) — a pure function of the filesystem, like Turbo/Nx.
  No output content participates in any cache key. **Early cutoff is
  gone**: an upstream that re-executes (comment edit, env change) but
  reproduces byte-identical output now still re-runs its dependents.
  This was a deliberate simplification — cutoff is rare in practice
  and not worth the cascade complexity (it forced output content into
  keys, which blocks any upfront/batched probe). **Multi-state is
  preserved**: branch ping-pong A→B→A still re-hits, because the
  upstream's _input_ differs per state and folds transitively into
  every dependent key. SCHEMA v21 drops the now-unused `outputs_hash`
  column; `CacheLayer.save` returns `void`.

- **v20 → v21: early cutoff** (+ SCHEMA v19, **reverted in v22**):
  downstream keys folded the upstream's output content identity
  (`outputsHash`) instead of its task hash. Removed — see v22.

- **v7 → v8** (PR #2): folded `forwardArgs` into the key for CLI
  argument-forwarding alignment.
- **v8 → v9** (PR #3): `TaskConfig` shape changed — `exec` collapsed
  from an array to a single command, `tasks` nested under `run`.
- **v9 → v10** (PR #7): on-disk layout switched from per-entry
  `meta.json` + `outputs/` directory to a workspace-wide `cache.db`
  (SQLite) plus output files directly at `<hash>/` and log files at
  `logs/<hash>.{stdout,stderr}`. Adds run history for `vx stats`.
  Removes the per-entry manifest.
- **v10 → v11** (PR #19): analytics columns added to the `runs`
  table: `run_id` (UUIDv7), `cpu_ms`, `peak_rss_bytes`,
  `wallclock_start_ns` / `wallclock_end_ns`, `cache_hit`. All
  nullable; directly queryable via `sqlite3 cache.db`. The on-disk
  `<hash>/` layout itself was unchanged.
- **v11 → v12** (PR #42): project's `package.json` bytes folded into
  every task's cache key implicitly. Matches Turbo / Nx "implicit
  dependencies" behavior — a `package.json` dep change invalidates
  the project's tasks even when `cache.inputs.files` is narrow and
  doesn't cover the file.
- **v12 → v13** (PR #65): per-entry on-disk layout unified. Outputs
  moved from `<hash>/<rel>` (mixed with metadata) to
  `<hash>/outputs/<rel>`; stdout / stderr moved from the sibling
  `logs/<hash>.{stdout,stderr}` into `<hash>/stdout` and
  `<hash>/stderr`. Eviction collapses to a single `rm -rf <hash>/`.
  Also dropped the runner's `logs/<run_id>/<project>__<task>.{stdout,stderr}`
  dump — output is already streamed live, surfaced on the outcome
  object, and the cache entry covers successful runs; CI captures
  parent stdout natively. The duplicate sibling dump was pure
  redundancy.
- **v13 → v14**: file enumeration switched from a `Bun.Glob` walker
  with our own `ignore`-library filter to `git ls-files --cached
--others --exclude-standard`. Matches what Turborepo and Nx both do
  at the bottom of their hash pipelines. Side-effects user-visible:
  (a) nested `.gitignore` patterns are anchored to the gitignore's own
  directory, fixing the v13 footgun where `pkg/.gitignore: src/skip.ts`
  was misinterpreted as `<workspaceRoot>/src/skip.ts`; (b)
  `.git/info/exclude` and global excludes participate; (c)
  untracked-but-not-ignored files enter inputs immediately (no
  `git add` required). (The non-git fallback walker was later removed
  entirely — vx hard-requires git; a non-repo workspace gets a clean
  `UserError` telling the user to `git init`.)
- **v14 → v15**: cache-key hash swapped from SHA-256 (via
  `Bun.CryptoHasher`) to xxHash3 (via `Bun.hash.xxHash3`). Key strings
  shrink from 64 hex chars to 16, matching Turbo's xxh64 output width;
  derivation is ~5× faster, dominating the cache-warm path that
  hashes hundreds of input files. xxHash3 has no streaming Hasher
  API, so `Cache.key()` chains via the seed parameter (each
  `xxh3(part, prevDigest)` folds one field into the running digest)
  and `hashFileFromDisk` reads the whole file before hashing — fine
  for source files (typically < 1MB each); the throughput win
  outweighs the memory hit. `SCHEMA_VERSION` bumps to `v15` at the
  same time (PR #86 already took `v14` for the tar.zst artifact
  layout): the `file_hashes.sha256` column is renamed to
  `content_hash`, and the schema-mismatch path now `DROP`s the stale
  tables before `CREATE TABLE IF NOT EXISTS` runs so the rename
  actually takes effect on existing DBs. Non-cryptographic by design
  — cache keys never need collision resistance against an adversary,
  just uniqueness across honest inputs.
- **v15 → v16** (PR #86 series): artifact storage moved to a single
  compressed `<hash>.tar.zst` per entry; the manifest.json entry was
  dropped (file fingerprints live in the `output_files` table).
- **v16 → v17**: artifact narrowed to exactly `stdout` +
  `outputs/<rel>` — no `meta.json`, no stderr (only successful runs
  are cached and their stderr is near-always empty noise). Local and
  remote layers transport the same bytes end-to-end; entry metadata
  lives solely in SQLite.
- **v17 → v18**: env-value folding in `Cache.key()` switched its
  name/value delimiter from `=` to `\0`. `${n}=${v}` was ambiguous —
  `("A", "B=C")` and `("A=B", "C")` folded identical bytes. Env names
  containing `=` are unreachable from a real POSIX environ, so this
  is contract hardening rather than a field bug, but the key
  derivation's stated invariant is unambiguous part boundaries —
  now it holds everywhere (file inputs already used `\0`).
- **v18 → v19**: `'^task'` dependsOn expansion switched from
  transitive-deps to nearest-holder frontier semantics (Turbo/Nx
  direct-deps parity, plus vx's sparse bridging through deps that
  don't declare the task). Task graphs lose the redundant deep edges,
  so the filtered-upstream-hash set (step 10) shrinks for any task
  whose deps chain `'^task'` themselves — same inputs now derive a
  different key. Reachability/ordering is unchanged whenever holders
  chain `'^task'` (the universal pattern); a holder that doesn't is
  now the documented stopping point. No on-disk format change.
- **v19 → v20**: input-file content hashes switched from xxh3 to
  **git blob OIDs** (Turbo's technique). The bulk enumeration spawn
  became `git ls-files -s --others --exclude-standard` — `-s` lines
  carry `<mode> <oid> <stage>\t<path>` for tracked files, so one
  spawn yields the file list AND the index OIDs; a second
  `git status --porcelain -z` spawn prunes OIDs for paths whose
  working tree diverges from the index (renames drop both sides;
  stage>0 conflict entries never get one; symlinks did not either
  until 2026-09-09, when the fallback started hashing a link the way
  the index does). A clean
  tree's key derivation does zero reads / stats / SQLite per file.
  Everything else falls back to `Cache.hashFile`, which now computes
  the identical blob OID in-process (object format auto-detected via
  `git rev-parse --show-object-format`, sha1 default) behind the
  existing mtime+size memo. `SCHEMA_VERSION` bumps to `v18` in the
  same change: pre-v20 `file_hashes.content_hash` rows store 16-hex
  xxh3 digests that must not leak into the OID domain through the
  memo. File-set visibility semantics are unchanged (verified: the
  `-s --others` path set is identical to `--cached --others`,
  including staged-but-deleted files and per-stage conflict
  duplicates).

---

# CLI reference

> The vx binary is the user-facing entry point. The implementation is

The `vx` binary is the user-facing entry point. The implementation is
intentionally simple: a hand-rolled argv parser (no commander / yargs)
in `src/cli/index.ts` dispatches to per-subcommand handlers under
`src/cli/<name>.ts`. The flag surface is aligned with
[Turborepo's `turbo run`](https://turborepo.com/docs/reference/run)
so existing Turbo users can swap in with minimal muscle-memory churn.

```sh
# Standalone binary via npm (no Bun required on target):
npm install -g @vzn/vx

# From source (Bun ≥ 1.4):
bun src/bin.ts --version
```

Below that floor vx still runs, and `vx info`'s `bun` row says so, because
what an older Bun breaks is the ANSWER, not the start: a large `--format json`
write is truncated mid-stream, no task reports what it used, and a config
syntax error surfaces as an internal error rather than the usual message.
[`modules/util-bun-version.md`](../modules/util-bun-version/) has the
measurements and why the verdict lives on that row rather than on stderr. The
released binary carries its own Bun and the row never says it.

## Top-level shape

```
# Core
vx run [OPTIONS] [TASK | PKG#TASK ...] [-- forwarded-args...]
vx watch [OPTIONS] TASK [-- forwarded-args...]
vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--format pretty|json] [--cache-dir <path>]
vx lock [--check] [--format pretty|json]
vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]
vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--format pretty|json]
vx info [--format pretty|json] [--cache-dir <path>]
vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]
vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]
vx upgrade [TAG]      # self-update a compiled binary
vx docs <query> [--limit N] [--format pretty|json]
vx completions bash|zsh|fish

# Meta
vx                    # in a workspace, vx --help; outside one, says so and exits 1
vx help [VERB]
vx --help, -h
vx version
vx --version
```

Each verb's lines are the usage lines `vx <verb> --help` prints, word
for word (`tests/cli-help-synopsis.test.ts`); the flags a verb accepts
are read from that line.

Multiple positional tasks run in one orchestrator invocation with a
shared task graph: `vx run build lint test` fans out all three across
the resolved project scope. Anchored entries (`pkg#task`) target a
specific project; bare entries follow the usual scope rules
(default = the cwd project; broaden with `--all` / `--filter` /
`--affected`). The cwd project is the deepest member holding the
directory, a member reached through a link (`packages/b -> ../ext/b`)
included.

**Every requested name must resolve.** If any positional matches no
project in scope, the run refuses to start — `vx run: no projects
declare task(s): &lt;name&gt;.` on stderr, a run and `--dry` / `--graph` alike
(a run printed it to stdout until 2026-10-03), exit 1, with `Did you mean <task>?` when a
declared task (or, for `pkg#task`, a runnable spec) is within two edits,
and with no name that near, what exists: `Tasks: build, test.`, `No
project is named zzz; projects: a, b.`, or `a's tasks: build, test.`
(M-56),
and with `Only projects outside the selection declare &lt;name&gt; — pass
--all, or --filter to pick them.` when the run was scoped (the cwd's
project, a `--filter`) and a project outside the scope declares it
— even when the other names resolved fine. A bare name declared by only SOME projects is normal and stays
green; the guard fires only when a name matched nowhere. So a CI job
running `vx run lint test typecheck` goes red the day `typecheck` is
renamed, instead of silently running two of three. Under a scope a git
diff chose (`--affected`, a `[ref]` filter) a bare name is judged against
the whole workspace instead, since which projects hold it depends on what
changed: `vx run test --affected` after a commit that changed only a
project without `test` exits 0 with `No affected project declares
task(s): test.`, and a name no project declares is still refused (item
1024). A change that reaches no requested task exits 0 with `Nothing
affected: the change reaches no test task.` A diff that touched no project stops before that check:
`nothing affected since <ref>` on stderr, exit 0, a typo unseen.

(No `-V` for version; `vx --version` only — matches Turbo.)

`vx <verb> --help` (and `-h`, and `vx help <verb>`) prints this reference
cut to that core verb — its usage lines and sections, then
`Full reference: vx help` —
and every argument error points at it. `vx help <name>` for a name that
is no verb here (core, a plugin's, or a moved one) is refused as
`vx <name>` is: one line, a guess when one is close, exit 1.
Past a `--` the flag belongs to the command being run, so
`vx run build -- --help` forwards it to the task instead. A plugin verb
owns its own arguments, `--help` included.

## `vx run`

```
vx run [OPTIONS] [TASK | PKG#TASK ...] [-- forwarded-args...]
```

Run the named task(s). By default only the project containing the
current working directory is selected — `dependsOn` still expands so
the project's upstream workspace deps run too. Override with `--all`,
`--filter`, `--affected`, or an explicit `pkg#task`.

If no task name is given:

- **In a TTY** — an interactive picker lists every `pkg#task` entry
  across the workspace (only the selected projects' under `--filter` /
  `--affected`; `--affected` selecting nothing exits `0` as a run does), prints `description` next to each, prompts
  for a number, runs the chosen one. The menu and prompt go to stderr,
  so `vx run > out.txt` still asks on the terminal. Ctrl-C at the prompt exits `130`
  as an interrupted run does; Ctrl-D exits `1` with `no task picked`.
  A workspace with no task exits `1` naming how to declare one (under
  `tasks` in a vx.config, or `vx init`).
- **Not a TTY** — exits `1` with
  `missing task name (stdin is not a TTY, so no picker; tasks here: build, test)`,
  naming the cwd project's tasks, else every project's (twelve, then
  `and N more`); outside a workspace it reads `vx run <task>, e.g. vx run build`.
- **Under `--format json` or `--dry=json`**, on a terminal too — the
  same refusal (`a JSON answer opens no picker; …`), with the
  `VX_E_USAGE` error document on stdout: a program cannot pick.

Exit codes:

| Code                  | When                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`                   | Every task finished `success` or `cache-hit` (local or remote); or `--affected` left no project that declares the task.                                                                                                                                                                                                                                                                     |
| `1`                   | At least one task ended `failed` or `skipped`; a persistent task exited non-zero after it was ready; a task name no project declares; or parse/setup error.                                                                                                                                                                                                                                 |
| `130` / `143` / `129` | Interrupted (SIGINT / SIGTERM / SIGHUP): each task's process group (the task and what it forked) gets vx's signal once (a SIGHUP as a SIGTERM), `VX_KILL_GRACE_MS` (2 s) to go, then SIGKILL; a second signal skips the grace. vx then dies of the signal, so a shell script running it stops too (a run that handed a task the terminal exits with the code, so the terminal is restored). |

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:
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.

A reader that leaves does not change the code. `vx run build | head -1`
closes the pipe after one line; the run still finishes, saves what it
built and releases its lock, and exits with its own verdict — the
output after that point goes nowhere (`EPIPE`, on stdout or stderr, is
not an error vx reports). Before 2026-09-16 the same pipeline died with
a stack and exit 1 after its task had succeeded.

### Selection

| Form                          | Effect                                                                                             |
| ----------------------------- | -------------------------------------------------------------------------------------------------- |
| (default)                     | The project that contains cwd. Errors if cwd is not inside a project.                              |
| `pkg#task`                    | Just that project.                                                                                 |
| `//#task`                     | The root project's task (Turbo's spelling; the root is a project, D-39).                           |
| `--all`                       | Every project that declares the task.                                                              |
| `--filter <pat>` (repeatable) | pnpm-style filter DSL (see below).                                                                 |
| `--affected[=<base>]`         | The tasks a git change reaches: the ones it touches and those whose `dependsOn` closure holds one. |

Combining: every include (`--filter <pat>`, `--affected`) is taken
first and every `!` exclude after them all, as pnpm does, so an
exclude removes what any include added, whichever side of it it sits
(items 955, 979). The union holds for tasks too: `--affected --filter
other` runs other's tasks whether or not the change reaches them
(X-10). `--all` with a filter is the filter's selection:
the filters refine it rather than being overridden by it
(`--all --filter '!docs'` is everything but docs).

### Filter DSL (`--filter`)

The full DSL lives in `src/workspace/filter.ts`; this is the user-
facing summary.

A filter that matches nothing refuses the run (`no projects matched
filter(s): …`) with `Did you mean &lt;name&gt;?` when a project name is within
two edits, or when exactly one scoped project's name after its `/` is
(`--filter vx-mcp` hints `@vzn/vx-mcp`), and `Projects: a, b` otherwise
(M-56). A list names eight, then a count. An unmatched `tag:` filter
hints the nearest tag instead (`Did you mean tag:scope:web?`), else
lists the tags. When every pattern matched and an exclusion took back
all of it, the refusal names the exclusion instead (`no projects
selected: !app excluded every project the other filters matched`).

| Form              | Meaning                                                                                                                                                                                                                                                                                                                                 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<pattern>`       | Match by package name. `*` matches any characters, including `/`. A pattern matching no package may leave out the scope, as pnpm reads it (`cart` is `@nx-example/cart` when one package carries it). One holding a `/` outside a scope that matches no package is a directory, as Nx's `--projects` reads it (`apps/*` is `./apps/*`). |
| `./<dir>`         | The package at `<dir>` alone, as Turbo and pnpm read it (`.` is the root project); a `<dir>` that is no package matches the packages under it (relative to workspace root; D-43).                                                                                                                                                       |
| `{<dir>}`         | Same as `./<dir>`.                                                                                                                                                                                                                                                                                                                      |
| `./<glob>`        | A glob over root-relative project dirs: `./packages/*` (direct children), `{apps/**}` (nested too; a trailing `**` matches zero dirs, so `./packages/kit/**` holds kit itself, as pnpm and Turbo read it). A path that names a project dir literally is read literally first, so `./packages/[abc]` is that directory.                  |
| `.`               | The root project alone, when the root is a project (D-39); otherwise the packages under the root, i.e. every package, not the one you are standing in.                                                                                                                                                                                  |
| `//`              | The root project alone, Turbo's name for it; matches nothing when the root is no project (D-46).                                                                                                                                                                                                                                        |
| `tag:<pattern>`   | The projects whose config `tags` hold a match, as Nx's `tag:` reads them (`*` as in a name). Takes every operator a name takes: `!tag:x`, `...tag:x`, `tag:x^...`, `tag:x[main]`. Nx's `--projects tag:x` aliases it.                                                                                                                   |
| `<pattern>...`    | Match + all transitive dependencies (see below what an edge is).                                                                                                                                                                                                                                                                        |
| `...<pattern>`    | Match + all transitive dependents.                                                                                                                                                                                                                                                                                                      |
| `<pattern>^...`   | Only the transitive dependencies, excluding the matched package itself.                                                                                                                                                                                                                                                                 |
| `...^<pattern>`   | Only the transitive dependents, excluding the matched package itself.                                                                                                                                                                                                                                                                   |
| `...<pattern>...` | Match + its dependents + the dependencies of all of them, as Turbo selects (`...db...` takes the packages the apps that use db build on).                                                                                                                                                                                               |
| `<sel>[<ref>]`    | The packages `<sel>` (a name pattern or `{<dir>}`) selects that changed since `<ref>`, as Turbo and pnpm read `@scope/*[main]` (D-44).                                                                                                                                                                                                  |
| `<sel>...[<ref>]` | The packages `<sel>` selects that changed since `<ref>` or depend on one that did; no dependency is added (Turbo: `@acme/api...[HEAD]` is api when only its dependency changed).                                                                                                                                                        |
| `!<pattern>`      | Exclude packages matching `<pattern>`, from everything the includes select, in any order.                                                                                                                                                                                                                                               |
| `[<git-ref>]`     | Projects whose files changed since `<git-ref>` (`main`, `HEAD~5`, …).                                                                                                                                                                                                                                                                   |

An edge is a `package.json` workspace dependency (`dependencies`,
`devDependencies`, `peerDependencies`, `optionalDependencies`; a peer
that would close a cycle counts for selection only, see
`modules/package-graph.md`) — an entry the package manager links to a
workspace package, not one whose key merely names it:
`"shared": "^1.0.0"` beside a local `shared@2.0.0` is a registry
dependency and no edge, and `"luigi": "workspace:../waluigi"` is an
edge to `waluigi` (the rule: `modules/package-graph.md` § Which entries
are edges) — OR a
cross-project `dependsOn` entry (`e2e`'s `test: { dependsOn:
['app#build'] }` makes `e2e` a dependent of `app`). The task graph knows
both, so selection follows both: `vx run test --filter '...app'` runs
`e2e#test` even though `e2e` has no manifest dependency on `app`. There
is no `implicitDependencies` field — declare the edge where the task
needs it.

A filter that names no project (`...`, a bare `!`) is refused, and one
whose pattern matched but whose walk selected nothing says what it
matched: `no projects selected: filter "...^core" matched core, and no
project depends on it` (item 1030).

Examples:

```sh
vx run build --filter @scope/*                # all packages under @scope
vx run build --filter app...                  # app and its transitive deps
vx run build --filter ...util                 # util and everything depending on it
vx run build --filter app^...                 # only app's deps (not app)
vx run build --filter '*' --filter '!docs'    # everything except docs
vx run build --filter '[origin/main]'         # projects with files changed since main
```

### `--affected[=<base>]`

Run the task only in projects whose files changed since `<base>`.

- `--affected` (no value) uses the workspace's `affectedBase` when it
  names one (`nx()` and `turbo()` set it from `NX_BASE` / nx.json's
  `defaultBase` and `TURBO_SCM_BASE`, `turbo()` on GitHub Actions from
  the pull request's base or the push's `before`, as Turbo does;
  [schema](../schema/)), else
  `origin/HEAD`; without one (actions/checkout sets none, nor does a
  repo with no remote), the first of `origin/main`, `origin/master`,
  `main`, `master` that is not HEAD itself, as Turbo and Nx compare with
  `main` (D-93); else `HEAD~1`. A clone with neither — a
  CI checkout at `fetch-depth: 1` — has no base at all, and vx says so
  (`--affected has no base here … a shallow clone?`) instead of failing
  on a `HEAD~1` nobody typed. And when the base IS the commit you are
  on (a single-branch clone whose `origin/HEAD` is the branch under
  test), the `nothing affected since <ref>` note says the ref is HEAD
  itself and names the two bases you probably meant
  (`--affected=origin/main`, `--affected=HEAD~1`).
- Without git on PATH, every shape is one line — `vx requires git:
failed to spawn 'git' … Install git and re-run` — the same the input
  enumeration prints; a minimal image met a stack here before
  (2026-09-16). Outside a git work tree every shape says `vx requires
git: &lt;root&gt; is not inside a git work tree`, as a plain run does, and a
  repository with no commit yet says so, not "a shallow clone?" (X-52).
- `--affected=<ref>` uses the given git ref. A value that is empty or
  starts with `-` is refused before git sees it: the ref is an argument,
  never a shell command, and an option-like one (`--output=<path>`)
  would be a real `git diff` option. A range (`HEAD~1..HEAD`,
  `main...feature`) is refused there too, naming the base to pass
  alone — `ranges are not supported — pass the base alone ("HEAD~1")`
  — because the other end is always the working tree; `<base>...HEAD`,
  Turbo's CI spelling, is read as `<base>`, since vx diffs from the merge
  base to a working tree that holds HEAD (D-117). Its two-dot `<base>..HEAD` diffs from
  `<base>` itself, not the merge base. An exclusion (`^main`) is refused
  the same way, naming `main`. A ref that does
  not exist is `git ref "<ref>" did not resolve`; in a shallow clone (CI's
  one-commit checkout) it adds that the clone is shallow and how to fetch
  the history (`git fetch --unshallow`, `fetch-depth: 0`). A ref naming
  a path inside a commit (`main:packages`) is refused, naming the commit
  to pass: its paths lack the prefix, so the diff would select the wrong
  projects. A root tree (`main^{tree}`) is still a base.
- A member whose directory is a symlink to a place elsewhere under the
  workspace root (`packages/b -> ../ext/b`) is selected by a change at
  that real place too: git names the files where they live, not by the
  link (item 1079). A link to a directory outside the root is outside
  git's view, and a change there selects nothing.
- The diff runs from the **merge base** of the ref and `HEAD`, not from
  the ref itself, so a branch whose base has moved on sees only its own
  changes — never the files other people landed on `main` since it
  forked (Turbo and Nx do the same). Refs with no common ancestor diff
  from the ref.

**It selects the tasks the change reaches (owner, 2026-10-04).** A
change seeds tasks in the projects it touches:

- a cached task when a changed path is one of its declared inputs
  (`files`, `workspaceFiles`), or a changed submodule or embedded
  repository is one its `workspaceFiles` may reach into (git reports it
  as one path; a glob whose fixed prefix is above or inside it counts);
- every task of a project whose `package.json` or `vx.config.*`
  changed, or that holds a changed path no cached task of its declares
  (vx cannot prove that path re-keys nothing), or that holds a changed
  submodule or embedded repository (git reports it as one path, and no
  task's globs can say whether they reach inside), or that a lockfile
  claim, a manifest edge at the base or a config import names;
- an uncached task when a changed path lies in its project or the
  project is reached whole; a root file another task of its declares
  (`workspaceFiles`) is no change there. A group seeds nothing.

A requested task runs when its `dependsOn` closure holds a seeded task,
so a change reaches another project only along a task edge. With
`app#test` behind `^build`, an edit to `ui/src/button.ts` that
`ui#build`'s inputs read runs `ui`'s tasks and `app#test`; an edit to
`ui/src/button.test.ts` that only `ui#test` reads runs `ui#test` alone,
and `app#lint`, which depends on nothing, never runs for a change in
`ui`. A `pkg#task` you name runs whatever the diff. This is the edge
the cache key folds (a cached `app#test` with no edge to `ui` never
sees `ui`'s files either). A project that declares no `build` gets one
keyed on all its files (`schema.md`), so any change there reaches a
dependant behind `^build`; a package `^name` passes through for want of a
config reaches it the same way.
The graph is the one a `graph` plugin leaves: an edge or an input it
adds reaches a task as a declared one does, and a task it marks
requested runs whatever the diff. With such a plugin every project is a
candidate once the diff touched anything, and its hook sees every
candidate task before the selection prunes the graph.
Nx 23.3 (`NX_LEGACY_AFFECTED=false`) and Turbo
(`affectedUsingTaskInputs`) select tasks the same way, behind flags.

Until 2026-09-16 the sugar was the changed-only `[<base>]` form (item
287), and until 2026-10-04 it took every task of every manifest
dependent, which the filter forms still do:

```bash
vx run test --affected                # the tasks the change reaches
vx run test --filter '...[main]'      # what changed + every dependent project
vx run test --filter '[main]'         # only the projects that changed
```

Its candidate projects are `--filter '...[<base>]'`'s; both are resolved by
`src/workspace/affected.ts`, which unions `git diff` against `<base>`
with `git ls-files --others` so a brand-new untracked source file counts
as a change (input hashing sees it, so `--affected` must too). A
project inside a submodule or an embedded repository is selected when
git reports that repository changed — a dirty or moved submodule
(`vendor/sub`), an untracked embedded repository (`vendor/nested/`):
the workspace repository sees the nested one as a single path (`git
diff --raw`'s gitlink mode, 160000, on either side names one), so a change inside is a
change to it, and every project under it is selected, the project that
holds it included. A repository's own request to hide submodules from a diff
(`diff.ignoreSubmodules`, `submodule.<name>.ignore`) does not apply:
the key sees the change whatever git is told to show.
`vx-lock.json` is filtered out of the changed set — a `vx lock`
re-write never marks every project affected.

**A lockfile change selects everything.** The root lockfiles,
`pnpm-workspace.yaml`, `.yarnrc.yml`, `.npmrc`, `bunfig.toml` and the patches `bun.lock` names are folded into the [workspace
fingerprint](../caching/), which is part of _every_ task's cache key —
so a `bun install` / `pnpm update` invalidates the whole cache. Those
files sit at the workspace root and belong to no project, so mapping
changed paths to project directories would select nothing; `--affected`
widens to every project instead, for the same reason it unions in
untracked files. Only the ROOT copies count: a lockfile vendored inside
a package is not hashed and selects just that package. A lockfile a
plugin CLAIMS (`VxPlugin.fingerprint`, e.g. `pnpm-lock.yaml` under
`@vzn/vx-lockfile`) is the exception on both sides: the key folds what the
plugin says per project, so `--affected` asks the plugin which projects
the change touches — given the bytes at the base ref and in the working
tree — and selects those; only a plugin that cannot tell widens.

**A dropped edge selects its dependent.** A package the change deleted
(its `package.json` was there at the base and is gone) is no project
now, so its paths map to nothing; and one whose `version` or `name`
moved may no longer satisfy what a dependent declares (`lib: ^1.0.0`
after a bump to 2.0.0). Either drops an edge the dependent's key folded,
while today's graph shows no dependent to walk to. So the package graph
is built again over the changed manifests as the base had them, and
every project whose workspace dependencies differ is selected, and so
is a project whose task names a removed or renamed package in
`dependsOn: ['lib#build']`, an edge the package graph cannot see
(item 1085). An edit to the root manifest's `workspaces` selects every project:
which packages left the workspace is a discovery at the base.

**A new nested project selects the project above it.** A project's
inputs stop at every project below it, so a `package.json` that makes
an existing directory a project re-keys the project that held it; the
change maps to the new project alone, so the one above it is selected
too. "New" is judged at the base: no manifest there, or one with no
`name`.

**A workspace config change selects everything.** An edit to
`vx.workspace.*`, or to a file it imports by relative specifier, selects
every project: the `config` and `project` stages its plugins install
shape every resolved config, so the edit can re-key any task, and
selection cannot tell which. It is not in the fingerprint (a key moves
only when a stage's output does). A root file a plugin's stages read
without importing it is seen when the plugin CLAIMS it
(`VxPlugin.fingerprint`): `turbo()` claims `turbo.json` and
`turbo.jsonc`, `nx()` claims `nx.json`, and an edit asks the claimant,
which answers every project (item 961).

**A file your config IMPORTS selects that project.** vx hashes the
resolved config, so a shared preset a `vx.config.*` imports is part of
the cache key — and selection follows the same rule. Editing
`shared/preset.ts` selects every project whose config imports it,
directly or through another shared file, even though the file belongs
to no project and no `workspaceFiles` glob names it. The scan is
STATIC (nothing is evaluated) and follows RELATIVE specifiers, and a
bare one the nearest tsconfig maps through `paths` or `baseUrl`; any
other bare specifier is a package, and a lockfile change already selects
everything. It crosses project boundaries as the evaluation does: a
config importing `../../packages/lib/preset.ts` is selected when
`preset.ts` or a file it imports inside `lib` changes. Import your
helpers by bare specifier to opt out. See
[`docs/modules/config-imports.md`](../modules/config-imports/).

**Nothing changed exits 0.** When the selection comes only from
`--affected` / `[<ref>]` and resolves to zero projects, vx prints
`nothing affected since <ref>` and exits 0 — a docs-only commit must not
fail `vx run lint test build --affected=origin/main`. When the diff
did match and an exclusion or an empty walk took it all back, the exit-0
note says that instead (`no projects selected: !app excluded every
project the other filters matched`), never that nothing changed. A name or path
pattern that matches nothing is still an error (a probable typo), and a
pattern that matches nothing alongside one that matched is warned about
on stderr.

**An empty selection never cancels an anchored task.** Project scope
applies to bare names only, so `vx run app#deploy build
--affected=origin/main` with nothing changed still runs `app#deploy`
(vx notes `nothing affected since <ref> — running app#deploy only` on
stderr). Only a bare-name-only invocation short-circuits to exit 0.
With only `pkg#task` names the scope goes unused, but `--filter` and
`--affected` are still resolved: a pattern that matches nothing or a ref
git does not know refuses the run as it does beside a bare name.

### Argument forwarding (`--`)

Anything after `--` is forwarded (shell-quoted) to the task's
`exec.command`:

```sh
vx run test -- --watch              # underlying test runner sees "--watch"
vx run build -- --sourcemap         # build command gets "--sourcemap"
```

They are appended to the command's last line (trailing blank lines are
dropped first, so a multi-line command's closing newline does not run
them as a command of their own), or before a `#` comment still
open there (`echo args: # show` gets them; with comment-only lines
below a commented line, before the earliest). A heredoc's body and
terminator are not command lines: `cat <<X … X` gets them on the
`cat <<X` line (X-12). A `<<X` in a comment or in quotes opens no
heredoc, and a quote in a body opens no string (X-110). A persistent task gets
them too, with or without a `readyWhen`.

Forwarded args are folded into the cache key — different args produce
different cache entries. They scope to user-requested tasks only;
dependsOn-pulled deps don't see them (so upstream cache identity
stays clean). A frame's `$ <command>` line shows the command as it
ran, so a requested task's carries the args and a dependency's does
not.
A group (a task with no command) takes none, so a request that names
only groups is refused (`args after \`--\` reach no task`) rather
than run with the args unheard.

### Flags

| Flag                               | Type           | Default                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------- | -------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--filter <pattern>`               | repeatable     | (none)                                    | pnpm-style filter DSL (see above). `--filter=<pattern>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--all`                            | boolean        | off                                       | Select every project that declares the task.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--affected[=<base>]`              | optional value | off                                       | Select the tasks a change since `<base>` reaches: the ones it touches and those whose `dependsOn` closure holds one (default `affectedBase`, else `origin/HEAD`, else `main` or `master`, else `HEAD~1`); candidates are `--filter "...[<base>]"`'s.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--exclude-dependencies[=<names>]` | optional value | off                                       | Drop `dependsOn` edges. No value = all (just the requested task runs; a group's members run as the group); comma-list = drop only those names, each of which some project must declare (a typo is refused with the nearest name, item 1026). An edge to a task the run schedules anyway (`--all` requests it) stays, so the two still run in order, and so does the order through a dropped task: with `gen` dropped from `test → gen → build` and `build` requested, `test` still waits for `build`. An empty `=` value is a parse error (ambiguous — see below). A dropped dependency does not run but is still keyed, so every key is the one a full run derives; a task keyed on one may hit but does not save (`caching.md` step 10).          |
| `--concurrency <n>`                | int or `<n>%`  | cores, capped by the cgroup quota         | Maximum parallel tasks that EXECUTE; confirmed cache-hit restores are disk work and run on their own lane, up to twice this. `1` serializes both; `50%` is half the CPUs (rounded, never below 1; over 100% is allowed for I/O-bound work). `--concurrency=<n>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--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-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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--timeout <ms>`                   | positive int   | none                                      | Default per-task timeout for tasks without their own `exec.timeout`. Sits above `VX_TASK_TIMEOUT` + workspace `timeout`; per-task `exec.timeout` always wins. A runaway task is killed + `failed`. Never affects cache keys. `--timeout=<ms>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--frozen`                         | boolean        | off                                       | Load configs from `vx-lock.json` instead of evaluating (CI) — the run's, and the ones `--affected` owners and the picker select from. See § `--frozen`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--output-logs <mode>`             | value          | flow-derived                              | `full` \| `errors-only` \| `hash-only` \| `none` — explicit output override. See § `--output-logs`. `--output-logs=<mode>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--download <mode>`                | value          | `all`                                     | `all` \| `toplevel` \| `none` — where a REMOTELY-executed task's outputs land. `none` leaves them in the remote CAS and fetches lazily, only when a locally-placed task needs them. Never affects cache keys. See § `--download`. `--download=<mode>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--verbosity <n>`                  | int (0+)       | `0`                                       | `1` or more prints a per-task table (groups left out) after the framed blocks, above the footer. `--verbosity=<n>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--dry[=text\|json]`               | optional value | off                                       | Print the task graph + predicted cache hit/miss; skip execution. `VX_TIMING=1` prints the stage table here as it does for a run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--graph[=<path>]`                 | optional value | off                                       | Emit Graphviz DOT (stdout if no path, its directory made if missing); skip execution. A path it cannot write is one line and exit 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--format <fmt>`                   | value          | `pretty`                                  | `json` prints the `--summarize` document on stdout when the run ends and moves every other line to stderr ([Machine-readable output](#machine-readable-output)). `--format=<fmt>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--summarize[=<path>]`             | optional value | off                                       | Write per-run JSON to `<cacheDir>/runs/<run_id>.json` (or the explicit path).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--profile[=<path>]`               | optional value | off (`profile.json` when set)             | Write Chrome-trace JSON of the run's wallclock spans.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--tag <k=v>`                      | repeatable     | (none)                                    | Label this invocation. Recorded on the run's `invocations` row so dashboards can filter runs. `--tag=k=v` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--report[=markdown]`              | optional value | off                                       | At the end of the run, print a markdown run report to stdout, above the footer. Only `markdown` is supported (`json` is reserved).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--report-file <path>`             | value          | off                                       | After the run, APPEND the same markdown report to `<path>`, making its directory as the other output paths do. Use this for `$GITHUB_STEP_SUMMARY` — redirecting stdout captures the whole run log too. `--report-file=<path>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

Mutual exclusion:

- `--dry` and `--graph` — both skip execution; pick one.
- `--dry` or `--graph` with `--summarize`, `--profile`, `--report` or
  `--report-file` — each needs a real run to write about. `--report` and
  `--report-file` were accepted and silently wrote nothing until item 992.

Unknown flags are a parse error (`unknown flag: --foo`), naming the
nearest flag the verb accepts when one is within two edits
(`unknown flag: --concurency (did you mean --concurrency?)`). Every verb
does this against its own usage line and `--help`: `vx info --formt`
hints `--format`, `vx lock --chek` hints `--check`, `vx upgrade --hlp`
hints `--help`, and `--json` on a verb that takes `--format` hints
`--format json`. `vx version` takes no word, so `vx version --hlp` is
refused (exit 1) where it once printed the version.

A task typed where the verb goes (`turbo build`, `nx build app`) is
refused with the `vx run` that runs it: `vx build` names
`vx run build --all` from the root and `vx run build` inside a project,
`vx build app` names `vx run build --filter app`, and `vx app#build`
names `vx run app#build`. A typo of a task (`vx biuld`) names the task
and the same `vx run`, unless a verb is as close (`vx rnu` hints `run`).
The default `build` is no declared task, so it is no hint: where it is
the only `build`, `vx build` is an unknown command.
It stays a refusal: a plugin verb of the same
name is the verb, and would change what `vx build` means the day one
was declared.

**Optional-value flags take their value with `=` only.** `--affected`,
`--exclude-dependencies`, `--dry`, `--graph`, `--summarize`, `--profile`,
and `--report` are all valid bare, so a following word is
read as a task name (a `--graph` word ending `.svg`, `.png`, `.json`
and the like is refused, see § Turbo and Nx flags) — `vx run --affected build` means "run
`build`, affected scope", and there is no way to tell that apart from
"`build` is the git base". Write `--graph=out.dot` or
`--affected=origin/main`. Getting it wrong is loud, not silent: the value
becomes a positional that matches no project, so the run refuses to
start (see "Every requested name must resolve" above).

`--exclude-dependencies=` with an EMPTY value is rejected rather than
guessed — "drop every edge" and "drop none" are both plausible readings.
Pass bare `--exclude-dependencies` for the first, omit the flag for the
second.

Value flags (`--filter`, `--concurrency`, `--output-logs`,
`--verbosity`, `--cache-dir`, `--report-file`, …)
accept both `--flag value` and `--flag=value`. In the space form,
`--cache-dir` and `--report-file` reject a value
starting with `-`: that is always a swallowed flag (an unquoted empty
shell variable), never a path or task id. Use the `=` form for a literal
leading dash.

**Numeric flags take a plain decimal integer.** `--concurrency`,
`--timeout`, `--retry` and `--verbosity` reject hex (`0x10`), exponent
(`1e3`), fractional (`2.7`), signed (`+4`) and space-padded forms, plus
anything past `2^53` (it would parse to a number you did not type).
These all used to be silently reinterpreted — `--concurrency 0x10` ran
16 workers.

An empty `=` value means "no value" on four flags, which then act like
their bare forms: `--profile=` writes `profile.json`, `--summarize=`
writes `<cacheDir>/runs/<run_id>.json`, `--graph=` prints to stdout and
`--affected=` uses the default base. Every other flag refuses an empty
value: `--dry=`, `--report=`, `--continue=` and
`--exclude-dependencies=` as well as the ones with no bare form
(`--retry=`, `--timeout=`, `--cache-dir=`, `--filter=`, `--cache=`).

#### Cache control: `--cache`, `--no-cache`, `--force`

The cache has four independent axes — **localRead**, **localWrite**,
**remoteRead**, **remoteWrite** — and the three flags above resolve
them in this precedence order:

1. Start with every axis **on** (the default).
2. Apply each `--cache=<spec>` segment (the base).
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).

A spec that names a remote axis (`remote:r`, `remote:w`, `remote:rw`)
in a workspace whose plugins supply no remote layer gets one status
line saying so — the axes are inert without a layer to serve them, and
a CI job that believes it is filling a shared cache should be told.

So `--no-cache` always wins over `--force`. The common cases:

- `--no-cache` → nothing reads, nothing writes, and declared output
  globs are left untouched (you're debugging; vx won't manage your
  tree).
- `--force` → re-execute every task (reads off) but still write fresh
  artifacts to both layers (writes on). Output globs ARE cleaned
  before each task so the saved snapshot is clean. This is the "rebuild
  and refresh the cache" flag.

`--cache=<spec>` is a comma-separated list of `<layer>:<flags>`
segments. `layer` is `local` or `remote`; `flags` is any subset of `r`
(read) and `w` (write), order-independent and possibly empty. A
**mentioned** layer is set EXACTLY to its flags; an **unmentioned**
layer keeps its current value. Both `--cache=<spec>` and the space form
`--cache <spec>` are accepted.

| Spec                        | Effect                                                  |
| --------------------------- | ------------------------------------------------------- |
| `--cache=local:rw,remote:r` | remote read-only (won't upload); local full             |
| `--cache=local:r`           | local read-only; remote untouched (still full)          |
| `--cache=remote:`           | remote fully off; local untouched                       |
| `--cache=local:,remote:rw`  | don't touch the local cache, but still upload to remote |

`local:` means "don't serve hits out of the pre-existing local cache" —
a remote hit is still delivered (the artifact has to land on disk to be
extracted), it just never short-circuits the remote read.

Combine with `--force` for "re-execute and refresh only the remote":
`--cache=local: --force` (local off, reads off, remote write-only).

Invalid layers/flags are a parse error
(`invalid --cache layer 'disk'`, `invalid --cache flag 'x'`, …).

### Output

What a run prints is derived from the run's intent (its "flow"),
unless explicitly overridden:

- **FOCUSED** — no selection flag was passed. The user is running
  "their" task; cwd and task count are irrelevant to the
  classification.
- **BROAD** — the invocation used `--all`, `--filter`, or
  `--affected`. The user asked about a swath of the workspace and
  wants news, not output.
- **CI** — the `CI` env var is truthy (`CI=0` / `CI=false` don't
  count). Wins over the flow.

Reported task lines share one column grid —
`<glyph> <time> <status> <cache> <name>` — with two orthogonal axes:
the glyph SHAPE encodes the cache axis, the glyph COLOR (and the
status word) the task axis.

| Glyph | Cache axis                 | Status word |
| ----- | -------------------------- | ----------- |
| `⏺`   | miss — the task ran        | success     |
| `►`   | fresh (up-to-date)         | success     |
| `⇢`   | restored from local cache  | success     |
| `⇣`   | restored from remote       | success     |
| `◼`   | failed                     | failed      |
| `⊘`   | skipped (blocked upstream) | skipped     |
| `▸`   | persistent (dev server)    | running     |

A live WORKER row carries no glyph: the ticking elapsed time leads it,
which is the motion the run has instead of a spinner.

Per-task visibility by outcome. Each cell is the SHAPE of what prints —
`silent`, `one-liner`, `frame`, or a conditional; the table is pinned to
the renderer by `tests/output-doc-drift.test.ts`, so the vocabulary is
fixed:

| Outcome                | focused (requested task) | focused (dependency)      | broad                     | CI / `full`                  |
| ---------------------- | ------------------------ | ------------------------- | ------------------------- | ---------------------------- |
| executed               | frame                    | silent                    | one-liner                 | frame                        |
| restored-local/-remote | frame                    | silent                    | silent                    | frame, or one-liner if quiet |
| up-to-date             | frame                    | silent                    | silent                    | frame, or one-liner if quiet |
| failed                 | frame                    | one-liner + frame replays | one-liner + frame replays | frame                        |
| skipped                | one-liner                | one-liner                 | one-liner                 | one-liner                    |

What the shapes mean in each column:

- **focused, requested task.** The frame is LIVE when it is the only
  requested task: `┌─` prints at task start, the command's output (or a
  hit's replayed stdout) streams raw between the brackets, `└─` closes
  it. With several requested tasks the same frame is buffered and
  emitted atomically (see below). Every outcome that ran or was cached
  gets one — including an `up-to-date` hit, whose frame carries the
  `$ cmd` line so a requested task looks the same whether it ran or not.
- **skipped** is the exception: it never started, so no frame was opened,
  and it produced nothing a frame could hold. The one-liner says
  everything, the blocker included (`⊘ skipped app#deploy • blocked by
lib#build`; a fail-fast skip, which nothing blocked, carries no
  suffix). Every view that lists tasks prints it, a dependency's
  included: nothing prints below the footer. `--report` reads the same fact into the status cell,
  `skipped (blocked by lib#build)`.
- **`frame, or one-liner if quiet`** — a cache hit with stored stdout is
  worth a frame (the output is the point); a hit with nothing to replay
  compresses to one line, which is what keeps a 2000-task warm run
  readable.
- **`one-liner + frame replays`** — the `◼ … failed` line prints
  immediately; the full frame is held and replayed at run end.

When a dependency fails mid-run, the stream gets ONE permanent
`◼ … failed miss <id>` line and the run continues; **all full failure
frames replay together at run end**, right above the summary, and are
never capped.

The end-of-run summary always prints; cache-hit counts that broad
mode silences per-task surface there. A focused `vx run test` is meant
to feel like running the test command directly — same output, just
faster.

**Groups are transparent folders.** A group task (no `exec`, just
`dependsOn`) has no output of its own, so running one focused —
`vx run build` where `build` chains `build.bun` which chains
`build.bun.darwin-arm64` … — surfaces the **real tasks** it stands for
and shows them like requested tasks. The walk descends through nested
groups but never leaves the requested project (`^`/cross-project deps
aren't surfaced) and never goes past a real task into its own deps.
The requested count for the live-vs-buffered decision counts the
surfaced tasks: one real task streams live, several buffer into atomic
blocks. (Surfacing is display-only — it does not make those tasks
"requested", so `--` `forwardArgs` still go only to what you named.)

Live streaming applies only when there is exactly **one** requested
task. Live open/close framing assumes a single task owns the terminal
between its open (`┌─`) and close (`└─`) lines — with two requested
tasks running concurrently their frames would interleave into garbage.
So when more than one task is requested (`vx run build test`), each
requested task instead **buffers** its output and renders as a single
atomic block at completion. The shapes are the ones in the table above —
anything that ran or was cached gets a full frame, `up-to-date`
included; only `skipped` is a one-liner. The blocks are blank-line
separated and never interleave. A single `vx run test` keeps the
live-stream experience unchanged.

On an interactive terminal (TTY stdout, not CI) a status region
tracks the run live. Top to bottom:

1. **A blank separator line** — keeps the live region visually apart
   from the completed-task scrollback above it.
2. **Pinned persistent tasks** — `▸ <id> running` for every persistent
   task that became ready. The pin lives until run end, so it is the
   visible evidence the dev server is still alive. After the summary,
   a requested persistent task keeps vx in the foreground, with the
   persistent tasks it depends on, until it — or, with several, the
   first of them — exits (one kept only as a dependency that exits 0,
   a daemon that forked and returned, does not end it); the rest still up are then torn
   down (SIGTERM, `VX_KILL_GRACE_MS`, SIGKILL), one status line names
   the task and its code (`vx: app#dev exited with code 1; stopping 1
other persistent task`), and a non-zero exit makes the run exit 1
   and is what `vx last` records.
   A Ctrl-C prints no such line: the server ended because it was
   stopped, and vx exits 130. A run with a failure elsewhere (a task
   failed or skipped, a server never ready or crashed) holds nothing: it
   stops its servers and exits 1, unless `--continue=always`; `vx watch`
   keeps its server through a failed cycle. While vx holds them, what
   the servers write streams below the summary a line at a time under
   each one's id (`app#dev │ Local: http://localhost:5173`), except
   under `--output-logs errors-only`, `hash-only` or `none`; a single
   requested server in the focused flow streams raw from its frame.
3. **Worker rows** — one per worker slot (sized
   `min(concurrency, 10)`), no glyph and no spinner: the live ticking
   elapsed time leads (`     568ms running  <id>`). A task stays in
   its row for its whole life; idle rows hold their place dimmed, so
   nothing ever jumps; overflow shows as `+k more`. A second in, a row
   says what waits on it: `critical path` (yellow) on the running task
   the longest unfinished chain waits on, by the same p50s as the
   forecast below and only while two or more run, and a dim
   `blocks N`, its unfinished dependents direct and transitive.
4. **The live summary section** — the SAME meters the final footer
   prints (`tasks` + `cache` bars with legends, `time`), filling in as
   the run progresses, under a bare `vx` wordmark rule. A second in,
   the `time` row adds what is left (`time  1.41s · ~3s left`): each
   unfinished task's executed p50 from local history, the longer of
   the longest unfinished chain and that work spread over the
   workers, a running task's spent time taken off its own. It says
   nothing when history knows none of what is left, or once a running
   task is 25% past its p50. A run that ends inside the second never
   reads history for it, and the final summary never shows it.

In a terminal known to read them, the region also sends zero-width
escapes: tab or taskbar progress (OSC 9;4: Ghostty, iTerm2 3.6+,
Windows Terminal, ConEmu), filling by the forecast or else by tasks
done, red once a task fails, and cleared when the region goes; and a
run of 10 s or more ends with a desktop notification (OSC 9: Ghostty,
iTerm2, WezTerm), `vx: 12 tasks done` or `vx: 1 of 12 tasks failed`.
The terminal is named by `TERM_PROGRAM` (or `WT_SESSION`,
`ConEmuPID`); any other, tmux included, gets neither, since there
OSC 9 may itself be a notification.

In a terminal known to open OSC 8 links (Ghostty, iTerm2 3.1+, WezTerm,
VS Code, Windows Terminal, kitty, Konsole, VTE terminals; never inside
tmux or screen), a failed task's frame links each path that names a
file in the task's project, `src/a.ts:12:5` or `src/a.ts(12,5)`, to
that file, so a click from the workspace root opens the right one. The
text is the task's output unchanged; a successful task's frame is never
linked.

The region is redrawn in place (cursor-up + clear; not a TUI — no
alternate screen) and erased before the final summary prints. In the
focused flow it only lives while dependencies run; it disappears for
good the moment the requested task starts streaming.

Redraw cost is bounded: task events force a redraw, but forced
redraws within 30 ms of the last draw coalesce into a single
trailing draw when the floor expires (the final state always lands).
On a 3,270-task warm run this cuts ~6.7 MB of redraw ANSI to ~20 KB.

Identity coloring: every `project#task` renders its project half in
a stable hue hashed from the project name (same project = same color
in every run and every surface) and its task half in a fixed pink —
both deliberately outside the status palette, so an id can never
read as an outcome.

On GitHub Actions (`GITHUB_ACTIONS` truthy, full output mode), each
task's block is wrapped in `::group::<id> (<outcome> <duration>)` /
`::endgroup::` so it collapses in the log viewer. Failed tasks stay
pre-expanded and emit an `::error title=<id>::failed (exit N)`
annotation instead (above 128 the label names the signal:
`failed (exit 137, 128 + SIGKILL)`, a timeout its reason,
`failed (timed out, exit 143)`, a persistent task that never became
ready its reason, and a sandboxed task its violation count, as every
surface labels a failure). In every output mode there, a task's own
text (a frame, a server's output since ready) is fenced in
`::stop-commands::`, so a line it prints never becomes a workflow
command.

### `--output-logs <mode>`

Explicit override; always beats the flow and CI defaults. `full`
(frames for executed work, one-liners for quiet cache hits),
`errors-only` (only failed tasks print, a server that died on its
own after ready included, with what it wrote since; the CI noise
budget),
`hash-only` (one line per task — outcome word, task id, cache key — and
no log output at all; the run's audit trail of which key each task
resolved to, Turbo parity), `none` (no per-task output). The
end-of-run summary always prints.

### Failure propagation — `--continue`

`--continue[=never|deps-ok|always]` controls what a failed task takes
down with it:

- **`deps-ok`** (default): the failure's transitive dependents are
  skipped; independent siblings keep running. A server that dies after
  it became ready is a failure to its dependents not yet started,
  including those that reach it through a group.
- **`never`**: fail fast — the first failure stops dispatch. In-flight
  tasks finish their attempt and start no retry; everything not yet started (cache restores
  included) completes as skipped. A server that dies after it became
  ready stops dispatch the same way.
- **`always`** (bare `--continue`): dependents run even when an
  upstream failed — to surface every failure in one pass. A task
  downstream of a failure (directly, or through successes built on it)
  runs and cleans its outputs as usual but is **never saved**: under
  pure-input hashing its key is the one a healthy run derives, while its
  bytes were built on a partial tree, so caching it would hand the next
  clean run a stale hit. A server that died after it became ready is
  such a failure to what starts after its death. A cache hit still
  restores (that artifact came from a healthy run), and the next run
  without the failure rebuilds the rest.

The mode is the local scheduler's: a task a plugin executor runs
elsewhere is one dispatch, failed or not, like any other.

### `--download <mode>`

Where a **remotely-executed** task's outputs land. `all` (default)
downloads every task's outputs to this machine as it completes —
today's behaviour, byte for byte. `toplevel` brings home only the tasks
you actually asked for — including the real tasks behind a requested
group — and leaves intermediates remote. `none` leaves
them in the remote CAS
and fetches them **lazily**: only when a locally-placed task in the
same run actually needs them (Bazel calls this "build without the
bytes"). A CI job that only wants the verdict moves no output bytes at
all.

Locally-executed tasks always write in place and ignore the flag, and
`exec.remote: 'only'` still means never — `--download` cannot override
it in either direction. **It never affects a cache key**: transfer
tuning cannot change what a command produces.

One safety gate: a task whose outputs another task's `cache.inputs`
globs could read on disk is silently kept eager, because deferring it
would make that key depend on whether the bytes arrived. A task with no
`cache` that a cached task depends on counts as reading its whole
project (C-16). `--dry` reports
how many tasks would keep their outputs remote and names each downgrade,
so a run that defers nothing says why. A run in which any task declares a
`cache.inputs.runtime` / `workspaceRuntime` command defers **nothing**:
a shell command's reads cannot be bounded, so vx cannot prove it will
not read a deferred output (the same reason vx refuses to infer inputs
by tracing). When bytes are fetched later, vx saves an ordinary
cache entry for them, so the next run is a plain local hit.

## Planning mode (`--dry`, `--graph`)

Both flags short-circuit execution. They build the full task graph,
compute every task's cache key, and probe the cache to predict the
hit/miss outcome. Against a remote cache the probe is a lightweight
existence check — planning never downloads or ingests artifacts.

```
$ vx run ci --dry
would run:
  ◉  @vzn/vx#format-check  cache hit (local)         02bfe8a9
  ◉  @vzn/vx#lint          cache hit (local)         d66cfed2
  ▶  @vzn/vx#test          cache miss — would exec   68595e49  ~72.64s

3 task(s) planned, 2 cache hits (2 local), 1 would run.
predicted: ~72.64s wall · ~72.64s total execution
```

**Time prediction.** A would-run task with recorded history shows its
typical executed duration (`~p50` over its recent non-hit runs in the
local `cache.db`). The footer predicts the run: `wall` is the longest dependency
chain of would-run cost (cache hits restore near-instantly and count
as 0), `total execution` is the sum across would-run tasks. Tasks with
no history count as 0 and are called out (`N tasks without history
(+?)`) — the totals are honest lower bounds. The footer is omitted
when nothing would run or when no would-run task has history.

**Placement.** When the workspace's plugins supply more than one
executor, each row carries the one the task would land on (`@spy-remote`;
`@local` for the floor; `@noop` for an `exec.remote: 'only'` task no
remote accepts, which the run would skip rather than run here) and the
JSON object carries it as `executor`. With one executor there is
nothing to choose and the column is absent, except `@noop`, which a
remote-only task carries whatever the count; it costs nothing in the
prediction. If an executor hook throws
or returns something that is not an executor, the plan still prints —
`--dry` never fails over a label — but says so on the status line, in
the plugin's name: `[vx] placement not shown — plugin 'x' … (the run
would refuse on it)`.

Status legend:

| Symbol | Meaning                                                                                    |
| ------ | ------------------------------------------------------------------------------------------ |
| `◉`    | cache hit (local) — entry already in `<cacheDir>/`                                         |
| `↓`    | cache hit (remote) — entry would be fetched from the layer                                 |
| `▶`    | cache miss — task would execute (under `--force` too: nothing is read, what runs is saved) |
| `·`    | no-cache — task opts out (no `cache` block, or `--no-cache`)                               |
| `∅`    | `@noop` — task would not run anywhere                                                      |
| `−`    | not started — a server you did not request whose every dependant restores a local hit      |
| `○`    | group task (suppressed in human view; in DOT + JSON)                                       |

`--dry=json` emits the same data as a structured object, alone on stdout
(a stage's warnings go to stderr); `schemas/plan.json` is its JSON
Schema, held like the read verbs' (see Machine-readable output):

```json
{
  "tasks": [
    {
      "id": "@vzn/vx#lint",
      "project": "@vzn/vx",
      "task": "lint",
      "description": "oxlint with tsgolint-backed type-aware checks",
      "hash": "d66cfed2...",
      "cacheStatus": "hit-local",
      "deps": [],
      "p50Ms": 72640
    }
  ],
  "predicted": { "wallMs": 0, "workMs": 0, "unknownCount": 0, "criticalPath": [] }
}
```

Every task with history carries `p50Ms`, hits included (only the text
view's `~p50` is limited to tasks that would run); `predicted` counts
would-run tasks only and is present whenever local history was
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:

```
$ vx run build lint --affected=main --dry
  ▶  app#build  cache miss — would exec  …
                affected: packages/lib/src/a.ts changed (an input), via lib#build
  ·  lib#lint   no-cache                 …
                affected: packages/lib/src/a.ts changed (in its project)
```

`kind` is `input` (a changed `file` is a declared input), `project` (its
project changed and the task reads it whole: an uncached task, or no
single `file` for a lockfile claim, a manifest edge or a config import),
`package` (a `^` edge passes a changed `project` with no such task),
`named` (`pkg#task` beside a bare task) or `selected` (another filter
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.

`--graph` prints Graphviz DOT (stdout by default; `--graph=path`
writes a file):

```
vx run ci --graph | dot -Tsvg > graph.svg
vx run ci --graph=graph.dot
```

Node `fillcolor` varies by predicted status (green = local hit,
sky-blue = remote hit, orange = miss, gray = no-cache, fuchsia =
group, white = not started). Edges are unstyled.

## Run artifacts (`--summarize`, `--profile`)

Both flags add a side-effect after a real run completes. Errors
writing the artifact are surfaced via `vx: failed to write …` but
don't change the run's exit code — the run already happened.

### `--summarize[=<path>]`

Writes a per-run JSON file; `schemas/summary.json` is its JSON Schema:

```json
{
  "runId": "01a0e3ef-206c-708d-95bf-c2b07211adf6",
  "ok": true,
  "exitCode": 0,
  "startedAt": "2026-09-27T17:34:54.572Z",
  "endedAt": "2026-09-27T17:34:54.586Z",
  "totalMs": 14.123643,
  "savedMs": 9,
  "tasks": [
    {
      "id": "a#build",
      "project": "a",
      "task": "build",
      "status": "cache-hit",
      "exitCode": 0,
      "durationMs": 3,
      "hash": "48007ccadd42ed7d",
      "storedDurationMs": 9,
      "storedCpuMs": 2.059,
      "wallclockStartNs": "9456491",
      "wallclockEndNs": "12902888"
    }
  ],
  "aborted": [],
  "summary": {
    "successful": 1,
    "failed": 0,
    "skipped": 0,
    "cachedLocal": 1,
    "restoredLocal": 0,
    "restoredRemote": 0,
    "upToDate": 1,
    "cachedRemote": 0,
    "aborted": 0,
    "total": 1
  }
}
```

`runId` is a UUIDv7. Default path: `<cacheDir>/runs/<run_id>.json`. hrtime fields are
strings (bigints serialized as strings) to preserve ns precision
through JSON. `cpuMs` / `peakRssBytes` are what the task's own
execution used and appear on executed rows only (`peakRssBytes` only
when the task's peak rose above vx's own footprint — a lighter task's
figure would be vx's, handed back by the kernel; a Linux sandboxed task
reports neither, since what bwrap's pid namespace used never reaches vx);
`restored` appears on a hit only: `true` when its outputs were restored,
`false` when they were already up to date. A hit's `durationMs`
is the restore it cost, and what the PRODUCING execution used rides the
artifact and appears under its own keys, `storedDurationMs` /
`storedCpuMs` / `storedPeakRssBytes` (the work the hit skipped) — a
remote worker's peak is never presented as this run's. `savedMs` is
their sum over the hits, the footer's `saved` as a number. `admissionHeldMs` appears on a row
only when an `admit` policy (a plugin's — `@vzn/vx-schedule-history`
packs learned reservations) refused the task while a worker was free:
the wait from that first refusal to its dispatch, the plugin's hand on
the run. The footer's `info` row sums the waits, task-seconds:
`admit held 3 tasks, 4.2s in all` (85 held tasks can read 4783s beside
a 160 s run).

**`ok` / `exitCode`** are the run's verdict — the same value the CLI
exits with: a stopping signal's code (130 for Ctrl-C), and with a kept
server, its exit (the file is written again when the server ends). Gate on these rather than re-deriving a pass from the
buckets: a run can be red without a single failed task (see `aborted`).

**`tasks[]` and `summary` describe the same population**, so
`tasks.length === summary.total` always holds. Group tasks (no `exec`)
are in neither — they do no work.

**`aborted[]`** lists tasks whose attempt ended while the run was
stopping (Ctrl-C, a signal to vx), with their exit code, and tasks the stop reached before they started, with
exit 1, `durationMs: 0` and no `wallclockStartNs`. Neither joins an
outcome bucket or `total`, but they make the run red, so they are
listed separately and counted as `summary.aborted`.

**`noCache: true`** marks a task no cache answered for: it declares no
`cache` block (it executes every run by design), or the run's `--cache`
read and wrote nothing (`--no-cache`), so a hit rate should leave it out
of the denominator. The key is present only when true; every other row is
unchanged. Its `hash` is still set: dependents fold it.

**`notReady`** is present only on a failed persistent task: why it never
became ready — `timeout` (the readiness deadline fired; `exitCode` is
the kill's, 143 or 137 after the grace, and 143 for a server that
traps the TERM and exits 0, as an ordinary timeout's),
`exited` (the child exited first; `exitCode` is then its own) or `spawn`
(the spawn itself failed). Every label reads it, `failed (never ready:
timed out, exit 143)`. A server the run's stop (a Ctrl-C) killed while it started is
`aborted`, not failed, as any task the stop kills; so is one that
became ready only after the stop.

**`sandboxViolations`** is present only on a sandboxed task with a
SANDBOX VIOLATIONS section — the count of its denials (vx's own notes
there count none), and the reason the task failed (its exit is forced to 1
when it was 0); every label counts it, `failed (exit 1, 2 sandbox
violations)`.

**`timedOut: true`** is present only on a `failed` row vx's own
`timeout` killed: its exit is the shell's 143, and every label reads
`failed (timed out, exit 143)` rather than a signal.

**`blockedBy`** is present only on a `skipped` row: the id of the failed
(or aborted) task at the root of what blocked it, through any chain of
skips between — what the skipped row prints, for a script.
A fail-fast skip has none.

**`flaky: { passes, failures, attempts }`** is present only on a task
this run proved flaky (its row's `flaky` note, typed): `passes` and
`failures` count the outcomes on record for this exact `hash`, this run
included, and `attempts` is what this run took. A consumer gating on
`status: "failed"` can tell a break (no `flaky` key) from a flake
without reading the history. Every other row is byte-identical.

**`durationMs` is always what THIS run spent on the task.** For a cache
hit that is the probe + restore, not the exec time the entry was stored
with — so it is small even for an expensive task. The work a hit
_skipped_ is a different number; `--report`'s "N saved" is the surface
that reports it.

### `--profile[=<path>]`

Writes a Chrome-trace JSON of every task's wallclock span. Open in
`chrome://tracing` or https://ui.perfetto.dev.

```json
{
  "traceEvents": [
    {
      "name": "@vzn/vx#lint",
      "cat": "success",
      "ph": "X",
      "ts": 12345,
      "dur": 4321,
      "pid": 1,
      "tid": 1,
      "args": {
        "exitCode": 0,
        "hash": "...",
        "cpuMs": 123,
        "peakRssBytes": 45678
      }
    }
  ]
}
```

Each project gets a distinct `tid` so concurrent tasks across packages
render on separate lanes. `ts` and `dur` are microseconds derived
from the per-task `hrtime.bigint()` spans the runner captures.
`cat` carries the task's final status (`success`, `cache-hit`,
`cache-hit-remote`, `failed`).

Default path: `profile.json` (cwd-relative).

### `--report[=markdown]`

At the end of a real run, prints a markdown run report to **stdout**,
just above the footer: nothing prints below the footer. The report
itself is machine-clean. One header line of
totals plus a table, one row per task:

```markdown
## vx run — passed

**3 tasks** · 3 success · 0 failed · 2 cached (1 up-to-date, 1 restored) · 1.23s total · 2.65s saved

| Task      | Status  | Cache      | Duration |
| --------- | ------- | ---------- | -------- |
| web#build | success | miss       | 1.23s    |
| web#test  | success | local      | 5ms      |
| api#test  | success | up-to-date | 3ms      |
```

`Status` is the task outcome (`success` / `failed (exit N)`, with the
signal an exit above 128 stands for, `failed (exit 137, 128 + SIGKILL)`,
or a timeout's reason, `failed (timed out, exit 143)`, a persistent
task's `never ready: …`, or a sandboxed task's violation count, or
`skipped`, naming what blocked it: `skipped (blocked by lib#build)`);
`Cache` is its provenance (`miss` / `no-cache` for a task no cache
answered for — no `cache` block, or a `--no-cache` / `--cache=local:` run —
which never consulted one / `local` / `remote` / `up-to-date` /
`—`). A stopped run (a Ctrl-C teardown) reads `## vx run — interrupted`,
and its tasks keep the terminal's words: one the signal killed is
`aborted` with its time so far, one the stop reached before it ran is
`not run` with no time. Neither joins the counts; the header names them
after the total, `not counted: 1 aborted, 1 not run`, so a red report
with no failing row still says why. Group tasks (no `exec`) get neither — they are not
work, and the header's counts match the terminal summary and
`--summarize` exactly.

The two durations in the header mean different things, and the
distinction is the point:

- **`N total`** sums `Duration` over the tasks that actually EXECUTED,
  an aborted task's time so far included — the time this run spent.
- **`N saved`** sums the exec times the cache hits SKIPPED, read from
  each entry as it was stored (above, 2.01s and 640ms). It is
  deliberately not the hits' `Duration` column, which is the restore
  they cost this run: summing that reported a task taking 2.01s cold
  as "6ms saved".

Only `markdown` is supported today (`json` is reserved; a bad value is a
parse error). Built purely from the run's outcomes after it returns — it
adds zero cost when both flags are absent.

### `--report-file <path>`

Writes the same markdown report to a file instead of (or as well as)
stdout, and is the form to use for a CI step summary:

```sh
vx run ci --report-file="$GITHUB_STEP_SUMMARY"
```

**Do not redirect stdout for this.** The report itself is machine-clean,
but stdout is not vx's alone — the status logger writes frames, meter
bars and `::group::` workflow commands to the same stream, so
`--report=markdown >> "$GITHUB_STEP_SUMMARY"` puts the entire run log
into the step summary above the table.

The report is **appended**, never truncated: `$GITHUB_STEP_SUMMARY` is a
shared, append-only file that other steps in the same job also write to,
so overwriting it would silently discard their content. Passing both
flags writes the report to stdout AND appends it to the file. A run
stopped by Ctrl-C or SIGTERM still writes both, its stopped tasks
`aborted`. A write
failure is reported (`vx: failed to write report to …`) but does not
change the exit code — the run already happened, the same contract
`--summarize` and `--profile` follow.

### `--tag <k=v>`

Labels the invocation. Repeatable; `--tag=k=v` form too. The pair is
split on the **first** `=`, so values may contain `=` (e.g. a URL). An
empty key is a parse error. Tags are recorded on the run's
`invocations` row so dashboards can filter runs by label, and reach
telemetry as `vx.tag.<key>`; a secret value in one is masked there as
in the task's output (see [Masking](../schema/)).

## Sandbox

Sandbox isolation is opt-in **per task** via an `exec.sandbox` block in
the task's config — there is no `--sandbox` CLI flag. See
[`modules/sandbox-runtime.md`](../modules/sandbox-runtime/) for the
full reference.

```ts
// vx.config.ts
export default {
  tasks: {
    build: {
      exec: {
        command: 'tsc',
        sandbox: {
          allow: {
            read: ['.'],
            write: ['dist/**'],
          },
        },
      },
      cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
    },
  },
}
```

The grants are the task's whole permission surface — nothing is derived
from `cache`, and the only thing core adds is `node_modules` plus the
workspace packages linked there, never a link back to the task's own
project (npm and Yarn link that too). For a task that declares `cache`
a linked package is granted only when its key folds a task of that
package; declaring `cache` narrows core's grant and widens nothing.
Enforcement anchors at the workspace root (a task never leaves its
project); only denials inside the project, or under a withheld linked
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.
"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`
§ `exec.sandbox` has the shape and the remedy (outputs in a
subdirectory).

`vx run` arms the sandbox runtime when a task that declares
`exec.sandbox` is about to execute; a cache hit needs none. If the
platform cannot host it (Linux needs `bwrap`, `socat` and `rg` on PATH;
macOS, `sandbox-exec`), that task fails with one line, `sandbox not
available: &lt;reason&gt;`, and never runs unsandboxed. Tasks without a
sandbox run as usual, and the failure's dependents follow `--continue`.

## `vx watch`

```
vx watch [OPTIONS] TASK [-- forwarded-args...]
```

Run the named task, then re-run it on every filesystem change in the
projects in scope. Press `Ctrl+C` to stop.

```sh
vx watch test                       # cwd project; re-test on changes
vx watch test --all                 # every project that declares `test`
vx watch lint --filter '@scope/*'   # filtered scope
vx watch build -- --sourcemap       # forwarded args carry through every cycle
```

### Lifecycle

1. **Initial run.** Same code path as `vx run` — same scope resolution,
   same task graph, same cache behaviour. The line `vx watch: initial
run...` precedes it.
2. **Watch loop.** After the initial run finishes (or once it waits only
   on a server's readiness, X-139), the directory of
   every project a cycle can run — the scope (the bare tasks' scope
   plus each `pkg#task`'s own project; only those when every task is
   anchored) plus its transitive dependencies, the closure `--filter 'app...'` walks, cross-project
   `dependsOn` edges included — is watched recursively, less any project
   nested inside it, with a config or not (a root project's key leaves a nested
   project's files out, so an edit there is no cycle; X-42, X-57). The workspace root is
   watched (non-recursively) for lockfile / `pnpm-workspace.yaml`
   changes and for an edit to `vx.workspace.*` — the one root file that
   shapes a run (plugins, `config` stage, concurrency) without being any
   task's input; the cycle after it re-evaluates the file. A `.gitignore`
   there or in a package glob's directory is a cycle too: inputs are
   gitignore-aware, so it changes what keys read (X-136). A file a
   config imports by relative path from outside the watched projects (a
   shared preset) is watched too, and its edit is a cycle that re-reads
   the configs; so is one inside a project, which re-reads the set as the
   config's own edit does (WD-14). A file the workspace config imports is loaded once per
   process, so its edit is named with the restart it needs rather than
   run stale (item 949). An import whose file is gone stays on the list
   by the name it would have, so its return is a cycle (X-133). The directory
   each `<dir>/*` package glob names (`packages/` for `packages/*`) is
   watched for members coming and going: a package added while the watch
   runs is a cycle that runs it, and its directory is watched from before
   that cycle runs, so an edit made during it queues (X-138); a removed one is dropped. An edit to the glob list itself (the
   root `package.json`'s `workspaces`, `pnpm-workspace.yaml`) re-reads
   the set, so a glob added there is watched from the cycle it triggers
   (item 1018). A base, or a directory a config imports from, removed and made
   again (a checkout that restores `packages/`) is heard from its nearest directory that exists, and a
   watch whose directory was replaced is armed again (an OS watch holds
   the deleted one; `watch-recreated-dirs.test.ts`). Under `--filter` or `--affected` the scope is the one
   resolved at start, and a new package joins it only as a dependency of
   it; a glob of another shape (`apps/**`) has no such directory, so a
   package added under it waits for a restart. A task's own declared outputs (`cache.outputs.files`,
   `outputs.workspaceFiles`; a plugin's `project` stage counts, as in
   a run) never trigger a re-run — a cycle that writes `dist/` is not
   an edit, nor is the `dist` directory itself coming and going (a
   literal entry covers its whole tree, as in the schema), unless some
   task reads the path as an input (an in-place formatter's `src/**`
   output still leaves a `build` reading `src/**` watching it, item 946;
   a task's own outputs are no input of it, so a `turbo()` task reading
   `**/*` does not re-run on its own `dist/`; only the tasks the run
   reaches through `dependsOn` are asked, so an unwatched `lint` reading
   `**/*` beside `vx watch build` asks nothing) — and neither do `node_modules`,
   `.git` or the cache directory. A write the task did NOT declare (a
   task with no `cache` block declares nothing) is caught by state,
   judged once the bytes have settled: a file whose bytes and mode did
   not change since the loop last saw it is not an edit (a `chmod` is one,
   as the key reads the executable bit), nor is a directory
   whose entries (names and sizes) did not, nor a path that stayed
   gone; a symlink is its target string, as the key folds it, so a
   retarget is an edit; a path the loop has never judged is an edit only if it was
   modified after the watchers went live (macOS delivers the initial
   run's own writes after the arm; the later of the path's mtime and
   ctime says which side of it a path belongs to, so a file moved in
   with an old mtime by `mv`, `cp -p` or `tar x` still counts, and a
   symlink's own times are read, never its target's), and a
   path git did not list at the arm that is gone again (vim's `4913`
   write probe, a lock file) is no edit; and
   nothing is judged while a cycle runs — its
   own writes are mid-flight, a `dist` deleted and not yet rebuilt is
   a state the tree will not keep — so paths that land mid-run are
   judged together one debounce window after it ends, an edit made
   meanwhile included. A task that writes into its own project,
   `rm -rf dist && tsc` included, costs one extra cycle instead of
   re-running forever — when the bytes it leaves are the same. A file
   it rewrites with DIFFERENT bytes every run (a pid file, a
   timestamped log) is either git-ignored — a git-ignored path never
   starts a cycle, since no cache key can see it (a user's edit to one
   still does in a project with a task that has a command and no cache,
   which reads what it likes, item 947, outside any project nested
   in it) — or declared an
   output, or the loop re-runs on it; after three such cycles in a row
   watch names the path and the remedy, once, and keeps going. A dev
   server the last cycle left running counts as that cycle for as long
   as it runs, so a log it rewrites in its project is named too, with
   `.gitignore` as the remedy (a persistent task declares no outputs;
   item 948). A file git tracks is never blamed on the server: three
   saves of a source file are the user's (WD-7). When any project's config declares
   `cache.inputs.workspaceFiles`, the per-project watchers are swapped
   for ONE recursive root watcher (boundaries are off for those globs,
   so a root-relative glob can name a file anywhere). That watcher
   hears every write in the tree and keeps only the ones a key can
   see: a path inside a project's directory, a fingerprint file at the
   root, or a match of a declared `workspaceFiles` glob. A log written
   at the root, a `coverage/` or `.turbo/` tree, an editor's scratch
   file are dropped before the trigger — so `vx watch … > build.log`
   inside the repo settles instead of feeding itself a cycle per line
   of its own output. `vx watch: watching …` is
   printed only after every watcher has reported a probe file written
   under it (`.vx-watch-probe`, re-written on a short backoff until its
   event arrives, then removed): on macOS a directory watcher can return
   before its event stream is live, and an edit in that gap is silently
   lost — so the line is a promise, not a hope. A probe is never an
   edit, at any depth: another watcher's, seen under a nested project,
   ran a cycle (and restarted a dev server) with no edit made (item
   1016). A
   watcher whose probe is not heard within 2 s is replaced by a poller
   that checks every 250 ms, with the notice `vx watch: &lt;dir&gt;: no OS
watch events within 2000 ms; polling every 250 ms instead`.
3. **On change.** The triggering path is logged
   (`vx watch: <project> <relpath>; re-running...`): the first changed
   path that still exists, so an editor's temporary file renamed away
   names nothing; a deletion names the cycle when nothing else changed. The
   orchestrator is invoked again with the same options, save one: the
   `--affected` diff is read once, for the initial run. A later cycle
   runs the requested task in every project of the scope fixed at start,
   and the cache keys decide what executes (the startup diff, asked
   again, kept an edit made since out of every cycle). Events arriving
   while a run is in flight queue and drain after the current cycle.
   Re-runs are debounced ~150ms after the last event, and wait at most
   1 s after the first, so a writer that never pauses holds no edit back.
4. **Exit.** `SIGINT` (Ctrl+C) exits 0; once the cycle in flight is down, `vx watch: stopped` is the last line.

### Path filtering

Always ignored (no re-trigger):

- `node_modules/`, `.git/`, `.vx/` anywhere in the path.
- A path git ignores (`git check-ignore`, asked once per debounce
  window, never per event): invisible to every cache key — inputs are
  tracked + untracked-not-ignored — so a cycle it started could change
  nothing. A tracked file that matches a pattern is not ignored, by
  git's own rule; outside a repository nothing is.
- Files ending in `.tsbuildinfo` or `~` (editor swap files).
- The run's **resolved cache directory**, wherever it is. `.vx/` covers the
  default, but `defineWorkspace({ cacheDir })` and `--cache-dir` can put it
  anywhere; watching it would let vx's own cache writes trigger the next
  cycle, which writes again — a loop that never settles.

Everything else triggers a cycle. We deliberately don't filter events
against per-task `cache.inputs.files` — the cache hash is the source
of truth. A change to an irrelevant file produces a cache-hit run
(typically tens of ms); the cost is much smaller than the engineering
cost of a per-event glob match.

### How changes are seen

One recursive OS watcher (`fs.watch`) per project directory in scope,
plus the workspace root for the fingerprint files. Each watcher must
prove it delivers: a directory whose watcher reports nothing within
2 s of the probe is polled every 250 ms instead, with a one-line
notice on stderr (`no OS watch events within 2000 ms; polling every
250 ms instead`). Where the watcher is known not to deliver — a sandbox
without FSEvents access on macOS, a network mount, a container bind —
`VX_WATCH_POLL=1` polls from the start and skips the 2 s probe; the loop
says so once (`vx watch: polling every 250 ms (VX_WATCH_POLL)`). A
watcher the OS refuses for its watch limit (`ENOSPC`, `EMFILE`) is
polled too, with a notice naming the limit to raise. The
poller walks the same tree the event filter keeps: the always-ignored
segments and the run's declared output containers are never sampled.
It samples each file's later clock of mtime and ctime, so a replacement
that carries the old file's mtime (`cp -p`, `rsync -a`, a `mv`) is an
edit to it as it is to the OS watcher.

### Workspace fingerprint changes

Edits to a lockfile (`pnpm-lock.yaml`, `bun.lock`, …) or
`pnpm-workspace.yaml` at the root invalidate every task's cache key
via the [workspace fingerprint](../caching/#cache-key-derivation).
Watch mode hears those because it watches the workspace root
(non-recursively). A lockfile a plugin claims still triggers a cycle,
and so does any other root file a plugin claims (`turbo.json` under
`turbo()`, item 961), a plugin added to the workspace config mid-watch
included from the cycle that loads it; the keys then decide which
projects actually re-run. Under `vx watch --frozen` every cycle's configs come from
`vx-lock.json`, so a config edit alone changes no command, and a re-lock
(`vx lock`) is a cycle that re-reads the watched set (item 971).

### Constraints

The following flags are rejected (parser exits 1 before the initial
run):

- `--dry` / `--graph` — those skip execution; nothing to watch.
- `--summarize` / `--profile` — would overwrite their target per cycle.
- `--report` / `--report-file` / `--verbosity <n>` (n > 0) / `--format json` — all
  format ONE run's result; a watch loop has no single run to report. (`--verbosity 0`
  is accepted: it asks for what watch already prints.)

A requested persistent task (`exec.persistent`, a dev server) starts
once and stays up across cycles; each cycle re-runs what it depends on,
as the cache keys decide. So `vx watch dev`, with `dev` depending on
`^build`, rebuilds only the libraries an edit reaches on the way to the
app and leaves the server running; the dev tool's own reload picks up
what was rebuilt. What the server writes keeps printing. It restarts
only when its own task config (or the args forwarded to it) changed, or
when it died: the old one is stopped first (the kill grace, then
SIGKILL), so the two never hold one port. One that dies while watch
idles is said (`vx: app#dev exited with code 3`); the next change
starts it again. A cycle in which a task the server depends on fails
stops it. An edit while a cycle waits only on a server that has not
printed its `readyWhen` line stops that cycle and starts the next, so a
fix reaches a server stuck before ready, in the initial run too.
Stopping watch stops the server too. A one-shot task (`vx watch build`)
re-runs itself and what it depends on.

### Exit codes

- `0` — clean Ctrl+C / SIGTERM exit. A cycle in flight is torn down
  first — its children, and the dev server held between cycles, get the
  signal watch received (a Ctrl-C as SIGINT; a SIGTERM or SIGHUP as SIGTERM),
  `VX_KILL_GRACE_MS` (2 s), then SIGKILL — and the process leaves only
  once it has returned, so a CI cancellation never orphans a task.
  Also `0`, with no watch, when `--affected` selects nothing: watch
  prints `vx watch: nothing affected since <ref>` and exits as `vx run`
  does.
- `1` — parser error, missing scope, or a task name no project in
  scope declares: the initial run refuses it as `vx run` does, with the
  same `Did you mean` hint, and watch exits rather than re-run the
  refusal on every change.

A cycle that throws — a `vx.config.*` that does not parse — prints
`vx watch: cycle failed: <reason>` and watch keeps watching, the initial
run included, so saving the fix re-runs (item 1017).

Re-run cycles whose orchestrator returns `{ ok: false }` do NOT exit
the watch loop — a failed cycle just prints the framed FAILED block
and waits for the next change. This matches `turbo watch` / `nx
watch`.

## `vx cache prune`

Evict old or oversized cache entries. Operates on the entries and
`<hash>.tar.zst` artifacts of the store the workspace's index records
(`~/.vx/<id>/cache`, shared by every checkout of the repository), or of
`<cacheDir>` itself when the workspace names one (`cacheDir`,
`VX_CACHE_DIR`, `--cache-dir`).

`prune` is the only `vx cache` subcommand: the statistics other runners
put under a `cache` verb — the directory, the entry count, the size —
are part of [`vx info`](#vx-info), and `vx cache stats`, `list`, `ls`,
`clean`, `gc`, `purge` and their neighbours say so (`list` also names
`vx last --list`) rather than printing a bare "unknown subcommand".

```
vx cache prune --older-than <duration>     # Drop entries last used before now - duration (up to 1h slack).
vx cache prune --max-size <size>            # After age-based pruning, evict LRU until under <size>.
vx cache prune ... --dry-run                # Say what either policy would reap; delete nothing.
vx cache prune ... --format json            # { dryRun, evicted, bytesFreed, orphans, orphanBytes }
vx cache prune ... --cache-dir <path>       # The cache a run with the same flag uses.
```

At least one of `--older-than` / `--max-size` is required. Both may
be combined: age-based eviction runs first, then LRU eviction if the
total is still over the size cap. The same policy runs unattended at
the end of every run when `vx.workspace.ts` declares
`cacheRetention: { olderThan, maxSize }` (same spellings; see
[schema](../schema/)).

After eviction, prune sweeps the cache directory for **orphans**: a
`<hash>.tar.zst` the index has no row for (a `SCHEMA_VERSION` bump
drops every table and leaves the artifacts behind, as a deleted
`cache.db` does) and a `<hash>.tar.zst.tmp-*` a save that crashed never
renamed. A run that asks for an orphan's key indexes it again from its
bytes and hits; one no task asks for again is only reclaimed here. The
policy judges a row-less artifact as it judges an entry, by its file
time plus an hour (a hit renews a file time over an hour old): another
vx version sharing the store may still use it. A temp goes once it is an
hour old; nothing younger than an hour is taken. Only the names vx writes are taken:
`<hash>` is the key's 16 lowercase hex digits and the temp suffix is
the one a save makes, so a `release.tar.zst` beside the index in a
`cacheDir` you share is never touched (item 968). The converse, an
index row whose artifact is gone (deleted by hand), is dropped by the
same prune, and its bytes count toward neither `--max-size` nor the
evicted total: they are on no disk, and counting them evicted real
entries to make room for them (item 975). A row used within the hour
is kept until a later prune, but its bytes are left out all the same
(item 1081). The sweep runs on every prune, under
either flag, and reports separately from the policy's evictions. A
workspace's `cacheRetention` runs it too, at the end of a run, at most
once an hour even when nothing the index holds is due (the policy sums
index rows, so orphans alone never make it due).

Both flags take either form: `--older-than 30d` or `--older-than=30d`.

**Duration units**: `s`, `m`, `h`, `d`, case-insensitive. Examples:
`30d`, `24h`, `60m`, `30s`, `30D`.

**Size units**: `K`, `M`, `G`, `T` (powers of 1024), case-insensitive.
Optional `B` suffix is accepted. Examples: `500M`, `1G`, `100K`, `2T`,
`500MB`, `1gb`. A bare number is refused here: `--max-size 10` would
read as ten bytes and evict nearly everything, and nobody means that —
write `10G`, or `10B` when bytes really are the unit.

**A zero bound is rejected.** `--max-size 0` and `--older-than 0d` would
evict every entry in the cache, which is far more often a
computed-to-zero retention than an intent — and no flag combination
expresses "wipe the cache" (running with neither flag is an error, not a
full prune). Delete the cache store `vx info` names when that is really
what you want: the entries live there, not in the workspace's `.vx`.

```
$ vx cache prune --older-than 30d
Pruned 42 entries (1.3 GB freed)

$ vx cache prune --older-than 7d --max-size 500M
Pruned 18 entries (320 MB freed)

$ vx cache prune --older-than 30d      # after a SCHEMA_VERSION bump
Pruned 0 entries (0 B freed), reaped 42 orphaned artifacts (1.3 GB)

$ vx cache prune --older-than 30d --dry-run
Would prune 42 entries (1.3 GB), would reap 3 orphaned artifacts (12 MB)
```

`--dry-run` picks the victims under the same policy and counts the
orphans the sweep would take, then returns without touching the index
or the directory; the real prune with the same flags reaps exactly what
it named (an in-flight save aside). On an index an earlier vx wrote,
which the real prune resets first, it reads the index as that reset
leaves it: the shared store's entries still face the policy, and every
artifact in the workspace's own directory is row-less, judged by the
policy on its file time (item 1083).

A prune that deletes waits for a `vx run` on the same workspace to
finish first (the run's lock; it says `[vx] waiting for another vx run
(pid N) on this workspace to finish…` after a second), so it never
evicts what that run is restoring. One started by a task of that run
is refused instead: the run holds the lock until the task ends. A run it cannot see — another
workspace sharing the `--cache-dir` — survives a prune anyway: an
artifact that vanishes before its restore is a miss, and the task runs
([caching](../caching/#concurrent-runs)).

Exit codes:

- `0` — pruning completed (zero or more entries evicted). A workspace
  that never ran has no cache: `Pruned 0 entries (0 B freed)`, and
  nothing is created.
- `1` — parse error, missing policy, or workspace-discovery error.

`vx cache prune` resolves the workspace root from cwd and honors a
`defineWorkspace({ cacheDir })` override — it prunes the same
directory a run would use. `--cache-dir <path>` (cwd-relative, as on
`vx run`) names another one, so a run that wrote elsewhere can be
pruned there.

## `--frozen` (run flag)

`vx run ... --frozen` loads configs from the committed `vx-lock.json`
instead of evaluating them — CI reproducibility mode. Plain `vx run`
always evaluates live (a byte hash can't see a config's import
closure, so silently consuming the lock locally would risk stale
freezes). `--frozen` errors only when no lock exists or a project
is missing from it — it performs NO staleness checks of its own:
run `vx lock --check` first in the pipeline; that audit re-evaluates
everything, making any per-run re-check redundant.

## `vx lock`

Freeze every project's **resolved** config into `vx-lock.json` at the
workspace root. Configs are programs; `vx lock` evaluates them in the
current environment and stores the post-evaluation objects plus a
content hash of each config file. "Every project" is the set a run
sees, a plugin's `discover` stage included (X-143).

```
vx lock              # Evaluate all vx.config.* now; write vx-lock.json.
vx lock --check      # Audit: hash checks + full re-evaluation vs the lock. Exit 1 on drift.
vx lock --check --format json   # The audit as {upToDate, audited, notAudited, problems}.
```

Plain runs ALWAYS evaluate live — the lock's existence changes
nothing. Only `vx run --frozen` consumes it: configs come from the
lock with no evaluation and no staleness checks of its own (frozen-env
semantics: env reads in a config keep their lock-time values; a
project absent from the lock, a locked project whose config file is
gone (X-144) or a missing lock is a hard error).

`--check` is the audit: it reports changed config files via the
stored hashes AND re-evaluates every config in the current
environment, `Bun.deepEquals`-comparing against the frozen objects —
catching eval-time env and import-closure drift that byte hashes
cannot see. The CI recipe is `vx lock --check && vx run … --frozen`.
`--format json` prints the audit as one document
(`schemas/lock.json`, exit code unchanged; a missing lock is one of
its `problems`); it answers `--check` only.
Full design: `docs/design/config-lock-2026-06.md`. A lock written by a
1.x vx stays valid for every later 1.x (`tests/contract-lockfile.test.ts`).

A project with no `vx.config.*` — its tasks from a plugin's `project`
stage (`turbo()` from `@vzn/vx-migrate`), or none at all — has nothing
to freeze: the lock records nothing for it, `--check` does not audit
it, and `--frozen` still loads its tasks live. Both verbs say how many
such projects the workspace has (`locked 0 project configs →
vx-lock.json (2 projects have no vx.config; their tasks are never
frozen)`), so an empty lock on a plugin-only workspace never reads like
an audit.

The lock is committed, so `vx lock` refuses to write one that holds a
secret: a config that evaluated to the value of a secret-named variable
(or one a task lists in `exec.env.secret`), say
`` `--token ${process.env.API_TOKEN}` ``. It names each place
(`a: tasks.deploy.exec.command holds $API_TOKEN`) and writes nothing.
Masking it instead would freeze a `***` that `--frozen` runs. Let the
shell expand it: `$API_TOKEN` in the command, the name in
`exec.env.passThrough` (L-42).

Exit codes:

- `0` — lock written / lock is up to date.
- `1` — parse error, workspace-discovery error, missing lock
  (`--check` without one), any drift (every mismatched project is
  listed on stderr), or a secret value the lock would hold.

## Releasing (maintainers)

Releases are on demand. Dispatching `auto-release.yml` releases a
commit on `main` whose CI went green: the `sha` input, or by default the
newest such commit; one CI did not pass on is refused. Claude dispatches
it at least once a day when `main` has changes, after merging that
release's blog post (`.claude/skills/release/SKILL.md`), and shares the
post on Bluesky. The workflow tags the commit with the next version and
creates the GitHub release, both from the Conventional Commits since the
last tag (`scripts/release-notes.ts`, run by the `release.auto` task,
`scripts/auto-release.ts`). The release is created as a draft: this
repo's releases are immutable and take assets only before they are
published, so `release.yml` publishes it after its last upload. The version: below 0.1.0 always a
patch (cutting 0.1.0 is the owner's, by hand); then before 1.0 a `feat`
or a breaking change (`type!:`, a `BREAKING CHANGE:` footer) is a minor
(`v0.4.2` → `v0.5.0`) and anything else a patch (`v0.4.3`); from 1.0 a
breaking change is a major. The notes: breaking changes first, then
`feat`, `fix` and `perf`, the rest counted. It then
dispatches `release.yml` (with `tag`) and
`npm.yml` (with `version` and `ref`). A release made with the workflow
token fires no `release` event in other workflows, which is why the two
are dispatched rather than triggered. A commit is released only when the
last release is its ancestor, so an older tree never gets a higher
version, and one that already carries a `v*` tag is a no-op.

A version can still be cut by hand: push its tag (say `v1.0.0`),
create a draft release for it, and dispatch `release.yml` (`tag`) and
`npm.yml` (`version`, `ref`); the next auto-release continues from it.

A GitHub release publishes everything: `release.yml` builds the four
binaries, proves the darwin ones on macOS (re-signed ad hoc only where
macOS refuses one) and attaches them; `npm.yml`
builds the twelve npm packages (`@vzn/vx`, one per platform, and the
seven plugin packages) and publishes them with **npm trusted
publishing** — the job's OIDC token
is exchanged for a short-lived credential and provenance is attached,
so no long-lived npm token exists anywhere. Both publish loops skip a
package already on the registry, so a re-run (`npm publish` →
_Run workflow_ with the version) resumes where it stopped. That dispatch
also takes a `ref`: it runs the workflow from the default branch against
the code that ref names, so a release whose publish died on a workflow
bug is completed by the FIXED workflow building the tag's own source
(`version: 0.0.20`, `ref: v0.0.20`) — re-running the failed run itself
would replay the broken file, which is pinned to the tag.

Every step of the three workflows past the setup (checkout, Bun, Node,
`bun install`, the runner action) is one vx task: CI runs no command of
its own (owner, 2026-10-03), and `tests/workflow-runner.unsafe.test.ts`
holds it. The tasks are `@vzn/vx`'s `release.*`, all uncached and in no
`ci` graph:

| Task                    | Does                                                                                                                                     |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `release.stamp`         | writes `VX_RELEASE_VERSION` into `packages/vx/package.json`, the manifest the binary inlines                                             |
| `release.npm`           | checks npm can publish with provenance (>= 11.5.1, `sigstore` loads); else installs npm into `dist/npm-cli/`                             |
| `release.prove.<os>`    | launches the host's binary (re-signed only if macOS refuses it) and asserts `vx <version>`; on darwin, launches both (x64 under Rosetta) |
| `release.assemble.<os>` | emits the platform packages under `dist/npm` (linux: also `@vzn/vx` and the plugins)                                                     |
| `release.publish.<os>`  | `npm publish --provenance` each in order, skipping one the registry holds                                                                |
| `release.upload.<os>`   | attaches `dist/vx-<os>-*` the draft release lacks; darwin's then publishes it                                                            |
| `release.auto`          | decides the version, creates the draft release with its notes, dispatches the two workflows                                              |

The version reaches them as `VX_RELEASE_VERSION` (the tag or the
dispatch input) and each refuses one that is not a version. Every one
is sandboxed: the publish is granted the registry, the OIDC token host
and Sigstore, the GitHub-Actions variables npm reads, and `~/.npm`;
`release.auto` reads `.git` and reaches `api.github.com` with `GH_TOKEN`;
`release.upload.<os>` reaches it and `uploads.github.com`.
A dispatch with `ref` builds that ref's code, so it must hold these tasks.

All Linux jobs go through `.github/actions/vx-runner` before any
`vx run`: every task in this repo declares `exec.sandbox`, and a
declared sandbox whose runtime is missing is a hard error, not a
downgrade — the compile tasks fail in 0 ms saying which of bubblewrap,
socat and ripgrep is absent. v0.0.20 shipped its darwin packages and
then stopped exactly there.

One-time setup, per package, on npmjs.com → package → Settings →
Trusted Publisher → GitHub Actions: owner `vznjs`, repository `vx`,
workflow `npm.yml`, environment left blank. Do this for `@vzn/vx`,
`@vzn/vx-darwin-x64`, `@vzn/vx-darwin-arm64`, `@vzn/vx-linux-x64`,
`@vzn/vx-linux-arm64` and the seven plugins: `@vzn/vx-ci`,
`@vzn/vx-lockfile`, `@vzn/vx-mcp`, `@vzn/vx-migrate`, `@vzn/vx-otel`,
`@vzn/vx-reapi` and `@vzn/vx-schedule-history`.

Each platform package carries `LICENSE` and `THIRD_PARTY_NOTICES.txt`:
the binary embeds Bun and npm code whose licenses must travel with it.
The GitHub release carries the same file as an asset beside the binaries.
`tests/dependency-licenses.unsafe.test.ts` holds every published package's
production dependency closure to permissive licenses (MIT, ISC, BSD,
Apache-2.0, 0BSD, or a dual license offering one).
After a dependency or Bun bump, `bun packages/vx/scripts/third-party-notices.ts`
regenerates the notices; `tests/third-party-notices.unsafe.test.ts`
fails until it does.

The plugins ship as the TypeScript source Bun runs, at the release's
version, with `@vzn/vx` as a peer on the same minor (`^<version>`).
`scripts/build-npm.ts --only=plugins` emits every public workspace
package other than `@vzn/vx`, so a new plugin package is published
without a workflow edit, and `tests/build-npm.unsafe.test.ts` holds the
set. If npm will not add a trusted publisher to a name that has never
been published, publish that plugin once by hand from an owner's
account (`npm publish dist/npm-plugins/plugins/<dir> --access public`
after a `build-npm.ts <version> --only=plugins --out=dist/npm-plugins`
build), then add the publisher. Then
delete the `NPM_TOKEN` repository secret:
the workflow no longer reads it, and npm restricts classic tokens for
direct publishing (the `E401 token is invalid` that stopped v0.0.17).
Every `uses:` in both workflows is pinned to a commit SHA with the
version in a comment; bump the SHA and the comment together.

## `vx upgrade`

Self-update the compiled binary in place: asks the GitHub release API
for this platform's asset and the SHA-256 digest it publishes,
downloads the asset, verifies the digest, and atomically replaces the
running executable (`vx upgrade TAG` pins a specific release; default
latest; a second tag is refused, not dropped). A download that does not match the digest replaces nothing —
`the download did not match the release's SHA-256 … nothing replaced` —
and a release that publishes no digest for the asset is refused before
the download. The digest comes from the same API as the asset, so it
proves the transfer, not who built the bytes: every release binary also
carries a Sigstore-signed build-provenance attestation, checked with
`gh attestation verify vx-<target> --repo vznjs/vx`. Named
`upgrade` per CLI convention (`bun upgrade`, `deno upgrade`). Refuses
when running from source — use `git pull` — and when the binary is
npm's: an npm install runs the platform package's compiled binary
under `node_modules`, and a rename over that file lasts until the next
`npm install` puts the version npm knows back, so `vx upgrade` there
says `this vx was installed by npm … Update with: npm install -g
@vzn/vx@latest`. A host it cannot reach (no route, a proxy that is
down) is one line — `could not reach api.github.com to read the
release (…) — check the network or the proxy and re-run` — never a
stack; so is a release document cut after the headers arrived or not
JSON (a captive portal's page served with a 200): `could not read the
release from api.github.com (…) — nothing replaced; …`, and an asset
download cut the same way: `could not download the release asset from
github.com (…) — nothing replaced; …`. A binary whose directory this
user cannot write (a root-owned `/usr/local/bin`) is refused before the
download: `cannot write to &lt;dir&gt; (EACCES), where this vx lives — nothing
downloaded; re-run as a user who can (sudo vx upgrade), …`. The new binary
keeps the old one's mode (and, as root, its owner), and must answer
`--version` before the upgrade reports it installed: one that does not
start on this machine — or does not answer within 10 s — is swapped back
for the previous vx, and the command exits 1 saying so (item 1097). On the version it already is
it says `already at <version>` and downloads nothing; a second tag is
refused rather than ignored; and GitHub's hourly API limit for an
unauthenticated address is named, with its reset time, instead of a
bare `(403)` (item 1098).

Exit codes: `0` the new binary installed, or already at that version;
`1` anything refused or swapped back: from source, from npm, a host it
cannot reach, a directory it cannot write, a digest that does not match,
a binary that does not start.

## `vx init`

In a Turbo or Nx repo (a `turbo.json`, `turbo.jsonc` or `nx.json` at
the root) it runs `@vzn/vx-migrate`, so `vx init` is the one command
(owner, 2026-10-08): the installed one, else this vx's version through
`bun x` (`BUN_BE_BUN=1` makes the compiled binary that runtime). It asks a
terminal native (a `vx.config.ts` per package, the default) or keep;
`--native` or `--keep` answer it, and without a terminal it is native.
`--dry`, `--format`, `--force` and `--mjs` pass through.

`vx init --dry --format json` prints the plan as one JSON document
(`schemas/init.json`), nothing written: `files` (each path and its
whole text), `kept`, `replaced`, `todos` (a reason and its tasks),
`notes` and `next`. In a Turbo or Nx repo it is `@vzn/vx-migrate`'s
plan. `--format json` without `--dry`, or with `--plugin`, is refused
(`VX_E_USAGE`).
Run again after the native migration (a workspace file that declares
neither `turbo()` nor `nx()`, and project configs), it says vx is already
set up and prints the next step, exit 0, without starting
`@vzn/vx-migrate`; `--force` regenerates the files.

`vx init --keep` writes `vx.workspace.ts` declaring `turbo()` or `nx()`
from `@vzn/vx-migrate` and nothing else: those read the repo's own
config live, so no task is copied — a temporary start until
`vx init --native` writes native config. `--native` or `--keep` in any
other repo is refused. The `next:` line is one command:
install what the file imports and is missing, with the manager the
lockfile names (at the workspace root: pnpm's `-w`, Yarn 1's `-W`,
which Yarn Berry lacks), then run the config's `build` (else its first task).
An existing workspace file is kept and named unless it already
declares the plugin; `--force` replaces it. When the repo shows a remote
cache — turbo.json's `remoteCache`, a `.turbo/config.json` naming a
team or token (`turbo link` writes it), or a line setting `TURBO_TOKEN` /
`NX_SELF_HOSTED_REMOTE_CACHE_SERVER` (`NAME:` or `NAME=`, not a comment)
in `.github/workflows/*`, `.gitlab-ci.yml` or `.circleci/config.yml`,
and turbo.json does not say `remoteCache.enabled: false` — it
declares `turboCache()` / `nxCache()` beside the runner and names the
file that showed it (a kept file lacking it is told to add it); the
plugin is inert where its variable is unset. An nx.json that connects
Nx Cloud (`nxCloudId`, `nxCloudAccessToken`, the `nx-cloud` runner) is
named instead: vx does not speak its wire, so runs cache locally.

Anywhere else it scaffolds a workspace that comes from nowhere: one `vx.config.ts` per
package from its `package.json` scripts, plus a `vx.workspace.ts` of
`{ plugins: [] }`: running and caching here are the floor, so it
declares no executor or cache, and the file carries no comment (it is
the user's). `@vzn/vx-migrate` takes the
same `--dry` / `--force` flags but reads a runner's config (turbo, nx);
package.json scripts are `init`'s. A workspace with no scripts at
all still gets the workspace file, a printed example config, and the
next command to run. A root
`package.json` with no `workspaces` field is single-project mode, and
when `packages/*/package.json` files sit below it unreached, both
`init` and a run that finds no config say so instead ("package.json
declares no workspaces … Add "workspaces": ["packages/*"] to
package.json and re-run") rather than "no scripts" or "run vx init". A
workspace whose globs match no `package.json` gets a note naming them
(M-42); a nameless member, or two sharing a name, is matched and
named on its own line instead (M-46). When such skipped scripts are all there
is, the report opens `no package.json scripts became tasks.` rather than
saying there are none (M-59). When `pnpm-workspace.yaml` lists the
members and the root `package.json`'s `workspaces` lists other globs,
the note names the unread list (M-51): pnpm reads only the yaml, while
bun, npm and yarn read `package.json`. With
no `package.json` here or above, `init` says to create one (`bun init` or
`npm init -y`) first. Every
generated config is typed for the editor through
`import type { ProjectConfig } from '@vzn/vx/config'` and `satisfies
ProjectConfig` — a type-only import Bun erases, so the file loads in a
workspace that runs the `vx` binary without the package installed. The
workspace file takes the same form (`satisfies WorkspaceConfig`). A
runtime `import { defineWorkspace } from '@vzn/vx'` costs nothing extra
since 2026-09-10: the running `vx` serves its own core to that
specifier (bin.ts registers the alias), so a config or a plugin package
never loads a second copy, and a workspace that runs the binary needs
no `@vzn/vx` installed for it — the type-only form is still what the
scaffold writes, because it types the same with no import to resolve
in an editor without the package. A workspace that imports a PLUGIN
package at runtime without having installed it is told so, and to
install its dependencies. `--mjs` writes the same objects as `vx.config.mjs` and
`vx.workspace.mjs`, with no type import and no `satisfies`: a package whose
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.

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
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`
generated until 2026-09-04), and a guessed `dist/**` would restore the
wrong tree for every package that writes elsewhere. The block the TODO
shows names `dist/**`, or the default output of the framework the command
runs: `.next/**` minus `!.next/cache/**` for `next build`, `.output/**`
for Nuxt, `build/**` for Remix, React Router, Create React App and
Docusaurus, `public/**` for Gatsby, `storybook-static/**` for Storybook;
for any other command, the directory it names with `--outDir` / `--out-dir`
/ `-d`, else the ones it cleans first (`del-cli distribution`, `rimraf lib
types`), unless it makes one again with `mkdir` (D-90).
A package in a cycle of builds (nuxt's `@nuxt/nitro-server` devDepends
on `nuxt`, which depends on it; pnpm sorts it away) gets, instead of
`^build`, an edge to each build outside its cycle that `^build` would
reach, and a TODO to order the cycle: `^build` there refuses the run.
`test` / `typecheck` wait for
`build` when the package has one (`lint` reads sources and gets no
edge); `dev` / `start` / `serve` / `watch` /
`preview` become persistent tasks, with a TODO to add `readyWhen` when
another task depends on one, and so does a watcher: a `watch` segment in the script's name (`build:watch`),
a `--watch` flag, `tsc -w` / `rollup -w`, or nodemon (D-40), and a server:
`serve <dir>`, `http-server`, bare `vite`, a tool's `dev` / `serve` /
`start` / `preview` verb (`next start`, `netlify dev`), or a script that
runs such a script of its package by name (`cross-env X=1 pnpm start`) or
through a runner (`run-p web api`, `concurrently "npm:web" "npm:api"`, D-113),
outside quotes and not sent to the background with `&` (D-91), read past
a launcher's `--package <name>` / `-p <name>` (`pnpm dlx --package
netlify-cli netlify dev`, D-112). A
script whose name no task may carry (`lint#fix`, `^up`; the schema's
rule, item 1000) is left out with a TODO rather than written into a
config every later command refuses, and a `__proto__` script is written
as a computed key, since a literal `__proto__:` sets the prototype. An
existing `vx.workspace.*` in any extension the loader reads (`.mts`
included) is kept, and `--force` REPLACES a package's config of another
extension (`replaced:` in the report) rather than writing a second one
the loader would choose between by its order (item 1033). Without
`--force`, `init` never overwrites: a package that already has a vx
config keeps it, untouched, the rest get theirs, and the report lists
the kept ones under `kept`, so a half-adopted workspace adopts the rest
(M-52). `@vzn/vx-migrate` still refuses an existing config.

A missing `vx.workspace.*` is not an error. A run where no package has
a config fails before any task, exit 1:
``vx run: no projects declare task(s): build. No package declares a vx.config — run `vx init` to write one per package from its package.json scripts.``

Two npm conventions are mapped rather than copied, because copying them
loses behaviour. `pre<x>` / `post<x>` hooks, which npm runs around `x`
without being named, are folded into `x`'s command in that order, each
in its own subshell, so the chain stops at the first that fails whatever
a part holds (a `;`, an `exit`), and forwarded `--` args reach `x` alone,
as npm hands them to the script and not its hooks (item 905), appended
as text, so no part sees them as `$1` (X-60). The
command is a small shell function, `vx_script`, around the three parts;
it carries a TODO saying so; a `pre<x>` with no `x` stays a task of its own, and
npm's lifecycle hooks (`prepack`, `prepublishOnly`, …) are never tasks.
A member with no script to run (none, or only lifecycle hooks: a
types-only or config package) gets no `vx.config.ts` and is named in
the report; it is still a project, and a task declared in its own
`vx.config.ts` runs. A package with no `build` script whose `prepack`, `prepublishOnly`,
`prepublish` or `prepare` runs a builder (`bob build`, `tsc`, `tsup`, …)
is named in the report, which says to add a `build` script running it
(react-navigation's twelve packages, whose root `build` is `lerna run
prepack`, mapped with no build at all).
Where the package's manager runs no such hooks every `pre<x>` and
`post<x>` is a task of its own: Yarn 2+ (the nearest `packageManager:
yarn@2+`, or a Berry `yarn.lock`, D-31; a `packageManager` naming none of npm,
pnpm, yarn or bun defers to the lockfile, D-96), npm under `ignore-scripts=true`
in the `.npmrc` beside its lockfile, pnpm under
`enable-pre-post-scripts=false` there or `enablePrePostScripts: false` in
`pnpm-workspace.yaml` (D-33). Bun and Yarn 1 run them whatever those say.
Under Yarn 2+ a segment's `run <script>`, Yarn's shell builtin, is written
`yarn run <script>`: vx's shell has no `run` (D-92).
A Yarn 2+ repo on Plug'n'Play (no `nodeLinker: node-modules` or `pnpm` in
`.yarnrc.yml`) keeps its bins in `.pnp.cjs`, where vx's PATH finds none;
the report says so and names `nodeLinker: node-modules` or `yarn exec
'&lt;command&gt;'` (D-108).
A script reading `$npm_package_version`, `$npm_package_name` or
`$npm_lifecycle_event`, which every manager sets and vx does not, gets
them under `exec.env.define`, the first two read from an imported
`package.json` so a version bump reaches them; any other `$npm_*` it
reads gets a TODO (D-34). Among several packages, a workspace root
script that runs the members (`pnpm -r build`, `--filter`, `-C`, pnpm's `pn` alias
included (D-97), Yarn's
`--cwd` and `yarn workspace <name>`, npm's `--prefix`, npm's
and Yarn's workspace flags, a `cd` into or above a member, turbo, nx, lerna, `vp run`, vx itself) is not mapped
(a flag counts on the package manager, or after `node <bin> run`, and not on the program it
runs: berry's `yarn node -r ./setup.ts` is node's `--require`, D-81; bun's
`cd test && …` enters no member, D-83),
nor is one that runs such a script by name (vite's `ci-docs`: `pnpm build &&
pnpm docs-build`; through `run-s` / `run-p` / `npm-run-all` or `concurrently
"npm:x"` too, lexical's `ci-check`, D-95), and neither is one whose name a member's task carries, so `--all` never runs
a check twice (D-45). The rest check the whole repo (`lint: oxlint .`,
`test: vitest`) and become the root's own tasks in a root vx.config, when
the root has a `"name"` (vx skips a nameless root's config) and no config
of its own; one already there, hand-written or from an earlier
`vx init`, stays as written, `--force` included, and is listed under
`kept`. The report names each script left out and why
(a `pre` / `post` hook goes with its script, D-85), its examples of running
the members spelled by the repo's manager (`--workspaces` under npm, `yarn
workspaces foreach` under Yarn 2+), and says which;
with nothing mapped it names the root whenever it has a script, a member
or not (pnpm's root is not), and why: its scripts run the workspace, or
share a member's task name (listed), or both; it tells a root with no `"name"` to add one
first (vuejs/core), naming the scripts that would then map (react, D-87), and a root whose
`"name"` a member also carries to rename it, since a root config would make the
workspace refuse every run for the duplicate (insomnia, D-129). A single-package repo's root is its project and maps.
A lone root beside a `lerna.json` (Lerna-classic: packages listed there, not
in `workspaces`) gets a note naming the `workspaces` globs to add, Lerna's
`packages/*` default when it lists none (D-111).
A member whose package.json has no `name` is no project; one with a
script is named in the report, to be given a name (remix's
`packages/component/bench`, D-106).
A member's script that runs another member's work (`pnpm -C ../pinia
run build`, `yarn workspace &lt;name&gt;`, `-r` / `--filter`, a `cd` or `-C`
/ `--cwd` / `--prefix` into another member) keeps its command and gets a
TODO naming that part: the graph runs that member's task once, so name it
under `dependsOn` and drop it from the command (pinia). A directory inside
the member or the root is no other member.
A script that is nothing but `npm run <other>` (`pnpm <other>`, `yarn
&lt;other&gt;`, `bun run &lt;other&gt;`, `npm test`, `npm start`) becomes a **group**
over `<other>` — `dependsOn` and no command — so the graph runs and
caches the target instead of a package-manager subprocess it cannot
see. When `build` is such a group, the task it reaches that runs a
command takes `^build` and the cache TODO, since a group has nothing
to cache; it and the groups on the way drop the wait on `build` a
`typecheck` or `test` would carry, since they are the build (D-16). Bare, a package manager's own command is not a script: `bun test`
is Bun's test runner, `bun build` its bundler, `pnpm install` and `yarn
add` the managers' verbs, so each stays a command (item 908), and so do
the names each manager reserves or hands on: `pnpm docs` and `pnpm
version` (npm's), `bun deploy`, `yarn check` (D-32); `pnpm test`, `yarn
test` and `bun lint` do run the script. Arguments, flags or a `&&`
chain make it a real command again and
it is left verbatim, and so is one whose target becomes no task (a
lifecycle script, or a hook folded into another script): a group over
it would name a task nothing defines (D-12). A verbatim chain whose
parts run this package's own scripts (`check: pnpm run build && pnpm run
lint`) gets a TODO naming those parts: each ran again inside the command,
beside its own task, so `vx run check` built twice (M-41). So does a
part that runs them through `run-s`, `run-p` or `npm-run-all`
(`build: run-p build:*`), unless the task is persistent (M-48). Its
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
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
runner, a bare `vx`. Outside a git work tree it starts with
`git init`, and with no script mapped with declaring a task, since the
run would refuse without either. It runs `build`, else the first task that
neither serves (`persistent`) nor changes the repo (`clean`, `release`,
`publish`, `deploy`, `version`, `format`, `fix`, …), else the first task
(react-navigation was told `vx run clean --all`).

`vx init --plugin <seam>` writes a plugin instead: `plugins/<seam>.ts`,
a small runnable plugin for that seam (`executor`, `cache`,
`telemetry`, `schedule`, `admit`, `commands`, `project`, `graph`,
`key`), and `plugins/<seam>.test.ts`, which drives it through `run()`
(`bun test`, with `@vzn/vx` installed). It prints the line that
declares it in the workspace file a run reads (`vx.workspace.ts` when
there is none). The templates are TypeScript, so `--mjs` with
`--plugin` is refused. An existing file is refused without
`--force`; `--dry` names the files and writes nothing. The two files are
`packages/vx-plugin-examples/plugins`, which the gate runs, copied into
core (`src/cli/plugin-templates.ts`) and held equal by
`tests/plugin-templates.unsafe.test.ts` (H-21).

Exit codes: `0` the files written (or, with `--dry`, printed); `1` no
`package.json` here or in a parent, a file it would write already there
without `--force`, or a parse error (`--mjs` with `--plugin` among them).

## `vx migrate`

Moved out of core on 2026-09-10: the Turbo and Nx mappers are
`@vzn/vx-migrate`, their own package, run without a workspace file —

```
bunx @vzn/vx-migrate           # turbo.json, an Nx graph or vite-plus run.tasks → vx.config.ts
bunx @vzn/vx-migrate --dry     # print the generated files instead of writing
bunx @vzn/vx-migrate --force   # overwrite existing vx.config.* / vx-preset.ts
bunx @vzn/vx-migrate --from nx # disambiguate when both runners are checked in
```

— and `package.json` scripts are `vx init` (above). Typing `vx migrate`
prints that pointer and exits 1. What the package writes reads exactly
like what `vx init` writes: both hand a plan to core's migration seam
(`applyMigration`, exported from `@vzn/vx`), which renders, guards
against overwriting, writes and reports. The mapping rules live in the
package's README.

## Turbo and Nx flags

What a Turbo, Nx or Vite Task (`vp run`) user types into `vx run` (and `vx watch`): each flag
vx takes as it is (`same`), rewrites to its own spelling before the
parse (`alias`), or refuses with the vx way to say it (`refuse`) —
none is dropped in silence. An Nx flag's camelCase spelling (`--nxBail`,
`--skipNxCache`), which Nx's parser takes and its docs print, is its
kebab-case row. A `[=<bool>]` row takes `=true` (the flag bare) and `=false` (left out), as Turbo's and Nx's parsers do. `vx run-many` and `vx affected` name the
`vx run` that does the same, and the other verbs a hand types from
either tool name what does it here: `graph` (`--graph`), `ls`
(`vx show`), `query` (`--dry=json`), `reset` (`vx cache prune`), and
`daemon`, `login`, `logout`, `link` and `unlink`, which vx has no use
for. Nx's `project:target` (`vx run web:build`,
when `web` declares `build`) is answered with `vx run web#build`: from
outside a project in place of "not inside a project", in scope as the
unresolved name's `Did you mean`. A name that is no project but ends
the one scoped package (`cart` for `@nx-example/cart`, as Nx names it)
means that package there and in `vx build cart`. The table is `cli/foreign-flags.ts`,
rendered; `tests/foreign-flags.test.ts` drives every row and holds this
copy to the source.

| runner | flag                                              | outcome | in vx                                                                                                                                             |
| ------ | ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| turbo  | `--filter <v>`                                    | same    | `--filter`, the same grammar (`...[ref]`, `{dir}`, `^`, `!`)                                                                                      |
| turbo  | `-F <v>`                                          | alias   | `--filter <v>`                                                                                                                                    |
| turbo  | `--concurrency <v>`                               | same    | `--concurrency <n\|n%>`                                                                                                                           |
| turbo  | `--continue=dependencies-successful`              | alias   | `--continue=deps-ok`                                                                                                                              |
| turbo  | `--continue`                                      | same    | `--continue[=never\|deps-ok\|always]`                                                                                                             |
| turbo  | `--dry-run`                                       | alias   | `--dry[=text\|json]`                                                                                                                              |
| turbo  | `--graph=<file>.svg\|png\|json\|html\|…`          | refuse  | vx writes Graphviz DOT only: `--graph=<file>.dot`, then `dot -Tsvg`                                                                               |
| turbo  | `--graph`                                         | same    | `--graph[=<file>.dot]`                                                                                                                            |
| turbo  | `--force[=<bool>]`                                | same    | `--force`: skip cache reads, keep writes                                                                                                          |
| turbo  | `--affected`                                      | same    | `--affected[=<base>]`                                                                                                                             |
| turbo  | `--summarize[=<bool>]`                            | same    | `--summarize[=<path>]`                                                                                                                            |
| turbo  | `--output-logs=new-only`                          | refuse  | use `--output-logs=full` (a hit replays its log) or `errors-only`                                                                                 |
| turbo  | `--output-logs <v>`                               | same    | `--output-logs full\|errors-only\|hash-only\|none`                                                                                                |
| turbo  | `--no-cache`                                      | same    | `--no-cache` reads nothing either; Turbo's (reads, no writes) is `--cache local:r,remote:r`                                                       |
| turbo  | `--cache <v>`                                     | same    | `--cache local:rw,remote:r`                                                                                                                       |
| turbo  | `--cache-dir <v>`                                 | same    | `--cache-dir <path>`                                                                                                                              |
| turbo  | `--profile`                                       | same    | `--profile[=<path>]` (Chrome trace)                                                                                                               |
| turbo  | `--only`                                          | alias   | `--exclude-dependencies`                                                                                                                          |
| turbo  | `--color`                                         | refuse  | set `FORCE_COLOR=1`                                                                                                                               |
| turbo  | `--no-color`                                      | refuse  | set `NO_COLOR=1`                                                                                                                                  |
| turbo  | `--heap <v>`, `--trace <v>`                       | refuse  | use `--profile[=<path>]` for vx's own trace                                                                                                       |
| turbo  | `--login <v>`                                     | refuse  | vx has no login: a remote cache is a plugin (`turboCache()` from @vzn/vx-migrate)                                                                 |
| turbo  | `--no-update-notifier`                            | refuse  | vx prints no update notice: drop it                                                                                                               |
| turbo  | `--skip-infer`                                    | refuse  | vx runs the binary it is: drop it                                                                                                                 |
| turbo  | `--root-turbo-json <v>`                           | refuse  | `turbo()` reads the `turbo.json` at the workspace root: move it there                                                                             |
| turbo  | `--experimental-otel-*`                           | refuse  | telemetry is a plugin: `otel()` from @vzn/vx-otel in vx.workspace.ts                                                                              |
| nx     | `--parallel <n>`                                  | alias   | `--concurrency <n>` (`--parallel=false` is 1)                                                                                                     |
| turbo  | `--parallel`                                      | refuse  | vx always honours `dependsOn`; `--concurrency <n>` sets how many run at once                                                                      |
| turbo  | `--scope <v>`                                     | refuse  | use `--filter <pkg>`                                                                                                                              |
| turbo  | `--since <v>`                                     | refuse  | use `--filter '[<ref>]'` or `--affected=<ref>`                                                                                                    |
| turbo  | `--remote-only[=<bool>]`                          | refuse  | use `--cache local:,remote:rw`                                                                                                                    |
| turbo  | `--remote-cache-read-only[=<bool>]`               | refuse  | use `--cache local:rw,remote:r`                                                                                                                   |
| turbo  | `--anon-profile`                                  | refuse  | use `--profile[=<path>]`; vx has no redacting variant, so read it before sharing it                                                               |
| turbo  | `--cache-workers <v>`                             | refuse  | vx sizes its own cache I/O: drop it                                                                                                               |
| turbo  | `--cwd <v>`                                       | refuse  | run vx from that directory: `cd <dir> && vx run …`                                                                                                |
| turbo  | `--dangerously-disable-package-manager-check`     | refuse  | vx reads no `packageManager` field: drop it                                                                                                       |
| turbo  | `--env-mode <v>`                                  | refuse  | vx passes only the variables a task declares (strict): list the rest in `exec.env.passThrough`                                                    |
| turbo  | `--framework-inference <v>`                       | refuse  | under `turbo()` inference is Turbo's; take a name back with a `!` entry in the task's `env`                                                       |
| turbo  | `--global-deps <v>`                               | refuse  | declare them in `cache.inputs.workspaceFiles` (under `turbo()`, turbo.json's `globalDependencies`)                                                |
| turbo  | `--json`                                          | refuse  | use `--format json` for the run's result on stdout, `--dry=json` for the plan                                                                     |
| turbo  | `--log-file`                                      | refuse  | use `--summarize[=<path>]` for the run's JSON record                                                                                              |
| turbo  | `--preflight`                                     | refuse  | set `turboCache({ preflight: true })` or `TURBO_PREFLIGHT=1`                                                                                      |
| turbo  | `--remote-cache-timeout <v>`                      | refuse  | set `turboCache({ timeoutMs })` or `TURBO_REMOTE_CACHE_TIMEOUT`                                                                                   |
| turbo  | `--single-package`                                | refuse  | a repo with no workspaces is one project already: drop it                                                                                         |
| turbo  | `--token <v>`, `--team <v>`, `--api <v>`          | refuse  | a remote cache is a plugin: `turboCache()` from @vzn/vx-migrate in vx.workspace.ts reads TURBO_TOKEN / TURBO_TEAM / TURBO_API                     |
| turbo  | `--no-daemon`, `--daemon`                         | refuse  | vx has no daemon: drop it                                                                                                                         |
| turbo  | `--ui <v>`, `--log-order <v>`, `--log-prefix <v>` | refuse  | vx frames each task’s output: `--output-logs <mode>` sets how much                                                                                |
| nx     | `-t <v>`, `--targets <v>`, `--target <v>`         | alias   | the task names, positional: `vx run build test`                                                                                                   |
| nx     | `-p <v>`, `--projects <v>`                        | alias   | `--filter <pattern>`, one per project (`directory:<d>` is `./<d>`, `name:<n>` is `<n>`); a list opening with `!` starts from all (`--filter '*'`) |
| nx     | `--exclude <v>`                                   | alias   | `--filter '!<pattern>'`, one per project                                                                                                          |
| nx     | `--base <v>`                                      | alias   | `--affected=<ref>`                                                                                                                                |
| nx     | `--head HEAD`                                     | alias   | nothing: vx compares `--affected=<base>` with the working tree                                                                                    |
| nx     | `--head <v>`                                      | refuse  | vx compares `--affected=<base>` with the working tree: check out the head first                                                                   |
| nx     | `--skip-nx-cache[=<bool>]`                        | alias   | `--force`                                                                                                                                         |
| nx     | `--all`                                           | same    | `--all`                                                                                                                                           |
| nx     | `--nx-bail[=<bool>]`                              | alias   | `--continue=never`                                                                                                                                |
| nx     | `-c <v>`, `--configuration <v>`                   | refuse  | a configuration is its own task: `vx run <target>:<configuration>`                                                                                |
| nx     | `--output-style <v>`                              | refuse  | use `--output-logs <mode>`                                                                                                                        |
| nx     | `--uncommitted`, `--untracked`                    | refuse  | use `--affected=HEAD` (the working tree against the last commit)                                                                                  |
| nx     | `--max-parallel <v>`                              | alias   | `--concurrency <n>`                                                                                                                               |
| nx     | `--exclude-task-dependencies[=<bool>]`            | alias   | `--exclude-dependencies`                                                                                                                          |
| nx     | `--skip-remote-cache[=<bool>]`                    | alias   | `--cache local:rw,remote:`                                                                                                                        |
| nx     | `--verbose`                                       | refuse  | use `--verbosity <n>` (1 adds the summary table)                                                                                                  |
| nx     | `--files <v>`                                     | refuse  | vx asks git what changed: `--affected=<base>`                                                                                                     |
| nx     | `--batch`                                         | refuse  | vx runs one command per task: drop it                                                                                                             |
| nx     | `--dte`, `--use-agents`                           | refuse  | vx distributes nothing: drop it                                                                                                                   |
| nx     | `--nx-ignore-cycles`                              | refuse  | vx refuses a task cycle by name: break it                                                                                                         |
| nx     | `--runner <v>`                                    | refuse  | a remote cache is a plugin: `nxCache()` from @vzn/vx-migrate in vx.workspace.ts                                                                   |
| nx     | `--skip-sync`                                     | refuse  | vx never runs sync generators: drop it                                                                                                            |
| nx     | `--tui`, `--no-tui`, `--tui-auto-exit`            | refuse  | vx frames each task’s output: `--output-logs <mode>` sets how much                                                                                |
| nx     | `--no-cloud`                                      | refuse  | vx has no cloud: drop it                                                                                                                          |
| vp     | `-r`, `--recursive`                               | alias   | `--all`                                                                                                                                           |
| vp     | `-w`, `--workspace-root`                          | alias   | `--filter //` (the root project)                                                                                                                  |
| vp     | `--concurrency-limit <v>`                         | alias   | `--concurrency <n>`                                                                                                                               |
| vp     | `--ignore-depends-on`                             | alias   | `--exclude-dependencies`                                                                                                                          |
| vp     | `--fail-if-no-match`                              | alias   | nothing: a filter that matches nothing already fails the run                                                                                      |
| vp     | `--log <v>`                                       | refuse  | vx frames each task’s output: `--output-logs <mode>` sets how much                                                                                |
| vp     | `--last-details`                                  | refuse  | `vx last` prints the last run                                                                                                                     |

## Machine-readable output

`vx show`, `vx info`, `vx why`, `vx last` and `vx cache prune` take
`--format json`. Each prints one JSON document whose shape is a
checked-in JSON Schema (draft 2020-12) shipped with the package:
`schemas/show.json`, `schemas/info.json`, `schemas/why.json`,
`schemas/last.json`, `schemas/cache.json`
(`node_modules/@vzn/vx/schemas/` in an install). Every object closes its
key set, so a field vx adds is a schema change, never a surprise.
`tests/cli-json-schemas.test.ts` holds each verb's output to its schema,
each declared field to some output, and each object's keys to the
source type. `tests/cli-json-doc.test.ts` holds this page to the
schemas: each `{ … }` a verb's section shows is an object its schema
closes with those keys, each object the verb prints whole is shown, and
`vx info`'s field list is its schema's top level.

`vx run --format json` prints, when the run ends, the `--summarize`
document (`schemas/summary.json`: `runId`, `ok`, `exitCode`, one row per
task with its status, exit code and key). Everything else the run writes,
the frame and the tasks' output with it, goes to stderr, so
`vx run build --all --format json | jq .ok` reads only the result. It
refuses `--dry` (use `--dry=json`), a bare `--graph` and
`--report=markdown`, which print on stdout too.

### Error codes

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","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_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')`.

**Streams.** A verb whose stdout is a product (a `--format json`
document, `--dry` / `--dry=json`, `--graph`'s DOT, a completion
script) writes that product alone there; a notice or warning it meets
on the way (a cache index from another vx version, a plugin's warning) goes
to stderr, as every refusal does. `vx run`'s stdout is the run's frame,
the tasks' output it carries, except under `--format json`, where that
moves to stderr. `tests/cli-streams.test.ts` holds each
product verb to it under a notice.

## `vx show`

Introspect the workspace's **live resolved configs** — what a run
would see right now. Configs load through the same path a run uses,
plugin `config` and `project` stages included, so a package a plugin
gives tasks to (`turbo()` or `nx()` from `@vzn/vx-migrate`, a
temporary start toward native config) shows them; cached
evaluations are served from the local cache like a run's. `vx show`
never reads `vx-lock.json` (the lock is already the frozen JSON — open
it directly if you want the frozen view).

```
vx show                          # list every project
vx show <project>                # one project's resolved config (`//`: the root project's)
vx show <pkg>#<task>             # a single task (`//#<task>`: the root project's)
vx show <task>                   # that task in every project declaring it
vx show [<task>] --filter <p>    # only the projects `vx run --filter <p>` selects
vx show <task> --affected        # only the projects whose <task> `vx run <task> --affected` runs
vx show --affected               # the run's candidates: the changed projects and their dependents
vx show ... --format json        # machine-readable (default: pretty)
```

`--filter` and `--affected[=<ref>]` narrow the list, or a task's
projects, as `vx run` selects: `turbo ls --affected` is
`vx show --affected`, and `nx show projects --affected --with-target t`
is `vx show t --affected`. Beside a task, `--affected` lists the
projects whose task the run keeps: a change reaches another project
only along a task edge, so a dependent whose `test` has no `^test` is
not listed (X-147). With no task there is no edge to follow, and the
list is the run's candidates, `--filter "...[<base>]"`'s: the changed
projects and their package dependents. Beside one project or
`<pkg>#<task>` they are refused.

Nx's spellings name these: `vx show projects` (when no project or task
has that name) and `vx show project <name>` say `vx show` and
`vx show <name>`.

No target: one line per project — name, root-relative dir, task count,
and a `(no vx config)` marker for config-less packages; one whose
tasks all come from plugins reads `N tasks (no vx config; from
plugins)`, and one a configured project depends on reads `1 task (no
vx config; default build)`: a run loads it for that dependant's
`^build` (X-48). A project's `tags` follow in brackets. With `--format json`
it's an array of `{ name, dir, tags: string[], tasks: string[] }`.

```
$ vx show
app   packages/app   3 tasks  [scope:web]
bare  packages/bare  (no vx config)
```

Under its header `vx show <project>` prints its `tags`.
`vx show <project>` prints a block per task with every field the run
reads: description, command (`(group)` for group tasks), `dependsOn`,
`timeout`, `retries`, `env.passThrough` / `env.define` / `env.secret`,
`remote`, `sandbox`, `persistent`, `interactive` (`yes` / `no`), and the
cache block
(`inputs.files` / `.workspaceFiles` / `.env` / `.tasks` / `.runtime` /
`.workspaceRuntime`, `outputs.files` / `.workspaceFiles`). Fields the
task does not set are not printed; a value that spans lines (a
multi-line command) continues under its first line. `--format json` emits `{ name, dir,
config }` with the config exactly as resolved. `vx show &lt;pkg&gt;#&lt;task&gt;`
narrows to one task (`{ name, dir, task, config }` in JSON). A bare
name that is no project is a task: `vx show build` prints the block
from every project declaring `build` (an array of the one-task shape
in JSON). The default `build` is declared by none: it counts in the
list and `vx show <project>`, but `vx show build`, like
`vx run build --all`, does not name it (X-145).

```
$ vx show app#build
app — packages/app

build
  description:   compile the app
  command:       tsc -b
  dependsOn:     ^build
  inputs.files:  src/**
  inputs.env:    NODE_ENV
  outputs.files: dist/**
```

Unknown project / task names exit `1` with the same near-miss hint
every verb gives (two edits, or a partial name); a bare name that is
neither reads `unknown project or task: "buidl" — did you mean build?`,
and a `pkg#task` hints whole specs (`unknown task: "app#bui" — did you
mean app#build?`). With nothing near, it lists what exists instead: `unknown
project: "zzz"; projects: app, lib`, `; its tasks: app#build, app#test`,
or `; projects and tasks: …` (M-57).

An empty target (`vx show ''`) is refused: omit it to list every project.

Exit codes: `0` success; `1` parse error or unknown target.

Two runs on one workspace take turns: the second waits for the first's
run lock and, after a second, says `[vx] waiting for another vx run
(pid N) on this workspace to finish…` (see caching.md § Concurrent
runs). The lock lives in this user's own directory in the temp
directory, so two runs take turns only when they are one user's and
share `TMPDIR`: a `nix develop` shell sets its own.

Every verb: a path vx must write that this user cannot (`EACCES`,
`EPERM`, `EROFS` — a read-only checkout, another user's files) or that
the disk has no room for (`ENOSPC`, `EDQUOT`) exits 1 with one line
naming the path, `vx: EACCES: permission denied, open '…/vx-lock.json'
— a path vx must write is not writable by this user` (or `— the disk
that path is on is full`), never a stack. Inside a run the task's line
says the same. A process out of file descriptors (`EMFILE`, `ENFILE`;
macOS starts a shell at 256) exits 1 with the error and `— the process
is out of file descriptors; raise the limit (ulimit -n 4096) and re-run`.

## `vx info`

Workspace doctor — one screen of facts for bug reports and sanity
checks. The task count and the sandbox row's declared count come from
the same load a run uses, plugin stages included; a config that fails
to load counts as zero in both rather than failing the doctor, every
other project still counts as a run loads it, and the broken one is
named (`12 (34 tasks · 1 config did not load)`, then a `config errors`
row per config with the message `vx run` stops on):

```
$ vx info
vx:               0.0.0
bun:              1.4.2
git:              2.53.0
git status cache: core.fsmonitor, core.untrackedCache off
workspace root:   /work/repo
projects:         12 (34 tasks)
plugins:          2 — @vzn/vx-reapi (executor, cache); @vzn/vx-otel (telemetry)
workers:          2 — cgroup CPU quota 2 of 8 cores
memory:           13 GB usable — cgroup limit; the machine has 16 GB
cache dir:        /work/repo/.vx/cache
cache store:      /home/me/.vx/3f2a9c1e7b4d5a60/cache
cache versions:   keys vx-cache-v42 · index schema v34
cache entries:    42 (1.3 GB)
orphans:          3 artifacts (12 MB) the index does not know — `vx cache prune` reaps them
task runs (24h):  7 (5 cache hits)
flaky tasks:      1 — web#test (3 of 11 runs failed on unchanged inputs)
sandbox:          available (9 tasks declare exec.sandbox)
vx-lock.json:     yes
```

- `git` shows `(not found)` when the binary is missing; a broken
  project config contributes zero tasks instead of failing the
  printout, and the `config errors` row (present only then) names it
  with the loader's message — the same line `vx run` would stop on.
- `git status cache`: vx runs ONE `git status` per run to find dirty
  and untracked files, and on a large tree that walk is the warm run's
  critical path. git's `core.fsmonitor` (a daemon that watches the
  worktree) and `core.untrackedCache` make it near-free after the first
  run; both are off by default, so `vx info` says when they are.
- `sandbox` is the runtime probe's verdict for THIS host — one sandboxed
  `true`, memoized — and how many loaded tasks declare `exec.sandbox`. A
  declared sandbox whose runtime cannot start fails the task at run
  time rather than downgrading, so `unavailable — &lt;why&gt;; 3 tasks declare
exec.sandbox and will fail` says it first: root inside a container
  (the runtime's seccomp helper cannot create its nested user namespace;
  run as a non-root user or set `sandbox.weakerWhenNested: true`), a
  missing bubblewrap, socat or ripgrep, a nested seatbelt on macOS.
  On Linux an available sandbox that cannot report the reads it denies
  (no `strace` on PATH, one whose `--version` fails, or one that may not
  attach) adds `, untraced — &lt;why&gt;, so the reads it denies go
unreported`: the sandbox still enforces, but a task that tolerates a
  denied read passes and caches with no word of it. The `--format json` fact is
  `sandbox.untraced`, the reason or `null`.
- `plugins` names every plugin `vx.workspace.*` declares and the seams
  each fills, in pipeline order (`config`, `discover`, `project`, `graph`, `key`,
  `fingerprint`, `schedule`, `admit`, `executor`, `cache`, `telemetry`,
  `setup`, `commands`), or `none`. It reads the declarations: a plugin
  that declines a task at run time still lists its seam here.
- `workers` is the count a run defaults to and where it comes from:
  `vx.workspace.ts`'s `concurrency` when set, else the cores this
  process may use — the CPU count, capped by the cgroup CPU quota a
  container runs under (`8 — the CPU count`, `2 — cgroup CPU quota 2 of
8 cores`). `memory` is what a memory-packing policy budgets
  (`@vzn/vx-schedule-history`): the machine's total, capped by the
  cgroup limit — inside a container the raw numbers are the host's,
  and the doctor is where to see which one a run reads.
- `flaky tasks` is the standing list a run's flaky notes add to:
  every task whose history (30 days, what the cache keeps) holds a
  cache key that failed after it had passed, most failures first, with
  the outcomes over those keys. A cache hit counts as a pass (it
  replayed one), and a pass that took a retry counts too, its failed
  attempts counted as failures. A task with no cache block keys on its
  config alone, so its key says nothing about its inputs: it is never
  listed. A pass or a failure behind a failed dependency, in a run that
  continues past failures, is not its key's and counts on no key. `none` when
  no key did.
- `task runs (24h)` counts task runs, executed and replayed alike, so
  the hits are a share of it: three `vx run` of two tasks are six. An
  invocation is what `vx last` calls a run; `vx last --list` counts
  those.
- `cache store` is where the entries and their artifacts live: the
  store every workspace of this user shares (`docs/caching.md`), or
  `none: the cache dir holds the entries` when the workspace names its
  cache dir. Before a first run it is the store a run would open.
- `cache entries` counts the entries and their size; with a
  `cacheRetention.maxSize` it reads against it (`812 (3.0 GB of 10 GB,
30%)`), and a `cache retention` row says what each run's end evicts.
  Paths under the home directory print as `~/…`; the JSON keeps them
  absolute.
- `cache versions` are the two constants a bug report needs and the
  reset notice names: the key prefix (`CACHE_VERSION`; a bump orphans
  every entry) and the index schema (`SCHEMA_VERSION`; a mismatch drops
  every table on the next open, which the run then says once).
- `orphans` appears only when the cache directory holds artifacts or
  save temps the index has no row for, older than an hour (what a
  `SCHEMA_VERSION` reset leaves behind; a fresh one is a save in
  flight). A task that asks for one's key again indexes it and hits;
  the rest only `vx cache prune` reclaims, so the doctor says so.
- `--format json` prints the same facts as one typed object, for a
  script or a bug-report template: `vx`, `bun`, `bunSupported` (false
  below Bun 1.4.0), `git` (null when not
  found), `gitStatusCache` (`{ fsmonitor, untrackedCache }`, null when
  git could not answer), `workspaceRoot`, `projects`, `tasks`,
  `configErrors` (`[{ path, message }]`, the configs that did not load,
  empty when all did), `plugins` (`[{ name, seams }]`), `workers` (`{ count, source, cores,
cpuQuota }`, the source one of `workspace` / `cgroup` / `cores`,
  `cpuQuota` in cores or null), `memory` (`{ usableBytes, totalBytes,
cgroupLimitBytes }`, the limit null when none binds), `cacheDir`, `cacheStore`
  (null when the cache dir holds the entries), `cacheVersion`,
  `schemaVersion`, `cacheEntries`, `cacheBytes`, `cacheRetention`
  (`{ olderThan, maxSize, maxBytes }`, each only when set, null when none is declared),
  `orphans` (`{ artifacts, bytes }`, always present), `runs24h`, `hits24h` (task
  runs, as the row), `restored24h` (of those hits, the ones that restored
  outputs; the rest found them up to date), `flakyTasks` (`[{ taskId, project, task, keys, passes, failures }]`,
  empty when none), `lockfile`, `sandbox` (`{ available, reason,
declared, untraced }`, `declared` the count of tasks with `exec.sandbox`,
  `untraced` the reason denied reads go unreported or null). The
  pretty rows render this object;
  there is no second source.
- `--cache-dir <path>` reads the cache a run with the same flag uses, as
  `vx why`, `vx last` and `vx cache prune` do.

Exit codes: `0` the facts printed, a config that did not load included;
`1` no workspace here or above, or a parse error.

## `vx why`

Answer "why did this task re-run?" from the terminal, from the
per-component input fingerprints core persists on every miss. Read-only over the local
`cache.db`: no config evaluation, no re-hash.

```
vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]
```

By default it compares the task's **latest** recorded run against its
immediately-previous run; `--run RUNID` pins a specific run (a unique
prefix of the id is enough; a task that run did not run is refused,
pointing at `vx last --list`, and so is an id no run carries). History is
the cache directory's, not the checkout's: worktrees that share one
`--cache-dir` share one history, so the previous run may be another
worktree's (its branch is in `vx last`), and its edits read as changes. Latest and
previous are the order runs were recorded, not their clock: a clock that
stepped back once swapped the two and diffed the edit backwards. A bare task
name resolves when exactly one project ran it (several → the project
the current directory is in, as `vx run` picks, else an error listing
the candidates; unknown → include-match suggestions, or, with
none near, a pointer to `vx last --list`, or word that nothing has run
yet; after runs of only groups, which record no task row, that no run
executed a task and to ask about one the group depends on, X-50).

A control character in a component's name (a file named with an
escape or a carriage return) prints as `\xNN`, so no file name drives
the terminal; `--format json` carries the name as it is.

An **unchanged** key has three endings, and the verdict distinguishes
them rather than calling all three a re-run: the run was served from
cache (nothing re-ran), it re-executed on the same key, or it recorded
no cache outcome at all, in which case vx says so instead of guessing.
A re-execution names its cause when the index shows one: the previous
run on the key failed and saved nothing, the run did not read the cache
(`--force`, or a `--cache` without read), no entry for the key was
there when it ran (pruned or evicted), the previous run was not saved
because it ran beside a failed task (a task run past a failed dependency
under `--continue` is never cached; said ahead of a prune, and as
"neither run saved it" when this run ran beside one too), or the previous run executed and no entry
holds the key (its save failed, or a prune took it; a previous run whose
policy wrote no cache says that instead). Otherwise, with this run's
policy recorded as reading the cache, it says it cannot name the cause;
only a run with no recorded policy names `--no-cache` / `--force`.

```
$ vx why app#build
app#build — run 01a1193a-7b39-75a9-870b-5c03e26d7104
  this run   2026-10-08T01:57:05.486Z · success · executed · key 9ef9806a9c69209e
  previous   2026-10-08T01:57:05.325Z · success · key e240348b20e79fd6
  verdict    cache key changed: file packages/app/src/input.txt

  what changed (1 component, 6 unchanged):
    changed file  packages/app/src/input.txt  78981922613b2afb6025042ff6bd878ac1994e85 → 61780798228d17af2d34fce4cfbdf35556832472

  what to do:
    file  an edit re-runs by design; a file the task does not read belongs out of cache.inputs.files
```

A changed key's verdict names what moved, kind and name, three at most
and then a count (`cache key changed: env MODE`), so a key that moved
only by an environment variable says so in one line; when neither
entry kept its components it reads `(inputs differ)`.

Under the rows, `what to do` gives one line per changed kind: what
moves it and how to stop a move the task does not need. An upstream
row is only the carrier, so `vx why` follows each dependency that moved
in the same run down to the tasks whose OWN inputs moved and prints
them under `root cause`, one chain per root (five at most, then a
count), and `what to do` speaks to those kinds instead:

```
  root cause:
    app#build ← lib#build ← file packages/lib/src/index.ts
```

A dependency the walk cannot find in the run keeps the `upstream` line,
which names the `vx why` to run next; a `config` line names the
`vx show` that prints the task's config now. `--format json` carries
the walk as `roots` (`chain`, `entries`).

A hit's line is `cache-hit · key …` (or `cache-hit-remote`): the status
names the hit and its tier, so only an executed run carries the word.
A skipped task never ran and derived no key: its line is `skipped · no key`.
A row's kind is what the key folded: `file` (an input file, by blob
id), `env` (a declared variable, by digest), `runtime` and
`ws-runtime` (a declared command's output, `inputs.runtime` and
`inputs.workspaceRuntime`), `forward` (the argv forwarded after `--`),
`package` (the project's own `package.json`), `workspace` (the
fingerprint: the lockfile and the other root manifests), `config` (the
evaluated task config), `upstream` (a dependency's input key — a
lockfile change moves it too, so that row rides with the
fingerprint's), `plugin` (a `key` plugin's material, by name) and
`format` (the key format vx itself folds: it moves only with an
upgrade, and re-keys every task once, X-142).
The component-level rows come from the `entry_inputs` input
fingerprints persisted with each cache entry; when either side's entry
is gone (pruned, or the run failed and never saved one) the verb still
names the hash change and says the component diff is unavailable. When
only the previous run failed, the diff is taken against the last run
that saved an entry instead, and the detail line names that run. A
task with no `cache` block derives a key too — it is what dependents
fold — but saves no entry, so for it the verb can only report the key
change and says so.
`--format json` emits one machine-readable object (`{ taskId, runId,
why, diff, roots }`); when the task's recorded runs predate run ids, `{ taskId,
why, diff, explanation }`, `why` and `diff` null and `explanation` the
latest cache entry's key.

Exit codes: `0` the task's run explained; `1` no recorded run of the
task, a `--run` with no row for it, or a parse error.

## `vx prune`

```
vx prune <project...> [--out-dir <dir>] [--docker] [--production]
```

A plugin verb of `@vzn/vx-lockfile`: declaring `pnpm()`, `bun()`,
`npm()` or `yarn()` adds it. It copies the named projects, their
transitive workspace dependencies, the root manifests (workspace lists
rewritten to the subset), the vx configs and each lockfile pruned to what
the subset installs into `--out-dir` (default `out/`), so a Docker build
installs it with a frozen lockfile; `--docker` splits `json/` (the
install layer) from `full/`; `--production` leaves out a workspace
package only a dev dependency reaches and strikes it from the kept
manifests and lockfiles. `turbo prune`. Reference:
`packages/vx-lockfile/README.md` § `vx prune`. Without the plugin, typing
`vx prune` says where it comes from and exits 1. History: core verb
2026-08-25, `@vzn/vx-prune` 2026-09-10, removed 2026-09-11 (it copied the
lockfile unpruned), back in `@vzn/vx-lockfile` 2026-10-03.

## `vx stats`

Removed (H-19). It was an alias of `vx info`, which absorbed it, and
warned on every use. Typing `vx stats` points at `vx info` and exits 1 —
unless a declared plugin claims the verb through the `commands` seam.

## `vx last`

Replay a recorded run's summary from the local history — no
re-execution, no cache probe, no config evaluation. With the
self-hosted dashboard gone (2026-08-23), this is THE run-replay
surface. A run a Ctrl-C (or SIGTERM, SIGHUP) stopped records nothing,
so `vx last` still shows the run before it.

```
vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]
```

Bare `vx last` replays the most recent run: a header (verdict, command,
when, duration, branch @ sha, CI, task/hit/failure counts) and a
per-task table — status, id, duration, cache key, and for a task that
executed, what it used (peak RSS and CPU parallelism, `312 MB · 1.4×
cpu`: the runner's own record, and the number `@vzn/vx-schedule-history`
reserves from; a hit spent nothing and shows nothing, and a task lighter
than vx itself shows its CPU only) — failures first, each as the frame
read it, `failed (exit 137)`, with the signal an exit above 128 stands
for at the row's end (`128 + SIGKILL`; the shell's convention, so a
command that exits 137 on its own reads the same). Where the run's
footer gave a reason, the row ends with it instead: `timed out`,
`never ready: exited`, `2 sandbox violations`, and for a skipped task
`after lib#build failed` (the v27 columns; rows older than them read
as before). Rows run failures first, then what executed or was
skipped, then hits; past sixteen hits the rest fold into one line with
their count (`… +980 more cache hits`) — a thousand-task warm run is a
thousand rows otherwise, with the one failure a screen above the
prompt — and the sixteen shown are the slowest restores, the one thing
a hit's row tells. `--format json` lists every row.
`vx last --list` prints the N most recent runs (default 10), one per
line in aligned columns (verdict, start, run id, counts, duration,
command), each run id cut to the shortest prefix no other run shares, 13 characters at least (`--list 5`
and `--list=5` alike; the space form takes the next argument as the
count unless it is a flag or a run id, eight hex digits at least, so
`--list 1.5` is refused as a count); `vx last RUNID` replays a
specific one, and the two do not combine (a word beside `--list` no run
id could be is refused as an unexpected argument). `--failed` replays the latest
run that failed, past any green one since, and with `--list` lists only
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
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
recorded the task, or in RUNID's. A failed task's is the kept failure
output; any other task's is its cache entry's log (the one a hit
replays, masked as it was), so a passing task's log reads too, on a hit
or in the run that saved it. An uncached task that passed, or a skip,
kept none: stdout is empty and stderr says so, exit 0. With
`--format json` it is `{ runId, taskId, status, source, output }`,
`source` `'failure'`, `'cache'` or `null`. A task no run recorded is
refused, exit 1; `--log` does not combine with `--list` or `--failed`. `--list --format json`
an array of the same `invocation` objects, newest first. An unknown run id fails
loud and points at `--list`. Before any run, every form says so
(`vx last: no recorded runs yet — run something first`, exit 1; `--list`
prints `no recorded runs`, exit 0), and past green runs only,
`--list --failed` prints `no recorded run failed`. A run id may be typed as a unique prefix; a
prefix several runs share fails and lists them. A replayed run with
failures ends with the command that re-runs them (`re-run what failed:
vx run app#test -- …`, with the arguments the run forwarded to the
tasks that got them; a failed dependency, which never got them, gets a
line of its own without them, X-140). The
replayed `$ vx run …` or `$ vx watch …` line and that one keep each
argument shell-quoted (`-- 'a b'`), so either pastes back as it ran (X-49).

`vx why`, `vx last`, `vx info` and `vx cache prune` all read the cache
a run wrote, so each takes `--cache-dir <path>` with `vx run`'s rules
(cwd-relative, absolute used as-is): a run that wrote its history
elsewhere is replayed, explained, reported on and pruned there. Without
the flag they open the workspace's cache (`defineWorkspace({ cacheDir })`
or `.vx/cache`). A `--cache-dir` that is not there is refused by name
(`--cache-dir .vx/cahce: no such directory`). In a workspace that never
ran, `vx why`, `vx last`, `vx info`, `vx show` and `vx cache prune`
(dry or not) read it as empty and create nothing (item 900, E-7, E-38).

Exit codes: `0` the run (or the list) printed, `--list` with no runs
included; `1` no recorded run yet, a run id it has no record of, or a
parse error.

## `vx docs`

`vx docs <query>` searches vx's reference with no network: `cli`,
`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; 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`).
The guides live on the site: `https://vznjs.github.io/vx/llms.txt`
indexes them.

Exit codes: `0` the search ran, a search with no match included (it
names the pages searched); `1` a missing query or a bad flag
(`VX_E_USAGE`).

## `vx completions`

Print a completion script for `bash`, `zsh` or `fish`:

```
eval "$(vx completions bash)"                          # this shell
vx completions zsh > ~/.zfunc/_vx                      # zsh, with ~/.zfunc on $fpath
vx completions fish > ~/.config/fish/completions/vx.fish
```

The script completes the verbs — core's, and the plugin verbs the
workspace around the cwd declares at generation time — and every flag
of each verb, read from the same help text `vx <verb> --help` prints:
the verb's own Usage line, and for `run` and `watch` the run option
lines, less the ones `watch` refuses. So a flag cannot be documented
and not completed, nor completed and then refused: a flag another
verb's line names in passing (`vx lock --check` beside `--frozen`) is
not one. After a flag with a fixed value set the script offers that
set: `--format` pretty or json, `--output-logs` full, errors-only,
hash-only or none, `--download` all, toplevel or none — each value one
the flag's parser takes (`tests/completions.test.ts` holds it). A plugin verb completes `--help` only. Task and project
names are not completed (they are the workspace's, and a completion
that evaluates configs on every Tab is the wrong price). The zsh script
works both ways zsh loads one: from `$fpath` it completes on the first
Tab (it rang the bell there until 2026-10-03 and completed on the
second), and sourced it registers itself; `tests/completions-shells.test.ts`
loads the script in zsh both ways and in fish where they are installed. An unknown
shell is an error naming the three, and the nearest of them when one is
within two edits (`got bsh). Did you mean bash?`).

Exit codes: `0` the script printed; `1` an unknown shell or flag.

## Plugin commands

A plugin declared in `vx.workspace.ts` can add verbs:

```ts
import { definePlugin, type VxPlugin } from '@vzn/vx'

export function mcp(): VxPlugin {
  return definePlugin(import.meta, {
    commands: {
      mcp: {
        description: 'serve the run history to an AI agent over stdio',
        async run(argv, ctx) {
          // ctx.workspaceRoot, ctx.cacheDir, ctx.concurrency, ctx.warn(...)
          return 0 // the process exit code
        },
      },
    },
  })
}
```

The plugin's name is its package name, which `definePlugin` reads from
`import.meta`; a plain object is refused when the workspace loads.

(`@vzn/vx-mcp` ships exactly this: declare `mcp()` and `vx mcp` serves
six read-only tools to AI agents — four over the cache database, one
over the resolved task catalog, one the workspace doctor's facts.
`@vzn/vx-schedule-history` adds `vx history`: what it learned per task
and the reservation its `admit` hook packs.) The dispatcher tries core's verbs
first and consults plugins only for a word core does not know, loading
the workspace config from the cwd to find them (outside a workspace the
verb is simply unknown). A plugin verb that names a core verb, or one
plugins of two packages both declare, is refused when the workspace
loads — such a verb could never run, or would hide the other plugin's.
Plugins of one package are one owner (`bun()` and `pnpm()` both carry
`prune`): the first declared runs. A plugin verb's
return value is the exit code, an integer 0–255 (anything else — nothing,
a fraction, 256, which the OS would keep as 0 — fails naming the plugin
and the verb), and a thrown `UserError` prints as
cleanly as core's own. Anything else thrown fails in one line, no stack:
`plugin '<p>' failed in command '<verb>': <msg>`. `vx help` lists every plugin verb under "Plugin
commands", with the plugin's name.

An unknown verb is answered with what this workspace knows: the "did you
mean" set is core's verbs AND the ones its plugins declare (the lookup
that just failed already loaded them, so it costs nothing), and when
nothing is close enough to guess, a second line says where a verb can
come from — the verbs declared here, or that `vx.workspace.ts` is what
would declare one, or that there is no workspace here at all. Core still
names no package: it lists what the workspace itself declares.

## Environment variables vx reads

The variables core reads. Each is read where it applies, per call, so a
value set for one invocation is that invocation's. A plugin's own (the
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`).                             |

Colors are the two conventions in § Output format › Colors (`NO_COLOR`,
`FORCE_COLOR`). A truthy `CI` picks the CI output flow and
`GITHUB_ACTIONS` its `::group::` framing (§ Output); the run's
`invocations` row records the provider, the first truthy of
`GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE`, `CIRCLECI`, then `CI`. Core never reads `GITHUB_STEP_SUMMARY`: `--report`
prints to stdout, and `--report-file=<path>` appends to a file, so on
Actions pass `--report-file="$GITHUB_STEP_SUMMARY"`. A sandboxed
task's temp dir sits under `CLAUDE_CODE_TMPDIR` (else `CLAUDE_TMPDIR`,
else `/tmp/claude`), the sandbox runtime's own convention
(`docs/modules/sandbox-runtime.md`).

## Output format

`vx run` emits framed blocks. Stdout/stderr from each task is
buffered until completion, then dumped inside the block — so
concurrent tasks never interleave their lines. A lone requested task
streams live instead (§ Output).

Frame anatomy:

```
┌─ app#test > failed (exit 1, 1 sandbox violation)

$ bun test

├─ OUTPUT ──────────────────────────────────────────────────

2 pass
error: expected 3, got 2
1 fail

├─ SANDBOX VIOLATIONS (1) ──────────────────────────────────

write ../shared/notes.txt

└─ app#test ── (2.10s) failed (exit 1, 1 sandbox violation)
```

Every section is conditional: the `$ <command>` line only for an
executed task (success or failed — a hit replays its stored output and
shows none), `OUTPUT` only when the task wrote something,
`SANDBOX VIOLATIONS (N)` only when the sandbox recorded some or vx
has a note on a failure. The
header carries the outcome (`restored-local • abc12345`, `failed (exit
N)`, …) and the footer repeats it after the duration. A test renders
this block and checks it against this page, byte for byte.

`OUTPUT` holds what the task wrote in the order vx read it, so an
error stays beside the test that printed it: a stderr line renders
red when colour is on (a line the task coloured itself keeps its own
colours, and a line takes the stream that began it); without colour
the lines are the task's bytes.
The two streams are two pipes, so lines written within the same
instant may read stdout first; a cache hit replays the same order. A
persistent task's tail after ready keeps `STDOUT (since ready)` and
`STDERR (since ready)` apart: its bounded tails hold no order.

Frame corners and rules render dim, section labels (`├─ …`) bold in
their state colour; the id keeps its identity coloring. Content lines are **raw** — no left border, no
indent — so long lines wrap without colliding with frame glyphs and
copy/paste yields the verbatim output. Every block (and every live
frame close in focused flow) is followed by a blank line so frames
never collide with the next one-liner. A persistent task's frame is
marked with a cyan `▸` after `┌─`/`└─`, and its close reads `running`
(the child is still alive), or `failed (exit <n>)` for a server that
died on its own before the run stopped it.

There is **no top-of-run banner** — the run context lives in the
footer. A broad run looks like:

```
 ⇢     4ms success local    @vzn/vx#format-check
 ⏺︎   5.20s success miss     @vzn/vx#test

─ vx 0.0.0 ───────────────────────────────────────────────────
  projects  ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱
            1 in run · 3 total
  tasks     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            2 success · 2 total
  cache     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            1 miss · 1 local

  info      8 workers · local cache
  time      5.34s · max 5.20s · avg 5.20s · min 5.20s
  result    2 tasks · 1 cached (50%) · 900ms saved · 5.34s
```

The three bars are meters: `projects` is what the run covered against
the workspace, `tasks` is failed / success / skipped, `cache` is miss /
no-cache / up-to-date / local / remote (a skipped task rides it too, so
the two legends sum alike). The `time` spread counts executed tasks
only — a hit's restore time never enters it — which is why one executed
task reads as its own max, avg and min. The `result` row is the run in
one line, last: tasks, cached (every hit, local or remote, over every
task with a cache that ran or hit; a skipped task asked no cache) and the wall time — `3 tasks · all cached · 40ms`
when nothing that could hit ran, with `N failed` after the count on a
red run. A task with no `cache` block, or any task of a run whose
`--cache` reads and writes nothing (`--no-cache`), could never hit, so it
is counted apart (`1 task · 1 no-cache · 37ms` for `vx run dev`), as
`--dry` labels it. A test renders this run and
checks it against this page, byte for byte.

Group tasks emit no framed block by design (they aren't real tasks);
running a group focused surfaces its real member tasks instead.

**Nothing below the footer.** The footer is the run's last word.
What a run has to say about one task rides that task's row; what it
says about the run (a server that died, outputs left remote, a file
`--summarize` / `--profile` wrote, a history, upload, plugin or sandbox
warning) prints above the footer: it prints once the run's closing work
is done, the `VX_TIMING=1` table included. Cache housekeeping
(`cacheRetention`) prints nothing. Only a kept server's own output
follows it.

**Skipped rows.** A red run lists every task that never started as a
row naming the failure that blocked it, so the footer's `1 skipped`
always has a name above it:

```
 ⊘         skipped          app#build • blocked by lib#build
 ⊘         skipped          web#build • blocked by lib#build
```

A skip's cause is followed through a chain of skips to the failure at
its root; a skip with no failed upstream is fail-fast's and carries no
suffix. A blocked group (a task with no command) has no row: it never
starts by definition and no counter counts it.

**Aborted and not-run rows.** After a stop (a shutdown signal), the
task list names what it cut short (`aborted`, with its time so far) and
what it reached first (`not run`). Neither reached the cache:

```
 ✗   2.41s aborted          app#dev
 ◌         not run          web#build
 ◌         not run          web#test
```

The tasks legend names them outside the total, which history and
telemetry share: `2 success · 2 total · not counted: 1 aborted, 2 not
run`. A framed task (focused or `full`) that
printed while it stopped shows its frame instead of a row.

**Flaky rows.** A task the run just proved nondeterministic says so
in a dim note on its own row (and its frame's footer) — from the local
run history alone, no service:

```
 ◼︎   4.21s failed  miss     app#test flaky - passed 3× before
 ⏺︎  12.84s success miss     api#e2e flaky - failed 1× before · 2 attempts
```

A task is flaky when its exact cache key FAILED AFTER IT HAD PASSED
(this run counted; a cache hit is a pass, it replayed one), or when it
needed a retry (`exec.retries` / `--retry`) this run. A failure on a
key that never passed is a break and carries no note — a changed input
that fails is what a red run usually means — and the first pass after
only failures is a recovery (a missing tool installed), not a flake.
Only tasks with a `cache` block are judged: "same inputs, red after
green" is a claim
only declared inputs can back, and a task without them keys on its
config alone. It is judged as the task finishes, so the row carries
it: zero cost for a hit or a skip, one probe of the failed-row index
for a green miss; `vx info` keeps the standing list.

### Colors

ANSI truecolor (`ansi-16m`) sequences, gated by env:

| Var                         | Effect                                                   |
| --------------------------- | -------------------------------------------------------- |
| `NO_COLOR=…` (non-empty)    | Force off. Overrides `FORCE_COLOR`.                      |
| `FORCE_COLOR=0` / `=false`  | Force off, on a TTY too.                                 |
| `FORCE_COLOR=…` (any other) | Force on — `1`, `true`, `2`, `3`, the empty string, etc. |
| (neither)                   | On iff `stdout.isTTY`.                                   |

`0` and `false` are `FORCE_COLOR`'s "off" by the convention
supports-color, chalk and Node follow; until 2026-09-24 vx read every
non-empty value as "on", so a CI setting `FORCE_COLOR=0` got escape
sequences in its log (the bug Nx has as nx#35292). An empty `NO_COLOR`
has no effect (no-color.org).

A task's output is a pipe, so a tool would print plain; vx sets
`FORCE_COLOR=1` on every task, as Nx and Turbo do, unless the task
already sees a `FORCE_COLOR` (any value, `0` included) or a non-empty
`NO_COLOR`. The cache stores the coloured bytes, and wherever vx's own
output is plain (a pipe, CI without `FORCE_COLOR`, `NO_COLOR`) it
strips the escapes from task output, live and replayed alike, an
escape cut across two chunks included (`tests/plain-output.test.ts`,
`tests/cli-colors-e2e.test.ts`). A custom `log` passed to `run()` gets
task output as written. A task that writes its own output to a file
and wants it plain sets `env: { define: { FORCE_COLOR: '0' } }`.

Programmatic callers passing a custom `log` to the run options always
see plain text.

Only a run's own output (`vx run`, `vx watch`) is painted, and the
help on a terminal: headings bold, `vx <verb>` and each flag or example
in cyan; `NO_COLOR` or `FORCE_COLOR=0` turns it off
(`tests/help-colors.test.ts`). Every other verb (`show`, `info`, `why`,
`last`, a `--dry` plan, `--graph`, `cache prune`), and the help off a
terminal, prints plain text whatever `FORCE_COLOR` says, so a script
that forces colour for a run's log still parses them
(`tests/cli-colors-e2e.test.ts`).

## Remote cache (plugin-driven)

Core ships **no remote-cache wire client** — the remote cache is a
plugin concern. A `cache` plugin composes core's `LayeredCache` over a
wire client; `@vzn/vx-reapi` provides one for any Bazel REAPI server
(ActionCache + CAS).

Reads try local first, then remote (hydrating local on remote hit),
with a background prefetch pass overlapping remote GETs with
execution. Writes go to local immediately; the remote upload is a
fire-and-forget background task drained at end of run — failures are
logged via `onRemoteError` but never fail the build.

For any OTHER cache server (a Turbo-wire deployment, S3-direct, …),
implement core's `RemoteCacheLayer` interface in a plugin's `cache`
capability — the recipe lives in the plugins guide. Embedders
holding a wire client can inject it per-run via
`RunOptions.remoteCache` (explicit injection wins over the plugin
consult). The retired `VX_REMOTE_CACHE_*` env vars are gone.

## Run analytics

`vx info` surfaces the aggregate cache stats (entry count, total
size, runs + hits in the last 24 h). For anything deeper, vx records
every task to a `runs` table in `cache.db` (UUIDv7 `run_id`, hrtime
wallclock spans, cpu_ms, peak RSS, status, cache_hit flag) plus one
`invocations` header row per run (command, git/CI context, tags,
counts). The SQLite file IS the API:

```sh
sqlite3 .vx/cache/cache.db "
  SELECT project, task, status, duration_ms
  FROM runs
  WHERE run_id = (SELECT run_id FROM runs ORDER BY id DESC LIMIT 1)
  ORDER BY duration_ms DESC;
"
```

The schema is documented in
[`caching.md` § SQLite tables](../caching/#sqlite-tables).

## What's still missing vs Turbo

Tracked in [`comparison.md`](../comparison/). Nothing visible from the
CLI is open: `--output-logs hash-only`, `--continue=<mode>`
and `--cache-dir <path>` all shipped and are documented above.
Remote-cache credentials are not core CLI flags at all: core carries no
HTTP cache client — a remote cache arrives through a plugin's `cache`
capability, which owns its own configuration.

## Programmatic API

```ts
import { run, planRun, defineProject, defineWorkspace } from '@vzn/vx'

const summary = await run({
  cwd: process.cwd(),
  tasks: ['build', 'test'],
  concurrency: 4,
  // Optional 4-axis cache control; omit for everything-on.
  cache: { localRead: true, localWrite: true, remoteRead: true, remoteWrite: true },
})
// summary.ok: boolean; summary.outcomes: TaskOutcome[]

const plan = await planRun({
  cwd: process.cwd(),
  tasks: ['build'],
})
// plan.tasks: PlannedTask[]
```

Surface:

- `run(options)` — execute. Returns `Promise<RunSummary>`.
- `planRun(options)` — predict, no execute. Returns
  `Promise<RunPlan>`. Used by `--dry` / `--graph`.
- `prepareRun(options, log)` — the shared setup (discovery → configs →
  graph → cache). What an embedder builds on.
- `defineProject` / `defineWorkspace` — identity helpers for type
  inference in user configs.
- Every one of the three returns a type the façade exports, so an
  embedder can hold it: `RunOptions` / `RunSummary` / `TaskOutcome`,
  `RunPlan` / `PlannedTask`, `PreparedRun` — alongside the plugin
  (`VxPlugin`, `TaskExecutor`, `CacheLayer`) and telemetry
  (`TelemetrySink`, `RunSummaryRecord`) surfaces. See `src/index.ts`.

A `log: Logger` option lets embedders swap the default framed-block
logger for a custom one (e.g. JSON-line emission). Custom loggers
always see plain text (colors are off when a non-default logger is
provided).

The CLI dispatcher (`run(argv)` in `src/cli/index.ts`) is not part of
the public package exports; `bin.ts` calls it directly.

---

# vx, Turborepo, Nx, Bazel

> The design choices behind each tool, what each buys and what it costs, and when another tool is the better pick.

import ChoiceMap from '../../components/demos/ChoiceMap.astro'
import ChoosingCheckpoint from '../../components/demos/ChoosingCheckpoint.astro'
import ChoosingMatrix from '../../components/demos/ChoosingMatrix.astro'

Four tools run the tasks of a monorepo and cache their results: vx,
[Turborepo](https://turborepo.com/docs), [Nx](https://nx.dev/docs) and
[Bazel](https://bazel.build/). All four build a
[task graph](../glossary/#task-graph), compute a
[cache key](../glossary/#cache-key) per task and share a
[remote cache](../glossary/#remote-cache). A feature table ticks those
boxes for every tool and stops there. It does not say how the key is
computed, what checks it, who hosts the cache, or what each answer costs
you.

This page names the design choices behind the four tools. For each one it
says what each tool chose, what that buys, what it costs, and when another
tool's choice is the better one. After reading it you should be able to
choose a tool for stated reasons, including when that tool is not vx.

vx's maintainers wrote this page. Every claim about another tool links to
that tool's own documentation, checked against its docs source on
2026-09-24. Every claim about vx links to the page or the test that holds
it. When a tool's docs say nothing about something, this page says "its
docs describe no …". That is not the same as "it cannot".

## A choice, not a checkmark

Take the first question every runner answers: which files can change a
task's result? Those files are the task's
[inputs](../glossary/#inputs), and a runner can find them three ways.

- **A default.** Hash every file in the project. Nothing to write, and a
  task reruns whenever anything in its project changes, even a README.
- **Inference.** Read the configuration of the tools a task runs, such as
  `vite.config.ts`, and derive the inputs from it. Little to write, as
  long as the inference is right.
- **Declaration.** You list the inputs. The key covers exactly what you
  wrote, and the lists are yours to keep right.

None of the three is free. A file the key does not cover can make a
[stale hit](../glossary/#cache-hit-miss-and-stale-hit): the cache
replays yesterday's result under a green run. So a second choice sits
beside the first: does anything check that the key covers what the task
reads? A [sandbox](../glossary/#hermeticity-and-sandboxing) does, by
running the task where undeclared files cannot be reached.

The two choices together decide what a cache hit is worth, and how much
work a task takes to set up:

<ChoiceMap />

Turborepo hashes every tracked file in the package by default
([`inputs`](https://turborepo.com/docs/reference/configuration#inputs)),
and its docs describe no file sandbox. Nx starts from every file in the
project and lets plugins infer more
([inputs](https://nx.dev/docs/reference/inputs)), and it sandboxes tasks
on Nx Cloud ([task sandboxing](https://nx.dev/docs/features/ci-features/sandboxing)).
Bazel makes you declare every action's inputs and sandboxes each action
by default ([sandboxing](https://bazel.build/docs/sandboxing)). vx makes
you declare the inputs and sandboxes the tasks that opt in
([Sandboxing tasks](../guides/sandboxing/)).

## The other choices

The same trade shows up everywhere else. The matrix below has twelve
choices in four groups:

- **Correctness.** How a task's inputs are found, and what checks the
  key.
- **Writing it down.** The configuration language, how the runner is
  extended, and which languages it builds.
- **Where the work runs.** The runtime the runner needs, the remote cache
  wire, running tasks on other machines, which ready task starts first,
  and whether a process keeps state between runs.
- **Getting there.** Coming from another tool, and how mature each tool
  and its ecosystem are.

## Filter by what you need

The first table lists needs a team might have and which tools meet
each. With JavaScript on, tick the ones that matter to you: the second
table keeps only the choices that decide them, marks the tools each
favours, and says which need rules out each tool. Without JavaScript,
both tables show everything.

<ChoosingMatrix />

## What vx's choices cost

- **Bun only.** vx runs its configs and plugins on Bun: Bun 1.4 or later
  from source, or the Bun inside its binary. A config or plugin that needs
  an API only Node has does not run, and Windows means WSL
  ([Quickstart](../quickstart/)).
- **Pre-alpha.** `@vzn/vx` and its plugins are on npm only as 0.0.x
  builds. 0.1.0 is not cut and there is no support policy
  ([Roadmap to 1.0](https://github.com/vznjs/vx/blob/main/packages/vx/docs/design/roadmap-1.0.md)).
- **Explicit inputs are work.** Every cached task lists its inputs, and
  keeping the lists right is on you. The sandbox checks reads against its
  own `allow.read`, not the inputs, so it catches what they miss only on
  the tasks that opt in and whose `allow.read` mirrors their inputs
  ([Caching](../guides/configure/#caching)).
- **A small ecosystem.** The plugins that exist are the first-party ones
  ([Writing a vx plugin](../guides/plugins/)).
- **Nothing distributed ships.** The repository holds no workers, no
  service and no dashboard. Remote caching and remote execution are
  plugins that speak other tools' protocols to servers you run or rent
  ([Writing a vx plugin](../guides/plugins/)).
- **No first-party cloud.** Nobody sells a hosted vx
  ([Remote caching](../guides/ci/#remote-cache)).

## When another tool is the better choice

- **Turborepo**, if caching should work before anyone writes an input
  list ([`inputs`](https://turborepo.com/docs/reference/configuration#inputs)),
  if you build on native Windows, or if you need a stable release with a
  support policy today
  ([support policy](https://turborepo.com/docs/support-policy)).
- **Nx**, if you want plugins that already know your tools
  ([Nx plugins](https://nx.dev/docs/concepts/nx-plugins)), JVM or .NET
  projects in the same graph
  ([multi-language support](https://nx.dev/docs/features/multi-language-support)),
  or CI distribution run for you as a service
  ([Nx Agents](https://nx.dev/docs/features/ci-features/distribute-task-execution)).
- **Bazel**, if the repository is heavily polyglot
  ([intro](https://bazel.build/about/intro)), if every action should be
  sandboxed by default
  ([sandboxing](https://bazel.build/docs/sandboxing)), or if you need
  remote execution in production today
  ([remote execution](https://bazel.build/remote/rbe)).

vx is the pick when you want declared inputs and a local sandbox that
checks what a task reads, TypeScript configs, and a core you extend through plugins
instead of forking, on a JavaScript monorepo, and you can run pre-alpha
software on Bun.

## Checkpoint

<ChoosingCheckpoint />

---

# vx vs Nx

> The same 1,090-package graph run by both, what each one asks of you, what Nx keeps for Nx Cloud, and when Nx is the better pick.

Both tools run the tasks of a JavaScript monorepo and cache their results.
This page puts them side by side on one benchmark, feature by feature, and
says when Nx is the better choice. The design choices behind both are on
[vx, Turborepo, Nx, Bazel](../).

## The numbers

<!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->

| 1,090 packages, 3,270 tasks                     | vx             | Nx                        |
| ----------------------------------------------- | -------------- | ------------------------- |
| Cold build: total time                          | **3 min 40 s** | 3 min 49 s (vx 4% faster) |
| Cold build: CPU burned                          | **17 s**       | 52 s (vx 3× faster)       |
| Fully cached run (restored)                     | **650 ms**     | 6.25 s (vx 9.6× faster)   |
| Fully cached run (up-to-date)                   | **393 ms**     | 6.45 s (vx 16× faster)    |
| Secondary: time the runner adds to a cold build | **2 s**        | 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.

Same graph, commands and concurrency, each tool in its own native config: [how it is measured](../../benchmarks/).

<!-- bench:end -->

Every Nx task is an `nx:run-commands` target running the same command vx
runs, with Nx's daemon off as in CI.

## Feature by feature

|                                     | vx                                                                     | Nx                                                      |
| ----------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- |
| Config                              | TypeScript, evaluated into the cache key                               | JSON (`project.json`, `nx.json`), plus inferred targets |
| Daemon                              | None; nothing boots per task                                           | On by default locally                                   |
| Outputs on run and restore          | Wiped first: no stale file survives a hit                              | Additive                                                |
| Task sandbox                        | Free and local, opt-in per task (Linux, macOS)                         | An Nx Cloud feature                                     |
| Remote cache                        | Any wire through a plugin: Bazel REAPI, Turbo's, Nx's self-hosted spec | Nx Cloud or a plugin                                    |
| Flaky task detection                | Local: the same key failed after it passed                             | Nx Cloud                                                |
| Why a task missed                   | `vx why` diffs two keys: the file, env var or upstream that moved      | Shows hashes, not the diff                              |
| Tasks on other machines             | `@vzn/vx-reapi` over Bazel's REAPI, on servers you run or rent         | Nx Agents on Nx Cloud                                   |
| Plugins                             | Every pipeline stage, 14 hooks; core applies none                      | Inferred tasks, graph data, generators, executors       |
| Non-JS projects                     | No                                                                     | Gradle, Maven and .NET                                  |
| One task, many modes (`build:prod`) | No: a TypeScript function per mode, two tasks                          | `configurations` and `-c`                               |
| Terminal output                     | Streamed blocks you can scroll, copy and pipe                          | Terminal UI                                             |
| Windows                             | WSL2                                                                   | Native                                                  |
| Install                             | One binary; no Bun, Node optional                                      | npm and Node                                            |

Every row is held in [vx vs Turborepo vs Nx](../../comparison/), which
links each claim to its source.

## Free on vx, Nx Cloud on Nx

Nx offers these through Nx Cloud. With vx they run on your machine, at no
cost:

- **The sandbox.** Opt a task in, and a workspace file it did not declare
  is out of its reach. A violation fails the task, and a failed task is
  never cached. Nx sandboxes tasks on Nx Cloud
  ([task sandboxing](https://nx.dev/docs/features/ci-features/sandboxing)).
- **Flaky detection.** vx flags a task whose same key failed after it
  passed, from its local run history.
- **Run history.** `vx last` replays any recorded run; `vx info` and
  `vx why` read the same local data.

## A shared cache a pull request cannot poison

A pull request that can write the cache your default branch reads can
plant bytes that main later replays. That attack is CREEP
([CVE-2025-36852](https://nx.dev/blog/cve-2025-36852-critical-cache-poisoning-vulnerability-creep));
Nx's advisory names its bucket-based self-hosted cache packages as
affected.

vx gives each run a cache scope. A pull request reads the trusted keys and
writes only its own, so it never writes what main reads. On GitHub Actions,
`github()` from `@vzn/vx-ci` sets the scope from the ref. The scope is the
client half: the real boundary is a token your cache server limits, so give
pull request jobs one that cannot write the trusted keys
([security model](../../security/#cache-poisoning)).

## Where Nx wins

Pick Nx if one of these decides it for you:

- **Plugins that already know your tools.** Nx infers targets from your
  tool configs ([Nx plugins](https://nx.dev/docs/concepts/nx-plugins)).
  vx asks you to write each task.
- **JVM or .NET in the same graph**
  ([multi-language support](https://nx.dev/docs/features/multi-language-support)).
  vx runs JavaScript workspaces only.
- **CI distribution run for you as a service**
  ([Nx Agents](https://nx.dev/docs/features/ci-features/distribute-task-execution)).
  vx ships the seam and a REAPI plugin; the servers are yours.
- **One task, many modes.** Nx's `configurations` keep `build:prod` as one
  target.
- **A stable release.** vx is pre-alpha: 0.0.x on npm, no support policy
  yet.

## Switch in one command

```sh
vx init
vx run build --all
```

`vx init` reads the resolved Nx graph and writes one `vx.config.ts` per
package, plus the workspace file, through
[`@vzn/vx-migrate`](../../guides/migrate/). Anything Nx can say that vx
cannot becomes a `TODO(vx-migrate)` comment, never a silent wrong value.
Executor targets (`@nx/js:tsc`, `@nx/vite:build`) run as themselves, so Nx
stays installed until you rewrite each one as the command it runs. Keep
your remote cache with `nxCache()`, which speaks Nx's self-hosted
`/v1/cache` spec. The numbers above are native vx config.

## FAQ

**Do my Nx flags still work?**
`vx run` takes each Nx flag as it is, rewrites it to vx's spelling, or
refuses it and names the vx way. None is dropped in silence.
`vx run web:build` is answered with `vx run web#build`.

**Does vx have a daemon?**
No. vx spawns your command and nothing else. Each run does one git walk,
and on a clean tree keys come from git's index.

**What does it cost?**
Nothing. vx is MIT, with no cloud and no account.

**Do I need Bun?**
No. The npm package installs a prebuilt binary for Linux and macOS, x64 and
arm64. Windows: use WSL2.

---

# vx on real repos

> Public monorepos moved to vx and timed against the tool they ship with, with the commit, versions and machine for every number.

The benchmark on [vx vs Nx](../nx/) is a synthetic graph built to be
fair to every tool. This page is the other half: real public repos, moved
to vx with one command and timed against the tool they already use.

## TanStack/query, against Nx

[TanStack/query](https://github.com/TanStack/query) at commit `817bd02`,
the `build` tasks without examples and integrations: 25 tasks for each
tool.

| Case                     | vx         | Nx     | vx is       |
| ------------------------ | ---------- | ------ | ----------- |
| Cold build               | **34.6 s** | 39.4 s | 14% faster  |
| Restore from cache       | **0.39 s** | 1.26 s | 3.2× faster |
| Nothing changed          | **0.22 s** | 1.43 s | 6.5× faster |

"N% faster" means Nx takes N% longer. Restore deletes the build outputs
and keeps the cache; "nothing changed" deletes nothing.

Run 2026-10-09 on linux x64, 4 cores: vx 0.0.633 configured by
`vx init --native`, Nx 23.2.1 with the daemon off and no Nx Cloud, pnpm
12.4.2. 5 workers each, best of three interleaved runs. Every run is in
[the benchmarks](../../benchmarks/#real-repos).

## Try it on yours

```sh
npm install -D @vzn/vx
npx vx init --keep
```

`--keep` writes one file, `vx.workspace.ts`, which reads your
`turbo.json` or Nx graph as it is: nothing in the repo changes. Run
`vx run build --all` next to the tool you use today. To undo, delete
`vx.workspace.ts`. When you want native config, `vx init --native`
writes a `vx.config.ts` per package; [Migrate](../../guides/migrate/)
walks through it.

More repos join this page as they are measured, each with its commit,
versions and machine.

---

# Config support for Turbo and Nx

> Every key turbo.json, nx.json and project.json accept, read from the upstream schemas (@turbo/types 2.11.5, nx 23.2.1), and what @vzn/vx-migrate's turbo()…

<!-- Generated by tests/turbo-nx-support.test.ts from tests/contract/turbo-nx-support.json; edit the table, not this page. -->

Every key `turbo.json`, `nx.json` and `project.json` accept, read from the upstream schemas (`@turbo/types` 2.11.5, `nx` 23.2.1), and what `@vzn/vx-migrate`'s `turbo()` or `nx()`, a temporary start before native config, does with it. A key a new upstream release adds fails vx's tests until it has a row here.

- **supported**: vx honours it with the same meaning.
- **mapped, with a note**: vx honours it through a translation; the note says how it differs.
- **not supported**: vx ignores or refuses it; the note says which.
- **not applicable**: it configures something outside a task runner and its cache.

## `turbo.json`

| Key | vx | Note |
| --- | --- | --- |
| `$schema` | not applicable | Editor schema hint only; the mapper never reads it. |
| `agentGuidance` | not applicable | Guidance for AI agents, not task or cache config; vx ignores it. |
| `boundaries` | not applicable | Turbo's import-rule checker; vx has no module-boundary rules and ignores it. |
| `cacheDir` | not supported | Ignored without a warning; vx uses its own `cacheDir` in `vx.workspace.ts`. |
| `cacheMaxAge` | mapped, with a note | turbo() fills `cacheRetention.olderThan` when `vx.workspace.ts` sets no retention; weeks become days, `"0"` is off; `TURBO_CACHE_MAX_AGE` wins over it. |
| `cacheMaxSize` | mapped, with a note | turbo() fills `cacheRetention.maxSize` when `vx.workspace.ts` sets no retention; `"0"` is off; `TURBO_CACHE_MAX_SIZE` wins over it. |
| `concurrency` | mapped, with a note | turbo() fills the workspace's `concurrency` when `vx.workspace.ts` sets none (`"50%"` of the cores too); `TURBO_CONCURRENCY` wins over it, as in Turbo. |
| `daemon` | not applicable | vx has no daemon by design. |
| `dangerouslyDisablePackageManagerCheck` | not applicable | Turbo's package-manager check; vx has none. |
| `envMode` | mapped, with a note | Strict is vx's behaviour; `loose` gets a note, since vx passes only declared variables, and so do the tasks a Turbo 1 `pipeline` config's inferred mode ran loose (no pass-through list); under `turbo()` `TURBO_ENV_MODE` wins over it. |
| `extends` | supported | Package configs' `extends` chains are followed as Turbo does; cycles and missing parents are refused. |
| `futureFlags` | mapped, with a note | The flags are not read; what they gate (`global`, structured inputs) is detected by shape. |
| `global` | mapped, with a note | `inputs`, `env` and `passThroughEnv` are read as the `global*` fields they replace; `envMode: loose` gets a note. |
| `globalDependencies` | mapped, with a note | Becomes `cache.inputs.workspaceFiles`; `$NAME` entries become env inputs. Under `turbo()` every package's `microfrontends.json` (or `.jsonc`, or the name `VC_MICROFRONTENDS_CONFIG_FILE_NAME` gives) joins them, as in Turbo, unless it is a child's `partOf`, and so do the files of every package the root depends on, transitively, as in Turbo 2's global hash (Turbo 1, a `pipeline` turbo.json, leaves them out, and so does the mapping). A path git ignores (`config.local.json`) is keyed by a `cache.inputs.workspaceRuntime` probe of its name and bytes, as Turbo hashes it; a glob reaches only files git reports. |
| `globalEnv` | mapped, with a note | Added to every task's `cache.inputs.env` and passthrough; under `turbo()` a `*` name expands over the run's environment, as Turbo does; otherwise a wildcard is dropped with a note. |
| `globalPassThroughEnv` | mapped, with a note | Added to every task's `exec.env.passThrough`, not hashed; under `turbo()` a `*` name expands over the run's environment; otherwise a wildcard is dropped with a note. |
| `noUpdateNotifier` | not applicable | Turbo CLI update notice. |
| `remoteCache` | mapped, with a note | `turboCache()` reads `apiUrl`, `teamId`, `teamSlug`, `enabled`, `signature`, `preflight`, `timeout` and `uploadTimeout`, below env vars and options. |
| `tags` | not applicable | Package tags feed only Turbo boundaries; never read. |
| `tasks` | supported | Each task (or Turbo 1 `pipeline`) becomes a vx task for the packages that declare the script, and a key-only one where a `^` edge reaches a package without it (`dependsOn`, below); a task no package has a script for is a group task in each package that defines it, as Turbo runs a no-op node there and exits 0. A script that names `$npm_package_name`, `$npm_package_version` or `$npm_lifecycle_event` gets it defined, as the package manager Turbo runs it through sets it. |
| `ui` | not applicable | Terminal UI choice. |
| `tasks.*.cache` | supported | `cache: false` means no cache block: the task always runs. |
| `tasks.*.dependsOn` | mapped, with a note | Same syntax; edges to tasks nobody runs are dropped; `$TURBO_ROOT$` deps get a TODO; `$NAME` becomes env. A package without the script of a `^` task others run keys it as Turbo's no-op node does: a cached `true` task with no outputs, its own edges kept. A task name no package has a script for (`ci: { dependsOn: ["lint", "build"] }`) is a group wherever it has an edge, so `vx run ci` runs them as `turbo run ci` does. |
| `tasks.*.description` | supported | Copied to the task's `description`. |
| `tasks.*.env` | mapped, with a note | Goes to `cache.inputs.env` and `exec.env.passThrough`; under `turbo()` a `*` name expands over the run's environment, as Turbo does; the CLI lists the names the package's files spell, and a wildcard nothing spells gets a TODO. |
| `tasks.*.inputs` | mapped, with a note | Globs translated; `$TURBO_DEFAULT$` becomes `**/*`, `$TURBO_ROOT$` workspace files; unsafe globs get a TODO; a path git ignores is keyed by a `cache.inputs.workspaceRuntime` probe, as for `globalDependencies`; a glob that reaches a workspace package nested in the task's package is also listed in `cache.inputs.workspaceFiles`, since Turbo hashes the nested package's files with its parent's. |
| `tasks.*.interactive` | mapped, with a note | `true` becomes `exec.interactive: true`, uncached (Turbo requires `cache: false` of it): the task holds the terminal when vx's stdin is one. |
| `tasks.*.interruptible` | not applicable | Maps to nothing, silently: `vx watch` stops and re-spawns every persistent task each cycle. |
| `tasks.*.outputLogs` | mapped, with a note | `new-only` is vx's default; other values get a TODO pointing at `--output-logs`. Turbo 1's `outputMode` is read as it. |
| `tasks.*.outputs` | mapped, with a note | Become `cache.outputs`, negations kept; vx cleans outputs, so a wildcard first segment leaves the task uncached with a TODO (save one of a kind the package tracks none of: `*.xml`, `**/dist/**`, `dist-*/**`, and a literal rest such as `*/package.json`, whose committed matches, up to 16, are taken back with `!`) and a file git tracks under an output, committed or only `git add`ed, is taken back with `!`. |
| `tasks.*.passThroughEnv` | mapped, with a note | Goes to `exec.env.passThrough`, not hashed; under `turbo()` a `*` name expands over the run's environment; the CLI lists the names the package's files spell, and a wildcard nothing spells gets a TODO. |
| `tasks.*.persistent` | mapped, with a note | An uncached `exec.persistent` task, with a `readyWhen` TODO when something depends on it. |
| `tasks.*.with` | mapped, with a note | An edge to each persistent sidecar, which vx starts beside the task (ready on spawn); a sidecar that ends is a todo, and a pair naming each other keeps one edge. A task with no script is a group that starts its persistent sidecars. |
| `tasks.*.inputs[].from` | not supported | Ignored; vx folds each dependency's cache key instead of its outputs. |
| `tasks.*.inputs[].globs` | mapped, with a note | For `startup` and `jit` entries, keyed like plain input strings. |
| `tasks.*.inputs[].mode` | mapped, with a note | `startup` and `jit` are keyed alike (no separate pass); `dependencyOutputs` adds nothing. |
| `tasks.*.inputs[].withDefaults` | mapped, with a note | `true` adds `$TURBO_DEFAULT$`: every package file. |
| `remoteCache.apiUrl` | supported | The cache URL when neither the option nor `TURBO_API` is set, as in Turbo. |
| `remoteCache.enabled` | mapped, with a note | `false` turns `turboCache()` off unless its options name a cache. |
| `remoteCache.loginUrl` | not applicable | Used only by `turbo login`; vx has no login. |
| `remoteCache.preflight` | supported | `true` sends Turbo's `OPTIONS` preflight and follows its `Location`, below `TURBO_PREFLIGHT` (1 or 0) and `turboCache({ preflight })`. |
| `remoteCache.signature` | supported | `true` signs and verifies with `TURBO_REMOTE_CACHE_SIGNATURE_KEY`, as in Turbo, and `TURBO_SIGNATURE` (1 or 0) overrides it; with signing off the env key is not read. `turboCache({ signatureKey })` signs either way. |
| `remoteCache.teamId` | supported | Used when neither the option nor `TURBO_TEAMID` is set. |
| `remoteCache.teamSlug` | supported | Used when neither the option nor `TURBO_TEAM` is set. |
| `remoteCache.timeout` | supported | Whole seconds, below `TURBO_REMOTE_CACHE_TIMEOUT` and `turboCache({ timeoutMs })`; 0 is no deadline, as in Turbo. |
| `remoteCache.uploadTimeout` | supported | Whole seconds, below `TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT` and `turboCache({ uploadTimeoutMs })`; 0 is no deadline. |
| `futureFlags.affectedUsingTaskInputs` | not supported | Ignored; `--affected` selects projects from vx's own git diff. |
| `futureFlags.errorsOnlyShowHash` | not supported | Ignored. |
| `futureFlags.experimentalCargoWorkspaces` | not supported | Ignored; vx discovers projects from `package.json` workspaces only. |
| `futureFlags.experimentalGoWorkspaces` | not supported | Ignored; vx discovers projects from `package.json` workspaces only. |
| `futureFlags.experimentalObservability` | not applicable | Turbo telemetry export; vx's is a telemetry plugin. |
| `futureFlags.experimentalPythonWorkspaces` | not supported | Ignored; vx discovers projects from `package.json` workspaces only. |
| `futureFlags.filterUsingTasks` | not supported | Ignored; `--filter` keeps vx's semantics. |
| `futureFlags.githubActionsRemoteBaseRefFallback` | supported | `turbo()` follows it on GitHub Actions: a pull request's base ref the checkout lacks is compared as `origin/<ref>`, as in Turbo. |
| `futureFlags.globalConfiguration` | supported | The `global` block is read whenever present, flag or not. |
| `futureFlags.longerSignatureKey` | mapped, with a note | Not read; `turboCache()` always requires a signature key of at least 32 bytes. |
| `futureFlags.pruneIncludesGlobalFiles` | not applicable | Affects only `turbo prune`; vx has none. |
| `futureFlags.strictTaskEntrypointSelection` | not supported | Ignored. |
| `futureFlags.watchUsingTaskInputs` | not supported | Ignored; `vx watch` re-runs on any change in a watched project but a declared output, and the cache keys decide what executes. |
| `boundaries.dependencies` | not applicable | A Turbo boundaries import rule. |
| `boundaries.dependents` | not applicable | A Turbo boundaries import rule. |
| `boundaries.implicitDependencies` | not applicable | A Turbo boundaries import rule. |
| `boundaries.tags` | not applicable | A Turbo boundaries tag rule. |

## `nx.json`

| Key | vx | Note |
| --- | --- | --- |
| `implicitDependencies` | not supported | The top-level map is not read. |
| `affected` | mapped, with a note | Its `defaultBase` (before Nx 20) is `affectedBase` when the top-level key is absent; nothing else in it is read. |
| `extends` | supported | The chain is followed and merged as Nx does, before named inputs are read. |
| `defaultBase` | mapped, with a note | `nx()` sets `affectedBase`, the base a bare `--affected` compares with; `NX_BASE` wins over it, as in Nx. |
| `tasksRunnerOptions` | mapped, with a note | Only `default.options.cacheableOperations` is read, as the legacy cached-targets list. |
| `namedInputs` | mapped, with a note | Expanded per project (project entries win) into each task's `cache.inputs`; vx has no named inputs. |
| `targetDefaults` | mapped, with a note | Applied by Nx while it builds the graph vx reads; vx sees the merged targets. |
| `workspaceLayout` | not applicable | Where generators create projects; vx has no generators. |
| `cli` | not applicable | Nx CLI and generator defaults. |
| `generators` | not applicable | Generator defaults; vx has no generators. |
| `plugins` | mapped, with a note | Targets Nx plugins infer arrive in the graph; `bunx @vzn/vx-migrate` freezes them as written. |
| `tui` | not applicable | Nx terminal UI. |
| `defaultProject` | not supported | Ignored; name tasks as `pkg#task` or select with `--filter`. |
| `nxCloudAccessToken` | not applicable | Nx Cloud credential; `nxCache()` talks to self-hosted `/v1/cache` servers. |
| `nxCloudUrl` | not applicable | Nx Cloud endpoint; `nxCache()` talks to self-hosted `/v1/cache` servers. |
| `nxCloudEncryptionKey` | not applicable | Nx Cloud artifact encryption. |
| `neverConnectToCloud` | not applicable | Nx Cloud opt-out; vx never connects to Nx Cloud. |
| `parallel` | mapped, with a note | nx() fills the workspace's `concurrency` when `vx.workspace.ts` sets none; `NX_PARALLEL` wins over it, as in Nx. |
| `cacheDirectory` | not supported | Ignored; vx uses its own `cacheDir`. |
| `useDaemonProcess` | not applicable | vx has no daemon; Nx's setting still applies when vx asks Nx for the graph. |
| `useInferencePlugins` | mapped, with a note | Applied by Nx when it builds the graph; vx sees the targets that result. |
| `analytics` | not applicable | Nx usage analytics. |
| `release` | not applicable | Nx versioning and publishing; `nx-release-publish` targets still run through `nx-exec`. |
| `sync` | not supported | Global sync generators never run; under `nx()` vx warns once per run to run `nx sync`, and a migration notes keeping their output by hand. |
| `migrate` | not applicable | Settings for `nx migrate`. |
| `conformance` | not applicable | Nx Powerpack conformance rules. |
| `owners` | not applicable | Nx Powerpack CODEOWNERS generation. |
| `targetDefaults.*.filter` | mapped, with a note | Applied by Nx while it builds the graph vx reads. |
| `targetDefaults.*.executor` | mapped, with a note | Merged into targets by Nx, then mapped as `targets.*.executor`. |
| `targetDefaults.*.command` | mapped, with a note | Merged into targets by Nx, then run as `targets.*.command`. |
| `targetDefaults.*.metadata` | mapped, with a note | Merged into targets by Nx, then read as `targets.*.metadata`. |
| `targetDefaults.*.options` | mapped, with a note | Merged into targets by Nx, then passed on as `targets.*.options`. |
| `targetDefaults.*.outputs` | mapped, with a note | Merged into targets by Nx, then mapped as `targets.*.outputs`. |
| `targetDefaults.*.defaultConfiguration` | mapped, with a note | Merged into targets by Nx, then read as `targets.*.defaultConfiguration`. |
| `targetDefaults.*.configurations` | mapped, with a note | Merged into targets by Nx, then one task per configuration. |
| `targetDefaults.*.continuous` | mapped, with a note | Merged into targets by Nx, then a persistent, uncached task. |
| `targetDefaults.*.parallelism` | not supported | `parallelism: false` gets a TODO to run with `--concurrency 1`. |
| `targetDefaults.*.inputs` | mapped, with a note | Merged into targets by Nx, then expanded as `targets.*.inputs`. |
| `targetDefaults.*.dependsOn` | mapped, with a note | Merged into targets by Nx, then mapped as `targets.*.dependsOn`. |
| `targetDefaults.*.cache` | mapped, with a note | Merged into targets by Nx, then read as `targets.*.cache`. |
| `targetDefaults.*.syncGenerators` | not supported | One workspace note per generator list, counting its tasks, says to run `nx sync` (a migration: keep their output by hand); vx never runs sync generators. |

## `project.json`

| Key | vx | Note |
| --- | --- | --- |
| `name` | mapped, with a note | Used in `nx-exec` lines and `project:target` edges; the vx project takes the `package.json` name. |
| `root` | supported | Graph nodes are matched to workspace packages by root directory. |
| `sourceRoot` | mapped, with a note | Not read by the mapper; executors still see it through `nx-exec`. |
| `projectType` | not applicable | App-or-library metadata for generators and tooling. |
| `generators` | not applicable | Per-project generator defaults; vx has no generators. |
| `namedInputs` | mapped, with a note | Merged over `nx.json`'s and expanded into each task's cache inputs. |
| `targets` | mapped, with a note | Each target becomes a vx task, plus one per non-default configuration. |
| `tags` | supported | Become the project's vx `tags` (a vx.config's own win), so `--filter tag:<name>` or `--projects tag:<name>` selects as `nx run-many -p tag:<name>` does; `tag:` patterns in `dependsOn` resolve against them. |
| `implicitDependencies` | mapped, with a note | Graph edges without a `package.json` link become explicit `pkg#target` edges for `^target`. |
| `metadata` | mapped, with a note | Only `targetGroups` is read, to find non-atomized targets' `.env` files. |
| `release` | not applicable | Nx release settings. |
| `targets.*.executor` | mapped, with a note | `run-commands` and `run-script` become shell lines, `noop` a group task; every other executor runs through `nx-exec`, under `nx()` and in the migrator's written config alike (the migrator translates no executor). |
| `targets.*.options` | mapped, with a note | Rendered into `run-commands`, or passed as `nx-exec`'s `--options`; `{args.*}` forwarding gets a TODO. |
| `targets.*.outputs` | mapped, with a note | Tokens and `{options.x}` resolved; paths outside the project become workspace files, and one outside the workspace is dropped with a TODO; negations kept; vx cleans outputs before a run, so a file git tracks under an output, committed or only `git add`ed, is taken back with `!` (past 16, the task runs uncached with a TODO), and so is the project's own `package.json` or vx.config; a wildcard first segment stays cached under git and leaves the task uncached with a TODO without it. |
| `targets.*.defaultConfiguration` | supported | The base task carries the default configuration's options, as `nx run` does. |
| `targets.*.configurations` | mapped, with a note | One task per configuration (`build:ci`); own, named and `^` edges take the configuration where declared, else the default (a `^` edge becomes one edge per dependency Nx links). |
| `targets.*.inputs` | mapped, with a note | Expanded into `cache.inputs`; none means `default` and `^default`; forms without an equivalent get TODOs. |
| `targets.*.dependsOn` | mapped, with a note | `project:target` becomes `pkg#target`; project patterns and tags resolved; a target glob (`test:e2e--*`) expands over the workspace's target names, as Nx 19.5+ does, a same-project one over its own; `params: forward` gets a TODO. |
| `targets.*.command` | mapped, with a note | Run as the `run-commands` shorthand: one POSIX sh line. |
| `targets.*.cache` | supported | `cache: true` (or `cacheableOperations`) gives a cache block; persistent tasks stay uncached. |
| `targets.*.continuous` | supported | An uncached `exec.persistent` task, ready on spawn: Nx starts its dependents once it has started, and so does vx. A run-commands `readyWhen` becomes `exec.persistent.readyWhen`. |
| `targets.*.parallelism` | not supported | `parallelism: false` gets a TODO to run with `--concurrency 1`; vx has no per-task exclusivity. |
| `targets.*.metadata` | mapped, with a note | Only `nonAtomizedTarget` is read, to find `.env` files. |
| `targets.*.syncGenerators` | not supported | One workspace note per generator list, counting its tasks, says to run `nx sync` (a migration: keep their output by hand); vx never runs sync generators. |

## Nx `inputs` forms

| Key | vx | Note |
| --- | --- | --- |
| `a string` | mapped, with a note | Named inputs expanded, token paths made project or workspace globs, `^name` folded over dependencies. |
| `{fileset, dependencies}` | mapped, with a note | The fileset becomes a glob; with `dependencies: true` it is folded through the dependencies. |
| `{projects, dependencies, input}` | mapped, with a note | Folded through the named projects' inputs (a superset); unknown project names get a TODO. |
| `{runtime}` | supported | Becomes `cache.inputs.workspaceRuntime`, run at the workspace root as Nx does. |
| `{env}` | supported | Goes to `cache.inputs.env` and `exec.env.passThrough`. |
| `{externalDependencies}` | not supported | Dropped: vx keys every task on the lockfile already. Silent for names the root package.json declares; a TODO names any other. |
| `{dependentTasksOutputFiles, transitive}` | supported | Nothing to map: vx folds each dependency's cache key (its inputs, transitively) through `dependsOn`, and an output follows from its inputs. |
| `{json, fields, excludeFields}` | mapped, with a note | The whole file is hashed, a superset of the selected fields. |

---

# vx vs Turborepo

> The same 1,090-package graph run by both, what each one asks of you, and when Turborepo is the better pick.

Both tools run the tasks of a JavaScript monorepo and cache their results.
This page puts them side by side on one benchmark, feature by feature, and
says when Turborepo is the better choice. The design choices behind both
are on [vx, Turborepo, Nx, Bazel](../).

## The numbers

<!-- 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                  |
| ----------------------------------------------- | -------------- | -------------------------- |
| Cold build: total time                          | **3 min 40 s** | 4 min 59 s (vx 36% faster) |
| Cold build: CPU burned                          | **17 s**       | 21 s (vx 22% faster)       |
| Fully cached run (restored)                     | **650 ms**     | 997 ms (vx 53% faster)     |
| Fully cached run (up-to-date)                   | **393 ms**     | 463 ms (vx 18% faster)     |
| Secondary: time the runner adds to a cold build | **2 s**        | 1 min 21 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.

Same graph, commands and concurrency, each tool in its own native config: [how it is measured](../../benchmarks/).

<!-- bench:end -->

## Feature by feature

|                            | vx                                                                | Turborepo                                    |
| -------------------------- | ----------------------------------------------------------------- | -------------------------------------------- |
| Config                     | TypeScript, evaluated into the cache key                          | JSON (`turbo.json`), static                  |
| Default inputs             | None: you declare `cache.inputs.files`                            | Every tracked file in the package            |
| Outputs on run and restore | Wiped first: no stale file survives a hit                         | Additive: stale files survive                |
| Task sandbox               | Free and local, opt-in per task (Linux, macOS)                    | Its docs describe no file sandbox            |
| Clean-tree hashing         | No source reads: git index OIDs                                   | git OIDs                                     |
| Daemon                     | None                                                              | None for `turbo run` since 2.8.11            |
| Remote cache               | Any wire through a plugin; `turboCache()` speaks Turbo's own      | Vercel's `/v8/artifacts`, hosted or your own |
| Plugins                    | Every pipeline stage, 14 hooks; core applies none                 | Its docs describe no plugin surface          |
| Why a task missed          | `vx why` diffs two keys: the file, env var or upstream that moved | `--summarize` shows hashes, not the diff     |
| Watch mode                 | `vx watch <task>`                                                 | `turbo watch`                                |
| Prune for Docker           | `vx prune`, from `@vzn/vx-lockfile`                               | `turbo prune`                                |
| Import boundaries          | No: a lint's job                                                  | `boundaries`                                 |
| Non-JS projects            | No                                                                | Experimental: Go, Cargo, uv                  |
| Terminal output            | Streamed blocks you can scroll, copy and pipe                     | Terminal UI                                  |
| Windows                    | WSL2                                                              | Native                                       |
| Install                    | One binary; no Bun, Node optional                                 | npm and Node                                 |

Every row is held in [vx vs Turborepo vs Nx](../../comparison/), which
links each claim to its source.

## A cache you can trust

- **Your config is in the key.** vx evaluates each TypeScript config
  before hashing, so imports and computed values move the key.
- **Outputs are owned.** Declared outputs are wiped before every run and
  every restore, so a file from last week's build cannot ride along on a
  hit.
- **Tasks can prove their reads.** Opt a task into the
  [sandbox](../../guides/sandboxing/), and a workspace file it did not
  declare is out of its reach. A violation fails the task, and a failed
  task is never cached.
- **Pull requests keep to their own scope.** A pull request run reads the
  trusted keys and writes only its own, over any wire, Turbo's included.
  The real boundary is a token your cache server limits; the scope keeps
  honest runs apart ([security model](../../security/#cache-poisoning)).

## Where Turborepo wins

Pick Turborepo if one of these decides it for you:

- **Caching before anyone writes an input list.** Turborepo hashes every
  tracked file in a package by default
  ([`inputs`](https://turborepo.com/docs/reference/configuration#inputs)).
  vx makes you declare inputs, and keeping them right is your job.
- **Native Windows.** vx runs under WSL2.
- **A stable release with a support policy, today.** vx is pre-alpha:
  0.0.x on npm, no
  [support policy](https://turborepo.com/docs/support-policy) yet.
- **A terminal UI and import boundaries.** Both ship in Turborepo. vx
  streams plain blocks and leaves boundaries to your linter.
- **Go, Cargo or uv in the graph.** Turborepo has experimental support.
  vx runs JavaScript workspaces only.

## Switch in one command

```sh
vx init
vx run build --all
```

`vx init` finds `turbo.json` and writes one `vx.config.ts` per package,
plus the workspace file, through [`@vzn/vx-migrate`](../../guides/migrate/).
Anything Turbo can say that vx cannot becomes a `TODO(vx-migrate)`
comment, never a silent wrong value. Your `package.json` scripts are never
edited. Keep your remote cache with `turboCache()`: any server speaking
Turbo's `/v8/artifacts` API, Vercel's hosted cache included. The numbers
above are native vx config.

## FAQ

**Do my Turbo flags still work?**
`vx run` takes each Turbo flag as it is (`--filter`, `--affected`,
`--concurrency`), rewrites it to vx's spelling, or refuses it and names the
vx way. None is dropped in silence.

**Can I keep Vercel Remote Cache?**
Yes. Set `TURBO_TOKEN` and `TURBO_TEAM`, declare `turboCache()`, and vx
stores its own artifacts there. Turbo cannot read what vx stores, and vx
does not read Turbo's entries.

**What does it cost?**
Nothing. vx is MIT, with no cloud and no account.

**Do I need Bun?**
No. The npm package installs a prebuilt binary for Linux and macOS, x64 and
arm64. Windows: use WSL2.

---

# Compared to Turborepo, Nx, vite-task

> A side-by-side reference for what each of the four tools does, plus an

A side-by-side reference for what each of the four tools does, plus an
explicit list of gaps `@vzn/vx` has against the other three.

This is a living document; every claim cites a source file or reference
page in the upstream repo so future revisions can be diffed against
reality. Last verified 2026-09-03 against `turbo@2.10.12`, `nx@23.2.0`
and `voidzero-dev/vite-task` `main` (now the engine behind Vite+'s
`vp run`). Five Turbo and Nx rows (the lockfile, non-JS projects, the
daemon, the plugin surface, Nx's language plugins) were corrected on
2026-09-24 against the tools' docs sources, for the choosing page (item
689).

## Positioning in one paragraph each

- **Turborepo** — production-grade. Per-package `turbo.json`, remote
  cache, OTLP observability, watch, prune, query, boundaries, a TUI.
  Maximally featureful; many features are flagged "experimental", and
  it has deprecated its own daemon for `turbo run` (2.8.11) and
  `--parallel` (by 2.9.18); the flag surface is the largest of the four.
  _Reference repo:_ `vercel/turborepo`.
- **Nx** — production-grade and pluggable. Per-package `project.json`,
  plugins that infer tasks and add generators and executors (first-party
  Gradle, Maven and .NET; community Rust, Go and Python), `affected`
  semantics, Terminal UI, named inputs / target defaults, distributed
  task execution via Nx Cloud agents. Heaviest schema. _Reference
  repo:_ `nrwl/nx`.
- **vite-task** — Rust-fast, smallest schema, novel **filesystem-spy
  auto-input inference** (default `{auto: true}`). Pre/post script
  lifecycle from `package.json` scripts. SQLite + tar.zst local cache
  with make-style validate-at-lookup (traced reads re-fingerprinted on
  every hit — gives early cutoff, but the key isn't derivable before
  execution, which is why it has no remote cache). _Reference repo:_
  `voidzero-dev/vite-task`.
- **`@vzn/vx`** — one thing, built to be built on. TypeScript-native
  config, opt-in caching, Turbo-shape cache key with two extensions
  (project package.json folded in; resolved-config hash captures TS
  imports). One self-contained binary per platform (Linux and macOS,
  x64 and arm64; Windows under WSL) — no Node or Bun to run it.
  Smallest CLI surface; deliberately no daemon, no cloud, no account
  and no JS-function tasks. The core is a Vite-style pipeline: plugins
  hook each stage (`config` → `discover` → `project` → `graph` → `key` →
  `fingerprint` → `schedule` → `admit`), supply the executor (WHERE a command
  runs, never what it is), the cache layers and the telemetry sinks,
  and add verbs — core applies none of them by default and names none.
  Strict output ownership. What Nx would be if it were not a product.

Every row a Turbo or Nx user would look for, spelled in vx and pinned by
a test that runs the real CLI, is [`parity.md`](../parity/); this page
is the wider matrix and the reasoning.

## Quick CLI flag map

`turbo run` / `nx run-many` / `vp run` / `vx run`:

| Capability                 | Turbo                                                                 | Nx                                              | vite-task                           | vx                                                                                                      |
| -------------------------- | --------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
| pnpm-style filter DSL      | `--filter`                                                            | `--projects`, `--exclude`                       | `--filter`                          | `--filter`                                                                                              |
| select by project tag      | —                                                                     | `-p tag:<name>`                                 | —                                   | `--filter tag:<name>` (config `tags`; `-p tag:` aliases it)                                             |
| recursive (every project)  | implicit                                                              | implicit (no `-p`); `--all` deprecated          | `-r`                                | `--all`                                                                                                 |
| transitive deps            | `pkg...`                                                              | `--with-deps` (legacy)                          | `-t`                                | `pkg...` (via DSL)                                                                                      |
| `pkg#task` addressing      | yes                                                                   | `nx run pkg:target`                             | yes                                 | yes                                                                                                     |
| concurrency cap            | `--concurrency`                                                       | `--parallel`                                    | `--concurrency-limit`               | `--concurrency`                                                                                         |
| serialize / drop dep order | `--parallel` (deprecated)                                             | (always topo)                                   | `--parallel`                        | `--concurrency 1` to serialize; no `--parallel` (see note)                                              |
| skip dependsOn             | `--only`                                                              | `--excludeTaskDependencies`                     | `--ignore-depends-on`               | `--exclude-dependencies[=<names>]`                                                                      |
| `pkg#task` + bare task     | cross-product: `web#lint build` also runs `web#build`                 | —                                               | —                                   | **≠** bare names take the filter scope only; an anchored task never widens it                           |
| one-at-a-time task         | —                                                                     | `parallelism: false`                            | —                                   | a `@vzn/vx-schedule-history` `cpus` reservation above the worker count runs alone; or `--concurrency 1` |
| forward args               | `--`                                                                  | `--args="..."`                                  | trailing args                       | `--`                                                                                                    |
| skip cache reads+writes    | `--cache=local:,remote:` (`--force` skips reads, `--no-cache` writes) | `--skipNxCache`, `--skipRemoteCache`            | `--no-cache`                        | `--no-cache` (all off) / `--force` (reads off, writes on) / `--cache=<spec>` per-layer                  |
| dry-run (print plan)       | `--dry`, `--dry=json`                                                 | `--graph` renders                               | —                                   | `--dry`, `--dry=json`                                                                                   |
| affected (git-relative)    | `--affected`                                                          | full `affected` subcommand                      | —                                   | `--affected[=<base>]` + `[<since>]` filter form                                                         |
| graph render               | `--graph file.{dot,html}`                                             | `--graph`                                       | —                                   | `--graph[=<path>]` (DOT)                                                                                |
| continue past failure      | `--continue=never\|dependencies-successful\|always`                   | `--nxBail`                                      | —                                   | `--continue[=never\|deps-ok\|always]` (deps-ok default)                                                 |
| per-run JSON summary       | `--summarize`, `--json`                                               | —                                               | `--last-details` replay             | `--summarize[=<path>]`                                                                                  |
| output log mode            | `--output-logs=full\|hash-only\|new-only\|errors-only\|none`          | `--outputStyle=tui\|dynamic\|static\|stream\|…` | `--log=interleaved/labeled/grouped` | `--output-logs full\|hash-only\|errors-only\|none` (+ flow-derived default)                             |
| profile / Chrome trace     | `--profile`                                                           | (via Nx Cloud)                                  | —                                   | `--profile[=<path>]`                                                                                    |
| daemon on/off              | (deprecated in 2.8.11; ignored)                                       | (Nx daemon, always on)                          | —                                   | (no daemon)                                                                                             |
| retries / timeouts         | —                                                                     | —                                               | —                                   | `--retry <n>`, `--timeout <ms>` (also per task in config)                                               |
| remote placement / outputs | — (remote cache only)                                                 | Nx Cloud agents                                 | —                                   | `--download=all\|toplevel\|none`, `exec.remote` (executor plugin, e.g. `@vzn/vx-reapi`)                 |
| run report                 | `--summarize`                                                         | —                                               | —                                   | `--report=markdown`, `--report-file`; `vx last` replays any recorded run                                |
| watch mode                 | `turbo watch`                                                         | `nx watch`                                      | —                                   | `vx watch <task>`                                                                                       |
| version / help             | `--version` / `--help`                                                | `--version` / `--help`                          | `--version` / `--help`              | `--version`, `--help` / `-h`                                                                            |

_Sources_: Turbo `/docs/reference/run` (turborepo.dev, 2.10.12); Nx
`/reference/core-api/nx/documents/run-many` (nx.dev, 23.2.0);
vite-task `/crates/vite_task/src/cli/mod.rs`; vx `src/cli/run.ts`.

> **Why no `--parallel`?** Turbo's `--parallel` exists because users
> often over-declare `dependsOn` and want an escape hatch. In vx,
> `dependsOn` is opt-in and explicit — if you wrote
> `dependsOn: ['^build']` you meant it. The legitimate
> "I want to fan out without waiting" cases are already covered by
> (a) not declaring `dependsOn` in the first place, and (b)
> `--exclude-dependencies`, which keeps dependencies from running, entirely
> or selectively.

## Config schema comparison

| Schema feature                                                              | Turbo                                                | Nx                                                       | vite-task                          | vx                                                                                                      |
| --------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Config language                                                             | JSON (`turbo.json`)                                  | JSON (`project.json`, `nx.json`)                         | Vite config (`run` key)            | TypeScript (`vx.config.ts`)                                                                             |
| Per-package config                                                          | yes                                                  | yes                                                      | yes                                | yes                                                                                                     |
| Workspace-level config                                                      | `turbo.json` at root + `extends`                     | `nx.json`                                                | root `vite.config.*`               | `vx.workspace.ts` (concurrency, cacheDir, timeout, cacheRetention, plugins)                             |
| Per-task `dependsOn`: same project                                          | bare name `lint`                                     | bare name                                                | bare name                          | `'lint'`                                                                                                |
| Per-task `dependsOn`: workspace deps                                        | `^lint`                                              | `^lint` (`{projects:"dependencies"}` deprecated)         | `pkg#task`                         | `'^lint'`                                                                                               |
| Per-task `dependsOn`: arbitrary other package's task                        | `pkg#task`                                           | `{projects:["pkg"],target:"task"}`                       | `pkg#task`                         | `'pkg#task'`                                                                                            |
| Wildcards in `dependsOn`                                                    | —                                                    | v19.5+: `build-*`, `^build-*`                            | —                                  | `'build.*'`, `'^build.*'` (task-name patterns; bare `*` stays filter-only)                              |
| Group / umbrella tasks                                                      | tasks with `dependsOn` only                          | (achieved via target groups)                             | (none)                             | yes — tasks with no `exec`                                                                              |
| Input declarations                                                          | `inputs: [...]` + `$TURBO_DEFAULT$` etc.             | `inputs: [...]` w/ rich types                            | `input: glob` or `{auto:true}`     | `cache.inputs.files: string[]`                                                                          |
| Auto-input inference                                                        | —                                                    | —                                                        | **yes** (`fspy`, see §3)           | — out of scope (see §3)                                                                                 |
| Root-anchored inputs/outputs                                                | `$TURBO_ROOT$/…`                                     | `{workspaceRoot}/…`                                      | (none)                             | `cache.inputs/outputs.workspaceFiles`                                                                   |
| Runtime-command inputs (tool versions, probes)                              | — (vercel/turborepo#4124)                            | `runtime` input                                          | (none)                             | `cache.inputs.runtime` / `workspaceRuntime`                                                             |
| Frozen / locked resolved configs                                            | —                                                    | —                                                        | —                                  | `vx lock` + `vx run --frozen`                                                                           |
| Migration generator from other runners                                      | —                                                    | —                                                        | —                                  | `bunx @vzn/vx-migrate` (Turbo, Nx → vx.config.ts)                                                       |
| Named / reusable input sets                                                 | (none)                                               | `namedInputs` at workspace + project level               | (none)                             | rejected by design — TS arrays/imports compose                                                          |
| Per-task env inputs                                                         | `env: ["NODE_ENV"]`                                  | `inputs: [{env: "NODE_ENV"}]`                            | `env: [...]` + `untrackedEnv`      | `cache.inputs.env: string[]`                                                                            |
| Pass-through env                                                            | `passThroughEnv`                                     | (always pass through)                                    | `untrackedEnv` (passed, no hash)   | `exec.env.passThrough`                                                                                  |
| Define / literal env                                                        | (no; rely on globalEnv)                              | (via executor options)                                   | (no; in script)                    | `exec.env.define`                                                                                       |
| Workspace-level env inputs                                                  | `globalEnv`, `globalPassThroughEnv`                  | workspace `namedInputs` + `inputs`                       | (no)                               | rejected by design — TS presets compose                                                                 |
| Output declarations                                                         | `outputs: [...]`                                     | `outputs: [...]`                                         | `output: glob` or `{pattern,base}` | `cache.outputs.files: string[]`                                                                         |
| Output cleaning before exec / restore                                       | (no — additive)                                      | (no — additive)                                          | (via materialized artifacts)       | **yes** — strict                                                                                        |
| Implicit-dependency hash (project `package.json`)                           | yes — `package.json` is a default input              | `externalDependencies`                                   | (via lockfile)                     | **yes** — folded directly (v12)                                                                         |
| Lockfile-aware invalidation (only the projects a dependency change reaches) | per package: the lockfile changes that affect it     | yes — pruned lockfile per project, in the daemon's graph | (whole lockfile)                   | **`@vzn/vx-lockfile`** — per-project closure digest, memoised by lockfile hash; `--affected` follows it |
| Resolved-config hash (captures TS imports)                                  | —                                                    | —                                                        | —                                  | **yes** — `node.config` JSON hashed                                                                     |
| Persistent / long-running tasks (dev servers)                               | `persistent`, `interruptible`, `interactive`, `with` | `continuous`                                             | (handled outside graph)            | `exec.persistent.readyWhen`, `exec.interactive`                                                         |
| Configurations (named option sets)                                          | —                                                    | `configurations` + `-c`                                  | —                                  | — **gap**                                                                                               |
| Per-target metadata (`description`)                                         | `description`                                        | `metadata.description`                                   | —                                  | `description: string`                                                                                   |
| Target defaults / inheritance                                               | `extends`, task `extends`                            | `targetDefaults` (priority-resolved)                     | (no)                               | rejected by design — presets are TS imports                                                             |
| Pre/post script lifecycle                                                   | yes — the package manager runs them                  | (executor-defined)                                       | `enablePrePostScripts: true`       | `vx init` folds them into the command                                                                   |
| Boundaries / package-tag visibility                                         | `boundaries.tags`                                    | `@nx/enforce-module-boundaries`                          | (no)                               | — **gap**                                                                                               |

## Cache feature comparison

| Cache feature            | Turbo                                      | Nx                     | vite-task                    | vx                                                                                                                                                                        |
| ------------------------ | ------------------------------------------ | ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Local cache              | tarball-per-hash in `.turbo/cache`         | `.nx/cache` SQLite-ish | materialized-artifact crates | SQLite index + one `<hash>.tar.zst` per entry in a store every checkout of the repo shares (`~/.vx/<id>/cache`)                                                           |
| Remote cache wire        | Vercel `/v8/artifacts/` (HMAC, pre-signed) | Nx Cloud or plugin     | —                            | plugin-driven: `@vzn/vx-reapi` (Bazel AC/CAS), `@vzn/vx-migrate`'s `turboCache()` (`/v8/artifacts`, self-hosted or Vercel), `@vzn/vx-migrate`'s `nxCache()` (`/v1/cache`) |
| Log replay on hit        | yes                                        | yes                    | yes                          | yes                                                                                                                                                                       |
| Output restore on hit    | yes                                        | yes                    | yes                          | yes                                                                                                                                                                       |
| Output cleaning          | (no — additive)                            | (no)                   | (materialized)               | **yes** — wipe before exec AND before restore                                                                                                                             |
| Cache pruning            | `cacheMaxAge`, `cacheMaxSize` in config    | `maxCacheSize`         | `vp run cache clean`         | `cacheRetention: { olderThan, maxSize }` in `vx.workspace.ts` (run end), `vx cache prune --older-than / --max-size`                                                       |
| Stats / run history      | `--summarize` JSON files                   | Nx Cloud dashboard     | `--last-details`             | `runs` + `invocations` tables in `cache.db` (direct SQL); `vx info`; `vx last`                                                                                            |
| Per-run JSON summary     | `--summarize`                              | `--outputStyle`        | `--last-details`             | `--summarize[=<path>]`                                                                                                                                                    |
| Flaky task detection     | —                                          | Nx Cloud (paid)        | —                            | **local** — same key failed after it passed: the task's row, `--summarize` (`flaky`), `vx info`                                                                           |
| Chrome-trace profile     | `--profile`                                | (Nx Cloud)             | —                            | `--profile[=<path>]`                                                                                                                                                      |
| Async remote prefetch    | —                                          | —                      | —                            | **yes** — stable-key GETs overlap execution                                                                                                                               |
| Restore-ahead scheduling | —                                          | —                      | —                            | **yes** — two-tier scheduler restores warm hits ahead of their deps                                                                                                       |
| Artifact integrity       | HMAC `x-artifact-tag`                      | (transport-level)      | —                            | core refuses a bomb, a non-vx archive, or one recording another key; `@vzn/vx-reapi` re-hashes every blob                                                                 |
| Pre-signed URL auth      | yes                                        | yes                    | —                            | plugin's business — core ships the `cache` seam, not a transport                                                                                                          |

## Workspace integration

| Capability                                | Turbo                                   | Nx                                      | vite-task  | vx                                                                  |
| ----------------------------------------- | --------------------------------------- | --------------------------------------- | ---------- | ------------------------------------------------------------------- |
| pnpm / npm / yarn / bun workspaces        | yes                                     | yes                                     | yes        | yes (pnpm-workspace.yaml, package.json `workspaces`, bare pkg.json) |
| Non-JS projects (Rust, .NET, Gradle, ...) | experimental (native Go, Cargo, uv)     | yes (plugins)                           | no         | no                                                                  |
| Filter DSL                                | pnpm-style + `[<since>]` (git-relative) | yes via `--projects/--exclude` (no DSL) | pnpm-style | pnpm-style + `[<since>]`                                            |
| Affected / git-relative                   | `--filter '[since...]'`, `--affected`   | full `affected` subcommand              | —          | `--affected[=<base>]` + `[<since>]`                                 |
| Daemon / persistent project-graph process | not for `turbo run` since 2.8.11        | yes (on by default locally)             | —          | — **out of scope**                                                  |
| Watch mode                                | `turbo watch`                           | `nx watch`                              | —          | `vx watch <task>`                                                   |
| Prune workspace (Docker subset)           | `turbo prune`                           | —                                       | —          | — **gap**                                                           |

## Gap audit 2026-09-04 — what a developer would miss, core or plugin

The owner's question: which Nx 23 / Turbo 2.10 features are a MUST or
a game changer for developers, and of those, which belong in core.
Rule applied: if a plugin can do it through an existing seam, it is
not core. Every row below was checked against `docs/cli.md`,
`docs/schema.md` and the source, not remembered.

**Verified present in core** (parity or ahead): the task graph with
`^task` / wildcards / nearest-holder frontier; `--filter` as a superset
of Turbo's DSL (`...`, `^...`, `!`, `./dir`, `[git-ref]`) and
`--affected`; caching with declared inputs, outputs, `inputs.env`,
workspace files; strict env isolation (Turbo's
`--env-mode=strict` is vx's only mode); `persistent` tasks with
readiness gating (ahead of Turbo's `persistent` and Nx's
`continuous`); the interactive picker; `watch`, `--dry`, `--graph`,
`--summarize`, `--profile`, `--continue` modes, retries, timeouts,
`--output-logs` modes; `init` (scripts to configs) and, its own
package, `bunx @vzn/vx-migrate` (Turbo, Nx); the cwd-scoped default;
`last`, `why`, `show`, `info`; remote cache and execution through the
seams (`@vzn/vx-reapi`).

**Missing, and where it belongs:**

| Feature                                                                     | Nx / Turbo    | Verdict                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zero-config adoption: `package.json` scripts are tasks, no per-package file | both, in core | SHIPPED 2026-09-09 as `@vzn/vx-turbo`, `turbo()` in `@vzn/vx-migrate` since 2026-09-11: a `project`-stage plugin over the same mapper `vx-migrate` renders from, so a `turbo.json` repo starts, temporarily, with only a `vx.workspace.ts`; the seam widening core needed (visit a config-less package when a plugin declares `project`) landed with it. Nx followed 2026-09-22 (`nx()`, item 590): the same stage over Nx's resolved graph, executor targets run as themselves through `nx-exec`. |
| Inferred tasks from tool configs (`vite.config` ⇒ build/serve/test)         | Nx plugins    | The `project` stage is the seam (a plugin visits every package, a config-less one as `{ tasks: {} }`, and fills what the package did not declare); a first-party family was built and RETIRED the same day (2026-09-10, owner): technology plugins are the community's, core names no tool. The recipe is in the plugins guide.                                                                                                                                                                    |
| `.env` files loaded into the task env                                       | Nx            | Tasks read their own `.env` (Vite, Next do); the cache side is `cache.inputs.files: ['.env*']`. A `config`-stage plugin can inject. Not core; a docs footnote.                                                                                                                                                                                                                                                                                                                                     |
| Configurations (`build:prod` as one task, two modes)                        | Nx            | The language: a TS function returning the task per mode. Not core.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Cache size / age caps applied during runs                                   | both          | SHIPPED 2026-09-23 (item 658) in core as `cacheRetention`: the local cache is core's floor, not a plugin, so its caps are a workspace field.                                                                                                                                                                                                                                                                                                                                                       |
| Graph UI, TUI, dashboards                                                   | both          | Rejected for core; `--graph` emits the data for a plugin or a site.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Versioning and publishing (`nx release`)                                    | Nx            | `commands` seam; changesets already exists. Not core.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Test splitting (Nx atomizer)                                                | Nx            | `graph`-stage plugin. Not core.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Import boundaries (`turbo boundaries`)                                      | Turbo         | A lint; out of scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Shell completions                                                           | both          | SHIPPED 2026-09-10: `vx completions bash\|zsh\|fish` over the verb table and each verb's help cut.                                                                                                                                                                                                                                                                                                                                                                                                 |
| Windows                                                                     | both          | Under WSL (owner, 2026-09-10): POSIX shell is the API, and WSL is where it is on Windows. A native port is not proposed.                                                                                                                                                                                                                                                                                                                                                                           |

Net: core is at parity or ahead on the must-haves; the gap that costs
adoption is the trial with no generated files, and its core half is a
small seam. Everything else is a plugin or the language.

## Gaps for `@vzn/vx` (the running list)

Ranked by leverage. Cited file paths are inside the respective
upstream repos.

### Likely-worth-adding

1. **Remote cache is PLUGIN-DRIVEN (owner directive 2026-07-10).** Core
   carries zero HTTP cache code: it keeps the seams (`LayeredCache`, the
   `RemoteCacheLayer` interface, the `cache` plugin capability,
   `RunOptions.remoteCache`), and a plugin ships the wire —
   `@vzn/vx-reapi` speaks Bazel's ActionCache + CAS, so NativeLink,
   BuildBuddy, Buildbarn and bazel-remote all work.
   Turbo `/v8/artifacts` compatibility was DROPPED from core and came
   back as a plugin: `turboCache()` in `@vzn/vx-migrate` speaks the Turbo
   wire (self-hosted or Vercel) and `nxCache()` the Nx self-hosted
   one, both against the same `cache` seam — the recipe for any other
   wire lives in the plugins guide.

2. **`--continue=<mode>` — shipped.** `--continue[=never|deps-ok|always]`
   controls failure propagation: `never` fail-fast (stop dispatch on the
   first failure), `deps-ok` (default) skip only a failure's dependents
   while independent siblings continue, `always` run everything. Bare
   `--continue` = `always`. Enforced in the scheduler; see
   [`cli.md`](../cli/) § Failure propagation.

3. **Wildcards in `dependsOn` — shipped.** `'build.*'` expands to every
   other same-project task matching the pattern (zero matches legal);
   `'^build.*'` walks the nearest-holder frontier where a holder is a
   dep declaring ≥1 match and receives edges to ALL of them. `*` is the
   sole metacharacter; bare `'*'`/`'^*'` stay filter-only
   (`cache.inputs.tasks`), and `'pkg#pattern'` is rejected. See
   [`schema.md`](../schema/) § dependsOn.
   - Nx 19.5+ `build-*` parity.

4. **Workspace-level `globalInputs` / `globalEnv` / `globalPassThrough`
   — owner-REJECTED (2026-07-05, "no global").** TypeScript configs
   compose: a shared preset imported and spread into each config IS the
   global-inputs/global-env mechanism (same rationale as the rejected
   named-inputs machinery — a schema field would duplicate the language).
   The `@vzn/vx-migrate` Turbo path already emits a generated `vx-preset.ts`
   for exactly this. Not a gap; will not be added.
   - Turbo `globalEnv`, `globalPassThroughEnv`.

5. **`--cache-dir <path>` CLI flag — shipped.** Overrides the
   `defineWorkspace({ cacheDir })` field + the `.vx/cache` default,
   resolved relative to cwd. A per-run knob; never folded into a cache
   key.

6. **Auto-input inference via filesystem tracing — owner-REJECTED
   (reconfirmed 2026-07-05, "no auto input").** Re-classified
   **out of scope** for vx (2026-06) after studying vite-task's
   implementation. Doing this soundly is a multi-platform native
   systems project — vite-task ships ~9 Rust crates for it:
   LD_PRELOAD / DYLD_INSERT_LIBRARIES interposition for glibc/macOS,
   a `seccomp_unotify` kernel supervisor for static binaries
   (esbuild, Go tools) that bypass libc, Microsoft Detours on
   Windows, a 4 GiB shared-memory IPC channel, and — because macOS
   SIP strips DYLD injection from Apple-signed binaries — their own
   shipped shell + coreutils to run commands under. Traced reads are
   re-validated at every cache lookup (not key-folded). vx cannot
   ship per-OS native helper binaries without abandoning its
   no-build-step distribution; explicit inputs stay the contract.
   - vite-task: `{auto: true}` is the default; backed by `crates/fspy*`.

### Maybe-worth-adding (heavier lift, narrower payoff)

7. **`--output-logs hash-only` — shipped (2026-08-25).** One line per
   task — outcome word, task id, cache key — with no log output; the
   run's audit trail of which key each task resolved to. All four
   Turbo modes now covered.
   - Turbo: `--output-logs`, schema `outputLogs`.

8. **Configurations (named option sets per target).** `build:prod` vs
   `build:dev` as one task with two configurations rather than two
   tasks. vx's answer today is the language: a TS function returning
   the task for a mode, spread into two tasks, plus a group over both.
   - Nx: `configurations` + `-c`.

9. **Pre/post script lifecycle — shipped in `vx init` (2026-09-03).**
   `pre<x>` / `post<x>` scripts fold into `x`'s command in npm order
   (tasks of their own where the manager runs no hooks)
   when the config is generated, so the ordering survives as a plain
   command rather than as runtime magic; a script that only delegates
   (`npm run other`) becomes a group over `other`. Not applied at run
   time: a task's command is exactly what its config says.
   - vite-task: `enablePrePostScripts` (default true).

10. **`vx prune` — shipped (2026-08-25), `@vzn/vx-prune` from 2026-09-10, removed 2026-09-11, back 2026-10-03 as a verb of `@vzn/vx-lockfile`.** Workspace subset for Docker
    builds: targets + transitive workspace deps, workspace lists rewritten,
    root manifests and vx configs, each lockfile (bun, pnpm, npm, yarn)
    PRUNED to what the subset installs so it installs frozen, `--docker`
    json/full split for layer caching. The 2026-09 verb copied the
    lockfile unpruned.
    - Turbo: `turbo prune`.

11. **Cache TTL / size caps in config — shipped (2026-09-23, item 658) as `cacheRetention`.** `defineWorkspace({ cacheRetention: {
olderThan: '30d', maxSize: '10G' } })` applies the `vx cache
prune` policy at the end of every run,
    only when something is due.
    - Turbo: `cacheMaxAge`, `cacheMaxSize` (verified in the 2.10
      configuration reference).
    - Nx: `maxCacheSize`.

12. **Last-run replay — shipped (2026-08-25) as `vx last`.** Replays
    the most recent (or any recorded) run's summary from the local
    history: header + per-task table, `--list` for recent run ids,
    `--format json` for scripting. Read-only over `metrics.ts`.

### Shipped since this list was first drawn

- `vx watch <task>` — debounced re-run loop.
- `--output-logs full|errors-only|hash-only|none`.
- `vx info` (absorbed `vx stats`, since removed).
- Artifact integrity at the ingest boundary — core refuses a remote
  artifact that decompresses past its ceiling, is not a vx archive, or
  records a key other than the one it was fetched under; `@vzn/vx-reapi`
  re-hashes every CAS blob against its digest, and `turboCache()`
  verifies Turbo's HMAC tag when given a `signatureKey`.
- OTel run telemetry — the `otel()` plugin in `@vzn/vx-otel` (declare
  it in `vx.workspace.ts` + set `OTEL_EXPORTER_OTLP_ENDPOINT`).
- Per-task OS sandboxing (`exec.sandbox`, SRT-backed,
  fail-on-violation).
- Root-anchored inputs/outputs (`workspaceFiles`) and runtime-command
  inputs (`runtime` / `workspaceRuntime`).
- `vx lock` / `vx run --frozen`, `vx init` / `@vzn/vx-migrate`, `vx show`.
- **The plugin pipeline (2026-09-02).** One `VxPlugin` hooks every
  stage — `config`, `discover`, `project`, `graph`, `key`, `fingerprint`,
  `schedule`, `admit` — beside the `executor` / `cache` / `telemetry`
  capabilities, `commands` (new verbs) and the `setup` / `teardown`
  pair. Core applies no plugin by default; a workspace declares all
  of them.
- **A config evaluation cache** for provably pure configs
  (`src/workspace/config-cache.ts`): a lexer-backed purity GATE, not a
  heuristic — with string literals and comments stripped, any BACKSLASH
  in code position (an identifier escape: `\u0070rocess` IS `process`,
  the one spelling a deny-list cannot see), any bare import but
  `@vzn/vx` (its pure values) and `@vzn/vx/config`, or a closure past 32 files opts a config out. Warm 1000-project run
  ~400 → 237 ms with the rest of the perf waves.
- `vx init` (scripts → configs), `vx why`, `vx last`,
  `--download`, remote execution through `@vzn/vx-reapi`,
  `@vzn/vx-ci` (job summary + check run), `@vzn/vx-mcp` (an MCP
  server as a plugin verb), the `schedule-history` plugin (critical-path
  priorities from recorded durations).
- npm distribution as per-platform binary packages plus a launcher,
  signed on macOS.

### Explicitly rejected (owner decisions — do not re-propose)

- **Named / reusable input sets (`namedInputs`) and target defaults /
  inheritance.** TypeScript configs compose — shared presets via
  import ARE vx's named inputs and defaults; schema machinery would
  duplicate the language.

### Explicitly out of scope (today)

These don't appear on the roadmap and won't be added without a
deliberate design pass.

- **Daemon / persistent project-graph process.** Re-discovery is fast
  enough on Bun (a warm 1000-project run is ~170 ms end to end, with
  config loading scoped and pure configs served from the eval cache);
  the operational cost of a daemon doesn't pay for itself. Turbo
  reached the same conclusion: from 2.9 its docs say the daemon is no
  longer used for `turbo run`.
- **JS-function tasks.** "Shell is the API" is a deliberate
  constraint: a task is a command string. The `executor` capability
  decides WHERE that command runs (a worker, a sandbox, this machine)
  and the pipeline hooks shape what the graph contains and how it is
  keyed and ordered — none of them can replace the command with code.
- **Generators / scaffolding.** Not a task-runner concern.
- **TUI / interactive panes.** Streamed framed blocks + the worker
  status region are the terminal format; no Nx-style Terminal UI (an
  attempt was built and dropped). `vx last` replays a recorded run from
  the local history; anything browsable is a telemetry-plugin story
  now that the self-hosted dashboard is gone (2026-08-23).
- **Boundaries / package-tag visibility.** Module-level constraint
  rules belong in lint (`oxlint`, `eslint-plugin-import`), not the
  task runner.
- **Non-JS executor plugins.** Rust / .NET / Gradle projects use their
  own runners. vx is a JS-monorepo runner.
- **Native Windows.** vx spawns POSIX shell. Binaries are built for
  linux/darwin × x64/arm64, and Windows runs the Linux one under WSL2;
  there is no native Windows build, by decision (owner, 2026-10-09).

## Where vx is ahead

Things `@vzn/vx` does that the others don't:

- **A Vite-style pipeline instead of a feature list.** Every stage
  has a hook and every capability is a plugin, in declaration order,
  with core re-validating what a hook returns. A plugin can fold a
  value into every cache key (`key`, and `vx why` shows it by plugin
  name), rewrite a project's tasks, add an edge, reorder the schedule,
  or add a verb — so "vx doesn't do X" is answered with a plugin, not
  a fork. Turbo documents no plugin surface; Nx's plugins infer tasks
  and add graph data, generators, migrations and executors.
- **`vx why` — cache-key explainability.** Per-component input
  fingerprints are recorded on every miss, so a re-run is explained by
  diffing two keys: which file, env var, upstream key or plugin part
  moved. Turbo's `--summarize` and Nx's cache view show hashes, not the
  diff.
- **TypeScript config with full type inference** — no string typos,
  IDE autocomplete, presets as plain imports. The closest thing in
  Turbo/Nx is `extends`; in vite-task it's tied to Vite's config
  loader.
- **Resolved-config hash.** Imports and computed values get folded
  into the cache key because the post-evaluation object is what we
  serialize. Turbo and Nx hash the static JSON file and miss anything
  computed at config-load time.
- **Project `package.json` hash folded in automatically.** Turbo and
  Nx get this transitively via the lockfile; vx folds the per-project
  bytes directly, so narrow `inputs.files` like `['src/**']` doesn't
  miss dep / version-bump invalidation.
- **Lockfile-aware invalidation as a plugin.** `@vzn/vx-lockfile` claims
  the lockfile (pnpm, bun, npm, yarn) and keys each project on its own resolved closure
  (name, version, peers, integrity, patches, `link:` reach), so
  `pnpm update foo` re-keys only the projects that reach `foo` and
  `--affected` selects their tasks (and the tasks behind them). Nx does this inside its daemon's
  project graph; Turbo hashes the lockfile changes that affect each
  package. vx parses once per lockfile
  content and memoises the digests, so a warm run pays a read and a
  hash, not a parse.
- **Strict output ownership.** Declared `cache.outputs.files` are
  wiped before exec AND before cache restore. Both Turbo and Nx
  restore additively; stale files from a prior build survive a cache
  hit there.
- **Group tasks as first-class.** A task with no `exec` (just
  `dependsOn`) is a pure aggregator; doesn't appear in the run output,
  isn't counted in the summary, isn't recorded in analytics.
- **Runtime-command inputs.** `cache.inputs.runtime` /
  `workspaceRuntime` fold a probe command's live output into the key
  (tool versions, OS info) — Nx has `runtime`; Turbo has no
  equivalent (vercel/turborepo#4124).
- **Restore-ahead two-tier scheduling.** A stable-key warm hit
  restores immediately, before its deps finish running, as worker
  backfill — misses still own the pool. Remote runs get the same idea
  as async prefetch (remote GETs overlap execution, at most one per
  key).
- **`vx lock` / `--frozen`.** Configs are programs; the lock freezes
  the resolved objects for CI reproducibility, with a full
  re-evaluation audit (`vx lock --check`). No analog in Turbo/Nx.
- **`bunx @vzn/vx-migrate`.** One command generates per-package `vx.config.ts`
  from Turbo or Nx, with TODO comments for
  everything unmappable.
- **A versioned telemetry contract + plugin seam.** `TelemetryRecord`
  / `RunSummaryRecord` (TELEMETRY_SCHEMA_VERSION) is one neutral
  export shape every sink reads — OTel (`@vzn/vx-otel`), the GitHub
  job summary and check run (`@vzn/vx-ci`), or a custom sink —
  observe-only by construction, zero cost when unused.
- **Bun-native everything, and none of it the user's concern.**
  `Bun.spawn` for child rusage capture, `bun:sqlite`, `Bun.YAML`,
  `Bun.Glob`, `Bun.hash.xxHash3`, `Bun.zstdCompress`, native `await
import()` with a content-hash query string for config cache-busting.
  The binary embeds the runtime: no native-binary build step on install,
  no Node or Bun on the machine.
- **One-binary distribution.** `bun build --compile` produces a
  single self-contained executable per platform target, published as
  per-platform npm packages behind a tiny launcher (the esbuild model)
  and as GitHub release assets — no Bun or Node needed at runtime.
- **Wallclock-ns analytics out of the box.** Every task records
  hrtime spans relative to the run's t=0; `cache.db`'s `runs` table
  is queryable with `sqlite3` directly; `--profile` exports
  Chrome-trace JSON without any additional setup.
- **Persistent tasks with regex-readiness.** `readyWhen: 'Local:'`
  for a dev server is a one-liner; downstream tasks unblock on ready,
  not on exit. Turbo's `persistent` is more elaborate (separate
  `interruptible` / `with` flavors); vx's surface is smaller.
  `exec.interactive` is Turbo's `interactive`, outside its TUI: on a
  TTY the task gets the terminal and runs alone.
- **Explicit `cache + persistent` rejection.** The project loader
  throws — no silent surprise.

## Deliberate divergences from Turbo / Nx

These are places where Turbo or Nx pin a specific behavior in their
test suites and `vx` deliberately does something else. Listed here so
the choices don't drift accidentally — if any of these change, the
rationale below needs revisiting. Sourced from the full gap analysis
in [`design/turbo-nx-test-gaps.md`](../design/turbo-nx-test-gaps/).

### Hashing pipeline

- **Git blob OIDs for input files, like Turbo (v20).** Tracked clean
  files contribute their index OID (harvested from the same bulk
  `git ls-files -s` spawn that enumerates files — zero reads on a
  clean tree); dirty/untracked files fall back to an in-process
  blob-OID computation that is byte-identical for identical content.
  The KEY composition on top of those per-file OIDs is xxHash3
  (16-hex), not SHA — Turbo composes with xxh64; the widths match.
- **No `.gitattributes` CRLF normalization in the fallback.** Turbo's
  manual-hash fallback replicates git's CRLF conversion so it matches
  `git hash-object` under `text=auto` / `autocrlf`. vx's in-process
  fallback hashes raw bytes (`blob <len>\0` + content), and a file
  under a clean filter (`text`/`eol`/`ident`/`filter`/`autocrlf`) drops
  its index OID for that worktree hash, so the key follows the bytes
  the task reads (`dropFilteredOids`, `cache/git-inputs.ts`).
- **No `.gitattributes` binary detection.** Same root: raw bytes; no
  text-vs-binary distinction needed at hash time.

### Task graph

- **`forwardArgs` does NOT inherit into `dependsOn` deps.** Nx
  forwards args/options into dependents via `options: 'forward'`.
  vx scopes `forwardArgs` to user-requested nodes only — passing
  `vx run build -- --foo` does NOT pollute upstream tasks' cache keys.
  Explicit > magical (architecture principle #1).

### Filter DSL

- **Stacked `--filter name --filter [ref]` is UNION, not intersection.**
  Turbo's discussion #9096 argues for intersection ("only packages
  that are both affected AND match the name"). vx unions
  (tests/filter.test.ts > applyFilters > stacked: --filter ui
  --filter [main] unions name + affected sets). Mental model: each
  filter ADDS to the selection; never narrows another filter's set.
- **A bare name is an exact match; it never reaches into a scope.**
  Nx resolves `core` to `@acme/core`; vx's `--filter core` selects only
  a package named exactly `core`. Name the scope (`@acme/core`) or lead
  with `*` (`*core`) (tests/filter.test.ts > applyFilters > scoped
  names).

### Affected detection

- **Project removal does NOT invalidate every project's cache.** Nx
  invalidates everything when a project is removed. vx already folds
  each project's `package.json` bytes into every task's cache key
  (PR #42, CACHE_VERSION → v12), which catches "project gone" at
  finer granularity — only tasks that actually consumed the gone
  project's bytes are busted.
- **`git diff --no-renames` for affected.** vx flips rename
  detection OFF so cross-project `git mv` flags BOTH source and
  destination projects. Turbo's default rename-on would surface only
  the destination, silently missing the source's affected status.

### Cache storage

- **stderr is not cached; stdout is stored twice on purpose.** Turbo
  embeds the run's full logs inside the cache archive. vx's artifact
  is `stdout`, `outputs/`, `workspace-outputs/`, a `.vx-meta.json`
  mode/mtime sidecar and a `.vx-sum` checksum (only successful runs are cached
  and their stderr is near-always empty); stdout ALSO lives in the
  SQLite `entries` row so a local hit replays it with pure SQL —
  never decompressing the artifact.
- **Per-run SCM metadata, not per-entry.** Turbo writes the git sha +
  dirty-hash into each cache entry's metadata. vx records git
  commit/branch/dirty on the per-run `invocations` row instead, and
  the per-component `entry_inputs` rows answer "what inputs produced
  this artifact" at finer granularity.

### Remote cache

- **No remote wire in core.** Turbo ships its HTTP cache client
  (bearer token, refresh on 403, preflight, timeout) inside the
  binary; vx core ships the `cache` seam and nothing else. The wire,
  its auth and its deadlines belong to the plugin — `@vzn/vx-reapi`
  speaks Bazel's ActionCache + CAS over gRPC with a per-call deadline
  on every cache-path RPC, and a remote error always degrades to a
  MISS rather than failing the run.

### Glob walking

- **A symlink is a link, not its target.** Turbo distinguishes
  shallow-wildcard vs doublestar follow-link behavior explicitly. vx
  scans with `followSymlinks: false` and folds a link's target STRING,
  as git does (`cache/inputs.ts`); since Bun 1.4.0 a scan can still
  descend a linked directory, so an output path whose directory
  resolves outside the project is refused before any delete. The
  symlink-cycle test (`tests/inputs.test.ts`) pins that the resolver
  doesn't hang.
- **A bracket is literal; no character classes (item 667).** Turbo and
  Nx read `[id]` in a glob as a class, so `app/[id]/**` matches
  `app/i/…` and never the route directory. Bracket route directories are
  everywhere in JS monorepos (Next.js, SvelteKit, Astro), and a class
  there silently keys nothing — a stale hit — while an output clean
  deletes the class's namesakes. vx reads `[` and `]` literally in every
  task glob; the escaped `\[id\]` Turbo users write means the same path.
  Member globs and `--filter` path globs keep the package manager's
  grammar. Under `turbo()` and `nx()` a class in turbo.json or an Nx
  input is translated: `[jt]` and a range (`[a-c]`, `[0-9]`) become
  their members plus the literal route directory, a negated class `?`.

### Engine / scheduling

- **No executor batching.** Nx batches same-executor tasks into a
  single child process. vx's executor is a PLACEMENT seam — it decides
  where one command runs, never merges commands — so every task is its
  own process. Tradeoff: more spawn overhead; far simpler model.
- **No incremental watcher state.** Turbo's watcher maintains rich
  incremental change-accumulator + rediscover state. vx re-runs the
  orchestrator from scratch on each cycle. Cheap because of
  `gitFilesCache` + `Cache.hashFile` mtime+size fast path; complexity
  not yet justified.

### Config schema

- **No `$WORKSPACE_ROOT$` / `$TURBO_ROOT$` token substitution.**
  Turbo + Nx use template tokens in path strings; vx uses real paths
  from the project-dir context. The path resolution context is
  unambiguous because every glob is scoped per-project.

### Env handling

- **No `.env` auto-loading.** Nx auto-loads `.env` files. vx
  requires explicit `cache.inputs.env` declarations. "Explicit over
  magical" (architecture principle #1).
- **No wildcards in `cache.inputs.env`.** Turbo supports `VERCEL_*`
  expansion. vx rejects wildcards at load time so a typo doesn't
  silently contribute an empty value to the cache key (pinned by
  tests/project-loader.test.ts > rejects wildcards in
  cache.inputs.env).

### Concurrency model

- **Single-event-loop JS, no shared mutex.** Turbo uses
  `RwLock<TaskHashTracker>` and tests concurrent reads + read/write.
  vx is single-threaded JS by construction — no shared mutable state
  across "threads" to race over.

---

# Built for the agents that run your builds

> vx is AI-first. An agent asks what to run, runs it, and learns why it failed, all as typed JSON. People get the same answers as text.

More and more builds start from a coding agent, not a person at a
terminal. vx is designed for that: an agent can ask what to run, run
it, and learn why it failed without scraping terminal output. People
get the same answers, formatted for reading.

## Ask the build over MCP

[`@vzn/vx-mcp`](../../plugins/vx-mcp/) adds `vx mcp`, an MCP server that
Claude Code, Cursor, Continue.dev, GitHub Copilot or any MCP client can
call. Its tools:

| Question                                      | Tool                                         |
| --------------------------------------------- | -------------------------------------------- |
| What can I run here?                          | `listTasks`                                  |
| What would run, and why?                      | `planTasks`                                  |
| Run these tasks and tell me how it went.      | `runTasks`                                   |
| Why did the run fail, at which file and line? | `getFailures`                                |
| What did a task print?                        | `getTaskLog`                                 |
| Why did this task run again?                  | `whyDidThisRerun`                            |
| What does a task declare?                     | `getConfig`                                  |
| What is this workspace?                       | `getWorkspaceInfo`                           |
| How is the cache doing?                       | `getCacheStats`, `explainCacheKey`           |
| What ran, how fast, what flaked?              | `getRunHistory`                              |
| Is the lock current? What would `vx init` do? | `checkLock`, `planInit`                      |
| Free cache space.                             | `pruneCache` (a dry run unless told not to)  |

Every tool but `runTasks` only reads. `runTasks` runs through the CLI
itself, so it writes only what `vx run` writes. You decide how far it
goes:

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { mcp } from '@vzn/vx-mcp'

export default defineWorkspace({
  // false: the agent runs nothing. A list: only these task names.
  plugins: [mcp({ run: ['test', 'lint'] })],
})
```

```sh
claude mcp add vx -- vx mcp
```

## JSON with a contract

`vx show`, `vx info`, `vx why`, `vx last` and `vx cache prune` take
`--format json`. Each prints one document whose shape is a JSON Schema
shipped in the package, and every object closes its key set, so a new
field is a schema change, never a surprise. `vx run --format json`
prints the run's result; `vx run --dry=json` prints the plan before
anything runs. See [Machine-readable output](../../cli/#machine-readable-output).

## Errors you can branch on

Asked for JSON, a refusal is one line on stdout with a stable code,
such as `VX_E_UNKNOWN_TASK` or `VX_E_CYCLE`. The code stays; the
message may change. See [Error codes](../../cli/#error-codes).

## Clean streams

A verb whose output is a product writes only that product to stdout.
Notices and warnings go to stderr, so `vx info --format json` pipes
straight into a parser.

## Answers, not guesses

`vx why app#test` walks the cause chain: which input changed, in which
upstream task. An agent fixes the cause instead of re-running to find
it. A mistyped flag gets the right one back: `--concurency` hints
`--concurrency`, and `--json` hints `--format json`.

## Docs an agent can read

[llms.txt](https://vznjs.github.io/vx/llms.txt) indexes every page as
markdown, and `vx docs <query>` searches the reference that ships
inside vx, offline.

## Still built for people

The same facts print as plain text. Run `vx run build --all`, and when
something re-runs, `vx why` tells you why. Setup steps for each agent
are in the [AI agents guide](../../guides/agents/).

---

# Why vx is fast

> The engineering behind vx's speed and its correctness guarantees — git-OID hashing, bitset scheduling, strict output ownership, and a daemonless design — with measured numbers.

vx's speed isn't a microbenchmark trick; it comes from a handful of
structural decisions. This page explains them. The exhaustive,
source-cited catalog lives in [Optimizations](../../optimizations/) and
the raw numbers in [Benchmarks](../../benchmarks/).

## The numbers

These are reproducible on your own machine, not marketing figures:

- **The total cold build**, the number to read first. On the
  synthetic 1,090-package, 3,270-task workspace (tasks of equal duration,
  deep dependency chains) vx finishes in 3m 40s, Nx in 3m 49s (vx 4%
  faster), Vite Task in 4m 49s (vx 31% faster) and Turborepo in
  4m 59s (vx 36% faster). Secondary: the time each runner adds over
  the tasks' ideal schedule of 3m 38s, per package (2 ms for vx, 10 ms per
  package for Nx and 74 ms for Turborepo), is how each grows with the codebase.
  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.

- **vx alone** — `bun packages/vx-bench/run.ts [projects]` measures vx across
  fresh / warm-no-restore / warm-restore, from a `vx lock` snapshot
  (`--frozen`), as every vx bench runs it. A 100-project workspace
  replayed fully-cached in **74 ms** whole-process (1,000 projects in
  172 ms) on one macOS arm64 machine (2026-09-02); a 4-core Linux
  container reads 271 ms at 1,000 projects. Its restore row deletes the outputs first and extracts
  every artifact, so it costs more than the untouched tree; the
  current floors are in [Benchmarks](../../benchmarks/).
- **Head-to-head vs Turborepo and Nx** — `bun packages/vx-bench/compare.ts` scaffolds
  one repo (1,090 packages, 100 dependency layers, a `build`,
  `installDeps` and `test` task each: 3,270 tasks) and runs all three runners across the same three cache states.
  vx leads on the warm paths; the committed results live in
  [Benchmarks](../../benchmarks/). Run it yourself — every number here is
  a command away.

## What others don't have

These are correctness *and* speed wins — they make the cache both safer
and faster:

1. **Sparse `^task` bridging.** `^build` walks *through* dependency
   packages that don't declare the task to the nearest one that does, so
   sparse task coverage doesn't need no-op filler tasks, and the graph
   carries no placeholder nodes for the packages walked through.
2. **Resolved-config hashing.** vx hashes the evaluated `vx.config.ts`
   object, so imports, presets, and computed values participate in the
   key. Static-JSON config can't see them.
3. **Strict output ownership.** Declared outputs are wiped before exec
   *and* restore, so the tree ends as the cached snapshot, with no stale
   files. Two tasks whose outputs overlap are refused by default
   (`rules.exclusiveOutputs`); with that rule off, a task that adds files
   to an upstream task's outputs cleans nothing before exec and only the
   files it recorded before a restore. Turborepo/Nx
   restore additively.
4. **Daemonless.** No background process, no staleness window, no socket
   to corrupt — and the fastest warm/cached runs in the head-to-head
   benchmark all the same.

## The mechanics under the hood

- **Hashes come straight from git's index.** One `git ls-files -s` spawn
  yields the tracked file list *and* every clean file's blob OID; a
  concurrent `git status` prunes anything that diverges and lists untracked
  files. Clean-tree key derivation
  costs zero source-file reads, zero stats, zero database lookups. Dirty files get the
  identical blob OID computed in-process, so a key never flips across a
  commit boundary — a class of spurious miss the others accept.
- **Bitset graph algorithms.** Scheduler priority and the package graph
  use packed-bitset closures with popcount instead of set-union DFS. On a
  3,270-task graph this turned an 8.5 s priority computation into
  single-digit milliseconds.
- **A scheduler tick that re-scans nothing.** Ready tasks come off an
  exact most-blocked-first binary heap; a completion decrements its
  direct dependents' counters and pushes the ones that reach zero, so
  the run costs one pass over the edges plus an `O(log N)` heap
  operation per task, never a re-scan of the graph per completion.
- **Stat-check restore skips.** A warm-on-warm restore is N stats with
  zero writes and zero decompression — fingerprints in SQLite tell vx the
  tree is already current.
- **One artifact format end to end.** Local and remote move the same
  `tar.zst` bytes — metadata rides SQLite locally and the remote's own
  record on the wire, so nothing is repacked at the boundary.
- **In-process tar**, atomic publish, single-transaction SQL, and
  collision-hardened xxh3 key derivation round it out.

## Things vx deliberately *didn't* build

Speed by subtraction is still speed:

- **No daemon / project-graph process** — the cold numbers say it isn't
  needed.
- **A config-eval cache only where it is provably sound** — configs
  are programs, so the cache is gated, not heuristic: a config that
  reads the environment, the clock, or anything non-deterministic is
  refused the cache outright (denied identifiers, including escaped and
  aliased spellings), and one that passes is keyed by the git blob ids
  of its whole import closure. The `load configs` stage is 16–25 ms per
  1,000 configs served from it, against ~200 ms of evaluations; a
  refused config simply evaluates live.
- **No filesystem-tracing auto-inputs.** Not a gap — a position. A
  traced input set describes what the task read *that time*, on that
  machine, which is not the same as what it depends on; and it cannot be
  known before the task runs, which is exactly when the key is needed.
  vx asks you to declare inputs and gives you a boundary to check them
  against: inside the workspace, a task with `sandbox` reads only what
  `allow.read` grants, plus `node_modules` and the linked packages it
  depends on. Reads outside the workspace stay open, except the
  credential stores under home (`~/.ssh`, `~/.aws`, …), and `cache.inputs`
  grants nothing, so the sandbox checks the input list only where
  `allow.read` mirrors it. Guessing is replaced by a boundary.

## Go deeper

- **[Optimizations](../../optimizations/)** — every decision with its
  invariant and source.
- **[Benchmarks](../../benchmarks/)** — methodology and full results.
- **[vx vs Turborepo vs Nx](../../comparison/)** — feature-by-feature.

---

# Task execution lifecycle

> This document traces what happens between vx run build typed at the

This document traces what happens between `vx run build` typed at the
terminal and a task succeeding or failing. Read it alongside
[`architecture.md`](../architecture/) (module map) and
[`caching.md`](../caching/) (cache mechanics).

## End-to-end timeline

```
 ┌─ CLI dispatch (src/bin.ts → src/cli/index.ts → src/cli/run.ts)
 │    1. bin.ts spawns; forwards process.argv to cli.run().
 │    2. cli/index.ts dispatches by subcommand (run / watch / cache /
 │       lock / init / upgrade / show / info / why / last / docs /
 │       completions / help / version); any other verb is asked of the
 │       workspace's plugins (`commands` seam — `vx mcp` is one).
 │    3. cli/run.ts:parseRunArgs(argv) → RunArgs (validated; resolves
 │       the 4-axis cache policy from --cache / --no-cache / --force).
 │    4. cli/run.ts:runCmd resolves the project scope:
 │         - bare positionals respect --all / --filter / --affected / cwd
 │         - anchored positionals (pkg#task) target directly
 │         - no positionals + TTY → interactive picker → pkg#task
 │    5. The options map to RunOptions and the run executes IN THIS
 │       PROCESS — always. (A whole-run `backend` seam existed until
 │       2026-08; it moved the scheduler server-side, which is why it
 │       went. Per-task placement is the `executor` capability.)
 │       --dry / --graph short-circuit into planRun instead.
 │
 ├─ Prepare (src/orchestrator/prepare.ts:prepareRun — shared with planRun)
 │    1. findWorkspaceRoot(cwd) — walks up over pnpm-workspace.yaml,
 │       package.json with a `workspaces` field (npm/yarn/bun), or a
 │       bare package.json (single-project mode). The nearest one whose
 │       package globs CLAIM cwd wins, so running from inside a member
 │       resolves the declaring root, not the member; the first
 │       directory holding pnpm-workspace.yaml stops the walk whether
 │       or not its globs claim cwd (pnpm's rule); when nothing claims
 │       cwd the nearest candidate wins. An UNSCOPED run (no explicit
 │       project scope, at least one bare task name) then starts
 │       step 12's git enumeration over the whole tree, overlapping
 │       steps 2–11; a scoped run waits, since its pathspecs depend on
 │       which projects the task graph holds.
 │    2. loadWorkspace — parses the appropriate manifest. Bun.YAML
 │       for pnpm; the package.json forms read as bytes (readOnce,
 │       shared with step 1) and JSON.parse.
 │    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),
 │       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
 │       names (hard error with both paths).
 │    5. buildPackageGraph — workspace dep edges from package.json.
 │    6. Local cache open: new Cache(cacheDir, { read, write }, root)
 │       with the policy's local slice — BEFORE the configs load,
 │       because it also holds their cached evaluations. Then
 │       computeWorkspaceFingerprints: one read of every supported
 │       lockfile + pnpm-workspace.yaml + .yarnrc.yml + .npmrc + bunfig.toml at the root
 │       yields `all` (every file; keys the config-evaluation cache),
 │       `unclaimed` (minus the files a `fingerprint` plugin claims —
 │       `@vzn/vx-lockfile` keys those per project; reused for every
 │       task's cache key) and `files` (the bytes, for the mid-run
 │       fingerprint check).
 │    7. SCOPED config loading — only in-scope projects plus their
 │       transitive dependency closure evaluate ('^task' frontier
 │       expansion never escapes the closure); one staged load,
 │       loadProjects, shared with every reading verb. Under --frozen,
 │       configs load from vx-lock.json — no evaluation, no staleness
 │       check of its own (vx lock --check is the audit), frozen-env
 │       semantics; a missing lock or entry is a hard UserError.
 │       Otherwise loadProjectConfigs in one batch: native Bun await
 │       import() with a content-hash query-string bust, cached
 │       evaluations served for pure configs; the loader validates
 │       each TaskConfig shape, and the plugin `project` stage runs
 │       on each config with a re-validation after every plugin.
 │    8. computeNestedProjectDirs — set of projects rooted inside each
 │       project, computed over EVERY config-bearing project (loaded
 │       or not) for boundary enforcement.
 │    9. expandRequested (see Task selection below).
 │   10. Cache layer: an injected RunOptions.remoteCache is composed
 │       with the local cache into a LayeredCache (it wins); else
 │       resolveCache lets a plugin's `cache` capability wrap or
 │       replace it; else bare local.
 │   11. buildTaskGraph (see below).
 │   12. Bulk git populate — the enumeration step 1 started is
 │       awaited, or a scoped run starts it here over the projects
 │       that own a task (not the dependency closure step 7 loaded,
 │       which a `lint` of one package does not key). THREE spawns at
 │       the root, concurrent, and the repository's facts asked while
 │       they run (`ls-files -s -v -z` for the index: every tracked
 │       path's OID and its cache-state flag;
 │       `status --porcelain -z -uall` for
 │       the dirty AND untracked sets, the one worktree walk; `var -l`
 │       for core.autocrlf and the attributes files git reads outside
 │       the tree; the facts — prefix, common dir, object format, index
 │       file — read off a plain `.git` directory, else one
 │       `rev-parse --show-prefix --git-common-dir --show-object-format
 │       --git-path index`,
 │       memoized per process and shared with the file hasher)
 │       fill the per-project GitFilesCache with file lists + index
 │       OIDs. `ls-files --others` is NOT among them — status's
 │       `-uall` already answers untracked, and asking git twice
 │       walked the same tree again. A fifth, `check-attr`, runs only
 │       when an attributes file could rewrite bytes. An index the
 │       cache holds no blob-size verdict for (keyed by the index
 │       file's hash, A-60) adds `ls-files --debug` for the recorded
 │       sizes and `cat-file --batch-check` for the blob sizes
 │       `blob_sizes` lacks: an OID whose blob is not the recorded size
 │       is not trusted. The run's HashCache is created
 │       after it.
 ├─ Task selection (graph/task-graph.ts:expandRequested)
 │    Bare task names fan out across the resolved candidate projects
 │    (every project that declares the task). Anchored entries
 │    (`pkg#task`) resolve directly. Duplicates are deduped.
 │    Empty result → run returns `{ ok: false, outcomes: [] }` —
 │    no task is treated as a CI footgun. The exception: a diff-scoped
 │    run (--affected) whose task names are all declared by projects
 │    outside the selection is `none-affected` and returns
 │    `{ ok: true, outcomes: [] }`.
 │
 ├─ Task graph (src/graph/task-graph.ts:buildTaskGraph)
 │    Starting from the resolved {project, task}[] pairs, walk
 │    dependsOn:
 │      - 'name'     → same-project task
 │      - '^name'    → task in the nearest deps declaring it
 │                     (frontier walk; non-holders passed through)
 │      - 'pkg#name' → specific package's task
 │    Detect cycles — throws with the path. After the graph and key
 │    stages, excluded edges (per --exclude-dependencies[=names]) leave
 │    the SCHEDULE; each dropped task is still keyed and folded into
 │    its dependant (orchestrator/excluded-keys.ts).
 │    Each node carries: id (`${project}#${task}`), projectName,
 │    projectDir, taskName, config, sorted deps, `requested: boolean`.
 │    markSurfacedDeps then flags the display-only `surfaced` tasks a
 │    requested GROUP stands for (transparent folders).
 │
 ├─ Plugins + telemetry (src/orchestrator/run.ts)
 │      1. installPlugins — always called; each plugin's optional
 │         setup() hook runs; a throw aborts the run with a clean
 │         UserError naming it. With no plugins it runs nothing.
 │      2. Run context capture — always, for the `invocations` row:
 │         commit + branch read from `.git` directly, `git rev-parse`
 │         only when that reader does not understand the layout; dirty
 │         reuses the GitFilesCache's status; CI-env detection,
 │         host/os/arch. Never fails a run.
 │      3. Telemetry — only when a plugin has a `telemetry` hook or
 │         RunOptions.telemetrySinks is passed: the run-context record
 │         (adding captureWorkspaceIdentity) is built and
 │         subscribeTelemetry collects the sinks; with ZERO sinks it
 │         returns undefined and NOTHING subscribes (the no-telemetry
 │         hot path is byte-identical).
 │
 ├─ Run-level state
 │    • runId   — UUIDv7 stamped once per `vx run` invocation; every
 │                task in the resulting graph carries it.
 │    • runStartHrTimeNs — hrtime.bigint() anchor; per-task wallclock
 │                spans are stored relative to it.
 │    • persistentRegistry — Map<taskId, Subprocess> of long-running
 │                children.
 │    • liveChildren — Set<Subprocess> of in-flight children; the
 │                runner adds/removes each around its spawn.
 │    • SIGINT/SIGTERM/SIGHUP handlers (removed in a finally): on
 │                signal, forward it (SIGHUP as SIGTERM) to everything
 │                in liveChildren + persistentRegistry (and kill any
 │                running cache.inputs.runtime probe, C-65), wait
 │                VX_KILL_GRACE_MS (2 s) for their groups, SIGKILL
 │                what is still there, let the run finish its own
 │                end (flush, teardown, cache close), then
 │                die of the signal (SIGINT → 130, SIGTERM → 143,
 │                SIGHUP → 129), so a shell script running vx stops
 │                too; a run that handed a task the terminal exits
 │                with that code instead, so Bun restores it. SIGHUP is registered because a task
 │                runs in its own session, so a closing terminal
 │                reaches vx and nothing else. A second signal
 │                SIGKILLs and exits at once.
 │
 ├─ Cache acceleration (before scheduling)
 │    • REMOTE PREFETCH (a cache layer with a remote only) — derive every
 │      stable-key cacheable task's key up front (reusing the run's
 │      hashCache memo) and fire the remote GETs in the background
 │      under a bounded pool. Not awaited before scheduling (the
 │      overlap is the point); drained before cache.close(). At most
 │      one remote GET per key (shared in-flight map with the lazy
 │      read-through).
 │    • LOCAL SHORT-CIRCUIT (no remote layer, local reads on, ≥1
 │      task) — derive the same stable keys and probe them in ONE
 │      batched cache.getMany (a layer without getMany: cache.get once
 │      per task under a bounded pool) → a `preProbed` map (hits AND
 │      stable misses; execute reuses these probes) + a `restoreTier`
 │      set (confirmed hits). Awaited before scheduling; never throws
 │      (degrades to the normal schedule).
 │
 ├─ Scheduling (src/graph/scheduler.ts:runGraph — two-tier)
 │    Two ready queues, each on its own lane:
 │      - EXEC tier — dep-gated; ready when every dep completed; up
 │        to N (concurrency) at once.
 │        Priority: transitive-reverse-dependent count (bitset
 │        closure), optionally overridden by a `priorities` map.
 │      - RESTORE tier — confirmed stable local hits; ready
 │        IMMEDIATELY (no dep gate, no failed-dep→skip check — their
 │        key is dep-independent) at LOW priority, on a restore lane
 │        of 2×N. The drain rule: exec-tier first; a restore never
 │        takes an exec slot and the two lanes never wait on each
 │        other — except at N = 1, where they share the one slot.
 │    On failure: exec-tier dependents are marked `skipped` (exit 1,
 │    durationMs 0, no spawn); independent siblings keep running.
 │    The scheduler doesn't know about caching; the execute callback
 │    is the seam. (An embedder running concurrent runs in one process
 │    may pass a shared `inflight` map; admission.ts then dedupes
 │    identical-key tasks across them. A plain `vx run` passes none.)
 │
 ├─ Per-task execution (src/orchestrator/execute-task.ts:executeTask)
 │    Each task takes one of three paths:
 │
 │    A. GROUP — no `exec`.
 │       Return success with a derived hash rolled up from upstream
 │       outcomes. No spawn, no I/O. Wallclock = 0.
 │
 │    B. PERSISTENT — `exec.persistent` set.
 │       1. Build isolated env (essentials + passThrough + define +
 │          <projectDir>/node_modules/.bin, then
 │          <workspaceRoot>/node_modules/.bin, prepended to PATH).
 │       2. runPersistent — Bun.spawn the command; subscribe to
 │          stdout/stderr chunk-by-chunk.
 │       3. Resolve `ready` when:
 │            - no readyWhen → immediately on spawn
 │            - readyWhen matches the output (complete lines OR the
 │              trailing partial line) → on that match
 │            - child exits before the match → reject with
 │              PersistentReadyError('persistent task exited before
 │              becoming ready (exit N)'); its output already streamed
 │              through the logger
 │            - readyWhen set and the timeout (exec.timeout, else the
 │              run default) elapses first → fail, SIGTERM, SIGKILL
 │              after the grace
 │       4. On ready: stash child in persistentRegistry; return
 │          success. Downstream tasks unblock.
 │       Note: cache + persistent is a config error (rejected by the
 │       project loader). Persistent tasks never write to cache.
 │
 │    C. NORMAL — `exec.command` only.
 │       1. resolveInputs(files, env, runtime)
 │            - glob inputs.files (git-backed, declared-outputs-
 │              excluded, nested-projects-excluded)
 │            - glob inputs.workspaceFiles from the WORKSPACE ROOT
 │              (git-aware, NO boundary rule — the documented escape
 │              hatch); resolved paths join the same input list
 │            - read host process.env values for inputs.env names
 │            - resolve inputs.runtime / workspaceRuntime command
 │              output (deduped per run; a non-zero exit throws a
 │              UserError that fails this task — its dependents skip,
 │              independent tasks continue)
 │       2. hashTaskConfig + project package.json hash (both memoized
 │          per run via HashCache)
 │       3. filterUpstreamHashes (apply cache.inputs.tasks filter)
 │       4. cache.key({ taskId, workspaceFingerprint,
 │                      projectPackageJsonHash, taskConfigHash,
 │                      forwardArgs, envValues, runtimeValues,
 │                      workspaceRuntimeValues, upstreamHashes,
 │                      pluginParts, inputFiles }) → 16-hex xxh3
 │          (pluginParts is whatever the `key` stage contributed,
 │          folded between the upstream keys and the input files —
 │          see caching.md § Cache key derivation for the order.)
 │          (Skipped when the local short-circuit pre-derived it.)
 │       5. If willRead (cache block + a read axis on):
 │            consume the up-front probe when present, else
 │            cache.get(hash)
 │              · hit → up-to-date short-circuit when the on-disk tree
 │                       already matches; else cleanOutputs →
 │                       restoreOutputs → replay stored stdout →
 │                       return cache-hit / cache-hit-remote
 │              · miss → fall through; cleanOutputs first (when
 │                       willWrite) so a stale prior build can't
 │                       survive the fresh exec
 │       6. Build isolated env. For a cacheable task,
 │          describeTaskInputs({ captureInto }) then describes the input
 │          set ONCE, before the spawn: the executor gets the input
 │          values and the save reuses the captured per-component input
 │          fingerprint (a re-fold over the memos, no I/O).
 │       7. runCommand (or runSandboxed when `sandbox` is declared) →
 │          Bun.spawn shell with `command` + forwardArgs
 │          (shell-quoted). Buffer chunks via onStdout/onStderr.
 │          exec.timeout SIGTERMs an overrun → real `failed`, never
 │          cached. An attempt that ends while the run is STOPPING
 │          (Ctrl-C teardown) classifies as `aborted` instead, whatever
 │          its exit — not counted, not recorded, not retried.
 │       8. On exit 0 + willSave (willWrite, no tainted upstream):
 │            keyStillTrue() — if the workspace fingerprint or an
 │              input moved since the key was taken, the result stands
 │              but the save is withheld (said on the status line).
 │            saveMiss — in the slot: resolveOutputs(outputs) +
 │              resolveWorkspaceOutputs → file lists, and the
 │              project's git snapshot notes the written output paths
 │              so a same-project downstream task doesn't re-spawn git
 │              unless its globs overlap. Deferred onto the run's save
 │              lane (2×concurrency wide): cache.save(...) — pack
 │              <hash>.tar.zst with stdout + outputs/<rel>
 │              (+ workspace-outputs/<rel-to-root>), upsert entries +
 │              output_files + entry_inputs rows in one transaction.
 │              The slot frees at once; dependents wait on the save's
 │              `landed` promise (the scheduler's settledOf). Under a
 │              LayeredCache with remote writes on, the remote upload
 │              fires in the BACKGROUND (drained at end of run).
 │       9. Return TaskOutcome { node, status, exitCode, durationMs,
 │            hash, cpuMs?, peakRssBytes?, restored?,
 │            wallclockStartNs, wallclockEndNs }.
 │
 └─ End-of-run
    1. SIGTERM dependency-only persistent children; persistent tasks
       the user REQUESTED, those a requested group stands for (through
       nested groups, not through a one-shot), and the persistent tasks
       they depend on, are kept alive (see below).
    2. Run summary footer (projects / tasks / cache meters + info +
       time + result) — counts only real tasks (with `exec`); group tasks
       don't pollute the totals; failure frames replay just above it.
    3. Optional --summarize JSON (default <cacheDir>/runs/<run_id>.json)
       and --profile Chrome-trace JSON (default profile.json).
    4. recordRunBundle — one transaction writing a `runs` row per real
       task plus the `invocations` header row (command, git/CI/host
       context, tags, counts). Group + aborted tasks skipped; a run
       a signal stopped records nothing.
    5. Telemetry: emit the RunSummaryRecord to every active sink +
       await their flush (crash-isolated; skipped when no sink).
    6. Drain background remote prefetches/uploads; cache.close();
       sandbox teardown when any task was sandboxed.
    7. Return { ok, outcomes }; ok = every task ended success or a
       cache hit (any failed/skipped/aborted → ok = false → exit 1),
       and no persistent child exited on its own before the run
       stopped it.
    8. FOREGROUND ONLY: if the user requested persistent tasks (dev
       servers) and nothing else failed (or under `--continue=always`),
       the process now blocks until ONE of them, or a persistent task they
       depend on, exits — the
       summary is already printed, `▸ <id> running` rows list what's
       alive, Ctrl-C reaps the process group. That first exit ends the
       session: the others are torn down (SIGTERM, grace, SIGKILL) and
       a non-zero exit makes the run exit 1, so a script's `vx run dev`
       fails when the server it started fell over. That server then reads
       `failed` with its own exit in the rewritten `--summarize` and in the
       report `--report-file` writes; one a Ctrl-C stopped does not. The
       stdout `--report` prints above the footer, so it reads as the
       footer does, before the wait. Under
       `holdPersistent` (the watch loop) run() instead returns them on
       `RunSummary.persistent`, still running, for the caller to stop;
       one that dies on its own after that is said, its `stop()` is not.
```

## One command per task

`exec.command` is a single shell command — there's no multi-step
sequence. Three ways to chain:

- **Shell composition** — `&&`, `;`, pipes. The shell is the API.
  ```ts
  exec: {
    command: 'gen && tsc && cp -r assets dist/'
  }
  ```
- **Separate tasks** linked by `dependsOn`:
  ```ts
  codegen: { exec: { command: 'gen' }, ... },
  build:   { exec: { command: 'tsc' }, dependsOn: ['codegen'], ... },
  ```
- **Group task** that fans out:
  ```ts
  release: {
    dependsOn: ['build', 'test', 'package']
  }
  ```

Per-task caching is the right granularity for invalidation. Splitting
gives you per-step caching naturally; combining with `&&` gives you
one cache slot for the whole chain.

A task is over when its command's own process exits. What a descendant
writes after that — one the command detached with `setsid … &`, or
daemonized — is not the task's output: the save has already run, and a
later hit's restore removes it ([caching](../caching/#cache-write)).
`wait` for what the command backgrounds.

## Env isolation

The child process gets, in priority order (lowest first):

1. **Essential allowlist** (`PATH`, `HOME`, `SHELL`, `USER`, `LOGNAME`,
   `TMPDIR`, `TEMP`, `TMP`, `LANG`, `LC_ALL`, `LC_CTYPE`, `TERM`,
   `COLORTERM`, `FORCE_COLOR`, `NO_COLOR`, `CI`, `NODE_OPTIONS`,
   `COREPACK_HOME`, `PNPM_HOME` — the list is
   `ESSENTIAL_ENV` in `src/exec/env.ts`).
2. **`exec.env.passThrough`** names → values from host `process.env`.
3. **`exec.env.define`** literal name/value pairs.
4. **PATH augmentation** — `<projectDir>/node_modules/.bin`, then
   `<workspaceRoot>/node_modules/.bin`, are prepended so installed
   tools (`oxlint`, `vite`, etc.) work without `npx`. Never a sibling
   project's bin; those stay invisible. A bin directory whose path holds
   PATH's delimiter (`:`) is left out: PATH cannot name it, and split it
   became two entries, one relative to the task's cwd. A task whose shell exits 127 or 126 gets one more frame line
   (`orchestrator/shell-verdict.ts`): for a bare word, that 127 is the
   shell's "command not found", the word (when the command is a plain
   `word args…`), the two bin directories vx puts first, and that a
   sibling project's bin is never visible (or, when a bin directory was
   left out for its `:`, that directory and the fix: move the
   workspace), and on 126 `chmod +x`; for
   a word with a slash, what the file says — missing (the resolved
   path), a directory, not executable by this user, a `#!` interpreter that does
   not exist (a CRLF line ending is named as such), or no `#!` line.
   An exit above 128 gets the same line for its signal: which one, and
   what sends it (the OOM killer, a crash in native code, an abort, a
   reader that left a pipe, a ulimit, a seccomp refusal); vx's own
   timeout and a shutdown's SIGTERM keep their own lines, and a task the
   run's stop killed (the SIGKILL past the grace too) gets none.

Anything not in these four layers is invisible to the child, except
the two vx sets itself — `VX_RUN_WORKSPACE` and `VX_RUN_TASK` — so a
task that shells out to `vx run` in its own workspace is refused
before it forks without bound, and `npm_execpath`, the workspace's
package manager (unkeyed; `schema.md` § `env`). A sandboxed task also gets the sandbox's own
proxy, CA and `TMPDIR` values
([`modules/sandbox-runtime.md`](../modules/sandbox-runtime/#the-environment-srt-sets)). This prevents incidental env leakage
between machines and gives reproducible runs.

The allowlist + isolation contract lives in
[`modules/env.md`](../modules/env/) and is the only field the
contract assumes for "what every command needs to function" on
Linux and macOS (Windows is WSL, which is Linux). Adding to the allowlist would be a deliberate
schema-extending change (consumer code expects a particular set;
broader access has cache-stability implications).

## Failure handling

| Failure                                                                                                                                                          | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Exec exits non-zero                                                                                                                                              | Task is `failed`; cache NOT written; output streamed live + the failure frame replays at run end                                                                                                                                                                                                                                                                                                                                                          |
| `exec.timeout` overrun                                                                                                                                           | SIGTERM to the task's group, SIGKILL for whoever is left after the grace; task is `failed` (timed out), exit 143 (137 when the SIGKILL took it, and the line says so), never cached                                                                                                                                                                                                                                                                       |
| Child killed by Ctrl-C teardown (SIGINT/SIGTERM/SIGHUP), or by an embedder's `RunOptions.signal` abort — which also completes every never-started task `aborted` | Task is `aborted` — not counted, not recorded. An attempt that ends while the run is stopping is `aborted` whatever its exit: a trap that exits 0 is not cached, and a failure is not retried (item 962). What it printed still shows in its frame. A child killed by a signal while the run is NOT stopping (a supervisor's SIGTERM, a `kill` from another shell) is `failed (exit 143, 128 + SIGTERM)`: retried, shown, and fail-fast trips (item 1100) |
| `execute()` throws (internal error)                                                                                                                              | Task marked `failed`; stderr written `[vx] internal error in <id>` (a `UserError` reports plainly); a plugin executor's throw reports plainly as `plugin '<p>' (executor '<e>') failed in execute: <reason>` (C-63, C-85)                                                                                                                                                                                                                                 |
| Persistent task exits before ready                                                                                                                               | Task marked `failed` with `exited before becoming ready (exit N)`; its output already streamed live; `aborted` when the run's stop killed it (C-62)                                                                                                                                                                                                                                                                                                       |
| Upstream task fails                                                                                                                                              | Under the default `--continue=deps-ok`, dependents marked `skipped` (exit 1, durationMs 0); no command runs — EXCEPT a restore-tier task, whose confirmed cache hit still restores (its key is dep-independent). `--continue=never` stops dispatch; `--continue=always` runs dependents, never saved                                                                                                                                                      |
| Sandbox violation (macOS monitor / Linux structural)                                                                                                             | Task is `failed`; violations render in the frame; nothing cached                                                                                                                                                                                                                                                                                                                                                                                          |
| Remote-cache error (500, timeout, corrupt artifact)                                                                                                              | Degrades to a cache miss; never fails the run                                                                                                                                                                                                                                                                                                                                                                                                             |
| No pnpm-workspace.yaml or package.json in cwd or any parent                                                                                                      | `findWorkspaceRoot` throws (UserError); `vx run` exits 1                                                                                                                                                                                                                                                                                                                                                                                                  |
| Same-project task referenced in `dependsOn` not declared                                                                                                         | `buildTaskGraph` throws with the offending edge                                                                                                                                                                                                                                                                                                                                                                                                           |
| Duplicate workspace package name                                                                                                                                 | `listProjects` throws with both paths                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Cycle in task graph                                                                                                                                              | `detectCycle` throws with the cycle path                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Malformed config                                                                                                                                                 | `loadProjectConfigs` throws (UserError) with file + field                                                                                                                                                                                                                                                                                                                                                                                                 |
| `cache.inputs.runtime` command exits non-zero                                                                                                                    | UserError naming the command + exit code; that task is `failed`, dependents skip                                                                                                                                                                                                                                                                                                                                                                          |

By default (`--continue=deps-ok`) failures don't kill the scheduler —
independent tasks already in flight finish, and unrelated tasks not yet
started still run. `--continue=never` stops dispatch at the first
failure; `--continue=always` runs dependents too
([`cli.md` § Failure propagation](../cli/#failure-propagation----continue)). The
overall exit code is 1 if any task ended in `failed`, `skipped` or
`aborted` status, or a persistent child exited before the run stopped
it.

## Output capture and rendering

The orchestrator emits `RunEvent`s through an in-process bus; the
terminal renderer is the always-on subscriber (plugins, telemetry, and
wire forwarders attach beside it). What renders:

- **Flow-aware policy.** What gets rendered depends on the run's
  intent: FOCUSED (no selection flag) streams the requested task's
  output raw and live and silences successful dependencies; BROAD
  (`--all` / `--filter` / `--affected`) prints news only — one grid
  one-liner per executed task, failure frames replayed at run end,
  silence for cache hits; truthy `CI` env (and the programmatic
  default) keeps full grouped output. `--output-logs` overrides
  everything. Full table in [`cli.md`](../cli/#output).
- **The glyph grid.** Reported task lines share one column grid —
  `<glyph> <time> <status> <cache> <name>`. Glyph SHAPE = cache axis
  (`⏺` miss / `►` fresh / `⇢` local / `⇣` remote / `◼` failed / `⊘`
  skipped, plus `▸` for a pinned persistent row; a live worker row has
  no glyph — its ticking elapsed time leads instead); glyph COLOR + the
  status word = task axis
  (success / failed / skipped / running); the cache word (miss /
  fresh / local / remote) spells it out.
- **Buffered, framed (non-focused paths).** `runCommand` listens to
  the child's stdout/stderr and calls `onStdout` / `onStderr` per
  chunk. Outside focused streaming, the default logger buffers the
  chunks per-task and dumps the full body as a framed block on task
  completion. No per-line prefix, no interleaving between concurrent
  tasks.
- **Cache write.** The captured stdout — its first and last 8 MiB,
  the cut middle named — is stored in the entry; replay is stdout-only.
- **Cache hit replay.** The stored stdout is fed through the same
  logger path, so it renders per the active flow (streamed raw for a
  focused requested task, framed in full mode, silent in broad).
- **Live stream for failures.** Even though cached output is not
  written for failures, the live stream means the user sees the
  failure as it happens; the full frames replay together at run end,
  right above the summary.
- **Status region.** On TTY stdout outside CI, a multi-row region
  tracks the run live: a blank separator, pinned `▸` persistent rows,
  one row per worker slot (the ticking elapsed time IS the motion —
  no spinner), and the live summary section (the same meters as the
  final footer). Redrawn in place; forced redraws coalesce under a
  30 ms floor; erased before the summary prints. All default-logger
  writes serialize through one writer so content and the region never
  interleave.
- **GitHub Actions.** With `GITHUB_ACTIONS` truthy in full mode, task
  blocks collapse under `::group::` commands; failures stay open and
  emit `::error` annotations.

A task's stdout and stderr are pipes, so `echo x > /dev/stdout` and
`cmd | tee /dev/stderr` work as in a terminal or under Turbo. Bun's own
`'pipe'` is a socketpair, which Linux will not open by path, and they
failed with "No such device or address" until X-113
(`tests/runner.test.ts` › "a task's stdout and stderr are pipes it can
open by path"; sandboxed in `tests/sandbox-runtime.unsafe.test.ts`).

There is no special handling for binary output. Stdin is never the
terminal unless the task declares `exec.interactive` and vx's stdin is
a TTY (schema.md § `interactive`): then the task gets vx's stdin,
stdout and stderr, runs alone, and nothing of it passes through vx.
Otherwise the rule splits on `exec.persistent`:

- **A one-shot task** gets `'ignore'`: it sees EOF at once, so a task
  that reads stdin finishes instead of hanging CI
  (`tests/runner.test.ts` › "a task that reads stdin sees EOF at once,
  never a hang"). A task that needs TTY input declares
  `exec.interactive`.
- **A persistent task** gets a pipe vx holds and never writes: it stays
  open while vx lives and ends when vx does. A dev server that exits on
  stdin EOF — esbuild `--watch`, the Vite case in turborepo#8915 —
  became ready and exited 0 under `'ignore'`, and `vx run dev` ended
  green (fixed 2026-09-24, `tests/keep-alive.test.ts` › "a server that
  exits on stdin EOF stays up while vx runs"). Each task has its own
  pipe, so several persistent tasks never compete for keystrokes; none
  receives any, so a server's keyboard shortcuts (Vite's `h`, `r`) do
  not reach it unless it declares `exec.interactive`. Not the terminal, because
  several servers would steal each other's input, and a CI's
  `/dev/null` stdin is the same EOF. Turbo's stream mode draws the same
  line: its pin is named `nonpersistent_task_sees_eof_on_stdin`.

A one-shot task ends when its shell exits, not when its pipes close. A
process the task left running (`server & echo up`) keeps stdout and
stderr open, so vx reads on for 250 ms after the shell exits and then
stops. That bound is what keeps a leftover server from hanging the run.
What the leftover writes after it is not captured — not in the frame,
not in the cache entry — and the frame says so with one line on stderr:
`[vx] output after the task's shell exited was cut: a process it left
running still held its stdout/stderr 250 ms later`. Until 2026-09-24 the
cut was silent (nx#35302 reproduced on vx; `tests/runner.test.ts` ›
"output a backgrounded child writes after the drain bound is cut, and
the frame says so"). A task whose output matters waits for what it
starts (`wait`).

Every surface uses one outcome vocabulary: task axis `success` /
`failed` / `skipped` / `aborted` (+ `running` live), cache axis
`miss` / `up-to-date` (fresh) / `local` / `remote`. The `--verbosity 1`
table spells the combinations out as `success` / `restored-local` /
`restored-remote` / `up-to-date`; `--report` keeps the two axes as its
Status and Cache columns.

The colors / framing modules:

- `orchestrator/colors.ts` — ANSI truecolor (`ansi-16m`), gated by
  `NO_COLOR` / `FORCE_COLOR` / `isTTY`. Programmatic-logger callers
  always see plain text.
- `orchestrator/framed-output.ts` — the `┌─` frames, the glyph grid
  (`formatTaskRow`), one-liners, persistent markers.
- `orchestrator/status-line.ts` — the serialized writer + the worker
  region.
- `orchestrator/logger.ts` — composes them; resolves the output view
  and applies the per-flow visibility policy.
- `orchestrator/summary.ts` — the closing footer (wordmark rule,
  projects/tasks/cache meters, info, time and result rows).

## Concurrency

- **Default** — the cores this process may use: `navigator.hardwareConcurrency`
  capped by the cgroup CPU quota a container runs under (`cpu.max` on v2,
  `cpu.cfs_quota_us` on v1, an ancestor's quota binding too; a 1.5-core
  quota is two workers, never below one — `util/cgroup.ts`), or
  `vx.workspace.ts`'s `concurrency` field when set. Inside a container the
  raw count is the HOST's, and eight workers on a two-core quota is
  oversubscription by four; `--concurrency <n>%` is a percentage of the
  same capped count.
- **Override** — `--concurrency N` (CLI). CLI wins over workspace
  config.
- **`concurrency: 1`** serializes everything while still respecting
  topo order: execs and restores share the one slot.
- The scheduler never exceeds the cap; tasks queue. Above 1,
  restore-tier tasks run on their own lane, `2 × concurrency` wide,
  and never take an exec slot.
- Failure of a task doesn't pause the scheduler — independent
  siblings continue running and starting (unless `--continue=never`).

### Executor pools

`concurrency` counts LOCAL worker slots. An executor that runs its tasks
somewhere else declares its own `capacity`, and the tasks placed on it are
admitted against that number instead — so a 64-wide worker pool is not
throttled by a 10-core laptop, and a `--concurrency 1` run still keeps the
pool full. A `capacity` that is not a positive integer is refused:
`plugin '&lt;p&gt;' returned executor '&lt;e&gt;' with capacity &lt;v&gt;: it must be a
positive integer`.

- **Placement is decided once per task, before scheduling.** `run()` asks
  the declared executors, in order, which one takes each task (see
  [`schema.md` § `remote`](../schema/#remote-optional) for what pins a
  task here); the scheduler then knows which pool every task will occupy.
- **A pooled task holds nothing on this machine.** The `admit` stage is
  asked only for tasks about to run here, with the tasks running here; a
  task on an executor pool is never asked and never counted, so it can
  never park behind a local reservation.
- **Restore-tier tasks always use the restore lane**, even when placed
  on an executor with a `capacity`: a restore is local disk work.
- **No pooled executor declared = the legacy path.** With every task on
  the local pool the admission gate is byte-identical to before pools
  existed.

## Cache control flags

`--no-cache` turns all four cache axes off: every task runs, nothing
is read or written, and `cleanOutputs` is skipped — the user is
debugging and managing the tree themselves; silently wiping `dist/`
mid-debug would be hostile.

`--force` turns only the READ axes off: every task re-executes, but
fresh artifacts are still written (outputs ARE cleaned so the saved
snapshot is clean). `--cache=<spec>` gives per-layer control. Full
semantics: [`cli.md` § Cache control](../cli/#cache-control---cache---no-cache---force)
and [`caching.md` § Cache policy](../caching/#cache-policy-readwrite-axes).

## Planning paths (`--dry`, `--graph`)

Both short-circuit execution. The planner (`orchestrator/plan.ts`)
runs the same setup steps — workspace discovery, config load, package
graph, task graph — and the same per-task hash derivation, then
probes the cache. The probe is read-only; against a remote layer it
is an existence check only (no artifact download, no ingest). The one
deliberate side effect: `cache.inputs.runtime` / `workspaceRuntime`
probe commands DO run, because predicting a key requires resolving
them — keep runtime inputs side-effect-free.

The two flags differ only in output format:

- `--dry[=text|json]` → text (default) or JSON list of predicted
  outcomes per task: `hit-local`, `hit-remote`, `miss`, `no-cache`,
  `group`. Formatter: `cli/plan-format.ts:formatPlanText` /
  `formatPlanJson`. When the workspace declares more than one executor,
  each line also names the executor the task would be PLACED on — the only
  surface that makes `exec.remote` checkable before the run. Resolving the
  executors is a plugin-factory call, the same class the cache capability
  already makes at plan time; a plugin that throws costs the label, never
  the plan.
- `--graph[=<path>]` → Graphviz DOT, colored by predicted status.
  Pipe to `dot` for SVG/PNG render. Formatter:
  `formatGraphDot`.

Mutually exclusive: `--dry` and `--graph` together is a parse error.
Combining either with `--summarize`, `--profile`, `--report` or
`--report-file` is a parse error (those need a real run; the last two
were accepted and wrote nothing until item 992).

## Run artifacts

- **`--summarize[=<path>]`** — per-run JSON to
  `<cacheDir>/runs/<run_id>.json` by default (or the explicit path).
  Mirrors the `runs` table shape — one task entry per real task, hits
  included, with status, hash, duration, cpu_ms, peak RSS, hrtime spans
  (bigint serialized as strings to preserve ns precision).
- **`--profile[=<path>]`** — Chrome-trace JSON of every task's
  wallclock span. Default path: `profile.json` (cwd-relative). One
  `tid` per project so concurrent tasks render on distinct lanes.
  Open with `chrome://tracing` or https://ui.perfetto.dev.
- **`--report[=markdown]`** — a markdown table to stdout
  above the footer (CI step summaries), through `RunOptions.beforeFooter`.
- **`--report-file <path>`** — the same report APPENDED to `<path>`
  (`$GITHUB_STEP_SUMMARY`).

Writers live in `orchestrator/run-artifacts.ts:writeRunSummary` /
`writeRunProfile` and `orchestrator/run-report.ts`. A `--summarize` or
`--profile` write error is surfaced via `log.status`, a `--report-file`
one on stderr (`cli/run.ts`); neither changes the run's exit code — the
run already happened.

## Why each rule

- **Cache failures are never cached.** Caching a failure prevents
  retry flows. The next run gets the same failure even after the
  user fixes the cause.
- **Group tasks are silent in the summary.** Including them in the
  count is confusing — "3 of 4 cached" when one was a group that
  ran nothing isn't informative.
- **Project scope defaults to cwd.** Most invocations are "build/
  test the thing I'm working on". `--all` / `--filter` exist for
  the workspace-wide case.
- **The scheduler doesn't bail on first failure by default.** A flaky
  test failing shouldn't stop an unrelated build. Independent siblings
  continue; only dependents are skipped. `--continue=never` opts into
  fail-fast.
- **Misses own the worker pool.** A miss is the critical path, so
  the exec lane is `concurrency` wide and only executions take it.
  Restores run on their own lane, so warm work never queues behind
  ordering it doesn't need and never takes a slot from real work.
- **Forwarded args don't reach upstream tasks.** Otherwise
  `vx run build -- --watch` would set `--watch` on every upstream's
  build, and upstream cache keys would partition by CLI args that
  don't change their behavior.
- **`recordRunBundle` skips group tasks.** They aren't real runs;
  analytics queries that sum duration would double-count without it.
- **A requested persistent task keeps the run alive.** The dev server
  IS the point of the run; tearing it down the instant it became
  ready would make `vx run dev` useless.

---

# Glossary

> One tool-neutral definition per term, with the name each tool uses for it.

Every task runner solves the same handful of problems, and each one names
them differently. This page defines each idea once, without reference to
any tool, then gives the name vx, Turborepo, Nx and Bazel use for it. Compare
tools by what they do, not by what they call it.

The other tools' names were checked against their own documentation on
2026-09-24, and each is linked. A dash means that tool's documentation has
no term for the idea. It does not mean the tool cannot do the thing some
other way.

## Workspace

**The repository as a unit of work: every project in it, their
relationships, and the settings that apply to all of them.** A workspace
is what a single command operates over.

- vx: the workspace, configured by `vx.workspace.ts` ([workspace config](../guides/configure/#workspace-config))
- Turborepo: the Workspace ([package and task graphs](https://turborepo.com/docs/core-concepts/package-and-task-graph))
- Nx: the workspace ([glossary](https://nx.dev/docs/reference/glossary#workspace))
- Bazel: the workspace, organised into [repositories](https://bazel.build/reference/glossary#repository)

## Project

**One buildable unit inside the workspace**, usually a package with its
own `package.json`. Projects depend on each other the way packages do.

- vx: a project, one `vx.config.ts` per package
- Turborepo: a package ([package graph](https://turborepo.com/docs/core-concepts/package-and-task-graph#package-graph))
- Nx: a project ([glossary](https://nx.dev/docs/reference/glossary#project))
- Bazel: a [package](https://bazel.build/reference/glossary#package), holding [targets](https://bazel.build/reference/glossary#target)

## Task

**One command run for one project**: build `ui`, test `api`. The task is
the unit a runner schedules, caches and reports on.

- vx: a task, id `project#task`, declared under `tasks` ([schema](../schema/#taskconfig))
- Turborepo: a task, declared under `tasks` in `turbo.json` ([configuration](https://turborepo.com/docs/reference/configuration#tasks))
- Nx: a task, an invocation of a [target](https://nx.dev/docs/reference/glossary#target) on a project ([glossary](https://nx.dev/docs/reference/glossary#task))
- Bazel: an [action](https://bazel.build/reference/glossary#action), produced from a target by its rule

## Task dependency

**An edge saying one task must finish before another starts**, because the
second reads what the first produced. The common case is "build my
dependencies first", written as the same task in every project this one
depends on.

- vx: `dependsOn: ['^build']`, where `^` means the dependency projects ([`dependsOn`](../schema/#dependson-optional))
- Turborepo: `dependsOn: ["^build"]` ([configuration](https://turborepo.com/docs/reference/configuration#dependson))
- Nx: `dependsOn`, the [task pipeline](https://nx.dev/docs/reference/glossary#task-pipeline)
- Bazel: a [dependency](https://bazel.build/reference/glossary#dependency) between targets, declared in `BUILD` files

## Task graph

**Every task a command will run, with the dependency edges between
them.** The runner derives it from the project graph and the task
dependencies, then schedules it. It is the thing to read when a run does
something surprising.

- vx: the task graph (`vx run --graph`, `vx run --dry=json`)
- Turborepo: the Task Graph ([package and task graphs](https://turborepo.com/docs/core-concepts/package-and-task-graph#task-graph))
- Nx: the task graph ([glossary](https://nx.dev/docs/reference/glossary#graph))
- Bazel: the [action graph](https://bazel.build/reference/glossary#action-graph)

## Project graph

**The projects and the dependencies between them**, read from the package
manager's manifests. The task graph is built on top of it.

- vx: the package graph
- Turborepo: the Package Graph ([package and task graphs](https://turborepo.com/docs/core-concepts/package-and-task-graph#package-graph))
- Nx: the project graph ([glossary](https://nx.dev/docs/reference/glossary#graph))
- Bazel: the [target graph](https://bazel.build/reference/glossary#target-graph)

## Affected

**The projects a change can reach**: those whose files changed, plus
everything that depends on them. Running only the affected tasks is how
a large repository keeps CI proportional to the change.

- vx: `--affected[=<base>]` ([CLI](../cli/))
- Turborepo: `--affected` ([run reference](https://turborepo.com/docs/reference/run#--affected))
- Nx: affected, `nx affected` ([affected](https://nx.dev/docs/features/ci-features/affected))
- Bazel: —

## Inputs

**Everything that can change a task's result**: its source files, its
configuration, the environment variables it reads, and the results of
the tasks it depends on. A runner can have you declare them, or infer
them, and the choice decides what it can prove.

- vx: `cache.inputs`, declared and required, never inferred ([caching](../caching/))
- Turborepo: `inputs` ([configuration](https://turborepo.com/docs/reference/configuration#inputs))
- Nx: cache inputs ([glossary](https://nx.dev/docs/reference/glossary#cache-inputs))
- Bazel: the declared input [artifacts](https://bazel.build/reference/glossary#artifact) of an action

## Outputs

**The files a task produces**, which a cache stores and restores. Terminal
output is usually stored too, so a replayed task prints what it printed.

- vx: `cache.outputs` ([caching](../caching/))
- Turborepo: `outputs` ([configuration](https://turborepo.com/docs/reference/configuration#outputs))
- Nx: cache outputs ([glossary](https://nx.dev/docs/reference/glossary#cache-outputs))
- Bazel: the declared output [artifacts](https://bazel.build/reference/glossary#artifact) of an action

## Cache key

**A digest of a task's inputs.** Two runs with the same key are expected to
produce the same outputs, so the second can replay the first. Everything
that decides the key decides what the cache can be trusted with.

- vx: the cache key, a 16-hex xxHash3 digest ([caching](../caching/))
- Turborepo: the hash, or "fingerprint" ([caching](https://turborepo.com/docs/crafting-your-repository/caching#task-inputs))
- Nx: the hash of the cache inputs ([glossary](https://nx.dev/docs/reference/glossary#cache-inputs))
- Bazel: the [action key](https://bazel.build/reference/glossary#action-key)

## Cache hit, miss and stale hit

**A hit** finds the key in the cache and replays the stored outputs
instead of running the task. **A miss** runs it. **A stale hit** is a hit
whose stored outputs are wrong for today's inputs, because something the
task read was never part of the key. It reports success and serves
yesterday's result, which makes it the worst failure a cache can have.

- vx: hit, miss and stale hit ([caching](../guides/configure/#caching))
- Turborepo: cache hit and cache miss ([caching](https://turborepo.com/docs/crafting-your-repository/caching))
- Nx: cache hit and cache miss ([glossary](https://nx.dev/docs/reference/glossary#cache-hit)); a stale result is called a "false cache hit" in its [sandboxing](https://nx.dev/docs/features/ci-features/sandboxing) docs
- Bazel: served from the [action cache](https://bazel.build/reference/glossary#action-cache); a wrong one breaks [correctness](https://bazel.build/reference/glossary#correctness)

## Remote cache

**A cache shared between machines**, so CI and every developer reuse each
other's results. It makes the cost of a stale hit shared too.

- vx: a remote `CacheLayer` from a plugin, such as `@vzn/vx-reapi` or `turboCache()` ([remote caching](../guides/ci/#remote-cache))
- Turborepo: Remote Caching ([remote caching](https://turborepo.com/docs/core-concepts/remote-caching))
- Nx: remote cache ([glossary](https://nx.dev/docs/reference/glossary#remote-cache)), offered as Nx Replay
- Bazel: remote caching, with a local [disk cache](https://bazel.build/reference/glossary#disk-cache)

## Hermeticity and sandboxing

**A task is hermetic when it reads only its declared inputs and writes
only its declared outputs.** A sandbox enforces that by running the task
where undeclared files cannot be reached, and reporting what it tried.
A sandbox is how a runner proves the key is complete, rather than
trusting it.

- vx: `exec.sandbox`, run locally on Linux and macOS ([sandboxing](../guides/sandboxing/))
- Turborepo: —
- Nx: task sandboxing, an Nx Cloud add-on run on a dedicated compute cluster ([task sandboxing](https://nx.dev/docs/features/ci-features/sandboxing))
- Bazel: [hermeticity](https://bazel.build/reference/glossary#hermeticity), enforced by [sandboxing](https://bazel.build/reference/glossary#sandboxing)

## Remote execution

**Running a task on another machine** and bringing its outputs back, so a
laptop can use a build farm. It needs every input declared, because the
other machine sees nothing else.

- vx: `exec.remote`, through the `@vzn/vx-reapi` plugin ([remote execution](../guides/ci/#remote-execution))
- Turborepo: —
- Nx: distributed task execution, which spreads tasks across CI agents ([glossary](https://nx.dev/docs/reference/glossary#distributed-task-execution))
- Bazel: remote execution, whose protocol (REAPI) the vx plugin speaks

## Persistent task

**A task that does not exit**, such as a dev server or a watcher. A runner
cannot wait for it to finish before starting what depends on it, and it
must never be cached.

- vx: `exec.persistent`, ready when its output matches `readyWhen` ([dev tasks](../guides/configure/#dev-tasks))
- Turborepo: `persistent: true` ([configuration](https://turborepo.com/docs/reference/configuration#persistent))
- Nx: a continuous task, `continuous: true`
- Bazel: —

## Critical path

**The longest chain of dependent work in the task graph.** No amount of
parallelism finishes a run faster than its critical path. A scheduler
that starts the tasks on it first finishes sooner on the same machine.

- vx: with no plugin the scheduler orders ready tasks by how many tasks wait on each; `@vzn/vx-schedule-history` orders them by remaining critical path, learned from past runs ([What a run does](../execution/#concurrency))
- Turborepo: —
- Nx: the critical path, named where its CI guide says what a cache cannot fix ([CI caching](https://nx.dev/docs/kb/ci-caching))
- Bazel: the critical path, which every build reports and the profiler draws ([JSON trace profile](https://bazel.build/advanced/performance/json-trace-profile))

## Seam and plugin

**A seam is a point in the pipeline where outside code decides.** Examples
are where a task runs, where artifacts live, who observes the run, and how
the graph is shaped. A plugin fills one or more seams. The width of the
seams decides what can be built on a tool without forking it.

- vx: plugin stages from `config` to `telemetry` ([plugins](../guides/plugins/))
- Turborepo: —
- Nx: a [plugin](https://nx.dev/docs/reference/glossary#plugin), which can infer tasks and supply [executors](https://nx.dev/docs/reference/glossary#executor)
- Bazel: [rules](https://bazel.build/reference/glossary#rule) written in [Starlark](https://bazel.build/reference/glossary#starlark)

---

# AI agents

> Let a coding agent run vx, read its answers as JSON, and ask the workspace about its cache and history.

vx is built to be run by agents as much as by people. Everything a
person reads in the terminal, an agent can read as data, and the docs
themselves are plain markdown.

## Give the agent the docs

Point the agent at [llms.txt](https://vznjs.github.io/vx/llms.txt): an index of every page as
markdown. [llms-full.txt](https://vznjs.github.io/vx/llms-full.txt) is every docs page in one
file. Any page is also served raw beside its HTML: add `.md` to its
path, as in [quickstart.md](https://vznjs.github.io/vx/quickstart.md).

Without network, `vx docs <query>` searches the reference that ships
inside vx (CLI, config schema, caching, execution, patterns, security,
features) and prints the matching sections whole; `--format json` gives
`{query, hits}`.

## Install the vx skill

`@vzn/vx` ships an agent skill: one `SKILL.md` that teaches an agent to
run tasks, read failures and query the workspace as JSON. Copy it where
your agent reads skills, for Claude Code:

```sh
mkdir -p .claude/skills/vx
cp node_modules/@vzn/vx/skills/vx/SKILL.md .claude/skills/vx/
```

## Run tasks

The commands are the same for an agent as for you:

```sh
vx run build --all
vx run test --affected=origin/main
```

Outside a terminal vx prints plain lines, with no live status region.
A run that is missing its task name does not open the picker without a
TTY; it fails and lists the tasks it found. The exit code is the
verdict: `0` when every task passed ([exit codes](#branch-on-exit-codes-and-error-codes)).

## Read answers as JSON

`vx run`, `vx show`, `vx info`, `vx why`, `vx last`, `vx cache prune`,
`vx lock --check` and `vx init --dry` take `--format json`. Each prints one JSON document to stdout, and every
notice goes to stderr, so stdout always parses. Each shape is a JSON
Schema shipped in the package (`node_modules/@vzn/vx/schemas/`).

```sh
vx show --format json              # every project and its tasks
vx why app#build --format json     # why app#build re-ran, down to the root cause
vx last --failed --format json     # the last failed run, task by task
vx run build --all --dry=json      # what a run would do, before it runs
vx run build --all --format json   # the run's result; task output goes to stderr
vx init --dry --format json        # what adopting vx would write, file by file
```

Under `--affected`, `--dry=json` gives each kept task an `affected`
reason: the changed input, or the `dependsOn` chain that reached it.
A failed row of `vx last --format json` carries the task's `output` and
the files it names (`locations`).

## Branch on exit codes and error codes

The exit code says whether `vx run` worked:

| Exit                  | Means                                                                  |
| --------------------- | ---------------------------------------------------------------------- |
| `0`                   | Every task passed or was a cache hit, or nothing was affected.         |
| `1`                   | A task failed or was skipped, or vx refused the command (see below).   |
| `130` / `143` / `129` | Interrupted by SIGINT / SIGTERM / SIGHUP; vx stopped every task first. |

When vx refuses a command asked for JSON, stdout carries one line with
a stable code, and the exit code stays `1`. Branch on the code, not the
message:

```sh frame="terminal"
$ vx run biuld --all --format json
{"ok":false,"error":{"code":"VX_E_UNKNOWN_TASK","message":"vx run: no projects declare task(s): biuld. Did you mean build?","docs":"https://vznjs.github.io/vx/cli/#vx_e_unknown_task"}}
```

| Code                | What to do                                             |
| ------------------- | ------------------------------------------------------ |
| `VX_E_UNKNOWN_TASK` | Read the task names from `vx show --format json`.      |
| `VX_E_USAGE`        | Fix the flag or argument; `vx help <verb>` lists them. |
| `VX_E_CONFIG`       | Fix the config file named in the message.              |
| `VX_E_NO_HISTORY`   | Run the task first; `vx why` and `vx last` need a run. |
| `VX_E_INTERNAL`     | A defect in vx: report it with the stack from stderr.  |

`docs` links the code's section of the [CLI reference](../../cli/#error-codes),
which says what to do; offline, `vx docs VX_E_UNKNOWN_TASK` prints the same
section. `node_modules/@vzn/vx/schemas/error.json` describes the line.

## Ask the workspace over MCP

`@vzn/vx-mcp` adds `vx mcp`, an MCP server over the workspace's
tasks, cache and run history. Claude Code, Cursor,
Continue.dev and Copilot can call it.

```sh
npm install -D @vzn/vx-mcp
```

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { mcp } from '@vzn/vx-mcp'

export default defineWorkspace({
  plugins: [mcp()],
})
```

```sh
claude mcp add vx -- vx mcp
```

Its tools: `listTasks`, `getCacheStats`, `getRunHistory`,
`explainCacheKey`, `whyDidThisRerun`, `getFailures`, `getTaskLog`, `getConfig`, `checkLock`, `pruneCache`, `planInit`, `searchDocs`,
`getWorkspaceInfo`, `runTasks` and `planTasks`. `runTasks` runs
`vx run <tasks> --format json` and returns the exit code and the run
summary; `planTasks` returns the `vx run <tasks> --dry=json` plan
without running anything; `pruneCache` evicts only with `dryRun:
false`; `planInit` returns the `vx init --dry --format json` plan; the others only read. See
[vx mcp](../plugins/#vx-mcp) for each one.

---

# CI and remote

> Choose what a run covers, run only what a change affects in CI, share the cache between machines, and send tasks to a worker pool.

Run what a change touched, and reuse what another machine already built.

## Run and filter

`vx run build` runs `build` in the package you are in, and what it
depends on.

```bash
vx run build --all                     # every package that has build
vx run build --filter "@app/*"         # packages whose name matches
vx run build --filter "...@app/ui"     # a package and everything that depends on it
vx run test --affected                 # changed since the base branch, and dependents
vx run test --affected=origin/main     # changed since that ref
vx run app#build api#test              # exact tasks, from anywhere
vx run lint test build --all           # several tasks, one graph
vx run test --all -- --bail            # the child runs: bun test --bail; the key sees it
vx run build --all --dry               # the plan, nothing runs
vx run build --all --graph=g.dot       # the task graph as Graphviz DOT
vx watch test --all                    # re-run whenever its files change
```

`--dry` prints what would run and where each result would come from:

```text
would run:
  ◉  @acme/api#build  cache hit (local)         8625b603
  ◉  @acme/ui#build   cache hit (local)         71e5d9a0
  ◉  @acme/web#build  cache hit (local)         42e9b39d

3 task(s) planned, 3 cache hits (3 local).
```

| Flag                | Does                                                        |
| ------------------- | ----------------------------------------------------------- |
| `--no-cache`        | ignore the cache: no reads, no writes                       |
| `--force`           | run everything, then refresh the cache                      |
| `--concurrency <n>` | at most n tasks at once (default: the cores you may use)    |
| `--continue`        | keep going after a failure ([modes](../configure/#tasks-and-dependencies)) |
| `--output-logs <m>` | `full`, `errors-only`, `hash-only` or `none`                |
| `--summarize`       | write a JSON summary of the run                             |
| `--frozen`          | load the configs from `vx-lock.json` ([below](#a-frozen-graph)) |

Every flag: [the CLI reference](../../cli/).

## GitHub Actions

Check out with `fetch-depth: 0`: `--affected` needs the history. Its base
is the target branch on a pull request, the commit before the push on a
push.

```yaml
# .github/workflows/ci.yml
on:
  pull_request:
  push:
    branches: [main] # a new branch's first push has no `before`
jobs:
  ci:
    runs-on: ubuntu-latest
    permissions:
      contents: read # checkout; naming any permission drops the rest
      checks: write # the PR check; the job summary needs nothing
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: oven-sh/setup-bun@v2 # the runner has no Bun
      - run: npm install -g @vzn/vx
      - run: bun install --frozen-lockfile
      - run: >
          vx run ci
          --affected=${{ github.event_name == 'pull_request'
            && format('origin/{0}', github.base_ref)
            || github.event.before }}
        env:
          GITHUB_TOKEN: ${{ github.token }} # the PR check; without it, no check
```

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { github } from '@vzn/vx-ci'

export default defineWorkspace({ plugins: [github()] })
```

`github()` writes a job summary, failures first, and a PR check. The
check needs `GITHUB_TOKEN` in the vx step's `env`, as above (the runner
sets `GITHUB_REPOSITORY` and `GITHUB_SHA`); without it the check is
skipped and the summary still writes. Outside GitHub Actions it declines.
A test renders this sample:

> ## ❌ vx run
>
> **5** tasks · **2** executed · **2** cache hits (1 up-to-date, 1 restored, 1 from remote) · **1** failed · 21.4s
>
> ### Failures
>
> - **@acme/web#build** — exit 2
>
> | Task | Status | Duration |
> | --- | --- | --- |
> | @acme/web#build | ❌ failed | 3.1s |
> | @acme/web#test | ✅ ran | 4.2s |
> | @acme/api#build | ☁️ restored remote | 0ms |
> | @acme/ui#build | ✔️ up-to-date | 0ms |
> | @acme/ui#lint | ⏭️ skipped | 0ms |
>
> <sub>vx 0.0.21 · `vx run ci --all` · 3/5 passed · 1 up-to-date · 1 restored</sub>

A failure on inputs that passed before says so on its row:

```
 ◼︎   4.21s failed  miss     web#test flaky - passed 3× before
```

### A frozen graph

`vx lock` writes each project's resolved config, with a hash of its
config file, to `vx-lock.json`; commit it. `vx run ci --frozen` loads the
configs from the lock instead of evaluating them, and builds the graph
from them as usual. A frozen run trusts the lock and checks nothing:
`vx lock --check` fails on drift, so run it in CI too. It buys
determinism, not speed: on the 1,000-project bench a plain run's median
of 177 ms against frozen's 165 is a tie.

### Common problems

- **`--affected has no base here … a shallow clone?`** Set `fetch-depth: 0`.
- **`nothing affected since <ref>` on every push.** `origin/main` on a push to `main` is the commit itself. Use `github.event.before`.
- **The whole log lands in the job summary.** Use `--report-file="$GITHUB_STEP_SUMMARY"`, not a `>>` redirect.

## Remote cache

A shared cache is a plugin. vx looks here, then asks the remote, and
uploads new results in the background.

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { reapi } from '@vzn/vx-reapi'

export default defineWorkspace({
  plugins: [reapi({ endpoint: 'grpcs://cache.example.com:443' })], // or VX_REAPI_ENDPOINT
})
```

`@vzn/vx-reapi` speaks Bazel's Remote Execution API (NativeLink,
BuildBuddy, Buildbarn, bazel-remote). It re-hashes every blob it reads: a
corrupt download, a down server or a refused token is a miss, never wrong
bytes. With no endpoint, it declines.

`turboCache()` from `@vzn/vx-migrate` keeps a Turborepo cache, Vercel's
included, and reads Turbo's own variables:

```sh
bun add -d @vzn/vx-migrate
npx turbo login && npx turbo link        # stores a token and a team
export TURBO_TOKEN=… TURBO_TEAM=…
```

Then declare `plugins: [turboCache()]`. `nxCache()` does the same for a
self-hosted Nx cache; your own backend is [a plugin](../plugins/#your-own-cache).
A laptop that only reads runs with `--cache=local:rw,remote:r`; so does a
pull request from a fork, which must never write what `main` restores.
The plugins honour the tools' own switches for it too: Turbo's
`TURBO_REMOTE_CACHE_READ_ONLY` and `TURBO_CACHE`, Nx's
`NX_SKIP_REMOTE_CACHE`.

## Remote execution

`reapi()` can also send tasks to a worker pool (NativeLink, BuildBuddy,
Buildbarn); the graph and the scheduling stay here. It is never on by
default:

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { reapi } from '@vzn/vx-reapi'

export default defineWorkspace({
  plugins: [
    reapi({
      endpoint: 'grpcs://cache.example.com:443',
      execute: true, // or VX_REAPI_EXECUTE=1
      platform: { OSFamily: 'Linux', 'container-image': 'docker://node:22' },
      capacity: 64, // remote tasks at once, apart from your cores
    }),
  ],
})
```

`--dry` says where each task runs (`@vx/reapi` or `@local`).
`exec.remote: false`, sandboxed and persistent tasks, and what depends on
them, stay here. A task with no `cache` block stays here too, because the
executor declines it, but what depends on it can still go remote. Workers have no `node_modules`: make
the install a `remote: 'only'` task the others depend on. The image needs
`/bin/sh` and your toolchain.

A worker gets only what `cache.inputs` declares, so a task that fails
there and passes here reads a file it never declared.

- A down server is a cache miss, never a hung run.
- Uploads chunk at 65535 bytes (`SAFE_CHUNK_BYTES`), the size no Bun http2
  stall has been seen at. A larger `chunkBytes` that stalls retries once at
  that size before the task fails.

---

# Configure

> Tasks and dependencies, caching, environment variables, dev servers, the workspace file and lockfiles, one section each.

Tell vx what each package runs, what it reads and what it may see. Every
field: [the config reference](../../schema/).

## Tasks and dependencies

Each task in a package's `vx.config.ts` is one shell command (chain
steps with `&&`). `dependsOn` says what finishes first.

```ts
// packages/app/vx.config.ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    codegen: {
      exec: { command: 'graphql-codegen' },
      cache: { inputs: { files: ['schema.graphql'] }, outputs: { files: ['src/gen/**'] } },
    },
    build: {
      description: 'compile TypeScript to dist/',
      dependsOn: ['codegen', '^build'],
      exec: { command: 'tsc -b' },
      // codegen's output reaches this key through codegen's own key; a key
      // that read it could not be known until codegen ran, so vx refuses it.
      cache: { inputs: { files: ['src/**', '!src/gen/**'] }, outputs: { files: ['dist/**'] } },
    },
    e2e: {
      dependsOn: ['build', 'api#build'],
      exec: { command: 'playwright test', timeout: 600_000, retries: 1 },
    },
    // A group: no command, it only runs its dependencies.
    ci: { dependsOn: ['build', 'e2e'] },
  },
})
```

| `dependsOn`   | Runs first                                                        |
| ------------- | ----------------------------------------------------------------- |
| `'build'`     | `build` in this package                                           |
| `'^build'`    | `build` in each package this one depends on (from `package.json`) |
| `'api#build'` | `build` in the `api` package                                      |
| `'build.*'`   | every task in this package whose name matches                     |

A task-name pattern is allowed: `dependsOn: ['build.*']` here, `'^build.*'`
in dependencies. Bare wildcards and negation (`*`, `!task`) are not.
A package that declares no `build` gets a default one: a group behind
`^build`, keyed on all its files, so editing a package consumed as source
re-runs its dependents (`vx show` lists it as a group; for a package
with no config it says `default build`). A cycle or a
missing `'pkg#task'` is an error.

| When a task fails            | vx                                                        |
| ---------------------------- | --------------------------------------------------------- |
| `--continue=deps-ok` (default) | skips its transitive dependents and runs the rest       |
| `--continue=never`           | stops at the first failure                                |
| `--continue=always`          | runs the dependents, but saves none of them               |

| Field             | Does                                                          |
| ----------------- | ------------------------------------------------------------- |
| `exec.command`    | the one shell command, run in the package's directory         |
| `exec.env`        | what the command sees ([below](#environment-variables))       |
| `exec.timeout`    | kill the task after this many ms                              |
| `exec.retries`    | re-run a failed task this many times                          |
| `exec.persistent` | a server or watcher that does not exit ([below](#dev-tasks))  |
| `exec.sandbox`    | only the declared files and network ([Sandboxing](../sandboxing/)) |
| `exec.interactive` | reads the terminal: a prompt, a REPL, a TUI; runs alone, never cached |
| `exec.remote`     | `false` keeps it here; `'only'` for a remote pool ([Remote execution](../ci/#remote-execution)) |

`exec.remote` is the one `exec` field stripped from the key: where a task
ran says nothing about what it made. The rest is in the key, `description`
included, so editing a description costs one re-run.

## Caching

A task with a `cache` block runs once per set of inputs. List every file
the command reads, and what it writes (`[]` for test or lint). Unsure the
list is complete? Add [`exec.sandbox`](../sandboxing/) with `allow.read`
listing the same files: a workspace read outside it fails the task. The
sandbox checks `allow.read`, never `cache.inputs`, so it catches a missing
input only while the two lists match.

```ts
// packages/app/vx.config.ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    build: {
      dependsOn: ['^build'],
      exec: { command: 'vite build', env: { passThrough: ['NODE_ENV'] } },
      cache: {
        inputs: {
          files: ['src/**', 'index.html', '!**/*.test.ts'],
          env: ['NODE_ENV'],
          workspaceFiles: ['tsconfig.base.json'], // from the workspace root
        },
        outputs: { files: ['dist/**'] },
      },
    },
  },
})
```

| The key                | Holds                                                                                   |
| ---------------------- | --------------------------------------------------------------------------------------- |
| Always in it           | the package's `package.json`, the lockfile, the keys of the tasks it depends on, the task's config, arguments after `--` |
| Always excluded        | an untracked `node_modules` (an install), `.git`, `.vx`, `*.tsbuildinfo`, `vx-lock.json`, `*.bun-build`, `.????????????????-????????.tmp` (Bun's compile scratch), `.vx-tmp-*` (a restore in progress), files git ignores, the task's own outputs, a nested project's files |
| In, when you say so    | a tool's version: `cache.inputs.workspaceRuntime: ['node -v']` runs once per run at the root and folds its output; `runtime` runs in the package |
| Out, when you say so   | a dependency only for order: `cache.inputs.tasks: []`, as the [dev task](#dev-tasks) does |

Declared outputs are wiped before every run that writes the cache and every
restore, so `dist/`
ends as the cache stored it; a hit that finds them already as stored skips
both. A task that adds files beside an upstream task's outputs wipes
nothing before a run and only the files it recorded before a restore. A failed task is never saved. `--force` runs
and refreshes the cache; `--no-cache` ignores it.

A fully cached 3,270-task run: vx 393ms, Turborepo 463ms (vx 18% faster),
Nx 6.45s (vx 16× faster)
([benchmarks](../../benchmarks/); the key, part by part:
[Caching in depth](../../caching/)).

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.

### Why did it re-run?

```bash
vx why app#build
```

```console
app#build — run 019f5a02-…
  this run   2026-07-13T05:39:20.590Z · success · executed · key f7ee661520…
  previous   2026-07-13T05:37:29.550Z · success · key 8b2e9bb2e8…
  verdict    cache key changed: file packages/app/src/index.ts

  what changed (1 component, 41 unchanged):
    changed file  packages/app/src/index.ts  a1b2c3… → d4e5f6…

  what to do:
    file  an edit re-runs by design; a file the task does not read belongs out of cache.inputs.files
```

| The verdict line says | It means |
| --- | --- |
| `cache key changed: env MODE, file packages/app/src/index.ts` | those inputs moved (three named, then a count); the lines below show each |
| `cache key changed between the previous run and this one (inputs differ)` | the key moved and neither entry kept its components (pruned, or a failed run saved none) |
| `cache key unchanged — this run was served from cache, nothing re-ran` | a hit |
| `cache key unchanged — the previous run on this key failed and saved nothing, so there was nothing to hit` | a failure saves no entry |
| `cache key unchanged — re-executed because this run did not read the cache (--force, or a --cache without read)` | the run's policy read no cache |
| `cache key unchanged — neither run saved it: each ran beside a failed task (…), and a task run past a failed dependency (--continue) is never cached` | both runs went past a failure under `--continue` |
| `cache key unchanged — the previous run on this key ran beside a failed task (…) and was not saved: a task run past a failed dependency (--continue) is never cached, so there was nothing to hit` | the previous run went past a failure under `--continue` |
| `cache key unchanged — no entry for this key was in the cache when it ran (pruned or evicted), so it executed and saved one` | the entry was gone |
| `cache key unchanged — the previous run on this key executed but no entry for it is in the cache (its save failed, or it was pruned since), so there was nothing to hit` | the previous run's save failed, or a prune took the entry |
| `cache key unchanged — the previous run on this key did not write the cache (--no-cache, or a --cache without write), so there was nothing to hit` | the previous run's policy wrote no cache |
| `cache key unchanged — re-executed on the same key though this run read the cache; vx cannot name the cause` | none of the above; vx cannot name the cause |
| `cache key unchanged — re-executed on the same key (--no-cache / --force, or unrelated)` | no invocation recorded this run's cache policy, so vx cannot rule the flags out |
| `cache key unchanged — this run recorded no cache outcome, so whether it re-ran is unknown` | vx does not guess |
| `` this task declares no `cache` block — it runs on every invocation; its key is folded by dependents only `` | not cached at all |
| `this task recorded no cache key (skipped, or a persistent task) — nothing to compare` | no key to compare |
| `no prior run for this (project, task)` | nothing to compare with yet |

A hit after you changed something means that something is not declared.

## Environment variables

Past a small essential allowlist (below), a task sees only the variables you pass it:

| List                   | The command sees it | The key sees it | Use it for                                          |
| ---------------------- | ------------------- | --------------- | --------------------------------------------------- |
| `exec.env.passThrough` | yes                 | no              | secrets and CI flags (`GITHUB_ACTIONS`, `GH_TOKEN`); stays on this machine |
| `cache.inputs.env`     | no                  | yes             | with `passThrough`: a variable that changes the output |
| `exec.env.define`      | yes                 | yes             | a literal value; a remote task gets it too          |
| `exec.env.secret`      | —                   | —               | names whose values (6 characters or more) print as `***`; names holding `TOKEN`, `SECRET`, `KEY`, `PASSWORD`, `PASSWD` or `CREDENTIAL` are masked without it |

The child always gets a small essential allowlist so normal CLI tools
work: `PATH`, `HOME`, `SHELL`, `USER`, `LOGNAME`, `TMPDIR`, `TEMP`,
`TMP`, `LANG`, `LC_ALL`, `LC_CTYPE`, `TERM`, `COLORTERM`, `FORCE_COLOR`,
`NO_COLOR`, `CI`, `NODE_OPTIONS`, `COREPACK_HOME`, `PNPM_HOME`. vx sets
`VX_RUN_WORKSPACE` (the workspace root) and `VX_RUN_TASK` (the
`project#task` running) on every task, and `npm_execpath` to the
workspace's package manager, as `pnpm run` does, so npm-run-all needs
no global npm. The package's `node_modules/.bin`
is first on `PATH`. What vx itself reads:
[the CLI reference](../../cli/#environment-variables-vx-reads).

## Dev tasks

A `persistent` task is a server or watcher. Its dependents start once it
prints a line matching `readyWhen`; if none comes, `exec.timeout` fails it.

```ts
// packages/web/vx.config.ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    dev: {
      exec: { command: 'vite', persistent: { readyWhen: 'Local:' }, timeout: 30_000 },
    },
    e2e: {
      dependsOn: ['dev'],
      exec: { command: 'playwright test' },
      cache: {
        inputs: { files: ['e2e/**'], tasks: [] }, // dev is for order, not the key
        outputs: { files: ['playwright-report/**'] },
      },
    },
  },
})
```

When the run ends, vx sends the server `SIGTERM`. One that ignores it gets
a 2-second grace and is then `SIGKILL`ed. A persistent task has no `cache`
block. A sandboxed server on Linux lists its port in
`sandbox.allow.localBinding`.

## Workspace config

`vx.workspace.ts`, beside the root `package.json`, is optional. Without
it, vx runs and caches on this machine.

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { reapi } from '@vzn/vx-reapi'

export default defineWorkspace({
  plugins: [reapi({ endpoint: 'grpcs://cache.internal:443' })],
  concurrency: 8,            // default: the cores this process may use
  cacheDir: 'build/.vx',     // unset: entries shared by this repo's checkouts in ~/.vx/<id>/cache
  timeout: 600_000,
  cacheRetention: { olderThan: '30d', maxSize: '10G' },
})
```

| Field            | Sets                                                                  |
| ---------------- | --------------------------------------------------------------------- |
| `plugins`        | asked in order; this machine is always last ([Plugins](../plugins/)) |
| `concurrency`    | tasks at once; `--concurrency <n>` overrides it for one run           |
| `cacheDir`       | keep the whole cache here, shared with no other workspace; unset, entries live in `~/.vx/<id>/cache` and every checkout of the repo hits them |
| `timeout`        | a default task timeout in ms; default none                            |
| `cacheRetention` | evict at the end of every run: `olderThan` unused, then least recently used past `maxSize`; default none |
| `affectedBase` | the git ref a bare `--affected` compares with; default `origin/HEAD`, then the first trunk (`origin/main`, `origin/master`, `main`, `master`) that is not HEAD, else `HEAD~1` |
| `cacheScope` | where remote writes land: `'trusted'` reads and writes (the default on CI), `'read-only'` writes nothing (the default off CI), a name like `'pr-123'` reads its own then trusted and writes only its own; `github()` sets it on Actions ([Security](../../security/#cache-poisoning)) |
| `rules` | graph checks, each on unless `false`: `exclusiveOutputs` refuses two tasks on one output path even when one depends on the other, `upfrontKeys` a task whose inputs can match another task's outputs, so every key is known before anything runs ([Schema](../../schema/#workspace-config-vxworkspacets)) |

For a timeout, the first one set wins: a task's `exec.timeout`, then
`--timeout <ms>`, then `VX_TASK_TIMEOUT`, then this. Only `exec.timeout` is in the
cache key. There is no `globalInputs`: import a shared array instead.

## Lockfiles

Without a plugin, the lockfile is in every task's key, so one install
re-runs everything. With `@vzn/vx-lockfile` (`bun add -d @vzn/vx-lockfile`),
each package is keyed on its own dependencies, and `--affected` follows.

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { pnpm } from '@vzn/vx-lockfile' // or bun, npm, yarn

export default defineWorkspace({
  plugins: [pnpm()], // pnpm({ scope: 'workspace' }) keys the whole file instead
})
```

| Plugin   | A package's key folds                                                                 | Install-wide, for every package |
| -------- | ------------------------------------------------------------------------------------- | ------------------------------- |
| `pnpm()` | every package it reaches, by name, version and resolved peers, with integrity and any patch | every top-level field but `importers`, `packages`, `snapshots`, `patchedDependencies`, `catalogs` and `overrides` (`settings`, `onlyBuiltDependencies`, …) |
| `bun()`  | the same, through Bun's hoisted layout                                                | every top-level field but `workspaces`, `packages`, `catalog`, `catalogs`, `overrides` and `patchedDependencies` (`trustedDependencies`, …) |
| `npm()`  | the same, from `package-lock.json` versions 2 and 3                                   | the `lockfileVersion`; root `overrides` reach a package through the entries they force |
| `yarn()` | the same, from a berry lockfile, each entry with every field but its dependency lists; a yarn 1 lockfile records no workspaces, so every package folds the whole file | `__metadata`'s `version` and `cacheKey`, and the root workspace's entry (its `dependenciesMeta`) through the root's closure |

Every package's key also folds the root package's own dependencies:
their bins run from the root `node_modules/.bin`, which is on every
task's PATH. So bumping a root devDependency re-runs every package.

`vx why` names the part `plugin @vzn/vx-lockfile/pnpm`. An unreadable
lockfile stops the run and names the install to re-run. An import you
never declared is in no package's key.

---

# Migrate

> Move a Turborepo, Nx or Vite Task repo to native vx config. `vx init` writes the vx.config.ts files that are the goal; `vx init --keep` gives a temporary start.

Move a Turborepo, Nx or Vite Task repo to native vx config. The `vx.workspace.ts`
that `vx init --keep` writes is a temporary start, not a way to run the repo;
`vx init` writes the `vx.config.ts` files you keep, and
vx's benchmarks measure only that native config. Any other repo starts at the
[quickstart](../../quickstart/): there `vx init` writes the configs from
your `package.json` scripts.

> `examples/turbo` runs the steps below against this repo's packages on
> every commit.

## One command

`npx vx init` is the whole adoption in a Turbo or Nx repo: beside
`turbo.json` or `nx.json` it runs `@vzn/vx-migrate` (the installed one, else
vx's own version), which `npx @vzn/vx-migrate` (`pnpx`, `bunx`, `yarn dlx`)
also runs directly, and a [Vite Task](#vite-task) repo needs. It asks whether to migrate natively (a `vx.config.ts` per
package, the default) or keep `turbo.json` / `nx.json` as the source
(`turbo()` / `nx()`, step 2 below); `--native` or `--keep` answer it, and
without a terminal, or from Vite Task, it is native. It installs vx with the repo's own package
manager and declares the plugins the repo calls for in `vx.workspace.ts`:
the lockfile's `@vzn/vx-lockfile` plugin (`pnpm()`, …), `scheduleHistoryPlugin()`,
and `github()` when `.github/workflows` exists, installing each beside vx at
the same version (`--no-install` leaves `package.json` alone). Your
`package.json` scripts stay as they are. The steps below
are the same adoption one stage at a time.

pnpm 12 refuses a version published within its `minimumReleaseAge`,
and vx releases daily. If an install stops on that, list the `@vzn/*`
packages it names under `minimumReleaseAgeExclude` in
`pnpm-workspace.yaml`, or install the previous version; vx-migrate's
error names the same fix.

## Turborepo

1. Install vx: `npm install -D @vzn/vx` (pnpm: `pnpm add -D -w @vzn/vx`; Bun: `bun add -d @vzn/vx`).
2. Run `npx vx init --keep`. Beside `turbo.json` or `turbo.jsonc` it writes this
   `vx.workspace.ts` and nothing else, then prints a `next:` line.
3. Run that line. It installs `@vzn/vx-migrate` with your lockfile's
   manager, then builds once through `turbo()`: a check that the mapping
   holds before you write configs, not a way to keep running the repo.
4. Preview the configs with `bunx @vzn/vx-migrate --dry`, then write them
   with `bunx @vzn/vx-migrate`: one `vx.config.ts` per package, plus a
   `vx-preset.ts` when turbo.json has global fields or a task `env` several
   packages share. It never overwrites a
   file without `--force`. It takes `turbo()` out of `vx.workspace.ts`
   and uninstalls `@vzn/vx-migrate` unless a `turboCache()` still needs it.
5. Review each `TODO(vx-migrate)` comment.
6. Once `vx run build --all` does what `turbo run build` did, delete
   `turbo.json`: the configs declare every task it mapped.

```ts
import type { WorkspaceConfig } from '@vzn/vx/config'
import { turbo } from '@vzn/vx-migrate'

export default { plugins: [turbo()] } satisfies WorkspaceConfig
```

```text
$ npx vx init --keep
vx init: turbo.json found — turbo() from @vzn/vx-migrate, a temporary start until vx init --native writes native config; nothing else written.
wrote vx.workspace.ts.

next: npm install -D @vzn/vx-migrate && npx vx run build --all
```

The `next:` line uses your lockfile's manager (`pnpm add -D -w …` beside
`pnpm-lock.yaml`, `yarn add -D -W …` beside a Yarn 1 lockfile) and names only what is not installed yet,
pinned to a released vx's own version (`@vzn/vx-migrate@<version>`): every `@vzn` package releases in lockstep.
`vx init --keep --dry` prints the file instead of writing it; `--mjs` writes
`vx.workspace.mjs` without the type import. An existing
`vx.workspace.ts` that does not declare `turbo()` is left alone: add it
to the plugins, or `--force` replaces the file.

Where the repo shows a remote cache (an enabled `remoteCache` in
turbo.json, a `.turbo/config.json` that `turbo link` wrote, or
`TURBO_TOKEN` set in a GitHub Actions, GitLab or CircleCI file), the file
declares `turboCache()` too, and init says why:

```text
turboCache(): .github/workflows/ci.yml sets TURBO_TOKEN, so vx shares that remote cache (inert where the variable is unset).
```

`bunx @vzn/vx-migrate` reports what it wrote:

```text
$ bunx @vzn/vx-migrate
vx-migrate: npm install -D @vzn/vx-lockfile @vzn/vx-schedule-history
vx-migrate: npm uninstall @vzn/vx-migrate
vx-migrate: turbo.json → vx.config.ts
note: dropped turbo() from vx.workspace.ts
note: installed @vzn/vx-lockfile @vzn/vx-schedule-history (npm install -D @vzn/vx-lockfile @vzn/vx-schedule-history)
note: removed @vzn/vx-migrate (npm uninstall @vzn/vx-migrate)

3 tasks migrated clean, 0 TODOs
files written:
  packages/app/vx.config.ts
  packages/lib/vx.config.ts

next: bunx vx run build --all
```

The first run after it misses every task once: the lockfile plugin it
declared, and the install, change each key (`vx why <task>` names both).
The run after that hits. The example below keeps its own
`vx.workspace.ts` and installs nothing, so it hits at once.

`packages/lib/vx.config.ts`, as written:

```ts
import type { ProjectConfig } from '@vzn/vx/config'

export default {
  tasks: {
    build: {
      exec: {
        command: 'mkdir -p dist && cp src/*.js dist/',
      },
      dependsOn: ['^build'],
      cache: {
        inputs: {
          files: ['src/**'],
        },
        outputs: {
          files: ['dist/**'],
        },
      },
    },
  },
} satisfies ProjectConfig
```

Where the repo has a lockfile and `vx.workspace.ts` declares no
`@vzn/vx-lockfile` plugin, the report names the one for it (`npm()` above,
`pnpm()` for `pnpm-lock.yaml`): Turbo keys each package on its own lockfile entries,
and vx keys every task on the whole file until a plugin claims it.

### Try it in five minutes

[`examples/turbo`](https://github.com/vznjs/vx/tree/main/examples/turbo)
is a Turbo repo with that `vx.workspace.ts` added. The first runs go
through `turbo()`, the bridge; the last runs on the written configs alone,
the goal. Each line and its comment is what a test runs and sees on each commit
(`packages/vx/tests/examples.unsafe.test.ts`).

```sh
npm install && git init && git add -A && git commit -m init
npx vx run test --all      # 3 miss: lib#build, app#build, app#test
npx vx run test --all      # 3 up-to-date
bunx @vzn/vx-migrate       # 3 tasks migrated clean, 0 TODOs
git add -A && git commit -m migrate
npx vx run test --all      # 3 up-to-date: the written configs derive the same keys
rm vx.workspace.ts         # drop turbo(); the configs stand alone
git add -A && git commit -m done
npx vx run test --all      # 3 up-to-date
```

| Turborepo (`turbo.json`)                                    | vx (`vx.config.ts`)                                                      |
| ----------------------------------------------------------- | ------------------------------------------------------------------------ |
| `tasks` / `pipeline`                                        | `tasks`                                                                  |
| `dependsOn`                                                 | `dependsOn`, the same `'build'`, `'^build'`, `'pkg#build'` syntax        |
| `inputs`                                                    | `cache.inputs.files`; a glob that reaches a nested workspace package also in `cache.inputs.workspaceFiles` |
| `outputs`                                                   | `cache.outputs.files`                                                    |
| `env`                                                       | `cache.inputs.env` **and** `exec.env.passThrough`                        |
| `passThroughEnv`                                            | `exec.env.passThrough`                                                   |
| `cache: false`                                              | no `cache` block: the task always runs                                   |
| `persistent: true`                                          | `exec.persistent: { … }`                                                 |
| `with` | `dependsOn` a persistent sidecar, started beside the task |
| `interactive: true` | `exec.interactive: true`: the task gets the terminal, alone |
| `interruptible` | nothing: `vx watch` keeps a persistent task up and restarts it only when its config changes or it dies |
| `tags` | nothing: labels Turbo keeps out of the hash and the behaviour |
| `outputLogs` (Turbo 1: `outputMode`)                        | `"new-only"` is the default; other values are the run's `--output-logs` |
| `dotEnv` (Turbo 1), a `.env` input                          | `cache.inputs.runtime`: a probe that prints every `.env` file's name and bytes, because a gitignored `.env` is invisible to a git glob (written configs name it from the preset: `dotenvFiles`, `dotenvFilesDeep`, and `dotenvRootFiles` for the root globs); a root one (`$TURBO_ROOT$/.env`, `globalDotEnv`) is `cache.inputs.workspaceRuntime`, a probe of just the files its globs name |
| an input or `globalDependencies` path git ignores (`config.local.json`) | `cache.inputs.workspaceRuntime`: a probe that prints the file's name and bytes, since core refuses a file input git ignores; a gitignored file a glob matches is not keyed |
| `command` (Turbo 2.11) | `exec.command` (the argv, quoted); `null` or `[]` is no task |
| `description` | `description` |
| `extends`                                                   | nothing: a package task merges over the root's, field by field           |
| `$TURBO_ROOT$/file`                                         | `cache.inputs.workspaceFiles` / `outputs.workspaceFiles`                 |
| `globalDependencies` / `globalEnv` / `globalPassThroughEnv` (and Turbo 1's `globalDotEnv`) | a generated `vx-preset.ts` each config imports as `vx-preset.js` (your `tsc` accepts it without `allowImportingTsExtensions`; Bun loads the `.ts`), except in a package whose `tsconfig.json` is a composite project or sets `rootDir` and takes the config in: there the config declares the values itself, as `tsc` refuses a file outside the package (TS6059); a wildcard env name is reported, not mapped |

The command itself comes from your `package.json` script, with its
`pre<name>` / `post<name>` hooks folded in.

| Turborepo                         | vx                                                     |
| --------------------------------- | ------------------------------------------------------ |
| `turbo run build`                 | `vx run build --all`                                   |
| `turbo run build --filter=@app/*` | `vx run build --filter "@app/*"`                       |
| `turbo run build --affected`      | `vx run build --affected` (`turbo()` takes `TURBO_SCM_BASE`, or GitHub Actions' base, as Turbo does) |
| `turbo run build --continue`      | `vx run build --continue` (`always`, as Turbo's; without it, vx skips only a failure's dependents where Turbo stops) |
| `TURBO_TOKEN` remote cache        | [`turboCache()`](../ci/#remote-cache) reads the same variables |

## Nx

1. Install vx: `npm install -D @vzn/vx` (pnpm: `pnpm add -D -w @vzn/vx`; Bun: `bun add -d @vzn/vx`).
2. Run `npx vx init --keep`. Beside `nx.json` it writes this `vx.workspace.ts`
   and nothing else. With `turbo.json` there too, it declares `turbo()`.
   A CI file that sets `NX_SELF_HOSTED_REMOTE_CACHE_SERVER` adds `nxCache()`;
   an Nx Cloud workspace is named instead, since vx cannot share its cache.
3. Run the `next:` line it prints. It installs `@vzn/vx-migrate`, then
   builds once through `nx()`: a check that the mapping holds before you
   write configs, not a way to keep running the repo.
4. `vx-migrate` reads the resolved graph, never `nx.json` alone: an
   exported `.nx/workspace-data/project-graph.json`, else the one your
   installed `nx` exports for it (`nx graph`, as `nx()` runs). Without
   `nx` installed it stops and prints the export command.
5. Preview the configs with `bunx @vzn/vx-migrate --dry`, then write them
   with `bunx @vzn/vx-migrate`. With `turbo.json` there too, pass
   `--from nx` (or `--from turbo`). It takes `nx()` out of
   `vx.workspace.ts` and uninstalls `@vzn/vx-migrate` unless a written
   task runs an `nx-exec` or `nx-env` line, or `nxCache()` needs it.
6. Review each `TODO(vx-migrate)` comment, and rewrite each `nx-exec`
   line (an executor target) as the command it runs.
7. Once `vx run build --all` does what `nx run-many -t build` did,
   delete `nx.json`: the configs declare every task the graph had. Keep
   Nx installed while a config still runs an `nx-exec` line.

A Lerna 6+ repo whose root scripts call `lerna run` runs on Nx's task
runner, `nx.json` or not, so `bunx @vzn/vx-migrate` maps it as an Nx repo
from the graph `nx graph` exports. `vx init --keep` adopts by `nx.json` alone and
maps such a repo's scripts instead.

```ts
import type { WorkspaceConfig } from '@vzn/vx/config'
import { nx } from '@vzn/vx-migrate'

export default { plugins: [nx()] } satisfies WorkspaceConfig
```

```text
$ npx vx init --keep
vx init: nx.json found — nx() from @vzn/vx-migrate, a temporary start until vx init --native writes native config; nothing else written.
wrote vx.workspace.ts.

next: npm install -D @vzn/vx-migrate && npx vx run build --all
```

`bunx @vzn/vx-migrate` reports what it wrote:

```text
$ bunx @vzn/vx-migrate
vx-migrate: npm install -D @vzn/vx-lockfile @vzn/vx-schedule-history
vx-migrate: nx graph → vx.config.ts
note: dropped nx() from vx.workspace.ts
note: installed @vzn/vx-lockfile @vzn/vx-schedule-history (npm install -D @vzn/vx-lockfile @vzn/vx-schedule-history)
note: migrating from the resolved project-graph snapshot — plugin-inferred targets are frozen as static config; `nx:run-commands` targets are their shell lines, and every other executor runs as itself through `nx-exec` (keep Nx and @vzn/vx-migrate installed until those targets are rewritten as commands); targets with `.env` files run through `nx-env`

2 tasks migrated clean, 0 TODOs
files written:
  packages/app/vx.config.ts
  packages/lib/vx.config.ts

next: bunx vx run build --all
```

`packages/lib/vx.config.ts`, as written (the `define` names are the
ones Nx sets for a task):

```ts
import type { ProjectConfig } from '@vzn/vx/config'

export default {
  tasks: {
    build: {
      exec: {
        command: 'mkdir -p dist && cp src/index.js dist/lib.js',
        env: {
          define: {
            NX_TASK_TARGET_PROJECT: 'lib',
            NX_TASK_TARGET_TARGET: 'build',
            LERNA_PACKAGE_NAME: 'lib',
          },
        },
      },
      cache: {
        inputs: {
          files: ['src/**/*'],
        },
        outputs: {
          files: ['dist'],
        },
      },
    },
  },
} satisfies ProjectConfig
```

An executor target is written as an `nx-exec` line: the executor runs
as itself, in its own Node process through Nx's public `runExecutor`,
with its options on the command line, as `nx()` runs it. The migrator
translates no executor; `nx:run-commands` targets are their shell
lines, `nx:run-script` the package script, and `nx:noop` a group task.
Rewriting each `nx-exec` line as the command the executor wraps (jest,
`vite build`, `tsc -p …`) is the step that lets you remove Nx:

```ts
test: { exec: { command: `nx-exec @nx/jest:jest --project a --target test --options '{"jestConfig":"libs/a/jest.config.ts"}'` } }
```

| Nx                                   | vx                                                        |
| ------------------------------------ | --------------------------------------------------------- |
| a project's `targets`                | `tasks`                                                   |
| `dependsOn` (`^build`, `app:build`)  | `dependsOn` (`^build`, `app#build`)                       |
| `configurations`                     | one task per configuration: `build`, `build:ci`           |
| `inputs` / `namedInputs`             | `cache.inputs.files`                                      |
| `{workspaceRoot}/file`               | `cache.inputs.workspaceFiles`                             |
| `{ "env": "VAR" }`                   | `cache.inputs.env` **and** `exec.env.passThrough`         |
| `{ "runtime": "<cmd>" }`             | `cache.inputs.workspaceRuntime`: it runs at the workspace root, as Nx's does |
| `{ "json": "<file>", "fields": … }`  | the whole file in `files` / `workspaceFiles`: a superset of the fields |
| `outputs`                            | `cache.outputs.files` (or `workspaceFiles` for `dist/<project>`) |
| `nx build app`                       | `vx run app#build`                                        |
| `nx run app:build:production`        | `vx run app#build:production`                             |
| `nx affected -t test`                | `vx run test --affected` (`nx()` takes `NX_BASE` or `defaultBase` as its base) |
| `nx graph`                           | `vx run build --all --graph`                              |
| `nx reset`                           | `vx cache prune --older-than <age>` trims it; delete the cache store `vx info` names to drop it all; there is no daemon |
| Nx Cloud cache                       | [`nxCache()`](../ci/#remote-cache) for a self-hosted Nx cache |

Generators, Nx Console and module-boundary rules have no vx equivalent;
keep Nx for those.

## Vite Task

`npx @vzn/vx-migrate` in a repo whose root `package.json` lists
`vite-plus` writes a `vx.config.ts` per package from each `vite.config`
`run.tasks` and its `package.json` scripts (`--from vite-task` when
turbo.json or Nx is there too). Vite Task traces the files a task reads
and writes; vx declares them, so a task without explicit `cache.input`
and `cache.output` runs uncached until its `TODO(vx-migrate)` is filled.
The field-by-field mapping is in the `@vzn/vx-migrate` README.

## Common problems

- **No workspace root.** vx finds projects through `pnpm-workspace.yaml` or `package.json` `workspaces`. `nx()` adds each Nx project the graph names that no package glob lists (a `project.json` library, the root project). `bunx @vzn/vx-migrate` writes a `package.json` for each such library that lacks one and prints the directories to add to the globs.
- **A task always runs.** vx caches only a task with a `cache` block. `vx-migrate` fills it from `turbo.json` or the Nx graph; a Turbo task with `cache: false` has none.
- **An env var is missing in the command.** vx isolates the environment: list it in `exec.env.passThrough` ([Environment variables](../configure/#environment-variables)).
- **`vx run build` ran one package.** Without `--all`, vx runs the package you are in.

Every Turborepo and Nx behaviour, spelled in vx and pinned by a test: the
[parity map](../../parity/).

---

# Plugins

> Write a plugin that fills one or more stages of every run, export runs to OpenTelemetry, and let an AI agent read your workspace with vx mcp.

Change every run from one place: add tasks, key material, a cache, an
exporter or a CLI verb.

## Write one

A plugin is a function that returns `definePlugin(import.meta, hooks)`.
Its name is its package's name. Fill only the hooks you need; an unfilled
hook costs nothing. Declare it in `vx.workspace.ts`
(`plugins: [typecheck()]`), and `vx info` lists it with its hooks. To test
it, call `run()` from `@vzn/vx` on a throwaway workspace. A runnable
plugin for each of nine seams, each held by a test that runs it, is in
[`packages/vx-plugin-examples`](https://github.com/vznjs/vx/tree/main/packages/vx-plugin-examples).
`vx init --plugin <seam>` writes one, with its test, into your workspace.

This one gives every TypeScript package a `typecheck` task:

```ts
import { definePlugin, type VxPlugin } from '@vzn/vx'

export function typecheck(): VxPlugin {
  return definePlugin(import.meta, {
    project(config, ctx) {
      const dev = ctx.packageJson['devDependencies'] as Record<string, string> | undefined
      if (!dev?.['typescript']) return
      config.tasks ??= {}
      config.tasks['typecheck'] ??= {
        exec: { command: 'tsc --noEmit' },
        cache: { inputs: { files: ['src/**', 'tsconfig.json'] }, outputs: { files: [] } },
      }
    },
  })
}
```

## The hooks

Plugins are asked in the order you list them. What every plugin declines
runs and is stored on this machine.

| Stage       | Hook                   | Decides                                                   |
| ----------- | ---------------------- | --------------------------------------------------------- |
| config      | `config(ws, ctx)`      | the workspace config, before it is used                   |
| discover | `discover(ctx)` | which directories are projects beyond the members |
| project     | `project(config, ctx)` | a project's tasks: add, remove, rewrite                   |
| graph       | `graph(nodes, ctx)`    | the run's edges                                           |
| key         | `key(task, ctx)`       | extra cache-key material, named in `vx why`               |
| fingerprint | `fingerprint`          | a root file it keys itself, such as a lockfile            |
| schedule    | `schedule(nodes, ctx)` | which ready task runs first                               |
| admit       | `admit(task, ctx)`     | whether a ready task starts now, beside what runs here    |
| execute     | `executor(ctx)`        | where one task's command runs                             |
| store       | `cache(ctx)`           | where artifacts live                                      |
| observe     | `telemetry(ctx)`       | where run records go; it can never change the run         |
| setup       | `setup(ctx)`           | once per run, before the first task                       |
| cli         | `commands`             | which verbs `vx` has                                      |
| teardown    | `teardown()`           | flush and close at the end of the run                     |

```ts
import type { VxPlugin } from '@vzn/vx'

interface VxPlugin {
  readonly name: string // your package's name: definePlugin reads it
  config?(workspace, ctx): void
  discover?(ctx): { dir; name }[] // directories to make projects
  project?(config, ctx): void
  graph?(nodes, ctx): void
  key?(task, ctx): Record<string, string>
  fingerprint?: { files; affected(change, ctx) }
  schedule?(nodes, ctx): Map<string, number>
  admit?(task, ctx): boolean
  executor?(ctx): TaskExecutor | undefined
  cache?(ctx): CacheLayer | undefined
  telemetry?(ctx): TelemetrySink | TelemetrySink[] | undefined
  commands?: { [verb]: { description: string; run(argv, ctx): number | Promise<number> } }
  setup?(ctx): void | Promise<void>
  teardown?(): void | Promise<void>
}
```

## Workspace and projects

`config` edits the workspace config before vx reads it. Here, two
workers on CI:

```ts
import { definePlugin, type VxPlugin } from '@vzn/vx'

export function ciConcurrency(): VxPlugin {
  return definePlugin(import.meta, {
    config(workspace) {
      if (process.env.CI) workspace.concurrency = 2
    },
  })
}
```

`discover` makes a directory no member glob lists a project; its
`vx.config.ts` gives it tasks:

```ts
import { definePlugin, type VxPlugin } from '@vzn/vx'

export function scriptsProject(): VxPlugin {
  return definePlugin(import.meta, {
    discover: () => [{ dir: 'scripts', name: 'scripts' }],
  })
}
```

`fingerprint` claims a root file the plugin reads. An edit to it makes
`--affected` ask `affected` which projects it touches (`undefined`: all of
them) and re-runs `vx watch`. Fold its bytes into the key with `key`:

```ts
import { readFileSync } from 'node:fs'
import path from 'node:path'
import { definePlugin, type VxPlugin } from '@vzn/vx'

export function toolVersions(): VxPlugin {
  const file = '.tool-versions'
  return definePlugin(import.meta, {
    key: (_task, ctx) => ({ [file]: readFileSync(path.join(ctx.workspaceRoot, file), 'utf8') }),
    fingerprint: { files: [file], affected: () => undefined },
  })
}
```

A lockfile is claimed the same way, and core then leaves it out of every
task's key: [`@vzn/vx-lockfile`](../configure/#lockfiles) keys each project
on its own dependencies.

## Keys and order

`key` adds what your inputs cannot see, like a tool version:

```ts
import { definePlugin, type VxPlugin } from '@vzn/vx'

export function nodeMajor(): VxPlugin {
  const major = process.versions.node.split('.')[0]!
  return definePlugin(import.meta, { key: () => ({ 'node-major': major }) })
}
```

`admit` holds a ready task back. Here, one e2e suite at a time:

```ts
import { definePlugin, type VxPlugin } from '@vzn/vx'

export function oneDatabase(): VxPlugin {
  return definePlugin(import.meta, {
    admit(task, ctx) {
      if (!task.id.endsWith('#e2e')) return true
      return !ctx.running.some((r) => r.id.endsWith('#e2e'))
    },
  })
}
```

`schedule` ranks ready tasks. This one learns from your run history:

```ts
import { defineWorkspace } from '@vzn/vx/config'
import { scheduleHistoryPlugin } from '@vzn/vx-schedule-history'

export default defineWorkspace({ plugins: [scheduleHistoryPlugin()] })
```

## Setup and teardown

`setup` runs once per run, before the first task; a throw stops the run.
`ctx.on` subscribes to the run's events (`onRunStart`, `onTaskStart`,
`onTaskStdout`, `onTaskStderr`, `onTaskComplete`, `onRunStatus`,
`onRunEnd`). `teardown` runs at the end, even on Ctrl-C:

```ts
import { definePlugin, type VxPlugin } from '@vzn/vx'

export function taskLog(): VxPlugin {
  const lines: string[] = []
  return definePlugin(import.meta, {
    setup(ctx) {
      ctx.on('onTaskComplete', (task, outcome) => {
        lines.push(`${task.id} ${outcome.status}`)
      })
    },
    teardown() {
      console.log(lines.join('\n'))
    },
  })
}
```

## A verb and a sink

`commands` adds a verb. A telemetry sink gets each run's summary; do
network I/O in `flush()`, which vx awaits for up to 3 s.

```ts
import { Cache, definePlugin, type VxPlugin } from '@vzn/vx'

export function mcp(): VxPlugin {
  return definePlugin(import.meta, {
    commands: {
      mcp: {
        description: 'serve run history to an AI agent over stdio',
        async run(argv, ctx) {
          const db = Cache.inspect(ctx.cacheDir).dbHandle() // read-only: never resets the index
          void argv
          void db
          return 0 // the exit code
        },
      },
    },
  })
}
```

```ts
import { definePlugin, defineWorkspace, type VxPlugin } from '@vzn/vx'

function hello(): VxPlugin {
  return definePlugin(import.meta, {
    telemetry() {
      return {
        onRunSummary(summary) {
          const { taskCount, failedCount, hitCount, totalDurationMs } = summary
          console.log(`${taskCount} tasks · ${failedCount} failed · ${hitCount} cached · ${totalDurationMs}ms`)
        },
      }
    },
  })
}

export default defineWorkspace({ plugins: [hello()] })
```

## Where a task runs

`executor` returns a `TaskExecutor`: a `name`, an optional `accepts`
that picks its tasks, and `execute`, which runs one command and returns
its exit code and output. A task every executor declines runs here.
Stream output through `onStdout` / `onStderr`, and stop on
`req.signal`, which core aborts on Ctrl-C, an embedder's abort or the
task's `exec.timeout`: core cannot reach a process your executor spawned,
so a stop that misses the shell's children leaves them running after vx
exits. Stopped on the timeout, return a non-zero exit and the task fails
as timed out. An executor still running two seconds after the abort
(`VX_KILL_GRACE_MS`) is abandoned: core settles the task without it.

```ts
import { definePlugin, type ExecuteResult, type VxPlugin } from '@vzn/vx'

export function nice(): VxPlugin {
  return definePlugin(import.meta, {
    executor: () => ({
      name: 'nice',
      accepts: (task) => task.taskId.endsWith('#e2e'),
      async execute(req): Promise<ExecuteResult> {
        const started = performance.now()
        const child = Bun.spawn(['nice', 'sh', '-c', req.command, 'sh', ...req.forwardArgs], {
          cwd: req.cwd,
          env: { ...req.env, ...req.envDefine },
          stdout: 'pipe',
          stderr: 'pipe',
          detached: true, // its own process group, so a stop reaches what the shell starts
        })
        const stop = () => process.kill(-child.pid, 'SIGTERM')
        req.signal?.addEventListener('abort', stop, { once: true })
        const drain = async (from: ReadableStream<Uint8Array>, to: (s: string) => void) => {
          const text = new TextDecoder()
          let all = ''
          for await (const bytes of from) {
            const s = text.decode(bytes, { stream: true })
            to(s)
            all += s
          }
          return all
        }
        const [stdout, stderr] = await Promise.all([
          drain(child.stdout, req.onStdout),
          drain(child.stderr, req.onStderr),
        ])
        const exitCode = await child.exited
        return { exitCode, durationMs: performance.now() - started, stdout, stderr, violations: [] }
      },
    }),
  })
}
```

## Your own cache

Implement core's `RemoteCacheLayer`: `has`, `get` and `put`, plus an
optional `hasMany`. Wrap it in `LayeredCache`, and a remote error is a
miss and one warning per kind of failure, naming the request, the
artifact and the layer's `endpoint` (`download <hash> from <endpoint>
failed: HTTP 500`). Core awaits every call and bounds none: a `get` that
never settles holds its task, and a `put` holds the end of the run. So
give every request a deadline; a timeout is an error, and an error is a
miss:

```ts
import { definePlugin, defineWorkspace, LayeredCache, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'

const deadline = () => AbortSignal.timeout(30_000) // core bounds no call

class AcmeRemote implements RemoteCacheLayer {
  constructor(readonly endpoint: string) {} // printed in warnings: no credentials in it
  async has(hash: string) {
    const res = await fetch(`${this.endpoint}/${hash}`, { method: 'HEAD', signal: deadline() })
    return res.ok
  }
  async get(hash: string) {
    const res = await fetch(`${this.endpoint}/${hash}`, { signal: deadline() })
    if (res.status === 404) return null
    if (!res.ok) throw new Error(`HTTP ${res.status}`) // a throw is a miss
    return { body: res, durationMs: undefined } // streamed to disk
  }
  async put(hash: string, body: Blob) {
    const res = await fetch(`${this.endpoint}/${hash}`, { method: 'PUT', body, signal: deadline() })
    if (!res.ok) throw new Error(`HTTP ${res.status}`) // fetch resolves on a 500
  }
}

function acmeCache(): VxPlugin {
  return definePlugin(import.meta, {
    cache(ctx) {
      const url = process.env.ACME_CACHE_URL
      if (!url) return undefined // decline: the local cache alone
      return new LayeredCache(ctx.localCache, new AcmeRemote(`${url}/artifacts`), {
        policy: ctx.policy,
        onRemoteError: (err) => ctx.warn(`acme-cache: ${err.message}`),
      })
    },
  })
}

export default defineWorkspace({ plugins: [acmeCache()] })
```

## What core refuses

- A `cache` or `executor` hook whose return breaks the contract: the fifteen `CacheLayer` methods, or `execute` and a `name`.
- A `name` on the hooks object: the name is the package's.
- A `ctx.on` hook name core does not know: `ctx.on: unknown hook '<h>' (one of …)`.
- A `config` or `project` edit the loader would refuse from a user, checked after each plugin: `vx.workspace (after plugin '<p>'): …`; a `project` edit names the project's config file, or `<name> (no config file)`, instead.
- A verb that names a core verb, or one plugins of two packages both declare (one package's plugins are one owner; the first declared runs).
- An executor `capacity` that is not a positive integer: `plugin '<p>' returned executor '<e>' with capacity <v>: it must be a positive integer`.

An `admit` that throws, or answers a Promise (it is synchronous), is
reported once and admits from then on. A sink that throws is switched
off for the run, with a warning. So is a
`ctx.on` handler that throws or rejects: its plugin is disabled for the
run and warns once, `[vx] plugin '<p>' threw in <hook>; disabled for this run: <msg>`.

A verb that throws anything but a `UserError` fails in one line, no stack:
`plugin '<p>' failed in command '<verb>': <msg>`.

## Plugins that ship

| Package                     | Hooks it fills                             |
| --------------------------- | ------------------------------------------ |
| [`@vzn/vx-reapi`](../../plugins/vx-reapi/)             | `cache`, `executor` ([CI and remote](../ci/#remote-cache)) |
| [`@vzn/vx-migrate`](../../plugins/vx-migrate/)           | `config`, `discover`, `project`, `fingerprint` (`turbo()`, `nx()`), `cache` (`turboCache()`, `nxCache()`) ([Migrate](../migrate/)) |
| [`@vzn/vx-lockfile`](../../plugins/vx-lockfile/)          | `fingerprint`, `key` ([Lockfiles](../configure/#lockfiles)), `commands` (`vx prune`) |
| [`@vzn/vx-schedule-history`](../../plugins/vx-schedule-history/)  | `schedule`, `admit`, `commands`            |
| [`@vzn/vx-otel`](../../plugins/vx-otel/)              | `telemetry` ([below](#opentelemetry))      |
| [`@vzn/vx-ci`](../../plugins/vx-ci/)            | `config`, `telemetry` ([GitHub Actions](../ci/#github-actions)) |
| [`@vzn/vx-mcp`](../../plugins/vx-mcp/)               | `commands` ([below](#vx-mcp))              |

One plugin can fill several: `@vzn/vx-schedule-history` fills three at once.

## OpenTelemetry

`@vzn/vx-otel` exports every run as OTLP traces, metrics and logs, with no
OpenTelemetry SDK: one trace per run, one span per task. Install it
(`bun add -d @vzn/vx-otel`) and point it at your collector
(`OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`). Without any
endpoint it declines; a signal's own endpoint alone exports that signal.

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { otel } from '@vzn/vx-otel'

export default defineWorkspace({
  plugins: [otel({ serviceName: 'my-monorepo', headers: { authorization: 'Bearer …' } })],
})
```

| Option            | Env var                                | Default                 |
| ----------------- | -------------------------------------- | ----------------------- |
| `endpoint`        | `OTEL_EXPORTER_OTLP_ENDPOINT`          | none                    |
| `tracesEndpoint`  | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`   | `<endpoint>/v1/traces`  |
| `metricsEndpoint` | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`  | `<endpoint>/v1/metrics` |
| `logsEndpoint`    | `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`     | `<endpoint>/v1/logs`    |
| `serviceName`     | `OTEL_SERVICE_NAME`                    | `vx`                    |
| `headers`         | `OTEL_EXPORTER_OTLP_HEADERS` (`k=v,…`) | `{}`                    |
| `metrics`         | `OTEL_METRICS_EXPORTER=none` turns it off | `true`               |
| `logs`            | `OTEL_LOGS_EXPORTER=none` turns it off | `true`                  |
| `timeoutMs`       | `OTEL_EXPORTER_OTLP_TIMEOUT`           | `15000`                 |
| `compression`     | `OTEL_EXPORTER_OTLP_COMPRESSION` (and `_<SIGNAL>_`) | `'none'`   |
| `live`            | none: send each task as it ends        | `true`                  |

| Signal            | Carries                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| `vx.run` span     | `vx.run.task_count`, `vx.run.failed_count`, `vx.run.aborted_count`, `vx.run.hit_local_count`, `vx.run.hit_remote_count`, `vx.run.up_to_date_count`, `vx.run.restored_local_count`, `vx.run.restored_remote_count`, `vx.run.exit_ok`, `vx.cache.upload.*` (remote uploads, once settled), `vx.workspace.id`, `vx.default_branch`, `vx.telemetry.schema` |
| `vx.task` span    | `vx.cache.source`, `vx.cache.restored` (on a hit), `vx.task.hash`, `vx.task.attempts`, `vx.task.blocked_by`, `vx.task.timed_out`, `vx.task.sandbox_violations`, `vx.task.not_ready`, `vx.task.command`, `vx.task.flaky.*`, `vx.cache.stored_*` (on a hit), `vx.task.admission_held_ms`, `vx.task.queued_ms`, `vx.task.input_files`, `vx.cache.miss.change_count` and `vx.cache.miss.changes` (what a miss's key changed since the last saved entry), `vx.cache.artifact_bytes`, `vx.cache.save_ms`, `vx.cache.fetch_ms`; links to the tasks it waited on; `vx.task.retry`, `vx.task.timeout` and `vx.sandbox.violation` events |
| a span per stage  | `startup`, `load configs`, `classify + probe`, `run graph`, … (the `VX_TIMING` stages), with `vx.stage.name` |
| metrics           | `vx.tasks.total`, `vx.tasks.failed`, `vx.tasks.cache_hits`, `vx.tasks.cache_restored`, `vx.tasks.cache_up_to_date`, `vx.run.duration_ms`, `vx.run.time_saved_ms` |
| metrics per task  | `vx.task.duration`, `vx.task.cpu_time`, `vx.task.peak_memory`, `vx.task.time_saved`, `vx.task.admission_held`, `vx.task.queued`, `vx.task.artifact_size`, `vx.task.cache_save`, `vx.task.cache_fetch` at its end; `vx.task.cpu_usage` and `vx.task.memory` each second while it runs; each point names its span as an exemplar |
| a log per task    | the task's output at its end, linked to its span; `vx.log.chars_full` says when it was cut               |
| every resource    | `service.instance.id` (the run id), `host.name`, `host.arch`, `os.type`, `vcs.ref.head.*`, `vcs.repository.*`, `vx.workspace.path` (the workspace root in its repository), and on CI `cicd.pipeline.run.url.full`, `cicd.pipeline.name`, `vcs.change.id` (the pull request), `vx.ci.job`, `vx.ci.attempt`: one key joins a run's traces, metrics and logs |

By default each task is sent as it ends (batched, at most one send a
second), and a log record as the run and each task start, so a dashboard
follows a CI run while it runs; the run span follows at the end.
`live: false` sends it all at the end. A send never holds a task, and one
a collector never answers is cut at the end-of-run deadline.

A failed task sets its span status to `ERROR`. A failed export warns once
and names the reply; a slow collector is cut off after `timeoutMs`, and
the run still exits green.

To see it on your machine, run
[otel-desktop-viewer](https://github.com/CtrlSpice/otel-desktop-viewer), a
single binary that shows traces, metrics and logs:

```sh
brew tap ctrlspice/otel-desktop-viewer
brew install --cask otel-desktop-viewer
otel-desktop-viewer
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 vx run build --all
```

## vx mcp

`@vzn/vx-mcp` lets Claude Code, Cursor, Continue.dev or Copilot ask your
workspace why a task re-ran, read-only, over stdio. Install it
(`npm install -D @vzn/vx-mcp`) and declare it; `vx help` then lists
`vx mcp`. Point your agent at it (`claude mcp add vx -- vx mcp`) and start
the agent inside the workspace; restart it if it lists no vx tools.

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { mcp } from '@vzn/vx-mcp'

export default defineWorkspace({ plugins: [mcp()] })
```

```jsonc
// .mcp.json at the workspace root; Cursor, Continue.dev and Copilot take the same shape
{ "mcpServers": { "vx": { "command": "vx", "args": ["mcp"] } } }
```

| Tool               | Answers                                                          |
| ------------------ | ---------------------------------------------------------------- |
| `listTasks`        | What can I run here?                                             |
| `getCacheStats`    | How big is the cache, and what is today's hit rate?              |
| `getRunHistory`    | Which tasks run, how fast, how often they fail or flake?         |
| `explainCacheKey`  | What is the cache identity of `pkg#build`?                       |
| `whyDidThisRerun`  | Why did `pkg#test` re-run instead of hitting?                    |
| `getTaskLog`       | What did one task print (`vx last --log`)                        |
| `pruneCache`       | Evict cache entries (`vx cache prune`), dry run by default       |
| `planInit`         | What `vx init` would write (`vx init --dry`), nothing written    |
| `searchDocs`       | Search the reference offline (`vx docs`)                         |
| `checkLock`        | The config lock audit (`vx lock --check`)                        |
| `getConfig`        | A project's or task's resolved config (`vx show`)                |
| `getFailures`      | Why did the run fail: each task's output and the files it names  |
| `getWorkspaceInfo` | What `vx info` says: versions, plugins, cache, sandbox           |
| `runTasks`         | Run these tasks: the exit code and the run summary               |
| `planTasks`        | What would run and why: the `vx run --dry=json` plan, nothing run |

Only `runTasks` runs anything, and it runs `vx run --format json`
itself, so the CLI's selection, refusals and sandbox apply. The server speaks
MCP in about 230 lines, with no dependencies.

---

# Sandboxing tasks

> Run a task where only the workspace files you declared exist, so an undeclared input cannot hide in the cache.

Prove a task reads only what it declares.

## Steps

1. Add `sandbox` to the task's `exec`. `sandbox: {}` allows nothing in the workspace, not even the package. Outside the workspace root (`~/.cache`, `/etc`) reads are open and fold into no key: declare what the output depends on as a key input. The credential stores under home (`~/.ssh`, `~/.aws`, `~/.npmrc` and the like) are the exception: denied unless `allow.read` names one.
2. Grant the package: `allow: { read: ['.'] }`. Its `node_modules` is readable already. Another package of yours, linked there, is readable when the task depends on one of that package's command tasks; an uncached task reads every linked package.
3. Grant each output directory in `write`, and each host in `network`. The sandbox does not read `cache`: declare both.
4. Run the task. An undeclared read or write fails it and names the path.
5. Declare that path, or silence a noisy tool's path with `ignore`.

## Config

```ts
// packages/app/vx.config.ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    build: {
      exec: {
        command: 'vite build',
        sandbox: {
          allow: {
            read: ['.', '~/.cache/ms-playwright'],
            write: ['dist/**'],
            network: ['registry.npmjs.org'],
          },
          deny: { network: ['telemetry.example.com'] },
          ignore: { write: ['*.bun-build'] },
        },
      },
      cache: { inputs: { files: ['src/**', 'index.html'] }, outputs: { files: ['dist/**'] } },
    },
  },
})
```

## What you can grant

`allow` takes every key below. `deny` takes only `network`. Domain lists are one union per run, which every sandboxed task reaches; `deny.network` is refused to every sandboxed task. `ignore` takes `read`, `write`, `systemInfo` and `network`, as patterns, and refuses the rest.

| Key            | Grants                                                            |
| -------------- | ----------------------------------------------------------------- |
| `read`         | paths or globs: package-relative, absolute or `~/`                |
| `write`        | paths or globs; a directory ends in `/` or is a glob (`dist/**`)  |
| `network`      | `true`, or a list of domains (`*.sentry.io`)                      |
| `localBinding` | bind localhost ports (macOS; Linux needs no grant); a list (`[3000]`) makes them reachable from outside |
| `unixSockets`  | `true`, or socket paths (Linux: any path)                         |
| `systemInfo`   | sysctl names a tool probes (`vfs.disk-space`)                     |
| `machLookup`   | macOS services (`com.apple.FSEvents`)                             |
| `pty`          | a terminal                                                        |
| `gitConfig`    | write the repository's `.git/config`, for this task only          |

## The boundary is the project

A task never reaches another package or a root file you did not grant,
bar the linked packages of step 2.
That wall is silent. An undeclared touch of the task's own files fails the
task, and a failed task is never cached. A write refused past the wall
(a tool filling its cache in your home) is named beside a failed task,
with the directory to grant; under the host's temp directory it names
`$TMPDIR` instead, the empty temp directory the task has of its own.

## Requirements & platform support

- **Linux:** `bubblewrap` (`bwrap`), `socat` and `ripgrep` (`rg`); `strace` to fail and name an undeclared read. `vx info` says if your host can.
- **macOS:** the system sandbox. Its report can miss a record under load; the denial never does.
- **Windows:** under WSL.

## What can't be sandboxed

- A group task: it has no command.
- A task that itself sandboxes, on macOS (a sandbox cannot nest).

A persistent task (a dev server) runs inside the same walls, but nothing
traces it: a read outside its grants is refused as missing (`ENOENT`) and
named nowhere, and step 4's failure does not happen. One that exits
failing before it is ready says so beside its failure; run its command
as a one-shot sandboxed task to see what it was refused.

## Common problems

- **`write /proc/self/uid_map: Operation not permitted`.** You are root in a container. Run as a normal user, or set `weakerWhenNested: true` on every sandboxed task.
- **`File exists` or `Not a directory` from the task's own `mkdir`.** A write grant with no trailing slash is a file (`mkdir -p coverage` reads the first, `mkdir -p coverage/lcov` the second). Write `'coverage/'`.
- **A file the task creates later is refused on Linux** ("Read-only file system"). A glob with a file part (`*.log`, `gen/**/*.ts`) is matched when the task starts. Grant its directory (`'gen/'`; `'dist/**'` grants the directory too). A temp directory the tool makes and removes in the package (`.*.tmp/**`) needs only the glob: nothing written there is kept.
- **`bun build --compile --target=…` fails on a fresh machine** ("Network error downloading executable", then "Failed to extract executable"). Bun fetches the target's runtime from npm into its cache. Grant `network: ['registry.npmjs.org']` and `write: ['~/.bun/install/cache/', '.*.tmp/**']`.
- **`read packages/ui through packages/app/node_modules/@x/ui, and its key folds no task of @x/ui`.** The task imports a sibling its key never sees. Depend on a command task of it (`dependsOn: ['^source']`, or `^build`), or grant and key the files yourself.

---

# Troubleshooting

> What vx printed, what it means, and the fix.

The messages and surprises of a first run, each with its fix. Problems
specific to one guide stay there: [Sandboxing](../sandboxing/#common-problems),
[CI](../ci/#common-problems), [Migrate](../migrate/#common-problems).

## vx printed an error

| vx prints                                          | Fix                                                                     |
| -------------------------------------------------- | ----------------------------------------------------------------------- |
| `not inside a project`                             | Run from a package directory, or pass `--all` or `--filter <pattern>`.  |
| `… has a vx config but no package.json — skipped` | Add a `package.json` with a `"name"` to that directory: vx names a project by it. |
| `vx requires git: … is not inside a git work tree` | Run `git init` at the workspace root.                                   |
| `vx requires git: failed to spawn 'git'`           | Install git.                                                            |
| `--affected has no base here`                      | Fetch the history (`fetch-depth: 0` in CI), or pass `--affected=<ref>`. |
| `… has unknown field "<key>"`                      | A typo, or a Turbo or Nx key: the message lists the fields vx allows.  |
| `Cycle detected in task graph`                     | Remove one `dependsOn` edge of the loop it prints.                      |
| `depends on … but no such project or task is declared` | Fix the name, or declare that task in that package.                 |
| `no projects declare task(s)`                      | A typo, or no config declares it: `vx show` lists every task.           |
| `unknown flag`                                     | `vx run --help` lists the flags.                                        |
| `no projects matched filter(s)`                    | A typo: the message suggests the closest name. `vx show` lists every project. |
| `waiting for another vx run (pid …)`               | One run per workspace at a time: it starts when that one ends. Stop it, or wait. |
| `vx: command not found`                            | A local install is not on PATH: run `npx vx` or `bunx vx`.              |

## vx did something unexpected

- **Only one package ran.** `vx run build` runs the package you are in
  and what it depends on. Add `--all`.
- **`0 tasks · build has no command in these projects`.** No selected
  package gives `build` a command, so vx ran only its default group.
  Give `build` an `exec.command` in the packages that build.
- **A task runs every time.** It has no `cache` block. `vx init` leaves
  a TODO with the block to add.
- **A task hit after you changed a file.** The file is not in
  `cache.inputs.files`. `vx why <project#task>` shows what the key saw;
  [`exec.sandbox`](../sandboxing/), with reads granted no wider than
  the inputs, refuses that read and names it.
- **`cache.inputs matched no files`.** The globs name nothing in the
  project, so the key ignores its source. Fix the paths; they are
  relative to the project directory.
- **`cache.outputs matched no files`.** The task wrote elsewhere, so a
  hit restores nothing. Point `outputs.files` at what the task writes;
  a sandboxed task also needs `exec.sandbox.allow.write` for it.
- **`not ready after …: waiting for a line matching`.** A persistent
  task's `readyWhen` has not matched its output yet. Fix the pattern,
  or set `exec.timeout` to bound the wait.
- **A task re-ran and you do not know why.** `vx why <project#task>`
  names the part of the key that changed.
- **A variable is empty inside the command.** Past a small essential
  allowlist (`PATH`, `HOME`, `CI` and a few more), vx passes only what
  you list: add it to `exec.env.passThrough`
  ([Environment variables](../configure/#environment-variables)).
- **`dist/` is empty after `tsc -b`.** tsc's build info sits outside
  `dist/`; add `tsconfig.tsbuildinfo` to `outputs.files`
  ([Quickstart](../../quickstart/#common-problems)).

## Platforms

- **Windows:** use WSL.
- **Alpine:** not supported; vx's Linux binary needs glibc.
- **From source:** Bun 1.4 or later. The binary needs neither Bun nor Node.

---

# Upgrading to 1.0

> Every breaking change before 1.0, newest first, and what to do about it.

<!-- Generated by packages/vx/scripts/upgrading.ts from git log; do not hand-edit. -->

Before 1.0 a release may break what the last one did. Each heading below
is a breaking commit (`type!:` or a `BREAKING CHANGE:` footer), newest
first; its text is that footer: what changed and what to do.

## cache: one entry_inputs row per entry, not per component

SCHEMA_VERSION v34. The first run drops the local index once; artifact files stay and are re-adopted on their next hit.

## cache: store small artifacts inline in the store index

SCHEMA_VERSION v33. The first run drops the local index once; artifact files stay and are re-adopted on their next hit.

## vx-reapi: connect a bare endpoint with TLS, as Bazel does

a vx-reapi endpoint with no scheme now uses TLS; a plaintext server needs grpc:// or tls: false.

## cache: replay stderr on cache hits

every cached task misses once after upgrading to vx-cache-v42.

## cache: drop unread store fields, fix chunking comments

Cache.storeFallback and Cache.storeMoved are removed; nothing read them.

## cache: clean through an in-project output link, bump to v41

every cached task misses once after upgrading to vx-cache-v41.

## workspace: refuse env names sh would drop

exec.env define and passThrough names must be shell identifiers ([A-Za-z_][A-Za-z0-9_]*); other names are refused at load.

## config: accept readonly lists in every config array field

config array fields are typed readonly; code that mutates a resolved config list must copy it first.

## workspace: refuse a tag that --filter tag: cannot name

a tag that --filter tag: cannot select (`**`, an upper-case glob such as `A*`) is now refused at config load.

## cache: dry prune on an earlier index previews the store

Cache.orphansBeforeReset is gone; open a Cache in 'preview' mode instead.

## cache: bump CACHE_VERSION to vx-cache-v40

every cached task misses once after the upgrade.

## vx-ci: rename @vzn/vx-github to @vzn/vx-ci

import github() from '@vzn/vx-ci' instead of '@vzn/vx-github'.

## cache: keep artifacts when the store schema changes

Cache.getMany and CacheLayer.getMany take an optional per-hash get context; a layer that ignores it is unchanged.

## cache: share cache entries across workspaces

SCHEMA_VERSION v32; existing entries miss once.

## cache: count restored and up-to-date hits everywhere

SCHEMA_VERSION v30 -> v31; an older index is dropped on first open and its artifacts are left for `vx cache prune`. WhyDidThisRerun's thisRun / previousRun, RunSummaryRow, InvocationDetail, RunSummaryRecord and CacheStats gain fields.

## orchestrator: drop the end-of-run failure recap

src/orchestrator/failure-recap.ts leaves the package, with formatFailureRecap and DefaultLogger.failureRecap.

## cache: key the blob-size verdict by the index file's hash

SCHEMA_VERSION v29 -> v30; an older index is dropped on first open and its artifacts are left for `vx cache prune`.

## vx-migrate: run every Nx executor through nx-exec

a migrated config writes nx-exec lines where it wrote jest, vite, tsc, node and other executor commands.

## workspace: keep existing configs in vx init, write the rest

`vx init` where configs already exist exits 0 (kept) instead of 1 (refused).

## vx-reapi: inline the wire-only keys

@vzn/vx-reapi's plugin-api record no longer lists the WireOnly type (it was never exported; ReapiPluginOptions is unchanged in shape).

## vx-reapi: refuse the wire-form options reapi() ignored

reapi() no longer accepts onWarn, tlsCaPem, tlsClientCertPem or tlsClientKeyPem; use tlsCertificate, tlsClientCertificate and tlsClientKey (PEM files).

## vx-reapi: stop exporting the wire and Merkle internals

@vzn/vx-reapi no longer exports ReapiClient, reapiExecutor, acceptsTask, globToOutputPath, outputPathSets, buildInputTree, canDigest, decodeDirectory, decodeTree, digestWith, encodeAction, encodeCommand, encodeDigest, encodeDirectory, encodeNodeProperties, sha256, assertBunSupportsChunking, CHUNK_BYTES, SAFE_CHUNK_BYTES, MIN_BUN, COMPRESSOR, DIGEST_FUNCTION, OUTPUT_DIRECTORY_FORMAT or the wire and Merkle types.

## vx-migrate: export only the four plugins

@vzn/vx-migrate no longer exports mapTurboWorkspace, mapNxWorkspace, nxExecCommand, parseNxGraph, readNxJsonFacts, TurboRemoteCache, NxRemoteCache, resolveTurboCacheConfig, resolveNxCacheConfig, turboRemoteAccess, artifactTag, VERCEL_API, MIN_SIGNATURE_KEY_LENGTH, migrateCmd, parseMigrateArgs or their types.

## vx-lockfile: stop exporting the parser namespaces

@vzn/vx-lockfile no longer exports the pnpmLock, bunLock, npmLock and yarnLock namespaces.

## vx-otel: stop exporting the OTLP builders

@vzn/vx-otel no longer exports buildLogsRequest, buildMetricsRequest, buildTraceRequest, resourceAttributes, runSpanAttributes, taskSpanAttributes, taskStatusCode, SEMCONV, VX_ATTR or the KeyValue, OtlpLogRecord and OtlpSpan types.

## vx-github: stop exporting the Checks API helpers

@vzn/vx-github no longer exports buildCheckRunPayload, clampSummary, postCheckRun, resolveCheckRunEnv or the CheckRunEnv type.

## plugins: refuse a plugin option value of the wrong kind

refuseUnknownOptions(factory, options, known) takes a PluginOptionKinds<Options> record instead of a list of option names (released in 0.0.397). Pass each option with its kind; the type checker derives the kinds from the options interface.

## drop native Windows code paths

tasks no longer receive SYSTEMROOT, APPDATA and the other Windows essential env vars; native Windows is unsupported.

## vx: type generated configs from the @vzn/vx/config entry

vx init and vx-migrate now write `import type { ProjectConfig } from '@vzn/vx/config'`, and @vzn/vx exports ./config.

## vx-migrate: adopt Turbo and Nx only

lage(), wireit(), workspaceScripts(), the lage-worker bin and vx-migrate --from lage|wireit|scripts are removed.

## vx-migrate: drop moon support

moon(), mapMoonWorkspace and vx-migrate --from moon are removed.

## cli: say in vx info when the sandbox runs untraced

vx info's JSON and vx mcp's getWorkspaceInfo gain sandbox.untraced (string | null).

## cli: map a workspace root's repo-wide scripts in vx init

No migration note.

## cli: drop vx init's readiness note where nothing waits

No migration note.

## vx-migrate: cache an output no tracked top-level entry matches

No migration note.

## vx: launch the npm binary from CommonJS, not ESM

No migration note.

## vx-migrate: cache an untracked **/dist/** output

No migration note.

## config: take a bare --affected's base from affectedBase

No migration note.

## vx-migrate: map Turbo task tags to nothing

the turbo-nx-support record moves turbo.json tasks.*.interruptible from not-supported to not-applicable.

## vx-mcp: take a run id prefix in whyDidThisRerun

@vzn/vx packs src/orchestrator/run-id.ts in place of src/cli/run-id.ts, and vx-mcp's whyDidThisRerun runId description now names a prefix.

## vx-migrate: run Turbo root tasks with no root vx.config

PLUGIN_HOOKS gains `discover` after `config`.

## config: type-check unknown keys in defineWorkspace

defineWorkspace rejects keys the schema does not declare at type-check time. vx already refused them at load.

## config: type-check unknown keys in defineProject

defineProject rejects keys the schema does not declare at type-check time. vx already refused them when it loaded the config.

## cli: remove the vx stats alias before 1.0

`vx stats` is removed; run `vx info`, which prints the same report.

## rename to @vzn/vx; drop run: { tasks } wrapper from config

No migration note.

---

# The diagram kit

> The site's build-time SVG picture component and the data it draws from, each part rendered with the toy monorepo.

import Diagram from '../../../components/guide/diagram/Diagram.astro'
import { lanes } from '../../../components/guide/diagram/diagram.js'

`Diagram` draws one value of `Picture`: boxes, arrows between them, notes
and frames. The landing's picture uses it; the pages imported from
`packages/vx/docs` still draw with Mermaid. It renders SVG
into the page when the site is built, so the picture is there with no
script, in both themes, and at any width. The data is documented in
`packages/vx-docs/src/components/guide/diagram/README.md`; this page renders
each part, and `packages/vx-docs/tests/diagram-kit.test.ts` reads what it
built.

## Boxes and arrows

<Diagram
  name="kit-graph"
  label="The toy monorepo's builds: utils#build before ui#build and api#build, both before app#build."
  caption="Tones: accent is the one the text is about, muted is skipped, danger is wrong."
  height={250}
  boxes={[
    { id: 'utils', x: 225, y: 10, w: 150, label: 'utils#build', tone: 'accent' },
    { id: 'ui', x: 60, y: 100, w: 150, label: 'ui#build' },
    { id: 'api', x: 390, y: 100, w: 150, label: 'api#build', sub: 'cache hit', tone: 'muted' },
    { id: 'app', x: 225, y: 190, w: 150, label: 'app#build', tone: 'danger' },
  ]}
  arrows={[
    { from: 'utils', to: 'ui' },
    { from: 'utils', to: 'api' },
    { from: 'ui', to: 'app', label: '^build' },
    { from: 'api', to: 'app', dashed: true },
  ]}
/>

## Timelines

<Diagram
  name="kit-timeline"
  label="Two workers: worker 1 runs utils#build from 0 to 2 s, ui#build to 5 s and app#build to 7 s; worker 2 runs api#build from 2 to 4 s."
  caption="lanes() turns workers and their bars into boxes, one row per worker."
  height={130}
  {...lanes(
    [
      {
        name: 'worker 1',
        bars: [
          { start: 0, end: 2, label: 'utils', sub: 'build', tone: 'accent' },
          { start: 2, end: 5, label: 'ui', sub: 'build' },
          { start: 5, end: 7, label: 'app', sub: 'build' },
        ],
      },
      { name: 'worker 2', bars: [{ start: 2, end: 4, label: 'api', sub: 'build' }] },
    ],
    { x: 100, y: 16, scale: 68, row: 56, h: 48 },
  )}
/>

## Notes and frames

<Diagram
  name="kit-frame"
  label="Inside a frame, app#build reads src/index.ts. banner.txt sits outside it."
  caption="A frame groups boxes; a note says what a picture cannot draw."
  height={200}
  frames={[{ x: 6, y: 10, w: 380, h: 150, label: 'a frame', tone: 'link' }]}
  boxes={[
    { id: 'app', x: 26, y: 80, w: 150, label: 'app#build', tone: 'accent' },
    { id: 'src', x: 216, y: 80, w: 150, label: 'src/index.ts' },
    { id: 'banner', x: 440, y: 80, w: 150, label: 'banner.txt', tone: 'ok' },
  ]}
  arrows={[{ from: 'app', to: 'src', label: 'reads', tone: 'link' }]}
  notes={[{ x: 300, y: 188, text: 'a note, in the tone it needs', tone: 'danger' }]}
/>

---

# Try it

> vx's own planner in your browser, on four small packages. Edit a file, the environment or a config, run, and read which tasks would run and why.

import Playground from '../../components/demos/Playground.astro'

This is vx's own planner, running in your page on four small packages.

Edit a file, the environment or a config, press **Run**, and read which tasks
would run and why.

<Playground />

The planner plans: it runs no command and writes no file.

On your own repository, after the [quickstart](../quickstart/), the same plan
is one command:

```sh
vx run build test --all --dry
```

---

# @vzn/vx-ci

> GitHub Actions integration for @vzn/vx — a

GitHub Actions integration for [`@vzn/vx`](https://github.com/vznjs/vx) — a
telemetry plugin that writes every `vx run` as a **job summary** on the
workflow run page.

```sh
npm install -D @vzn/vx @vzn/vx-ci   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
```

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { github } from '@vzn/vx-ci'

export default defineWorkspace({
  plugins: [github()],
})
```

That's the whole setup. On a GitHub Actions runner (`GITHUB_STEP_SUMMARY`
set) every `vx run` appends a summary block, on its own line after
anything already written in the step: verdict headline, stats
(tasks / executed / cache hits / duration), failures called out above the
per-task table with their exit code, the signal an exit above 128
stands for (`exit 137 (128 + SIGKILL)`, as the run's own frame and
`vx last` say it), a timeout as `timed out, exit 143`, a persistent task
that never became ready as `never ready (timed out)`, a sandboxed task's
violation count, and the tasks each failure blocked. A footer line
names the vx version, the command (what follows `--` counted, not
quoted), tasks passed and outputs restored.
Anywhere else — laptops, other CI — the plugin **declines** and costs
nothing, so declaring it unconditionally is safe.

## Options

The options type is `GithubPluginOptions`; `renderJobSummary` renders the
summary lines the plugin posts (the site's CI guide sample is rendered from it).
The package exports `github`, `renderJobSummary` and the types `GithubPluginOptions`
and `FetchFn`; nothing else. `fetchFn`, `append` and `sizeOf` are test seams:
they replace the Checks API transport, the summary writer and its size probe.

```ts
github({
  summaryFile: '/path/override.md', // default: $GITHUB_STEP_SUMMARY
  title: 'build & test', // default: 'vx run'
  checks: true, // default: on with GITHUB_TOKEN; true warns when it is missing, false opts out
  checkName: 'ci', // default: 'vx', the check run's name
  cacheScope: false, // default: on; scope remote cache writes by ref
})
```

## Cache scope

On Actions (`GITHUB_ACTIONS=true`), when `vx.workspace.ts` sets no `cacheScope`, the plugin's
`config` stage sets it from the ref (`GITHUB_REF`, `GITHUB_REF_NAME`, and
the default branch from the `GITHUB_EVENT_PATH` payload): a push to the default branch stays
trusted (reads and writes the task keys), a pull request becomes
`pr-<n>` (so is a `pull_request_target`, `issue_comment` or `workflow_run`
run on a PR's behalf, by `GITHUB_EVENT_NAME`, though its ref is main's) and any other branch or tag `ref-<name>`, which read their
own keys, then the trusted ones, and write only their own. A PR never writes what main
reads. `VX_CACHE_SCOPE` or a `cacheScope` in `vx.workspace.ts` overrides it. This is a client-side convention: the real boundary is a cache
token the server limits, so give PR jobs one that cannot write the
trusted keys (`docs/security.md` § Cache poisoning).

## How it works

`github()` contributes one observe-only telemetry sink through vx's
`telemetry` seam. It receives the versioned `RunSummaryRecord` at run end
and renders + appends the markdown in `flush()` — it holds no run handle,
streams no per-event records (`wants: []`), and a slow or failing write can
never fail or stall the run (core's crash-isolation + flush deadline).

Core's manual path still exists without this plugin:
`vx run --report=markdown --report-file "$GITHUB_STEP_SUMMARY"` writes a
plain table. The plugin's summary is richer (verdict, stats, failure
callouts) and automatic on every run.

## The PR check run

With `GITHUB_TOKEN` in the environment (plus `GITHUB_REPOSITORY` /
`GITHUB_SHA`, both set by the runner) the plugin also creates one
**completed check-run** on the built commit — conclusion `success`,
`failure`, or `cancelled` for a run a signal stopped with nothing
failed (a cancelled job), its output the same summary markdown — so the verdict shows in
the PR's checks list, not just the workflow page. The workflow must grant
the permission:

```yaml
permissions:
  checks: write
```

Without the token the check is silently skipped (the job summary still
writes); pass `checks: true` to warn instead, or `checks: false` to opt
out entirely; a value that is not a boolean is refused. GitHub's own blips (`502`, `503`, `504`, a dropped
connection) are retried twice, 200 then 800 ms apart, until the flush deadline, which warns the last answer. A failed POST warns and never fails the run — a `403` says
to check `permissions: checks: write`, a rate limit (`429`, or a `403`
saying so) says so and is not retried — and a slow API costs the run
nothing past core's end-of-run flush deadline. On `pull_request` events
`GITHUB_SHA` is the merge commit; GitHub still surfaces the check on the
PR.

On GitHub Enterprise Server the POST goes to `GITHUB_API_URL`. A host
behind a private CA is trusted through `NODE_EXTRA_CA_CERTS` (a PEM
file of the CA); an untrusted certificate is not retried and its warning
names that variable.

Both artifacts are bounded by GitHub's own limits, because exceeding
either loses the whole thing rather than its tail: the check-run output
at 65 535 bytes, the job summary at 1 MiB counted in bytes (about 19 000 task rows; fewer when task names are not ASCII), cut on a character boundary. GitHub's cap is the step's whole summary file, so the page fits in what earlier writers in the step left; with no room it is skipped with a warning.
Past either, what is written ends with a line saying it was truncated.

---

# @vzn/vx-lockfile

> Lockfile plugins for @vzn/vx: pnpm(), bun(), npm() and yarn(). Each keys every task on its own project's resolved dependency closure from the package…

Lockfile plugins for [`@vzn/vx`](https://github.com/vznjs/vx): `pnpm()`, `bun()`, `npm()` and `yarn()`. Each keys every task on its **own project's resolved dependency closure** from the package manager's lockfile, not on the whole file. `pnpm update foo` (or `bun add`, `npm install`, `yarn up`) re-keys exactly the projects that reach `foo` — through their dependencies, transitively, and through workspace links — and `vx run … --affected` selects the same projects. Zero dependencies: Bun's own YAML and JSONC parsers, and a classic-yarn reader.

Without a plugin, core folds the whole lockfile into the workspace fingerprint that every cache key sees, so one install invalidates every task in the workspace.

## Usage

```sh
npm install -D @vzn/vx @vzn/vx-lockfile   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
```

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { pnpm } from '@vzn/vx-lockfile' // or bun, npm, yarn

export default defineWorkspace({
  plugins: [pnpm()],
})
```

That is the whole setup. The plugin **claims** its lockfile (`VxPlugin.fingerprint`), so core leaves it out of the workspace fingerprint, and its `key` hook folds one digest per project. `vx why <task>` names the material as `plugin @vzn/vx-lockfile/pnpm` (or `/bun`, `/npm`, `/yarn`).

| Option  | Values                               | Meaning                                                                                                                                                                                        |
| ------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope` | `'project'` (default), `'workspace'` | `project`: each task folds its own project's closure. `workspace`: the whole file, as core folds it — the coarse key through the plugin, for a workspace not yet ready to trust the precision. |

## What a project's digest covers

Every package the project can reach, by resolved identity (name, version, integrity), and under bun and npm by the name it installs under, not where it sits, so a re-hoist of one version re-keys nothing, plus the install-wide material every project folds — and **the root package's own closure**. The root's `dependencies` and `devDependencies` reach every task: their bins run from the root `node_modules/.bin`, which vx puts on every task's PATH, and Node's resolution walks up to the root `node_modules` (`@types/*`, a plugin a root tool's config names). So a root devDependency bump (`pnpm add -Dw oxlint@next`) re-keys every project and `--affected` selects every project; a package only project A reaches still moves only A. A root `workspace:` dependency folds that package's closure into every project too. Per manager:

- **pnpm** (`pnpm-lock.yaml`, lockfile v5, v6, v9): importers → snapshots, transitively; each package by name, version **and resolved peers** (`foo@1(react@18)` is not `foo@1(react@19)`), resolution and any `patchedDependencies` entry; `link:` folds the linked importer's reach, and a `file:` directory dependency folds its own closure (v9 keys it `name@file:…`, v5/v6 by the bare `file:…`); every other top-level field but `overrides` and the catalogs, whose effect is the snapshot an importer reaches (`settings`, `packageExtensionsChecksum`, `pnpmfileChecksum`, `ignoredOptionalDependencies`, v6's `onlyBuiltDependencies`, and any field pnpm adds later) and the lockfile version into every project. A multi-document lockfile (pnpm 10.x and 11 write the env lockfile — `configDependencies`, the package manager's own install — ahead of the project's) reads its last document as the lockfile and folds the ones before it into every project.
- **bun** (`bun.lock`): Bun's hoisted layout — a dependency `d` of the package at path `p` is `p/d` when that key exists, else the nearest ancestor's, else the root's, so a nested version counts for the package it is nested under and no other; `workspace:` entries fold the linked package's reach; each `patchedDependencies` entry and the CONTENT of its patch file (bun.lock records only its path) with the package it patches, so a patch edit re-keys only the projects reaching it; every top-level field but `workspaces`, `packages`, the catalogs, `overrides` and `patchedDependencies` (`trustedDependencies`, and any field Bun adds later), and any patch naming no entry, into every project — a catalog bump reaches only the projects whose `catalog:` dependency resolves anew, through the `packages` entry it installs.
- **npm** (`package-lock.json`, lockfileVersion 2 and 3): the `packages` map — `p/node_modules/d`, then each ancestor directory's (a workspace nested in another's directory resolves through the outer one's `node_modules`, as Node does), then `node_modules/d`; a `link: true` entry folds its target workspace's reach; root `overrides` reach a project through the entries they force (npm 10 does not write them to the lockfile). Version 1 (npm 6) has no `packages` map and is refused.
- **yarn** (`yarn.lock`): berry (yarn 2+) resolves `name@npm:range` descriptors to entries, workspaces included, each entry folding every field but its dependency lists (so the root workspace's `dependenciesMeta` reaches every project), `__metadata`'s `version` and `cacheKey` into every project. A Yarn 4 catalog dependency (`catalog:`, `catalog:<name>`) is recorded as that literal and its range lives in `.yarnrc.yml`, so it reaches every entry of its package: a bump of any of them re-keys the workspace. So does a descriptor the file does not key: a root `resolutions` override (to a `patch:`, or another range) leaves the original descriptor out of `yarn.lock`, and the entry installed in its place is reached through the package's name, so a patch edit re-keys the workspaces that depend on it. A path range (`portal:`, `file:`, `link:`) reaches the entry keyed bound to the package naming it (`::locator=…`), not another workspace's of the same name. Yarn's builtin compat patches (`resolve`, `typescript`, `fsevents`) are reached too: the workspace asks for the plain descriptor, and the patched entry is the one Yarn installs. `.yarnrc.yml` itself is in core's workspace fingerprint, so a catalog edit re-keys every project, as a `pnpm-workspace.yaml` edit does. Classic (yarn 1) records no workspaces, so it yields one digest for the root that every project folds — coarse, and honest about what the file records.

A project the lockfile has no entry for folds the root's digest alone — the only `node_modules` it can resolve from. A phantom dependency (imported, never declared by the project or the root — a sibling's package hoisted to the root) is not in any closure; declare it.

A lockfile the parser cannot read **refuses the run**, naming the file, the reason and the install that regenerates it. That is deliberate: the alternative to reading the lockfile is keying on nothing, and a key that is missing material is a stale hit waiting to happen. Under `--affected` the refusal also says which side could not be read — the working tree's copy, or the one at the base ref (a lockfile-migration commit hits the second). A lockfile holding git merge conflict markers is refused the same way: it names two installs at once, and yarn classic's format parsed one side of it without a word.

## Cost

The claim, the per-project key, the memo and the `--affected` diff are core's `lockfileClaim`; this package is the parsers, and they are internal: it exports `pnpm`, `bun`, `npm`, `yarn` and `LockfileOptions`. A lockfile is parsed **once per content**: the digests are memoised under the cache dir (`lockfile-claims/<file>.json`) by the file's xxh3 and the claimant, so a warm run pays one read, one hash and one small JSON read — never a parse — and the read happens once per run, not per task. The digest is one hash per strongly connected component of the dependency graph (lockfiles carry cycles), children first, so a 1000-importer / 3000-package lockfile digests in ~20 ms when it does change.

## `--affected`

`vx run test --affected=origin/main` after a lockfile change used to select every project. With a plugin declared at `scope: 'project'`, core hands it the lockfile at the base ref and in the working tree; it digests both and names the projects whose digest moved. At `scope: 'workspace'` a change still selects every project. A lockfile that appeared or was deleted still selects everything — every project's `node_modules` is in question.

## `vx prune`

Declaring any of the four plugins adds `vx prune` (the `commands` seam): the workspace cut to some projects and their transitive workspace dependencies, for a Docker build that installs and builds only what it ships — `turbo prune`.

```sh
vx prune <project...> [--out-dir <dir>] [--docker] [--production]
```

The out dir (default `out/`, relative to the cwd) gets the root `package.json` with `workspaces` rewritten to the subset's dirs (a glob character in a dir name bracketed, `a[1]` → `a[[]1]`, so the pattern matches that dir alone), `pnpm-workspace.yaml` with `packages` rewritten (every other key as written), each lockfile at the root **pruned** to what the subset installs, the install config (`.npmrc`, `.yarnrc.yml`, `.pnpmfile.cjs`, `bunfig.toml`, `.nvmrc`, `.node-version`, the patch files `patchedDependencies` names, Yarn's `yarnPath` and plugins), `vx.workspace.*`, the root `vx.config.*`, and each project directory less `node_modules`, `.git`, `.vx` and `.turbo`. A workspace package a copied vx config imports (a local plugin) comes along with its closure: the config loads before any task. A relative config import that leaves the subset is warned about. `--docker` writes `json/` — the root install files and each project's `package.json`, the cacheable install layer — and `full/`, everything:

```dockerfile
COPY out/json/ .
RUN bun install --frozen-lockfile
COPY out/full/ .
RUN bunx vx run app#build
```

The pruned lockfile is the source with whole entries cut, in the package manager's own layout, so it installs with a frozen lockfile (`bun install --frozen-lockfile`, `pnpm install --frozen-lockfile`, `npm ci`, `yarn install --immutable`) and a line only another project reaches no longer busts the install layer. Kept: the root's and each kept workspace's entries and every package they reach — through Bun's and npm's hoisted walk (a package stays at the path it held; nothing is re-hoisted), pnpm's snapshots, Yarn's descriptors. Workspace-wide fields (catalogs, overrides, patches, settings, `trustedDependencies`) stay whole: the root manifest still names them. pnpm's env document stays whole. Yarn classic records no workspaces, so its walk starts at each kept manifest's dependencies.

`--production` follows no `devDependencies` edge between workspace packages: a package only a dev dependency reaches is left out (`turbo prune --production`). Each kept manifest, the root's too, loses the `devDependencies` entries naming one, its field gone when it empties, and every lockfile drops the same entries: bun's and npm's workspace records, pnpm's importer (`{}` when it empties), Yarn berry's `workspace:` link in the workspace entry; Yarn classic walks the stripped manifests. A name another field also holds is installed in production and stays. Third-party dev dependencies stay in the lockfile: an install with `--production` / `--omit=dev` / `--prod` skips them. For the stage that runs a built app, not the one that builds it.

Refused, with the reason: an out dir that is or contains the root, one inside a copied project, one that already has content; a project name the workspace lacks (the root is always kept); `bun.lockb` without `bun.lock` (binary — `bun install --save-text-lockfile`). A `file:` or `link:` dependency outside every copied project is not copied. One plugin or four, there is one `prune`: it prunes every lockfile at the root.

## Testing

`bun test` covers each parser's digests (transitive bumps, nested versions, workspace links, peer suffixes, patches, install-wide knobs, cycles, key order, aliases, refusals) and `vx run` / `vx why` / `--affected` end to end. `vx prune` is pinned on lockfiles each package manager wrote (bun 1.4, pnpm 10, npm 10, yarn 1 and 4) and end to end: the pruned lockfile is installed frozen and offline by bun always, and by pnpm, npm and yarn 1 where they are on PATH (yarn 1's `--frozen-lockfile` passes a lockfile missing entries, so its check is an install that leaves the file byte-identical). vx's own repository declares `bun()`.

---

# @vzn/vx-mcp

> A Model Context Protocol server for

A [Model Context Protocol](https://modelcontextprotocol.io/) server for
[`@vzn/vx`](https://github.com/vznjs/vx), as a plugin. Declaring it adds
`vx mcp`: a stdio JSON-RPC surface over your workspace's tasks, cache
and run history that Claude Code, Cursor, Continue.dev, GitHub Copilot and
any other MCP client can call.

```sh
npm install -D @vzn/vx @vzn/vx-mcp   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
```

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { mcp } from '@vzn/vx-mcp'

export default defineWorkspace({
  plugins: [mcp()],
})
```

Then point your agent at it:

```jsonc
// Claude Code: .mcp.json at the workspace root (or `claude mcp add vx -- vx mcp`)
{ "mcpServers": { "vx": { "command": "vx", "args": ["mcp"] } } }
```

Run the agent from inside the workspace — `vx mcp` finds the workspace
(and its cache) from the current directory, like every other verb.
`vx mcp --help` prints its usage; `--stdio`, the default, is its one flag.

## Tools

| Tool               | Answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `listTasks`        | "What can I run here?" — every project, its `tags`, and the tasks a run would see (command, `dependsOn`, whether it caches), resolved like `vx run` resolves them, plugin stages included; a command's `exec.env.secret` values read `***`, as in `vx show`. `project` narrows to one; `filter` and `affected` narrow as `vx show --filter` / `--affected` do, the CLI making the selection.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `getCacheStats`    | "What's the state of my cache?" — entries, total size, runs / hits in the last 24h, hit rate. `scope: { project }` narrows every number to that project.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `getRunHistory`    | "Which tasks have I been running, and how fast?" — recent runs plus per-task p50 / p99 / success rate / hit rate / failure mode (flaky only on a real nondeterminism signal), and the largest peak RSS and CPU parallelism the executions showed (`maxPeakRssBytes`, `maxCpuParallelism` — the peak is what `@vzn/vx-schedule-history` reserves from; a task lighter than vx itself shows no peak). Each recent row carries its exit code and, where it applies, why it failed or was skipped as the run's footer said it (`blockedBy`, `timedOut`, `sandboxViolations`, `notReady`). Filters: `project`, `task` (a task name; a `project#task` is refused), `limit` (1..500, clamped rather than refused — the answer carries the `limit` it applied, so a truncated list cannot read as an exhausted one). |
| `explainCacheKey`  | "What's the cache identity of `pkg#build`?" (`taskId`) — the latest entry's hash, command, exit code, duration, size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `whyDidThisRerun`  | "Why did `pkg#test` re-execute in run X?" (`taskId`, `runId`) — the run's key against the previous run's, whether it changed, what moved (`diff`) and, under a moved upstream, the tasks whose own inputs moved (`roots`), as `vx why --format json` answers (`runId` optional: the task's latest run; whole or the unique prefix `vx last --list` prints; runs recorded before run ids answer the task's latest cache entry, as `vx why` does).                                                                                                                                                                                                                                                                                                                                                             |
| `pruneCache`       | "Free cache space." (`olderThan`, `maxSize`, `dryRun`) — `vx cache prune --format json` on the cache the other tools read: `dryRun`, `evicted`, `bytesFreed`, `orphans`, `orphanBytes`. A dry run unless `dryRun` is false.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `planInit`         | "What would adopting vx write here?" (`mode`) — `vx init --dry --format json`: each file with its text, `kept`, `replaced`, `todos`, `notes`, `next`. Nothing written; in a Turbo or Nx repo the plan is vx-migrate's.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `searchDocs`       | "Where is X documented?" (`query`, `limit`) — `vx docs <query> --format json`: the reference sections holding every word, each whole with its URL. No network.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `checkLock`        | "Is the config lock current?" — `vx lock --check --format json`: `upToDate`, `audited`, `notAudited`, and each drift in `problems`; `exitCode` 1 on drift.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `getConfig`        | "What does this task declare?" (`target`: a project, `project#task`, or a task name) — `vx show <target> --format json`'s resolved config: inputs, outputs, env, sandbox, dependsOn, secrets masked.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `getTaskLog`       | "What did task X print?" (`taskId`, `runId`) — `vx last --log`'s answer: `runId`, `taskId`, `status`, `source` (`failure`, `cache`, or null when vx kept none: an uncached pass, a skip) and `output` (plain text, a cached log masked as a hit replays it). `runId` defaults to the latest run that recorded the task.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `getFailures`      | "Why did run X fail?" (`runId`) — each failed task's `taskId`, `exitCode`, `timedOut`, its `output` (plain text, the first 8 KiB and last 56 KiB, secrets masked) and the `locations` it names (`{ file, line?, col? }`, file absolute) — no terminal scraping (`runId` optional: the latest failed run; whole or a unique prefix).                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `runTasks`         | "Run these tasks and tell me how it went." (`tasks`, `all`, `filter`, `affected`, `force`) — runs `vx run <tasks> --format json` here, with this workspace's cache and sandbox, and returns `exitCode` and the run `summary` (the `--summarize` document: `ok`, each task's status, hits, durations). `filter` is the `--filter` values, `affected` is `true` or a git ref. A refusal before the run (an unknown task) returns no summary and the CLI's message, secrets masked, as `error`; a failed task's output is `getFailures`.                                                                                                                                                                                                                                                                        |
| `planTasks`        | "What would run, and why?" (`tasks`, `all`, `filter`, `affected`) — `vx run <tasks> --dry=json` here, nothing executed: each task's predicted cache status, hash, deps and p50, an `affected` reason under `--affected`, and `predicted` (`wallMs`, `workMs`, `criticalPath`). Answers `exitCode` and `plan`; a refusal returns no plan and the CLI's message, secrets masked, as `error`.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `getWorkspaceInfo` | "What is this workspace, and what will a run use?" — `vx info --format json`: versions, the git status cache, projects and tasks (and the configs that did not load), plugins and their seams, the worker count and memory budget with their sources, cache versions and state, flaky tasks, the sandbox runtime's verdict for this host and how many tasks declare one, the lock.                                                                                                                                                                                                                                                                                                                                                                                                                           |

Arguments are checked, never coerced: `arguments` that is not an object
(a string, an array), a key the tool does not take (`tsk` for `task`, or a `task` in
`getCacheStats`' scope),
a filter that is not a non-empty string, a task id
missing a half (`#build`, `app#`) or an empty run id, or a `limit` that is not a
finite number is refused with a line naming it, rather than answered
for a question the agent did not ask.

Every tool but `runTasks` is **read-only** (`planTasks` plans and runs nothing): none runs a task or writes
the cache (`listTasks` opens it only to serve cached config evaluations).
`runTasks` writes only what `vx run` writes, through the CLI itself, as a
child process; the plugin declares only a CLI verb, no executor and no
cache layer. The four cache tools open the index as `vx last`
does: where there is none they answer from an empty one and make nothing
on disk, an index from an earlier vx is refused by name and left for the
next `vx run` to reset, and old run history is never pruned by a read.

`mcp({ run })` (`McpOptions`) limits `runTasks`. With `run: false` the tool is not listed and
the server runs nothing. With `run: ['test', 'lint']` an agent may run only
those task names, and any other is refused before anything runs. A task's
`dependsOn` still runs. The default, `true`, runs any task.

## Why no SDK

MCP over stdio is newline-delimited JSON-RPC 2.0 and four methods
(`initialize`, `tools/list`, `tools/call`, `ping`); a batch, which the 2025-03-26 revision allows, is answered as one array. `src/server.ts` speaks it in
about 230 lines with no dependencies, where the reference SDK pulls
in an HTTP stack this transport never touches. `@vzn/vx` is the only peer.
What a config or plugin stage prints while a tool loads the workspace
goes to stderr: `console`, `process.stdout`, `Bun.write(Bun.stdout, …)`
and `Bun.stdout.writer()` (item 1069). A write straight to fd 1
(`fs.writeSync(1, …)`) or a child with inherited stdout still lands in
the reply stream: give such a child `stdout: 'pipe'`.
It speaks revisions 2024-11-05, 2025-03-26 and 2025-06-18 (a client asking for
another is offered the newest), and answers a request
outside JSON-RPC 2.0's envelope with -32600 and a call to an unknown
tool or with non-object `arguments` with -32602; a tool's own refusal
is an `isError` result. Either error's text has secret values masked
(`***`), as the CLI masks the error it ends on: a config's refusal quotes
the config's own strings.

## Troubleshooting

- **The agent lists no vx tools.** Most clients read their MCP config only
  at launch — restart the agent. Check `vx help` shows `vx mcp` under
  "Plugin commands" from the directory the agent runs in.
- **`unknown command: mcp`.** The cwd is outside a workspace that declares
  the plugin; `vx mcp` exists only where `vx.workspace.ts` says `mcp()`.
- **Empty stats.** No `vx run` has happened in this workspace yet, or the
  agent runs from a different workspace.
- **`… a running process cannot evaluate an imported module again`.** A
  file a config imports changed while the server ran; Bun cannot load a
  module twice. Restart the agent (or its MCP server) to apply the edit.

---

# @vzn/vx-migrate

> Everything for adopting @vzn/vx from Turborepo, Nx or Vite Task, in one package with zero dependencies:

Everything for adopting [`@vzn/vx`](https://github.com/vznjs/vx) from Turborepo, Nx or Vite Task, in one package with zero dependencies:

- **`turbo()`** — a temporary start for a Turbo repository: the plugin fills vx's `project` stage from `turbo.json` and each package's `package.json` scripts until the migrator writes native config.
- **`nx()`** — the same temporary start for an Nx repository, filled from Nx's resolved project graph. Executor targets (`@nx/js:tsc`, `@nx/vite:build`, your own) run as themselves through **`nx-exec`**, one executor per process.
- **`bunx @vzn/vx-migrate`** — write one `vx.config.ts` per workspace package from your `turbo.json`, an exported Nx project graph, or vite-plus's `run.tasks` (Vite Task, `vp run`), plus the workspace file every run needs. Runs without a workspace file, so it is the first command, not the second.
- **`turboCache()`** and **`nxCache()`** — keep the remote cache you have: any server speaking Turbo's `/v8/artifacts` API (Vercel's hosted cache included) or Nx's self-hosted `/v1/cache` spec.

```sh
npm install -D @vzn/vx @vzn/vx-migrate   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
```

In a Turbo or Nx repo, `npx vx init` writes the `vx.workspace.ts` that
declares `turbo()` or `nx()` and prints the install-and-run line. Add
`turboCache()` or `nxCache()` to keep your remote cache:

```ts
// vx.workspace.ts — a Turbo repo mid-migration, with its remote cache
import { defineWorkspace } from '@vzn/vx/config'
import { turbo, turboCache } from '@vzn/vx-migrate'

export default defineWorkspace({ plugins: [turboCache(), turbo()] })
```

The package exports `turbo`, `nx`, `turboCache`, `nxCache` and their options types (`TurboPluginOptions`, `NxPluginOptions`, `TurboCacheOptions`, `NxCacheOptions`); the mappers and cache clients are internal.

## `turbo()` — a Turbo repo, mid-migration

Until `bunx @vzn/vx-migrate` writes native config, `vx run build --all` maps every package's `build` script the way `turbo run build` would: `dependsOn` edges (`^build`, same-package deps, `pkg#task`), `inputs` / `outputs` as the cache block, `env` / `passThroughEnv`, `cache: false`, `persistent`. Turbo's global fields (`globalDependencies`, `globalEnv`, `globalPassThroughEnv`, Turbo 1's `globalDotEnv`) are inlined into every task; a `*` env name (`NEXT_PUBLIC_*`) expands over the run's environment, as Turbo matches it; `*` is Turbo's only wildcard (`\*`, a leading `\!`, `?` and `[` are literal), and a literal vx cannot key (unkey's `NEXT_PUBLIC_\*`) is left out, reported once only when the run's environment sets it; per-package `turbo.json` overlays apply. A `turbo.jsonc` (Turbo 2.5+) is read wherever a `turbo.json` would be, at the root and in a package; a workspace root with neither is refused, naming the fix. Turbo 2's framework inference (a package on `next` has `NEXT_PUBLIC_*` and `NEXT_DEPLOYMENT_ID` hashed and passed; Turbo's whole table, `expo`, `nuxt`, `remix`, `@sveltejs/kit` and the rest, each package taking the first framework it matches, as Turbo does, and leaving out names under the platform's `TURBO_CI_VENDOR_ENV_KEY`) applies too: the prefix expands over the run's environment into that package's tasks, and a task's `!` entry takes names back (`bunx @vzn/vx-migrate`, which writes files for another environment, names each framework and its packages in a note instead). What runs is what a migration would have written, minus the file: the key a task derives here equals the key the written config would derive.

| Option | Meaning                                                         |
| ------ | --------------------------------------------------------------- |
| `root` | Directory holding `turbo.json`. Defaults to the workspace root. |

### Locking

`vx lock` freezes the evaluation of written `vx.config.*` files only. A package that has none gets its tasks from `turbo.json` on every load — under `--frozen` too — so the lock records nothing for it and `vx lock --check` does not audit it; `turbo.json` is its source of truth, committed like one.

### What it does not do

- A task the package's own `vx.config` already declares is left alone — the plugin fills, it never overwrites. Migrate a package by writing its config; the rest of the repo keeps running from `turbo.json`.
- The mapping's gaps are the migration's gaps, reported as warnings on every run instead of `TODO(vx-migrate)` comments: `$TURBO_ROOT$` tasks, an env name vx cannot key that the run's environment sets (`FOO_?`, which Turbo reads literally), unknown turbo keys. A persistent task's readiness note (`readyWhen`) is reported only when something depends on it — with no dependent there is nothing to gate (refine printed it for 375 `dev` targets a run). `bunx @vzn/vx-migrate --dry` lists the same set once. Each gap is one line per run for every task that carries it, not one per task (n8n marks `dev` and `watch` persistent in most of its 84 packages; astro negates `vendor/**` in the outputs of 57 tasks). A per-package `{ "extends": false }` with nothing else is Turbo's opt-out and maps to no task; with keys, the task runs on those keys alone. A glob that climbs out of the package (`../../packages/app-store/*.generated.ts`) is re-anchored on the workspace root as a `workspaceFiles` glob. A negated output under a literal-rooted one (`dist/**` minus `!dist/**/*.map`) takes its paths back (see `outputs` below); one against a wildcard-rooted output (medusa's `*/**` minus `!src/**`) makes the task uncached, because the clean before exec would otherwise delete the sources — declare the exact outputs in a vx.config to cache it.
- The cost is the stage's: on a 1,000-package workspace with no `vx.config` files the mapping loads in about 42 ms where 1,000 evaluated configs load in 22.
- The mapping is kept in `<cache dir>/vx-migrate-turbo-mapping.json`, keyed on every `turbo.json` / `turbo.jsonc`, every package manifest, the mapper's own code and the environment variable names a wildcard can match (one in a Turbo config or Turbo's framework table) or core cannot key, so an unrelated variable keeps it; a run with none changed reads it instead of mapping (astro, 562 packages: ~40 ms of mapping against ~12 ms of key reads).
- The mapping is read once per run, never once per process: under `vx watch`, a `package.json` script edit or a per-package `turbo.json` overlay edit is the next cycle's tasks. The root `turbo.json` is no task's input and lives in no project dir, so an edit to it is not a cycle — restart the watch.

### The mapper (`mapTurboWorkspace`)

The plugin and the CLI read a repo the same way: the mapper the plugin runs live is what `bunx @vzn/vx-migrate` writes `vx.config.ts` per package from, splicing Turbo's global fields in as imports of a generated `vx-preset.ts` (its exports alone, no comments), where the plugin inlines the values; a global input another task writes to is taken back after the spread (`[...globalInputs, '!packages/plugin/dist/**']`), as the plugin takes it back from the inlined values. `splice` is the seam between the two consumers; `uses` names which globals a task drew on. Before 2026-09-10 the mapper lived in `@vzn/vx` itself; until 2026-09-11 the plugin was its own package, `@vzn/vx-turbo`.

Rules:

- **A task exists for a package only when the package declares the script** — Turbo's own rule. An absent script is silent; a script key whose value cannot be a command (a number, `null`, an empty string, an array) produces a `task: null` entry whose todo says why, rather than a config that fails to load.
- **Definition order**: root `pkg#name` if there is one, else root `name` (the first replaces the second whole, as Turbo looks it up), then each package config its own `turbo.json` extends (`"extends": ["//", "shared"]`, read by Turbo 2.11, refused by 2.5; nearest last, a parent missing or a cycle refused as Turbo refuses it) and its own, each winning field by field, except an overlay array holding `$TURBO_EXTENDS$` (Turbo 2.5+), which is the inherited list plus the overlay's other entries (`inputs: ["$TURBO_EXTENDS$", "config.json"]`).
- **The command is the script body** with its `pre<name>` / `post<name>` hooks folded in, in that order, through core's `foldScriptHooks`: each part in its own subshell, the chain stopping at the first that fails, forwarded `--` args reaching the body alone (npm and pnpm run them around `<name>` without being asked; novu's `prebuild` copies the CSS its `build` inlines), one process less per task than `pnpm run <name>` — except a body that calls yarn's `run` builtin (`run -T rollup -c`, `run clean && run build`; yarn ≥ 2 runs scripts in its own shell), which is `run: command not found` in sh: it runs as `yarn run <name>`, as Turbo and Nx run it, and yarn ≥ 2 runs no hooks, so none are folded there. A Yarn Plug'n'Play workspace (`.yarnrc.yml` with no `nodeLinker`, or `pnp`) has no `node_modules`: a dependency resolves only through `.pnp.cjs` and a bin only through yarn's shims, so there every script runs as `yarn run <name>`, and a `nodeLinker` change maps afresh. Same rules for `nx:run-script` below (strapi and novu, 2026-09-11).
- **Turbo 2.11's task `command`** (`futureFlags.experimentalTaskCommand`) wins over the script, as Turbo holds it: an argv is the command — each word quoted, run from the package dir, no `pre`/`post` hooks — and gives the package the task even with no script (turborepo's `@turbo/types#build`, `docs#schema`); `null` or `[]` is Turbo's no-op node, no task even where the script exists, its edges passed through; a per-toolchain map applies its `javascript` entry (or `typescript`, Turbo's alias), and without one the script runs. A shape Turbo would refuse keeps the script, with a todo.
- `dependsOn`: `^x` passes through when some package runs `x` or turbo.json defines it, and is dropped otherwise (core refuses a `^x` no project declares as a typo); `pkg#task` is kept only when `pkg` emits `task` (else a todo: edge dropped); a same-package task Turbo defines but the package has no script for is Turbo's no-op node, so its own edges pass through in its place (`test → codegen → ^build` with no `codegen` script is `test → ^build`); another package's `^x` or `pkg#x` reaches such a node through a group task when its edges name a task of its own package or another (with-tailwind's `ui` has no `build` script; its `build` builds `build:styles` and `build:components`, and `web#build` waits on them), and so does one whose `^` edge names another task (rallly's script-less `build` holds `^db:generate`), while one whose only edge is `^` to its own name needs none, since core's `^x` walks past a package without `x`; a no-op node nothing else reaches is a group too in a package nothing but the root depends on, since no dependant's `^` edge runs its edges there (vercel/ai's `turbo run type-check` builds each example through its script-less `type-check: [build]`, and kitchen-sink's `turbo run test` builds `@repo/ui` for `admin`, which has no `test` script); elsewhere it is none, its edges run by its dependants'; a name Turbo does not define has no edge; `$TURBO_ROOT$` deps are a todo. A task turbo.json defines and no package has a script for (documenso's `lint`, shadcn-ui's `check`) is a group task in each package that defines it, its edges kept (a `pkg#task` edge only in `pkg`), so `vx run lint` runs Turbo's no-op nodes and exits 0 as `turbo run lint` does. Root `//#task`s run in the workspace root, as under Turbo: `turbo()` names the root a project through core's `discover` stage when turbo.json declares one (no `vx.config` needed; a root no member glob lists), and `//#x` in `dependsOn` is an edge to it, named by the root `package.json` `name`; a root task's globs are the workspace's (`workspaceFiles`), since Turbo hashes a root task over the whole repo; with no root project (a root `package.json` with no `name`, or one a package holds) they are a note and such an edge a todo. Turbo runs no plain task in the root package of a monorepo, and neither does `turbo()`; in a single-package repo (no workspaces, Turbo's `non-monorepo` example) turbo.json's plain tasks run on the root package, as under Turbo.
- A transit node (Turbo's documented pattern, its with-vitest example: `transit: { dependsOn: ["^transit"] }` with no script anywhere, and `test: { dependsOn: ["transit"] }`) is a key-only task in each package that defines it: a keyed group (no command, nothing spawns) keyed on its inputs, with its `^transit` edge, so a dependant's `test` re-keys on its dependencies' sources as Turbo re-hashes it. A `^` task that some package has a script for, or that nothing depends on, is no transit node. A package without the script of a `^` task others run gets the same key-only task, as Turbo hashes a no-op node there: an edit to it re-keys its dependants. A `build` whose only edge is `^build` is not written: core gives every project with no `build` that node (solid's three script-less packages each got a `build` of their own). A dependency without the script whose own edges lack `^x` gets it too, so a `^x` stops there as Turbo's does (opencode's `build: { dependsOn: [] }`: core walked past to the builds below, which Turbo's `^build` never reaches).
- `with` (tasks Turbo runs alongside, `web#dev` with `api#dev`): an edge to each sidecar that is persistent, so vx starts the task once the sidecar has spawned and runs the sidecar only when the task runs; a sidecar that ends would be waited for, so it is a todo instead, and a pair that names each other keeps one edge (two would be a cycle). A task with no script whose `with` names persistent sidecars (Turbo's with-tailwind example: `ui` has no `dev` script, its `dev` starts `dev:styles` and `dev:components`) is a group task that depends on them.
- `inputs`: a structured entry (Turbo 2.11) is its `globs`, plus `**/*` with `withDefaults`, for `startup` and `jit` alike; `dependencyOutputs` adds none where the producer is cached (vx folds each dependency's key); from a `cache: false` producer (vercel/vercel's `//#generate:cache-keys`, which records the host) the named files, or its outputs, are a `cache.inputs.workspaceRuntime` probe, and `cache.inputs.tasks` leaves the producer out, so core answers the probe after it ran. Then: absent or `[]` → `**/*` (Turbo's default); `$TURBO_DEFAULT$` → `**/*`; exclusions alone narrow `**/*`; `$TURBO_ROOT$/<path>` → `cache.inputs.workspaceFiles` (negation kept); any other `$TURBO_ROOT$` use is a todo. `globalDependencies` and Turbo 1's `globalDotEnv` land in `workspaceFiles` too, and a task's Turbo 1 `dotEnv` in its `files`. Turbo 1's `$NAME` entries, in `globalDependencies` or a task's `dependsOn`, are env vars: they join `cache.inputs.env` and `exec.env.passThrough`. A package nested in the task's package (cal.com's apps inside `@calcom/app-store`) is hashed by Turbo with its parent, and core's globs stop at a project: each glob that reaches one is also listed in `cache.inputs.workspaceFiles`. Turbo's glob grammar is translated as Nx's is (`*.[jt]s` is `*.{[jt],j,t}s`); an input with no safe form widens to `**/*` with a todo. A `.env`-shaped input (`.env*`, `.env.local`, a task's Turbo 1 `dotEnv`, create-turbo's `globalDependencies: ["**/.env.*local"]`) is gitignored as a rule, so it is keyed by a probe that hashes the `.env` files it can name (`cache.inputs.runtime`) or, for a root entry, the files its root-relative globs name, hidden ones too, as Turbo's `*` matches them (`workspaceRuntime`; `**/<name>` is a `find -name` that skips `node_modules`, and another `**` walks the workspace), rather than as a file glob git never reports. A package whose `.env` globs all sit at its root gets a one-shell probe of that directory; one below the root walks the package.
- `outputs`: `$TURBO_ROOT$/<path>` → `cache.outputs.workspaceFiles`; a negated output rides beside its positives and takes its paths back from the clean, the save and the restore (Next's `.next/**` minus `!.next/cache/**` keeps the cache), and one with no positive beside it takes back nothing and is dropped. Past its first segment an output takes Turbo's grammar (`dist/**/*.[cm]js`); the first stays a literal (a route directory). An output whose first segment is a wildcard (`**/*.d.ts`, `*/**`) runs the task uncached with a todo: Turbo never cleans an output, vx cleans it before every run, and such a glob reaches the sources. One segment with a literal extension the package tracks no file of (`*.xml`, `*.tsbuildinfo`) reaches only top-level artifacts and stays cached, and so does `**/<dir>/**` when the package tracks nothing under a directory of that name (vercel/ai's `**/dist/**`; `node_modules` is never an output), and so does a first segment no tracked top-level entry matches (tldraw's `dist-*/**`). A wildcard first segment with a literal rest (clerk's `*/package.json`, the subpath stubs it commits) reaches only files of that name: each committed one, up to 16, is taken back with `!` and the task stays cached; more, and it runs uncached. An output that covers the package's own `package.json` (trpc's client build lists it: the build rewrites `exports`) runs the task uncached with a todo: vx would delete the manifest before every run, and core refuses that config. `nx()` takes the manifest back with `!package.json` instead and keeps the cache (owner, 2026-10-03). So does one that covers the package's vx.config; `turbo()` and `nx()` check the config the package has, and `vx-migrate` the one it writes, so sanity's `*.js` shims stay cached beside none. `nx()` keeps a wildcard-first output cached instead: each committed file it reaches is taken back with `!` (past sixteen, uncached with a todo), and the clean removes the rest, what the task writes (owner, 2026-10-03). A committed file under an output (typescript-eslint's `data/sponsors.json` in a cached `data`) is taken back with `!` — Turbo and Nx never clean an output, vx does — so it survives the clean and the task keeps its cache; past sixteen such files the task runs uncached with a todo. `turbo()` and `nx()` both do this, and so do the configs `vx-migrate` writes from turbo.json or an Nx graph (each take-back is a todo there, as it names files a later commit may move).
- `env` / `passThroughEnv`: explicit names go to `cache.inputs.env` (env only) and `exec.env.passThrough` (both, plus both globals); a wildcard expands over the run's environment under `turbo()`, which maps where the tasks run (a new variable name such a wildcard matches maps afresh); the CLI, which writes for another environment, lists the names the task's package and its workspace dependencies spell (a root task: the whole repo; clerk's `E2E_*`), noted once per entry, and one nothing spells is a todo; `*` is the only wildcard, as in Turbo, so `\*`, a leading `\!`, `?` and `[` are literal: unkey's `NEXT_PUBLIC_\*` names one variable, which vx cannot key, so it is dropped and reported once for the workspace with the count of tasks naming it (openstatus's root `build` env `\*` had written one todo into each of 45 configs; `turbo()`: only when the run's environment sets it, as Turbo hashes nothing otherwise); and a `!` entry (openstatus' `!NEXT_PUBLIC_VERCEL_URL`) removes the names it matches from its list, with no todo, since vx matches no name it is not given. A name both a global list and the task's own list carry is listed once. A name that is no shell variable name (`p-q`) is keyed but left out of `exec.env.passThrough`, as `sh` drops it before the task runs.
- Framework inference (Turbo hashes and passes Next's `NEXT_PUBLIC_*`, Vite's `VITE_*`, … for a package that depends on the framework): `turbo()` expands the prefix over the run's environment; the CLI writes the names the tracked source and `.env.example` of the package and its workspace dependencies spell (the bare prefix, as a `startsWith` test spells it, is none) (Next bundles theirs: cal.com's web, 23 alone, 58 with them), and a note asks for any only an installed dependency reads.

- **Two tasks of one package on one output path** (strapi's `build`, `build:code` and `build:types`, all on `dist/**`): vx cleans a task's outputs before it runs and before a restore, so the loader refuses two cached tasks whose outputs provably overlap. Under vx's default `rules.exclusiveOutputs` an edge between the two changes nothing (twenty's `build:individual` writing into `build`'s `dist`). The mapping resolves it before the file is written — the task with a `^` edge keeps its cache (the first declared when none has one); the rest run uncached with a todo naming the keeper and the fix, their own output path. Same rule for Nx targets.
- **A task whose inputs read another task's outputs** (a `test` keyed on `**/*` beside a `build` writing `dist/**`): vx's default `rules.upfrontKeys` refuses it, since such a key cannot be known before the producer ran. Each overlapping output is taken back from the reader's inputs with `!` (`['**/*', '!dist/**']`), in package and workspace inputs alike, and a workspace output another package writes into this one is taken back from its package inputs too; Turbo and Nx hash what git tracks, and a build's outputs are not, so the key reads what the adopted tool read. A literal input another task writes cannot be taken back: that task runs uncached with a todo. A committed file under such an output is still a source: a reader the `!` would hide it from runs uncached with a todo. An output that names one committed file (eslint's `eslint-suppressions.json` in a `lint` task's outputs) is dropped, and so is the `!` each reader got for it: the file stays in every key, as Turbo and Nx hash it, and the readers stay cached. Same for Nx targets.
- **Two packages' tasks on one workspace output** (cal.com's shared `post-install` writes `../../node_modules/@prisma/client/**` from every package with the script): core refuses two cached tasks on one path with no edge between them, so `turbo()` (and `nx()`) keeps the first (in package and task order) cached and runs the rest uncached, each with a todo naming the keeper. A package's own outputs count at their workspace path: typescript-eslint's root project caches `dist` and each package's typecheck `dist/packages/<name>`, one path twice. Edges across packages are not read, so an ordered pair loses its cache too.
- `cache: false` or `persistent: true` → no `cache` block; a persistent task gets `exec.persistent: {}` and, when some task depends on it, the consumer's `persistentTodo`.
- A task's `description` (Turbo 2.11.5's schema) is the vx task's `description`.
- `outputLogs: "new-only"` maps to nothing: frames for the tasks that ran and a one-liner per cache hit is vx's default flow already. The other values are per-run in vx, so they are a todo naming the flag (`vx run … --output-logs hash-only`).
- `interruptible` maps to nothing: `vx watch` keeps a persistent task up across cycles and restarts it only when its config changes or it dies.
- A task's `tags` (Turbo main, after 2.11.5) map to nothing: Turbo keeps them out of the hash and the run.
- `envMode: "loose"` (top-level or in `global`, or `TURBO_ENV_MODE=loose`, which wins) is a note: Turbo hands every task the whole environment, vx only the declared names.
- The workspace keys vx has a home for, top level or in `global`, fill what `vx.workspace.ts` leaves unset: `concurrency` (`"10"`, `"50%"` of the cores) → `concurrency`; `cacheMaxSize` / `cacheMaxAge` (`"0"` is off; weeks become days, a bare number days; a size in Turbo's grammar, `7.5GB` or bare bytes, restated whole: `7680MB`) → `cacheRetention.maxSize` / `.olderThan`. `TURBO_CONCURRENCY`, `TURBO_CACHE_MAX_SIZE` and `TURBO_CACHE_MAX_AGE` win over turbo.json, as under Turbo; a set one decides, its `0` included.
- `TURBO_SCM_BASE`, the base `turbo run --affected` compares with, is `affectedBase` when `vx.workspace.ts` sets none: a bare `vx run build --affected` compares with the same ref. With it unset on GitHub Actions (`GITHUB_ACTIONS`), Turbo's own base applies: a pull request's `GITHUB_BASE_REF`, else the push event's `before` from `GITHUB_EVENT_PATH`.
- Turbo hashes each package's `microfrontends.json` (or `.jsonc`) into every task, or the one file `VC_MICROFRONTENDS_CONFIG_FILE_NAME` names; so does `turbo()`.
- Turbo 2.11's `global` block (`futureFlags.globalConfiguration`) is read as the `globalDependencies`, `globalEnv` and `globalPassThroughEnv` it replaces.
- An unknown Turbo key is a todo naming it; `extends` is accepted and ignored (the overlay order above is what it means).

## `nx()` — an Nx repo, mid-migration

```ts
// vx.workspace.ts — an Nx repo, mid-migration
import { defineWorkspace } from '@vzn/vx/config'
import { nx } from '@vzn/vx-migrate'

export default defineWorkspace({ plugins: [nx()] })
```

Until `bunx @vzn/vx-migrate` writes native config, `vx run build --all` maps every project's `build` target the way `nx run-many -t build` would. The plugin reads Nx's **resolved** project graph — where Nx has already applied `targetDefaults`, expanded `namedInputs`, inferred targets through its plugins and interpolated `{projectRoot}` and friends — so nothing is re-derived here. Per target: `nx:run-commands` and a plain `command` run as one shell line that does what Nx's run-commands does (below); `nx:run-script` is the package script, with the `$npm_package_name`, `$npm_package_version` and `$npm_lifecycle_event` it reads defined as `<pm> run` sets them (a migration reads the name and version from the manifest it imports, so a bump reaches them; any other `$npm_*` is a todo); `nx:noop` is a group task, and so is a target with neither an executor nor a command that has dependencies, as Nx normalizes it (one with none is dropped, as Nx drops it); **every other executor runs through `nx-exec`** with the executor and its options on the command line. A target Nx caches (`cache: true`, or the legacy `cacheableOperations` list in `nx.json`) gets its `inputs` / `outputs` as the cache block, with no `inputs` meaning Nx's `default` and `^default`, named inputs resolved per project (nx.json's under the project's own; one neither defines, such as an `extends` preset not installed, keys the whole project with a todo, never an empty list that keys the task on its config alone), `{workspaceRoot}` / `{projectRoot}` / `{projectName}` interpolated anywhere in a path as Nx does (`{workspaceRoot}/coverage/{projectRoot}`), Nx's glob grammar translated (`*.[jt]s` is `*.{j,t}s`; the default `production` negation `?(*.)+(spec|test).[jt]s?(x)` becomes brace sets, a narrowing only a negation may take; what has no safe form is a todo), a project fileset of negations alone (nx-recipes' `noMarkdown`) starting from every project file, as Nx reads it, and an output outside the project dir (`dist/<project>` at the workspace root, Nx's default layout) a `workspaceFiles` output, an output outside the workspace (an old generator's `reportsDirectory: "../../coverage/<lib>"`) a todo and dropped, as vx caches only inside it, an output whose first segment is a wildcard (`{projectRoot}/**/*.d.ts`) cached, with each committed file it reaches taken back by `!` and the rest cleaned before the run (typescript-eslint's `**/*.shot`, 3,656 committed snapshots, is past sixteen and runs uncached with a todo), and an output that covers the project's own `package.json` or vx.config cached with the file taken back by `!`; `dependsOn` becomes the edges (`^build` — dropped when no project has the target, as Nx gives it no edges and core refuses a `^name` nothing declares — `build`, `project:target` → `project#target`, everything past `project:` one target name, as Nx joins it (`ui:build:esm` is ui's `build:esm`; `ui:build:ci` names target `build:ci`, never `build`'s `ci` configuration, and is no edge where ui lacks it), this project's own target winning over a project name, `{ target, projects }` → each matched project's task, `projects` read as Nx's `findMatchingProjects` reads it: a name or a list of names, globs over names and over project directories (`libs/*`), `name:` / `tag:` / `directory:` labels, a bare word as a word in a name, and `!` exclusions; an edge to a target its project lacks is dropped without a word, as Nx drops it — `targetDefaults` that give every `typecheck` a `codegen` one project has; `^name` is every dependency's `name` whatever it holds, `^rsbuild:typecheck` included; a target glob — `test:e2e--*`, `^build-*`, `ui:build-{esm,cjs}`, a `{ target }` object's — expands over every target name in the workspace, as Nx 19.5+ does, before those rules; a same-project glob keeps its own project's matches), `{ env }` inputs pass through (one that is no shell variable name is keyed only), `{ runtime }` inputs run at the workspace root as Nx runs them (`cache.inputs.workspaceRuntime`), a `{ fileset, includeIgnored: true }` literal (Nx 23 hashes it from disk, gitignored or missing) is read by such a probe, since vx's globs see only what git lists, and a glob of one is a todo, a target that says `continuous` — or, in a graph from an Nx older than that field, runs a server executor (`@nx/vite:dev-server`, `@nx/next:server`, …) — is a persistent task and never cached, ready on spawn as Nx has it (Nx starts the dependents once it has started; a run-commands `readyWhen` gates them, below). The target's name never decides: a cached `dev` caches like any other target (nx#32610). `parallelism: false` (Nx runs the target alone) has no vx form and is a todo naming `--concurrency 1`; `syncGenerators` (Nx runs them first) is one workspace note per generator list, counting its tasks and naming `nx sync`; nx.json's `sync.globalGenerators` is one note per run naming `nx sync`. A target with `configurations` is one task per configuration (one whose name another target holds, `vite`'s `build` beside an inferred `vite:build`, is not written, with a todo, as Nx resolves `a:vite:build` to the target): `build` carries the default configuration's options, `build:ci` the `ci` one, and an edge of `build:ci` (own, named or `^`) reaches each target's `ci` task where it declares one, else its default, as Nx's `resolveConfiguration` does; a `^build` there becomes one edge per dependency Nx links. A `^name` input (`^production`, `{ input, dependencies: true }`, the pre-17 `{ input, projects: "dependencies" }`; `projects: "self"` is the own input, as Nx 23 still reads both) is what Nx hashes: each dependency's `name`, over the project graph, whether or not a task edge exists. A `{ input, projects }` list is read as `dependsOn`'s `projects` is. Each project some reader reaches gets an `nx-input:<name>` task — a keyed group (no command, nothing spawns, not counted in the run summary) keyed on its own `name` input, depending on its Nx dependencies' twins (a project nothing reaches gets none) — and a task that reads `^name` depends on its direct dependencies' twins, so the whole closure folds into its key with each project hashed once. A dependency FILESET (`^{projectRoot}/tsconfig.lib.json`, `{ fileset, dependencies: true }`, which Nx's own inferred `typecheck` writes) folds the same way: its twin, `nx-input:fileset-<hash>` (a glob's `*` is no task name; the task's description names the fileset), keys on that fileset in each project. A twin lists its project's `package.json` and `project.json` first (whichever exists; Nx keys every task on its project's manifest and configuration): a fileset that matches nothing (an absent `tsconfig.spec.json`, a dependency's unbuilt `*.d.ts`) is nothing to Nx and no "matched no files" warning, and the file appearing re-keys its readers. The twins spawn nothing and stay out of a run's output and task count, so `vx run build` counts the tasks `nx run-many -t build` does. A path input inside an output one of the project's own targets declares (TanStack/table's `public` input lists `{projectRoot}/dist`) is generated, and gitignored where Nx caches it: Nx's file map skips gitignored files, so Nx hashes nothing there (a changed `dist` file is a cache hit under Nx 23.3), and it is dropped without a todo, and the task that writes it keys its dependants through `dependsOn`.

| Option  | Meaning                                                                                                                                                      |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `root`  | Directory holding `nx.json`. Defaults to the workspace root.                                                                                                 |
| `graph` | An exported graph (`nx graph --file=<path>`) to read instead of keeping a snapshot; with it set the plugin never runs `nx`. Relative to `root`, or absolute. |

### `nx:run-commands`

Nx's own option handling, rendered as one POSIX `sh` line (`vx show` prints it):

- **Where:** the workspace root unless `cwd` says otherwise — a `cd` from the project dir, since vx has no per-task cwd — with `{projectRoot}`, `{projectName}` and `{workspaceRoot}` expanded.
- **How:** each command runs in a shell of its own. `commands` run in **parallel** unless `parallel: false` (Nx's default): all start at once, the first failure TERMs the rest and fails the task once they have exited (exit 1, as Nx), and the task succeeds once every command has (nx#28477). With `parallel: false` they run in order and the first failure stops the rest. `commands: []` is a no-op that succeeds (nx#31345).
- **Arguments:** every option run-commands does not consume is appended to each command as `--name=value`, then `args`, then whatever follows `vx run … --` — per command unless `forwardAllArgs` is false (nx#12165). `{args}` takes them in place; `{args.name}` is the value passed after `vx run … --` under that name, else the target's options and `args`, spliced in as text as Nx splices it.
- **An argument replaces its option:** an option the arguments after `vx run … --` name (`--region=us`, `--region us`, `--no-region`, `-r` for a one-letter option; no camel-case expansion) is not appended, as Nx drops it; the line decides once it has them. `tests/nx-run-commands-override-live.test.ts` holds it to `nx run`.
- **Environment:** `env` is `exec.env.define` (so it is in the key), and `color: true` sets `FORCE_COLOR=true`, as Nx does (nx#20465). `envFile` is loaded after the task's `.env` files (below), a name they already set winning, as in Nx (nx#23581).
- **`readyWhen`** makes the task persistent with that string as its `readyWhen`, so dependents start once it is printed; several strings, all of which Nx waits for, run the line under `nx-env --ready-when` (one flag per string), which passes the output through and prints `nx-env: ready` once every string has appeared on stdout or stderr; that line is the task's `readyWhen`.
- **A leading Nx call** (`nx <target> <project>`, `nx run <project>:<target>`, through `npx` / `pnpm` / `yarn` / `bunx` or not) in a serial line, or as its one command, is a `dependsOn` edge to that target (its default configuration, as Nx runs it) and leaves the line: ngrx's `build` opens with `nx build-package <project>`. One Nx would hand options or arguments to, one after another command, and one in a parallel line stay commands.
- **Reported, not reproduced:** per-command `prefix` / `color` decoration, `streamOutput: false`. Decoration in a serial run (`parallel: false`), which Nx refuses, is the failing placeholder with Nx's reason, as `readyWhen` there is. Display-only options (`usePty`, `tty`, `verbose`) change nothing here: vx runs every task without a pseudo-terminal.

`tests/nx-exec-live.test.ts` holds each of these shapes to Nx's own run-commands executor on the same options and arguments.

### Your own executors

A workspace executor that wraps a shell command (a run-commands with your defaults) can be a command instead of an `nx-exec` line, which spares the Node boot each `nx-exec` task pays. Pass `executors` to `nx()`, a function per executor name:

```ts
import { defineWorkspace } from '@vzn/vx/config'
import { nx, type NxExecutorTarget } from '@vzn/vx-migrate'

export default defineWorkspace({
  plugins: [
    nx({
      executors: {
        '@acme/tools:run': ({ options }: NxExecutorTarget) =>
          typeof options.command === 'string'
            ? { command: options.command, timeout: options.timeoutMs as number | undefined }
            : undefined,
      },
    }),
  ],
})
```

Each function (`NxExecutorTranslator`) gets one target, an `NxExecutorTarget`: `executor`, `project`, `projectRoot` (workspace-root-relative), `target`, `configuration` (set for a `<target>:<configuration>` task) and the resolved `options`. The option's type is `NxExecutors`. It returns an `NxExecutorTranslation`, `{ command, timeout?, env? }`: the command runs in the project dir, `timeout` is `exec.timeout` in ms, `env` is defined as a run-commands `env` is, and the target's `.env` files load as for a run-commands line. Returning `undefined` runs that target through `nx-exec`, as any executor not named. Inputs, outputs (cleaned before each run), `dependsOn` and caching come from the graph as for every target. `nx:run-commands`, `nx:run-script` and `nx:noop` (and their legacy names) are translated by `nx()` itself and are refused here, and so is a return that is not `undefined` or a valid translation. A function's source text keys the cached mapping, so it should depend on its argument alone. `bunx @vzn/vx-migrate` writes executor targets as `nx-exec` lines regardless.

### `.env` files

Nx loads a task's `.env` files into its environment — the project's before the workspace root's, the most specific name first (`.env.build.production.local`, `.env.build.production`, …, `.env.local`, `.local.env`, `.env`), a grouped target's named by its group's owner and parent (cypress's atomized `e2e-ci--a.cy.ts` loads `.env.e2e-ci` and `.env.e2e`), the first to define a name winning and the environment winning over every file — unless `NX_LOAD_DOT_ENV_FILES=false`. `nx()` finds the ones that exist from one listing of each project dir per run (about 4 ms at 1,000 projects) and the task loads them when it runs, with Nx's own parser: a shell line runs under `nx-env --dotenv <file>… --`, an executor line passes `--dotenv <file>` to `nx-exec`. Their values never enter a config, so a `.env.local` secret is not in `vx show`, `vx-lock.json` or a migrated `vx.config.ts`. A cached task keys on their bytes through a `cache.inputs.runtime` probe (`for f in …; do echo "$f"; cat -- "$f"; …`), which sees a gitignored file a glob would not; a file added or removed changes the command, and so the key, on the next run. `tests/nx-exec-live.test.ts` compares what the line sees with what `nx run` gives the same target.

### The target a task sees

Every task gets `NX_TASK_TARGET_PROJECT`, `NX_TASK_TARGET_TARGET`, `LERNA_PACKAGE_NAME` (the project, which Lerna on Nx's runner documents to scripts) and, where it runs a configuration, `NX_TASK_TARGET_CONFIGURATION` in `exec.env.define`, as Nx hands them to every task; a run-commands `env` wins. A package script's `nx exec -- <cmd>` reads them: without them it starts Nx's own task runner, which runs the target and its dependencies again.

### Inputs that key nothing here

`{ dependentTasksOutputFiles }` hashes the outputs of the tasks a target depends on; vx folds those tasks' keys through `dependsOn`, and an output follows from its inputs. `{ workingDirectory }` hashes the directory Nx was started from; a vx task runs in its project dir from wherever vx is started. Neither is a todo.

### The environment a task sees

Nx hands every task its whole environment; vx hands a task only its essentials (`PATH`, `HOME`, `CI`, `NODE_OPTIONS`, …), the names its Nx `{ env }` inputs declare (which also key it), and what `nx()` defines (the target, `.env` files, a run-commands `env`). A variable set in the shell and read by no declared input, `NODE_ENV` or `DATABASE_URL`, does not reach the task: declare it as an `{ env }` input of the target in the Nx config.

### Atomized targets

Two cached tasks on one workspace path cannot both keep their cache, and the first declared is kept. Cypress's atomizer gives `e2e` the whole `videos` dir and each `e2e-ci--<spec>` a subdir of it, so `nx()` also tries the split target (a `nonAtomizedTarget`) last and keeps the order that caches more tasks: each spec's CI task keeps its cache and `e2e` runs uncached, with the todo. Where the specs share the split target's one path (jest's coverage dir) the declared order stands.

### nx.json `parallel`

`parallel` (or the legacy `tasksRunnerOptions.default.options.parallel`) is the run's `concurrency` when `vx.workspace.ts` sets none, and `NX_PARALLEL` (a count or `50%`) wins over it, as in Nx: a repo that set `1` for a shared resource ran on every core under vx before.

### nx.json `defaultBase`

`NX_BASE`, else `defaultBase` (Nx 19's `affected.defaultBase` before it), is `affectedBase` when `vx.workspace.ts` sets none: a bare `vx run test --affected` compares with the ref `nx affected` does.

### nx.json `maxCacheSize`

`maxCacheSize` (or `NX_MAX_CACHE_SIZE`, above it as in Nx) is the run's `cacheRetention.maxSize` when `vx.workspace.ts` sets no retention, in Nx's grammar (`10GB`, `1.5 GB`, bare bytes); `0` is no cap.

### Lerna

`lerna run build` (Lerna 6+ runs it on Nx's task runner) runs each package's `build` after its dependencies' `build`, unless the repo configures Nx's task dependencies: nx.json `targetDefaults` (or the legacy `targetDependencies`), or an `nx` key in the `package.json` of a package that has the target. Beside a `lerna.json` with neither, each target's `dependsOn` is its `^` self (`build` → `^build`), in place of any other, as Lerna hands it to Nx; the exported graph holds no such edge. A migration writes the same.

### Project tags

An Nx project's `tags` are its vx `tags`, so `vx run build --filter tag:scope:web` (or Nx's `--projects tag:scope:web`) selects what `nx run-many -t build -p tag:scope:web` does. A package whose `vx.config` declares `tags` keeps its own. A blank tag is dropped (vx refuses one).

### The graph snapshot

Once per run the plugin keys its snapshot (`<cache dir>/nx-project-graph.json`) on what Nx computes the graph from: `nx.json` and the files its `extends` chain names by content, and the worktree as git sees it — `HEAD`, `git status -uall` (core's own for the run, `DiscoverContext.worktreeChanges`: the tree is walked once, which took ~96 ms per run on refine; a `root` elsewhere asks git itself), and the content of every listed path under a project root (the last graph's too, so a project `discover` names counts before it is one), any `project.json`, or at the root (manifests, lockfiles, `tsconfig*.json`). A different key, or no snapshot, runs `node_modules/.bin/nx graph --file=<snapshot>` (or, where the root links no `nx`, a Lerna repo on pnpm, the `nx` Lerna depends on, which `lerna run` runs) — the one time Nx itself runs, served from the daemon when one is up. So a source edit that adds a cross-package `import` (an edge Nx derives) or a config an Nx plugin infers targets from (`vite.config.ts`) re-exports before the run, tracked or untracked, and a touch without an edit, or a stray file a task writes at the root, does not. Outside a git worktree the plugin falls back to the manifests' mtimes. The snapshot and its key live in the cache dir, which ignores itself (a `*` `.gitignore` inside it), so writing them moves nothing. Nx's own caches (`.nx/cache/`, `.nx/workspace-data/`, which the export writes) never enter the key: under a root project (a standalone repo) that does not ignore them, each export re-exported on the next run. An export that fails with a snapshot in hand warns and runs on the previous graph. The snapshot is machine-local, like the cache: nothing about it enters a key. Measured at 1,000 projects: the export runs once (1.5 s with the daemon off after an edit, 0.9 s with it on; Nx's own computation), and a warm run with nothing changed pays the key, 43 ms at min where the manifest stats it replaced took 9 (item 1075), plus the mapping. Under `vx watch` the same rule runs per cycle: a `project.json` edit is the next cycle's tasks, the export included — 1.3 s from the edit to the new command's effect on that workspace. The mapping itself is kept beside it (`<cache dir>/vx-migrate-nx-mapping.json`), keyed on everything it reads — the graph, `nx.json` and its `extends` chain, every package manifest, each project dir's `.env` names, `NX_LOAD_DOT_ENV_FILES`, which bins are installed and the mapper's own code — so a warm run with nothing changed maps nothing.

### What it does not do

- A task the package's own `vx.config` already declares is left alone — the plugin fills, it never overwrites. Migrate a package by writing its config; the rest of the repo keeps running from the graph.
- An Nx project no workspace package matches — the root project, or an integrated repo's `project.json` library no package glob lists (analogjs) — is made a project through core's `discover` stage, by its `package.json` name or else its Nx name, and its targets attach there by directory; no `vx.config` is needed. One whose name a package already holds, or whose directory is gone, has nowhere to go and is reported once per run; run its targets with `nx`. A `^target` only such a project declares is no edge, as under Nx, and an explicit edge to one of its targets is dropped with a todo (the key misses it) rather than refusing the run. A negated output (`!{projectRoot}/dist/cache`) takes its path back from the positive ones (core's A-44). A cached target with no `outputs` takes what Nx caches for it: `options.outputPath` (each path of a list), or for `build` and `prepare` `dist/{projectRoot}` and `{projectRoot}/dist`; Nx's `{projectRoot}/build` and `{projectRoot}/public` are outputs too when git tracks nothing under them; one that holds a tracked file is a todo, since vx cleans an output before the run.
- Nx adds an `nx-release-publish` target (`@nx/js:release-publish`) to every project with a `package.json`; it comes along as one `nx-exec` task per package, run only when asked (`vx run nx-release-publish --filter <pkg>`), and counts in `vx info`'s task total. A migration does not write it: Nx release's publish step skips a private package and a published version and rewrites `workspace:` ranges, which no one line does, so the report has one note naming the package manager's own `publish`.
- `nx-exec` and `nx-env` must be on every task's PATH, which they are when `@vzn/vx-migrate` is a devDependency of the workspace (its bins land in `node_modules/.bin`); a plugin loaded by path warns once per run when they are not. Both load Nx from the workspace, so a repo run from an exported `graph` with no `node_modules/nx` warns once too.
- A `dependsOn` entry's `params: "forward"` (the run's arguments) and `options: "forward"` (this target's options, its configuration's merged in) hand the dependency overrides, a different command than vx's one task per target: each is one todo per task, naming no dependency so a run's warnings group them (an atomized `e2e-ci` forwards to every spec), `options` only when there are options to forward.
- Batch executors run one task per process; an executor that reads `context.taskGraph` under `NX_BUILDABLE_LIBRARIES_TASK_GRAPH` sees none and takes Nx's project-graph path.
- The mapping's gaps are the migration's gaps, reported as warnings once per run for all the tasks that carry each one. `bunx @vzn/vx-migrate --dry --from nx` lists the same set once.

## `nx-exec` — one Nx executor, one process

```
nx-exec <executor> --project <name> --target <name> [--configuration <name>] [--options '<json>'] [--dotenv <file>]... [overrides…]
nx-env [--dotenv <file>]... [--envFile <file>] [--ready-when <string>]... -- <command> [args…]
```

`nx-exec` is a bin this package installs, and what `nx()` runs for every executor target. It runs under the workspace's Node (executors are Node programs), resolves `nx` from the working directory up to the workspace's `node_modules`, reads Nx's cached project graph for the `ExecutorContext` executors expect (project root, dependencies for buildable libraries; computed in-process when the cache is missing or lacks the project, as `nx run` computes it, never through the daemon), **replaces** that project's target in the in-memory graph with the executor and options given, and calls Nx's own public `runExecutor`, so Nx's option merging, schema defaults and validation run unchanged. The executor runs from the workspace root, where Nx forks one, though vx starts the task in its project dir: an executor that resolves against `process.cwd()` (@nx/js's ts transformers, prettier's config) sees what it sees under Nx. Anything else on the line — what `vx run <target> -- --otp=123` appends — is an override, parsed by Nx's own `createOverrides` and handed to the executor as `nx run <p>:<t> --otp=123` would (nx#12165). `--dotenv` files are loaded into its environment first (see `.env` files above). The exit code is the outcome `nx run` reports: the executor's returned result when it returns one, else its last yielded result; a server executor keeps the process alive for as long as it yields. A thrown error (an executor's own, or a missing executor package) exits 1 with its message, and its stack only under `NX_VERBOSE_LOGGING=true`, as `nx run` reports one; an executor package that is not installed is one line naming it. The bin enables Node's on-disk compile cache for its own process (Node ≥ 22.1, a no-op below), which takes about 30 ms off every executed task after the first.

`nx-exec` sets `NX_DAEMON=false` unless set (it never dials the daemon), and `NX_VERBOSE_LOGGING=true` is the context's `isVerbose`.

`nx-env` loads the `.env` files and a run-commands `envFile` with Nx's own functions, then runs the command with `sh -c`, whatever follows it appended as vx appends forwarded arguments; its exit is the shell's. With `--ready-when`, the command's stdout and stderr pass through unchanged and `nx-env: ready` is printed once every string has been seen (one split across two writes included).

Why the command carries the options: vx's key sees them (resolved-config hashing holds), no ambient state decides what runs, `vx show` prints the truth and the line pastes into a shell. Each executed `nx-exec` line still loads Nx's own module graph (about 220 ms, on a miss only): it is a bridge, and the bare command that replaces it in native config pays none of that. The design is in `docs/design/nx-unchanged-2026-09.md`.

## `bunx @vzn/vx-migrate` — write the configs

```bash
bunx @vzn/vx-migrate           # auto-detect: turbo.json, .nx/workspace-data/project-graph.json, nx.json or lerna.json, then vite-plus
bunx @vzn/vx-migrate --dry     # print the generated files + the report instead of writing
bunx @vzn/vx-migrate --force   # overwrite existing vx.config.* / vx-preset.ts
bunx @vzn/vx-migrate --from nx # disambiguate when both runners are checked in
bunx @vzn/vx-migrate --from vite-task # Vite Task beside turbo.json or Nx
bunx @vzn/vx-migrate --native  # write vx.config.ts files without asking
bunx @vzn/vx-migrate --keep    # keep turbo.json / nx.json as the source: turbo() or nx(), as `vx init` writes it
bunx @vzn/vx-migrate --help    # the usage, exit 0
```

It is the one command a repo needs (`pnpx @vzn/vx-migrate` in a pnpm repo works the same):

- In a terminal it asks which adoption you want: **native** (the default, a `vx.config.ts` per package) or **keep** (the workspace file `vx init` writes, declaring `turbo()` or `nx()`). `--native` / `--keep` answer it; with no terminal (CI, a pipe) it is native.
- With no `vx.workspace.*` yet, it writes one declaring the plugins the repo calls for (`src/workspace-plugins.ts`): the `@vzn/vx-lockfile` factory for the lockfile (`pnpm()`, `bun()`, `npm()`, `yarn()`), `scheduleHistoryPlugin()`, and `github()` when `.github/workflows` exists, from `@vzn/vx-ci`, each installed beside `@vzn/vx` at vx-migrate's own version. Keep adds them to the file `vx init` writes, or to one already in that shape; any other workspace file is the user's and left alone. Native over a file vx wrote (a keep adoption's) rewrites it: `turbo()` and `nx()` go, since the configs written replace them, and the other plugins stay.
- It installs what the written files import with the repo's own manager (`packageManager`, else the lockfile): `@vzn/vx`, the declared plugins' packages, and `@vzn/vx-migrate` for keep or when a written task runs its `nx-exec` or `nx-env` bin (`pnpm add -D -w`, `yarn add -D -W` on Yarn 1 and without `-W` on Yarn 2+, `bun add -d`, `npm install -D`). A package the root both lists and has installed at vx-migrate's own version is left alone; any other is installed at that version. Native removes a listed `@vzn/vx-migrate` when nothing written needs it (no `nx-exec` / `nx-env` task, no `turboCache()` or `nxCache()` left in the workspace file): `pnpm remove -w`, `yarn remove` (`-W` on Yarn 1), `bun remove`, `npm uninstall`. `--no-install` skips both.

A Lerna repo is an Nx one: Lerna 6+ runs `lerna run` on Nx's task runner over the graph `nx graph` exports, nx.json or not, so a `lerna.json` with no nx.json and no turbo.json is mapped from that graph, and keep writes the workspace file declaring `nx()` (`vx init` adopts by nx.json, and would map the scripts). Lerna is the installed one, else the root manifest's range; with neither, the lerna.json is another tool's (lerna-lite reads it too, and runs no Nx). A root whose scripts never `lerna run` runs its tasks another way and publishes with Lerna (webdriverio: `run-s`, `pnpm -r`), so its scripts stay the source. Not where Lerna runs its own runner: `useNx: false`, or Lerna 5 without `useNx: true`; those are `vx init`'s scripts mapping. Beside turbo.json, Turbo runs the tasks and Lerna only publishes: turbo.json is the source.

Your `package.json` scripts are never edited. `--dry` installs nothing and says what it would install.

`--dry` prints the files instead of writing them; `--force` overwrites existing ones; `--mjs` writes `vx.config.mjs` (and `vx-preset.mjs`) instead of `.ts` — the same objects with no type import and no `satisfies`, for a package whose own `tsconfig` includes every `.ts` under it and would compile the config into its dist (TanStack/query, 2026-09-11).

`package.json` scripts are core's own `vx init`. What this package writes reads exactly like what `vx init` writes: both hand a plan to core's migration seam (`applyMigration` from `@vzn/vx`), which renders, refuses to overwrite without `--force`, writes and reports. Anything a source cannot say becomes a `TODO(vx-migrate)` comment, never a silent wrong value.

### Turbo

Reads the root pipeline (`tasks` in Turbo 2, `pipeline` in Turbo 1), per-package `turbo.json` `extends` overlays and each package's scripts, through the same mapper `turbo()` runs live — so the written configs say what the plugin was doing. Turbo's global fields become a generated root `vx-preset.ts` each config imports and spreads: TypeScript composition replaces global config. A package whose `tsconfig.json` is a composite project (or sets `rootDir`) and takes in its config declares the values it uses instead: `tsc` refuses a file outside the package (TS6059, TS6307; withastro/astro's `scripts/`). So does a task's `env` that several configs share (`buildEnv`), where inline it would repeat in every package (vercel/ai: 63 names, twice in each of ~100 configs, half the output). Turbo's `//#` root tasks are written to a `vx.config.ts` at the workspace root, which makes the root a project (core's D-39), and a package task's `//#x` edge reaches it. When a `vx.workspace.ts` already exists without one, the report names the `@vzn/vx-lockfile` plugin for the repo's lockfile: Turbo keys each package on its own lockfile entries, and core keys every task on the whole file until a plugin claims it.

| Turborepo                           | vx                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `dependsOn`                         | `dependsOn`, same micro-syntax (`$TURBO_ROOT$` deps are a TODO)                                   |
| `inputs`                            | `cache.inputs.files` (`$TURBO_DEFAULT$` → `**/*`; `$TURBO_ROOT$/x` → `workspaceFiles`)            |
| `outputs`                           | `cache.outputs.files`, a negated one included                                                     |
| `env`                               | `cache.inputs.env` **and** `exec.env.passThrough` (child envs are isolated)                       |
| `passThroughEnv`                    | `exec.env.passThrough`                                                                            |
| `cache: false` / `persistent: true` | no `cache` block; `exec.persistent: {}`, with a TODO to set `readyWhen` when a task depends on it |

### Nx

Reads the **resolved** project graph only (`.nx/workspace-data/project-graph.json` when exported, else the one the workspace's own `nx graph` exports into a temp file, as `nx()` does; with no `node_modules/.bin/nx`, as in a fresh clone, it stops and names the repo manager's install), through the same mapper `nx()` runs live, executors aside (below). Targets Nx plugins infer at runtime are frozen as the snapshot saw them. `nx:run-commands` is the one shell line `nx()` runs (see [`nx:run-commands`](#nxrun-commands) above: where, parallel or in order, forwarded arguments, `env`, `readyWhen`) — storybook's `compile` is `cd ../../.. && node ./scripts/build/build-package.ts --cwd code/lib/cli`; a plain `command` is that shorthand; `nx:run-script` is the package's script body with its `pre<name>` / `post<name>` hooks folded in (or `yarn run <name>` when the body calls yarn's `run` builtin; an empty script is the placeholder with a todo), `nx:noop` is a group task; Nx 15–16's `@nrwl/workspace:run-commands` and `run-script` (and their `@nx/workspace:` names) are the `nx:` executors they re-exported; **an executor target is its `nx-exec` line**, as `nx()` runs it: the migrator translates no executor, so Nx and `@vzn/vx-migrate` stay installed until each such line is rewritten as the command it runs (a server executor Nx knows, `@nx/js:node` or a dev server, is still a persistent task). The report also says what `vx.workspace.ts` still holds, as the Turbo migration does: the `nx()` `vx init` declared, which keeps reading nx.json, and a lockfile with no `@vzn/vx-lockfile` plugin, where Nx keyed each project on the npm packages it depends on. A written command that still runs Nx itself (a run-commands `nx run b:build`, `npx nx test b`, a script's `nx exec -- tsc`) carries a TODO: it works only while Nx is installed. An Nx project no workspace glob lists (an integrated repo's `project.json` library) gets a `package.json` (`name`, `private`) where it has none, and a note names the directories to add to `workspaces` (or `pnpm-workspace.yaml`): core finds a project only through those globs, and the migrator never edits the root manifest. A target with `configurations` writes one task per configuration (`build`, `build:ci`). A project's Nx `tags` are written as its `tags`. Named inputs expand from `nx.json` when readable. An output path is kept as written, a `!` one too (`{projectRoot}/dist` → `dist`, `{projectRoot}/bin/tool` → `bin/tool`; one naming an unset `{options.x}` is dropped, as Nx drops it; a dotted `{options.outputPath.base}` walks the options, as Nx does; an extglob is put in vx's grammar: Next's inferred `.next/!(cache)/**/*` is `.next/*/**/*` with `!.next/cache/**/*`, `@(js|map)` is `{js,map}`, and a form with no vx spelling is dropped with a TODO): vx reads a bare path as the file or the whole tree under it, so a directory and an extensionless binary both save and restore. nx.json's `parallel`, `defaultBase` and `maxCacheSize`, which `nx()` applies live, are each a field of the `vx.workspace.ts` it writes (`concurrency`, `affectedBase`, `cacheRetention.maxSize`), read from nx.json alone, never the environment; beside a workspace file already there, or for a size vx cannot read (`1.5 GB`), each is a note naming the field to add. vx derives package edges from `package.json`; an Nx graph edge with no manifest path (`implicitDependencies`, a tsconfig path) becomes, for each `^target` of the dependant, an explicit `pkg#target` edge to what Nx's own walk reaches — each dependency that has the target, and through one that lacks it, its dependencies — so the order and the key are Nx's. The reverse too: where a project's manifest names a workspace package its Nx graph does not reach (an `implicitDependencies: ["!a"]` that breaks a manifest cycle), its `^target` becomes the explicit edges Nx draws, since vx's `^` would follow the manifest and bring the cycle back.

### Vite Task

Detected when the root `package.json` lists `vite-plus`, after turbo.json and Nx: vite-plus is a whole toolchain, so a repo with either of those runs its tasks there; `--from vite-task` picks Vite Task anyway. There is no live plugin, so `--keep` is refused. Each package's `vite.config.*` (vite-plus's file order) is loaded by Bun as `vp run` sees it, a function config called in build mode, and its `run` block mapped with the package's `package.json` scripts, which `vp run` runs too. The root package's tasks and scripts (`vp run -w`) make it a project when it has a `name`. A command that opens with `vp run` (or `vpr`) is inlined as Vite Task inlines it: `vp run x`, `pkg#x`, `-r x`, `-w x` and `-F <name> x` are `dependsOn` edges (`-r` to each package with `x`, the task's own reference pruned), and the task is a group when nothing follows them. They run in parallel where Vite Task ran a chain in order; any other form (`--parallel`, `-t`, forwarded arguments, a `vp run` after another command) stays in the command with a TODO.

| Vite Task                                                 | vx                                                                                                                                                                                                     |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `command` (a string, or an array run in order)            | `exec.command`, the array joined with `&&`; `command: []` is a group task                                                                                                                              |
| `cwd`                                                     | `cd <cwd> && ` before the command                                                                                                                                                                      |
| `dependsOn: 'x'` / `'pkg#x'`                              | the same                                                                                                                                                                                               |
| `dependsOn: { task, from }`                               | `^task`; when a member listed under a field `from` leaves out also has the task, the explicit `pkg#task` edges, since `^` follows every field                                                          |
| `cache.input` / `cache.output` globs                      | `cache.inputs.files` / `cache.outputs.files`; `base: 'workspace'` → `workspaceFiles`, a root task's too                                                                                                |
| omitted or `{ auto: true }` (traced files)                | no `cache` block, with a TODO: vx infers no inputs or outputs                                                                                                                                          |
| `cache.env`                                               | `cache.inputs.env` **and** `exec.env.passThrough`; a `*` entry lists the names the package's tracked files and its workspace dependencies' spell (a TODO when none match); `!` entries take names back |
| `cache.untrackedEnv`                                      | `exec.env.passThrough`, wildcards as `cache.env`                                                                                                                                                       |
| `cache: false`, root `run.cache` `false` / `tasks: false` | no `cache` block                                                                                                                                                                                       |
| a `package.json` script                                   | a task, uncached; with root `run.cache.scripts` a TODO for its cache                                                                                                                                   |
| `run.enablePrePostScripts` (default `true`)               | a script's `pre<name>` / `post<name>` folded into its command; `false` keeps them tasks of their own                                                                                                   |

## `turboCache()` — a Turbo remote cache

Store vx artifacts in any server speaking Turbo's `/v8/artifacts` API — Vercel's hosted cache or a self-hosted implementation of the published OpenAPI spec (Bearer auth, `x-artifact-duration`, HMAC-SHA256 `x-artifact-tag` signatures). The wire is theirs; the bytes are vx's own artifacts under vx's own keys. The server is storage — the other tool cannot read what vx stores there, and vx does not read its entries.

Nothing is on by default. Declare the plugin in `vx.workspace.ts` and configure it explicitly. Reads try the local cache first and the remote only on a local miss:

```ts
import { defineWorkspace } from '@vzn/vx/config'
import { turboCache } from '@vzn/vx-migrate'

export default defineWorkspace({
  plugins: [
    turboCache({
      apiUrl: 'https://cache.example.com',
      token: process.env.CACHE_TOKEN,
      teamSlug: 'acme',
      // Optional: sign uploads and verify downloads (Turbo's artifact signature).
      // signatureKey: process.env.CACHE_SIGNATURE_KEY, teamId: 'team_acme',
    }),
  ],
})
```

Every option falls back to the tool's own environment variable, so a self-hosted setup carries over unchanged. A token with no `apiUrl` means Vercel's hosted Remote Cache (`https://vercel.com/api`), exactly as it does for `turbo` — so `npx turbo login && npx turbo link`, then `turboCache()` with `TURBO_TOKEN` / `TURBO_TEAM` set, is the whole hosted setup. Below the environment, in Turbo's order: a Vercel build's `VERCEL_ARTIFACTS_TOKEN` and `VERCEL_ARTIFACTS_OWNER` (the team id, where `TURBO_TOKEN` with a team is not set), then the repo's `.turbo/config.json` (what `turbo link` writes: `apiUrl`, `teamId`, `teamSlug`, `token`), then the root `turbo.json`'s `remoteCache` (`apiUrl`, `teamId`, `teamSlug`), whose `enabled: false` declines unless the options name a cache. With no token the plugin **declines** and the run stays local.

| Option            | Environment variable                                                                                                                     | Meaning                                                                                                                                                                                                                                                                       |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiUrl`          | `TURBO_API`                                                                                                                              | base URL of the cache server; default with a token: `https://vercel.com/api`; a `user:pass@` in it is refused                                                                                                                                                                 |
| `token`           | `TURBO_TOKEN`                                                                                                                            | Bearer token on every request                                                                                                                                                                                                                                                 |
| `teamId`          | `TURBO_TEAMID`                                                                                                                           | `teamId` query parameter; required with `signatureKey`                                                                                                                                                                                                                        |
| `teamSlug`        | `TURBO_TEAM`                                                                                                                             | `slug` query parameter                                                                                                                                                                                                                                                        |
| `signatureKey`    | `TURBO_REMOTE_CACHE_SIGNATURE_KEY`, read only under turbo.json's `remoteCache.signature: true` (or `TURBO_SIGNATURE`), as Turbo reads it | HMAC-SHA256 key (≥ 32 bytes, used raw); a download whose tag does not verify is a miss                                                                                                                                                                                        |
| `timeoutMs`       | `TURBO_REMOTE_CACHE_TIMEOUT`, then `remoteCache.timeout` (seconds)                                                                       | HEAD/GET/POST deadline (default 30 s; 0 none)                                                                                                                                                                                                                                 |
| `uploadTimeoutMs` | `TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT`, then `remoteCache.uploadTimeout` (seconds)                                                          | PUT deadline (default 60 s; 0 none)                                                                                                                                                                                                                                           |
| `retries`         | —                                                                                                                                        | resends of a request answered 429 / 5xx (not 501) or never connected (default 1, Turbo's); 0 turns them off                                                                                                                                                                   |
| `preflight`       | `TURBO_PREFLIGHT` (1 or 0), then `remoteCache.preflight`                                                                                 | send Turbo's `OPTIONS` preflight before each artifact request and go where its `Location` points (relative to `apiUrl`); the token goes along only when the API's `Access-Control-Allow-Headers` admits `Authorization`; a redirected preflight is not followed (default off) |

The signature is Turbo's current scheme (`artifact-signature:v2`: prefix, hash, team id and body, each length-prefixed, under HMAC-SHA256, base64 in `x-artifact-tag`). A signed body is written to a temp file before its tag can be checked, so one past core's artifact ceiling (2 GiB, at zstd's bound) is refused as it passes it, and is a miss.

Artifacts stream both ways on both wires: an upload sends the local artifact from its file, a download hands vx the response body to write straight to disk. A signed download must verify before vx sees a byte, so it is written to a temp file in vx's cache directory (which the sandbox walls, unlike the shared temp dir a sandboxed task may read) and verified from there (the tag covers the body's length, which a chunked response does not declare up front); a bad tag deletes the temp and reads as a miss, and a good one is handed over as a stream that deletes the temp once it is read or cancelled. A process that exits first (vx's Ctrl-C exit awaits no stream) deletes it on the way out.

## `nxCache()` — an Nx self-hosted remote cache

Store vx artifacts in any server implementing Nx's remote cache OpenAPI spec (`GET`/`PUT /v1/cache/{hash}`, Bearer auth, immutable records — a second write of a hash is `409`, which the plugin treats as done). Same rule: the wire is theirs, the bytes are vx's. A download asks for `Accept: application/octet-stream`, as Nx's own client does: an API gateway that keys binary media on `Accept` base64-encodes anything else (nx#33092); `turboCache()` asks the same way.

```ts
import { defineWorkspace } from '@vzn/vx/config'
import { nxCache } from '@vzn/vx-migrate'

export default defineWorkspace({
  plugins: [nxCache({ server: 'https://cache.example.com', accessToken: process.env.CACHE_TOKEN })],
})
```

Every option falls back to the tool's own environment variable; with nothing configured the plugin **declines** and the run stays local.

| Option        | Environment variable                       | Meaning                                                       |
| ------------- | ------------------------------------------ | ------------------------------------------------------------- |
| `server`      | `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`       | base URL of the cache server; a `user:pass@` in it is refused |
| `accessToken` | `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN` | Bearer token; omit for a server that runs open                |
| `timeoutMs`   | —                                          | per-request deadline (default 30 s; a positive number of ms)  |
| `retries`     | —                                          | resends, as `turboCache()`'s (default 1)                      |

The Nx spec has no existence probe, so `has` (the `--dry` prediction; the prefetch pass calls `get`) is a `GET` whose body is cancelled before it answers. The wire carries no producing-task duration, so a remote hit reports none.

## Remote-cache behaviour (both)

- A remote error degrades to a **miss** and a warning that names the request, the artifact and the server — `vx/turbo-cache: upload 32248a2a7c89e241 to https://cache.example.com/v8/artifacts failed: no answer within 60000 ms` — never the token. The run never fails because of the cache.
- The same failure is said once per run: an unreachable server fails the probe, the download and the upload alike, and the run prints the first and, at its end, `vx/turbo-cache: 2 more requests failed the same way: Unable to connect. Is the computer able to access the url?` (core's `LayeredCache` does the counting, for every cache plugin).
- A request answered `429` or `5xx` (not `501`), or one that never connected (a refused port, an unresolved host), is sent again after 2 s — a `429` after its `Retry-After`, capped at 10 s — as Turbo's client does. A spent deadline is not: it has already cost its wait.
- Three outages in a row (no connection, no answer within the deadline, or a `5xx` once the resends are spent) open Turbo's outage breaker: no request is sent for 30 s, each lookup is a miss at once, then one request probes and its answer closes or reopens it. A hit is judged when its body ends, so a server that sends headers and then stalls the body counts the same way. A hung server costs three deadlines, not one per task.
- A refused token (`401`/`403`) warns **once** and turns the layer off for the rest of the process (a `403` on an upload is a read-only token — Nx's spec, or turborepo-remote-cache's `READ_ONLY` and write-less JWTs: it turns off uploads alone, and reads go on) — including the requests already in flight when the refusal lands, which degrade in silence rather than repeating it (a six-project run printed five identical lines before 2026-09-20).
- Policy (`--cache=remote:r`, …) is enforced by core's `LayeredCache`, which the plugins wrap — a read-only token pairs naturally with `remote:r`.
- Each tool's own switches narrow that policy, never widen it, as they do for the tool: `TURBO_CACHE` (`--cache`'s syntax, an omitted source off) and `TURBO_REMOTE_CACHE_READ_ONLY` for `turboCache()`, `NX_SKIP_REMOTE_CACHE` / `NX_DISABLE_REMOTE_CACHE` (`true`) for `nxCache()`. A CI that keeps untrusted pull requests off the shared cache that way keeps vx off it too.

## Testing

`bun test` runs the Turbo and Nx plugins over fixture workspaces (the Nx one against a fake `nx` whose graph export and `runExecutor` are stubs, so the vx → `nx-exec` → executor → cache round trip is real), the migrate CLI over both sources, and each remote-cache wire against a strict in-memory implementation of its spec plus a full `vx run` round trip (miss → upload → local wipe → restore from the server). A separate suite points both plugins at a HOSTILE server — 500 on every request, 401, a server that never answers, and a body that is not an artifact — and pins that each one degrades to a miss with the run still green. `tests/nx-exec-live.test.ts` runs `nx-exec` against REAL Nx when `VX_NX_MODULES` names a directory whose `node_modules` holds `nx`, `@nx/js` and `typescript` (CI installs one under `packages/vx-migrate/.nx-live` and sets `VX_REQUIRE_NX=1`, so an absent install fails there instead of skipping).

## History

`vx migrate` was a core verb until 2026-09-10; it moved here so core reads no other runner's format. `@vzn/vx-turbo`, `@vzn/vx-turbo-cache` and `@vzn/vx-nx-cache` were separate packages until 2026-09-11, when adoption became one package. Typing `vx migrate` prints the pointer here.

---

# @vzn/vx-otel

> The OpenTelemetry exporter plugin for @vzn/vx.

The OpenTelemetry exporter plugin for [`@vzn/vx`](https://github.com/vznjs/vx).
Maps each `vx run` to **OTLP traces, metrics and logs** over HTTP/JSON — no
OpenTelemetry SDK dependency (it speaks the OTLP wire protocol directly, so the
package stays zero-dependency and version-drift-free).

## Usage

The options type is `OtelPluginOptions`.

```sh
npm install -D @vzn/vx @vzn/vx-otel   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
```

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { otel } from '@vzn/vx-otel'

export default defineWorkspace({
  plugins: [otel()],
})
```

`otel()` is **zero-config** via the standard OTel environment variables and
**declines safely** (exports nothing) when no endpoint is set — so it is safe
to declare in every environment:

| Variable                                                | Purpose                                                                                                                                                                            |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT`                           | base collector URL (e.g. `http://localhost:4318`)                                                                                                                                  |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`                    | full traces URL override                                                                                                                                                           |
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`                   | full metrics URL override                                                                                                                                                          |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`                      | full logs URL override                                                                                                                                                             |
| `OTEL_LOGS_EXPORTER=none`                               | export traces + metrics only                                                                                                                                                       |
| `OTEL_METRICS_EXPORTER=none`                            | no metrics                                                                                                                                                                         |
| `OTEL_TRACES_EXPORTER=none`                             | no traces                                                                                                                                                                          |
| `OTEL_SDK_DISABLED=true`                                | export nothing (the plugin declines)                                                                                                                                               |
| `OTEL_SERVICE_NAME`                                     | service name (default `vx`)                                                                                                                                                        |
| `OTEL_EXPORTER_OTLP_HEADERS`                            | `k=v,k=v` headers (e.g. auth), percent-encoded                                                                                                                                     |
| `OTEL_EXPORTER_OTLP_<SIGNAL>_HEADERS`                   | one signal's headers, over the shared ones                                                                                                                                         |
| `OTEL_RESOURCE_ATTRIBUTES`                              | `k=v,k=v` resource attributes, percent-encoded (a malformed one is dropped whole and warned); its `service.name` names the service when `OTEL_SERVICE_NAME` is unset               |
| `OTEL_EXPORTER_OTLP_TIMEOUT`                            | per-request timeout in ms (default 15000, at most 2³¹−1); `OTEL_EXPORTER_OTLP_<SIGNAL>_TIMEOUT` for one signal. The `timeoutMs` option must be a positive number, or it is refused |
| `OTEL_EXPORTER_OTLP_COMPRESSION`                        | `gzip` or `none` (default); `OTEL_EXPORTER_OTLP_<SIGNAL>_COMPRESSION` for one signal, the `compression` option over both                                                           |
| `OTEL_EXPORTER_OTLP_CERTIFICATE`                        | a PEM file of the CA that signed the collector's certificate (`_<SIGNAL>_` for one signal)                                                                                         |
| `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE` / `_CLIENT_KEY` | PEM files of a client certificate and key, for a collector that asks for mutual TLS                                                                                                |
| `OTEL_EXPORTER_OTLP_PROTOCOL`                           | vx sends OTLP/HTTP JSON only; under `grpc` a failed export says so (`OTEL_EXPORTER_OTLP_<SIGNAL>_PROTOCOL` per signal)                                                             |

Each signal ships only to its own URL: the base endpoint's `/v1/<signal>`
(appended to its path, before any query), or its override. A signal's own endpoint alone is enough: with only a metrics or logs
endpoint set, that signal exports and the others stay off. Spans and log records go at most 1 000 and 4 MiB to a
request, so a large run stays under a collector's body limit. Header names are case-insensitive (a signal's own
`Authorization` replaces the shared `authorization`); a name no header can
carry (`Authorization: Basic …` written curl-style, with a colon) is not
sent, and the warning prints neither its name nor its value. A `headers`
option value that is not a string is not sent either, with a warning
naming the header.

With only a traces URL set, metrics and logs are not
exported (they used to be POSTed to the traces URL, which a collector
refuses), and `metrics: true` or `logs: true` without a URL says so once.
Both are booleans: a string (`'false'` is truthy) is refused.

The package exports `otel`, its options type `OtelPluginOptions`, and the
types of the `post` option (a `PostFn`: the transport, fetch unless given,
handed each request's URL, body, headers, abort signal and `OtlpTls`). The
OTLP builders are internal (the wire they send is the contract,
`tests/contract/otlp.txt`).

Options override env:

```ts
otel({
  endpoint: 'https://collector.example.com',
  serviceName: 'my-monorepo',
  headers: { authorization: 'Bearer …' },
  metrics: true, // default
  logs: true, // default: each executed task's output tail
  timeoutMs: 15_000, // default: per request
  compression: 'none', // default; 'gzip' for every signal
  tracesEndpoint: 'https://traces.example.com/v1/traces', // one signal's full URL; also metricsEndpoint, logsEndpoint
})
```

## What it exports

**A trace per run** (OTel CI/CD + VCS semantic conventions):

- a root `vx.run` span — `cicd.pipeline.run.id`, `vcs.ref.head.revision`,
  `vcs.ref.head.name`, `vx.command` (the command line; what follows `--`
  is counted, `-- <N arguments>`, never quoted, and a secret value
  before it is `***`), CI provider,
  host/os/arch, vx version, `--tag k=v` →
  `vx.tag.<k>`, and `cicd.pipeline.result` (`success`, `failure`, or
  `cancellation` for a run stopped with nothing failed); a red run sets
  span status `ERROR`;
- a child `vx.task` span per task — `cicd.pipeline.task.name`,
  `cicd.pipeline.task.run.result` (the convention's enum: `success` for a
  run or a hit, `failure`, `timeout`, `skip`, `cancellation`), vx's own
  status as `vx.task.status`, `vx.cache.source` (miss/local/remote, or none for a task that never ran),
  on a hit `vx.cache.restored` (`true` when it restored outputs, `false` when they were already up to date),
  `vx.task.hash`, duration, CPU ms, peak RSS, and on a skipped task its root
  blocker (`vx.task.blocked_by`), on a timed-out one `vx.task.timed_out`, on
  a sandboxed one its violation count (`vx.task.sandbox_violations`), on a
  persistent one that never became ready why (`vx.task.not_ready`), its
  command (`vx.task.command`, secrets masked), on a flaky one its record
  (`vx.task.flaky.passes`, `vx.task.flaky.failures`), on a hit what the
  stored run took (`vx.cache.stored_duration_ms`, `vx.cache.stored_cpu_ms`,
  `vx.cache.stored_peak_rss_bytes`), how long an `admit` policy held it
  (`vx.task.admission_held_ms`), how long it waited ready for a worker
  (`vx.task.queued_ms`, the hold included), and on a cacheable task that
  ran how many files its key read (`vx.task.input_files`) and what its key
  changed since the last entry the cache saved for it
  (`vx.cache.miss.change_count`, and `vx.cache.miss.changes`, the first ten
  as `changed file packages/a/src/x.ts`), and what the cache cost: the
  artifact's size (`vx.cache.artifact_bytes`, a hit's entry or the one a
  miss saved), a miss's save (`vx.cache.save_ms`) and a remote hit's
  download (`vx.cache.fetch_ms`). The run span adds the remote uploads
  once they settled (`vx.cache.upload.count`, `.bytes`, `.ms` summed,
  `.failed`). A
  failed task sets span status
  `ERROR`. A task span links to the spans of the tasks it waited on (a
  group seen through to the tasks behind it), and carries an event per
  attempt that failed and was run again (`vx.task.retry`, with
  `vx.task.attempt` and `vx.task.exit_code`), one when vx's own
  timeout killed it (`vx.task.timeout`), and one per sandbox violation
  (`vx.sandbox.violation`, its line; past 100, `vx.sandbox.violations_dropped`
  says how many more);
- a child span per stage of the run, named by the stage (`startup`,
  `load configs`, `git enumeration`, `classify + probe`, `run graph`,
  `record history`, …, the stages `VX_TIMING` prints), with
  `vx.stage.name`: where the time before the first task and after the
  last went. The stages ahead of the run lock end before the `vx.run`
  span starts.

**Metrics per run**: `vx.tasks.total`, `vx.tasks.failed`,
`vx.tasks.cache_hits{source=local|remote}`, what those hits did to the disk as
`vx.tasks.cache_restored{source=local|remote}` and `vx.tasks.cache_up_to_date`,
and the `vx.run.duration_ms` and `vx.run.time_saved_ms` (what the hits'
stored runs took) gauges. The `vx.run` span carries the same counts
(`vx.run.hit_count`, `vx.run.up_to_date_count`, `vx.run.restored_local_count`,
`vx.run.restored_remote_count`).
The counts are DELTA sums over the run's own interval (start to end), so a
backend adds runs rather than reading each as the series' new total.

**Metrics per task**, as gauges keyed by `cicd.pipeline.task.name`,
`vx.task.project` and `vx.task.task`: at each task's end
`vx.task.duration` (ms, with `vx.cache.source`), and for a task the runner
measured `vx.task.cpu_time` (ms) and `vx.task.peak_memory` (bytes), on a
hit `vx.task.time_saved` (ms), `vx.task.admission_held` (ms) when an
`admit` policy held it, `vx.task.queued` (ms) when it waited for a
worker, `vx.task.artifact_size` (bytes), `vx.task.cache_save` and
`vx.task.cache_fetch` (ms); a skipped task sends none. While a task runs, its process tree is sampled
each second: `vx.task.cpu_usage` (cores busy since the last sample, 1 =
one core) and `vx.task.memory` (resident bytes). Sampling runs only while
metrics export; a remote task, or a task under 1 s, has no samples.

**Logs per run** (on by default): the captured output tail of each executed
task, as one log record at the task's end, linked to its task span (unlinked
when traces are off: the span is never exported). Build output can hold
secrets, and this sends it to the collector; `logs: false` or
`OTEL_LOGS_EXPORTER=none` turns it off.

**One run, three signals, linked.** Every request's resource names the run
(`service.instance.id` and `cicd.pipeline.run.id`, its id), the host
(`host.name`, `host.arch`, `os.type`), the commit (`vcs.ref.head.*`) and
the repository (`vcs.repository.url.full`, `vcs.repository.name`,
`vcs.owner.name`, `vcs.provider.name`, from the `origin` remote) with
`vx.workspace.path`, the workspace root inside it (`.` at the top), and on
CI the run (`cicd.pipeline.run.url.full`, `cicd.pipeline.name`,
`vx.ci.job`, `vx.ci.attempt`) and the pull request it builds
(`vcs.change.id`; GitHub Actions, GitLab, Buildkite, CircleCI), under `OTEL_RESOURCE_ATTRIBUTES`, which wins. Each task metric point carries
its task's span as an exemplar, and each log record its span, so a chart
opens the trace and a span opens its output.

## Live export

On by default; `otel({ live: false })` sends everything at the end instead.
Each task's span, metrics and output tail are sent as the
task ends, its process samples as they are taken, and a log record
(`event.name` `vx.run.start` or `vx.task.start`, linked to the trace) as the
run and each task start; the `vx.run` span, the stage spans and the run's
metrics follow at the end. A dashboard follows a CI run while it runs.
Sends are batched: one per second at most, one in flight at a time, each
taking everything that ended meanwhile; a refused send warns once per
signal for the run. On 60 tasks against a local collector the run burns the
same CPU live as with one send at the end (median of 10: 815 ms both).

No send ever holds a task: a task's end only queues its records. A collector
that never answers holds nothing either: at the end of the run every send
still in flight is cut at core's teardown deadline (3 s,
`VX_TEARDOWN_TIMEOUT_MS`), and the process exits.

## Behavior note

This replaces core's previous hardcoded OTel emit, which fired automatically
whenever `OTEL_EXPORTER_OTLP_ENDPOINT` was set. OTel is now a **plugin**: the
env var alone no longer auto-exports — you must declare `otel()` in
`vx.workspace.ts`. Telemetry is observe-only and can never change, slow, or
fail a run (every export is buffered, time-bounded, and swallows errors).

A collector shedding load (`429`, `502`, `503`, `504`, or a dropped
connection) is retried twice, 200 then 800 ms apart or after the
`Retry-After` it names (at most 2 s), inside the end-of-run deadline; a
deadline that passes mid-wait ends the retries and warns the last answer.

Swallowed, but not silent: an export that does not land warns once per
signal URL, naming what happened — a collector that cannot be reached, one
that refuses the request (`HTTP 401`, `404`, `500`, with the collector's own
message), or one that accepts it and reports part of the data dropped
(OTLP's `partialSuccess`). A collector that answers with a redirect
is refused too, naming where it points: like the OTel SDK exporters,
vx-otel follows none, since a header such as `x-honeycomb-team` would
reach the new origin with it. The URL in that line is printed with any
userinfo and query string replaced by `***`, so an endpoint that carries
its credential in the URL does not leak it into a CI log. The run stays
green either way; a collector that
takes too long is cut off by core's end-of-run deadline
(`VX_TEARDOWN_TIMEOUT_MS`, 3 s by default) with a line saying the buffered
records were lost.

---

# @vzn/vx-reapi

> A vx remote cache backed by any server speaking Bazel's

A vx **remote cache** backed by any server speaking Bazel's
[Remote Execution API](https://github.com/bazelbuild/remote-apis) — NativeLink,
BuildBuddy, Buildbarn, bazel-remote: mature server implementations, none of
which we had to write, because a REAPI server is deliberately dumb.

```sh
npm install -D @vzn/vx @vzn/vx-reapi   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
```

```ts
// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { reapi } from '@vzn/vx-reapi'

export default defineWorkspace({
  // Reads try the local cache first, then the remote; a remote hit is copied to local.
  plugins: [reapi({ endpoint: 'grpcs://cache.example.com:443' })],
})
```

`ReapiRemoteCache` is the layer class behind `reapi()`, for a workspace that
composes cache layers by hand. The package exports `reapi`, `ReapiPluginOptions`,
`ReapiRemoteCache` and its `ReapiOptions`; the wire client, the Merkle
encoders and the executor are internal. `ReapiOptions` is the connection
as the plugin resolves it: the same fields, with the PEM text itself
(`tlsCaPem`, `tlsClientCertPem`, `tlsClientKeyPem`) in place of the files,
and `onWarn` for a degraded-but-recovered call; `reapi()` refuses those four,
reading files and warning through vx. With no endpoint configured (or a blank
one) the plugin **declines** and costs nothing, so it is
safe to leave declared. An endpoint that is not `host[:port]`, with an
optional `grpc(s)://` or `http(s)://` scheme, or a gRPC resolver target
(`unix:`, `unix-abstract:`, `dns:`, `ipv4:`, `ipv6:`), is refused at startup
with a line naming the setting. `VX_REAPI_ENDPOINT` / `VX_REAPI_INSTANCE` configure it
from the environment, and `VX_REAPI_EXECUTE=1` turns on remote execution the
way `execute: true` does (off by default: a plugin must not move where a
build runs merely by being configured for caching). `execute` is a
boolean: a string (`process.env.X`) is refused.
`instanceName` is the option form of `VX_REAPI_INSTANCE`; like the endpoint
it is trimmed, and a blank one is unset. `headers`
adds gRPC metadata to every call: a hosted server's API key goes there
(`headers: { 'x-buildbuddy-api-key': process.env.BB_KEY! }`).
`toolName` and `toolVersion` (default `vx`, `0.0.0`) fill each call's
`RequestMetadata.tool_details`, and `correlatedInvocationsId` groups several
runs as one build in a server's UI.

TLS is on unless asked off, as in Bazel: a bare `host:port`, a `grpcs://`
or `https://` endpoint, and a `dns:`/`ipv4:`/`ipv6:` target all use it.
Plaintext takes a `grpc://` or `http://` endpoint or `tls: false`; a `unix:`
or `unix-abstract:` socket is plaintext (`tls: true` turns it on). It uses the system roots unless told otherwise. A server behind a private
CA takes `tlsCertificate` (or `VX_REAPI_TLS_CERTIFICATE`), a PEM file of
that CA; one that asks for mutual TLS takes `tlsClientCertificate` and
`tlsClientKey` (`VX_REAPI_TLS_CLIENT_CERTIFICATE` / `VX_REAPI_TLS_CLIENT_KEY`)
— Bazel's `--tls_certificate`, `--tls_client_certificate` and
`--tls_client_key`. Any of them turns TLS on unless `tls: false` is set; a file that cannot be read
is refused at startup, naming the setting.

## How a vx cache key becomes a REAPI entry

A CAS digest is the sha256 of the **content**, so it cannot be derived from a
vx cache key before the bytes exist — `has(key)` could never answer. The
ActionCache supplies the missing indirection:

| vx                   | REAPI                                                                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cache key            | synthetic action digest — `sha256("vx-reapi-v1\0" + key)`                                                                                                        |
| artifact (`tar.zst`) | one CAS blob, referenced by the ActionResult's `output_files`                                                                                                    |
| task duration        | `stdout_raw` on the ActionResult                                                                                                                                 |
| cache miss           | `GetActionResult` → `NOT_FOUND`                                                                                                                                  |
| cache hit            | `GetActionResult` asking for stdout and the artifact inline: a server that honours it (bazel-remote, up to ~1 MiB) answers a small hit in one round trip         |
| cache save           | an artifact up to 256 KiB is read once and goes in one `BatchUpdateBlobs`, unprobed; a larger one is probed with `FindMissingBlobs` and streamed only if missing |

The `vx-reapi-v1` prefix does two jobs: it keeps vx keys out of the address
space of real Bazel action digests on a shared server, and it makes a future
change to this mapping **miss cleanly** rather than read bytes written under
different rules.

Servers may normalise an inline `stdout_raw` into a CAS blob and hand back a
`stdout_digest` instead (bazel-remote does). The read path accepts either.

## Bun and chunk size

`chunkBytes` defaults to **65535 and is not a throughput knob.** Bun's
`node:http2` client _hangs_ — it does not error — when a request carries more
than one message and any single message exceeds a ceiling that **the server's
flow-control behaviour decides**. Go's gRPC servers grow their window
dynamically (a `WINDOW_UPDATE` then a `SETTINGS` raise) and Bun mishandles the
tail of that sequence; a `node:http2` server, which does not do it, accepts
4 MB writes happily.

See Bun [#30342](https://github.com/oven-sh/bun/issues/30342) and
[#26915](https://github.com/oven-sh/bun/issues/26915), largely fixed by
[#31584](https://github.com/oven-sh/bun/pull/31584) — which is why the ceiling
_rose_ from ~64 KB on Bun 1.3.x to ~216 KB on 1.4.0 rather than the hang going
away. Hence **Bun >= 1.4** is required, and the plugin refuses to start on
anything older with a named error: the alternative is a wedged upload with
nothing for a user to act on.

The default is the one size with no peer-dependence — 65535, the RFC 7540
default initial window every peer must honour with no `WINDOW_UPDATE` at
all (`SAFE_CHUNK_BYTES`). 128 KB was the default until it stalled a 1 MiB
write against bazel-remote in 2 of 12 fresh runs (Bun 1.4.2), each costing
the call's 30 s deadline; 65535 stalled in none, and costs ~51% on a 32 MiB
upload (390 → 590 ms on loopback). A larger `chunkBytes` is still accepted:

```ts
reapi({ endpoint: '…', chunkBytes: 128 * 1024 })
```

The stall is a RACE, not a boundary. So above the safe size the client
**downgrades adaptively** — a deadline on a multi-message write retries once at
`SAFE_CHUNK_BYTES` with a warning, turning a lost coin-flip into a logged
retry instead of a failed task. The deadline counts in either spelling: the
client's own `DEADLINE_EXCEEDED`, or the `CANCELLED` a grpc-go server such as
bazel-remote sends when the call's `grpc-timeout` runs out first (a
`CANCELLED` before the deadline is the server's own and is not retried). The full probe matrix is in
`packages/vx/docs/design/plugin-executor-reapi-2026-08.md` §14.

## Repeat runs skip the worker

Every successful remote execution writes an execution record under the
task's vx key (`vx-reapi-exec-v1`), listing its outputs by digest plus
its stdout (inline up to 64 KiB, a CAS blob past it), written while the
outputs come down. A later run whose vx cache missed but whose key already has
a record skips the Merkle build, the upload pass and `Execute`
entirely: the outputs are already in the CAS, and stdout replays from
the record. `--force` bypasses it.

The input tree is read after the key was taken, so each file's bytes are
held to the git blob id the key folded for it. A file edited or removed
in between (an edit mid-run under `vx watch`) still runs, but the
execution is not recorded under a key that no longer describes it; the
record once replayed the edited outputs on every machine after the file
was restored. The project's own `package.json`, which the key folds
whether or not a glob lists it, is always in the input root.

This matters most under `--download=none`, where deferral leaves no
local cache entry behind, so vx's own probe misses on every later run
and the record is what makes the second run cheap. Records are checked
against the CAS first (`FindMissingBlobs`) — the action cache and the
CAS evict independently, so a record that outlived its blobs falls
through to a real execution rather than "succeeding" with nothing.
The replay itself is a cache read too: a transport failure reading the
record, its stdout or any output warns and executes, after removing
whatever the half-done replay created (core cleaned the outputs once,
before the replay, and the real run's result must not inherit them).
The probe sees a Tree by its own digest, not the blobs inside it, so
one of those gone is caught by the replay: under any capture shape it
fails the replay, and the task executes. (A fresh result under a
whole-tree capture still only warns, since the capture holds more
than the outputs.)

An UPSTREAM's evicted blobs get the opposite answer, because there is
nothing to fall through to. When a dependency's outputs live only in
the CAS — vx grafts them by reference precisely because no local copy
exists — and those blobs are gone, the action cannot be built with the
inputs its key claims. vx fails the task and names the upstream rather
than shipping the action without them: a command that tolerates the
absence exits 0, and that successful-but-wrong result would be cached
under a key asserting those bytes were present. Which upstream bytes a
command actually reads is unknowable — that is what `dependsOn`
declares — so the refusal is the only sound reading, and it matches
what core does when a deferred producer cannot be materialised.
Re-run the upstream (`--force`) to repopulate the store.

Bringing a task's OWN outputs back gets the same treatment. Core's
contract is that once an executor returns, the declared outputs are on
disk, because the ordinary save path then tars whatever it finds — so
an output blob that cannot be fetched is a hole that would be cached
under a key claiming a complete build. Under a literal capture the
worker returns only what `output_paths` named, so every returned file
is a declared output and an unfetchable one fails the task. The
exception is a glob whose FIRST segment is a wildcard (`*.js`): it has
no REAPI spelling, so it is sent as `''` — whole-working-directory
capture — and inputs and undeclared siblings come back too. Those
cannot be told apart from real outputs, so a missing blob there only
warns, unless a declared glob names it: that is a hole in a declared
output and fails the task under either shape. Inline output bytes are
checked against their digest like fetched ones; a mismatch is fetched.

A capture cut at a wildcard holds more than the outputs: `src/*.gen.js`
is sent as `src`, and the worker returns the sources beside the
generated files. Only what a declared glob names (or what sits under a
directory it names) is written back; the rest stays as it is on disk.
Writing all of it once put the worker's copy of the sources over the
user's, so an edit made while the action ran was lost. A directory a
literal glob names is written whole.

## The existence probe confirms the artifact, not just the entry

`has()` — what `vx run --dry` and `--graph` use to predict hit vs miss —
reads the ActionCache entry AND checks the artifact blob is still in the
CAS. The second call is not redundant, because servers disagree: measured
against both, bazel-remote validates an ActionResult's referenced blobs
and hides a dangling entry, while NativeLink serves it. Without the
check, a plan would report `cache hit (remote)` for a task that then
executes for real. It costs one extra round trip and only for a PREDICTED
HIT — a miss still answers in a single call.

## Downloads are verified

Every blob read — ByteStream and batch alike, compressed or not — is
re-hashed with the negotiated digest function and length-checked against
the digest it was requested under. Bytes that don't match are refused with
a named integrity error instead of being written into the local
content-addressed store: a corrupt or poisoned remote degrades to a miss
(the cache invariant), never to wrong bytes under a trusted name. Uploads
were always server-verified; this is the mirror on the read side, the same
check Bazel's client performs. A streamed read (the cache artifact) is
hashed as its bytes pass and errors at its end on a mismatch, so vx's
ingest fails and the hit is a miss. The size is held as the bytes arrive:
a body past its digest's size is refused at the byte that passes it, a
zstd reply is decoded no further than that size, and a batch entry for a
digest not asked for is dropped.

A verified blob still lands where the server's ActionResult says, so its
paths are held to the workspace: an output path or Tree name that climbs
out (`..`, absolute), a link whose target leaves the workspace (read as
the OS follows it, through the links the result placed), and a
directory that resolves out through a link are refused before anything
is written through them; a link standing at an output file is replaced, never written
through; a Tree file's setuid and setgid bits are dropped.

## Artifacts stream

An artifact up to 256 KiB is read whole and sent in one batch, with no
probe first. Up to the batch limit (about 4 MiB) it is read whole once,
probed with `FindMissingBlobs`, and those bytes sent. Past that the cache
layer never holds an artifact whole: `put` digests the file-backed `Blob`
vx hands it in one pass over its stream, asks `FindMissingBlobs`, and
uploads from a second pass, read `chunkBytes` at a time as the ByteStream
write drains, identity-encoded (the artifact is zstd already). `get` returns the ByteStream read as a
`Response`, each message taken from the call as vx writes the previous one
to disk.

## Deadlines: a wedged server degrades, it does not hang

Every call carries a deadline, because the killer case is not a server that is
DOWN — that is an instant `UNAVAILABLE` the cache layer degrades to a miss —
but one that accepts TCP and never answers. Without a deadline no error ever
happens and the first probe hangs the whole run.

There are TWO deadlines, and the split matters:

| option          | covers                                                                                | default                      |
| --------------- | ------------------------------------------------------------------------------------- | ---------------------------- |
| `metaTimeoutMs` | Capabilities, GetActionResult, UpdateActionResult, FindMissingBlobs, QueryWriteStatus | `min(callTimeoutMs, 15 000)` |
| `callTimeoutMs` | ByteStream transfers, Batch{Read,Update}Blobs, Split/SpliceBlob                       | `30 000`                     |

A control-plane message is small and bounded: a healthy server answers in
single-digit milliseconds. A bulk transfer is size-proportional and
legitimately slow — capturing a `node_modules` tree is what pushes real
deployments to raise `callTimeoutMs` into the minutes. With one knob for both,
buying headroom for that upload also buys every metadata probe the same
minutes before it can degrade, which is the opposite of what the deadline is
for.

Each deadline must be a positive number of ms; anything else is refused when
the plugin starts. `executeTimeoutMs` and `queueTimeoutMs` are held to the
same rule when the executor starts, so with `execute` off they are not
checked.

That is not hypothetical. A NativeLink instance degraded into a state where it
answered every ActionCache MISS in 3 ms and every HIT never — idle CPU,
nothing in its logs, cleared by a restart with identical on-disk data. With a
single 180 s deadline, every task burned three minutes on a lookup before
failing. Now the probe gives up in 15 s and the run re-executes.

What the run prints is one line per kind of failure:
`vx/reapi: probe <key> at <endpoint> failed: 4 DEADLINE_EXCEEDED: …`.
Core's layered cache names the request, the vx key and the server (a
gRPC status carries none of them), and a later request that fails with
the same status is counted, not repeated: the run ends with
`vx/reapi: N more requests failed the same way: …`.

Execution streams are deliberately NOT bounded by either: queueing behind a
busy worker pool is legitimate. A wedged server still cannot reach Execute,
because the deadline-bounded Capabilities call runs first. The wait for a
worker is bounded by `queueTimeoutMs` when set: no EXECUTING within it, the
Execute stream is closed, the operation is cancelled with
`Operations.CancelOperation` (one attempt on `metaTimeoutMs`; a server
that refuses it, or lacks the service, may still run the action, and its
result lands in the action cache) and the task is given back to vx, which
runs it here and says so once:
`[vx] <task>: vx/reapi: no worker started the action within queueTimeoutMs (…ms); its operation was cancelled — running it here`.
A task placed `exec.remote: 'only'` fails with that reason instead. Unset,
the task's own `exec.timeout` bounds the queue as it bounds the run (the
task fails as timed out); with neither, the wait is unbounded.
A stream that drops with a transient status, or ends cleanly before its
operation is done, re-attaches with `WaitExecution` (three times, backing
off 100, 400 and 1600 ms) rather than running the action again. If
`WaitExecution` answers NOT_FOUND — the server lost the operation, as a
restart does — nothing is left running to re-attach to, and the action is
executed again on the same budget.
Once a worker reports EXECUTING, the task's `exec.timeout` (or
`executeTimeoutMs`) bounds the wait, and the bound holds across a
re-attach: firing during the backoff between a dropped stream and its
`WaitExecution`, it ends the task there rather than being lost.
The run stopping (Ctrl-C, an embedder's abort) cancels the operation
stream the same way, and an action not yet submitted is not sent.

A ByteStream Read, like every unary call, retries UNAVAILABLE,
RESOURCE_EXHAUSTED and INTERNAL three times (100, 400 and 1600 ms) before it
counts as failed. A streamed read (the artifact of a remote hit) spends
the same budget across the whole blob: a cut after bytes have reached the
reader re-opens the Read at `read_offset` = what the reader has, and the
digest is checked over the joined bytes as before. INTERNAL is on the list because it is how the gRPC client
reports a call cut in transit: the RST_STREAM(INTERNAL_ERROR) a proxy sends
when the server behind it goes away, or a stream that ends with no gRPC
status. The same three statuses are what re-attach a dropped execution
stream.

A server that stays down pays that backoff once: after a call spends its
retries on UNAVAILABLE, the cache path's calls (unary, Read, Write) give up
at their first UNAVAILABLE until the server answers again, so a refused port
costs a five-task run 2.6 s, not 24.

A status the server answers with and no retry heals (PERMISSION_DENIED on
Execute, a refused upload) fails the task with a line naming the task and
the status, never as a vx "internal error".

A failed READ is never a failed task. The execution-record lookup is a
shortcut past the worker, so a transport error there means "no usable record"
and the task executes normally, with a warning naming why. The UPSTREAM record
reads are the deliberate exception — those decide whether a dependency's bytes
exist at all, and carrying on past a failure there is how an action runs
without its inputs and caches the result.

## Tests

`bun test` runs the unit suite anywhere. The round-trip suite needs a real
server:

```sh
docker run -d -p 19092:9092 buchgr/bazel-remote-cache:latest \
  --dir /data --max_size 1 --grpc_address 0.0.0.0:9092 --http_address 0.0.0.0:8080

VX_REAPI_TEST_ENDPOINT=grpc://127.0.0.1:19092 bun test
```

Without an endpoint those tests skip; CI sets `VX_REQUIRE_REAPI=1`, which turns
an absent endpoint into a failure so the suite cannot silently vanish. The
remote-execution suites need an execution server in `VX_REAPI_EXEC_ENDPOINT`;
CI sets it with `VX_REQUIRE_REAPI_EXEC=1`.

## Protocol coverage

All **14 RPCs** across the five services, not a working subset:

| Service                     | RPCs                                                                                           |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| `Execution`                 | `Execute`, `WaitExecution`                                                                     |
| `ActionCache`               | `GetActionResult`, `UpdateActionResult`                                                        |
| `ContentAddressableStorage` | `FindMissingBlobs`, `BatchUpdateBlobs`, `BatchReadBlobs`, `GetTree`, `SplitBlob`, `SpliceBlob` |
| `Capabilities`              | `GetCapabilities`                                                                              |
| `ByteStream`                | `Read`, `Write`, `QueryWriteStatus`                                                            |

Protocol features in use, not just reachable:

- **Digest negotiation** — SHA256 by default (the universal baseline; the
  Merkle encoders must hash with the SAME function as every upload, so
  auto-upgrading would mix functions inside one action). The plugin
  offers no other.
- **zstd compression** — `compressed-blobs/zstd/…` resource names on
  ByteStream and `compressor: ZSTD` on batch updates, enabled only when
  `supported_compressors` says so.
- **`RequestMetadata`** in the well-known binary header (tool name/version,
  action id, correlated invocations id) — how a server groups an action's
  dozens of CAS/AC calls into one build in its UI.
- **Inline stdout/stderr** on `ExecuteRequest`, sparing two CAS round trips
  per finished action. A failed execution status that carries a partial
  result (a worker past its timeout) still prints what the command wrote.
- **Execution stages** — `QUEUED` / `EXECUTING` / `COMPLETED` decoded from
  `ExecuteOperationMetadata`, so a queued action is distinguishable from a
  hung one.
- **`Action.platform`** (v2.2) alongside `Command.platform` for older
  servers.
- **`NodeProperties`** — `unix_mode` and `mtime` on tree nodes.
- **Output directories** via the `Tree` blob an `OutputDirectory.tree_digest`
  addresses, plus **output symlinks** (a v2.0 server's
  `output_file_symlinks` / `output_directory_symlinks` when it sends only
  those). A tree's small files are fetched
  together across its directories (`BatchReadBlobs`, 64 MiB at a time),
  not one call per directory.
- **Upload minimality** — `FindMissingBlobs` first (split so no request
  passes a 4 MiB message), then batched blobs while they fit the server's
  budget and ByteStream beyond it.

## Remote execution

Off by default. Remote execution changes where a user's build runs, which is
not something a plugin should switch on merely by being configured for
caching:

```ts
reapi({
  endpoint: 'grpcs://grpc.example.com:443',
  execute: true,
  platform: { 'container-image': 'docker://alpine:3.20', OSFamily: 'Linux' },
  capacity: 64, // concurrent remote tasks; becomes the scheduler's pool
})
```

A cache-only server (bazel-remote advertises `exec_enabled: false`) makes the
plugin **decline the executor with a warning** rather than submit work that
will never be answered. Only cacheable tasks are eligible — a task with no
`cache` block has no described inputs, so a worker would run it against an
empty input root. A cacheable task's root holds its declared input files
and its project's `package.json`.

Verified end-to-end against a live NativeLink scheduler + worker: input tree
uploaded, QUEUED → EXECUTING → COMPLETED streamed, stdout returned inline,
declared outputs materialised byte-correct, and the worker attributed. Every
hand-rolled encoder AND decoder is pinned byte-for-byte against protobufjs
over the same vendored protos — the decoder tests exist because a wrong field
number parses garbage without ever erroring (`tests/encoding.test.ts`).

One environmental note for NativeLink specifically: its official image is
distroless, so a worker inside it has no `/bin/sh` and cannot run any vx task.
`tests/helpers/nativelink.md` has the three-command busybox rehost.

## node_modules: install as an action

REAPI workers are stateless, and vx deliberately treats `node_modules` as
ambient environment rather than a cache input — so a remote task cannot see
the packages a build needs. The answer is the design doc's §7.4 recipe,
`exec.remote: 'only'`:

```ts
install: {
  exec: { command: 'pnpm install --frozen-lockfile', remote: 'only' },
  cache: {
    inputs: { files: ['package.json', 'pnpm-lock.yaml'] },
    outputs: { files: ['node_modules/**'] },
  },
},
build: {
  dependsOn: ['install'],
  exec: { command: 'tsc -p .' },
  cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
},
```

What actually happens, all verified live against a NativeLink scheduler +
worker (`tests/vx-run-e2e.test.ts`):

- `install` executes **on a worker** — so platform binaries build for the
  worker's platform, not the laptop's — and runs once per lockfile change,
  ever: repeats are satisfied from an execution record the plugin keeps under
  the task's vx cache key.
- Its outputs **never land on the submitter's disk**: not materialised, not
  restored, and the local `node_modules` a dev installed is never cleaned.
- A dependent task's input tree grafts the install outputs **by reference**
  (per-file digests from the execution record; whole directories as
  re-canonicalised REAPI `Tree`s), so the bytes flow worker→CAS→worker and
  never transit the submitter. The graft applies ONLY to outputs that exist
  nowhere locally: when an upstream's outputs are materialised on this
  machine, **local disk is truth** — two machines racing a nondeterministic
  miss can leave the artifact store and the execution record holding
  results of different executions under one pure-input key, and a worker
  fed the record would see bytes this machine's own tasks do not.
- With **no remote executor declared**, `install` is a local no-op and
  dependents use whatever the machine has ambient — a laptop run behaves
  exactly as it did before the field existed.

The execution record lives under `sha256("vx-reapi-exec-v1\0" + key)` — a
second AC namespace beside the artifact mapping, listing outputs file-by-file
with workspace-relative paths.

## What the worker's environment contains

An action's `Command` carries exactly two of vx's three environment lists,
sorted by name — the proto requires that, so equivalent Commands hash alike:

- **`exec.env.define`** — literal `name: value` pairs from the task config.
  They read the same on every machine, so they are safe to put into the
  action identity, and they are already in the vx cache key.
- **`cache.inputs.env`** — the values this machine resolved for those names,
  for each name the task's local child would get too (it is also in
  `exec.env.passThrough`). They are in the vx cache key by definition, so a
  change to one already produces a different action. A name unset here, or
  one the config only tracks, is left out of the `Command`, so the worker
  sees what a local run would: shipping a tracked-only value ran the worker
  on something a local run never saw, under the same key (item 1092).

A `define` wins over an `inputs.env` entry of the same name: it is the more
explicit statement of intent.

Nothing else crosses. In particular **`exec.env.passThrough` does not reach a
remote worker**, and neither does the essential allowlist (`PATH`, `HOME`,
`TMPDIR`, …) — those are the submitting machine's resolved environment, and
the worker has its own. Two reasons, and both matter:

- Host values in the `Command` would enter the action digest, so a laptop and
  a CI runner would never share a remote entry — the same reason the vx key
  excludes them.
- A `Command` blob lives in the CAS. `passThrough` is where secrets go, and a
  token written to a shared content-addressed store is readable by anyone who
  can name its digest.

So a task that needs a value on a worker must `define` it (config literal) or
list it in both `cache.inputs.env` and `exec.env.passThrough` (host value,
keyed, and seen by a local run the same way). A task whose command reads
a `passThrough` secret is one to keep local with `exec: { remote: false }`.

---

# @vzn/vx-schedule-history

> History-based scheduling for @vzn/vx: a schedule plugin that orders ready tasks by their expected REMAINING critical-path duration — a task's own p50 plus…

History-based scheduling for [`@vzn/vx`](https://github.com/vznjs/vx): a `schedule` plugin that orders ready tasks by their expected REMAINING critical-path duration — a task's own p50 plus the longest chain of dependents behind it — learned from the workspace's local run history. Zero dependencies.

## Usage

```sh
npm install -D @vzn/vx @vzn/vx-schedule-history   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
```

```ts
// vx.workspace.ts
import { scheduleHistoryPlugin } from '@vzn/vx-schedule-history'

export default { plugins: [scheduleHistoryPlugin()] }
```

`scheduleHistoryPlugin({ window?, assume?, resources?, memory?, reservations? })` learns from the last `window` invocations (default 20) through core's `LocalHistoryProvider` over the cache's own SQLite handle. With one worker and two chains of identical shape, the chain history says is slow starts first; with no history yet, the scheduler's structural order stands.

`assume` is for the run that has no history: a fresh CI runner. It names durations (task id → ms) for tasks the history has not seen, so a long leaf task — a docs build, a cross-compile — starts first instead of last:

```ts
export default {
  plugins: [scheduleHistoryPlugin({ assume: { '@vzn/vx-docs#build': 30_000 } })],
}
```

A recorded p50 always wins over an assumption, and assumptions never feed the workspace median: they are a hint for the cold run, not evidence. A duration that is not a finite non-negative number (`Number()` of an unset variable is NaN) is dropped with one warning naming its task ids; the rest still order the run. vx's own CI declares four, this one among them — its docs build was the 29 s tail of a 99 s cold gate, ready from the second second and started last (2026-09-10).

## Reservations learned from history

The same history answers what each task used: the runner records every
execution's CPU time and peak RSS. Core's only gate is the worker count;
this plugin's `admit` hook packs the finer numbers, and core never
learns them. Each task's reservation is the largest peak RSS in the
window times a headroom (1.25), rounded up to 64 MB; cores are never
learned (the parallelism a build shows is what the machine let it have,
and reserving the solo reading packed 92 real builds two wide on four
cores for a 21% longer run, 2026-09-15), only declared. A task is
admitted while its reservation and those of everything running beside
it fit the budgets —
cores are the run's worker count, memory is what this process may use
(the machine's total, capped by the cgroup limit a container runs
under) — and a task over a whole budget runs alone. A task with no execution in the
window reserves nothing and runs freely, as it would with no plugin; a
spike or a refactor ages out with the window. A cache hit counts too:
the producing execution's usage rides the artifact, so a fresh CI runner
that restored a task from a remote cache has its reservation on the
next run without ever having executed it.

```ts
plugins: [
  scheduleHistoryPlugin({
    // MB. The default is the machine's total capped by the cgroup limit; set it to budget below either.
    memory: 8192,
    resources: { headroom: 1.5 },
    // Declared by hand for what history cannot size (a first run); a declaration wins.
    reservations: { 'app#e2e': { cpus: 2, memory: 4096 } },
  }),
]
```

`window`, `memory` and `headroom` must each be a finite number above 0 (`window` a whole one). One that is not — `Number(process.env.X)` with `X` unset is NaN, and no reservation fits a NaN budget, so every task that reserved memory would wait for an idle machine — runs on its default, named in one warning per run and in `vx history`. So does a declared `reservations` axis (`cpus`, `memory`): one that is not a number above 0 reserves nothing on that axis (a NaN held its task alone and every reserving task beside it waited); `0` is taken as nothing, silently. An entry that is not an object (`{ "app#build": 2048 }`) reserves nothing and is named the same way.

`vx history [--format pretty|json]` (a verb this plugin adds; `--help`
prints its usage) shows what it learned per task and the reservation it
will pack, with the budgets it packs into:

```
$ vx history
history: last 20 runs · budgets 4 cores (the default worker count; --concurrency changes it per run) · 13567 MB (what this process may use)
  task       runs      p50  peak rss    cpu  reserves
  app#build    12    8.41s    612 MB   1.9×  768 MB
  app#e2e       3   41.20s    1.4 GB   1.1×  4096 MB · 2 cores (declared)
  lib#test     12    1.02s         —   1.0×  —
  3 tasks with no execution in the window reserve nothing
```

`--format json` emits `{ window, budgets, tasks }` with every task's
`runs`, `p50DurationMs`, `maxPeakRssBytes`, `maxCpuParallelism`,
`reservation` and `declared`; `schemas/history.json` (shipped) is its
JSON Schema, held to the output by core's
`tests/plugin-json-schemas.unsafe.test.ts`. A cache hit's row carries the producing
execution's usage, so a task restored from a remote cache shows a
reservation on a machine that never executed it. A task lighter than
vx itself has no peak on record (the runner reports one only above its
own footprint, since Linux hands a lighter child the parent's figure)
and reserves nothing — what a task under vx's own footprint needs.

`resources: false` turns the learning off (declared `reservations` are
still packed). Admission control, not enforcement: nothing is
cgroup-limited or reniced, and a task that exceeds its reservation is
the job of `exec.timeout` and the OS. Design:
`docs/design/resource-estimates-2026-09.md` in `@vzn/vx`.

## What it does and does not do

- It is an ORDERING hint over the scheduler's structural baseline (how many tasks wait on each one, directly or through others), merged as `VxPlugin.schedule` returns it: task id → weight. It never changes what runs, only which ready task runs first.
- Cache hits are not modelled as zero-cost: predicting cache state needs the key and a probe, which the scheduler handles at run time (a confirmed hit is backfill, never a critical-path task). The estimate is "what if everything ran", which is exactly the case where order matters.
- It fails open: a broken history read warns (`[vx] schedule-history: ordering falls back to the baseline`) and leaves the baseline order and only the declared reservations. Observability never breaks a run.
- Cost: one history read per run, serving both hooks, paid only by workspaces that declare the plugin. Core applies no plugin by default.

`criticalPathPriorities(nodes, history, assume?)`, `resourceEstimates(nodes, history, headroom)`, `withDeclared(learned, declared)` and `admits(id, running, reservations, budgets)` are exported for tests and for policies that want the same scoring over another history source, with the types `ScheduleHistoryOptions`, `ResourceEstimate` and `Budgets`.

## History

Core's opt-in `predictive` mode until 2026-09-02, then core's one bundled plugin (`@vzn/vx/plugins/schedule-history`) until 2026-09-10, when it moved here so core ships no plugin at all.

---

# Quickstart

> Install vx, describe one task, and run it from the cache the second time, in a new repo or one you already have.

Run your first cached task in five minutes.

You need a git repository on Linux with glibc (not Alpine's musl) or macOS
(Windows: run vx inside WSL2). vx is
one prebuilt binary. The release binary alone needs neither Node nor Bun;
installed from npm, the `vx` command is a small Node script that runs
that binary.

## Install

1. Install it at the workspace root: `npm install -D @vzn/vx` (in a pnpm
   workspace, `pnpm add -D -w @vzn/vx`: npm refuses `workspace:*`; Bun:
   `bun add -d @vzn/vx`).
2. Run `npx vx init`. It writes a `vx.config.ts` per package from its
   scripts, and a `vx.workspace.ts`. A root script that checks the whole
   repo (`format: prettier --check .`) becomes a task in a root
   `vx.config.ts`; one that runs the members (`pnpm -r build`) does not,
   nor one named like a package's own task (a root `lint` beside a
   package's `lint`), so `--all` never runs a check twice. No task gets a `cache` block, so
   nothing is cached yet: add the one each `build`'s TODO shows. A
   repo with `turbo.json` or `nx.json` starts at
   [Coming from Turbo, Nx or Vite Task](#coming-from-turbo-nx-or-vite-task) instead.
3. Or write one by hand, beside a package's `package.json`.

## Config

```ts
// packages/app/vx.config.ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    build: {
      dependsOn: ['^build'], // my dependencies' build first
      exec: { command: 'tsc -b' },
      cache: {
        inputs: { files: ['src/**', 'tsconfig.json'] },
        outputs: { files: ['dist/**'] },
      },
    },
    test: {
      dependsOn: ['build'], // my own build first
      exec: { command: 'bun test' },
      cache: { inputs: { files: ['src/**', 'tests/**'] }, outputs: { files: [] } },
    },
  },
})
```

## Run

Installed from npm, the command is `npx vx` (pnpm: `pnpm vx`, Bun:
`bunx vx`); the lines below drop the prefix.

```bash
vx run build --all        # every package, in dependency order
vx run test --affected    # changed since main or the last commit, and dependents
vx run build --all --dry  # the plan; runs nothing
cd packages/app           # without --all, a run takes the package you are in
vx run build              # ⇢ success local — after dist/ is deleted; else up-to-date
vx run build --graph      # the task graph as Graphviz DOT
```

The first run stores the result. The second finds nothing changed and
`dist/` still as stored, so it restores nothing: the task's frame closes
`up-to-date` (`► success fresh` in the `--output-logs full` row). Delete
`dist/` and the next run restores it from the cache: `restored-local`, the
`⇢ success local` row.

## An existing repo

Start with one package and leave the rest of your tooling as it is.

1. Give one package a `vx.config.ts` with the command its `build` script runs.
2. Run `vx run build` twice in it. The second run is a cache hit.
3. Edit a file the build reads. `vx run build --dry` now predicts a miss.
4. Add configs to more packages. `^build` orders them by your `package.json` dependencies.

## Coming from Turbo, Nx or Vite Task

`npx vx init` beside `turbo.json` or `nx.json` runs `@vzn/vx-migrate`, which
writes the native `vx.config.ts` files from `turbo.json` or the Nx graph
(`bunx @vzn/vx-migrate` does the same from each `vite.config`'s `run.tasks`);
from there everything above applies. `vx init --keep` writes only a
`vx.workspace.ts` declaring `turbo()` or `nx()`: a temporary start, dropped
once the configs exist.
[Migrate](../guides/migrate/) has the steps.

## Common problems

- **`--affected has no base here`.** A repo with one commit has nothing to compare with. Commit again, or name a base: `--affected=<ref>`.
- **Only one package ran.** `vx run build` runs the package you are in. Add `--all`.
- **The editor cannot resolve `@vzn/vx`.** Add it as a devDependency. vx itself runs a config without it.
- **`vx requires git`.** Run `git init` at the workspace root.
- **A package has no `vx.config.ts`.** It gets a default `build`: a group behind `^build`, keyed on all its files, so editing it re-runs the packages that depend on it.
- **`tsc -b` ran, but `dist/` came back empty.** With `rootDir: "src"`, tsc writes `tsconfig.tsbuildinfo` beside `tsconfig.json`, outside `dist/`. vx empties `dist/` before a miss, tsc sees the buildinfo, thinks it is current and writes nothing. Add `tsconfig.tsbuildinfo` to `outputs.files`, or point `tsBuildInfoFile` into `dist/`.
- **A package has nothing to build, but others depend on it.** Its default `build` waits on its own dependencies' builds. `build: { dependsOn: [] }` waits on nothing, but also drops its files from its dependents' keys: use it only when no dependent reads its source.

## Known limits

- Running from source needs Bun ≥ 1.4. The binary needs nothing.
- The Linux sandbox needs `bubblewrap`, `socat` and `ripgrep`, and no root
  in a container, or set `exec.sandbox.weakerWhenNested: true` on each
  sandboxed task ([Sandboxing](../guides/sandboxing/#requirements--platform-support)).
- Windows: run vx inside WSL2.
- On macOS the sandbox's report can miss records under load. Enforcement
  holds.
- A cache hit replays the first and last 8 MiB of a task's output.
- A `kill -9` of vx leaves its persistent tasks running, except a server
  that exits when its stdin closes (esbuild `--watch`).
- A process a task detaches into its own session (`setsid … &`) outlives
  Ctrl-C: vx signals the task's process group.

---

# Config schema

> Complete reference for every field accepted by vx.config.{ts,mts,js,mjs,cts,cjs}

Complete reference for every field accepted by `vx.config.{ts,mts,js,mjs,cts,cjs}`
and the optional workspace-level `vx.workspace.{ts,mts,js,mjs,cts,cjs}`. The
authoritative TypeScript definitions live in `src/config.ts` and are
re-exported from `@vzn/vx`.

## File layout

```
<workspaceRoot>/
├── pnpm-workspace.yaml          (or: package.json with "workspaces", or bare package.json)
├── vx.workspace.ts              (optional, workspace-wide settings)
└── packages/
    └── <pkg>/
        ├── package.json
        └── vx.config.ts         (per-package task definitions)
```

A project is discovered as a vx project by the **presence of a
`vx.config.*` file alongside the project's `package.json`.** Projects
without a config are visible in the workspace graph but contribute no
tasks.

## Project config

```ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tags: ['scope:web', 'type:app'],
  tasks: {
    <taskName>: TaskConfig,
    ...
  },
})
```

```ts
interface ProjectConfig {
  tags?: readonly string[] // labels for `--filter tag:<name>`
  tasks?: Record<string, TaskConfig> // keyed by task name
}
```

`defineProject` is an identity function — it exists purely so
TypeScript narrows literal types in your config (clean autocomplete,
strict validation against the schema). It has zero runtime effect.
The same typing without a runtime import is
`import type { ProjectConfig } from '@vzn/vx/config'` plus
`export default { … } satisfies ProjectConfig` — the form `vx init`
and `@vzn/vx-migrate` generate, because Bun erases the type import and the
file then loads in a workspace that runs the `vx` binary without the
package installed. Either form is fine; the object is what vx reads.
`@vzn/vx/config` is the schema alone (`src/config.ts`, which imports
nothing): your own `tsc` checks that one file, where `@vzn/vx` would
walk core's Bun-only sources and fail without `@types/bun`.

The object is JSON data. The cache key folds `JSON.stringify` of each
task's config, `vx lock` stores the same JSON, and `vx watch` re-reads a
config through a worker that hands it back as JSON, so a value JSON
cannot carry would be dropped, rewritten or refused depending on the
path. vx refuses it on every path, before the schema: a function, a
symbol, a bigint, `NaN` or `±Infinity`, `undefined` inside an array
(JSON writes `null`), a cycle, a getter or setter (code that each read
may answer differently; vx never calls it), and any object that is not a
plain object or an array (a `Date`, `Map`, `Set`, `RegExp` or class
instance). An
`undefined` property is fine: JSON drops it and the schema reads it as
absent, which is what a conditional spread
(`...(ci ? { retries: 2 } : {})`) relies on. The workspace config is not
held to this: its plugins are objects of functions.

`tasks` is a `Record<string, TaskConfig>`. Task names are strings
referenced by `dependsOn`, by `cache.inputs.tasks`, and by the CLI
(`vx run <taskName>` or `vx run <pkg>#<taskName>`), so a name those
could not spell is refused at load: an empty one, one with surrounding
whitespace, one holding `#` (the project separator) or `*` (a pattern),
and one starting with `^` (dependencies' tasks) or `!` (a negation).

`tags` label the project for selection: `--filter tag:<name>` selects
the projects carrying one (`cli.md` § Filter DSL), as Nx's `tag:` does.
Each is a non-empty string a tag filter can name, or it is refused at
load: no surrounding whitespace, no `*` (a pattern), and no ending in
`...` (a dependency walk) or `[<ref>]` (a git range). A
`project` plugin may set or edit them (`nx()` gives each project its Nx
`tags` unless the vx.config has its own). A tag is in no cache key: it
changes no task's behaviour, so editing one re-runs nothing.

## `TaskConfig`

```ts
interface TaskConfig {
  description?: string // one-line blurb for the picker / --dry view
  exec?: ExecConfig // omit to declare a group task
  dependsOn?: readonly string[] // Turbo/Nx micro-syntax
  cache?: CacheConfig // caching is opt-in; on a group, a key with no outputs
}
```

A task either has an `exec` (it does work) or omits `exec` and declares
`dependsOn` or `cache` (it's a **group task**: an aggregator, or a key).
The loader rejects a task that has none of them — a no-op standalone
task is almost always a config mistake. `dependsOn: []` is the deliberate form: an
explicit empty group, for a package that wants a task by that name to
exist and do nothing.

A project whose config and plugins declare no `build` gets one (owner,
2026-10-04): a group with `dependsOn: ['^build']` keyed on every file of
the project (`cache.inputs.files: ['**']`, no outputs). It runs nothing,
but a dependant behind `^build` folds its key, so a package consumed as
source moves its dependants' keys and reaches them under `--affected`.
A config can declare a keyed group too (Group tasks, below). A
bare `vx run build` does not select it: run where no selected project
declares `build`, it is refused as any undeclared name is, while
`lib#build` names it and a dependant's `^build` reaches it. `vx show`
and `vx info` count it; `vx show build` and the `vx build` hint, which
name declared tasks, do not.

### `description` (optional)

```ts
description?: string
```

A short one-line blurb describing what the task does. No effect on
scheduling or execution, but it **does** participate in the cache key —
the key hashes the whole resolved task config (see `caching.md`, step 5),
and carving exceptions out of that object is what invites stale hits.
Editing a description therefore costs one re-run. Surfaced in three
places:

- The interactive task picker (`vx run` with no positional in a TTY) —
  printed to the right of each `pkg#task` id.
- The `--dry` text preview — printed on a second indented line under
  the cache-status row.
- The `--dry=json` output — `description` lives on each task entry.

```ts
test: {
  description: 'bun test against the tests/ tree',
  exec: { command: 'bun test' },
  cache: {
    inputs: { files: ['src/**', 'tests/**'] },
    outputs: { files: [] },
  },
}
```

### `exec` (optional — required for non-group tasks)

```ts
interface ExecConfig {
  command: string // shell command, run from the project's dir
  remote?: boolean | 'only' // placement: pin here, or remote-only (see below)
  env?: ExecEnv // optional per-task env layering
  timeout?: number // ms before vx SIGTERMs the child (see below)
  retries?: number // max additional attempts after a failure (see below)
  persistent?: PersistentConfig // long-running task (dev server, watcher)
  interactive?: boolean // reads the terminal: a prompt, a REPL (see below)
  sandbox?: SandboxConfig // opt-in OS sandbox for this command
}
```

`command` is a string. Run via `sh -c` (`dash` on macOS, as Linux's
`sh` is), so POSIX
shell semantics work directly — pipes, redirects, `&&` chaining:

```ts
exec: {
  command: 'tsc -b'
}
exec: {
  command: 'gen && tsc && cp -r assets dist/'
}
exec: {
  command: 'find src -name "*.snap" | xargs rm -f'
}
```

CLI args after `--` are appended to `command`, each POSIX single-quoted
unless it holds only safe characters:

```sh
vx run test -- --bail 'a b'
# child sees:   bun test --bail 'a b'
```

Forwarded args are folded into the cache key — different args produce
distinct cache entries.

#### `timeout` (optional)

Maximum time in milliseconds before vx SIGTERMs the child. Omitted →
no limit.

```ts
build: { exec: { command: 'tsc -b', timeout: 120_000 } }
```

- For a **normal task**, `timeout` bounds the total run time, counted
  from the spawn (a sandbox's setup, its wrap included, is vx's, not the
  task's). A task
  that overruns is killed — its whole process group, so what it forked
  goes with it — and reported `failed` (timed out) — never cached. (A timeout SIGTERM is a real failure, distinct from a Ctrl-C
  teardown, which is reported `aborted`.)
- For a **persistent task**, `timeout` bounds the **readiness wait**
  instead: if `readyWhen` hasn't matched within the window the child is
  SIGTERMed and the task fails — see `persistent` below. A persistent
  task that's ready on spawn (no `readyWhen`) becomes ready before the
  timer can fire, so the timeout is a no-op for it.
- On a **plugin executor**, the timeout aborts the request's `signal`
  instead (core cannot kill a process the executor spawned); any exit
  after it is reported timed out, a 0 from a child that trapped the stop
  included (X-125), and an executor still running after the kill grace
  is abandoned (H-12, H-14).

**Upper bound.** `timeout` must be at most **2147483647 ms (~24.8 days)**,
the largest delay a timer can hold. A larger value does _not_ mean "no
limit" — the platform silently reduces it to **1 ms**, so the task would
be killed the moment it spawns and reported `failed`. vx refuses it at
load rather than let that happen. **Omit `timeout` entirely for no
limit.** The same bound applies to `--timeout` and to the workspace-level
`timeout`; the `VX_TASK_TIMEOUT` env rung is clamped to it instead of
refused, since that rung never fails a run.

A task with **no** `exec.timeout` falls back to a run-level default, if
one is set. Precedence, highest first: **per-task `exec.timeout` →
`--timeout <ms>` / `RunOptions.timeout` → `VX_TASK_TIMEOUT` env →
workspace `timeout`** (see workspace config below). Per-task always
wins. The run-level defaults are threaded as run options, so — like
`--retry` — they never touch a cache key: a `--timeout` run cache-hits a
plain run's entry.

**Why no multi-step `commands: string[]`?** Per-task caching is the
right granularity for invalidation. If you'd benefit from caching each
step independently (e.g. `codegen` then `build`), split into two
tasks linked by `dependsOn`. If you don't need that, `&&` in shell is
the right tool.

#### `retries` (optional)

Maximum ADDITIONAL attempts after a failed attempt. `retries: 2` means
up to 3 executions total. `0` / omitted → no retries (fail on the first
non-zero exit).

```ts
test: { exec: { command: 'bun test', retries: 1 } }
```

- A retry fires after ANY failure, `timeout` kills included. A Ctrl-C
  teardown (`aborted`) is never retried — the run is tearing down.
  Nor is a task in flight when `--continue=never` stops the run: its
  attempt finishes, and its failure is the last, even when its retry
  was already announced and preparing.
- Declared outputs are re-cleaned before each retry, exactly like the
  first attempt — a failed attempt's partial outputs can't leak into
  the next.
- Every attempt streams its output live. Between attempts vx emits one
  stderr line into the task's stream, ending in the reason:
  `vx: retrying <id> (attempt <k>/<total>) after exit <code>`, or
  `after a timeout` when the attempt was killed by `timeout`.
- The final outcome is the LAST attempt's: the first success wins (and
  is what gets cached — its output only, not a concatenation of failed
  attempts); if every attempt fails, the task is `failed` with the last
  exit code and nothing is cached, as today.
- The task's reported duration sums every attempt; a saved entry keeps
  the producing attempt's time.
- `retries` is part of the resolved config, so declaring it derives a
  distinct cache key (like every config field); tasks without it keep
  byte-identical keys.
- Not allowed with `persistent` — a persistent task has no exit to
  retry (config error, like `cache` + `persistent`).

The run-level default is `vx run --retry <n>` — it applies to tasks
that don't declare their own `retries`, never to a persistent one (a
server that exits before it is ready fails at once); explicit config
always wins, including an explicit `retries: 0`. The CLI flag never
affects cache keys.

#### `remote` (optional)

```ts
remote?: boolean | 'only' // default true
```

**Placement.** `false` pins the task to the machine that started the run:
it is never offered to an executor that declared itself `remote`. Use it
for a task that talks to something only this machine has — a local
daemon, a Docker socket, a device, a VPN-only host.

```ts
'docker:build': {
  exec: { command: 'docker build -t app .', remote: false },
}
```

- **Only meaningful with a remote executor declared.** A workspace with
  no executor plugin already runs everything here, so the field changes
  nothing.
- **Pinned by inference too.** A `persistent` task, and anything that
  depends on one (transitively), is pinned regardless of what it
  declares — a worker cannot reach a port served on the submitter. So is
  a task with a `sandbox` block, and its dependants: the sandbox is this
  machine's machinery, and a boundary a worker does not enforce would
  pass vacuously. So is a task whose key folds `cache.inputs.runtime` or
  `workspaceRuntime`: the key holds this machine's answer, which a worker
  cannot prove it shares. Its dependants are not pinned.
- **Placement is decided once per task**, before scheduling, so the
  scheduler knows which pool a task will occupy (see
  [execution.md](../execution/#executor-pools)).
- **`'only'` is the inverse pin — the install-as-action recipe.** The task
  exists to produce a REMOTE input tree (canonically `pnpm install` feeding
  remote workers) and is a NO-OP on this machine: never executed locally,
  its declared outputs never cleaned or restored on this disk. With a remote
  executor declared it runs on a worker, its outputs stay in the remote
  store, and dependents' input trees reference them there — the bytes flow
  worker→store→worker without ever transiting the submitter. With no remote
  executor it succeeds without running and dependents use the machine's
  ambient state (the dev's own `node_modules`), exactly as before the field
  existed. An `'only'` task must declare `cache` — its inputs are what a
  worker reproduces and its key is the address of its remote record. One
  without is refused at load.

  ```ts
  install: {
    exec: { command: 'pnpm install --frozen-lockfile', remote: 'only' },
    cache: {
      inputs: { files: ['package.json', 'pnpm-lock.yaml'] },
      outputs: { files: ['node_modules/**'] },
    },
  },
  build: { dependsOn: ['install'], /* … */ },
  ```

- **Never busts a cache:** `remote` is stripped from the cache key —
  `'only'` included, and it is the only `exec` field that is. The contract of a remote executor
  is that the same command over the same inputs produces the same outputs,
  so a key that moved with placement would split a laptop from a worker pool
  over nothing.

#### `persistent` (optional)

```ts
interface PersistentConfig {
  readyWhen?: string // regex (as string); first matching line marks ready
}
```

Marks the task as a long-running process — a dev server, a file
watcher, a daemon. The runner spawns the command but does NOT wait
for it to exit. Instead it considers the task "ready":

- Immediately on successful spawn when no `readyWhen` is given.
- On the first stdout/stderr line that matches the `readyWhen`
  regex string. Each line is tested on its own, without its line
  break (`\n`, `\r\n` or a bare `\r`) and without terminal escapes
  (colour, OSC titles), so `^` and `$` anchor to a line as you read
  it and `Local:` matches Vite's bold `Local` under `FORCE_COLOR`.
  The trailing partial line is tested too, so prompt-style banners
  without a newline (`printf 'Listening on :3000'`) count, and so does
  output read up to 250 ms after the shell exits. A server
  not ready after 10 s (`VX_READY_NOTICE_MS`) is said once, naming
  the pattern it waits for, and whether `exec.timeout` bounds the wait.

```ts
dev: {
  exec: {
    command: 'vite',
    timeout: 30_000, // bound the readiness wait
    persistent: { readyWhen: 'Local:' },
  },
}

watch: {
  exec: {
    command: 'tsc --watch --preserveWatchOutput',
    persistent: { readyWhen: 'Watching for file changes' },
  },
}

// No readyWhen — ready as soon as spawn succeeds. Useful for daemons
// that have no observable "ready" signal but downstream doesn't need
// to gate on one.
agent: {
  exec: {
    command: 'my-agent --daemon',
    persistent: {},
  },
}
```

Semantics:

- **Downstream unblocks on ready, not on exit.** Useful for e2e tests
  that need a dev server up first:
  ```ts
  'dev:run':  { exec: { command: 'vite', persistent: { readyWhen: 'Local:' } } },
  'e2e':      { dependsOn: ['dev:run'], exec: { command: 'playwright test' } },
  ```
- **Not started when nothing needs it.** A persistent task you did not
  request, whose every dependant is a confirmed local cache hit, is
  never spawned: a fully cached `vx run e2e` does not boot the server
  `e2e` depends on, and the server is in no outcome or count. It starts
  if one of those hits turns out to need running (its artifact went),
  and that task runs once it is ready. A dependant whose key the
  server's writes could change (one in its own project, unless a sandbox
  bounds the server's writes) is not probed ahead of it, so there the
  server still starts. `vx run --dry` says so: such a server is
  `not started` (`not-started` in `--dry=json`), not `would exec`.
- **Exit before ready ⇒ failed.** If the persistent task crashes or
  exits before `readyWhen` matches, the task is reported as `failed`.
- **Crash after ready ⇒ failed run.** A persistent task that exits
  non-zero (or is killed) on its own after it became ready fails the
  run, and vx names it: `vx: <id> exited with code <n>` (a signal death
  as its `128 + n` code), at once while the graph still runs (`… while
the run went on`), so a dependant failing against it reads why. Its own outcome is `failed` with that exit
  code, and the footer counts it so (item 1071). An exit 0 on its own is
  fine (a daemon that forks and returns), and one kept only as a
  dependency does not end the foreground hold (WD-3).
- **End-of-graph SIGTERM.** Once the rest of the graph finishes
  (success OR failure of downstream), the orchestrator sends `SIGTERM`
  to every persistent subprocess it does not keep, and waits for them to
  exit (`SIGKILL` past the kill grace). In the foreground it KEEPS the
  persistent tasks you requested, those a requested group stands for,
  and the persistent tasks they depend on: vx stays up after the summary
  until one of them exits or you press Ctrl-C, streaming what they write.
  A run where anything else failed keeps none and exits 1, unless
  `--continue=always` (`cli.md` § Output, "Pinned persistent tasks").
- **`cache` is rejected.** The config loader throws on
  `cache + persistent` — persistent tasks don't terminate, so there's
  no exit code to cache and no outputs to capture at a well-defined
  moment.

#### `interactive` (optional)

`true` hands the task the terminal: a prompt (`drizzle-kit push`), a
REPL, a watch mode that reads keys. Turbo's `interactive`.

- **On a TTY** (vx's stdin is one) the task gets vx's own stdin,
  stdout and stderr. Its output is not framed, masked, kept or
  replayed: it goes to the terminal as the task writes it. A frame
  line opens before it and closes after (`--output-logs full`, and
  the default views), and the live status region goes for the rest
  of the run, as it would repaint over a prompt.
- **Alone.** It starts once nothing else runs, and nothing starts
  until it exits. A persistent one holds the terminal from its spawn
  to the run's end, so other tasks may run once it is spawned (their
  output goes to the same terminal), a run may hold one, and every
  other interactive task must be its dependency. A run that breaks
  either is refused before any task runs.
- **Off a TTY** (CI, a pipe) it runs as any task: stdin is empty, or
  a pipe vx holds for a persistent one, and it runs beside others.
  A prompt there reads end of input; it never hangs.
- **Here, never cached.** No executor plugin is offered it, and
  `cache` is refused. `sandbox` is refused (a sandboxed task's
  output passes through vx), and so is `persistent.readyWhen` (vx
  reads none of its output; it is ready once spawned).
- It runs in its own session, as every task does, so a tool that
  opens `/dev/tty` itself rather than its stdin still cannot, and
  the terminal's resize signal does not reach it. Ctrl-C reaches vx,
  which stops the run; a task that puts the terminal in raw mode
  reads the key itself.
- **Its terminal modes end with it.** vx reads them (`stty -g`)
  before the task starts and puts them back when it exits, so a task
  killed in raw mode, or one that never undid its `stty raw -echo`,
  leaves no terminal without echo or Ctrl-C behind it
  (`tests/terminal.unsafe.test.ts` › "a task that leaves the terminal
  raw"). Without `stty` on PATH the modes stay the task's.

```ts
'db:push': {
  exec: { command: 'drizzle-kit push', interactive: true },
}
```

#### `ExecEnv` (optional)

```ts
interface ExecEnv {
  passThrough?: readonly string[] // names taken from host process.env; exact names, a wildcard is refused
  define?: Record<string, string> // explicit name=value pairs
  secret?: readonly string[] // names whose values are masked (`***`) whatever the name; see Masking
}
```

The child process sees a deliberately limited env. From lowest to
highest priority:

1. **Essential allowlist** (hard-coded in `src/exec/env.ts`, and pinned
   against this list by a test): `PATH`, `HOME`, `SHELL`, `USER`,
   `LOGNAME`, `TMPDIR`, `TEMP`, `TMP`, `LANG`, `LC_ALL`, `LC_CTYPE`,
   `TERM`, `COLORTERM`, `FORCE_COLOR`, `NO_COLOR`, `CI`, `NODE_OPTIONS`,
   `COREPACK_HOME`, `PNPM_HOME`.
   Nothing else from the parent environment reaches a task —
   that is the whole list. When neither `FORCE_COLOR` nor a non-empty
   `NO_COLOR` reaches the task by any layer, vx sets `FORCE_COLOR=1`
   (its own output strips the colour where it prints plain; `docs/cli.md`
   § Colors). Without these, typical CLI tools break. vx
   adds two markers of its own on top, `VX_RUN_WORKSPACE` (the root of
   the workspace running the task) and `VX_RUN_TASK` (`project#task`):
   a task whose command shells out to `vx run` in that same workspace
   is refused — a loop back to itself forks a run per run without
   bound, and a nested run that terminates is still invisible to the
   outer graph (its tasks escape the schedule, the concurrency budget
   and the cache key); declare it with `dependsOn`. Driving a
   _different_ workspace from a task (a fixture suite, a benchmark) is
   fine. **_NOT_ folded into the cache key** — the
   same rule `passThrough` states below, and for the same reason.

   Read that carefully if your build's _output_ depends on one of
   them, because three can change what a task produces:
   **`NODE_OPTIONS`** (`--require` / `--import` / `--loader` /
   `--conditions` inject code or switch package-export resolution),
   **`LC_ALL` / `LANG`** (collation — anything shelling out to `sort`
   orders differently), and **`CI` / `FORCE_COLOR` / `TERM`** (output
   bytes, and vx caches and replays output).

   They are not hashed because hashing them would mean a laptop and a
   CI runner could **never share a remote cache entry** — `PATH`,
   `HOME` and `TERM` differ on every machine, which is the whole point
   of a remote cache. vx does not guess which ones matter to your
   build; if one does, say so explicitly:

   ```ts
   cache: { inputs: { files: ['src/**'], env: ['NODE_OPTIONS'] }, outputs: { files: [] } }
   ```

   That folds its value into the key. The two axes are orthogonal on
   purpose: `cache.inputs.env` decides what the key _sees_,
   `exec.env.passThrough` decides what the child _gets_.

2. **`passThrough`** names → value taken from host `process.env` at
   spawn time. A project config cannot set one for it: a first load
   that writes `process.env` is refused (D-76). _NOT_ folded into the cache key — for secrets,
   regional values, CI flags that legitimately vary between machines.
3. **`define`** → explicit literal values. _ARE_ folded into the
   cache key via the task config hash (the values are in your config
   file, so they participate naturally).

```ts
exec: {
  command: 'bun test',
  env: {
    passThrough: ['CI', 'GH_TOKEN'],  // values forwarded; cache-invariant
    define: { NODE_ENV: 'test' },      // literal; in the cache key
  },
}
```

Every name in these lists (and in `cache.inputs.env`) must be one an
environment can hold: non-empty, with no `=` and no NUL, and a `define`
value holds no NUL. Such a name is refused at load; it used to reach the
child split at its `=` or not at all. A `passThrough` or `define` name is
also a shell variable name, `[A-Za-z_][A-Za-z0-9_]*`: the task runs under
`sh -c`, and dash (Linux's `sh`) drops any other name from the environment
it hands the command, so `my.var` reached a task on macOS and never on
Linux. `cache.inputs.env` takes any such name: the key reads it from vx's
own environment.

vx also sets `npm_execpath` to the workspace's package manager (the root
`package.json`'s `packageManager`, else its lockfile, found on the root's
`node_modules/.bin` or `PATH`) unless a layer gives one, as `pnpm run`
does: npm-run-all calls that manager back and falls back to a global `npm`
without it. It names a binary on this machine, so it is not in the key.

Anything outside these three layers, the two variables vx sets for
the run (`VX_RUN_WORKSPACE`, `VX_RUN_TASK`) and `npm_execpath`, is invisible to the child:
a host credential (`SSH_AUTH_SOCK`, `GITHUB_TOKEN`) reaches a task only
when `passThrough` names it, held end to end by `env.test.ts` (a
sandboxed task with a restricted network also gets the sandbox's own
proxy, CA and temp-directory (`TMPDIR`, `TMP`, `TEMP`) values over these names:
`modules/sandbox-runtime.md` § The environment SRT sets). This
matches Turbo's `passThroughEnv` semantics and exists for two reasons:

- **Cache stability.** If every host env var entered the key, every
  shell with a different `PS1` would cache-miss.
- **Determinism.** If host env leaked into the child, two machines
  with different `FOO=bar` set would produce different outputs and
  the user would never know why.

**Masking.** The value of a variable whose name holds `TOKEN`, `SECRET`,
`KEY`, `PASSWORD`, `PASSWD` or `CREDENTIAL` (vx's own environment or a
task's `define`, six characters or more; not a name ending `_FILE`,
`_PATH` or `_DIR`, nor git's `GIT_CONFIG_KEY_<n>`) is printed as `***` wherever vx
shows it: the task's output and the line vx adds under a shell's 127 or
126 (the command's first word), the stdout the cache keeps and a hit
replays, the command a cache entry stores (what `vx why` prints and a
remote cache receives), the `$ command` line, telemetry records,
`vx show`, the hashes `vx why` gives for such a variable in
`cache.inputs.env` (its value, unsalted: the row names it and its change), an executor's error, a plugin's warning or failure (a remote's reply; the failure masked in the error `run()` rejects with), any error `vx mcp` answers an agent with, a failed `cache.inputs` runtime probe's error (its command and output), and the run's own invocation line that `vx last` prints (a
secret passed after `--`) and its `--tag`s. So are every string of a
task `vx show` prints (a runtime probe, `readyWhen`, the description),
the description `--dry` and the task picker print, a runtime probe's
command as the run history stores it and `vx why` names its row (two
probes that mask alike are numbered, `echo *** (2)`), the readiness
notice's pattern, a sandbox violation line, `vx info`'s config errors,
the error a verb ends on (a plugin's failure, a config's own throw) and
`vx watch`'s `cycle failed` line. A multi-line value (a PEM
key) is also masked line by line, each line of six characters or more,
and a value holding a `'` also as a shell-quoted line spells it (`'\''`).
A value
split across two output chunks is still caught; the output holds back
that many characters until the next chunk. A plugin that reads a task's
config directly sees it as written. A secret whose name holds none of
those words (`GH_PAT`, `NPM_AUTH`) is listed in `exec.env.secret`, and is
then masked in the same places.

Two `node_modules/.bin` directories are prepended to `PATH` so
installed tools (`oxlint`, `vite`, etc.) work without `npx`: the
project's own, then the WORKSPACE ROOT's, where a monorepo's shared
tooling lives. Never a sibling project's, so sibling bins stay invisible
(project isolation). A directory whose path holds `:` (PATH's delimiter)
cannot be named in PATH and is left out; a task's 127 then says so.

### `dependsOn` (optional)

Tasks that must complete successfully before this task runs.
Turbo/Nx-style micro-syntax — a flat array of strings:

```ts
dependsOn?: readonly string[]
```

| Form         | Meaning                                                            |
| ------------ | ------------------------------------------------------------------ |
| `'name'`     | Same-project task `name`.                                          |
| `'^name'`    | The `name` task in the nearest workspace deps that declare it.     |
| `'pkg#name'` | The `name` task in a specific other package (cross-project edge).  |
| `'name.*'`   | Every OTHER same-project task matching the pattern (`*` = any).    |
| `'^name.*'`  | All matching tasks of the nearest deps that declare any (pattern). |

Examples:

```ts
dependsOn: ['build'] // same-project build first
dependsOn: ['^build'] // build in every workspace dep first
dependsOn: ['codegen', '^build'] // both
dependsOn: ['lib#build', 'shared#test'] // cross-project edges
dependsOn: ['lint.*'] // every lint.<x> task in this project
dependsOn: ['^build.*'] // all build.<x> tasks of the nearest deps
```

Semantics:

- **Same-project (`'name'`)** — name must exist in this project's
  `tasks` map; missing is a hard error at graph-build time. When the
  config is authored through `defineProject`, a bare entry is also
  **type-checked against this config's task keys** — a typo is a
  compile error (`'^name'` / `'pkg#name'` reference other projects
  and stay free strings).
- **`'^name'`** — nearest-holder frontier. Walk the package dep graph
  from this project's direct deps (`dependencies`, `devDependencies`,
  `optionalDependencies`, and a `peerDependencies` entry on a
  workspace sibling unless that edge would close a cycle — then the
  consumer provides it and it orders nothing; an entry is a dep when
  the package manager links it to the workspace package, so a range the
  local version does not satisfy is a registry dependency, see
  `modules/package-graph.md` § Which entries are edges); each path stops at the first dep
  that declares the task and an edge is added to it (Turbo/Nx
  direct-deps parity). The holder's own `dependsOn` is responsible
  for anything deeper — chain `'^name'` in the holder to keep the
  cascade going (the universal pattern). Deps that don't declare the
  task are passed through, so a sparse dep doesn't break ordering to
  deeper packages that do (sparse tasks across a workspace are normal
  — not every package has a `lint`). Finding no holder at all is legal
  too, as long as SOME project in the workspace declares `name`: a
  preset spreads `'^build'` over packages whose deps have no `build`.
  A `'^name'` that **no project in the whole workspace declares** is a
  hard error at graph-build time, since it can only be a typo: "Task
  app#test depends on ^biuld but no project in the workspace declares
  biuld". Until 2026-09-24 it resolved to no edges and the run went
  green (Nx#32779 is the same bug). A scoped run (an anchored
  `app#test`, `--filter`, a project directory) loads only its projects
  and their dependency closure; when a `'^name'` there finds no holder
  and nothing loaded declares it, vx evaluates the remaining configs to
  decide, and if one of them fails to load the name is let through
  rather than failing the scoped run. A `'^name.*'` pattern matching
  nothing anywhere stays legal, as `'name.*'` does.
- **`'pkg#name'`** — missing pkg or task is a hard error (you named
  them explicitly). `'//#name'`, Turbo's spelling of the root package,
  names the root project (D-39) here and in `cache.inputs.tasks`; with no
  root project it is refused as such.
- **Patterns (`'name.*'` / `'^name.*'`)** — `*` matches any run of
  characters in a task NAME; everything else is literal (the dotted
  namespace convention needs no escaping). A same-project pattern
  expands to every other matching task (the declaring task never
  matches itself); **zero matches is legal** — a preset-spread pattern
  needn't match in every project. A `'^pattern'` walks the same
  nearest-holder frontier as `'^name'`, where a holder is a dep
  declaring at least one matching task; the holder receives edges to
  ALL its matches and stops the walk. Patterns are not supported in
  the `'pkg#task'` form. (Nx 19.5 `build-*` parity.)
- **No bare wildcards or negation here.** `'*'` / `'^*'` / `'!form'`
  belong in `cache.inputs.tasks` (filtering which upstream hashes
  participate in this task's cache key), not in `dependsOn` (declaring
  graph edges). The micro-syntax parser rejects them in this position.
- **Cycle detection** runs across the resolved graph at the end of
  `buildTaskGraph`. Cycles throw with a path-formatted message.

### `cache` (optional)

```ts
interface CacheConfig {
  inputs: CacheInputs // required when `cache` is provided
  outputs: CacheOutputs // required when `cache` is provided
}
```

**Caching is opt-in.** Omit `cache` and the task always runs (no read,
no write). Provide it and caching is active for that task. The
project loader requires _both_ `inputs` and `outputs` when `cache` is
set — declaring "what does this read?" and "what does it produce?" is
a deliberate, conscious choice.

**Why opt-in?** Defaulting caching to ON with implicit "all files / no
outputs" silently produces stale builds the moment a user forgets
to revisit the config. The cost of a single forgotten cache miss
(re-run a task) is much less than the cost of a stale cache hit
(ship broken artifacts).

#### `CacheInputs`

```ts
interface CacheInputs {
  files: readonly string[] // required
  workspaceFiles?: readonly string[] // optional; workspace-root-relative
  env?: readonly string[] // optional
  runtime?: readonly string[] // optional; project-dir shell commands
  workspaceRuntime?: readonly string[] // optional; workspace-root shell commands
  tasks?: readonly string[] // optional; same micro-syntax as dependsOn
}
```

##### `inputs.files` (required)

Project-relative globs. `!`-prefix negates. A **literal** entry (no
glob character) names a file or a whole directory tree — `src` and
`src/` both mean everything under `src`, as in Turbo and `.gitignore`;
`!src` subtracts the tree. A `!` entry subtracts wherever it sits in the
list, so a literal file it covers (`['src/**', '!src/gen/**',
'src/gen/keep.ts']`) would never be an input: that is refused at load.
Spellings a matcher would otherwise turn into
nothing are normalized: a leading `./` (`./src/**` is `src/**`, `!./gen`
is `!gen`), an inner `/./` segment, a doubled `//`, and a trailing `/` on
a pattern (`src/*/` is the trees under `src`, `src/*/**`). A bare `.` or
`./` names the project directory itself and is refused at load — write
`**`. Turbo's `$TURBO_DEFAULT$` and `$TURBO_ROOT$` and Nx's
`{projectRoot}`, `{workspaceRoot}`, `{projectName}` and `{options.…}`
(D-52), pasted from turbo.json or
project.json, are refused in every glob list with what to write instead
(D-50): vx expands none of them, so each matched no file and a task
keyed on `$TURBO_DEFAULT$` alone replayed a stale output. A glob that
starts with `^` (Nx's `^production`, the dependencies' named input) is
refused too (D-51): vx keys a task on its dependencies through
`dependsOn`. A bare named input (`default`) can be a directory, so it
is taken as one and only warns when it matches nothing.

The wildcards are `*`, `**`, `?` and a brace set `{a,b}`, which matches
what its alternatives match on their own: `{src/**,lib/**}` is `src/**`
plus `lib/**`. A bracket is a
**literal character**, not a character class: `app/[id]/**` is the route
directory `app/[id]` (Next.js, SvelteKit, Astro), never `app/i` or
`app/d`. The escaped spelling `app/\[id\]/**` (Turbo's) means the same
path. An input brace of one alternative (`{b}.ts`) is refused: it
would match `b.ts` and never a file named `{b}.ts`; write the one you
mean, `\{b\}.ts` for the braces. An extglob (`@(a|b)`, `!(x)`,
`+(…)`, `*(…)`, `?(…)`) is refused too: `Bun.Glob` reads it as literal
text or a plain wildcard, so the key would miss the files it names;
write `{a,b}`. A leading `!` is still the negation, so `!(group)/**`
takes a route group back. This holds for every task glob — `inputs.files`,
`inputs.workspaceFiles`, `outputs.files`, `outputs.workspaceFiles` — and
for everything read from them (`--affected`, `vx watch`, the
overlapping-output refusal). Package-manager member globs (`workspaces`,
`pnpm-workspace.yaml`) and `--filter` path globs keep the package
manager's grammar, class included — all but extglob (`packages/!(x)`),
which a member glob refuses by name: `Bun.Glob` cannot read it, and
list the exclusion as its own `!packages/x` entry instead.

```ts
files: ['**/*'] // all project files
files: ['src/**', '!**/*.test.ts'] // narrow with exclusion
files: [] // no file inputs at all
files: ['src/**', 'tsconfig.json', 'package.json'] // specific paths
files: ['src', 'package.json'] // a directory literal is its tree
files: ['app/[id]/**'] // a bracket is literal: the route dir `[id]`
```

Empty array is valid — the cache key still incorporates command, env,
upstream hashes, workspace fingerprint, and the project's
package.json. A task with no _file_ inputs (e.g. a pure
"download-and-verify") still cache-misses on a lockfile change.

Always applied to every glob pass (regardless of what you wrote):

- **gitignore filter** — workspace-root + project `.gitignore`.
- **Always-ignored** — `.git/**`, `.vx/**`, `*.tsbuildinfo`,
  `vx-lock.json`, `*.bun-build`, and Bun's cross-compile extraction
  directory `.<16 hex>-<8 hex>.tmp/**`, and vx's own restore temp
  `.vx-tmp-*`, at any depth.
- **Installs** — an untracked file under any `node_modules/` (ignored or
  not). A file git TRACKS there, such as a committed test fixture, is an
  input like any other.
- **Declared `outputs.files`** are excluded — a task never invalidates
  itself via its own output. A path an output `!` entry takes back is
  no output, so it stays an input (A-44). Another task's outputs are
  not excluded for you: an input glob that can match them is refused
  while `rules.upfrontKeys` is on (X-54). Write the exclusion,
  `['**/*', '!dist/**']`. An input entry the task's OWN outputs take
  back whole is always refused (X-55): vx removes outputs before a run,
  so a formatter declaring `src/**` as both would delete its sources. A
  task that rewrites files in place declares no outputs.
- **Nested-project subtree** — files belonging to a project rooted
  inside this one's dir are excluded. No cross-project leakage via
  globs; the only cross-project relationship is `dependsOn` +
  upstream-hash propagation.

##### `inputs.workspaceFiles` (optional, default `[]`)

Workspace-root-relative globs — the Turbo `$TURBO_ROOT$` / Nx
`{workspaceRoot}` equivalent, for inputs that live outside the project
dir (a root `tsconfig.base.json`, shared codegen output, …). Same
syntax as `files` (`!` negation subtracts, in any order), same git-aware
resolution (tracked + untracked-not-ignored; gitignored files are
invisible), and the resolved paths join the same cache-key file list.

```ts
inputs: {
  files: ['src/**'],
  workspaceFiles: ['tsconfig.base.json', 'shared/**', '!shared/README.md'],
}
```

**No boundary rule — deliberate escape hatch.** Unlike `files`,
`workspaceFiles` globs may match files anywhere in the workspace,
including inside other projects' directories. That's bad practice
(prefer project-relative declarations plus `dependsOn` + upstream-hash
propagation for cross-project relationships), but it is there for the
cases that genuinely need root-anchored inputs. The hard
project-boundary rule continues to apply to project-relative `files`
globs only.

No input or output glob, `files` or `workspaceFiles`, may be absolute
or hold a `..` segment, and a brace arm counts: `{../shared,src}/**` and
`{/etc,src}/*` are refused at load, where the glob engine would have
matched nothing under that arm and said so nowhere. A Windows spelling
is refused the same way, with the forward-slash glob to write: a
backslash separator (`src\**`, `src\*.ts`) or a drive (`C:\src\**`,
`C:/src/**`). A backslash before a bracket, a brace, a `!` or a
backslash stays an escape.

Still applied: the always-ignored set (`.git/**`, `.vx/**`,
`*.tsbuildinfo`, `vx-lock.json`, `*.bun-build`, `.<16 hex>-<8 hex>.tmp/**`, `.vx-tmp-*`),
untracked files under `node_modules/`, and the task's own declared
outputs, `outputs.workspaceFiles` and the `outputs.files` its globs reach
in its own project (a task never invalidates itself).

`vx watch`: when any config declares `inputs.workspaceFiles`, the loop
watches the workspace root recursively (any file can be an input once
boundaries are off), so root-subdir changes re-trigger cycles like any
other edit. The always-ignored set still filters the noise.

##### `inputs.env` (optional, default `[]`)

Env var names whose host values are folded into the cache key.
**Independent of `exec.env`:**

- Listing a name in `exec.env.passThrough` does NOT make its value
  affect the cache.
- Listing a name here does NOT forward it to the child process.

To both forward AND track, list it in both places. Yes, the
double-declaration is mild noise; a preset helper
(`envTracked('NODE_ENV')`) can sugar it.

Names are exact: a wildcard (`NEXT_PUBLIC_*`) is refused, and so is
Turbo's `!NAME` exclusion, here, in `exec.env.passThrough` and in
`exec.env.secret` (D-53). With no wildcard to take it out of, `!NAME`
was a variable of that name, and nothing was excluded.

```ts
inputs: {
  files: ['src/**'],
  env: ['NODE_ENV', 'TARGET_BROWSER'],  // changes here bust the cache
}
```

A cache-input env var the task actually reads must ALSO appear in
`exec.env.passThrough` (or `define`) — the child environment is
isolated, so without it the key varies on a value the command never
sees. Tracking-only declarations (an env var that influences inputs
some other way) are legal but rare; if in doubt, declare both.

An unset name, a name set to the empty string, and a name never
listed are three different keys: the key holds the count of names,
the names, and each value, with "unset" folded apart from every value
(the child tells unset from empty too — `process.env.X ?? 'dflt'`,
`${X-dflt}`). A name holding a NUL is refused.

##### `inputs.runtime` (optional, default `[]`)

Shell commands whose **trimmed stdout and stderr, kept apart,** are folded
into the cache key — the runtime-output analog of `inputs.env`. It runs
in the project dir; the Nx
[`runtime` input](https://nx.dev/recipes/running-tasks/configure-inputs),
which Nx runs at the workspace root, is `workspaceRuntime` below (Turbo
has no built-in for this — see
[vercel/turborepo#4124](https://github.com/vercel/turborepo/issues/4124)).
Use it for tool/runtime versions, OS info, or a project-local probe
script whose value should bust the cache when it changes.

```ts
inputs: {
  files: ['src/**'],
  runtime: ['./scripts/probe.sh', 'rustc --version'],
}
```

Semantics:

- Each command runs in the **project dir** (cwd = the project's
  directory), via `sh -c`, so pipelines and redirects work ("shell is
  the API"). Deduped per `(projectDir, command)` within a run — a
  command declared by both `build` and `test` in the same project runs
  once.
- The **output is resolved live at hash time on every run** (inside
  `resolveInputs`), exactly like `inputs.env` reads host env values
  live. `vx lock` freezes the command _strings_ (they're in the
  resolved config), not their output, so the field stays correct under
  `vx run --frozen` — the changed output of a frozen command still
  busts the cache.
- A **non-zero exit fails the run** (a hard `UserError` naming the
  command and exit code) — fail-loud, like a missing git binary. A
  flaky probe should not silently degrade to a stale hit.
- **Output that is not UTF-8 fails the run** too: a lossy decode keyed
  every invalid byte alike. Pipe binary output through a hash or `od`.
- The command **inherits vx's full environment**, _not_ the isolated
  env that task `exec` commands get — `exec.env.define` and
  `passThrough` describe the command's environment, not the probe's.
  This is deliberate — `node -v` / `rustc --version` need the real
  `PATH` and toolchain env, and it is what lets two tasks sharing a
  probe share one spawn (the per-run dedup above). The flip side (same
  as `inputs.env`): an env var that differs between machines silently
  changes the key; declare such inputs explicitly if you want them
  visible.
- Its `PATH` does lead with the **same `node_modules/.bin` directories
  the task's does** (the project's, then the workspace root's), so
  `tsc --version` keys the `tsc` the task runs. Before item 996 it keyed
  the global one, or failed with 127 where only the workspace had it, and
  a changed local tool replayed the old output.
- The command **runs whenever a task's key is derived** — that's every
  run (warm runs included, since the key decides hit vs miss), plus
  `vx run --dry` / `--graph` (which predict the key) and `vx run
--no-cache` (which still derives the key). Keep runtime commands pure
  probes with no side effects.
- The command runs as part of **hash derivation, before** the task's
  `exec` — so it is **not** constrained by the task's own `sandbox`
  policy (the probe runs unsandboxed even on a sandboxed task).

##### `inputs.workspaceRuntime` (optional, default `[]`)

Like `runtime`, but commands run at the **workspace root** (cwd = the
workspace root) and are deduped **globally per command** across the
whole run — a `node -v` declared in 500 projects spawns exactly once.
The runtime-input analog of `workspaceFiles`: per-task, root-anchored.
Use it for global tool versions, OS info, or any probe whose value is
the same for every project. Its `PATH` leads with the workspace root's
`node_modules/.bin` only (no project's: the value is shared by all).

```ts
inputs: {
  files: ['src/**'],
  workspaceRuntime: ['node -v'], // runs once per run, root cwd
}
```

Same `sh -c` execution, live-at-hash-time resolution (frozen-safe), and
non-zero-exit-fails semantics as `runtime`. The two fields are folded
into the cache key in **distinct namespaces**, so an identical
`(command, output)` pair never aliases between them.

##### `inputs.tasks` (optional, default = all upstream)

Same micro-syntax as `dependsOn`, plus two filter-only extras:

| Form         | Meaning                                        |
| ------------ | ---------------------------------------------- |
| `'*'`        | Include every same-project upstream hash.      |
| `'^*'`       | Include every dep-workspace upstream hash.     |
| `'name'`     | Include same-project task `name`.              |
| `'^name'`    | Include `name` in every dep workspace.         |
| `'pkg#name'` | Include the specific package's `name` task.    |
| `'!<form>'`  | Exclude — any of the above with a leading `!`. |

**Patterns** work here too, in EITHER half of every form:
`'build.*'`, `'^build.*'`, `'pkg#build.*'`, `'@acme/*#build'`,
`'!codegen.*'` — the same `*`-glob `dependsOn` patterns use. A filter
only ever selects from upstreams that already exist, so a package
pattern is unambiguous here, unlike `dependsOn`, which must
materialize concrete edges and rejects it. (A filter that matched
patterns literally would silently select zero hashes and decouple the
task from its dependencies — a stale-hit trap.)

Patterns are applied in order; **last write wins**. So
`['*', '^*', '!^noisy']` reads as "all upstream except deps' noisy
task". Defaults:

- **Omitted** → all upstream contribute (`['*', '^*']`). Most common.
- **`[]`** → fully decoupled; no upstream contributes.

An **exact** entry (`'codegen'`, `'^build'`, `'lib#build'`) must be
named by some `dependsOn` entry of the same task — exactly, or by that
entry's own `*` pattern (`dependsOn: ['build.*']` names
`tasks: ['build.bun']`), and in a form that reaches the same task:
`build` is this project's, `^build` only the dependencies', so
`tasks: ['build']` against `dependsOn: ['^build']` names nothing. A
`pkg#task` entry may be this project or a dependency, so it pairs with
either form; two `pkg#task` entries must agree on the project. One that
is not named (`['buidl']`) is refused at load: it would match nothing at hash time and fold no upstream hash,
decoupling the task from its dependencies with no diagnostic — a stale
hit waiting for the next upstream change. Patterns, wildcards and
negations stay silent (a preset-spread pattern legitimately matches
nothing in some projects); `[]` is the explicit way to decouple.

A filter selects among the task's own dependencies, never through a
group: over `dependsOn: ['build']`, where `build` is a group of
`build.a` and `build.b`, the filter sees `build`, not its members. A
pattern that matches no dependency but does match a group's member
(`'build.*'` there) is refused when the run plans: it would select
nothing and stop the key moving with that member. Name the group, or
depend on the member directly.

Examples:

```ts
tasks: ['^build'] // only ^build from deps; nothing from self
tasks: ['codegen', '^*'] // self.codegen + everything from deps
tasks: ['*', '^*', '!^noisy'] // all upstream except deps.noisy
tasks: ['lib#build'] // a single cross-project hash
tasks: [] // fully decoupled
```

**When to use this:** when a task `dependsOn`s another for ordering
(it has to run after) but the upstream's outputs do NOT affect this
task's outputs. Typical case: an integration-test task `dependsOn`s
`build` for ordering, but its inputs are only the test source — so
`inputs.tasks: []` to keep `build` from invalidating it.

#### `CacheOutputs`

```ts
interface CacheOutputs {
  files: readonly string[] // required
  workspaceFiles?: readonly string[] // optional; workspace-root-relative
}
```

Project-relative globs of files the task produces. Captured on cache
write, restored on cache hit (overwriting any local modifications),
and **wiped before exec AND before restore** so the project dir ends
every run bit-identical to the cached snapshot. A literal entry names
a file or a whole directory tree: `dist` and `dist/` are `dist/**`
(the turbo.json shape `"outputs": ["dist"]` migrates as it is); a
leading `./` is accepted and dropped; `.` alone is refused.

```ts
outputs: {
  files: ['dist/**']
} // typical build output
outputs: {
  files: []
} // tasks with no file output (lint, test)
outputs: {
  files: ['dist/**', 'coverage/**']
}
```

Outputs are **NOT** filtered through gitignore — typical artifact
dirs like `dist/`, `coverage/`, `.next/`, `pkg/` are captured normally
even when gitignored (they usually are).

A **symlink** the globs match is an output: it is captured as its
target's bytes and restored as a regular file, and the clean unlinks
it (never following it). An output DIRECTORY that is a symlink
(`dist -> real-out`) is followed: its target is cleaned, saved and
restored as the output; one that resolves outside the project refuses
the task, naming the link. A link to a directory, a dangling one, or
one whose target is outside the project cannot be stored — the save refuses it by name and caches nothing, so
the next run executes again. A link to another output of the same task
is stored wherever it is: `gen/latest -> v2.txt` under a
`workspaceFiles` output caches (A-53). The clean also prunes the directories it
emptied, so an output that is a directory one run and a file the next
restores either way.

Empty `[]` is valid for tasks that produce no files (e.g. `lint`,
`typecheck`, `test`); you still cache the no-op success so the next
run is a no-op too.

A **`!` entry takes a path back** from what the positive globs select
(A-44; a tracked fixture and a scratch dir under `dist` stay out of
the clean this way):

```ts
outputs: {
  files: ['dist/**', '!dist/fixture.html', '!**/*.tmp']
}
```

A path taken back is not cleaned before a run or a restore, not saved,
not accepted from a remote artifact, and not hidden from `vx watch`;
it stays an input, so an edit to it moves the key. A list of only `!`
entries selects nothing and is refused, and `!!x` is refused as it is
for inputs. The directory short-circuit on a warm hit reads the
positive globs, so a task with a `!` entry keeps it (A-46).
`workspaceFiles` takes `!` the same way.

**Cleaning semantics** (one of vx's strict-output-ownership rules):

- Before exec on a cache miss: the declared output globs are resolved
  and matching files / dirs are wiped. So a leftover `dist/old.js`
  from a prior build can't survive into a fresh build that doesn't
  rewrite it.
- Before restore on a cache hit: same wipe, then files are copied
  from the cache entry into the project dir. The post-restore tree
  is the cached snapshot, byte-for-byte.

Skipped when `cache.outputs.files` is empty (nothing declared as
output) and when no cache-write axis is enabled (e.g. `--no-cache`,
or a read-only `--cache=local:r`) — the user is debugging and
managing the tree themselves. `--force` keeps writes on, so it does
clean.

##### `outputs.workspaceFiles` (optional, default `[]`)

Workspace-root-relative globs for outputs the task writes OUTSIDE its
project dir (e.g. a root-level generated file). Same capture / restore
/ wipe semantics as `files`, anchored at the workspace root; packed
into the artifact under a separate `workspace-outputs/<rel-to-root>`
namespace so project and workspace outputs never collide. A project
`outputs.files` glob under a top-level `workspace-outputs/` is refused
at load: that name is the namespace. A file another glob matches there
(`**/*.js`) is refused at save, and the task is not cached.

```ts
outputs: {
  files: ['out.txt'],
  workspaceFiles: ['generated/**'],
}
```

**No boundary rule — deliberate escape hatch.** These globs may
capture (and on restore, overwrite; on clean, wipe) files anywhere in
the workspace, including inside other projects' dirs. Prefer
project-relative `files` whenever the task can write inside its own
dir. Two tasks whose workspace outputs provably overlap (equal
literals, or a literal a glob matches) are refused at graph build, like
overlapping `files`: vx cleans declared outputs before a run and before
a restore, so the second would delete the first's. The comparison is by
PATH, not by spelling — `./dist/**` and `dist/**` are one declaration,
and so are `dist//**` and `dist/./app.js` (item 441) — and a literal
entry is read as the file OR its whole tree, the same rule the resolver
uses, so `dist` collides with `dist/app.js` (item 442). A whole subtree
collides with any glob whose literal head lies inside it: `dist/**` with
`dist/extra/**` or `dist/*.js` (item 941). Globs that only _might_
overlap (`dist/*` and `dist/sub/**`) are let through; there, last
restore wins. A workspace output is also compared with every other
project's `files` outputs, read from the root: `packages/b/dist/a.txt`
collides with `b`'s `dist/**` (item 1088). An overlap
between two tasks one of which depends on the other is refused too,
unless the workspace sets `rules: { exclusiveOutputs: false }` (X-53);
then the dependant is additive and owns only what its run adds to the
tree (`caching.md` § Additive outputs, item 588). Across the two namespaces
an upstream `files` task is told the dependant's globs in its own
project's terms, so a workspace glob that does not start inside that
project (`**/a.txt`) is refused even with the edge.

### `exec.sandbox` (optional)

Opt this command into an OS-level sandbox. A persistent task runs
inside it too — enforced, but with no violation report, since the report
reads the trace after the child exits and a server exits only at
teardown. **Opt-in per task — omit it and the command runs
unsandboxed.** Full walkthrough in the
[sandboxing guide](https://vznjs.github.io/vx/guides/sandboxing/).

```ts
interface SandboxConfig {
  allow?: SandboxGrants // what the command may do
  deny?: { network?: string[] } // domains to refuse, run-wide (below)
  ignore?: SandboxIgnore // violations to leave out of the report
  weakerWhenNested?: boolean // Linux: let a sandboxed task sandbox (default false)
  weakerNetworkIsolation?: boolean // macOS: host-proxy net, lower isolation (default false)
}

interface SandboxGrants {
  read?: readonly string[] // paths or globs, project-relative or absolute
  write?: readonly string[] // paths or globs; a write grant is readable too
  network?: true | readonly string[] // an allowlist of domains; `true` adds none (below)
  systemInfo?: readonly string[] // sysctl names, e.g. 'vfs.disk-space'; each grants system-info and sysctl-read (macOS)
  unixSockets?: true | readonly string[] // AF_UNIX bind/connect, all or by path (Linux: any path)
  localBinding?: boolean | readonly number[] // bind and reach localhost ports (macOS; Linux needs no grant); a list also exposes them to the host (a port the host or another running task already holds fails the task)
  machLookup?: readonly string[] // mach global-names (macOS)
  pty?: boolean // acquire a TTY
  gitConfig?: boolean // write the repository's .git/config (this task only)
}

interface SandboxIgnore {
  read?: readonly string[] // denied reads to leave out of the report
  write?: readonly string[]
  systemInfo?: readonly string[]
  network?: readonly string[] // '<host>:<port>'
}
```

One shape describes what a task may do; vx translates it into a seatbelt
profile on macOS and bwrap mounts plus seccomp on Linux. `ignore` takes
patterns per class a denial is reported in — `read`, `write`,
`systemInfo`, `network` — so a noisy probe is silenced with the grant
that would have permitted it; any other name is refused. Every grant is
the task's own: `unixSockets` (or a `localBinding` port list, whose
bridge is a unix socket) lifts the `socket(AF_UNIX)` block for the task
that declares it, never for the run's other sandboxed tasks. On Linux
the block is the kernel's answer to the call itself, so it is reported
nowhere: the task reads only its tool's own `socket(1, 1, 0): Operation
not permitted` (a Docker, ssh-agent or database socket), and the grant
is `unixSockets`:

```ts
exec: {
  command: 'bun build --compile --target=bun-linux-arm64 src/bin.ts --outfile dist/vx',
  sandbox: {
    allow: {
      read: ['.'],
      // A cross-compile target the Bun cache lacks is fetched from npm,
      // extracted into `<cwd>/.<hash>-00000000.tmp/` and moved into the cache.
      write: ['dist/vx', '~/.bun/install/cache/', '.*.tmp/**'],
      network: ['registry.npmjs.org'],
      systemInfo: ['vfs.disk-space'],
    },
    ignore: { write: ['*.bun-build'] },
  },
}
```

**Globs.** `read` and `write` accept patterns. On macOS the pattern
reaches the policy and matches files created during the run; on Linux a
grant is a mount, so the pattern is expanded when the task starts and a
file created later is not covered — grant its directory instead. On both
platforms `<dir>/**` and `<dir>/**/*` collapse to `<dir>`, so
`read: ['**/*']` lets a task list its own cwd; a `<dir>` that is itself a
glob keeps its subtree (`.*.tmp/**` covers what is inside each match).
Unlike a task glob, a grant keeps `Bun.Glob`'s brackets: `[id]` is a
class, so a Next.js route is granted escaped, `read: ['pages/\\[id\\].tsx']`.
On Linux a WRITE path holding a bracket, `*` or `?` cannot be mounted
(the runtime drops it): vx says so once, names the directory above it to
grant instead, and a write under it is refused and reported. A READ path
whose name holds `*` or `?` (granted escaped, `a\\*b.txt`) cannot be
granted alone either — the runtime would grant its siblings too — so vx
leaves it out, says so once, and a read of it is refused and reported.
A Linux grant of either kind holding a backslash is left out the same
way: Bun's `realpath` refuses such a path, and the runtime mounts none
it cannot resolve.

A Linux WRITE grant that matches nothing when the task starts therefore
mounts nothing. Where a read grant mounts its directory, the task's first
write under it fails with `Read-only file system` — a message naming
neither vx nor the grant — so vx reports that grant itself before the
task runs, once, and names the directory to grant instead, spelled as
the config spells it (`allow: { write: ['gen/'] }`). Where no mount
holds the directory, it is the sandbox's own scratch, the one mask left
writable: the task may create, write and remove what the glob matches
(anything else it writes there too), and nothing it leaves there
outlives the task. That is right for a tool's temp directory and
wrong for an output. A read grant matching nothing is ordinary
(an optional file, a cache not yet populated) and is not reported. A
pattern under a directory that does not exist yet matches nothing the
same way, where the scan once failed the task with a bare `ENOENT` (B-6).

**A write grant's shape.** A write path that does not exist yet is
created before the task starts (a mount needs something to bind), and a
literal names a FILE: `write: ['dist/vx']` is an empty `dist/vx` the
build overwrites. A directory the task will create is spelled with a
trailing slash — `write: ['coverage/']` — or as a glob (`'dist/**'`);
outside the project (`'~/.bun/install/cache/'`) only these two shapes are
created, never a file.
Spell a directory as a bare literal and the task's own `mkdir` meets
"File exists" ("Not a directory" for a path inside it, `mkdir -p
coverage/lcov`); the failure then says so, names the `dir/` spelling, and
vx removes the empty file it made (it takes back any placeholder the
task never wrote, so an unwritten one is never archived as an output).
A grant that leaves the project through a symlink is refused: the grant
binds the path it names, and vx follows no link out of the project. So
is one whose bind would make `.git`, `.vx`, the cache directory or a
nested project writable:
a file grant at a single-package workspace's root binds the root. A
directory grant is judged as the directory, made before the judgement
when it does not exist yet, so `dist/` or `dist/**` at that root stands.

**A write grant is readable, and on Linux it reads WIDER than it looks.**
A write path is readable too (`tsc --incremental` re-reads its own
`.tsbuildinfo`). On Linux a grant is a mount and bwrap cannot rename onto
an active file mount — every atomic writer stages beside its target and
renames — so a FILE-shaped grant is bound as its DIRECTORY. That
directory is then readable AND writable in full: with
`write: ['out.txt']` in the project root, every file in the project root
can be read. Such a read succeeds, so there is no denial; vx reports it
from the trace instead, as a violation: a read of anything that was in
that directory when the task started and that no grant covers, the
directory's listing included. The declared file and what the task made
there itself stay readable. Put declared outputs in a subdirectory and
the rest stays denied outright. macOS matches paths rather than
mounting, so a file grant stays exact there. Pinned in
`tests/sandbox-runtime.unsafe.test.ts` (2026-09-20) and
`tests/sandbox-widened-reads.unsafe.test.ts`.

**A `network` entry is a host pattern**: `example.com`, `*.example.com`,
either with a port (`example.com:443`), or `localhost`. A scheme or path
(`https://example.com`), a dotless host, a bad port, and `*` or `*.com`
(too broad) refuse the run with the entry named; `deny.network` also
takes a bare `*` (deny all, `*:22` for one port). Until 2026-10-02 such an
entry matched nothing with no word, and an allowed `*` opened every host
to every sandboxed task of the run.

**`network` is per-RUN, not per-task.** SRT runs one filtering proxy
per `vx run` and checks every request against the allowlist that proxy
was started with: the union of every domain list any sandboxed task in
the graph declared. Every sandboxed task is handed that proxy. So a task
that declares no network reaches the domains another task of the run
listed, and `network: true` reaches only those (nothing in a run with no
list). `deny.network` is the run's too: the proxy starts with the union
of every task's denies and refuses those domains to every task, checked
before the allowlist (B-21). A refused request is a violation on both
platforms, `deny network-outbound <host>:<port> (<reason>)` from the
proxy, and fails the task even when it survived the refusal;
`ignore: { network: ['<host>:<port>'] }` silences one, matched as the
proxy matches: case-blind, a trailing dot dropped (until 2026-10-08 the
client's spelling, `EXAMPLE.Com` or `example.com.`, escaped it). Until
2026-10-02 Linux reported none, and the line could not be ignored on macOS.

**Baseline** (`sandbox: {}`): the task reads nothing in the workspace,
writes nothing but its own `TMPDIR` and reaches no domain no task of the run lists — not even its own project
directory, which is why `allow: { read: ['.'] }` is the first line of
almost every real block. The task still starts in its own directory, an empty one
then: a relative read is refused and reported, never resolved elsewhere. The read wall is the WORKSPACE ROOT: a path
outside it (`~/.cache`, `/etc`, the toolchain) is readable and folds into
no key, so a task whose output depends on one declares it as a key input
(`inputs.runtime`, `inputs.env`) — the sandbox does not catch it (item
966).
The one exception is where tools keep credentials, denied unless a
grant names one (`read: ['.', '~/.npmrc']` for a publish; a write grant at
or inside a store frees that path alone), since a
dependency the task ran could copy a key into an output the cache
shares (L-41): `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.azure`, `~/.kube`,
`~/.config/gcloud`, `~/.config/gh`, `~/.docker/config.json`, `~/.netrc`,
`~/.git-credentials`, `~/.npmrc`, `~/.yarnrc.yml`, `~/.pypirc`,
`~/.bunfig.toml`, `~/.config/.bunfig.toml`, `~/.cargo/credentials`,
`~/.cargo/credentials.toml`, `~/.gem/credentials`, `~/.config/hub`,
`~/.config/containers/auth.json`, `~/.terraform.d/credentials.tfrc.json`,
`~/.vault-token`, `~/.pgpass`.
What it grants from there is the union of the read grants and, on Linux,
the DIRECTORY holding each file-shaped write grant (above).
Nothing is inherited from `cache` — `cache.inputs` says what INVALIDATES a task, `sandbox.allow`
says what it may TOUCH, and deriving one from the other made a
declaration added for caching silently widen the sandbox. The one grant
vx makes for you is dependencies: `node_modules` and, through it, the
real path of every workspace package linked there, and in turn in each
such package's own `node_modules`. A project never names
a sibling to import what its `package.json` already depends on. A link
back to the task's own project, or to a directory holding it, is not
followed: npm and Yarn link every workspace package at the root, the
task's own included, and following it would grant the whole project
past its `allow.read`.

A task that declares `cache` gets a linked workspace package only when
its key already answers for it: some task of that package is folded into
the key through `dependsOn` (as `cache.inputs.tasks` selects it, groups
passing everything through). Every other link inside the workspace root
is withheld, and a read through one fails the task with the denial plus
one line naming the package and the edge that would key it. Declaring
`cache` can only narrow this grant, never widen one: a task with no
`cache` keeps it whole, having no key to be stale, and your own `allow`
grants never depend on it. The key answers for the package, not the
file: an edge to `ui#source` (inputs `src/**`) covers a read of
`ui/README.md` too.

**A missing write grant fails the task.** On macOS seatbelt refuses the
write and reports it. On Linux the write meets a read-only bind or a
read-only mask: the empty directory the sandbox lays over what it hides
(the workspace root around a project, a single-package workspace's root,
the project root around a write grant punched out of a read grant —
`read: ['.']` with `write: ['dist/']` binds the children one by one). It
is `Read-only file system` on both; until 2026-10-02 the Linux mask was
writable, and a write there succeeded and left nothing on disk. The
runtime's write observer saw the attempt, and a write no grant binds is
reported and fails the task, even when the command swallowed the error
and exited 0 (B-5; before it, both Linux shapes passed with nothing
reported, items 444 and 1011). A write outside the project is refused
the same way and named on a failed task, never counted. The remedy is to
declare it: `allow: { write: [...] }`.

**A write grant cannot be removed on Linux.** A directory grant is
mounted in place, so `rm -rf dist && tsc` under `write: ['dist/']`
empties `dist` and then fails with `Read-only file system`; a failed
task names the grant. Remove its contents instead: `rm -rf dist/*`.

**The boundary is the workspace root.** A task may not leave its own
project, so every sibling project and every root file is denied. Being
stopped at that wall is the sandbox working, not a finding: only
denials INSIDE the project are reported, because those are the reads
that make a cache key wrong. A write refused past the wall is named
beside a FAILED task, never counted, with the directory to grant, spelled
from the project when it is in the workspace (under the host's temp
directory, `$TMPDIR`, the task's own, instead): a
tool that cannot fill its cache (`~/.bun/install/cache`) rarely says
where it tried. So is a read the wall hid of a path that exists on the
host, with the grant spelled from the project (`'../../tsconfig.base.json'`):
the tool said only "not found". To reach a path outside the project but
inside the workspace — a workspace-level fixture — declare it; a path
outside the workspace is not walled (above).

**git in a sandboxed task** reads the repository only if it is granted:
`read: ['.', '../../.git']` from a project two levels down (`.git` is a
wall, so `read: ['.']` in a root project leaves it out too). On Linux
a task whose grants name a `.git` gets `GIT_DISCOVERY_ACROSS_FILESYSTEM=1`
(a value the task sets wins), since every sandbox mount is a filesystem
boundary git's discovery stops at. `git rev-parse` and `git log` then answer as outside;
`git status` reports a file the task may not read as deleted.

**Policy: fail on violation.** An undeclared read, or a write the
sandbox refuses, fails the task, and a failed task is never cached.
On Linux a denied read is reported only where `strace` is on PATH and
may attach; elsewhere the sandbox still denies it, the task fails
only if the command does, and the run says once that reads go unreported. Activation is lazy (only when
some task declares `exec.sandbox`); on an unsupported platform a
sandboxed task fails fast rather than running unsandboxed. Linux needs
`bubblewrap`, `socat` and `ripgrep` installed (the runtime expands its
mandatory deny globs with `rg`); a missing one is named with the install.
Inside a write grant, a file named like a shell or tool config
(`.bashrc`, `.zshrc`, `.gitconfig`, `.mcp.json`, …), anything under
`.vscode/` or `.idea/`, and `.git/hooks` or `.git/config` stay read-only
to the task, down to three levels below the workspace root, ignored by
git or not.

**No `[`, `]`, `*` or `?` in the project's path.** The runtime reads a
path holding one as a pattern: on Linux it mounts no write path that
does and a read grant matches its siblings, and macOS's rules compile it
as a pattern too. So a sandboxed task in a project under such a directory
(`~/[old]/repo`, `~/w*s/repo`) is refused, naming it: rename the
directory or drop `exec.sandbox`. On Linux so is a project under a
directory holding a backslash, which the runtime cannot mount at all (its
task saw no project and ran in `$HOME`).

**macOS cannot nest.** `sandbox_apply` is refused inside a sandboxed
process, so a task that itself sandboxes something (vx's own test suite)
cannot be sandboxed on macOS. `weakerWhenNested` covers the Linux case;
there is no macOS equivalent to offer.

## Group tasks (no `exec`)

A task with no `exec` and a `dependsOn` is a **group task** — a pure
aggregator. Running a group is equivalent to running its dependencies;
nothing else happens (no spawn, no I/O, no cache read/write). An empty
`dependsOn: []` is an explicit no-op group: it exists to be named — by a
dependant's `^build`, by `vx run build --all` — and runs nothing. A
project with no `build` gets a keyed one (above), which a bare name
does not select.

A group with `cache` is a **keyed group**: its `cache.inputs` are a key
and nothing runs. A task that depends on it folds that key, so an edit
to those inputs re-runs the dependant, and `--affected` reaches it. Its
`cache.outputs` must be `{ files: [] }` (a group writes nothing), and it
needs no `dependsOn`. It spawns nothing, writes no cache entry, and the
run summary does not count it. `@vzn/vx-migrate` writes one for each
Nx `^production`-style input and each Turbo transit node.

```ts
// `test` re-runs when a file under fixtures/ changes; nothing spawns for it
fixtures: { cache: { inputs: { files: ['fixtures/**'] }, outputs: { files: [] } } },
test: { exec: { command: 'bun test' }, dependsOn: ['fixtures'], cache: { /* … */ } },
```

Bare `--exclude-dependencies` keeps a group's edges for the same reason:
`vx run ci --exclude-dependencies` runs `ci`'s members without their own
dependencies. A name list (`--exclude-dependencies=lint.oxfmt`) drops a
member it names, like any edge.

```ts
// `vx run install --all`  →  fans out to `build` in every workspace dep
install: {
  description: 'build everything in workspace dependency order',
  dependsOn: ['^build'],
}

// `vx run ci`  →  runs format-check + lint + test in the cwd project
ci: {
  description: 'format-check + lint + test (CI gate)',
  dependsOn: ['format-check', 'lint', 'test'],
}
```

Group tasks:

- **Are not counted in the run summary.** "3 tasks, 2 cached" reflects
  real executable tasks — including a group in the count is confusing
  ("3 of 4 cached" when one was a group that ran nothing).
- **Are not recorded in the `runs` table.** Analytics queries that
  aggregate runtime won't see them.
- **Render no framed block** in the live output.
- **DO contribute a stable hash to downstream tasks** that filter
  `inputs.tasks` to include the group. The hash is rolled up from
  the group's upstream outcomes (sorted, joined, hashed). So any
  change beneath the group cascades correctly.

The loader rejects:

- A task with no `exec`, no `dependsOn` and no `cache` (literal no-op).
- A group whose `cache.outputs` names a file (a group writes nothing).

## Workspace config (`vx.workspace.ts`)

Loaded from `vx.workspace.{ts,mts,js,mjs,cts,cjs}` at the workspace root.
**Optional** — when missing, every field falls back to its built-in
default.

```ts
import { defineWorkspace } from '@vzn/vx/config'
import { otel } from '@vzn/vx-otel'

export default defineWorkspace({
  concurrency: 8,
  cacheDir: 'build/.vx-cache',
  timeout: 600_000,
  cacheRetention: { olderThan: '30d', maxSize: '10G' },
  affectedBase: 'origin/main',
  cacheScope: 'trusted',
  rules: { exclusiveOutputs: true, upfrontKeys: true },
  plugins: [otel()],
})
```

```ts
interface WorkspaceConfig {
  /** Maximum concurrent tasks. Defaults to the cores this process may use (the CPU count, capped by a cgroup quota). */
  concurrency?: number
  /** Cache directory, relative to workspace root. Named, it holds the whole cache; unset, entries live in the user's shared store. */
  cacheDir?: string
  /** Default per-task timeout (ms) for tasks without their own exec.timeout. */
  timeout?: number
  /** Evict from the local cache at the end of each run (the `vx cache prune` policy). */
  cacheRetention?: { olderThan?: string; maxSize?: string }
  /** The git ref a bare `--affected` compares with. */
  affectedBase?: string
  /** Where remote writes land: 'trusted' (default), 'read-only', or an untrusted scope name. */
  cacheScope?: string
  /** Graph rules checked before anything runs; each on unless set to false. */
  rules?: WorkspaceRules
  /** Run-level plugins (cache / executor / telemetry capabilities). */
  plugins?: readonly Plugin[]
}

interface WorkspaceRules {
  /** Refuse overlapping outputs even across a dependsOn edge. Default true. */
  exclusiveOutputs?: boolean
  /** Refuse a task whose inputs can match another task's outputs. Default true. */
  upfrontKeys?: boolean
}
```

- **`concurrency`** — used as the default cap on parallel tasks; the
  CLI `--concurrency <n>` still wins when passed.
- **`timeout`** — the lowest-precedence default per-task timeout (ms),
  applied to any task that declares no `exec.timeout`. Precedence,
  highest first: per-task `exec.timeout` → `--timeout` /
  `RunOptions.timeout` → `VX_TASK_TIMEOUT` env → this. A runaway task's
  process group is SIGTERMed and the task reported `failed`. Purely a safety net — never folded
  into a cache key (a timed-out task fails and is never cached).
- **`cacheDir`** — unset, the workspace keeps its index and history in
  `.vx/cache` and its entries and artifacts in its repository's shared
  store (`~/.vx/<id>/cache`), where every other checkout of the
  repository hits them (`docs/caching.md`). Named here, by
  `VX_CACHE_DIR`, or by `--cache-dir`, the directory holds the whole
  cache, shared with no other workspace.
  Relative paths are resolved against the workspace
  root, `~/` against the home directory; absolute paths are used
  as-is. The home directory itself (`~`) is refused. `vx run`, `vx cache prune`,
  and any other reader use the same resolution
  (`src/workspace/workspace.ts:resolveCacheDir`). The cache is a
  directory of its own: a first index in one that holds a
  `package.json` or `pnpm-workspace.yaml` (`''` and `'.'` name the
  root), whose subdirectory does (`'packages'`), or that holds the
  workspace (`'..'`, `'/'`) is refused before anything is written, since its `*`
  `.gitignore` would hide the sources from git and the cache keys.
- **`cacheRetention`** — the `vx cache prune` policy, applied at the
  end of every run: entries unused for
  `olderThan` (`30d`, `12h`, `90m`, `45s`) go first, then the
  least-recently-used until the cache is under `maxSize` (`10G`,
  `500MB`, `64KB`; a bare number is refused as a typo, `10B` is not).
  Either or both, and neither may be zero: each would evict what every
  run just saved (item 969). It runs after the run's saves
  and uploads have landed, never on a run a signal or an abort stopped
  (one stopped while it waited on the workspace lock never held it), only when something is due (a run with
  nothing to evict pays one scan of the index), and says nothing:
  housekeeping prints no line (owner, 2026-10-06). Under `olderThan` an entry the run just used is never due, but `maxSize` is least-recently-used first, so a bound below one run's outputs evicts that run's own. The prune's
  orphan sweep (artifacts no index row counts, judged by file time —
  see `vx cache prune`) also runs on its own clock, at most once an
  hour, so their bytes go even when nothing the index holds is due;
  listing the directory every run would cost 0.5 ms per 1,000
  entries. Housekeeping,
  not the run's work: a failure is silent, never a failed run. Not
  folded into any cache key. Omitted → the cache grows until
  `vx cache prune`.
- **`affectedBase`** — the git ref a bare `--affected` compares with
  (`origin/develop`); `--affected=<base>` still wins. Omitted →
  `origin/HEAD`, then the first of `origin/main`, `origin/master`, `main`, `master` that is not HEAD (D-93), else `HEAD~1`. A plugin's `config` stage may set it:
  `nx()` from `NX_BASE` or nx.json's `defaultBase`, `turbo()` from
  `TURBO_SCM_BASE`, else on GitHub Actions from `GITHUB_BASE_REF` or the
  push event's `before`, as Turbo does. Not folded into any cache key.
- **`cacheScope`** — where this run's remote cache writes land.
  `'trusted'` reads and writes the task keys: the default branch's CI.
  `'read-only'` reads them and writes nothing: a laptop. Omitted, `vx
run` takes `'read-only'` off CI (`CI` unset, `0` or `false`) and
  `'trusted'` on CI or when `--cache` names the remote; `run()` takes
  `RunOptions.defaultCacheScope`, else `'trusted'`.
  Any other name (`'pr-123'`; letters, digits, `. _ - / @`, at most 128) is an untrusted scope: a remote read tries the scope's key, then
  the trusted one, and a write goes to the scope's only, so a pull request
  never writes what the default branch reads, and two scopes never see
  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
  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.
- **`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,
  or a rule vx does not know, is refused.
  - **`exclusiveOutputs`** (X-53) — two tasks whose declared outputs
    overlap are refused even when a `dependsOn` edge orders them:
    `&lt;a&gt; and &lt;b&gt; both declare the output "&lt;glob&gt;" … Give each task its
own output path, or set rules: { exclusiveOutputs: false } in
vx.workspace.ts to let a dependant add to its upstream's outputs.`
    Off, the dependant adds to its upstream's tree (item 588;
    `caching.md` § Additive outputs). Two overlapping tasks with no
    edge are refused either way.
  - **`upfrontKeys`** (X-54) — a cached task whose `inputs.files` can
    match a same-project task's `outputs.files`, or whose
    `inputs.workspaceFiles` can match any task's `outputs.workspaceFiles`
    or another project's `outputs.files` read from the root, or whose
    `inputs.files` can match another task's `outputs.workspaceFiles`
    landing in its project (X-135), is refused,
    edge or no edge: `&lt;reader&gt; reads "&lt;glob&gt;" in cache.inputs.&lt;field&gt;,
which matches &lt;writer&gt;'s output "&lt;glob&gt;" … Exclude it: add "!&lt;glob&gt;"
to &lt;reader&gt;'s cache.inputs.&lt;field&gt;, or set rules: { upfrontKeys:
false } in vx.workspace.ts to let it wait for its producer.` Such a key
    reads what the producer writes this run, so vx cannot know it before
    the producer ran: it is not probed, prefetched or restored ahead of
    the schedule (`caching.md` § Local restore tier). The upstream's key
    already reaches the reader through `dependsOn`. A `!` entry that
    takes the whole output back clears it, and an output the reader's
    `!` entries take back no longer holds its key back either. A task's
    own outputs, a task with no `cache`, and a group are exempt. Off,
    the key waits for its producer, as before.
- **`plugins`** — the run-level extension points. Optional: core
  applies no plugin by default, and the local executor and the local
  cache are its floor — the tail of every executor list and cache chain
  — so a workspace that declares none runs and caches here.
  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
  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`
  (edit a loaded project's tasks — inject, remove, rewrite;
  re-validated by core and hashed into the key like a hand edit),
  `graph` (edit the task graph's edges), `key` (per-task
  `{ name: value }` material folded into the cache key), `fingerprint`
  (claim a lockfile and key it per project, or a root file the plugin's
  stages read, such as `turbo.json`, so `--affected` asks the plugin
  about it and `vx watch` re-runs on it), `schedule` (task id →
  priority, merged over the scheduler's baseline), `admit` (may this
  ready task start now beside what runs here), `executor` (return a
  `TaskExecutor` — where one task's command runs — or decline), `cache`
  (return a cache layer or decline), `telemetry` (observe-only export:
  OTel, the GitHub job summary, a custom sink), `setup` and `teardown`
  around the run, and CLI `commands` (`{ verb: { description, run } }`,
  consulted for a verb core does not know). First-party plugins:
  `@vzn/vx-otel`, `@vzn/vx-ci`, `@vzn/vx-reapi`, `@vzn/vx-lockfile`,
  `@vzn/vx-schedule-history`, `@vzn/vx-mcp`, `@vzn/vx-migrate`. A
  plugin that declines every capability (`otel()` with no OTLP endpoint
  configured) costs nothing — a run with no active plugin is
  byte-identical to one with none declared. Plugins observe, route and
  execute; they never change what a task is.

The loader validates the shape (positive integer for `concurrency`,
string for `cacheDir`, plugin objects with a name and at least one
capability) and throws a `UserError` on
malformed input.

There are no workspace-level `globalInputs` / task-default fields:
root-anchored file inputs are declared per task via
`cache.inputs.workspaceFiles`, root-anchored probes via
`cache.inputs.workspaceRuntime`, and shared task shapes compose
through plain TypeScript (import a preset and spread it) — the
language replaces Nx-style `namedInputs` / `targetDefaults` schema
machinery by design.

## Helpers

```ts
import { defineProject, defineWorkspace } from '@vzn/vx/config'

// Identity functions; their purpose is type inference.
defineProject<const T extends ProjectConfig>(config: T): T
defineWorkspace<T extends WorkspaceConfig>(config: T): T
```

Use them so TypeScript narrows literal types in your config —
autocomplete for task names in `dependsOn` against your declared
tasks, strict validation against the schema, errors at edit time
rather than at `vx run` time.

They cost one runtime import of `@vzn/vx/config` per config file:
`src/config.ts`, which imports nothing, so it is cheap, but it must
resolve from the config's directory. The type-only form gives the same
editor checking with no runtime import, and is what `vx init` /
`@vzn/vx-migrate` write:

```ts
import type { ProjectConfig, WorkspaceConfig } from '@vzn/vx/config'
export default { tasks: { … } } satisfies ProjectConfig
export default { plugins: [] } satisfies WorkspaceConfig
```

You _can_ skip the helpers and write
`export default { tasks: { … } }`, but the IDE experience is
strictly worse.

## Full example

```ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    // Real cached task with file inputs, env tracking, and outputs.
    build: {
      description: 'compile TypeScript to dist/',
      // NODE_ENV is a cache input below, so it must reach the child
      // too — the exec env is isolated, not inherited.
      exec: { command: 'tsc -b', env: { passThrough: ['NODE_ENV'] } },
      dependsOn: ['^build'],
      cache: {
        inputs: {
          files: ['src/**', '!**/*.test.ts', 'tsconfig.json'],
          env: ['NODE_ENV'],
        },
        outputs: { files: ['dist/**'] },
      },
    },

    // Cached, depends on upstream build; CI is in passThrough only
    // (CI=1 shouldn't bust the cache — it's true on every CI run).
    test: {
      description: 'run unit tests',
      exec: { command: 'bun test', env: { passThrough: ['CI'] } },
      dependsOn: ['build'],
      cache: {
        inputs: { files: ['src/**', 'tests/**'] },
        outputs: { files: [] },
      },
    },

    // Cross-project edges. The pkg.tgz from one project's build is
    // cached, and depends on builds in every workspace dep.
    package: {
      description: 'pack the npm tarball',
      exec: { command: 'rm -rf pkg && npm pack --pack-destination ./pkg' },
      dependsOn: ['build', 'test', '^build'],
      cache: {
        inputs: {
          files: ['package.json'],
          tasks: ['build', '^build'], // hash these upstream too
        },
        outputs: { files: ['pkg/*.tgz'] },
      },
    },

    // Persistent dev server. Downstream tasks unblock on the
    // "Local:" line, not on exit (which never comes).
    dev: {
      description: 'vite dev server',
      exec: {
        command: 'vite',
        timeout: 30_000,
        persistent: { readyWhen: 'Local:' },
        env: { passThrough: ['VITE_API_URL'] },
      },
    },

    // E2E test gated on the dev server. Together: vx run e2e runs
    // dev → e2e; e2e exits → orchestrator SIGTERMs dev → run ends.
    e2e: {
      description: 'end-to-end tests against dev server',
      exec: { command: 'playwright test' },
      dependsOn: ['dev'],
    },

    // Two cached checks with no outputs: the verdict is the exit code.
    // A name with a hyphen is quoted, as any object key is.
    lint: {
      description: 'oxlint',
      exec: { command: 'oxlint .' },
      cache: { inputs: { files: ['src/**', '.oxlintrc.json'] }, outputs: { files: [] } },
    },
    'format-check': {
      description: 'oxfmt --check',
      exec: { command: 'oxfmt --check .' },
      cache: { inputs: { files: ['src/**', '.oxfmtrc.json'] }, outputs: { files: [] } },
    },

    // Pure group task — `vx run ci` fans out, the group itself is
    // silent in the run output. `dependsOn` is typed against the task
    // names above: a name declared nowhere is a type error, not a
    // silent no-op.
    ci: {
      description: 'format-check + lint + test',
      dependsOn: ['format-check', 'lint', 'test'],
    },
  },
})
```

The rest of the task fields, in one config:

```ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    // Prompts on the terminal, so it runs alone and is never cached.
    'db:push': { exec: { command: 'drizzle-kit push', interactive: true } },
    // Talks to this machine's Docker daemon: never sent to a remote executor.
    'docker:build': { exec: { command: 'docker build -t app .', remote: false } },
    e2e: {
      exec: {
        command: 'playwright test',
        env: {
          define: { BASE_URL: 'http://localhost:3000' },
          passThrough: ['E2E_TOKEN'],
          secret: ['E2E_TOKEN'],
        },
        sandbox: {
          allow: {
            read: ['.'],
            write: ['test-results/'],
            localBinding: [3000],
            unixSockets: true,
            pty: true,
            gitConfig: false,
            systemInfo: ['hw.memsize'],
            machLookup: ['com.apple.SecurityServer'],
          },
          weakerNetworkIsolation: false,
          weakerWhenNested: false,
        },
      },
      cache: {
        inputs: {
          files: ['e2e/**'],
          runtime: ['npx playwright --version'],
          workspaceRuntime: ['node -v'],
        },
        outputs: { files: ['test-results/**'] },
      },
    },
  },
})
```

## Common patterns

### Sharing inputs across tasks

TypeScript composition is the mechanism (named-input schema machinery
was deliberately rejected — the language already does this). Plain TS
arrays:

```ts
import { defineProject } from '@vzn/vx/config'

const srcInputs = ['src/**', 'tsconfig.json']

export default defineProject({
  tasks: {
    build: {
      exec: { command: 'tsc' },
      cache: { inputs: { files: srcInputs }, outputs: { files: ['dist/**'] } },
    },
    test: {
      exec: { command: 'bun test' },
      cache: { inputs: { files: [...srcInputs, 'tests/**'] }, outputs: { files: [] } },
    },
  },
})
```

### Presets

A preset is a TypeScript function that returns a `TaskConfig`:

```ts
// presets/ts-build.ts
import type { TaskConfig } from '@vzn/vx/config'

export function tsBuild(opts?: { tsconfig?: string }): TaskConfig {
  return {
    description: 'compile TypeScript',
    exec: { command: `tsc -b ${opts?.tsconfig ?? ''}`.trim() },
    cache: {
      inputs: { files: ['src/**', opts?.tsconfig ?? 'tsconfig.json'] },
      outputs: { files: ['dist/**'] },
    },
  }
}
```

```ts
// packages/app/vx.config.ts
import { defineProject } from '@vzn/vx/config'
import { tsBuild } from '../../presets/ts-build.ts'

export default defineProject({
  tasks: {
    build: tsBuild(),
    test: {
      exec: { command: 'bun test' },
      dependsOn: ['build'],
      cache: { inputs: { files: ['src/**'] }, outputs: { files: [] } },
    },
  },
})
```

When the preset is consumed at config-load time, it should resolve
to `.ts` source — see
[`architecture.md` § Config-time imports](../architecture/#config-time-imports--the-bootstrap-problem)
for the bootstrap-cycle tradeoff.

### When to use `cache.inputs.tasks: []`

When a `dependsOn` exists for ordering only, and the upstream's
output doesn't influence this task's output. Common case: an
integration test that depends on a dev server starting up but whose
own inputs are just the test source.

```ts
e2e: {
  dependsOn: ['dev'],
  exec: { command: 'playwright test' },
  cache: {
    inputs: {
      files: ['e2e/**'],
      tasks: [],   // dev's hash does not affect e2e's cache identity
    },
    outputs: { files: ['playwright-report/**'] },
  },
}
```

### When to use `--no-cache` instead of removing `cache`

`--no-cache` is a runtime flag, not a config change. Reach for it
when:

- You suspect cache corruption and want a clean run.
- You're benchmarking and need fresh timings.
- You're forwarding one-off args and don't want to pollute the cache
  with a one-shot key (though note: forwarded args are already in
  the key, so they form their own entry anyway).

It applies to the whole run; per-task opt-out belongs in config (omit
the `cache` block).

## Schema validation errors

The loader (`src/workspace/project-loader.ts`) validates at load time
and surfaces `UserError` (clean output, no stack). Every field's
accepted values and exact refusal text are recorded in
`tests/contract/config-schema.json`, which a test regenerates from the
validator and compares, so a change to either is deliberate
(`design/versioning-1.0.md` § How the contract is held).

When the field a refusal names is in the file, the CLI prints the file
at its line and column, relative to the current directory (a terminal
opens it on click), and the lines up to it with a caret under the field
(`util/config-frame.ts`):

```
vx: packages/b/vx.config.ts:4:15: tasks.build.exec has unknown field "comand" (allowed: …) — did you mean command?

  2 |   tasks: {
  3 |     build: {
> 4 |       exec: { comand: 'mkdir -p dist' },
    |               ^
```

A field the file does not hold (a required one missing, or one a plugin
set) prints the one line as before. The table below lists the messages
a user meets most:

| Symptom                                                                                                                               | Cause                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `did not export a default object`                                                                                                     | Forgot `export default`, or exported a non-object; a function (Vite's `defineConfig(() => …)` shape) adds that it is one and to export what it returns (D-110).                                                                |
| `tasks must be an object keyed by task name`                                                                                          | `tasks` is not an object — an ARRAY included.                                                                                                                                                                                  |
| `<path> is <what> — a config must be JSON data, because the cache key folds its JSON`                                                 | A value JSON cannot carry, anywhere in the config: a function, a symbol, a bigint, `NaN` / `±Infinity`, `undefined` in an array, a cycle, a getter or an object that is not plain (`Date`, `Map`, `RegExp`, a class instance). |
| `<level> has unknown field "<key>"`                                                                                                   | Typo'd / unsupported key (see below).                                                                                                                                                                                          |
| `<level> has field "<key>", which vx <version> removed — use <replacement>`                                                           | A field an earlier release accepted (`exec.resources`, removed in 0.0.19). The message names what replaced it (`design/versioning-1.0.md` § Deprecation).                                                                      |
| `<level> must be an object (fields: <fields>), not an array`                                                                          | An array where an object goes — `outputs: ['dist/**']` (Turbo's spelling) is `outputs: { files: ['dist/**'] }`, and the message says so.                                                                                       |
| `cannot find '<name>' — no node_modules above the config provides it; install the workspace's dependencies first`                     | A bare import nothing installed serves — a fresh clone before its install, or a typo. Refused before the config is evaluated, so Bun never auto-installs it from the registry (it would, when no `node_modules` exists above). |
| `cannot find '<name>' — Yarn Plug'n'Play installed the workspace's dependencies into .pnp.cjs, which Bun does not read; set <remedy>` | The same, with a `.pnp.cjs` at or above the config: the install is there and Bun cannot read it, so the remedy is `nodeLinker: node-modules` in `.yarnrc.yml` and `yarn install` (D-109).                                      |
| `tasks.<name> must be an object`                                                                                                      | The task value is null / a string / etc.; a string (package.json's `name: 'command'`) adds the `{ exec: { command } }` it goes in.                                                                                             |
| `exec must be an object with a command string`                                                                                        | `exec` is malformed.                                                                                                                                                                                                           |
| `exec.command must be a non-empty string`                                                                                             | Forgot `command`, or an empty or whitespace-only string.                                                                                                                                                                       |
| `exec.command holds a NUL, which no command line can carry`                                                                           | A `\0` in the command (a template slip); the spawn refused it as exit 127, "not on this task's PATH", with the NUL printed as a space.                                                                                         |
| `exec.persistent must be an object (or omitted)`                                                                                      | Wrong shape.                                                                                                                                                                                                                   |
| `exec.persistent.readyWhen must be a string regex`                                                                                    | Non-string `readyWhen`.                                                                                                                                                                                                        |
| `exec.persistent.readyWhen is not a valid regex (<error>)`                                                                            | A `readyWhen` the runner could not compile (`(`); it failed the task as an internal error at run time.                                                                                                                         |
| `cache is not allowed on a persistent task`                                                                                           | persistent + cache combined.                                                                                                                                                                                                   |
| `exec.interactive must be a boolean (or omitted)`                                                                                     | Wrong shape.                                                                                                                                                                                                                   |
| `cache is not allowed on an interactive task`                                                                                         | interactive + cache combined: what it does depends on what is typed.                                                                                                                                                           |
| `sandbox is not allowed on an interactive task`                                                                                       | interactive + sandbox combined.                                                                                                                                                                                                |
| `persistent.readyWhen is not allowed on an interactive task`                                                                          | vx reads none of an interactive task's output.                                                                                                                                                                                 |
| `a task with no exec must declare dependsOn`                                                                                          | Group task with no edges.                                                                                                                                                                                                      |
| `a task with no exec writes nothing`                                                                                                  | Group task with `cache.outputs` that names a file.                                                                                                                                                                             |
| `dependsOn must be an array of strings`                                                                                               | Wrong shape.                                                                                                                                                                                                                   |
| `cache.inputs is required when cache is set`                                                                                          | Forgot `inputs`.                                                                                                                                                                                                               |
| `cache.inputs must be an object`                                                                                                      | Present but not an object: a string (`outputs: 'dist'`). An array is the row above.                                                                                                                                            |
| `cache.inputs.files must be an array`                                                                                                 | Wrong shape.                                                                                                                                                                                                                   |
| `cache.inputs.runtime must be an array of non-empty shell command strings with no NUL`                                                | Non-string / blank entry (whitespace alone runs as a no-op), or one holding a NUL.                                                                                                                                             |
| `cache.inputs.workspaceRuntime must be an array of non-empty shell command strings with no NUL`                                       | Non-string / blank entry (whitespace alone runs as a no-op), or one holding a NUL.                                                                                                                                             |
| `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.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.                                                                                                                                                                                     |
| `cache.inputs.files: "<file>" is taken back by "!<glob>"`                                                                             | A literal input a `!` entry covers: the negation subtracts wherever it sits, so the file never entered the key.                                                                                                                |
| `cache.outputs.files: every entry is a negation, which selects NOTHING`                                                               | Only `!` globs: a `!` entry only takes back what a positive glob selected (A-44).                                                                                                                                              |
| `cache.outputs.files: "<glob>" covers the project's own <file>`                                                                       | An output glob that matches the project's `package.json` or its own `vx.config.*` (`**`, `*.json`): the clean before a run would delete them. A `!` entry that takes the file back (`!package.json`) lets it load.             |
| `cache.outputs.files: "<glob>" is under workspace-outputs/`                                                                           | A project output named into the artifact's namespace for `outputs.workspaceFiles`: every hit read it back as a workspace output.                                                                                               |
| `cache.inputs.files: '!!' is not a double negation`                                                                                   | `!!x` inverts the set — it folds only `x`.                                                                                                                                                                                     |
| `exec.timeout: <n> ms exceeds the maximum timer delay`                                                                                | Past 2^31-1 ms a timer fires at once, not never.                                                                                                                                                                               |
| `description must be a string`                                                                                                        | Non-string description.                                                                                                                                                                                                        |
| `tag "<tag>" <why> — --filter tag:<name> could not name it`                                                                           | A tag with surrounding whitespace or a `*`, or one ending in `...` or `[<ref>]`, which a filter reads as a pattern, a dependency walk or a git range.                                                                          |

**Unknown fields are rejected**, not ignored, at every object level —
the project's top level (`tasks`), the task itself, `exec`, `exec.env`,
`exec.persistent`, `exec.sandbox` and its `allow` /
`deny` / `ignore` blocks, `cache`, `cache.inputs`, and `cache.outputs`
(`tests/schema-unknown-keys.test.ts` walks every one) — and at the top
of `vx.workspace.ts`,
where `plugin:` (singular) would otherwise declare no plugins and run
the workspace bare. A silently-dropped
`workspaceFile` (singular) or `timeoutMs` would make the task hash as
though the field had never been written, so vx would replay an artifact
built from different inputs; a silently-dropped `env: { set: … }` would
run the task without the variables it was written to have. The error
names the offending key, lists what that level accepts, and adds the
nearest accepted spelling when one is within two edits:
`tasks.build.exec.env has unknown field "passthrough" (allowed: define,
passThrough, secret) — did you mean passThrough?`. A field another runner spells
on the task names vx's home for it instead (D-37): Turbo's `outputs`,
`inputs`, `env`, `passThroughEnv`, `persistent`, `outputLogs`, `interactive`
(`exec.interactive`) and `with`, Nx's target `executor`, `options`, `continuous` (D-49), `cwd`,
`parallelism` and `configurations` (D-89), and a `command`
(`cmd`, `script`) on the task or `cmd` on `exec`, and on `exec` Nx
run-commands' `cwd`, `args`, `commands`, `parallel` and `shell`
(D-100), and in a `cache` block wireit's `files` / `output`,
`env`, `dependencies`, `enabled`, and `globs` / `include` / `patterns` /
`exclude` / `ignore` under `inputs` or `outputs` (D-118). So `outputs` on a task
ends `— vx spells it cache.outputs.files` in code quotes. A `cache` that
is no object (Turbo's `cache: false`) and a `persistent` that is none
(`true`) name the shape to write.

Workspace-discovery errors (`src/workspace/workspace.ts`):

| Symptom                                                                                                      | Cause                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `failed to parse <file>: <why>`                                                                              | A `package.json` / `pnpm-workspace.yaml` is not valid.                                                                                                                                                                                                     |
| `<file>: packages must be an array of glob strings`                                                          | `pnpm-workspace.yaml` `packages:` is a bare string, etc.                                                                                                                                                                                                   |
| `<file>: must be a JSON object`                                                                              | A `package.json` (the root's or a member's) is `null`, a list or a scalar; it crashed with a TypeError until item 988.                                                                                                                                     |
| `<file>: "name" must be a string with no surrounding whitespace`                                             | A `package.json` `name` is a number, an object, or has surrounding whitespace (npm refuses one too); `{"name":123}` planned `123#build` until item 988.                                                                                                    |
| `<file>: "name" cannot hold "#" — vx addresses a task as <name>#<task>`                                      | A `package.json` `name` holds `#` (npm refuses one too): `{"name":"a#b"}` planned `a#b#build` under `--all`, but `vx run a#b#build` and a `dependsOn` split at the first `#` and found nothing.                                                            |
| `<file>: must be a mapping (packages: and pnpm's settings)`                                                  | `pnpm-workspace.yaml` is a list or a scalar. A mapping with no `packages:`, or an empty one (pnpm 10 settings or catalogs in a single-package repo) is not an error: the root's `package.json` decides, as without the file (item 984).                    |
| `<file>: workspaces must be an array of glob strings`                                                        | `package.json` `workspaces` holds a non-string entry.                                                                                                                                                                                                      |
| `workspace member <dir> (<abs>) is outside the workspace root <root>: vx keeps every project under the root` | A member glob (`../ext/*`, an absolute path) reached a package outside the root. npm and pnpm take one; `--affected` asks git from the root and missed edits there. Move the root up to a directory that holds every member.                               |
| `<file>: workspaces.packages must be an array of glob strings`                                               | The yarn-legacy `workspaces: { packages: [...] }` form holds a non-string entry.                                                                                                                                                                           |
| `<file>: <field> entry "<glob>" is an extglob, which vx's glob engine does not read`                         | A member glob holds `!(…)`, `@(…)`, `+(…)`, `*(…)` or `?(…)`. `Bun.Glob` has no extglob (its scan widened `packages/!(x)` to include x, turborepo#3766); a whole-segment `!(a\|b)` gets its exact rewrite, `["packages/*", "!packages/a", "!packages/b"]`. |

Workspace-config errors:

| Symptom                                                                                                                                                                        | Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `concurrency must be a positive integer`                                                                                                                                       | `concurrency` is negative, zero, NaN, ...                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `timeout must be a positive integer (milliseconds)`                                                                                                                            | Workspace `timeout` is ≤ 0, NaN, or not an int.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `cacheDir must be a string`                                                                                                                                                    | Wrong shape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `cacheDir is only whitespace — name a directory`                                                                                                                               | A `cacheDir` of spaces: it made a directory named so at the root, hidden by the cache's own `.gitignore`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `cacheDir holds a NUL, which no path can carry`                                                                                                                                | No path can hold a NUL; the cache directory's creation failed and blamed the workspace's permissions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `cacheRetention must be { olderThan?: '30d', maxSize?: '10G' }`                                                                                                                | Not an object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `cacheRetention names neither olderThan nor maxSize`                                                                                                                           | An empty policy would evict nothing and read as one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `cacheRetention.olderThan must be a duration like '30d', '12h', '90m' or '45s'`                                                                                                | The `vx cache prune --older-than` spelling, or not a string.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `cacheRetention.maxSize must be a size like '10G', '500MB' or '64KB'`                                                                                                          | The `vx cache prune --max-size` spelling (no fractions), or not a string.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `cacheRetention.olderThan of 0 evicts every entry after every run`                                                                                                             | Every run would evict what it just saved; `vx cache prune --older-than 0` is refused too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `cacheRetention.maxSize of 0 evicts every entry after every run`                                                                                                               | The same, for the size bound.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `cacheRetention.maxSize '<n>' reads as <n> bytes — give a unit (e.g. '<n>M', '<n>G')`                                                                                          | A bare number is bytes; a cache capped at `10` bytes is a typo for `10G`. `10B` still loads.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `affectedBase must be a git ref like 'origin/main'`                                                                                                                            | Not a string, empty, holding whitespace or a NUL, or opening with `-` (git would read an option).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `cacheScope must be 'trusted', 'read-only', or a scope name of <rule>`                                                                                                         | Not a string, or a scope name holding a character outside letters, digits and `. _ - / @`, or longer than 128.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `rules must be { exclusiveOutputs?: boolean; upfrontKeys?: boolean }`                                                                                                          | Not an object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `rules.<name> must be true or false`                                                                                                                                           | A rule set to something other than a boolean (`'off'`, `0`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `plugins must be an array of plugin objects`                                                                                                                                   | Wrong shape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `plugins[<i>] must be an object`                                                                                                                                               | A non-object entry in `plugins`; a string (Nx's `'@nx/vite/plugin'`) adds that a plugin is what its package's function returns, not a module name (D-49).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `plugins[<i>] must come from definePlugin(import.meta, { … })`                                                                                                                 | A plain object where a plugin was expected: a plugin's name is its package name, and only `definePlugin` sets it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `plugins[<i>] is a Promise — await the factory that returns the plugin`                                                                                                        | An async plugin factory called without `await` (`plugins: [later()]`); the refusal said the plugin did not come from `definePlugin` (D-159).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `plugins[<i>].name overrides the package name`                                                                                                                                 | A `name` set over `definePlugin`'s result; drop the field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `plugins[<i>].<capability> of plugin '<name>' must be a function`                                                                                                              | A capability key holding something that is not callable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `plugins[<i>] (plugin '<name>') must contribute at least one of config/discover/project/graph/key/fingerprint/schedule/admit/executor/cache/telemetry/setup/commands/teardown` | A plugin object with no capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `plugin '<name>' declares '<key>', which is no plugin hook`                                                                                                                    | A key on a plugin that names no hook (`excutor`, `setUp`): it was never called. The nearest hook is hinted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `<file> has unknown field "<key>"`                                                                                                                                             | Typo'd / unsupported top-level key (`plugin`); the hint names the nearest spelling, or where vx keeps a Turbo or Nx key (`pipeline`, `remoteCache`, `parallel`, `cacheDirectory`, `defaultBase`, `tasksRunnerOptions`, `globalPassThroughEnv`; D-38, D-49; pnpm-workspace.yaml's, Lerna's and package.json's `packages`, `workspaces`, `catalog`, `npmClient`, and `ignore`, `cache`, `remote`, `env`, D-98; in a project's vx.config, `targets`, `extends`, `implicitDependencies` and `name`, D-56; `scripts`, `pipeline`, `namedInputs`, `root`, `sourceRoot`, `projectType`, and a task's `dependsOn`, `cache`, `exec`, `inputs`, `outputs`, `env` one level too high, D-99). |
| `plugin '<name>' declares command '<verb>', a core verb — core verbs cannot be shadowed`                                                                                       | A plugin verb the dispatcher matches first; it could never run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `plugin '<name>' declares command '<verb>', which is not a word — a verb is a letter or digit, then letters, digits, ':', '.', '_' or '-'`                                     | A verb like `--version`, `''` or `a b`: core reads a flag first, an empty word is no verb, and `vx completions` writes verbs unquoted into a shell script.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `plugins '<a>' and '<b>' both declare command '<verb>' — a verb has one owner`                                                                                                 | Two packages on one verb; the first would win and hide the second. Plugins of one package are one owner, and the first declared runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `plugins[<i>].fingerprint of plugin '<name>' must be { files: [name, …], affected: function }`                                                                                 | A fingerprint claim without its file list or its `affected` answer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `plugin '<name>' claims fingerprint file "<file>", which is not a file name at the workspace root`                                                                             | A claim names a path, or no name: a claim is a bare file at the root (`vx watch`'s root arm is not recursive).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `plugins '<a>' and '<b>' both claim fingerprint file '<file>' — a file has one claimant`                                                                                       | Two plugins keying the same lockfile; the key would fold both and `--affected` could ask only one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `plugin '<name>' claims fingerprint file '<file>' twice (plugins[<i>] and plugins[<j>]) — a file has one claimant; declare the plugin once`                                    | One plugin package declared twice (`plugins: [bun(), bun()]`); the message named it as two plugins (D-158).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

---

# Security model

> What vx trusts, what it checks, what the sandbox stops and what it does

What vx trusts, what it checks, what the sandbox stops and what it does
not, and how to report a problem. Report a vulnerability privately
through GitHub's private vulnerability reporting on
[vznjs/vx](https://github.com/vznjs/vx/security) (Security → Report a
vulnerability), never in a public issue.

## What vx trusts

- **Your configs.** `vx.config.ts` and `vx.workspace.ts` are programs vx
  runs in its own process. A config can do anything you can: vx
  validates what it returns, not what it does. What a config imports
  must already be installed: vx runs Bun with `--no-install`, so an
  import no `node_modules` provides is refused, never fetched from the
  registry (L-22).
- **Your plugins.** A plugin is code you imported. It runs in vx's
  process with a config's reach; vx checks the shape of what it hands
  back and isolates a telemetry plugin's failures, nothing more.
- **Your lockfile and your repo.** vx parses a lockfile (and
  `turbo.json` or an Nx graph when migrating) into keys and refuses one
  it cannot read, naming the file. A lockfile that names another
  install is a different key, never a code path.
- **Whoever can write your remote cache.** A cache key names the
  inputs, not the bytes, so a store that answers a key with bytes of its
  choosing is trusted as a writer, as it is in every action cache. Use a
  store only your builds write to, or `turboCache()`'s signature key,
  which refuses an artifact a keyholder did not sign. A job you do not
  trust (a fork's pull request) reads at most: `--cache=local:rw,remote:r`,
  or the tools' own `TURBO_REMOTE_CACHE_READ_ONLY`, `TURBO_CACHE` and
  `NX_SKIP_REMOTE_CACHE`, which the cache plugins honour (L-34).

## Cache poisoning

A pull request that can write the cache the default branch reads can
plant bytes main later replays (CREEP, CVE-2025-36852). The boundary is
the credential, enforced by the cache server: the default branch's job
holds a token that writes the trusted keys, and a pull request's job
holds one that cannot (read-only, or confined by the server to its own
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.
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
key.

A boundary the server holds, with bazel-remote and `@vzn/vx-reapi`: reads
are open, writes need a password, and only main's push job has it.

```sh
htpasswd -cB /etc/bazel-remote/htpasswd ci   # the write credential
bazel-remote --dir /data --max_size 50 --grpc_address 0.0.0.0:9092 \
  --htpasswd_file /etc/bazel-remote/htpasswd --allow_unauthenticated_reads
```

```ts
// vx.workspace.ts: the header only where the secret is set
reapi({
  endpoint: 'grpcs://cache.example.com:9092',
  headers: process.env.CACHE_AUTH ? { authorization: `Basic ${process.env.CACHE_AUTH}` } : {},
})
```

```yaml
# .github/workflows/ci.yml: CACHE_AUTH (base64 of ci:<password>) is a
# secret of the `cache-write` environment, whose only deployment branch
# is main, so no other branch's workflow can read it
jobs:
  build:
    if: github.event_name != 'push' || github.ref != 'refs/heads/main'
    steps:
      - run: vx run build --all
  build-main:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    environment: cache-write
    env:
      CACHE_AUTH: ${{ secrets.CACHE_AUTH }}
    steps:
      - run: vx run build --all
```

A pull request's job has no `CACHE_AUTH`, so the server refuses its
writes whatever its config says. Never give the write secret to a
`pull_request_target`, `issue_comment` or `workflow_run` job that checks
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.

## What vx checks on bytes it did not write

Every artifact that arrives from a remote, and every one read back from
the local store:

- ends in a CRC-32 of its entries: a byte changed in transit or at rest
  makes the hit a miss, never a replay of the damaged bytes;
- on arrival, records the cache key it was packed under, and is
  refused under another (a local read-back is not re-checked);
- on arrival, carries only the files the task declares as outputs;
- lands each file under the task's project or declared workspace path:
  traversal (`..`, `.`, absolute names) is refused before anything
  lands, a refused archive leaves nothing behind, and links and devices
  are never written; a seeded fuzz of hostile archives holds this;
- is bounded: a decompression bomb, an oversized header or body, and a
  remote answer larger than asked for are refused as they are read.

Remote execution (`@vzn/vx-reapi`) holds each blob to its digest, and
writes only the server's outputs a declared glob names, inside the
workspace, through no link that leads out of it.

## What the sandbox stops

A task with `exec.sandbox` runs where only what it declares exists:

- reads of the workspace outside the task's project and grants fail;
- writes outside its `allow.write` grants fail (declared outputs grant
  none);
- the network is closed except to the domains granted, one union per
  run: a task granted any domain reaches every domain the run grants;
  with none, it reaches no listener on the host's loopback and no unix
  socket outside the workspace (L-46);
- its temp directory, port-bridge socket and trace log are its own
  (mode 0700), unreachable from another task and another local user;
- the host's credential stores (`~/.ssh`, `~/.gnupg`, `~/.aws`,
  `~/.npmrc`, `~/.netrc` and the like; the list is in the schema's
  sandbox section) are unreadable unless `allow.read` names one (L-41);
- vx's own cache directory, wherever `cacheDir` puts it in the
  workspace, is a wall like `.vx`: a broad grant stops at it, and a write
  grant that would bind it is refused (L-24);
- a symlinked output must resolve inside its project: vx packs outputs
  outside the sandbox, and a link to another project's file would have
  carried that file into the cache (L-23). An output directory linked out
  of the project refuses the task by name (X-88).

An undeclared touch of the task's own files fails the task, and a failed
task is never cached. See [Sandboxing tasks](https://vznjs.github.io/vx/guides/sandboxing/).

## What it does not stop

- **A task with no `exec.sandbox`.** It runs with your permissions.
- **Reads outside the workspace root.** `~/.cache`, `/etc` and the like
  stay readable (tools need them) and fold into no key. The credential
  stores under home (`~/.ssh`, `~/.aws`, `~/.npmrc` and the like) are
  not: a task reads one only when its `allow.read` names it (L-41).
- **Resource use.** CPU, memory and disk are bounded by timeouts and the
  artifact ceiling, not by the sandbox.
- **A weaker sandbox where the host cannot nest one**:
  `weakerWhenNested` in a container, a task that itself sandboxes on
  macOS. `vx info` says what the host supports.

## Agents (`vx mcp`)

An agent connected to `vx mcp` can do what `vx run` can do, nothing more.
Every tool but `runTasks` only reads. `runTasks` runs `vx run --format json`
as a child process: the agent names tasks and sets `all`, `force`,
`filter` and `affected`, and nothing else. A task name that starts with
`-` is refused, a filter goes as one `--filter=` value, and a ref reaches
git after `--end-of-options`, so no argument becomes a flag. The commands
that run are the ones your configs declare, from the workspace root, with
the environment `vx mcp` started with, filtered by each task's `exec.env`
and held by its `exec.sandbox`. `force` costs a rerun, not a wrong entry:
the key stays the same. What reaches the agent (summaries, refusals,
`getFailures` output) is masked as described under Secrets.
`mcp({ run: false })` takes `runTasks` away, and `mcp({ run: ['test'] })`
limits it to those task names. An agent that
can edit `vx.config.ts` can run anything, as you can, because configs are
code vx trusts.

## Secrets

The value, of 6 characters or more, of a variable whose name holds
`TOKEN`, `SECRET`, `KEY`, `PASSWORD`, `PASSWD` or `CREDENTIAL` (not one
ending `_FILE`, `_PATH` or `_DIR`, nor `GIT_CONFIG_KEY_<n>`), or that a
task lists in `exec.env.secret`, and the password of a URL
(`scheme://user:<password>@`) in any variable's value, is printed as `***` wherever vx shows, stores or
exports it: task output, the stdout a hit replays, commands, an
executor's error, telemetry,
`vx show` and `vx mcp`'s `listTasks` (L-26). Values in the run history are digests under a per-store
salt, and what follows `--` on the command line reaches telemetry as a
count, not a quote, a secret before it masked (L-44). A remote executor (`@vzn/vx-reapi`) receives a
task's `exec.env.define` values and the `cache.inputs.env` values its
local child gets, never `passThrough`; those values sit unmasked in the
action's Command, which the remote stores in its CAS, as Bazel's
`--action_env` does, so a secret a remote task needs is trusted to that
remote. `vx lock` refuses to write a lock holding a secret value: the lock is
committed (L-42).

Masking covers the text vx shows and stores, not a task's outputs: they
are cached and uploaded as the task wrote them, so a build that bakes a
secret into a file (a server bundle reading `process.env.API_KEY`) hands
it to every reader of the remote cache. Keep secrets out of cached
outputs, or give that task no `cache`. vx does not scan outputs for
secret values: a name-based match would refuse public `*_KEY` values too.

## Releases

Release binaries carry a build-provenance attestation
(`gh attestation verify vx-<target> --repo vznjs/vx`); `vx upgrade`
checks each download's SHA-256 before it replaces anything and stages it in a fresh directory, never a name another user could plant a link at, which proves
the bytes arrived intact, not who built them: the digest comes from the
release that serves the asset, and no signature is checked (owner,
2026-10-03: no release signing key for now); npm packages
publish with provenance; every third-party action in CI runs from a
full commit SHA; and a workflow hands an event's or a dispatcher's value
to a script through `env`, never pasted in (a release tag is checked as a
version first); every workflow names its token's permissions, and CI's
is read-only. A test holds each rule.