@vzn/vx 0.0.135 → 0.0.137

package/README.md

@@ -5,8 +5,8 @@
 <h1 align="center">vx</h1>
 
 <p align="center">
-  <strong>A fast, correct task runner and build cache for JavaScript monorepos.</strong><br>
-  One binary. No daemon, no cloud, no account.
+  <strong>A faster runner for your Turborepo or Nx repo.</strong><br>
+  Keep <code>turbo.json</code> or <code>nx.json</code> and run it unchanged.
 </p>
 
 <p align="center">
@@ -16,29 +16,52 @@
   <a href="https://vznjs.github.io/vx/"><img src="https://img.shields.io/badge/docs-vznjs.github.io%2Fvx-c6f84e" alt="Documentation"></a>
 </p>
 
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://vznjs.github.io/vx/bench-dark.svg">
-    <img src="https://vznjs.github.io/vx/bench-light.svg" width="760" alt="Bar chart: vx against Turborepo and Nx on a 3,270-task graph, cold and fully cached.">
-  </picture>
-</p>
+<!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
 
-<p align="center">
-  <em>Same graph, same commands, same concurrency. <a href="https://vznjs.github.io/vx/benchmarks/">Methodology and how to reproduce it</a>.</em>
-</p>
+| 1,090 packages, 3,270 tasks      | vx         | Turborepo  | Nx       |
+| -------------------------------- | ---------- | ---------- | -------- |
+| Cold build: time the runner adds | **8 s**    | 1 min 35 s | 31 min   |
+| Cold build: CPU burned           | **35 s**   | 1 min 13 s | 114 min  |
+| Fully cached run                 | **510 ms** | 760 ms     | 3.59 s   |
+| Overhead per package             | **8 ms**   | 88 ms      | 1,712 ms |
 
-<!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
+Time added is the wall time over the tasks' own ideal schedule (3 min 38 s).
+Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).
 
-The runner adds seconds to a cold build where others add minutes. On a
-1,090-package graph of 3,270 tasks whose ideal schedule is 3m 38s,
-vx finishes in 3m 46s (+0:08), Turborepo in 5m 13s (+1:35) and Nx in
-34m 44s (+31:06) — 8 ms of overhead per package against 88 ms and
-1,712 ms, so the graph can grow and the runner stays in seconds. The cold build
-burns 35 s of CPU in vx, 73 s in Turborepo and 114 minutes in Nx; a
-fully cached run replays the graph in 510 ms.
 <!-- bench:end -->
 
