@vzn/vx 0.0.16 → 0.0.21

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 nxt contributors
+Copyright (c) 2026 vx contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,11 +3,33 @@
 **The fastest way to build a monorepo.**
 
 vx runs your task graph, remembers every result, and never does the
-same work twice. Fully cached runs finish in milliseconds — 144 ms
-across 100 packages, 0.62 s across a 1090-package graph of 3,270
-tasks. Measured, reproducible, on hardware you own.
-
-One binary. No daemon. No Node. Nothing to babysit.
+same work twice.
+
+<!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
+
+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 -->
+
+On a real Turbo monorepo (`solidjs/solid`, its own `turbo.json`, no
+config rewritten) vx replays a cached build in 51 ms where Turbo takes
+95, restores every output in 66 ms against 127, and builds cold in
+40.6 s against 45.5 s. Measured, reproducible, on hardware you own
+([benchmarks](packages/vx/docs/benchmarks.md)).
+
+One binary. No daemon, no cloud, no account, no paywall. Sandboxed
+tasks, a plugin at every stage, seconds of overhead at a thousand
+packages.
+
+vx does one thing — run and cache a task graph, correctly — and stops
+there. Remote caches, remote execution, telemetry, AI agents, learned
+scheduling and your own verbs are plugins on documented seams, not
+features inside: what Nx would be if it weren't a product.
 
 📖 **[Documentation site →](https://vznjs.github.io/vx/)** — guides,
 architecture, caching, and the full CLI / config reference.
@@ -42,6 +64,7 @@ export default defineProject({
 ```
 
 ```sh
+vx init                   # scaffold vx.workspace.ts + a vx.config.ts per package from scripts
 vx run build              # cwd project + its workspace deps
 vx run test --all         # every project that declares `test`
 vx run ci --affected      # only what changed since origin/HEAD
@@ -73,16 +96,11 @@ skip extraction entirely when the tree already matches. In-process
 tar (no subprocess on the hot path). Atomic artifact publishes.
 Single-transaction metadata writes. Every optimization is recorded
 with the invariant that keeps it valid —
-[`docs/optimizations.md`](docs/optimizations.md) is the ledger, and
-[`bench/`](bench/) reproduces the numbers.
+[`packages/vx/docs/optimizations.md`](packages/vx/docs/optimizations.md) is the ledger, and
+[`packages/vx-bench/`](packages/vx-bench/) reproduces the numbers.
 
 ## Built for trust
 
-- **Provable cache correctness.** `vx run --verify` re-runs each
-  cacheable task and byte-compares outputs (determinism);
-  `--verify=inputs` sandboxes it against the declared inputs and fails
-  loud naming any undeclared read (completeness). No other runner can
-  prove a cache entry safe.
 - **Corruption can't go live.** A remote artifact is verified against
   its content digest and validated before it enters the store
   (zstd-bomb and oversize downloads refused); bad bytes degrade to a
@@ -92,7 +110,11 @@ with the invariant that keeps it valid —
 - **Readiness you can bound.** Persistent tasks gate downstream work
   on a `readyWhen` signal; `exec.timeout` bounds any task (with
   `--timeout` / workspace defaults), `exec.retries` + `--retry` absorb
-  flakes — and retried-then-passed tasks are flagged flaky.
+  flakes.
+- **Flaky tasks are found, not guessed.** The same inputs both passing
+  and failing is the definition, and vx holds every hash and outcome
+  locally: a run names them under its footer, `--summarize` types them
+  per task, `vx info` lists them. No service.
 - **Kernel-level sandboxing**, opt-in per task, that fails the build
   on violation instead of hiding it.
 
@@ -125,46 +147,75 @@ resolution that bridges packages without the task · multi-task runs
 with one shared graph · pnpm-style filters and `--affected` ·
 watch mode · `--dry` / `--graph` plans · persistent dev servers ·
 retries, timeouts, `--continue` modes · per-layer cache control
-(`--cache=local:r,remote:`) · `vx info`, `--summarize`, `--profile`
-Chrome traces, `--report` · `vx cache prune` with TTL and size caps ·
-`vx migrate` from turbo.json or an Nx graph.
-
-## Extensible by design — the core is provider-neutral
-
-`vx` runs tasks and nothing else. A dashboard, a remote cache,
-distributed execution, and telemetry export all arrive through
-**plugins** declared in `vx.workspace.ts`, filling three seams the
-core exposes — **backend** (where a task runs), **cache** (a remote
-layer behind the local one), and **telemetry** (a read-only stream of
-the versioned `TelemetryRecord` / `RunSummaryRecord` contract). Core
-depends on none of them; the arrow only ever points plugin → core.
-First-party plugins ship the OpenTelemetry exporter
-([`@vzn/vx-otel`](https://www.npmjs.com/package/@vzn/vx-otel), OTLP
-traces + metrics with zero OTel-SDK deps) and **vx Cloud** (below) —
-and the same seams are open to anyone.
+(`--cache=local:r,remote:`) · `vx why` explains a re-run from the
+persisted input fingerprints · `vx last` replays a recorded run ·
+`vx info`,
+`--summarize`, `--profile` Chrome traces, `--report` · `vx cache prune`
+with TTL and size caps · `bunx @vzn/vx-migrate` from turbo.json or an Nx graph.
+
+## A pipeline with seams — plugins decide what happens
+
+Core is the pipeline: discover projects, evaluate configs, build the
+task graph, derive keys, schedule, execute, cache, observe. Plugins
+declared in `vx.workspace.ts` hook each stage, Vite-style, on one
+`VxPlugin` object:
+
+| Stage     | Hook                       | A plugin can…                                               |
+| --------- | -------------------------- | ----------------------------------------------------------- |
+| workspace | `config(ws, ctx)`          | edit the workspace config before it is used                 |
+| project   | `project(config, ctx)`     | add, remove or rewrite a project's tasks (keyed like yours) |
+| graph     | `graph(nodes, ctx)`        | add or drop edges, mark tasks requested                     |
+| key       | `key(task, ctx)`           | fold extra material into the cache key (named in `vx why`)  |
+| schedule  | `schedule(nodes, ctx)`     | decide which ready task runs first                          |
+| execute   | `executor(ctx)`            | decide WHERE a task's command runs (local, a REAPI worker)  |
+| store     | `cache(ctx)`               | decide where artifacts live (local, a shared remote)        |
+| observe   | `telemetry(ctx)` / `setup` | receive every run record, or the raw event bus              |
+| cli       | `commands`                 | add verbs to `vx`                                           |
+
+Core applies **no plugin by default** and names none. Running here and
+caching here are its floor — the tail of every executor list and cache
+chain — so a workspace with no `vx.workspace.ts` runs and caches, and a
+plugin that declines a task hands it back to this machine. First-party
+plugins:
+[`@vzn/vx-reapi`](packages/vx-reapi) (Bazel Remote Execution API —
+remote cache and remote execution against NativeLink, BuildBuddy,
+Buildbarn or bazel-remote), [`@vzn/vx-otel`](packages/vx-otel)
+(OpenTelemetry traces + metrics + logs, zero SDK deps),
+[`@vzn/vx-github`](packages/vx-github) (Actions job summary + Checks
+API), [`@vzn/vx-mcp`](packages/vx-mcp) (`vx mcp` — a read-only Model
+Context Protocol server for AI coding agents, no SDK),
+[`@vzn/vx-migrate`](packages/vx-migrate) (adoption in one package:
+`turbo()` runs a Turbo repo under vx with nothing written, `bunx
+@vzn/vx-migrate` writes configs from `turbo.json` or an Nx graph, and
+`turboCache()` / `nxCache()` keep a remote cache speaking Turbo's
+`/v8/artifacts` API or Nx's self-hosted spec — the wire is theirs, the
+artifacts are vx's),
+[`@vzn/vx-lockfile`](packages/vx-lockfile) (`pnpm()`, `bun()`, `npm()`,
+`yarn()`: the lockfile keyed per project, so one install re-keys only the
+projects it reaches, and `--affected` follows), and [`@vzn/vx-schedule-history`](packages/vx-schedule-history)
+(order by learned critical path) and [`@vzn/vx-migrate`](packages/vx-migrate)
+(`bunx @vzn/vx-migrate`: turbo.json or an Nx graph → vx.config.ts, through
+core's migration seam). Core ships no plugin and reads no other runner's
+format; nothing
+distributed ships in this repo; the seams are how you build it.
 
 ## How it compares
 
-|                           | vx                                                                    | Turborepo                      | Nx               |
-| ------------------------- | --------------------------------------------------------------------- | ------------------------------ | ---------------- |
-| Fully cached, 100 pkgs¹   | **144 ms**                                                            | 279 ms                         | 583+ ms          |
-| 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               |
-| Provable cache safety     | **Yes** — `--verify` (determinism) + `--verify=inputs` (completeness) | No                             | No               |
-| MCP server for AI agents  | **Yes** — `vx mcp` (stdio, reads your local cache)                    | No                             | No               |
-| Plugin API                | **Yes** — backend / cache / telemetry seams                           | No                             | Yes (TS-tied)    |
-| Predictive scheduling     | **Yes** (opt-in: `predictive: true`)                                  | No                             | No               |
-| OTel CI/CD spans          | **Yes** — `otel()` plugin, zero OTel-SDK deps                         | No                             | Paid             |
-| Self-hosted platform²     | **Yes** — dashboard, distributed CI, remote cache; Docker compose     | Vercel-only cache              | Paid (Nx Cloud)  |
-| Install                   | **Single binary** — npm or 1 curl line, no Node/Bun needed            | npm + Node                     | npm + Node       |
+|                           | vx                                                         | Turborepo                      | Nx               |
+| ------------------------- | ---------------------------------------------------------- | ------------------------------ | ---------------- |
+| Fully cached, 100 pkgs¹   | **144 ms**                                                 | 279 ms                         | 583+ ms          |
+| 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** — executor / cache / telemetry seams               | No                             | Yes (TS-tied)    |
+| OTel CI/CD spans          | **Yes** — `otel()` plugin, zero OTel-SDK deps              | No                             | Paid             |
+| Install                   | **Single binary** — npm or 1 curl line, no Node/Bun needed | npm + Node                     | npm + Node       |
 
 ¹ Wall-clock, direct binaries, same machine and workspace — full
 methodology and more scenarios in
-[`docs/benchmarks.md`](docs/benchmarks.md). ² Optional, self-hosted,
-OSS — see [vx Cloud](#vx-cloud).
+[`packages/vx/docs/benchmarks.md`](packages/vx/docs/benchmarks.md).
 
 ## Switching from another runner
 
@@ -212,51 +263,9 @@ Differences to know:
 - Persistent tasks: `persistent: { readyWhen: 'regex' }` (Turbo uses just `persistent: true`).
 - Remote caching is a plugin, not a built-in — connect one and every `vx run` reads through it.
 
-Side-by-side feature matrix + every known gap: [`docs/comparison.md`](./docs/comparison.md).
-
-## vx Cloud
-
-An **optional, self-hosted CI platform** — the first-party service you
-run yourself. It is a fully independent app (accounts, roles,
-organizations, teams, multiple workspaces), with **Postgres** as the
-system of record and an **S3-compatible bucket** for artifacts; the
-controller keeps zero artifact bytes at rest. Core `vx` never depends
-on it — it connects to a deployment through the plugin seams above.
-
-What a connected platform adds:
-
-- **Dashboard.** Runs, flamegraphs, a live run cockpit with the task
-  DAG, per-task logs + artifacts, cache-key diffs ("why did this
-  re-run?"), and flaky-task detection with the concrete fix.
-- **Remote cache.** The vx-native `/v1/cache` wire, tenant-partitioned
-  per org/workspace, with **trusted / untrusted tiers derived from the
-  token** — a fork-PR artifact can never feed a trusted build — and an
-  always-on integrity digest the client verifies.
-- **Distributed CI (DTE).** Agents form a session-keyed pool; a
-  `vx run` fans tasks out across same-commit agents, outputs propagate
-  through the shared artifact store, and a standing pool multiplexes
-  concurrent runs with fair scheduling.
-- **MCP over the platform.** `POST /mcp` (Postgres-backed, behind the
-  token) exposes the analytics as typed tools for AI agents — alongside
-  the core `vx mcp` stdio server that reads your local cache.
-
-Deploy the stack (app + Postgres + object storage) with Docker
-Compose, then connect any workspace with one URL and a minted token:
-
-```sh
-# Deploy — open the URL, register the first admin, mint a CI token under Admin → Tokens:
-VX_CLOUD_SECRET=$(openssl rand -hex 32) \
-  docker compose -f packages/cloud/deploy/docker-compose.yml up
-
-# Connect a workspace (remote cache + analytics + distribution):
-vx-cloud connect https://ci.acme.dev --token vxc_…
-# …or set VX_CLOUD_URL + VX_CLOUD_TOKEN in the environment.
-```
-
-Install the platform CLI with `npm i -g @vzn/vx-cloud` (a standalone
-binary, or the `ghcr.io/vznjs/vx-cloud` image). Full setup, RBAC,
-distributed CI, and the wire protocol live in the **vx Cloud** section
-of the [documentation site](https://vznjs.github.io/vx/).
+Side-by-side feature matrix + every known gap: [`packages/vx/docs/comparison.md`](packages/vx/docs/comparison.md).
+What a Turbo or Nx user relies on, spelled in vx and pinned by a test:
+[`packages/vx/docs/parity.md`](packages/vx/docs/parity.md).
 
 ## Architecture (one paragraph)
 
@@ -275,58 +284,60 @@ versioned telemetry contract (`TelemetryRecord` / `RunSummaryRecord`)
 them. Core never imports a plugin; the arrow only points plugin → core.
 Every module has a docs page; every interface is a swappable seam.
 
-Read [`docs/architecture.md`](./docs/architecture.md) for the module
-map; the design record lives under [`docs/design/`](./docs/design/).
+Read [`packages/vx/docs/architecture.md`](packages/vx/docs/architecture.md) for the module
+map; the design record lives under [`packages/vx/docs/design/`](packages/vx/docs/design/).
 
 ## Documentation
 
-Full technical docs live under [`docs/`](./docs/) and on the
+Full technical docs live under [`packages/vx/docs/`](packages/vx/docs/) and on the
 [documentation site](https://vznjs.github.io/vx/):
 
-- [`docs/architecture.md`](./docs/architecture.md) — module map + data flow
-- [`docs/schema.md`](./docs/schema.md) — every config field
-- [`docs/caching.md`](./docs/caching.md) — cache-key derivation + invalidation table
-- [`docs/execution.md`](./docs/execution.md) — `vx run` lifecycle
-- [`docs/cli.md`](./docs/cli.md) — every flag
-- [`docs/comparison.md`](./docs/comparison.md) — Turbo / Nx / vite-task feature matrix
-- [`docs/modules/`](./docs/modules/) — one reference page per source module
-- The **vx Cloud** section of the [docs site](https://vznjs.github.io/vx/) — deploy, RBAC, dashboard, distributed CI, wire protocol
+- [`packages/vx/docs/architecture.md`](packages/vx/docs/architecture.md) — module map + data flow
+- [`packages/vx/docs/schema.md`](packages/vx/docs/schema.md) — every config field
+- [`packages/vx/docs/caching.md`](packages/vx/docs/caching.md) — cache-key derivation + invalidation table
+- [`packages/vx/docs/execution.md`](packages/vx/docs/execution.md) — `vx run` lifecycle
+- [`packages/vx/docs/cli.md`](packages/vx/docs/cli.md) — every flag
+- [`packages/vx/docs/comparison.md`](packages/vx/docs/comparison.md) — Turbo / Nx / vite-task feature matrix
+- [`packages/vx/docs/modules/`](packages/vx/docs/modules/) — one reference page per source module
 
-The full design record (including the platform-pivot notes) lives
-under [`docs/design/`](./docs/design/).
+The design record lives under [`packages/vx/docs/design/`](packages/vx/docs/design/); the
+maintainers' handoff is [`packages/vx/docs/STATUS.md`](packages/vx/docs/STATUS.md).
 
 ## Status
 
 **Pre-alpha.** The schema is settling; we bump `CACHE_VERSION` rather
-than maintain back-compat. **1,600+ tests (core + packages); CI green
-on every commit**; the project dogfoods itself (`vx run ci`).
-Published on npm: [`@vzn/vx`](https://www.npmjs.com/package/@vzn/vx)
-(a prebuilt standalone binary) and `@vzn/vx-cloud`.
+than maintain back-compat. **~2,500 core tests plus the package suites; CI green on every commit**;
+the project dogfoods itself (`vx run ci`). Published on npm:
+[`@vzn/vx`](https://www.npmjs.com/package/@vzn/vx) (a prebuilt standalone
+binary).
 
 Production readiness for the **core task runner**: the semantics are
-solid; it is dogfooded continuously. The main operational rough edge
-is Windows (unsupported).
-
-| Surface                                        | Maturity                       | Notes                                                             |
-| ---------------------------------------------- | ------------------------------ | ----------------------------------------------------------------- |
-| Core task runner + caching                     | **production-ready**           | dogfooded continuously; 1,200+ core tests, all green              |
-| `vx run --verify` (provable cache correctness) | **shippable**                  | determinism + input-completeness proofs; CI-gate recipe in docs   |
-| `vx mcp`                                       | **shippable**                  | live cache.db tools over stdio                                    |
-| Plugin API (backend / cache / telemetry)       | **shippable**                  | crash-isolated; the cloud + OTel plugins are ordinary plugins     |
-| Predictive scheduling                          | **shippable as opt-in**        | gated on `predictive: true` + observed data                       |
-| OTel export (`@vzn/vx-otel`)                   | **shippable**                  | declare `otel()` in `vx.workspace.ts`; OTLP traces + metrics      |
-| vx Cloud platform (self-hosted)                | **shippable for self-hosting** | accounts/RBAC/orgs on Postgres, S3 artifacts, dashboard, DTE, MCP |
+solid; it is dogfooded continuously. Linux and macOS, x64 and arm64;
+Windows runs vx under WSL (POSIX shell is the API), with no native
+build.
+
+| Surface                                            | Maturity             | Notes                                                                                                                                                             |
+| -------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Core task runner + caching                         | **production-ready** | dogfooded continuously; ~2,500 core tests + the package suites, green                                                                                             |
+| Plugin pipeline (9 hooks, `commands` included)     | **shippable**        | crash-isolated, re-validated; the local executor + cache are the floor under every plugin                                                                         |
+| `vx init` / `@vzn/vx-migrate` (scripts; Turbo, Nx) | **shippable**        | one config per package, TODOs where a source cannot say                                                                                                           |
+| REAPI remote cache + execution (`@vzn/vx-reapi`)   | **shippable**        | Bazel AC + CAS + Execute; NativeLink / BuildBuddy / Buildbarn / bazel-remote                                                                                      |
+| OTel export (`@vzn/vx-otel`)                       | **shippable**        | OTLP traces + metrics + logs, zero SDK deps                                                                                                                       |
+| GitHub Actions (`@vzn/vx-github`)                  | **shippable**        | job summary + Checks API run                                                                                                                                      |
+| MCP server (`@vzn/vx-mcp`)                         | **shippable**        | `vx mcp` — read-only tools for AI agents, no SDK                                                                                                                  |
+| Adoption (`@vzn/vx-migrate`)                       | **shippable**        | `turbo()`: a `turbo.json` workspace runs with no `vx.config` written; `turboCache()` / `nxCache()`: any `/v8/artifacts` or Nx `/v1/cache` server; the migrate CLI |
+| Lockfile keys (`@vzn/vx-lockfile`)                 | **shippable**        | `pnpm()` `bun()` `npm()` `yarn()`: per-project dependency-closure keys; `--affected` follows                                                                      |
 
 ## Development
 
 ```sh
 git clone https://github.com/vznjs/vx && cd vx
 bun install
-bun src/bin.ts run ci          # format-check + lint + test
-bun src/bin.ts run build       # cross-target binaries → dist/
+bun packages/vx/src/bin.ts run ci --all     # lint + test + docs build, every package
+bun packages/vx/src/bin.ts run build --filter @vzn/vx   # cross-target binaries → packages/vx/dist/
 ```
 
-vx is self-hosted: every dev task routes through `bun src/bin.ts run <task>` per the repo's own `vx.config.ts`. No `package.json` scripts; CI invokes vx directly.
+vx is self-hosted: every dev task routes through `bun packages/vx/src/bin.ts run <task>` per each package's own `vx.config.ts`. No `package.json` scripts; CI invokes vx directly. Start with [`packages/vx/docs/STATUS.md`](packages/vx/docs/STATUS.md) — the living handoff — and `CLAUDE.md`.
 
 ## License
 

package/index.ts

@@ -0,0 +1,10 @@
+// Root entry shim. Bun 1.4.0's `--compile` binaries resolve an on-disk
+// package by directory convention (`<pkg>/index.ts`, `<pkg>/<subpath>/index.ts`)
+// and ignore package.json `exports` / `main` (measured 2026-09-03: an
+// entry of `./src/index.ts` resolved to the root `index.ts` regardless of the
+// manifest, and a package with no root file was "not found"). Without this
+// file every `import … from '@vzn/vx'` in a workspace config fails under the
+// standalone binary. The exports map still wins everywhere else and points
+// at the same module, so this is one extra hop for the binary and nothing
+// for anyone else.
+export * from './src/index.js'

package/launcher.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 // npm launcher for a vx command — the entry a published package's `bin` points
 // at. It execs the prebuilt standalone binary shipped as a per-platform
-// optionalDependency, so end users get the command WITHOUT installing Bun. ONE
-// launcher serves both `@vzn/vx` and `@vzn/vx-cloud`: everything is derived from
-// this package's OWN name, read from the package.json sitting beside this file.
+// optionalDependency, so end users get the command WITHOUT installing Bun.
+// Everything is derived from this package's OWN name, read from the
+// package.json sitting beside this file, so any package built by
+// scripts/build-npm.ts can carry it:
 //
-//   @vzn/vx        → platform pkg @vzn/vx-<key>,        binary `vx`
-//   @vzn/vx-cloud  → platform pkg @vzn/vx-cloud-<key>,  binary `vx-cloud`
+//   @vzn/vx → platform pkg @vzn/vx-<key>, binary `vx`
 //
 // Resolution order:
 //   1. the matching <name>-<platform> optionalDependency's binary (the normal
@@ -26,11 +26,10 @@ const require = createRequire(import.meta.url)
 const here = dirname(fileURLToPath(import.meta.url))
 const pkg = require('./package.json')
 
-// Derive the platform-package prefix + binary basename from this package's name
-// so the same launcher works for @vzn/vx and @vzn/vx-cloud. `base` is the
-// unscoped name (vx / vx-cloud) — the command AND the binary filename inside the
-// platform package. `vxSourceEntry` (a package.json field) is the source-mode
-// entry: `src/bin.ts` for vx, `src/cli/bin.ts` for vx-cloud.
+// Derive the platform-package prefix + binary basename from this package's
+// name. `base` is the unscoped name — the command AND the binary filename
+// inside the platform package. `vxSourceEntry` (a package.json field) is the
+// source-mode entry, `src/bin.ts` by default.
 const name = pkg.name
 const base = name.replace(/^@[^/]+\//, '')
 const sourceEntry = pkg.vxSourceEntry ?? 'src/bin.ts'
@@ -86,7 +85,7 @@ process.stderr.write(
   `${base}: no prebuilt binary for ${key}.\n` +
     `  Supported platforms: ${supported}.\n` +
     `  If your platform should be supported, reinstall so npm fetches the\n` +
-    `  matching ${name}-${key} optionalDependency, or install Bun (>=1.3) to\n` +
+    `  matching ${name}-${key} optionalDependency, or install Bun (>=1.4) to\n` +
     `  run ${base} from source.\n`,
 )
 process.exit(1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.16",
+  "version": "0.0.21",
   "description": "An open, extensible monorepo task runner.",
   "type": "module",
   "exports": {
@@ -17,21 +17,25 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.16",
-    "@vzn/vx-linux-arm64": "0.0.16",
-    "@vzn/vx-darwin-x64": "0.0.16",
-    "@vzn/vx-darwin-arm64": "0.0.16"
+    "@vzn/vx-linux-x64": "0.0.21",
+    "@vzn/vx-linux-arm64": "0.0.21",
+    "@vzn/vx-darwin-x64": "0.0.21",
+    "@vzn/vx-darwin-arm64": "0.0.21"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.56"
+    "@anthropic-ai/sandbox-runtime": "^0.0.75"
   },
   "files": [
+    "index.ts",
     "src",
     "launcher.mjs",
     "README.md",
     "LICENSE"
   ],
-  "repository": "https://github.com/vznjs/vx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vznjs/vx.git"
+  },
   "homepage": "https://github.com/vznjs/vx#readme",
   "bugs": "https://github.com/vznjs/vx/issues",
   "license": "MIT",

package/src/bin.ts

@@ -1,6 +1,12 @@
 #!/usr/bin/env bun
-import { run } from './cli/index.js'
-import { UserError } from './util/index.js'
+import { registerCoreAlias, run } from './cli/index.js'
+import { isUserError } from './util/index.js'
+
+// Every `import … from '@vzn/vx'` this process evaluates — a plugin
+// package, a workspace or project config — resolves to THIS core, not to
+// a second copy from node_modules (core-alias.ts says why and what it
+// costs). Registered before any verb runs; the façade loads on first use.
+registerCoreAlias(() => import('./index.js') as Promise<Record<string, unknown>>)
 
 // Wrapped in an explicit async main so `bun build --compile` accepts
 // the file. The compile target doesn't allow top-level await.
@@ -12,8 +18,12 @@ async function main(): Promise<void> {
     // print the message only; the stack is noise the user can't act
     // on. Everything else gets the full stack so internal bugs are
     // debuggable.
-    if (err instanceof UserError) {
-      process.stderr.write(`vx: ${err.message}\n`)
+    if (isUserError(err)) {
+      // A message that already names the tool (`vx why: …`, thrown by a verb
+      // that wants its own name in the line) is printed as it is; prefixing
+      // it produced `vx: vx why: …` (walkthrough, 2026-09-04).
+      const m = err.message
+      process.stderr.write(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
     } else {
       const message = err instanceof Error ? (err.stack ?? err.message) : String(err)
       process.stderr.write(`vx: ${message}\n`)