@vzn/vx 0.0.18 → 0.0.21

package/src/orchestrator/logger.ts

@@ -20,6 +20,7 @@ import { formatDuration, formatSummarySection, type RunContext } from './summary
 import { isGroupTask } from '../graph/index.js'
 import { appendTail, createTail, resetTail, tailText, type Tail } from '../util/index.js'
 import { isCacheHit } from './telemetry.js'
+import { outcomeWord } from './events.js'
 
 export interface Logger {
   /** Header / footer / status text. Written verbatim, one trailing \n added. */
@@ -124,19 +125,8 @@ function ghaFence(body: string, token: string): string {
   return `::stop-commands::${token}\n${body}::${token}::\n`
 }
 
-/** The unified outcome vocabulary word for a non-failed outcome. */
-function outcomeWord(o: TaskOutcome): string {
-  switch (o.status) {
-    case 'success':
-      return 'success'
-    case 'cache-hit':
-      return o.restored === false ? 'up-to-date' : 'restored-local'
-    case 'cache-hit-remote':
-      return o.restored === false ? 'up-to-date' : 'restored-remote'
-    default:
-      return o.status
-  }
-}
+const cacheWordOf = (n: TaskNode): 'miss' | 'no-cache' =>
+  n.config.cache === undefined ? 'no-cache' : 'miss'
 
 export function resolveOutputView(
   options: {
@@ -182,8 +172,6 @@ export function defaultLogger(
   // a one-liner or streamed output since the last block does.
   let lineEmitted = false
   let streamedSinceBlock = false
-  // Ids whose output went straight to the terminal (focused mode).
-  const streamed = new Set<string>()
   // True while the live stream sits mid-line (chunk without trailing
   // newline) — the frame close must not glue onto partial output.
   let streamMidLine = false
@@ -257,6 +245,8 @@ export function defaultLogger(
   let slots: (WorkerSlot | null)[] = []
   const slotQueue: WorkerSlot[] = []
   let succeeded = 0
+  // Executed with no `cache` block: never a miss, counted apart.
+  let noCache = 0
   let upToDate = 0
   let restoredLocal = 0
   let restoredRemote = 0
@@ -311,7 +301,8 @@ export function defaultLogger(
         upToDate,
         restoredLocal,
         restoredRemote,
-        miss: succeeded + failed,
+        miss: succeeded + failed - noCache,
+        noCache,
         left: total - done,
         spread:
           spreadCount > 0
@@ -472,7 +463,6 @@ export function defaultLogger(
     taskStdout(node, chunk) {
       if (discardsOutput) return
       if (streamsLive(node)) {
-        streamed.add(node.id)
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
         writer.write(chunk)
@@ -488,7 +478,6 @@ export function defaultLogger(
     taskStderr(node, chunk) {
       if (discardsOutput) return
       if (streamsLive(node)) {
-        streamed.add(node.id)
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
         writer.write(chunk)
@@ -534,6 +523,7 @@ export function defaultLogger(
         done++
         if (outcome.status === 'failed') {
           failed++
+          if (node.config.cache === undefined) noCache++
         } else if (node.config.exec?.persistent !== undefined && outcome.status === 'success') {
           // A persistent task's outcome arrives at READY; the child
           // keeps running until the orchestrator SIGTERMs it at run
@@ -557,6 +547,7 @@ export function defaultLogger(
         switch (outcome.status) {
           case 'success':
             succeeded++
+            if (node.config.cache === undefined) noCache++
             break
           case 'cache-hit':
             if (outcome.restored === false) upToDate++
@@ -593,7 +584,7 @@ export function defaultLogger(
         }
         case 'errors-only':
           if (outcome.status !== 'failed') return
-          emitLine(formatFailureLine(node.id, outcome.durationMs, colors))
+          emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
           deferredFailures.push(
             formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors),
           )
@@ -605,7 +596,7 @@ export function defaultLogger(
           // surface in the end-of-run summary.
           if (outcome.status === 'failed') {
             // ✗ marker now; the full frame replays at runEnd.
-            emitLine(formatFailureLine(node.id, outcome.durationMs, colors))
+            emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
             deferredFailures.push(
               formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors),
             )
@@ -640,7 +631,7 @@ export function defaultLogger(
             // to runEnd like everywhere else; everything else emits
             // ONE atomic block from the buffered output.
             if (outcome.status === 'failed') {
-              emitLine(formatFailureLine(node.id, outcome.durationMs, colors))
+              emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
               deferredFailures.push(
                 formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors),
               )
@@ -654,7 +645,7 @@ export function defaultLogger(
           // Dependency-pulled nodes: silent on success; failures get
           // the ✗ marker now and their frame replayed at runEnd.
           if (outcome.status === 'failed') {
-            emitLine(formatFailureLine(node.id, outcome.durationMs, colors))
+            emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
             deferredFailures.push(
               formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors),
             )

package/src/orchestrator/metrics.ts

@@ -30,6 +30,8 @@ export interface RunSummaryRow {
   startedAt: number
   endedAt: number
   cacheHit: boolean | null
+  /** Whether the task declared a `cache` block; null on rows older than the column. */
+  cached: boolean | null
   hash: string
   cpuMs: number | null
   peakRssBytes: number | null
@@ -65,8 +67,12 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
     params.push(args.runId)
   }
   const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''
-  type RawRow = Omit<RunSummaryRow, 'cacheHit' | 'wallclockStartNs' | 'wallclockEndNs'> & {
+  type RawRow = Omit<
+    RunSummaryRow,
+    'cacheHit' | 'cached' | 'wallclockStartNs' | 'wallclockEndNs'
+  > & {
     cacheHit: number | null
+    cached: number | null
     wallclockStartNs: bigint | null
     wallclockEndNs: bigint | null
   }
@@ -74,7 +80,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
     .query(
       `SELECT run_id AS runId, project, task, status, exit_code AS exitCode,
               duration_ms AS durationMs, started_at AS startedAt, ended_at AS endedAt,
-              cache_hit AS cacheHit, hash,
+              cache_hit AS cacheHit, cached, hash,
               cpu_ms AS cpuMs, peak_rss_bytes AS peakRssBytes,
               wallclock_start_ns AS wallclockStartNs, wallclock_end_ns AS wallclockEndNs
        FROM runs ${clause} ORDER BY started_at DESC LIMIT ?`,
@@ -83,6 +89,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
   return rows.map((r) => ({
     ...r,
     cacheHit: r.cacheHit === null ? null : Boolean(r.cacheHit),
+    cached: r.cached === null ? null : Boolean(r.cached),
     wallclockStartNs: r.wallclockStartNs === null ? null : r.wallclockStartNs.toString(),
     wallclockEndNs: r.wallclockEndNs === null ? null : r.wallclockEndNs.toString(),
   }))
@@ -350,7 +357,14 @@ export interface WhyDidThisRerun {
   runId: string
   taskId: string
   found: boolean
-  thisRun?: { hash: string; status: string; cacheHit: boolean | null; startedAt: number }
+  thisRun?: {
+    hash: string
+    status: string
+    cacheHit: boolean | null
+    /** Whether the task declared a `cache` block; null on rows older than the column. */
+    cached: boolean | null
+    startedAt: number
+  }
   previousRun?: { hash: string; status: string; cacheHit: boolean | null; startedAt: number } | null
   hashChanged?: boolean | null
   note: string
@@ -370,11 +384,17 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      `SELECT hash, status, cache_hit AS cacheHit, started_at AS startedAt
+      `SELECT hash, status, cache_hit AS cacheHit, cached, started_at AS startedAt
        FROM runs WHERE run_id = ? AND project = ? AND task = ?`,
     )
     .get(runId, project, task) as
-    | { hash: string; status: string; cacheHit: number | null; startedAt: number }
+    | {
+        hash: string
+        status: string
+        cacheHit: number | null
+        cached: number | null
+        startedAt: number
+      }
     | undefined
   if (!this_) {
     return {
@@ -403,24 +423,32 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
     runId,
     taskId,
     found: true,
-    thisRun: { ...this_, cacheHit: this_.cacheHit === null ? null : Boolean(this_.cacheHit) },
+    thisRun: {
+      ...this_,
+      cacheHit: this_.cacheHit === null ? null : Boolean(this_.cacheHit),
+      cached: this_.cached === null ? null : Boolean(this_.cached),
+    },
     previousRun: prev
       ? { ...prev, cacheHit: prev.cacheHit === null ? null : Boolean(prev.cacheHit) }
       : null,
     hashChanged: prev && !noKey ? prev.hash !== this_.hash : null,
     note: noKey
       ? 'this task recorded no cache key (skipped, or a persistent task) — nothing to compare'
-      : prev && prev.hash !== this_.hash
-        ? 'cache key changed between the previous run and this one (inputs differ)'
-        : prev
-          ? // An unchanged key has two very different endings, and calling
-            // both a "re-run" answered the question wrong: a cache HIT did not
-            // re-run at all, so blaming `--no-cache` named a cause that cannot
-            // have applied. Only a run that EXECUTED on an unchanged key is
-            // the case this verb exists to explain. A row with no recorded
-            // cacheHit (older rows) is neither — say that, do not guess.
-            unchangedKeyNote(this_.cacheHit)
-          : 'no prior run for this (project, task)',
+      : this_.cached === 0
+        ? // Not a cache decision at all: the task runs every time by design,
+          // and its key is derived only so dependents can fold it.
+          'this task declares no `cache` block — it runs on every invocation; its key is folded by dependents only'
+        : prev && prev.hash !== this_.hash
+          ? 'cache key changed between the previous run and this one (inputs differ)'
+          : prev
+            ? // An unchanged key has two very different endings, and calling
+              // both a "re-run" answered the question wrong: a cache HIT did not
+              // re-run at all, so blaming `--no-cache` named a cause that cannot
+              // have applied. Only a run that EXECUTED on an unchanged key is
+              // the case this verb exists to explain. A row with no recorded
+              // cacheHit (older rows) is neither — say that, do not guess.
+              unchangedKeyNote(this_.cacheHit)
+            : 'no prior run for this (project, task)',
   }
 }
 
@@ -483,9 +511,11 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      'SELECT hash, started_at AS startedAt FROM runs WHERE run_id = ? AND project = ? AND task = ?',
+      'SELECT hash, cached, started_at AS startedAt FROM runs WHERE run_id = ? AND project = ? AND task = ?',
     )
-    .get(runId, project, task) as { hash: string; startedAt: number } | undefined
+    .get(runId, project, task) as
+    | { hash: string; cached: number | null; startedAt: number }
+    | undefined
   if (!this_) {
     return {
       runId,
@@ -559,7 +589,10 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
       previousRunId: prev.runId,
       entries: [],
       unchangedCount: 0,
-      note: 'cache key changed but input fingerprints are unavailable (entry pruned); only the hash change is known',
+      note:
+        this_.cached === 0
+          ? 'this task declares no `cache` block — it runs every time; its key moved, but no input fingerprints exist for an uncached task'
+          : 'cache key changed but input fingerprints are unavailable — the entry was pruned (or the row predates the `cached` column); only the key change is known',
     }
   }
 

package/src/orchestrator/miss-save.ts

@@ -0,0 +1,169 @@
+// What a MISS leaves behind once the command exited 0 and the task will
+// save: the declared outputs resolved, the artifact and its rows saved in
+// one transaction, the whole-subtree output prefixes recorded for the
+// next hit's skip-restore, and the exact written paths marked against the
+// git snapshot so a same-project consumer re-spawns git only when its
+// globs can see them. Stale-hit-critical: a line moved here changes what
+// a later run replays. Moved out of execute-task.ts 2026-09-09 as pure
+// code motion.
+
+import path from 'node:path'
+import {
+  type CacheLayer,
+  type GitFilesCache,
+  resolveOutputs,
+  resolveWorkspaceOutputs,
+} from '../cache/index.js'
+import type { TaskNode } from '../graph/index.js'
+import { span, wholeSubtreePrefixes } from '../util/index.js'
+import type { Logger } from './logger.js'
+import type { TaskInputComponent } from './task-hash.js'
+
+/** A snapshot request for `recordOutputDirs`, taken at run end. */
+export interface OutputDirSnapshot {
+  hash: string
+  projectDir: string
+  prefixes: readonly string[]
+}
+
+export interface SaveMissArgs {
+  node: TaskNode
+  hash: string
+  cache: CacheLayer
+  log: Logger
+  workspaceRoot: string
+  nestedProjectDirs: string[]
+  gitFilesCache?: GitFilesCache | undefined
+  /** Declared `cache.outputs.files` / `.workspaceFiles`. */
+  outputs: string[]
+  wsOutputs: string[]
+  /** The Tier-3 input fingerprint rows captured by the pre-exec describe. */
+  captured: readonly TaskInputComponent[]
+  command: string
+  durationMs: number
+  stdout: string
+  /** The execution's usage, when the runner reported it — rides the artifact's sidecar. */
+  cpuMs?: number | undefined
+  peakRssBytes?: number | undefined
+  /** When present, the directory snapshot is queued here instead of taken now. */
+  outputDirSnapshots?: OutputDirSnapshot[] | undefined
+  /**
+   * When present, the cache save itself runs off the execution slot: the
+   * outputs are resolved and the git snapshot marked here, in the slot
+   * (a same-project downstream task reads both), and the pack + write +
+   * index go to the run's save lane (save-lane.ts).
+   */
+  deferSave?: ((save: () => Promise<void>) => Promise<void>) | undefined
+}
+
+/** `landed` settles when the entry is in the cache — at once without a lane. */
+export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void> }> {
+  const { node, cache, log } = a
+  const endResolve = span('miss: resolve outputs')
+  const outputFiles = await resolveOutputs({
+    projectDir: node.projectDir,
+    outputs: a.outputs,
+    nestedProjectDirs: a.nestedProjectDirs,
+  })
+  const wsOutputFiles = await resolveWorkspaceOutputs({
+    workspaceRoot: a.workspaceRoot,
+    outputs: a.wsOutputs,
+  })
+  endResolve()
+  // The mirror of the input warning: declared outputs that resolve to
+  // nothing save an empty artifact, and the next hit "restores" it —
+  // the build that ran nowhere looks like a build that ran. `files: []`
+  // is a deliberate cached no-op and says nothing; a glob that matched
+  // nothing is a glob against the wrong directory.
+  if (
+    a.outputs.length + a.wsOutputs.length > 0 &&
+    outputFiles.length + wsOutputFiles.length === 0
+  ) {
+    log.status(
+      `[vx] ${node.id}: cache.outputs matched no files (${[...a.outputs, ...a.wsOutputs].join(', ')}) — ` +
+        `an empty artifact is saved; a later hit restores nothing`,
+    )
+  }
+  const save = async (): Promise<void> => {
+    const endSave = span('miss: save')
+    // Tier-3 input fingerprint: the digest rows captured by the pre-exec
+    // describe above, persisted with the entry inside `cache.save`'s
+    // transaction. Miss path only — the warm/hit path never reaches here.
+    await cache.save({
+      hash: a.hash,
+      projectDir: node.projectDir,
+      outputFiles,
+      ...(wsOutputFiles.length > 0
+        ? { workspaceOutputFiles: wsOutputFiles, workspaceRoot: a.workspaceRoot }
+        : {}),
+      inputComponents: a.captured.map((c) => ({ entryHash: a.hash, ...c })),
+      // No `exitCode`: the save only runs under `effectiveExitCode === 0`, and
+      // the contract no longer accepts one — so the invariant is enforced by
+      // the type rather than by every call site remembering the gate.
+      entry: {
+        taskId: node.id,
+        command: a.command,
+        durationMs: a.durationMs,
+        stdout: a.stdout,
+        ...(a.cpuMs !== undefined ? { cpuMs: a.cpuMs } : {}),
+        ...(a.peakRssBytes !== undefined ? { peakRssBytes: a.peakRssBytes } : {}),
+      },
+    })
+    endSave()
+    // The directory snapshot behind the next hit's skip-restore. Taken at
+    // run end when the run keeps a list: the task wrote these directories
+    // milliseconds ago, inside the snapshot's racy window, so a snapshot
+    // taken here was refused and the next hit walked every output tree —
+    // 1,000 walks, 296 ms accumulated, on the first warm run after a cold
+    // build of the 1,000-project bench (2026-09-10).
+    const savedDirPrefixes = wholeSubtreePrefixes(a.outputs)
+    if (savedDirPrefixes !== null) {
+      if (a.outputDirSnapshots !== undefined) {
+        a.outputDirSnapshots.push({
+          hash: a.hash,
+          projectDir: node.projectDir,
+          prefixes: savedDirPrefixes,
+        })
+      } else {
+        await cache.recordOutputDirs?.(a.hash, node.projectDir, savedDirPrefixes)
+      }
+    }
+  }
+  // This task just wrote outputs to the project's tree. Record the
+  // exact declared-output paths as changed (same as the cache-hit
+  // restore path) instead of dropping the whole snapshot: a downstream
+  // same-project task then re-spawns git ONLY when its input globs can
+  // actually see one of these paths. On a 1000-package cold run this
+  // removes ~one synchronous `git ls-files` spawn per project (the
+  // single largest cold-run cost — 22% of CPU in profiling). Contract:
+  // outputs must be declared — an executed task that writes files
+  // outside `cache.outputs.files` which a same-project downstream task
+  // reads is undeclared behavior (the restore path already assumes it).
+  if (outputFiles.length > 0) {
+    a.gitFilesCache?.markOutputsChanged(
+      node.projectDir,
+      outputFiles.map((p) => path.relative(node.projectDir, p).split(path.sep).join('/')),
+    )
+  }
+  // Declared workspace outputs may have landed inside OTHER
+  // projects' dirs (no-boundary escape hatch) — mark the exact
+  // paths against every partition that can see them.
+  if (wsOutputFiles.length > 0) {
+    a.gitFilesCache?.markWorkspaceOutputsChanged(
+      a.workspaceRoot,
+      wsOutputFiles.map((f) => path.relative(a.workspaceRoot, f).split(path.sep).join('/')),
+    )
+  }
+  // The workspace-wide partition (when one exists) spans this
+  // project's subtree, so it inherits the same "undeclared writes
+  // are only visible to git" rule as the project drop above.
+  if (outputFiles.length + wsOutputFiles.length > 0) {
+    a.gitFilesCache?.invalidateWorkspacePartition()
+  }
+  // Off the slot when the run keeps a lane (the save lane bounds and
+  // drains it); in the slot otherwise — an embedder without a lane gets
+  // the entry before the outcome.
+  if (a.deferSave !== undefined) return { landed: a.deferSave(save) }
+  await save()
+  return { landed: Promise.resolve() }
+}

package/src/orchestrator/options.ts

@@ -8,6 +8,7 @@ import type { TaskOutcome } from '../graph/index.js'
 import type { EventBus } from './events.js'
 import type { TelemetrySink } from './telemetry.js'
 import type { Logger } from './logger.js'
+import type { ProjectEntry } from '../workspace/index.js'
 
 export interface RunOptions {
   cwd: string
@@ -19,6 +20,16 @@ export interface RunOptions {
    */
   tasks: readonly string[]
   projects?: string[]
+  /**
+   * Configs a selection pass in this same process already loaded and
+   * staged with the same `cacheDir` and `frozen` (the CLI walks every
+   * `pkg#task` edge for `--filter 'app...'` and `--affected`). The run
+   * seeds and scopes as it always does and reuses these entries instead
+   * of evaluating and staging them again. One run only — never carry a
+   * map across runs, a config can change between them (`vx watch` drops
+   * it per cycle).
+   */
+  staged?: ReadonlyMap<string, ProjectEntry>
   concurrency?: number
   /**
    * Cache directory override (`--cache-dir <path>`). Absolute, or relative
@@ -34,6 +45,13 @@ export interface RunOptions {
    * both reads false (re-execute, still refresh the cache).
    */
   cache?: CachePolicy
+  /**
+   * The caller asked for a remote axis by name (`--cache=remote:rw`). With
+   * no cache plugin supplying a remote layer the axes are inert, and a CI
+   * job that believes it is filling a shared cache deserves one line
+   * saying it is not.
+   */
+  remoteRequested?: boolean
   /**
    * CI mode: load configs FROM the committed vx-lock.json instead of
    * evaluating them (frozen-env reproducibility). Requires the lock
@@ -62,7 +80,7 @@ export interface RunOptions {
    * task in the run actually needs them (Bazel's "build without the
    * bytes").
    * Pure transfer tuning: it can never change what a command produces,
-   * so it is NEVER folded into a cache key (a RunOption, like --verify).
+   * so it is NEVER folded into a cache key: it is a RunOption, not config.
    * Locally-placed tasks always write in place and ignore this.
    */
   download?: 'all' | 'toplevel' | 'none'
@@ -82,24 +100,6 @@ export interface RunOptions {
    * the same run with and without `--retry` derives identical keys.
    */
   retries?: number
-  /**
-   * Cache-correctness verification (`vx run --verify`). When set, an
-   * executed + cacheable task is re-run after its save and its outputs are
-   * content-compared: a divergence means the task is non-hermetic and its
-   * cache entry is provably unsafe (see docs/design/cache-correctness).
-   * `fingerprint` computes + ships an output-tree fingerprint on executed
-   * tasks (no re-run — the cross-machine diff feed; `--verify`/`=all` set
-   * it too, for free). `allow` (from `--verify-allow=<pkg#task>,…`) exempts
-   * known-nondeterministic tasks from failing the run. A pure side-channel —
-   * never folded into a cache key; the re-run never saves. Undefined = off
-   * (a plain run is byte-identical).
-   */
-  verify?: {
-    determinism: boolean
-    inputs: boolean
-    fingerprint: boolean
-    allow: ReadonlySet<string>
-  }
   /**
    * Run-level default task timeout (ms), for tasks that declare no
    * `exec.timeout`. Highest of the run-level defaults: `--timeout` /
@@ -109,14 +109,6 @@ export interface RunOptions {
    * cached), so a `--timeout` run cache-hits a plain run's entry.
    */
   timeout?: number
-  /**
-   * Memory budget (bytes) that per-task `exec.resources.memory`
-   * reservations pack against (`--memory <size>`). Defaults to
-   * `os.totalmem()` — override it in cgroup-limited containers, where
-   * totalmem() reports the HOST's RAM, not the limit. A per-run
-   * scheduling knob only — never folded into any cache key.
-   */
-  memory?: number
   /**
    * Failure propagation: 'never' stops dispatch on the first failure
    * (in-flight tasks finish; everything queued skips), 'deps-ok'
@@ -154,6 +146,16 @@ export interface RunOptions {
    * exit the process out from under it.
    */
   handleSignals?: boolean
+  /**
+   * Abort the run from outside. On `abort` every live and persistent
+   * child is SIGTERMed, given the kill grace, then SIGKILLed; nothing
+   * further is dispatched; run() returns with the killed tasks and the
+   * never-started ones `aborted`. The seam for an embedder that owns its
+   * process's lifetime instead of `handleSignals` — the watch loop aborts
+   * its in-flight cycle on SIGINT/SIGTERM this way, so a cancellation
+   * never orphans a cycle's children.
+   */
+  signal?: AbortSignal
   log?: Logger
   /**
    * Inject the run's event bus. When provided, the orchestrator emits
@@ -168,7 +170,8 @@ export interface RunOptions {
   bus?: EventBus
   /**
    * Shared in-flight execution registry, keyed by task hash. Supplied by a
-   * long-lived service (`vx serve`) so concurrent runs DEDUP work: a task
+   * long-lived embedder (a daemon built on the façade; core ships none) so
+   * concurrent runs DEDUP work: a task
    * already executing for one run is awaited by another (which then
    * restores the just-saved artifact from cache) instead of re-running.
    * A stateless `vx run` passes none and is byte-identical to before.
@@ -183,8 +186,8 @@ export interface RunOptions {
   /**
    * Additional observe-only telemetry sinks, merged with whatever the
    * workspace plugins contribute. The embedder seam: a host executing
-   * runs on behalf of others (a serve recording delegated runs
-   * into its ingest store) attaches a sink without needing a workspace
+   * runs on behalf of others (a daemon recording delegated runs
+   * into its own store) attaches a sink without needing a workspace
    * plugin. Undefined → zero cost, identical to before; the telemetry
    * host's zero-sink invariant still applies when both sources are
    * empty.
@@ -200,7 +203,7 @@ export interface RunOptions {
   /**
    * An injected remote cache layer — the embedder seam mirroring
    * `telemetrySinks`: a host that already holds a wire client (a
-   * distribution agent, a serve executing on behalf of a submitter)
+   * distribution agent, a daemon executing on behalf of a submitter)
    * passes it here and run() composes `LayeredCache(local, injected)`.
    * Explicit injection WINS over the plugin `cache` capability (the
    * host knows best; prevents double-wrapping when the workspace also

package/src/orchestrator/persistent.ts

@@ -0,0 +1,79 @@
+// End-of-run disposition of persistent children (dev servers, watchers).
+// `executeTask` spawns them and returns at "ready" without awaiting exit;
+// ownership moves to the run's registry, and this is the one place that
+// decides which of them outlive the graph and how the rest go down.
+
+import type { TaskNode } from '../graph/index.js'
+import { killGraceMs } from '../util/index.js'
+
+type Child = ReturnType<typeof Bun.spawn>
+
+/**
+ * Grace after SIGTERMing the dependency-only persistent tasks before
+ * force-killing any that trap or ignore it — so a wedged mock server can't
+ * hang a normal run at completion. Well-behaved servers exit far under
+ * this, so the happy path never waits it out.
+ */
+export const PERSISTENT_SHUTDOWN_GRACE_MS = 2000
+
+export interface KeepAlive {
+  nodes: TaskNode[]
+  children: Child[]
+}
+
+/**
+ * A persistent task the user REQUESTED (or one surfaced for display) is the
+ * run's whole purpose — it is left running and blocked on at the very end,
+ * after the summary. Only in the real CLI foreground: a custom logger or
+ * `handleSignals: false` (watch mode, embedders) expects `run()` to return,
+ * not to sit on a server.
+ */
+export function selectKeepAlive(
+  registry: ReadonlyMap<string, Child>,
+  nodes: ReadonlyMap<string, TaskNode>,
+  foreground: boolean,
+): KeepAlive {
+  const out: KeepAlive = { nodes: [], children: [] }
+  if (!foreground) return out
+  for (const [id, child] of registry) {
+    const n = nodes.get(id)
+    if (n !== undefined && (n.requested || n.surfaced === true)) {
+      out.nodes.push(n)
+      out.children.push(child)
+    }
+  }
+  return out
+}
+
+/**
+ * SIGTERM every persistent child not kept alive and wait for them, bounded:
+ * SIGTERM gives well-behaved servers (vite, next, esbuild --watch) a moment
+ * to clean up; past the grace the stragglers are SIGKILLed so the run's
+ * normal completion cannot hang on one that traps the signal. Bun's
+ * `kill` is idempotent on an exited child; the timer is cleared and
+ * unref'd so a fast shutdown never delays CLI exit.
+ */
+export async function shutdownPersistent(
+  registry: ReadonlyMap<string, Child>,
+  keepAlive: readonly Child[],
+  graceMs: number = killGraceMs(PERSISTENT_SHUTDOWN_GRACE_MS),
+): Promise<void> {
+  const kept = new Set(keepAlive)
+  const dying = [...registry.values()].filter((c) => !kept.has(c))
+  if (dying.length === 0) return
+  for (const child of dying) child.kill('SIGTERM')
+  const allExited = Promise.allSettled(dying.map((c) => c.exited))
+  let graceTimer: ReturnType<typeof setTimeout> | undefined
+  const winner = await Promise.race([
+    allExited.then(() => 'exited' as const),
+    new Promise<'grace'>((resolve) => {
+      graceTimer = setTimeout(() => resolve('grace'), graceMs)
+      graceTimer.unref?.()
+    }),
+  ])
+  if (graceTimer !== undefined) clearTimeout(graceTimer)
+  if (winner === 'grace') {
+    for (const child of dying) child.kill('SIGKILL')
+    await allExited
+  }
+}