@vzn/vx 0.0.637 → 0.0.639

package/src/{orchestrator → report}/status-line.ts

@@ -5,14 +5,16 @@
 // 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 { dumbTerminal, paint, type ColorSupport } from '../util/index.js'
 import { formatTaskRow, paintIdParts, TIME_COL } from './framed-output.js'
+import type { BlockedTask } from './forecast.js'
 
 const NO_COLOR: ColorSupport = { enabled: false }
 // Same palette as framed-output.ts so glyphs and stats agree.
 const ACCENT = '#06b6d4'
 const ERROR = '#ef4444'
 const WARN = '#eab308' // yellow-500, as the summary's
+const SUCCESS = '#22c55e'
 
 /** Erase the current line and return the cursor to column 0. */
 const CLEAR = '\x1b[2K\r'
@@ -35,6 +37,11 @@ export interface OutputWriter {
   readonly enabled: boolean
   /** Serialized content write: erase status → content → redraw. */
   write(chunk: string): void
+  /**
+   * The same, to another stream on the same terminal (stderr): the region
+   * on this one is erased first and redrawn after.
+   */
+  writeTo(target: StatusStream, chunk: string): void
   /**
    * Replace the status line's content. Redraws are throttled to
    * `minRedrawMs` unless `force` (task start/finish) is set.
@@ -79,7 +86,7 @@ export function createOutputWriter(
   stream: StatusStream,
   opts: OutputWriterOptions = {},
 ): OutputWriter {
-  const enabled = (opts.enabled ?? true) && stream.isTTY === true
+  const enabled = (opts.enabled ?? true) && stream.isTTY === true && !dumbTerminal()
   const minRedrawMs = opts.minRedrawMs ?? 100
   const forceFloorMs = opts.forceFloorMs ?? 30
   const now = opts.now ?? Date.now
@@ -236,6 +243,22 @@ export function createOutputWriter(
       if (chunk.length > 0) atLineStart = chunk.endsWith('\n')
       if (!dead && current !== null && atLineStart) draw()
     },
+    writeTo(target, chunk) {
+      if (target === stream) return this.write(chunk)
+      // Held stdout is older than this chunk.
+      flushHeld()
+      if (!enabled) {
+        target.write(chunk)
+        return
+      }
+      if (shown) {
+        stream.write(eraseSeq())
+        shown = false
+        shownRows = 0
+      }
+      target.write(chunk)
+      if (!dead && current !== null && atLineStart) draw()
+    },
     setStatus(line, o = {}) {
       set([line], o)
     },
@@ -283,8 +306,15 @@ export interface StatusRegionState {
   pinnedPersistent: readonly string[]
   /** Fixed-size slot array; null = idle worker. Index = display row. */
   slots: readonly (WorkerSlot | null)[]
+  /** The blocked task an idle slot's row holds instead of `idle`, by the same index. */
+  blocked?: readonly (BlockedTask | null)[]
   /** Running tasks beyond the displayed slots. */
   overflow: number
+  /**
+   * vx's own steps still running, shown below the worker rows: no worker
+   * slot or `--concurrency` bounds them (M, 2026-10-15).
+   */
+  steps?: readonly WorkerSlot[]
   /** Clock value used for per-slot elapsed (injectable for tests). */
   nowMs: number
   /**
@@ -299,8 +329,12 @@ export interface StatusRegionState {
 /** Identity-colored id, full (never truncated) — name is the last column. */
 function paintPinnedId(id: string, colors: ColorSupport): string {
   const sep = id.indexOf('#')
-  if (sep < 0) return id
-  return paintIdParts(id.slice(0, sep), id.slice(0, sep), id.slice(sep + 1), colors)
+  if (sep >= 0) return paintIdParts(id.slice(0, sep), id.slice(0, sep), id.slice(sep + 1), colors)
+  // One of vx's own steps: `<owner>:<step>`, painted as a task id is.
+  const step = id.lastIndexOf(':')
+  if (step < 0) return id
+  const owner = id.slice(0, step)
+  return paintIdParts(owner, owner, id.slice(step + 1), colors, { sep: ':' })
 }
 
 /**
@@ -327,6 +361,28 @@ export function formatFailureLine(
   )
 }
 
+/**
+ * The list row of one of vx's own steps (`vx:uploads`), on the task grid
+ * with no cache column: a step is no task and caches nothing.
+ */
+export function formatStepLine(
+  id: string,
+  durationMs: number,
+  ok: boolean,
+  colors: ColorSupport = NO_COLOR,
+): string {
+  return formatTaskRow(
+    ok ? paint(SUCCESS, '\u23fa\uFE0E', colors) : paint(ERROR, '\u25fc\uFE0E', colors),
+    durationMs,
+    ok ? 'success' : 'failed',
+    ok ? SUCCESS : ERROR,
+    '',
+    '',
+    paintPinnedId(id, colors),
+    colors,
+  )
+}
+
 /**
  * Worker region: pinned ready persistent tasks, one row per worker
  * slot — a task stays in its slot for its whole life so names never
@@ -363,12 +419,19 @@ export function formatStatusRegion(
   // Worker rows: NO glyph — the live elapsed time leads (no spinner;
   // the ticking time IS the motion), then `running`, full id (never
   // truncated — name is the last column). Idle rows hold their slot's
-  // place, dim, aligned under the status column.
+  // place, dim, aligned under the status column: the blocked task the row
+  // holds and what holds it back, else `idle`.
   // One task running has no path to compare against.
   const busy = s.slots.filter((x) => x !== null).length
-  for (const slot of s.slots) {
+  for (const [row, slot] of s.slots.entries()) {
     if (slot === null) {
-      lines.push(`${' '.repeat(3 + TIME_COL + 1)}${paint(IDLE, 'idle', colors, { dim: true })}`)
+      const w = s.blocked?.[row]
+      lines.push(
+        w == null
+          ? `${' '.repeat(3 + TIME_COL + 1)}${paint(IDLE, 'idle', colors, { dim: true })}`
+          : formatTaskRow(' ', null, 'blocked', '', '', '', paintPinnedId(w.id, colors), colors) +
+              `  ${dim(`by ${w.by}`)}`,
+      )
       continue
     }
     // What waits on it, after the id: the row to watch is the one the
@@ -394,6 +457,20 @@ export function formatStatusRegion(
   if (s.overflow > 0) {
     lines.push(dim(`\u2026 +${s.overflow} more running`))
   }
+  for (const step of s.steps ?? []) {
+    lines.push(
+      formatTaskRow(
+        ' ',
+        Math.max(0, s.nowMs - step.startedMs),
+        'running',
+        ACCENT,
+        '',
+        '',
+        paintPinnedId(step.id, colors),
+        colors,
+      ),
+    )
+  }
   // The live summary section — identical shape to the final printout,
   // so the region visually BECOMES the summary when the run ends.
   lines.push(...s.summaryLines)

package/src/{orchestrator → report}/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 { isCacheHit } from '../graph/index.js'
 import { outcomeLabel, projectOutcome, ranNoCache } from './events.js'
 import { isGroupTask } from '../graph/index.js'
-import { formatElapsed } from '../util/index.js'
+import {
+  barWidth,
+  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
@@ -67,9 +41,10 @@ function segmentBar(
 ): string {
   const total = segments.reduce((sum, seg) => sum + seg.n, 0)
   if (total === 0) return ''
-  const exact = segments.map((seg) => (seg.n / total) * BAR_WIDTH)
+  const width = barWidth(colors)
+  const exact = segments.map((seg) => (seg.n / total) * width)
   const cells = exact.map(Math.floor)
-  let leftover = BAR_WIDTH - cells.reduce((sum, c) => sum + c, 0)
+  let leftover = width - cells.reduce((sum, c) => sum + c, 0)
   const order = exact
     .map((e, i) => ({ i, frac: e - Math.floor(e) }))
     .sort((x, y) => y.frac - x.frac)
@@ -87,9 +62,12 @@ function segmentBar(
   }
   return segments
     .map((seg, i) =>
-      paint(seg.color, (seg.glyph ?? '\u25b0').repeat(cells[i]!), colors, {
-        ...(seg.dim === true ? { dim: true } : {}),
-      }),
+      // An empty segment paints nothing: no escape pair around no cell.
+      cells[i] === 0
+        ? ''
+        : paint(seg.color, (seg.glyph ?? '\u25b0').repeat(cells[i]!), colors, {
+            ...(seg.dim === true ? { dim: true } : {}),
+          }),
     )
     .join('')
 }
@@ -111,6 +89,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. */
@@ -128,6 +110,67 @@ export interface SummaryStats {
   savedMs?: number
   /** A run of groups only: their names, so `0 tasks` says why. */
   emptyGroups?: readonly string[]
+  /** Each finished task's cache bucket by its key, so its remote traffic can move it. */
+  buckets?: ReadonlyMap<string, CacheBucket>
+}
+
+/** The cache bar segment a finished task fills before its remote traffic is weighed. */
+export type CacheBucket =
+  | 'miss'
+  | 'noCache'
+  | 'upToDate'
+  | 'restoredLocal'
+  | 'restoredRemote'
+  | 'saved'
+
+/** A finished task's own cache bucket; none for a group, a skip or an abort. */
+export function cacheBucketOf(o: TaskOutcome): CacheBucket | undefined {
+  if (isGroupTask(o.node)) return undefined
+  switch (o.status) {
+    case 'success':
+      return ranNoCache(o) ? 'noCache' : o.saved === true ? 'saved' : 'miss'
+    case 'failed':
+      return ranNoCache(o) ? 'noCache' : 'miss'
+    case 'cache-hit':
+      return o.restored === false ? 'upToDate' : 'restoredLocal'
+    case 'cache-hit-remote':
+      return o.restored === false ? 'upToDate' : 'restoredRemote'
+    default:
+      return undefined
+  }
+}
+
+type Buckets = Record<CacheBucket | 'uploaded' | 'uploading' | 'remoteFailed', number>
+
+/**
+ * The cache bar's segments, each task in one (M, 2026-10-15). With layers
+ * named, a saved task leaves the misses, and a task with remote traffic
+ * leaves its own bucket for its strongest remote state: a failed read or
+ * write, then an upload still running, then one that landed. Without, the
+ * plain legend's buckets.
+ */
+function cacheBuckets(stats: SummaryStats, layers: RunContext['cache']): Buckets {
+  const saved = layers === undefined ? 0 : (stats.saved ?? 0)
+  const b: Buckets = {
+    miss: stats.miss - saved,
+    noCache: stats.noCache ?? 0,
+    upToDate: stats.upToDate,
+    restoredLocal: stats.restoredLocal,
+    restoredRemote: stats.restoredRemote,
+    saved,
+    uploaded: 0,
+    uploading: 0,
+    remoteFailed: 0,
+  }
+  if (layers?.remote !== true || stats.buckets === undefined) return b
+  for (const [hash, k] of layers.traffic.keys) {
+    const from = stats.buckets.get(hash)
+    // Still running: it counts once it ends.
+    if (from === undefined) continue
+    b[from]--
+    b[k.failures.length > 0 ? 'remoteFailed' : k.uploading > 0 ? 'uploading' : 'uploaded']++
+  }
+  return b
 }
 
 /**
@@ -138,11 +181,30 @@ export interface SummaryStats {
  */
 export interface RunContext {
   version: string
-  /** Projects covered by the graph — the "affected" half of the bar. */
+  /** Projects with a real task in the graph — the "affected" half of the bar. */
   packageCount: number
   /** 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 remote traffic per key, filled as it happens (a live ref). */
+    traffic: {
+      /** Uploads queued or running. */
+      readonly inFlight: number
+      readonly keys: ReadonlyMap<string, { uploading: number; failures: readonly string[] }>
+    }
+    /** Tasks whose outputs are still in the remote store. */
+    notDownloaded: () => number
+  }
   /** Total projects discovery found — the bar's denominator. */
   workspaceProjectCount?: number
 }
