@vzn/vx 0.0.637 → 0.0.638

package/docs/caching.md

@@ -839,10 +839,10 @@ Skipped when:
   on, so it DOES clean (the saved snapshot must be clean).
 - `cache.outputs.clean` is `false` (on the task, else the workspace's
   `cache.outputs.clean`): the command sees last run's outputs (tsc's
-  `.tsbuildinfo`). The first attempt stamps what it finds instead;
-  if the run leaves any old file unchanged, nothing is cached, so no
-  entry holds a file this run did not write. A retry cleans as usual; a hit still
-  cleans before its restore.
+  `.tsbuildinfo`). You opt out of the clean-tree guarantee: the save
+  stores every file the outputs match after the run, so a leftover from
+  an older build is cached and restored everywhere. A retry cleans as
+  usual; a hit still cleans before its restore.
 
 A declared output the process cannot remove (a `dist/` another user
 wrote, a read-only checkout) fails the task with `cannot remove declared
@@ -1192,7 +1192,8 @@ in `~/.vx/<id>/cache`, and each workspace keeps only its own index in
 its `.vx/cache`: every checkout of the repository hits what another
 saved (a second clone, a worktree), and none reads another's history.
 Task timings are shared too: `task_durations`, what a duration forecast
-reads, so a new worktree has one on its first run.
+reads, so a new worktree has one on its first run. So are plugins' own
+entries (`plugin_blobs`, a plugin's `ctx.cache`).
 The id is Nx 23's: 16 hex of a sha256 of the remote (`origin`, then
 `upstream`, `base`, the first; `host/owner/repo` in lower case, so ssh
 and https agree) and the workspace's path in the repository; with no
@@ -1204,7 +1205,7 @@ owner-only; vx closes one of yours that others can read (chmod 700), and one oth
 ~/.vx/<id>/cache/                           the shared store
 ├── store.db                                entries, entry_stdout, output_files,
 │                                           entry_inputs, task_durations,
-│                                           store_meta; artifacts
+│                                           plugin_blobs, store_meta; artifacts
 │                                           of at most 32 KiB compressed (v33)
 └── <hash>.tar.zst                          the larger artifacts (below)
 
@@ -1469,9 +1470,9 @@ keep). The artifacts stay: each is indexed again from its own bytes
 when its task next asks for its key (below).
 
 ```sql
--- src/cache/schema.ts (SCHEMA_VERSION = 'v36', in cache.ts)
+-- src/cache/schema.ts (SCHEMA_VERSION = 'v38', in cache.ts)
 -- With a shared store, entries, entry_stdout, output_files, entry_inputs,
