@vzn/vx 0.0.639 → 0.0.641

package/src/orchestrator/execute-task.ts

@@ -84,6 +84,7 @@ import {
   describeTaskInputs,
   type HashCache,
   type InputFact,
+  isKeyless,
   movedInput,
   type UpfrontGroupKey,
 } from './task-hash.js'
@@ -252,9 +253,10 @@ export interface ExecuteArgs {
   /**
    * The run keeps its bytes in a remote (run-store.ts): an attempt captures
    * its output at the entry's bounds, and an outcome that saves no entry
-   * (a failure, an uncached run) carries it as `runLog`.
+   * carries it as `runLog`; a failure's only when `failures`
+   * (`cache.upload.failures`).
    */
-  keepRunLog?: boolean
+  keepRun?: { failures: boolean }
   /**
    * Whether a task has rewritten a root file a plugin claims (whose bytes
    * the claimant folded) since the run read it (fingerprint-watch.ts): past that, no key taken
@@ -394,7 +396,7 @@ function fingerprintMoved(args: ExecuteArgs): boolean {
  * through us.
  */
 async function executeGroupTask(args: ExecuteArgs): Promise<TaskOutcome> {
-  if (args.node.config.cache === undefined) {
+  if (args.node.config.inputs === undefined) {
     return unkeyedGroupOutcome(
       args.node,
       args.upstream,
@@ -417,7 +419,7 @@ async function executeGroupTask(args: ExecuteArgs): Promise<TaskOutcome> {
 }
 
 /**
- * An unkeyed group's outcome (no `cache`, no key of its own): its key is
+ * An unkeyed group's outcome (no `inputs`, no key of its own): its key is
  * its upstream's alone (`computeGroupKey`), so the up-front one stands when
  * that upstream is unchanged. Synchronous: the scheduler settles such a
  * group in place (`ScheduleOptions.settleNow`), and `upstream` is the key's
@@ -490,7 +492,17 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // exists to prevent), no output clean, no local artifact save. Its result
   // lives in the remote executor's own store.
   const remoteOnly = args.remoteOnly === true
-  const willRead = !remoteOnly && cfgCacheable && (policy.localRead || policy.remoteRead)
+  // A key that folds a task with no inputs is this run's alone (`isKeyless`):
+  // nothing to read under it, and nothing a later run could find.
+  const present = upstream.filter((u): u is TaskOutcome => u !== undefined)
+  const folded = new Set(
+    filterUpstreamHashes(present, cfg.inputs?.tasks, node.projectName, node.id).map(([id]) => id),
+  )
+  const foldedTasks = expandGroupUpstream(present.filter((u) => folded.has(u.node.id)))
+  const keyless =
+    isKeyless(cfg) || foldedTasks.some((u) => u.keyless === true || isKeyless(u.node.config))
+  const reads = policy.localRead || policy.remoteRead
+  const willRead = !remoteOnly && cfgCacheable && !keyless && reads
   const willWrite = !remoteOnly && cfgCacheable && (policy.localWrite || policy.remoteWrite)
   // `willWrite` governs output hygiene (clean before exec); the save itself
   // is also withheld from a task downstream of a failure (see `taintedUpstream`),
@@ -503,17 +515,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // (`tasks: []` and a file input) is judged by its bytes. `upstream` holds
   // a hole where a dependency did not run (a skipped one, a restore-tier
   // task's unfinished deps).
-  const present = upstream.filter((u): u is TaskOutcome => u !== undefined)
-  const folded = new Set(
-    filterUpstreamHashes(present, cacheCfg?.inputs?.tasks, node.projectName, node.id).map(
-      ([id]) => id,
-    ),
-  )
-  const unkeyedUpstream = expandGroupUpstream(present.filter((u) => folded.has(u.node.id))).find(
-    (u) => u.unkeyed === true,
-  )
+  const unkeyedUpstream = foldedTasks.find((u) => u.unkeyed === true)
   let unkeyed = unkeyedUpstream !== undefined
-  const willSave = willWrite && args.taintedUpstream !== true && !unkeyed
+  const willSave = willWrite && args.taintedUpstream !== true && !unkeyed && !keyless
 
   // The executor retains nothing: the entry's output is the attempt's
   // `output` log, both streams in the order they reached the logger, kept
@@ -615,7 +619,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   const taskStartNs = process.hrtime.bigint() - args.runStartHrTimeNs
 
   // Hash is computed mid-run, not at prepareRun time. Tasks whose
-  // `cache.inputs.files` matches sibling outputs (e.g. `'**/*'` after
+  // `inputs.files` matches sibling outputs (e.g. `'**/*'` after
   // a `codegen` step has written `generated.txt`) need the upstream
   // outputs ALREADY on disk when their hash is computed — so we
   // can't lift this into prepareRun. Same model as Turbo / Nx.
@@ -812,13 +816,10 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // is a hit. Almost always a glob written against the wrong directory
   // (`lib/**` in a package that builds `src/`). Said once per miss, on the
   // run's status line — the task itself succeeds.
-  const declaredInputs = [
-    ...(cacheCfg?.inputs.files ?? []),
-    ...(cacheCfg?.inputs.workspaceFiles ?? []),
-  ]
+  const declaredInputs = [...(cfg.inputs?.files ?? []), ...(cfg.inputs?.workspaceFiles ?? [])]
   if (inputs !== undefined && declaredInputs.length > 0 && inputs.files.length === 0) {
     warnOf(log)(
-      `[vx] ${node.id}: cache.inputs matched no files (${declaredInputs.join(', ')}) — ` +
+      `[vx] ${node.id}: inputs matched no files (${declaredInputs.join(', ')}) — ` +
         `the key will not change when this project's source does`,
     )
   }
@@ -1177,7 +1178,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
 
   async function buildRequest(local: boolean): Promise<ExecuteRequest> {
     const kept =
-      willSave || args.keepRunLog === true
+      willSave || args.keepRun !== undefined
         ? new BoundedCapture()
         : new BoundedCapture(FAILED_OUTPUT_HEAD_CHARS, FAILED_OUTPUT_TAIL_CHARS)
     output = kept
@@ -1456,11 +1457,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       : {}),
     ...(inputChanges !== undefined ? { inputChanges } : {}),
     ...(unkeyed ? { unkeyed: true as const } : {}),
+    ...(keyless ? { keyless: true as const } : {}),
     ...(saved ? { saved: true as const } : {}),
     ...(effectiveExitCode !== 0 && output !== undefined
-      ? { failedOutput: failedOutputLog(output, willSave || args.keepRunLog === true) }
+      ? { failedOutput: failedOutputLog(output, willSave || args.keepRun !== undefined) }
       : {}),
-    ...(args.keepRunLog === true && (effectiveExitCode !== 0 || !willSave) && output !== undefined
+    ...(args.keepRun !== undefined &&
+    (effectiveExitCode !== 0 ? args.keepRun.failures : !willSave) &&
+    output !== undefined
       ? { runLog: storedOutput() }
       : {}),
     ...(result.timedOut === true && effectiveExitCode !== 0 ? { timedOut: true as const } : {}),
@@ -1484,7 +1488,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
               finalViolations,
               node.projectDir,
               (t) => secrets?.mask(t) ?? t,
-              cacheCfg?.inputs.files,
+              cfg.inputs?.files,
             ),
           ),
         }

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/index.ts

@@ -125,5 +125,6 @@ export {
   type TaskLog,
   taskLog,
 } from './run-failures.js'
+export { type RunStep, runSteps } from './run-steps.js'
 export { resolveRunId, shortRunId } from './run-id.js'
 export { collectInfo, type CollectInfoOptions, type InfoFacts } from './doctor.js'

package/src/orchestrator/keyed-projects.ts

@@ -5,8 +5,7 @@
 // is decided — on the graph, before any hash exists, through the same
 // selection the hash path applies (`selectFoldedDeps`).
 
-import { isGroupTask, type TaskNode } from '../graph/index.js'
-import { keyedDeps, selectFoldedDeps, type FoldCandidate } from './upstream.js'
+import { foldedDeps, isGroupTask, type FoldCandidate, type TaskNode } from '../graph/index.js'
 
 /**
  * A run's keyed-set lookup: for a task, the directories of every project
@@ -14,18 +13,17 @@ import { keyedDeps, selectFoldedDeps, type FoldCandidate } from './upstream.js'
  * task itself is not counted.
  *
  * The fold relation is the hash path's, computed on the graph:
- *   - an exec task folds its dependencies as its own `cache.inputs.tasks`
- *     selects them (absent, or no `cache` at all, means all);
- *   - a group folds every dependency (`computeGroupKey`) and folds no
- *     files of its own, but for the default `build`, which folds every
- *     file of its project as a task does;
- *   - a persistent task is keyed as a task with no `cache` (A-17).
+ *   - an exec task folds its dependencies as its own `inputs.tasks`
+ *     selects them (absent means all);
+ *   - a group folds every dependency (`computeGroupKey`); a keyed one
+ *     (`inputs`, the default `build`) folds its project's files as a task
+ *     does;
+ *   - a persistent task is keyed as any task with no `cache` (A-17).
  *
- * Every exec task reached contributes its project, cached or not: a key
- * folds the task's own project files, and a task with no `cache` declares
- * no `inputs.files`, so it folds every file of its project (inputs.ts's
- * `DEFAULT_FILE_GLOBS`). `tests/keyed-projects.test.ts` holds that to the
- * key itself.
+ * Every exec task reached contributes its project, cached or not: its key
+ * folds its own project's files through its `inputs`, and one with no
+ * `inputs` is keyless, so a key that folds it is never stored or read.
+ * `tests/keyed-projects.test.ts` holds that to the key itself.
  *
  * Lazy and memoized by task id: only a sandboxed task that executes asks,
  * so a run of hits walks nothing, and a shared subgraph is walked once.
@@ -57,7 +55,7 @@ export function keyedProjects(
       stack.pop()
       const out = new Set<string>()
       for (const { node: dep } of deps) {
-        if (!isGroupTask(dep) || dep.config.cache !== undefined) out.add(dep.projectDir)
+        if (!isGroupTask(dep) || dep.config.inputs !== undefined) out.add(dep.projectDir)
         for (const dir of below.get(dep.id)!) out.add(dir)
       }
       below.set(node.id, out)
@@ -65,40 +63,3 @@ export function keyedProjects(
     return below.get(root.id)!
   }
 }
-
-/**
- * The dependencies `node`'s key folds, per the hash path's rules above, as
- * `keyUpstream` hands them to the key: the scheduled ones less the edges
- * `--exclude-dependencies` left for order alone, plus the dropped ones it
- * keys all the same (`excludedUpstream`), whose own dependencies the walk
- * reads from the run's `keyOnly` map. `node.deps` held the order-only
- * edges and lacked the dropped ones: the sandbox granted a sibling the key
- * does not answer for.
- */
-export function foldedDeps(node: TaskNode, nodeOf: (id: string) => TaskNode): FoldCandidate[] {
-  const candidates: FoldCandidate[] = []
-  for (const id of keyedDeps(node)) {
-    const dep = nodeOf(id)
-    candidates.push({ node: dep, unit: foldUnit(dep) })
-  }
-  for (const { node: dep } of node.excludedUpstream ?? []) {
-    candidates.push({ node: dep, unit: foldUnit(dep) })
-  }
-  if (isGroupTask(node) && node.config.cache === undefined) return candidates
-  return selectFoldedDeps(candidates, node.config.cache?.inputs?.tasks, node.projectName, node.id)
-}
-
-/**
- * What stands in for a dependency's hash in the dedup: equal exactly when
- * the hashes are. An exec task's key folds its own id (`task:<id>`), so its
- * id is enough; a group's hash is a roll-up of its members' ids and hashes
- * with no id of its own, so two groups over the same members hash alike.
- * The members are `keyUpstream`'s, which `computeGroupHash` is handed: under
- * `--exclude-dependencies` `node.deps` holds order-only edges and lacks the
- * dropped ones, and two groups the key told apart shared a unit.
- */
-function foldUnit(node: TaskNode): string {
-  if (!isGroupTask(node) || node.config.cache !== undefined) return `task|${node.id}`
-  const members = [...keyedDeps(node), ...(node.excludedUpstream ?? []).map((u) => u.node.id)]
-  return `group|${members.sort().join('|')}`
-}

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 {
@@ -232,7 +240,7 @@ export function restoreTierExclusions(
   const dependants = new Map<string, string[]>()
   for (const node of nodes.values()) {
     const dir = relPosix(workspaceRoot, node.projectDir)
-    const wsInputs = node.config.cache?.inputs?.workspaceFiles ?? []
+    const wsInputs = node.config.inputs?.workspaceFiles ?? []
     if (reaches(dir) || (wsInputs.length > 0 && workspaceInputsReach(wsInputs, prefixes))) {
       out.add(node.id)
     }

package/src/orchestrator/persistent-task.ts

@@ -55,9 +55,9 @@ export async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutc
   const effectiveForwardArgs = node.requested ? (args.forwardArgs ?? []) : []
   const env = taskEnv(node, step, args.workspaceRoot)
   const wallclockStartNs = process.hrtime.bigint() - args.runStartHrTimeNs
-  // Keyed like an uncached task (its whole project), so a cached dependant
-  // behind a dev server re-runs when the server's sources change; with no
-  // key the dependant folded nothing of it and replayed a stale e2e (A-17).
+  // Keyed on its inputs like any task, so a cached dependant behind a dev
+  // server re-runs when the server's sources change; with none it has no
+  // key and the dependant always runs (A-17).
   const hash =
     args.noDependants === true
       ? undefined

package/src/orchestrator/placement.ts

@@ -59,7 +59,7 @@ export function pinnedLocalSet(nodes: Map<string, TaskNode>): Set<string> {
 }
 
 /**
- * A key that folds `cache.inputs.runtime` / `workspaceRuntime` holds what
+ * A key that folds `inputs.runtime` / `workspaceRuntime` holds what
  * THIS machine answered (`node -v`); a worker runs its own runtime, which no
  * executor can prove equal, and its output saved under this key is a stale
  * hit here (C-2). Such a task runs here. Its dependants are not pinned with
@@ -68,7 +68,7 @@ export function pinnedLocalSet(nodes: Map<string, TaskNode>): Set<string> {
  */
 function withProbedRuntime(nodes: Map<string, TaskNode>, pinned: Set<string>): Set<string> {
   for (const node of nodes.values()) {
-    const inputs = node.config.cache?.inputs
+    const inputs = node.config.inputs
     if ((inputs?.runtime?.length ?? 0) > 0 || (inputs?.workspaceRuntime?.length ?? 0) > 0) {
       pinned.add(node.id)
     }

package/src/orchestrator/plan.ts

@@ -6,7 +6,7 @@
 // restoreOutputs. Cache probing uses the byte-free `cache.has()`
 // existence probe (a remote layer answers it its own way — no
 // artifact download, no local ingest), so the plan is read-only — with
-// one deliberate exception: `cache.inputs.runtime` / `workspaceRuntime`
+// one deliberate exception: `inputs.runtime` / `workspaceRuntime`
 // probe commands DO run, because predicting a task's key requires
 // resolving them (same as a real run). Keep runtime inputs
 // side-effect-free pure probes.

package/src/orchestrator/plugin-host.ts

@@ -381,41 +381,81 @@ export async function claimedAffected(
   return names
 }
 
+/** 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>
+  readonly refined?: (merged: ReadonlyMap<string, number>) => void
+}
+
 /**
  * `schedule` stage: the merged priorities map (a later plugin's weight for
- * a task overrides an earlier one's). Empty when no plugin answered.
+ * a task overrides an earlier one's). Empty when no plugin answered. Each
+ * plugin's call is the step `<plugin>:schedule`. A plugin's `ctx.refine`
+ * replaces its own weights and hands `refined` the merge again; with no
+ * `refined` (a plan), it is ignored.
  */
 export async function applyScheduleHooks(
   plugins: readonly VxPlugin[],
   nodes: ReadonlyMap<string, TaskNode>,
-  ctx: Omit<ScheduleHookContext, 'cache'>,
+  ctx: Omit<ScheduleHookContext, 'cache' | 'refine'>,
   cacheFor: (plugin: string) => PluginCache = () => absentPluginCache,
+  run: ScheduleRun = {},
 ): Promise<ReadonlyMap<string, number>> {
-  const merged = new Map<string, number>()
-  for (const plugin of plugins) {
+  const sets: (ReadonlyMap<string, number> | undefined)[] = []
+  const merged = (): ReadonlyMap<string, number> => {
+    const out = new Map<string, number>()
+    for (const set of sets) if (set !== undefined) for (const [id, w] of set) out.set(id, w)
+    return out
+  }
+  for (const [i, plugin] of plugins.entries()) {
     if (plugin.schedule === undefined) continue
-    const own = { ...ctx, cache: cacheFor(plugin.name) }
-    const weights = await safe(plugin, 'schedule', () => plugin.schedule!(nodes, own))
-    if (weights === undefined) continue
-    // Iterating a string destructures its characters into `[id, w]` pairs
-    // that match no task — a plugin returning `'fast'` used to be a no-op
-    // with no word said.
-    if (!(weights instanceof Map)) {
+    const refine = (weights: ReadonlyMap<string, number>): void => {
+      if (run.refined === undefined) return
+      try {
+        sets[i] = scheduleWeights(plugin, weights, nodes)
+      } catch (err) {
+        ctx.warn(`[vx] ${err instanceof Error ? err.message : String(err)}; refine ignored`)
+        return
+      }
+      run.refined(merged())
+    }
+    const own = { ...ctx, cache: cacheFor(plugin.name), refine }
+    const call = (): Promise<ReadonlyMap<string, number> | undefined> =>
+      safe(plugin, 'schedule', () => plugin.schedule!(nodes, own))
+    const weights = await (run.step === undefined
+      ? call()
+      : run.step(`${plugin.name}:schedule`, call))
+    // A refine that landed while the call ran is the newer set.
+    if (weights !== undefined) sets[i] ??= scheduleWeights(plugin, weights, nodes)
+  }
+  return merged()
+}
+
+/** A `schedule` answer's weights for tasks in the graph, refused by name when it is not a Map of finite numbers. */
+function scheduleWeights(
+  plugin: VxPlugin,
+  weights: unknown,
+  nodes: ReadonlyMap<string, TaskNode>,
+): ReadonlyMap<string, number> {
+  // Iterating a string destructures its characters into `[id, w]` pairs
+  // that match no task — a plugin returning `'fast'` used to be a no-op
+  // with no word said.
+  if (!(weights instanceof Map)) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in schedule: returned ${describeValue(weights)}, not a Map of task id → weight`,
+    )
+  }
+  const out = new Map<string, number>()
+  for (const [id, w] of weights as Map<unknown, unknown>) {
+    if (typeof id !== 'string' || !nodes.has(id)) continue
+    if (typeof w !== 'number' || !Number.isFinite(w)) {
       throw new UserError(
-        `plugin '${plugin.name}' failed in schedule: returned ${describeValue(weights)}, not a Map of task id → weight`,
+        `plugin '${plugin.name}' failed in schedule: weight for ${id} is not a finite number`,
       )
     }
-    for (const [id, w] of weights) {
-      if (!nodes.has(id)) continue
-      if (typeof w !== 'number' || !Number.isFinite(w)) {
-        throw new UserError(
-          `plugin '${plugin.name}' failed in schedule: weight for ${id} is not a finite number`,
-        )
-      }
-      merged.set(id, w)
-    }
+    out.set(id, w)
   }
-  return merged
+  return out
 }
 
 /**
@@ -491,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(
@@ -506,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)

package/src/orchestrator/plugin.ts

@@ -137,6 +137,9 @@ export interface VxPlugin {
    * only when a task will start: a run of confirmed local hits restores
    * in no order a weight changes. A later plugin's weight for a task
    * overrides an earlier one's. Return undefined to leave the baseline.
+   * The run waits for this answer before its first task, so it should
+   * come from what is at hand (local history); better weights that need
+   * a fetch go to `ctx.refine` when they arrive, without holding the run.
    */
   schedule?(
     nodes: ReadonlyMap<string, TaskNode>,
@@ -244,8 +247,9 @@ export interface VxPlugin {
 /**
  * What a finished run hands each plugin's `teardown`: its facts and every
  * task, with the names core kept the task's bytes under. Core keeps them
- * only when a remote takes the run's writes (CI by default): a failed
- * task's log and the files its outputs left, an uncached task's log. Read
+ * only when a remote takes the run's writes (CI by default): the log of a
+ * task that saved no entry, and a failed task's log and the files its
+ * outputs left when `cache.upload.failures` covers the run. Read
  * them with `ctx.cache.getRun(name)`. Core keeps no manifest of its own; a
  * plugin that wants one writes it from here (`ctx.cache.put`).
  */
@@ -448,6 +452,12 @@ export interface ScheduleHookContext extends BaseContext {
   readonly branch: string | null
   /** This plugin's entries in the workspace's cache, as `setup` has them. */
   readonly cache: PluginCache
+  /**
+   * Replace this plugin's weights while the run goes on: the tasks not yet
+   * started re-rank at once. For weights that arrive late (timings fetched
+   * from a remote). Ignored in a plan and once the run's tasks are done.
+   */
+  refine(weights: ReadonlyMap<string, number>): void
 }
 
 /** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */