@vzn/vx 0.0.12 → 0.0.15

package/README.md

@@ -61,45 +61,48 @@ below is built into the binary; no external services required.
 vx mcp                                    # Model Context Protocol server (stdio)
                                           # — Claude Code / Cursor / Continue.dev talk to vx as a typed tool
 
-vx coordinator build test --workers 4     # start a distributed-CI coordinator
-vx run --worker ws://coord:5180           # pull tasks from a coordinator and execute them
-
-vx serve --ui --open                      # unified backend + embedded dashboard + open browser
-                                          # /v1/* JSON, SSE events, WS run protocol, CORS *
+npm i -g @vzn/vx-cloud                    # the service CLI — also a standalone binary, no Bun
+vx-cloud serve --ui --open                # team backend + embedded dashboard (token-authenticated)
+vx-cloud agent --url https://ci.acme.dev  # join a distributed-execution pool (Nx-Agents-style DTE)
+vx-cloud connect https://ci.acme.dev      # one-URL analytics + remote cache for every `vx run`
 ```
 
 ### Open platform highlights
 
-- **Wire protocol = JSON-RPC 2.0 + OTel LogRecord payload.** Any
-  JSON-RPC client works against `vx serve`. Three transports — WS,
-  SSE, NDJSON — off the same bus.
-- **MCP server with live tools** (`getCacheStats`, `getRunHistory`,
-  `explainCacheKey`, `whyDidThisRerun`) that read your real
-  `cache.db`. Drop into any agent's stdio MCP slot.
-- **Plugin API.** Declare `plugins: [...]` in `vx.workspace.ts`;
-  each plugin subscribes to bus lifecycle events with crash
-  isolation per hook.
-- **Predictive scheduling.** Opt in with `predictive: true` in
-  `vx.workspace.ts` — the scheduler reads run history and picks
-  the task on the longest expected remaining critical path.
-- **Distributed CI.** `vx coordinator` + `vx run --worker` over the
-  same protocol. Content-addressed: any worker producing
-  `<hash>` satisfies every consumer of `<hash>`.
-- **OTel CI/CD spans (native).** Set `OTEL_EXPORTER_OTLP_ENDPOINT`,
-  install the three `@opentelemetry/*` peer deps — core speaks OTel
-  natively; every event flows to Grafana / Honeycomb / Datadog /
-  Tempo with zero bridge package.
-- **Self-host vx serve.** Same backend everywhere — laptop, Docker,
-  any container runtime. JSON `/v1/*` metrics API + WebSocket run
-  protocol + SSE event stream + permissive CORS. One stack.
-- **Dashboard embedded in the binary.** `vx serve --ui` serves a Solid
-  SPA at `/` — task averages, p50/p99, cache savings, recent runs,
-  flamegraphs — compiled into `vx` itself, nothing to install.
-  Connection picker switches between local and hosted backends.
-
-Each lives behind a one-paragraph design doc under
-`docs/design/*-2026-06.md`. Phase-by-phase implementation log:
-`docs/progress/implementation-log-2026-06.md`.
+- **Provider-neutral core.** `vx` runs tasks and nothing else — the
+  dashboard, remote cache, distribution, and telemetry all arrive via
+  PLUGINS declared in `vx.workspace.ts`. `@vzn/vx-cloud` is the
+  first-party one; anyone can write another against the same seams
+  (backend / cache / telemetry).
+- **MCP for AI agents, twice.** `vx mcp` (stdio, reads your real
+  `cache.db`: `getCacheStats`, `getRunHistory`, `explainCacheKey`,
+  `whyDidThisRerun`) and `POST /mcp` on any `vx-cloud serve` — local
+  or hosted, behind the bearer token.
+- **Provable cache correctness.** `vx run --verify` re-runs each
+  cacheable task and byte-compares outputs; `--verify=inputs` runs it
+  sandboxed against the declared inputs and names any undeclared read.
+  The only runner that PROVES a cache entry safe instead of hoping.
+- **Distributed CI (DTE).** `vx-cloud agent` joins 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.
+- **Remote cache, one URL.** `vx-cloud connect <url>` wires analytics
+  ingest AND a Turborepo-wire-compatible artifact store (HMAC signing,
+  trusted/untrusted tiers derived from the token). Third-party Turbo
+  cache servers work via two env vars.
+- **OTel CI/CD spans.** Declare `otel()` from `@vzn/vx-otel` in
+  `vx.workspace.ts` — OTLP/HTTP traces + metrics with ZERO
+  OpenTelemetry SDK dependency; runs flow to Grafana / Honeycomb /
+  Datadog, including `--verify` hermeticity verdicts as span status.
+- **Dashboard embedded in the `vx-cloud` binary.** Runs, flamegraphs,
+  live run cockpit with the task DAG, per-task logs + artifacts,
+  cache-key diffs ("why did this re-run?"), flaky-task detection.
+  Nothing to build or install; Docker image on ghcr for hosting.
+- **Predictive scheduling.** Opt in with `predictive: true` — the
+  scheduler reads run history and starts the longest expected critical
+  path first.
+
+Each surface lives behind a design doc under `docs/design/`.
 
 ## A cache that actually understands your build
 
@@ -130,15 +133,25 @@ with the invariant that keeps it valid —
 
 ## 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.
 - **Signed artifacts.** HMAC signing on the remote-cache wire; with a
   key configured, unsigned or tampered artifacts are rejected and the
   task simply re-runs. A poisoned cache can't reach your machines.
+- **Cache trust tiers.** The server derives trusted/untrusted from the
+  bearer token — a fork-PR artifact can never feed a trusted build.
 - **Corruption can't go live.** Artifacts are validated before they
-  enter the store; bad bytes degrade to a cache miss, never a crash.
+  enter the store (zstd-bomb and oversize downloads refused); bad
+  bytes degrade to a cache miss, never a crash.
 - **Clean exits.** SIGINT/SIGTERM reap every child process — no
   orphaned dev servers in CI.
 - **Readiness you can bound.** Persistent tasks gate downstream work
-  on a `readyWhen` signal with a `readyTimeoutMs` ceiling.
+  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.
 - **Kernel-level sandboxing**, opt-in per task, that fails the build
   on violation instead of hiding it.
 
@@ -170,29 +183,33 @@ TypeScript config with real imports · task graph with `^task`
 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 ·
-remote caching via two env vars, wire-compatible with existing
-artifact servers · `vx stats`, `--summarize`, `--profile` Chrome
-traces · `vx cache prune` with TTL and size caps.
+remote caching via one URL (or two env vars, wire-compatible with
+existing Turbo artifact 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.
 
 ## 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                 |
-| Artifact signing          | **Hard-fail** on unsigned                                            | Soft                           | No                  |
-| Per-task sandbox          | **Yes** — kernel-level, opt-in                                       | No                             | No                  |
-| MCP server for AI agents  | **Yes** (`vx mcp`, stdio)                                            | No                             | No                  |
-| Distributed CI execution  | **Yes** — OSS, self-hostable (`vx coordinator` + `vx run --worker`)  | No                             | Paid (Nx Cloud DTE) |
-| Dashboard SPA             | **Yes** — bundled into `vx serve --ui`, Solid + p50/p99 + sparklines | No                             | Paid                |
-| Self-hosted cloud         | **Yes** — same `vx serve` in Docker; one stack                       | Vercel-only                    | No (proprietary)    |
-| Plugin API                | **Yes** — Vite-style lifecycle hooks                                 | No                             | Yes (TS-tied)       |
-| Predictive scheduling     | **Yes** (opt-in: `predictive: true`)                                 | No                             | No                  |
-| OTel CI/CD spans          | **Yes** (`OTEL_EXPORTER_OTLP_ENDPOINT`)                              | No                             | Paid                |
-| Install                   | **Single binary** — 1 curl line                                      | 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                 |
+| Artifact signing          | **Hard-fail** on unsigned                                             | Soft                           | No                  |
+| 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 + `POST /mcp` on the serve)                   | No                             | No                  |
+| Distributed CI execution  | **Yes** — OSS, self-hostable (`vx-cloud agent`, Nx-DTE-style)         | No                             | Paid (Nx Cloud DTE) |
+| Dashboard SPA             | **Yes** — embedded in `vx-cloud serve --ui`: runs, logs, DAG, flaky   | No                             | Paid                |
+| Self-hosted cloud         | **Yes** — `vx-cloud` binary or the ghcr Docker image; one stack       | Vercel-only                    | No (proprietary)    |
+| 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                |
+| 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
@@ -251,22 +268,20 @@ Side-by-side feature matrix + every known gap: [`docs/comparison.md`](./docs/com
 `bin.ts → cli/index.ts` dispatches subcommands.
 `orchestrator/run.ts:run()` calls `prepareRun()` which discovers the
 workspace, loads configs, builds the package + task graph, opens the
-cache (local SQLite + optional remote layer), loads
-`HistoryProvider` (if `predictive: true`), and installs plugins from
-`vx.workspace.ts`. The scheduler runs the graph in topological order
-with bounded concurrency; each task hits the cache (hash → get →
+cache (local SQLite + optional remote layer), and installs plugins
+from `vx.workspace.ts`. The two-tier scheduler runs the graph in
+topological order with bounded concurrency (confirmed cache hits
+restore ahead of their deps); each task hits the cache (hash → get →
 restore on hit; spawn → save on miss) or short-circuits as a group /
-persistent. Every observation flows through one event bus —
-terminal renderer, MCP server, OTel bridge, user plugins, and cloud
-uploader all subscribe to it. The on-wire form (JSON-RPC 2.0 +
-OTel-LogRecord-shaped payload) is the same across WS / SSE / NDJSON
-on `vx serve` and across the distributed-CI coordinator. Every
-module has a docs page; every interface is a swappable seam.
+persistent. Every observation flows through one event bus — the
+terminal renderer subscribes directly, and PLUGINS receive the
+versioned telemetry contract (`TelemetryRecord` / `RunSummaryRecord`)
+— that's how `otel()` and `cloud()` export without core knowing 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 2026-06 platform arc is documented under
-[`docs/design/`](./docs/design/) and
-[`docs/progress/implementation-log-2026-06.md`](./docs/progress/implementation-log-2026-06.md).
+map; the design record lives under [`docs/design/`](./docs/design/).
 
 ## Documentation
 
@@ -287,8 +302,8 @@ Full technical docs live under [`docs/`](./docs/):
 - [`architecture-north-star-2026-06.md`](./docs/design/architecture-north-star-2026-06.md) — the unified vision
 - [`architecture-review-2026-06.md`](./docs/design/architecture-review-2026-06.md) — review + applied checklist
 - [`wire-protocol-2026-06.md`](./docs/design/wire-protocol-2026-06.md) — JSON-RPC 2.0 + OTel envelope (shipped)
-- [`distributed-ci-2026-06.md`](./docs/design/distributed-ci-2026-06.md) — coordinator + worker (Phase A-B shipped)
-- [`vx-cloud-2026-06.md`](./docs/design/vx-cloud-2026-06.md) — original CF cloud (superseded; vx serve now runs in Docker)
+- [`distributed-ci-2026-06.md`](./docs/design/distributed-ci-2026-06.md) — original coordinator/worker (superseded by `vx-cloud agent` DTE — `distributed-execution-2026-07.md`)
+- [`vx-cloud-2026-06.md`](./docs/design/vx-cloud-2026-06.md) — original CF cloud (superseded by the standalone `vx-cloud` service)
 - [`extension-protocol-2026-06.md`](./docs/design/extension-protocol-2026-06.md) — subscriber/inspector/driver/plugin (Phase 1 shipped)
 - [`predictive-execution-2026-06.md`](./docs/design/predictive-execution-2026-06.md) — history-aware scheduling (Phase A-B shipped)
 - [`docs/progress/implementation-log-2026-06.md`](./docs/progress/implementation-log-2026-06.md) — phase-by-phase narrative
@@ -296,25 +311,27 @@ Full technical docs live under [`docs/`](./docs/):
 ## Status
 
 **Pre-alpha.** The schema is settling; we bump `CACHE_VERSION` rather
-than maintain back-compat. **958+ tests across 70 files; CI green on
-every commit**; the project dogfoods itself (`bun run ci` → `vx run ci`).
+than maintain back-compat. **1,400+ 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)
+and `@vzn/vx-cloud`, both as prebuilt standalone binaries.
 
 Production readiness for the **core task runner**: the semantics are
-solid. The rough edges are operational (Windows unsupported, no
-published versions on npm).
-
-Production readiness for the **2026-06 platform layer**:
-
-| Surface                                       | Maturity                         | Notes                                                                    |
-| --------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------ |
-| Core task runner + caching                    | **production-ready**             | dogfooded continuously; 836 tests pre-existing, all green                |
-| `vx mcp`                                      | **shippable**                    | live cache.db tools, stdio; agents work today                            |
-| `vx serve` (WS + SSE + NDJSON, JSON-RPC 2.0)  | **shippable**                    | accepts both legacy + new envelope; `curl` works                         |
-| `vx coordinator` + `vx run --worker`          | **shippable for self-hosted CI** | content-addressed assignment, disconnect recovery                        |
-| Plugin API                                    | **shippable**                    | crash-isolated, lifecycle hooks fire end-to-end                          |
-| Predictive scheduling                         | **shippable as opt-in**          | gated on `predictive: true` + observed data                              |
-| Dashboard SPA (`packages/cloud/ui`, embedded) | **scaffold**                     | served by `vx-cloud`; HTTP /v1/\* reads; pages need real-world iteration |
-| OTel export (`@vzn/vx-otel` telemetry plugin) | **shippable**                    | declare `otel()` in `vx.workspace.ts`; OTLP traces + metrics             |
+solid. The main operational rough edge is Windows (unsupported).
+
+Production readiness for the **platform layer**:
+
+| Surface                                        | Maturity                         | Notes                                                            |
+| ---------------------------------------------- | -------------------------------- | ---------------------------------------------------------------- |
+| Core task runner + caching                     | **production-ready**             | dogfooded continuously; 1,150+ core tests, all green             |
+| `vx run --verify` (provable cache correctness) | **shippable**                    | determinism + input-completeness proofs; CI-gate recipe in docs  |
+| `vx mcp` + serve `POST /mcp`                   | **shippable**                    | live cache.db tools (stdio); serve-hosted MCP behind the bearer  |
+| `vx-cloud serve` (ingest + dashboard + /v8)    | **shippable**                    | token-auth, multi-workspace, artifact store, ghcr image          |
+| `vx-cloud agent` distributed execution         | **shippable for self-hosted CI** | session-keyed DTE, shared pools, fair multi-run scheduling       |
+| Plugin API (backend / cache / telemetry)       | **shippable**                    | crash-isolated; `cloud()` + `otel()` are ordinary plugins        |
+| Predictive scheduling                          | **shippable as opt-in**          | gated on `predictive: true` + observed data                      |
+| Dashboard SPA (embedded in `vx-cloud`)         | **iterating**                    | runs/logs/DAG/flaky live; data-first entity redesign in progress |
+| OTel export (`@vzn/vx-otel`)                   | **shippable**                    | declare `otel()` in `vx.workspace.ts`; OTLP traces + metrics     |
 
 ## Development
 

package/launcher.mjs

@@ -1,44 +1,52 @@
 #!/usr/bin/env node
-// npm launcher for the `vx` command — the entry the published `@vzn/vx`
-// package's `bin` points at. It execs the prebuilt standalone binary shipped
-// as a per-platform optionalDependency (@vzn/vx-<platform>), so end users get
-// vx WITHOUT installing Bun. This file is authored for the PUBLISHED layout:
-// at install time it sits at the package root, next to `src/`.
+// 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.
+//
+//   @vzn/vx        → platform pkg @vzn/vx-<key>,        binary `vx`
+//   @vzn/vx-cloud  → platform pkg @vzn/vx-cloud-<key>,  binary `vx-cloud`
 //
 // Resolution order:
-//   1. the matching @vzn/vx-<platform> optionalDependency's binary (the
-//      normal path — esbuild/turborepo/biome model, no install-time download);
-//   2. a source fallback: `bun src/bin.ts` (works in a source checkout, or on a
-//      platform with no prebuilt binary if the user happens to have Bun).
+//   1. the matching <name>-<platform> optionalDependency's binary (the normal
+//      path — esbuild/turborepo/biome model, no install-time download);
+//   2. a source fallback: `bun <sourceEntry>` (a source checkout, or a platform
+//      with no prebuilt binary if the user happens to have Bun).
 // Anything else is a clear, actionable error.
 
 import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
+import { constants as osConstants } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const require = createRequire(import.meta.url)
 const here = dirname(fileURLToPath(import.meta.url))
+const pkg = require('./package.json')
 
-const PLATFORM_PACKAGES = {
-  'linux-x64': '@vzn/vx-linux-x64',
-  'linux-arm64': '@vzn/vx-linux-arm64',
-  'darwin-x64': '@vzn/vx-darwin-x64',
-  'darwin-arm64': '@vzn/vx-darwin-arm64',
-}
+// 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.
+const name = pkg.name
+const base = name.replace(/^@[^/]+\//, '')
+const sourceEntry = pkg.vxSourceEntry ?? 'src/bin.ts'
 
+const SUPPORTED = ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64']
 const key = `${process.platform}-${process.arch}`
 const args = process.argv.slice(2)
 
 function platformBinary() {
-  const pkg = PLATFORM_PACKAGES[key]
-  if (pkg === undefined) return undefined
+  if (!SUPPORTED.includes(key)) return undefined
+  const platformPkg = `${name}-${key}`
   try {
     // No `exports` restriction on the platform packages, so package.json
     // resolves; the binary sits beside it. Works under npm hoisting + pnpm.
-    const manifest = require.resolve(`${pkg}/package.json`)
-    const bin = join(dirname(manifest), 'vx')
+    const manifest = require.resolve(`${platformPkg}/package.json`)
+    const bin = join(dirname(manifest), base)
     return existsSync(bin) ? bin : undefined
   } catch {
     return undefined
@@ -53,11 +61,11 @@ function hasBun() {
 function run(cmd, cmdArgs) {
   const res = spawnSync(cmd, cmdArgs, { stdio: 'inherit' })
   if (res.error) {
-    process.stderr.write(`vx: failed to launch (${res.error.message})\n`)
+    process.stderr.write(`${base}: failed to launch (${res.error.message})\n`)
     process.exit(1)
   }
   // Mirror the child's exit; a signal death maps to the POSIX 128+signo code.
-  if (res.signal) process.exit(1)
+  if (res.signal) process.exit(128 + (osConstants.signals[res.signal] ?? 1))
   process.exit(res.status ?? 0)
 }
 
@@ -68,17 +76,17 @@ if (bin !== undefined) {
 
 // No prebuilt binary for this platform — fall back to the shipped source if Bun
 // is available (a source checkout, or an unsupported platform + Bun installed).
-const sourceEntry = join(here, 'src', 'bin.ts')
-if (existsSync(sourceEntry) && hasBun()) {
-  run('bun', [sourceEntry, ...args])
+const source = join(here, sourceEntry)
+if (existsSync(source) && hasBun()) {
+  run('bun', [source, ...args])
 }
 
-const supported = Object.keys(PLATFORM_PACKAGES).join(', ')
+const supported = SUPPORTED.join(', ')
 process.stderr.write(
-  `vx: no prebuilt binary for ${key}.\n` +
+  `${base}: no prebuilt binary for ${key}.\n` +
     `  Supported platforms: ${supported}.\n` +
     `  If your platform should be supported, reinstall so npm fetches the\n` +
-    `  matching @vzn/vx-${key} optionalDependency, or install Bun (>=1.3) to\n` +
-    `  run vx from source.\n`,
+    `  matching ${name}-${key} optionalDependency, or install Bun (>=1.3) to\n` +
+    `  run ${base} from source.\n`,
 )
 process.exit(1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.12",
+  "version": "0.0.15",
   "description": "An open, extensible monorepo task runner.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.12",
-    "@vzn/vx-linux-arm64": "0.0.12",
-    "@vzn/vx-darwin-x64": "0.0.12",
-    "@vzn/vx-darwin-arm64": "0.0.12"
+    "@vzn/vx-linux-x64": "0.0.15",
+    "@vzn/vx-linux-arm64": "0.0.15",
+    "@vzn/vx-darwin-x64": "0.0.15",
+    "@vzn/vx-darwin-arm64": "0.0.15"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.56"

package/src/cache/cas-backend.ts

@@ -1,7 +1,7 @@
 // CASBackend — pluggable content-addressed storage beneath the cache.
 //
-// Today's Cache + LayeredCache + RemoteCache all bundle "where do the
-// bytes live" with "how do we look up entries metadata + key derivation."
+// Today's Cache + LayeredCache both bundle "where do the bytes live"
+// with "how do we look up entries metadata + key derivation."
 // CASBackend separates the former so a future R2/S3 backend
 // or REAPI CAS bridge can drop in without touching the
 // orchestrator or the SQL entries index.

package/src/cache/index.ts

@@ -25,5 +25,4 @@ export {
   resolveOutputs,
   resolveWorkspaceOutputs,
 } from './inputs.js'
-export { LayeredCache } from './layered-cache.js'
-export { RemoteCache } from './remote-cache.js'
+export { LayeredCache, type RemoteCacheLayer } from './layered-cache.js'

package/src/cache/inputs.ts

@@ -34,6 +34,12 @@ const ALWAYS_IGNORE = [
   '**/.vx/**',
   '**/*.tsbuildinfo',
   '**/vx-lock.json',
