vx | Blog

What vx is, and what it refuses to be

Thu, 10 Sep 2026 23:59:00 GMT

Every monorepo tool eventually describes itself with a paragraph of nouns: caching, task graph, remote execution, affected detection, generators, a dashboard, a cloud. vx’s description is one sentence.

vx runs and caches a task graph, correctly, and stops there.

That sentence is a design, not a slogan, and this post walks through what it commits us to.

The pipeline

A run is a pipeline with five stages, and each one has a documented seam a plugin can fill:

Discover the projects in the workspace (the package manager’s workspace globs, one package.json each).
Evaluate each vx.config.ts. Configs are TypeScript programs, not JSON; the pipeline sees the object they evaluate to.
Build one task graph across the whole workspace from dependsOn and the package dependency graph.
Derive a content-addressed key per task from its declared inputs, its resolved config, and the keys of everything upstream.
Schedule the graph: look each key up, restore hits, execute misses with bounded parallelism, save results.

In plugin terms the stages are named config → project → graph → key → fingerprint → schedule → admit, followed by the two behaviour capabilities executor (where a command runs) and cache (where artifacts live), the observe-only telemetry capability, setup and teardown around the run, and commands (CLI verbs). Core applies no plugin by default and names none. A workspace with no vx.workspace.ts still runs and caches, because the local executor and the local cache are the floor under every list, not plugins you have to remember to add.

What a task is

A task is one shell command with declared inputs and outputs:

build: {
  exec: { command: 'tsc -b' },
  cache: {
    inputs: { files: ['src/**', 'tsconfig.json'] },
    outputs: { files: ['dist/**'] },
  },
}

Three rules hold across the whole tool:

Caching is opt-in. No cache block, no cache. When there is one, both inputs and outputs are required. vx never infers what a task reads.
One command per task. A plugin may change where the command runs, never what it is. Chain with && or split into tasks wired by dependsOn so each step caches on its own.
Project boundaries are hard. A glob never crosses into another project’s directory. What one project needs from another arrives through the graph, as an upstream task’s outputs.

What is not inside

The list below is not a roadmap gap. It is a boundary, and it is in the repository’s memory file so nobody re-proposes it by accident:

No cloud, no account, no dashboard. vx does not know your organisation exists.
No daemon. Every run pays its own discovery and still answers a fully cached 3,270-task graph in about half a second.
No auto-inferred inputs. A traced read set describes what a task read once, on one machine, after the fact. A key is needed before the task runs. You declare inputs, and the sandbox lets you enforce the declaration.
No JavaScript-function tasks. The shell is the API. Your tools stay yours.
No named inputs, no global inputs, no global env. Configs are TypeScript. A shared preset is an import and a spread.
Nothing distributed in the core repository. Remote caches, remote execution, telemetry sinks, agent protocols, GitHub summaries are all plugins in their own packages. @vzn/vx-reapi (Bazel Remote Execution API) is the proof the seams are wide enough to build those on.

Why the boundary matters

A tool that owns the cloud has an incentive to make the local path merely adequate. A tool that owns nothing but the graph has one job: be correct and be fast on the machine in front of you. Everything that follows in this series is a consequence of that job. The next post is about the fast part.

Where to look next: the Quickstart, the Architecture page, and the comparison with Turborepo, Nx and vite-task.

Why vx is fast: five decisions, not a trick

Thu, 10 Sep 2026 23:58:00 GMT

The headline number is the one you pay on every uncached build: what the runner adds on top of your tasks. On a synthetic workspace of 1,090 packages and 3,270 tasks whose ideal schedule is 3m 38s, vx finishes the cold build in 3m 46s, eight seconds over the schedule. Turborepo finishes in 5m 13s (a minute and a half over) and Nx in 34m 44s (half an hour over). Warm, a fully cached vx run build test --all finishes in 510ms, Turborepo in 760ms and Nx in 3.59s; the cold build burns 35 s of CPU in vx, 73 s in Turborepo and 114 minutes in Nx. On a real Turbo repository (solidjs/solid) the warm restore is 66 ms against Turbo’s 127 ms.

None of that comes from a microbenchmark trick. It comes from five decisions, and every one of them is also a reason to trust the cache more, not less.

1. The cache key is already in git’s index

A content-addressed key needs a hash of every input file. Most tools read each file and hash it, or keep a daemon around so they do not have to. vx spawns one git ls-files -s, which returns the file list and every clean file’s blob object id, and one concurrent git status to prune anything that diverges from the index. Clean-tree key derivation costs zero file reads, zero stats and zero database lookups.

Dirty files get the identical blob id computed in-process, so a key never flips when you commit. That class of spurious miss, “I committed and everything rebuilt”, does not exist here.

There is a whole post on this: Your cache key is already in git’s index.

2. Bitsets where others walk

Scheduling priority and the package graph are computed over packed bitsets with popcount instead of set-union depth-first search. On the 3,270-task graph that turned an 8.5 s priority computation into single-digit milliseconds. The scheduler tick 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, and the run costs one pass over the edges plus an O(log N) heap operation per task.

3. Strict output ownership makes restore cheap

Declared outputs are wiped before a miss executes and before a hit restores, so the tree after either is exactly the cached snapshot. That is a correctness rule first (no stale dist/old.js survives), but it also means vx knows what the tree looks like after a hit. On a warm-on-warm run it verifies the recorded (size, mode, mtime, inode, ctime) of each output with a stat and writes nothing, decompresses nothing. A restore onto a current tree costs about what an untouched tree costs.

4. One artifact format end to end

A cache entry is one tar.zst archive plus a SQLite row. Metadata and the captured stdout live in the row, so a hit is one indexed SELECT and a replay from the row, not a decompression. The same bytes go over the wire to a remote cache; nothing is repacked at the boundary. Packing is in-process (vx’s own streaming tar), the publish is an atomic rename, and each save is a single transaction.

5. Nothing runs when nothing is needed

vx has no daemon, so there is no process to keep warm and no staleness window between what the daemon believes and what the disk holds. What replaces the daemon is a set of zero-cost gates: no telemetry plugin means no event-bus subscriber, no summary, no git spawn for provenance; a plugin that declines a task costs nothing; a config that passes the purity gate is served from an evaluation cache keyed on the git blob ids of its whole import closure, and a config that reads the environment or the clock is simply evaluated live.

The method behind the numbers

Every change to the warm path in this repository ships with a number, measured the same way: A/B arms interleaved, min-of-N, the “before” arm checked out into an immutable git worktree, one workspace copy per arm pre-warmed by that arm. A change without a number is not done. The history of where the headroom went is in Benchmarks, and the full catalogue of decisions, each with its invariant and its source file, is in Optimizations.

There was no choice on the market

Thu, 10 Sep 2026 23:57:00 GMT

vx exists because of a gap, and the gap is easiest to describe by what sits on either side of it.

Turborepo: fast, and it stops

Turborepo got the important thing right. One turbo.json, a content-addressed cache, dependsOn micro-syntax that reads the way you think, a --filter DSL borrowed from pnpm. It is quick on a warm cache and it stays out of the way.

It also stops. Everything beyond “run it here and cache it in Vercel’s remote cache” is either absent or marked experimental. There is no remote execution and no seam to add one. There is no way to change where a task runs. The config is JSON, so a shared input list is a globalDependencies array you keep in sync by hand, and nothing computed can participate in a key. Inputs default to every file in the package, which turns a README edit into a rebuild and makes the per-task overhead visible in the solidjs/solid benchmark. Outputs are restored additively, so a deleted file survives a cache hit. And the parts that would have grown into a platform are being deprecated rather than finished: the daemon, --parallel, --no-cache, --remote-only are all deprecated in 2.10, and the flag surface is the largest of any tool in this space.

Turborepo is the right tool until the repository is large enough or the team needs something it cannot do, and then there is no next step inside it.

Nx: scales, and it is a product

Nx got the other important thing right. It has a project graph that scales, affected that works, and a plugin model that reaches into Rust, .NET, Java and Gradle. The company behind it is serious about large repositories.

It is also a product, and the runner is the part of the product that gets you to the rest. The features that make a large monorepo bearable, distributed task execution, remote cache, flaky-test detection, the graph visualiser, the analytics, are Nx Cloud, paid and walled. The open-source runner carries a daemon that is on by default, a heavy schema (project.json, nx.json, namedInputs, targetDefaults, executors wrapping every tool behind a JSON options object), and a cold-run cost that is not in the same league: on the same 3,270-task workspace, Nx’s cold build burns 114 minutes of CPU where Turborepo burns 73 seconds and vx 35. A fully cached run takes 3.59s against Turborepo’s 760ms, with the daemon running.

Nx is the right tool if you want the platform. If you want the runner, you pay for the platform’s weight and are steered toward its price.

The gap

Between them is the thing a large JavaScript monorepo actually needs:

a runner as small and as fast as Turborepo’s, on the warm path and the cold one;
a key that is correct in the cases Turbo’s is not: computed config, strict outputs, no spurious miss at a commit;
seams for the things Nx sells, remote execution, remote cache, task scheduling, telemetry, so that they can be built by anyone, on any wire, without the runner having an opinion about who provides them;
no daemon, no account, no cloud, no dashboard, nothing that needs a business model to keep working.

Nobody was building that, for a reason that is not technical: the seams are where the money is. A runner whose remote execution is a plugin on a public API is a runner nobody can sell a cloud for. vx is built that way on purpose and ships nothing distributed in its own repository. @vzn/vx-reapi, which does remote cache and remote execution against any Bazel Remote Execution API server, exists to prove the seams are wide enough for someone else to build the platform, and to make sure no one has to.

The bar

