@vzn/vx 0.0.21 → 0.0.22

package/src/orchestrator/run.ts

@@ -3,6 +3,7 @@
 // so the layers can be swapped without touching the others.
 
 import type { ProjectEntry } from '../workspace/index.js'
+import { loadWorkspace, unreachedHint, unreachedPackages } from '../workspace/index.js'
 import path from 'node:path'
 import { type CacheLayer, type CachePolicy, FULL_CACHE_POLICY } from '../cache/index.js'
 import { VERSION } from '../version.js'
@@ -18,36 +19,51 @@ import {
   type TaskOutcome,
 } from '../graph/index.js'
 import {
+  formatBytes,
   mark,
+  killGraceMs,
   MAX_TIMEOUT_MS,
+  parseDuration,
+  parseSize,
   printTimings,
   ulid,
   nearest,
   UserError,
   machineParallelism,
+  teardownTimeoutMs,
 } from '../util/index.js'
+import { keyedProjects } from './keyed-projects.js'
 import { prepareSandbox } from './sandbox-request.js'
 import type { OutputDirSnapshot } from './miss-save.js'
 import { admitTasks, taintTracker } from './admission.js'
-import { busLogger, createEventBus, terminalSubscriber } from './events.js'
+import { excludedTaint } from './excluded-keys.js'
+import { keyUpstream } from './upstream.js'
+import { busLogger, createEventBus, terminalSubscriber, type EventBus } from './events.js'
 import { installPlugins } from './plugin.js'
 import { buildAdmission, resolveExecutors, teardownPlugins } from './plugin-host.js'
 import { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
 import { assembleRunSummary, isPassStatus } from './telemetry.js'
 import type { RunContextRecord } from './telemetry.js'
-import { defaultLogger, resolveOutputView } from './logger.js'
-import { detectColors } from './colors.js'
+import { defaultLogger, resolveOutputView, type Logger } from './logger.js'
+import { detectColors, type ColorSupport } from './colors.js'
 import { formatPersistentList } from './framed-output.js'
 import { LocalHistoryProvider } from './history.js'
 import { plan, type RunPlan } from './plan.js'
-import { prepareRun } from './prepare.js'
-import { forwardSignals, terminateChildren } from './signals.js'
+import { prepareRun, type PreparedRun } from './prepare.js'
+import { acquireRunLock } from './run-lock.js'
+import {
+  forwardedSignal,
+  forwardSignals,
+  SIGNAL_SHUTDOWN_GRACE_MS,
+  terminateChildren,
+} from './signals.js'
 import {
   hasPooledExecutor,
   placeTasks,
   planExecutorOf,
   poolOfPlacement,
   UNPLACED_EXECUTOR,
+  locallyPlaced,
 } from './placement.js'
 import {
   captureDefaultBranch,
@@ -60,10 +76,15 @@ import { startRemotePrefetch } from './remote-prefetch.js'
 import { startLocalShortCircuit, type ShortCircuit } from './local-shortcircuit.js'
 
 import { assembleRunRecords } from './run-records.js'
-import { selectKeepAlive, shutdownPersistent } from './persistent.js'
+import { hasEnded, selectKeepAlive, shutdownPersistent } from './persistent.js'
 import { writeRunProfile, writeRunSummary } from './run-artifacts.js'
 import { createSaveLane } from './save-lane.js'
-import { formatAbortedSection, formatFlakySection, formatRunSummary } from './summary.js'
+import {
+  formatAbortedSection,
+  formatFlakySection,
+  formatRunSummary,
+  formatSkippedSection,
+} from './summary.js'
 import { detectFlaky, type FlakyCandidate } from './failure-mode.js'
 import type { RunOptions, RunSummary } from './options.js'
 
@@ -167,11 +188,31 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // additional subscribers. The fan-out is synchronous and order-
   // preserving, so terminal output is byte-identical to a direct call.
   // See docs/design/event-stream-2026-06.md.
-  const sink = options.log ?? defaultLogger(colors, resolveOutputView(options))
-  // An injected bus (e.g. from `--ui`) already has surfaces subscribed;
-  // we just add the terminal renderer. Otherwise a fresh internal bus.
+  const terminal =
+    options.log === undefined
+      ? defaultLogger(colors, resolveOutputView(options), process.stdout, { coalesce: true })
+      : null
+  const sink = options.log ?? terminal!
+  // An injected bus already has surfaces subscribed; we add the terminal
+  // renderer for this run and take it off again on every way out: the bus
+  // outlives the run, and a renderer left behind reported the next run on
+  // it twice (item 635). Otherwise a fresh internal bus.
   const bus = options.bus ?? createEventBus()
-  bus.subscribe(terminalSubscriber(sink))
+  const unsubscribeTerminal = bus.subscribe(terminalSubscriber(sink))
+  try {
+    return await runOnBus(options, bus, colors, () => terminal?.failureRecap() ?? [])
+  } finally {
+    unsubscribeTerminal()
+    terminal?.settle()
+  }
+}
+
+async function runOnBus(
+  options: RunOptions,
+  bus: EventBus,
+  colors: ColorSupport,
+  failureRecap: () => string[],
+): Promise<RunSummary> {
   const log = busLogger(bus)
 
   const prepared = await prepareRun(options, log)
@@ -198,7 +239,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // case too; the message is identical, so that branch stays below.
   if (prepared.unresolvedTasks.length > 0) {
     log.status(
-      `No projects declare task(s): ${prepared.unresolvedTasks.join(', ')}.${didYouMean(prepared.unresolvedTasks, prepared.projects)}${initHint(prepared)}`,
+      `No projects declare task(s): ${prepared.unresolvedTasks.join(', ')}.${didYouMean(prepared.unresolvedTasks, prepared.projects)}${await initHint(prepared)}`,
     )
     prepared.cache.close()
     return { ok: false, outcomes: [] }
@@ -210,7 +251,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     // buildTaskGraph semantics but logged just in case.
     const msg =
       prepared.empty === 'no-tasks-declared'
-        ? `No projects declare task(s): ${options.tasks.join(', ')}.${initHint(prepared)}`
+        ? `No projects declare task(s): ${options.tasks.join(', ')}.${await initHint(prepared)}`
         : 'No tasks to run.'
     log.status(msg)
     prepared.cache.close()
@@ -242,6 +283,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     cache,
     nodes,
     workspaceFingerprint,
+    fingerprintWatch,
     nestedDirsByProject,
     gitFilesCache,
     hashCache,
@@ -268,7 +310,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // can admit a remote-pooled task against its pool instead of a local
   // worker slot. Group tasks run nothing; persistent tasks never reach an
   // executor (local by construction) — both stay off the map.
-  const placements = placeTasks(nodes, executors, false)
+  const placements = placeTasks(nodes, executors)
   // A `remote: 'only'` task nobody takes succeeds WITHOUT running. That is
   // deliberate — on a machine with no remote pool the ambient state already
   // is what the task would have produced — but it must not be SILENT: a task
@@ -313,9 +355,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // `--download` (default `all`) decides ONCE per task, here, whether a
   // remote execution's outputs come home.
   const downloadPolicy = options.download ?? 'all'
-  const localPlaced = new Set(
-    [...nodes.keys()].filter((id) => placements.executors.get(id)?.remote !== true),
-  )
+  const localPlaced = locallyPlaced(placements, nodes.keys())
   const download = resolveDownloadModes({
     nodes,
     policy: downloadPolicy,
@@ -339,25 +379,59 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   //     exit; ownership moves here so the orchestrator can SIGTERM
   //     them once the rest of the graph finishes.
   //
-  // A SIGINT/SIGTERM mid-run forwards SIGTERM to everything in both
+  // A SIGINT/SIGTERM mid-run forwards that signal to everything in both
   // (`signals.ts`); the handlers are removed in the finally below so
   // repeated run() calls (test suites) never stack listeners.
   const liveChildren = new Set<ReturnType<typeof Bun.spawn>>()
   const persistentRegistry = new Map<string, ReturnType<typeof Bun.spawn>>()
+  // One stop for the run: an embedder's `RunOptions.signal` and a process
+  // signal both abort it. The scheduler stops dispatching (it reads the
+  // signal), the children are torn down, and run() returns through its own
+  // end-of-run path. Detached in the finally below.
+  const stopRun = new AbortController()
+  const forwardAbort = (): void => stopRun.abort(options.signal?.reason)
+  if (options.signal?.aborted === true) forwardAbort()
+  else options.signal?.addEventListener('abort', forwardAbort, { once: true })
+  // A run a process signal stopped records no history: until item 849 the
+  // handler exited before any outcome landed, and a Ctrl-C'd run then read
+  // in `vx last` as FAILED with 0 tasks (item 854). An embedder's abort is
+  // its own call and keeps its record.
+  let stoppedBySignal = false
+  let leftRun = (): void => {}
+  const runLeft = new Promise<void>((resolve) => {
+    leftRun = resolve
+  })
   const signals = forwardSignals({
     enabled: options.handleSignals ?? true,
     log,
     cache,
     liveChildren,
     persistentRegistry,
+    stop: (signal) => {
+      stoppedBySignal = true
+      stopRun.abort(signal)
+    },
+    done: runLeft,
+    // The grace, then one flush and each teardown at their own bound, and
+    // slack for the summary and the cache close.
+    boundMs:
+      killGraceMs(SIGNAL_SHUTDOWN_GRACE_MS) +
+      teardownTimeoutMs() * (1 + prepared.plugins.filter((p) => p.teardown).length) +
+      2_000,
   })
-  // `RunOptions.signal`: the same teardown the process handler runs, minus
-  // the exit — the scheduler stops dispatching (it reads the signal) and
-  // run() returns to its caller. Detached in the finally below.
+  // Awaited before run() leaves: a task's shell can die of the signal at
+  // once while a child it backgrounded ignores it and dies only to the
+  // SIGKILL after the grace, and a run that returned first left that child
+  // running past vx's exit (turborepo#14043's class).
+  let aborting: Promise<void> | undefined
   const onAbort = (): void => {
-    void terminateChildren(() => [...liveChildren, ...persistentRegistry.values()])
+    aborting = terminateChildren(
+      () => [...liveChildren, ...persistentRegistry.values()],
+      forwardedSignal(stopRun.signal.reason),
+    )
   }
-  options.signal?.addEventListener('abort', onAbort, { once: true })
+  if (stopRun.signal.aborted) onAbort()
+  else stopRun.signal.addEventListener('abort', onAbort, { once: true })
   // The cache handle must be released on EVERY exit path, not just the
   // happy one: `close()` is also where the run's deferred `accessed_at`
   // bumps are flushed, so a throw between opening the cache and the
@@ -368,11 +442,25 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // holding the handle open for a dev server's whole lifetime would be
   // worse — and because close() re-runs its retention DELETEs.
   let cacheClosed = false
-  const closeCache = (): void => {
+  const closeCache = async (): Promise<void> => {
     if (cacheClosed) return
     cacheClosed = true
     cache.close()
+    // Released with the handle: before a persistent task's wait, on every
+    // exit path (see run-lock.ts for why a run holds one at all). AWAITED:
+    // fired and forgotten, the release lost the race with the CLI's exit —
+    // `bin.ts` ends the process as soon as run() resolves — and every CLI
+    // run left its lock directory in the temp dir (658 of them after one
+    // day's gates, 2026-09-16); the next run reclaimed it, so nothing
+    // waited, but a directory per run is litter the box never sheds.
+    await releaseRunLock()
   }
+  // Taken after the early exits above (nothing they do touches a tree) and
+  // before the schedule: from here on tasks clean, restore and write.
+  const releaseRunLock = await acquireRunLock(prepared.workspaceRoot, {
+    log: (m) => log.status(m),
+    signal: stopRun.signal,
+  })
   try {
     // One run-id per `vx run` invocation. Every task in the resulting
     // graph carries it so analytics queries can group by invocation.
@@ -463,6 +551,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     }
 
     const sandboxArmer = prepareSandbox(nodes.values())
+    const keyed = keyedProjects(nodes)
     const outputDirSnapshots: OutputDirSnapshot[] = []
     // Saves run off the execution slot, twice the cap at once (memory:
     // each pack holds an artifact's bytes); a failed save is a miss next
@@ -566,9 +655,18 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     }
 
     // Whether this task runs behind a failure (`continueMode: 'always'`
-    // only) — its save is withheld and the taint propagates; see
+    // only) or on the key of a dependency `--exclude-dependencies` kept
+    // from running — its save is withheld and the taint propagates; see
     // admission.ts.
-    const isTainted = taintTracker(options.continueMode === 'always')
+    const excluded = excludedTaint(nodes)
+    if (excluded.unsaved > 0) {
+      log.status(
+        `[vx] --exclude-dependencies: ${excluded.unsaved} cached task(s) build on a skipped dependency; what they build is not saved`,
+      )
+    }
+    const isTainted = taintTracker(options.continueMode === 'always', excluded.seeds)
+    const dependedOn = new Set<string>()
+    for (const n of nodes.values()) for (const d of n.deps) dependedOn.add(d)
 
     const buildExecuteArgs = (node: TaskNode, upstream: TaskOutcome[], reuseProbe = true) => {
       const probe = reuseProbe ? shortCircuit.preProbed.get(node.id) : undefined
@@ -597,10 +695,14 @@ export async function run(options: RunOptions): Promise<RunSummary> {
         hashCache,
         ...(probe !== undefined ? { preProbed: probe } : {}),
         ...(taint ? { taintedUpstream: true } : {}),
+        ...(dependedOn.has(node.id) ? {} : { noDependants: true as const }),
+        fingerprintWatch,
         ...(sandboxArmer !== null ? { armSandbox: () => sandboxArmer.arm() } : {}),
+        keyedProjects: keyed,
         outputDirSnapshots,
         deferSave: saveLane.defer,
         deferredSaves,
+        stopSignal: stopRun.signal,
       }
     }
 
@@ -628,7 +730,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
       ...(hasPooledExecutor(executors) ? { poolOf: poolOfPlacement(placements) } : {}),
       ...(admit !== undefined ? { admit } : {}),
       ...(options.continueMode !== undefined ? { continueMode: options.continueMode } : {}),
-      ...(options.signal !== undefined ? { signal: options.signal } : {}),
+      signal: stopRun.signal,
       onStart: (node) => {
         log.taskStart?.(node)
       },
@@ -636,7 +738,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
         log.taskComplete(o.node, o)
         narrowDemand(o.node.id)
       },
-      execute: executeWithDedup,
+      execute: (node, upstream) => executeWithDedup(node, keyUpstream(node, upstream)),
       // A `schedule` plugin's weights; the scheduler keeps its structural
       // baseline as the tie-break. Empty map → baseline only.
       ...(prepared.priorities.size > 0 ? { priorities: prepared.priorities } : {}),
@@ -653,15 +755,17 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     // signal loop) and embedders that manage lifecycle themselves — both
     // expect run() to return, not block on a server.
     const foreground = options.log === undefined && (options.handleSignals ?? true)
-    const keepAlive = selectKeepAlive(persistentRegistry, nodes, foreground)
-    await shutdownPersistent(persistentRegistry, keepAlive.children)
+    // An aborted run's children are already being torn down: nothing to hold.
+    const hold = options.holdPersistent === true && !stopRun.signal.aborted
+    const keepAlive = selectKeepAlive(persistentRegistry, nodes, foreground || hold)
+    const crashedPersistent = await shutdownPersistent(persistentRegistry, keepAlive.children)
 
     mark('run graph')
     // Clear the status line for good before the summary prints.
     log.runEnd?.()
 
     const list = [...outcomes.values()]
-    const ok = list.every((o) => isPassStatus(o.status))
+    const ok = list.every((o) => isPassStatus(o.status)) && crashedPersistent.length === 0
 
     // The summary + artifact writers + recordRun pass all exclude group
     // tasks via the shared tallyOutcomes helper. We pass the full
@@ -670,13 +774,23 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     const totalMs = Number(process.hrtime.bigint() - runStartHrTimeNs) / 1_000_000
     // Foreground dev mode: between the task frame and the footer, list
     // the persistent tasks still running (see the keep-alive block below).
-    if (keepAlive.nodes.length > 0) {
-      for (const line of formatPersistentList(keepAlive.nodes, colors)) log.status(line)
+    // Only the ones still up: a requested server that crashed while its
+    // dependants ran is dead, and the wait below says so.
+    const stillUp = keepAlive.nodes.filter((_, i) => !hasEnded(keepAlive.children[i]!))
+    if (stillUp.length > 0) {
+      for (const line of formatPersistentList(stillUp, colors)) log.status(line)
     }
     for (const line of formatRunSummary(list, totalMs, colors, runContext)) log.status(line)
     // A task killed by a shutdown signal is in no bucket above, yet it makes
     // `ok` false — name it, or the red exit is undiagnosable.
     for (const line of formatAbortedSection(list)) log.status(line)
+    // Likewise a dependency-only server that died before the end of the
+    // graph stopped it: its outcome says `success` (it became ready).
+    for (const c of crashedPersistent)
+      log.status(`vx: ${c.id} exited with code ${c.code} before the run stopped it`)
+    // The footer's "N skipped" names no task; this names each under the
+    // failure that blocked it.
+    for (const line of formatSkippedSection(list)) log.status(line)
     // Judged against the history BEFORE this run's rows land, so the query
     // is one scan over the executed tasks' keys and nothing at all on a run
     // that executed none (every hit, every skip).
@@ -692,6 +806,8 @@ export async function run(options: RunOptions): Promise<RunSummary> {
         `  Deferred: ${stillDeferred.length} task(s) left outputs remote (--download=none): ${stillDeferred.join(', ')}`,
       )
     }
+    // Last, where a long log's reader lands: each failure's own last lines.
+    for (const line of failureRecap()) log.status(line)
 
     // Optional artifacts. Errors are surfaced to the user but don't
     // change the run's exit code — the run already happened.
@@ -755,7 +871,16 @@ export async function run(options: RunOptions): Promise<RunSummary> {
       host: hostContext,
       withTelemetry: telemetry !== undefined,
     })
-    cache.recordRunBundle(records)
+    try {
+      if (!stoppedBySignal) cache.recordRunBundle(records)
+    } catch (err) {
+      // History is observability: a full cache disk at the very end must
+      // not turn a finished run's verdict into a stack and exit 1 (seen as
+      // an unprivileged user on a 2 MiB disk, 2026-09-16). The run said
+      // what happened; `vx last` and the flaky list will not know this one.
+      const message = err instanceof Error ? err.message : String(err)
+      log.status(`[vx] run history not recorded: ${message} — the verdict above stands`)
+    }
     mark('record history')
     // Hand the per-run summary to the telemetry sinks + drain them. Only
     // when a sink is active (telemetry !== undefined) — otherwise this
@@ -768,6 +893,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
         endedAt: endedAtMs,
         totalDurationMs: Math.round(totalMs),
         exitOk: ok,
+        abortedCount: list.filter((o) => o.status === 'aborted' && !isGroupTask(o.node)).length,
       })
       telemetry.emitSummary(summary)
       await telemetry.flush()
@@ -792,16 +918,16 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     // write with nothing but a warning. The seam's contract is that a
     // cache layer stays usable until the run's uploads have settled.
     await prefetchDone
-    // Every deferred save settles first: the upload drain below carries
-    // the entries the saves queued, and the snapshot loop after it reads
-    // what the saves pushed.
-    await saveLane.drain()
-    mark('save lane')
+    // Every deferred save has settled by here: the scheduler finishes a
+    // task only once its `settledOf` promise (the lane's `landed`) has,
+    // so `runGraph` resolved with every save in the cache. A second
+    // drain of the lane stood here until item 634; deleting it changed
+    // nothing the suite could see, because this gate is the rule.
     await cache.drainUploads?.()
     // The miss path's output-directory snapshots, taken now that the
     // directories are old enough for the snapshot's racy window (see
     // miss-save.ts). A few at a time: each is an lstat + readdir per
-    // prefix and one index transaction.
+    // prefix; the rows land together at close, in one transaction.
     for (let i = 0; i < outputDirSnapshots.length; i += 32) {
       await Promise.all(
         outputDirSnapshots
@@ -810,8 +936,11 @@ export async function run(options: RunOptions): Promise<RunSummary> {
       )
     }
     mark('output dir snapshots')
+    // Not on a stopped run: one stopped while it waited on another run's
+    // lock never held it, and its prune evicted under that run (item 858).
+    if (!stopRun.signal.aborted) await applyCacheRetention(prepared, log)
     await teardownPlugins(prepared.plugins, (m) => log.status(m))
-    closeCache()
+    await closeCache()
     mark('close')
     printTimings()
 
@@ -841,29 +970,51 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     // run that never returned. One status line names the server that
     // ended the session and its code — the summary above said `success`
     // for it, and an exit 1 with no word about why is a mystery in a log.
+    if (keepAlive.children.length > 0 && hold) {
+      const held = keepAlive.children
+      return {
+        ok,
+        outcomes: list,
+        persistent: {
+          ids: keepAlive.nodes.map((n) => n.id),
+          stop: (signal) => terminateChildren(() => held, signal),
+        },
+      }
+    }
     if (keepAlive.children.length > 0) {
       const first = await Promise.race(
         keepAlive.children.map((c, i) => c.exited.then((code) => ({ code, i }))),
       )
       const node = keepAlive.nodes[first.i]!
       const others = keepAlive.nodes.length - 1
-      log.status(
-        `vx: ${node.id} exited with code ${first.code}` +
-          (others > 0
-            ? `; stopping ${others} other persistent task${others === 1 ? '' : 's'}`
-            : ''),
-      )
+      // 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).
+      if (!stopRun.signal.aborted) {
+        log.status(
+          `vx: ${node.id} exited with code ${first.code}` +
+            (others > 0
+              ? `; stopping ${others} other persistent task${others === 1 ? '' : 's'}`
+              : ''),
+        )
+      }
       await terminateChildren(() => keepAlive.children)
       return { ok: ok && first.code === 0, outcomes: list }
     }
 
     return { ok, outcomes: list }
   } finally {
-    // Idempotent; also reached on mid-run throws, so a crashed cycle
-    // can't leave a live status-line ticker behind.
+    // Idempotent. The status-line ticker starts in runStart, and every
+    // call between it and the success path's runEnd is crash-isolated
+    // today (admit, the observers, execute's rejection arm, the
+    // short-circuit, the prefetch, killTree; the bus swallows a
+    // subscriber's throw, so even a logger's own runStart cannot reach
+    // here), so deleting this line reddens nothing (item 635). It is the
+    // floor for a throw a later change adds, not a path a row can drive.
     log.runEnd?.()
     signals.remove()
-    options.signal?.removeEventListener('abort', onAbort)
+    options.signal?.removeEventListener('abort', forwardAbort)
+    stopRun.signal.removeEventListener('abort', onAbort)
     // Plugins installed at the top of run() get their bus subscriptions
     // released here. Idempotent; safe even if installPlugins threw.
     disposePlugins?.()
@@ -874,10 +1025,50 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     // NOT drained here: they hold no database state, and awaiting a
     // wedged remote would turn a failing run into a hanging one.
     try {
-      closeCache()
+      await closeCache()
     } catch {
       // teardown must not throw on the way out
     }
+    await aborting?.catch(() => {})
+    // Last: a process signal waits for this before it exits.
+    leftRun()
+  }
+}
+
+/**
+ * The workspace's `cacheRetention`, after every save and upload of this run
+ * has landed (so nothing this run wrote is mid-flight) and before the cache
+ * closes. Housekeeping, not the run's work: a failure is one warning, never
+ * a failed run. Declared nowhere → one property read.
+ */
+async function applyCacheRetention(prepared: PreparedRun, log: Logger): Promise<void> {
+  const retention = prepared.workspaceConfig?.cacheRetention
+  if (retention === undefined) return
+  // Validated at load (`validateRetention`), so both parse.
+  const maxAgeMs =
+    retention.olderThan === undefined ? undefined : parseDuration(retention.olderThan)!
+  const maxBytes = retention.maxSize === undefined ? undefined : parseSize(retention.maxSize)!
+  try {
+    const result = await prepared.localCache.evictIfDue({
+      ...(maxAgeMs !== undefined ? { maxAgeMs } : {}),
+      ...(maxBytes !== undefined ? { maxBytes } : {}),
+    })
+    if (result !== null && (result.evicted > 0 || result.orphans > 0)) {
+      const said: string[] = []
+      if (result.evicted > 0) {
+        said.push(
+          `evicted ${result.evicted} entr${result.evicted === 1 ? 'y' : 'ies'} (${formatBytes(result.bytesFreed)})`,
+        )
+      }
+      if (result.orphans > 0) {
+        said.push(
+          `reaped ${result.orphans} orphaned artifact${result.orphans === 1 ? '' : 's'} (${formatBytes(result.orphanBytes)})`,
+        )
+      }
+      log.status(`vx: cache retention ${said.join(', ')}`)
+    }
+  } catch (err) {
+    log.status(`vx: cache retention skipped: ${err instanceof Error ? err.message : String(err)}`)
   }
 }
 