+  // `bun build --compile` writes a transient `.<hash>-<n>.bun-build` intermediate
+  // in the cwd. It never rests on disk, so it can't be a real input — but a
+  // broad `inputs.files: ['**/*']` on a compile task would try to hash the temp
+  // file that a CONCURRENT compile is mid-write, racing to EACCES/ENOENT. Always
+  // exclude it (vx is Bun-native; compiling standalone binaries is a common task).
+  '**/*.bun-build',
 ]
 
 const DEFAULT_FILE_GLOBS: readonly string[] = ['**/*']

package/src/cache/layered-cache.ts

@@ -32,7 +32,27 @@ import type {
   SaveArgs,
 } from './cache.js'
 import { FULL_CACHE_POLICY } from './cache.js'
-import type { RemoteCache } from './remote-cache.js'
+
+/**
+ * What a remote cache layer must provide — THE plugin seam for remote
+ * caching. Core ships no wire client; a plugin's `cache` capability (or an
+ * embedder via `RunOptions.remoteCache`) supplies an implementation speaking
+ * whatever protocol it wants, and `LayeredCache` owns everything else:
+ * policy gating, in-flight dedup, remote provenance, and the never-fail
+ * contract (implementations THROW on failure; LayeredCache degrades every
+ * throw to a cache miss via `onRemoteError`). The artifact bytes are the
+ * local `<hash>.tar.zst` verbatim. See
+ * docs/design/native-cache-wire-2026-07.md.
+ */
+export interface RemoteCacheLayer {
+  /** Existence probe (drives the plan path's `--dry` remote prediction). */
+  has(hash: string): Promise<boolean>
+  /** Fetch an artifact's bytes; `null` = miss. `durationMs` is the
+   *  producing task's duration when the wire carries it. */
+  get(hash: string): Promise<{ body: ArrayBuffer; durationMs: number | undefined } | null>
+  /** Store an artifact (fire-and-forget from LayeredCache's perspective). */
+  put(hash: string, body: ArrayBuffer | Uint8Array, meta: { durationMs: number }): Promise<void>
+}
 
 /**
  * Cap on concurrent background PUTs. Keeps a burst of cache misses from
@@ -90,7 +110,7 @@ export class LayeredCache implements CacheLayer {
 
   constructor(
     private readonly local: Cache,
-    private readonly remote: RemoteCache,
+    private readonly remote: RemoteCacheLayer,
     private readonly options: LayeredCacheOptions = {},
   ) {
     this.policy = options.policy ?? FULL_CACHE_POLICY

package/src/cli/cache.ts

@@ -1,7 +1,12 @@
 import { Cache } from '../cache/index.js'
+import { parseSize } from '../util/index.js'
 import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
 import { formatBytes } from './format.js'
 
+// parseSize moved to `util` (the orchestrator's resource resolver needs it
+// and can't import cli); re-exported here so existing callers are unchanged.
+export { parseSize } from '../util/index.js'
+
 export async function cacheCmd(args: readonly string[]): Promise<number> {
   const [sub, ...rest] = args
   switch (sub) {
@@ -89,13 +94,3 @@ export function parseDuration(input: string): number | null {
   const mult = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000
   return n * mult
 }
-
-export function parseSize(input: string): number | null {
-  const m = input.match(/^(\d+)([KMGT])?B?$/i)
-  if (!m) return null
-  const n = Number(m[1])
-  const u = (m[2] ?? '').toUpperCase()
-  const mult =
-    u === '' ? 1 : u === 'K' ? 1024 : u === 'M' ? 1024 * 1024 : u === 'G' ? 1024 ** 3 : 1024 ** 4
-  return n * mult
-}

package/src/cli/help.ts

@@ -44,10 +44,16 @@ export function printHelp(): void {
       '      --timeout <ms>              Default per-task timeout for tasks without their own exec.timeout',
       '                                  (above VX_TASK_TIMEOUT env + workspace timeout). Kills + fails',
       '                                  a runaway task. Per-task exec.timeout always wins.',
+      '      --memory <size>             Memory budget (e.g. 8GB) that exec.resources.memory reservations',
+      '                                  pack against. Default: total system RAM — pass this in',
+      '                                  cgroup-limited containers (the default reads the HOST RAM).',
+      '                                  Reservations are per-task config (exec.resources), not flags.',
       '      --verify[=<what>]           Prove cache correctness. determinism (default): re-run each',
       '                                  executed cacheable task + content-compare outputs. inputs: sandbox',
       '                                  with the declared-input baseline + flag reads of undeclared inputs.',
-      '                                  all: both. An unsafe task fails the run with the exact paths.',
+      '                                  fingerprint: ship output-tree fingerprints for the cross-machine',
+      '                                  diff on a connected serve (~1× exec — no re-run). all: everything.',
+      '                                  An unsafe task fails the run with the exact paths.',
       '                                  ~2× exec (determinism); CI-shaped. inputs/all need the OS sandbox.',
       '      --verify-allow <pkg#task,…> Exempt known-nondeterministic tasks from failing --verify.',
       '      --frozen                    Load configs from vx-lock.json (CI; pair with vx lock --check).',
@@ -95,7 +101,7 @@ export function printHelp(): void {
       '      --format <fmt>   pretty (default) | json.',
       '  vx info              Workspace doctor: vx/bun/git versions, project +',
       '                       task counts, cache dir/entries/size, recent runs,',
-      '                       lock + remote-cache status.',
+      '                       lock status.',
       '  vx stats             Deprecated: alias of vx info.',
       '  vx mcp               Model Context Protocol server (stdio) — exposes inspector',
       '                       RPCs as MCP tools for AI agents (Claude Code, Cursor, …).',

package/src/cli/info.ts

@@ -48,8 +48,6 @@ export async function infoCmd(args: readonly string[]): Promise<number> {
   }
 
   const lockPresent = await Bun.file(lockfilePath(root)).exists()
-  const remoteConfigured =
-    Boolean(process.env.VX_REMOTE_CACHE_URL) && Boolean(process.env.VX_REMOTE_CACHE_TOKEN)
 
   const rows: [string, string][] = [
     ['vx', VERSION],
@@ -61,7 +59,6 @@ export async function infoCmd(args: readonly string[]): Promise<number> {
     ['cache entries', `${stats.entryCount} (${formatBytes(stats.totalBytes)})`],
     ['runs (24h)', `${stats.runCountLast24h} (${stats.hitCountLast24h} cache hits)`],
     ['vx-lock.json', lockPresent ? 'yes' : 'no'],
-    ['remote cache', remoteConfigured ? 'yes' : 'no'],
   ]
   const labelW = Math.max(...rows.map(([label]) => label.length))
   const lines = rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`)