@vzn/vx 0.0.639 → 0.0.641

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.
@@ -384,12 +399,26 @@ On a hit:
    clock (4 ms at HZ=250), so a same-size rewrite inside the tick of
    vx's own write, in place or as a new file that took the same inode,
    with its mtime forged back, still matches.
-3. Otherwise the task's declared outputs are wiped from the project
-   dir (`cleanOutputs`) — see
-   [§ Strict output ownership](#strict-output-ownership) — and the
-   `outputs/<rel>` (+ `workspace-outputs/<rel>`) entries are extracted
-   from the artifact into place: its bytes inline in the index, read in
-   one read transaction with the entry's rows, or `<cacheDir>/<hash>.tar.zst`.
+3. Otherwise the `outputs/<rel>` (+ `workspace-outputs/<rel>`) entries
+   are extracted from the artifact (its bytes inline in the index, read
+   in one read transaction with the entry's rows, or
+   `<cacheDir>/<hash>.tar.zst`) **in place**: every entry is staged in
+   the workspace's `.vx/tmp/` (never an output folder), and only once the
+   whole archive has staged is each renamed over the file it replaces. A
+   file that already holds the entry's bytes (compared byte for byte, up
+   to 4 MiB) is left in place, only its mode and mtime set. A
+   target on another filesystem goes through a temp beside it; a file
+   takes the group its directory gives new files (setgid on Linux, any
+   directory on macOS), ACLs are not copied. The next run removes
+   the staging a killed run left. A process reading the output tree during the
+   restore never finds a declared output missing or half-written, and a
+   restore that fails first (a full disk, a damaged entry) leaves the
+   outputs as they were. Then the declared outputs the entry does not
+   hold are removed — see
+   [§ Strict output ownership](#strict-output-ownership). Only a found
+   output that blocks a rename (a file where the entry needs a directory,
+   or the reverse) goes before. Turbo also restores in place; Nx deletes
+   and copies each file, and a reader meets a missing or short file.
 4. Captured stdout is replayed to the live terminal via the logger —
    the framed block looks like a fresh run. (stderr is not cached —
    only successful runs are cached and their stderr is near-always
@@ -452,10 +481,12 @@ 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, unless git
-ignores those outputs whole, so the clauses on declared outputs fire
-only with the rule off. An output git ignores whole is no reach either:
+`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
@@ -466,10 +497,11 @@ 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
-short-circuit never runs under a `LayeredCache` (remote prefetch owns
-those runs — an up-front `get` there would put remote GETs on the
-critical path), never fires with local reads off or on a local cache
+With a
+remote declared the short-circuit probes the local store alone, so a
+local hit still restores ahead of its dependencies and no remote GET
+sits on the critical path (remote prefetch asks the remote for the
+rest). It never fires with local reads off or on a local cache
 that holds no artifact (`Cache.holdsNothing`: every probe would miss,
 and a cold 1,090-package run started its first task ~90 ms sooner
 without it), and never throws —
@@ -550,9 +582,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
@@ -628,12 +659,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.
@@ -784,7 +817,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
@@ -804,7 +837,7 @@ the run (`tests/runner.test.ts`) — and the save resolves the output
 globs at once. A descendant the command detached (`setsid … &`, a
 daemon) that writes after that is not in the artifact: the entry saves
 what was there, often nothing (with the `cache.outputs matched no
-files` line), and the next hit's clean-before-restore removes what the
+files` line), and the next hit's restore removes what the
 descendant wrote and restores the saved entry in its place (upstream
 survey, turborepo#12786). vx does not wait for it and cannot see it: a
 process that left the task's session is outside the process group vx
@@ -831,14 +864,15 @@ Declared `cache.outputs.files` are wiped in two distinct places:
 - **Before exec on a cache miss.** A leftover `dist/old.js` from a
   prior build can't survive into a fresh build that doesn't rewrite
   it.
-- **Before restore on a cache hit.** The post-restore tree is the
-  cached snapshot byte-for-byte. Hand-edits to output files don't
-  persist through a cache replay. When the hit's own check walked the
-  output globs to find the tree stale, the clean deletes from that walk's
-  list instead of walking again: nothing is awaited between them (X-161).
-
-Both branches use the same `cleanOutputs` helper (`src/cache/inputs.ts`)
-with the same boundary rules, and vx's own paths stay off the wipe
+- **After restore on a cache hit.** The post-restore tree is the
+  cached snapshot byte-for-byte: the restore renames the entry's files
+  over the ones it finds, then removes what the entry does not hold.
+  Hand-edits to output files don't persist through a cache replay. When
+  the hit's own check walked the output globs to find the tree stale,
+  the removal uses that walk's list instead of walking again (X-161).
+
+Both use the same helpers (`cleanOutputs`, `cleanOutputPaths` in
+`src/cache/inputs.ts`) with the same boundary rules, and vx's own paths stay off the wipe
 whatever the glob: `.git`, `.vx` and each `vx.lock.json` (`OUTPUT_NEVER`;
 `.vx` holds the workspace config and the lock, which a clean deleted and a
 hit restored stale while `.vx/cache` alone was listed). `node_modules` is
@@ -871,7 +905,7 @@ Skipped when:
   `.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.
+  usual; a hit's restore still removes what its entry does not hold.
 
 A declared output the process cannot remove (a `dist/` another user
 wrote, a read-only checkout) fails the task with `cannot remove declared
@@ -948,13 +982,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                                                                                                                                      |
@@ -968,7 +1002,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
@@ -985,21 +1019,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
@@ -1061,8 +1096,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`
@@ -1214,7 +1249,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
@@ -1314,8 +1349,9 @@ pax `path`/`size`, GNU long names, header checksums, truncation; an
 extended header (read whole) past 1 MiB or a pax `size` that is not a
 whole number is refused as corrupt, since a 1 GiB pax header costs 2 GiB
 of memory from a ~32 KB artifact — and
-every regular entry is written beside its target as a short `.vx-tmp-*` sibling (never a suffix on the target's name, which pushed a legal 242–255-byte name past NAME_MAX) and
-renamed into place only after the whole archive has ended cleanly and
+every regular entry is written to the workspace's `.vx/tmp/<pid>-0/`
+(vx's own, ignored by git, never an output folder) and renamed over its
+target only after the whole archive has ended cleanly and
 the index's recorded outputs are all present. vx itself holds one
 chunk of the tar at a time (measured 2026-09-03, incompressible
 artifacts, fresh process: 150 MiB peaked at +644 MiB through
@@ -1394,7 +1430,14 @@ them, `CacheGetContext.outputs`), and never when it holds one path as a
 file and a directory at once. Either used to reach the tree, an input
 overwritten or a `.git/hooks` file planted under a green
 `cache-hit-remote`, or a restore that failed every later run from the
-local copy (item 942); now the read is a miss and the task runs. On the save side a
+local copy (item 942); now the read is a miss and the task runs. Every
+restore asks the same of the local copy, whatever route it reached the
+store by: an entry outside the declared outputs, one a `!` entry takes
+back, one under `.git`, `.vx` or a `vx.lock.json`, or one under a
+`node_modules` no output glob names fails the whole restore before
+anything is written; the entry is dropped and the task runs. Remote
+execution (`@vzn/vx-reapi`) writes a remote action's outputs through the
+same gate (`restorableOutput`). On the save side a
 **symlinked output** is captured as its target's bytes and comes back
 as a regular file (a hit that finds the task's own link still current
 leaves it); a link to a directory, or a dangling one, has no bytes to
@@ -1850,10 +1893,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
@@ -2187,11 +2239,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
@@ -2236,7 +2288,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