@vzn/vx 0.0.635 → 0.0.637

package/src/orchestrator/logger.ts

@@ -1,4 +1,5 @@
 import type { TaskNode, TaskOutcome } from '../graph/index.js'
+import { settingEnv } from '../settings.js'
 import { detectColors, type ColorSupport } from './colors.js'
 import {
   formatFrameClose,
@@ -177,7 +178,10 @@ export function resolveOutputView(
     ...(gha ? { gha: true } : {}),
     ...(ci ? { ci: true } : {}),
   })
-  if (options.outputLogs !== undefined) return mk(options.outputLogs)
+  // `run.outputLogs`: chosen before the workspace loads, so flag, then variable.
+  const outputLogs =
+    options.outputLogs ?? (settingEnv('run.outputLogs', env) as OutputView['mode'] | undefined)
+  if (outputLogs !== undefined) return mk(outputLogs)
   if (ci) return mk('full')
   if (options.flow !== undefined) return mk(options.flow)
   return mk('full')
@@ -198,6 +202,8 @@ export function defaultLogger(
     tty?: boolean
     /** The args after `--`: a requested task's `$ <command>` line shows them, as it ran. */
     forwardArgs?: readonly string[]
+    /** `false`: no summary in the live region and no blank line opening the log (`RunOptions.footer`). */
+    footer?: boolean
     /** The environment that names the terminal (`TERM_PROGRAM`, …); `process.env` by default. */
     env?: Readonly<Record<string, string | undefined>>
   } = {},