--- store_meta and task_durations live in its store.db, attached as `store`; the rest is
+-- store_meta, task_durations, task_outcomes, blob_sizes and plugin_blobs live in its store.db, attached as `store`; the rest is
 -- the workspace's cache.db. A named cache dir holds all of them.
 
 CREATE TABLE schema_meta (
@@ -1537,10 +1538,6 @@ CREATE TABLE runs (
 -- the history reader bounds its scan by rowid instead (see history.md).
 CREATE INDEX runs_started_at ON runs(started_at);
 CREATE INDEX runs_run_id     ON runs(run_id);
--- The one keyed index, PARTIAL over failed rows: a green run's inserts only
--- evaluate its predicate, and the flakiness probe after a miss
--- (failure-mode.ts, "did this key ever fail?") reads a few leaves.
-CREATE INDEX runs_failed ON runs(hash) WHERE status = 'failed';
 
 -- Every non-group, non-aborted outcome of a run gets a row, so
 -- `invocations.task_count` always equals `COUNT(*)` here for that run_id
@@ -1575,7 +1572,8 @@ CREATE TABLE file_hashes (
 -- The size of each index blob the enumeration checked against the
 -- worktree size git recorded (§ Cache key derivation, A-60): fixed for
 -- its OID, so a warm run asks git for none. Swept with file_hashes by
--- seen_at, the time the row was written.
+-- seen_at, the time the row was written. v38: in the store, so a worktree
+-- reads what another learned.
 CREATE TABLE blob_sizes (
   oid     TEXT PRIMARY KEY,
   size    INTEGER NOT NULL,
@@ -1636,7 +1634,7 @@ CREATE TABLE invocations (
   run_id            TEXT PRIMARY KEY,         -- UUIDv7, == runs.run_id
   command           TEXT NOT NULL,            -- full argv, e.g. "vx run build --all"
   requested_tasks   TEXT NOT NULL,            -- JSON string[] of options.tasks
-  cache_policy      TEXT NOT NULL,            -- compact flags, e.g. "lR,lW,rR,rW"
+  cache_policy      TEXT NOT NULL,            -- the --cache-policy spec, e.g. "local:rw,remote:r"
   concurrency       INTEGER NOT NULL,
   flow              TEXT,                     -- 'focused' | 'broad' | NULL (programmatic)
   started_at        INTEGER NOT NULL,         -- ms-epoch
@@ -1696,6 +1694,8 @@ CREATE TABLE store_meta (
 -- v36: each executed success's duration, appended in the run's history
 -- transaction, in the store so every worktree forecasts from it.
 -- source: 'branch:<name>'; the forecast reads the newest five per task.
+-- v37: 'remote' rows are a default-branch commit's timings a plugin
+-- imported, one per (sha, task).
 CREATE TABLE task_durations (
   id          INTEGER PRIMARY KEY AUTOINCREMENT,
   project     TEXT NOT NULL,
@@ -1706,6 +1706,33 @@ CREATE TABLE task_durations (
   recorded_at INTEGER NOT NULL
 );
 CREATE INDEX task_durations_task ON task_durations(project, task, source, id);
+CREATE UNIQUE INDEX task_durations_remote
+  ON task_durations(sha, project, task) WHERE source = 'remote';
+
+-- v38: the flaky record (failure-mode.ts), in the store so a key that
+-- passed in one worktree and failed in another is flaky in both. Every
+-- executed success or failure that names its key (keyed, cached, not run
+-- behind a failure), and a key's first hit: a later hit replays a pass on
+-- record, so a warm run on passed keys writes no row (one index probe,
+-- ~1 ms per 1,000 hits). Pruned by age with the run history.
+CREATE TABLE task_outcomes (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  project     TEXT NOT NULL,
+  task        TEXT NOT NULL,
+  hash        TEXT NOT NULL,
+  status      TEXT NOT NULL,
+  attempts    INTEGER,
+  recorded_at INTEGER NOT NULL
+);
+CREATE INDEX task_outcomes_hash ON task_outcomes(hash, status);
+
+-- v37: a plugin's own entries (`ctx.cache`), by core's key for its
+-- name; written once, pruned by age with the run history.
+CREATE TABLE plugin_blobs (
+  key   TEXT PRIMARY KEY,
+  bytes BLOB NOT NULL,
+  at    INTEGER NOT NULL
+);
 
 -- v33: an artifact of at most 32 KiB compressed, its exact <hash>.tar.zst
 -- bytes, written in the transaction that writes its entry rows. In the

package/docs/cli.md

@@ -69,7 +69,8 @@ declare task(s): <name>.` on stderr, a run and `--dry` / `--graph` alike
 declared task (or, for `pkg#task`, a runnable spec) is within two edits,
 and with no name that near, what exists: `Tasks: build, test.`, `No
 project is named zzz; projects: a, b.`, or `a's tasks: build, test.`
-(M-56),
+(M-56), each followed by ``A run reads the lock: after editing a
+vx.config, run `vx lock`.`` (a task just added is not in the lock yet),
 and with `Only projects outside the selection declare <name> — pass
 --all, or --filter to pick them.` when the run was scoped (the cwd's
 project, a `--filter`) and a project outside the scope declares it
@@ -999,7 +1000,9 @@ $ vx run build lint --affected=main --dry
 `kind` is `input` (a changed `file` is a declared input), `project` (its
 project changed and the task reads it whole: an uncached task, or a changed
 `file` no cached task of the project declares, often an output git does not
-ignore; no `file` for a lockfile claim or a config import),
+ignore; no `file` for a config import), `workspace` (a workspace-wide
+`file` changed: the workspace config, or a root file a plugin claims such
+as a lockfile, reached every task of the project),
 `package` (a `^` edge passes a changed `project` with no such task),
 `named` (`pkg#task` beside a bare task) or `selected` (another filter
 selected its project). `via` is the `dependsOn` chain, nearest first, to
@@ -1392,7 +1395,10 @@ run...` precedes it.
    heard from its nearest directory that exists and each one above it,
    and a watch whose
    directory was replaced is armed again (an OS watch holds the deleted
-   one; `watch-recreated-dirs.test.ts`). Under `--filter` or
+   one; `watch-recreated-dirs.test.ts`). There, a project directory
+   that is still the same one starts no cycle: a task writing at its
+   top level moved its mtime, which macOS reports to the parent
+   (`watch-project-dir-write.test.ts`). Under `--filter` or
    `--affected` the scope is the one resolved at start, and a new
    project joins it only as a dependency of it. A task's own declared outputs (`cache.outputs.files`,
    `outputs.workspaceFiles`; a plugin's `project` stage counts, as in
@@ -1432,7 +1438,10 @@ run...` precedes it.
    starts a cycle, since no cache key can see it (a user's edit to one
    still does in a project with a task that has a command and no cache,
    which reads what it likes, item 947, outside any project nested
-   in it) — or declared an
+   in it; a write the last cycle made is not, read off the later of
+   its mtime and ctime, so an output a cache hit restores with its
+   saved mtime is the run's, and so is the restore's own `.vx-tmp-*`
+   file, `watch-restored-output.test.ts`) — or declared an
    output, or the loop re-runs on it; after three such cycles in a row
    watch names the path and the remedy, once, and keeps going. A dev
    server the last cycle left running counts as that cycle for as long
@@ -1467,9 +1476,11 @@ watch events within 2000 ms; polling every 250 ms instead`.
    changed, then its task rows as `vx run` prints them, with no footer.
    The named path is the first changed one that still exists, so an
    editor's temporary file renamed away names nothing; a deletion names
-   the cycle when nothing else changed. A cycle that re-read the watched
-   set (a member came or went, the lock or a plugin changed) says the
-   `watching` line again. Errors and refusals go to stderr. The
+   the cycle when nothing else changed. The `watching` line is said
+   once: a cycle that re-reads the watched set (a member came or went,
+   the lock or a plugin changed) says nothing more; `VX_DEBUG_WATCH=1`
+   says each arm on stderr as `vx watch: armed N projects`. Errors and
+   refusals go to stderr. The
    orchestrator is invoked again with the same options, save one: the
    `--affected` diff is read once, for the initial run. A later cycle
    runs the requested task in every project of the scope fixed at start,
@@ -1490,7 +1501,8 @@ Always ignored (no re-trigger):
   tracked + untracked-not-ignored — so a cycle it started could change
   nothing. A tracked file that matches a pattern is not ignored, by
   git's own rule; outside a repository nothing is.
-- Files ending in `.tsbuildinfo` or `~` (editor swap files).
+- Files ending in `~` (editor swap files), and a restore's own
+  `.vx-tmp-*` file.
 - The run's **resolved cache directory**, wherever it is. `.vx/cache/` covers the
   default, but `defineWorkspace({ cache: { dir } })` and `--cache-dir` can put it
   anywhere; watching it would let vx's own cache writes trigger the next
@@ -1661,16 +1673,19 @@ bound clears the whole cache when that is really what you want.
 
 ```
 $ vx cache clean --older-than 30d
-Pruned 42 entries (1.3 GB freed)
+✓ vx cache clean  freed 1.3 GB
 
-$ vx cache clean --older-than 7d --max-size 500M
-Pruned 18 entries (320 MB freed)
+  42 entries
 
 $ vx cache clean --older-than 30d      # after a SCHEMA_VERSION bump
-Pruned 0 entries (0 B freed), reaped 42 orphaned artifacts (1.3 GB)
+✓ vx cache clean  freed 1.3 GB
+
+  42 orphaned artifacts
 
 $ vx cache clean --older-than 30d --dry-run
-Would prune 42 entries (1.3 GB), would reap 3 orphaned artifacts (12 MB)
+› vx cache clean  would free 1.3 GB (dry run)
+
+  42 entries · 3 orphaned artifacts
 ```
 
 `--dry-run` picks the victims under the same policy and counts the
@@ -1694,8 +1709,8 @@ artifact that vanishes before its restore is a miss, and the task runs
 Exit codes:
 
 - `0` — pruning completed (zero or more entries evicted). A workspace
-  that never ran has no cache: `Pruned 0 entries (0 B freed)`, and
-  nothing is created.
+  that never ran has no cache: `› vx cache clean  nothing to free`,
+  and nothing is created.
 - `1` — parse error, missing policy, or workspace-discovery error.
 
 `vx cache clean` resolves the workspace root from cwd and honors a
@@ -1723,17 +1738,19 @@ and the directory goes only if that empties it. A directory with no
 names goes only if it is one (`.vx/<id>/cache` holding a `store.db`): the
 index is a file in the checkout, which a commit or a restored CI cache
 could point at any directory. A workspace that never ran says
-`Nothing to clear: no cache here`. The next run misses every task once
+`› vx cache clean  nothing to free`. The next run misses every task once
 and saves again.
 
 ```
 $ vx cache clean
-Cleared this repository's store, shared by its checkouts, and this workspace's run history (1.4 GB freed):
+✓ vx cache clean  freed 1.4 GB
+
   .vx/cache
   /home/me/.vx/3f2a9c01b4d5e6f7/cache
 
 $ vx cache clean --global --dry-run
-Would clear every repository's store and this workspace's run history (3.1 GB):
+› vx cache clean  would free 3.1 GB (dry run)
+
   .vx/cache
   /home/me/.vx/3f2a9c01b4d5e6f7/cache
   /home/me/.vx/9b8e7d6c5a4f3e2d/cache
@@ -1775,8 +1792,8 @@ add directories (X-143). Before writing, it
 builds the graph of every task the workspace declares, `graph` stage
 included, and checks the graph rules (`run.rules`), which no run
 checks, `dependencies` (which projects a project may depend on,
-`VX_E_DEPENDENCY_RULE`) among them: a broken one prints `vx lock: .vx/projects.lock.json not written:
-<the rule's refusal>` and writes nothing.
+`VX_E_DEPENDENCY_RULE`) among them: a broken one prints `✗ vx lock  lock not written`
+with the rule's refusal under it and writes nothing.
 
 ```
 vx lock              # Evaluate all vx.config.* now; write .vx/projects.lock.json.
@@ -1830,7 +1847,7 @@ A project with no `vx.config.*` — its tasks from a plugin's `project`
 stage (`turbo()` from `@vzn/vx-migrate`), or none at all — has nothing
 to freeze: the lock records nothing for it, `--check` does not audit
 it, and a run still loads its tasks live. Both verbs name such
-projects that have tasks (`locked 0 project configs → .vx/projects.lock.json (no
+projects that have tasks (`0 project configs → .vx/projects.lock.json (no
 vx.config, so not locked: app, lib)`, five names then `and N more`),
 so an empty lock on a plugin-only workspace never reads like an audit.
 One with no task (core's default `build` aside) is not named.
@@ -2035,8 +2052,9 @@ binary keeps the old one's mode (and, as root, its owner), and must
 answer `--version` before the upgrade reports it installed: one that
 does not start on this machine, or does not answer within 10 s, is
 swapped back for the previous vx, and the command exits 1 saying so
-(item 1097). On the version it already is it says `already at
-<version>` and downloads nothing.
+(item 1097): `✓ vx upgrade  installed 0.0.2`. On the version it
+already is it says `› vx upgrade  already at <version>` and downloads
+nothing.
 
 **A vx a package manager installed** (the npm package's launcher runs
 `…/node_modules/@vzn/vx-<os>-<arch>/vx`) is upgraded by that package
@@ -2060,10 +2078,16 @@ root adds `--workspace-root`. The lockfile is updated by that manager.
 Run inside a project that installs `@vzn/vx`, a global vx hands
 `vx upgrade` to the project's own (§ Which vx runs), so the project's
 dependency is what moves.
-vx prints what it runs (`vx upgrade: 0.0.1 → 0.0.2: running pnpm add
-@vzn/vx@0.0.2 --save-dev (in /repo)`), runs it there, and exits with an
-error if it fails. vx never installs Node or a package manager: one not
-on `PATH` is refused with the command to run. A vx run from an npx or
+vx prints what it runs, runs it there, and exits with an error if it
+fails:
+
+```
+› vx upgrade  0.0.1 → 0.0.2
+
+  bun add @vzn/vx@0.0.2 in /repo
+```
+
+vx never installs Node or a package manager: one not on `PATH` is refused with the command to run. A vx run from an npx or
 bunx cache has nothing installed to upgrade, and says to ask for
 `@vzn/vx@latest` instead.
 
@@ -2321,12 +2345,15 @@ lists core's verbs. A plugin's verb exists once its plugin is in
 No project in scope declares a requested task. The message lists the
 tasks it found; `vx show --format json` lists each project's. Check the
 spelling, and the scope: `--filter`, `--all`, or the project the working
-directory is in.
+directory is in. A run reads its configs from the lock, so a task
+added to a `vx.config` since the last `vx lock` is not there yet: run
+`vx lock`.
 
 #### `VX_E_UNKNOWN_PROJECT`
 
 `vx show` names a project the workspace does not have. A project is named
-by its `package.json` `name`; `vx show --format json` lists them.
+by its config's `name`, else by a plugin (a lockfile plugin names it from
+its `package.json`), else by its directory; `vx show --format json` lists them.
 
 #### `VX_E_NO_HISTORY`
 
@@ -2487,23 +2514,25 @@ Nx's spellings name these: `vx show projects` (when no project or task
 has that name) and `vx show project <name>` say `vx show` and
 `vx show <name>`.
 
-No target: one line per project — name, root-relative dir, task count,
-and a `(no vx config)` marker for config-less packages; one whose
-tasks all come from plugins reads `N tasks (no vx config; from
-plugins)`, and one a configured project depends on reads `1 task (no
-vx config; default build)`: a run loads it for that dependant's
-`^build` (X-48). A project's `tags` follow in brackets. With `--format json`
+No target: a table, one row per project — name, root-relative dir,
+task count, and `no vx config` for config-less packages; one whose
+tasks all come from plugins reads `N tasks from plugins (no vx
+config)`, and one a configured project depends on reads `1 task,
+default build (no vx config)`: a run loads it for that dependant's
+`^build` (X-48). A `tags` column appears when any project has tags. With `--format json`
 it's an array of `{ name, dir, tags: string[], tasks: string[] }`.
 
 ```
 $ vx show
-app   packages/app   3 tasks  [scope:web]
-bare  packages/bare  (no vx config)
+  project  dir            tasks         tags
+  app      packages/app   3 tasks       scope:web
+  bare     packages/bare  no vx config
 ```
 
-Under its header `vx show <project>` prints its `tags`.
-`vx show <project>` prints a block per task with every field the run
-reads: description, command (`(group)` for group tasks), `dependsOn`,
+A report naming the project opens it: its `dir`, its `tags`, and
+`config  none` for a package with no config file. Then
+`vx show <project>` prints a block per task, headed by its
+`project#task`, with every field the run reads: description, command (`(group)` for group tasks), `dependsOn`,
 `timeout`, `retries`, `env.passThrough` / `env.define` / `env.secret`,
 `remote`, `sandbox`, `persistent`, `interactive` (`yes` / `no`), and the
 cache block
@@ -2521,15 +2550,15 @@ list and `vx show <project>`, but `vx show build`, like
 
 ```
 $ vx show app#build
-app — packages/app
 
-build
-  description:   compile the app
-  command:       tsc -b
-  dependsOn:     ^build
-  inputs.files:  src/**
-  inputs.env:    NODE_ENV
-  outputs.files: dist/**
+─ app#build ──────────────────────────────────────────────────
+  dir            packages/app
+  description    compile the app
+  command        tsc -b
+  dependsOn      ^build
+  inputs.files   src/**
+  inputs.env     NODE_ENV
+  outputs.files  dist/**
 ```
 
 Unknown project / task names exit `1` with the same near-miss hint
@@ -2572,24 +2601,26 @@ counts are zero and `projects lock` says `no` — a broken config is
 
 ```
 $ vx info
-vx:               0.0.0
-bun:              1.4.2
-git:              2.53.0
-git status cache: core.fsmonitor, core.untrackedCache off
-workspace root:   /work/repo
-projects:         12 (34 tasks)
-plugins:          2 — @vzn/vx-reapi (executor, cache); @vzn/vx-otel (telemetry)
-workers:          2 — cgroup CPU quota 2 of 8 cores
-memory:           13 GB usable — cgroup limit; the machine has 16 GB
-cache dir:        /work/repo/.vx/cache (8.2 MB, this workspace's run history)
-cache store:      /home/me/.vx/3f2a9c1e7b4d5a60/cache (1.3 GB, shared by this repo's checkouts)
-cache versions:   keys vx-cache-v43 · index schema v36
-cache entries:    42 (1.3 GB)
-orphans:          3 artifacts (12 MB) the index does not know — `vx cache clean` reaps them
-task runs (24h):  7 (5 cache hits)
-flaky tasks:      1 — web#test (3 of 11 runs failed on unchanged inputs)
-sandbox:          available (9 tasks declare exec.sandbox)
-projects lock:    yes
+
+─ vx info ────────────────────────────────────────────────────
+  vx                0.0.0
+  bun               1.4.2
+  git               2.53.0
+  git status cache  core.fsmonitor, core.untrackedCache off
+  workspace root    /work/repo
+  projects          12 (34 tasks)
+  plugins           2 — @vzn/vx-reapi (executor, cache); @vzn/vx-otel (telemetry)
+  workers           2 — cgroup CPU quota 2 of 8 cores
+  memory            13 GB usable — cgroup limit; the machine has 16 GB
+  cache dir         /work/repo/.vx/cache (8.2 MB, this workspace's run history)
+  cache store       /home/me/.vx/3f2a9c1e7b4d5a60/cache (1.3 GB, shared by this repo's checkouts)
+  cache versions    keys vx-cache-v43 · index schema v38
+  cache entries     42 (1.3 GB)
+  orphans           3 artifacts (12 MB) the index does not know — `vx cache clean` reaps them
+  task runs (24h)   7 (5 cache hits)
+  flaky tasks       1 — web#test (3 of 11 runs failed on unchanged inputs)
+  sandbox           available (9 tasks declare exec.sandbox)
+  projects lock     yes
 ```
 
 - `git` shows `(not found)` when the binary is missing.
@@ -2905,9 +2936,9 @@ measured. `--stats` does not combine with `--list`, `--failed` or
 `--log`; `--branch` combines only with `--stats`. `--list --format json`
 an array of the same `invocation` objects, newest first. An unknown run id fails
 loud and points at `--list`. Before any run, every form says so
-(`vx last: no recorded runs yet — run something first`, exit 1; `--list`
-prints `no recorded runs`, exit 0), and past green runs only,
-`--list --failed` prints `no recorded run failed`. A run id may be typed as a unique prefix; a
+(`› vx last  no runs yet` with `fix  vx run`, exit 1; `--list` prints
+`› vx last  no runs yet`, exit 0), and past green runs only,
+`--list --failed` prints `› vx last  no failed runs`. A run id may be typed as a unique prefix; a
 prefix several runs share fails and lists them. A replayed run with
 failures ends with the command that re-runs them (`re-run what failed:
 vx run app#test -- …`, with the arguments the run forwarded to the
@@ -2994,7 +3025,7 @@ export function mcp(): VxPlugin {
       mcp: {
         description: 'serve the run history to an AI agent over stdio',
         async run(argv, ctx) {
-          // ctx.workspaceRoot, ctx.cacheDir, ctx.concurrency, ctx.warn(...)
+          // ctx.workspaceRoot, ctx.cacheDir, ctx.concurrency, ctx.cache, ctx.warn(...)
           return 0 // the process exit code
         },
       },
@@ -3005,6 +3036,9 @@ export function mcp(): VxPlugin {
 
 The plugin's name is its package name, which `definePlugin` reads from
 `import.meta`; a plain object is refused when the workspace loads.
+`ctx.cache` reads the plugin's own entries as `setup` writes them (the
+local store, then each remote the workspace's cache plugins supply,
+under the run's scope), read-only, opened on first use.
 
 (`@vzn/vx-schedule-history` ships exactly this: `vx history`, what it
 learned per task and the reservation its `admit` hook packs.) The dispatcher tries core's verbs
@@ -3066,11 +3100,11 @@ what a TASK sees is `exec.env` in `docs/schema.md`.
 | `VX_CACHE_DOWNLOAD`                 | [`cache.download`](schema.md#settings)                | Which remote hits land on disk: every one, only the requested tasks, or none.                                                                               |
 | `VX_CACHE_INPUT_STABILITY_STRATEGY` | [`cache.inputStability.strategy`](schema.md#settings) | What a write to an input during the command means for the save, for tasks without their own.                                                                |
 | `VX_CACHE_INPUT_STABILITY_SEVERITY` | [`cache.inputStability.severity`](schema.md#settings) | Whether a skipped save warns or fails the task, for tasks without their own.                                                                                |
-| `VX_CACHE_OUTPUTS_CLEAN`            | [`cache.outputs.clean`](schema.md#settings)           | Remove a task's declared outputs before it runs on a miss, for tasks without their own.                                                                     |
 | `VX_LOCK_REVIEW_FILES`              | [`lock.reviewFiles`](schema.md#settings)              | `vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.                           |
 | `VX_WATCH_POLL`                     | [`watch.poll`](schema.md#settings)                    | Poll for changes from the start instead of the OS watcher.                                                                                                  |
 | `VX_CONFIG_WORKER_TIMEOUT`          | [`config.workerTimeout`](schema.md#settings)          | How long one config evaluation may take.                                                                                                                    |
 | `VX_DEBUG_TIMING`                   | [`debug.timing`](schema.md#settings)                  | Print the run's stage timings to stderr.                                                                                                                    |
+| `VX_DEBUG_WATCH`                    | [`debug.watch`](schema.md#settings)                   | `vx watch`: say on stderr each time the loop arms, with the projects it watches.                                                                            |
 | `VX_DEBUG_DUMPABLE`                 | [`debug.dumpable`](schema.md#settings)                | Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.                                 |
 | `VX_HANDED_OFF`                     | —                                                     | Set by a global vx that hands the call to the project's own (§ Which vx runs): the path of the vx that handed off, so the receiver does not hand off again. |
 | `VX_RUN_WORKSPACE`, `VX_RUN_TASK`   | —                                                     | Set by vx on every task (below); a `vx run` a task starts reads them back.                                                                                  |
@@ -3165,7 +3199,7 @@ A broad run looks like:
   tasks     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
             2 success · 2 total
   cache     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
-            1 miss · 1 local
+            local 1↓ 1↑
 
   info      8 workers · local cache
   time      5.34s · 900ms saved
@@ -3174,7 +3208,15 @@ A broad run looks like:
 The three bars are meters: `projects` is what the run covered against
 the workspace, `tasks` is failed / success / skipped, `cache` is miss /
 no-cache / up-to-date / local / remote (a skipped task rides it too, so
-the two bars fill alike; its count is on the tasks legend only). The
+the two bars fill alike; its count is on the tasks legend only). Its
+legend reads per layer: `local 1● 1○ 2↓ 4↑ · remote 3↓ 4↑`.
+`●` is a fresh hit (outputs already on disk, whichever layer answered,
+so it counts under local), `○` a task with no cache, `↓` is restored
+from that layer and `↑` saved to it (local `↑` counts only tasks that ran here; remote `↑` counts
+uploads that landed). A layer shows only when the run's
+`--cache-policy` uses it. `N not saved` (ran, succeeded, saved nothing),
+`N not downloaded` (outputs left in the remote store) and `N ↑ failed`
+show only when non-zero. The
 `time` row is the wall time, then what the cache saved (the hits' stored
 exec times, never the restore), then the spread over executed tasks
 only — a hit's restore time never enters it. The footer never says a

package/docs/execution.md

@@ -548,7 +548,7 @@ Status and Cache columns.
 
 The colors / framing modules:
 
-- `orchestrator/colors.ts` — ANSI truecolor (`ansi-16m`), gated by
+- `util/colors.ts` — ANSI truecolor (`ansi-16m`), gated by
   `NO_COLOR` / `FORCE_COLOR` / `isTTY`. Programmatic-logger callers
   always see plain text.
 - `orchestrator/framed-output.ts` — the `┌─` frames, the glyph grid

package/docs/features.md

@@ -75,7 +75,7 @@ config key or an environment variable is missing here.
 - **Docs for agents** (`llms.txt`, `llms-full.txt`) — the whole site as markdown for coding agents. [page](https://vznjs.github.io/vx/features/llms-txt/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 - **vx docs** (`vx docs`, `--limit`) — search the CLI, config and cache reference offline; it ships inside vx. [page](https://vznjs.github.io/vx/features/vx-docs/) · post: [The reference, offline](https://vznjs.github.io/vx/blog/vx-docs-offline/)
 - **Affected reasons** (`--affected --dry`) — each kept task says the changed file or the dependency chain that reached it, text or JSON. [page](https://vznjs.github.io/vx/features/affected-reasons/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
-- **Agent skill** (`skills/vx/SKILL.md`, `npx skills add vznjs/vx/packages/vx/skills/vx`) — an installable skill that teaches a coding agent to run, debug and query vx through the CLI's `--format json`; copy it from `node_modules/@vzn/vx/skills/vx/` to match the installed version. [page](https://vznjs.github.io/vx/features/agent-skill/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
+- **Agent skill** (`skills/vx/SKILL.md`, `npx skills add vznjs/vx`) — an installable skill that teaches a coding agent to run, debug and query vx through the CLI's `--format json`; copy it from `node_modules/@vzn/vx/skills/vx/` to match the installed version. [page](https://vznjs.github.io/vx/features/agent-skill/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 
 ## Cache
 
@@ -83,7 +83,7 @@ config key or an environment variable is missing here.
 - **Inputs** (`cache.inputs.env`, `cache.inputs.runtime`, `cache.inputs.tasks`, `cache.inputs.workspaceFiles`, `cache.inputs.workspaceRuntime`) — env vars, tool versions, upstream tasks and workspace files in the key. [page](https://vznjs.github.io/vx/features/key-inputs/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Outputs** (`cache.outputs.files`, `cache.outputs.workspaceFiles`) — what a hit restores. [page](https://vznjs.github.io/vx/features/cache-outputs/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Input stability** (`cache.inputStability`, workspace `cache.inputStability`, `VX_CACHE_INPUT_STABILITY_STRATEGY`, `VX_CACHE_INPUT_STABILITY_SEVERITY`) — an input written while the command runs withholds the save, on CI too, and the saves of every task that ran over its outputs; `strategy: 'mutable'` accepts a task's identical rewrite of its own input, `'unchecked'` skips the check; `severity: 'error'` fails the run instead of warning. no post
-- **Keep outputs on a miss** (`cache.outputs.clean`, workspace `cache.outputs.clean`, `VX_CACHE_OUTPUTS_CLEAN`) — `false` leaves a task's outputs in place for a tool that reads its last output (tsc's `.tsbuildinfo`); if the run leaves any old file unchanged, nothing is cached. no post
+- **Keep outputs on a miss** (`cache.outputs.clean`, workspace `cache.outputs.clean`) — `false` leaves a task's outputs in place for a tool that reads its last output (tsc's `.tsbuildinfo`) and caches everything the outputs then hold, leftovers included (an opt-out of the clean-tree guarantee). no post
 - **Outputs are exactly the snapshot** (`run.rules.exclusiveOutputs`, `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`) — a hit leaves the tree as the run did; two tasks may not own one output without an edge. [page](https://vznjs.github.io/vx/features/strict-outputs/) · post: [The tree is exactly the snapshot](https://vznjs.github.io/vx/blog/strict-output-ownership/)
 - **Keys from git's index** — tracked clean files hash by their blob id, no read. [page](https://vznjs.github.io/vx/features/keys-from-git/) · post: [Your cache key is already in git's index](https://vznjs.github.io/vx/blog/keys-from-git/)
 - **Config keyed as evaluated** — the key sees the resolved config object. [page](https://vznjs.github.io/vx/features/typescript-config/) · post: [Configs are programs](https://vznjs.github.io/vx/blog/resolved-config-hashing/)
@@ -109,7 +109,7 @@ config key or an environment variable is missing here.
 - **Sandboxed tasks** (`exec.sandbox`: `allow`, `deny`, `ignore`, `weakerNetworkIsolation`, `weakerWhenNested`) — a task reads and writes only what it declares; `allow` names `read`, `write`, `network`, `unixSockets`, `localBinding`, `pty`, `systemInfo`, `gitConfig`, `machLookup`. [page](https://vznjs.github.io/vx/features/sandbox/) · post: [The sandbox](https://vznjs.github.io/vx/blog/the-sandbox/)
 - **Env isolation** (`exec.env`: `define`, `passThrough`, `secret`, `VX_DEBUG_DUMPABLE`) — a task sees only the env it names; secrets are masked; vx hides its own env from tasks (Linux and macOS). [page](https://vznjs.github.io/vx/features/env-isolation/) · post: [A task sees only the env it names](https://vznjs.github.io/vx/blog/env-isolation/)
 - **vx lock** (`vx lock`, `--check`, `--format json`, `lock.reviewFiles`, `VX_LOCK_REVIEW_FILES`) — find the projects (every directory holding a `vx.config`), freeze what their configs evaluate to and check the graph rules once; only `vx lock` evaluates configs: runs, `vx show` and `vx info` read the lock and never write it; a pretty `vx.lock.json` beside each config shows reviewers what it resolves to. [page](https://vznjs.github.io/vx/features/vx-lock/) · post: [vx lock: freezing what the key sees](https://vznjs.github.io/vx/blog/lock-and-frozen/)
-- **Flaky detection** — a task that fails then passes is reported flaky. [page](https://vznjs.github.io/vx/features/flaky-detection/) · post: [Flaky is a claim](https://vznjs.github.io/vx/blog/flaky-tasks/)
+- **Flaky detection** — a task whose key fails after it passed is reported flaky, judged on every worktree's record of the repo. [page](https://vznjs.github.io/vx/features/flaky-detection/) · post: [Flaky is a claim](https://vznjs.github.io/vx/blog/flaky-tasks/)
 - **Project boundaries** — globs never cross into another project. [page](https://vznjs.github.io/vx/features/project-boundaries/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Artifact integrity checks** — a CRC-32, a key match and an outputs-only check on every artifact; damage is a miss. [page](https://vznjs.github.io/vx/features/artifact-integrity/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Sandbox names what to grant** — a refused write is named beside the failed task with the path to allow. [page](https://vznjs.github.io/vx/features/sandbox-grants/) · post: [Guard rails that tell you the fix](https://vznjs.github.io/vx/blog/guard-rails/)
@@ -118,7 +118,7 @@ config key or an environment variable is missing here.
 
 ## Daily work
 
-- **Watch mode** (`vx watch`, `--poll`, `watch.poll`, `VX_WATCH_POLL`) — re-run what a change affects, on content, not events. [page](https://vznjs.github.io/vx/features/watch/) · post: [Watch: a content gate](https://vznjs.github.io/vx/blog/watch-mode/)
+- **Watch mode** (`vx watch`, `--poll`, `watch.poll`, `VX_WATCH_POLL`, `VX_DEBUG_WATCH`) — re-run what a change affects, on content, not events. [page](https://vznjs.github.io/vx/features/watch/) · post: [Watch: a content gate](https://vznjs.github.io/vx/blog/watch-mode/)
 - **Dev servers in the graph** (`exec.persistent`, `readyWhen`, `--ready-notice`, `run.readyNotice`, `VX_RUN_READY_NOTICE`) — a server is a node; dependents start when it is ready. [page](https://vznjs.github.io/vx/features/dev-servers/) · post: [Dev servers as graph nodes](https://vznjs.github.io/vx/blog/dev-servers-in-the-graph/)
 - **Interactive tasks** (`exec.interactive`) — a task that owns the terminal. [page](https://vznjs.github.io/vx/features/interactive-tasks/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
 - **Shell completions** (`vx completions`) — bash, zsh, fish. [page](https://vznjs.github.io/vx/features/completions/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
@@ -169,7 +169,7 @@ config key or an environment variable is missing here.
 - **Remote cache and execution** (`@vzn/vx-reapi`, `exec.remote`) — Bazel REAPI cache and workers; the scheduler stays here. [page](https://vznjs.github.io/vx/features/remote-execution/) · post: [Remote execution without moving the scheduler](https://vznjs.github.io/vx/blog/remote-execution/)
 - **OpenTelemetry** (`@vzn/vx-otel`) — each run exported to your OpenTelemetry backend, never breaking it. [page](https://vznjs.github.io/vx/features/opentelemetry/) · post: [Observability that cannot break a run](https://vznjs.github.io/vx/blog/telemetry-never-breaks-a-run/)
 - **vx history** (`@vzn/vx-schedule-history`, `vx history`) — what the scheduler learned per task. [page](https://vznjs.github.io/vx/features/vx-history/) · post: [A scheduler that learns from your runs](https://vznjs.github.io/vx/blog/a-scheduler-that-learns/)
-- **Setup and teardown hooks** (`setup`, `teardown`) — plugin code around the run, bounded by a timeout. [page](https://vznjs.github.io/vx/features/setup-teardown/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)
+- **Setup and teardown hooks** (`setup`, `teardown`, `RunReport`, `ctx.cache.getRun`) — plugin code around the run, bounded by a timeout; on a run that writes a remote, vx keeps failed tasks' logs and outputs and uncached tasks' logs there, and `teardown` gets the run, its CI job and every task with the names to read them by, which a plugin verb reads back through its read-only `ctx.cache`. [page](https://vznjs.github.io/vx/features/setup-teardown/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)
 - **REAPI TLS, mTLS and headers** — connect to hosted servers such as BuildBuddy the way Bazel does. [page](https://vznjs.github.io/vx/features/reapi-tls/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
 - **REAPI execution records** — a repeat remote execution skips the worker and replays outputs and stdout. [page](https://vznjs.github.io/vx/features/reapi-action-cache/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
 - **REAPI verified downloads and deadlines** — a corrupt blob or a wedged server degrades to a miss, never a hang. [page](https://vznjs.github.io/vx/features/reapi-safety/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
@@ -177,3 +177,4 @@ config key or an environment variable is missing here.
 - **OTel live export** (`otel({ live })`) — spans and metrics stream as tasks end, so a dashboard follows a CI run live. [page](https://vznjs.github.io/vx/features/otel-live/) · post: [Watch a CI run while it runs](https://vznjs.github.io/vx/blog/otel-live/)
 - **Memory-aware admission** (`@vzn/vx-schedule-history`) — tasks are packed by the peak memory learned from past runs. [page](https://vznjs.github.io/vx/features/memory-admission/) · post: [A scheduler that learns from your runs](https://vznjs.github.io/vx/blog/a-scheduler-that-learns/)
 - **CI timings file** (`@vzn/vx-schedule-history`, `file`) — one JSON file of learned task times a CI cache carries between runners, so a fresh runner orders by real times. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Carry the scheduler's memory between CI runners](https://vznjs.github.io/vx/blog/ci-timings-file/)
+- **Shared timings** (`@vzn/vx-schedule-history`, `defaultBranch`) — CI on the default branch writes task timings to the remote cache; a branch with none imports its merge-base's. Plugins keep their own entries there through `ctx.cache`. [page](https://vznjs.github.io/vx/features/critical-path/)