@@ -203,13 +265,14 @@ export function formatSummarySection(
   if (context !== undefined) {
     const wsTotal = context.workspaceProjectCount
     if (wsTotal !== undefined && wsTotal > 0) {
+      const width = barWidth(colors)
       const cells = Math.min(
-        BAR_WIDTH,
-        Math.max(1, Math.round((context.packageCount / wsTotal) * BAR_WIDTH)),
+        width,
+        Math.max(1, Math.round((context.packageCount / wsTotal) * width)),
       )
       const bar =
         paint(WARN, '▰'.repeat(cells), colors) +
-        paint('', '▱'.repeat(BAR_WIDTH - cells), colors, { dim: true })
+        paint('', '▱'.repeat(width - cells), colors, { dim: true })
       lines.push(
         row('projects', bar),
         legend([paint(WARN, `${context.packageCount} affected`, colors), dim(`${wsTotal} total`)]),
@@ -234,29 +297,65 @@ 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 layers = context?.cache
+    const b = cacheBuckets(stats, layers)
     const cacheBar = segmentBar(
       [
-        { n: miss, color: ERROR },
-        { n: noCache, color: '', dim: true },
-        { n: stats.upToDate, color: SUCCESS },
-        { n: stats.restoredLocal, color: LOCAL },
-        { n: stats.restoredRemote, color: REMOTE },
+        { n: b.miss, color: ERROR },
+        { n: b.noCache, color: '', dim: true },
+        { n: b.upToDate, color: SUCCESS },
+        { n: b.restoredLocal, color: LOCAL },
+        { n: b.saved, color: LOCAL },
+        { n: b.restoredRemote, color: REMOTE },
+        { n: b.uploaded, color: REMOTE },
+        { n: b.uploading, color: ACCENT },
+        { n: b.remoteFailed, color: ERROR },
         { n: stats.skipped, color: WARN },
         remainder,
       ],
       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))
+    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; `✗` a remote read or write failed, `⇡` still
+      // uploading. Each count is its bar segment's, glyph and number in its colour.
+      const n = (count: number, glyph: string, color: string, dim = false): string[] =>
+        count > 0 ? [paint(color, `${count}${glyph}`, colors, dim ? { dim: true } : {})] : []
+      const local = [
+        ...(layers.local ? n(b.upToDate, '\u2713', SUCCESS) : []),
+        ...n(b.noCache, '\u2205', '', true),
+        ...(layers.local ? n(b.restoredLocal, '\u2193', LOCAL) : []),
+        ...(layers.localWrite ? n(b.saved, '\u2191', LOCAL) : []),
+      ]
+      // The layer words are dim; only the counts carry colour (M, 2026-10-15).
+      if (local.length > 0) cacheParts.push(`${dim('local')} ${local.join(' ')}`)
+      const remote = [
+        ...n(b.restoredRemote, '\u2193', REMOTE),
+        ...n(b.uploaded, '\u2191', REMOTE),
+        ...n(b.remoteFailed, '\u2717', ERROR),
+        ...n(b.uploading, '\u21e1', ACCENT),
+      ]
+      if (layers.remote && remote.length > 0)
+        cacheParts.push(`${dim('remote')} ${remote.join(' ')}`)
+      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,15 +463,19 @@ 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,
   colors: ColorSupport = NO_COLOR,
   context?: RunContext,
 ): string[] {
-  // Counted here, not in the Tally: that object is the `--summarize` payload
-  // (ten documented fields) and a task with no `cache` block is a terminal
-  // distinction — it never consulted the cache, so it is not a miss.
+  // Counted here, not in the Tally: a task with no `cache` block never
+  // consulted the cache, so it is not a miss.
   const noCache = outcomes.filter(
     (o) =>
       !isGroupTask(o.node) && (o.status === 'success' || o.status === 'failed') && ranNoCache(o),
@@ -402,6 +505,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,
@@ -423,6 +528,7 @@ export function formatRunSummary(
           }
         : {}),
       ...(emptyGroups.length > 0 ? { emptyGroups } : {}),
+      buckets: bucketsOf(outcomes),
     },
     totalMs,
     colors,
@@ -430,6 +536,16 @@ export function formatRunSummary(
   )
 }
 
+/** Each finished task's cache bucket by its key. */
+function bucketsOf(outcomes: readonly TaskOutcome[]): Map<string, CacheBucket> {
+  const out = new Map<string, CacheBucket>()
+  for (const o of outcomes) {
+    const bucket = o.hash === undefined ? undefined : cacheBucketOf(o)
+    if (bucket !== undefined) out.set(o.hash!, bucket)
+  }
+  return out
+}
+
 /**
  * An `aborted` outcome the stop reached before dispatch. The scheduler gives
  * it an invented exit 1; only a started task carries a wall-clock start, so

package/src/report/tally.ts

@@ -0,0 +1,83 @@
+// Outcome tally for the end-of-run footer (`summary.ts`): the bucket rules,
+// group tasks excluded.
+
+import { isGroupTask, type TaskOutcome } from '../graph/index.js'
+
+export interface Tally {
+  successful: number
+  failed: number
+  skipped: number
+  cachedLocal: number
+  /** Hits that materialized files from the local artifact. */
+  restoredLocal: number
+  /** Hits that materialized files pulled from the remote layer. */
+  restoredRemote: number
+  /** Cache hits whose tree already matched — nothing was written. */
+  upToDate: number
+  cachedRemote: number
+  /**
+   * Killed by a shutdown signal. No work, so it joins no outcome bucket and
+   * not `total` — but it is counted, because it makes the run red: a red run
+   * whose every counted task succeeded is undiagnosable without this.
+   */
+  aborted: number
+  /** Tasks counted toward `total`. Group tasks are excluded by default. */
+  total: number
+}
+
+function emptyTally(): Tally {
+  return {
+    successful: 0,
+    failed: 0,
+    skipped: 0,
+    cachedLocal: 0,
+    restoredLocal: 0,
+    restoredRemote: 0,
+    upToDate: 0,
+    cachedRemote: 0,
+    aborted: 0,
+    total: 0,
+  }
+}
+
+/**
+ * Walk live outcomes and return a `Tally` — the single owner of the bucket
+ * rules.
+ *
+ * Group tasks (no `exec`) aren't real work; including them inflates the
+ * per-run "N total" count in ways that mislead ("3 of 4 cached" when one was
+ * a group that ran nothing).
+ *
+ * Status bucket rules:
+ *   `success`            → +successful
+ *   `cache-hit`          → +successful, +cachedLocal
+ *   `cache-hit-remote`   → +successful, +cachedRemote
+ *   `failed`             → +failed
+ *   `skipped`            → +skipped
+ *   `aborted`            → +aborted only (no bucket, no total)
+ */
+export function tallyOutcomes(outcomes: readonly TaskOutcome[]): Tally {
+  const t = emptyTally()
+  for (const o of outcomes) {
+    if (isGroupTask(o.node)) continue
+    if (o.status === 'aborted') {
+      t.aborted++
+      continue
+    }
+    t.total++
+    if (o.status === 'success') t.successful++
+    else if (o.status === 'cache-hit') {
+      t.successful++
+      t.cachedLocal++
+      if (o.restored === true) t.restoredLocal++
+      else t.upToDate++
+    } else if (o.status === 'cache-hit-remote') {
+      t.successful++
+      t.cachedRemote++
+      if (o.restored === true) t.restoredRemote++
+      else t.upToDate++
+    } else if (o.status === 'failed') t.failed++
+    else if (o.status === 'skipped') t.skipped++
+  }
+  return t
+}

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
@@ -100,27 +102,6 @@ export const SETTINGS: readonly Setting[] = [
     flag: { verb: 'run', name: '--output-logs' },
     config: false,
   },