@@ -295,6 +301,7 @@ export function defaultLogger(
   let etaMs: number | undefined
   let critical: string | undefined
   let blocks: ReadonlyMap<string, number> | undefined
+  let expected: ReadonlyMap<string, number> | undefined
   let etaAtMs = 0
   const signals = writer.enabled
     ? terminalSignals(opts.env ?? process.env)
@@ -311,6 +318,10 @@ export function defaultLogger(
   // as `+k more` on the stats line. Focused flow keeps its lifecycle:
   // the region dies the moment a requested node starts streaming.
   let slots: (WorkerSlot | null)[] = []
+  // Rows shown: the most workers busy at once so far. An idle row past it
+  // was noise (a 10-core machine drew 9 on a one-chain run); it never
+  // shrinks, so a row never jumps.
+  let shownSlots = 0
   const slotQueue: WorkerSlot[] = []
   let succeeded = 0
   // Executed with no `cache` block: never a miss, counted apart.
@@ -375,16 +386,16 @@ export function defaultLogger(
       if (text.length < KEPT_LINE_CAP) held.rest = text
       else {
         held.rest = ''
-        writer.write(fenced(formatKeptLines(node, text, colors)))
+        taskWrite(fenced(formatKeptLines(node, text, colors)))
       }
       return
     }
     held.rest = text.slice(cut + 1)
-    writer.write(fenced(formatKeptLines(node, text.slice(0, cut), colors)))
+    taskWrite(fenced(formatKeptLines(node, text.slice(0, cut), colors)))
   }
   const flushKept = (): void => {
     for (const held of keptLines.values()) {
-      if (held.rest.length > 0) writer.write(fenced(formatKeptLines(held.node, held.rest, colors)))
+      if (held.rest.length > 0) taskWrite(fenced(formatKeptLines(held.node, held.rest, colors)))
       held.rest = ''
     }
   }
@@ -404,6 +415,7 @@ export function defaultLogger(
       etaMs = f.etaMs
       critical = f.critical
       blocks = f.blocks
+      expected = f.expected
     }
     if (signals.progress && total > 0) {
       const elapsed = now - startedAtMs
@@ -421,38 +433,42 @@ export function defaultLogger(
     }
     // The live summary IS the final summary's section, built from the
     // same formatter so the region visually becomes the printout.
-    const summaryLines = formatSummarySection(
-      {
-        failed,
-        successful: succeeded + upToDate + restoredLocal + restoredRemote,
-        skipped: skippedCount,
-        total,
-        upToDate,
-        restoredLocal,
-        restoredRemote,
-        miss: succeeded + failed - noCache,
-        noCache,
-        savedMs,
-        left: total - done,
-        ...(etaMs !== undefined ? { etaMs } : {}),
-        spread:
-          spreadCount > 0
-            ? { maxMs: spreadMax, minMs: spreadMin, sumMs: spreadSum, count: spreadCount }
-            : null,
-      },
-      Date.now() - startedAtMs,
-      colors,
-      runContext,
-    )
+    const summaryLines =
+      opts.footer === false
+        ? []
+        : formatSummarySection(
+            {
+              failed,
+              successful: succeeded + upToDate + restoredLocal + restoredRemote,
+              skipped: skippedCount,
+              total,
+              upToDate,
+              restoredLocal,
+              restoredRemote,
+              miss: succeeded + failed - noCache,
+              noCache,
+              savedMs,
+              left: total - done,
+              ...(etaMs !== undefined ? { etaMs } : {}),
+              spread:
+                spreadCount > 0
+                  ? { maxMs: spreadMax, minMs: spreadMin, sumMs: spreadSum, count: spreadCount }
+                  : null,
+            },
+            Date.now() - startedAtMs,
+            colors,
+            runContext,
+          )
     writer.setRegion(
       formatStatusRegion(
         {
           pinnedPersistent,
-          slots,
+          slots: slots.slice(0, shownSlots),
           overflow: slotQueue.length,
           nowMs: Date.now(),
           summaryLines,
           ...(blocks !== undefined ? { blocks } : {}),
+          ...(expected !== undefined ? { expected } : {}),
           ...(critical !== undefined ? { critical } : {}),
         },
         colors,
@@ -478,8 +494,21 @@ export function defaultLogger(
     writer.clearStatus()
   }
 
+  // The task log opens with one blank line before its first row, on a
+  // terminal and off one (M, 2026-10-14). A note vx prints before it is
+  // no task row (`status`). Without a footer, the caller frames the log
+  // (`vx watch` opens each cycle with its own line).
+  let logOpened = opts.footer === false
+  const taskWrite = (chunk: string): void => {
+    if (!logOpened && chunk.length > 0) {
+      logOpened = true
+      writer.write(`\n${chunk}`)
+      return
+    }
+    writer.write(chunk)
+  }
   const emitLine = (line: string): void => {
-    writer.write(`${line}\n`)
+    taskWrite(`${line}\n`)
     lineEmitted = true
   }
   // formatTaskBlock returns '' for group tasks (no exec) — skip the
@@ -487,14 +516,14 @@ export function defaultLogger(
   const emitBlock = (block: string): void => {
     if (block.length === 0) return
     const lead = lineEmitted || streamedSinceBlock ? '\n' : ''
-    writer.write(`${lead}${block}\n`)
+    taskWrite(`${lead}${block}\n`)
     lineEmitted = false
     streamedSinceBlock = false
   }
   // Live-frame close lines end a frame the same way emitBlock does:
   // with a trailing blank line, resetting the separator state.
   const emitFrameClose = (line: string): void => {
-    writer.write(`${line}\n\n`)
+    taskWrite(`${line}\n\n`)
     lineEmitted = false
     streamedSinceBlock = false
   }
@@ -549,6 +578,7 @@ export function defaultLogger(
       startedAtMs = Date.now()
       const cap = Math.max(1, Math.min(info.concurrency ?? 10, 10))
       slots = Array.from({ length: cap }, () => null)
+      shownSlots = 0
       if (writer.enabled && !statusDead && ticker === null) {
         // Keeps the per-worker elapsed time ticking between task events
         // (the time IS the motion — there's no spinner). The writer
@@ -585,8 +615,10 @@ export function defaultLogger(
       }
       const slot: WorkerSlot = { id: node.id, startedMs: Date.now() }
       const free = slots.indexOf(null)
-      if (free >= 0) slots[free] = slot
-      else slotQueue.push(slot)
+      if (free >= 0) {
+        slots[free] = slot
+        shownSlots = Math.max(shownSlots, free + 1)
+      } else slotQueue.push(slot)
       refresh(true)
     },
     forecast(load) {
@@ -675,7 +707,7 @@ export function defaultLogger(
       if (streamsLive(node)) {
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
-        writer.write(chunk)
+        taskWrite(chunk)
         return
       }
       const tail = persistentTails.get(node.id)
@@ -691,7 +723,7 @@ export function defaultLogger(
       if (streamsLive(node)) {
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
-        writer.write(chunk)
+        taskWrite(chunk)
         return
       }
       const tail = persistentTails.get(node.id)
@@ -747,7 +779,7 @@ export function defaultLogger(
             (framesTerminal && holdsTerminal(node)))
         if (framed && streamsLive(node)) {
           if (streamMidLine) {
-            writer.write('\n')
+            taskWrite('\n')
             streamMidLine = false
           }
           emitFrameClose(formatFrameClose(node, outcome, colors))
@@ -830,7 +862,7 @@ export function defaultLogger(
       if (isGroupTask(node)) return
       if (holdsTerminal(node) && streamsLive(node) && outcome.status !== 'skipped') {
         if (streamMidLine) {
-          writer.write('\n')
+          taskWrite('\n')
           streamMidLine = false
         }
         emitFrameClose(formatFrameClose(node, outcome, colors))
@@ -908,7 +940,7 @@ export function defaultLogger(
               // and up-to-date included (owner: "always full frame
               // for a single task").
               if (streamMidLine) {
-                writer.write('\n')
+                taskWrite('\n')
                 streamMidLine = false
               }
               emitFrameClose(formatFrameClose(node, outcome, colors))
@@ -1003,7 +1035,7 @@ export function defaultLogger(
               // The message is ours (a literal, an integer and a signal
               // name); only the title carries user input.
               emitBlock(
-                `::error title=${ghaProperty(node.id)}::${failedLabel(outcome.exitCode, outcome.timedOut, outcome.sandboxViolations, outcome.notReady)}\n${body}`,
+                `::error title=${ghaProperty(node.id)}::${failedLabel(outcome.exitCode, outcome.timedOut, outcome.sandboxViolations, outcome.notReady, outcome.inputMoved)}\n${body}`,
               )
             } else {
               emitBlock(

package/src/orchestrator/metrics.ts

@@ -1,15 +1,18 @@
 // Run-history queries — pure functions over a `bun:sqlite` Database.
 //
 // `vx why` and `vx last` read through them, and so can any out-of-process
-// surface (an MCP server plugin, a dashboard). One canonical home for every
+// surface. One canonical home for every
 // aggregate over the runs / entries tables. The schema itself is owned by
 // src/cache/cache.ts.
 //
-// Pure SQL + JSON-safe return shapes. No Cache lifecycle here; the
+// Pure SQL + JSON-safe return shapes (`inputWriters` also stats the
+// files it names). No Cache lifecycle here; the
 // caller opens and closes. bigints are serialized as decimal strings
 // for JSON compatibility (matches the WireEvent timeUnixNano rule).
 
 import type { Database } from 'bun:sqlite'
+import { statSync } from 'node:fs'
+import path from 'node:path'
 // The keyed-run predicate lives beside the schema in cache/cache.ts, so a
 // rule written once cannot drift.
 import { KEYED_RUNS_SQL } from '../cache/index.js'
@@ -410,7 +413,7 @@ function unchangedKeyNote(
     } | null
   )?.p
   if (policy !== undefined && !policy.split(',').some((axis) => axis === 'lR' || axis === 'rR')) {
-    return 'cache key unchanged — re-executed because this run did not read the cache (--force, or a --cache without read)'
+    return 'cache key unchanged — re-executed because this run did not read the cache (--force, or a --cache-policy without read)'
   }
   // `get` answers null, not undefined, for no row.
   const createdAt = (
@@ -470,7 +473,7 @@ function unchangedKeyNote(
             } | null
           )?.p
     if (prevPolicy !== undefined && !prevPolicy.split(',').some((a) => a === 'lW' || a === 'rW')) {
-      return 'cache key unchanged — the previous run on this key did not write the cache (--no-cache, or a --cache without write), so there was nothing to hit'
+      return 'cache key unchanged — the previous run on this key did not write the cache (--no-cache, or a --cache-policy without write), so there was nothing to hit'
     }
     return 'cache key unchanged — the previous run on this key executed but no entry for it is in the cache (its save failed, or it was pruned since), so there was nothing to hit'
   }
@@ -479,8 +482,7 @@ function unchangedKeyNote(
 
 /**
  * The latest recorded run of a task (run_id may be NULL on very old rows).
- * One query for `vx why` and `vx mcp`: the CLI defaulted to it while the
- * tool demanded a run id an agent had to fetch first (2026-09-16).
+ * `vx why`'s default when no run id is given.
  */
 export function latestRunId(db: Database, taskId: string): string | null {
   const [project, task] = splitTaskId(taskId)
@@ -875,6 +877,69 @@ export function rootCauses(
   return roots
 }
 
+export interface InputWriter {
+  /** The task whose key read the file. */
+  taskId: string
+  /** Workspace-relative, as the key names it. */
+  file: string
+  /** The tasks that were running when the file last changed. */
+  writers: string[]
+}
+
+/**
+ * Slack around a task's recorded window: its edges are rounded to the
+ * millisecond and a write lands just before the process exits.
+ */
+const WRITE_SLACK_MS = 5
+
+/**
+ * For each moved input file of `taskId` and of each root cause, the
+ * recorded tasks that were running when the file last changed: a task
+ * that writes a file another key reads re-keys that task on every run.
+ * The file's mtime against the recorded windows, so
+ * a writer that runs each time is named from its latest run, and an
+ * edit made outside a run names none.
+ */
+export function inputWriters(
+  db: Database,
+  workspaceRoot: string,
+  taskId: string,
+  entries: CacheKeyDiff['entries'],
+  roots: readonly RootCause[],
+): InputWriter[] {
+  const during = db.query(
+    `SELECT project, task FROM runs
+      WHERE started_at <= ?1 + ${WRITE_SLACK_MS} AND ended_at >= ?1 - ${WRITE_SLACK_MS}
+        AND status != 'skipped'
+      GROUP BY project, task ORDER BY MIN(started_at) LIMIT 3`,
+  )
+  const out: InputWriter[] = []
+  const owners = [
+    { taskId, entries },
+    ...roots.map((r) => ({ taskId: r.chain.at(-1)!, entries: r.entries })),
+  ]
+  for (const owner of owners) {
+    for (const e of owner.entries) {
+      if (e.kind !== 'file' || e.change === 'removed') continue
+      let mtime: number
+      try {
+        mtime = statSync(path.join(workspaceRoot, e.name)).mtimeMs
+      } catch {
+        continue
+      }
+      const rows = during.all(mtime) as { project: string; task: string }[]
+      if (rows.length > 0) {
+        out.push({
+          taskId: owner.taskId,
+          file: e.name,
+          writers: rows.map((r) => `${r.project}#${r.task}`),
+        })
+      }
+    }
+  }
+  return out
+}
+
 // ---------------------------------------------------------------------------
 // Run comparison — diff a run against the immediately-previous invocation
 // ---------------------------------------------------------------------------

package/src/orchestrator/miss-save.ts

@@ -81,6 +81,8 @@ export interface SaveMissArgs {
   ownOutputFiles?: string[] | undefined
   /** `ownOutputFiles` for `cache.outputs.workspaceFiles` (A-43). */
   ownWsOutputFiles?: string[] | undefined
+  /** A sandboxed task's reach: a symlinked output it could not read is refused (`sandboxReadable`). */
+  readable?: ((real: string) => boolean) | undefined
   /** The Tier-3 input fingerprint rows captured by the pre-exec describe. */
   captured: readonly TaskInputComponent[]
   command: string
@@ -176,6 +178,7 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
         ? { workspaceOutputFiles: wsOutputFiles, workspaceRoot: a.workspaceRoot }
         : {}),
       inputComponents: a.captured.map((c) => ({ entryHash: a.hash, ...c })),
+      readable: a.readable,
       // 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.

package/src/orchestrator/options.ts

@@ -2,7 +2,7 @@
 // so internals like prepare.ts can import them without an upward
 // import of index.ts — the module entry must stay cycle-free.
 
-import type { CachePolicy, RemoteCacheLayer } from '../cache/index.js'
+import type { CacheFlags, CachePolicy, RemoteCacheLayer } from '../cache/index.js'
 import type { ContinueMode } from '../graph/index.js'
 import type { TaskOutcome } from '../graph/index.js'
 import type { AffectedReason } from './affected-tasks.js'
@@ -11,6 +11,7 @@ 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'
 
 export interface RunOptions {
   cwd: string
@@ -47,7 +48,7 @@ export interface RunOptions {
   affectedReasons?: Map<string, AffectedReason>
   /**
    * Configs a selection pass in this same process already loaded and
-   * staged with the same `cacheDir` and `frozen` (the CLI walks every
+   * staged with the same `cacheDir` (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
@@ -67,40 +68,39 @@ export interface RunOptions {
   concurrency?: number
   /**
    * Cache directory override (`--cache-dir <path>`). Absolute, or relative
-   * to `cwd`. Takes precedence over the workspace `cacheDir` field and the
+   * to `cwd`. Takes precedence over the workspace `cache.dir` field and the
    * `.vx/cache` default. A per-run knob — never folded into a cache key.
    */
   cacheDir?: string
   /**
    * Granular cache read/write control across the local + remote layers.
    * Each of the four axes (localRead / localWrite / remoteRead /
-   * remoteWrite) is independent. Undefined → {@link FULL_CACHE_POLICY}
-   * (everything on). `--no-cache` sets all four false; `--force` sets
-   * both reads false (re-execute, still refresh the cache).
+   * remoteWrite) is independent. Undefined → the workspace's
+   * `cache.policy` with `cacheFlags` applied, else {@link FULL_CACHE_POLICY}
+   * (everything on).
    */
   cache?: CachePolicy
   /**
-   * The caller asked for a remote axis by name (`--cache=remote:rw`). With
+   * With no `cache`: `--no-cache` (all four off) and `--force` (both reads
+   * off), applied over the workspace's `cache.policy`.
+   */
+  cacheFlags?: CacheFlags
+  /**
+   * The caller asked for a remote axis by name (`--cache-policy=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
+  /** This run's `cache.scope` (the CLI's `--cache-scope`), above `VX_CACHE_SCOPE` and `.vx/workspace`. */
+  cacheScope?: string
   /**
-   * The `cacheScope` a run takes when `vx.workspace` names none. The CLI
-   * passes `'read-only'` off CI (`CI` unset, `0` or `false`) unless
-   * `--cache` names the remote; omitted → trusted.
-   */
-  defaultCacheScope?: string
-  /**
-   * CI mode: load configs FROM the committed vx-lock.json instead of
-   * evaluating them (frozen-env reproducibility). Requires the lock
-   * to exist and pass its content-hash tripwire. Local runs default
-   * to live evaluation — byte hashes can't see a config's import
-   * closure, so a strict local mode would give false confidence.
-   * Pair with `vx lock --check` in CI for the full evaluation audit.
+   * The default policy's remote write is off (`remote:r`): the CLI passes it
+   * off CI (`CI` unset, `0` or `false`) unless `--cache-policy` or
+   * `VX_CACHE_POLICY` names the remote. Dropped when the workspace's
+   * `cache.policy` names the remote.
    */
-  frozen?: boolean
+  remoteReadOnlyByDefault?: boolean
   /**
    * Explicit per-task output volume for the default logger. ALWAYS
    * overrides the flow default. 'full': frames for work + one-liners
@@ -133,19 +133,18 @@ export interface RunOptions {
    */
   flow?: 'focused' | 'broad'
   /**
-   * Run-level retry default (`--retry <n>`): max additional attempts
+   * `run.retries` from its flag (`--retries <n>`): max additional attempts
    * after a failed attempt, for tasks that don't declare their own
-   * `exec.retries` (explicit config wins, including `retries: 0`).
-   * Threaded as an option only — never folded into any cache key, so
-   * the same run with and without `--retry` derives identical keys.
+   * `exec.retries` (explicit config wins, including `retries: 0`); unset,
+   * `VX_RUN_RETRIES`, then the workspace's. Never folded into any cache
+   * key, so the same run with and without `--retries` derives identical keys.
    * A non-negative integer; run() refuses anything else (C-61).
    */
   retries?: number
   /**
-   * Run-level default task timeout (ms), for tasks that declare no
-   * `exec.timeout`. Highest of the run-level defaults: `--timeout` /
-   * this option → `VX_TASK_TIMEOUT` env → workspace `timeout`. Per-task
-   * `exec.timeout` always wins. Threaded as an option only — never
+   * `run.timeout` in ms from its flag (`--timeout 30m`), for tasks that
+   * declare no `exec.timeout`; unset, `VX_RUN_TIMEOUT`, then the
+   * workspace's. Per-task `exec.timeout` always wins. Never
    * folded into any cache key (a timed-out task fails and is never
    * cached), so a `--timeout` run cache-hits a plain run's entry.
    * A positive integer of ms up to `2 ** 31 - 1`; run() refuses anything
@@ -161,6 +160,16 @@ export interface RunOptions {
    * `--continue[=never|deps-ok|always]`; bare `--continue` = 'always'.
    */
   continueMode?: ContinueMode
+  /** `--branch`; unset, `VX_RUN_BRANCH`, then git's, then the CI provider's. */
+  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
@@ -188,6 +197,12 @@ export interface RunOptions {
    * 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
+   * cycle with its own line).
+   */
+  footer?: boolean
   /**
    * If set, write a Chrome-trace JSON profile of the run's wallclock
    * spans. Path is cwd-relative. Default `profile.json` is selected

package/src/orchestrator/output-host.ts

@@ -0,0 +1,72 @@
+// The `output` capability: a plugin may take the terminal for a run. Sibling
+// 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 type { OutputContext, VxPlugin } from './plugin.js'
+
+const REQUIRED = ['status', 'taskStdout', 'taskStderr', 'taskComplete'] as const
+const OPTIONAL = ['runStart', 'taskStart', 'runEnd'] as const
+
+/** Reject anything that is not Logger-shaped, naming what is missing. */
+function checkLogger(value: unknown): Logger {
+  if (typeof value !== 'object' || value === null) {
+    throw new Error(`output must be a Logger object, got ${value === null ? 'null' : typeof value}`)
+  }
+  const o = value as Record<string, unknown>
+  const missing = REQUIRED.filter((k) => typeof o[k] !== 'function')
+  if (missing.length > 0) throw new Error(`output Logger has no ${missing.join(', ')}`)
+  const wrong = OPTIONAL.filter((k) => o[k] !== undefined && typeof o[k] !== 'function')
+  if (wrong.length > 0) throw new Error(`output Logger's ${wrong.join(', ')} must be functions`)
+  return value as Logger
+}
+
+/**
+ * The first plugin, in declaration order, whose `output` returns a Logger.
+ * A hook that throws or returns something else is warned about and passed
+ * over: a renderer must never fail a run.
+ */
+export async function claimOutput(
+  plugins: readonly VxPlugin[],
+  ctx: OutputContext,
+): Promise<{ logger: Logger; owner: string } | undefined> {
+  for (const plugin of plugins) {
+    if (plugin.output === undefined) continue
+    try {
+      const logger = await plugin.output(ctx)
+      if (logger !== undefined) return { logger: checkLogger(logger), owner: plugin.name }
+    } catch (err) {
+      ctx.warn(
+        `[vx] plugin '${plugin.name}' output: ${err instanceof Error ? err.message : String(err)}; vx renders the run`,
+      )
+    }
+  }
+  return undefined
+}
+
+/**
+ * The bus subscriber for a plugin's Logger. The first throw hands that
+ * event and every later one to `fallback` (core's renderer), after one
+ * status line naming the plugin.
+ */
+export function guardedOutput(
+  claimed: { logger: Logger; owner: string },
+  fallback: RunEventSubscriber,
+): RunEventSubscriber {
+  const render = terminalSubscriber(claimed.logger)
+  let failed = false
+  return (event) => {
+    if (failed) return fallback(event)
+    try {
+      render(event)
+    } catch (err) {
+      failed = true
+      fallback({
+        kind: 'run:status',
+        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/plan.ts

@@ -50,7 +50,7 @@ export interface PlannedTask {
   executor?: string
   /**
    * `'deferred'` when this task's outputs would stay in the remote store
-   * (`--download=none` / `toplevel`). Attached only when it is TRUE — an
+   * (`--cache-download=none` / `toplevel`). Attached only when it is TRUE — an
    * eager task is the default and saying so on every line says nothing.
    */
   download?: 'deferred'
@@ -91,22 +91,21 @@ export interface RunPlan {
   /** Set when `--affected` left nothing to run: the line the run would print, and why. */
   noneAffected?: string
   /**
-   * Producers `--download` WANTED to defer but could not, mapped to why.
-   * Without this the gate is invisible: a user asks for `--download=none`,
+   * Producers `--cache-download` WANTED to defer but could not, mapped to why.
+   * Without this the gate is invisible: a user asks for `--cache-download=none`,
    * gets no deferral, and has nothing to read. Empty/absent under
-   * `--download=all`, which defers nothing by definition.
+   * `--cache-download=all`, which defers nothing by definition.
    */
   downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
 }
 
 export interface PlanArgs {
   nodes: Map<string, TaskNode>
-  /** Per-task `--download` decision, when the policy is not `all`. */
+  /** Per-task `--cache-download` decision, when the policy is not `all`. */
   downloadOf?: (id: string) => 'eager' | 'deferred' | 'never' | undefined
   /** See `RunPlan.downloadDowngrades`. */
   downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
   workspaceRoot: string
-  workspaceFingerprint: string
   cache: CacheLayer
   cachePolicy?: CachePolicy
   forwardArgs?: readonly string[] | undefined
@@ -150,7 +149,6 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
         node,
         upstream,
         workspaceRoot: args.workspaceRoot,
-        workspaceFingerprint: args.workspaceFingerprint,
         cache: args.cache,
         forwardArgs: args.forwardArgs,
         nestedProjectDirs: args.nestedDirsByProject.get(node.projectName) ?? [],
@@ -166,7 +164,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
 
       // Prediction keys off READS: a no-read policy re-executes every task,
       // so nothing is probed. Whether that run is a miss or no cache at all
-      // is the WRITE axes': `--force` and `--cache=local:w` save what they
+      // is the WRITE axes': `--force` and `--cache-policy=local:w` save what they
       // run, and the plan called them `no-cache`, the label a task with no
       // `cache` block gets (item 991). The probe below routes through the
       // policy-aware cache layer, which itself respects read gating.