@vzn/vx 0.0.638 → 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 '../util/index.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

@@ -5,10 +5,11 @@
 
 import type { TaskOutcome } from '../graph/index.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 {
+  barWidth,
   ERROR,
   formatElapsed,
   gradientRule,
@@ -28,7 +29,6 @@ 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
 /**
  * Stacked state meter: one ▰ run per bucket, proportional cells via
  * largest-remainder, every non-zero bucket guaranteed at least one
@@ -41,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)
@@ -61,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('')
 }
@@ -106,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
 }
 
 /**
@@ -116,7 +181,7 @@ 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
@@ -131,8 +196,12 @@ export interface RunContext {
     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 }
+    /** 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
   }
@@ -196,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`)]),
@@ -230,37 +300,48 @@ export function formatSummarySection(
   // 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[] = []
-    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}`] : [])
+      // 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(stats.upToDate, '\u25cf') : []),
-        ...n(noCache, '\u25cb'),
-        ...(layers.local ? n(stats.restoredLocal, '\u2193') : []),
-        ...(layers.localWrite ? n(stats.saved ?? 0, '\u2191') : []),
+        ...(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 (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))
+        cacheParts.push(`${dim('remote')} ${remote.join(' ')}`)
       if ((stats.notSaved ?? 0) > 0)
         cacheParts.push(paint(WARN, `${stats.notSaved} not saved`, colors))
       const notDownloaded = layers.notDownloaded()
@@ -393,9 +474,8 @@ export function formatRunSummary(
   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),
@@ -448,6 +528,7 @@ export function formatRunSummary(
           }
         : {}),
       ...(emptyGroups.length > 0 ? { emptyGroups } : {}),
+      buckets: bucketsOf(outcomes),
     },
     totalMs,
     colors,
@@ -455,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

@@ -102,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' },
@@ -249,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')

package/src/util/colors.ts

@@ -20,6 +20,8 @@ export const ERROR = '#ef4444'
 
 export interface ColorSupport {
   enabled: boolean
+  /** The terminal's width, read live; none off a terminal. Bars and rules fit it. */
+  readonly columns?: number | undefined
 }
 
 export interface PaintOptions {
@@ -32,16 +34,32 @@ export interface PaintOptions {
  *   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.
+ *   else: on iff stdout is a TTY that is not `TERM=dumb`.
  * `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 }
   const force = process.env['FORCE_COLOR']
-  if (force !== undefined) return { enabled: force !== '0' && force !== 'false' }
-  return { enabled: stream.isTTY === true }
+  const enabled = process.env['NO_COLOR']
+    ? false
+    : force !== undefined
+      ? force !== '0' && force !== 'false'
+      : stream.isTTY === true && !dumbTerminal()
+  return {
+    enabled,
+    get columns() {
+      return stream.isTTY === true ? stream.columns : undefined
+    },
+  }
+}
+
+/**
+ * `TERM=dumb` (Emacs `M-x shell`, some CI log viewers) can neither paint
+ * nor move the cursor: vx prints to it as off a terminal.
+ */
+export function dumbTerminal(): boolean {
+  return process.env['TERM'] === 'dumb'
 }
 
 // Bun.color() is pure for a given (hex, mode) pair but does FFI work
@@ -71,3 +89,25 @@ export function paint(
   if (prefix.length === 0) return text
   return `${prefix}${text}${RESET}`
 }
+
+/**
+ * Identity hues for the two halves of a `project#task` id, never a status
+ * colour: one name, one hue, in every run, list and row (M, 2026-10-15:
+ * every `#build` matches every other `#build`).
+ */
+const IDENTITY_PALETTE = [
+  '#a78bfa', // violet-400
+  '#60a5fa', // blue-400
+  '#e879f9', // fuchsia-400
+  '#818cf8', // indigo-400
+  '#c084fc', // purple-400
+  '#93c5fd', // blue-300
+  '#f472b6', // pink-400
+] as const
+
+/** A project's or a target's hue: a fold of the name into the palette. */
+export function identityColor(name: string): string {
+  let h = 0
+  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0
+  return IDENTITY_PALETTE[h % IDENTITY_PALETTE.length]!
+}