@vzn/vx 0.0.645 → 0.0.648

package/README.md

@@ -23,37 +23,19 @@ Task orchestration with a cache you can trust, on a core you can extend.
 Each task is one shell command with declared inputs and outputs; vx runs
 them in dependency order and replays results from a content-addressed cache.
 
-## Install
-
-```sh
-npm install -D @vzn/vx     # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
-```
-
-A prebuilt binary for Linux (glibc, not Alpine's musl) and macOS, x64 and arm64; no Bun needed. The
-[release](https://github.com/vznjs/vx/releases) binary needs no Node either.
-Windows: run vx inside WSL2.
-
 ## Quick start
 
 In a git repo:
 
 ```sh
-npx @vzn/vx init       # installs vx globally and in the repo; beside turbo.json or nx.json: migrates them; else a root vx.config.ts
-vx run build --all     # builds in dependency order and stores the results
-vx run build --all     # nothing changed: every task up-to-date
+bunx @vzn/vx init   # installs vx, writes an empty root vx.config.ts and the lockfile plugin
 ```
 
-Bun workspaces: `bun add -d @vzn/vx` and `bunx @vzn/vx` (npm refuses to run in
-a repo whose `devEngines` names Bun).
+A prebuilt binary for Linux (glibc, not Alpine's musl) and macOS, x64 and
+arm64. Windows: run vx inside WSL2.
 
-Without Turbo or Nx, tasks run uncached until you declare what they read (below).
-
-`init` prints what it wrote and anything left to decide (a `TODO`). A miss you did not expect?
-`npx @vzn/vx why <task>` names the input that moved.
-
-### Without Turbo or Nx
-
-`init` writes one task per package script, uncached. Cache one by saying what it reads and writes:
+A task runs its tool directly, never through a package script. Cache one by
+saying what it reads and writes:
 
 ```ts
 // packages/app/vx.config.ts
@@ -74,10 +56,10 @@ export default defineProject({
 ```
 
 ```sh
-npx @vzn/vx run build --all    # builds, in dependency order; stores the results
-npx @vzn/vx run build --all    # nothing changed: up-to-date, in milliseconds
+vx run build --all    # builds, in dependency order; stores the results
+vx run build --all    # nothing changed: up-to-date, in milliseconds
 rm -rf packages/*/dist
-npx @vzn/vx run build --all    # restored from the cache, not rebuilt
+vx run build --all    # restored from the cache, not rebuilt
 ```
 
 <img src="https://vznjs.github.io/vx/demo.svg" width="760" alt="vx run ci --all on examples/basic: cold, three tasks run; again, three up-to-date.">
@@ -86,7 +68,7 @@ npx @vzn/vx run build --all    # restored from the cache, not rebuilt
 
 `init` also writes `.vx/projects.lock.json`, every project's config as it evaluated.
 Commit it. Every run reads its configs from the lock, so run
-`npx @vzn/vx lock` and commit the lock again after you:
+`vx lock` and commit the lock again after you:
 
 - edit any `vx.config.ts` or `.vx/workspace.ts`,
 - update dependencies or plugins,
@@ -97,12 +79,11 @@ stale lock before any task runs.
 
 Starters: [`examples/basic`](examples/basic), and
 [`examples/ci`](examples/ci) with a GitHub Actions workflow; CI runs both
-on every commit. The [CI guide](https://vznjs.github.io/vx/guides/ci/)
+on every commit. The [CI guide](https://vznjs.github.io/vx/docs/ci/)
 explains the workflow.
 More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
-[Configure](https://vznjs.github.io/vx/guides/configure/) ·
-[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).
+[Configure](https://vznjs.github.io/vx/docs/workspace/) ·
+[CLI](packages/vx/docs/cli.md) · [every config field](packages/vx/docs/schema.md).
 
 ## A foundation you own
 
@@ -120,21 +101,29 @@ More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 
 What vx can do, not what it is limited to. Declared in `.vx/workspace.ts`; without any, vx runs and caches locally.
 
-| Package                                                    | What it adds                                                                  |
-| ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [`@vzn/vx-migrate`](packages/vx-migrate)                   | Migrate from Turbo or Nx: write native 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-ci`](packages/vx-ci)                             | GitHub Actions job summary and Checks API                                     |
-| [`@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/) ·
+| Package                                                | What it adds                                                                  |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`@vzn/vx-migrate`](packages/vx-migrate)               | Migrate from Turbo or Nx: write native 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-ci`](packages/vx-ci)                         | GitHub Actions job summary                                                    |
+| [`@vzn/vx-history`](packages/vx-history)               | Schedule by the critical path learned from past runs                          |
+| [`@vzn/vx-cache`](packages/vx-cache)                   | Remote cache for CI jobs, on a vx cache server                                |
+| [`@vzn/vx-cache-server`](packages/vx-cache-server)     | The cache server you host: Bun or Docker with S3, or Workers with R2          |
+| [`@vzn/vx-history-server`](packages/vx-history-server) | The task timings server `vxHistory()` reads: Bun, Docker or Workers           |
+| [`@vzn/vx-devtools`](packages/vx-devtools)             | Code the servers and plugins share: the CI OIDC token check                   |
+| [`@vzn/vx-dte`](packages/vx-dte)                       | Spread one run over workers your own CI starts                                |
+| [`@vzn/vx-dte-server`](packages/vx-dte-server)         | The relay `dte()` meets its workers at: Workers, Bun or Docker                |
+
+Hosting the three servers: [servers docs](https://vznjs.github.io/vx/docs/servers/).
+
+Write your own: [plugin guide](https://vznjs.github.io/vx/docs/writing-plugins/) ·
 [architecture](packages/vx/docs/architecture.md).
 
 ## Coming from Turbo or Nx
 
-Beside `turbo.json` or `nx.json`, `npx @vzn/vx init` runs `@vzn/vx-migrate`:
+Beside `turbo.json` or `nx.json`, `bunx @vzn/vx init` runs `@vzn/vx-migrate`:
 it writes a `vx.config.ts` per package from `turbo.json` or the Nx graph,
 and you keep those and delete the old config. `vx init --keep` writes only
 a `.vx/workspace.ts` that maps the old config instead, and its lock: a temporary start,
@@ -163,19 +152,19 @@ Every gap, and when another tool is the better pick:
 - **No source-file reads to hash:** on a clean tree, keys come from git's index; each project's `package.json` and the lockfile are still read.
 - **One pass:** one git walk per run; each stat and lookup happens once.
 
-<!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
+<!-- bench:start — generated by private/vx-bench/update-site.ts from results.json; do not hand-edit -->
 
-| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx         | Turborepo | Nx         | Vite Task |
-| ---------------------------------------------------------- | ---------- | --------- | ---------- | --------- |
-| Nothing changed                                            | **757 ms** | 761 ms    | 22.63 s    | 12.26 s   |
-| Nothing changed, outputs restored                          | **1.27 s** | 1.76 s    | 22.16 s    | 11.66 s   |
-| Cold build                                                 | **6.13 s** | 8.87 s    | 3 min 20 s | 7.94 s    |
-| Cold build: CPU the runner burns                           | 30.06 s    | 1 min 8 s | 5 min 45 s | 23.91 s   |
+| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx         | Turborepo  | Nx         | Vite Task |
+| ---------------------------------------------------------- | ---------- | ---------- | ---------- | --------- |
+| Nothing changed                                            | **799 ms** | 927 ms     | 24.15 s    | 12.07 s   |
+| Nothing changed, outputs restored                          | **1.28 s** | 2.01 s     | 24.45 s    | 11.86 s   |
+| Cold build                                                 | **7.57 s** | 9.63 s     | 3 min 6 s  | 9.01 s    |
+| Cold build: CPU the runner burns                           | 36.64 s    | 1 min 12 s | 5 min 34 s | 25.32 s   |
 
 Time each tool adds over the ideal run; lower is better.
 
 Benchmark workload: a synthetic monorepo of 1,601 projects and 9,603 tasks in 30 dependency levels, five core libraries a quarter of the projects use; build 300 ms, test and typecheck 150 ms, lint 75 ms, publish 30 ms; real repos with uneven task times will differ.
-Run 2026-10-20 on linux x64, 4 cores: vx at commit a88652b0b, Turborepo 2.11.9, Nx 23.3.0, Vite Task (vite-plus) 1.3.0.
+Run 2026-10-25 on linux x64, 4 cores: vx at commit 9abdfb52c, Turborepo 2.11.10, Nx 24.0.1, Vite Task (vite-plus) 1.4.0.
 
 Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).
 

package/launcher.cjs

@@ -102,8 +102,15 @@ function run(cmd, cmdArgs) {
     process.stderr.write(`${base}: failed to launch (${err.message})\n`)
     process.exit(1)
   })
-  // Mirror the child's exit; a signal death maps to the POSIX 128+signo code.
+  // Mirror the child's exit. A stop signal vx died of is mirrored by dying
+  // of it: a shell running vx in a script stops on Ctrl-C only when its
+  // child died of SIGINT, and an exit 130 ran the script's next line. The
+  // POSIX 128+signo code is the rest, and the fallback should it not land.
   child.on('exit', (code, signal) => {
+    if (signal === 'SIGINT' || signal === 'SIGTERM' || signal === 'SIGHUP') {
+      process.removeAllListeners(signal)
+      process.kill(process.pid, signal)
+    }
     process.exit(signal ? 128 + (osConstants.signals[signal] ?? 1) : (code ?? 0))
   })
 }
@@ -133,7 +140,7 @@ if (bin !== undefined) {
     `${base}: no prebuilt binary for ${key}${noGlibc ? ' without glibc (musl)' : ''}.\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.4) to\n` +
+      `  matching ${name}-${key} optionalDependency, or install Bun (>=1.4.4) to\n` +
       `  run ${base} from source.\n`,
   )
   process.exit(1)

package/launcher.sh

@@ -29,14 +29,14 @@ base=${here##*/}
 scope=${here%/*}
 scope=${scope##*/}
 
-# A global vx hands off to the project's own (owner, 2026-10-13): the
+# A global vx hands off to the project's own (2026-10-13): the
 # workspace root's node_modules/<scope>/<name>, through its .bin entry. The
 # root is the first directory holding a .vx/workspace.* from the working
 # directory up to the git top-level (handoff.ts workspaceFile, the same
 # rule). One hop (VX_HANDED_OFF, which also names this launcher), never to
 # this package itself (`-ef`: same inode, so a pnpm symlink counts as
 # itself). Shell tests and builtins only, no fork per level. `vx upgrade -g`
-# moves only this global vx, so it never hands off (owner, 2026-10-16).
+# moves only this global vx, so it never hands off (2026-10-16).
 stay=
 if [ "${1-}" = upgrade ]; then
   for a in "$@"; do

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.645",
+  "version": "0.0.648",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.645",
-    "@vzn/vx-linux-arm64": "0.0.645",
-    "@vzn/vx-darwin-x64": "0.0.645",
-    "@vzn/vx-darwin-arm64": "0.0.645"
+    "@vzn/vx-linux-x64": "0.0.648",
+    "@vzn/vx-linux-arm64": "0.0.648",
+    "@vzn/vx-darwin-x64": "0.0.648",
+    "@vzn/vx-darwin-arm64": "0.0.648"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/cache.json

@@ -1,15 +1,15 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "vx cache clean --format json",
-  "description": "With a bound (prune): what the policy evicted and the orphan sweep reaped. With no bound (clear): the directories it deleted. With dryRun, what they would.",
+  "description": "With a bound (prune): what the policy evicted and the orphan sweep reaped. With no bound (clear): the directories it deleted. With dry, what they would.",
   "oneOf": [{ "$ref": "#/$defs/prune" }, { "$ref": "#/$defs/clear" }],
   "$defs": {
     "prune": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["dryRun", "evicted", "bytesFreed", "orphans", "orphanBytes"],
+      "required": ["dry", "evicted", "bytesFreed", "orphans", "orphanBytes"],
       "properties": {
-        "dryRun": { "type": "boolean" },
+        "dry": { "type": "boolean" },
         "evicted": {
           "type": "integer",
           "description": "index entries evicted by the age / size policy"
@@ -28,9 +28,9 @@
     "clear": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["dryRun", "cleared", "bytesFreed"],
+      "required": ["dry", "cleared", "bytesFreed"],
       "properties": {
-        "dryRun": { "type": "boolean" },
+        "dry": { "type": "boolean" },
         "cleared": {
           "type": "array",
           "items": { "type": "string" },

package/schemas/error.json

@@ -14,7 +14,7 @@
       "properties": {
         "code": {
           "type": "string",
-          "description": "Stable; branch on it. VX_E_USAGE, VX_E_UNKNOWN_COMMAND, VX_E_UNKNOWN_TASK, VX_E_UNKNOWN_PROJECT, VX_E_NO_HISTORY, VX_E_AMBIGUOUS, VX_E_CONFIG, VX_E_CYCLE, VX_E_NO_WORKSPACE, VX_E_CACHE_VERSION, VX_E_REFUSED, VX_E_FS, VX_E_FDS, VX_E_INTERNAL."
+          "description": "Stable; branch on it. VX_E_USAGE, VX_E_UNKNOWN_COMMAND, VX_E_UNKNOWN_TASK, VX_E_UNKNOWN_PROJECT, VX_E_NO_HISTORY, VX_E_AMBIGUOUS, VX_E_CONFIG, VX_E_CYCLE, VX_E_LOCK, VX_E_NO_WORKSPACE, VX_E_CACHE_VERSION, VX_E_REFUSED, VX_E_FS, VX_E_FDS, VX_E_AFFECTED_BASE, VX_E_NO_GIT, VX_E_GIT, VX_E_NETWORK, VX_E_DEPENDS_ON, VX_E_OUTPUT_OVERLAP, VX_E_INPUT_IS_OUTPUT, VX_E_DEPENDENCY_RULE, VX_E_NESTED_INPUT, VX_E_INTERNAL. A plugin may name its own."
         },
         "message": { "type": "string", "description": "The refusal in prose; may change." },
         "docs": {

package/schemas/info.json

@@ -25,6 +25,7 @@
     "schemaVersion",
     "cacheEntries",
     "cacheBytes",
+    "cacheIndexError",
     "settings",
     "orphans",
     "runs24h",
@@ -32,6 +33,7 @@
     "restored24h",
     "flakyTasks",
     "lockfile",
+    "lockError",
     "sandbox"
   ],
   "properties": {
@@ -68,7 +70,7 @@
       "required": ["count", "source", "cores", "cpuQuota"],
       "properties": {
         "count": { "type": "integer" },
-        "source": { "enum": ["workspace", "cgroup", "cores"] },
+        "source": { "enum": ["env", "workspace", "cgroup", "cores"] },
         "cores": { "type": "integer" },
         "cpuQuota": { "type": ["number", "null"] }
       }
@@ -91,6 +93,10 @@
     "schemaVersion": { "type": "string" },
     "cacheEntries": { "type": "integer" },
     "cacheBytes": { "type": "integer" },
+    "cacheIndexError": {
+      "type": ["string", "null"],
+      "description": "Why the cache index cannot be read, with the fix; null when it reads. While set, the counts it holds read 0."
+    },
     "settings": {
       "type": "object",
       "description": "every setting (docs/schema.md § Settings) by path, as a run with no flags takes it: its variable as written, else .vx/workspace's value, else null with source default",
@@ -100,7 +106,11 @@
         "required": ["value", "source"],
         "properties": {
           "value": { "type": ["string", "number", "boolean", "null"] },
-          "source": { "enum": ["env", "workspace", "default"] }
+          "source": { "enum": ["env", "workspace", "default"] },
+          "refused": {
+            "type": "string",
+            "description": "why a run refuses the variable's value; absent when a run takes it"
+          }
         }
       }
     },
@@ -133,6 +143,10 @@
       }
     },
     "lockfile": { "type": "boolean" },
+    "lockError": {
+      "type": ["string", "null"],
+      "description": "Why a run refuses the lock that is there (run `vx lock`); null when a run reads it or there is none."
+    },
     "sandbox": {
       "type": "object",
       "additionalProperties": false,

package/schemas/last.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "vx last --format json",
-  "description": "`vx last [RUNID] [--failed]` prints a run; `--list` prints an array of invocations, newest first; `--log <task>` prints that task's output; `--stats` prints per-task history numbers.",
+  "description": "`vx last [RUNID] [--failed]` prints a run; `--list` prints an array of invocations, newest first; `--log <task>` prints that task's output; `--stats` prints per-task history numbers; `--sql` prints the rows a read-only query over the history selects; `--live` prints the run in progress (with `--follow`, its events after, one per line).",
   "oneOf": [
     {
       "type": "object",
@@ -9,14 +9,88 @@
       "required": ["invocation", "tasks"],
       "properties": {
         "invocation": { "$ref": "#/$defs/invocation" },
-        "tasks": { "type": "array", "items": { "$ref": "#/$defs/task" } }
+        "tasks": { "type": "array", "items": { "$ref": "#/$defs/task" } },
+        "warnings": {
+          "type": "array",
+          "description": "what the run warned of, plain text; absent when it warned of nothing",
+          "items": { "type": "string" }
+        },
+        "steps": {
+          "type": "array",
+          "description": "vx's own steps the run did not wait on (vx:prefetch); absent when it had none or they are no longer kept",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "durationMs", "ok"],
+            "properties": {
+              "id": { "type": "string" },
+              "durationMs": { "type": "number" },
+              "ok": { "type": "boolean" }
+            }
+          }
+        }
       }
     },
     { "type": "array", "items": { "$ref": "#/$defs/invocation" } },
     { "$ref": "#/$defs/log" },
-    { "$ref": "#/$defs/stats" }
+    { "$ref": "#/$defs/stats" },
+    { "$ref": "#/$defs/rows" },
+    { "$ref": "#/$defs/live" }
   ],
   "$defs": {
+    "live": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["live", "tasks", "warnings"],
+      "properties": {
+        "live": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["runId", "command", "pid", "startedAt", "elapsedMs"],
+          "properties": {
+            "runId": { "type": "string" },
+            "command": { "type": "string" },
+            "pid": { "type": "integer" },
+            "startedAt": { "type": "integer", "description": "epoch ms" },
+            "elapsedMs": { "type": "integer" }
+          }
+        },
+        "tasks": {
+          "type": "array",
+          "description": "`--live`: running first, then ended, then waiting; groups left out",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["taskId", "status", "startedAt", "durationMs"],
+            "properties": {
+              "taskId": { "type": "string" },
+              "status": {
+                "type": "string",
+                "description": "running, waiting, or the status it ended with"
+              },
+              "startedAt": { "type": ["integer", "null"] },
+              "durationMs": { "type": ["number", "null"] }
+            }
+          }
+        },
+        "warnings": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "rows": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rows"],
+      "properties": {
+        "rows": {
+          "type": "array",
+          "description": "`--sql`: one object per row, keyed by the query's column names",
+          "items": {
+            "type": "object",
+            "additionalProperties": { "type": ["string", "number", "null"] }
+          }
+        }
+      }
+    },
     "stats": {
       "type": "object",
       "additionalProperties": false,
@@ -166,6 +240,9 @@
         "hash",
         "cpuMs",
         "peakRssBytes",
+        "peakCores",
+        "avgRssBytes",
+        "placement",
         "wallclockStartNs",
         "wallclockEndNs",
         "blockedBy",
@@ -173,14 +250,18 @@
         "sandboxViolations",
         "notReady",
         "remoteError",
-        "forwarded"
+        "forwarded",
+        "attempts"
       ],
       "properties": {
         "runId": { "type": ["string", "null"] },
         "project": { "type": "string" },
         "task": { "type": "string" },
         "status": { "type": "string" },
-        "exitCode": { "type": "integer" },
+        "exitCode": {
+          "type": "integer",
+          "description": "a skipped task records 0 when an exec.platforms skip is its root, 1 behind a failure or fail-fast"
+        },
         "durationMs": { "type": "number" },
         "startedAt": { "type": "integer", "description": "epoch ms" },
         "endedAt": { "type": "integer", "description": "epoch ms" },
@@ -199,6 +280,18 @@
         "hash": { "type": "string" },
         "cpuMs": { "type": ["number", "null"] },
         "peakRssBytes": { "type": ["integer", "null"] },
+        "peakCores": {
+          "type": ["number", "null"],
+          "description": "most cores one sampling interval burned; null when nothing sampled"
+        },
+        "avgRssBytes": {
+          "type": ["integer", "null"],
+          "description": "mean resident memory over the samples; null when nothing sampled"
+        },
+        "placement": {
+          "type": ["string", "null"],
+          "description": "where an executor ran it (small#1); null when here"
+        },
         "wallclockStartNs": {
           "type": ["string", "null"],
           "description": "decimal nanoseconds from the run's start"
@@ -213,6 +306,14 @@
           "description": "each failed remote read or write of the key, `; `-joined"
         },
         "forwarded": { "type": "boolean" },
+        "inputMoved": {
+          "type": "string",
+          "description": "on a row failed by inputStability.severity 'error': the input that changed during the run"
+        },
+        "attempts": {
+          "type": ["integer", "null"],
+          "description": "the attempts a retried task took (more than one); null when it ran once"
+        },
         "output": {
           "type": "string",
           "description": "on a failed row: its output, plain text, bounded (first 8 KiB, last 56 KiB), secrets masked; '' when none was recorded"
@@ -231,6 +332,27 @@
             }
           }
         },
+        "sandboxFix": {
+          "type": "object",
+          "description": "on a sandboxed failed row: the exec.sandbox.allow entries that would have granted its denials",
+          "additionalProperties": false,
+          "properties": {
+            "read": { "type": "array", "items": { "type": "string" } },
+            "write": { "type": "array", "items": { "type": "string" } },
+            "network": { "type": "array", "items": { "type": "string" } },
+            "systemInfo": { "type": "array", "items": { "type": "string" } },
+            "withheld": {
+              "type": "array",
+              "description": "credential paths it denied and left out of the grants",
+              "items": { "type": "string" }
+            },
+            "inputs": {
+              "type": "array",
+              "description": "a cached task's reads of its project no inputs.files glob matches",
+              "items": { "type": "string" }
+            }
+          }
+        },
         "fixedIn": {
           "type": "string",
           "description": "on a failed row: the first later run where this task passed (ran or hit); absent while it has not"

package/schemas/plan.json

@@ -20,9 +20,21 @@
           "id": { "type": "string", "description": "project#task" },
           "project": { "type": "string" },
           "task": { "type": "string" },
-          "hash": { "type": "string", "description": "the cache key" },
+          "hash": {
+            "type": "string",
+            "description": "the cache key; empty when the run derives none"
+          },
           "cacheStatus": {
-            "enum": ["hit-local", "hit-remote", "miss", "no-cache", "group", "not-started"]
+            "enum": [
+              "hit-local",
+              "hit-remote",
+              "miss",
+              "no-cache",
+              "group",
+              "not-started",
+              "skipped"
+            ],
+            "description": "skipped: exec.platforms leave this machine out, or a task it depends on is skipped; the run skips it too"
           },
           "deps": { "type": "array", "items": { "type": "string" } },
           "p50Ms": {
@@ -38,6 +50,20 @@
             "description": "outputs would stay remote (--cache-download)"
           },
           "description": { "type": "string" },
+          "otherPlatform": {
+            "type": "object",
+            "description": "a skipped task's own exec.platforms, and this machine's",
+            "additionalProperties": false,
+            "required": ["needs", "host"],
+            "properties": {
+              "needs": { "type": "array", "items": { "type": "string" } },
+              "host": { "type": "string" }
+            }
+          },
+          "blockedBy": {
+            "type": "string",
+            "description": "a skipped task's root: the task off this machine's platforms it depends on"
+          },
           "affected": {
             "type": "object",
             "description": "why --affected kept this requested task; absent on a dependency it pulled in",

package/schemas/show.json

@@ -6,7 +6,12 @@
     { "type": "array", "items": { "$ref": "#/$defs/listRow" } },
     { "$ref": "#/$defs/project" },
     { "$ref": "#/$defs/task" },
-    { "type": "array", "items": { "$ref": "#/$defs/task" } }
+    {
+      "type": "array",
+      "minItems": 1,
+      "description": "`vx show <task>`; when no project in scope declares it, `[]`, which the list branch holds",
+      "items": { "$ref": "#/$defs/task" }
+    }
   ],
   "$defs": {
     "listRow": {
@@ -84,6 +89,10 @@
               "properties": { "readyWhen": { "type": "string" } }
             },
             "interactive": { "type": "boolean" },
+            "platforms": {
+              "type": "array",
+              "items": { "enum": ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64"] }
+            },
             "sandbox": {
               "type": "object",
               "description": "as declared; its fields are the `exec.sandbox` section of the config schema"

package/skills/vx/SKILL.md

@@ -53,6 +53,13 @@ does not):
 is one of its inputs), `project`, `package`, `named` or `selected`, and
 `via` is the `dependsOn` chain that carried the change.
 
+## While a run is in progress
+
+```sh
+vx last --live --format json            # what runs, what ended, what waits, warnings so far
+vx last --live --follow --format json   # then each event (output included), one per line, until the run ends
+```
+
 ## When a task fails
 
 ```sh
@@ -60,6 +67,7 @@ vx last --failed --format json   # the last failed run; a failed row has output
 vx last --log app#build          # one task's output: a failure's, or its cached log
 ```
 
+`warnings` holds what the run warned of (absent when nothing).
 A failed row's `output` is the task's output as plain text (secrets masked)
 and `locations` the files it names as `{ file, line?, col? }`. Read those
 files, fix, and re-run the same command: cached tasks that passed replay from the cache.
@@ -77,12 +85,20 @@ vx last --stats --format json            # per task: p50 (the live estimate's),
 vx last --stats --branch main --format json  # p50 from main's timings
 vx last --stats app#build --format json  # one task; a task name covers every project
 vx last --list --format json             # recent runs, newest first
+vx last --sql "SELECT name, sql FROM sqlite_schema" --format json  # the history's tables
 ```
 
+Any other question (one task's memory trend, failures per project, which
+inputs a key folded) is one read-only query: `vx last --sql "<SELECT>"
+--format json` prints `{ rows }`. `runs` holds one row per task per run
+(duration, cache hit, cpu, memory, attempts, failure reasons),
+`invocations` one per run; join on `run_id`. Times are epoch ms.
+
 ## Workspace health
 
 ```sh
-vx info --format json   # vx and Bun versions, projects, config errors, plugins, cache
+vx info --format json        # vx and Bun versions, projects, plugins, cache
+vx lock --check --format json  # a vx.config that changed since the lock, or no longer loads
 ```
 
 ## Rules
@@ -100,13 +116,13 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
   print whole.
 - Docs as markdown: https://vznjs.github.io/vx/llms.txt (its index).
   When that host is unreachable, the same pages are
-  `https://raw.githubusercontent.com/vznjs/vx/main/packages/vx-docs/src/content/docs/<page>.md`:
+  `https://raw.githubusercontent.com/vznjs/vx/main/private/vx-docs/src/content/docs/<page>.md`:
   `quickstart`, `guides/migrate`, `guides/configure`, `guides/agents`,
   `guides/troubleshooting`, `guides/ci`, `guides/plugins`.
 
 ## Install
 
-`npx skills add vznjs/vx` installs this skill. To match the vx a workspace
+`bunx skills add vznjs/vx` installs this skill. To match the vx a workspace
 has installed, copy it from there instead:
 `cp node_modules/@vzn/vx/skills/vx/SKILL.md .claude/skills/vx/`.
 `vx upgrade` inside a workspace moves the project's `@vzn/vx` and the