@vzn/vx 0.0.639 → 0.0.641

package/docs/cli.md

@@ -37,7 +37,7 @@ vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--for
 vx info [--format pretty|json] [--cache-dir <path>]
 vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]
 vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--stats [<task>] [--branch <name>]] [--format pretty|json] [--cache-dir <path>]
-vx upgrade [TAG]      # upgrade vx the way it was installed
+vx upgrade [TAG] [-g|--global]
 vx docs <query> [--limit N] [--format pretty|json]
 vx completions bash|zsh|fish
 
@@ -301,13 +301,13 @@ change seeds tasks in the projects it touches:
   repository is one its `workspaceFiles` may reach into (git reports it
   as one path; a glob whose fixed prefix is above or inside it counts);
 - every task of a project whose `vx.config.*`
-  changed, or that holds a changed path no cached task of its declares
+  changed, or that holds a changed path no task of its declares
   (vx cannot prove that path re-keys nothing), or that holds a changed
   submodule or embedded repository (git reports it as one path, and no
   task's globs can say whether they reach inside), or that a lockfile
   claim or a config import names (a dependency an install added or
   removed reaches here as the lockfile's change);
-- an uncached task when a changed path lies in its project or the
+- a task with no `inputs` when a changed path lies in its project or the
   project is reached whole; a root file another task of its declares
   (`workspaceFiles`) is no change there. A group seeds nothing.
 
@@ -354,6 +354,14 @@ change to it, and every project under it is selected, the project that
 holds it included. A repository's own request to hide submodules from a diff
 (`diff.ignoreSubmodules`, `submodule.<name>.ignore`) does not apply:
 the key sees the change whatever git is told to show.
+A symlinked input keys what it points to, so a link whose target
+changed (a file the diff names, or one under a linked directory) is a
+changed path of its project, and a link to a target git cannot diff
+(outside the workspace, or git-ignored) is one on every run.
+A gitignored file a task's inputs name outright (`.env.local`,
+`dist/**`) never selects the task on its own, as in Nx: `--affected`
+reflects only what git sees. The key still hashes it, so a run of the
+task misses when it changed.
 `.vx/projects.lock.json` is filtered out of the changed set — a `vx lock`
 re-write never marks every project affected.
 
@@ -766,22 +774,26 @@ other persistent task`), and a non-zero exit makes the run exit 1
    local history knows the task, its row also shows its usual duration
    (its executed p50) in the cache column, fixed while the elapsed time
    counts up toward it (`3.33s running ~5.2s  solid-js#types`).
-4. **vx's own steps** — what vx does around the tasks, as rows of
+4. **vx's own steps** — what vx does around the tasks that the run
+   waits on, before its first task starts or before it ends, as rows of
    their own below the worker rows: `vx:load` (configs and graph from
    the lock), `vx:run-lock`, `<plugin>:setup`, `vx:keys` (keys and local
-   probes), `vx:prefetch`, `vx:schedule`, then after the graph
-   `vx:uploads`, `vx:history`, `vx:keep-run`, `vx:telemetry`,
-   `<plugin>:teardown`, `vx:snapshots`, `vx:retention`, `vx:close` and
-   `vx:sandbox`. A step shows once it has run 150 ms, ticking like a
-   task (`     1.2s running   vx:uploads`); no worker slot or
+   probes), `<plugin>:schedule`, then after the graph `vx:uploads`,
+   `vx:history`, `<plugin>:telemetry`, `<plugin>:teardown`,
+   `vx:snapshots`, `vx:retention`, `vx:close` and `vx:sandbox`. A step
+   shows once it has run 150 ms, ticking like a task
+   (`     1.2s running internal vx:uploads`); no worker slot or
    `--concurrency` holds it back. When it ends it leaves a list row
