@vzn/vx 0.0.637 → 0.0.639

package/src/orchestrator/run.ts

@@ -11,6 +11,7 @@ import {
   type CacheLayer,
   type CachePolicy,
   cachesNothing,
+  formatCachePolicy,
   stopRuntimeProbes,
 } from '../cache/index.js'
 import { VERSION } from '../version.js'
@@ -35,7 +36,6 @@ import {
 import {
   mark,
   stageTimes,
-  killGraceMs,
   MAX_TIMEOUT_MS,
   printTimings,
   ulid,
@@ -44,57 +44,64 @@ import {
   nearest,
   UserError,
   machineParallelism,
-  teardownTimeoutMs,
   secretMask,
   isFsRefusal,
   isUserError,
+  detectColors,
+  type ColorSupport,
 } from '../util/index.js'
 import { keyedProjects } from './keyed-projects.js'
 import { isDefaultBuild } from './projects.js'
 import { commandWriteReach, prepareSandbox } from './sandbox-request.js'
-import type { OutputDirSnapshot, SaveFacts } from './miss-save.js'
+import { recordOutputDirSnapshots, type OutputDirSnapshot, type SaveFacts } from './miss-save.js'
 import { admitTasks, taintTracker } from './admission.js'
 import { unkeyedGroupOutcome, type ExecuteArgs } from './execute-task.js'
+import { executeArgsOf, type RunScope } from './execute-args.js'
 import { excludedTaint } from './excluded-keys.js'
 import { keyUpstream } from './upstream.js'
-import { busLogger, createEventBus, terminalSubscriber, type EventBus } from './events.js'
-import { installPlugins, PluginSetupError } from './plugin.js'
-import { buildAdmission, executorLabel, resolveExecutors, teardownPlugins } from './plugin-host.js'
+import {
+  busLogger,
+  createEventBus,
+  createForecast,
+  defaultLogger,
+  type DefaultLogger,
+  type EventBus,
+  formatOutcomeTable,
+  formatPersistentList,
+  formatRunSummary,
+  type Logger,
+  plainOutput,
+  resolveOutputView,
+  terminalSubscriber,
+  warnOf,
+} from '../report/index.js'
+import { installPlugins, PluginSetupError, type RunReport } from './plugin.js'
+import { keepRunBytes } from './run-report.js'
+import { buildAdmission, executorDemand, resolveExecutors, teardownPlugins } from './plugin-host.js'
+import { createSteps } from './steps.js'
 import { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
 import { claimOutput, guardedOutput } from './output-host.js'
-import { assembleRunSummary, isPassStatus } from './telemetry.js'
+import { assembleRunSummary } from './telemetry.js'
+import { isPassStatus } from '../graph/index.js'
 import type { RunContextRecord } from './telemetry.js'
-import { defaultLogger, type DefaultLogger, resolveOutputView, type Logger } from './logger.js'
-import { detectColors, type ColorSupport } from './colors.js'
-import { plainOutput } from './plain-output.js'
-import { formatPersistentList } from './framed-output.js'
-import { createForecast } from './forecast.js'
-import { LocalHistoryProvider } from './history.js'
 import { plan, type RunPlan } from './plan.js'
 import type { AffectedReason } from './affected-tasks.js'
 import { prepareRun, type PreparedRun } from './prepare.js'
 import { acquireRunLock } from './run-lock.js'
-import {
-  forwardedSignal,
-  type StopSignal,
-  forwardSignals,
-  SIGNAL_SHUTDOWN_GRACE_MS,
-  terminateChildren,
-} from './signals.js'
+import { terminateChildren } from './signals.js'
+import { runStop } from './run-stop.js'
 import {
   hasPooledExecutor,
   placeTasks,
   planExecutorOf,
   poolOfPlacement,
   terminalHolders,
-  UNPLACED_EXECUTOR,
   locallyPlaced,
 } from './placement.js'
 import {
-  captureDefaultBranch,
+  telemetryRunContext,
   captureGitContext,
   captureHostContext,
-  captureWorkspaceIdentity,
   detectCi,
 } from './run-context.js'
 import { startRemotePrefetch } from './remote-prefetch.js'
@@ -106,26 +113,25 @@ import {
 import { deriveStableKeys, probesAfterWrites } from './stable-keys.js'
 
 import { writeRunFailures } from './run-failures.js'
-import { assembleRunRecords } from './run-records.js'
+import { assembleRunRecords, recordLateRemoteErrors } from './run-records.js'
 import {
   hasEnded,
-  selectKeepAlive,
-  serverConfig,
-  shutdownPersistent,
+  disposeServers,
+  failServer,
+  holdServers,
+  sessionEnd,
   takeHeldServers,
 } from './persistent.js'
-import {
-  runSummaryJson,
-  writeRunProfile,
-  writeRunSummary,
-  type RunSummaryJson,
-} from './run-artifacts.js'
+import { writeRunProfile } from './run-artifacts.js'
 import { createSaveLane } from './save-lane.js'
 import { commandWindows } from './command-windows.js'
-import { formatOutcomeTable, formatRunSummary } from './summary.js'
-import { detectFlaky, type FlakyCandidate, type FlakyFinding } from './failure-mode.js'
-import { createMissExplainer } from './miss-reason.js'
-import type { HeldServer, RunOptions, RunSummary } from './options.js'
+import {
+  createMissExplainer,
+  detectFlaky,
+  type FlakyCandidate,
+  LocalHistoryProvider,
+} from '../history/index.js'
+import type { RunOptions, RunSummary } from './options.js'
 import { withRunSettings } from './run-settings.js'
 import { resolveSetting } from '../settings.js'
 
@@ -138,20 +144,6 @@ const emptyShortCircuit = (): ShortCircuit => ({
   groupKeys: new Map(),
 })
 
-/**
- * Compact the 4-axis cache policy into the `invocations.cache_policy`
- * column string. Each enabled axis contributes its flag; a fully-on
- * policy reads `'lR,lW,rR,rW'`. Pure presentation — never affects the key.
- */
-function compactCachePolicy(p: CachePolicy): string {
-  const parts: string[] = []
-  if (p.localRead) parts.push('lR')
-  if (p.localWrite) parts.push('lW')
-  if (p.remoteRead) parts.push('rR')
-  if (p.remoteWrite) parts.push('rW')
-  return parts.join(',')
-}
-
 /**
  * The policy that will actually govern the run. The remote axes are inert
  * without a remote layer to serve them: a `remote:w` policy over a bare
@@ -201,17 +193,6 @@ function maskInvocation(command: string): string {
   return secretMask([process.env])?.mask(command) ?? command
 }
 
-/**
- * A run's `--tag`s, stored on its history row and handed to telemetry
- * (`vx.tag.<key>`): a tag that carries a secret is masked as the
- * invocation line that spells it is (L-38).
- */
-function maskTags(tags: Readonly<Record<string, string>>): Record<string, string> {
-  const mask = secretMask([process.env])
-  if (mask === null) return { ...tags }
-  return Object.fromEntries(Object.entries(tags).map(([k, v]) => [mask.mask(k), mask.mask(v)]))
-}
-
 /**
  * The command line a run hands to its telemetry sinks, with what follows
  * `--` counted, not quoted. Those are the task's arguments,
@@ -286,15 +267,11 @@ function refuseRunOptions(options: RunOptions): void {
     refuse('concurrency', concurrency, 'a positive integer')
   if (retries !== undefined && !(Number.isInteger(retries) && retries >= 0))
     refuse('retries', retries, 'a non-negative integer')
-  for (const [name, ms] of [
-    ['timeout', timeout],
-    ['killGrace', options.killGrace],
-    ['teardownTimeout', options.teardownTimeout],
-    ['readyNotice', options.readyNotice],
-  ] as const) {
-    if (ms !== undefined && !(Number.isInteger(ms) && ms > 0 && ms <= MAX_TIMEOUT_MS))
-      refuse(name, ms, `a positive integer of ms, at most ${MAX_TIMEOUT_MS}`)
-  }
+  if (
+    timeout !== undefined &&
+    !(Number.isInteger(timeout) && timeout > 0 && timeout <= MAX_TIMEOUT_MS)
+  )
+    refuse('timeout', timeout, `a positive integer of ms, at most ${MAX_TIMEOUT_MS}`)
 }
 
 export async function run(options: RunOptions): Promise<RunSummary> {
@@ -315,17 +292,12 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // See docs/design/event-stream-2026-06.md.
   const terminal =
     options.log === undefined
-      ? defaultLogger(
-          colors,
-          resolveOutputView(options),
-          options.json === true ? process.stderr : process.stdout,
-          {
-            coalesce: true,
-            ...(options.tty === true ? { tty: true } : {}),
-            ...(options.forwardArgs !== undefined ? { forwardArgs: options.forwardArgs } : {}),
-            ...(options.footer === false ? { footer: false } : {}),
-          },
-        )
+      ? defaultLogger(colors, resolveOutputView(options), process.stdout, {
+          coalesce: true,
+          ...(options.tty === true ? { tty: true } : {}),
+          ...(options.forwardArgs !== undefined ? { forwardArgs: options.forwardArgs } : {}),
+          ...(options.footer === false ? { footer: false } : {}),
+        })
       : null
   const sink = options.log ?? terminal!
   // An injected bus already has surfaces subscribed; we add the terminal
@@ -355,7 +327,10 @@ export async function run(options: RunOptions): Promise<RunSummary> {
         }
   let held = false
   try {
-    const summary = await runOnBus(options, bus, colors, terminal, takeOutput)
+    // vx's own steps are timed only where something renders them.
+    const showsSteps =
+      terminal !== null ? terminal.showsSteps : options.log?.stepStart !== undefined
+    const summary = await runOnBus(options, bus, colors, terminal, showsSteps, takeOutput)
     if (summary.persistent === undefined) return summary
     // Servers handed back still running still write: `vx watch dev` printed
     // none of its server's log while it idled, the renderer gone with this
@@ -379,9 +354,11 @@ async function runOnBus(
   bus: EventBus,
   colors: ColorSupport,
   terminal: DefaultLogger | null,
+  showsSteps: boolean,
   takeOutput?: (claimed: { logger: Logger; owner: string }) => void,
 ): Promise<RunSummary> {
   const log = busLogger(bus)
+  const { step, stepSync } = createSteps(log, showsSteps)
   // A server's output goes through a cell of its own: a later watch cycle
   // that keeps the server points it at that cycle's bus (`RunOptions.keep`).
   const serverOuts = new Map<string, { bus: EventBus }>()
@@ -395,7 +372,7 @@ async function runOnBus(
     }
   }
 
-  const prepared = await prepareRun(options, log)
+  const prepared = await step('vx:load', () => prepareRun(options, log))
   options = withRunSettings(options, prepared.workspaceConfig)
   mark('plugin stages')
   // Every exit from here tears the plugins down: their capability
@@ -405,11 +382,11 @@ async function runOnBus(
   // per cycle under `vx watch`. A plugin whose own setup threw set up
   // nothing, and is the one left out.
   let tornDown = false
-  const teardown = async (except?: unknown): Promise<void> => {
+  const teardown = async (except?: unknown, report?: RunReport): Promise<void> => {
     if (tornDown) return
     tornDown = true
     const plugins = prepared.plugins.filter((p) => p !== except)
-    await teardownPlugins(plugins, (m) => log.status(m))
+    await teardownPlugins(plugins, warnOf(log), report, step)
   }
   // A task whose command re-enters `vx run` in the workspace running it
   // is refused. When the inner run reaches this task again it forks a run
@@ -437,7 +414,7 @@ async function runOnBus(
   // A refusal is the caller's to print (on stderr, as `vx run:`): as a
   // status line it went to stdout, into whatever a script piped there.
   if (prepared.unresolvedTasks.length > 0) {
-    const refused = `no projects declare task(s): ${prepared.unresolvedTasks.join(', ')}.${elsewhereHint(prepared.declaredElsewhere)}${didYouMean(prepared.unresolvedTasks, prepared.hintProjects, prepared.declaredElsewhere)}${await initHint(prepared)}`
+    const refused = `no projects declare task(s): ${prepared.unresolvedTasks.join(', ')}.${await unresolvedHint(prepared)}`
     await teardown()
     prepared.cache.close()
     return { ok: false, outcomes: [], refused }
@@ -467,13 +444,24 @@ async function runOnBus(
   // the plugin. A plugin without `setup` subscribes nothing.
   let disposePlugins: (() => void) | undefined
   let telemetry: TelemetryHandle | undefined
+  // One run-id per `vx run` invocation. Every task in the resulting graph
+  // carries it so analytics queries can group by invocation; plugins get it
+  // in their teardown's `RunReport`.
+  const runId = ulid()
+  const head = captureGitContext(prepared.workspaceRoot)
+  const ciContext = detectCi(process.env)
+  const keepRunLog = prepared.keepRunEntry !== undefined
   try {
     disposePlugins = await installPlugins({
       plugins: prepared.plugins,
       bus,
       workspaceRoot: prepared.workspaceRoot,
       cacheDir: prepared.cacheDir,
-      warn: (m) => log.status(m),
+      warn: warnOf(log),
+      cache: prepared.cacheFor,
+      ci: ciContext.ci,
+      branch: prepared.branch(),
+      step,
     })
   } catch (err) {
     disposePlugins?.()
@@ -526,7 +514,7 @@ async function runOnBus(
     resolveExecutors(prepared.plugins, {
       workspaceRoot: prepared.workspaceRoot,
       cacheDir: prepared.cacheDir,
-      warn: (m: string) => log.status(m),
+      warn: warnOf(log),
       concurrency,
     }),
   )
@@ -550,51 +538,11 @@ async function runOnBus(
         : nodes.get(id)?.config.cache === undefined
           ? 'no remote executor accepted it — the task declares no `cache` block, so there is no input set to ship'
           : 'no remote executor accepted it'
-      log.status(`[vx] ${id}: exec.remote is 'only' and ${why} — nothing ran`)
-    }
-  }
-  // Demand: what each executor still has left to run. An executor that
-  // provisions per task (a container, an allocation, a pod) otherwise has to
-  // guess from `capacity` alone and hold everything until teardown. Built
-  // ONLY for executors that asked — with none declared there is no map, no
-  // set, and no call in the completion path.
-  const demandOf = new Map<TaskExecutor, Set<string>>()
-  for (const [id, executor] of placements.executors) {
-    if (executor.demand === undefined) continue
-    let remaining = demandOf.get(executor)
-    if (remaining === undefined) demandOf.set(executor, (remaining = new Set()))
-    remaining.add(id)
-  }
-  // The SAME set is handed back every time, narrowed in place: a consumer
-  // reading it later sees the truth rather than a stale snapshot. A hint,
-  // as `admit` is: one that throws is named once and asked no more, where
-  // it surfaced as a bare stack, or mid-run from the completion path
-  // (item 1022).
-  const tellDemand = (executor: TaskExecutor, remaining: ReadonlySet<string>): void => {
-    const failed = (err: unknown): void => {
-      if (!demandOf.delete(executor)) return
-      const m = err instanceof Error ? err.message : String(err)
-      log.status(`[vx] ${executorLabel(executor)} failed in demand: ${m}; not asked again this run`)
-    }
-    try {
-      // An `async demand` that rejects did so where no one listened: an
-      // unhandled rejection, a stack, the run killed. Its rejection is a
-      // throw like any other.
-      const ret: unknown = executor.demand!(remaining)
-      if (ret instanceof Promise) ret.catch(failed)
-    } catch (err) {
-      failed(err)
+      warnOf(log)(`[vx] ${id}: exec.remote is 'only' and ${why} — nothing ran`)
     }
   }
-  for (const [executor, remaining] of demandOf) tellDemand(executor, remaining)
-  const narrowDemand =
-    demandOf.size === 0
-      ? (): void => {}
-      : (id: string): void => {
-          for (const [executor, remaining] of demandOf) {
-            if (remaining.delete(id)) tellDemand(executor, remaining)
-          }
-        }
+  // Demand: what each executor still has left to run (`executorDemand`).
+  const narrowDemand = executorDemand(placements.executors, warnOf(log))
 
   // `cache.download` (default `all`) decides ONCE per task, here, whether a
   // remote execution's outputs come home.
@@ -621,88 +569,19 @@ async function runOnBus(
     | boolean
     | undefined
 
-  // Run-scoped registries of live subprocesses:
-  //   - `liveChildren`: in-flight children. The runner adds/removes
-  //     each child around its spawn (persistent children stay until
-  //     they exit).
-  //   - `persistentRegistry`: ready persistent tasks (dev servers,
-  //     watchers). executeTask spawns them but does NOT await their
-  //     exit; ownership moves here so the orchestrator can SIGTERM
-  //     them once the rest of the graph finishes.
-  //
-  // 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>>()
-  // A server that ends on its own while the graph still runs is said at
-  // once: its dependants were failing against it, and the end of the run
-  // was the first word of it (C-69). Not once the graph is done (the end
-  // of the run and the keep-alive wait say it) nor under a stop.
-  let graphDone = false
-  const persistentRegistry = new (class extends Map<string, ReturnType<typeof Bun.spawn>> {
-    override set(id: string, child: ReturnType<typeof Bun.spawn>): this {
-      super.set(id, child)
-      void child.exited.then((code) => {
-        if (code !== 0 && !graphDone && !stopRun.signal.aborted)
-          log.status(`vx: ${id} exited with code ${code} while the run went on`)
-      })
-      return this
-    }
-  })()
-  // 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 stoppedBy: StopSignal | undefined
-  let leftRun = (): void => {}
-  const runLeft = new Promise<void>((resolve) => {
-    leftRun = resolve
-  })
-  const signals = forwardSignals({
-    enabled: options.handleSignals ?? true,
+  const stop = runStop({
     log,
     cache,
-    liveChildren,
-    persistentRegistry,
-    stop: (signal) => {
-      stoppedBy = signal
-      stopRun.abort(signal)
-    },
-    done: runLeft,
+    external: options.signal,
+    handleSignals: options.handleSignals ?? true,
     handsTerminal: holders.size > 0,
-    // 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,
+    teardowns: prepared.plugins.filter((p) => p.teardown).length,
+    onStop: () => {
+      stopRuntimeProbes(hashCache.runtime, hashCache.workspaceRuntime)
+      cache.stopUploads?.()
+    },
   })
-  // 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
-  // The servers that had ended when the stop landed: those crashed. One that
-  // ends after it is the stop's own kill, and was named a crash (item 1061).
-  let endedBeforeStop: ReadonlySet<ReturnType<typeof Bun.spawn>> | undefined
-  const onAbort = (): void => {
-    stopRuntimeProbes(hashCache.runtime, hashCache.workspaceRuntime)
-    endedBeforeStop = new Set([...persistentRegistry.values()].filter(hasEnded))
-    aborting = terminateChildren(
-      () => [...liveChildren, ...persistentRegistry.values()],
-      forwardedSignal(stopRun.signal.reason),
-    )
-  }
-  if (stopRun.signal.aborted) onAbort()
-  else stopRun.signal.addEventListener('abort', onAbort, { once: true })
+  const { liveChildren, persistentRegistry } = stop
   // 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
@@ -729,15 +608,14 @@ async function runOnBus(
   // 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 abandoning(() =>
-    acquireRunLock(prepared.workspaceRoot, {
-      log: (m) => log.status(m),
-      signal: stopRun.signal,
-    }),
+    step('vx:run-lock', () =>
+      acquireRunLock(prepared.workspaceRoot, {
+        log: warnOf(log),
+        signal: stop.signal,
+      }),
+    ),
   )
   try {
-    // One run-id per `vx run` invocation. Every task in the resulting
-    // graph carries it so analytics queries can group by invocation.
-    const runId = ulid()
     const runStartHrTimeNs = process.hrtime.bigint()
     const endedAtMsAtStart = Date.now()
     const remoteCacheEnabled = prepared.hasRemoteLayer
@@ -748,7 +626,7 @@ async function runOnBus(
     // happened.
     const policy: CachePolicy = effectiveCachePolicy(prepared.cachePolicy, prepared.hasRemoteLayer)
     if (options.remoteRequested === true && !prepared.hasRemoteLayer) {
-      log.status(
+      warnOf(log)(
         'vx: --cache-policy named the remote cache, but no cache plugin in .vx/workspace.* supplies one — the remote axes are off for this run',
       )
     }
@@ -768,10 +646,10 @@ async function runOnBus(
     // second status spawn.
     // `run.branch` names the branch over git's (`prepared.branch`).
     const gitContext = {
-      ...captureGitContext(workspaceRoot, gitFilesCache.worktreeDirty),
+      ...head,
+      dirty: gitFilesCache.worktreeDirty,
       branch: prepared.branch(),
     }
-    const ciContext = detectCi(process.env)
     const hostContext = captureHostContext()
 
     // The canonical run-context record — the same git/CI/host data the
@@ -791,51 +669,29 @@ async function runOnBus(
     // but declines still pays — its answer is only knowable by asking.
     const hasTelemetryPlugin = prepared.plugins.some((p) => p.telemetry !== undefined)
     if (hasTelemetryPlugin || options.telemetrySinks !== undefined) {
-      // Workspace identity (telemetry v2), paid only when a telemetry
-      // consumer can exist — a plain run never reaches here. The remote URL
-      // is the enumeration's `git var -l`: a spawn here cost ~4 ms.
-      const wsIdentity = captureWorkspaceIdentity(
-        workspaceRoot,
-        gitFilesCache.configValue('remote.origin.url'),
-      )
-      runContextRecord = {
+      runContextRecord = telemetryRunContext({
         runId,
-        vxVersion: VERSION,
         // An embedder's `command` is redacted as the argv is: it passed a
         // token after `--` to every sink verbatim (C-67).
-        // Masked as the stored line is: `--tag key=$DEPLOY_KEY` sits before
+        // Masked as the stored line is: a flag's secret value sits before
         // the `--` the count covers (L-44).
         command: maskInvocation(
           invocationCommand(options.command?.split(' ') ?? process.argv.slice(1)),
         ),
-        requestedTasks: [...options.tasks],
-        cachePolicy: compactCachePolicy(policy),
+        requestedTasks: options.tasks,
+        cachePolicy: formatCachePolicy(policy),
         concurrency,
         flow: options.flow ?? null,
-        commitSha: gitContext.commitSha,
-        branch: gitContext.branch,
-        defaultBranch: captureDefaultBranch(process.env, workspaceRoot),
-        dirty: gitContext.dirty,
-        ci: ciContext.ci,
-        ciProvider: ciContext.provider,
-        ...(ciContext.runUrl !== undefined ? { ciRunUrl: ciContext.runUrl } : {}),
-        ...(ciContext.change !== undefined ? { ciChange: ciContext.change } : {}),
-        ...(ciContext.pipeline !== undefined ? { ciPipeline: ciContext.pipeline } : {}),
-        ...(ciContext.job !== undefined ? { ciJob: ciContext.job } : {}),
-        ...(ciContext.attempt !== undefined ? { ciAttempt: ciContext.attempt } : {}),
-        host: hostContext.host,
-        os: hostContext.os,
-        arch: hostContext.arch,
-        workspaceId: wsIdentity.id,
-        workspaceName: wsIdentity.name,
-        ...(wsIdentity.repository !== undefined ? { repository: wsIdentity.repository } : {}),
-        ...(wsIdentity.path !== undefined ? { workspacePath: wsIdentity.path } : {}),
-        tags: maskTags(options.tags ?? {}),
-      }
+        git: gitContext,
+        ci: ciContext,
+        host: hostContext,
+        workspaceRoot,
+        originUrl: gitFilesCache.configValue('remote.origin.url'),
+      })
       telemetry = await subscribeTelemetry(
         prepared.plugins,
         bus,
-        { workspaceRoot, cacheDir, warn: (m: string) => log.status(m) },
+        { workspaceRoot, cacheDir, warn: warnOf(log) },
         runContextRecord,
         options.telemetrySinks,
         nodes,
@@ -868,7 +724,7 @@ async function runOnBus(
     // each pack holds an artifact's bytes); a failed save is a miss next
     // time, said once — the task's work ran.
     const saveLane = createSaveLane(2 * concurrency, (err) =>
-      log.status(`[vx] cache save failed: ${err instanceof Error ? err.message : String(err)}`),
+      warnOf(log)(`[vx] cache save failed: ${err instanceof Error ? err.message : String(err)}`),
     )
     const deferredSaves = new Map<string, Promise<SaveFacts>>()
     const windows = commandWindows()
@@ -884,9 +740,10 @@ async function runOnBus(
     // for display. Marks `node.surfaced`; never touches `requested`.
     markSurfacedDeps(nodes)
 
-    // Header counts: unique projects covered by the graph (including
-    // dependsOn-pulled deps, not just the user-requested set), and the
-    // total number of real (non-group) task executions. Mirrors the
+    // Header counts: unique projects with a real (non-group) task in the
+    // graph (including dependsOn-pulled deps, not just the user-requested
+    // set; a `^build` placeholder in a project with no build is not one),
+    // and the total number of real task executions. Mirrors the
     // count the end-of-run summary reports under "total". The
     // requested count drives the focused logger's live-vs-buffered
     // decision, so surfaced nodes count toward it too — they display
@@ -895,8 +752,8 @@ async function runOnBus(
     let taskCount = 0
     let requestedCount = 0
     for (const node of nodes.values()) {
-      packagesInScope.add(node.projectName)
       if (!isGroupTask(node)) {
+        packagesInScope.add(node.projectName)
         taskCount++
         if (node.requested || node.surfaced === true) requestedCount++
       }
@@ -904,7 +761,7 @@ async function runOnBus(
     // Admission over the worker count is a plugin's (`admit`): built once
     // into the predicate the scheduler asks at every local dispatch. No
     // plugin answers → undefined → the count-only path, byte for byte.
-    const admit = buildAdmission(prepared.plugins, nodes, concurrency, (m) => log.status(m))
+    const admit = buildAdmission(prepared.plugins, nodes, concurrency, warnOf(log))
 
     // Run context for the footer. The top-of-run header is gone — the
     // banner now lives in the summary, where the eye lands at the end.
@@ -912,20 +769,25 @@ async function runOnBus(
       version: VERSION,
       packageCount: packagesInScope.size,
       remoteCacheEnabled,
+      cache: {
+        local: policy.localRead || policy.localWrite,
+        localWrite: policy.localWrite,
+        remote: remoteCacheEnabled && (policy.remoteRead || policy.remoteWrite),
+        traffic: prepared.localCache.traffic,
+        notDownloaded: () => deferredOutputs.pending().length,
+      },
       concurrency,
       workspaceProjectCount,
     }
 
     // Asked only when a plugin declares `output`: a plain run pays nothing.
     if (takeOutput !== undefined && prepared.plugins.some((p) => p.output !== undefined)) {
-      const json = options.json === true
       const claimed = await claimOutput(prepared.plugins, {
         workspaceRoot,
         cacheDir,
-        warn: (m: string) => log.status(m),
-        isTTY: (json ? process.stderr : process.stdout).isTTY === true,
+        warn: warnOf(log),
+        isTTY: process.stdout.isTTY === true,
         ci: ciContext.ci,
-        json,
       })
       if (claimed !== undefined) takeOutput(claimed)
     }
@@ -961,18 +823,21 @@ async function runOnBus(
     // unchanged (no upfront key pass, no local probing).
     let prefetchDone: Promise<void> = Promise.resolve()
     if (prepared.hasRemoteLayer) {
-      prefetchDone = startRemotePrefetch({
-        nodes,
-        cache,
-        workspaceRoot,
-        claimedFiles: fingerprintWatch.names,
-        forwardArgs: options.forwardArgs,
-        nestedDirsByProject,
-        gitFilesCache,
-        hashCache,
-        concurrency,
-        remoteRead: policy.remoteRead,
-      })
+      prefetchDone = step('vx:prefetch', () =>
+        startRemotePrefetch({
+          nodes,
+          cache,
+          workspaceRoot,
+          claimedFiles: fingerprintWatch.names,
+          forwardArgs: options.forwardArgs,
+          nestedDirsByProject,
+          gitFilesCache,
+          hashCache,
+          concurrency,
+          remoteRead: policy.remoteRead,
+          remoteWrite: policy.remoteWrite,
+        }),
+      )
     }
 
     // Local cache short-circuit (default-on). Up-front classify: derive
@@ -993,17 +858,19 @@ async function runOnBus(
       prepared.localCache.holdsNothing()
     if (coldLocal) prewarm()
     else if (shouldShortCircuit(nodes, policy, cache)) {
-      shortCircuit = await startLocalShortCircuit({
-        nodes,
-        cache,
-        workspaceRoot,
-        claimedFiles: fingerprintWatch.names,
-        forwardArgs: options.forwardArgs,
-        nestedDirsByProject,
-        gitFilesCache,
-        hashCache,
-        concurrency,
-      })
+      shortCircuit = await step('vx:keys', () =>
+        startLocalShortCircuit({
+          nodes,
+          cache,
+          workspaceRoot,
+          claimedFiles: fingerprintWatch.names,
+          forwardArgs: options.forwardArgs,
+          nestedDirsByProject,
+          gitFilesCache,
+          hashCache,
+          concurrency,
+        }),
+      )
       // A confirmed miss runs too.
       if (sandboxed.some((n) => shortCircuit.preProbed.get(n.id)?.hit === null)) prewarm()
     }
@@ -1014,7 +881,7 @@ async function runOnBus(
     // admission.ts.
     const excluded = excludedTaint(nodes)
     if (excluded.unsaved > 0) {
-      log.status(
+      warnOf(log)(
         `[vx] --exclude-dependencies: ${excluded.unsaved} cached task(s) build on a skipped dependency; what they build is not saved`,
       )
     }
@@ -1043,19 +910,50 @@ async function runOnBus(
     // The scheduler's fail-fast stop, as the retry loop of a task already
     // in flight sees it.
     const failFast = new AbortController()
-    // A literal of the fields every task carries, then each optional one
-    // assigned only when present: twelve conditional spreads per task cost
-    // ~18 ms of object copying on a 1,090-package warm run (X-149).
-    const track = telemetry?.track
-    const armSandbox = sandboxArmer !== null ? () => sandboxArmer.arm() : undefined
+    const scope: RunScope = {
+      workspaceRoot,
+      cache,
+      cachePolicy: policy,
+      forwardArgs: options.forwardArgs,
+      deferred: deferredOutputs,
+      cacheDir,
+      runStartHrTimeNs,
+      persistentRegistry,
+      liveChildren,
+      gitFilesCache,
+      hashCache,
+      probesAfterWrites: lateProbes,
+      fingerprintWatch,
+      keyedProjects: keyed,
+      outputDirSnapshots,
+      deferSave: saveLane.defer,
+      deferredSaves,
+      commandWindows: windows,
+      stopSignal: stop.signal,
+      failFast: failFast.signal,
+      inputStability,
+    }
+    if (options.retries !== undefined) scope.retries = options.retries
+    if (taskTimeoutDefault !== undefined) scope.timeout = taskTimeoutDefault
+    if (cleanOutputs !== undefined) scope.cleanOutputs = cleanOutputs
+    if (telemetry?.track !== undefined) scope.track = telemetry.track
+    if (explainMiss !== undefined) scope.explainMiss = explainMiss
+    if (keepRunLog) scope.keepRunLog = true
+    if (sandboxArmer !== null) scope.armSandbox = () => sandboxArmer.arm()
+    const argsOf = executeArgsOf(scope, {
+      log: (node) => (node.config.exec?.persistent !== undefined ? serverLog(node.id) : log),
+      placements,
+      nestedDirsByProject,
+      downloadModeOf: download.modeOf,
+      shortCircuit,
+      dependedOn,
+      holders,
+    })
     const buildExecuteArgs = (
       node: TaskNode,
       upstream: TaskOutcome[],
       reuseProbe = true,
     ): ExecuteArgs => {
-      const probe = reuseProbe ? shortCircuit.preProbed.get(node.id) : undefined
-      const upfrontKey = shortCircuit.uncachedKeys.get(node.id)
-      const upfrontGroupKey = shortCircuit.groupKeys.get(node.id)
       let deadServer: string | undefined
       if (options.continueMode === 'always') {
         for (const d of node.deps) {
@@ -1066,51 +964,7 @@ async function runOnBus(
       }
       const tainted = taint.judge(node, upstream)
       if (tainted) taintedRan.set(node.id, deadServer ?? taint.cause(node, upstream))
-      const a: ExecuteArgs = {
-        node,
-        upstream,
-        workspaceRoot,
-        cache,
-        cachePolicy: policy,
-        forwardArgs: options.forwardArgs,
-        log: node.config.exec?.persistent !== undefined ? serverLog(node.id) : log,
-        executor: placements.executors.get(node.id) ?? UNPLACED_EXECUTOR,
-        deferred: deferredOutputs,
-        nestedProjectDirs: nestedDirsByProject.get(node.projectName) ?? [],
-        cacheDir,
-        runStartHrTimeNs,
-        persistentRegistry,
-        liveChildren,
-        gitFilesCache,
-        hashCache,
-        probesAfterWrites: lateProbes,
-        fingerprintWatch,
-        keyedProjects: keyed,
-        outputDirSnapshots,
-        deferSave: saveLane.defer,
-        deferredSaves,
-        commandWindows: windows,
-        stopSignal: stopRun.signal,
-        failFast: failFast.signal,
-      }
-      if (options.retries !== undefined) a.retries = options.retries
-      if (taskTimeoutDefault !== undefined) a.timeout = taskTimeoutDefault
-      if (options.readyNotice !== undefined) a.readyNotice = options.readyNotice
-      a.inputStability = inputStability
-      if (cleanOutputs !== undefined) a.cleanOutputs = cleanOutputs
-      if (download.modeOf.get(node.id) === 'deferred') a.download = 'deferred'
-      if (placements.remoteOnlyNoop.has(node.id)) a.remoteOnlyNoop = true
-      if (placements.remoteOnly.has(node.id)) a.remoteOnly = true
-      if (track !== undefined) a.track = track
-      if (explainMiss !== undefined) a.explainMiss = explainMiss
-      if (probe !== undefined) a.preProbed = probe
-      if (upfrontKey !== undefined) a.upfrontKey = upfrontKey
-      if (upfrontGroupKey !== undefined) a.upfrontGroupKey = upfrontGroupKey
-      if (tainted) a.taintedUpstream = true
-      if (!dependedOn.has(node.id)) a.noDependants = true
-      if (holders.has(node.id)) a.terminal = true
-      if (armSandbox !== undefined) a.armSandbox = armSandbox
-      return a
+      return argsOf(node, upstream, reuseProbe, tainted)
     }
 
     const executeWithDedup = admitTasks({
@@ -1136,13 +990,12 @@ async function runOnBus(
       (n) => n.config.exec?.command === undefined || shortCircuit.restoreTier.has(n.id),
     )
       ? new Map<string, number>()
-      : await prepared.priorities()
+      : await step('vx:schedule', () => prepared.priorities())
     mark('schedule')
     // Judged as each task finishes, against the history BEFORE this run's
     // rows land, so the row that prints next carries the verdict: nothing
     // prints below the footer. A hit or a skip asks nothing; a green miss
     // is one probe of the failed-row index.
-    const flaky: FlakyFinding[] = []
     const historyDb = prepared.localCache.dbHandle()
     const cacheOff = cachesNothing(policy)
     const judgeFlaky = (o: TaskOutcome): void => {
@@ -1151,7 +1004,6 @@ async function runOnBus(
       try {
         const found = detectFlaky(historyDb, candidates)[0]
         if (found === undefined) return
-        flaky.push(found)
         o.flaky = { passes: found.passes, failures: found.failures }
       } catch {
         // History is observability: an unreadable one judges nothing.
@@ -1187,7 +1039,7 @@ async function runOnBus(
       ...(options.continueMode !== undefined ? { continueMode: options.continueMode } : {}),
       serverDied,
       onFailFast: () => failFast.abort(),
-      signal: stopRun.signal,
+      signal: stop.signal,
       onStart: (node) => {
         log.taskStart?.(node)
       },
@@ -1238,7 +1090,7 @@ async function runOnBus(
       // Empty when the short-circuit didn't fire → byte-identical.
       restoreTier: shortCircuit.restoreTier,
     })
-    graphDone = true
+    stop.graphDone()
 
     // Which persistent children outlive the graph, and the bounded SIGTERM
     // of the rest, before the summary prints. Scoped to the real CLI
@@ -1248,49 +1100,19 @@ async function runOnBus(
     // expect run() to return, not block on a server.
     const foreground = options.log === undefined && (options.handleSignals ?? true)
     // An aborted run's children are already being torn down: nothing to hold.
-    const hold = options.holdPersistent === true && !stopRun.signal.aborted
-    // A run that failed elsewhere holds nothing: `vx run dev --all` with one
-    // server that never became ready sat on the others for good, so a
-    // script hung, and the Ctrl-C that ended it read 130 over the failure
-    // (C-60). A kept server's own crash ends the wait below as before, and
-    // `--continue=always` asked to keep going, and does. The watch loop
-    // (`holdPersistent`) still holds: a failing test in a cycle stopped
-    // the dev server the next change would restart anyway.
-    let keepAlive = selectKeepAlive(persistentRegistry, nodes, foreground || hold)
-    const failedElsewhere =
-      ![...outcomes.values()].every((o) => isPassStatus(o.status)) ||
-      [...persistentRegistry.values()].some(
-        (c) => hasEnded(c) && c.exitCode !== 0 && !keepAlive.children.includes(c),
-      )
-    if (failedElsewhere && !hold && options.continueMode !== 'always')
-      keepAlive = { nodes: [], children: [] }
-    const crashedPersistent = (
-      await shutdownPersistent(persistentRegistry, keepAlive.children)
-    ).filter((c) => endedBeforeStop?.has(persistentRegistry.get(c.id)!) ?? true)
+    const hold = options.holdPersistent === true && !stop.signal.aborted
+    const { keepAlive, crashed: crashedPersistent } = await disposeServers({
+      registry: persistentRegistry,
+      nodes,
+      outcomes,
+      keep: foreground || hold,
+      hold,
+      continueAlways: options.continueMode === 'always',
+      endedBeforeStop: stop.endedBeforeStop,
+    })
 
     mark('run graph')
 
-    // 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
-    // over the run's red exit (item 1071). A kept one that has already
-    // died is the same; the keep-alive wait below names it. Its code is its
-    // own, or the shell's report of the signal that took it.
-    const failServer = (id: string, code: number | string): void => {
-      const o = outcomes.get(id)
-      if (o === undefined) return
-      // 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) => {
-      const child = keepAlive.children[i]!
-      if (!hasEnded(child) || child.exitCode === 0) return
-      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()]
@@ -1316,7 +1138,7 @@ async function runOnBus(
     // 1102).
     for (const c of crashedPersistent) {
       const code = typeof c.code === 'number' ? c.code : signalExitCode(c.code)
-      log.status(`vx: ${c.id} exited with code ${code} before the run stopped it`)
+      warnOf(log)(`vx: ${c.id} exited with code ${code} before the run stopped it`)
     }
     // Outputs that never came home are not an error, but a silent `dist/`
     // that is empty-or-stale would be: name every task whose bytes are
@@ -1324,7 +1146,7 @@ async function runOnBus(
     const stillDeferred = deferredOutputs.pending()
     if (stillDeferred.length > 0) {
       log.status(
-        `  Deferred: ${stillDeferred.length} task(s) left outputs remote (--cache-download=none): ${stillDeferred.join(', ')}`,
+        `  Deferred: left outputs remote (--cache-download=none): ${stillDeferred.join(', ')}`,
       )
     }
 
@@ -1332,56 +1154,20 @@ async function runOnBus(
     // change the run's exit code — the run already happened.
     // Written again after the keep-alive wait: a kept server's crash or a
     // Ctrl-C there is the process's exit, and the first write said ok.
-    let json: RunSummaryJson | undefined
-    const summarize = async (runOk: boolean, final = list): Promise<void> => {
-      if (options.json === true) {
-        json = runSummaryJson({
-          runId,
-          startedAtMs: endedAtMsAtStart,
-          endedAtMs,
-          totalMs,
-          ok: runOk,
-          ...(stoppedBy !== undefined && { exitCode: signalExitCode(stoppedBy) }),
-          outcomes: final,
-          flaky,
-        })
-      }
-      if (options.summarize === undefined) return
-      // The rewrite after the keep-alive wait says nothing: the footer is
-      // the run's last word.
-      const quiet = final !== list
-      try {
-        const wrote = await writeRunSummary({
-          target: options.summarize,
-          cacheDir,
-          cwd: options.cwd,
-          runId,
-          startedAtMs: endedAtMsAtStart,
-          endedAtMs,
-          totalMs,
-          ok: runOk,
-          ...(stoppedBy !== undefined && { exitCode: signalExitCode(stoppedBy) }),
-          outcomes: final,
-          flaky,
-        })
-        if (!quiet) log.status(`vx: summary written to ${wrote}`)
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err)
-        log.status(`vx: failed to write summary: ${msg}`)
-      }
-    }
-    await summarize(ok)
-    if (options.profile !== undefined) {
+    const profile = options.profile
+    if (profile !== undefined) {
       try {
-        const wrote = await writeRunProfile({
-          target: options.profile,
-          cwd: options.cwd,
-          outcomes: list,
-        })
+        const wrote = await step('vx:profile', () =>
+          writeRunProfile({
+            target: profile,
+            cwd: options.cwd,
+            outcomes: list,
+          }),
+        )
         log.status(`vx: profile written to ${wrote}`)
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err)
-        log.status(`vx: failed to write profile: ${msg}`)
+        warnOf(log)(`vx: failed to write profile: ${msg}`)
       }
     }
     // Record each task to the run history in a single SQLite transaction
@@ -1405,15 +1191,15 @@ async function runOnBus(
         // own output masks it, so cache.db holds no plaintext value.
         command: maskInvocation(options.command ?? process.argv.slice(1).join(' ')),
         requestedTasks: options.tasks,
-        cachePolicy: compactCachePolicy(policy),
+        cachePolicy: formatCachePolicy(policy),
         concurrency,
         flow: options.flow ?? null,
         forwardArgs: options.forwardArgs,
-        tags: maskTags(options.tags ?? {}),
         git: gitContext,
         ci: ciContext,
         host: hostContext,
         withTelemetry: telemetry !== undefined,
+        remoteTraffic: prepared.localCache.traffic.keys,
       })
     const records = recordsOf(list, ok)
     const recordHistory = (write: () => void): void => {
@@ -1425,27 +1211,21 @@ async function runOnBus(
         // 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`)
+        warnOf(log)(`[vx] run history not recorded: ${message} — the verdict above stands`)
       }
     }
     // A server kept in the foreground can still fail the run after the
     // cache closes: its history is written once the wait has decided, or it
     // read `ok` over the exit 1 and fed the flaky list a pass (X-23).
-    const historyAfterWait = keepAlive.children.length > 0 && !hold && stoppedBy === undefined
-    // A failed task's output, for `vx last` and an agent: files beside the
-    // index, so a refused write (a full disk, a read-only cache dir) costs
-    // only that output.
-    const recordFailures = (final: readonly TaskOutcome[]): void => {
-      try {
-        writeRunFailures(prepared.cacheDir, runId, final)
-      } catch (err) {
-        if (!isFsRefusal(err)) throw err
-        log.status(`[vx] failed tasks' output not kept: ${err.message} — the verdict above stands`)
-      }
-    }
-    if (stoppedBy === undefined && !historyAfterWait) {
-      recordHistory(() => cache.recordRunBundle(records))
-      recordFailures(list)
+    const historyAfterWait = keepAlive.children.length > 0 && !hold && stop.stoppedBy === undefined
+    // A failed task's output, for `vx last` and an agent (run-failures.ts).
+    const recordFailures = (final: readonly TaskOutcome[]): void =>
+      writeRunFailures(prepared.cacheDir, runId, final, warnOf(log))
+    if (stop.stoppedBy === undefined && !historyAfterWait) {
+      stepSync('vx:history', () => {
+        recordHistory(() => cache.recordRunBundle(records))
+        recordFailures(list)
+      })
     }
     mark('record history')
     // Drain any still-in-flight background prefetches before closing the
@@ -1463,13 +1243,29 @@ async function runOnBus(
     // channel shut from under the upload — silently losing every remote
     // 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 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?.()
+    await step('vx:uploads', async () => {
+      await prefetchDone
+      await cache.drainUploads?.()
+    })
+    // An upload that failed after the rows went in: its row says so too.
+    if (prepared.localCache.uploads.failed > 0 && stop.stoppedBy === undefined && !historyAfterWait)
+      recordHistory(() => recordLateRemoteErrors(prepared.localCache, records.runs, runId))
+    const report = await step('vx:keep-run', () =>
+      keepRunBytes(list, {
+        runId,
+        commit: head.commitSha,
+        ciRun: ciContext,
+        ok,
+        workspaceRoot: prepared.workspaceRoot,
+        nestedDirsByProject: prepared.nestedDirsByProject,
+        keep: prepared.keepRunEntry,
+      }),
+    )
     // Hand the per-run summary to the telemetry sinks + drain them. Only
     // when a sink is active (telemetry !== undefined) — otherwise this
     // whole block is skipped and the run is byte-identical to before.
@@ -1488,72 +1284,52 @@ async function runOnBus(
         uploads: prepared.localCache.uploads,
       })
       telemetry.emitSummary(summary)
-      await telemetry.flush()
+      const sinks = telemetry
+      await step('vx:telemetry', () => sinks.flush())
     }
     // End-of-run plugin lifecycle: each plugin's teardown(). Crash-isolated
     // + time-bounded inside teardownPlugins, so a faulty plugin can neither
     // fail nor hang the run. Here on the normal path, after the drains
     // above; every other exit takes it through `teardown` too.
-    // 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; the rows land together at close, in one transaction.
-    // Each walk is held to its entry's rows (item 1087), read here in one
-    // batch: read per snapshot, each read also flushed the snapshots before
-    // it, one transaction apiece (+110 ms at 1,000).
-    const snapshotRows = new Map<string, ReadonlyArray<{ path: string }>>()
-    for (let i = 0; i < outputDirSnapshots.length; i += 900) {
-      const batch = cache.loadOutputFilesBatch(
-        outputDirSnapshots.slice(i, i + 900).map((s) => s.hash),
-      )
-      for (const [hash, rows] of batch) snapshotRows.set(hash, rows)
-    }
-    for (let i = 0; i < outputDirSnapshots.length; i += 32) {
-      await Promise.all(
-        outputDirSnapshots
-          .slice(i, i + 32)
-          .map((s) =>
-            cache.recordOutputDirs?.(s.hash, s.projectDir, s.prefixes, (files) =>
-              s.holds(files, snapshotRows.get(s.hash) ?? []),
-            ),
-          ),
-      )
-    }
+    // The miss path's output-directory snapshots first (miss-save.ts).
+    await step('vx:snapshots', () => recordOutputDirSnapshots(cache, outputDirSnapshots))
     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)
+    if (!stop.signal.aborted) await step('vx:retention', () => applyCacheRetention(prepared))
     // A plugin hears the run until its teardown and nothing after: released
     // only in the finally, its handlers heard a kept server through the
     // whole keep-alive wait below (C-66). Idempotent; the finally's stay.
     disposePlugins?.()
     telemetry?.dispose()
-    await teardown()
-    await closeCache()
+    await teardown(undefined, report)
+    await step('vx:close', closeCache)
     mark('close')
     printTimings()
 
     // Tear down SRT's network bridge + (on macOS) log monitor. No-op if
     // no task was sandboxed; otherwise SRT keeps proxy servers alive and
     // the next vx run would init on top of stale state.
-    await prewarming
-    if (sandboxArmer?.armed) {
-      try {
-        await resetSandbox()
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err)
-        log.status(`vx: sandbox cleanup failed: ${msg}`)
+    await step('vx:sandbox', async () => {
+      await prewarming
+      if (sandboxArmer?.armed) {
+        try {
+          await resetSandbox()
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err)
+          warnOf(log)(`vx: sandbox cleanup failed: ${msg}`)
+        }
       }
-    }
+    })
 
     // The footer is the run's last word (owner, 2026-10-06): it prints once
     // the run's own work is done, history, uploads, plugin teardown and the
     // sandbox reset included, so any warning they raise lands above it. A
     // task's own facts (flaky, blocked) ride its row. Only a kept server's
     // own output follows.
+    // The footer replaces the live region in place.
+    log.runDone?.()
     if (options.summaryTable === true) for (const line of formatOutcomeTable(list)) log.status(line)
-    const above = options.beforeFooter?.(list, ok)
-    if (above) log.status(above.replace(/\n$/, ''))
     if (options.footer !== false)
       for (const line of formatRunSummary(list, totalMs, colors, runContext)) log.status(line)
 
@@ -1572,57 +1348,18 @@ async function runOnBus(
     // 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
-      // A held server that dies on its own is said, as the foreground's
-      // keep-alive says it: `vx watch` sat on "watching" over a dead dev
-      // server. The holder's own stop() is not such a death.
-      let stopping = false
-      // Taken by a later run (`RunOptions.keep`): kept or stopped there.
-      const handed = new Set<ReturnType<typeof Bun.spawn>>()
-      const servers = new Map<string, HeldServer>()
-      keepAlive.nodes.forEach((n, i) => {
-        const child = held[i]!
-        servers.set(n.id, {
-          child,
-          config: serverConfig(n, options.forwardArgs),
-          out: serverOuts.get(n.id) ?? { bus },
-          handOver: () => void handed.add(child),
-        })
-        // One that died during the graph was said then.
-        if (hasEnded(child)) return
-        void child.exited.then((code) => {
-          if (!stopping && !handed.has(child) && code !== 0)
-            log.status(`vx: ${n.id} exited with code ${code}`)
-        })
-      })
       return {
         ok,
         outcomes: list,
-        persistent: {
-          ids: keepAlive.nodes.map((n) => n.id),
-          servers,
-          stop: (signal) => {
-            stopping = true
-            return terminateChildren(() => held.filter((c) => !handed.has(c)), signal)
-          },
-        },
+        persistent: holdServers(keepAlive, {
+          forwardArgs: options.forwardArgs,
+          outOf: (id) => serverOuts.get(id) ?? { bus },
+          warn: warnOf(log),
+        }),
       }
     }
     if (keepAlive.children.length > 0) {
-      // 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 first = await sessionEnd(keepAlive)
       const node = keepAlive.nodes[first.i]!
       // Only the ones still up are stopped: a kept server already dead was
       // counted as one (WD-11).
@@ -1630,8 +1367,8 @@ async function runOnBus(
       // 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(
+      if (!stop.signal.aborted) {
+        warnOf(log)(
           `vx: ${node.id} exited with code ${first.code}` +
             (others > 0
               ? `; stopping ${others} other persistent task${others === 1 ? '' : 's'}`
@@ -1641,14 +1378,11 @@ async function runOnBus(
       // 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(() => {})
+      if (stop.signal.aborted) await stop.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).
-      if (!stopRun.signal.aborted && first.code !== 0) failServer(node.id, first.code)
+      // The server that ended the session on its own, not cleanly, failed.
+      if (!stop.signal.aborted && first.code !== 0) failServer(outcomes, node.id, first.code)
       const final = [...outcomes.values()]
-      await summarize(ok && first.code === 0, final)
       if (historyAfterWait) {
         recordHistory(() => {
           // A writer's open: another vx version may have reset the index
@@ -1662,10 +1396,10 @@ async function runOnBus(
         })
         recordFailures(final)
       }
-      return { ok: ok && first.code === 0, outcomes: final, ...(json && { json }) }
+      return { ok: ok && first.code === 0, outcomes: final }
     }
 
-    return { ok, outcomes: list, ...(json && { json }) }
+    return { ok, outcomes: list }
   } finally {
     // Idempotent. The status-line ticker starts in runStart, and every
     // call between it and the success path's runEnd is crash-isolated
@@ -1675,9 +1409,8 @@ async function runOnBus(
     // 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', forwardAbort)
-    stopRun.signal.removeEventListener('abort', onAbort)
+    log.runDone?.()
+    stop.detach()
     // Plugins installed at the top of run() get their bus subscriptions
     // released here. Idempotent; safe even if installPlugins threw.
     disposePlugins?.()
@@ -1694,9 +1427,9 @@ async function runOnBus(
     } catch {
       // teardown must not throw on the way out
     }
-    await aborting?.catch(() => {})
+    await stop.aborting?.catch(() => {})
     // Last: a process signal waits for this before it exits.
-    leftRun()
+    stop.left()
   }
 }
 
@@ -1741,7 +1474,7 @@ function noneAffected(prepared: PreparedRun, options: RunOptions): string {
  * Planning mode. Same setup as `run()` — workspace discovery, config
  * load, package graph, task graph — but stops short of execution.
  * Returns a `RunPlan` predicting the cache hit/miss outcome of every
- * task. Used by `--dry-run` and `--graph`.
+ * task. Used by `--dry`.
  *
  * Side-effects are limited to opening + closing the local Cache handle
  * (and running `cache.inputs.runtime` probe commands, which key
@@ -1761,7 +1494,7 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
       return {
         tasks: [],
         unresolvedTasks: prepared.unresolvedTasks,
-        unresolvedHint: `${elsewhereHint(prepared.declaredElsewhere)}${didYouMean(prepared.unresolvedTasks, prepared.hintProjects, prepared.declaredElsewhere)}${await initHint(prepared)}`,
+        unresolvedHint: await unresolvedHint(prepared),
       }
     }
     if (prepared.empty === 'no-tasks-declared' && prepared.declaredElsewhere.length > 0) {
@@ -1816,7 +1549,7 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
   } finally {
     // The plan called the cache and executor factories; teardown releases
     // what they opened, as a run's end does (item 1021).
-    await teardownPlugins(prepared.plugins, (m) => log.status(m))
+    await teardownPlugins(prepared.plugins, warnOf(log))
     prepared.cache.close()
     // The same table a run prints: a dry run is how the prepare stages
     // (discovery, config load, the git enumeration) get profiled on a
@@ -1865,6 +1598,31 @@ function elsewhereHint(names: readonly string[]): string {
   return ` Only projects outside the selection declare ${names.join(', ')} — pass --all, or --filter to pick them.`
 }
 
+/**
+ * What follows "no projects declare task(s): …": where the name is, its
+ * nearest spelling, and, with neither, the lock a run reads its configs
+ * from: a task just added to a vx.config is not in it until `vx lock`.
+ */
+async function unresolvedHint(prepared: {
+  unresolvedTasks: readonly string[]
+  hintProjects: ReadonlyMap<string, ProjectEntry>
+  declaredElsewhere: readonly string[]
+  anyProjectConfig: boolean
+}): Promise<string> {
+  const elsewhere = elsewhereHint(prepared.declaredElsewhere)
+  const near = didYouMean(
+    prepared.unresolvedTasks,
+    prepared.hintProjects,
+    prepared.declaredElsewhere,
+  )
+  const init = await initHint(prepared)
+  const lock =
+    init === '' && elsewhere === '' && !near.startsWith(' Did you mean')
+      ? ' A run reads the lock: after editing a vx.config, run `vx lock`.'
+      : ''
+  return `${elsewhere}${near}${init}${lock}`
+}
+
 /**
  * The first-run case, told apart from a typo: no project in the workspace
  * has a `vx.config.*` at all, so no name could have resolved. Reached only