@vzn/vx 0.0.646 → 0.0.648

package/src/orchestrator/execute-task.ts

@@ -1,3 +1,4 @@
+import path from 'node:path'
 import type { ExecConfig, TaskConfig, CacheConfig, InputStability } from '../config.js'
 import {
   ArtifactVanishedError,
@@ -43,7 +44,7 @@ import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '..
 import {
   killGraceMs,
   MASKED,
-  maskedEmitter,
+  maskedStreams,
   outputMatcher,
   printable,
   relPosix,
@@ -67,9 +68,15 @@ import {
   type WithheldLink,
   withheldLinkLine,
 } from './sandbox-request.js'
-import { markUnsaved, saveMiss, type OutputDirSnapshot, type SaveFacts } from './miss-save.js'
+import {
+  bracketLiteralHint,
+  markUnsaved,
+  saveMiss,
+  type OutputDirSnapshot,
+  type SaveFacts,
+} from './miss-save.js'
 import type { FingerprintWatch } from './fingerprint-watch.js'
-import { restoreHit } from './hit-restore.js'
+import { currentHit, restoreHit } from './hit-restore.js'
 import type { MissExplainer } from '../history/index.js'
 import { shellVerdict } from './shell-verdict.js'
 import { sandboxFix } from './sandbox-fix.js'
@@ -111,6 +118,8 @@ export interface ExecuteArgs {
   log: Logger
   /** The executor this task was PLACED on (run.ts, before scheduling). */
   executor: TaskExecutor
+  /** Told the task executes, so the executor's demand counts it again (`ExecutorDemand.executing`). */
+  executing?: ((id: string) => void) | undefined
   /**
    * `exec.remote: 'only'` with no remote executor to take it: succeed
    * WITHOUT executing, cleaning, restoring or saving anything on this
@@ -276,6 +285,8 @@ export interface ExecuteArgs {
   carried?: true
   /** The persistent tasks its `servers` executor starts where it runs it. */
   servers?: readonly TaskNode[]
+  /** Each of `servers`' nested project dirs, in its order. */
+  serversNested?: readonly (readonly string[])[]
   /** When each command of the run ran and where it may write (command-windows.ts). */
   commandWindows?: CommandWindows
 }
@@ -306,6 +317,28 @@ export async function executeTask(args: ExecuteArgs): Promise<TaskOutcome> {
   return executeCachedTask(args)
 }
 
+/**
+ * A probed hit `executeTask` would restore, settled now when its tree is
+ * already current (`currentHit`): the thunk replays its output and returns
+ * the outcome. Undefined dispatches it as usual. A dispatch, a slot and the
+ * promises around it were ~10 µs of each of a warm run's hits.
+ */
+export function settleProbedHit(args: ExecuteArgs): (() => TaskOutcome) | undefined {
+  const probed = args.preProbed
+  if (probed?.hit == null || !readsCache(args) || args.remoteOnlyNoop === true) return undefined
+  if (isGroupTask(args.node) || args.node.config.exec?.persistent !== undefined) return undefined
+  // A moved fingerprint is said, and demotes the hit, on the dispatch.
+  if (args.fingerprintWatch?.moved() !== undefined) return undefined
+  const restore = {
+    args,
+    hash: probed.hash,
+    hit: probed.hit,
+    cacheOpStart: performance.now(),
+    taskStartNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+  }
+  return currentHit(restore)
+}
+
 /** Whether this task reads the cache: a cached, not remote-only task with a read axis on. */
 function readsCache(args: ExecuteArgs): boolean {
   const policy = args.cachePolicy ?? FULL_CACHE_POLICY
@@ -364,7 +397,7 @@ async function restoreOrMiss(
 /**
  * What a write to an input during the command means, each field highest
  * first: the env var (`layers.run`), the task's `cache.inputStability`,
- * the workspace's, then `'immutable'` and `'warn'` (owner, 2026-10-12), so
+ * the workspace's, then `'immutable'` and `'warn'` (2026-10-12), so
  * by default any such write withholds the save, on CI too, since a
  * concurrent task can change an input and put it back.
  */
@@ -549,7 +582,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // The local executor keeps its own timer from the spawn (it signals the
   // process group), so its request carries no clock: armed here, it also
   // timed the sandbox's wrap, and a wrap slower than the timeout aborted
-  // the request before the spawn — a task reported killed, never run.
+  // the request before the spawn — a task reported killed, never run. So
+  // does an executor that declares `timeouts`.
   let timeoutTimer: ReturnType<typeof setTimeout> | undefined
   let timeoutFired = false
   // The attempt's listener on the run's stop signal, taken off once the
@@ -570,7 +604,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     }
     clearTimeout(timeoutTimer)
     timeoutFired = false
-    if (effectiveTimeout !== undefined && !local) {
+    if (effectiveTimeout !== undefined && !local && args.executor.timeouts !== true) {
       timeoutTimer = setTimeout(() => {
         timeoutFired = true
         stop.abort(new Error(`timed out after ${effectiveTimeout}ms`))
@@ -598,7 +632,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
           const why = timeoutFired ? `timeout (${effectiveTimeout}ms)` : 'stop'
           log.taskStderr(
             node,
-            `vx: ${executorLabel(args.executor)} did not return within ${graceMs}ms of the ${why}; abandoned\n`,
+            `${midLine ? '\n' : ''}vx: ${executorLabel(args.executor)} did not return within ${graceMs}ms of the ${why}; abandoned\n`,
           )
           const reason: unknown = signal.reason
           resolve({
@@ -702,8 +736,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   let wsStampedBefore: ReadonlyMap<string, OutputStamp> | undefined
   // `cache.outputs.clean: false` leaves the outputs to the first attempt's
   // command, and the save stores whatever they hold after it, a leftover
-  // included: the user opted out of the clean-tree guarantee (M,
-  // 2026-10-15). A retry still starts clean. An additive task never cleans
+  // included: the user opted out of the clean-tree guarantee
+  // (2026-10-15). A retry still starts clean. An additive task never cleans
   // by glob anyway.
   const keepOutputs = !additive && (cacheCfg?.outputs.clean ?? args.cleanOutputs ?? true) === false
 
@@ -797,11 +831,13 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     for (const c of captured)
       if (c.kind === 'env' && named.includes(c.name) && !secretNamed(c.name))
         c.hash = MASKED + c.hash
+  // The values of secret-named variables, masked in what the task prints
+  // and what the cache keeps of it (L-11); null when there are none.
+  const secrets = secretMask([process.env, env, step.env?.define], step.env?.secret)
   // A runtime probe's row is named by its command, which a TS config may
   // build from `process.env`: the run history stored it and `vx why`
   // printed it (L-11).
-  const nameSecrets =
-    captured.length > 0 ? secretMask([process.env, env, step.env?.define], step.env?.secret) : null
+  const nameSecrets = captured.length > 0 ? secrets : null
   if (nameSecrets !== null) {
     // Two probes that differ only by a secret mask to one name, and a row
     // is stored once per name: numbered, the second's change still shows.
@@ -829,7 +865,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   if (inputs !== undefined && declaredInputs.length > 0 && inputs.files.length === 0) {
     warnOf(log)(
       `[vx] ${node.id}: inputs matched no files (${declaredInputs.join(', ')}) — ` +
-        `the key will not change when this project's source does`,
+        `the key will not change when this project's source does` +
+        bracketLiteralHint([
+          ...(cfg.inputs?.files ?? []).map((g) => [node.projectDir, g] as const),
+          ...(cfg.inputs?.workspaceFiles ?? []).map((g) => [args.workspaceRoot, g] as const),
+        ]),
     )
   }
 
@@ -902,6 +942,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       const cleanedWsRels = await cleanWorkspaceOutputs(wsCleanArgs)
       args.gitFilesCache?.markWorkspaceOutputsChanged(args.workspaceRoot, cleanedWsRels)
     }
+    // What the attempt before this one left, put back if this one is
+    // withdrawn: it stands, with its output and its refusals.
+    const standing = { output, violations, flushMasked }
     violations = []
     const endReq = span('miss: build request')
     const req = await buildRequest(isLocalExecutor(args.executor))
@@ -910,6 +953,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // cleans or builds its request, after the loop's own check: the retry
     // is withdrawn and the attempt before it stands.
     if (attempt > 1 && args.failFast?.aborted === true) {
+      output = standing.output
+      violations = standing.violations
+      flushMasked = standing.flushMasked
       clearTimeout(timeoutTimer)
       unlistenStop?.()
       unlistenStop = undefined
@@ -931,6 +977,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         node.projectDir,
         commandWriteReach(node, args.workspaceRoot),
       ) ?? (() => {})
+    args.executing?.(node.id)
     try {
       running = Promise.resolve(args.executor.execute(req))
     } catch (thrown) {
@@ -950,8 +997,12 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
           const why = secrets?.mask(raw.message) ?? raw.message
           if (remoteOnly) {
             raw = new UserError(`${why}, and remote: 'only' keeps it off this machine`)
+          } else if (args.executor.exclusive === true) {
+            raw = new UserError(`${why}, and ${args.executor.name} runs no task on this machine`)
           } else {
-            warnOf(log)(`[vx] ${node.id}: ${why} — running it here`)
+            warnOf(log)(
+              `[vx] ${node.id}: ${executorLabel(args.executor)} gave it back: ${why} — running it here`,
+            )
             const local = await localExecutor().execute(await buildRequest(true))
             assertExecuteResult('local', node.id, local)
             return local
@@ -977,6 +1028,12 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         load = untrack?.() ?? load
         untrack = undefined
       })
+      .catch((thrown: unknown) => {
+        // The scheduler prints the throw's line into the task's stream,
+        // after the masked tail the finally above flushed.
+        if (midLine) log.taskStderr(node, '\n')
+        throw thrown
+      })
     endExec()
     if (secrets !== null)
       res = {
@@ -1016,7 +1073,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // before the strace pass shipped, false since, and the branch below is
     // live on Linux.) Violations surface via `TaskOutcome.sandboxViolationLines`.
     let code = res.exitCode
-    // ANY violation fails the task (owner, 2026-09-05). A sandboxed task
+    // ANY violation fails the task (2026-09-05). A sandboxed task
     // declares what it touches; a denial means it touched something else,
     // and an artifact built while reading — or failing to read — something
     // the cache key never folded is not a safe thing to replay. A task that
@@ -1032,7 +1089,10 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // 137 (item 1063).
     if (res.timedOut) {
       const how = res.signal === 'SIGKILL' ? 'SIGKILL after the SIGTERM grace' : 'SIGTERM'
-      log.taskStderr(node, `\n[vx] timed out after ${effectiveTimeout}ms — killed (${how})\n`)
+      log.taskStderr(
+        node,
+        `${midLine ? '\n' : ''}[vx] timed out after ${effectiveTimeout}ms — killed (${how})\n`,
+      )
       // Force a non-zero classification even if the child TRAPPED SIGTERM and
       // still exited 0 (`trap 'exit 0' TERM`, a common graceful-shutdown
       // pattern). Without this a timed-out task is classified `success` and its
@@ -1047,7 +1107,15 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // about what sent it (259). One frame line names the rule. A spawn that
     // threw ran no shell: its 127 is vx's, and the line would send the
     // reader after a command that exists (A-41). A run's stop killed it
-    // itself: the SIGKILL past the grace read as the OOM killer's.
+    // itself: the SIGKILL past the grace read as the OOM killer's. A
+    // SIGINT/SIGTERM death waits a turn for a pending handler first, as the
+    // shutdown check below does: a Ctrl-C reaches the child and vx together.
+    if (
+      !res.timedOut &&
+      (res.signal === 'SIGINT' || res.signal === 'SIGTERM') &&
+      args.stopSignal?.aborted !== true
+    )
+      await new Promise((resolve) => setTimeout(resolve, 0))
     if (!res.timedOut && res.spawnFailed !== true && args.stopSignal?.aborted !== true) {
       const verdict = shellVerdict({
         code,
@@ -1059,7 +1127,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       })
       // The line quotes the command's first word, which a config may have
       // built from a secret: masked as the task's own output is (L-37).
-      if (verdict !== undefined) log.taskStderr(node, `\n${secrets?.mask(verdict) ?? verdict}\n`)
+      if (verdict !== undefined)
+        log.taskStderr(node, `${midLine ? '\n' : ''}${secrets?.mask(verdict) ?? verdict}\n`)
     }
     return { result: res, exitCode: code }
   }
@@ -1075,7 +1144,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       await args.deferred.materializeFor(node)
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
-      log.taskStderr(node, `\n[vx] ${msg}\n`)
+      // Nothing ran: the note is the frame's first line.
+      log.taskStderr(node, `[vx] ${msg}\n`)
       return {
         node,
         status: 'failed',
@@ -1088,14 +1158,19 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     }
   }
 
-  // The values of secret-named variables, masked in what the task prints
-  // and what the cache keeps of it (L-11); null when there are none.
-  const secrets = secretMask([process.env, env, step.env?.define], step.env?.secret)
   let flushMasked = (): void => {}
+  // The attempt's output, both streams, last ended mid-line: vx's own line
+  // (a retry, a timeout, the shell's verdict, an abandoned or thrown
+  // executor) starts its own, and only then: a newline always before it
+  // printed a blank line under the OUTPUT rule or the task's last line. Glued, a frame read
+  // `partialvx: retrying …`.
+  let midLine = false
   // The attempt's output as the logger got it (masked): the entry's when
   // the task saves, else only what a failure reports (`failedOutput`).
   let output: BoundedCapture | undefined
-  const storedOutput = (): string => encodeOutputLog(output?.chunks() ?? [])
+  // Masked again whole: the live stream lets a held piece go after a pause.
+  const storeMask = secrets ?? undefined
+  const storedOutput = (): string => encodeOutputLog(output?.chunks() ?? [], storeMask)
   const failedAttempts: { endedAt: number; exitCode: number; timedOut?: true }[] = []
   // The sampling of the attempt's process tree, stopped once it settles.
   let untrack: (() => TreeLoad | undefined) | undefined
@@ -1184,7 +1259,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     })
     log.taskStderr(
       node,
-      `vx: retrying ${node.id} (attempt ${attempt + 1}/${maxAttempts}) after ${result.timedOut === true ? 'a timeout' : `exit ${effectiveExitCode}`}\n`,
+      `${midLine ? '\n' : ''}vx: retrying ${node.id} (attempt ${attempt + 1}/${maxAttempts}) after ${result.timedOut === true ? 'a timeout' : `exit ${effectiveExitCode}`}\n`,
     )
   }
 
@@ -1194,20 +1269,19 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         ? new BoundedCapture()
         : new BoundedCapture(FAILED_OUTPUT_HEAD_CHARS, FAILED_OUTPUT_TAIL_CHARS)
     output = kept
+    midLine = false
     const toOut = (t: string): void => {
       kept.push(t)
+      if (t.length > 0) midLine = !t.endsWith('\n')
       log.taskStdout(node, t)
     }
     const toErr = (t: string): void => {
       kept.push(t, true)
+      if (t.length > 0) midLine = !t.endsWith('\n')
       log.taskStderr(node, t)
     }
-    const out = secrets && maskedEmitter(secrets, toOut)
-    const err = secrets && maskedEmitter(secrets, toErr)
-    flushMasked = () => {
-      out?.end()
-      err?.end()
-    }
+    const masked = secrets && maskedStreams(secrets, toOut, toErr)
+    flushMasked = () => masked?.end()
     const base: ExecuteRequest = {
       taskId: node.id,
       workspaceRoot: args.workspaceRoot,
@@ -1217,8 +1291,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       env,
       envDefine: step.env?.define ?? {},
       capture,
-      onStdout: out ? (chunk) => out.push(chunk) : toOut,
-      onStderr: err ? (chunk) => err.push(chunk) : toErr,
+      onStdout: masked ? masked.out : toOut,
+      onStderr: masked ? masked.err : toErr,
       ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
       ...(args.track !== undefined
         ? {
@@ -1231,7 +1305,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       ...(effectiveTimeout !== undefined ? { timeoutMs: effectiveTimeout } : {}),
       ...(inputs !== undefined ? { inputs } : {}),
       ...(cfgCacheable ? { cacheKey: hash } : {}),
+      ...(cfgCacheable && !remoteOnly && !willSave ? { unsaved: true } : {}),
       ...(remoteOnly ? { remoteOnly: true } : {}),
+      ...(node.platform !== undefined ? { platform: node.platform } : {}),
       ...(deferralRequested ? { download: 'deferred' as const } : {}),
       // `--force`/`--no-cache` reach a remote executor's private record
       // through this flag — the policy gates above only cover vx's OWN cache.
@@ -1240,7 +1316,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       ...(args.terminal === true ? { terminal: true as const } : {}),
       ...(args.servers === undefined
         ? {}
-        : { servers: args.servers.map((s) => serverSpec(s, args.workspaceRoot)) }),
+        : {
+            servers: args.servers.map((s, i) =>
+              serverSpec(s, args.workspaceRoot, args.serversNested?.[i] ?? []),
+            ),
+          }),
     }
     // The signal last: it arms a plugin's `exec.timeout`, and the sandbox's arming
     // below is vx's work, not the task's. Armed first, a 60 ms timeout
@@ -1267,7 +1347,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   let movedFails: string | undefined
   let own: Awaited<ReturnType<typeof ownOutputs>>
   let saved = false
-  if (effectiveExitCode === 0 && willSave && deferralRequested) {
+  if (
+    effectiveExitCode === 0 &&
+    willSave &&
+    (deferralRequested || result.outputs?.kind === 'deferred')
+  ) {
     // The outputs never landed here: no artifact, no rows. A partial local
     // record (a row with no artifact) is exactly the corrupt-entry shape
     // `restoreOutputs` refuses, so writing none is the only clean answer.
@@ -1393,6 +1477,12 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
    */
   async function movedSinceKey(): Promise<string | null | undefined> {
     if (described!.hash !== hash) return null
+    // Changed where an executor ran it: this disk never shows it.
+    if (result.changed !== undefined && result.changed.length > 0) {
+      const changed = new Set(result.changed.map((f) => path.join(args.workspaceRoot, f)))
+      const there = keyedInputs(described!.facts).find((f) => changed.has(f.path))
+      if (there !== undefined) return there.path
+    }
     return (
       (await movedInput(
         keyedInputs(described!.facts),
@@ -1483,7 +1573,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     ...(keylessBy !== undefined ? { keylessBy } : {}),
     ...(saved ? { saved: true as const } : {}),
     ...(effectiveExitCode !== 0 && output !== undefined
-      ? { failedOutput: failedOutputLog(output, willSave || args.keepRun !== undefined) }
+      ? { failedOutput: failedOutputLog(output, willSave || args.keepRun !== undefined, storeMask) }
       : {}),
     ...(args.keepRun !== undefined &&
     (effectiveExitCode !== 0 ? args.keepRun.failures : !willSave) &&
@@ -1497,11 +1587,13 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     ...(load !== undefined ? { peakCores: load.peakCores, avgRssBytes: load.avgRssBytes } : {}),
     ...(result.where !== undefined ? { where: result.where } : {}),
     ...(result.where !== undefined && result.machine !== undefined
-      ? { whereCores: result.machine.cores, whereMemoryBytes: result.machine.memoryBytes }
-      : {}),
-    ...(deferralRequested && result.outputs?.kind === 'deferred'
-      ? { outputs: 'deferred' as const }
+      ? {
+          whereCores: result.machine.cores,
+          whereMemoryBytes: result.machine.memoryBytes,
+          ...(result.machine.cpuShare === undefined ? {} : { cpuShare: result.machine.cpuShare }),
+        }
       : {}),
+    ...(result.outputs?.kind === 'deferred' ? { outputs: 'deferred' as const } : {}),
     wallclockStartNs,
     wallclockEndNs,
     ...(finalViolations.length > 0

package/src/orchestrator/fingerprint-watch.ts

@@ -85,7 +85,7 @@ export class FingerprintWatch {
     this.said = true
     warnOf(log)(
       `[vx] a task rewrote \`${this.movedFiles.join('`, `')}\` during the run, which a plugin ` +
-        `folds into every key: nothing keyed before it is restored or saved from here on`,
+        `puts into every key: nothing keyed before it is restored or saved from here on`,
     )
   }
 }

package/src/orchestrator/graph-memo.ts

@@ -0,0 +1,140 @@
+// The task graph memo: the graph a run built, read back whole when nothing
+// it is built from has moved. Building 1,206 tasks' graph was 4.5 ms of a
+// warm run (2026-10-23), nearly all of it code a short process runs cold;
+// reading it back is half that.
+//
+// A run's configs come from the lock and nowhere else when no plugin fills
+// the `project` stage, so the token names them by the lock's bytes instead
+// of serializing them (3 ms at 1,206 tasks): the bytes, the projects
+// discovered and loaded, their package edges, the requested tasks, the
+// rules, the root and the code are everything `buildTaskGraph` reads. A
+// scoped load hands undeclared `^name`s back instead of refusing them, so
+// it is never remembered.
+
+import type { FoldMemo } from '../cache/index.js'
+import { buildTaskGraph, declaredTask, type TaskNode } from '../graph/index.js'
+import { xxh3hex } from '../util/index.js'
+import type { ProjectMeta } from '../workspace/index.js'
+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'
+
+/** What names a run's configs: the lock they were read from and the projects discovered. */
+export interface GraphMemo {
+  folds: FoldMemo
+  lock: string
+  metas: readonly ProjectMeta[]
+}
+
+/**
+ * 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.
+ */
+type Row = [
+  project: string,
+  task: string,
+  requested: 0 | 1,
+  deps: number[],
+  adds?: number[] | null,
+  added?: string[] | null,
+]
+
+/**
+ * `buildTaskGraph`, answered from the memo when it built this graph before,
+ * and the token that names the graph (undefined when not remembered).
+ */
+export function memoGraph(
+  options: BuildGraphOptions,
+  memo: GraphMemo | undefined,
+): { nodes: Map<string, TaskNode>; token: string | undefined } {
+  if (memo === undefined || options.undeclaredDeps !== undefined) {
+    return { nodes: buildTaskGraph(options), token: undefined }
+  }
+  const { projects, packageGraph } = options
+  const parts: string[] = [
+    GRAPH_MEMO_VERSION,
+    codeIdentity(),
+    memo.lock,
+    options.workspaceRoot ?? '',
+    JSON.stringify(options.rules ?? null),
+    String(packageGraph.edgeSource),
+    JSON.stringify(options.requested),
+  ]
+  for (const m of memo.metas) {
+    parts.push(
+      m.name,
+      m.dir,
+      m.configPath ?? '\u0001',
+      packageGraph.directDeps(m.name).join('\u0001'),
+    )
+  }
+  for (const name of projects.keys()) parts.push(name)
+  const id = `\0graph\0${xxh3hex(JSON.stringify(options.requested))}`
+  const token = xxh3hex(parts.join('\0'))
+  const row = memo.folds.get(id, token)
+  if (row !== undefined) {
+    const nodes = rebuilt(row, projects)
+    if (nodes !== undefined) return { nodes, token }
+  }
+  const nodes = buildTaskGraph(options)
+  memo.folds.set(id, token, JSON.stringify(rowsOf(nodes)))
+  return { nodes, token }
+}
+
+function rowsOf(nodes: Map<string, TaskNode>): Row[] {
+  const at = new Map<string, number>()
+  for (const id of nodes.keys()) at.set(id, at.size)
+  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)
+      row.push(
+        n.addsToOutputsOf === undefined ? null : pos(n.addsToOutputsOf),
+        n.outputsAddedToBy ?? null,
+      )
+    return row
+  })
+}
+
+function rebuilt(
+  row: string,
+  projects: BuildGraphOptions['projects'],
+): Map<string, TaskNode> | undefined {
+  let rows: Row[]
+  try {
+    rows = JSON.parse(row)
+  } catch {
+    return undefined
+  }
+  const list: TaskNode[] = []
+  for (const [projectName, taskName, requested] of rows) {
+    const project = projects.get(projectName)
+    const config = declaredTask(project?.config, taskName)
+    if (project === undefined || config === undefined) return undefined
+    list.push({
+      id: `${projectName}#${taskName}`,
+      projectName,
+      projectDir: project.dir,
+      taskName,
+      config,
+      deps: [],
+      requested: requested === 1,
+    })
+  }
+  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 node = list[i]!
+    node.deps = ids(deps)
+    if (adds != null) node.addsToOutputsOf = ids(adds)
+    if (added != null) node.outputsAddedToBy = added
+    nodes.set(node.id, node)
+  }
+  return nodes
+}

package/src/orchestrator/graph-stage.ts

@@ -2,11 +2,13 @@
 // CLI's `--affected` task selection (`vx show <task> --affected`), so both
 // select over the graph the hooks leave.
 
+import path from 'node:path'
 import type { GraphRules, 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'
 import type { VxPlugin } from './plugin.js'
-import { isDefaultBuild } from './projects.js'
+import { isDefaultBuild } from '../graph/index.js'
 
 export async function applyGraphStage(
   plugins: readonly VxPlugin[],
@@ -23,6 +25,10 @@ export async function applyGraphStage(
   // edit is held to what the loader accepts from a user: a misspelled
   // `exec` field ran as an empty command and failed with no reason.
   const configPaths = new Map(args.projectMetas.map((m) => [m.name, m.configPath]))
+  // A node under a directory no project owns, or another project's, ran,
+  // keyed and cleaned its outputs there: past the hard project boundary.
+  const dirs = new Map(args.projectMetas.map((m) => [m.name, path.resolve(m.dir)]))
+  const shown = (dir: string): string => relPosix(args.workspaceRoot, dir) || '.'
   await applyGraphHooks(
     plugins,
     nodes,
@@ -34,6 +40,17 @@ export async function applyGraphStage(
     },
     (plugin) => {
       for (const n of nodes.values()) {
+        const dir = dirs.get(n.projectName)
+        if (dir === undefined) {
+          throw new UserError(
+            `plugin '${plugin.name}' failed in graph: ${n.id}'s project ${n.projectName} is not a project in this workspace`,
+          )
+        }
+        if (path.resolve(n.projectDir) !== dir) {
+          throw new UserError(
+            `plugin '${plugin.name}' failed in graph: ${n.id}'s projectDir is ${shown(n.projectDir)}, not project ${n.projectName}'s directory ${shown(dir)}`,
+          )
+        }
         if (isDefaultBuild(n.config)) continue
         const own = configPaths.get(n.projectName) ?? null
         validateProjectConfig(

package/src/orchestrator/held-servers.ts

@@ -1,7 +1,7 @@
 // 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 (M 2026-10-22), as it never starts behind local hits.
+// 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'