-  {
-    path: 'run.killGrace',
-    kind: { type: 'duration', timer: true },
-    default: '2s',
-    doc: 'How long a task that ignores SIGTERM gets before SIGKILL.',
-    flag: { verb: 'run', name: '--kill-grace' },
-  },
-  {
-    path: 'run.teardownTimeout',
-    kind: { type: 'duration', timer: true, zero: true },
-    default: '3s',
-    doc: "The bound on each plugin's end-of-run flush and teardown.",
-    flag: { verb: 'run', name: '--teardown-timeout' },
-  },
-  {
-    path: 'run.readyNotice',
-    kind: { type: 'duration', timer: true },
-    default: '10s',
-    doc: 'How long a persistent task may take to match `readyWhen` before vx says it waits.',
-    flag: { verb: 'run', name: '--ready-notice' },
-  },
   {
     path: 'run.rules.exclusiveOutputs',
     kind: { type: 'bool' },
@@ -193,6 +174,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 +203,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' },
@@ -239,7 +228,7 @@ export function setting(path: string): Setting {
   return BY_PATH.get(path)!
 }
 
-/** `run.killGrace` → `VX_RUN_KILL_GRACE`. */
+/** `run.affectedBase` → `VX_RUN_AFFECTED_BASE`. */
 export function envName(path: string): string {
   return `VX_${path
     .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
@@ -356,7 +345,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