@vzn/vx 0.0.646 → 0.0.648

package/README.md

@@ -79,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
 
@@ -102,16 +101,24 @@ 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
@@ -145,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.646",
+  "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.646",
-    "@vzn/vx-linux-arm64": "0.0.646",
-    "@vzn/vx-darwin-x64": "0.0.646",
-    "@vzn/vx-darwin-arm64": "0.0.646"
+    "@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,
@@ -176,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" },
@@ -228,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"
@@ -246,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,7 +116,7 @@ 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`.
 

package/src/bin.ts

@@ -25,11 +25,28 @@ async function main(): Promise<void> {
       // ~7 ms, half of this verb (2026-10-02). A reader gone (EPIPE) is no
       // failure of the line.
       // Handed off, it says which vx ran and which one handed it the call.
-      const from = process.env['VX_HANDED_OFF']
+      const from = process.env['VX_HANDED_OFF'] || undefined
       const where = from === undefined ? '' : ` (${vxPath()}, handed off from ${from})`
-      await Bun.write(Bun.stdout, `vx ${(await import('./version.js')).VERSION}${where}\n`).catch(
-        () => {},
-      )
+      // Painted as every other line; piped, the same words a script reads.
+      // Decided here, not by util's `detectColors`: the util barrel was the
+      // 20 ms above, and `node:tty` 17 ms; fd 1 as a character device is the
+      // TTY answer. A CI's log is not painted for this one line.
+      const [{ VERSION }, { fstatSync }] = await Promise.all([
+        import('./version.js'),
+        import('node:fs'),
+      ])
+      const env = process.env
+      const on = env['NO_COLOR']
+        ? false
+        : env['FORCE_COLOR'] !== undefined
+          ? env['FORCE_COLOR'] !== '0' && env['FORCE_COLOR'] !== 'false'
+          : env['TERM'] !== 'dumb' && fstatSync(1).isCharacterDevice()
+      const sgr = (code: string, text: string): string =>
+        on ? `\x1b[${code}m${text}\x1b[0m` : text
+      await Bun.write(
+        Bun.stdout,
+        `${sgr('1', 'vx')} ${sgr('38;2;6;182;212', VERSION)}${where === '' ? '' : sgr('2', where)}\n`,
+      ).catch(() => {})
       settled = true
       return
     }
@@ -64,15 +81,19 @@ async function main(): Promise<void> {
     // A plugin's failure quotes what it was told (a remote's reply, a
     // header), and a config's own throw is its author's text: a secret in
     // either reached stderr whole (L-11).
-    const say = (line: string): void => void process.stderr.write(maskedLine(line))
+    const say = (line: string): void =>
+      void process.stderr.write(
+        `${ui.tagged('error', maskedLine(line), detectColors(process.stderr))}\n`,
+      )
     // 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)) {
-      // A message that names its verb (`vx why: …`) is that verb's; any
-      // other is the verb typed. A config refusal shows its line.
-      const named = /^(vx [a-z][\w-]*): /.exec(err.message)
+      // A message that names its verb (`vx why: …`, a plugin's `vx dte
+      // worker: …`) is that verb's; any other is the verb typed. A config
+      // refusal shows its line.
+      const named = /^(vx [a-z][\w-]*(?: [a-z][\w-]*)?): /.exec(err.message)
       const typed = /^[a-z][\w-]*$/.test(argv[0] ?? '') ? `vx ${argv[0]}` : 'vx'
       const block = refusalNotice(
         named?.[1] ?? typed,
@@ -87,8 +108,7 @@ async function main(): Promise<void> {
       // the verb's write, which the reader cannot act on either.
       say(`vx: ${err.message} — ${fsRefusalHint(err)}\n`)
     } else {
-      const message = err instanceof Error ? (err.stack ?? err.message) : String(err)
-      say(`vx: ${message}\n`)
+      say(`vx: ${withCauses(err)}\n`)
     }
     // A verb asked for JSON answers JSON on a refusal too: an agent reading
     // stdout got nothing to parse, and only prose on stderr to branch on.
@@ -126,6 +146,26 @@ async function exitOnceFlushed(): Promise<void> {
   process.stderr.end(ended)
 }
 
+/**
+ * An error's stack, then each `cause` under it: a config or plugin that
+ * wraps a failure (`new Error(msg, { cause })`) put the reason there, and
+ * the stack alone printed only the wrapper. Bounded, and a cause seen
+ * before ends the chain.
+ */
+function withCauses(err: unknown): string {
+  const text = (e: unknown): string =>
+    e instanceof Error ? (e.stack ?? `${e.name}: ${e.message}`) : String(e)
+  let out = text(err)
+  const seen = new Set<unknown>([err])
+  let at = err instanceof Error ? err.cause : undefined
+  for (let depth = 0; at !== undefined && at !== null && !seen.has(at) && depth < 8; depth++) {
+    seen.add(at)
+    out += `\nCaused by: ${at instanceof Error ? text(at) : Bun.inspect(at)}`
+    at = at instanceof Error ? at.cause : undefined
+  }
+  return out
+}
+
 // 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
@@ -134,8 +174,9 @@ async function exitOnceFlushed(): Promise<void> {
 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',
+  ;(require('./util/index.js') as typeof import('./util/index.js')).ui.say(
+    'error',
+    'vx: the run stopped before it finished: something it awaited can never settle (a plugin hook?)',
   )
   process.exitCode = 1
 })