@vzn/vx 0.0.591 → 0.0.595

package/src/orchestrator/logger.ts

@@ -318,7 +318,7 @@ export function defaultLogger(
   // for as long as vx holds it: `vx run dev --all` showed none of its
   // servers' logs while it ran (C-56). So a ready server's output streams
   // from then on, a line at a time under its id; the partial line each
-  // holds waits for its newline, a second runEnd, or `settle`.
+  // holds waits for its newline, a status line, a second runEnd, or `settle`.
   const KEPT_LINE_CAP = 64 * 1024
   const keptLines = new Map<string, { node: TaskNode; rest: string }>()
   const streamKept = (node: TaskNode, chunk: string): void => {
@@ -450,6 +450,9 @@ export function defaultLogger(
       writer.settle()
     },
     status(line) {
+      // A kept server's held partial line is older than this line: held
+      // past it, a server's last words printed below its own exit notice.
+      flushKept()
       writer.write(`${line}\n`)
     },
     runStart(info) {

package/src/orchestrator/miss-save.ts

@@ -17,7 +17,14 @@ import {
   WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
 import type { TaskNode } from '../graph/index.js'
-import { asTrees, span, staticPrefix, taskGlob, wholeSubtreePrefixes } from '../util/index.js'
+import {
+  asTrees,
+  relPosix,
+  span,
+  staticPrefix,
+  taskGlob,
+  wholeSubtreePrefixes,
+} from '../util/index.js'
 import type { Logger } from './logger.js'
 import type { TaskInputComponent } from './task-hash.js'
 
@@ -272,7 +279,7 @@ function markWritten(
   if (outputFiles.length > 0) {
     a.gitFilesCache?.markOutputsChanged(
       projectDir,
-      outputFiles.map((p) => path.relative(projectDir, p).split(path.sep).join('/')),
+      outputFiles.map((p) => relPosix(projectDir, p)),
     )
   }
   // Declared workspace outputs may have landed inside OTHER projects' dirs
@@ -281,7 +288,7 @@ function markWritten(
   if (wsOutputFiles.length > 0) {
     a.gitFilesCache?.markWorkspaceOutputsChanged(
       a.workspaceRoot,
-      wsOutputFiles.map((f) => path.relative(a.workspaceRoot, f).split(path.sep).join('/')),
+      wsOutputFiles.map((f) => relPosix(a.workspaceRoot, f)),
     )
   }
   // The workspace-wide partition (when one exists) spans this project's

package/src/orchestrator/placement.ts

@@ -281,13 +281,27 @@ export function hasPooledExecutor(executors: readonly TaskExecutor[]): boolean {
   return executors.some((e) => e.capacity !== undefined)
 }
 
+/**
+ * Each pooled executor's pool, under a name no other executor's pool
+ * shares: the scheduler counts a pool by its name, and one package declared
+ * twice (`@vzn/vx-reapi` against two clusters) names both executors alike,
+ * so their two capacities were one. A repeat takes `#2`, `#3` in placement
+ * order.
+ */
 export function poolOfPlacement(
   placements: Placements,
 ): (id: string) => { name: string; capacity: number } | undefined {
+  const pools = new Map<TaskExecutor, { name: string; capacity: number }>()
+  const taken = new Set<string>()
+  for (const executor of placements.executors.values()) {
+    if (executor.capacity === undefined || pools.has(executor)) continue
+    let name = executor.name
+    for (let n = 2; taken.has(name); n++) name = `${executor.name}#${n}`
+    taken.add(name)
+    pools.set(executor, { name, capacity: executor.capacity })
+  }
   return (id) => {
     const executor = placements.executors.get(id)
-    return executor?.capacity === undefined
-      ? undefined
-      : { name: executor.name, capacity: executor.capacity }
+    return executor === undefined ? undefined : pools.get(executor)
   }
 }

package/src/orchestrator/plan.ts

@@ -13,7 +13,13 @@
 
 import type { CacheLayer, CachePolicy, GitFilesCache } from '../cache/index.js'
 import { FULL_CACHE_POLICY } from '../cache/index.js'
-import { isGroupTask, runGraph, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import {
+  idleServers,
+  isGroupTask,
+  runGraph,
+  type TaskNode,
+  type TaskOutcome,
+} from '../graph/index.js'
 import type { HistoryProvider } from './history.js'
 import { computeGroupKey, computeTaskHash } from './task-hash.js'
 import { keyUpstream } from './upstream.js'
@@ -24,6 +30,7 @@ export type CacheStatus =
   | 'miss' // caching enabled but no entry — would execute
   | 'no-cache' // task opts out of caching (no `cache` block) or --no-cache
   | 'group' // no `exec`; just an aggregator
+  | 'not-started' // a server every dependant of which restores early: the run never spawns it
 
 export interface PlannedTask {
   node: TaskNode
@@ -108,6 +115,12 @@ export interface PlanArgs {
   history?: HistoryProvider
   /** Placement lookup (`placement.ts`): >1 executor declared, or a `noop` task. */
   executorOf?: (id: string) => string | undefined
+  /**
+   * The tasks the run's short-circuit would restore ahead of their deps on
+   * a local hit (stable key, no workspace-output reach). A server whose
+   * every dependant is one of those and a local hit is never spawned.
+   */
+  restorable?: ReadonlySet<string>
 }
 
 /**
@@ -171,6 +184,17 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
     },
   })
 
+  if (args.restorable !== undefined) {
+    const restoreTier = new Set(
+      [...args.restorable].filter((id) => cacheStatusById.get(id) === 'hit-local'),
+    )
+    const dependents = new Map<string, string[]>()
+    for (const node of args.nodes.values())
+      for (const dep of node.deps) dependents.set(dep, [...(dependents.get(dep) ?? []), node.id])
+    for (const id of idleServers(args.nodes, dependents, restoreTier))
+      cacheStatusById.set(id, 'not-started')
+  }
+
   const tasks: PlannedTask[] = []
   for (const id of args.nodes.keys()) {
     const o = outcomes.get(id)

package/src/orchestrator/plugin-host.ts

@@ -7,6 +7,7 @@
 //
 // See docs/design/pipeline-2026-09.md.
 
+import path from 'node:path'
 import { ChainedCache, type CacheLayer } from '../cache/index.js'
 import { localExecutor, type TaskExecutor } from '../exec/index.js'
 import { settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
@@ -106,6 +107,25 @@ export function hasHook(
   return false
 }
 
+/**
+ * An in-place stage reads nothing a hook returns: Vite's `config` hook
+ * returns a partial config, and one written that way here loaded, changed
+ * nothing and said nothing. Returning the object it was handed is harmless.
+ */
+function assertEditedInPlace(
+  plugin: VxPlugin,
+  hook: 'config' | 'project' | 'graph',
+  returned: unknown,
+  edited: unknown,
+  what: string,
+): void {
+  if (returned === undefined || returned === edited) return
+  throw new UserError(
+    `plugin '${plugin.name}' failed in ${hook}: returned ${describeValue(returned)}, which core ` +
+      `ignores — edit ${what} in place`,
+  )
+}
+
 /** `config` stage: every plugin edits the workspace config in place. */
 export async function applyConfigHooks(
   plugins: readonly VxPlugin[],
@@ -116,7 +136,8 @@ export async function applyConfigHooks(
 ): Promise<void> {
   for (const plugin of plugins) {
     if (plugin.config === undefined) continue
-    await safe(plugin, 'config', () => plugin.config!(workspace, ctx))
+    const returned = await safe(plugin, 'config', () => plugin.config!(workspace, ctx))
+    assertEditedInPlace(plugin, 'config', returned, workspace, 'the workspace config')
     afterEach?.(plugin)
   }
 }
@@ -157,7 +178,8 @@ export async function applyProjectHooks(
 ): Promise<void> {
   for (const plugin of plugins) {
     if (plugin.project === undefined) continue
-    await safe(plugin, 'project', () => plugin.project!(config, ctx))
+    const returned = await safe(plugin, 'project', () => plugin.project!(config, ctx))
+    assertEditedInPlace(plugin, 'project', returned, config, "the project's config")
     afterEach?.(plugin)
   }
 }
@@ -183,7 +205,8 @@ export async function applyGraphHooks(
   let last: VxPlugin | undefined
   for (const plugin of plugins) {
     if (plugin.graph === undefined) continue
-    await safe(plugin, 'graph', () => plugin.graph!(nodes, ctx))
+    const returned = await safe(plugin, 'graph', () => plugin.graph!(nodes, ctx))
+    assertEditedInPlace(plugin, 'graph', returned, nodes, 'the task graph')
     await safe(plugin, 'graph', () => checkNodeShapes(nodes))
     afterEach?.(plugin)
     last = plugin
@@ -207,6 +230,21 @@ function checkNodeShapes(nodes: Map<string, TaskNode>): void {
     if (!Array.isArray(deps)) {
       throw new Error(`${key}'s deps is ${what(deps)}, not an array of task ids`)
     }
+    // A node a hook adds is read as it wrote it: one with no `projectDir`
+    // ran as `internal error in a#x: TypeError: The "path" property must
+    // be of type string`, and a relative one keyed and ran against
+    // whatever directory vx was started in.
+    const fields = node as { projectName?: unknown; taskName?: unknown; projectDir?: unknown }
+    const shown = (v: unknown): string => (typeof v === 'string' ? JSON.stringify(v) : what(v))
+    for (const field of ['projectName', 'taskName'] as const) {
+      if (typeof fields[field] !== 'string' || fields[field] === '') {
+        throw new Error(`${key}'s ${field} is ${shown(fields[field])}, not a name`)
+      }
+    }
+    const dir = fields.projectDir
+    if (typeof dir !== 'string' || !path.isAbsolute(dir)) {
+      throw new Error(`${key}'s projectDir is ${shown(dir)}, not an absolute path`)
+    }
   }
 }
 

package/src/orchestrator/plugin.ts

@@ -227,7 +227,14 @@ interface BaseContext {
   warn(message: string): void
 }
 
-export interface PluginSetupContext extends BaseContext {}
+/** What `setup` receives: the run's lifecycle, observe-only. */
+export interface PluginSetupContext extends BaseContext {
+  /**
+   * Subscribe a lifecycle handler; it leaves with the run. A throw or a
+   * rejection warns once and switches the plugin's handlers off for the run.
+   */
+  on<K extends PluginHookName>(hook: K, handler: PluginHookHandlers[K]): void
+}
 
 /** One CLI verb contributed by a plugin. */
 export interface PluginCommand {
@@ -357,23 +364,12 @@ export interface ExecutorContext extends BaseContext {
   readonly concurrency: number
 }
 
-export interface PluginContext {
-  /** Where the workspace lives on disk. */
-  readonly workspaceRoot: string
-  /** Where vx's cache lives — read-only as far as the plugin is concerned. */
-  readonly cacheDir: string
-  /** Funnel warnings into the run:status channel, as every hook's context does. */
-  warn(message: string): void
+export interface PluginContext extends PluginSetupContext {
   /**
    * The run event bus. A plugin can subscribe directly if its needs exceed
    * the hooks; the subscription ends with the run, as a hook's does.
    */
   readonly bus: EventBus
-  /**
-   * Convenience: register a typed handler keyed off `RunEvent.kind`.
-   * Multiple hooks can chain via repeated calls.
-   */
-  on<K extends PluginHookName>(hook: K, handler: PluginHookHandlers[K]): void
 }
 
 export type PluginHookName =
@@ -444,7 +440,8 @@ function pluginPackageName(dir: string): string {
   for (let d = dir; ;) {
     let text: string | undefined
     try {
-      text = readFileSync(path.join(d, 'package.json'), 'utf8')
+      // A byte-order mark is stripped, as npm, Node and discovery strip it.
+      text = readFileSync(path.join(d, 'package.json'), 'utf8').replace(/^\uFEFF/, '')
     } catch {
       /* not here; look one level up */
     }

package/src/orchestrator/projects.ts

@@ -43,16 +43,25 @@ export async function loadWorkspacePlugins(
   workspaceRoot: string,
   warn: (message: string) => void,
 ): Promise<{ workspaceConfig: WorkspaceConfig | null; plugins: readonly VxPlugin[] }> {
-  const workspaceConfig = await loadWorkspaceConfig(workspaceRoot)
-  const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
-  if (workspaceConfig !== null && hasHook(plugins, 'config')) {
-    // Re-validated after each plugin, as the `project` stage is: an edit
-    // the loader would refuse from a user (`concurrency: -3`) hung the run,
-    // and `cacheDir: 42` reached `path.resolve` as a TypeError.
-    await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn }, (plugin) =>
-      validateWorkspace(workspaceConfig, `vx.workspace (after plugin '${plugin.name}')`),
-    )
+  const loaded = await loadWorkspaceConfig(workspaceRoot)
+  const plugins = (loaded?.plugins ?? []) as readonly VxPlugin[]
+  if (loaded === null || !hasHook(plugins, 'config')) return { workspaceConfig: loaded, plugins }
+  // Bun keeps one module per specifier, so the file's export is one object
+  // per process: the CLI's selection pass, the run and each `vx watch`
+  // cycle handed the hooks what the last load's hooks had edited
+  // (`concurrency *= 2` doubled per load). The hooks edit a copy; the file
+  // holds data and plugins, and validation refused anything else.
+  const { plugins: list, ...data } = loaded
+  const workspaceConfig: WorkspaceConfig = {
+    ...structuredClone(data),
+    ...(list !== undefined ? { plugins: [...list] } : {}),
   }
+  // Re-validated after each plugin, as the `project` stage is: an edit
+  // the loader would refuse from a user (`concurrency: -3`) hung the run,
+  // and `cacheDir: 42` reached `path.resolve` as a TypeError.
+  await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn }, (plugin) =>
+    validateWorkspace(workspaceConfig, `vx.workspace (after plugin '${plugin.name}')`),
+  )
   return { workspaceConfig, plugins }
 }
 

package/src/orchestrator/run-context.ts

@@ -13,7 +13,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { executablePath, ulid, xxh3hex } from '../util/index.js'
+import { executablePath, relPosix, ulid, xxh3hex } from '../util/index.js'
 
 export interface GitContext {
   /** `git rev-parse HEAD`, or null outside a repo / on failure. */
@@ -410,7 +410,7 @@ function workTreePath(root: string): string | undefined {
   const abs = path.resolve(root)
   for (let dir = abs; ;) {
     if (fs.existsSync(path.join(dir, '.git'))) {
-      return path.relative(dir, abs).split(path.sep).join('/') || '.'
+      return relPosix(dir, abs) || '.'
     }
     const up = path.dirname(dir)
     if (up === dir) return undefined

package/src/orchestrator/run-lock.ts

@@ -41,8 +41,8 @@
 // A holder's pid can come back: the temp directory outlives a container
 // restart, and the restarted container's vx got the dead run's pid (1) and
 // waited for itself forever (nx#36473 reproduced on vx, 2026-09-24). So a
-// lock naming OUR pid is stale — a run of this process would be in
-// `heldHere` — and on Linux the entry also carries the holder's start
+// lock naming OUR pid is stale unless this process placed that entry and
+// has not left it (`placed`) — and on Linux the entry also carries the holder's start
 // time, so a pid another process now wears is stale too. Where the lock
 // cannot be made or read for any reason but "held" (a temp directory this
 // user cannot write), the run says so once and proceeds unlocked: the
@@ -71,6 +71,12 @@ import { isTmpdirRefusal, procfsIsOwn, TMPDIR_HINT, xxh3hex } from '../util/inde
 const heldHere = new Map<string, number>()
 /** The entry this process's taking of each held lock wrote. */
 const takers = new Map<string, string>()
+/**
+ * Every entry this process has placed and not yet left, listed before its
+ * rename: a concurrent taking here reads it before `heldHere` names it, and
+ * must wait for it, not reclaim it as a dead run of this pid.
+ */
+const placed = new Set<string>()
 
 /**
  * A signal exit is `process.exit` (signals.ts): no finally runs and nothing
@@ -248,7 +254,7 @@ function nextEntry(): string {
  * procfs once per holder, not once per poll.
  */
 function holderLive(h: Holder, sameAsLast: boolean): boolean {
-  if (h.pid === process.pid) return false
+  if (h.pid === process.pid) return placed.has(h.entry)
   if (!alive(h.pid)) return false
   if (h.start === null || sameAsLast) return true
   const now = startTime(h.pid)
@@ -278,11 +284,13 @@ async function place(lockDir: string): Promise<string | null> {
   // directory a killed pid 1 left, and refuse every run after it.
   const staging = `${lockDir}.${entry}.${Math.random().toString(36).slice(2)}`
   await mkdir(staging)
+  placed.add(entry)
   try {
     await writeFile(path.join(staging, entry), '')
     await rename(staging, lockDir)
     return entry
   } catch (err) {
+    placed.delete(entry)
     await rm(staging, { recursive: true, force: true })
     const code = (err as NodeJS.ErrnoException).code
     if (code === 'ENOTEMPTY' || code === 'EEXIST') return null
@@ -327,6 +335,8 @@ export async function acquireRunLock(
     }
     heldHere.delete(lockDir)
     const taker = takers.get(lockDir)
+    // Leaving: a taking here from now on may reclaim it, as before its unlink.
+    if (taker !== undefined) placed.delete(taker)
     // The unlink of this taking's own entry is the proof no later run
     // reclaimed the lock: had one, the entry is gone and nothing else is
     // touched. A run that joined another's taking in this process leaves
@@ -388,6 +398,6 @@ export async function acquireRunLock(
         opts.log(`[vx] waiting for another vx run (pid ${h.pid}) on this workspace to finish…`)
       }
     }
-    await new Promise((r) => setTimeout(r, POLL_MS))
+    await Bun.sleep(POLL_MS)
   }
 }

package/src/orchestrator/run.ts

@@ -4,6 +4,7 @@
 
 import type { ProjectEntry } from '../workspace/index.js'
 import { loadWorkspace, unreachedHint, unreachedPackages } from '../workspace/index.js'
+import { realpathSync } from 'node:fs'
 import path from 'node:path'
 import { Cache, type CacheLayer, type CachePolicy, stopRuntimeProbes } from '../cache/index.js'
 import { VERSION } from '../version.js'
@@ -18,6 +19,7 @@ import { resolveDownloadModes } from './download-policy.js'
 import type { TaskExecutor } from '../exec/index.js'
 import {
   deadServerBehind,
+  declaredTask,
   isGroupTask,
   markSurfacedDeps,
   runGraph,
@@ -85,8 +87,12 @@ import {
   detectCi,
 } from './run-context.js'
 import { startRemotePrefetch } from './remote-prefetch.js'
-import { startLocalShortCircuit, type ShortCircuit } from './local-shortcircuit.js'
-import { probesAfterWrites } from './stable-keys.js'
+import {
+  restoreTierExclusions,
+  startLocalShortCircuit,
+  type ShortCircuit,
+} from './local-shortcircuit.js'
+import { deriveStableKeys, probesAfterWrites } from './stable-keys.js'
 
 import { assembleRunRecords } from './run-records.js'
 import { hasEnded, selectKeepAlive, shutdownPersistent } from './persistent.js'
@@ -366,8 +372,10 @@ async function runOnBus(
   // its tasks escape the schedule, the concurrency budget and this task's
   // cache key. The markers `taskEnv` sets on every child (exec/env.ts)
   // name the task; the check is on the root so both shapes are caught.
+  // Compared canonical: a root reached through a symlink (`run({ cwd })`,
+  // macOS's /var/folders) and the inner vx's realpath'd cwd are one tree.
   const outerRoot = process.env[VX_RUN_WORKSPACE_ENV]
-  if (outerRoot !== undefined && path.resolve(outerRoot) === path.resolve(prepared.workspaceRoot)) {
+  if (outerRoot !== undefined && canonical(outerRoot) === canonical(prepared.workspaceRoot)) {
     await teardown()
     prepared.cache.close()
     throw new UserError(
@@ -395,7 +403,8 @@ async function runOnBus(
     const reachedNone =
       options.affected !== undefined &&
       [...prepared.projects.values()].some(
-        (p) => inScope.has(p.name) && options.tasks.some((t) => p.config.tasks?.[t] !== undefined),
+        (p) =>
+          inScope.has(p.name) && options.tasks.some((t) => declaredTask(p.config, t) !== undefined),
       )
     log.status(
       reachedNone
@@ -427,7 +436,7 @@ async function runOnBus(
   let telemetry: TelemetryHandle | undefined
   try {
     disposePlugins = await installPlugins({
-      plugins: prepared.plugins as never,
+      plugins: prepared.plugins,
       bus,
       workspaceRoot: prepared.workspaceRoot,
       cacheDir: prepared.cacheDir,
@@ -930,6 +939,9 @@ async function runOnBus(
     const explainMiss =
       telemetry === undefined ? undefined : createMissExplainer(prepared.localCache.dbHandle())
     const lateProbes = probesAfterWrites(nodes, workspaceRoot)
+    // The scheduler's fail-fast stop, as the retry loop of a task already
+    // in flight sees it.
+    const failFast = new AbortController()
     const buildExecuteArgs = (node: TaskNode, upstream: TaskOutcome[], reuseProbe = true) => {
       const probe = reuseProbe ? shortCircuit.preProbed.get(node.id) : undefined
       const upfrontKey = shortCircuit.uncachedKeys.get(node.id)
@@ -977,6 +989,7 @@ async function runOnBus(
         deferSave: saveLane.defer,
         deferredSaves,
         stopSignal: stopRun.signal,
+        failFast: failFast.signal,
       }
     }
 
@@ -1025,6 +1038,7 @@ async function runOnBus(
       ...(holders.size > 0 ? { exclusive: holders } : {}),
       ...(options.continueMode !== undefined ? { continueMode: options.continueMode } : {}),
       serverDied,
+      onFailFast: () => failFast.abort(),
       signal: stopRun.signal,
       onStart: (node) => {
         log.taskStart?.(node)
@@ -1076,8 +1090,6 @@ async function runOnBus(
     ).filter((c) => endedBeforeStop?.has(persistentRegistry.get(c.id)!) ?? true)
 
     mark('run graph')
-    // Clear the status line for good before the summary prints.
-    log.runEnd?.()
 
     // A server that died on its own before the stop failed, whatever its
     // outcome said when it became ready: the footer counted it a success
@@ -1087,8 +1099,11 @@ async function runOnBus(
     const failServer = (id: string, code: number | string): void => {
       const o = outcomes.get(id)
       if (o === undefined) return
-      const exitCode = typeof code === 'number' ? code : signalExitCode(code)
-      outcomes.set(id, { ...o, status: 'failed', exitCode })
+      // In place: the renderer holds this outcome (events carry live refs)
+      // and closes the server's output block from it at runEnd, where a
+      // copy left it reading `running` under its exit line (WD-10).
+      o.status = 'failed'
+      o.exitCode = typeof code === 'number' ? code : signalExitCode(code)
     }
     for (const c of crashedPersistent) failServer(c.id, c.code)
     keepAlive.nodes.forEach((n, i) => {
@@ -1097,6 +1112,8 @@ async function runOnBus(
       if (endedBeforeStop !== undefined && !endedBeforeStop.has(child)) return
       failServer(n.id, child.exitCode ?? child.signalCode ?? 'unknown')
     })
+    // Clear the status line for good before the summary prints.
+    log.runEnd?.()
     const list = [...outcomes.values()]
     const ok = list.every((o) => isPassStatus(o.status))
 
@@ -1371,11 +1388,24 @@ async function runOnBus(
       }
     }
     if (keepAlive.children.length > 0) {
-      const first = await Promise.race(
-        keepAlive.children.map((c, i) => c.exited.then((code) => ({ code, i }))),
-      )
+      // A server kept only as a dependency that exits 0 is a daemon that
+      // forked and returned (schema.md), not the end of the session: a
+      // `db: 'docker compose up -d'` under `app#dev` stopped the dev server
+      // right after the summary (WD-3). It ends the wait only as the last.
+      const first = await new Promise<{ code: number; i: number }>((resolve) => {
+        let left = keepAlive.children.length
+        keepAlive.children.forEach((c, i) => {
+          void c.exited.then((code) => {
+            left--
+            const n = keepAlive.nodes[i]!
+            if (code !== 0 || n.requested || n.surfaced === true || left === 0) resolve({ code, i })
+          })
+        })
+      })
       const node = keepAlive.nodes[first.i]!
-      const others = keepAlive.nodes.length - 1
+      // Only the ones still up are stopped: a kept server already dead was
+      // counted as one (WD-11).
+      const others = keepAlive.children.filter((c, j) => j !== first.i && !hasEnded(c)).length
       // Not when the run was stopped: the server ended because the user
       // stopped it, and "exited with code 130" read as a crash after every
       // Ctrl-C once a stop let run() finish its own path (item 852).
@@ -1387,7 +1417,11 @@ async function runOnBus(
               : ''),
         )
       }
-      await terminateChildren(() => keepAlive.children)
+      // Under a stop the abort is already taking them down with the stop's
+      // signal; a second SIGTERM in its grace cut short the graceful
+      // shutdown of a server that reads it as "quit now" (WD-16).
+      if (stopRun.signal.aborted) await aborting?.catch(() => {})
+      else await terminateChildren(() => keepAlive.children)
       // The server that ended the session on its own, not cleanly, failed:
       // the rewritten summary said `ok: false` over every task `success`
       // and `failed: 0`, and so did the outcomes `--report` renders (C-53).
@@ -1501,12 +1535,13 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
     // Its own mark: a dry run's plan (every task's hash, the cache lookups,
     // the history p50s) was booked under `close`, the next mark, and read
     // as 105 ms of closing a cache at 1,000 projects (item 601).
+    const policy = effectiveCachePolicy(prepared.cachePolicy, prepared.hasRemoteLayer)
     const planned = await plan({
       nodes: prepared.nodes,
       workspaceRoot: prepared.workspaceRoot,
       workspaceFingerprint: prepared.workspaceFingerprint,
       cache: prepared.cache,
-      cachePolicy: effectiveCachePolicy(prepared.cachePolicy, prepared.hasRemoteLayer),
+      cachePolicy: policy,
       forwardArgs: options.forwardArgs,
       nestedDirsByProject: prepared.nestedDirsByProject,
       gitFilesCache: prepared.gitFilesCache,
@@ -1523,6 +1558,7 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
       // the same plugin-factory call `prepareRun` already makes for the
       // cache capability, so plan mode gains no new class of side effect.
       ...(await planExecutorOf(prepared, log, options.download ?? 'all')),
+      ...(await planRestorable(prepared, policy, options.forwardArgs)),
     })
     mark('plan')
     return planned
@@ -1539,6 +1575,39 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
   }
 }
 
+/**
+ * What the run's short-circuit would restore ahead of its deps, so the plan
+ * can tell a server nobody needs from one that starts: `--dry` called a
+ * server every dependant of which was a local hit `would exec`, and the run
+ * never spawned it. The run's own gates (`shouldShortCircuit`, stable keys,
+ * workspace-output reach), asked only when a server could idle.
+ */
+async function planRestorable(
+  prepared: PreparedRun,
+  policy: CachePolicy,
+  forwardArgs: readonly string[] | undefined,
+): Promise<{ restorable?: Set<string> }> {
+  const { nodes } = prepared
+  const serves = [...nodes.values()].some(
+    (n) => n.config.exec?.persistent !== undefined && !n.requested && n.surfaced !== true,
+  )
+  if (!serves || !shouldShortCircuit(nodes, policy, prepared.cache)) return {}
+  const keptOut = restoreTierExclusions(nodes, prepared.workspaceRoot)
+  const stable = await deriveStableKeys({
+    nodes,
+    cache: prepared.cache,
+    workspaceRoot: prepared.workspaceRoot,
+    workspaceFingerprint: prepared.workspaceFingerprint,
+    forwardArgs,
+    nestedDirsByProject: prepared.nestedDirsByProject,
+    gitFilesCache: prepared.gitFilesCache,
+    hashCache: prepared.hashCache,
+  })
+  return {
+    restorable: new Set(stable.map((k) => k.node.id).filter((id) => !keptOut.has(id))),
+  }
+}
+
 /** The names a project outside the run's selection declares, and how to reach them. */
 function elsewhereHint(names: readonly string[]): string {
   if (names.length === 0) return ''
@@ -1652,7 +1721,7 @@ export function nxProjectTarget(
   if (colon <= 0 || spec.includes('#')) return undefined
   const [typed, task] = [spec.slice(0, colon), spec.slice(colon + 1)]
   const project = projectNamed(typed, projects)
-  return project === undefined || projects.get(project)?.config.tasks?.[task] === undefined
+  return project === undefined || declaredTask(projects.get(project)?.config, task) === undefined
     ? undefined
     : `${project}#${task}`
 }
@@ -1692,3 +1761,12 @@ function flakyCandidates(outcomes: readonly TaskOutcome[]): FlakyCandidate[] {
   }
   return out
 }
+
+/** `dir` with its links resolved; as written when it is gone (a stale marker). */
+function canonical(dir: string): string {
+  try {
+    return realpathSync(dir)
+  } catch {
+    return path.resolve(dir)
+  }
+}