@vzn/vx 0.0.21 → 0.0.22

package/src/index.ts

@@ -30,6 +30,10 @@ export { collectInfo, type CollectInfoOptions, type InfoFacts } from './orchestr
 // first; a policy that budgets memory (`@vzn/vx-schedule-history`) reads
 // the second, so the cgroup walk has one implementation.
 export { machineMemoryBytes, machineParallelism } from './util/index.js'
+// How core reads a task glob — its spelling, and which characters are
+// wildcards (`[` `]` are not; item 667) — for a plugin that turns declared
+// outputs into something else (`@vzn/vx-reapi`'s literal `output_paths`).
+export { isLiteralPattern, normalizeGlob } from './util/index.js'
 
 // Schema types and helpers (used by user vx.config files and presets).
 export type {
@@ -60,6 +64,11 @@ export { run, planRun, prepareRun } from './orchestrator/index.js'
 export { LocalHistoryProvider } from './orchestrator/index.js'
 export type { HistoryProvider, HistoryTable, TaskHistory } from './orchestrator/index.js'
 export type { PreparedRun } from './orchestrator/index.js'
+// `planRun` returns these, and an embedder that cannot NAME a return type
+// cannot hold it: `run` and `prepareRun` both had theirs here from the
+// start, so the omission read as "planRun is not really public" while
+// docs/cli.md § Programmatic API listed all three (item 387, 2026-09-19).
+export type { RunPlan, PlannedTask } from './orchestrator/index.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './orchestrator/index.js'
 export type {
   CachePolicy,
@@ -72,7 +81,7 @@ export type {
 // with only `taskId()` to JOIN an id and nothing exported to SPLIT one,
 // consumers roll their own `split('#', 2)` and drift from the graph, which
 // splits on the FIRST '#'.
-export { splitTaskId } from './graph/index.js'
+export { outputsOverlap, splitTaskId } from './graph/index.js'
 export type { TaskNode, TaskOutcome, TaskStatus } from './graph/index.js'
 
 // Cache classes + the layer interface (the `cache` capability's currency).
@@ -106,6 +115,7 @@ export type { ProjectEntry } from './workspace/index.js'
 // `@vzn/vx-migrate` (Turbo, Nx) and any other adoption tool use it from here.
 export {
   applyMigration,
+  foldScriptHooks,
   PERSISTENT_TASK_NAMES,
   PERSISTENT_TODO,
   quoteTsLiteral,
@@ -193,6 +203,10 @@ export {
 // a hit's bytes belong to the run that executed) are a decision, not an
 // implementation detail. Two sinks rolling their own is how they fork.
 export { LOG_WIRE_VERSION, TaskLogBuffer } from './orchestrator/index.js'
+// `exitSignal` is on the façade on the same demonstrated need: a sink that
+// renders a failed task's exit code faces 137 where the frame and `vx last`
+// say `128 + SIGKILL`; the decode is the runner's convention, one copy.
+export { exitSignal } from './orchestrator/index.js'
 export type {
   CacheSource,
   RunContextRecord,
@@ -212,4 +226,4 @@ export type { RunResult, TaskView, OutcomeView } from './orchestrator/index.js'
 // answer, which `@vzn/vx-mcp` serves. The event bus / wire form and the
 // other history readers (`listRuns`, `getRun`, …) left the façade 2026-09-10
 // with no consumer; the telemetry seam above is the canonical export path.
-export { whyDidThisRerunQuery } from './orchestrator/index.js'
+export { latestRunId, whyDidThisRerunQuery } from './orchestrator/index.js'

package/src/orchestrator/admission.ts

@@ -13,36 +13,42 @@
 //   every success built on it — or a grand-dependent would cache the same
 //   partial tree one hop later. Only that mode ever executes a task behind
 //   a failure; the other modes skip it, so a default run carries no check.
+//   `--exclude-dependencies` seeds the same taint: a task whose key folds a
+//   dependency that did not run has bytes nothing vouches for
+//   (excluded-keys.ts).
 //
 // Split from `run.ts` on 2026-09-10 (pure motion).
 
 import type { CachePolicy } from '../cache/index.js'
-import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import { executeTask, type ExecuteArgs } from './execute-task.js'
 import type { ShortCircuit } from './local-shortcircuit.js'
 import { computeTaskHash, type ComputeHashArgs } from './task-hash.js'
 
 /**
- * Records which tasks ran behind a failure and answers, per task, whether
- * this one does. Disabled (always `false`, nothing recorded) unless the
- * run's `continueMode` is `'always'`.
+ * Records which tasks ran behind a failure, or on the key of a dependency
+ * that did not run (`seeds`), and answers, per task, whether this one does.
+ * Disabled (always `false`, nothing recorded) unless the run's
+ * `continueMode` is `'always'` or there is a seed.
  */
 export function taintTracker(
-  enabled: boolean,
+  continueAlways: boolean,
+  seeds: ReadonlySet<string>,
 ): (node: TaskNode, upstream: TaskOutcome[]) => boolean {
-  if (!enabled) return () => false
+  if (!continueAlways && seeds.size === 0) return () => false
   const tainted = new Set<string>()
   return (node, upstream) => {
-    const taint = upstream.some(
-      // A restore-tier task may run before its deps and see holes here;
-      // it never saves anyway (a hit restores), so a hole is not taint.
-      (u) =>
-        u !== undefined &&
-        (u.status === 'failed' ||
-          u.status === 'aborted' ||
-          u.status === 'skipped' ||
-          tainted.has(u.node.id)),
-    )
+    const taint =
+      seeds.has(node.id) ||
+      upstream.some(
+        // A restore-tier task may run before its deps and see holes here;
+        // it never saves anyway (a hit restores), so a hole is not taint.
+        (u) =>
+          u !== undefined &&
+          (tainted.has(u.node.id) ||
+            (continueAlways &&
+              (u.status === 'failed' || u.status === 'aborted' || u.status === 'skipped'))),
+      )
     if (taint) tainted.add(node.id)
     return taint
   }
@@ -70,6 +76,15 @@ export function admitTasks(
   args: AdmissionArgs,
 ): (node: TaskNode, upstream: TaskOutcome[]) => Promise<TaskOutcome> {
   const { inflight, policy, shortCircuit, hashArgs, buildExecuteArgs } = args
+  // A probed hit whose artifact vanished before its restore is thrown back
+  // to the scheduler (`RestoreDemoted`, execute-task.ts), which dispatches
+  // the task again once its deps are done. That dispatch probes for itself:
+  // the up-front probe answered for an artifact that is gone. The task
+  // stays in the restore-tier SET, so it still skips dedup below.
+  const dropProbe = (err: unknown): never => {
+    if (err instanceof RestoreDemoted) shortCircuit.preProbed.delete(err.taskId)
+    throw err
+  }
   return async (node, upstream) => {
     // Dedup only helps when the sibling will WRITE the artifact and this
     // task can READ it back — i.e. both axes effectively on.
@@ -87,8 +102,15 @@ export function admitTasks(
     // wrong. Route it straight to executeTask, which reuses the up-front
     // probe.
     const restorable = shortCircuit.restoreTier.has(node.id)
+    // `!cacheable` is an early-out for bookkeeping, not a guard: measured
+    // (item 506), a non-cacheable task never finds a sibling barrier,
+    // because the hash folds the taskId and a taskId executes once per
+    // run. Removing it reddens nothing and a throw on "a non-cacheable
+    // task joined a barrier" never fires across the whole suite. It saves
+    // the set/delete, and the wait a joiner would spend before running the
+    // task anyway — there is no artifact for it to hit.
     if (inflight === undefined || !cacheable || restorable) {
-      return executeTask(buildExecuteArgs(node, upstream))
+      return executeTask(buildExecuteArgs(node, upstream)).catch(dropProbe)
     }
     const { nestedDirsByProject, ...rest } = hashArgs
     const hash = await computeTaskHash({
@@ -119,6 +141,8 @@ export function admitTasks(
       // `return await`, deliberately: the finally must run after the task
       // settles, not when its promise is handed back.
       return await executeTask(execArgs)
+    } catch (err) {
+      return dropProbe(err)
     } finally {
       // The barrier lifts when the ENTRY is there, not when the task is:
       // the save runs off the slot (save-lane.ts), and a sibling released

package/src/orchestrator/colors.ts

@@ -24,13 +24,18 @@ export interface PaintOptions {
 
 /**
  * Standard env precedence:
- *   NO_COLOR=anything   → off (overrides FORCE_COLOR)
- *   FORCE_COLOR=anything → on
+ *   NO_COLOR non-empty          → off (overrides FORCE_COLOR)
+ *   FORCE_COLOR=0 or =false     → off, even on a TTY
+ *   FORCE_COLOR any other value → on (the empty string too)
  *   else: on iff stdout is a TTY.
+ * `0` and `false` are the convention's "off" (supports-color, chalk,
+ * Node); reading every non-empty value as on painted a piped CI log that
+ * set `FORCE_COLOR=0` (nx#35292's bug).
  */
 export function detectColors(stream: NodeJS.WriteStream = process.stdout): ColorSupport {
   if (process.env['NO_COLOR']) return { enabled: false }
-  if (process.env['FORCE_COLOR']) return { enabled: true }
+  const force = process.env['FORCE_COLOR']
+  if (force !== undefined) return { enabled: force !== '0' && force !== 'false' }
   return { enabled: stream.isTTY === true }
 }
 

package/src/orchestrator/deferred-outputs.ts

@@ -77,15 +77,24 @@ export class DeferredOutputs {
   async materializeFor(node: TaskNode): Promise<void> {
     const needed: string[] = []
     const seen = new Set<string>()
-    const walk = (id: string): void => {
-      for (const dep of this.args.nodes.get(id)?.deps ?? []) {
-        if (seen.has(dep)) continue
-        seen.add(dep)
-        if (this.entries.has(dep)) needed.push(dep)
-        walk(dep)
+    // Pre-order on an explicit stack of dependency lists: a closure is as
+    // deep as the graph, and a recursion per edge threw `RangeError` at the
+    // 50,000 the builder takes (item 737).
+    const stack: Array<[deps: readonly string[], next: number]> = [
+      [this.args.nodes.get(node.id)?.deps ?? [], 0],
+    ]
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1]!
+      if (frame[1] === frame[0].length) {
+        stack.pop()
+        continue
       }
+      const dep = frame[0][frame[1]++]!
+      if (seen.has(dep)) continue
+      seen.add(dep)
+      if (this.entries.has(dep)) needed.push(dep)
+      stack.push([this.args.nodes.get(dep)?.deps ?? [], 0])
     }
-    walk(node.id)
     if (needed.length === 0) return
     await Promise.all(needed.map((id) => this.materializeOne(id)))
   }
@@ -110,6 +119,12 @@ export class DeferredOutputs {
 
     // Mirror `restoreHit`'s sequencing so the two paths cannot drift: wipe
     // the declared outputs, write, then tell the git snapshot what moved.
+    // The wipe is a rule (a straggler in the declared tree is gone after
+    // the fetch); the two marks are the mirror's cost, not a rule: no
+    // reader of these outputs can be in the run — `deferralEligibility`
+    // keeps every same-project reader and every workspaceFiles reader
+    // eager — so deleting the post-fetch mark survives the whole core
+    // suite (item 643).
     if (outputs.length > 0) {
       const cleaned = await cleanOutputs(cleanArgs)
       this.args.gitFilesCache?.markOutputsChanged(producer.projectDir, cleaned)

package/src/orchestrator/doctor.ts

@@ -12,14 +12,18 @@ import { PLUGIN_HOOKS } from '../config.js'
 import {
   cgroupCpuQuota,
   cgroupMemoryLimitBytes,
+  executablePath,
+  isUnsupportedBun,
   machineMemoryBytes,
   machineParallelism,
 } from '../util/index.js'
 import { VERSION } from '../version.js'
+import { probeSandbox, resetSandbox } from '../exec/index.js'
 import {
   buildPackageGraph,
   computeWorkspaceFingerprint,
   findWorkspaceRoot,
+  type LoadReads,
   listProjects,
   loadProjectConfig,
   loadWorkspace,
@@ -39,12 +43,27 @@ const warnToStderr = (message: string): void => {
 export interface InfoFacts {
   vx: string
   bun: string
+  /**
+   * False when `bun` is below `MIN_BUN`. A separate field on purpose: `bun`
+   * is a machine surface (`vx info --format json`, and a test holds it to
+   * `Bun.version` exactly), so the verdict is a boolean here and prose only
+   * in the rendered row. What an unsupported runtime breaks is measured in
+   * `util/bun-version.ts`.
+   */
+  bunSupported: boolean
   git: string | null
   /** null when git could not answer. */
   gitStatusCache: { fsmonitor: boolean; untrackedCache: boolean } | null
   workspaceRoot: string
   projects: number
   tasks: number
+  /**
+   * The project configs that did not load, each with the loader's own
+   * message (the path stripped). A broken config counts as zero tasks
+   * rather than failing the doctor — and the doctor says which, since a
+   * `0 tasks` that hides a typo is the one fact a bug report needs.
+   */
+  configErrors: Array<{ path: string; message: string }>
   plugins: Array<{ name: string; seams: string[] }>
   /**
    * The worker count a run defaults to and where it comes from: the
@@ -74,6 +93,14 @@ export interface InfoFacts {
   /** Tasks the retained history shows both passing and failing on unchanged inputs. */
   flakyTasks: FlakyTask[]
   lockfile: boolean
+  /**
+   * Whether this host can run a task's `exec.sandbox`, and how many loaded
+   * tasks declare one. A declared sandbox whose runtime cannot start is a
+   * hard failure at run time, not a downgrade — so the doctor says so
+   * first (root inside a container, a missing bubblewrap, a nested
+   * seatbelt), with the probe's own reason.
+   */
+  sandbox: { available: boolean; reason: string; declared: number }
 }
 
 export interface CollectInfoOptions {
@@ -85,19 +112,22 @@ export interface CollectInfoOptions {
 
 export async function collectInfo(cwd: string, opts: CollectInfoOptions = {}): Promise<InfoFacts> {
   const warn = opts.warn ?? warnToStderr
-  const root = await findWorkspaceRoot(cwd)
-  const metas = await listProjects(await loadWorkspace(root))
+  const reads: LoadReads = new Map()
+  const root = await findWorkspaceRoot(cwd, reads)
+  const metas = await listProjects(await loadWorkspace(root, reads))
   const { workspaceConfig, plugins } = await loadWorkspacePlugins(root, warn)
   const cacheDir =
     opts.cacheDir === undefined
       ? resolveCacheDir(root, workspaceConfig)
       : path.resolve(cwd, opts.cacheDir)
-  const cache = new Cache(cacheDir)
+  const cache = Cache.inspect(cacheDir)
   noteSchemaReset(cache, warn)
   let stats
   let orphans
   let flaky: FlakyTask[]
   let taskCount = 0
+  let sandboxed = 0
+  let configErrors: InfoFacts['configErrors'] = []
   try {
     stats = cache.stats()
     orphans = await cache.orphanStats()
@@ -116,23 +146,42 @@ export async function collectInfo(cwd: string, opts: CollectInfoOptions = {}): P
         seeds: 'all',
         closure: false,
         lock: null,
-        evalCache: { store: cache, workspaceFingerprint: await computeWorkspaceFingerprint(root) },
+        evalCache: {
+          store: cache,
+          workspaceFingerprint: await computeWorkspaceFingerprint(root, reads),
+        },
         warn,
       })
       for (const p of loaded.projects.values()) {
-        taskCount += Object.keys(p.config.tasks ?? {}).length
+        const tasks = p.config.tasks ?? {}
+        taskCount += Object.keys(tasks).length
+        for (const t of Object.values(tasks)) if (t?.exec?.sandbox !== undefined) sandboxed++
       }
     } catch {
-      taskCount = await countLoadableTasks(metas)
+      // A config that will not load counts as zero, for both numbers: the
+      // sandbox row's "N tasks declare" must not read 0 because one other
+      // project's config is broken while this one's declares a sandbox.
+      ;({
+        tasks: taskCount,
+        sandboxed,
+        errors: configErrors,
+      } = await countLoadableTasks(metas, root))
     }
   } finally {
     cache.close()
   }
 
   const lockPresent = await Bun.file(lockfilePath(root)).exists()
+  const sandbox = await sandboxFact(sandboxed)
   return {
     vx: VERSION,
+    // An unsupported Bun does not stop a run, it makes the run's ANSWERS
+    // wrong (util/bun-version.ts measures which). The row a reader already
+    // consults for "is my setup sane" is where that belongs: a warning on
+    // every invocation would put a line on stderr that a clean run must not
+    // have, which is a property 19 tests hold on purpose.
     bun: Bun.version,
+    bunSupported: !isUnsupportedBun(Bun.version),
     git: gitVersion(),
     // The one `git status` walk per run is the warm path's critical path on
     // a large tree (~55 ms at 1000 projects, measured 2026-09-02). git's
@@ -142,6 +191,7 @@ export async function collectInfo(cwd: string, opts: CollectInfoOptions = {}): P
     workspaceRoot: root,
     projects: metas.length,
     tasks: taskCount,
+    configErrors,
     // Which plugins loaded and which seams each fills, in pipeline order —
     // the answer to "why did this task run there / cache there / not at
     // all" before reading any config. A declined seam still costs nothing;
@@ -168,9 +218,39 @@ export async function collectInfo(cwd: string, opts: CollectInfoOptions = {}): P
     // this is the workspace's standing list.
     flakyTasks: flaky,
     lockfile: lockPresent,
+    sandbox,
   }
 }
 
+/**
+ * The runtime probe's verdict — one sandboxed `true` (memoized) — and the
+ * count of loaded tasks that would meet it. The probe initializes the
+ * Linux runtime, whose proxy sockets would keep a standalone process
+ * alive; reset after asking, since the doctor runs nothing.
+ */
+async function sandboxFact(declared: number): Promise<InfoFacts['sandbox']> {
+  try {
+    const verdict = await probeSandbox()
+    return { available: verdict.available, reason: stableSandboxReason(verdict.reason), declared }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return { available: false, reason: stableSandboxReason(message), declared }
+  } finally {
+    await resetSandbox()
+  }
+}
+
+/**
+ * The doctor's output is pasted into bug reports and compared between
+ * invocations (`vx stats` is pinned byte-identical to `vx info`), so a
+ * reason must not carry this process's id. The Linux runtime names its
+ * mux socket after the pid (`srt-mux-<pid>-<n>.sock`), and a listen that
+ * fails — a nested sandbox, a read-only tmpdir — quotes that path.
+ */
+export function stableSandboxReason(reason: string): string {
+  return reason.replace(/srt-mux-\d+-\d+\.sock/g, 'srt-mux-<pid>.sock')
+}
+
 /** The seams a plugin can fill, in pipeline order: the one hook list, less the lifecycle end. */
 const SEAMS = PLUGIN_HOOKS.filter((h) => h !== 'teardown')
 
@@ -209,7 +289,7 @@ function memoryFact(): InfoFacts['memory'] {
 function gitStatusCache(root: string): InfoFacts['gitStatusCache'] {
   try {
     const p = Bun.spawnSync({
-      cmd: ['git', 'config', '--get-regexp', '^core\\.(fsmonitor|untrackedcache)$'],
+      cmd: [executablePath('git'), 'config', '--get-regexp', '^core\\.(fsmonitor|untrackedcache)$'],
       cwd: root,
       stdout: 'pipe',
       stderr: 'pipe',
@@ -227,7 +307,11 @@ function gitStatusCache(root: string): InfoFacts['gitStatusCache'] {
 
 function gitVersion(): string | null {
   try {
-    const p = Bun.spawnSync({ cmd: ['git', '--version'], stdout: 'pipe', stderr: 'pipe' })
+    const p = Bun.spawnSync({
+      cmd: [executablePath('git'), '--version'],
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
     if (p.exitCode !== 0) return null
     return new TextDecoder()
       .decode(p.stdout)
@@ -238,18 +322,42 @@ function gitVersion(): string | null {
   }
 }
 
-async function countLoadableTasks(metas: readonly ProjectMeta[]): Promise<number> {
-  let count = 0
+async function countLoadableTasks(
+  metas: readonly ProjectMeta[],
+  root: string,
+): Promise<{ tasks: number; sandboxed: number; errors: InfoFacts['configErrors'] }> {
+  let tasks = 0
+  let sandboxed = 0
+  const errors: InfoFacts['configErrors'] = []
   await Promise.all(
     metas.map(async (meta) => {
       if (meta.configPath === null) return
       try {
         const config = await loadProjectConfig(meta.configPath)
-        count += Object.keys(config.tasks ?? {}).length
-      } catch {
-        // counted as zero
+        const declared = Object.values(config.tasks ?? {})
+        tasks += declared.length
+        for (const t of declared) if (t?.exec?.sandbox !== undefined) sandboxed++
+      } catch (err) {
+        // Counted as zero, and named: the loader's message opens with the
+        // absolute path — bare for a schema refusal, behind `Project config`
+        // for an import that failed — which the row carries
+        // workspace-relative instead, once (the second form named the file
+        // twice, 2026-09-16).
+        const raw = err instanceof Error ? err.message : String(err)
+        let message = raw
+        for (const prefix of [`${meta.configPath}: `, `Project config ${meta.configPath}: `]) {
+          if (raw.startsWith(prefix)) {
+            message = raw.slice(prefix.length)
+            break
+          }
+        }
+        errors.push({
+          path: path.relative(root, meta.configPath).split(path.sep).join('/'),
+          message,
+        })
       }
     }),
   )
-  return count
+  errors.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  return { tasks, sandboxed, errors }
 }

package/src/orchestrator/events.ts

@@ -6,6 +6,7 @@
 // additional subscribers later, so a slow/wedged renderer can never
 // stall task exec. See docs/design/event-stream-2026-06.md.
 
+import { exitSignal } from '../exec/index.js'
 import type { TaskNode, TaskOutcome } from '../graph/index.js'
 import { isGroupTask } from '../graph/index.js'
 import type { Logger } from './logger.js'
@@ -231,6 +232,13 @@ export interface OutcomeView {
   hash?: string
   cpuMs?: number
   peakRssBytes?: number
+  /** A failure vx's own `timeout` killed (see `TaskOutcome`). */
+  timedOut?: true
+  /** A persistent task that never became ready, and why (see `TaskOutcome`). */
+  notReady?: 'timeout' | 'exited' | 'spawn'
+  /** A skipped task: the failed (or aborted) task at the root of the block
+   *  (see `TaskOutcome`); absent for fail-fast's skip, which nothing blocked. */
+  blockedBy?: string
   /** How long an `admit` policy held the task with a worker free (see `TaskOutcome`). */
   admissionHeldMs?: number
   restored?: boolean
@@ -260,8 +268,66 @@ export function outcomeWord(o: Pick<OutcomeView, 'status' | 'restored'>): string
 }
 
 /** `outcomeWord` with the exit code a failure carries: `failed (exit 9)`. */
-export function outcomeLabel(o: Pick<OutcomeView, 'status' | 'restored' | 'exitCode'>): string {
-  return o.status === 'failed' ? `failed (exit ${o.exitCode})` : outcomeWord(o)
+export function outcomeLabel(
+  o: Pick<
+    OutcomeView,
+    'status' | 'restored' | 'exitCode' | 'timedOut' | 'sandboxViolations' | 'notReady' | 'blockedBy'
+  >,
+): string {
+  if (o.status === 'failed')
+    return failedLabel(o.exitCode, o.timedOut, o.sandboxViolations, o.notReady)
+  if (o.status === 'skipped') return skippedLabel(o.blockedBy)
+  return outcomeWord(o)
+}
+
+/**
+ * Why a task was skipped, one copy for every surface: `blocked by lib#build`
+ * (the failed or aborted task at the root of the block, what the footer's
+ * Skipped section groups by), or '' for fail-fast's skip — the run stopped,
+ * nothing blocked it, and a label claiming an upstream failure would lie.
+ */
+export function skippedReason(blockedBy: string | undefined): string {
+  return blockedBy === undefined ? '' : `blocked by ${blockedBy}`
+}
+
+/** `skipped (blocked by lib#build)`, or a bare `skipped` for fail-fast's. */
+export function skippedLabel(blockedBy: string | undefined): string {
+  const why = skippedReason(blockedBy)
+  return why === '' ? 'skipped' : `skipped (${why})`
+}
+
+/**
+ * A failure's label, one copy for every surface (the frame's footer, the
+ * status line, the run report, the Actions annotation): the exit code, and
+ * above 128 the signal it stands for — `failed (exit 137, 128 + SIGKILL)` —
+ * or, for vx's own timeout, `failed (timed out, exit 143)`, or a persistent
+ * task that never became ready, `failed (never ready: timed out, exit 1)`; a
+ * sandboxed task's violations are counted after: `failed (exit 1, 2 sandbox
+ * violations)`.
+ */
+export function failedLabel(
+  exitCode: number,
+  timedOut?: true,
+  sandboxViolations?: number,
+  notReady?: 'timeout' | 'exited' | 'spawn',
+): string {
+  // A sandboxed task that touched what it never declared fails on that
+  // alone (its exit is forced to 1 when it was 0): the count is the reason.
+  const violations =
+    sandboxViolations === undefined || sandboxViolations === 0
+      ? ''
+      : `, ${sandboxViolations} sandbox violation${sandboxViolations === 1 ? '' : 's'}`
+  // A persistent task that never became ready: the reason reads first; its
+  // exit is the child's own when it exited, else vx's 1.
+  if (notReady !== undefined) {
+    const why =
+      notReady === 'timeout' ? 'timed out' : notReady === 'exited' ? 'exited' : 'spawn failed'
+    return `failed (never ready: ${why}, exit ${exitCode}${violations})`
+  }
+  // A timeout's 143 is vx's own SIGTERM: the reason, not the signal, reads.
+  if (timedOut === true) return `failed (timed out, exit ${exitCode}${violations})`
+  const signal = exitSignal(exitCode)
+  return `failed (exit ${exitCode}${signal === undefined ? '' : `, 128 + ${signal}`}${violations})`
 }
 
 export function projectNode(node: TaskNode): TaskView {
@@ -294,6 +360,9 @@ export function projectOutcome(outcome: TaskOutcome): OutcomeView {
   if (outcome.cpuMs !== undefined) view.cpuMs = outcome.cpuMs
   if (outcome.peakRssBytes !== undefined) view.peakRssBytes = outcome.peakRssBytes
   if (outcome.admissionHeldMs !== undefined) view.admissionHeldMs = outcome.admissionHeldMs
+  if (outcome.timedOut === true) view.timedOut = true
+  if (outcome.notReady !== undefined) view.notReady = outcome.notReady
+  if (outcome.blockedBy !== undefined) view.blockedBy = outcome.blockedBy
   if (outcome.restored !== undefined) view.restored = outcome.restored
   if (outcome.sandboxViolations !== undefined) view.sandboxViolations = outcome.sandboxViolations
   if (outcome.sandboxViolationLines !== undefined)