@vzn/vx 0.0.21 → 0.0.22

package/src/orchestrator/miss-save.ts

@@ -37,6 +37,13 @@ export interface SaveMissArgs {
   /** Declared `cache.outputs.files` / `.workspaceFiles`. */
   outputs: string[]
   wsOutputs: string[]
+  /**
+   * An ADDITIVE task's own set (item 588): the files its run added or
+   * changed under its declared outputs, resolved by execute-task against
+   * the stamp it took before the run. Replaces the glob walk below, which
+   * would also take the upstream's files the task adds beside.
+   */
+  ownOutputFiles?: string[] | undefined
   /** The Tier-3 input fingerprint rows captured by the pre-exec describe. */
   captured: readonly TaskInputComponent[]
   command: string
@@ -60,11 +67,13 @@ export interface SaveMissArgs {
 export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void> }> {
   const { node, cache, log } = a
   const endResolve = span('miss: resolve outputs')
-  const outputFiles = await resolveOutputs({
-    projectDir: node.projectDir,
-    outputs: a.outputs,
-    nestedProjectDirs: a.nestedProjectDirs,
-  })
+  const outputFiles =
+    a.ownOutputFiles ??
+    (await resolveOutputs({
+      projectDir: node.projectDir,
+      outputs: a.outputs,
+      nestedProjectDirs: a.nestedProjectDirs,
+    }))
   const wsOutputFiles = await resolveWorkspaceOutputs({
     workspaceRoot: a.workspaceRoot,
     outputs: a.wsOutputs,
@@ -79,9 +88,22 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void>
     a.outputs.length + a.wsOutputs.length > 0 &&
     outputFiles.length + wsOutputFiles.length === 0
   ) {
+    // One cause is common enough to name, because the task shows no other
+    // symptom: a sandboxed task with no write grant. Its writes land in the
+    // sandbox's own scratch and never reach disk, and whether the shell
+    // even notices depends on the layout — in a single-package workspace
+    // (project dir === workspace root) the write SUCCEEDS into that
+    // scratch and the task exits 0, so this warning is the only thing that
+    // says the build produced nothing (item 444). A declared
+    // `cache.outputs` is not a write grant; `exec.sandbox.allow.write` is.
+    const sandboxed = node.config.exec?.sandbox !== undefined
+    const grantsWrite = (node.config.exec?.sandbox?.allow?.write?.length ?? 0) > 0
     log.status(
       `[vx] ${node.id}: cache.outputs matched no files (${[...a.outputs, ...a.wsOutputs].join(', ')}) — ` +
-        `an empty artifact is saved; a later hit restores nothing`,
+        `an empty artifact is saved; a later hit restores nothing` +
+        (sandboxed && !grantsWrite
+          ? ` — the task is sandboxed and declares no exec.sandbox.allow.write, so its writes never reached disk`
+          : ''),
     )
   }
   const save = async (): Promise<void> => {
@@ -110,60 +132,101 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void>
       },
     })
     endSave()
-    // The directory snapshot behind the next hit's skip-restore. Taken at
-    // run end when the run keeps a list: the task wrote these directories
+    // The files the task just wrote are the entry's bytes: stamp them,
+    // so the next hit can tell them from another entry's with the same
+    // size and mtime (item 886).
+    cache.recordOutputStamps?.(a.hash, node.projectDir, a.workspaceRoot)
+    // The directory snapshot behind the next hit's skip-restore, taken at
+    // run end from the run's list: the task wrote these directories
     // milliseconds ago, inside the snapshot's racy window, so a snapshot
     // taken here was refused and the next hit walked every output tree —
     // 1,000 walks, 296 ms accumulated, on the first warm run after a cold
-    // build of the 1,000-project bench (2026-09-10).
+    // build of the 1,000-project bench (2026-09-10). A caller with no
+    // list gets no snapshot: recording here was that same refusal (item
+    // 637 deleted the fallback and nothing reddened), and the next hit
+    // walks, as it did.
     const savedDirPrefixes = wholeSubtreePrefixes(a.outputs)
-    if (savedDirPrefixes !== null) {
-      if (a.outputDirSnapshots !== undefined) {
-        a.outputDirSnapshots.push({
-          hash: a.hash,
-          projectDir: node.projectDir,
-          prefixes: savedDirPrefixes,
-        })
-      } else {
-        await cache.recordOutputDirs?.(a.hash, node.projectDir, savedDirPrefixes)
-      }
+    if (savedDirPrefixes !== null && a.outputDirSnapshots !== undefined) {
+      a.outputDirSnapshots.push({
+        hash: a.hash,
+        projectDir: node.projectDir,
+        prefixes: savedDirPrefixes,
+      })
     }
   }
-  // This task just wrote outputs to the project's tree. Record the
-  // exact declared-output paths as changed (same as the cache-hit
-  // restore path) instead of dropping the whole snapshot: a downstream
-  // same-project task then re-spawns git ONLY when its input globs can
-  // actually see one of these paths. On a 1000-package cold run this
-  // removes ~one synchronous `git ls-files` spawn per project (the
-  // single largest cold-run cost — 22% of CPU in profiling). Contract:
-  // outputs must be declared — an executed task that writes files
-  // outside `cache.outputs.files` which a same-project downstream task
-  // reads is undeclared behavior (the restore path already assumes it).
+  markWritten(a, outputFiles, wsOutputFiles)
+  // Off the slot when the run keeps a lane (the save lane bounds and
+  // drains it); in the slot otherwise — an embedder without a lane gets
+  // the entry before the outcome.
+  if (a.deferSave !== undefined) return { landed: a.deferSave(save) }
+  await save()
+  return { landed: Promise.resolve() }
+}
+
+/** What `markUnsaved` reads of a miss: where its declared outputs are. */
+export type UnsavedArgs = Pick<
+  SaveMissArgs,
+  'node' | 'workspaceRoot' | 'nestedProjectDirs' | 'gitFilesCache' | 'outputs' | 'wsOutputs'
+>
+
+/**
+ * A miss that ran here and saves nothing (it failed, the policy writes
+ * nothing, an upstream failed, its key no longer held) still wrote its
+ * outputs, and a same-project reader after it must see them as it sees a
+ * save's: resolved and marked the same way.
+ */
+export async function markUnsaved(a: UnsavedArgs): Promise<void> {
+  const endResolve = span('miss: resolve outputs')
+  const outputFiles = await resolveOutputs({
+    projectDir: a.node.projectDir,
+    outputs: a.outputs,
+    nestedProjectDirs: a.nestedProjectDirs,
+  })
+  const wsOutputFiles = await resolveWorkspaceOutputs({
+    workspaceRoot: a.workspaceRoot,
+    outputs: a.wsOutputs,
+  })
+  endResolve()
+  markWritten(a, outputFiles, wsOutputFiles)
+}
+
+/**
+ * The task just wrote outputs to the project's tree. Record the exact
+ * declared-output paths as changed (same as the cache-hit restore path)
+ * instead of dropping the whole snapshot: a downstream same-project task
+ * then re-spawns git ONLY when its input globs can actually see one of
+ * these paths. On a 1000-package cold run this removes ~one synchronous
+ * `git ls-files` spawn per project (the single largest cold-run cost —
+ * 22% of CPU in profiling). Contract: outputs must be declared — an
+ * executed task that writes files outside `cache.outputs.files` which a
+ * same-project downstream task reads is undeclared behavior (the restore
+ * path already assumes it).
+ */
+function markWritten(
+  a: Pick<SaveMissArgs, 'node' | 'workspaceRoot' | 'gitFilesCache'>,
+  outputFiles: readonly string[],
+  wsOutputFiles: readonly string[],
+): void {
+  const { projectDir } = a.node
   if (outputFiles.length > 0) {
     a.gitFilesCache?.markOutputsChanged(
-      node.projectDir,
-      outputFiles.map((p) => path.relative(node.projectDir, p).split(path.sep).join('/')),
+      projectDir,
+      outputFiles.map((p) => path.relative(projectDir, p).split(path.sep).join('/')),
     )
   }
-  // Declared workspace outputs may have landed inside OTHER
-  // projects' dirs (no-boundary escape hatch) — mark the exact
-  // paths against every partition that can see them.
+  // Declared workspace outputs may have landed inside OTHER projects' dirs
+  // (no-boundary escape hatch) — mark the exact paths against every
+  // partition that can see them.
   if (wsOutputFiles.length > 0) {
     a.gitFilesCache?.markWorkspaceOutputsChanged(
       a.workspaceRoot,
       wsOutputFiles.map((f) => path.relative(a.workspaceRoot, f).split(path.sep).join('/')),
     )
   }
-  // The workspace-wide partition (when one exists) spans this
-  // project's subtree, so it inherits the same "undeclared writes
-  // are only visible to git" rule as the project drop above.
+  // The workspace-wide partition (when one exists) spans this project's
+  // subtree, so it inherits the same "undeclared writes are only visible
+  // to git" rule as the project drop above.
   if (outputFiles.length + wsOutputFiles.length > 0) {
     a.gitFilesCache?.invalidateWorkspacePartition()
   }
-  // Off the slot when the run keeps a lane (the save lane bounds and
-  // drains it); in the slot otherwise — an embedder without a lane gets
-  // the entry before the outcome.
-  if (a.deferSave !== undefined) return { landed: a.deferSave(save) }
-  await save()
-  return { landed: Promise.resolve() }
 }

