@vzn/vx 0.0.640 → 0.0.641

package/src/cache/inputs.ts

@@ -27,6 +27,8 @@ import {
   isInstalledPath,
   isLiteralPattern,
   normalizeGlob,
+  namesNodeModules,
+  OUTPUT_NEVER,
   outputMatcher,
   realpathOf,
   relPosix,
@@ -89,21 +91,8 @@ const ALWAYS_IGNORE = [
   // must not select every `**` reader under --affected.
   '**/.vx/.gitattributes',
   '**/.vx/.gitignore',
-  // `bun build --compile` writes a transient `.<hash>-<n>.bun-build` intermediate
-  // in the cwd. It never rests on disk, so it can't be a real input — but a
-  // broad `inputs.files: ['**/*']` on a compile task would try to hash the temp
-  // file that a CONCURRENT compile is mid-write, racing to EACCES/ENOENT. Always
-  // exclude it (vx is Bun-native; compiling standalone binaries is a common task).
-  '**/*.bun-build',
-  // …and, cross-compiling for a target its cache lacks, the directory it
-  // extracts the downloaded runtime into, `<cwd>/.<16 hex>-<8 hex>.tmp/`,
-  // 60 MB mid-write under the same race (2026-09-29).
-  '**/.????????????????-????????.tmp/**',
-  // vx's own restore temp (archive.ts), live only while an artifact lands
-  // beside its target. A key taken meanwhile listed it, the rename removed
-  // it, and every task reading that directory was withheld its save
-  // (withastro/astro: 25 of 33 builds re-ran on a restore, X-209).
-  '**/.vx-tmp-*',
+  // Where restores stage (archive.ts): vx's own, never an input.
+  '**/.vx/tmp/**',
 ]
 
 const DEFAULT_FILE_GLOBS: readonly string[] = ['**/*']
@@ -677,17 +666,6 @@ async function resolveRuntimeValues(
   )
 }
 
