@vzn/vx 0.0.635 → 0.0.637

package/docs/security.md

@@ -8,12 +8,31 @@ vulnerability), never in a public issue.
 
 ## What vx trusts
 
-- **Your configs.** `vx.config.ts` and `vx.workspace.ts` are programs vx
+- **Your configs.** `vx.config.ts` and `.vx/workspace.ts` are programs vx
   runs in its own process. A config can do anything you can: vx
-  validates what it returns, not what it does. What a config imports
+  validates what it returns, not what it does. The workspace root is
+  the nearest `.vx/workspace.*`, and vx never looks for it above the git
+  top-level, so a file planted in a shared directory such as `/tmp`
+  cannot claim your checkout and run as you. Outside git, one another
+  user owns is refused, root aside, judged by the file itself (a link,
+  not what it names) and its `.vx` (`tests/workspace-root-file.test.ts`).
+  No task output reaches `.vx` or a `vx.lock.json`: a clean never deletes
+  them and a hit never restores them (`tests/output-never-dotvx.test.ts`).
+  What a config imports
   must already be installed: vx runs Bun with `--no-install`, so an
   import no `node_modules` provides is refused, never fetched from the
   registry (L-22).
+- **Your projects lock.** A run executes `.vx/projects.lock.json` as
+  written and never re-evaluates or re-validates it, so the lock is code
+  too. It is minified and marked generated, which collapses it in a
+  pull request's diff: a change to it alone changes what runs while every
+  config and `vx.lock.json` reads the same. Run `vx lock --check` in CI
+  before anything else; it fails on any entry that differs from what its
+  config evaluates to and on one with no config (`tests/lock.test.ts`).
+- **Your project's own vx.** A global vx hands every call to the
+  workspace root's `node_modules/.bin/vx` (cli.md § Which vx runs), so even
+  `vx --version` in a repo you do not trust runs that repo's code. One
+  another user owns is never run.
 - **Your plugins.** A plugin is code you imported. It runs in vx's
   process with a config's reach; vx checks the shape of what it hands
   back and isolates a telemetry plugin's failures, nothing more.
@@ -26,7 +45,7 @@ vulnerability), never in a public issue.
   choosing is trusted as a writer, as it is in every action cache. Use a
   store only your builds write to, or `turboCache()`'s signature key,
   which refuses an artifact a keyholder did not sign. A job you do not