-Measured on fourteen real Turborepo, Nx, moon, wireit and lage repos too: [tried on real repos](#tried-on-real-repos).
+## Try it on your repo
+
+In a Turborepo or Nx workspace, add one file:
+
+```ts
+// vx.workspace.ts
+import { defineWorkspace } from '@vzn/vx'
+import { turbo } from '@vzn/vx-migrate' // Nx: import { nx } and use nx()
+
+export default defineWorkspace({ plugins: [turbo()] })
+```
+
+Then:
+
+```sh
+npm install -D @vzn/vx @vzn/vx-migrate
+npx vx run build --all      # your turbo.json or Nx targets, run by vx
+npx vx run build --all      # again: up-to-date in milliseconds
+```
+
+Nothing is rewritten. `@vzn/vx-migrate` is not on npm yet (first publish
+pending); [`examples/turbo`](examples/turbo) runs this setup on every
+commit.
+
+## Why it is faster
+
+- **Nothing boots per task.** No daemon, no Node process per task: vx
+  spawns your command directly.
+- **Hashing without reading.** On a clean tree, cache keys come from
+  git's index; no file is read.
+- **One pass over the repo.** One git walk per run; each stat and
+  lookup happens once.
 
 ## Install
 
@@ -93,48 +116,20 @@ runs on every commit. More: [Quickstart](https://vznjs.github.io/vx/quickstart/)
 [CLI](packages/vx/docs/cli.md) · [every config field](packages/vx/docs/schema.md) ·
 [playground](https://vznjs.github.io/vx/playground/) (the planner, in your browser).
 
-## Already on Turborepo, Nx or moon?
-
-Keep your `turbo.json`, Nx project graph or `.moon/`. Two lines run it
-under vx, with nothing rewritten:
-
-```ts
-// vx.workspace.ts
-import { defineWorkspace } from '@vzn/vx'
-import { turbo } from '@vzn/vx-migrate' // or: nx, moon
+## Configs of your own
 
-export default defineWorkspace({ plugins: [turbo()] })
-```
-
-When you want configs of your own, one command writes them:
-
-```sh
-bunx @vzn/vx-migrate      # vx.config.ts per package, from turbo.json, an Nx graph or .moon/
-```
-
-The written configs derive the same cache keys, so what `turbo()` cached
-still hits: [`examples/turbo`](examples/turbo) runs both steps on every
-commit.
-
-`turboCache()` and `nxCache()` keep the remote cache you have (Turbo's
-`/v8/artifacts` API, Vercel's included, or Nx's `/v1/cache`). What each
-Turbo and Nx feature is in vx, pinned by a test:
-[parity map](packages/vx/docs/parity.md) ·
+When you want them, `bunx @vzn/vx-migrate` writes a `vx.config.ts` per
+package from `turbo.json` or the Nx graph. They derive the same cache
+keys, so what `turbo()` cached still hits. `turboCache()` and `nxCache()`
+keep your Turbo or Nx remote cache. [Parity map](packages/vx/docs/parity.md) ·
 [migration guide](https://vznjs.github.io/vx/guides/migrate/).
 
-> The plugin packages (`@vzn/vx-migrate` and the rest below) are not on
-> npm yet; only `@vzn/vx` is.
-
-## Why vx
+## More than speed
 
 - **A cache you can trust.** Configs are TypeScript, evaluated before
   hashing, so imports and computed values are part of the key. Declared
   outputs are wiped before every run and every restore: no stale file
-  survives. On a clean tree keys come from git's index, with no file
-  read.
-- **Fast where it counts.** Milliseconds of overhead per package, no
-  daemon, one git walk per run. Every optimization is recorded with
-  the invariant that keeps it valid ([ledger](packages/vx/docs/optimizations.md)).
+  survives.
 - **Sandboxed tasks.** Opt in per task: a read the task did not
   declare fails the build instead of poisoning the cache.
 - **Clean exits.** Ctrl-C reaps every child. No orphaned dev servers.
@@ -145,27 +140,23 @@ Turbo and Nx feature is in vx, pinned by a test:
 
 ## Tried on real repos
 
-Fourteen public monorepos, each run with its own `turbo.json`, Nx graph, moon, wireit or lage config
-and nothing rewritten, against the tool it ships with. Both tools on the same machine and
-tasks per row, medians; vx first, theirs second. Where the other tool
-wins, the row says so.
-
-| Repo                                                                    | Against | Cold build            | Restore outputs | Nothing to do       |
-| ----------------------------------------------------------------------- | ------- | --------------------- | --------------- | ------------------- |
-| [solidjs/solid](https://github.com/solidjs/solid)                       | Turbo   | 40.6 s / 45.5 s       | 66 ms / 127 ms  | 51 ms / 95 ms       |
-| [withastro/astro](https://github.com/withastro/astro)                   | Turbo   | 48.0 s / 57.9 s       | 478 ms / 1.43 s | 249 ms / 1.38 s     |
-| [payloadcms/payload](https://github.com/payloadcms/payload)             | Turbo   | 126.9 s / 127.5 s     | 3.44 s / 3.46 s | 256 ms / **237 ms** |
-| [medusajs/medusa](https://github.com/medusajs/medusa)                   | Turbo   | 308 s / 315 s         | 3.86 s / 7.16 s | 947 ms / 3.29 s     |
-| [n8n-io/n8n](https://github.com/n8n-io/n8n)                             | Turbo   | 137.2 s / **133.7 s** | 8.27 s / 12.5 s | 842 ms / 1.36 s     |
-| [calcom/cal.com](https://github.com/calcom/cal.com)                     | Turbo   | 245.7 s / 250.7 s     | 17.4 s / 19.9 s | 14.7 s / 18.5 s     |
-| [TanStack/query](https://github.com/TanStack/query)                     | Nx      | 47.4 s / 55.1 s       | 656 ms / 1.98 s | 174 ms / 1.88 s     |
-| [strapi/strapi](https://github.com/strapi/strapi)                       | Nx      | 238.2 s / 245.7 s     | 1.61 s / 3.94 s | 341 ms / 4.02 s     |
-| [novuhq/novu](https://github.com/novuhq/novu)                           | Nx      | 291.2 s / 299.4 s     | 3.10 s / 9.05 s | 655 ms / 8.55 s     |
-| [TanStack/router](https://github.com/TanStack/router)                   | Nx      | 199.9 s / 226.7 s     | 1.00 s / 3.33 s | 505 ms / 3.21 s     |
-| [refinedev/refine](https://github.com/refinedev/refine)                 | Nx      | 96.2 s / 105.9 s      | 1.06 s / 1.19 s | 303 ms / 1.16 s     |
-| [kindspells/astro-shield](https://github.com/kindspells/astro-shield)   | moon    | 2.64 s / 3.78 s       | 125 ms / 2.46 s | 111 ms / 2.37 s     |
-| [FormidableLabs/spectacle](https://github.com/FormidableLabs/spectacle) | wireit  | 21.5 s / 22.2 s       | 394 ms / 574 ms | 387 ms / 593 ms     |
-| [microsoft/lage](https://github.com/microsoft/lage)                     | lage    | 32.4 s / **29.4 s**   | 730 ms / 1.70 s | 284 ms / 1.56 s     |
+Eleven public monorepos, each run with its own `turbo.json` or Nx graph
+and nothing rewritten, against the tool it ships with. Same machine and
+tasks per row, medians; vx first, theirs second.
+
+| Repo                                                        | Against | Cold build            | Restore outputs | Nothing to do       |
+| ----------------------------------------------------------- | ------- | --------------------- | --------------- | ------------------- |
+| [solidjs/solid](https://github.com/solidjs/solid)           | Turbo   | 40.6 s / 45.5 s       | 66 ms / 127 ms  | 51 ms / 95 ms       |
+| [withastro/astro](https://github.com/withastro/astro)       | Turbo   | 48.0 s / 57.9 s       | 478 ms / 1.43 s | 249 ms / 1.38 s     |
+| [payloadcms/payload](https://github.com/payloadcms/payload) | Turbo   | 126.9 s / 127.5 s     | 3.44 s / 3.46 s | 256 ms / **237 ms** |
+| [medusajs/medusa](https://github.com/medusajs/medusa)       | Turbo   | 308 s / 315 s         | 3.86 s / 7.16 s | 947 ms / 3.29 s     |
+| [n8n-io/n8n](https://github.com/n8n-io/n8n)                 | Turbo   | 137.2 s / **133.7 s** | 8.27 s / 12.5 s | 842 ms / 1.36 s     |
+| [calcom/cal.com](https://github.com/calcom/cal.com)         | Turbo   | 245.7 s / 250.7 s     | 17.4 s / 19.9 s | 14.7 s / 18.5 s     |
+| [TanStack/query](https://github.com/TanStack/query)         | Nx      | 47.4 s / 55.1 s       | 656 ms / 1.98 s | 174 ms / 1.88 s     |
+| [strapi/strapi](https://github.com/strapi/strapi)           | Nx      | 238.2 s / 245.7 s     | 1.61 s / 3.94 s | 341 ms / 4.02 s     |
+| [novuhq/novu](https://github.com/novuhq/novu)               | Nx      | 291.2 s / 299.4 s     | 3.10 s / 9.05 s | 655 ms / 8.55 s     |
+| [TanStack/router](https://github.com/TanStack/router)       | Nx      | 199.9 s / 226.7 s     | 1.00 s / 3.33 s | 505 ms / 3.21 s     |
+| [refinedev/refine](https://github.com/refinedev/refine)     | Nx      | 96.2 s / 105.9 s      | 1.06 s / 1.19 s | 303 ms / 1.16 s     |
 
 **Bold** marks the other tool winning. Versions, revisions, scopes and
 harness per repo: [benchmarks](packages/vx/docs/benchmarks.md) (astro
@@ -173,46 +164,35 @@ and refine as re-measured on 2026-09-27, the rest 2026-09-10 and -11).
 
 ## How it compares
 
-|                           | vx                                        | Turborepo                      | Nx               | moon²                          |
-| ------------------------- | ----------------------------------------- | ------------------------------ | ---------------- | ------------------------------ |
-| Fully cached, 1,090 pkgs¹ | **510 ms**                                | 760 ms                         | 3.59 s           | not measured                   |
-| Config                    | TypeScript, evaluated into the cache key  | JSON (static)                  | JSON (static)    | YAML, Pkl and others (static)  |
-| Output ownership          | **Strict**: wiped before exec and restore | Additive (stale files survive) | Additive         | Glob outputs pruned on restore |
-| Clean-tree hashing        | **Zero reads** (git index OIDs)           | git OIDs                       | re-hash / daemon | `git hash-object`              |
-| Daemon required for speed | **No**                                    | Optional                       | Yes              | Optional (experimental)        |
-| Per-task sandbox          | **Yes**: kernel-level, opt-in             | No                             | No               | No                             |
-| Plugin API                | **Yes**: every pipeline stage             | No                             | Yes (TS-tied)    | WASM toolchains, extensions    |
-| OTel CI/CD spans          | **Yes**: `otel()` plugin, no OTel SDK     | No                             | Paid             | No                             |
-| Install                   | **Single binary**; no Bun, Node optional  | npm + Node                     | npm + Node       | Single binary                  |
-
-¹ Warm, nothing to rebuild, the graph charted above. Every gap, and
-when another tool is the better pick:
+|                           | vx                                        | Turborepo                      | Nx               |
+| ------------------------- | ----------------------------------------- | ------------------------------ | ---------------- |
+| Config                    | TypeScript, evaluated into the cache key  | JSON (static)                  | JSON (static)    |
+| Output ownership          | **Strict**: wiped before exec and restore | Additive (stale files survive) | Additive         |
+| Clean-tree hashing        | **Zero reads** (git index OIDs)           | git OIDs                       | re-hash / daemon |
+| Daemon required for speed | **No**                                    | Optional                       | Yes              |
+| Per-task sandbox          | **Yes**: kernel-level, opt-in             | No                             | No               |
+| Plugin API                | **Yes**: every pipeline stage             | No                             | Yes (TS-tied)    |
+| OTel CI/CD spans          | **Yes**: `otel()` plugin, no OTel SDK     | No                             | Paid             |
+| Install                   | **Single binary**; no Bun, Node optional  | npm + Node                     | npm + Node       |
+
+Every gap, and when another tool is the better pick:
 [comparison](packages/vx/docs/comparison.md) ·
 [vx, Turborepo, Nx, Bazel](https://vznjs.github.io/vx/compare/).
 
-² From moon's own docs (2026-09-28): [config](https://github.com/moonrepo/moon/blob/master/website/docs/config/overview.mdx),
-[outputs](https://github.com/moonrepo/moon/blob/master/website/docs/config/project.mdx),
-[hashing](https://github.com/moonrepo/moon/blob/master/website/docs/guides/debug-task.mdx),
-[daemon](https://github.com/moonrepo/moon/blob/master/website/docs/guides/daemon.mdx),
-[plugins](https://github.com/moonrepo/moon/blob/master/website/docs/guides/wasm-plugins.mdx),
-[install](https://github.com/moonrepo/moon/blob/master/website/docs/install.mdx);
-they describe no per-task sandbox and no OpenTelemetry export. Already on
-moon: `moon()` runs it unchanged.
-
 ## Plugins
 
 Declared in `vx.workspace.ts`. Without one, vx runs and caches on this
 machine.
 
-| Package                                                    | What it adds                                                                    |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| [`@vzn/vx-migrate`](packages/vx-migrate)                   | Run a Turbo, Nx or moon repo unchanged; write configs; keep a Turbo or Nx cache |
-| [`@vzn/vx-reapi`](packages/vx-reapi)                       | Remote cache and remote execution over Bazel's REAPI (NativeLink, BuildBuddy)   |
-| [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn                |
-| [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                  |
-| [`@vzn/vx-github`](packages/vx-github)                     | GitHub Actions job summary and Checks API                                       |
-| [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: a read-only MCP server for AI coding agents                           |
-| [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                            |
+| Package                                                    | What it adds                                                                  |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| [`@vzn/vx-migrate`](packages/vx-migrate)                   | Run a Turbo or Nx repo unchanged; write configs; keep its remote cache        |
+| [`@vzn/vx-reapi`](packages/vx-reapi)                       | Remote cache and remote execution over Bazel's REAPI (NativeLink, BuildBuddy) |
+| [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn              |
+| [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                |
+| [`@vzn/vx-github`](packages/vx-github)                     | GitHub Actions job summary and Checks API                                     |
+| [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: a read-only MCP server for AI coding agents                         |
+| [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                          |
 
 Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
 [architecture](packages/vx/docs/architecture.md).

package/launcher.mjs

@@ -105,7 +105,7 @@ const source = join(here, sourceEntry)
 if (bin !== undefined) {
   run(bin, args)
 } else if (existsSync(source) && hasBun()) {
-  run('bun', [source, ...args])
+  run('bun', ['--no-env-file', '--no-install', source, ...args])
 } else {
   const supported = SUPPORTED.join(', ')
   process.stderr.write(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.135",
+  "version": "0.0.137",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.135",
-    "@vzn/vx-linux-arm64": "0.0.135",
-    "@vzn/vx-darwin-x64": "0.0.135",
-    "@vzn/vx-darwin-arm64": "0.0.135"
+    "@vzn/vx-linux-x64": "0.0.137",
+    "@vzn/vx-linux-arm64": "0.0.137",
+    "@vzn/vx-darwin-x64": "0.0.137",
+    "@vzn/vx-darwin-arm64": "0.0.137"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/bin.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env -S bun --no-env-file
+#!/usr/bin/env -S bun --no-env-file --no-install
 import { registerCoreAlias, run } from './cli/index.js'
 import {
   fsRefusalHint,

package/src/orchestrator/hit-restore.ts

@@ -20,7 +20,14 @@ import {
   WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
 import type { TaskOutcome } from '../graph/index.js'
-import { asTrees, secretMask, span, taskGlob, wholeSubtreePrefixes } from '../util/index.js'
+import {
+  asTrees,
+  secretMask,
+  span,
+  splitNegations,
+  taskGlob,
+  wholeSubtreePrefixes,
+} from '../util/index.js'
 import type { ExecuteArgs } from './execute-task.js'
 import { entryHolds } from './miss-save.js'
 
@@ -51,7 +58,10 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
   const outputs = cacheCfg?.outputs.files ?? []
   const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
   const anyOutputs = outputs.length > 0 || wsOutputs.length > 0
-  const dirPrefixes = wholeSubtreePrefixes(outputs)
+  // The directories the positive globs cover whole. A `!` entry inside one
+  // leaves the snapshot sound: a file added or removed there still bumps a
+  // recorded directory, and the walk that follows applies the `!` (A-46).
+  const dirPrefixes = wholeSubtreePrefixes(splitNegations(outputs).positive)
   const cleanArgs = {
     projectDir: node.projectDir,
     outputs,

package/src/orchestrator/run-artifacts.ts

@@ -15,7 +15,7 @@
 
 import path from 'node:path'
 import { isGroupTask, type TaskOutcome } from '../graph/index.js'
-import { tallyOutcomes } from './tally.js'
+import { tallyOutcomes, type Tally } from './tally.js'
 import type { FlakyFinding } from './failure-mode.js'
 
 export interface SummarizeArgs {
@@ -36,8 +36,45 @@ export interface SummarizeArgs {
   flaky?: readonly FlakyFinding[]
 }
 
+/** One task of `--summarize`: the wire, stated by `schemas/summary.json`. */
+export interface SummaryTaskJson {
+  id: string
+  project: string
+  task: string
+  status: TaskOutcome['status']
+  exitCode: number
+  durationMs: number
+  hash: string | null
+  noCache?: true
+  flaky?: { passes: number; failures: number; attempts: number }
+  cpuMs?: number
+  peakRssBytes?: number
+  storedCpuMs?: number
+  storedPeakRssBytes?: number
+  admissionHeldMs?: number
+  blockedBy?: string
+  timedOut?: true
+  sandboxViolations?: number
+  notReady?: 'timeout' | 'exited' | 'spawn'
+  wallclockStartNs?: string
+  wallclockEndNs?: string
+}
+
+/** The `--summarize` document. */
+export interface RunSummaryJson {
+  runId: string
+  ok: boolean
+  exitCode: number
+  startedAt: string
+  endedAt: string
+  totalMs: number
+  tasks: SummaryTaskJson[]
+  aborted: SummaryTaskJson[]
+  summary: Tally
+}
+
 /** One task's entry. Shared by `tasks` and `aborted` so they read alike. */
-function taskEntry(o: TaskOutcome, flaky?: FlakyFinding): Record<string, unknown> {
+function taskEntry(o: TaskOutcome, flaky?: FlakyFinding): SummaryTaskJson {
   return {
     id: o.node.id,
     project: o.node.projectName,
@@ -99,7 +136,7 @@ export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
   const aborted = args.outcomes.filter((o) => !isGroupTask(o.node) && o.status === 'aborted')
   const flakyById = new Map((args.flaky ?? []).map((f) => [f.taskId, f]))
   const exitCode = args.exitCode ?? (args.ok ? 0 : 1)
-  const payload = {
+  const payload: RunSummaryJson = {
     runId: args.runId,
     // The run-level verdict, first: a consumer gating on this artifact must
     // not have to re-derive it by re-implementing the bucket rules.

package/src/orchestrator/run-report.ts

@@ -113,9 +113,16 @@ function fmtDuration(ms: number): string {
  * unvalidated names and shipped WITHOUT this escape, so a `|` in a task name
  * or an output path shifted its columns. One definition, so the two
  * cannot disagree about what a cell may contain.
+ *
+ * A pipe splits the row unless an ODD run of backslashes precedes it (GFM
+ * reads `\\` as one escaped backslash), so a pipe after an odd run is already
+ * escaped and one more backslash would free it: `a\|b` became `a\\|b`, two
+ * cells. A lone `\r` ends a line too.
  */
 export function escapeMarkdownCell(value: string): string {
-  return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ')
+  return value
+    .replace(/(\\*)\|/g, (pipe, run: string) => (run.length % 2 === 0 ? `${run}\\|` : pipe))
+    .replace(/\r\n|\r|\n/g, ' ')
 }
 
 const cell = escapeMarkdownCell

package/src/workspace/migration.ts

@@ -5,6 +5,7 @@
 // tool wrote it. Core knows no source format here: a mapper returns a
 // `MigrationPlan` and this file does the rest.
 
+import { existsSync } from 'node:fs'
 import { unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { relPosix, UserError } from '../util/index.js'
@@ -304,11 +305,40 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   if (!cached && todos.has(CACHE_TODO)) {
     report.push('', 'no task caches yet: add the cache block a TODO shows, and a second run hits')
   }
-  report.push('', `next: vx run ${firstTask} --all`)
+  const installed = existsSync(path.join(root, 'node_modules', '@vzn', 'vx', 'package.json'))
+  report.push(
+    '',
+    `next: ${vxInvocation(process.env['npm_config_user_agent'], installed)} run ${firstTask} --all`,
+  )
   process.stdout.write(`${report.join('\n')}\n`)
   return 0
 }
 
+/**
+ * How the user runs vx, for the report's `next:` line. After `npx vx init`
+ * or `bunx @vzn/vx init` a bare `vx` is on no PATH (the first-five-minutes
+ * walk, 2026-09-28), so the line names the runner that started this
+ * process — npx, pnpm, yarn and Bun each set `npm_config_user_agent` — and
+ * the spec it resolves: the installed bin, else the package, since a bare
+ * `bunx vx` or `npx vx` would fetch an unrelated package named `vx`. No
+ * runner (a global install, the compiled binary): `vx`.
+ */
+export function vxInvocation(userAgent: string | undefined, installed: boolean): string {
+  const runner = /^(npm|pnpm|yarn|bun)\//.exec(userAgent ?? '')?.[1]
+  switch (runner) {
+    case 'npm':
+      return installed ? 'npx vx' : 'npx @vzn/vx'
+    case 'bun':
+      return installed ? 'bunx vx' : 'bunx @vzn/vx'
+    case 'pnpm':
+      return installed ? 'pnpm vx' : 'pnpm dlx @vzn/vx'
+    case 'yarn':
+      return installed ? 'yarn vx' : 'yarn dlx @vzn/vx'
+    default:
+      return 'vx'
+  }
+}
+
 /** Ids named per shared TODO; the files carry each one (sveltejs/kit: 92 persistent tasks). */
 const TODO_IDS_SHOWN = 5