@vzn/vx 0.0.18 → 0.0.22

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,15 +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 — 76 ms
-across 46 packages, 559 ms across a 1,090-package graph of 3,270 tasks,
-where Turborepo takes 760 ms and Nx 3.59 s on the identical workspace —
-and a cold build of that graph burns 34 s of CPU in vx, 73 s in Turborepo
-and 114 minutes in Nx.
-Measured, reproducible, on hardware you own
-([benchmarks](docs/benchmarks.md)).
-
-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.
@@ -49,7 +67,7 @@ export default defineProject({
 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
+vx run ci --affected      # changed since origin/HEAD, and what depends on it
 vx watch lint             # re-run on file changes
 vx run build --dry        # show the plan, don't execute
 ```
@@ -78,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
@@ -97,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.
 
@@ -119,9 +136,11 @@ vx lock --check && vx run ci --frozen     # CI: audit, then run EXACTLY that gra
 | `vx lock --check` | full graph        | compares — catches env and import drift that byte hashes cannot |
 
 Env values read at lock time are frozen by design — cache keys become
-reproducible across machines. Bonus: `--frozen` runs skip config
-evaluation entirely (~120 ms back per 1,000 packages). No other
-runner has an equivalent.
+reproducible across machines. Take it for that, not for speed: measured
+on the 1,000-project bench, a plain warm run and a frozen one are a tie
+(177 ms against 165, 2026-09-12), because the config-evaluation cache
+already serves a pure config without evaluating it. No other runner has
+an equivalent.
 
 ## Everything you need, nothing to configure twice
 
@@ -132,9 +151,9 @@ watch mode · `--dry` / `--graph` plans · persistent dev servers ·
 retries, timeouts, `--continue` modes · per-layer cache control
 (`--cache=local:r,remote:`) · `vx why` explains a re-run from the
 persisted input fingerprints · `vx last` replays a recorded run ·
-`vx prune` cuts a Docker-ready workspace subset · `vx info`,
+`vx info`,
 `--summarize`, `--profile` Chrome traces, `--report` · `vx cache prune`
-with TTL and size caps · `vx migrate` from turbo.json or an Nx graph.
+with TTL and size caps · `bunx @vzn/vx-migrate` from turbo.json or an Nx graph.
 
 ## A pipeline with seams — plugins decide what happens
 
@@ -155,37 +174,50 @@ declared in `vx.workspace.ts` hook each stage, Vite-style, on one
 | 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** — even its own local executor and
-cache are plugins your workspace declares, which is what makes "replace
-any part" real rather than promised. First-party plugins:
+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), and
-`@vzn/vx/plugins/schedule-history` (order by learned critical path). Nothing distributed ships in this repo; the seams are how you
-build it.
+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               |
-| 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       |
+|                           | 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 one release file; 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).
+[`packages/vx/docs/benchmarks.md`](packages/vx/docs/benchmarks.md).
 
 ## Switching from another runner
 
@@ -233,7 +265,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).
+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)
 
@@ -252,47 +286,50 @@ 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
+- [`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 design record lives under [`docs/design/`](./docs/design/); the
-maintainers' handoff is [`docs/STATUS.md`](./docs/STATUS.md).
+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. **~2,500 core tests plus the package suites; CI green on every commit**;
+than maintain back-compat. What 1.0 will promise is in
+[`versioning-1.0.md`](packages/vx/docs/design/versioning-1.0.md). **~3,000 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; ~2,500 core tests + the package suites, green        |
-| `vx run --verify` (provable cache correctness)   | **shippable**        | determinism + input-completeness proofs; CI-gate recipe in docs              |
-| Plugin pipeline (9 hooks, `commands` included)   | **shippable**        | crash-isolated, re-validated; core's own executor + cache are plugins        |
-| `vx init` / `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                             |
+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; ~3,000 core tests + the package suites, green                                                                                             |
+| Plugin pipeline (13 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
 
@@ -303,7 +340,7 @@ bun packages/vx/src/bin.ts run ci --all     # lint + test + docs build, every pa
 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 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 [`docs/STATUS.md`](docs/STATUS.md) — the living handoff — and `CLAUDE.md`.
+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/package.json

@@ -1,24 +1,12 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.18",
+  "version": "0.0.22",
   "description": "An open, extensible monorepo task runner.",
   "type": "module",
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "import": "./src/index.ts"
-    },
-    "./plugins/local-executor": {
-      "types": "./src/plugins/local-executor/index.ts",
-      "import": "./src/plugins/local-executor/index.ts"
-    },
-    "./plugins/local-cache": {
-      "types": "./src/plugins/local-cache/index.ts",
-      "import": "./src/plugins/local-cache/index.ts"
-    },
-    "./plugins/schedule-history": {
-      "types": "./src/plugins/schedule-history/index.ts",
-      "import": "./src/plugins/schedule-history/index.ts"
     }
   },
   "types": "./src/index.ts",
@@ -29,23 +17,25 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.18",
-    "@vzn/vx-linux-arm64": "0.0.18",
-    "@vzn/vx-darwin-x64": "0.0.18",
-    "@vzn/vx-darwin-arm64": "0.0.18"
+    "@vzn/vx-linux-x64": "0.0.22",
+    "@vzn/vx-linux-arm64": "0.0.22",
+    "@vzn/vx-darwin-x64": "0.0.22",
+    "@vzn/vx-darwin-arm64": "0.0.22"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.56"
+    "@anthropic-ai/sandbox-runtime": "^0.0.76"
   },
   "files": [
     "index.ts",
-    "plugins",
     "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,25 +1,84 @@
 #!/usr/bin/env bun
-import { run } from './cli/index.js'
-import { isUserError } from './util/index.js'
+import { registerCoreAlias, run } from './cli/index.js'
+import { fsRefusalHint, isFsRefusal, 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.
+let settled = false
+
 async function main(): Promise<void> {
   try {
-    process.exit(await run(process.argv.slice(2)))
+    const code = await run(process.argv.slice(2))
+    // NOTHING calls `process.exit` here, and that is the fix rather than a
+    // simplification. Bun drops what a pipe has not yet taken when
+    // `process.exit` follows a large write: 300 KB written then exit
+    // delivered 64 KiB (128 KiB after a tick), and `vx history --format
+    // json` on a 300-project workspace was cut mid-string (2026-09-15).
+    // `stdout.end(cb)` fixed that on 1.4.2 — and on 1.3.11 the callback
+    // still fires early: 2 MiB written, 214 KB delivered (2026-09-20).
+    // Setting the code and letting the loop drain is the one form that
+    // does not depend on when a runtime decides a pipe is flushed; it
+    // costs a hang if a verb leaves a handle open, which the suite's
+    // several hundred spawns of this binary would show at once.
+    process.exitCode = code
   } catch (err) {
     // UserError (workspace not found, cycle, config invalid, ...) —
     // 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 (isUserError(err)) {
-      process.stderr.write(`vx: ${err.message}\n`)
+      // 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 if (isFsRefusal(err)) {
+      // The file system's refusal names the path; the stack would name
+      // the verb's write, which the reader cannot act on either.
+      process.stderr.write(`vx: ${err.message} — ${fsRefusalHint(err)}\n`)
     } else {
       const message = err instanceof Error ? (err.stack ?? err.message) : String(err)
       process.stderr.write(`vx: ${message}\n`)
     }
-    process.exit(1)
+    // Same reason as the success path above: a large stderr is truncated by
+    // `process.exit` too, and an error message cut in half is the one a
+    // reader most needs whole.
+    process.exitCode = 1
   }
+  settled = true
+}
+
+// The loop drained while the verb was still pending: something it awaits
+// can never settle (a plugin hook whose promise is never resolved), and
+// with no exit code set Bun exits 0 — a run whose task failed reported
+// green, and its task had not even run (item 921). An exit that no
+// verdict reached is a failure, and says so.
+process.on('beforeExit', () => {
+  if (settled) return
+  settled = true
+  process.stderr.write(
+    'vx: the run stopped before it finished: something it awaited can never settle (a plugin hook?)\n',
+  )
+  process.exitCode = 1
+})
+
+// A reader that leaves is not the run's failure. `vx run build | head -1`
+// closes the pipe after one line; every later write gets EPIPE, which Bun
+// raises as an `error` event on the stream, and an `error` nobody listens
+// for is an uncaught exception: the run died with a stack after its task
+// had succeeded, exit 1, its lock directory left behind (2026-09-16). With
+// a listener the write returns false, the run finishes, saves, releases,
+// and exits with its own verdict; what was going to the reader goes
+// nowhere. Same for stderr (`2>&1 | head`). Here and not in the logger:
+// an embedder's streams are the embedder's.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', () => {})
 }
 
 void main()