@vzn/vx 0.0.646 → 0.0.648

package/src/orchestrator/hit-restore.ts

@@ -16,8 +16,8 @@ import {
   committedFiles,
   OUTPUT_DIRS_OVER_CAP,
   outputWalkTakes,
-  resolveOutputs,
-  resolveWorkspaceOutputs,
+  resolveOutputTree,
+  resolveWorkspaceOutputTree,
   sweepRestoreTemps,
   WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
@@ -33,7 +33,7 @@ import {
 } 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
@@ -55,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
@@ -85,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
@@ -114,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.
@@ -126,91 +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 &&
           hit.outputDirRows?.some((r) => r.mtimeMs === OUTPUT_DIRS_OVER_CAP) !== true
         ) {
-          await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes)
+          // 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),
+          )
         }
       }
     }
@@ -221,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))
@@ -255,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,
           })
         }
       }
@@ -291,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
@@ -306,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
@@ -351,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.
@@ -359,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 =
@@ -370,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,
@@ -387,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,
   }
@@ -446,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,6 +2,7 @@
 // through here (enforced by tests/module-boundaries.test.ts).
 
 export { run, planRun, nxProjectTarget, projectNamed } from './run.js'
+export { CYCLE_INTERRUPT } from './run-stop.js'
 export {
   namesRemote,
   openRemotes,
@@ -15,7 +16,6 @@ export type { AffectedReason } from './affected-tasks.js'
 export {
   discoverProjects,
   gitOfDiscovery,
-  isDefaultBuild,
   keepDiscoveryGraph,
   loadProjects,
   loadResolvedProjects,
@@ -42,6 +42,7 @@ 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,
@@ -145,8 +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, type SandboxRequest } from './sandbox-request.js'
+export { sandboxRequestFor, sweepPlaceholders, type SandboxRequest } from './sandbox-request.js'