@vzn/vx 0.0.637 → 0.0.638

package/src/orchestrator/run.ts

@@ -11,6 +11,11 @@ import {
   type CacheLayer,
   type CachePolicy,
   cachesNothing,
+  formatCachePolicy,
+  packRunOutputs,
+  resolveOutputs,
+  resolveWorkspaceOutputs,
+  runEntryName,
   stopRuntimeProbes,
 } from '../cache/index.js'
 import { VERSION } from '../version.js'
@@ -48,6 +53,9 @@ import {
   secretMask,
   isFsRefusal,
   isUserError,
+  detectColors,
+  relPosix,
+  type ColorSupport,
 } from '../util/index.js'
 import { keyedProjects } from './keyed-projects.js'
 import { isDefaultBuild } from './projects.js'
@@ -58,14 +66,14 @@ import { unkeyedGroupOutcome, type ExecuteArgs } from './execute-task.js'
 import { excludedTaint } from './excluded-keys.js'
 import { keyUpstream } from './upstream.js'
 import { busLogger, createEventBus, terminalSubscriber, type EventBus } from './events.js'
-import { installPlugins, PluginSetupError } from './plugin.js'
+import { installPlugins, PluginSetupError, type RunReport, type RunReportTask } from './plugin.js'
+import { decodeOutputLog } from './output-log.js'
 import { buildAdmission, executorLabel, resolveExecutors, teardownPlugins } from './plugin-host.js'
 import { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
 import { claimOutput, guardedOutput } from './output-host.js'
 import { assembleRunSummary, isPassStatus } from './telemetry.js'
 import type { RunContextRecord } from './telemetry.js'
 import { defaultLogger, type DefaultLogger, resolveOutputView, type Logger } from './logger.js'
-import { detectColors, type ColorSupport } from './colors.js'
 import { plainOutput } from './plain-output.js'
 import { formatPersistentList } from './framed-output.js'
 import { createForecast } from './forecast.js'
@@ -138,18 +146,19 @@ const emptyShortCircuit = (): ShortCircuit => ({
   groupKeys: new Map(),
 })
 
-/**
- * Compact the 4-axis cache policy into the `invocations.cache_policy`
- * column string. Each enabled axis contributes its flag; a fully-on
- * policy reads `'lR,lW,rR,rW'`. Pure presentation — never affects the key.
- */
-function compactCachePolicy(p: CachePolicy): string {
-  const parts: string[] = []
-  if (p.localRead) parts.push('lR')
-  if (p.localWrite) parts.push('lW')
-  if (p.remoteRead) parts.push('rR')
-  if (p.remoteWrite) parts.push('rW')
-  return parts.join(',')
+/** The files `node`'s declared outputs match on disk now, workspace-relative and sorted. */
+async function outputsLeft(
+  node: TaskNode,
+  workspaceRoot: string,
+  nestedProjectDirs: string[],
+): Promise<string[]> {
+  const declared = node.config.cache?.outputs
+  if (declared === undefined) return []
+  const [own, ws] = await Promise.all([
+    resolveOutputs({ projectDir: node.projectDir, outputs: declared.files, nestedProjectDirs }),
+    resolveWorkspaceOutputs({ workspaceRoot, outputs: declared.workspaceFiles ?? [] }),
+  ])
+  return [...new Set([...own, ...ws].map((p) => relPosix(workspaceRoot, p)))].sort()
 }
 
 /**
@@ -405,11 +414,11 @@ async function runOnBus(
   // per cycle under `vx watch`. A plugin whose own setup threw set up
   // nothing, and is the one left out.
   let tornDown = false
-  const teardown = async (except?: unknown): Promise<void> => {
+  const teardown = async (except?: unknown, report?: RunReport): Promise<void> => {
     if (tornDown) return
     tornDown = true
     const plugins = prepared.plugins.filter((p) => p !== except)
-    await teardownPlugins(plugins, (m) => log.status(m))
+    await teardownPlugins(plugins, (m) => log.status(m), report)
   }
   // A task whose command re-enters `vx run` in the workspace running it
   // is refused. When the inner run reaches this task again it forks a run
@@ -437,7 +446,7 @@ async function runOnBus(
   // A refusal is the caller's to print (on stderr, as `vx run:`): as a
   // status line it went to stdout, into whatever a script piped there.
   if (prepared.unresolvedTasks.length > 0) {
-    const refused = `no projects declare task(s): ${prepared.unresolvedTasks.join(', ')}.${elsewhereHint(prepared.declaredElsewhere)}${didYouMean(prepared.unresolvedTasks, prepared.hintProjects, prepared.declaredElsewhere)}${await initHint(prepared)}`
+    const refused = `no projects declare task(s): ${prepared.unresolvedTasks.join(', ')}.${await unresolvedHint(prepared)}`
     await teardown()
     prepared.cache.close()
     return { ok: false, outcomes: [], refused }
@@ -467,6 +476,13 @@ async function runOnBus(
   // the plugin. A plugin without `setup` subscribes nothing.
   let disposePlugins: (() => void) | undefined
   let telemetry: TelemetryHandle | undefined
+  // One run-id per `vx run` invocation. Every task in the resulting graph
+  // carries it so analytics queries can group by invocation; plugins get it
+  // in their teardown's `RunReport`.
+  const runId = ulid()
+  const head = captureGitContext(prepared.workspaceRoot)
+  const ciContext = detectCi(process.env)
+  const keepRunLog = prepared.keepRunEntry !== undefined
   try {
     disposePlugins = await installPlugins({
       plugins: prepared.plugins,
@@ -474,6 +490,9 @@ async function runOnBus(
       workspaceRoot: prepared.workspaceRoot,
       cacheDir: prepared.cacheDir,
       warn: (m) => log.status(m),
+      cache: prepared.cacheFor,
+      ci: ciContext.ci,
+      branch: prepared.branch(),
     })
   } catch (err) {
     disposePlugins?.()
@@ -735,9 +754,6 @@ async function runOnBus(
     }),
   )
   try {
-    // One run-id per `vx run` invocation. Every task in the resulting
-    // graph carries it so analytics queries can group by invocation.
-    const runId = ulid()
     const runStartHrTimeNs = process.hrtime.bigint()
     const endedAtMsAtStart = Date.now()
     const remoteCacheEnabled = prepared.hasRemoteLayer
@@ -768,10 +784,10 @@ async function runOnBus(
     // second status spawn.
     // `run.branch` names the branch over git's (`prepared.branch`).
     const gitContext = {
-      ...captureGitContext(workspaceRoot, gitFilesCache.worktreeDirty),
+      ...head,
+      dirty: gitFilesCache.worktreeDirty,
       branch: prepared.branch(),
     }
-    const ciContext = detectCi(process.env)
     const hostContext = captureHostContext()
 
     // The canonical run-context record — the same git/CI/host data the
@@ -809,7 +825,7 @@ async function runOnBus(
           invocationCommand(options.command?.split(' ') ?? process.argv.slice(1)),
         ),
         requestedTasks: [...options.tasks],
-        cachePolicy: compactCachePolicy(policy),
+        cachePolicy: formatCachePolicy(policy),
         concurrency,
         flow: options.flow ?? null,
         commitSha: gitContext.commitSha,
@@ -912,6 +928,13 @@ async function runOnBus(
       version: VERSION,
       packageCount: packagesInScope.size,
       remoteCacheEnabled,
+      cache: {
+        local: policy.localRead || policy.localWrite,
+        localWrite: policy.localWrite,
+        remote: remoteCacheEnabled && (policy.remoteRead || policy.remoteWrite),
+        uploads: prepared.localCache.uploads,
+        notDownloaded: () => deferredOutputs.pending().length,
+      },
       concurrency,
       workspaceProjectCount,
     }
@@ -1107,6 +1130,7 @@ async function runOnBus(
       if (upfrontKey !== undefined) a.upfrontKey = upfrontKey
       if (upfrontGroupKey !== undefined) a.upfrontGroupKey = upfrontGroupKey
       if (tainted) a.taintedUpstream = true
+      if (keepRunLog) a.keepRunLog = true
       if (!dependedOn.has(node.id)) a.noDependants = true
       if (holders.has(node.id)) a.terminal = true
       if (armSandbox !== undefined) a.armSandbox = armSandbox
@@ -1324,7 +1348,7 @@ async function runOnBus(
     const stillDeferred = deferredOutputs.pending()
     if (stillDeferred.length > 0) {
       log.status(
-        `  Deferred: ${stillDeferred.length} task(s) left outputs remote (--cache-download=none): ${stillDeferred.join(', ')}`,
+        `  Deferred: left outputs remote (--cache-download=none): ${stillDeferred.join(', ')}`,
       )
     }
 
@@ -1332,6 +1356,55 @@ async function runOnBus(
     // change the run's exit code — the run already happened.
     // Written again after the keep-alive wait: a kept server's crash or a
     // Ctrl-C there is the process's exit, and the first write said ok.
+    // The run's own bytes, kept in a remote that takes its writes (owner
+    // 2026-10-15): a failed task's log and the files its outputs left, an
+    // uncached task's log. Then the report every plugin's teardown reads.
+    const keepRunBytes = async (final: readonly TaskOutcome[]): Promise<RunReport> => {
+      const keep = prepared.keepRunEntry
+      const tasks: RunReportTask[] = []
+      const work: (() => Promise<void>)[] = []
+      for (const o of final) {
+        if (isGroupTask(o.node)) continue
+        const task: { -readonly [K in keyof RunReportTask]: RunReportTask[K] } = {
+          id: o.node.id,
+          status: o.status,
+          durationMs: Math.round(o.durationMs),
+          ...(o.hash !== undefined ? { key: o.hash } : {}),
+        }
+        tasks.push(task)
+        if (keep === undefined) continue
+        const runLog = o.runLog
+        if (runLog !== undefined) {
+          work.push(async () => {
+            const text = decodeOutputLog(runLog)
+              .map((c) => c.text)
+              .join('')
+            if (text.length === 0) return
+            const name = runEntryName(runId, o.node.id, 'log')
+            if (await keep(name, new TextEncoder().encode(text))) task.log = name
+          })
+        }
+        if (o.status === 'failed' && o.where === undefined) {
+          work.push(async () => {
+            const bytes = await packRunOutputs(
+              prepared.workspaceRoot,
+              await outputsLeft(
+                o.node,
+                prepared.workspaceRoot,
+                prepared.nestedDirsByProject.get(o.node.projectName) ?? [],
+              ),
+            )
+            if (bytes === null) return
+            const name = runEntryName(runId, o.node.id, 'outputs')
+            if (await keep(name, bytes)) task.outputs = name
+          })
+        }
+      }
+      for (let i = 0; i < work.length; i += 8) {
+        await Promise.all(work.slice(i, i + 8).map((w) => w()))
+      }
+      return { runId, commit: head.commitSha, ciRun: ciContext, ok, tasks }
+    }
     let json: RunSummaryJson | undefined
     const summarize = async (runOk: boolean, final = list): Promise<void> => {
       if (options.json === true) {
@@ -1405,7 +1478,7 @@ async function runOnBus(
         // own output masks it, so cache.db holds no plaintext value.
         command: maskInvocation(options.command ?? process.argv.slice(1).join(' ')),
         requestedTasks: options.tasks,
-        cachePolicy: compactCachePolicy(policy),
+        cachePolicy: formatCachePolicy(policy),
         concurrency,
         flow: options.flow ?? null,
         forwardArgs: options.forwardArgs,
@@ -1470,6 +1543,7 @@ async function runOnBus(
     // drain of the lane stood here until item 634; deleting it changed
     // nothing the suite could see, because this gate is the rule.
     await cache.drainUploads?.()
+    const report = await keepRunBytes(list)
     // Hand the per-run summary to the telemetry sinks + drain them. Only
     // when a sink is active (telemetry !== undefined) — otherwise this
     // whole block is skipped and the run is byte-identical to before.
@@ -1528,7 +1602,7 @@ async function runOnBus(
     // whole keep-alive wait below (C-66). Idempotent; the finally's stay.
     disposePlugins?.()
     telemetry?.dispose()
-    await teardown()
+    await teardown(undefined, report)
     await closeCache()
     mark('close')
     printTimings()
@@ -1761,7 +1835,7 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
       return {
         tasks: [],
         unresolvedTasks: prepared.unresolvedTasks,
-        unresolvedHint: `${elsewhereHint(prepared.declaredElsewhere)}${didYouMean(prepared.unresolvedTasks, prepared.hintProjects, prepared.declaredElsewhere)}${await initHint(prepared)}`,
+        unresolvedHint: await unresolvedHint(prepared),
       }
     }
     if (prepared.empty === 'no-tasks-declared' && prepared.declaredElsewhere.length > 0) {
@@ -1865,6 +1939,31 @@ function elsewhereHint(names: readonly string[]): string {
   return ` Only projects outside the selection declare ${names.join(', ')} — pass --all, or --filter to pick them.`
 }
 
+/**
+ * What follows "no projects declare task(s): …": where the name is, its
+ * nearest spelling, and, with neither, the lock a run reads its configs
+ * from: a task just added to a vx.config is not in it until `vx lock`.
+ */
+async function unresolvedHint(prepared: {
+  unresolvedTasks: readonly string[]
+  hintProjects: ReadonlyMap<string, ProjectEntry>
+  declaredElsewhere: readonly string[]
+  anyProjectConfig: boolean
+}): Promise<string> {
+  const elsewhere = elsewhereHint(prepared.declaredElsewhere)
+  const near = didYouMean(
+    prepared.unresolvedTasks,
+    prepared.hintProjects,
+    prepared.declaredElsewhere,
+  )
+  const init = await initHint(prepared)
+  const lock =
+    init === '' && elsewhere === '' && !near.startsWith(' Did you mean')
+      ? ' A run reads the lock: after editing a vx.config, run `vx lock`.'
+      : ''
+  return `${elsewhere}${near}${init}${lock}`
+}
+
 /**
  * The first-run case, told apart from a typo: no project in the workspace
  * has a `vx.config.*` at all, so no name could have resolved. Reached only

package/src/orchestrator/status-line.ts

@@ -5,7 +5,7 @@
 // ordinary write erases the status display first, writes its content,
 // then redraws, so the display can never interleave with task output.
 
-import { paint, type ColorSupport } from './colors.js'
+import { paint, type ColorSupport } from '../util/index.js'
 import { formatTaskRow, paintIdParts, TIME_COL } from './framed-output.js'
 
 const NO_COLOR: ColorSupport = { enabled: false }

package/src/orchestrator/summary.ts

@@ -4,57 +4,31 @@
 // aren't real work and would inflate "N total" misleadingly.
 
 import type { TaskOutcome } from '../graph/index.js'
-import { paint, type ColorSupport } from './colors.js'
 import { tallyOutcomes } from './tally.js'
 import { isCacheHit } from './telemetry.js'
 import { outcomeLabel, projectOutcome, ranNoCache } from './events.js'
 import { isGroupTask } from '../graph/index.js'
-import { formatElapsed } from '../util/index.js'
+import {
+  ERROR,
+  formatElapsed,
+  gradientRule,
+  paint,
+  SUCCESS,
+  WARN,
+  type ColorSupport,
+} from '../util/index.js'
 
 const NO_COLOR: ColorSupport = { enabled: false }
 
-const SUCCESS = '#22c55e'
-const WARN = '#eab308'
 // Cache provenance hues (owner): local light blue, remote dark blue —
 // yellow is skipped's color on both meters.
 const LOCAL = '#38bdf8' // sky-400
 const REMOTE = '#2563eb' // blue-600
-const ERROR = '#ef4444'
 const ABORTED = '#f97316' // orange-500: red's neighbour, not a failure
 const NOT_RUN = '#a855f7' // purple-500: stopped before it began, apart from every other state
 const ACCENT = '#06b6d4' // cyan-500: the live region's running word
 
 const BAR_WIDTH = 50
-// Brand gradient for the rule: identity violet → pink (the project /
-// task hues), faded across the dash run. Plain dashes when colors
-// are off.
-const GRADIENT_FROM = [0xa7, 0x8b, 0xfa] as const
-const GRADIENT_TO = [0xf4, 0x72, 0xb6] as const
-// Rule ends flush with the bars: 2 indent + 8 label + 2 gap + 50 cells.
-const RULE_DASHES = 57
-
-/** Total visible rule width: `\u2500 <mark> ` + dashes. Shared by summary + header. */
-function gradientRule(colors: ColorSupport, mark = 'vx'): string {
-  const head = `\u2500 `
-  const dashes = '\u2500'.repeat(Math.max(8, RULE_DASHES + 2 - mark.length))
-  if (!colors.enabled) return `${head}${mark} ${dashes}`
-  const chunks = 8
-  const per = Math.ceil(RULE_DASHES / chunks)
-  let out = ''
-  for (let i = 0; i < chunks; i++) {
-    const seg = dashes.slice(i * per, (i + 1) * per)
-    if (seg.length === 0) break
-    const f = i / (chunks - 1)
-    const hex = `#${GRADIENT_FROM.map((c, j) =>
-      Math.round(c + (GRADIENT_TO[j]! - c) * f)
-        .toString(16)
-        .padStart(2, '0'),
-    ).join('')}`
-    out += paint(hex, seg, colors)
-  }
-  return `${paint(`#${GRADIENT_FROM.map((c) => c.toString(16).padStart(2, '0')).join('')}`, head, colors)}${paint('', mark, colors, { bold: true })} ${out}`
-}
-
 /**
  * Stacked state meter: one ▰ run per bucket, proportional cells via
  * largest-remainder, every non-zero bucket guaranteed at least one
@@ -111,6 +85,10 @@ export interface SummaryStats {
   upToDate: number
   restoredLocal: number
   restoredRemote: number
+  /** Ran here and saved to the cache: the legend's `↑`. */
+  saved?: number
+  /** Ran here with a `cache` block, succeeded, and saved nothing. */
+  notSaved?: number
   /** Tasks that executed (success + failed) with a `cache` block — the misses. */
   miss: number
   /** Executed with no `cache` block: never consulted the cache, not a miss. */
@@ -143,6 +121,21 @@ export interface RunContext {
   /** Worker-pool size for this run; shown on the `info` row. */
   concurrency?: number
   remoteCacheEnabled: boolean
+  /**
+   * The cache layers the run used, so the legend reads `local 1= 2↓ 4↑ ·
+   * remote 3↓ 4↑`. Absent: the plain `N miss` legend.
+   */
+  cache?: {
+    /** The run's policy reads or writes the local layer. */
+    local: boolean
+    localWrite: boolean
+    /** A remote layer exists and the policy reads or writes it. */
+    remote: boolean
+    /** The run's uploads, filled as each lands (a live ref). */
+    uploads: { count: number; failed: number }
+    /** Tasks whose outputs are still in the remote store. */
+    notDownloaded: () => number
+  }
   /** Total projects discovery found — the bar's denominator. */
   workspaceProjectCount?: number
 }
@@ -234,8 +227,8 @@ export function formatSummarySection(
     if (taskParts.length > 0) lines.push(legend(taskParts))
   }
 
-  // Cache meter + numbers, fixed order: miss · up-to-date · local ·
-  // remote.
+  // Cache meter + numbers: per layer when the run context names its
+  // layers, else miss · no-cache · up-to-date · local · remote.
   if (miss + noCache + hits + left + stats.skipped > 0) {
     const cacheBar = segmentBar(
       [
@@ -250,13 +243,38 @@ export function formatSummarySection(
       colors,
     )
     const cacheParts: string[] = []
-    if (miss > 0) cacheParts.push(paint(ERROR, `${miss} miss`, colors))
-    if (noCache > 0) cacheParts.push(paint('', `${noCache} no-cache`, colors, { dim: true }))
-    if (stats.upToDate > 0) cacheParts.push(paint(SUCCESS, `${stats.upToDate} up-to-date`, colors))
-    if (stats.restoredLocal > 0)
-      cacheParts.push(paint(LOCAL, `${stats.restoredLocal} local`, colors))
-    if (stats.restoredRemote > 0)
-      cacheParts.push(paint(REMOTE, `${stats.restoredRemote} remote`, colors))
+    const layers = context?.cache
+    if (layers !== undefined) {
+      // Per layer (M, 2026-10-15): `●` fresh (outputs already on disk, from
+      // either layer) and `○` no cache, both local; `↓` restored from a
+      // layer, `↑` saved to it.
+      const n = (count: number, glyph: string): string[] => (count > 0 ? [`${count}${glyph}`] : [])
+      const local = [
+        ...(layers.local ? n(stats.upToDate, '\u25cf') : []),
+        ...n(noCache, '\u25cb'),
+        ...(layers.local ? n(stats.restoredLocal, '\u2193') : []),
+        ...(layers.localWrite ? n(stats.saved ?? 0, '\u2191') : []),
+      ]
+      if (local.length > 0) cacheParts.push(paint(LOCAL, `local ${local.join(' ')}`, colors))
+      const remote = [...n(stats.restoredRemote, '\u2193'), ...n(layers.uploads.count, '\u2191')]
+      if (layers.remote && remote.length > 0)
+        cacheParts.push(paint(REMOTE, `remote ${remote.join(' ')}`, colors))
+      if (layers.uploads.failed > 0)
+        cacheParts.push(paint(ERROR, `${layers.uploads.failed} \u2191 failed`, colors))
+      if ((stats.notSaved ?? 0) > 0)
+        cacheParts.push(paint(WARN, `${stats.notSaved} not saved`, colors))
+      const notDownloaded = layers.notDownloaded()
+      if (notDownloaded > 0) cacheParts.push(paint(WARN, `${notDownloaded} not downloaded`, colors))
+    } else {
+      if (miss > 0) cacheParts.push(paint(ERROR, `${miss} miss`, colors))
+      if (noCache > 0) cacheParts.push(paint('', `${noCache} no-cache`, colors, { dim: true }))
+      if (stats.upToDate > 0)
+        cacheParts.push(paint(SUCCESS, `${stats.upToDate} up-to-date`, colors))
+      if (stats.restoredLocal > 0)
+        cacheParts.push(paint(LOCAL, `${stats.restoredLocal} local`, colors))
+      if (stats.restoredRemote > 0)
+        cacheParts.push(paint(REMOTE, `${stats.restoredRemote} remote`, colors))
+    }
     // Skipped tasks ride the bar, yellow like the tasks meter, so the two
     // bars fill alike; their count is the tasks legend's alone (the footer
     // never says a fact twice, M, 2026-10-14).
@@ -364,6 +382,11 @@ export function formatOutcomeTable(outcomes: readonly TaskOutcome[]): string[] {
 
 // Local byte formatter — the orchestrator can't import cli/format.ts
 // (module boundary), and the footer only needs one compact form.
+/** Ran here with a `cache` block, succeeded, and its result was not saved. */
+export function ranUnsaved(o: TaskOutcome): boolean {
+  return o.status === 'success' && !ranNoCache(o) && o.saved !== true && o.where === undefined
+}
+
 export function formatRunSummary(
   outcomes: readonly TaskOutcome[],
   totalMs: number,
@@ -402,6 +425,8 @@ export function formatRunSummary(
       upToDate: t.upToDate,
       restoredLocal: t.restoredLocal,
       restoredRemote: t.restoredRemote,
+      saved: outcomes.filter((o) => o.saved === true && !isGroupTask(o.node)).length,
+      notSaved: outcomes.filter((o) => !isGroupTask(o.node) && ranUnsaved(o)).length,
       miss: t.total - t.skipped - (t.cachedLocal + t.cachedRemote) - noCache,
       noCache,
       savedMs,

package/src/orchestrator/telemetry.ts

@@ -117,7 +117,7 @@ export interface RunContextRecord {
   /** The invocation command line (process.argv-derived), what follows `--` counted, not quoted. */
   command: string
   requestedTasks: readonly string[]
-  /** Compact cache-policy flags, e.g. `'lR,lW,rR,rW'`. */
+  /** The `--cache-policy` spec, e.g. `'local:rw,remote:r'`. */
   cachePolicy: string
   concurrency: number
   flow: 'focused' | 'broad' | null

package/src/settings.ts

@@ -36,6 +36,8 @@ export interface Setting {
   readonly task?: string
   /** False: read before `.vx/workspace` loads, so flag and env only. */
   readonly config?: false
+  /** False: `.vx/workspace` only, no variable. */
+  readonly env?: false
 }
 
 const SCHEDULES = ['most-work', 'critical-path', 'direct-dependents', 'ready-order'] as const
@@ -193,6 +195,7 @@ export const SETTINGS: readonly Setting[] = [
     default: 'true',
     doc: "Remove a task's declared outputs before it runs on a miss, for tasks without their own.",
     task: 'cache.outputs.clean',
+    env: false,
   },
   {
     path: 'lock.reviewFiles',
@@ -221,6 +224,13 @@ export const SETTINGS: readonly Setting[] = [
     doc: "Print the run's stage timings to stderr.",
     config: false,
   },
+  {
+    path: 'debug.watch',
+    kind: { type: 'bool' },
+    default: 'false',
+    doc: '`vx watch`: say on stderr each time the loop arms, with the projects it watches.',
+    config: false,
+  },
   {
     path: 'debug.dumpable',
     kind: { type: 'bool' },
@@ -356,7 +366,8 @@ export function settingRefusal(
 
 /** A setting's environment value, parsed; undefined when unset or empty. */
 export function settingEnv(path: string, env: NodeJS.ProcessEnv = process.env): unknown {
-  const { kind } = setting(path)
+  const { kind, env: read } = setting(path)
+  if (read === false) return undefined
   const name = envName(path)
   const raw = env[name]
   if (raw === undefined || raw === '') return undefined

package/src/{orchestrator → util}/colors.ts

@@ -13,6 +13,11 @@ const RESET = '\x1b[0m'
 const BOLD = '\x1b[1m'
 const DIM = '\x1b[2m'
 
+// State hues every report shares with the run summary.
+export const SUCCESS = '#22c55e'
+export const WARN = '#eab308'
+export const ERROR = '#ef4444'
+
 export interface ColorSupport {
   enabled: boolean
 }

package/src/util/config-frame.ts

@@ -7,8 +7,9 @@
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
 
-// `<file>: tasks.<path>[:] …`, or a top-level `<file> has unknown field …`.
-const HEAD = /^(\/[^\n]*?\/vx\.config\.[cm]?[jt]s)(?:: (tasks\.[^\s:]+)(:?))? /
+// `<file>: tasks.<path>[:] …`, or a top-level `<file> has unknown field …`,
+// from a project's vx.config or the workspace's .vx/workspace.ts.
+const HEAD = /^(\/[^\n]*?\/(?:vx\.config|\.vx\/workspace)\.[cm]?[jt]s)(?:: (tasks\.[^\s:]+)(:?))? /
 
 /**
  * The message with its file named at `line:col`, relative to `cwd`, and a
@@ -88,3 +89,31 @@ function locate(
 function escapeRe(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
+
+/** A config refusal laid out for `ui.notice`: where, what, the allowed set, the fix, the frame. */
+export interface ConfigRefusal {
+  where: string
+  problem: string
+  allowed?: string
+  fix?: string
+  frame: string
+}
+
+/** `configErrorFrame`'s answer in parts, or undefined when it has none. */
+export function configRefusal(message: string, cwd: string): ConfigRefusal | undefined {
+  const framed = configErrorFrame(message, cwd)
+  if (framed === undefined) return undefined
+  const cut = framed.indexOf('\n\n')
+  const line = framed.slice(0, cut)
+  const frame = framed.slice(cut + 2)
+  const at = /^(\S+?:\d+:\d+):? (.*)$/s.exec(line)
+  if (at === null) return { where: line, problem: '', frame }
+  const said = /^(.*?)(?: \(allowed: ([^)]*)\))?(?: — did you mean ([^?]+)\?)?$/s.exec(at[2]!)!
+  return {
+    where: at[1]!,
+    problem: said[1]!.replace(/^has /, ''),
+    ...(said[2] !== undefined ? { allowed: said[2] } : {}),
+    ...(said[3] !== undefined ? { fix: `use ${said[3]}` } : {}),
+    frame,
+  }
+}

package/src/util/errors.ts

@@ -13,6 +13,8 @@ export class UserError extends Error {
    * does not. `VX_E_REFUSED` is any refusal without a code of its own.
    */
   readonly code: string
+  /** The refusal laid out for a terminal (`refusal`); the message is the same in one line. */
+  parts?: RefusalParts
   // Two signatures, not an optional parameter: the package-api record
   // keeps the one-argument form every plugin already calls.
   constructor(message: string)
@@ -24,6 +26,36 @@ export class UserError extends Error {
   }
 }
 
+/** A refusal in parts, as `ui.notice` draws it: one fact a line, why, and the fix. */
+export interface RefusalParts {
+  /** `info`: nothing is wrong, there is just nothing to show yet. Default `error`. */
+  readonly tone?: 'info'
+  readonly headline: string
+  readonly what?: readonly string[]
+  readonly why?: string
+  readonly fix?: string
+}
+
+/**
+ * A UserError whose terminal form is `parts`. Its message, what JSON and
+ * logs carry, is `message` when given, else the parts in one line.
+ */
+export function refusal(
+  parts: RefusalParts,
+  opts: { code?: string; message?: string } = {},
+): UserError {
+  const message =
+    opts.message ??
+    [
+      [parts.headline, ...(parts.what ?? [])].join(': '),
+      ...(parts.why !== undefined ? [parts.why] : []),
+      ...(parts.fix !== undefined ? [parts.fix] : []),
+    ].join('; ')
+  const err = new UserError(message, opts.code ?? 'VX_E_REFUSED')
+  err.parts = parts
+  return err
+}
+
 // A refusal that opens with the config that caused it: the schema's
 // `<file>: tasks.<name> …` and the loader's `<file> has unknown field …`.
 const CONFIG_REFUSAL = /^\/\S*\/(?:vx\.config|\.vx\/workspace)\.[cm]?[jt]s\b/

package/src/util/index.ts

@@ -13,6 +13,8 @@ export {
   isPermissionError,
   isUserError,
   PERMISSION_HINT,
+  refusal,
+  type RefusalParts,
   UserError,
   gitSpawnRefusal,
   isExecutableMissing,
@@ -21,7 +23,12 @@ export {
   OUT_OF_FDS_HINT,
   wantsJson,
 } from './errors.js'
-export { configErrorFrame } from './config-frame.js'
+export { configErrorFrame, configRefusal } from './config-frame.js'
+export { detectColors, ERROR, paint, SUCCESS, WARN, type ColorSupport } from './colors.js'
+export { gradientRule } from './report.js'
+import * as ui from './ui.js'
+export { refusalNotice, sayLine, sayNotice } from './refusal-notice.js'
+export { ui }
 export { xxh3, xxh3hex } from './hash.js'
 export {
   beginRun,