@@ -900,7 +1091,10 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
       return { tasks: [], unresolvedTasks: prepared.unresolvedTasks }
     }
     if (prepared.empty !== null) return { tasks: [] }
-    return await plan({
+    // 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 planned = await plan({
       nodes: prepared.nodes,
       workspaceRoot: prepared.workspaceRoot,
       workspaceFingerprint: prepared.workspaceFingerprint,
@@ -926,6 +1120,8 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
       // cache capability, so plan mode gains no new class of side effect.
       ...(await planExecutorOf(prepared, log, options.download ?? 'all')),
     })
+    mark('plan')
+    return planned
   } finally {
     prepared.cache.close()
     // The same table a run prints: a dry run is how the prepare stages
@@ -939,12 +1135,23 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
 /**
  * The first-run case, told apart from a typo: no package in the workspace
  * has a `vx.config.*` at all, so no name could have resolved. Reached only
- * on the error path.
+ * on the error path. A workspace whose package globs match NOTHING is
+ * told that instead — `vx init` would find no package to write for.
  */
-function initHint(prepared: { anyProjectConfig: boolean }): string {
-  return prepared.anyProjectConfig
-    ? ''
-    : ' No package declares a vx.config — run `vx init` to write one per package from its package.json scripts.'
+async function initHint(prepared: {
+  anyProjectConfig: boolean
+  workspaceProjectCount: number
+  workspaceRoot: string
+}): Promise<string> {
+  if (prepared.anyProjectConfig) return ''
+  if (prepared.workspaceProjectCount === 0) {
+    return " No package matched the workspace's package globs — check `workspaces` in package.json (or pnpm-workspace.yaml)."
+  }
+  // Single-project mode with packages the root's missing `workspaces`
+  // never reaches: `vx init` would find no scripts either (item 248).
+  const unreached = await unreachedPackages(await loadWorkspace(prepared.workspaceRoot))
+  if (unreached.length > 0) return ` ${unreachedHint(unreached)}`
+  return ' No package declares a vx.config — run `vx init` to write one per package from its package.json scripts.'
 }
 
 /**