@vzn/vx 0.0.645 → 0.0.648

package/src/orchestrator/held-servers.ts

@@ -0,0 +1,86 @@
+// A server the run's local store cannot settle: some dependant missed here
+// but may be a hit the remote holds. The scheduler holds such a server
+// until the remote answers; when every dependant hit, the server never
+// starts (2026-10-22), as it never starts behind local hits.
+
+import type { TaskNode } from '../graph/index.js'
+import type { CacheEntry, CacheLayer } from '../cache/index.js'
+import type { ShortCircuit } from './local-shortcircuit.js'
+import { getContext } from './remote-prefetch.js'
+
+/** The persistent tasks nobody asked for whose every dependant is a local hit or a key the remote may hold. */
+export function serversToHold(
+  nodes: ReadonlyMap<string, TaskNode>,
+  restoreTier: ReadonlySet<string>,
+  remoteAsk: ReadonlyMap<string, string>,
+): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  if (remoteAsk.size === 0) return out
+  const dependents = new Map<string, string[]>()
+  for (const n of nodes.values())
+    for (const d of n.deps) {
+      const list = dependents.get(d)
+      if (list === undefined) dependents.set(d, [n.id])
+      else list.push(n.id)
+    }
+  for (const n of nodes.values()) {
+    if (n.config.exec?.persistent === undefined || n.requested || n.surfaced === true) continue
+    const ds = dependents.get(n.id)
+    if (
+      ds !== undefined &&
+      ds.every((d) => restoreTier.has(d) || remoteAsk.has(d)) &&
+      ds.some((d) => remoteAsk.has(d))
+    )
+      out.set(n.id, ds)
+  }
+  return out
+}
+
+/**
+ * For each held server, whether the remote holds every dependant: one
+ * `get` per dependant through the layered cache, which shares the
+ * prefetch's request. All hits join the restore tier at once, so the
+ * scheduler finds the server idle; the first miss answers at once, with
+ * nothing promoted, so the server starts without waiting on the rest.
+ */
+export function askRemote(
+  held: ReadonlyMap<string, readonly string[]>,
+  nodes: ReadonlyMap<string, TaskNode>,
+  shortCircuit: Pick<ShortCircuit, 'preProbed' | 'restoreTier' | 'remoteAsk'>,
+  cache: CacheLayer,
+): Map<string, Promise<readonly string[]>> {
+  const asked = new Map<string, Promise<CacheEntry | null>>()
+  const ask = (id: string): Promise<CacheEntry | null> => {
+    let p = asked.get(id)
+    if (p === undefined) {
+      const node = nodes.get(id)!
+      p = cache
+        .get(shortCircuit.remoteAsk.get(id)!, getContext(node, node.config.exec?.command ?? ''))
+        .catch(() => null)
+      asked.set(id, p)
+    }
+    return p
+  }
+  const out = new Map<string, Promise<readonly string[]>>()
+  for (const [server, ds] of held) {
+    const remote = ds.filter((d) => shortCircuit.remoteAsk.has(d))
+    out.set(
+      server,
+      new Promise((resolve) => {
+        const hits = new Map<string, CacheEntry>()
+        for (const d of remote)
+          void ask(d).then((hit) => {
+            if (hit === null) return resolve([])
+            hits.set(d, hit)
+            if (hits.size < remote.length) return
+            for (const [id, entry] of hits) {
+              shortCircuit.preProbed.set(id, { hash: shortCircuit.remoteAsk.get(id)!, hit: entry })
+              shortCircuit.restoreTier.add(id)
+            }
+            resolve(remote)
+          })
+      }),
+    )
+  }
+  return out
+}

package/src/orchestrator/hit-restore.ts