package/src/orchestrator/options.ts

@@ -139,16 +139,18 @@ export interface RunOptions {
    */
   profile?: string
   /**
-   * Install SIGINT/SIGTERM handlers for the run's duration: forward
-   * SIGTERM to every live child, close the cache, exit 128+signo
-   * (130/143). Default true. The watch loop disables this — it owns
+   * Install SIGINT/SIGTERM handlers for the run's duration: forward the
+   * signal received to every live child's group (a SIGHUP as SIGTERM),
+   * close the cache, exit 128+signo (130/143). Default true. The watch loop disables this — it owns
    * signal disposition for its whole lifetime and a cycle must never
    * exit the process out from under it.
    */
   handleSignals?: boolean
   /**
    * Abort the run from outside. On `abort` every live and persistent
-   * child is SIGTERMed, given the kill grace, then SIGKILLed; nothing
+   * child is sent SIGINT when the abort reason is `'SIGINT'` (a Ctrl-C
+   * the embedder received), SIGTERM otherwise, given the kill grace,
+   * then SIGKILLed; nothing
    * further is dispatched; run() returns with the killed tasks and the
    * never-started ones `aborted`. The seam for an embedder that owns its
    * process's lifetime instead of `handleSignals` — the watch loop aborts
@@ -156,6 +158,14 @@ export interface RunOptions {
    * never orphans a cycle's children.
    */
   signal?: AbortSignal
+  /**
+   * Hand the requested persistent tasks still running back on
+   * `RunSummary.persistent` instead of stopping them when the graph ends.
+   * The caller owns them from then on and stops them with its `stop()`.
+   * The watch loop sets this: a dev server stays up while watch idles and
+   * is replaced only when the next cycle starts.
+   */
+  holdPersistent?: boolean
   log?: Logger
   /**
    * Inject the run's event bus. When provided, the orchestrator emits
@@ -210,9 +220,25 @@ export interface RunOptions {
    * declares a cache plugin). Undefined → identical to before.
    */
   remoteCache?: RemoteCacheLayer
+  /**
+   * The largest artifact, decoded, the local cache saves, ingests or
+   * restores; default 2 GiB. A seam for a test, which cannot produce 2 GiB
+   * of output to prove the refusal: the CLI never sets it, and no config
+   * or variable reaches it.
+   */
+  artifactCeiling?: number
 }
 
 export interface RunSummary {
   ok: boolean
   outcomes: TaskOutcome[]
+  /** The persistent tasks `RunOptions.holdPersistent` handed back; absent when none is running. */
+  persistent?: HeldPersistent
+}
+
+export interface HeldPersistent {
+  /** The held tasks' ids, `pkg#task`. */
+  ids: readonly string[]
+  /** Send every held task `signal` (default SIGTERM), then SIGKILL after the kill grace; resolves once each is gone. */
+  stop(signal?: 'SIGINT' | 'SIGTERM'): Promise<void>
 }