vx has to clear the same bar as both of them, and the way to know is to run their tests. The parity suite in the repository takes the behaviours a Turborepo or Nx user would reach for, spells each one in vx, and pins it with a test that runs the real CLI. Where vx diverges on purpose (bare task names never widen an anchored pkg#task’s scope; there is no --parallel because dependsOn is explicit) the divergence is documented as such. The matrix is Compared to Turborepo, Nx, vite-task, and every claim in it cites a file in the upstream repository so it can be re-verified as they change.

That is what “no choice on the market” meant: not that the others are bad, but that they are each half of the tool, and the halves do not combine. vx is the whole runner and nothing else.

Performance, modularity, extensibility. In that order.

Thu, 10 Sep 2026 23:56:00 GMT

Most projects have values in the sense of a paragraph on the README. vx has them in the sense of a tie-breaker: when two designs are both reasonable, the one that scores higher on the earlier driver wins, and the decision is not reopened. The drivers, in order:

Performance. Measured, not asserted.
Modularity. Each module’s index.ts is its contract; cross-module imports go through it and a test enforces that.
Extensibility. A seam for every stage; a plugin for everything distributed.

The order matters because it says what loses. A seam that costs a millisecond on the warm path when no plugin fills it is not added; the zero-cost gate is added first. A module boundary that would force a copy of a hot loop is redrawn rather than crossed.

The nine principles

Perf first. Measure before and after. A/B arms interleaved, min-of-N, the “before” arm in an immutable git worktree, one workspace copy per arm pre-warmed by that arm. A change to the warm path without a number is not done. This has killed features that felt obviously good: lookahead scheduling was measured against the plain critical-path priority and lost, so it is on the rejected list.

Explicit over magical. Caching is opt-in; cache.inputs.files is required; nothing is inferred. The sandbox is how a task proves what it touches. The argument is that an under-declared input is the worst failure a cache can have, and inference produces exactly that kind.

One command per task; the shell is the API. A plugin changes where a command runs, never what it is. There are no JavaScript-function tasks and no executors wrapping tools behind options objects. Your tools stay yours and their documentation stays correct.

Resolved-config hashing. The key sees the evaluated config object, so imports, presets and computed values participate. Named inputs and global inputs are rejected because a TypeScript config composes without them.

Cascade through deps by folding upstream input keys, never outputs. Every key is knowable before anything runs, which is what --dry, remote prefetch, the restore tier and remote execution all stand on. Early cutoff was tried and reverted.

Project boundaries are hard. A glob never crosses into another project. What a project needs from another arrives through the graph.

No defaults. Core names no plugin. Only the local floor is implicit. A capability a plugin must supply is declared in vx.workspace.ts or it does not exist. This is the principle that keeps vx from quietly becoming a product: there is no built-in remote anything to grow a business model around.

Seam over special case. When core grows a branch for one consumer, the seam is too narrow. vx migrate and the history-based scheduler both left core for their own packages once the seam they needed existed.

Once per run. Within a run, nothing outside vx changes the files it reads, so each fact is learned once: a file read once, a path looked up once, a process asked once. Only vx’s own writes, or its tasks’ runs, make it ask again. A test traces a run and fails on a repeat that has no written reason.

The rejected list

Some things are written down so they are not re-proposed by the next person with a good afternoon: named inputs and global env; auto-input inference via tracing; folding NODE_OPTIONS into the key; lookahead and idle-insertion scheduling; a first-party platform, dashboard, agents or cloud; Turbo’s remote-cache wire in core; HTTP/3. Each was either measured and lost, or conflicts with a principle above. The list lives in the repository’s own memory file, next to the principles, where a contributor reads it before writing code.

Rules learned the hard way

The values above are the design. These are the scars, kept as rules:

Repro before fix, and record what a probe refutes too.
Every fix must fail without itself. A test that passes with the fix reverted is not a test of the fix.
A skip is a silent pass. Gate on an env var CI sets.
Assert the exact expected set, not the absence of one string.
A comment claiming a guarantee the code lacks is a defect: de-claim or implement.
A timed wait in a test is a claim about time; prove it with the shortest window that still fails without the fix.
A feature is not done until its docs land in the same commit.

None of that is unusual advice. What is unusual is that it is enforced in the repository the way a lint rule is, and that the tool’s own test suite is run by the tool, under its own sandbox, on every commit.

Your cache key is already in git's index

Thu, 10 Sep 2026 23:55:00 GMT

A content-addressed cache stands or falls on one question: how cheaply can you compute the key, and how sure are you that the key captures everything that matters? This post is about the first half. The next few are about the second.

Twelve parts, one chain

A vx cache key is an xxh3 hash, seed-chained across twelve parts: each part folds into the running digest under its own label (task:, workspace:, config:, upstream:, inputs:, …), and every list of pairs folds its length first and delimits name from value with a \0, so no two layouts of the same bytes can collide by concatenation. The parts, as Caching numbers them:

The key-derivation sentinel (CACHE_VERSION), so a change to how keys are derived can never be served by an entry from before it.
The task id, project#task.
The workspace fingerprint: every supported workspace-level file at the root (lockfiles, pnpm-workspace.yaml), hashed once per run.
The project’s own package.json bytes. A dependency bump re-keys the project it belongs to.
The resolved task config, the evaluated object, not the source text (its own post).
Arguments forwarded after --.
The resolved values of the env vars in cache.inputs.env.
The output of each cache.inputs.runtime command (node --version, say), resolved live at hash time.
The same for workspaceRuntime, resolved once per run.
Every upstream task’s cache key, filtered to the ones the graph says this task depends on (cascade post).
Any material a plugin’s key stage contributes — folded right after the upstream keys and BEFORE the input files, and only when a plugin returned any, so a workspace with no key plugin derives the keys it derived before the stage existed.
The content hashes of every file cache.inputs.files resolves to.

Part 12 is where the money is. A build task in a real package resolves to hundreds of files, and a workspace has hundreds of packages.

Ask git, once

Git already stores a content hash for every tracked file: the blob object id in the index. vx runs one git ls-files -s -v for the whole workspace — the index only, no walk — and gets every tracked path, its blob id and its cache-state flag in a single stream. A concurrent git status --porcelain -uall is the one command that walks the worktree, and it answers two questions at once: which tracked files differ from the index, and what is untracked.

An index id is trusted only where git stores the worktree bytes verbatim, so three prunes run against it: a dirty path (status), a skip-worktree or assume-unchanged path (the -v flag, whose id says nothing about what is on disk), and a path a clean filter could rewrite. Every pruned path, and every untracked one, is hashed in-process with the exact blob-id algorithm git uses (blob <size>\0<bytes>, SHA-1 — or SHA-256 in an --object-format=sha256 repository).

The consequences:

A clean tree costs no file reads. No open, no stat, no lookup in a hash database, for any tracked-clean file. The per-file cost is a string in a stream.
A commit never changes a key. The dirty-file hash and the committed-file hash are the same blob id, so editing a file, running, committing and running again is one miss followed by one hit. Tools that hash mtimes or keep their own fingerprint store see a second miss at the commit boundary, or lean on a daemon to avoid it.
Clean filters are not trusted. Under a text, eol or ident attribute, or with core.autocrlf on, the index holds a normalised blob while your build sees different bytes, and git status calls the file clean. vx drops the index id for exactly those paths and hashes the working-tree bytes instead. A repository with no attributes file and no core.autocrlf pays nothing for the check: the gate is one git var -l, which also names the attributes files git reads outside the tree, and a stat of each.

Ignored files are not inputs; if your task reads a generated file, declare the task that generates it as a dependency and let the cascade carry it.

Boundaries are hard

cache.inputs.files globs are resolved inside the project’s directory and nowhere else. ../shared/** is an error, not a wider key. The reason is not purity: a glob that crosses into a sibling makes that sibling’s edits invisible to the sibling’s own dependents while making this project’s key depend on files it does not own. What a project needs from another arrives as an upstream task’s outputs, and its key arrives through part 10. The one deliberate exception is cache.inputs.workspaceFiles, which addresses files at the workspace root (a shared tsconfig.base.json) and says so in its name.

What the key deliberately ignores

exec.env.passThrough values. They reach the command but not the key, because a HOME or a CI that differs per machine would defeat a shared cache. If a variable changes the output, list it under cache.inputs.env too: that puts it in the key, and passThrough still passes it to the task.
Tool versions you did not declare. node --version is a cache.inputs.runtime line away.
exec.remote. Placement. Where a task ran says nothing about what it produced.
vx-lock.json, so that vx lock itself does not re-key the world.

When a key does change and you want to know which of the twelve parts moved, that is vx why. The full derivation with every rule and its history is in Caching.

Configs are programs. Hash what they evaluate to.

Thu, 10 Sep 2026 23:54:00 GMT

Turborepo’s turbo.json and Nx’s project.json are data. The tools hash the file and call the config part of the key. That works exactly as long as the file is the whole story.

A vx.config.ts is a program:

import { defineProject } from '@vzn/vx'
import { lib } from '../../vx-preset.ts'

export default defineProject({
  tasks: {
    ...lib({ entry: 'src/index.ts' }),
    docs: {
      exec: { command: `typedoc --out ${process.env.DOCS_OUT ?? 'docs'}` },
      cache: { inputs: { files: ['src/**'] }, outputs: { files: ['docs/**'] } },
    },
  },
})

Hashing this file’s bytes would miss every change to vx-preset.ts. It would also miss the value of DOCS_OUT. Both change what the task does.

The key sees the object

vx evaluates the config and hashes the resolved task object, the thing the scheduler is about to act on. Part five of the key derivation is xxh3(JSON.stringify(hashableConfig(node.config))) after the plugin project stage has run — one field wide, dropping exec.remote, which says where a task runs rather than what it does. Whatever a preset returned, whatever a template literal expanded to, whatever a plugin added or removed: all of it is in the key, because all of it is in the object.

Two properties fall out:

Presets are safe to share. Edit vx-preset.ts and every task that spread it re-keys, with no globalDependencies list to keep in sync.
Plugins are in the key. turbo() from @vzn/vx-migrate fills the project stage from a turbo.json; the resolved tasks it produces are what gets hashed. A plugin cannot change a task’s behaviour behind the key’s back.

Placement is stripped before hashing. exec.remote says where a task runs, which is not what it produces. timeout, retries and description are folded, because a task that was allowed to run longer may have finished where the shorter one was killed.

Evaluating a program has a cost, so gate the cache

Evaluating a hundred TypeScript files per run is not free, and the obvious fix, caching the evaluation, is unsound for a program that reads the environment or the clock. vx caches evaluation results only where it can prove soundness. Every file in the import closure is read, with its string literals and comments stripped first (a command string is not code: node -e "process.exit(0)" is an ordinary task). If what is left names a global through which an evaluation can observe something the file bytes do not capture, the config is refused the cache and evaluated live every run. The list is process, Bun, globalThis, global, self, fetch, Date, Temporal, Intl, crypto, performance, navigator, require, eval, Function, constructor, localeCompare, await, any toLocale* method, the reflective primitives that reach Function without naming it (Reflect, getPrototypeOf, setPrototypeOf, getOwnPropertyNames, getOwnPropertyDescriptor, getOwnPropertyDescriptors, __proto__, prototype, __defineGetter__, __defineSetter__, __lookupGetter__, __lookupSetter__), import.meta, random (as a word, so a destructured Math.random too), prompt, confirm and alert (they read the terminal) and a dynamic import() — the aliases and the property-name routes to each (global['proc' + 'ess'], ({}).constructor.constructor) included. A string literal naming constructor, __proto__ or prototype evaluates live too. The list stops accidental impurity; a config built to defeat it can assemble a key at run time. Five of those names were listed only after a config using them had been cached as pure. An identifier escape is the one spelling a name list cannot see, so a backslash in code position is refused on sight, and a bare import of anything but @vzn/vx is refused too: a pure closure is relative files.

A config that passes is keyed by the git blob ids of its whole import closure — so an edit to the preset invalidates the cached evaluation of every importer — together with the workspace fingerprint and the Bun and vx versions that evaluated it. A closure of more than 32 files evaluates live: a preset tree that big is not the case this serves.

What the gate buys: load configs is 16–25 ms per 1,000 configs served from the cache, against ~200 ms of evaluations. The refusal is what makes having it at all sound.

Freezing the evaluation: `vx lock`

Sometimes you want the evaluation pinned rather than repeated. vx lock evaluates every config now and writes the resolved objects plus a content hash of each file to vx-lock.json; vx run --frozen consumes the lock with no evaluation at all, and vx lock --check re-evaluates everything against it and exits non-zero on drift, including drift a byte hash cannot see: an env value read at eval time, an import that changed. The CI recipe is vx lock --check && vx run … --frozen. That gets its own post.

Why not named inputs

Turborepo’s globalDependencies and Nx’s namedInputs exist because JSON cannot compose. A vx.config.ts can: a shared input list is a constant in a file you import, and the resolved-config hash sees the result. Named inputs, global inputs and global env are on the repository’s rejected list for that reason, and they will stay there.

The tree is exactly the snapshot

Thu, 10 Sep 2026 23:53:00 GMT

Ask a monorepo tool what dist/ contains after a cache hit and the honest answer from most of them is “the cached files, plus whatever was already there.” That “plus” is the source of an entire genre of bugs: the deleted module that keeps being served, the renamed asset with two copies, the test fixture from a branch you checked out last week.

vx’s answer is shorter. The declared outputs are exactly the cached snapshot.

The rule

Every task with a cache block declares outputs.files. vx treats those globs as territory the task owns:

Before a miss executes, the current matches are removed. A leftover dist/old.js from a previous build cannot be picked up by the new build’s globs and cached as if it were produced now.
Before a hit restores, the current matches are removed. The post-restore tree is the snapshot, not the snapshot merged with the present.

Outputs are a task’s territory in the other direction too: two tasks whose output declarations provably overlap (equal literals, or a literal that another task’s glob matches) are refused when the graph is built, because a restore of one would delete the other’s work. Two globs that only might overlap are let through, and there the last restore wins. The one overlap vx accepts is the ordered one: when the second task depends on the first, it runs after it and adds to the tree — twenty’s build:individual writing dist/individual into build’s dist — and vx caches exactly what it added, never the files it found there.

Why it is also the fast path

Owning the outputs is what makes the warm-on-warm case cheap. Because vx knows the tree after any hit is the snapshot, it records a fingerprint per output file (size, mode, mtime-ms, inode, ctime) alongside the entry. On the next hit it checks two things:

The set. The files under the output globs must be exactly the recorded set, no more, no fewer.
The files. Every recorded fingerprint must match the file on disk.

If both hold, the restore is N stats and zero writes, zero decompression. That is the “current tree” short-circuit, and it is why the restore row and the no-op row in the benchmarks are within a few milliseconds of each other. A tool that merges cannot do this; it does not know what “current” means for a directory it only ever adds to.

What the wipe never touches

Files outside the declared globs. A task that writes somewhere it did not declare is a bug the sandbox can catch, but the wipe itself is bounded by the declaration.
Another project’s directory. Boundaries are hard.
.git and the .vx cache directory, whatever the glob says.
node_modules, unless a glob names it. **/*.js leaves installed files alone; node_modules/** is a legitimate output of an install task.

A task with no cache block declares no outputs and owns nothing. It runs every time and vx does not touch its tree.

The consequences you feel

The one you notice first: git status after a hit is clean in the way you expect, because the restore did not leave a merged pile behind. The one you notice never: the build that would have shipped a deleted file. Cache correctness is the worst failure class this tool can have, a stale hit replays wrong bytes under a green check, and strict ownership is the cheapest rule that removes one whole species of it.

Cascade through dependencies by folding input keys, never outputs

Thu, 10 Sep 2026 23:52:00 GMT

A monorepo cache has to propagate change. Edit packages/ui/src/button.tsx and apps/web#build must miss, even though nothing under apps/web changed. The mechanism for that is the tenth part of the key derivation: every upstream task’s key is folded into its dependents’ keys. The question is which upstream hash gets folded.

Two designs

Output-based cascade (also called early cutoff): fold the hash of the upstream task’s outputs. If ui#build re-ran but produced byte-identical dist/, the downstream key is unchanged and web#build hits. Attractive: a whitespace-only edit in a library does not rebuild the app.

Input-based cascade: fold the upstream task’s input key. If anything ui#build depends on changed, web#build re-keys, whether or not the output moved.

vx shipped early cutoff in one cache version and reverted it in the next. The reason is not that it was wrong. It is that it makes the key unknowable at the moment the key is most useful.

Keys before execution

With input-based cascade, every key in the graph is a pure function of the working tree, the configs and the environment. All of them can be derived up front, before a single task starts, and that is the property almost everything else in vx is built on:

vx run --dry prints the real key and the real hit/miss status for every task without executing anything. Under early cutoff, a downstream key does not exist until its upstream has run.
Remote prefetch issues the lookups for the whole graph at once and lets network latency overlap with real work instead of sitting on the critical path. It needs the keys first.
The restore tier of the scheduler classifies every stable task as a hit or a miss up front, makes the hits ready immediately at low priority, and lets misses own the worker pool while restores backfill idle capacity. Measured at −6.6% on a mixed workload. It needs the keys first.
Remote execution ships a task to a worker as one self-contained action whose inputs are exactly what the key declares. The action digest is the key’s cousin; it must be computable without running the upstream locally.
vx why can explain a change as a diff of named components, because a component is an input, and inputs have names.

Early cutoff trades all of that for the whitespace-edit case. In practice that case is rare, cheap (the downstream task runs once, and its own output is then cached under the new key) and, when it matters, better handled by declaring narrower inputs so the whitespace edit is not an input at all.

What “pure input” means precisely

A dependent’s key folds the upstream’s key, which is itself pure input. The fold is transitive through the graph, so web#build carries the keys of everything it can reach, and an edit anywhere in that closure moves it. The fold is also filtered: only the upstreams the graph actually connects are folded, so an unrelated package’s edit does not move it.

There is one subtlety the scheduler is careful about. A task whose input globs could match a same-project upstream’s declared outputs (a test task reading dist/** produced by build) has a key that is technically pure but preliminary: the files it reads are the upstream’s outputs, which may not exist yet. Such a task stays gated on its dependencies and is excluded from the up-front probe. The rule that finds it is shared between the local restore tier and remote prefetch, so the two cannot disagree about which keys are stable.

Full derivation and every version’s reason: Caching.

No daemon, on purpose

Thu, 10 Sep 2026 23:51:00 GMT

Nx runs a daemon by default. Turborepo shipped one and, as of 2.10, is deprecating it. Both exist for the same reason: a warm run needs to know what changed since the last one, and walking the filesystem to find out is slow. So a background process watches the tree and keeps the answer ready.

vx has no daemon and will not grow one. Here is the reasoning, and what replaced it.

What a daemon costs

A daemon is a second copy of the truth. It holds a model of the tree that is correct exactly as long as every change went through a filesystem event it received and processed. The failure modes are familiar to anyone who has typed nx reset: a socket left behind by a crashed process, a stale graph after a branch switch, an event dropped on a busy machine, a watcher that started after the edit. Each one turns a fast answer into a wrong one, and “wrong” for a build cache means a stale hit under a green check.

It also costs the thing it is meant to save. A daemon must be started, must warm up, must be restarted after an upgrade, and holds memory for the whole session. The first run of the day pays a cold start either way.

What replaced it

The question a daemon answers is “which files’ hashes do I need to recompute?” vx made the recomputation cheap enough that the question stopped mattering:

The hashes are in git’s index. One git ls-files -s returns the file list and every clean file’s blob id. A concurrent git status names the dirty ones. A clean tree of thousands of files is keyed with no file reads at all (the details).
Config evaluation is cached where it is provably safe, keyed by the git blob ids of the import closure, and evaluated live where it is not.
The graph algorithms are bitsets, so building priorities over 3,270 tasks is milliseconds, not seconds.
A warm hit on a current tree is N stats and zero writes, because strict output ownership means vx knows what the tree should contain.

The result is a fully cached run of 3,270 tasks in 510ms with no process left behind, against Turborepo’s 760ms and Nx’s 3.59s. On solidjs/solid, Turbo measured with --no-daemon so both tools pay discovery, vx’s no-op run is 51 ms to Turbo’s 95 ms. Turbo’s daemon would close part of that gap. vx has nothing to turn on.

The invariant, stated plainly

There is exactly one source of truth for what a task depends on: the working tree as git sees it, read fresh on every run. There is no staleness window because there is no second copy that could be stale. vx run in a terminal, in CI, in a container, on a machine whose watcher limits are exhausted, all take the same path and give the same answer.

That is worth more than a daemon’s best case, and it costs less than a daemon’s average case.

Bitsets, popcount, and a scheduler tick that re-scans nothing

Thu, 10 Sep 2026 23:50:00 GMT

A monorepo task graph is small by graph-algorithm standards: a few thousand nodes, a few tens of thousands of edges. It is large enough that the naive algorithm shows up in the profile of every warm run, because the graph is rebuilt every run and there is no daemon to hide it in.

Closures as bitsets

Two questions come up constantly: which tasks are downstream of this one (to prioritise the ones that unblock the most work) and which packages are reachable from this one (for --filter 'app...' and --affected). The textbook answer is a depth-first search with a set per node, unioning children’s sets into the parent’s. On 3,270 tasks, the priority computation done that way took 8.5 seconds.

vx represents each closure as a packed bitset over a topological numbering: one bit per node, one row of 32-bit words per node, every row in a single Uint32Array (N² bits, so N² / 8 bytes — 1.3 MB at 3,270 tasks). A union is a loop of bitwise ORs over those words; a size is a popcount. The same computation is single-digit milliseconds. The package graph uses the same representation, so a filter over a thousand packages is a handful of row ORs.

The tick

Priority in vx is “most blocked first”: the task with the most transitive dependents goes to the worker pool first, because finishing it releases the most work. The scheduler keeps ready tasks in an exact binary max-heap, ordered by that count and breaking ties in graph-insertion order, and on every completion decrements the pending dependency count of the completed task’s direct dependents and pushes the ones that reached zero. No re-scan of the graph: each edge is touched once, for O(E) over the run, plus one O(log N) heap operation per task that becomes ready and one per dispatch.

That is also why lookahead and idle-insertion scheduling are on the repository’s rejected list: they were measured, and the critical-path priority already ties or wins. The one refinement worth having is learning the real durations, which is what @vzn/vx-schedule-history does on the schedule seam: order by the critical path measured in previous runs instead of by edge count.

Two tiers: misses own the pool, hits backfill

A cache hit costs a restore, and a restore should never take a worker slot away from a miss that is on the critical path. On local-only runs, before scheduling, vx classifies every stable, cacheable task by probing the local cache once, up front:

Confirmed hits form the restore tier. They are made ready immediately, with no dependency gate — their key does not depend on any upstream’s success — but in a lane of their own: a second heap the tick drains only after the exec tier, under its own cap of twice the worker count (a restore is disk I/O, not CPU; --concurrency 1 stays serial). So a restore can never take a slot from a miss.
Misses own the worker pool from the first tick.

The up-front probe is not extra work: the execution path consumes the same result instead of probing again. Measured at −6.6% on a mixed slow-upstream, warm-downstream workload and at parity on all-hit runs.

A task whose key is only preliminary, because its inputs could match a same-project upstream’s declared outputs, stays in neither tier: it waits for its dependencies like any other task and is not probed early, because reusing a preliminary probe would be a stale-hit path. The rule that decides stability is shared with the remote prefetch so the two cannot disagree.

Admission is part of the tick

Core’s only gate is the worker count. Anything finer is a plugin’s: the admit stage is asked at every local dispatch, with the tasks running here right now, and a false holds the ready task until something finishes. Core keeps no notion of what a task needs — a developer cannot know a linker’s peak RSS, and it changes with every dependency bump — so @vzn/vx-schedule-history learns it: the runner records every execution’s CPU time and peak RSS (none for a sandboxed task on Linux), and the plugin packs the largest seen, with headroom, against the machine’s memory. It is 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. A remote executor with capacity gets its own pool and is never asked, so a 64-wide worker fleet is not throttled by a laptop’s core count.

Reference: the scheduler module notes under Architecture.

Explicit over magical: why vx never guesses your inputs

Thu, 10 Sep 2026 23:49:00 GMT

The most common first reaction to a vx.config.ts is: why do I have to write inputs: { files: ['src/**'] }? Nx has namedInputs with a default of everything. Turborepo defaults to every file in the package. vite-task traces the filesystem and infers the set. Surely the tool could work it out.

It could work something out. It could not work out the right thing, and the difference is the whole reliability of the cache.

What inference actually produces

A traced input set is the list of files a task opened that time, on that machine, with that environment. It is a description of one execution, gathered after the fact. Three things are wrong with using it as a key:

It arrives too late. The key is needed before the task runs, to decide whether to run it. An inferred set can only key the next run, which means the first run on every new key is untraceable, and a remote cache cannot be consulted with a key that does not exist yet. vite-task, which does this well, has no remote cache for exactly this reason.
It describes a path, not a dependency. A build that reads config/prod.json when NODE_ENV=production and config/dev.json otherwise has two traces and one dependency set. A key from either trace is wrong for the other environment.
It over-approximates in the direction that hurts. ** as a default input turns a README edit into a rebuild of every task in the package. Both Turbo’s default and Nx’s default do this; on solidjs/solid, Turbo’s per-package ** hashing is a visible part of the per-task overhead in the cold benchmark.

The explicit declaration is a statement about what the task depends on, which is the thing a key must capture. Only the author of the task can make that statement.

The cost, honestly

The cost of a wrong declaration is asymmetric, and the asymmetry is the argument:

An over-declared input (a file listed that the task never reads) costs a spurious miss. The task re-runs. Annoying, visible, cheap.
An under-declared input (a file read but not listed) costs a stale hit. The task does not run, the old output is restored, the check is green, and nothing downstream can tell. This is the worst failure a build cache can have.

Inference systematically produces the second kind, because a trace is always of one execution and dependency sets are larger than any one execution. Declaration lets you err toward the first kind, and it gives you two tools to find the second: vx why tells you when a task re-executed on an unchanged key, and the sandbox makes an undeclared read a hard failure that names the path.

Explicit everywhere else too

The same principle sets most of the schema:

cache is opt-in. No block, no cache, and no default globs.
dependsOn is explicit. There is no --parallel escape hatch because nobody has to over-declare edges to be safe; and there is sparse ^task bridging, so a package that lacks build does not need a filler task for its dependents’ ^build to walk through it.
Env reaches a task only through exec.env. A variable that merely has to be present goes under passThrough and stays out of the key. One that changes the output goes under passThrough and cache.inputs.env: the first passes it to the task, the second puts it in the key.
The sandbox derives nothing from cache. What a task may touch and what invalidates it are two declarations, because when one was derived from the other, a path added for caching silently widened the sandbox.

Magic is a debt whose interest is paid by the person debugging the stale hit. vx would rather you write one glob.

The sandbox: turning a declaration into a boundary

Thu, 10 Sep 2026 23:48:00 GMT

The previous post argued that inputs must be declared, not inferred. Declared inputs have a weakness of their own: they can be wrong, and a task that reads a file its inputs never named produces a cache entry that silently depends on that file. Green check, stale hit, nothing downstream can tell.

vx’s answer is to let you enforce the declaration. A task with a sandbox block runs inside an OS-level sandbox where the paths you grant are the only ones it can read, write or reach.

lint: {
  exec: {
    command: 'eslint .',
    sandbox: { allow: { read: ['.'] } },
  },
  cache: { inputs: { files: ['src/**', '.eslintrc'] }, outputs: { files: [] } },
}

One allow-list, no inheritance

sandbox: {} is the baseline: reads nothing in the workspace, writes nothing, no network of its own (a run’s domain lists are one union every sandboxed task reaches; schema.md § exec.sandbox). Not even the project’s own directory, which is why read: ['.'] is the first line of nearly every real block. The read wall stands at the workspace root: ~/.cache and /etc stay readable, and fold into no key. On top of the baseline you grant exactly what the tool needs:

read and write paths or globs, project-relative, absolute or ~-expanded. A write grant is readable too, so tsc --incremental can re-read its own .tsbuildinfo.
network: true, or a list of domains with wildcards. Domain lists are enforced by one filtering proxy per run; a task that declares no network is never given the proxy’s port and reaches nothing.
localBinding for a test that boots its own server, unixSockets, systemInfo, gitConfig for the rare tool that must write .git/config, and the macOS-specific machLookup and pty.

Two lists sit beside allow. deny takes a capability back — it is evaluated first, so a domain in both is denied — and ignore keeps a denial out of the report without granting it.

There is no workspace-wide default and no inheritance between tasks. Those three lists are the whole permission surface of that one task.

Why it derives nothing from `cache`

The obvious shortcut would be to grant the cache.inputs globs as reads. vx did that once and removed it. cache.inputs says what invalidates a task; sandbox.allow says what it may touch. When one was derived from the other, a path added for caching silently widened the sandbox, and a path the task genuinely needed had to be laundered through the cache key to become readable. Two declarations, and the place they meet is the violation: a sandboxed task that reads a file its inputs never named fails on the denied read, which is exactly the under-declaration you wanted to find.

What a violation looks like

An undeclared path inside the project is a finding: the run fails and the report names the path. An undeclared path outside the project is the wall, denied silently, because a project reading its neighbour is not a mis-declaration to fix but a boundary being held.

A failed task is never cached, so a violation cannot poison the cache. When a tool is legitimately noisy (a probe for a file that may not exist), ignore silences the specific pattern without granting it.

How it is built

Linux needs three binaries on PATH: bwrap for the namespaces, socat for the network bridge, and ripgrep (rg) to expand the runtime’s mandatory deny globs. The child lives in its own mount and network namespaces; an undeclared path structurally does not exist, so the tool sees ENOENT. With strace present, that becomes the same structured report macOS produces. Each localBinding port is bridged to the host’s loopback over a unix socket so a downstream task or your browser can reach the server.
macOS uses the system sandbox (seatbelt) plus a log monitor for the report. Enforcement is the OS’s; the unified log feeding the report is lossy under load, so a violation can go unreported while still having been denied.
Windows is WSL, where the Linux sandbox applies.

The two limits worth knowing: root inside a container usually cannot create the nested user namespace the Linux runtime needs (run as an unprivileged user, or accept weakerWhenNested), and seatbelt cannot nest, so a task that itself sandboxes cannot be sandboxed on macOS. In vx’s own repository exactly two tasks have no sandbox block: the part of the core suite a sandbox cannot host, and the one plugin suite that dials service containers on the host’s loopback. Everything else, lint, format, docs build, every other package’s tests, runs inside one.

Where it fits

The sandbox is opt-in per task. Use it on the tasks whose inputs you are least sure of, in CI where hermeticity is worth the setup, and before marking a task eligible for remote execution, where a worker will see exactly the declared inputs and nothing else. The guide is Sandboxing tasks.

Why did this re-run?

Thu, 10 Sep 2026 23:47:00 GMT

A cache key is one opaque hash. When it changes, knowing that it changed is nearly useless. You need to know which of its parts moved. Most tools do not keep that information; they compute the hash, compare it, and print miss. The afternoon you then spend bisecting your own inputs is the real cost of the cache.

vx records the per-component input fingerprint alongside every cache entry. That makes the question answerable from the terminal:

$ vx why app#build
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 between the previous run and this one (inputs differ)

  what changed (1 component, 41 unchanged):
    changed file  src/input.txt  3fe2a1b0… → 91c47d22…

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

One component moved and it is named. Forty-one did not.

What it reads

vx why is read-only over the local cache.db. It evaluates no project config (the workspace file, once, for the cache directory, unless --cache-dir names it), re-hashes nothing, runs nothing. It compares the task’s latest recorded run with the one before it (or a run you pin with --run) and diffs the stored components, one row per kind: file (path and blob id), env (a declared variable), runtime and ws-runtime (a declared command’s output, project- or workspace-rooted), forward (the argv forwarded after --), package (the project’s own package.json), workspace (the fingerprint), config (the evaluated task config), upstream (a dependency’s input key, by task id) and plugin (a plugin’s material, by name). When @vzn/vx-lockfile is declared, a dependency bump shows up as plugin @vzn/vx-lockfile/pnpm for exactly the projects it reaches.

Because it only reads the database, it works after the fact and on another machine: a CI job that copied .vx/cache out can be asked why it rebuilt, tomorrow, from a laptop.

Six endings for an unchanged key

The interesting cases are the ones where the key did not change, and vx why distinguishes them rather than calling all six a re-run. The verdict line is one of these nine sentences, quoted from the code:

vx says	What happened
cache key changed between the previous run and this one (inputs differ)	the components are listed
cache key unchanged — this run was served from cache, nothing re-ran	it was a cache 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 — 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 — re-executed on the same key (—no-cache / —force, or unrelated)	none of the above; vx cannot name the cause
cache key unchanged — this run recorded no cache outcome, so whether it re-ran is unknown	the run recorded no outcome for this task; vx says so, not guesses
this task declares no `cache` block — it runs on every invocation; its key is folded by dependents only	not a cache decision at all
this task recorded no cache key (skipped, or a persistent task) — nothing to compare	there is no key to compare

The sixth row (“re-executed on the same key”) is the one to read twice: vx could not name the cause. An undeclared input does not end up there. A file, env var or tool version the key cannot see changes the output but not the key, so the task hits and replays stale bytes. The way to make that impossible is the sandbox, which turns the input declaration into a boundary the task cannot cross.

The same answer for machines

--format json emits one object: { taskId, runId, why, diff }. The @vzn/vx-mcp plugin exposes the same query as a tool a coding agent can call (whyDidThisRerun), so “why is CI rebuilding everything” is a question an agent can answer without reading the source of the runner.

A cache is a claim that the work has been done before. vx why is how the claim is audited. The guide is Caching.

A lockfile bump should re-key two tasks, not sixty

Thu, 10 Sep 2026 23:46:00 GMT

Out of the box, vx does what everyone does with the lockfile: it goes into the workspace fingerprint, and the workspace fingerprint is in every task’s key. That is coarse but correct. Any pnpm install that changes pnpm-lock.yaml invalidates every cached task, and --affected selects every project.

It is also the single largest source of “why did everything rebuild” in a large workspace. A patch bump to a test utility used by one package re-runs the builds of all of them.

Key each project on what it can reach

@vzn/vx-lockfile ships one plugin per package manager: pnpm(), bun(), npm(), yarn(). Each claims its lockfile out of the workspace fingerprint through the fingerprint seam and instead contributes, per task, a digest of its project’s resolved dependency closure:

vx.workspace.ts

import { defineWorkspace } from '@vzn/vx'
import { pnpm } from '@vzn/vx-lockfile'

export default defineWorkspace({ plugins: [pnpm()] })

Nothing else changes. vx why names the material as plugin @vzn/vx-lockfile/pnpm, and the workspace fingerprint line stops moving when the lockfile is edited.

The closure is exactly what the project’s node_modules can resolve:

its dependencies, devDependencies and optionalDependencies, transitively through the lockfile’s own resolution graph;
each package by name, version and resolved peers, because foo@1(react@18) and foo@1(react@19) are different directories on disk, plus its integrity and any patch applied to it;
a link: or workspace: dependency folds the linked workspace package’s whole reach, since what A can import through B is B’s closure;
install-wide material every project folds: lockfileVersion, overrides, settings (and, under bun(), patchedDependencies and the catalogs).
the root package’s own closure, folded into every project (added 2026-09-24): the root’s tools run from the root node_modules/.bin on every task’s PATH, so a root devDependency bump that re-keyed nothing replayed the old tool’s output.

bun() does the same through Bun’s hoisted layout (a nested version counts for the package it is nested under and no other); npm() through package-lock.json’s packages map; yarn() per workspace through berry’s descriptors. Yarn classic records no workspaces, so every project folds one root digest, which is coarse and honest about what that file contains.

A phantom dependency, imported but never declared, is in no closure. Declare it.

`--affected` follows the same claim

The plugin’s affected(change) hook answers the selection question too. vx run test --affected with a lockfile diff selects the projects whose closure the diff reaches, not every project. The rule that keys a task and the rule that selects it are one rule, so they cannot drift.

Measured in the repository that ships it

vx’s own repository declares bun(). Bumping one package’s resolved version in bun.lock re-keys that package’s own tasks and its dependants’ instead of every task in the gate. That is the whole pitch: a dependency change costs what the dependency change touches.

The plugin is separate from core on purpose. Core owns the fingerprint seam, the memo and the per-run gate; the lockfile parsers are package-manager knowledge, and package-manager knowledge changes on the package manager’s schedule. The guide is Lockfile-aware caching.

Config in TypeScript, and why there are no named inputs

Thu, 10 Sep 2026 23:45:00 GMT

Turborepo and Nx both grew the same features for the same reason. globalDependencies, globalEnv, namedInputs, targetDefaults, extends: every one of them is a way to say something once and reuse it, added because JSON cannot say anything once. vx’s config is a TypeScript module, so the feature list is a language feature list, and it is already complete.

The shape

packages/app/vx.config.ts

import { defineProject } from '@vzn/vx'

export default defineProject({
  tasks: {
    build: {
      exec: { command: 'tsc -b' },
      cache: {
        inputs: { files: ['src/**', 'tsconfig.json'] },
        outputs: { files: ['dist/**'] },
      },
    },
    test: {
      dependsOn: ['build'],
      exec: { command: 'vitest run' },
      cache: { inputs: { files: ['src/**', 'test/**'] }, outputs: { files: [] } },
    },
  },
})

defineProject is an identity function — it returns its argument — that exists for autocomplete and validation. The files vx init and @vzn/vx-migrate generate skip even that and write satisfies ProjectConfig with a type-only import: the same checking without a runtime import of core in every config file, which is a second copy of core loaded per run, ~17 ms on a two-package workspace.

Composition is an import

A shared preset is a file:

// vx-preset.ts (workspace root)
export const lib = (entry: string) => ({
  build: {
    exec: { command: `tsup ${entry}` },
    cache: { inputs: { files: ['src/**', 'tsup.config.ts'] }, outputs: { files: ['dist/**'] } },
  },
})

packages/ui/vx.config.ts

import type { ProjectConfig } from '@vzn/vx'
import { lib } from '../../vx-preset.ts'
export default { tasks: { ...lib('src/index.ts') } } satisfies ProjectConfig

Because the key hashes the resolved config, an edit to vx-preset.ts re-keys every task that spread it. There is no list of global dependencies to maintain, because the dependency is the import, and the runtime already tracks imports.

The same shape covers what namedInputs and targetDefaults do. A named input is a constant. A target default is a function that returns a task and takes the parts that vary. Nx’s extends is ...spread. All of them are features you already know from the language, checked by the compiler, refactorable by the editor.

What a config may not do

A program can do too much, and two things are refused rather than allowed:

Reading another project. Globs are resolved inside the project directory. ../shared/** is an error, and cache.inputs.workspaceFiles is the one named exception for files at the workspace root.
Being impure without saying so. A config that names process, Date, fetch, import.meta, a dynamic import() or any of the other globals on the purity gate’s list is evaluated live every run and never served from the evaluation cache. That is the correct behaviour, not a penalty; it just means a config that reads process.env should be one that has to.

Freezing it

When “evaluated live” is exactly what a CI pipeline must not do, vx lock evaluates every config once and writes the resolved objects to vx-lock.json; vx run --frozen consumes the lock with no evaluation at all, and --check catches drift a byte hash cannot see.

The migration path

vx init writes these files from package.json scripts. bunx @vzn/vx-migrate writes them from a turbo.json or an Nx project graph, and when it meets a globalDependencies list it generates the preset file and the import for you, because that is what the list was trying to be. The schema reference is Configuration schema.

vx lock: freezing what the key sees

Thu, 10 Sep 2026 23:44:00 GMT

A TypeScript config buys composition and costs one guarantee: what it evaluates to can depend on where it is evaluated. process.env.CI, a Date, an import that resolved differently on another machine. On a laptop that is fine. In a pipeline that must run exactly the config a reviewer approved, it is a hole.

vx lock closes it the way package managers closed the same hole for dependencies.

Three verbs

vx lock              # evaluate every vx.config.* now; write vx-lock.json
vx lock --check      # audit: hashes + full re-evaluation against the lock; exit 1 on drift
vx run … --frozen    # consume the lock; no evaluation at all

vx lock evaluates each config in the current environment and stores the post-evaluation object plus a content hash of the config file. Plain runs always evaluate live; the lock’s existence changes nothing about vx run. Only --frozen consumes it, and under --frozen there is no evaluation and no staleness check of its own: a config’s env reads keep their lock-time values, a project absent from the lock is a hard error, a missing lock is a hard error.

The check that a hash cannot do

--check does two things, and the second is the reason the verb exists. It compares the stored content hash of each config file, which catches an edit. Then it re-evaluates every config in the current environment and compares the result to the frozen object, which catches what an edit-detector cannot: an env value read at evaluation time that differs from the lock’s, an imported preset that changed, a computed command whose input moved. Every mismatched project is listed on stderr and the exit code is 1.

The CI recipe is two lines:

vx lock --check && vx run ci --all --frozen

The first line proves the lock still describes the configs as this machine would evaluate them. The second runs exactly the lock. A pull request that changes a config without re-running vx lock fails the first line, which is the point.

What the lock is not

Not a cache key input. vx-lock.json is excluded from every task’s input set and from the workspace fingerprint, so running vx lock does not re-key the workspace.
Not a substitute for cache.inputs.env. The lock freezes what a config evaluated to. An env var a task reads at run time is still a run-time input and belongs under cache.inputs.env, where it joins the key. The two mechanisms are parallel on purpose: config-time values are locked, run-time values are keyed.
Not a performance feature. Evaluation is already cheap and cached where it is provably pure. --frozen is about determinism, and the milliseconds it saves are incidental.

Where it came from

The lock exists because the resolved-config hash made configs powerful, and power needs an audit. Package managers learned the same lesson with --frozen-lockfile: let resolution be dynamic in development and pin it where reproducibility is the contract. The design note is in the repository under docs/design/config-lock; the reference is vx lock.

One command per task; the shell is the API

Thu, 10 Sep 2026 23:43:00 GMT

exec.command is a string. It runs under sh -c with the project’s and the workspace root’s node_modules/.bin on PATH, in the project’s directory, with the environment you declared. That is the entire execution model, and it is a constraint chosen on purpose.

What it rules out

JavaScript-function tasks. A task that is a function in the config file is convenient right up to the moment you want to run it somewhere else. It cannot be shipped to a worker, cannot be sandboxed at the OS level, cannot be replayed from a log, and its inputs are whatever the closure captured. vx has no run: async () => …, and will not.

Executors. Nx wraps tools behind plugins with options objects, so @nx/js:tsc with { main, tsConfig } is a layer between you and the tsc documentation. When the tool adds a flag, the executor has to learn it. When the executor has a bug, the tool did not. vx has no executor plugins; a plugin changes where a command runs, never what it is.

Step lists. A task that is [build, then copy, then compress] is three tasks pretending to be one, with one cache key for three behaviours. Chain with && if the steps truly are one unit, or split them into tasks wired by dependsOn so each caches independently.

What it makes possible

Once a task is a command with declared inputs and outputs, every capability in vx becomes a transformation of the same triple:

Remote execution ships it as one REAPI action: the command string, the declared input tree, the declared output paths. Nothing about the task has to be serialisable beyond what it already is.
The sandbox wraps the command in bwrap or seatbelt with the declared paths. There is exactly one process to confine.
Replay stores the captured stdout in the cache row and prints it byte-identical on a hit, NUL bytes, carriage-return progress rewrites and raw ANSI included. A hit looks like the run.
Migration from Turborepo or Nx is mostly a rendering problem, because both of them ultimately run a command too; vx just writes it where you can read it.
vx show, --dry, MCP’s listTasks all print the same thing a human would type.

The environment is declared too

A command’s environment is part of what it does, so it is not inherited wholesale. Each task gets an isolated environment built from exec.env: values you set (part of the config, so in the key) and variables you passThrough from the parent (not in the key). cache.inputs.env puts a variable in the key but does not pass it to the task, so a variable that changes the output and must reach the task goes in both. PATH is prepended with the project’s node_modules/.bin, then the workspace root’s, so tsc resolves without npx. A variable that changes the output and is missing from cache.inputs.env is the most common under-declaration, and it shows up as a stale hit: the key did not change, so vx replays the old output.

Two variables are always set: the workspace vx is running and the task id, so a command that runs vx itself against the same workspace is refused instead of recursing into the same cache.

The API is the one you already have

The practical consequence is that vx never needs a plugin for a tool. There is no @vzn/vx-vite, no @vzn/vx-jest, and there is not going to be one, because vite build and jest are already the API. The repository briefly shipped a package that inferred tasks from tool configs and retired it: technology-specific knowledge is the community’s to write as presets, in TypeScript, on top of a runner that only knows what a command is.

Reference: Running tasks and Environment variables.

One binary, nothing to install underneath

Thu, 10 Sep 2026 23:42:00 GMT

The runner for a JavaScript monorepo is the first thing that runs in CI and the last thing you want to have an opinion about your Node version. vx is built on Bun, and the way you never notice that is that you never install Bun.

What you install

npm install -D @vzn/vx    # or pnpm add -D · yarn add -D · bun add -d

The package ships the prebuilt standalone binary for your platform: Linux and macOS, x64 and arm64 (Windows under WSL). It is the same binary the GitHub release carries, so a CI image can fetch the tarball directly and skip the package manager entirely. There is no postinstall that compiles anything, no download at first run, and no runtime to match.

Your tasks are unaffected. tsc, vite, eslint run under whatever Node your project uses, because a task is a shell command and vx only prepends the project’s and the workspace root’s node_modules/.bin to its PATH. vx’s runtime is vx’s business.

What that buys

A CI step with no setup. No setup-node before the runner, no cache of the runner’s own dependencies. Fetch, run.
No version skew between the tool and its host. A compiled binary carries its runtime. The vx that ran yesterday is the vx that runs today, byte for byte, on every machine in the team.
No runtime to boot before vx’s own code runs. A compiled Bun binary starts as itself, which is part of what makes a 50 ms fully cached run on a real repository possible at all.
vx.config.ts evaluated natively. TypeScript config with no transpile step, no ts-node, no loader flag. The binary resolves the @vzn/vx import from your node_modules, which is also why the package stays in devDependencies even when you run the release binary: it carries the types.

Why Bun, and why it does not leak

The core depends on things Bun does natively that would otherwise be dependencies with their own opinions: bun:sqlite for the cache index, Bun.zstd* under vx’s own streaming tar, Bun.spawn for the runner, Bun.Glob for input resolution, and bun build --compile for the binary itself. Every dependency in the repository has a written reason next to it, and the list is short because the runtime covers most of what a runner needs.

None of that reaches you. A workspace on Node 18 with pnpm and a .nvmrc runs under vx exactly as it does under Turborepo. The one place Bun shows is if you want to run vx from source, which needs Bun ≥ 1.4; the binary needs nothing.

No daemon, no service

The binary is also the whole deployment. There is no background process to start (by design), no account to log into, no service to reach. vx run in a container with no network does what vx run on a laptop does. The plugins that talk to the outside world are packages you add, and the local floor is what runs when they are absent or decline.

Install and first run: the Quickstart.

A pipeline with seams

Thu, 10 Sep 2026 23:41:00 GMT

The word “plugin” usually means one of two things. Either a plugin is a whole subsystem with its own configuration language (Nx executors), or it is a callback bolted to one event the tool happened to expose. vx uses the word the way Vite does: the core is a pipeline, every stage has a named hook, and a plugin is an object that implements the hooks it needs.

The stages

config → project → graph → key → fingerprint → schedule → admit
        → executor / cache → telemetry
setup and teardown wrap the run; commands adds a verb

Stage	What a plugin can do there
`config`	See and adjust the workspace config before anything uses it.
`project`	Add, remove or edit one loaded project’s tasks.
`graph`	Add or drop edges, mark tasks requested.
`key`	Contribute extra cache-key material per task.
`fingerprint`	Claim a lockfile out of the workspace fingerprint and key it per project.
`schedule`	Return a priority per ready task.
`admit`	Vet each local dispatch against what is running right now; `false` holds the task.
`executor`	Decide where one task’s command runs.
`cache`	Provide a layer where artifacts live.
`telemetry`	Receive immutable run records. Cannot change behaviour, by construction.
`setup`	Once per run, after the planning stages and before the first task.
`commands`	Add a CLI verb. Core’s verbs match first; nothing can shadow `vx run`.
`teardown`	Flush and close at the end of the run.

A plugin is definePlugin(import.meta, hooks). Its name is its package name, read from import.meta, never a field you set. Declaration order in vx.workspace.ts is the order everywhere: executors are consulted in order, cache layers are chained in order, telemetry sinks receive in order.

What fits in one hook

The proof that the seams are the right width is what has been built on them without a special case in core:

turbo() from @vzn/vx-migrate fills the project stage from a turbo.json and each package’s scripts. A Turborepo workspace runs under vx with a two-line workspace file and no config rewritten.
@vzn/vx-lockfile uses fingerprint to claim pnpm-lock.yaml (or bun.lock, package-lock.json, yarn.lock) and key each task on its own project’s dependency closure. --affected follows the same claim.
@vzn/vx-schedule-history fills schedule with the critical path learned from run history, and admit with a memory reservation packed from what each task used before.
@vzn/vx-reapi provides both executor and cache against any Bazel Remote Execution API server: remote cache and remote execution from one plugin.
turboCache() and nxCache(), from the same package, are cache layers speaking Turbo’s /v8/artifacts and Nx’s /v1/cache wire formats, so an existing self-hosted cache server keeps working.
@vzn/vx-otel and @vzn/vx-github are telemetry sinks: an OTLP exporter with no OpenTelemetry SDK dependency, and a GitHub Actions job summary plus a check run on the built commit.
@vzn/vx-mcp is commands: a Model Context Protocol server for coding agents, a verb core does not know.

Every one of these lives in its own package and imports core only through @vzn/vx’s public façade. A test pins the façade so it cannot widen by accident.

The rule that keeps the seams honest

Seam over special case. When core grows a branch for one consumer, the seam is too narrow, and the fix is to widen the seam, not to keep the branch. Twice in this repository’s history a capability shipped inside core and was moved out once the hook it needed existed: vx migrate became @vzn/vx-migrate, and the run-history scheduler became @vzn/vx-schedule-history on schedule. Core got smaller both times.

The second rule is the one that keeps the floor under your feet: core applies no plugin by default and names none. A capability a plugin must supply, a remote, a wire format, is declared in vx.workspace.ts or it does not exist. The one thing that is implicit is the local floor: running here and caching here.

Writing one is a short guide: Writing a vx plugin.

The local floor: running here is not a plugin

Thu, 10 Sep 2026 23:40:00 GMT

A pipeline that applies no plugin by default has to answer one question honestly: what happens with no plugins at all? For vx the answer is that the workspace runs and caches exactly as it would with a full workspace file, because the local executor and the local cache are not plugins. They are the floor.

Two lists, one tail

When vx places a task, it walks the executor list from vx.workspace.ts in declaration order and asks each one whether it will take the task. When vx looks a key up, it walks the cache layers in order. Both lists have the same implicit last element:

executors: [ reapi, …, local ]
cache:     [ turboCache, …, .vx/cache ]

You never write the last element and you cannot remove it. A workspace with no vx.workspace.ts is the empty list plus the floor, which is why vx run build works in a fresh repository with one vx.config.ts and nothing else.

Declining is a first-class outcome

Because the floor is always there, a plugin is allowed to say no. That turns a lot of would-be failure modes into placement decisions:

A remote executor declines a task that has no cache block (a worker would run it against an empty tree). It runs here.
A persistent task and everything that depends on it is never offered to a remote executor, because a worker cannot reach a port on your laptop. They run here.
A sandboxed task is never offered either: the sandbox is local machinery a worker does not have, and a boundary verified remotely would pass vacuously. It runs here, inside the sandbox, and so does everything that depends on it.
A remote cache that errors, times out or is simply unreachable degrades to a miss on that layer, and the lookup continues down the chain to the local cache. A remote outage is a slower run, not a broken one.
@vzn/vx-reapi against a server that only advertises caching declines the executor with a warning; the cache layer still works.

vx run --dry shows the decision per line once the workspace declares more than one executor: @vx/reapi, @local, or @noop for a task with nothing to execute.

Why it is the floor and not a default plugin

It would have been easy to ship localExecutorPlugin() and localCachePlugin() and prepend them when the list is empty. That design has a hole: a list that is not empty would have no floor unless the user remembered to append them, and a plugin that declined would have nowhere to hand the task. Making local behaviour the tail of every list instead of a member means the “no plugin” case and the “plugin declined” case are the same case, and there is no configuration in which a task has nowhere to run.

It also keeps the principle intact. Core names no plugin. What it names is a machine and a directory, which is not a capability anyone supplies. Everything above the floor, including the wire a remote cache speaks, is declared in the workspace file or it does not exist.

Observability that cannot break a run

Thu, 10 Sep 2026 23:39:00 GMT

Every build tool eventually grows an integration point for “tell someone what happened”: Sentry, Slack, a metrics endpoint, an OpenTelemetry collector. Every one of those integrations is also a way for a network hiccup to fail a build, and the usual defence is a policy: please catch your errors, please do not block.

vx’s telemetry capability makes it a structure instead.

The contract

interface TelemetrySink {
  readonly name?: string
  readonly wants?: ReadonlyArray<'run.start' | 'task.start' | 'task.end' | 'task.log' | 'run.end'>
  onRecord?(record: TelemetryRecord): void          // must return promptly; buffer here
  onRunSummary?(summary: RunSummaryRecord): void    // one per run, at the end
  flush?(signal: AbortSignal): Promise<void>        // awaited at end of run, time-bounded;
                                                    // `signal` aborts at the deadline
}

A sink is handed immutable records and a read-only context: the workspace root, the cache directory, a warn function. No event bus, no cache handle, no run request. There is no method on anything it receives that reaches scheduling, caching or execution. The guarantee that a sink cannot change a build is not a rule sinks follow; it is the absence of a path.

Crash isolation

If a sink throws, from onRecord, onRunSummary or flush, it is disabled for the rest of the run and a warning is printed. Other sinks keep receiving records. The run’s outcome is unaffected.
onRecord must return promptly, so the contract says buffer and do not await. flush() is the one awaited drain point, at the end of the run. All sinks flush at once under one shared bound, three seconds by default (VX_TEARDOWN_TIMEOUT_MS overrides it), so a wedged collector cannot hold the process’s exit hostage.
A sink that lists what it wants costs the source nothing for the kinds it skips; the large task.log stream is off unless asked for.

The other direction is isolated too. A plugin whose setup() throws aborts the run before any work starts, naming the plugin, because a broken plugin should fail loudly and early rather than silently degrade. An executor or cache factory that throws aborts the same way; those are load-bearing.

Zero cost when absent

The design has a second property that matters as much as safety: no telemetry plugin means no telemetry cost. No bus subscriber is registered, no run summary is assembled, no git is spawned for provenance. A workspace with no sinks pays nothing for the capability existing. That is the general rule for every seam in vx: a stage nobody fills is not a no-op call, it is no call.

What is built on it

@vzn/vx-otel maps each run to OTLP traces and metrics over HTTP/JSON with no OpenTelemetry SDK dependency. The wire format is small and the SDK is not.
@vzn/vx-github writes every run as a GitHub Actions job summary and, given a token, a completed check run on the built commit, so a red run explains itself in the pull request’s checks list.
Anything else is a few dozen lines: buffer records in onRecord, post them in flush. The guide has a runnable sink against the exported types.

The same rule for remote caches

The never-fail discipline is not only for telemetry. A remote cache layer that errors, times out or is unreachable degrades to a miss on that layer, the lookup continues down the chain to the local cache, and the run completes. Every remote path (get, put, ingest, prefetch) is wrapped the same way; a remote outage is a slower run, never a broken one, and a plugin that never fails still warns so you know it happened.

The guide is Writing a vx plugin.

Remote execution without moving the scheduler

Thu, 10 Sep 2026 23:38:00 GMT

Distributed builds usually arrive as a platform: a service that owns the graph, agents that run it, a dashboard that shows it. vx’s version is a plugin that fills two seams, executor and cache, against a wire that already exists: Bazel’s Remote Execution API, spoken by NativeLink, BuildBuddy, Buildfarm and bazel-remote.

vx.workspace.ts

import { defineWorkspace } from '@vzn/vx'
import { reapi } from '@vzn/vx-reapi'

export default defineWorkspace({
  plugins: [
    reapi({
      endpoint: 'grpcs://cache.example.com:443',
      execute: true,
      platform: { OSFamily: 'Linux', 'container-image': 'docker://node:22' },
      capacity: 64,
    }),
  ],
})

Execution is off unless execute: true is set, even with the plugin declared for caching. Changing where a build runs is not something a plugin should do by being present.

The scheduler never leaves

vx owns the task graph and decides placement once per task, before scheduling. Telemetry, retries, timeouts, the cache and the logger behave exactly as they do locally, because none of them moved. The executor’s job is one function: run this command with these inputs and give me the outputs. capacity gives it its own scheduler pool, so a 64-wide fleet is not throttled by a laptop’s core count and remote tasks reserve none of the local CPU budget.

vx run --dry prints the decision per line: @vx/reapi, @local or @noop.

What goes remote

Only cacheable tasks. A task with no cache block has no declared inputs, so a worker would run it against an empty tree.
Not persistent tasks, or anything depending on one. A worker cannot reach a port on your machine; the placement stage knows.
Not sandboxed tasks. The sandbox is local machinery a worker does not have, and a boundary verified remotely would pass vacuously.
Not exec.remote: false. A task that talks to Docker, a device or a local daemon is pinned by one field.

A task’s inputs on the worker are exactly what its cache key declares: cache.inputs.files, resolved env values, upstream outputs. Ambient state such as an undeclared tsconfig.json, .npmrc or node_modules is not in the key and therefore not on the worker. The sandbox is how you find the gap before you mark a task remote-eligible: a task that passes locally with the declared paths as its only reads will pass on a worker.

`node_modules`: install as an action

Workers are stateless and node_modules is ambient. The answer is an explicit install task pinned to the pool with exec.remote: 'only':

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/**'] } },
},

Verified end to end against a live NativeLink pool: install runs on a worker, once per lockfile change, and its outputs never touch your disk. A dependent’s input tree references the install outputs in the remote content-addressed store, so the bytes flow worker to store to worker without transiting your machine. With no remote executor declared, install is a local no-op and dependents use whatever your machine has, so a laptop run behaves as it did before the field existed.

One artifact format, both directions

The same tar.zst bytes serve the local cache and the remote’s action cache. Nothing is repacked at the boundary. A remote error, a timeout, an unreachable endpoint all degrade to a miss on that layer and the run continues locally; a cache-only server that advertises no execution capability declines the executor with a warning and keeps serving the cache.

None of this is in core. Core has the two seams and the placement stage; @vzn/vx-reapi is the proof they are wide enough. The guide, including worker image requirements and how output globs travel over a wire that has no globs, is Remote execution.

Give your coding agent the build's memory

Thu, 10 Sep 2026 23:37:00 GMT

A coding agent dropped into a large monorepo spends a surprising share of its tokens working out how the build works: reading turbo.json or a hundred project.json files, guessing which task to run, re-running things to see whether they are cached. The runner already knows all of that. @vzn/vx-mcp hands it over.

vx.workspace.ts

import { defineWorkspace } from '@vzn/vx'
import { mcp } from '@vzn/vx-mcp'

export default defineWorkspace({ plugins: [mcp()] })

// Claude Code: .mcp.json at the workspace root — or: claude mcp add vx -- vx mcp
{ "mcpServers": { "vx": { "command": "vx", "args": ["mcp"] } } }

Cursor, Continue.dev and VS Code Copilot take the same command-and-args shape. Run the agent from inside the workspace and vx mcp finds the workspace and its cache from the current directory, exactly as vx run does.

What it answers

Tool	The question
`listTasks`	What can I run here? Every project and task as a run would see them, plugin stages included.
`getCacheStats`	What is the cache’s state right now? Entries, size, runs and hit rate, per workspace or per project.
`getRunHistory`	What have I been running and how fast? Recent runs with per-task p50, p99, success rate, hit rate.
`explainCacheKey`	What is the cache identity of `pkg#build`? The latest entry’s hash, command, exit code, duration, size.
`whyDidThisRerun`	Why did `pkg#test` re-execute instead of hitting? The run’s key against the previous run’s.
`getWorkspaceInfo`	What is this workspace? Versions and state, the plugins declared, the flaky tasks, whether `vx-lock.json` exists — the facts a bug report needs.

The history tools read the same local cache.db tables that vx why, vx last and vx info read. getRunHistory calls a task flaky only on a real nondeterminism signal, a within-run retry or one key that both failed and succeeded, so an agent does not learn to shrug at repeated failures on changing inputs.

Nothing exposed can run a task or write the cache. The transport is stdio, which is process-private, so there is no port, no auth and no attack surface beyond the process the agent already spawned.

Why it is about 210 lines

MCP over stdio is newline-delimited JSON-RPC 2.0 and the three methods an agent needs: initialize, tools/list, tools/call, plus ping. The plugin speaks it natively in about 210 lines with no dependencies; the reference SDK pulls in an HTTP stack this transport never uses. A tool’s own refusal (“a task id must be project#task”) comes back as an isError result the agent can read and correct, not as a protocol error that ends the conversation.

It is also the clearest example of the commands seam doing what it is for: one plugin contributes one verb, vx help lists it under “Plugin commands” from any directory inside the workspace that declares it, and outside such a workspace the verb does not exist. Core knows nothing about agents.

The other half

The MCP server is how an agent reads the build. The other half of working with agents is letting one run the build safely, and that is what the rest of vx already is: explicit inputs, strict outputs, a sandbox that denies undeclared reads and any domain no task of the run lists, and a teardown that leaves nothing running when the agent’s session is cancelled. An agent that can only run declared commands against declared paths is an agent you can leave alone with the repository.

The guide is vx mcp — AI agents.

Dev servers as graph nodes: readiness instead of sleep

Thu, 10 Sep 2026 23:36:00 GMT

Some tasks do not finish. A dev server, a watcher, a database for the integration tests. Most runners either refuse to model them or model them as “run this and never wait,” which leaves the interesting problem to a sleep 5 in a shell script.

vx models them as persistent tasks and gives them the two things a graph node needs: a notion of ready, and a guaranteed end.

dev: {
  exec: {
    command: 'vite',
    persistent: { readyWhen: 'Local:' },
    timeout: 30_000,
  },
},
e2e: {
  dependsOn: ['dev'],
  exec: { command: 'playwright test' },
},

Ready is a line of output

readyWhen is a regex matched against the task’s output. The moment a line matches, the task is ready and its dependents are released; e2e starts against a server that is actually listening. The match also sees a trailing partial line, so a prompt with no newline (Listening on :3000) works.

exec.timeout bounds the wait. If the pattern never appears, vx kills the process and fails the task instead of hanging the run. A persistent task with no readyWhen is ready on spawn, which is right for a daemon nothing gates on.

No polling loop, no wait-on package, no guessed number of seconds. The server tells you when it is up, and you wrote down what it says.

The end is guaranteed

When the run finishes, every persistent task is sent SIGTERM, given a grace period, then SIGKILLed if it is still there. Nothing is left listening on a port after vx run e2e returns, whether the tests passed, failed, timed out or you pressed Ctrl-C. That last case is its own post.

Readiness escalates the same way. A server that ignores the timeout’s SIGTERM gets SIGKILL after the grace, so a wedged process cannot hold the run open.

In the foreground

vx run dev with nothing depending on it is the other common case: you want the server in your terminal and you want vx to stay attached. When the requested tasks are persistent, vx stays in the foreground until one of them exits, then reports which one and stops the rest:

vx: web#dev exited with code 1; stopping 2 other persistent tasks

A crashed server makes vx exit 1.

What it costs elsewhere

A persistent task is pinned to this machine, and so is everything that depends on it: a remote worker cannot reach a port on your laptop, and the placement stage knows that without being told. A persistent task under a sandbox gets the same grants and walls as any other, but no violation report, because the report reads the trace after the child exits and a server exits only when the run tears it down.

Persistent tasks are not cached. They have no end state to store. Their dependents can be; e2e’s key includes dev’s key, so a config change to the server re-runs the tests.

The guide, with the readiness patterns for the common servers, is Dev & long-running tasks.

Ctrl-C leaves nothing running

Thu, 10 Sep 2026 23:35:00 GMT

Ask around about any monorepo tool and you will hear the same story: a vite still holding port 5173 after the run was cancelled, a tsc -w from last Tuesday, a CI job whose cancellation left a database container running until the runner was reclaimed. A task runner spawns processes. The least it owes you is that they die when it does.

vx has one teardown, and every way a run can end goes through it.

The teardown

Every live child’s process group receives the signal vx got: SIGINT stays SIGINT, so a Ctrl-C cleanup runs, and SIGTERM or SIGHUP arrives as SIGTERM.
vx waits a grace period, two seconds by default, VX_KILL_GRACE_MS to change it.
It re-reads its registries, because a child may have spawned during the grace, and sends SIGKILL to anything still alive.
It reaps, so nothing is left as a zombie. Then the run finishes the way any run does: the summary prints, every telemetry sink flushes and every plugin tears down, each within its bound. Only then does the process exit.

The exit code says what happened: 130 after SIGINT, 143 after SIGTERM, 129 after SIGHUP, 1 when a foreground persistent task ended the run with a non-zero code. A second Ctrl-C during the grace skips the rest of it and escalates immediately, for the case where you already know the child will not listen.

Every way a run ends

The teardown is not a signal handler bolted to the side. It is the same function called from every exit path:

A signal. SIGINT, SIGTERM or SIGHUP to the vx process, including a CI cancellation. SIGHUP is the one that matters most here and is easiest to forget: a task runs in its own session, so a closing terminal no longer reaches it — only vx hears the hang-up, and unless vx passes it on the tree outlives the window.
An abort. run() is also a library call, and it takes an AbortSignal. Abort it and the same teardown runs; tasks that never started are reported as aborted, not skipped, so a summary can tell the two apart.
A readiness timeout. A persistent task whose readyWhen never matched is SIGTERMed, then SIGKILLed after the grace if it ignores that.
A foreground persistent task exiting. vx run dev with three servers up: when one exits, the other two are torn down, and vx exits 1 if that one failed.
The normal end of a run. Persistent tasks that gated other work are torn down when the graph completes.
vx watch. A Ctrl-C mid-cycle tears the cycle’s children down first and returns only once they are gone, so a cancelled watch never orphans a task.

The tests are the claim

Every one of those paths has a test that spawns a real child, records its pid to a marker file, ends the run the way that path ends it, and asserts the child is dead within the window, with a zombie counting as alive. The window is the shortest one that still fails without the fix, because a timed wait in a test is a claim about time and a generous window would hide a regression that merely got slower. “The task has started” is a marker file, never a sleep.

That is also why the grace is a named constant rather than a literal: SIGNAL_SHUTDOWN_GRACE_MS is the default, VX_KILL_GRACE_MS is the env var the tests set to 200 ms so they prove the escalation without waiting two seconds each, and a change to either is a visible diff.

One more refusal

A task can run vx itself. If it runs vx against the same workspace, the inner run would build the same graph, claim the same cache, and, on Ctrl-C, race the outer teardown for the same children. vx exports the workspace it is running into the task’s environment and refuses a nested run on it with a clear error, instead of letting the recursion look like it worked.

Watch: a content gate, not an event storm

Thu, 10 Sep 2026 23:34:00 GMT

vx watch test --all runs test in every project, then re-runs it on every change. The interesting design decisions are in what it refuses to do.

No per-event glob matching

The tempting design is to compare each filesystem event against each task’s cache.inputs.files and re-run only the tasks whose inputs matched. vx does not do this, because the cache key is already the source of truth for “does this change matter to this task,” and a second copy of that rule, written in terms of events instead of hashes, would drift from the first.

Instead, every change triggers a cycle, the cycle is the same code path as vx run, and the key decides. A change to an irrelevant file produces a fully cached cycle, typically tens of milliseconds. A change to a relevant one produces exactly the re-runs the graph implies, including downstream tasks, because the cascade is the key’s, not the watcher’s. The engineering cost of a per-event matcher is much larger than the cost of a cheap cycle, and the correctness cost of two rules is larger still.

The content gate

A task that writes into its own project is the classic watch-mode trap: it writes, the watcher sees the write, the task re-runs, forever. The usual fix is a list of ignored paths, which fails for any task whose writes were not declared.

vx ignores the declared outputs of every task in scope (and their containing directories, so a dist/** glob does not re-trigger on the dist directory being created). For everything else it gates on content: a file whose bytes did not change since the loop last saw it is not an edit. A task that rewrites its own files costs one extra cycle, which the cache serves, and then settles.

Always ignored regardless: node_modules, .git, .vx, the run’s resolved cache directory wherever --cache-dir put it, .tsbuildinfo files and editor backup files (a trailing ~).

Watchers that are actually watching

On macOS a directory watcher can return before its event stream is live, and an edit in that gap is silently lost. vx writes a probe file under every watcher and does not print vx watch: watching … until each probe’s event has arrived, re-writing on a short backoff. The line is a promise, not a hope. A directory whose watcher stays silent for two seconds is polled instead, with a warning naming the interval.

The workspace root is watched non-recursively so a lockfile or pnpm-workspace.yaml edit is heard; those move the workspace fingerprint, or, with @vzn/vx-lockfile, the keys of the projects they reach.

The rest of the contract

Events during a cycle queue and drain after it; re-runs are debounced about 150 ms after the last event.
A failed cycle prints its failure and waits for the next change; it does not exit the loop. That matches turbo watch and nx watch.
Ctrl-C prints vx watch: stopped, tears down the in-flight cycle’s children and exits 0 only once they are gone.
Flags that describe one run (--dry, --graph, --summarize, --profile, --report, --report-file, --verbosity) are rejected up front, because a loop has no single run.
Persistent tasks re-spawn each cycle. For a server that should stay up across edits, the tool’s own watch (vite, tsc -b -w) is the right layer.

Reference: vx watch.

Flaky is a claim only declared inputs can back

Thu, 10 Sep 2026 23:33:00 GMT

Flaky-test detection is one of the features that usually lives behind a cloud login. Nx sells it. It is also one of the easiest things to get wrong, because “flaky” is used to mean “failed and I do not want to look,” and a tool that agrees with that use is teaching a team to ignore red.

vx defines it narrowly, and the narrow definition is the feature.

The definition

A task is flaky when one of two things is on record:

its exact cache key has both passed and failed, this run included (a cache hit counts as a pass; it replayed one), or
it needed a retry this run (exec.retries or --retry) and then passed.

A failure on a key that never passed is a break. The inputs changed and the result is red, which is what a red run usually means, and it is not listed. Only tasks with a cache block are judged at all: “same inputs, different outcome” is a claim only declared inputs can back. A task without them is keyed on its config alone, and two runs of it are not the same inputs in any meaningful sense.

What you see

After the footer, a run names the tasks it just proved nondeterministic:

  Flaky:    2 tasks with the same inputs both passing and failing on record
    ✗ app#test — failed on inputs that passed 3× before
    ✓ api#e2e — passed on inputs that failed 1× before · 2 attempts this run

The section is not printed when nothing was flaky. vx info keeps the standing list across runs, --summarize carries it as typed data (flaky: { passes, failures, attempts } on the task, so a consumer can tell a break from a flake without parsing text), and the MCP server reports the same signal to an agent — getRunHistory as each task’s failure mode, getWorkspaceInfo as the standing list — so an agent does not learn to shrug at a repeated failure on changing inputs.

Why it is free

The information was already there. Every cache entry records its key, its outcome and its run. Asking “has this key ever had the other outcome” is one probe of the failed-row index on a green miss, and nothing at all on a run that executed nothing. There is no upload because there is nothing to upload to; the history is the local cache.db that vx why and vx last already read.

That is also why it works on the first day. A service-side detector needs a fleet of runs before it can say anything. vx’s needs the second run of the same key on your machine.

What it is not

It is not a retry policy. exec.retries is separate and explicit, and a task that passes on retry is reported as flaky rather than quietly made green. It is not a quarantine: nothing is skipped, ever, because a skip is a silent pass. It is a label on a fact, kept where you can act on it, and the act is yours.

From Turborepo: run it as it is, then migrate at your pace

Thu, 10 Sep 2026 23:32:00 GMT

vx is shaped like Turborepo on purpose. Same per-package model, same dependsOn micro-syntax ('build', '^build', 'pkg#build'), same --filter DSL, same --affected. The migration is easy because almost nothing has to change in how you think about the graph; what changes is where the config lives and what it can say.

Step zero: do not migrate

turbo() from @vzn/vx-migrate fills vx’s project stage from your existing turbo.json and each package’s scripts. One file, and the repository runs under vx:

vx.workspace.ts

import { defineWorkspace } from '@vzn/vx'
import { turbo } from '@vzn/vx-migrate'

export default defineWorkspace({ plugins: [turbo()] })

bun add -d @vzn/vx @vzn/vx-migrate   # or npm / pnpm / yarn
vx run build --all

That is how solidjs/solid was benchmarked: five packages, pnpm 9, Turbo 2.10.10 as the repo’s own dependency, and vx on top of the untouched turbo.json. Both tools see the same graph and restore the same 64 output files; vx’s warm restore is 66 ms to Turbo’s 127.

Whatever the mapping cannot express becomes a warning on every run, which is the same list bunx @vzn/vx-migrate --dry prints once. A package that writes its own vx.config.ts keeps it; the plugin fills and never overwrites. So you can migrate one package at a time, or never.

Step one: let the tool write the files

bunx @vzn/vx-migrate --dry   # preview the generated files and a report
bunx @vzn/vx-migrate         # write them; never overwrites without --force

@vzn/vx-migrate is its own package so it runs before any vx file exists. It reads the root pipeline and any per-package extends, inlines the matching package.json script as the task’s command, and emits one vx.config.ts per package. It emits a task only where the script exists. Anything it cannot infer becomes a TODO(vx-migrate) comment, never a silently wrong value. It renders from the same mapper turbo() runs, so the files say exactly what the plugin was already doing.

What maps, and what is better

`turbo.json`	`vx.config.ts`
`tasks` / `pipeline`	`tasks`
`dependsOn`	`dependsOn`, identical syntax
`inputs` / `outputs`	`cache.inputs.files` / `cache.outputs.files`
`env`	`cache.inputs.env` and `exec.env.passThrough`
`passThroughEnv`	`exec.env.passThrough`
`cache: false`	omit the `cache` block
`persistent: true`	`exec.persistent: { readyWhen }`
`extends`	a package task merges over the root’s; `false` alone opts out, `false` + keys runs on those alone
`outputLogs`	no per-task knob: the per-run `--output-logs` flag
`$TURBO_ROOT$/file`	`cache.inputs.workspaceFiles`
`dotEnv` (Turbo 1)	`cache.inputs.runtime`: a probe that hashes the `.env` files
`command` (Turbo 2.11)	the task’s `exec.command`; `null` is no task
`description`	the task’s `description`
`globalDependencies`, `globalEnv`, `globalPassThroughEnv`, `globalDotEnv`	a generated `vx-preset.ts` you import and spread

Those are every key the mapper knows. Any other key in a task becomes a TODO naming it, so nothing is dropped silently.

Three things you get that the JSON could not give you:

The command is in the config. Turborepo runs the script with the task’s name; vx makes exec.command explicit. A task is one shell command, and you can read it where it is declared.
Inputs are required and explicit. The migration writes Turbo’s default, every file in the package, as **/*, where you can see and narrow it; the sandbox can then prove them.
Presets are imports. globalDependencies becomes a constant in a file every config imports, and the resolved-config hash sees it. No list to keep in sync.

The deliberate divergences

A bare task name never widens an anchored task’s scope. In Turbo, turbo run web#lint build also runs web#build; in vx, build takes the filter scope and web#lint stays anchored.
No --parallel. It exists in Turbo as an escape hatch for over-declared edges. dependsOn in vx is explicit, so the hatch is --concurrency 1 to serialise and nothing to drop edges.
Failure propagation starts one notch further along. Turbo stops the run at the first failure; a vx run with no flag is deps-ok — a task runs when its own dependencies succeeded, and only its dependents are skipped. --continue=never is Turbo’s default behaviour, and bare --continue is always, which is what bare --continue means in Turbo too.

Every other Turbo behaviour a user would reach for is pinned by a parity case that runs vx’s real CLI against the Turbo contract it stands in for. The full guide, with before/after configs, is Migrate from Turborepo.

From Nx: keep the graph, drop the platform

Thu, 10 Sep 2026 23:31:00 GMT

Leaving Nx is a bigger step than leaving Turborepo, and the honest version of this post says why before it says how. You keep the things you relied on: the task graph, caching, affected. You shed the daemon, the executor plugins and the generators. If you were using the generators as a scaffolding system, that is a real loss and vx does not replace it. If you were using Nx as a task runner, everything below is a simplification.

Try it unchanged first

Nothing has to be written to find out what vx does for the repo. nx() from @vzn/vx-migrate fills vx’s project stage from the resolved project graph, so every project’s targets are vx tasks with their inputs, outputs and dependsOn, and vx run build --all runs what nx run-many -t build ran, under vx’s cache:

// vx.workspace.ts — the only file
import { defineWorkspace } from '@vzn/vx'
import { nx } from '@vzn/vx-migrate'

export default defineWorkspace({ plugins: [nx()] })

Executor targets keep running as executors. Each becomes an nx-exec line that runs the executor in its own Node process through Nx’s public runExecutor, with the executor and its options on the command line, so vx’s key sees them and vx show prints what runs. A warm vx run never runs Nx at all; the plugin exports the graph again only when the worktree changes (nx.json, a manifest, a source file). (Added 2026-09-22.)

The one real shift: executors become commands

An Nx target runs through an executor, a plugin that wraps a tool behind a JSON options object:

{ "build": { "executor": "@nx/js:tsc", "options": { "main": "src/index.ts", "tsConfig": "tsconfig.lib.json" } } }

vx has no executors. A task is a shell command. When you migrate, an executor target is written as the nx-exec line that runs it — no placeholder, the repo runs on day one — and, target by target, that line becomes the command the executor was wrapping:

build: {
  exec: { command: 'tsc -b tsconfig.lib.json' },
  cache: { inputs: { files: ['src/**', 'tsconfig.lib.json'] }, outputs: { files: ['dist/**'] } },
}

More explicit, more portable, and one less layer between you and the tool’s own documentation. Every executor runs through nx-exec until you replace it, nx:run-commands targets are the shell they already were, and the server executors — @nx/vite:dev-server, @nx/vite:preview-server, @nx/webpack:dev-server, @nx/next:server, @nx/storybook:storybook and @angular-devkit/build-angular:dev-server — come through as persistent tasks, whatever the target is called. Nothing is silently wrong.

Read the graph Nx actually uses

Nx’s real configuration is not nx.json; it is the resolved project graph, after every plugin has inferred its targets. The migration reads that:

nx graph --file=.nx/workspace-data/project-graph.json
bun add -d @vzn/vx
bunx @vzn/vx-migrate --dry   # preview the generated vx.config.ts files and a report
bunx @vzn/vx-migrate         # write them; never overwrites without --force

If only nx.json is present, the tool tells you to run the nx graph command rather than guessing at plugin-inferred targets. The generated files freeze that snapshot as static config: review them, replace the nx-exec lines when you are ready, fill the TODOs.

What maps

Nx	vx
a project’s `targets`	`tasks`
`dependsOn` (`^build`, …)	`dependsOn`, same syntax
`inputs` / `namedInputs` (resolved)	`cache.inputs.files`
`{workspaceRoot}/file`	`cache.inputs.workspaceFiles`
`outputs`	`cache.outputs.files`
`nx affected`	`vx run … --affected[=<base>]`
`nx run-many --projects`	`vx run … --filter`
`parallelism: false`	`--concurrency 1`, or a schedule-plugin reservation at or above the worker count
`nx watch`	`vx watch`
`targetDefaults`	already applied in the graph; share them as a preset you import

namedInputs and targetDefaults never reach the migration as themselves: the resolved graph has already applied them, so what gets written is each task’s own cache.inputs.files and its own values. Neither exists in vx and neither will — a TypeScript config composes, so a shared input list is an import.

What you drop, and what replaces it

The daemon. vx has none. On the 3,270-task benchmark a fully cached run is 510ms to Nx’s 3.59s, and the cold run burns 34.61s of CPU to Nx’s 114m 06s.
Nx Cloud’s distributed execution. The seam is public: @vzn/vx-reapi runs tasks on any Bazel Remote Execution API pool. There is no first-party service and there will not be one.
Nx Cloud’s remote cache. nxCache() from @vzn/vx-migrate speaks the self-hosted /v1/cache wire, so an existing self-hosted server keeps working. Any other wire is a cache plugin.
Nx Cloud’s flaky-test detection. vx detects flaky tasks from the local run history: a key that has both passed and failed on record, no service involved.
The graph visualiser. vx run build --all --graph renders DOT; vx show prints what a run would see.

The full guide, with the trade-offs spelled out one by one, is Migrate from Nx.

Benchmarks you can re-run

Thu, 10 Sep 2026 23:30:00 GMT

Benchmark numbers are only worth what the method behind them is worth. Here is the method, then the numbers, then how to read the ones that flatter vx less than the headline.

One number first, because it is the one that decides whether a runner is worth having. Imagine your tasks take three minutes on their own. What does the tool add on top? On the 3,270-task workspace below the tasks alone take 3m 38s under an ideal schedule. vx finishes the cold build in 3m 46s: eight seconds of overhead. Turborepo finishes in 5m 13s, a minute and a half. Nx finishes in 34m 44s, half an hour. Every warm number on this page is a consequence of the same discipline, but this is the one you feel on every uncached build.

Synthetic: the same graph, three runners

bun packages/vx-bench/compare.ts 100 11 1 scaffolds one workspace of 1,090 packages in 100 dependency layers, about 30 dependencies per package and three tasks each, 3,270 task nodes, and runs vx, Turborepo and Nx across the same three cache states: cold, warm with outputs wiped (restore), and warm with nothing touched (no-op). The run below is Turbo 2.10.12 and Nx 23.2.0 on macOS arm64 with 10 cores, every runner pinned to concurrency 10. Fairness is deliberate: vx runs as the compiled binary users install, Turbo and Nx run as a user would with their daemons on, and the runners are measured strictly one at a time, each daemon stopped before the next runner is timed so it cannot idle-contend for CPU. build and test are sleep 1, so the numbers isolate the runner’s own overhead from compilation.

build test --all, the tasks’ own ideal schedule being 3m 38s:

Runner	Cold build	Fully cached	Cold build CPU
vx	3m 46s (+0:08)	510ms	34.61s
Turborepo	5m 13s (+1:35)	760ms	1m 13s
Nx	34m 44s (+31:06)	3.59s	114m 06s

The first two columns are wall clock; the third is CPU time (user plus system, of the invocation and every child it waited for), because on a synthetic workspace the tasks sleep and that column measures the runner’s own work per task. A daemon that outlives the invocation is not counted, so Turbo’s and Nx’s are floors. It is the fairest number for “what does the tool cost me,” and Nx’s is not a typo. The wall-clock rows, the theoretical baseline and the measured floors (one git walk is 67ms on that machine) are in Benchmarks.

Real: solidjs/solid under its own `turbo.json`

A synthetic workspace cannot tell you what happens with rollup, tsc and vitest in the loop. So the second benchmark is solidjs/solid at a pinned commit: five packages, pnpm 9, Turbo 2.10.10 as the repository’s own dependency, Node 22. vx is put on top through turbo() from @vzn/vx-migrate, a two-line vx.workspace.mjs, no config rewritten, so both tools see the same graph and restore the identical 64 output files. vx runs as its compiled binary; Turbo 2.10 uses no daemon for turbo run (deprecated there since 2.9), so both pay their own discovery. Four cores, Linux, arms interleaved, medians.

`build` (4 tasks)	vx	Turbo 2.10.10
cold (caches and outputs wiped)	40.6 s	45.5 s (1.12×)
warm, outputs wiped (restore)	66 ms	127 ms (1.9×)
warm, nothing wiped (no-op)	51 ms	95 ms (1.9×)

`test test-types` (7 tasks)	vx	Turbo 2.10.10
cold	53.6 s	58.2 s (1.09×)
warm, restore	80 ms	166 ms (2.1×)
warm, no-op	59 ms	93 ms (1.6×)

Read the cold rows honestly

The cold rows are rollup, tsc and vitest. The runner is a few percent of them. The 4–5 s gap is Turbo’s per-task work around the same commands, its ** default inputs hashed per package, its log capture, its cache write, and it was not profiled to the frame here. A cold build is dominated by your tools, in both runners, and any tool that tells you otherwise is measuring something else.

The warm rows are the product. With everything cached, vx answers in 50–80 ms where Turbo takes 95–170 ms, and the restore case, which is what a CI job or a fresh checkout does, is where the ratio is widest. Neither has a daemon to turn on here: Turbo’s no longer serves turbo run, and vx has none.

The method is the point

Every warm-path change in vx’s history shipped with a number measured this way: A/B arms interleaved, min-of-N, the “before” arm checked out into an immutable git worktree, one workspace copy per arm pre-warmed by that arm. Where the headroom went, release by release, is a table in Benchmarks. The scripts are in the repository: packages/vx-bench/compare.ts for the synthetic workspace and packages/vx-bench/real/turbo-repo.sh for any Turbo repository you want to point it at. If a number here does not reproduce on your machine, that is a bug report.

Hello, vx

Thu, 10 Sep 2026 00:00:00 GMT

Announcements, design notes and release write-ups for vx land here. The first one is short.

vx runs and caches a task graph, correctly, and stops there. It discovers the projects in a JavaScript monorepo, evaluates each vx.config.ts, builds one task graph, derives a content-addressed key per task and schedules the work. A fully cached run answers in tens of milliseconds; a cold run spends its time in your tools, not in the runner. Everything distributed — remote caches, remote execution, telemetry, AI agents — is a plugin on a documented seam, never a feature inside.

Where to look next:

Quickstart — a workspace running under vx in a few minutes, or add vx to an existing repo without rewriting a config (a Turbo repo runs as it is).
Benchmarks — synthetic workspaces up to 3,270 tasks, and a real Turbo monorepo measured against Turbo itself.
Architecture — the pipeline, its seams, and why the cache can be trusted.

Release write-ups will follow here as they ship.

vx | Blog

What vx is, and what it refuses to be

The pipeline

What a task is

What is not inside

Why the boundary matters

Why vx is fast: five decisions, not a trick

1. The cache key is already in git’s index

2. Bitsets where others walk

3. Strict output ownership makes restore cheap

4. One artifact format end to end

5. Nothing runs when nothing is needed

The method behind the numbers

There was no choice on the market

Turborepo: fast, and it stops

Nx: scales, and it is a product

The gap

The bar

Performance, modularity, extensibility. In that order.

The nine principles

The rejected list

Rules learned the hard way

Your cache key is already in git's index

Twelve parts, one chain

Ask git, once

Boundaries are hard

What the key deliberately ignores

Configs are programs. Hash what they evaluate to.

The key sees the object

Evaluating a program has a cost, so gate the cache

Freezing the evaluation: vx lock

Why not named inputs

The tree is exactly the snapshot

The rule

Why it is also the fast path

What the wipe never touches

The consequences you feel

Cascade through dependencies by folding input keys, never outputs

Two designs

Keys before execution

What “pure input” means precisely

No daemon, on purpose

What a daemon costs

What replaced it

The invariant, stated plainly

Bitsets, popcount, and a scheduler tick that re-scans nothing

Closures as bitsets

The tick

Two tiers: misses own the pool, hits backfill

Admission is part of the tick

Explicit over magical: why vx never guesses your inputs

What inference actually produces

The cost, honestly

Explicit everywhere else too

The sandbox: turning a declaration into a boundary

One allow-list, no inheritance

Why it derives nothing from cache

What a violation looks like

How it is built

Where it fits

Why did this re-run?

What it reads

Six endings for an unchanged key

The same answer for machines

A lockfile bump should re-key two tasks, not sixty

Key each project on what it can reach

--affected follows the same claim

Measured in the repository that ships it

Config in TypeScript, and why there are no named inputs

The shape

Composition is an import

What a config may not do

Freezing it

The migration path

vx lock: freezing what the key sees

Three verbs

The check that a hash cannot do

What the lock is not

Where it came from

One command per task; the shell is the API

Freezing the evaluation: `vx lock`

Why it derives nothing from `cache`

`--affected` follows the same claim

`node_modules`: install as an action

Real: solidjs/solid under its own `turbo.json`