@@ -14,8 +14,10 @@ import {
   type CacheEntry,
   cleanOutputPaths,
   committedFiles,
-  resolveOutputs,
-  resolveWorkspaceOutputs,
+  OUTPUT_DIRS_OVER_CAP,
+  outputWalkTakes,
+  resolveOutputTree,
+  resolveWorkspaceOutputTree,
   sweepRestoreTemps,
   WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
@@ -27,11 +29,11 @@ import {
   span,
   splitNegations,
   taskGlob,
-  wholeSubtreePrefixes,
+  outputDirPrefixes,
 } from '../util/index.js'
 import type { ExecuteArgs } from './execute-task.js'
 import { entryHolds } from './miss-save.js'
-import { decodeOutputLog } from './output-log.js'
+import { decodeOutputLog, maskStreams } from './output-log.js'
 
 export interface RestoreHitArgs {
   args: ExecuteArgs
@@ -53,28 +55,33 @@ export interface RestoreHitArgs {
  * schedule using the IDENTICAL logic — there is one restore path, not
  * two that could drift.
  */
-export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome> {
-  const { args, hash, hit, cacheOpStart, taskStartNs } = restore
-  const { node, log } = args
+export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
+  const { args, hash } = given
+  const { node } = args
   const cacheCfg: CacheConfig | undefined = node.config.cache
   const outputs = cacheCfg?.outputs.files ?? []
   const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
   const anyOutputs = outputs.length > 0 || wsOutputs.length > 0
+  // A layer that handed no rows: one SELECT, read by both paths below.
+  const restore =
+    anyOutputs && given.hit.outputRows === undefined
+      ? {
+          ...given,
+          hit: {
+            ...given.hit,
+            outputRows: args.cache.loadOutputFilesBatch([hash]).get(hash) ?? [],
+          },
+        }
+      : given
+  const { hit } = restore
+  const now = currentHit(restore)
+  if (now !== undefined) return now()
   // The directories the positive globs cover whole. A `!` entry inside one
   // leaves the snapshot sound: a file added or removed there still bumps a
   // recorded directory, and the walk that follows applies the `!` (A-46).
-  const dirPrefixes = dirPrefixesOf(outputs)
-  const cleanArgs = {
-    projectDir: node.projectDir,
-    outputs,
-    nestedProjectDirs: args.nestedProjectDirs,
-    committed: committedFiles(args.gitFilesCache, node.projectDir),
-  }
-  const wsCleanArgs = {
-    workspaceRoot: args.workspaceRoot,
-    outputs: wsOutputs,
-    committed: committedFiles(args.gitFilesCache, args.workspaceRoot),
-  }
+  // Asked only of a task that declares outputs: most hits declare none,
+  // and a warm run of 1,000 such hits paid this set-up for each.
+  const dirPrefixes = anyOutputs ? dirPrefixesOf(outputs) : null
   // The two sides of an overlapping pair (item 588). An ADDITIVE task owns
   // only its recorded rows: its glob also selects the upstream's files it
   // adds beside, so "no strays" is not a claim it can make, and its clean
@@ -83,9 +90,10 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
   // addition below is not a stray — while its glob clean still takes them:
   // the dependant restores or runs after it, by the edge.
   const additive = (node.addsToOutputsOf?.length ?? 0) > 0
-  const addedGlobs = (node.outputsAddedToBy ?? [])
-    .flatMap((g) => asTrees([g]))
-    .map((g) => taskGlob(g))
+  const addedGlobs =
+    anyOutputs && node.outputsAddedToBy !== undefined
+      ? node.outputsAddedToBy.flatMap((g) => asTrees([g])).map((g) => taskGlob(g))
+      : []
   const isAddition = (rel: string): boolean => addedGlobs.some((g) => g.match(rel))
 
   // "Tree is already current" short-circuit — skip cleanOutputs
@@ -112,11 +120,9 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
   // The walk that found the tree stale, handed to the clean when nothing
   // was awaited between them: the clean's own walk would only repeat it
   // (X-161).
-  let walked: { proj: string[]; ws: string[] } | undefined
+  let walked: { proj: Tree; ws: Tree } | undefined
   if (anyOutputs) {
-    const endRows = span('output rows')
-    const expected = hit.outputRows ?? args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
-    endRows()
+    const expected = hit.outputRows ?? []
     if (expected.length > 0) {
       // Two namespaces in the rows: bare rels are project outputs,
       // `workspace-outputs/<rel>` rows anchor at the workspace root.
@@ -124,86 +130,92 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
       const wsExpected = expected
         .filter((e) => e.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
         .map((e) => ({ ...e, path: e.path.slice(WORKSPACE_OUTPUT_PREFIX.length) }))
-      // The directory short-circuit: for whole-subtree globs, unchanged
-      // mtimes on every directory recorded at the last save/restore prove
-      // the output SET is unchanged (a file added or removed anywhere the
-      // glob could see bumps a recorded directory), so the walk that cost
-      // 0.36 ms per warm hit is replaced by a few stats. The per-file
-      // fingerprint check below still runs; only the enumeration is skipped.
-      let setKnown = false
-      if (dirPrefixes !== null && wsOutputs.length === 0 && args.cache.outputDirsCurrent) {
-        const endDirs = span('output dirs')
-        // Loaded with the entry (batched by getMany, or with the lazy get).
-        const dirRows = hit.outputDirRows ?? []
-        // Rows are recorded for these same prefixes under this same key
-        // (the outputs are folded into it), so `covers` cannot be false
-        // today — deleting it reddens nothing (item 638). Kept: a row
-        // set that shrank would otherwise vouch for a tree it never saw,
-        // and the failure it would let through is a skipped restore.
-        const covers = dirPrefixes.every((pre) => dirRows.some((r) => r.path === pre))
-        setKnown = covers && (await args.cache.outputDirsCurrent(node.projectDir, dirRows))
-        endDirs()
-      }
-      let treeMatches: boolean
-      if (setKnown) {
-        // The snapshot proved the tree holds exactly the entry's project
-        // rows (one per path, the table's key) and no workspace output is
-        // declared, so the comparisons below hold by construction: mapping
-        // each row to a path and back was ~5 ms per 1,000 warm hits.
-        treeMatches = wsExpected.length === 0
-      } else {
-        const endGlob = span('output glob')
-        const actualAbs = await resolveOutputs({
-          projectDir: node.projectDir,
-          outputs,
-          nestedProjectDirs: args.nestedProjectDirs,
-        })
-        const actualWsAbs = await resolveWorkspaceOutputs({
-          workspaceRoot: args.workspaceRoot,
-          outputs: wsOutputs,
-        })
-        endGlob()
-        const setsMatch = (
-          actual: readonly string[],
-          exp: ReadonlyArray<{ path: string }>,
-        ): boolean => {
-          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
-        // this entry recorded is never dropped, even where that glob covers
-        // the whole tree (strapi's shape: both on `dist`).
-        const expectedRels = new Set(projExpected.map((e) => e.path))
-        const expectedWsRels = new Set(wsExpected.map((e) => e.path))
-        const actualRels = actualAbs
-          .map((p) => relPosix(node.projectDir, p))
-          .filter((rel) => expectedRels.has(rel) || !isAddition(rel))
-        const actualWsRels = actualWsAbs
-          .map((p) => relPosix(args.workspaceRoot, p))
-          .filter((rel) => expectedWsRels.has(rel) || !isAddition(rel))
-        const rowsPresent = (
-          actual: readonly string[],
-          exp: ReadonlyArray<{ path: string }>,
-        ): boolean => {
-          const have = new Set(actual)
-          return exp.every((e) => e.path.endsWith('/') || have.has(e.path))
+      const endGlob = span('output glob')
+      const projTree = await resolveOutputTree({
+        projectDir: node.projectDir,
+        outputs,
+        nestedProjectDirs: args.nestedProjectDirs,
+      })
+      const wsTree = await resolveWorkspaceOutputTree({
+        workspaceRoot: args.workspaceRoot,
+        outputs: wsOutputs,
+      })
+      endGlob()
+      const actualAbs = projTree.files
+      const actualWsAbs = wsTree.files
+      // An empty directory is an entry row (`dist/empty/`): one the entry
+      // does not hold is a stray, as a file is. A directory row with a row
+      // under it is one kept for its mode (`DIR_MODE`), and the walk lists
+      // no such directory: only the files and empty directories it holds.
+      const setsMatch = (
+        actual: readonly string[],
+        exp: ReadonlyArray<{ path: string }>,
+      ): boolean => {
+        const held = new Set<string>()
+        for (const { path: p } of exp) {
+          for (let i = p.lastIndexOf('/', p.length - 2); i > 0; i = p.lastIndexOf('/', i - 1))
+            held.add(p.slice(0, i + 1))
         }
-        treeMatches = additive
-          ? rowsPresent(actualRels, projExpected) && rowsPresent(actualWsRels, wsExpected)
-          : setsMatch(actualRels, projExpected) && setsMatch(actualWsRels, wsExpected)
-        if (!treeMatches) walked = { proj: actualAbs, ws: actualWsAbs }
+        const expSet = new Set(
+          exp.map((e) => e.path).filter((p) => !p.endsWith('/') || !held.has(p)),
+        )
+        return actual.length === expSet.size && actual.every((r) => expSet.has(r))
+      }
+      const dirRels = (root: string, dirs: readonly string[]): string[] =>
+        dirs.map((d) => `${relPosix(root, d)}/`)
+      // A stray a dependant's glob could have added is not a stray; a path
+      // this entry recorded is never dropped, even where that glob covers
+      // the whole tree (strapi's shape: both on `dist`).
+      const expectedRels = new Set(projExpected.map((e) => e.path))
+      const expectedWsRels = new Set(wsExpected.map((e) => e.path))
+      const actualRels = actualAbs
+        .map((p) => relPosix(node.projectDir, p))
+        .filter((rel) => expectedRels.has(rel) || !isAddition(rel))
+      const actualWsRels = actualWsAbs
+        .map((p) => relPosix(args.workspaceRoot, p))
+        .filter((rel) => expectedWsRels.has(rel) || !isAddition(rel))
+      const actualDirRels = dirRels(node.projectDir, projTree.emptyDirs).filter(
+        (rel) => expectedRels.has(rel) || !isAddition(rel.slice(0, -1)),
+      )
+      const actualWsDirRels = dirRels(args.workspaceRoot, wsTree.emptyDirs).filter(
+        (rel) => expectedWsRels.has(rel) || !isAddition(rel.slice(0, -1)),
+      )
+      const rowsPresent = (
+        actual: readonly string[],
+        exp: ReadonlyArray<{ path: string }>,
+      ): boolean => {
+        const have = new Set(actual)
+        return exp.every((e) => e.path.endsWith('/') || have.has(e.path))
       }
+      const treeMatches = additive
+        ? rowsPresent(actualRels, projExpected) && rowsPresent(actualWsRels, wsExpected)
+        : setsMatch([...actualRels, ...actualDirRels], projExpected) &&
+          setsMatch([...actualWsRels, ...actualWsDirRels], wsExpected)
+      if (!treeMatches) walked = { proj: projTree, ws: wsTree }
       if (treeMatches) {
         const endStat = span('output stat')
         skipRestore =
-          (await args.cache.isOutputsCurrent(node.projectDir, projExpected)) &&
-          (await args.cache.isOutputsCurrent(args.workspaceRoot, wsExpected))
+          args.cache.isOutputsCurrent(node.projectDir, projExpected) &&
+          args.cache.isOutputsCurrent(args.workspaceRoot, wsExpected)
         endStat()
         // The walk ran and proved the tree current (rows absent, or a
         // directory had moved — a benign touch): snapshot the directories
         // so the next hit skips the walk.
-        if (skipRestore && !setKnown && dirPrefixes !== null) {
-          await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes)
+        if (
+          skipRestore &&
+          dirPrefixes !== null &&
+          hit.outputDirRows?.some((r) => r.mtimeMs === OUTPUT_DIRS_OVER_CAP) !== true
+        ) {
+          // Held to the rows like the run-end snapshot (item 1087): a stray
+          // written since the walk listed its directory, more than a racy
+          // window before this, is not the entry's.
+          const holds = entryHolds(
+            node,
+            outputWalkTakes(node.projectDir, outputs, args.nestedProjectDirs),
+          )
+          await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes, (files) =>
+            holds(files, expected),
+          )
         }
       }
     }
@@ -214,24 +226,37 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
   // of the tar is spared. A stray under the glob still falls through to
   // the clean, as strict ownership requires (item 589).
   if (anyOutputs && !skipRestore) {
-    const expected = hit.outputRows ?? args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
+    const expected = hit.outputRows ?? []
     if (expected.length === 0) {
       const endGlob = span('output glob')
-      const actual = await resolveOutputs({
+      const actual = await resolveOutputTree({
         projectDir: node.projectDir,
         outputs,
         nestedProjectDirs: args.nestedProjectDirs,
       })
-      const actualWs = await resolveWorkspaceOutputs({
+      const actualWs = await resolveWorkspaceOutputTree({
         workspaceRoot: args.workspaceRoot,
         outputs: wsOutputs,
       })
       endGlob()
-      skipRestore = actual.length === 0 && actualWs.length === 0
+      skipRestore =
+        actual.files.length + actual.emptyDirs.length + actualWs.files.length === 0 &&
+        actualWs.emptyDirs.length === 0
       walked = { proj: actual, ws: actualWs }
     }
   }
   if (!skipRestore) {
+    const cleanArgs = {
+      projectDir: node.projectDir,
+      outputs,
+      nestedProjectDirs: args.nestedProjectDirs,
+      committed: committedFiles(args.gitFilesCache, node.projectDir),
+    }
+    const wsCleanArgs = {
+      workspaceRoot: args.workspaceRoot,
+      outputs: wsOutputs,
+      committed: committedFiles(args.gitFilesCache, args.workspaceRoot),
+    }
     const heldRels = hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX))
     const heldWsRels = hit.outputFiles
       .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
@@ -248,34 +273,42 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     let foundWsRels: string[] = []
     let staleRels: string[] = []
     let staleWsRels: string[] = []
+    let staleDirs: string[] = []
+    let staleWsDirs: string[] = []
     if (!additive) {
-      sweepRestoreTemps(node.projectDir, outputs)
-      sweepRestoreTemps(args.workspaceRoot, wsOutputs)
+      sweepRestoreTemps(node.projectDir, outputs, cleanArgs.committed)
+      sweepRestoreTemps(args.workspaceRoot, wsOutputs, wsCleanArgs.committed)
       if (outputs.length > 0) {
-        const abs = walked?.proj ?? (await resolveOutputs(cleanArgs))
-        foundRels = abs.map((f) => relPosix(node.projectDir, f))
+        const tree = walked?.proj ?? (await resolveOutputTree(cleanArgs))
+        foundRels = tree.files.map((f) => relPosix(node.projectDir, f))
         const blocking = inTheWay(foundRels, heldRels)
         staleRels = notHeld(foundRels, heldRels).filter((f) => !blocking.has(f))
-        if (blocking.size > 0) {
+        const dirs = splitDirs(node.projectDir, tree.emptyDirs, heldRels)
+        staleDirs = dirs.stale
+        if (blocking.size > 0 || dirs.blocking.length > 0) {
           await cleanOutputPaths({
             projectDir: node.projectDir,
             rels: [...blocking],
             outputs,
             committed: cleanArgs.committed,
+            emptyDirs: dirs.blocking,
           })
         }
       }
       if (wsOutputs.length > 0) {
-        const abs = walked?.ws ?? (await resolveWorkspaceOutputs(wsCleanArgs))
-        foundWsRels = abs.map((f) => relPosix(args.workspaceRoot, f))
+        const tree = walked?.ws ?? (await resolveWorkspaceOutputTree(wsCleanArgs))
+        foundWsRels = tree.files.map((f) => relPosix(args.workspaceRoot, f))
         const blocking = inTheWay(foundWsRels, heldWsRels)
         staleWsRels = notHeld(foundWsRels, heldWsRels).filter((f) => !blocking.has(f))
-        if (blocking.size > 0) {
+        const dirs = splitDirs(args.workspaceRoot, tree.emptyDirs, heldWsRels)
+        staleWsDirs = dirs.stale
+        if (blocking.size > 0 || dirs.blocking.length > 0) {
           await cleanOutputPaths({
             projectDir: args.workspaceRoot,
             rels: [...blocking],
             outputs: wsOutputs,
             committed: wsCleanArgs.committed,
+            emptyDirs: dirs.blocking,
           })
         }
       }
@@ -284,10 +317,11 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
       files: outputs,
       workspaceFiles: wsOutputs,
     })
-    if (staleRels.length > 0) {
+    if (staleRels.length > 0 || staleDirs.length > 0) {
       await cleanOutputPaths({
         projectDir: node.projectDir,
         rels: staleRels,
+        emptyDirs: staleDirs,
         outputs,
         committed: cleanArgs.committed,
         // A stale file in an output directory the entry holds empty takes
@@ -299,12 +333,18 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
         ),
       })
     }
-    if (staleWsRels.length > 0) {
+    if (staleWsRels.length > 0 || staleWsDirs.length > 0) {
       await cleanOutputPaths({
         projectDir: args.workspaceRoot,
         rels: staleWsRels,
+        emptyDirs: staleWsDirs,
         outputs: wsOutputs,
         committed: wsCleanArgs.committed,
+        keep: new Set(
+          heldWsRels
+            .filter((r) => r.endsWith('/'))
+            .map((r) => path.join(args.workspaceRoot, r.slice(0, -1))),
+        ),
       })
     }
     // The tree now holds this entry's bytes: stamp them for the next hit
@@ -323,7 +363,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
         hash,
         projectDir: node.projectDir,
         prefixes: dirPrefixes,
-        holds: entryHolds(node),
+        holds: entryHolds(node, outputWalkTakes(node.projectDir, outputs, args.nestedProjectDirs)),
       })
     }
     // Restored outputs changed the project's tree — but on this
@@ -344,6 +384,47 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
       ])
     }
   }
+  return hitOutcome(restore, !skipRestore && anyOutputs)
+}
+
+/**
+ * The hit's outcome now, when its tree is provably current without a walk
+ * or an await: it declares no outputs, or every directory the entry
+ * recorded and every file it holds are as the entry left them (the
+ * directory snapshot proves the set, the stamps the bytes). Undefined
+ * sends it down `restoreHit`'s full path. Nothing happens until the thunk
+ * runs, which replays the stored output: the scheduler starts a hit it
+ * settles in place first, so its output follows its start.
+ */
+export function currentHit(restore: RestoreHitArgs): (() => TaskOutcome) | undefined {
+  const { args, hash, hit } = restore
+  const { node } = args
+  const outputs = node.config.cache?.outputs.files ?? []
+  if ((node.config.cache?.outputs.workspaceFiles?.length ?? 0) > 0) return undefined
+  if (outputs.length > 0) {
+    const dirPrefixes = dirPrefixesOf(outputs)
+    if (dirPrefixes === null || args.cache.outputDirsCurrent === undefined) return undefined
+    const expected = hit.outputRows ?? args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
+    if (expected.length === 0) return undefined
+    // Loaded with the entry (batched by getMany, or with the lazy get).
+    const dirRows = hit.outputDirRows ?? []
+    // Rows are recorded for these same prefixes under this same key (the
+    // outputs are folded into it), so this cannot fail today (item 638).
+    // Kept: a row set that shrank would otherwise vouch for a tree it never
+    // saw, and the failure it would let through is a skipped restore.
+    if (!dirPrefixes.every((pre) => dirRows.some((r) => r.path === pre))) return undefined
+    if (!args.cache.outputDirsCurrent(node.projectDir, dirRows)) return undefined
+    // No workspace output is declared, so every row is the project's.
+    if (expected.some((e) => e.path.startsWith(WORKSPACE_OUTPUT_PREFIX))) return undefined
+    if (!args.cache.isOutputsCurrent(node.projectDir, expected)) return undefined
+  }
+  return () => hitOutcome(restore, false)
+}
+
+/** Replay the stored output and build the hit's outcome. */
+function hitOutcome(restore: RestoreHitArgs, restored: boolean): TaskOutcome {
+  const { args, hash, hit, cacheOpStart, taskStartNs } = restore
+  const { node, log } = args
   if (hit.stdout) {
     // An entry saved before masking, or by another machine, can hold a
     // secret-named variable's value (L-11). Asked only of a hit that prints.
@@ -352,10 +433,9 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
       node.config.exec?.env?.secret,
     )
     // The stored log holds both streams in the order the run printed them.
-    for (const c of decodeOutputLog(hit.stdout)) {
-      const text = secrets === null ? c.text : secrets.mask(c.text)
-      if (c.err) log.taskStderr(node, text)
-      else log.taskStdout(node, text)
+    for (const c of maskStreams(decodeOutputLog(hit.stdout), secrets ?? undefined)) {
+      if (c.err) log.taskStderr(node, c.text)
+      else log.taskStdout(node, c.text)
     }
   }
   const status =
@@ -363,10 +443,10 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
   // `restored` distinguishes "we just wrote files to disk" from
   // "disk already matched the cached snapshot". Drives the
   // "up-to-date" vs "local-cache" / "remote-cache" label in the
-  // framed block. Only meaningful when at least one output was
-  // declared — no-outputs tasks never materialize anything, so
-  // they're vacuously up-to-date.
-  const restored = !skipRestore && anyOutputs
+  // framed block. A hit the remote answered is never up to date: up to
+  // date is fresh here, and a remote hit waited on the network and
+  // downloaded its entry, outputs or none (2026-10-24: "Up to date is
+  // a fresh. It should not require any cache").
   return {
     node,
     status,
@@ -380,7 +460,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     ...(hit.sizeBytes !== undefined ? { artifactBytes: hit.sizeBytes } : {}),
     ...(hit.fetchMs !== undefined ? { fetchMs: hit.fetchMs } : {}),
     hash,
-    restored,
+    restored: restored || hit.source === 'remote',
     wallclockStartNs: taskStartNs,
     wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
   }
@@ -396,7 +476,7 @@ function dirPrefixesOf(outputs: readonly string[]): readonly string[] | null {
   const key = JSON.stringify(outputs)
   let prefixes = prefixMemo.get(key)
   if (prefixes === undefined) {
-    prefixes = wholeSubtreePrefixes(splitNegations(outputs).positive)
+    prefixes = outputDirPrefixes(splitNegations(outputs).positive)
     prefixMemo.set(key, prefixes)
   }
   return prefixes
@@ -439,6 +519,31 @@ function inTheWay(found: readonly string[], held: readonly string[]): Set<string
 }
 
 /** The found outputs the entry does not hold: the stale ones, once it has restored. */
+type Tree = { files: string[]; emptyDirs: string[] }
+
+/**
+ * The empty directories found under the outputs (absolute) that the entry
+ * does not hold, as rels: one where it holds a file blocks that file's
+ * rename and goes first, the rest go after the restore, as a miss's clean
+ * takes them.
+ */
+function splitDirs(
+  root: string,
+  emptyDirs: readonly string[],
+  held: readonly string[],
+): { blocking: string[]; stale: string[] } {
+  const heldKeys = new Set(held.map(fold))
+  const blocking: string[] = []
+  const stale: string[] = []
+  for (const d of emptyDirs) {
+    const rel = relPosix(root, d)
+    if (heldKeys.has(fold(`${rel}/`))) continue
+    if (heldKeys.has(fold(rel))) blocking.push(rel)
+    else stale.push(rel)
+  }
+  return { blocking, stale }
+}
+
 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

@@ -2,14 +2,20 @@
 // through here (enforced by tests/module-boundaries.test.ts).
 
 export { run, planRun, nxProjectTarget, projectNamed } from './run.js'
-export { prepareRun, type PreparedRun } from './prepare.js'
+export { CYCLE_INTERRUPT } from './run-stop.js'
+export {
+  namesRemote,
+  openRemotes,
+  prepareRun,
+  workspaceCachePolicy,
+  type PreparedRun,
+} from './prepare.js'
 export { affectedTaskProjects } from './affected-tasks.js'
 export { applyGraphStage } from './graph-stage.js'
 export type { AffectedReason } from './affected-tasks.js'
 export {
   discoverProjects,
   gitOfDiscovery,
-  isDefaultBuild,
   keepDiscoveryGraph,
   loadProjects,
   loadResolvedProjects,
@@ -36,7 +42,16 @@ export { exitSignal, shellQuote } from '../exec/index.js'
 export { forwardedSignal } from './signals.js'
 // `vx cache clean` waits for a run on the workspace before it evicts.
 export { acquireRunLock } from './run-lock.js'
+export { type LiveSnapshot, liveSocketPath } from './run-live.js'
 export type { RunPlan, PlannedTask, PlanPrediction, CacheStatus } from './plan.js'
+export {
+  cacheFacts,
+  taskArtifacts,
+  type ArtifactRun,
+  type ArtifactTask,
+  type CacheFacts,
+  type TaskArtifacts,
+} from './task-artifacts.js'
 export {
   installPlugins,
   type CacheContext,
@@ -131,6 +146,8 @@ export {
   type TaskLog,
   taskLog,
 } from './run-failures.js'
-export { type RunStep, runSteps } from './run-steps.js'
+export { type RunStep, runSteps, runWarnings } from './run-steps.js'
 export { resolveRunId, shortRunId } from './run-id.js'
 export { collectInfo, type CollectInfoOptions, type InfoFacts } from './doctor.js'
+export { localFloor, type LocalFloor } from './local-floor.js'
+export { sandboxRequestFor, sweepPlaceholders, type SandboxRequest } from './sandbox-request.js'