@vzn/vx 0.0.652 → 0.0.653

package/src/orchestrator/graph-memo.ts

@@ -16,6 +16,8 @@ import {
   buildTaskGraph,
   computeReverseDepCount,
   declaredTask,
+  setStandIns,
+  standInsOf,
   type TaskNode,
 } from '../graph/index.js'
 import { xxh3hex } from '../util/index.js'
@@ -25,7 +27,7 @@ import { codeIdentity } from './run-keys.js'
 type BuildGraphOptions = Parameters<typeof buildTaskGraph>[0]
 
 /** Moves every remembered graph: bump it when what a token stands for changes. */
-const GRAPH_MEMO_VERSION = 'graph-memo-v1'
+const GRAPH_MEMO_VERSION = 'graph-memo-v2'
 
 /** What names a run's configs: the lock they were read from and the projects discovered. */
 export interface GraphMemo {
@@ -38,7 +40,9 @@ export interface GraphMemo {
  * A node as the memo holds it: its project and task, requested, its deps
  * and the tasks it adds outputs to as positions in the list (ids in full
  * were 123 KB for 1,206 tasks, and parsing them back cost what the walk
- * saved), and the globs that add to its own outputs.
+ * saved), the globs that add to its own outputs, and its stand-ins
+ * (rebuilt without it, `inputs.tasks` dropped the edges past a default
+ * build on a package cycle on every warm run).
  */
 type Row = [
   project: string,
@@ -47,6 +51,7 @@ type Row = [
   deps: number[],
   adds?: number[] | null,
   added?: string[] | null,
+  stands?: Array<[edge: number, past: number[]]>,
 ]
 
 /**
@@ -97,11 +102,23 @@ function rowsOf(nodes: Map<string, TaskNode>): Row[] {
   const pos = (ids: readonly string[]): number[] => ids.map((d) => at.get(d)!)
   return [...nodes.values()].map((n) => {
     const row: Row = [n.projectName, n.taskName, n.requested ? 1 : 0, pos(n.deps)]
-    if (n.addsToOutputsOf !== undefined || n.outputsAddedToBy !== undefined)
+    const standsFor = standInsOf(n)
+    if (
+      n.addsToOutputsOf !== undefined ||
+      n.outputsAddedToBy !== undefined ||
+      standsFor !== undefined
+    )
       row.push(
         n.addsToOutputsOf === undefined ? null : pos(n.addsToOutputsOf),
         n.outputsAddedToBy ?? null,
       )
+    if (standsFor !== undefined)
+      row.push(
+        Object.entries(standsFor).map(([edge, past]): [number, number[]] => [
+          at.get(edge)!,
+          pos(past),
+        ]),
+      )
     return row
   })
 }
@@ -134,11 +151,16 @@ function rebuilt(
   const ids = (at: readonly number[]): string[] => at.map((i) => list[i]!.id)
   const nodes = new Map<string, TaskNode>()
   for (let i = 0; i < rows.length; i++) {
-    const [, , , deps, adds, added] = rows[i]!
+    const [, , , deps, adds, added, stands] = rows[i]!
     const node = list[i]!
     node.deps = ids(deps)
     if (adds != null) node.addsToOutputsOf = ids(adds)
     if (added != null) node.outputsAddedToBy = added
+    if (stands !== undefined) {
+      const standsFor: Record<string, string[]> = {}
+      for (const [edge, past] of stands) standsFor[list[edge]!.id] = ids(past)
+      setStandIns(node, standsFor)
+    }
     nodes.set(node.id, node)
   }
   return nodes

package/src/orchestrator/graph-stage.ts

@@ -3,7 +3,13 @@
 // select over the graph the hooks leave.
 
 import path from 'node:path'
-import type { GraphRules, TaskNode } from '../graph/index.js'
+import {
+  setStandIns,
+  standInsOf,
+  type GraphRules,
+  type StandIns,
+  type TaskNode,
+} from '../graph/index.js'
 import { relPosix, UserError } from '../util/index.js'
 import { type ProjectMeta, validateProjectConfig } from '../workspace/index.js'
 import { applyGraphHooks } from './plugin-host.js'
@@ -31,9 +37,13 @@ export async function applyGraphStage(
   const shown = (dir: string): string => relPosix(args.workspaceRoot, dir) || '.'
   // The lock shares a task config two tasks declare alike: an edit in place
   // works on this node's own copy.
-  if (plugins.some((p) => p.graph !== undefined)) {
-    for (const n of nodes.values())
-      if (!isDefaultBuild(n.config)) n.config = structuredClone(n.config)
+  if (!plugins.some((p) => p.graph !== undefined)) return
+  for (const n of nodes.values())
+    if (!isDefaultBuild(n.config)) n.config = structuredClone(n.config)
+  const standIns = new Map<string, StandIns>()
+  for (const n of nodes.values()) {
+    const s = standInsOf(n)
+    if (s !== undefined) standIns.set(n.id, s)
   }
   await applyGraphHooks(
     plugins,
@@ -68,4 +78,17 @@ export async function applyGraphStage(
     },
     args.rules,
   )
+  // A hook may rebuild a node, which drops what its edges stand in for, or
+  // remove an edge a record names: re-attach each by id, less what is gone.
+  for (const [id, before] of standIns) {
+    const n = nodes.get(id)
+    if (n === undefined) continue
+    const kept: Record<string, string[]> = {}
+    for (const [edge, past] of Object.entries(before)) {
+      if (!n.deps.includes(edge)) continue
+      const still = past.filter((p) => n.deps.includes(p))
+      if (still.length > 0) kept[edge] = still
+    }
+    setStandIns(n, kept)
+  }
 }

package/src/orchestrator/held-servers.ts

@@ -3,12 +3,19 @@
 // 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 { idleServers, 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. */
+/**
+ * The persistent tasks nobody asked for that would be idle if the remote
+ * held every key it may hold, each with the remote keys it waits on: those
+ * above it, through the groups and servers nobody asked for between, as
+ * `idleServers` walks local hits. Held only on its direct dependants, a
+ * server behind `env: { dependsOn: ['dev'] }` or under another held server
+ * booted on a remote-only warm run.
+ */
 export function serversToHold(
   nodes: ReadonlyMap<string, TaskNode>,
   restoreTier: ReadonlySet<string>,
@@ -23,15 +30,28 @@ export function serversToHold(
       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)
+  const idleNow = idleServers(nodes, dependents, restoreTier)
+  const between = new Set<string>()
+  const hoped = idleServers(
+    nodes,
+    dependents,
+    new Set([...restoreTier, ...remoteAsk.keys()]),
+    between,
+  )
+  for (const id of hoped) {
+    if (idleNow.has(id)) continue
+    const remote = new Set<string>()
+    const seen = new Set<string>()
+    const stack = [id]
+    while (stack.length > 0) {
+      for (const d of dependents.get(stack.pop()!) ?? []) {
+        if (seen.has(d)) continue
+        seen.add(d)
+        if (between.has(d)) stack.push(d)
+        else if (remoteAsk.has(d) && !restoreTier.has(d)) remote.add(d)
+      }
+    }
+    if (remote.size > 0) out.set(id, [...remote])
   }
   return out
 }
@@ -63,7 +83,9 @@ export function askRemote(
   }
   const out = new Map<string, Promise<readonly string[]>>()
   for (const [server, ds] of held) {
-    const remote = ds.filter((d) => shortCircuit.remoteAsk.has(d))
+    // A set: counted against a list naming one twice, the hits never
+    // reached its length and the server waited forever.
+    const remote = new Set(ds.filter((d) => shortCircuit.remoteAsk.has(d)))
     out.set(
       server,
       new Promise((resolve) => {
@@ -72,12 +94,12 @@ export function askRemote(
           void ask(d).then((hit) => {
             if (hit === null) return resolve([])
             hits.set(d, hit)
-            if (hits.size < remote.length) return
+            if (hits.size < remote.size) return
             for (const [id, entry] of hits) {
               shortCircuit.preProbed.set(id, { hash: shortCircuit.remoteAsk.get(id)!, hit: entry })
               shortCircuit.restoreTier.add(id)
             }
-            resolve(remote)
+            resolve([...remote])
           })
       }),
     )

package/src/orchestrator/hit-restore.ts

@@ -24,6 +24,7 @@ import type { TaskOutcome } from '../graph/index.js'
 import {
   asTrees,
   relPosix,
+  maskStreams,
   secretMask,
   span,
   splitNegations,
@@ -32,7 +33,7 @@ import {
 } from '../util/index.js'
 import type { ExecuteArgs } from './execute-task.js'
 import { entryHolds } from './miss-save.js'
-import { decodeOutputLog, maskStreams } from './output-log.js'
+import { decodeOutputLog } from './output-log.js'
 
 export interface RestoreHitArgs {
   args: ExecuteArgs
@@ -57,6 +58,7 @@ export interface RestoreHitArgs {
 export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
   const { args, hash } = given
   const { node } = args
+  const outputNested = args.outputNestedDirs ?? args.nestedProjectDirs
   const cfgOut = node.config.outputs
   const outputs = cfgOut?.files ?? []
   const wsOutputs = cfgOut?.workspaceFiles ?? []
@@ -94,6 +96,11 @@ export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
       ? node.outputsAddedToBy.flatMap((g) => asTrees([g])).map((g) => taskGlob(g))
       : []
   const isAddition = (rel: string): boolean => addedGlobs.some((g) => g.match(rel))
+  const ownInputs = {
+    projectDir: node.projectDir,
+    workspaceRoot: args.workspaceRoot,
+    declared: node.config.inputs,
+  }
 
   // "Tree is already current" short-circuit — skip cleanOutputs
   // + restoreOutputs when the on-disk state matches what this
@@ -130,14 +137,22 @@ export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
         .filter((e) => e.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
         .map((e) => ({ ...e, path: e.path.slice(WORKSPACE_OUTPUT_PREFIX.length) }))
       const endGlob = span('output glob')
+      // The FIFOs, sockets and devices listed only if the tree is stale: a
+      // listing reads every directory again, ~17% of a walk.
       const projTree = await resolveOutputTree({
         projectDir: node.projectDir,
         outputs,
-        nestedProjectDirs: args.nestedProjectDirs,
+        nestedProjectDirs: outputNested,
+        inputs: ownInputs,
+        special: 'later',
+        clearing: true,
       })
       const wsTree = await resolveWorkspaceOutputTree({
         workspaceRoot: args.workspaceRoot,
         outputs: wsOutputs,
+        inputs: ownInputs,
+        special: 'later',
+        clearing: true,
       })
       endGlob()
       const actualAbs = projTree.files
@@ -208,10 +223,7 @@ export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
           // 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),
-          )
+          const holds = entryHolds(node, outputWalkTakes(node.projectDir, outputs, outputNested))
           await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes, (files) =>
             holds(files, expected),
           )
@@ -231,11 +243,17 @@ export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
       const actual = await resolveOutputTree({
         projectDir: node.projectDir,
         outputs,
-        nestedProjectDirs: args.nestedProjectDirs,
+        nestedProjectDirs: outputNested,
+        inputs: ownInputs,
+        special: 'later',
+        clearing: true,
       })
       const actualWs = await resolveWorkspaceOutputTree({
         workspaceRoot: args.workspaceRoot,
         outputs: wsOutputs,
+        inputs: ownInputs,
+        special: 'later',
+        clearing: true,
       })
       endGlob()
       skipRestore =
@@ -248,12 +266,14 @@ export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
     const cleanArgs = {
       projectDir: node.projectDir,
       outputs,
-      nestedProjectDirs: args.nestedProjectDirs,
+      nestedProjectDirs: outputNested,
+      inputs: ownInputs,
       committed: committedFiles(args.gitFilesCache, node.projectDir),
     }
     const wsCleanArgs = {
       workspaceRoot: args.workspaceRoot,
       outputs: wsOutputs,
+      inputs: ownInputs,
       committed: committedFiles(args.gitFilesCache, args.workspaceRoot),
     }
     const heldRels = hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX))
@@ -268,83 +288,105 @@ export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
     // 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.
+    const walkArgs = { special: 'later', clearing: true } as const
     let foundRels: string[] = []
     let foundWsRels: string[] = []
     let staleRels: string[] = []
     let staleWsRels: string[] = []
     let staleDirs: string[] = []
     let staleWsDirs: string[] = []
-    if (!additive) {
-      sweepRestoreTemps(node.projectDir, outputs, cleanArgs.committed)
-      sweepRestoreTemps(args.workspaceRoot, wsOutputs, wsCleanArgs.committed)
-      if (outputs.length > 0) {
-        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))
-        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,
-          })
+    // The restore writes into the tree as a command would, and a write in a
+    // cycle no window covers is the user's to `vx watch` (`sawEvent`): with
+    // none, a hit's restore started one more cycle whenever the next
+    // command opened its window more than a racy window later (CI stalls).
+    const closeWindow =
+      args.commandWindows?.open(
+        node.id,
+        node.projectDir,
+        wsOutputs.length > 0 ? 'workspace' : 'project',
+      ) ?? (() => {})
+    try {
+      if (!additive) {
+        sweepRestoreTemps(node.projectDir, outputs, cleanArgs.committed)
+        sweepRestoreTemps(args.workspaceRoot, wsOutputs, wsCleanArgs.committed)
+        if (outputs.length > 0) {
+          const tree = walked?.proj ?? (await resolveOutputTree({ ...walkArgs, ...cleanArgs }))
+          // A FIFO, socket or device is found too: one the entry does not hold
+          // is a stray like any file, and one in a held path's way goes first.
+          foundRels = [...tree.files, ...(tree.findSpecial?.() ?? [])].map((f) =>
+            relPosix(node.projectDir, f),
+          )
+          const blocking = inTheWay(foundRels, heldRels)
+          staleRels = notHeld(foundRels, heldRels).filter((f) => !blocking.has(f))
+          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 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))
-        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,
-          })
+        if (wsOutputs.length > 0) {
+          const tree =
+            walked?.ws ?? (await resolveWorkspaceOutputTree({ ...walkArgs, ...wsCleanArgs }))
+          foundWsRels = [...tree.files, ...(tree.findSpecial?.() ?? [])].map((f) =>
+            relPosix(args.workspaceRoot, f),
+          )
+          const blocking = inTheWay(foundWsRels, heldWsRels)
+          staleWsRels = notHeld(foundWsRels, heldWsRels).filter((f) => !blocking.has(f))
+          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,
+            })
+          }
         }
       }