-  trust (a fork's pull request) reads at most: `--cache=local:rw,remote:r`,
+  trust (a fork's pull request) reads at most: `--cache-policy=local:rw,remote:r`,
   or the tools' own `TURBO_REMOTE_CACHE_READ_ONLY`, `TURBO_CACHE` and
   `NX_SKIP_REMOTE_CACHE`, which the cache plugins honour (L-34).
 
@@ -35,14 +54,20 @@ vulnerability), never in a public issue.
 A pull request that can write the cache the default branch reads can
 plant bytes main later replays (CREEP, CVE-2025-36852). The boundary is
 the credential, enforced by the cache server: the default branch's job
-holds a token that writes the trusted keys, and a pull request's job
+holds a token that writes the default keys, and a pull request's job
 holds one that cannot (read-only, or confined by the server to its own
 namespace), or none.
 
-`cacheScope` is the client half. `'pr-123'` reads its own keys,
-then the trusted ones, and writes only its own, which `github()` sets on
-Actions (`pr-<n>`, `ref-<name>`; the default branch stays trusted)
-and `VX_CACHE_SCOPE` sets on any CI.
+`cache.scope` is the client half. `'pr-123'` reads the default keys,
+then its own, and writes only its own, which `github()` sets on
+Actions (`pr-<n>`, `ref-<name>`; the default branch sets none)
+and `VX_CACHE_SCOPE` or `--cache-scope` sets on any CI. Whether a run
+writes is `cache.policy`'s call: off CI the default reads the remote and
+writes nothing, since a key holds only declared inputs and a laptop's
+undeclared tool or file would replay on CI. A laptop that should never
+write gets a read-only token too. The local cache follows the same
+key rule, so on one disk a PR's entries sit under its scope's keys and
+a persistent runner never serves them to main.
 It keeps honest runs apart and stops a non-hermetic PR build from
 landing where main reads; it is not a boundary, since the PR's own
 config decides it and any run holding a write credential can write any
@@ -58,7 +83,7 @@ bazel-remote --dir /data --max_size 50 --grpc_address 0.0.0.0:9092 \
 ```
 
 ```ts
-// vx.workspace.ts: the header only where the secret is set
+// .vx/workspace.ts: the header only where the secret is set
 reapi({
   endpoint: 'grpcs://cache.example.com:9092',
   headers: process.env.CACHE_AUTH ? { authorization: `Basic ${process.env.CACHE_AUTH}` } : {},
@@ -114,7 +139,8 @@ the local store:
 
 Remote execution (`@vzn/vx-reapi`) holds each blob to its digest, and
 writes only the server's outputs a declared glob names, inside the
-workspace, through no link that leads out of it.
+workspace, through no link that leads out of it, and through no link
+into a place no declared glob names.
 
 ## What the sandbox stops
 
@@ -130,22 +156,45 @@ A task with `exec.sandbox` runs where only what it declares exists:
 - its temp directory, port-bridge socket and trace log are its own
   (mode 0700), unreachable from another task and another local user;
 - the host's credential stores (`~/.ssh`, `~/.gnupg`, `~/.aws`,
-  `~/.npmrc`, `~/.netrc` and the like; the list is in the schema's
-  sandbox section) are unreadable unless `allow.read` names one (L-41);
-- vx's own cache directory, wherever `cacheDir` puts it in the
-  workspace, is a wall like `.vx`: a broad grant stops at it, and a write
+  `~/.npmrc`, `~/.netrc`, the token files of deploy and agent CLIs such
+  as Vercel, Wrangler, Fly or Claude, and the like; the list is in the
+  schema's sandbox section) are unreadable unless `allow.read` names one
+  (L-41), cannot be hard-linked into an output for vx to pack, and a denied read's `fix:` hint never suggests granting one
+  (`tests/sandbox-credential-stores.unsafe.test.ts`, `tests/sandbox-fix.test.ts`);
+- vx's own cache directory, wherever `cache.dir` puts it in the
+  workspace, is a wall like `.vx/cache`: a broad grant stops at it, and a write
   grant that would bind it is refused (L-24);
 - a symlinked output must resolve inside its project: vx packs outputs
   outside the sandbox, and a link to another project's file would have
   carried that file into the cache (L-23). An output directory linked out
-  of the project refuses the task by name (X-88).
+  of the project refuses the task by name (X-88). Inside the project, a
+  link must name a file the task could read (a read or write grant, its
+  `node_modules`) or one of its own outputs, so `dist/x -> ../.env` under
+  `read: ['src/']` is refused, and Linux judges making the link by the
+  link, never its target (`tests/sandbox-output-link.unsafe.test.ts`).
+- vx's own environment, which holds the variables a task is not given
+  (a token, a key), is unreadable: the task cannot see vx's
+  `/proc/<pid>/environ` on Linux or read it through `ps eww` on macOS
+  (`tests/sandbox-parent-env.unsafe.test.ts`).
 
 An undeclared touch of the task's own files fails the task, and a failed
 task is never cached. See [Sandboxing tasks](https://vznjs.github.io/vx/guides/sandboxing/).
 
+The sandbox costs each task it runs; a cache hit runs nothing and costs
+nothing. `tests/sandbox-parent-env.unsafe.test.ts` prints the cost of one
+`true` task, min of 20, on every CI run. On GitHub-hosted runners on
+2026-10-13 it printed +269 ms on Linux and +97 ms on macOS.
+
 ## What it does not stop
 
-- **A task with no `exec.sandbox`.** It runs with your permissions.
+- **A task with no `exec.sandbox`.** It runs with your permissions:
+  it reads anything you can. vx hides its own environment from it on
+  every command: on Linux vx makes itself non-dumpable (about 0.8 ms), on
+  macOS it zeroes the values `ps eww` reads, every variable but the
+  essentials every task gets (about 0.7 ms). It starts its helpers with `PATH`
+  alone and each `git` with only what git reads
+  (`tests/hide-env.unsafe.test.ts`, `tests/git-env.test.ts`). That hides
+  the environment only, not files.
 - **Reads outside the workspace root.** `~/.cache`, `/etc` and the like
   stay readable (tools need them) and fold into no key. The credential
   stores under home (`~/.ssh`, `~/.aws`, `~/.npmrc` and the like) are
@@ -156,24 +205,6 @@ task is never cached. See [Sandboxing tasks](https://vznjs.github.io/vx/guides/s
   `weakerWhenNested` in a container, a task that itself sandboxes on
   macOS. `vx info` says what the host supports.
 
-## Agents (`vx mcp`)
-
-An agent connected to `vx mcp` can do what `vx run` can do, nothing more.
-Every tool but `runTasks` only reads. `runTasks` runs `vx run --format json`
-as a child process: the agent names tasks and sets `all`, `force`,
-`filter` and `affected`, and nothing else. A task name that starts with
-`-` is refused, a filter goes as one `--filter=` value, and a ref reaches
-git after `--end-of-options`, so no argument becomes a flag. The commands
-that run are the ones your configs declare, from the workspace root, with
-the environment `vx mcp` started with, filtered by each task's `exec.env`
-and held by its `exec.sandbox`. `force` costs a rerun, not a wrong entry:
-the key stays the same. What reaches the agent (summaries, refusals,
-`getFailures` output) is masked as described under Secrets.
-`mcp({ run: false })` takes `runTasks` away, and `mcp({ run: ['test'] })`
-limits it to those task names. An agent that
-can edit `vx.config.ts` can run anything, as you can, because configs are
-code vx trusts.
-
 ## Secrets
 
 The value, of 6 characters or more, of a variable whose name holds
@@ -183,7 +214,7 @@ task lists in `exec.env.secret`, and the password of a URL
 (`scheme://user:<password>@`) in any variable's value, is printed as `***` wherever vx shows, stores or
 exports it: task output, the stdout a hit replays, commands, an
 executor's error, telemetry,
-`vx show` and `vx mcp`'s `listTasks` (L-26). Values in the run history are digests under a per-store
+`vx show` (L-26). Values in the run history are digests under a per-store
 salt, and what follows `--` on the command line reaches telemetry as a
 count, not a quote, a secret before it masked (L-44). A remote executor (`@vzn/vx-reapi`) receives a
 task's `exec.env.define` values and the `cache.inputs.env` values its
@@ -204,10 +235,16 @@ secret values: a name-based match would refuse public `*_KEY` values too.
 
 Release binaries carry a build-provenance attestation
 (`gh attestation verify vx-<target> --repo vznjs/vx`); `vx upgrade`
-checks each download's SHA-256 before it replaces anything and stages it in a fresh directory, never a name another user could plant a link at, which proves
-the bytes arrived intact, not who built them: the digest comes from the
-release that serves the asset, and no signature is checked (owner,
-2026-10-03: no release signing key for now); npm packages
+installs a binary only after npm's registry signature over the platform
+package's `name@version:integrity` verifies against npm's key, pinned
+in vx, and the tarball matches that integrity: the host that serves the
+bytes cannot make the signature, so a swapped tarball is refused before
+anything is written, and a key id vx does not pin is refused with a hint
+that the installer needs updating (owner, 2026-10-13; pnpm's installer
+checks the same). The new binary is staged in a fresh directory, never a
+name another user could plant a link at. A vx a package manager
+installed is upgraded by that manager, which checks its own integrity.
+npm packages
 publish with provenance; every third-party action in CI runs from a
 full commit SHA; and a workflow hands an event's or a dispatcher's value
 to a script through `env`, never pasted in (a release tag is checked as a

package/launcher.sh

@@ -29,6 +29,49 @@ base=${here##*/}
 scope=${here%/*}
 scope=${scope##*/}
 
+# A global vx hands off to the project's own (owner, 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.
+if [ -z "${VX_HANDED_OFF-}" ]; then
+  d=$PWD
+  while :; do
+    root=
+    for ext in ts mts js mjs cts cjs; do
+      if [ -f "$d/.vx/workspace.$ext" ]; then
+        root=${d:-/}
+        break
+      fi
+    done
+    if [ -n "$root" ]; then
+      bin=$d/node_modules/.bin/$base
+      # -O: a vx another user planted would run as you.
+      if [ -d "$d/node_modules/$scope/$base" ] && [ ! "$d/node_modules/$scope/$base" -ef "$here" ] && [ -x "$bin" ] && [ -O "$bin" ]; then
+        VX_HANDED_OFF=$self
+        export VX_HANDED_OFF
+        exec "$bin" "$@"
+      fi
+      break
+    fi
+    [ -z "$d" ] && break
+    # A submodule's .git file points into its superproject's .git/modules:
+    # the walk goes on to the superproject.
+    if [ -d "$d/.git" ]; then
+      break
+    elif [ -f "$d/.git" ]; then
+      read -r gitdir <"$d/.git" || :
+      case $gitdir in
+        *.git/modules/*) ;;
+        *) break ;;
+      esac
+    fi
+    d=${d%/*}
+  done
+fi
+
 key=
 loader=
 case $(uname -sm) in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.635",
+  "version": "0.0.637",
   "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.635",
-    "@vzn/vx-linux-arm64": "0.0.635",
-    "@vzn/vx-darwin-x64": "0.0.635",
-    "@vzn/vx-darwin-arm64": "0.0.635"
+    "@vzn/vx-linux-x64": "0.0.637",
+    "@vzn/vx-linux-arm64": "0.0.637",
+    "@vzn/vx-darwin-x64": "0.0.637",
+    "@vzn/vx-darwin-arm64": "0.0.637"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/cache.json

@@ -1,24 +1,46 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "vx cache prune --format json",
-  "description": "What the policy evicted and the orphan sweep reaped; with dryRun, what they would.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["dryRun", "evicted", "bytesFreed", "orphans", "orphanBytes"],
-  "properties": {
-    "dryRun": { "type": "boolean" },
-    "evicted": {
-      "type": "integer",
-      "description": "index entries evicted by the age / size policy"
+  "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.",
+  "oneOf": [{ "$ref": "#/$defs/prune" }, { "$ref": "#/$defs/clear" }],
+  "$defs": {
+    "prune": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dryRun", "evicted", "bytesFreed", "orphans", "orphanBytes"],
+      "properties": {
+        "dryRun": { "type": "boolean" },
+        "evicted": {
+          "type": "integer",
+          "description": "index entries evicted by the age / size policy"
+        },
+        "bytesFreed": {
+          "type": "integer",
+          "description": "bytes those entries occupied, per the index"
+        },
+        "orphans": {
+          "type": "integer",
+          "description": "artifacts and temp files with no index row, reaped"
+        },
+        "orphanBytes": { "type": "integer" }
+      }
     },
-    "bytesFreed": {
-      "type": "integer",
-      "description": "bytes those entries occupied, per the index"
-    },
-    "orphans": {
-      "type": "integer",
-      "description": "artifacts and temp files with no index row, reaped"
-    },
-    "orphanBytes": { "type": "integer" }
+    "clear": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dryRun", "cleared", "bytesFreed"],
+      "properties": {
+        "dryRun": { "type": "boolean" },
+        "cleared": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "the cache directory and the store deleted: workspace-relative inside it, else absolute"
+        },
+        "bytesFreed": {
+          "type": "integer",
+          "description": "bytes under those directories"
+        }
+      }
+    }
   }
 }

package/schemas/info.json

@@ -5,6 +5,8 @@
   "additionalProperties": false,
   "required": [
     "vx",
+    "vxPath",
+    "handedOffFrom",
     "bun",
     "bunSupported",
     "git",
@@ -12,16 +14,18 @@
     "workspaceRoot",
     "projects",
     "tasks",
-    "configErrors",
     "plugins",
     "workers",
     "memory",
     "cacheDir",
+    "cacheDirBytes",
     "cacheStore",
+    "cacheStoreBytes",
     "cacheVersion",
     "schemaVersion",
     "cacheEntries",
     "cacheBytes",
+    "settings",
     "cacheRetention",
     "orphans",
     "runs24h",
@@ -33,6 +37,8 @@
   ],
   "properties": {
     "vx": { "type": "string" },
+    "vxPath": { "type": "string" },
+    "handedOffFrom": { "type": ["string", "null"] },
     "bun": { "type": "string" },
     "bunSupported": { "type": "boolean" },
     "git": { "type": ["string", "null"] },
@@ -45,15 +51,6 @@
     "workspaceRoot": { "type": "string" },
     "projects": { "type": "integer" },
     "tasks": { "type": "integer" },
-    "configErrors": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["path", "message"],
-        "properties": { "path": { "type": "string" }, "message": { "type": "string" } }
-      }
-    },
     "plugins": {
       "type": "array",
       "items": {
@@ -88,14 +85,29 @@
       }
     },
     "cacheDir": { "type": "string" },
+    "cacheDirBytes": { "type": "integer" },
     "cacheStore": { "type": ["string", "null"] },
+    "cacheStoreBytes": { "type": ["integer", "null"] },
     "cacheVersion": { "type": "string" },
     "schemaVersion": { "type": "string" },
     "cacheEntries": { "type": "integer" },
     "cacheBytes": { "type": "integer" },
+    "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",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["value", "source"],
+        "properties": {
+          "value": { "type": ["string", "number", "boolean", "null"] },
+          "source": { "enum": ["env", "workspace", "default"] }
+        }
+      }
+    },
     "cacheRetention": {
       "type": ["object", "null"],
-      "description": "the workspace's cacheRetention, maxSize also in bytes; null when none is declared",
+      "description": "cache.retention from its variables, else the workspace, maxSize also in bytes; null when none is declared",
       "additionalProperties": false,
       "properties": {
         "olderThan": { "type": "string" },

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.",
+  "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.",
   "oneOf": [
     {
       "type": "object",
@@ -13,9 +13,55 @@
       }
     },
     { "type": "array", "items": { "$ref": "#/$defs/invocation" } },
-    { "$ref": "#/$defs/log" }
+    { "$ref": "#/$defs/log" },
+    { "$ref": "#/$defs/stats" }
   ],
   "$defs": {
+    "stats": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["window", "branch", "stats"],
+      "properties": {
+        "window": { "type": "integer", "description": "the newest runs the numbers cover" },
+        "branch": {
+          "type": ["string", "null"],
+          "description": "the branch p50 forecasts from: --branch, VX_RUN_BRANCH, git's, then CI's"
+        },
+        "stats": { "type": "array", "items": { "$ref": "#/$defs/taskStats" } }
+      }
+    },
+    "taskStats": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "taskId",
+        "runs",
+        "p50DurationMs",
+        "p99DurationMs",
+        "successRate",
+        "hitRate",
+        "failureMode",
+        "maxPeakRssBytes",
+        "maxCpuParallelism"
+      ],
+      "properties": {
+        "taskId": { "type": "string" },
+        "runs": { "type": "integer", "description": "executed runs in the window, skips aside" },
+        "p50DurationMs": {
+          "type": ["number", "null"],
+          "description": "the forecast a run shows: median of the last 5 timings on branch, else on any branch; null when none"
+        },
+        "p99DurationMs": { "type": ["number", "null"] },
+        "successRate": { "type": "number", "description": "0 to 1" },
+        "hitRate": { "type": "number", "description": "0 to 1" },
+        "failureMode": { "enum": ["stable", "flaky-recoverable", "flaky-fatal"] },
+        "maxPeakRssBytes": { "type": ["integer", "null"] },
+        "maxCpuParallelism": {
+          "type": ["number", "null"],
+          "description": "cpu time over wall time; 2.0 is two cores busy"
+        }
+      }
+    },
     "log": {
       "type": "object",
       "additionalProperties": false,

package/schemas/lock.json

@@ -10,7 +10,7 @@
     "audited": { "type": "integer", "description": "projects with a vx.config, each audited" },
     "notAudited": {
       "type": "integer",
-      "description": "projects without a vx.config: nothing to freeze, never audited"
+      "description": "projects with tasks and no vx.config: nothing to freeze, never audited"
     },
     "problems": {
       "type": "array",

package/schemas/plan.json

@@ -35,7 +35,7 @@
           },
           "download": {
             "const": "deferred",
-            "description": "outputs would stay remote (--download)"
+            "description": "outputs would stay remote (--cache-download)"
           },
           "description": { "type": "string" },
           "affected": {
@@ -80,7 +80,7 @@
     },
     "downloadDowngrades": {
       "type": "array",
-      "description": "producers --download wanted to defer but could not, and why",
+      "description": "producers --cache-download wanted to defer but could not, and why",
       "items": {
         "type": "object",
         "additionalProperties": false,

package/schemas/show.json

@@ -32,9 +32,10 @@
         "dir": { "type": "string" },
         "config": {
           "type": ["object", "null"],
-          "description": "null when the package has no vx config and no plugin gave it one",
+          "description": "null when the project has no vx config and no plugin gave it one",
           "additionalProperties": false,
           "properties": {
+            "name": { "type": "string" },
             "tags": { "$ref": "#/$defs/stringList" },
             "tasks": { "type": "object", "additionalProperties": { "$ref": "#/$defs/taskConfig" } }
           }
@@ -66,7 +67,7 @@
           "properties": {
             "command": { "type": "string" },
             "remote": { "enum": [true, false, "only"] },
-            "timeout": { "type": "number", "description": "ms" },
+            "timeout": { "type": "string", "description": "a duration as written, like '30s'" },
             "retries": { "type": "integer" },
             "env": {
               "type": "object",
@@ -113,10 +114,18 @@
               "required": ["files"],
               "properties": {
                 "files": { "$ref": "#/$defs/stringList" },
-                "workspaceFiles": { "$ref": "#/$defs/stringList" }
+                "workspaceFiles": { "$ref": "#/$defs/stringList" },
+                "clean": { "type": "boolean" }
               }
             },
-            "rewrittenInputs": { "enum": ["withhold", "compare"] }
+            "inputStability": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "strategy": { "enum": ["immutable", "mutable", "unchecked"] },
+                "severity": { "enum": ["warn", "error"] }
+              }
+            }
           }
         }
       }

package/schemas/why.json

@@ -6,7 +6,7 @@
     {
       "type": "object",
       "additionalProperties": false,
-      "required": ["taskId", "runId", "why", "diff", "roots"],
+      "required": ["taskId", "runId", "why", "diff", "roots", "writers"],
       "properties": {
         "taskId": { "type": "string" },
         "runId": { "type": "string" },
@@ -38,6 +38,20 @@
               }
             }
           }
+        },
+        "writers": {
+          "type": "array",
+          "description": "For each moved input file of the task or a root cause, the recorded tasks running when the file last changed: a task writing a file another key reads re-keys it every run.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["taskId", "file", "writers"],
+            "properties": {
+              "taskId": { "type": "string" },
+              "file": { "type": "string" },
+              "writers": { "type": "array", "items": { "type": "string" } }
+            }
+          }
         }
       }
     },

package/skills/vx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vx
-description: Run, inspect and debug tasks in a vx monorepo (vx.config.ts, vx.workspace.ts). Use to build or test projects, find what a change affects, read why a task failed or re-ran, and query the cache as JSON.
+description: Run, inspect and debug tasks in a vx monorepo (vx.config.ts, .vx/workspace.ts). Use to build or test projects, find what a change affects, read why a task failed or re-ran, and query the cache as JSON.
 ---
 
 # vx
@@ -59,22 +59,20 @@ files, fix, and re-run the same command: cached tasks that passed replay from th
 vx why app#build --format json   # which input changed, down to the root cause
 ```
 
-## Workspace health
+## Run history
 
 ```sh
-vx info --format json   # vx and Bun versions, projects, config errors, plugins, cache
+vx last --stats --format json            # per task: p50 (the live estimate's), p99, pass and hit rate, failure mode, peak RSS
+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
 ```
 
-## MCP
+## Workspace health
 
-When `@vzn/vx-mcp` is a plugin in `vx.workspace.ts`, `vx mcp` serves the
-same facts and runs tasks. Adoption does not add it: install
-`@vzn/vx-mcp` and put `mcp()` (from `'@vzn/vx-mcp'`) in `plugins`. Its tools: `listTasks`, `getCacheStats`,
-`getRunHistory`, `explainCacheKey`, `whyDidThisRerun`, `getFailures`, `getTaskLog`, `getConfig`, `checkLock`, `pruneCache`, `planInit`, `searchDocs`,
-`getWorkspaceInfo`, `runTasks`, `planTasks`. `runTasks` answers what
-`vx run <tasks> --format json` prints, `planTasks` what
-`vx run <tasks> --dry=json` prints, `pruneCache` evicts only with
-`dryRun: false`; the others only read.
+```sh
+vx info --format json   # vx and Bun versions, projects, config errors, plugins, cache
+```
 
 ## Rules
 
@@ -93,3 +91,9 @@ same facts and runs tasks. Adoption does not add it: install
   `https://raw.githubusercontent.com/vznjs/vx/main/packages/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/packages/vx/skills/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/`.