@vzn/vx 0.0.638 → 0.0.640

package/src/orchestrator/index.ts

@@ -36,43 +36,7 @@ export { exitSignal, shellQuote } from '../exec/index.js'
 export { forwardedSignal } from './signals.js'
 // `vx cache clean` waits for a run on the workspace before it evicts.
 export { acquireRunLock } from './run-lock.js'
-export { defaultLogger, resolveOutputView } from './logger.js'
-export type { Logger, OutputView } from './logger.js'
 export type { RunPlan, PlannedTask, PlanPrediction, CacheStatus } from './plan.js'
-export {
-  createEventBus,
-  wireForwarder,
-  toWireEvent,
-  projectNode,
-  projectOutcome,
-  outcomeWord,
-} from './events.js'
-export type {
-  EventBus,
-  RunEvent,
-  RunEventSubscriber,
-  RunStartInfo,
-  WireEvent,
-  TaskView,
-  OutcomeView,
-} from './events.js'
-export { escapeMarkdownCell, formatRunReportMarkdown, type RunResult } from './run-report.js'
-export {
-  EmptyHistoryProvider,
-  type HistoryProvider,
-  type HistoryTable,
-  LocalHistoryProvider,
-  type TaskHistory,
-  type TaskResources,
-} from './history.js'
-export {
-  detectFlaky,
-  type FailureMode,
-  type FlakyCandidate,
-  type FlakyFinding,
-  type FlakyTask,
-  flakyTasks,
-} from './failure-mode.js'
 export {
   installPlugins,
   type CacheContext,
@@ -133,17 +97,8 @@ export { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
 // module header for why one implementation, not one per sink.
 export { LOG_WIRE_VERSION, TaskLogBuffer } from './task-log-buffer.js'
 export type { TaskLogBundle, TaskLogEntry } from './task-log-buffer.js'
-export {
-  assembleRunSummary,
-  createTelemetrySource,
-  deriveCacheSource,
-  isCacheHit,
-  isPassStatus,
-  TASK_STATUSES,
-  TELEMETRY_SCHEMA_VERSION,
-} from './telemetry.js'
+export { assembleRunSummary, createTelemetrySource, TELEMETRY_SCHEMA_VERSION } from './telemetry.js'
 export type {
-  CacheSource,
   RunContextRecord,
   RunSummaryRecord,
   TaskTelemetry,
@@ -163,18 +118,6 @@ export {
   detectCi,
 } from './run-context.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './run-context.js'
-export {
-  cacheKeyDiff,
-  explainCacheKey as explainCacheKeyQuery,
-  getInvocation,
-  getRun,
-  latestRunId,
-  listInvocations,
-  listRuns,
-  inputWriters,
-  rootCauses,
-  whyDidThisRerun as whyDidThisRerunQuery,
-} from './metrics.js'
 export {
   runFailures,
   type RunFailures,
@@ -182,20 +125,6 @@ export {
   type TaskLog,
   taskLog,
 } from './run-failures.js'
-export type { OutputLocation } from './path-links.js'
+export { type RunStep, runSteps } from './run-steps.js'
 export { resolveRunId, shortRunId } from './run-id.js'
-export type {
-  CacheEntryRow,
-  CacheKeyDiff,
-  InputWriter,
-  RootCause,
-  CacheKeyExplanation,
-  InputDiffEntry,
-  InvocationDetail,
-  ListInvocationsArgs,
-  ListRunsArgs,
-  RunDetail,
-  RunSummaryRow,
-  WhyDidThisRerun,
-} from './metrics.js'
 export { collectInfo, type CollectInfoOptions, type InfoFacts } from './doctor.js'

package/src/orchestrator/keyed-projects.ts

@@ -5,8 +5,7 @@
 // is decided — on the graph, before any hash exists, through the same
 // selection the hash path applies (`selectFoldedDeps`).
 
-import { isGroupTask, type TaskNode } from '../graph/index.js'
-import { keyedDeps, selectFoldedDeps, type FoldCandidate } from './upstream.js'
+import { foldedDeps, isGroupTask, type FoldCandidate, type TaskNode } from '../graph/index.js'
 
 /**
  * A run's keyed-set lookup: for a task, the directories of every project
@@ -14,18 +13,17 @@ import { keyedDeps, selectFoldedDeps, type FoldCandidate } from './upstream.js'
  * task itself is not counted.
  *
  * The fold relation is the hash path's, computed on the graph:
- *   - an exec task folds its dependencies as its own `cache.inputs.tasks`
- *     selects them (absent, or no `cache` at all, means all);
- *   - a group folds every dependency (`computeGroupKey`) and folds no
- *     files of its own, but for the default `build`, which folds every
- *     file of its project as a task does;
- *   - a persistent task is keyed as a task with no `cache` (A-17).
+ *   - an exec task folds its dependencies as its own `inputs.tasks`
+ *     selects them (absent means all);
+ *   - a group folds every dependency (`computeGroupKey`); a keyed one
+ *     (`inputs`, the default `build`) folds its project's files as a task
+ *     does;
+ *   - a persistent task is keyed as any task with no `cache` (A-17).
  *
- * Every exec task reached contributes its project, cached or not: a key
- * folds the task's own project files, and a task with no `cache` declares
- * no `inputs.files`, so it folds every file of its project (inputs.ts's
- * `DEFAULT_FILE_GLOBS`). `tests/keyed-projects.test.ts` holds that to the
- * key itself.
+ * Every exec task reached contributes its project, cached or not: its key
+ * folds its own project's files through its `inputs`, and one with no
+ * `inputs` is keyless, so a key that folds it is never stored or read.
+ * `tests/keyed-projects.test.ts` holds that to the key itself.
  *
  * Lazy and memoized by task id: only a sandboxed task that executes asks,
  * so a run of hits walks nothing, and a shared subgraph is walked once.
@@ -57,7 +55,7 @@ export function keyedProjects(
       stack.pop()
       const out = new Set<string>()
       for (const { node: dep } of deps) {
-        if (!isGroupTask(dep) || dep.config.cache !== undefined) out.add(dep.projectDir)
+        if (!isGroupTask(dep) || dep.config.inputs !== undefined) out.add(dep.projectDir)
         for (const dir of below.get(dep.id)!) out.add(dir)
       }
       below.set(node.id, out)
@@ -65,40 +63,3 @@ export function keyedProjects(
     return below.get(root.id)!
   }
 }
-
-/**
- * The dependencies `node`'s key folds, per the hash path's rules above, as
- * `keyUpstream` hands them to the key: the scheduled ones less the edges
- * `--exclude-dependencies` left for order alone, plus the dropped ones it
- * keys all the same (`excludedUpstream`), whose own dependencies the walk
- * reads from the run's `keyOnly` map. `node.deps` held the order-only
- * edges and lacked the dropped ones: the sandbox granted a sibling the key
- * does not answer for.
- */
-export function foldedDeps(node: TaskNode, nodeOf: (id: string) => TaskNode): FoldCandidate[] {
-  const candidates: FoldCandidate[] = []
-  for (const id of keyedDeps(node)) {
-    const dep = nodeOf(id)
-    candidates.push({ node: dep, unit: foldUnit(dep) })
-  }
-  for (const { node: dep } of node.excludedUpstream ?? []) {
-    candidates.push({ node: dep, unit: foldUnit(dep) })
-  }
-  if (isGroupTask(node) && node.config.cache === undefined) return candidates
-  return selectFoldedDeps(candidates, node.config.cache?.inputs?.tasks, node.projectName, node.id)
-}
-
-/**
- * What stands in for a dependency's hash in the dedup: equal exactly when
- * the hashes are. An exec task's key folds its own id (`task:<id>`), so its
- * id is enough; a group's hash is a roll-up of its members' ids and hashes
- * with no id of its own, so two groups over the same members hash alike.
- * The members are `keyUpstream`'s, which `computeGroupHash` is handed: under
- * `--exclude-dependencies` `node.deps` holds order-only edges and lacks the
- * dropped ones, and two groups the key told apart shared a unit.
- */
-function foldUnit(node: TaskNode): string {
-  if (!isGroupTask(node) || node.config.cache !== undefined) return `task|${node.id}`
-  const members = [...keyedDeps(node), ...(node.excludedUpstream ?? []).map((u) => u.node.id)]
-  return `group|${members.sort().join('|')}`
-}

package/src/orchestrator/local-shortcircuit.ts

@@ -232,7 +232,7 @@ export function restoreTierExclusions(
   const dependants = new Map<string, string[]>()
   for (const node of nodes.values()) {
     const dir = relPosix(workspaceRoot, node.projectDir)
-    const wsInputs = node.config.cache?.inputs?.workspaceFiles ?? []
+    const wsInputs = node.config.inputs?.workspaceFiles ?? []
     if (reaches(dir) || (wsInputs.length > 0 && workspaceInputsReach(wsInputs, prefixes))) {
       out.add(node.id)
     }

package/src/orchestrator/miss-save.ts

@@ -25,8 +25,8 @@ import {
   taskGlob,
   wholeSubtreePrefixes,
 } from '../util/index.js'
-import type { Logger } from './logger.js'
-import type { TaskInputComponent } from './task-hash.js'
+import { type Logger, warnOf } from '../report/index.js'
+import type { TaskInputComponent } from '../cache/index.js'
 
 /** A snapshot request for `recordOutputDirs`, taken at run end. */
 export interface OutputDirSnapshot {
@@ -61,6 +61,36 @@ export function entryHolds(
   }
 }
 
+/**
+ * The run-end output-directory snapshots, taken once the directories are
+ * old enough for the snapshot's racy window. Each walk is held to its
+ * entry's rows (item 1087), read in one batch: read per snapshot, each read
+ * also flushed the snapshots before it, one transaction apiece (+110 ms at
+ * 1,000). A few walks at a time: each is an lstat + readdir per prefix; the
+ * rows land together at close, in one transaction.
+ */
+export async function recordOutputDirSnapshots(
+  cache: CacheLayer,
+  snapshots: readonly OutputDirSnapshot[],
+): Promise<void> {
+  const rowsOf = new Map<string, ReadonlyArray<{ path: string }>>()
+  for (let i = 0; i < snapshots.length; i += 900) {
+    const batch = cache.loadOutputFilesBatch(snapshots.slice(i, i + 900).map((s) => s.hash))
+    for (const [hash, rows] of batch) rowsOf.set(hash, rows)
+  }
+  for (let i = 0; i < snapshots.length; i += 32) {
+    await Promise.all(
+      snapshots
+        .slice(i, i + 32)
+        .map((s) =>
+          cache.recordOutputDirs?.(s.hash, s.projectDir, s.prefixes, (files) =>
+            s.holds(files, rowsOf.get(s.hash) ?? []),
+          ),
+        ),
+    )
+  }
+}
+
 export interface SaveMissArgs {
   node: TaskNode
   hash: string
@@ -153,7 +183,7 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
     // A `workspaceFiles` directory linked out of the workspace drops every
     // file (M-65); a project one is refused by the resolver (X-88).
     const linkedOut = outputDirLinkedOut(a.workspaceRoot, a.wsOutputs)
-    log.status(
+    warnOf(log)(
       `[vx] ${node.id}: cache.outputs matched no files (${[...a.outputs, ...a.wsOutputs].join(', ')}) — ` +
         `an empty artifact is saved; a later hit restores nothing` +
         (linkedOut !== undefined

package/src/orchestrator/options.ts

@@ -6,10 +6,8 @@ import type { CacheFlags, CachePolicy, RemoteCacheLayer } from '../cache/index.j
 import type { ContinueMode } from '../graph/index.js'
 import type { TaskOutcome } from '../graph/index.js'
 import type { AffectedReason } from './affected-tasks.js'
-import type { EventBus } from './events.js'
+import type { EventBus, Logger } from '../report/index.js'
 import type { TelemetrySink } from './telemetry.js'
-import type { Logger } from './logger.js'
-import type { RunSummaryJson } from './run-artifacts.js'
 import type { AffectedChanges, ProjectEntry, ProjectMeta } from '../workspace/index.js'
 import type { RunSettings } from '../config.js'
 
@@ -164,12 +162,6 @@ export interface RunOptions {
   branch?: string
   /** `run.schedule` from its flag; unset, `VX_RUN_SCHEDULE`, then the workspace's. */
   schedule?: NonNullable<RunSettings['schedule']>
-  /** `run.killGrace` in ms from its flag; unset, `VX_RUN_KILL_GRACE`, then the workspace's. */
-  killGrace?: number
-  /** `run.teardownTimeout` in ms from its flag; unset, `VX_RUN_TEARDOWN_TIMEOUT`, then the workspace's. */
-  teardownTimeout?: number
-  /** `run.readyNotice` in ms from its flag; unset, `VX_RUN_READY_NOTICE`, then the workspace's. */
-  readyNotice?: number
   /**
    * Filter `dependsOn` expansion. `'all'` drops every edge (just the
    * requested task runs). A string array drops only those task names
@@ -178,25 +170,6 @@ export interface RunOptions {
   excludeDependencies?: 'all' | readonly string[]
   /** Forwarded to the last step of each task's exec array (shell-quoted). */
   forwardArgs?: readonly string[]
-  /**
-   * If set, write a per-run JSON summary at end of run. Empty string
-   * picks the default path `<cacheDir>/runs/<run_id>.json`; anything
-   * else is treated as the literal file path (cwd-relative).
-   */
-  summarize?: string
-  /**
-   * `vx run --format json`: the terminal renderer writes stderr, and the
-   * run hands back `RunSummary.json`, the `--summarize` document, for the
-   * caller to print on stdout.
-   */
-  json?: boolean
-  /**
-   * Text printed just above the run's footer, given the outcomes the
-   * footer counts, after the `summaryTable`: nothing prints below the
-   * footer (owner), so a caller's end-of-run report (`--report`) rides
-   * here. Not called on a refused run.
-   */
-  beforeFooter?: (outcomes: readonly TaskOutcome[], ok: boolean) => string
   /**
    * `false`: no footer, live or printed, and no blank line opening the
    * task log; the run is its task rows (`vx watch`, which frames each
@@ -283,12 +256,6 @@ export interface RunOptions {
    * A stateless `vx run` passes none and is byte-identical to before.
    */
   inflight?: Map<string, Promise<void>>
-  /**
-   * `--tag k=v` pairs (Tier-3). Persisted on the run's `invocations`
-   * row (JSON object) so dashboards can filter runs by label, a secret
-   * value masked (L-38). CLI parsing is the CLI's job.
-   */
-  tags?: Record<string, string>
   /**
    * Additional observe-only telemetry sinks, merged with whatever the
    * workspace plugins contribute. The embedder seam: a host executing
@@ -337,8 +304,6 @@ export interface RunSummary {
    * caller prints it; `vx run` writes it to stderr.
    */
   refused?: string
-  /** The `--summarize` document, when `RunOptions.json` asked for it. */
-  json?: RunSummaryJson
 }
 
 export interface HeldPersistent {

package/src/orchestrator/output-host.ts

@@ -2,12 +2,12 @@
 // to telemetry-host.ts. With no plugin declaring the hook nothing here runs,
 // and core's renderer is the run's, byte for byte.
 
-import { terminalSubscriber, type RunEventSubscriber } from './events.js'
-import type { Logger } from './logger.js'
+import { terminalSubscriber, type RunEventSubscriber } from '../report/index.js'
+import type { Logger } from '../report/index.js'
 import type { OutputContext, VxPlugin } from './plugin.js'
 
 const REQUIRED = ['status', 'taskStdout', 'taskStderr', 'taskComplete'] as const
-const OPTIONAL = ['runStart', 'taskStart', 'runEnd'] as const
+const OPTIONAL = ['runStart', 'taskStart', 'runEnd', 'stepStart', 'stepEnd', 'runDone'] as const
 
 /** Reject anything that is not Logger-shaped, naming what is missing. */
 function checkLogger(value: unknown): Logger {
@@ -64,6 +64,7 @@ export function guardedOutput(
       failed = true
       fallback({
         kind: 'run:status',
+        warn: true,
         line: `[vx] plugin '${claimed.owner}' output failed: ${err instanceof Error ? err.message : String(err)}; vx renders the rest of the run`,
       })
       fallback(event)

package/src/orchestrator/persistent-task.ts

@@ -0,0 +1,321 @@
+// A persistent task (a dev server, a watcher): keyed like an uncached task,
+// spawned, and held until `readyWhen` matches. Never cached and never routed
+// through an executor. Moved out of execute-task.ts as pure code motion.
+
+import type { ExecConfig } from '../config.js'
+import {
+  PersistentReadyError,
+  releaseBridges,
+  runPersistent,
+  signalExitCode,
+  withForwardArgs,
+  wrapSandboxedCommand,
+} from '../exec/index.js'
+import type { TaskOutcome } from '../graph/index.js'
+import { maskedEmitter, secretMask, testTimerMs } from '../util/index.js'
+import { warnOf } from '../report/index.js'
+import type { ExecuteArgs } from './execute-task.js'
+import {
+  commandWriteReach,
+  mayWriteFingerprint,
+  type Placeholder,
+  placeholderSweeper,
+  sandboxRequestFor,
+  sweepPlaceholders,
+  undeclaredWriteReach,
+  untouchedPlaceholderLine,
+} from './sandbox-request.js'
+import { forwardedSignal, terminateChildren } from './signals.js'
+import { computeTaskHash } from './task-hash.js'
+import { forgetUndeclaredWrites, isAborted, taskEnv, taskTimeoutMs } from './task-process.js'
+
+/** How long a server may take to match `readyWhen` before vx says it waits. */
+const READY_NOTICE_MS = 10_000
+
+/**
+ * Persistent task: dev server / file watcher / daemon. Spawn, wait
+ * for ready (regex match or immediate), stash the subprocess in the
+ * orchestrator-owned registry, return success. The orchestrator
+ * SIGTERMs the registry at end-of-run.
+ *
+ * Never reads or writes the cache — the project loader rejects
+ * `cache + persistent` at config-load time, so by the time we get
+ * here, `cache` is guaranteed undefined.
+ *
+ * Never routed through an executor: a persistent task is local by
+ * construction (its port lives on this machine).
+ */
+export async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
+  const { node, log } = args
+  // Type narrowing: the dispatcher checks `exec.persistent` before
+  // calling us, so `exec` and `exec.persistent` are both present.
+  const step = node.config.exec as ExecConfig & {
+    persistent: NonNullable<ExecConfig['persistent']>
+  }
+  const effectiveForwardArgs = node.requested ? (args.forwardArgs ?? []) : []
+  const env = taskEnv(node, step, args.workspaceRoot)
+  const wallclockStartNs = process.hrtime.bigint() - args.runStartHrTimeNs
+  // Keyed on its inputs like any task, so a cached dependant behind a dev
+  // server re-runs when the server's sources change; with none it has no
+  // key and the dependant always runs (A-17).
+  const hash =
+    args.noDependants === true
+      ? undefined
+      : (args.upfrontKey ??
+        (await computeTaskHash({
+          node,
+          upstream: args.upstream,
+          workspaceRoot: args.workspaceRoot,
+          cache: args.cache,
+          forwardArgs: args.forwardArgs,
+          nestedProjectDirs: args.nestedProjectDirs,
+          ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
+          ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
+        })))
+
+  // The args after `--` reach a server as they reach any task. A readyWhen
+  // server once got none — "so the matcher sees the unmodified output",
+  // though the args change the command, not what the matcher reads — and
+  // `vx run dev -- --port 4000` on the documented Vite task dropped the
+  // port in silence (item 1060).
+  const plainCommand = withForwardArgs(step.command, effectiveForwardArgs)
+  // A persistent task declaring `exec.sandbox` runs inside it like any
+  // other: the same grants, the same walls. What it cannot have is the
+  // violation REPORT — that reads the trace after the child exits, and a
+  // server exits when the run tears it down. Enforced, not reported.
+  // (Until 2026-09-09 the block was accepted and silently ignored.)
+  let command = plainCommand
+  let bridgeTag: string | undefined
+  let signalChannel = false
+  // The empty files the request pre-created for a literal write grant; a
+  // server that never writes one gets it taken back when it exits, and a
+  // server that dies before readiness is told the directory spelling — the
+  // same trap and the same answer as a one-shot task's (sandbox-request.ts).
+  let placeholders: Placeholder[] = []
+  if (step.sandbox !== undefined) {
+    await args.armSandbox?.()
+    // A persistent task never declares `cache` (the loader refuses it), so
+    // it keeps the whole linked grant: no key of its can be stale.
+    const sb = await sandboxRequestFor(
+      node,
+      step.sandbox,
+      args.workspaceRoot,
+      undefined,
+      args.nestedProjectDirs,
+      args.cacheDir,
+    )
+    placeholders = sb.placeholders
+    // A wrap that refuses (a port the host holds) leaves the server unspawned
+    // and the placeholders vx made for it in the project for every later run.
+    const wrapped = await wrapSandboxedCommand({
+      command: plainCommand,
+      cwd: node.projectDir,
+      env,
+      ...sb.sandbox,
+      server: true,
+    }).catch(async (err: unknown) => {
+      await sweepPlaceholders(placeholders)
+      throw err
+    })
+    command = wrapped.wrapped
+    bridgeTag = wrapped.tag
+    signalChannel = wrapped.forwardsSignals
+  }
+  // A server's output masked as a one-shot task's is (L-11); `readyWhen`
+  // is matched on the raw chunks, before this. Its held tail is flushed by
+  // the idle timer: a server never ends on the way to a flush.
+  const serverSecrets = secretMask([process.env, env, step.env?.define], step.env?.secret)
+  const serverOut = serverSecrets && maskedEmitter(serverSecrets, (t) => log.taskStdout(node, t))
+  const serverErr = serverSecrets && maskedEmitter(serverSecrets, (t) => log.taskStderr(node, t))
+  // A server writes until the run stops it: its window stays open.
+  args.commandWindows?.open(node.id, node.projectDir, commandWriteReach(node, args.workspaceRoot))
+  const persistentOpts: Parameters<typeof runPersistent>[0] = {
+    command,
+    cwd: node.projectDir,
+    env,
+    onStdout: serverOut ? (chunk) => serverOut.push(chunk) : (chunk) => log.taskStdout(node, chunk),
+    onStderr: serverErr ? (chunk) => serverErr.push(chunk) : (chunk) => log.taskStderr(node, chunk),
+    ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
+    ...(args.track !== undefined
+      ? { onSpawn: (pid: number) => void args.track!(node.id, pid) }
+      : {}),
+    ...(signalChannel ? { signalChannel } : {}),
+    ...(args.terminal === true ? { terminal: true } : {}),
+  }
+  if (step.persistent.readyWhen !== undefined) {
+    persistentOpts.readyWhen = step.persistent.readyWhen
+  }
+  // For a persistent task the timeout bounds the readiness wait. Per-task
+  // `exec.timeout` wins; else the run-level default (env/workspace/--timeout).
+  const effectiveTimeout = taskTimeoutMs(step) ?? args.timeout
+  if (effectiveTimeout !== undefined) {
+    persistentOpts.timeoutMs = effectiveTimeout
+  }
+
+  // A stop that landed during the awaits above (the key, the sandbox's
+  // arming, request and wrap) leaves nothing to kill yet: spawned now, the
+  // server came up after the teardown and held the run's exit 7 s.
+  if (args.stopSignal?.aborted === true) {
+    if (bridgeTag !== undefined) releaseBridges(bridgeTag)
+    await placeholderSweeper(placeholders)()
+    return {
+      node,
+      status: 'aborted',
+      // The signal a spawned server would have been sent (a hang-up forwards SIGTERM).
+      exitCode: signalExitCode(forwardedSignal(args.stopSignal.reason)),
+      durationMs: 0,
+      wallclockStartNs,
+      wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+    }
+  }
+  const spawn = runPersistent(persistentOpts)
+  // The host side of a port bridge lives exactly as long as the server:
+  // released on the child's exit, whether the run tore it down or it died.
+  // A placeholder the server never wrote goes back the same way.
+  // ONE sweep, shared by the exit handler and the readiness failure below
+  // — whichever asks second must get the SAME list. A second sweep cannot
+  // produce it: the first one's `rm` already happened, so the file is gone
+  // and `sweepPlaceholders` skips it. Collecting both lists and unioning
+  // them does not close that, because the union only covers an exit
+  // handler that FINISHED; one still between its `rm` and its return has
+  // published nothing yet, and the readiness path then reports no
+  // placeholder at all. The failure then says only "File exists", which is
+  // the message the hint exists to explain (seen under the gate's parallel
+  // load, and reproduced deterministically by delaying each side, item 450).
+  const sweptUntouched = placeholderSweeper(placeholders)
+  if (bridgeTag !== undefined || placeholders.length > 0) {
+    const tag = bridgeTag
+    const onExit = async (): Promise<void> => {
+      if (tag !== undefined) releaseBridges(tag)
+      await sweptUntouched()
+    }
+    // A spawn that failed has no child to wait on: release now, or the
+    // tag would hold the sandbox's reset for the rest of the process.
+    if (spawn.child === undefined) void onExit()
+    else void spawn.child.exited.then(onExit, onExit)
+  }
+  // Said once if readiness is slow: a dependency's output is hidden unless
+  // it fails, and with no `exec.timeout` the wait never ends, so a run
+  // whose `readyWhen` never matched showed nothing at all.
+  const readyWhen = step.persistent.readyWhen
+  // How long a server may take to match `readyWhen` before vx says it waits.
+  const noticeMs = testTimerMs('READY_NOTICE', READY_NOTICE_MS)
+  const notice =
+    readyWhen === undefined
+      ? undefined
+      : setTimeout(() => {
+          if (isAborted(args.stopSignal)) return
+          const after = noticeMs < 1000 ? `${noticeMs} ms` : `${noticeMs / 1000} s`
+          const unbounded = effectiveTimeout === undefined ? ', with no exec.timeout' : ''
+          warnOf(log)(
+            `vx: ${node.id} not ready after ${after}: waiting for a line matching /${serverSecrets?.mask(readyWhen) ?? readyWhen}/ (readyWhen)${unbounded}`,
+          )
+        }, noticeMs)
+  if (notice !== undefined) {
+    const quiet = (): void => clearTimeout(notice)
+    void spawn.ready.then(quiet, quiet)
+  }
+  try {
+    await spawn.ready
+  } catch (err) {
+    // A shell that exited before ready can leave its group running
+    // (`server & …; exit`): never registered, so no teardown reached it,
+    // and it held its port against the next `vx watch` cycle's server.
+    if (err instanceof PersistentReadyError && err.reason === 'exited')
+      await terminateChildren(() => [spawn.child])
+    // A server the run's stop killed while it started is aborted, as any
+    // task the stop kills (item 962): it read `failed (never ready:
+    // exited, exit 130)` with a recap after every Ctrl-C (C-62). The stop
+    // aborts before it kills, so it is set by the time the child is gone.
+    // Read through a call: the early return above narrows `aborted` to
+    // false, but the stop can land during `spawn.ready`.
+    if (isAborted(args.stopSignal)) {
+      return {
+        node,
+        status: 'aborted',
+        exitCode: err instanceof PersistentReadyError ? (err.exitCode ?? 1) : 1,
+        durationMs: spawn.readyMs(),
+        wallclockStartNs,
+        wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+      }
+    }
+    const message = err instanceof Error ? err.message : String(err)
+    // The task's OWN stream, not the process's: the frame is where a
+    // reader looks for why a task failed, and a run with a custom logger
+    // (an embedder) never saw a bare stderr write at all.
+    log.taskStderr(node, `\n[vx] ${node.id}: persistent task failed to become ready: ${message}\n`)
+    // A server is never traced, so the sandbox's refusals reach no report:
+    // a dev server that died on a file outside its grants read only as the
+    // tool's own "not found" (2026-10-03). Said for a sandboxed server that
+    // exited failing, which is the shape a refusal takes.
+    if (
+      step.sandbox !== undefined &&
+      err instanceof PersistentReadyError &&
+      err.reason === 'exited' &&
+      err.exitCode !== 0
+    ) {
+      log.taskStderr(
+        node,
+        `[vx] ${node.id} ran in the sandbox, which reports nothing for a server: a path outside ` +
+          `its grants reads as missing (ENOENT), a refused write as read-only (EROFS). Check ` +
+          `exec.sandbox.allow, or run the command as a one-shot sandboxed task to see what it was refused.\n`,
+      )
+    }
+    // The server is dead or being torn down, so the sweep on its exit may
+    // already be running: ask the shared one rather than starting a second.
+    for (const p of await sweptUntouched()) {
+      log.taskStderr(node, `${untouchedPlaceholderLine(node.projectDir, p)}\n`)
+    }
+    // The reason rides the outcome (every label reads it), and a child that
+    // exited before ready keeps its own exit code rather than a made-up 1.
+    // One the readiness timeout is killing reports the signal's, as an
+    // ordinary timeout does (X-24).
+    // A readiness timeout rejects once the group is gone (runner.ts), so a
+    // server that ignored the TERM holds no port into the next `vx watch`
+    // cycle, and a second signal here would cut a one-shot handler short.
+    const ready = err instanceof PersistentReadyError ? err : undefined
+    return {
+      node,
+      status: 'failed',
+      // A server that traps the TERM and exits 0 still timed out, as a
+      // one-shot task that does so reports 143 (X-116).
+      exitCode:
+        ready?.reason === 'timeout'
+          ? (await spawn.child.exited) || signalExitCode('SIGTERM')
+          : (ready?.exitCode ?? 1),
+      durationMs: spawn.readyMs(),
+      ...(ready !== undefined ? { notReady: ready.reason } : {}),
+      wallclockStartNs,
+      wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+    }
+  }
+
+  // Ready only once the stop had landed: a trap that prints the marker on
+  // the way down, or a race with the signal. The stop is killing it (it
+  // is in `liveChildren`), and it served nobody, as a one-shot that exits
+  // 0 on the stop is aborted (item 962).
+  if (isAborted(args.stopSignal)) {
+    return {
+      node,
+      status: 'aborted',
+      exitCode: signalExitCode(forwardedSignal(args.stopSignal!.reason)),
+      durationMs: spawn.readyMs(),
+      wallclockStartNs,
+      wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+    }
+  }
+  args.persistentRegistry?.set(node.id, spawn.child)
+  forgetUndeclaredWrites(args, undeclaredWriteReach(node, args.workspaceRoot))
+  if (mayWriteFingerprint(node, args.workspaceRoot, args.fingerprintWatch?.names ?? [])) {
+    args.fingerprintWatch?.wrote()
+  }
+  return {
+    node,
+    status: 'success',
+    exitCode: 0,
+    durationMs: spawn.readyMs(),
+    ...(hash !== undefined ? { hash } : {}),
+    wallclockStartNs,
+    wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+  }
+}