-   like a task's, with no cache column (`⏺︎ 1.2s success   vx:uploads`);
-   a quicker one shows nowhere. `:` is no task id's separator, so a
-   step never reads as a task: a project named `vx` keeps `vx#build`.
-   No step is a task: no count, bar, history row, forecast, flaky
-   verdict, `vx last` row or telemetry record holds one; `--profile`
-   and `VX_DEBUG_TIMING` time vx's stages their own way. Steps show only
-   beside a live region; a log (CI, a pipe) prints none.
+   like a task's, `internal` in the cache column
+   (`⏺︎ 4.60s success internal vx:uploads`); a quicker one shows
+   nowhere. A step that runs beside the tasks, `vx:prefetch` (a
+   remote's downloads), never shows: `vx last` lists it. `:` is no task
+   id's separator, so a step never reads as a task: a project named
+   `vx` keeps `vx#build`. No step is a task: no count, bar, history
+   row, forecast, flaky verdict or telemetry record holds one;
+   `--profile` and `VX_DEBUG_TIMING` time vx's stages their own way.
+   Steps show only beside a live region; a log (CI, a pipe) prints
+   none.
 5. **The live summary section** — the SAME meters the final footer
    prints (`tasks` + `cache` bars with legends, `time`), filling in as
    the run progresses, under a bare `vx` wordmark rule. A second in,
@@ -901,14 +913,14 @@ Locally-executed tasks always write in place and ignore the flag, and
 it in either direction. **It never affects a cache key**: transfer
 tuning cannot change what a command produces.
 
-One safety gate: a task whose outputs another task's `cache.inputs`
+One safety gate: a task whose outputs another task's `inputs`
 globs could read on disk is silently kept eager, because deferring it
 would make that key depend on whether the bytes arrived. A task with no
 `cache` that a cached task depends on counts as reading its whole
 project (C-16). `--dry` reports
 how many tasks would keep their outputs remote and names each downgrade,
 so a run that defers nothing says why. A run in which any task declares a
-`cache.inputs.runtime` / `workspaceRuntime` command defers **nothing**:
+`inputs.runtime` / `workspaceRuntime` command defers **nothing**:
 a shell command's reads cannot be bounded, so vx cannot prove it will
 not read a deferred output (the same reason vx refuses to infer inputs
 by tracing). When bytes are fetched later, vx saves an ordinary
@@ -1009,8 +1021,8 @@ $ 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
+project changed and the task reads it whole: a task with no `inputs`, or a
+changed `file` no task of the project declares, often an output git does not
 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),
@@ -1086,7 +1098,8 @@ export default {
           },
         },
       },
-      cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
+      inputs: { files: ['src/**'] },
+      cache: { outputs: { files: ['dist/**'] } },
     },
   },
 }
@@ -1110,7 +1123,7 @@ task's `SANDBOX VIOLATIONS` section ends with a dimmed `fix:` line,
 the grants that would have allowed each denial, project-relative:
 `fix: exec.sandbox.allow: { read: ['tsconfig.json'], write: ['dist/'] }`.
 A write grants the top directory it landed in, so the next file there
