@vzn/vx 0.0.640 → 0.0.642

package/src/orchestrator/execute-task.ts

@@ -61,7 +61,6 @@ import {
   type Placeholder,
   reachedWithheld,
   sandboxRequestFor,
-  sandboxReadable,
   sweepPlaceholders,
   undeclaredWriteReach,
   untouchedPlaceholderLine,
@@ -233,7 +232,7 @@ export interface ExecuteArgs {
    */
   outputDirSnapshots?: OutputDirSnapshot[]
   /** The run's save lane: a miss's cache save runs off the execution slot (save-lane.ts). */
-  deferSave?: (save: () => Promise<void>) => Promise<void>
+  deferSave?: (save: () => Promise<void>) => Promise<boolean>
   /**
    * Where a deferred save's `landed` promise is parked by task id, for the
    * in-flight join (admission.ts): a duplicate of this task in another run
@@ -1278,6 +1277,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   } else if (
     effectiveExitCode === 0 &&
     willSave &&
+    nothingLeftRunning() &&
     (await keyStillTrue()) &&
     (own = await ownOutputs()) !== undefined
   ) {
@@ -1302,19 +1302,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       deferSave: args.deferSave,
       // A sink listens: say what the save cost.
       measure: args.explainMiss !== undefined,
-      ...(userSandbox
-        ? {
-            readable: sandboxReadable(
-              node,
-              cfg.exec!.sandbox!,
-              args.workspaceRoot,
-              args.nestedProjectDirs,
-            ),
-          }
-        : {}),
     })
-    args.deferredSaves?.set(node.id, landed)
-    saved = true
+    // A run that settles the outcome on `landed` learns there whether the
+    // entry is in; without one, the save is taken as done.
+    if (args.deferredSaves !== undefined) args.deferredSaves.set(node.id, landed)
+    else saved = true
   } else if (cfgCacheable && !remoteOnly && !deferralRequested && args.noDependants !== true) {
     // Ran here and saves nothing — failed, a read-only policy, a tainted
     // upstream, a key that no longer held — yet it wrote what a save would
@@ -1362,6 +1354,20 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     return mine
   }
 
+  /**
+   * A process the shell left behind still held its output when the drain
+   * bound cut it, so it may still write outputs: a save now would file a
+   * tree the run does not leave, and a hit elsewhere would replay it.
+   */
+  function nothingLeftRunning(): boolean {
+    if (result.leftRunning !== true) return true
+    warnOf(log)(
+      `[vx] ${node.id}: a process it left running may still write its outputs — ` +
+        `the result stands, but is not saved; wait for it in the command (\`wait\`)`,
+    )
+    return false
+  }
+
   /**
    * The input that no longer holds what the key folded, or one the key did
    * not fold that is there now: `null` when the key re-derived just before

package/src/orchestrator/hit-restore.ts

@@ -8,15 +8,15 @@
 // which bytes a green run replays. Moved out of execute-task.ts
 // 2026-09-10 as pure code motion, the mirror of miss-save.ts.
 
+import path from 'node:path'
 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'
@@ -167,7 +167,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
           actual: readonly string[],
           exp: ReadonlyArray<{ path: string }>,
         ): boolean => {
-          const expSet = new Set(exp.map((e) => e.path))
+          const expSet = new Set(exp.map((e) => e.path).filter((p) => !p.endsWith('/')))
           return actual.length === expSet.size && actual.every((r) => expSet.has(r))
         }
         // A stray a dependant's glob could have added is not a stray; a path
@@ -186,7 +186,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
           exp: ReadonlyArray<{ path: string }>,
         ): boolean => {
           const have = new Set(actual)
-          return exp.every((e) => have.has(e.path))
+          return exp.every((e) => e.path.endsWith('/') || have.has(e.path))
         }
         treeMatches = additive
           ? rowsPresent(actualRels, projExpected) && rowsPresent(actualWsRels, wsExpected)
@@ -232,34 +232,81 @@ 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,
+        // A stale file in an output directory the entry holds empty takes
+        // only itself: the directory stays, as the miss left it.
+        keep: new Set(
+          heldRels
+            .filter((r) => r.endsWith('/'))
+            .map((r) => path.join(node.projectDir, r.slice(0, -1))),
+        ),
       })
-      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 +335,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 +403,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/index.ts

@@ -77,6 +77,7 @@ export {
   applyProjectHooks,
   applyScheduleHooks,
   claimedAffected,
+  claimedExtraFiles,
   fingerprintClaims,
   hasHook,
   REMOTE_CACHE_METHODS,

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/lockfile-claim.ts

@@ -39,7 +39,9 @@ export interface LockfileClaimOptions {
    * the lockfile does not pin (bun.lock's `patchedDependencies` names a patch
    * file and records no hash of it). Their content hashes ('' when absent)
    * reach `digest` as `files` and join the memo's identity, so an edited
-   * patch moves the key (item 1014). Called only when the memo misses.
+   * patch moves the key (item 1014). A directory (a `file:` dependency the
+   * install copies) hashes every file under it but `node_modules` and
+   * `.git`. Called only when the memo misses.
    */
   readonly extraFiles?: (text: string) => readonly string[]
   /** Folded into the memo's identity: bump when `digest` folds differently. */
@@ -109,13 +111,33 @@ interface Memo {
 /** A root-relative extra file's content hash, '' when absent; a path leaving the root is never read. */
 async function hashExtra(workspaceRoot: string, rel: string): Promise<string> {
   if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) return 'outside-root'
+  const abs = path.join(workspaceRoot, rel)
   try {
-    return xxh3hex(await Bun.file(path.join(workspaceRoot, rel)).bytes())
-  } catch {
+    return xxh3hex(await Bun.file(abs).bytes())
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'EISDIR') return hashDir(abs)
     return ''
   }
 }
 
+/**
+ * Every file under `dir` but its `node_modules` and `.git`, as `rel\0hash`
+ * lines in sorted order. Links are followed: a linked file is what a task
+ * reads, and the scan skipped it, so an edit to its target moved no key.
+ */
+async function hashDir(dir: string): Promise<string> {
+  const rels: string[] = []
+  const scan = { cwd: dir, dot: true, onlyFiles: true, followSymlinks: true }
+  for await (const rel of new Bun.Glob('**').scan(scan)) {
+    if (!rel.split('/').some((s) => s === 'node_modules' || s === '.git')) rels.push(rel)
+  }
+  rels.sort()
+  const lines = await Promise.all(
+    rels.map(async (rel) => `${rel}\0${xxh3hex(await Bun.file(path.join(dir, rel)).bytes())}`),
+  )
+  return `dir\0${xxh3hex(lines.join('\n'))}`
+}
+
 /**
  * A file's identity for the in-process gate, as `Cache.hashFile`'s memo
  * keys one: size and mtime alone kept the digests of a lockfile or patch
@@ -126,9 +148,16 @@ function identityOf(st: { size: number; mtimeMs: number; ctimeMs: number; ino: n
   return `${st.size}:${st.mtimeMs}:${st.ctimeMs}:${st.ino}`
 }
 
+// A directory's own stat moves only when an entry is added or removed, not
+// when a file in it is edited: its identity is its content hash.
 async function statsOf(workspaceRoot: string, rels: readonly string[]): Promise<string[]> {
   return Promise.all(
-    rels.map((rel) => stat(path.join(workspaceRoot, rel)).then(identityOf, () => 'gone')),
+    rels.map((rel) =>
+      stat(path.join(workspaceRoot, rel)).then(
+        (st) => (st.isDirectory() ? hashExtra(workspaceRoot, rel) : identityOf(st)),
+        () => 'gone',
+      ),
+    ),
   )
 }
 
@@ -262,15 +291,29 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         // lockfile is broken" and "the base commit's is" — a migration
         // commit hits the second, and the bare parser message named
         // neither (2026-09-20).
-        const sideOf = (bytes: Uint8Array, side: string): ReadonlyMap<string, string> => {
+        // A changed extra file is folded by its content on each side; one
+        // left out is the same on both, so it moves no digest either way.
+        const extrasOf = (pick: 'before' | 'after'): Map<string, string> => {
+          const out = new Map<string, string>()
+          for (const [rel, sides] of change.extras ?? []) {
+            const bytes = sides[pick]
+            out.set(rel, bytes === null ? '' : xxh3hex(bytes))
+          }
+          return out
+        }
+        const sideOf = (
+          bytes: Uint8Array,
+          pick: 'before' | 'after',
+          side: string,
+        ): ReadonlyMap<string, string> => {
           try {
-            return digest(decode(bytes), new Map())
+            return digest(decode(bytes), extrasOf(pick))
           } catch (err) {
             throw new Error(`${err instanceof Error ? err.message : String(err)} (${side})`)
           }
         }
-        const before = sideOf(change.before, `as of the base ref`)
-        const after = sideOf(change.after, `in the working tree`)
+        const before = sideOf(change.before, 'before', `as of the base ref`)
+        const after = sideOf(change.after, 'after', `in the working tree`)
         const names: string[] = []
         for (const p of ctx.projects) {
           const importer = importerOf(ctx.workspaceRoot, p.dir)
@@ -278,6 +321,9 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         }
         return names
       },
+      ...(options.extraFiles !== undefined
+        ? { extraFiles: (_file: string, bytes: Uint8Array) => options.extraFiles!(decode(bytes)) }
+        : {}),
     },
     async key(task, ctx) {
       const digests = await loadOnce(ctx)

package/src/orchestrator/miss-save.ts

@@ -12,6 +12,7 @@ import path from 'node:path'
 import {
   type CacheLayer,
   type GitFilesCache,
+  resolveOutputTree,
   resolveOutputs,
   resolveWorkspaceOutputs,
   WORKSPACE_OUTPUT_PREFIX,
@@ -51,7 +52,9 @@ export function entryHolds(
 ): (files: readonly string[], rows: ReadonlyArray<{ path: string }>) => boolean {
   return (files, rows) => {
     const expected = new Set(
-      rows.map((r) => r.path).filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX)),
+      rows
+        .map((r) => r.path)
+        .filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX) && !p.endsWith('/')),
     )
     const seen = new Set(files)
     if ((node.addsToOutputsOf?.length ?? 0) > 0) return [...expected].every((p) => seen.has(p))
@@ -111,8 +114,6 @@ export interface SaveMissArgs {
   ownOutputFiles?: string[] | undefined
   /** `ownOutputFiles` for `cache.outputs.workspaceFiles` (A-43). */
   ownWsOutputFiles?: string[] | undefined
-  /** A sandboxed task's reach: a symlinked output it could not read is refused (`sandboxReadable`). */
-  readable?: ((real: string) => boolean) | undefined
   /** The Tier-3 input fingerprint rows captured by the pre-exec describe. */
   captured: readonly TaskInputComponent[]
   command: string
@@ -129,7 +130,7 @@ export interface SaveMissArgs {
    * (a same-project downstream task reads both), and the pack + write +
    * index go to the run's save lane (save-lane.ts).
    */
-  deferSave?: ((save: () => Promise<void>) => Promise<void>) | undefined
+  deferSave?: ((save: () => Promise<void>) => Promise<boolean>) | undefined
   /** Time the save and size its artifact, for a telemetry sink: one stat. */
   measure?: boolean | undefined
 }
@@ -138,6 +139,8 @@ export interface SaveMissArgs {
 export interface SaveFacts {
   saveMs?: number
   artifactBytes?: number
+  /** The entry landed: the outcome's `saved`, set only once it has. */
+  saved?: true
 }
 
 /**
@@ -147,13 +150,16 @@ export interface SaveFacts {
 export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveFacts> }> {
   const { node, cache, log } = a
   const endResolve = span('miss: resolve outputs')
-  const outputFiles =
-    a.ownOutputFiles ??
-    (await resolveOutputs({
-      projectDir: node.projectDir,
-      outputs: a.outputs,
-      nestedProjectDirs: a.nestedProjectDirs,
-    }))
+  // An additive task owns only the files it wrote (item 588), no directory.
+  const tree =
+    a.ownOutputFiles !== undefined
+      ? { files: a.ownOutputFiles, emptyDirs: [] }
+      : await resolveOutputTree({
+          projectDir: node.projectDir,
+          outputs: a.outputs,
+          nestedProjectDirs: a.nestedProjectDirs,
+        })
+  const outputFiles = tree.files
   const wsOutputFiles =
     a.ownWsOutputFiles ??
     (await resolveWorkspaceOutputs({
@@ -204,11 +210,11 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
       hash: a.hash,
       projectDir: node.projectDir,
       outputFiles,
-      ...(wsOutputFiles.length > 0
-        ? { workspaceOutputFiles: wsOutputFiles, workspaceRoot: a.workspaceRoot }
-        : {}),
+      ...(tree.emptyDirs.length > 0 ? { outputDirs: tree.emptyDirs } : {}),
+      // The root an output symlink's target must stay inside, outputs.workspaceFiles or not.
+      workspaceRoot: a.workspaceRoot,
+      ...(wsOutputFiles.length > 0 ? { workspaceOutputFiles: wsOutputFiles } : {}),
       inputComponents: a.captured.map((c) => ({ entryHash: a.hash, ...c })),
-      readable: a.readable,
       // No `exitCode`: the save only runs under `effectiveExitCode === 0`, and
       // the contract no longer accepts one — so the invariant is enforced by
       // the type rather than by every call site remembering the gate.
@@ -258,9 +264,13 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
   // Off the slot when the run keeps a lane (the save lane bounds and
   // drains it); in the slot otherwise — an embedder without a lane gets
   // the entry before the outcome.
-  if (a.deferSave !== undefined) return { landed: a.deferSave(save).then(() => facts) }
+  if (a.deferSave !== undefined) {
+    return {
+      landed: a.deferSave(save).then((stored) => (stored ? { ...facts, saved: true } : facts)),
+    }
+  }
   await save()
-  return { landed: Promise.resolve(facts) }
+  return { landed: Promise.resolve({ ...facts, saved: true }) }
 }
 
 /** What `markUnsaved` reads of a miss: where its declared outputs are. */

package/src/orchestrator/output-host.ts

@@ -7,7 +7,15 @@ import type { Logger } from '../report/index.js'
 import type { OutputContext, VxPlugin } from './plugin.js'
 
 const REQUIRED = ['status', 'taskStdout', 'taskStderr', 'taskComplete'] as const
-const OPTIONAL = ['runStart', 'taskStart', 'runEnd', 'stepStart', 'stepEnd', 'runDone'] as const
+const OPTIONAL = [
+  'runStart',
+  'taskStart',
+  'runEnd',
+  'stepStart',
+  'stepEnd',
+  'runStop',
+  'runDone',
+] as const
 
 /** Reject anything that is not Logger-shaped, naming what is missing. */
 function checkLogger(value: unknown): Logger {

package/src/orchestrator/plan.ts

@@ -146,6 +146,10 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
   const outcomes = await runGraph({
     nodes: args.nodes,
     concurrency: 1,
+    // A plan's keys and probes do not depend on the order it walks in, so
+    // it ranks nothing: the default ranking's closure over every task was
+    // ~30 ms of a 1,000-project `--dry`.
+    strategy: 'ready-order',
     execute: async (node, live) => {
       const upstream = keyUpstream(node, live)
       const hashArgs = {

package/src/orchestrator/plugin-host.ts

@@ -381,6 +381,36 @@ export async function claimedAffected(
   return names
 }
 
+/**
+ * The files a claimed file names that its plugin keys too
+ * (`FingerprintClaim.extraFiles`); `undefined` when it names none it can
+ * answer for, and a plugin that throws is refused by its name.
+ */
+export function claimedExtraFiles(
+  plugin: VxPlugin,
+  file: string,
+  bytes: Uint8Array,
+): readonly string[] | undefined {
+  const read = plugin.fingerprint?.extraFiles
+  if (read === undefined) return undefined
+  let names: unknown
+  try {
+    names = read.call(plugin.fingerprint, file, bytes)
+  } catch (err) {
+    throw new UserError(
+      maskedLine(
+        `plugin '${plugin.name}' failed in fingerprint: ${err instanceof Error ? err.message : String(err)}`,
+      ),
+    )
+  }
+  if (!Array.isArray(names) || names.some((n) => typeof n !== 'string')) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in fingerprint: extraFiles returned ${describeValue(names)}, not a list of paths`,
+    )
+  }
+  return names as string[]
+}
+
 /** What a run hands the `schedule` stage: a step per plugin, and where refined weights go. */
 export interface ScheduleRun {
   readonly step?: <T>(id: string, work: () => Promise<T>) => Promise<T>
@@ -531,8 +561,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 +576,11 @@ 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,
+      plugin: plugin.name,
+      read: policy.remoteRead,
+      write: policy.remoteWrite,
       onError: (err) => ctx.warn(`[vx] plugin '${plugin.name}': ${err.message}`),
     }
     resolved.push(entry)