-/**
- * What no output glob reaches. An output is otherwise taken as written —
- * `node_modules/**` IS an install task's output, so `ALWAYS_IGNORE` does not
- * apply here — but no task produces these, and a root project declaring
- * `**` would otherwise wipe its repository and the cache it is restoring
- * from (2026-09-16). `.vx` whole and each `vx.lock.json` are vx's own: as
- * outputs, the clean deleted an uncommitted workspace config and a hit
- * restored a lock or ignore file the key does not see over the current one.
- */
-const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**', '**/vx.lock.json']
-
 /**
  * What a set of output globs may not reach: `OUTPUT_NEVER`, and every
  * `node_modules` unless a glob names one. `**\/*.js` meant the build's
@@ -697,8 +675,9 @@ const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**', '**/vx.lock.json']
  * even `.git`.
  */
 function outputExcludes(outputs: readonly string[]): Bun.Glob[] {
-  const namesNodeModules = outputs.some((o) => normalizeGlob(o).split('/').includes('node_modules'))
-  return (namesNodeModules ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**']).map(globFor)
+  return (namesNodeModules(outputs) ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**']).map(
+    globFor,
+  )
 }
 
 /**
@@ -877,6 +856,7 @@ export async function cleanOutputs(args: {
   resolved?: readonly string[] | undefined
 }): Promise<string[]> {
   const committed = args.committed ?? committedFiles(undefined, args.projectDir)
+  sweepRestoreTemps(args.projectDir, args.outputs)
   const matched = args.resolved ?? (await resolveOutputs(args))
   // `force: true` makes rm tolerate ENOENT (e.g. when two output
   // globs overlap and a sibling already deleted a path mid-iteration).
@@ -892,6 +872,70 @@ export async function cleanOutputs(args: {
   return matched.map((f) => relPosix(args.projectDir, f))
 }
 
+/**
+ * Remove the restore temps (`.vx-tmp-<pid>-<n>`, archive.ts) a killed run
+ * left beside an exact-file output. A restore stages in `.vx/tmp/` and
+ * writes one beside its target only where the target is on another
+ * filesystem (EXDEV); a glob over the directory takes it with the outputs,
+ * but `out/a.txt` reaches no sibling, and a partial temp stayed in `out/`
+ * through every later run (Growth's SIGKILL probe, 2026-10-16). A temp
+ * whose writer is alive, this process included, is left: it may be
+ * mid-restore.
+ */
+export function sweepRestoreTemps(base: string, outputs: readonly string[]): void {
+  const dirs = new Set<string>()
+  for (const g of outputs) {
+    if (g.startsWith('!') || !isLiteralPattern(g)) continue
+    dirs.add(path.dirname(path.resolve(base, stripTrailingSlash(normalizeGlob(g)))))
+  }
+  for (const dir of dirs) {
+    let names: string[]
+    try {
+      names = readdirSync(dir)
+    } catch {
+      continue
+    }
+    for (const name of names) {
+      const m = /^\.vx-tmp-([0-9a-z]+)-[0-9a-z]+$/.exec(name)
+      if (m === null) continue
+      const pid = Number.parseInt(m[1]!, 36)
+      if (pid === process.pid || writerAlive(pid)) continue
+      rmSync(path.join(dir, name), { force: true })
+    }
+  }
+}
+
+/**
+ * Empty `.vx/tmp/` (archive.ts `STAGING`) of the staging directories
+ * (`<pid>-<n>`) a killed run left, once per run. One whose writer is alive,
+ * another run's or this one's, is left: it may be mid-restore.
+ */
+export function sweepStaging(workspaceRoot: string): void {
+  const top = path.join(workspaceRoot, '.vx', 'tmp')
+  let names: string[]
+  try {
+    names = readdirSync(top)
+  } catch {
+    return
+  }
+  for (const name of names) {
+    const m = /^([0-9a-z]+)-[0-9a-z]+$/.exec(name)
+    if (m === null) continue
+    const pid = Number.parseInt(m[1]!, 36)
+    if (pid === process.pid || writerAlive(pid)) continue
+    rmSync(path.join(top, name), { recursive: true, force: true })
+  }
+}
+
+function writerAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
 /**
  * Remove exactly these project-relative paths — the recorded rows of an
  * ADDITIVE task's own artifact (item 588), never a glob: the glob would
@@ -1221,6 +1265,7 @@ export async function cleanWorkspaceOutputs(args: {
   resolved?: readonly string[] | undefined
 }): Promise<string[]> {
   const committed = args.committed ?? committedFiles(undefined, args.workspaceRoot)
+  sweepRestoreTemps(args.workspaceRoot, args.outputs)
   const matched = args.resolved ?? (await resolveWorkspaceOutputs(args))
   await pruneEmptiedDirs(
     args.workspaceRoot,
@@ -1324,10 +1369,12 @@ function outright(reach: { prefixes: readonly string[]; literals: readonly strin
 /**
  * The files on disk under the {@link ignoredReach} entries that `accept`
  * keeps, sorted and absolute. A file is hashed from disk like any untracked
- * one; nothing here is stored or restored. An install (`node_modules`)
- * stays out, as in the enumeration: lockfile plugins key it. lstat, not
- * `exists()`: that answers false for a directory. Never memoized: a dependency writes these
- * mid-run.
+ * one; nothing here is stored or restored. `node_modules` is no special
+ * case (owner, 2026-10-16): an ignored path named outright is an input,
+ * a generated client (`node_modules/.prisma/client/**`) too; skipping
+ * installs here folded such an entry to nothing, silently. lstat, not
+ * `exists()`: that answers false for a directory. Never memoized: a
+ * dependency writes these mid-run.
  */
 function ignoredInputs(
   root: string,
@@ -1340,8 +1387,7 @@ function ignoredInputs(
     const st = lstatSync(abs, { throwIfNoEntry: false })
     if (st === undefined) continue
     if (!st.isDirectory()) {
-      if ((st.isFile() || st.isSymbolicLink()) && !isInstalledPath(entry) && accept(entry))
-        found.add(abs)
+      if ((st.isFile() || st.isSymbolicLink()) && accept(entry)) found.add(abs)
       continue
     }
     for (const rel of WALK.scanSync({
@@ -1351,7 +1397,7 @@ function ignoredInputs(
       dot: true,
     })) {
       const full = `${entry}/${rel.split(path.sep).join('/')}`
-      if (isInstalledPath(full) || !accept(full)) continue
+      if (!accept(full)) continue
       const file = path.join(abs, rel)
       if (isInputOnDisk(file)) found.add(file)
     }

package/src/cache/layer.ts

@@ -677,7 +677,13 @@ export interface CacheLayer {
    * into the workspace root. Callers restoring entries that may carry
    * workspace outputs must pass `workspaceRoot`.
    */
-  restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void>
+  restoreOutputs(
+    hash: string,
+    projectDir: string,
+    workspaceRoot?: string,
+    /** The task's declared outputs: an entry outside them fails the restore, nothing written. */
+    outputs?: DeclaredOutputs,
+  ): Promise<void>
   save(args: {
     hash: string
     /**

package/src/cache/layered-cache.ts

@@ -21,6 +21,7 @@ import type { Cache } from './cache.js'
 import type {
   CacheEntry,
   CacheGetContext,
+  DeclaredOutputs,
   CacheKeyInput,
   CacheLayer,
   CacheStats,
@@ -61,11 +62,6 @@ export interface RemoteCacheLayer {
    * dropped before it is printed.
    */
   readonly endpoint?: string
-  /**
-   * What the wire's credential allows, when less than both (a read-only
-   * token): core clears the run's remote axis it lacks. Omitted → both.
-   */
-  readonly access?: { readonly read?: boolean; readonly write?: boolean }
   /** Existence probe: `--dry` and `--force` ask it per key when the remote cannot batch. */
   has(hash: string): Promise<boolean>
   /**
@@ -330,8 +326,13 @@ export class LayeredCache implements CacheLayer {
     return this.local.hashFile(filePath)
   }
 
-  async restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
-    await this.local.restoreOutputs(hash, projectDir, workspaceRoot)
+  async restoreOutputs(
+    hash: string,
+    projectDir: string,
+    workspaceRoot?: string,
+    outputs?: DeclaredOutputs,
+  ): Promise<void> {
+    await this.local.restoreOutputs(hash, projectDir, workspaceRoot, outputs)
   }
 
   async save(args: SaveArgs): Promise<void> {

package/src/cache/scoped-cache.ts

@@ -8,6 +8,7 @@ import type {
   CacheEntry,
   CacheGetContext,
   CacheLayer,
+  DeclaredOutputs,
   IngestMeta,
   InvocationRecord,
   OutputDirRow,
@@ -194,8 +195,13 @@ export class ScopedCache implements CacheLayer {
     return (await this.inner.outputDirsCurrent?.(projectDir, rows)) ?? false
   }
 
-  restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
-    return this.inner.restoreOutputs(this.keyOf(hash), projectDir, workspaceRoot)
+  restoreOutputs(
+    hash: string,
+    projectDir: string,
+    workspaceRoot?: string,
+    outputs?: DeclaredOutputs,
+  ): Promise<void> {
+    return this.inner.restoreOutputs(this.keyOf(hash), projectDir, workspaceRoot, outputs)
   }
 
   save(args: SaveArgs): Promise<void> {

package/src/cli/help.ts

@@ -117,7 +117,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx cache clean [--older-than <duration>] [--max-size <size>] [--global] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
     '  vx lock [--check] [--format pretty|json]',
     '  vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
-    '  vx upgrade [TAG]',
+    '  vx upgrade [TAG] [-g|--global]',
     '  vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--format pretty|json]',
     '  vx info [--format pretty|json] [--cache-dir <path>]',
     '  vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]',
@@ -274,6 +274,12 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
     '',
+    'Upgrade:',
+    '  vx upgrade [TAG]     Bring vx to TAG (default: latest) the way it was installed.',
+    "                       In a project: the project's vx, its @vzn/vx-* plugins and",
+    '                       the global vx that ran it, to one release.',
+    '      -g, --global     Only the global vx: no project, no plugin.',
+    '',
     'Shell completions:',
     '  vx completions <shell>   Print a completion script for bash, zsh or fish: the',
     '                           verbs (plugin verbs of this workspace included) and',

package/src/cli/upgrade.ts

@@ -712,6 +712,31 @@ export async function upgradeGlobal(
   })
 }
 
+/**
+ * `vx upgrade -g`: bring this vx, the global one, to `version` and nothing
+ * else (owner, 2026-10-16) — no project's package.json, no plugin. The
+ * project's own vx refuses: no global ran.
+ */
+export async function upgradeOnlyGlobal(
+  self: string,
+  version: string,
+  current = VERSION,
+): Promise<void> {
+  if (current === version) {
+    ui.print('out', ui.status('info', 'vx upgrade', `global already at ${current}`))
+    return
+  }
+  // Read from the binary's own directory, not cwd: a project there is not this install's.
+  const install = managedInstall(self, path.dirname(self))
+  if (install?.scope === 'project') {
+    throw new UserError(
+      `vx upgrade -g: no global vx ran — ${self} is the project's own. Install one (npm install -g ${PACKAGE}), or run \`vx upgrade\` to move the project's`,
+    )
+  }
+  if (install === null) await upgradeBinary(self, version, current, 'global ')
+  else await upgradeManaged(install, version, current, 'global ')
+}
+
 /** `run`, its refusal naming `what` after the verb: a run that moves two installs says which failed. */
 async function named(what: string, run: () => Promise<void>): Promise<void> {
   try {
@@ -722,7 +747,9 @@ async function named(what: string, run: () => Promise<void>): Promise<void> {
   }
 }
 
-export async function upgradeCmd(args: readonly string[]): Promise<number> {
+export async function upgradeCmd(argv: readonly string[]): Promise<number> {
+  const global = argv.some((a) => a === '-g' || a === '--global')
+  const args = argv.filter((a) => a !== '-g' && a !== '--global')
   const unknown = args.find((a) => a.startsWith('-'))
   if (unknown !== undefined) {
     sayNotice(
@@ -746,10 +773,18 @@ export async function upgradeCmd(args: readonly string[]): Promise<number> {
     )
   }
   const dest = process.execPath
+  const handedOffFrom = process.env['VX_HANDED_OFF']
+  if (global) {
+    // A launcher from before -g handed the call over: the global is the one that did.
+    const version = await targetVersion(tag)
+    if (handedOffFrom !== undefined) await upgradeGlobal(handedOffFrom, version)
+    else await upgradeOnlyGlobal(dest, version)
+    return 0
+  }
   const install = managedInstall(dest, process.cwd())
   // A global vx handed this run to the project's own: both move, to one
   // version, the project first (owner, 2026-10-15).
-  const from = process.env['VX_HANDED_OFF']
+  const from = handedOffFrom
   if (from !== undefined) {
     const version = await targetVersion(tag)
     await named('project vx', () =>

package/src/cli/watch-filter.ts

@@ -33,13 +33,8 @@ export function isIgnoredWatchPath(rel: string): boolean {
   const segments = rel.split(path.sep)
   for (let i = 1; i <= segments.length; i++) if (isIgnoredDir(segments.slice(0, i))) return true
   if (IGNORED_SUFFIXES.some((suf) => rel.endsWith(suf))) return true
-  const name = segments[segments.length - 1]!
-  // A restore's own temporary file, never an input (`ALWAYS_IGNORE`):
-  // renamed away before the judgement, it read as a deletion and ran one
-  // more cycle where an uncached task makes ignored paths count.
-  if (name.startsWith('.vx-tmp-')) return true
   // `vx lock`'s review copy: no input, so a re-lock is no cycle.
-  return name === 'vx.lock.json'
+  return segments[segments.length - 1] === 'vx.lock.json'
 }
 
 /**

package/src/cli/watch-fs.ts

@@ -16,7 +16,8 @@ export const IGNORED_SEGMENTS = ['node_modules', '.git']
 export function isIgnoredDir(segments: readonly string[]): boolean {
   const last = segments.length - 1
   if (IGNORED_SEGMENTS.includes(segments[last]!)) return true
-  return segments[last] === 'cache' && segments[last - 1] === '.vx'
+  // vx's cache, and where its restores stage (archive.ts).
+  return (segments[last] === 'cache' || segments[last] === 'tmp') && segments[last - 1] === '.vx'
 }
 
 /**

package/src/handoff.ts

@@ -5,6 +5,11 @@
 // walk runs before anything else loads, through `Bun.file(…).exists()`:
 // importing `node:fs` alone was ~1.1 ms of a 4 ms start (2026-10-13).
 
+/** `vx upgrade -g`: moves only the global vx, so it never hands off (owner, 2026-10-16). */
+export function upgradesOnlyItself(argv: readonly string[]): boolean {
+  return argv[0] === 'upgrade' && argv.some((a) => a === '-g' || a === '--global')
+}
+
 /**
  * The project-local vx to run instead of this one, or null: the workspace
  * root's ({@link workspaceFile}) `node_modules/@vzn/vx`, run through its

package/src/index.ts

@@ -22,7 +22,7 @@ export { machineMemoryBytes, machineParallelism } from './util/index.js'
 // How core reads a task glob — its spelling, and which characters are
 // wildcards (`[` `]` are not; item 667) — for a plugin that turns declared
 // outputs into something else (`@vzn/vx-reapi`'s literal `output_paths`).
-export { isLiteralPattern, normalizeGlob } from './util/index.js'
+export { isLiteralPattern, normalizeGlob, restorableOutput } from './util/index.js'
 
 // Schema types and helpers (used by user vx.config files and presets).
 export type {

package/src/orchestrator/hit-restore.ts

@@ -12,11 +12,10 @@ import type { CacheConfig } from '../config.js'
 import {
   type CacheEntry,
   cleanOutputPaths,
-  cleanOutputs,
-  cleanWorkspaceOutputs,
   committedFiles,
   resolveOutputs,
   resolveWorkspaceOutputs,
+  sweepRestoreTemps,
   WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
 import type { TaskOutcome } from '../graph/index.js'
@@ -232,34 +231,74 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     }
   }
   if (!skipRestore) {
-    let cleanedRels: string[] = []
-    let cleanedWsRels: string[] = []
-    if (additive) {
-      cleanedRels = hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX))
+    const heldRels = hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX))
+    const heldWsRels = hit.outputFiles
+      .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
+      .map((p) => p.slice(WORKSPACE_OUTPUT_PREFIX.length))
+    // In place, never clean-then-restore: each file is renamed over the one
+    // it replaces, so a reader of the tree never finds a declared output
+    // missing, and a restore that fails before its renames (a full disk,
+    // a damaged entry) leaves the outputs it found as they were. Only what blocks a rename
+    // goes first; what the entry does not hold goes after. The clean used
+    // to run first: a reader polling a 64 MB output while ten hits restored
+    // met ENOENT on 153,336 of 204,411 reads (2026-10-16). An ADDITIVE task
+    // owns only its rows (item 588), and the restore rewrites exactly those.
+    let foundRels: string[] = []
+    let foundWsRels: string[] = []
+    let staleRels: string[] = []
+    let staleWsRels: string[] = []
+    if (!additive) {
+      sweepRestoreTemps(node.projectDir, outputs)
+      sweepRestoreTemps(args.workspaceRoot, wsOutputs)
+      if (outputs.length > 0) {
+        const abs = walked?.proj ?? (await resolveOutputs(cleanArgs))
+        foundRels = abs.map((f) => relPosix(node.projectDir, f))
+        const blocking = inTheWay(foundRels, heldRels)
+        staleRels = notHeld(foundRels, heldRels).filter((f) => !blocking.has(f))
+        if (blocking.size > 0) {
+          await cleanOutputPaths({
+            projectDir: node.projectDir,
+            rels: [...blocking],
+            outputs,
+            committed: cleanArgs.committed,
+          })
+        }
+      }
+      if (wsOutputs.length > 0) {
+        const abs = walked?.ws ?? (await resolveWorkspaceOutputs(wsCleanArgs))
+        foundWsRels = abs.map((f) => relPosix(args.workspaceRoot, f))
+        const blocking = inTheWay(foundWsRels, heldWsRels)
+        staleWsRels = notHeld(foundWsRels, heldWsRels).filter((f) => !blocking.has(f))
+        if (blocking.size > 0) {
+          await cleanOutputPaths({
+            projectDir: args.workspaceRoot,
+            rels: [...blocking],
+            outputs: wsOutputs,
+            committed: wsCleanArgs.committed,
+          })
+        }
+      }
+    }
+    await args.cache.restoreOutputs(hash, node.projectDir, args.workspaceRoot, {
+      files: outputs,
+      workspaceFiles: wsOutputs,
+    })
+    if (staleRels.length > 0) {
       await cleanOutputPaths({
         projectDir: node.projectDir,
-        rels: cleanedRels,
+        rels: staleRels,
         outputs,
         committed: cleanArgs.committed,
       })
-      cleanedWsRels = hit.outputFiles
-        .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
-        .map((p) => p.slice(WORKSPACE_OUTPUT_PREFIX.length))
+    }
+    if (staleWsRels.length > 0) {
       await cleanOutputPaths({
         projectDir: args.workspaceRoot,
-        rels: cleanedWsRels,
+        rels: staleWsRels,
         outputs: wsOutputs,
         committed: wsCleanArgs.committed,
       })
-    } else {
-      if (outputs.length > 0) {
-        cleanedRels = await cleanOutputs({ ...cleanArgs, resolved: walked?.proj })
-      }
-      if (wsOutputs.length > 0) {
-        cleanedWsRels = await cleanWorkspaceOutputs({ ...wsCleanArgs, resolved: walked?.ws })
-      }
     }
-    await args.cache.restoreOutputs(hash, node.projectDir, args.workspaceRoot)
     // The tree now holds this entry's bytes: stamp them for the next hit
     // (item 886).
     args.cache.recordOutputStamps?.(hash, node.projectDir, args.workspaceRoot)
@@ -288,17 +327,12 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     // unconditional drop (an executed task may write undeclared
     // files only git can see).
     if (outputs.length > 0) {
-      args.gitFilesCache?.markOutputsChanged(node.projectDir, [
-        ...cleanedRels,
-        ...hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX)),
-      ])
+      args.gitFilesCache?.markOutputsChanged(node.projectDir, [...foundRels, ...heldRels])
     }
     if (wsOutputs.length > 0) {
       args.gitFilesCache?.markWorkspaceOutputsChanged(args.workspaceRoot, [
-        ...cleanedWsRels,
-        ...hit.outputFiles
-          .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
-          .map((p) => p.slice(WORKSPACE_OUTPUT_PREFIX.length)),
+        ...foundWsRels,
+        ...heldWsRels,
       ])
     }
   }
@@ -361,3 +395,43 @@ function dirPrefixesOf(outputs: readonly string[]): readonly string[] | null {
 }
 
 const prefixMemo = new Map<string, readonly string[] | null>()
+
+/**
+ * On a case-insensitive volume (macOS's default) a rename onto `out.txt`
+ * replaces `Out.txt`: the two are one file, and removing the found name
+ * after the restore would remove the restored one.
+ */
+const fold: (rel: string) => string =
+  process.platform === 'darwin' ? (rel) => rel.normalize('NFC').toLowerCase() : (rel) => rel
+
+/**
+ * The found outputs a rename cannot replace: a file where the entry needs a
+ * directory (`dist/out` for `dist/out/a.js`) and a file under a path the
+ * entry holds as a file (`dist/out/a.js` for `dist/out`), whose directory
+ * the prune then takes.
+ */
+function inTheWay(found: readonly string[], held: readonly string[]): Set<string> {
+  if (found.length === 0 || held.length === 0) return new Set()
+  const files = new Set<string>()
+  const dirs = new Set<string>()
+  for (const h of held) {
+    const key = fold(h)
+    files.add(key)
+    for (let i = key.indexOf('/'); i !== -1; i = key.indexOf('/', i + 1)) dirs.add(key.slice(0, i))
+  }
+  const out = new Set<string>()
+  for (const f of found) {
+    const key = fold(f)
+    if (dirs.has(key)) out.add(f)
+    for (let i = key.indexOf('/'); i !== -1; i = key.indexOf('/', i + 1)) {
+      if (files.has(key.slice(0, i))) out.add(f)
+    }
+  }
+  return out
+}
+
+/** The found outputs the entry does not hold: the stale ones, once it has restored. */
+function notHeld(found: readonly string[], held: readonly string[]): string[] {
+  const keep = new Set(held.map(fold))
+  return found.filter((f) => !keep.has(fold(f)))
+}

package/src/orchestrator/local-shortcircuit.ts

@@ -60,6 +60,12 @@ export interface ShortCircuitArgs {
   hashCache: HashCache
   /** Cap on concurrent probes — the run's concurrency. */
   concurrency: number
+  /**
+   * `cache` is the local store in front of a remote: a hit is certain, a
+   * miss is not (the remote may hold it), so only hits are recorded and
+   * execute probes every other task through the layers.
+   */
+  localOnly?: boolean | undefined
 }
 
 /** Per-task result of the up-front probe. `hit` null = a confirmed
@@ -159,6 +165,7 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
       endProbe()
       for (const { hash, node } of candidates) {
         const hit = hits.get(hash) ?? null
+        if (hit === null && args.localOnly === true) continue
         preProbed.set(node.id, { hash, hit })
         if (hit !== null && !keptOut.has(node.id)) restoreTier.add(node.id)
       }
@@ -175,6 +182,7 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
       const { hash, node } = candidates[next++]!
       try {
         const hit = await args.cache.get(hash, getContext(node, node.config.exec?.command ?? ''))
+        if (hit === null && args.localOnly === true) continue
         preProbed.set(node.id, { hash, hit })
         if (hit !== null && !keptOut.has(node.id)) restoreTier.add(node.id)
       } catch {

package/src/orchestrator/plugin-host.ts

@@ -531,8 +531,8 @@ export interface CacheHost extends CacheContext {
  * Collect every plugin's remote (`cache` hook) in declaration order and
  * layer each over the local store: a lookup asks the local store first,
  * then each remote in order (owner, 2026-10-13), and a save reaches every
- * remote. The run's policy, narrowed by a remote's `access`, gates each
- * remote; a remote's throw is a miss and a warning naming its plugin. No
+ * remote. The run's policy alone gates each remote (M, 2026-10-16: a
+ * plugin moves bytes, it never decides reads or writes); a remote's throw is a miss and a warning naming its plugin. No
  * remote → the local store alone.
  */
 export async function resolveCache(
@@ -546,11 +546,10 @@ export async function resolveCache(
     const remote = await safe(plugin, 'cache', () => plugin.cache!(ctx))
     if (remote === undefined) continue
     assertShape(plugin, 'cache', remote, REMOTE_CACHE_METHODS, 'a remote cache layer')
-    const access = remote.access
     const entry: ResolvedRemote = {
       remote,
-      read: policy.remoteRead && access?.read !== false,
-      write: policy.remoteWrite && access?.write !== false,
+      read: policy.remoteRead,
+      write: policy.remoteWrite,
       onError: (err) => ctx.warn(`[vx] plugin '${plugin.name}': ${err.message}`),
     }
     resolved.push(entry)