-    }
-    await args.cache.restoreOutputs(hash, node.projectDir, args.workspaceRoot, {
-      files: outputs,
-      workspaceFiles: wsOutputs,
-    })
-    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
-        // 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))),
-        ),
-      })
-    }
-    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))),
-        ),
+      await args.cache.restoreOutputs(hash, node.projectDir, args.workspaceRoot, {
+        files: outputs,
+        workspaceFiles: wsOutputs,
       })
+      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
+          // 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))),
+          ),
+        })
+      }
+      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))),
+          ),
+        })
+      }
+    } finally {
+      closeWindow()
     }
     // The tree now holds this entry's bytes: stamp them for the next hit
     // (item 886).
@@ -362,7 +404,7 @@ export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
         hash,
         projectDir: node.projectDir,
         prefixes: dirPrefixes,
-        holds: entryHolds(node, outputWalkTakes(node.projectDir, outputs, args.nestedProjectDirs)),
+        holds: entryHolds(node, outputWalkTakes(node.projectDir, outputs, outputNested)),
       })
     }
     // Restored outputs changed the project's tree — but on this
@@ -424,7 +466,9 @@ export function currentHit(restore: RestoreHitArgs): (() => TaskOutcome) | undef
 function hitOutcome(restore: RestoreHitArgs, restored: boolean): TaskOutcome {
   const { args, hash, hit, cacheOpStart, taskStartNs } = restore
   const { node, log } = args
-  if (hit.stdout) {
+  // Read here, once: a local entry reads its log from the index on access.
+  const stored = hit.stdout
+  if (stored) {
     // 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.
     const secrets = secretMask(
@@ -432,7 +476,7 @@ function hitOutcome(restore: RestoreHitArgs, restored: boolean): TaskOutcome {
       node.config.exec?.env?.secret,
     )
     // The stored log holds both streams in the order the run printed them.
-    for (const c of maskStreams(decodeOutputLog(hit.stdout), secrets ?? undefined)) {
+    for (const c of maskStreams(decodeOutputLog(stored), secrets ?? undefined)) {
       if (c.err) log.taskStderr(node, c.text)
       else log.taskStdout(node, c.text)
     }
@@ -446,7 +490,9 @@ function hitOutcome(restore: RestoreHitArgs, restored: boolean): TaskOutcome {
   // 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 {
+  // Assigned, not spread: one outcome per hit, and five conditional
+  // spreads were ~3 ms of an 8,002-hit warm run (2026-11-07).
+  const outcome: TaskOutcome = {
     node,
     status,
     exitCode: hit.exitCode,
@@ -454,18 +500,21 @@ function hitOutcome(restore: RestoreHitArgs, restored: boolean): TaskOutcome {
     // `storedDurationMs`, which is what the hit skipped.
     durationMs: Math.round(performance.now() - cacheOpStart),
     storedDurationMs: hit.durationMs,
-    ...(hit.cpuMs !== undefined ? { storedCpuMs: hit.cpuMs } : {}),
-    ...(hit.peakRssBytes !== undefined ? { storedPeakRssBytes: hit.peakRssBytes } : {}),
-    ...(hit.sizeBytes !== undefined ? { artifactBytes: hit.sizeBytes } : {}),
-    ...(hit.outputRows !== undefined
-      ? { outputBytes: hit.outputRows.reduce((n, r) => n + r.size, 0) }
-      : {}),
-    ...(hit.fetchMs !== undefined ? { fetchMs: hit.fetchMs } : {}),
     hash,
     restored: restored || hit.source === 'remote',
     wallclockStartNs: taskStartNs,
     wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
   }
+  if (hit.cpuMs !== undefined) outcome.storedCpuMs = hit.cpuMs
+  if (hit.peakRssBytes !== undefined) outcome.storedPeakRssBytes = hit.peakRssBytes
+  if (hit.sizeBytes !== undefined) outcome.artifactBytes = hit.sizeBytes
+  if (hit.outputRows !== undefined) {
+    let bytes = 0
+    for (const r of hit.outputRows) bytes += r.size
+    outcome.outputBytes = bytes
+  }
+  if (hit.fetchMs !== undefined) outcome.fetchMs = hit.fetchMs
+  return outcome
 }
 
 /**
@@ -521,7 +570,7 @@ 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[] }
+type Tree = { files: string[]; emptyDirs: string[]; findSpecial?: () => string[] }
 
 /**
  * The empty directories found under the outputs (absolute) that the entry

package/src/orchestrator/index.ts

@@ -1,12 +1,13 @@
 // Module contract for `orchestrator`. Cross-module imports must come
 // through here (enforced by tests/module-boundaries.test.ts).
 
-export { run, planRun, nxProjectTarget, projectNamed } from './run.js'
+export { run, planRun, nxProjectTarget, projectAtDir, projectNamed } from './run.js'
 export { CYCLE_INTERRUPT } from './run-stop.js'
 export {
   namesRemote,
   openRemotes,
   prepareRun,
+  unlockedDir,
   workspaceCachePolicy,
   type PreparedRun,
 } from './prepare.js'
@@ -16,6 +17,7 @@ export type { AffectedReason } from './affected-tasks.js'
 export {
   discoverProjects,
   gitOfDiscovery,
+  ignoredConfigRefusal,
   keepDiscoveryGraph,
   loadProjects,
   loadResolvedProjects,
@@ -27,6 +29,7 @@ export {
 } from './projects.js'
 export { computeTaskHash, createHashCache, type HashCache } from './task-hash.js'
 export type { HeldPersistent, RunOptions, RunSummary } from './options.js'
+export { commandWindows, type CommandWindows } from './command-windows.js'
 // Re-surface the cache policy contract (defined in the cache module) so
 // embedders constructing RunOptions.cache and the package façade can
 // reach it without importing the cache module directly.

package/src/orchestrator/keyed-projects.ts

@@ -91,3 +91,28 @@ export function readableDeps(
     return [...out.values()]
   }
 }
+
+/**
+ * A run's lookup of the projects nested in a keyed one, by its directory.
+ * A sandboxed task granted a linked package is walled from them: that
+ * package's key stops at a nested project (sandbox-request.ts). Built on
+ * the first ask, from every node the walk can reach.
+ */
+export function nestedDirsOf(
+  nodes: ReadonlyMap<string, TaskNode>,
+  keyOnly: ReadonlyMap<string, TaskNode>,
+  nestedDirsByProject: ReadonlyMap<string, readonly string[]>,
+): (projectDir: string) => readonly string[] {
+  let byDir: Map<string, readonly string[]> | undefined
+  return (dir) => {
+    if (byDir === undefined) {
+      byDir = new Map()
+      for (const map of [nodes, keyOnly]) {
+        for (const n of map.values()) {
+          byDir.set(n.projectDir, nestedDirsByProject.get(n.projectName) ?? [])
+        }
+      }
+    }
+    return byDir.get(dir) ?? []
+  }
+}