package/src/orchestrator/persistent.ts

@@ -5,6 +5,7 @@
 
 import type { TaskNode } from '../graph/index.js'
 import { killGraceMs } from '../util/index.js'
+import { holdGroups, killTree, untilGroupsGone } from '../exec/index.js'
 
 type Child = ReturnType<typeof Bun.spawn>
 
@@ -14,7 +15,7 @@ type Child = ReturnType<typeof Bun.spawn>
  * hang a normal run at completion. Well-behaved servers exit far under
  * this, so the happy path never waits it out.
  */
-export const PERSISTENT_SHUTDOWN_GRACE_MS = 2000
+const PERSISTENT_SHUTDOWN_GRACE_MS = 2000
 
 export interface KeepAlive {
   nodes: TaskNode[]
@@ -48,32 +49,51 @@ export function selectKeepAlive(
 /**
  * SIGTERM every persistent child not kept alive and wait for them, bounded:
  * SIGTERM gives well-behaved servers (vite, next, esbuild --watch) a moment
- * to clean up; past the grace the stragglers are SIGKILLed so the run's
- * normal completion cannot hang on one that traps the signal. Bun's
- * `kill` is idempotent on an exited child; the timer is cleared and
- * unref'd so a fast shutdown never delays CLI exit.
+ * to clean up; past the grace every group with a member left is SIGKILLed,
+ * so the run's normal completion cannot hang on one that traps the signal.
+ * The GROUP, not the leader: a `server & wait` shell dies on the SIGTERM
+ * while a server that ignores it lives on, holding the task's pipe, and
+ * vx printed its summary and never exited (nx#8286 reproduced on vx,
+ * 2026-09-24).
  */
 export async function shutdownPersistent(
   registry: ReadonlyMap<string, Child>,
   keepAlive: readonly Child[],
   graceMs: number = killGraceMs(PERSISTENT_SHUTDOWN_GRACE_MS),
-): Promise<void> {
+): Promise<CrashedPersistent[]> {
   const kept = new Set(keepAlive)
+  const crashed: CrashedPersistent[] = []
+  for (const [id, child] of registry) {
+    if (kept.has(child) || !hasEnded(child) || child.exitCode === 0) continue
+    crashed.push({ id, code: child.exitCode ?? child.signalCode ?? 'unknown' })
+  }
   const dying = [...registry.values()].filter((c) => !kept.has(c))
-  if (dying.length === 0) return
-  for (const child of dying) child.kill('SIGTERM')
-  const allExited = Promise.allSettled(dying.map((c) => c.exited))
-  let graceTimer: ReturnType<typeof setTimeout> | undefined
-  const winner = await Promise.race([
-    allExited.then(() => 'exited' as const),
-    new Promise<'grace'>((resolve) => {
-      graceTimer = setTimeout(() => resolve('grace'), graceMs)
-      graceTimer.unref?.()
-    }),
-  ])
-  if (graceTimer !== undefined) clearTimeout(graceTimer)
-  if (winner === 'grace') {
-    for (const child of dying) child.kill('SIGKILL')
-    await allExited
+  if (dying.length === 0) return crashed
+  const letGo = holdGroups(dying)
+  try {
+    for (const child of dying) killTree(child, 'SIGTERM')
+    for (const child of await untilGroupsGone(dying, graceMs)) killTree(child, 'SIGKILL')
+    await Promise.allSettled(dying.map((c) => c.exited))
+  } finally {
+    letGo()
   }
+  return crashed
+}
+
+/**
+ * A dependency-only persistent task that ended on its own, not by the stop
+ * at the end of the graph, and not cleanly. Its dependants may still have
+ * passed, and until item 892 the run did too: the server was reported
+ * `success` and its crash was said nowhere, while a requested server's
+ * crash failed the run.
+ */
+export interface CrashedPersistent {
+  id: string
+  /** The exit code, or the signal that killed it. */
+  code: number | string
+}
+
+/** The child has exited or been killed; Bun sets these once it reaps it. */
+export function hasEnded(child: Child): boolean {
+  return child.exitCode !== null || child.signalCode !== null
 }

package/src/orchestrator/placement.ts

@@ -1,9 +1,9 @@
 // Where each task runs: the placement of a graph over the resolved
 // executors, and the plan-mode view of it. Split from run.ts on 2026-09-10
 // (pure motion). A task is pinned to this machine when it is persistent,
-// depends on a persistent task, or says `exec.remote: false`; everything
-// else asks the executors in declaration order, and the local floor takes
-// what nothing claimed.
+// depends on a persistent task, is sandboxed, or says `exec.remote: false`;
+// everything else asks the executors in declaration order, and the local
+// floor takes what nothing claimed.
 
 import { machineParallelism } from '../util/index.js'
 import { selectExecutor, type TaskExecutor } from '../exec/index.js'
@@ -16,26 +16,42 @@ import type { prepareRun } from './prepare.js'
 /**
  * A task is pinned to this machine when it is persistent, transitively
  * depends on a persistent task (a worker cannot reach a port on the
- * submitter), or declares `exec.remote: false`.
+ * submitter), declares `exec.sandbox` (the sandbox is this machine's
+ * machinery — a worker has none of it, and a boundary "verified" where it
+ * is not enforced passes vacuously), or declares `exec.remote: false`. A
+ * dependant of a pinned task is pinned with it.
  */
 export function pinnedLocalSet(nodes: Map<string, TaskNode>): Set<string> {
   const pinned = new Set<string>()
-  const memo = new Map<string, boolean>()
-  const visit = (id: string): boolean => {
-    const known = memo.get(id)
-    if (known !== undefined) return known
-    const node = nodes.get(id)
-    if (node === undefined) return false
-    memo.set(id, false) // cycle guard; the graph builder already rejects cycles
-    const result =
+  for (const node of nodes.values()) {
+    if (
       node.config.exec?.persistent !== undefined ||
-      node.config.exec?.remote === false ||
-      node.deps.some((d) => visit(d))
-    memo.set(id, result)
-    if (result) pinned.add(id)
-    return result
+      node.config.exec?.sandbox !== undefined ||
+      node.config.exec?.remote === false
+    ) {
+      pinned.add(node.id)
+    }
+  }
+  if (pinned.size === 0) return pinned
+  // Pinning flows up the dependant edges from what pins itself, one walk on
+  // an explicit stack: a chain is as deep as the graph, and a recursion
+  // per edge threw `RangeError` on the 50,000 the builder takes (item 737).
+  const dependants = new Map<string, string[]>()
+  for (const node of nodes.values()) {
+    for (const dep of node.deps) {
+      const list = dependants.get(dep)
+      if (list === undefined) dependants.set(dep, [node.id])
+      else list.push(node.id)
+    }
+  }
+  const stack = [...pinned]
+  while (stack.length > 0) {
+    for (const up of dependants.get(stack.pop()!) ?? []) {
+      if (pinned.has(up)) continue
+      pinned.add(up)
+      stack.push(up)
+    }
   }
-  for (const id of nodes.keys()) visit(id)
   return pinned
 }
 
@@ -53,10 +69,28 @@ export interface Placements {
   remoteOnly: Set<string>
 }
 
+/**
+ * The tasks that write IN PLACE — everything not placed on a remote
+ * executor. `resolveDownloadModes` reads it as "the outputs are already
+ * here", so a task wrongly left out is one vx thinks it must fetch from a
+ * CAS that never held it.
+ *
+ * `remote` is a THREE-state field: `true` (remote), `false` (an explicit
+ * local plugin) and undefined — which is core's own local floor, since
+ * `localExecutor()` declares no `remote` at all. So the question is "not
+ * remote", never "declared local"; asking the latter drops every task on
+ * the floor executor, i.e. every task in a workspace with no executor
+ * plugin. It lives here, shared, because `run()` and `--dry` each built
+ * this set inline from the same predicate and a second copy is how the
+ * plan and the run would disagree about what comes home (441, 442, 445).
+ */
+export function locallyPlaced(placements: Placements, ids: Iterable<string>): Set<string> {
+  return new Set([...ids].filter((id) => placements.executors.get(id)?.remote !== true))
+}
+
 export function placeTasks(
   nodes: Map<string, TaskNode>,
   executors: readonly TaskExecutor[],
-  pinAllLocal = false,
 ): Placements {
   const pinned = pinnedLocalSet(nodes)
   const placements: Placements = {
@@ -71,7 +105,7 @@ export function placeTasks(
       projectName: node.projectName,
       projectDir: node.projectDir,
       command: node.config.exec!.command,
-      pinnedLocal: pinAllLocal || pinned.has(node.id),
+      pinnedLocal: pinned.has(node.id),
       cacheable: node.config.cache !== undefined,
     })
     placements.executors.set(node.id, executor)
@@ -126,11 +160,7 @@ export async function planExecutorOf(
       : resolveDownloadModes({
           nodes: prepared.nodes,
           policy,
-          localPlaced: new Set(
-            [...prepared.nodes.keys()].filter(
-              (id) => placements.executors.get(id)?.remote !== true,
-            ),
-          ),
+          localPlaced: locallyPlaced(placements, prepared.nodes.keys()),
           remoteOnly: placements.remoteOnly,
         })
   return {

package/src/orchestrator/plan.ts

@@ -16,6 +16,7 @@ import { FULL_CACHE_POLICY } from '../cache/index.js'
 import { isGroupTask, runGraph, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import type { HistoryProvider } from './history.js'
 import { computeGroupHash, computeTaskHash } from './task-hash.js'
+import { keyUpstream } from './upstream.js'
 
 export type CacheStatus =
   | 'hit-local' // entry exists in local cache
@@ -124,11 +125,20 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
   const outcomes = await runGraph({
     nodes: args.nodes,
     concurrency: 1,
-    execute: async (node, upstream) => {
+    execute: async (node, live) => {
+      const upstream = keyUpstream(node, live)
       if (isGroupTask(node)) {
         cacheStatusById.set(node.id, 'group')
         return planOutcome(node, computeGroupHash(upstream))
       }
+      // A persistent task has no key on the live path (its outcome carries
+      // none, `stable-keys.ts`), so a dependant folds nothing for it. The
+      // plan keyed it and folded that, and `--dry` then called a dependant
+      // a miss under a key the run never looks up (item 766).
+      if (node.config.exec?.persistent !== undefined) {
+        cacheStatusById.set(node.id, 'no-cache')
+        return planOutcome(node, undefined)
+      }
 
       const hash = await computeTaskHash({
         node,
@@ -142,17 +152,20 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
         ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
       })
 
-      // Prediction keys off READS: a no-read policy (--no-cache /
-      // --force / --cache=local:,remote:) would re-execute every task,
-      // so we predict misses for it. The probe below routes through the
-      // policy-aware cache layer, which itself respects local/remote
-      // read gating.
+      // Prediction keys off READS: a no-read policy re-executes every task,
+      // so nothing is probed. Whether that run is a miss or no cache at all
+      // is the WRITE axes': `--force` and `--cache=local:w` save what they
+      // run, and the plan called them `no-cache`, the label a task with no
+      // `cache` block gets (item 991). The probe below routes through the
+      // policy-aware cache layer, which itself respects read gating.
       const policy = args.cachePolicy ?? FULL_CACHE_POLICY
-      const cacheEnabled =
-        node.config.cache !== undefined && (policy.localRead || policy.remoteRead)
+      const reads = policy.localRead || policy.remoteRead
+      const writes = policy.localWrite || policy.remoteWrite
       let status: CacheStatus
-      if (!cacheEnabled) {
+      if (node.config.cache === undefined || (!reads && !writes)) {
         status = 'no-cache'
+      } else if (!reads) {
+        status = 'miss'
       } else {
         const where = await args.cache.has(hash)
         status = where === null ? 'miss' : where === 'remote' ? 'hit-remote' : 'hit-local'
@@ -261,12 +274,12 @@ function predictPlan(tasks: PlannedTask[]): PlanPrediction {
   return { wallMs, workMs, unknownCount }
 }
 
-function planOutcome(node: TaskNode, hash: string): TaskOutcome {
+function planOutcome(node: TaskNode, hash: string | undefined): TaskOutcome {
   return {
     node,
     status: 'success',
     exitCode: 0,
     durationMs: 0,
-    hash,
+    ...(hash !== undefined ? { hash } : {}),
   }
 }

package/src/orchestrator/plugin-host.ts

@@ -11,7 +11,7 @@ import { ChainedCache, type CacheLayer } from '../cache/index.js'
 import { localExecutor, type TaskExecutor } from '../exec/index.js'
 import { settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
-import { detectCycle, type TaskNode } from '../graph/index.js'
+import { checkGraph, type TaskNode } from '../graph/index.js'
 import type {
   CacheContext,
   ExecutorContext,
@@ -25,13 +25,6 @@ import type {
   WorkspaceHookContext,
 } from './plugin.js'
 
-/**
- * Run a capability factory with crash isolation. A throw becomes a clean
- * `UserError` naming the plugin + hook: every stage and capability resolved
- * here is load-bearing, so a broken one must abort with a clear message,
- * never silently degrade. (Telemetry sinks are the observe-only exception,
- * and telemetry-host.ts logs-and-skips them instead.)
- */
 /** `a string`, `an array`, `null`, `a number` — for a refusal that names what came back. */
 function describeValue(v: unknown): string {
   if (v === null) return 'null'
@@ -40,7 +33,6 @@ function describeValue(v: unknown): string {
   return t === 'object' ? 'an object' : `a ${t}`
 }
 
-/** What a capability hook handed back must be what the seam runs. */
 /** Every method `CacheLayer` requires (the optional ones are probed with `?.`). */
 export const CACHE_LAYER_METHODS: readonly string[] = [
   'key',
@@ -60,6 +52,7 @@ export const CACHE_LAYER_METHODS: readonly string[] = [
   'close',
 ]
 
+/** What a capability hook handed back must be what the seam runs. */
 function assertShape(
   plugin: VxPlugin,
   hook: string,
@@ -78,6 +71,13 @@ function assertShape(
   )
 }
 
+/**
+ * Run a capability factory with crash isolation. A throw becomes a clean
+ * `UserError` naming the plugin + hook: every stage and capability resolved
+ * here is load-bearing, so a broken one must abort with a clear message,
+ * never silently degrade. (Telemetry sinks are the observe-only exception,
+ * and telemetry-host.ts logs-and-skips them instead.)
+ */
 async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>): Promise<T> {
   try {
     return await fn()
@@ -132,8 +132,9 @@ export async function applyProjectHooks(
 
 /**
  * `graph` stage: every plugin edits the task graph in place, then the graph
- * is checked ONCE the way the builder checks its own output — every dep
- * names a node in the graph, and there is no cycle. A violation is reported
+ * is checked ONCE the way the builder checks its own output (`checkGraph`:
+ * each node under its own id, every dep a node, no cycle, no two tasks
+ * deleting each other's outputs). A violation is reported
  * against the LAST plugin that ran: usually the one whose edit made it so,
  * but an earlier plugin's edit that a later one left in place is blamed on
  * the later one, since nothing is checked between plugins.
@@ -150,16 +151,7 @@ export async function applyGraphHooks(
     last = plugin
   }
   if (last === undefined) return
-  await safe(last, 'graph', () => {
-    for (const node of nodes.values()) {
-      for (const dep of node.deps) {
-        if (!nodes.has(dep)) {
-          throw new Error(`${node.id} depends on '${dep}', which is not a task in this run's graph`)
-        }
-      }
-    }
-    detectCycle(nodes)
-  })
+  await safe(last, 'graph', () => checkGraph(nodes))
 }
 
 /**
@@ -299,8 +291,10 @@ export function buildAdmission(
   if (answering.length === 0) return undefined
   const broken = new Set<VxPlugin>()
   return (id, running) => {
-    const task = nodes.get(id)
-    if (task === undefined) return true
+    // The scheduler asks only about ids in this same map, so the lookup
+    // always lands: an unknown-id arm here was deleted with the whole core
+    // suite green (item 651).
+    const task = nodes.get(id)!
     const ctx = {
       running: [...running].flatMap((r) => nodes.get(r) ?? []),
       concurrency,