-passes too, unless `cache.inputs.files` reads that directory: then it
+passes too, unless `inputs.files` reads that directory: then it
 grants the file alone, so the task cannot write its own inputs; a read the output depends on is a key input as well, and
 the line says so, since a grant never adds one. A credential path
 (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.kube`, `~/.config/gh`,
@@ -1205,8 +1218,10 @@ run...` precedes it.
    not change since the loop last saw it is not an edit (a `chmod` is one,
    as the key reads the executable bit), nor is a directory
    whose entries (names and sizes) did not, nor a path that stayed
-   gone; a symlink is its target string, as the key folds it, so a
-   retarget is an edit; a path the loop has never judged is an edit only if it was
+   gone; a symlink is its target string and what it points to, as the
+   key folds them, so a retarget is an edit, and so is an edit behind
+   it: watch arms each link's target, wherever it lies, and names the
+   link; a path the loop has never judged is an edit only if it was
    modified after the watchers went live (macOS delivers the initial
    run's own writes after the arm; the later of the path's mtime and
    ctime says which side of it a path belongs to, so a file moved in
@@ -1228,8 +1243,7 @@ run...` precedes it.
    which reads what it likes, item 947, outside any project nested
    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
+   saved mtime is the run's, `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
@@ -1237,7 +1251,7 @@ run...` precedes it.
    `.gitignore` as the remedy (a persistent task declares no outputs;
    item 948). A file git tracks is never blamed on the server: three
    saves of a source file are the user's (WD-7). When any project's config declares
-   `cache.inputs.workspaceFiles`, the per-project watchers are swapped
+   `inputs.workspaceFiles`, the per-project watchers are swapped
    for ONE recursive root watcher (boundaries are off for those globs,
    so a root-relative glob can name a file anywhere). That watcher
    hears every write in the tree and keeps only the ones a key can
@@ -1285,19 +1299,20 @@ Always ignored (no re-trigger):
 
 - `node_modules/`, `.git/`, `.vx/cache/` anywhere in the path.
 - A path git ignores (`git check-ignore`, asked once per debounce
-  window, never per event): invisible to every cache key — inputs are
+  window, never per event), unless a task's inputs name it outright
+  (`.env.local`, `dist/**`): invisible to every other cache key — inputs are
   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 `~` (editor swap files), and a restore's own
-  `.vx-tmp-*` file.
+- Files ending in `~` (editor swap files), and `.vx/tmp/`, where
+  restores stage.
 - 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
   cycle, which writes again — a loop that never settles.
 
 Everything else triggers a cycle. We deliberately don't filter events
-against per-task `cache.inputs.files` — the cache hash is the source
+against per-task `inputs.files` — the cache hash is the source
 of truth. A change to an irrelevant file produces a cache-hit run
 (typically tens of ms); the cost is much smaller than the engineering
 cost of a per-event glob match.
@@ -1863,8 +1878,16 @@ manager is its lockfile (`pnpm-lock.yaml`, `bun.lock`, `yarn.lock`,
 `package-lock.json`), else `packageManager`, else npm; the field it is
 listed in is kept (`--save-dev`, `--dev`, …), and pnpm at a workspace
 root adds `--workspace-root`. The lockfile is updated by that manager.
-vx prints what it runs, runs it there, and exits with an error if it
-fails:
+Every `@vzn/vx-*` plugin the same package.json lists from the registry
+moves in the same install, to the same release, since every @vzn
+package releases together: `pnpm add @vzn/vx@0.0.2 @vzn/vx-otel@0.0.2
+--save-dev`. A plugin left behind is installed even when core is
+already at the release (`› vx upgrade  plugins → 0.0.2`); a plugin in
+another field than core is refused, so no install moves a dependency's
+field. The versions are pinned, so pnpm's `minimumReleaseAge` refuses a
+release too young rather than mixing releases, and the error names
+`minimumReleaseAgeExclude`. vx prints what it runs, runs it there, and
+exits with an error if it fails:
 
 ```
 › vx upgrade  0.0.1 → 0.0.2
@@ -1882,6 +1905,12 @@ project that fails leaves the global as it was. The project's vx run
 directly (a package script, `node_modules/.bin/vx`) has no global behind it, so only
 the project moves.
 
+**`vx upgrade -g`** (`--global`) moves only the global vx, wherever it
+runs: it never hands the call to a project's vx, and it never touches a
+`package.json` or a plugin. Run as the project's own vx, it refuses:
+`vx upgrade -g: no global vx ran — <path> is the project's own. Install
+one (npm install -g @vzn/vx), or run \`vx upgrade\` to move the project's`.
+
 ```
 › vx upgrade  project 0.0.1 → 0.0.2
 
@@ -1910,9 +1939,11 @@ or is missing.
 runs in, or one above it up to the git top-level, holds a
 `package.json`, `pnpm-workspace.yaml`, `turbo.json`, `turbo.jsonc` or
 `nx.json`, it runs `@vzn/vx-migrate` there, so `vx init` is the one
-command (owner, 2026-10-08): the installed one (the nearest
-`node_modules/@vzn/vx-migrate` up from the working directory), else
-this vx's version through `bun x` (`BUN_BE_BUN=1` makes the compiled
+command (owner, 2026-10-08): the latest release through `bun x`,
+never an installed one, so init always installs the latest `@vzn/vx`
+and moves every `@vzn/vx-*` plugin the root lists to it (M,
+2026-10-16; a source checkout runs the nearest installed
+`node_modules/@vzn/vx-migrate` instead) (`BUN_BE_BUN=1` makes the compiled
 binary that runtime). `--dry`, `--format`, `--force`, `--mjs`,
 `--native` and `--keep` pass through, and the exit is vx-migrate's.
 vx-migrate maps a Turbo, Nx or Vite Task repo, else the `package.json`
@@ -2059,7 +2090,7 @@ copy to the source.
 | turbo  | `--dangerously-disable-package-manager-check`     | refuse  | vx reads no `packageManager` field: drop it                                                                                                       |
 | turbo  | `--env-mode <v>`                                  | refuse  | vx passes only the variables a task declares (strict): list the rest in `exec.env.passThrough`                                                    |
 | turbo  | `--framework-inference <v>`                       | refuse  | under `turbo()` inference is Turbo's; take a name back with a `!` entry in the task's `env`                                                       |
-| turbo  | `--global-deps <v>`                               | refuse  | declare them in `cache.inputs.workspaceFiles` (under `turbo()`, turbo.json's `globalDependencies`)                                                |
+| turbo  | `--global-deps <v>`                               | refuse  | declare them in `inputs.workspaceFiles` (under `turbo()`, turbo.json's `globalDependencies`)                                                      |
 | turbo  | `--json`                                          | refuse  | use `vx last --format json` for the run's result, `--dry=json` for the plan                                                                       |
 | turbo  | `--log-file`                                      | refuse  | use `vx last --format json` for the run's JSON record                                                                                             |
 | turbo  | `--preflight`                                     | refuse  | set `turboCache({ preflight: true })` or `TURBO_PREFLIGHT=1`                                                                                      |
@@ -2251,7 +2282,7 @@ its own output path, or make one depend on the other.
 
 #### `VX_E_INPUT_IS_OUTPUT`
 
-A task's `cache.inputs` match outputs: its own (vx cleans outputs before
+A task's `inputs` match outputs: its own (vx cleans outputs before
 a run, so it would delete its sources) or another task's (its key must
 not read them; `dependsOn` already cascades). Exclude the outputs from
 the inputs with a `!` glob, as the message shows, or declare no outputs
@@ -2587,7 +2618,7 @@ app#build — run 01a1193a-7b39-75a9-870b-5c03e26d7104
     changed file  packages/app/src/input.txt  78981922613b2afb6025042ff6bd878ac1994e85 → 61780798228d17af2d34fce4cfbdf35556832472
 
   what to do:
-    file  an edit re-runs by design; a file the task does not read belongs out of cache.inputs.files
+    file  an edit re-runs by design; a file the task does not read belongs out of inputs.files
 ```
 
 A changed key's verdict names what moved, kind and name, three at most
@@ -2628,7 +2659,7 @@ A hit's line is `cache-hit · key …` (or `cache-hit-remote`): the status
 names the hit and its tier, so only an executed run carries the word.
 A skipped task never ran and derived no key: its line is `skipped · no key`.
 A row's kind is what the key folded: `file` (an input file, by blob
-id), `env` (a declared variable, by digest), `runtime` and
+id), `linked` (the content behind a `file` that is a symlink), `env` (a declared variable, by digest), `runtime` and
 `ws-runtime` (a declared command's output, `inputs.runtime` and
 `inputs.workspaceRuntime`), `forward` (the argv forwarded after `--`),
 `config` (the evaluated task config), `upstream` (a dependency's input
@@ -2643,9 +2674,9 @@ is gone (pruned, or the run failed and never saved one) the verb still
 names the hash change and says the component diff is unavailable. When
 only the previous run failed, the diff is taken against the last run
 that saved an entry instead, and the detail line names that run. A
-task with no `cache` block derives a key too — it is what dependents
-fold — but saves no entry, so for it the verb can only report the key
-change and says so.
+task with `inputs` and no `cache` block derives a key too — it is what
+dependents fold — but saves no entry, so for it the verb can only report
+the key change and says so.
 `--format json` emits one machine-readable object (`{ taskId, runId,
 why, diff, roots, writers }`); when the task's recorded runs predate run ids, `{ taskId,
 why, diff, explanation }`, `why` and `diff` null and `explanation` the
@@ -2687,6 +2718,11 @@ their count (`… +980 more cache hits`) — a thousand-task warm run is a
 thousand rows otherwise, with the one failure a screen above the
 prompt — and the sixteen shown are the slowest restores, the one thing
 a hit's row tells. `--format json` lists every row.
+Below the tasks, the steps the run did not wait on (`vx:prefetch`, a
+remote's downloads beside the tasks), which its own output never shows:
+`success  vx:prefetch  1.20s  internal`. They are kept per run, the
+newest 50, in `<cache dir>/steps/<run id>.json`, written only by a run
+that had one; `--format json` adds them as `steps`.
 `vx last --list` prints the N most recent runs (default 10), one per
 line in aligned columns (verdict, start, run id, counts, duration,
 command), each run id cut to the shortest prefix no other run shares, 13 characters at least (`--list 5`
@@ -2708,7 +2744,7 @@ sandboxed task's row adds `sandboxFix`, the `exec.sandbox.allow`
 entries (`read`, `write`, `network`, `systemInfo`) that would have
 granted its denials, the same grants the terminal prints as `fix:`;
 `withheld` lists the credential paths it denied and left out (a `.env` file, or a store under home the sandbox denies, `security.md`), and, for
-a cached task, `inputs` the reads of its project no `cache.inputs.files`
+a cached task, `inputs` the reads of its project no `inputs.files`
 glob matches (the terminal's `and, if the output depends on them, …`
 line). A task
 failed by `inputStability.severity: 'error'` adds `inputMoved`, the
@@ -2894,7 +2930,6 @@ what a TASK sees is `exec.env` in `docs/schema.md`.
 | `VX_RUN_CONTINUE`                   | [`run.continue`](schema.md#settings)                  | What a failed task takes down: `never` stops the run, `deps-ok` skips its dependents, `always` runs them too.                                               |
 | `VX_RUN_OUTPUT_LOGS`                | [`run.outputLogs`](schema.md#settings)                | Which task output the run prints. Chosen before the workspace loads, so flag and env only.                                                                  |
 | `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`    | [`run.rules.exclusiveOutputs`](schema.md#settings)    | Refuse two tasks whose outputs overlap even when an edge orders them.                                                                                       |
-| `VX_RUN_RULES_UPFRONT_KEYS`         | [`run.rules.upfrontKeys`](schema.md#settings)         | Refuse a task whose inputs can match another task's outputs.                                                                                                |
 | `VX_CACHE_DIR`                      | [`cache.dir`](schema.md#settings)                     | Where the cache lives, relative to the workspace root; named, it holds the whole cache.                                                                     |
 | `VX_CACHE_RETENTION_MAX_SIZE`       | [`cache.retention.maxSize`](schema.md#settings)       | Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).                                                               |
 | `VX_CACHE_RETENTION_OLDER_THAN`     | [`cache.retention.olderThan`](schema.md#settings)     | Evict entries unused for this long at each run's end (`'30d'`).                                                                                             |

package/docs/execution.md

@@ -154,7 +154,7 @@ terminal and a task succeeding or failing. Read it alongside
  │    • SIGINT/SIGTERM/SIGHUP handlers (removed in a finally): on
  │                signal, forward it (SIGHUP as SIGTERM) to everything
  │                in liveChildren + persistentRegistry (and kill any
- │                running cache.inputs.runtime probe, C-65), wait
+ │                running inputs.runtime probe, C-65), wait
  │                2 s for their groups, SIGKILL
  │                what is still there, let the run finish its own
  │                end (flush, teardown, cache close), then
@@ -174,12 +174,13 @@ terminal and a task succeeding or failing. Read it alongside
  │      overlap is the point); drained before cache.close(). At most
  │      one remote GET per key (shared in-flight map with the lazy
  │      read-through).
- │    • LOCAL SHORT-CIRCUIT (no remote layer, local reads on, ≥1
- │      task) — derive the same stable keys and probe them in ONE
- │      batched cache.getMany (a layer without getMany: cache.get once
- │      per task under a bounded pool) → a `preProbed` map (hits AND
- │      stable misses; execute reuses these probes) + a `restoreTier`
- │      set (confirmed hits). Awaited before scheduling; never throws
+ │    • LOCAL SHORT-CIRCUIT (local reads on, ≥1 task) — derive the
+ │      same stable keys and probe the LOCAL store in ONE batched
+ │      getMany (a layer without getMany: get once per task under a
+ │      bounded pool) → a `preProbed` map (hits AND stable misses;
+ │      with a remote declared, hits only: a local miss may be a
+ │      remote hit) + a `restoreTier` set (confirmed hits). Awaited
+ │      before scheduling; never asks a remote; never throws
  │      (degrades to the normal schedule).
  │
  ├─ Scheduling (src/graph/scheduler.ts:runGraph — two-tier)
@@ -243,7 +244,7 @@ terminal and a task succeeding or failing. Read it alongside
  │              UserError that fails this task — its dependents skip,
  │              independent tasks continue)
  │       2. hashTaskConfig (memoized per run via HashCache)
- │       3. filterUpstreamHashes (apply cache.inputs.tasks filter)
+ │       3. filterUpstreamHashes (apply inputs.tasks filter)
  │       4. cache.key({ taskId, taskConfigHash,
  │                      forwardArgs, envValues, runtimeValues,
  │                      workspaceRuntimeValues, upstreamHashes,
@@ -430,7 +431,7 @@ broader access has cache-stability implications).
 | Two projects of one name                                                                                                                                         | `checkProjectNames` throws with both paths                                                                                                                                                                                                                                                                                                                                                                                                              |
 | Cycle in task graph                                                                                                                                              | `detectCycle` throws with the cycle path                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Malformed config                                                                                                                                                 | `loadProjectConfigs` throws (UserError) with file + field                                                                                                                                                                                                                                                                                                                                                                                               |
-| `cache.inputs.runtime` command exits non-zero                                                                                                                    | UserError naming the command + exit code; that task is `failed`, dependents skip                                                                                                                                                                                                                                                                                                                                                                        |
+| `inputs.runtime` command exits non-zero                                                                                                                          | UserError naming the command + exit code; that task is `failed`, dependents skip                                                                                                                                                                                                                                                                                                                                                                        |
 
 By default (`--continue=deps-ok`) failures don't kill the scheduler —
 independent tasks already in flight finish, and unrelated tasks not yet
@@ -618,7 +619,7 @@ runs the same setup steps — workspace discovery, config load, package
 graph, task graph — and the same per-task hash derivation, then
 probes the cache. The probe is read-only; against a remote layer it
 is an existence check only (no artifact download, no ingest). The one
-deliberate side effect: `cache.inputs.runtime` / `workspaceRuntime`
+deliberate side effect: `inputs.runtime` / `workspaceRuntime`
 probe commands DO run, because predicting a key requires resolving
 them — keep runtime inputs side-effect-free.
 

package/docs/features.md

@@ -31,7 +31,7 @@ config key or an environment variable is missing here.
 - **Schedule strategy** (`--schedule`, `run.schedule`, `VX_RUN_SCHEDULE`) — pick the order with no timings: most work waiting (default), longest chain, most direct dependents, or ready order; plugins still lead. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Which task runs first?](https://vznjs.github.io/vx/blog/scheduling-strategies/#pick-the-guess)
 - **No daemon** — every run starts cold and still answers in milliseconds. [page](https://vznjs.github.io/vx/features/no-daemon/) · post: [No daemon, on purpose](https://vznjs.github.io/vx/blog/no-daemon/)
 - **Group tasks** (`dependsOn` with no `exec`) — a task that only runs its dependencies; `dependsOn: []` is a named no-op. [page](https://vznjs.github.io/vx/features/group-tasks/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
-- **Keyed groups** (`cache` with no `exec`) — a key a dependant folds: it re-runs on those inputs, and nothing spawns or counts for the group. [page](https://vznjs.github.io/vx/features/group-tasks/) · post: [A key with nothing to run](https://vznjs.github.io/vx/blog/keyed-groups/)
+- **Keyed groups** (`inputs` with no `exec`) — a key a dependant folds: it re-runs on those inputs, and nothing spawns or counts for the group. [page](https://vznjs.github.io/vx/features/group-tasks/) · post: [A key with nothing to run](https://vznjs.github.io/vx/blog/keyed-groups/)
 - **Implicit keyed `build`** — a project with no `build` gets a `^build` group keyed on its files, so source-only packages still move their dependants' keys. [page](https://vznjs.github.io/vx/features/implicit-build/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
 - **dependsOn syntax** (`^name`, `pkg#name`, `name.*`, `^name.*`) — upstream, cross-project and pattern edges; `^` follows the project edges a plugin supplies, and with none is refused naming the fix. [page](https://vznjs.github.io/vx/features/depends-on-syntax/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
 - **Every name must resolve** — `vx run lint test typecheck` refuses to start if one name matches no project. [page](https://vznjs.github.io/vx/features/names-must-resolve/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
@@ -55,7 +55,7 @@ config key or an environment variable is missing here.
 - **GitHub Actions log groups** — on Actions, each task's block folds in a `::group::` with its outcome and time. [page](https://vznjs.github.io/vx/features/actions-log-groups/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
 - **Colors** (`NO_COLOR`, `FORCE_COLOR`) — truecolor output, forced on or off by env; `TERM=dumb` prints plain, with no live region. [page](https://vznjs.github.io/vx/features/colors/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
 - **Signal-named exits** — a failure reads `exit 137, 128 + SIGKILL`. [page](https://vznjs.github.io/vx/features/signal-exits/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
-- **vx's own steps as rows** — on a terminal, what vx does around the tasks (`vx:uploads`, `<plugin>:teardown`) shows as a running row once it passes 150 ms, then a list row; never counted as a task. no post
+- **vx's own steps as rows** — on a terminal, what vx does around the tasks (`vx:uploads`, `<plugin>:teardown`) shows as a running row once it passes 150 ms, then a list row marked `internal`, only when the run waits on it (`vx:prefetch` runs beside the tasks and is listed by `vx last` alone); never counted as a task. no post
 - **Plain output off a TTY** — no live region, and a missing task lists tasks instead of opening the picker. [page](https://vznjs.github.io/vx/features/plain-off-tty/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
 
 ## Plan and explain
@@ -76,8 +76,8 @@ config key or an environment variable is missing here.
 
 ## Cache
 
-- **Opt-in, explicit inputs** (`cache.inputs.files`) — a task caches only when it names its inputs. [page](https://vznjs.github.io/vx/features/explicit-inputs/) · post: [Explicit over magical](https://vznjs.github.io/vx/blog/explicit-over-magical/)
-- **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/)
+- **Opt-in, explicit inputs** (`inputs.files`) — a task is keyed on the inputs it names, cached or not; one with none has no key, so every task behind it misses. A gitignored path named outright (`.env.local`, `dist/**`) is an input, hashed from disk and never stored; broad globs still skip ignored files. [page](https://vznjs.github.io/vx/features/explicit-inputs/) · post: [Explicit over magical](https://vznjs.github.io/vx/blog/explicit-over-magical/)
+- **Inputs** (`inputs.env`, `inputs.runtime`, `inputs.tasks`, `inputs.workspaceFiles`, `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`) — `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
@@ -86,13 +86,14 @@ config key or an environment variable is missing here.
 - **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/)
 - **Cascade through inputs** — a task's key folds its upstream input keys, never outputs. [page](https://vznjs.github.io/vx/features/cascade/) · post: [Cascade through dependencies](https://vznjs.github.io/vx/blog/cascade-through-inputs/)
 - **Lockfile-aware keys** (`@vzn/vx-lockfile`: `pnpm()`, `bun()`, `npm()`, `yarn()`) — a bump re-keys only the projects whose closure changed; each also adds every member with a `package.json` as a project named by its `name`, gives vx the project edges the lockfile records (core reads no `package.json`), keys each package's `package.json` as an input and folds its manager's install settings (`.npmrc`, `bunfig.toml`, `pnpm-workspace.yaml`, `.yarnrc.yml`) into every task. Core keys no package file, so without one an install re-keys nothing; `npm()` reads `npm-shrinkwrap.json` first, and `bun()` refuses a lone `bun.lockb`. [page](https://vznjs.github.io/vx/features/lockfile-keys/) · post: [A lockfile bump should re-key two tasks](https://vznjs.github.io/vx/blog/lockfile-aware-keys/)
-- **Upfront keys** (`run.rules.upfrontKeys`, `VX_RUN_RULES_UPFRONT_KEYS`) — refuses an input glob a same-project task's outputs could match, so every key is known before anything runs. [page](https://vznjs.github.io/vx/features/upfront-keys/) · post: [Cascade through dependencies by folding input keys, never outputs](https://vznjs.github.io/vx/blog/cascade-through-inputs/)
+- **Upfront keys** (`vx lock`, no opt-out) — refuses an input glob another task's outputs could match, so every key is known before anything runs; only a dependency the key does not fold (left out of `inputs.tasks`) may be read, its bytes hashed after it ran. [page](https://vznjs.github.io/vx/features/upfront-keys/) · post: [Cascade through dependencies by folding input keys, never outputs](https://vznjs.github.io/vx/blog/cascade-through-inputs/)
 - **Dependency rules** (`run.rules.dependencies`) — `vx lock` refuses a project depending on one a tag or name rule denies or does not allow, every broken edge named (`VX_E_DEPENDENCY_RULE`). [schema](https://vznjs.github.io/vx/schema/) · post: [Say which projects may depend on which](https://vznjs.github.io/vx/blog/dependency-rules/)
 - **Cache controls** (`--no-cache`, `--force`, `--cache-policy`, `--cache-policy`, `VX_CACHE_POLICY`, `cache.policy`) — off, re-run past it, or per-layer read/write. [page](https://vznjs.github.io/vx/features/cache-controls/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache location** (`--cache-dir`, `cache.dir`, `VX_CACHE_DIR`) — where the cache lives. [page](https://vznjs.github.io/vx/features/cache-location/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache scope** (`cache.scope`, `VX_CACHE_SCOPE`, `--cache-scope`) — a scope reads the default entries, then its own, and writes only its own. [page](https://vznjs.github.io/vx/features/cache-scope/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache pruning** (`vx cache clean`, `--older-than`, `--max-size`, `--global`, `--dry-run`, `cache.retention`, `maxSize`, `olderThan`, `VX_CACHE_RETENTION_MAX_SIZE`, `VX_CACHE_RETENTION_OLDER_THAN`) — evict by age or size, LRU; with no bound, clear this repo's store (shared by its checkouts) and run history; `--global` clears every repo's store. [page](https://vznjs.github.io/vx/features/cache-prune/) · post: [One command to know your workspace](https://vznjs.github.io/vx/blog/know-your-workspace/)
 - **Remote outputs** (`--cache-download`, `cache.download`, `VX_CACHE_DOWNLOAD`) — all, top-level only, or none. [page](https://vznjs.github.io/vx/features/remote-downloads/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
+- **Failure uploads** (`cache.upload.failures`) — which runs keep a failed task's log and outputs in the remote: CI (default), local or always. no post
 - **One store for every checkout** (`~/.vx/<id>/cache`) — clones and worktrees of a repo share cache entries. [page](https://vznjs.github.io/vx/features/shared-store/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Warm hits restore nothing** — when outputs on disk already match, a hit costs a few stats. [page](https://vznjs.github.io/vx/features/warm-hits/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Hits replay both streams** — stdout and stderr come back in the order the run printed them. [page](https://vznjs.github.io/vx/features/both-streams/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
@@ -120,7 +121,7 @@ config key or an environment variable is missing here.
 - **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/)
 - **Project-local vx** (`VX_HANDED_OFF`) — a global vx hands every call to the project's own `@vzn/vx`. [page](https://vznjs.github.io/vx/cli/#which-vx-runs)
-- **vx upgrade** (`vx upgrade`) — upgrade vx the way it was installed: a verified binary, or its package manager. Inside a project, the project's vx and the global vx that ran it move together. [page](https://vznjs.github.io/vx/features/upgrade/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
+- **vx upgrade** (`vx upgrade`) — upgrade vx the way it was installed: a verified binary, or its package manager. Inside a project, the project's vx, its `@vzn/vx-*` plugins (one install, one release) and the global vx that ran it move together; `vx upgrade -g` moves only the global. [page](https://vznjs.github.io/vx/features/upgrade/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
 - **Help and version** (`vx help`, `vx version`) — every verb's reference. [page](https://vznjs.github.io/vx/features/help-and-version/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
 - **Did-you-mean** — a mistyped flag or verb gets the nearest valid spelling. [page](https://vznjs.github.io/vx/features/did-you-mean/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Task typed as a verb** — `vx build app` answers with the exact `vx run` command that does it. [page](https://vznjs.github.io/vx/features/task-as-verb/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
@@ -144,7 +145,7 @@ config key or an environment variable is missing here.
 
 ## Adoption
 
-- **Start in a minute** (`vx init`, `--dry`, `--format json`, `--force`, `--mjs`) — write `.vx/workspace.ts`, one `vx.config.ts` per package (through `@vzn/vx-migrate`; with no `package.json`, one empty root project) and `.vx/projects.lock.json`; `--dry --format json` hands an agent the plan as data. [page](https://vznjs.github.io/vx/features/quickstart/) · post: [Hello, vx](https://vznjs.github.io/vx/blog/hello-vx/)
+- **Start in a minute** (`vx init`, `--dry`, `--format json`, `--force`, `--mjs`) — write `.vx/workspace.ts`, one `vx.config.ts` per package (through the latest `@vzn/vx-migrate`, which installs the latest `@vzn/vx` and moves every listed `@vzn/vx-*` plugin with it; with no `package.json`, one empty root project) and `.vx/projects.lock.json`; `--dry --format json` hands an agent the plan as data. [page](https://vznjs.github.io/vx/features/quickstart/) · post: [Hello, vx](https://vznjs.github.io/vx/blog/hello-vx/)
 - **Migrate from Turborepo or Nx** (`vx init`, `--native`, `--keep`, `@vzn/vx-migrate`) — native config, or keep `turbo()` / `nx()` as a start. [page](https://vznjs.github.io/vx/features/migrate/) · posts: [From Turborepo](https://vznjs.github.io/vx/blog/from-turborepo/), [From Nx](https://vznjs.github.io/vx/blog/from-nx/)
 - **Keep a Turbo or Nx remote cache** (`turboCache()`, `nxCache()`) — reuse the cache server you have. [page](https://vznjs.github.io/vx/features/keep-remote-cache/) · post: [From Nx: keep the graph, drop the platform](https://vznjs.github.io/vx/blog/from-nx/)
 - **One binary** — one file, nothing to install underneath. [page](https://vznjs.github.io/vx/features/one-binary/) · post: [One binary](https://vznjs.github.io/vx/blog/one-binary/)
@@ -174,4 +175,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/)
+- **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 without waiting for it, re-ranking the tasks not yet started when they land. Plugins keep their own entries there through `ctx.cache`. [page](https://vznjs.github.io/vx/features/critical-path/)

package/docs/patterns.md

@@ -44,7 +44,7 @@ package-manager parts come from a plugin.
 Core keys no package file (2026-10-14): the lockfile and each
 project's `package.json` key a task through `@vzn/vx-lockfile`, which
 claims the lockfile and adds `package.json` to every cached task's
-inputs, so narrow `cache.inputs.files` like `['src/**']` doesn't miss a
+inputs, so narrow `inputs.files` like `['src/**']` doesn't miss a
 `package.json` dep bump.
 
 The two **divergences** from Turbo's recipe — TypeScript-resolved