@vzn/vx 0.0.638 → 0.0.640

package/README.md

@@ -65,8 +65,8 @@ export default defineProject({
     build: {
       exec: { command: 'tsc -b' },
       dependsOn: ['^build'], // dependencies build first
+      inputs: { files: ['src/**', 'tsconfig.json'] },
       cache: {
-        inputs: { files: ['src/**', 'tsconfig.json'] },
         outputs: { files: ['dist/**'] },
       },
     },

package/docs/caching.md

@@ -8,8 +8,10 @@ invalidation_, _what's actually stored_, and _why_.
 ## Why caching is opt-in
 
 A task is cached iff its `TaskConfig` provides a `cache` block, with
-**both** `inputs.files` and `outputs.files`. Omit `cache` and the
-task always runs; no read, no write.
+`cache.outputs.files` and the task's `inputs.files`. Omit `cache` and
+the task always runs; no read, no write. `inputs` stands alone: a task
+is keyed on it whether it caches or not, and its dependents fold that
+key.
 
 The reasoning:
 
@@ -55,9 +57,9 @@ over (in order):
    `exec.remote` is dropped, because it says WHERE a task runs and not
    what it does (§ What's NOT in the key). Captures:
    - `exec` block (command, env declarations, timeout, persistent).
-   - `dependsOn` and `cache.inputs.tasks` declarations.
-   - `cache.outputs.files`, `cache.inputs.files`, `cache.inputs.env`,
-     `cache.inputs.runtime` / `workspaceRuntime` declarations (the
+   - `dependsOn` and `inputs.tasks` declarations.
+   - `cache.outputs.files`, `inputs.files`, `inputs.env`,
+     `inputs.runtime` / `workspaceRuntime` declarations (the
      strings themselves; their resolved file content / env values /
      command output contribute separately).
    - `description` (because it's part of the resolved object — even
@@ -73,14 +75,14 @@ over (in order):
    pulled deps don't see them (their cache identity stays clean) — and
    to a command: a requested default `build` runs none and folds none
    (X-119).
-5. **`cache.inputs.env` resolved values** — `[name, value]` pairs
+5. **`inputs.env` resolved values** — `[name, value]` pairs
    read from host `process.env` at hash time (delimited `name\0value`
    so boundaries are unambiguous). Listed names get their current
    values; an unset name folds its bare name, with no `\0`, so unset
    and set-to-empty are two keys (the child tells them apart:
    `passThrough` leaves an unset name out). A name holding a NUL is
    refused at load.
-6. **`cache.inputs.runtime` resolved output** — `[command, output]`
+6. **`inputs.runtime` resolved output** — `[command, output]`
    pairs, where `output` is the trimmed stdout of each command run via
    `sh -c` in the **project dir** at hash time; a command with stderr
    (or a NUL in stdout) folds `\0<stdout length>\0<stdout><stderr>`,
@@ -88,12 +90,12 @@ over (in order):
    The runtime-output analog of step 5: the command _strings_ are in
    the resolved config (step 3), their _output_ is resolved live every
    run. Folded with the command count + each `command\0output` pair.
-7. **`cache.inputs.workspaceRuntime` resolved output** — same as step
+7. **`inputs.workspaceRuntime` resolved output** — same as step
    8 but commands run at the **workspace root**, and the pairs fold
    into a **distinct namespace** (`ws-runtime-values:`) so an identical
    `(command, output)` never aliases the project-cwd `runtime` values.
 8. **Filtered upstream task cache hashes** — every upstream task's
-   own cache key, filtered by `cache.inputs.tasks` (default: all of
+   own cache key, filtered by `inputs.tasks` (default: all of
    them). Sorted by hash before folding so the ordering of `dependsOn`
    doesn't change the key. This is the cascade mechanism: if anything
    beneath you changes, your hash changes too. The set is `dependsOn`'s,
@@ -103,7 +105,7 @@ over (in order):
    whatever is on disk, which nothing proves current, so a task whose
    key folds one, and everything built on it, may hit but does not
    save (`orchestrator/excluded-keys.ts`); a task with
-   `cache.inputs.tasks: []` folds none and saves as usual.
+   `inputs.tasks: []` folds none and saves as usual.
 9. **Plugin key material** — the `{ name: value }` pairs a plugin's
    `key(task, ctx)` stage returned for this task, stored on the node as
    sorted `plugin/name` pairs and folded after the upstream keys and BEFORE the input files,
@@ -147,7 +149,7 @@ over (in order):
    [`modules/fingerprint-watch.md`](./modules/fingerprint-watch.md)).
    With nothing claimed, no root file is read or watched.
 
-10. **Input files' content hashes** — `cache.inputs.files` resolved to
+10. **Input files' content hashes** — `inputs.files` resolved to
     a concrete list of project-relative paths (gitignore-aware,
     declared-outputs-excluded, nested-projects-excluded), each file
     contributing its **git blob OID** (v20). On a clean tree the OID
@@ -216,19 +218,23 @@ add` under a clean filter (`core.autocrlf=true`, a `text` rule)
     same shape — git reports the nested repository as one changed path,
     and every project under it is selected.
 
-    A task with **no `cache` block** derives a key too — its dependents
-    fold it (step 8) — and, declaring nothing, folds **every file in
-    its project**: `**/*`, gitignore-aware, untracked files included,
-    and its own outputs not excluded, since it declared none. So its
-    key moves whenever it writes a file git does not ignore: a cached
-    dependent misses once more after the upstream's first run and hits
-    from the third. `vx why` on the dependent names the upstream as
-    the moved component; on the upstream it says the file set moved
-    and that no fingerprints say which. Ignore the outputs in git, or
-    declare the block (`tests/uncached-upstream-key.test.ts` pins both
-    arms).
-
-    Declaring nothing, such a task may also have **written** anywhere
+    A task with **no `cache` block** derives a key too, from its
+    `inputs` — its dependents fold it (step 8), as Turbo and Nx hash
+    every task. That key is for its dependents only: the task always
+    runs, and no cache, local or remote, is asked about or handed
+    anything under it; its log goes to the run's own store
+    (`run/<id>/<task>/log`). A lookup follows `cache`, never a key
+    (`tests/uncached-no-lookup.test.ts`). One that also declares no
+    `inputs` is **keyless**: no
+    key can stand for what it read, so a key that folds it is this
+    run's alone, and every task behind it misses and saves nothing.
+    A task reading `**` with no `cache` folds its own outputs too,
+    since it declared none: its key moves whenever it writes a file
+    git does not ignore, so a cached dependent misses once more after
+    the upstream's first run. Ignore the outputs in git, narrow its
+    `inputs`, or declare the block (`tests/uncached-upstream-key.test.ts`).
+
+    Declaring no outputs, such a task may also have **written** anywhere
     in its project, so what the run learned about that project at its
     start — the git listing and the index OIDs — is dropped once its command exits, pass or fail, and a later key
     re-lists and hashes by content. For the same reason a task after it
@@ -260,20 +266,19 @@ add` under a clean filter (`core.autocrlf=true`, a `text` rule)
     dropping out of the key or the artifact without a word
     (turborepo#9345). Rename it, or exclude it with a negated glob.
 
-    Your globs are a **filter over the set git reports**, so a filter
-    can only ever remove — a gitignored file can never be filtered back
-    in, however explicitly you name it. Naming one by hand is therefore
-    a **hard error** rather than a silent nothing: it would leave the
-    task ignoring a file its own config claims as an input, reporting
-    `up-to-date` while that file changed. Turbo lets an explicit entry
-    override gitignore; vx cannot, because the key would then depend on
-    a change `git diff` cannot see and `--affected` would stop selecting
-    the task. If the file is generated, depend on the task that produces
-    it via `cache.inputs.tasks`. A **glob** matching nothing stays
-    silent — that is legitimate — and so does a literal naming a file
-    that does not exist. A literal naming a **directory** is judged the
-    same way: an ignored one, or an empty one, has no file git lists
-    under it, folds nothing, and is refused (item 576).
+    Your globs are a **filter over the set git reports**, so a broad
+    glob never reaches a gitignored file. An entry that names one
+    outright does: a literal (`.env.local`, `gen`), or a glob whose fixed
+    prefix git ignores (`dist/**`), walked on disk under that prefix
+    only (owner, 2026-10-16). Such a file is hashed from disk with the
+    blob formula an untracked file gets, and is never stored or
+    restored. `--affected` reflects only what git sees, so an edit to
+    one never selects a task on its own (as in Nx); `vx watch` re-runs
+    it on an edit there.
+    A **glob** matching nothing stays silent, and so does a literal
+    naming a path that does not exist, until it does. An ignored
+    directory named outright folds every file under it; an empty one
+    folds nothing.
 
     A **bracket is literal** in a task glob, and there are no character
     classes (item 667): `app/[id]/**` folds the route directory
@@ -315,7 +320,15 @@ add` under a clean filter (`core.autocrlf=true`, a `text` rule)
     second by two, since FAT32 keeps even seconds; a rewrite later in
     the same stamp keeps it (`racyWindowMs`; until 2026-09-27, A-2 and
     A-38, such a rewrite of the same size was a hit on the first bytes'
-    output). That is the same value the index holds whenever no filter applies,
+    output). Every such window compares a file's stamp, on its file
+    system's clock, with a moment vx read from its own, so a run first
+    measures how far the file system runs behind (one file written and
+    removed in the cache dir) and widens every window by a lag past the
+    kernel's tick (20 ms): a WSL2 VM drifted from the Windows host that
+    stamps `/mnt/c`, a Docker Desktop bind mount or an NFS server dated an
+    edit made while a command ran before the command, and the entry
+    filed the edit's output under the old bytes' key (until 2026-10-16).
+    That is the same value the index holds whenever no filter applies,
     so a file's contribution doesn't flip across dirty↔clean
     transitions. Folded as `(relPath, identity)` pairs, sorted for
     stability across OSes and walk orders. The identity is the OID
@@ -330,19 +343,21 @@ add` under a clean filter (`core.autocrlf=true`, a `text` rule)
     there a clean file's mode comes from an lstat too, and its OID
     from the index (item 1076).
 
-    A **symlink** folds as git folds it: the blob of its target
-    _string_ (its mode-120000 index OID), whether it points at a file,
-    a directory, or nothing. Retargeting a link changes the key; the
-    bytes behind a link to a directory, or to a file outside the
-    project, do not — `git diff` and `--affected` cannot see them
-    either, so declare them with `workspaceFiles`. A link to a file
-    inside the project tracks that file's content only when the file
-    matches the task's input globs too: it is then an input of its own.
-    A link under `src/**` to `other/data.txt` folds the link, not
-    `other/data.txt`; name the target in the globs to track it.
-    (Before 2026-09-09 a file link folded the
-    bytes behind it and a directory or dangling link fell out of the
-    input set entirely, so retargeting one was a stale hit.)
+    A **symlink** folds as git folds it, the blob of its target
+    _string_ (its mode-120000 index OID), and then the content behind
+    it, as Nx reads a linked file where it points: a file's identity, or
+    for a directory every file beneath it at any depth, tracked or not
+    (`.git`, `node_modules`, `.vx/cache` and `.yarn/cache` aside, as Nx's walker skips them), a link
+    among them followed in turn. The target may be anywhere: in the
+    project, elsewhere in the workspace, outside it. Retargeting a link
+    changes the key, to equal bytes too; an edit behind it changes the
+    key. A dangling link, or a loop of links, keys its target string
+    alone. `--affected` selects a link whose target changed (a file
+    the diff names, or one under a linked directory) as a changed path of
+    its project, and a target git cannot diff (outside the workspace,
+    git-ignored) on every run; `vx watch` arms each link's target and
+    names the link when it changes (`linked-inputs.ts`). Nx does not
+    enter a linked directory; vx does, since the task reads it.
 
 The composition is seed-chained (`xxh3(part, prevDigest)`) with a
 label prefix per field, so two different field layouts can't collide.
@@ -452,9 +467,20 @@ root-anchored output can land in any project's directory — and every
 transitive dependant of one with it (their up-front keys fold a
 preliminary key); a glob with no literal prefix reaches every project.
 Before item 584 one such declaration emptied the tier graph-wide.
-`rules.upfrontKeys` (on by default, X-54) refuses at load a task whose
-input globs can match another task's declared outputs, so the clauses
-on declared outputs fire only with the rule off; undeclared writes, an
+`vx lock` refuses a task whose input globs can match another task's
+declared outputs (X-54, no opt-out), unless git ignores those outputs
+whole (and the entry does not start inside them) or the producer is a
+dependency its key does not fold, whose bytes it then hashes after the
+producer ran, so the clauses on declared outputs fire only for such a
+dependency read or a pair the check cannot decide. An output git ignores whole is no reach either:
+a key reads only what git lists, so a `**/*` reader beside a gitignored
+`**/dist/**` producer keys up front, the same key before and after the
+build. The run asks git once, beside its walk and only when a reader
+reaches a same-project output: one `git check-ignore` over each such
+output's directory (`dist/`, and a fresh `__vx_probe__/dist/` for a
+glob that starts with `**`), and the walk's listing must hold no file
+the glob matches (a tracked output, a directory a `!` rule takes back);
+anything git cannot answer keeps the key late. Undeclared writes, an
 `outputs.workspaceFiles` producer upstream, a rewriter the key does not
 fold, and runtime probes after a writer still leave a key preliminary.
 The
@@ -541,9 +567,8 @@ Hard invariants of the remote prefetch:
   stat pass.
 - **Stable keys only.** A task with a _preliminary_ key (§ Local
   restore tier's stability gate: undeclared writes, an
-  `outputs.workspaceFiles` producer upstream, or, with
-  `rules.upfrontKeys: false`, input globs that match an upstream's
-  declared outputs) is not prefetched: its key would name the wrong
+  `outputs.workspaceFiles` producer upstream, or input globs that match
+  the outputs of a dependency the key does not fold) is not prefetched: its key would name the wrong
   artifact, and it resolves via the lazy read-through in `execute-task`. Instability propagates: a task that folds an
   unstable upstream is itself unstable. When in doubt, skip.
 - **At most once.** The `LayeredCache` keeps an in-flight map keyed by
@@ -553,7 +578,24 @@ Hard invariants of the remote prefetch:
   later `get` finds it as a now-local hit — still reports
   `source: 'remote'`, so the outcome is `cache-hit-remote`.
 - **A remote-read-off policy** (`--no-cache`, `--force`, or
-  `--cache-policy=remote:`) fires no prefetch.
+  `--cache-policy=remote:`) fires no prefetch. With remote writes on
+  (`--force`), the same up-front keys go to one `hasMany` per remote
+  the run writes but does not read and that can batch, in the
+  background: no task waits for it, only each upload does. An upload
+  of a key that remote holds is skipped (an entry is immutable) and is
+  counted nowhere. A key the probe did not cover, or a remote with no
+  `hasMany`, asks `has` for that key inside its upload job; a probe
+  that fails uploads, as before.
+- **No `has` before a `put`.** An entry is immutable: a remote's `put`
+  of a key it holds keeps the stored bytes, and a wire that would
+  overwrite checks inside (`turboCache()` asks HEAD unless a 404 or a
+  batch answer this run said the key is absent; `reapi()` looks the
+  action up beside its upload and keeps a stored result; Nx servers
+  answer 409). `ctx.cache.put` and a run's own entries send the `put`
+  alone.
+- **`--dry` batches too.** The plan derives every key first, then asks
+  each remote with `hasMany` once; a remote without it is asked `has`
+  per key.
 - **Never fail.** Every remote path (get / put / ingest / prefetch)
   catches all errors and degrades to a cache miss. A remote 500, a
   network drop, a corrupt artifact, or a failed integrity check can
@@ -573,16 +615,16 @@ fire-and-forget background upload**. The task's outcome (and its
 dependents) never wait on upload latency — the uploads race alongside
 the rest of the run and are drained before `cache.close()`, so a
 short run still ships every artifact before the process exits. Upload
-failures log via `onRemoteError` and are otherwise ignored (the task
+failures are warned once per failure class and are otherwise ignored (the task
 already succeeded; the only loss is the remote entry).
 
 An upload is the outputs as the task wrote them; secret masking does
 not reach file contents, so a task whose outputs embed a secret is one
 to leave uncached ([security](./security.md)).
 
-### Planning probes (`--dry` / `--graph`)
+### Planning probes (`--dry`)
 
-The planning paths (`vx run --dry`, `--graph`) predict hits without
+The planning path (`vx run --dry`) predicts hits without
 side effects: against a remote cache they use a **lightweight
 existence probe** — no artifact download, no local ingest. A predicted
 `hit-remote` means the artifact exists remotely; the bytes move only
@@ -602,12 +644,14 @@ get/save and the file-hash memo's writes (never `recordRun` / `stats` / `prune`
 read-through (`remoteRead`), upload (`remoteWrite`), and prefetch
 (`remoteRead`). The orchestrator derives two booleans per task:
 
-- `willRead = task has a cache block AND it is not remote-only AND (localRead || remoteRead)`
+- `willRead = task has a cache block AND it is not remote-only AND it folds no keyless task AND (localRead || remoteRead)`
 - `willWrite = task has a cache block AND it is not remote-only AND (localWrite || remoteWrite)`
 
 A task reads the cache only when `willRead`, saves only when
-`willWrite`, and cleans its declared outputs before exec only when
-`willWrite`. Remote-only is an `exec.remote: 'only'` task placed on a
+`willWrite` and it folds no keyless task, and cleans its declared outputs
+before exec only when `willWrite`. A keyless task runs a command and
+declares no `inputs`: its key is unknown, so a task that folds it
+(through `dependsOn`, directly or through a group) always misses. Remote-only is an `exec.remote: 'only'` task placed on a
 remote executor: it never touches this machine's disk (no probe, no
 restore, no output clean, no local save), and its result lives in the
 remote executor's own store.
@@ -615,8 +659,8 @@ remote executor's own store.
 The CLI maps three flags to a policy (precedence: start all-on → apply
 `--cache-policy` → `--no-cache` forces all off → `--force` forces both reads
 off): `--no-cache` = everything off (no read, no write, no output
-clean); `--force` = reads off / writes on (re-execute and refresh the
-cache, outputs cleaned); `--cache-policy=<spec>` = explicit per-layer control.
+clean); `--force` = reads off / writes on (re-execute, outputs cleaned;
+a key already stored, locally or in a remote, is kept as it is); `--cache-policy=<spec>` = explicit per-layer control.
 Off CI, unless a spec names the remote, `remoteWrite` starts off: a key
 holds only declared inputs, so a laptop's undeclared tool or file could
 replay on CI. See `docs/cli.md` § Cache control.
@@ -665,7 +709,10 @@ is on):
    Until 2026-09-27 (A-3) the rename came first, and a commit refused
    past the busy timeout left the new bytes beside the old rows: every
    later hit on the key failed the task as a corrupt artifact.
-   A re-save (`--force`) first moves the previous artifact aside under
+   A `--force` save of a key the index already holds is skipped, so
+   `--force` rewrites nothing. A re-save (a key dropped as corrupt, or
+   two writers that both found it absent) first moves the previous
+   artifact aside under
    a temp name and unlinks it after the commit: ext4 flushes the
    incoming file when a rename replaces one, 0.55 ms a save on the main
    thread against 0.04 (a forced 1,000-task run 4.01 s → 3.46 s,
@@ -755,7 +802,7 @@ from the snapshot's index OID for an output (or for an input the task
 rewrote) restored the bytes from before the command.
 
 A declared set that resolves to **nothing** is said on the run's
-status line. `cache.inputs matched no files (lib/**)` — the key would
+status line. `inputs matched no files (lib/**)` — the key would
 not change when the source does — is said on every miss of a cacheable
 task, right after `describeTaskInputs` and before the command, whether
 or not it saves. `cache.outputs matched no files (build/**)` — an empty
@@ -919,13 +966,13 @@ A task's cache becomes invalid when any of these change:
 | Any package manager updates a lockfile (`pnpm`, `npm`, `yarn`, `bun`)                                                                    | step 9 — the `key` material of the plugin that claims it (`@vzn/vx-lockfile`: only the projects whose dependency closure moved); **NOT a trigger** with no such plugin, since core keys no package file |
 | Edit an install setting (`.npmrc`, `bunfig.toml`, `pnpm-workspace.yaml`, `.yarnrc.yml`)                                                  | step 9 — the claiming lockfile plugin folds it whole into every task; **NOT a trigger** without one                                                                                                     |
 | Edit `package.json`'s `workspaces` field                                                                                                 | membership: a project that joins or leaves changes which projects exist and which nested dirs its parent's globs exclude (step 10)                                                                      |
-| Edit the project's `package.json` (dep / version / scripts change)                                                                       | step 10 — an input file of every cached task when `@vzn/vx-lockfile` is declared (it adds `package.json` to `cache.inputs.files`), or when a task lists it; **NOT a trigger** otherwise                 |
+| Edit the project's `package.json` (dep / version / scripts change)                                                                       | step 10 — an input file of every cached task when `@vzn/vx-lockfile` is declared (it adds `package.json` to `inputs.files`), or when a task lists it; **NOT a trigger** otherwise                       |
 | Edit the task's `vx.config.ts`                                                                                                           | step 3 (task config hash)                                                                                                                                                                               |
 | Edit a config file that the task config imports                                                                                          | step 3 (configHash sees the resolved object after Bun evaluates imports)                                                                                                                                |
 | Change CLI `forwardArgs` (after `--`)                                                                                                    | step 4                                                                                                                                                                                                  |
-| Change a `cache.inputs.env` host value                                                                                                   | step 5                                                                                                                                                                                                  |
-| Change the combined stdout+stderr of a `cache.inputs.runtime` command (resolved at hash time)                                            | step 6                                                                                                                                                                                                  |
-| Change the combined stdout+stderr of a `cache.inputs.workspaceRuntime` command (resolved at hash time)                                   | step 7                                                                                                                                                                                                  |
+| Change a `inputs.env` host value                                                                                                         | step 5                                                                                                                                                                                                  |
+| Change the combined stdout+stderr of a `inputs.runtime` command (resolved at hash time)                                                  | step 6                                                                                                                                                                                                  |
+| Change the combined stdout+stderr of a `inputs.workspaceRuntime` command (resolved at hash time)                                         | step 7                                                                                                                                                                                                  |
 | Upstream task's cache key changes (because its inputs changed)                                                                           | step 8                                                                                                                                                                                                  |
 | Bump `CACHE_VERSION`                                                                                                                     | step 1 — orphans every entry                                                                                                                                                                            |
 | Change `exec.env.passThrough` _values_ alone                                                                                             | **NOT a trigger** by design — passThrough values are host-specific                                                                                                                                      |
@@ -939,7 +986,7 @@ re-runs automatically.
 
 ## Cross-project boundaries
 
-A project's `cache.inputs.files` globs **never** reach into another
+A project's `inputs.files` globs **never** reach into another
 project's directory, even if a `**/*` pattern would otherwise match.
 
 `workspace/nested-dirs.ts` computes the set of nested project
@@ -956,21 +1003,22 @@ globs is `dependsOn` + upstream-hash propagation (step 8).
 For a task with `exec.sandbox` and `cache`, the sandbox enforces that
 "only". A workspace package reached through a `node_modules` link is
 granted only when the task's key folds a task of that package, walking
-the same selection `cache.inputs.tasks` applies at hash time
-(`orchestrator/keyed-projects.ts`, over `upstream.ts`'s
+the same selection `inputs.tasks` applies at hash time
+(`orchestrator/keyed-projects.ts`, over `graph/folds.ts`'s
 `selectFoldedDeps`); every other link target inside the root is
 withheld, so an import of a sibling the key never sees fails and is
 reported instead of caching a result an edit there would not re-run.
-Any exec task counts, cached or not: a task with no `cache` declares no
-`inputs.files`, so its key folds every file of its project. A persistent
-task counts the same way: its key folds its whole project, so a cached
-e2e behind a dev server re-runs when the server's sources change.
+Any exec task counts, cached or not: its key folds its project's files
+through its `inputs`, and one with no `inputs` is keyless, so a key that
+folds it is never stored or read. A persistent task counts the same way,
+so a cached e2e behind a dev server keyed on its sources re-runs when
+they change.
 The coverage is per package, not per file: an edge to `ui#source`
 (inputs `src/**`) also admits a read of `ui/README.md`, whose edit moves
 no key — the same limit a grant wider than a task's own inputs already
 has. A task with no `cache` keeps every link, having no key to be stale.
 
-**Exception:** `cache.inputs.workspaceFiles` /
+**Exception:** `inputs.workspaceFiles` /
 `cache.outputs.workspaceFiles` are workspace-root-anchored and apply
 NO boundary rule — a deliberate escape hatch (owner call: "they don't
 care about boundaries; it is bad practice but is there"). Prefer
@@ -1032,8 +1080,8 @@ the gate exists to avoid paying needlessly.
 
 ## Runtime inputs and the lock (the env parallel)
 
-`cache.inputs.runtime` / `cache.inputs.workspaceRuntime` are modeled
-exactly on `cache.inputs.env`, and they share its asymmetry with the
+`inputs.runtime` / `inputs.workspaceRuntime` are modeled
+exactly on `inputs.env`, and they share its asymmetry with the
 lockfile:
 
 - **The command _strings_ live in the resolved config**, so `vx lock`
@@ -1185,7 +1233,7 @@ by this user, or point cacheDir / --cache-dir at one that is.` (A-40).
 An input the key must hash that this user cannot read fails its task
 naming the read: `<path> is not readable by this user (EACCES), and vx
 reads it to derive a cache key. Make it readable, or, for a task input,
-take it out of cache.inputs.files.` (A-50).
+take it out of inputs.files.` (A-50).
 
 By default the entries and their artifacts live in a **shared store**
 in `~/.vx/<id>/cache`, and each workspace keeps only its own index in
@@ -1470,7 +1518,7 @@ 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 = 'v38', in cache.ts)
+-- src/cache/schema.ts (SCHEMA_VERSION = 'v40', in cache.ts)
 -- With a shared store, entries, entry_stdout, output_files, entry_inputs,
 -- 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.
@@ -1527,7 +1575,8 @@ CREATE TABLE runs (
   timed_out           INTEGER,          -- 1 when vx's own timeout killed it
   sandbox_violations  INTEGER,          -- the sandbox's violation count
   not_ready           TEXT,             -- 'timeout' | 'exited' | 'spawn' (persistent task)
-  restored            INTEGER           -- v31, on a hit: 1 = outputs restored, 0 = up to date
+  restored            INTEGER,          -- v31, on a hit: 1 = outputs restored, 0 = up to date
+  remote_error        TEXT              -- v40: each remote read or write of the key that failed
 );
 
 -- Two indexes, both append-only under a run's inserts: every row of a run
@@ -1628,7 +1677,7 @@ CREATE TABLE output_dirs (
 
 -- v22 (Tier 3): one header row per `vx run` invocation. The `runs`
 -- table is per-task; this is the per-invocation record carrying the
--- command, git/CI/host context, tags, and run-level counts. Recorded
+-- command, git/CI/host context, and run-level counts. Recorded
 -- atomically alongside `runs` via recordRunBundle (one transaction).
 CREATE TABLE invocations (
   run_id            TEXT PRIMARY KEY,         -- UUIDv7, == runs.run_id
@@ -1657,8 +1706,7 @@ CREATE TABLE invocations (
   host              TEXT,                     -- os.hostname()
   os                TEXT,                     -- process.platform
   arch              TEXT,                     -- process.arch
-  vx_version        TEXT NOT NULL,
-  tags              TEXT NOT NULL DEFAULT '{}' -- JSON object {k:v} from --tag
+  vx_version        TEXT NOT NULL
 );
 CREATE INDEX invocations_started ON invocations(started_at);
 CREATE INDEX invocations_branch  ON invocations(branch);
@@ -1821,10 +1869,19 @@ moat.
   passthrough still bumps the key for affected tasks.
 - **Files outside the project directory that aren't declared.**
   Workspace-root configs (`tsconfig.base.json`, etc.) are not
-  auto-included — declare them via `cache.inputs.workspaceFiles`
+  auto-included — declare them via `inputs.workspaceFiles`
   (root-anchored globs).
+- **Gitignored files no entry names.** Vite and Next load `.env.local`
+  on their own; a broad glob skips it, so editing it replays the old
+  build. Name it: `files: ['src/**', '.env.local']`. Its bytes are
+  hashed, never stored, and a missing file is simply not an input.
+  Machines with different files compute different keys, so they miss
+  each other's shared entries. `--affected` ignores it (only what git
+  sees selects a task), and `vx watch` re-runs on its edit. A probe
+  (`runtime: ['cat .env.local 2>/dev/null | cksum']`) still works where
+  a command, not a path, decides what to read.
 - **Node / Bun / OS / build-tool versions — unless you declare them.**
-  The canonical mechanism is `cache.inputs.runtime` /
+  The canonical mechanism is `inputs.runtime` /
   `workspaceRuntime` (e.g. `workspaceRuntime: ['node -v']`): the
   command output is resolved live at hash time, so it stays correct
   under the lock. Avoid baking versions via
@@ -2141,7 +2198,7 @@ breaking footer).
   migration), so this costs one cold rebuild.
 - **SCHEMA v21 → v22 (no `CACHE_VERSION` bump)**: Tier-3 dashboard
   tables — `invocations` (one header row per `vx run` with command,
-  git/CI/host context, tags, and run-level counts, recorded with `runs`
+  git/CI/host context, and run-level counts, recorded with `runs`
   via `Cache.recordRunBundle`) and `entry_inputs` (one row per cache-key
   component, keyed by the cache-ENTRY hash — the input-fingerprint
   moat). `entry_inputs` is written **inside the entry-save transaction,
@@ -2158,11 +2215,11 @@ breaking footer).
   committed, so git enumerates it, but it's vx's own frozen-config
   metadata — never a task input. Without this, a `vx lock` re-write
   busts every key on a project that globs the root lockfile (a broad
-  `**/*` on the root project). Tasks whose `cache.inputs.files` never
+  `**/*` on the root project). Tasks whose `inputs.files` never
   matched it derive byte-identical keys. No SCHEMA bump — only the
   hashed file set changed, not the key layout or on-disk format.
 
-- **v22 → v23**: fold `cache.inputs.runtime` / `workspaceRuntime`
+- **v22 → v23**: fold `inputs.runtime` / `workspaceRuntime`
   command output into the key (two namespaced sections after
   env-values). The command _strings_ stay in the config hash (step 3);
   their combined trimmed stdout+stderr is resolved live at hash time
@@ -2207,7 +2264,7 @@ breaking footer).
 - **v11 → v12** (PR #42): project's `package.json` bytes folded into
   every task's cache key implicitly. Matches Turbo / Nx "implicit
   dependencies" behavior — a `package.json` dep change invalidates
-  the project's tasks even when `cache.inputs.files` is narrow and
+  the project's tasks even when `inputs.files` is narrow and
   doesn't cover the file.
 - **v12 → v13** (PR #65): per-entry on-disk layout unified. Outputs
   moved from `<hash>/<rel>` (mixed with metadata) to