@vzn/vx 0.0.651 → 0.0.653

package/src/report/summary.ts

@@ -6,7 +6,7 @@
 import type { TaskOutcome } from '../graph/index.js'
 import { tallyOutcomes } from './tally.js'
 import { outcomeLabel, projectOutcome, ranNoCache } from './events.js'
-import { isGroupTask } from '../graph/index.js'
+import { isGroupTask, isKeyFailed, markKeyFailed } from '../graph/index.js'
 import { formatBytes, formatElapsed } from '../util/index.js'
 import * as ui from '../ui/index.js'
 import {
@@ -62,12 +62,17 @@ export interface SummaryStats {
   restoredRemote: number
   /** Ran here and saved to the cache: the legend's `↑`. */
   saved?: number
-  /** Ran here with a `cache` block, succeeded, and saved nothing. */
+  /** Ran here with `cache: true`, succeeded, and saved nothing. */
   notSaved?: number
-  /** Tasks that executed (success + failed) with a `cache` block — the misses. */
+  /** Tasks that executed (success + failed) with `cache: true` — the misses. */
   miss: number
-  /** Executed with no `cache` block: never consulted the cache, not a miss. */
+  /** Executed without `cache: true`: never consulted the cache, not a miss. */
   noCache?: number
+  /**
+   * Failed hits whose restore threw: in no cache count, neither a miss nor
+   * a hit. They fill the cache bar as `failed` colours the tasks bar.
+   */
+  restoreFailed?: number
   /** Still to run (live section only; 0 in the final summary) — renders
    *  as a gray ▱ remainder so the live meters FILL toward the final. */
   left?: number
@@ -114,6 +119,8 @@ export function cacheBucketOf(o: TaskOutcome): CacheBucket | undefined {
             ? 'notSaved'
             : 'miss'
     case 'failed':
+      // A hit whose restore failed is in no bucket: not a miss, not a hit.
+      if (o.restoreFailed === true) return undefined
       return ranNoCache(o) ? 'noCache' : 'miss'
     case 'cache-hit':
       return o.restored === false ? 'upToDate' : 'restoredLocal'
@@ -237,6 +244,7 @@ export function formatSummarySection(
   const hits = stats.upToDate + stats.restoredLocal + stats.restoredRemote
   const miss = stats.miss
   const noCache = stats.noCache ?? 0
+  const restoreFailed = stats.restoreFailed ?? 0
   const left = stats.left ?? 0
   const aborted = stats.aborted ?? 0
   const notRun = stats.notRun ?? 0
@@ -264,7 +272,7 @@ export function formatSummarySection(
   if (stats.skipped > 0) taskParts.push(paint('warn', `${stats.skipped} skipped`, colors))
   if (aborted > 0) taskParts.push(paint('aborted', `${aborted} aborted`, colors))
   if (notRun > 0) taskParts.push(paint('notRun', `${notRun} not run`, colors))
-  if (running > 0) taskParts.push(paint('info', `${running} running`, colors))
+  if (running > 0) taskParts.push(paint('warn', `${running} running`, colors))
   if (scheduled > 0) taskParts.push(dim(`${scheduled} scheduled`))
   if (blocked > 0) taskParts.push(dim(`${blocked} blocked`))
   // What is not done yet, running included: the count the bar's unfilled part shows.
@@ -277,7 +285,7 @@ export function formatSummarySection(
       { n: stats.skipped, color: 'warn' },
       { n: aborted, color: 'aborted' },
       { n: notRun, color: 'notRun' },
-      { n: running, color: 'info' },
+      { n: running, color: 'warn' },
       { n: scheduled, color: 'muted', dim: true },
       { n: blocked, color: 'muted', dim: true },
       remainder,
@@ -329,7 +337,7 @@ 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) {
+  if (miss + noCache + hits + left + stats.skipped + restoreFailed > 0) {
     const layers = context?.cache
     const b = cacheBuckets(stats, layers)
     const cacheBar = segmentBar(
@@ -344,6 +352,7 @@ export function formatSummarySection(
         { n: b.uploaded, color: 'remote' },
         { n: b.uploading, color: 'info' },
         { n: b.remoteFailed, color: 'error' },
+        { n: restoreFailed, color: 'error' },
         { n: stats.skipped, color: 'warn' },
         remainder,
       ],
@@ -395,9 +404,9 @@ export function formatSummarySection(
       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, 2026-10-14).
+    // Skipped tasks ride the bar, yellow like the tasks meter, and failed
+    // restores red, so the two bars fill alike; their counts are the tasks
+    // legend's alone (the footer never says a fact twice, 2026-10-14).
     lines.push(row('cache', cacheBar))
     if (cacheParts.length > 0) lines.push(legend(cacheParts))
   }
@@ -478,7 +487,9 @@ export function formatSummarySection(
   }
   // The Summary panel; the final one names the vx that ran it (the live
   // one has no context yet).
+  // Two blank lines: the Summary stands apart from the task list above it.
   return [
+    '',
     '',
     panelTop(
       'Summary',
@@ -539,7 +550,9 @@ export function formatOutcomeTable(
     .filter((o) => !isGroupTask(o.node))
     .map((o) => {
       const v = projectOutcome(o)
-      const status = neverStarted(o) ? 'not run' : outcomeLabel(v)
+      const status = neverStarted(o)
+        ? 'not run'
+        : outcomeLabel(isKeyFailed(o) ? markKeyFailed(v) : v)
       return { o, task: v.taskId, status, duration: `${v.durationMs}ms` }
     })
   if (rows.length === 0) return []
@@ -582,9 +595,19 @@ function tableStatusColor(o: TaskOutcome): Style {
 
 // 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. */
+/**
+ * Ran here with `cache: true`, succeeded, and its result was not saved.
+ * Outputs left in the executor's store (`outputs: 'deferred'`) ran
+ * elsewhere, whether or not the executor names a `where`.
+ */
 export function ranUnsaved(o: TaskOutcome): boolean {
-  return o.status === 'success' && !ranNoCache(o) && o.saved !== true && o.where === undefined
+  return (
+    o.status === 'success' &&
+    !ranNoCache(o) &&
+    o.saved !== true &&
+    o.where === undefined &&
+    o.outputs !== 'deferred'
+  )
 }
 
 export function formatRunSummary(
@@ -593,17 +616,29 @@ export function formatRunSummary(
   colors: ColorSupport = NO_COLOR,
   context?: RunContext,
 ): string[] {
-  // Counted here, not in the Tally: a task with no `cache` block never
+  // Counted here, not in the Tally: a task without `cache: true` 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),
   ).length
+  const restoreFailed = outcomes.filter(
+    (o) => !isGroupTask(o.node) && o.status === 'failed' && o.restoreFailed === true,
+  ).length
+  // A task with no key asked no cache and ran nothing: not a miss.
+  const keyFailed = outcomes.filter(
+    (o) => !isGroupTask(o.node) && o.status === 'failed' && isKeyFailed(o),
+  ).length
   const t = tallyOutcomes(outcomes)
   // Spread over executed tasks only — `success`/`failed` statuses ran
-  // a command; cache-hit statuses replayed one.
+  // a command; cache-hit statuses replayed one, and a failed restore ran none.
   const durations = outcomes
-    .filter((o) => (o.status === 'success' || o.status === 'failed') && !isGroupTask(o.node))
+    .filter(
+      (o) =>
+        (o.status === 'success' ||
+          (o.status === 'failed' && o.restoreFailed !== true && !isKeyFailed(o))) &&
+        !isGroupTask(o.node),
+    )
     .map((o) => o.durationMs)
   const heldOutcomes = outcomes.filter((o) => o.admissionHeldMs !== undefined)
   const notRun = outcomes.filter((o) => neverStarted(o) && !isGroupTask(o.node)).length
@@ -623,8 +658,15 @@ export function formatRunSummary(
       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,
+      miss:
+        t.total -
+        t.skipped -
+        (t.cachedLocal + t.cachedRemote) -
+        noCache -
+        restoreFailed -
+        keyFailed,
       noCache,
+      ...(restoreFailed > 0 ? { restoreFailed } : {}),
       spread:
         durations.length > 0
           ? {
@@ -643,7 +685,8 @@ export function formatRunSummary(
           }
         : {}),
       ...(emptyGroups.length > 0 ? { emptyGroups } : {}),
-      buckets: bucketsOf(outcomes),
+      // Read only to move a task by its remote traffic.
+      ...(context?.cache?.remote === true ? { buckets: bucketsOf(outcomes) } : {}),
     },
     totalMs,
     colors,

package/src/settings.ts

@@ -118,7 +118,7 @@ export const SETTINGS: readonly Setting[] = [
   {
     path: 'cache.dir',
     kind: { type: 'string' },
-    default: '.vx/cache, entries in ~/.vx/<repo>/cache',
+    default: '.vx/cache, entries in ~/.vx/<id>/cache',
     doc: 'Where the cache lives, relative to the workspace root; named, it holds the whole cache.',
     flag: { verb: 'run', name: '--cache-dir' },
   },
@@ -165,25 +165,25 @@ export const SETTINGS: readonly Setting[] = [
     flag: { verb: 'run', name: '--cache-download' },
   },
   {
-    path: 'cache.inputStability.strategy',
+    path: 'inputs.stability.strategy',
     kind: { type: 'enum', values: ['immutable', 'mutable', 'unchecked'] },
     default: 'immutable',
     doc: 'What a write to an input during the command means for the save, for tasks without their own.',
-    task: 'cache.inputStability.strategy',
+    task: 'inputs.stability.strategy',
   },
   {
-    path: 'cache.inputStability.severity',
+    path: 'inputs.stability.severity',
     kind: { type: 'enum', values: ['warn', 'error'] },
     default: 'warn',
     doc: 'Whether a skipped save warns or fails the task, for tasks without their own.',
-    task: 'cache.inputStability.severity',
+    task: 'inputs.stability.severity',
   },
   {
-    path: 'cache.outputs.clean',
+    path: 'outputs.clean',
     kind: { type: 'bool' },
     default: 'true',
     doc: "Remove a task's declared outputs before it runs on a miss, for tasks without their own.",
-    task: 'cache.outputs.clean',
+    task: 'outputs.clean',
     env: false,
   },
   {
@@ -222,7 +222,7 @@ export const SETTINGS: readonly Setting[] = [
     path: 'config.workerTimeout',
     kind: { type: 'duration', timer: true },
     default: '30s',
-    doc: 'How long one config evaluation may take.',
+    doc: 'How long one config evaluation may await; at 5 s vx names the config still evaluating. A synchronous loop on the first load holds the thread the deadline needs, so it hangs until killed.',
     config: false,
   },
   {
@@ -249,7 +249,7 @@ export const SETTINGS: readonly Setting[] = [
 ]
 
 /** The `.vx/workspace` groups that hold settings; `baseBranch` and `plugins` are the other keys. */
-export const SETTING_GROUPS = ['run', 'cache', 'lock', 'watch'] as const
+export const SETTING_GROUPS = ['run', 'cache', 'inputs', 'outputs', 'lock', 'watch'] as const
 
 const BY_PATH = new Map(SETTINGS.map((s) => [s.path, s]))
 
@@ -327,7 +327,9 @@ export function parseSettingValue(kind: SettingKind, raw: unknown): unknown {
     }
     case 'size':
       if (kind.off === true && (raw === false || raw === 'false')) return 0
-      return typeof raw === 'string' ? parseSize(raw) : null
+      // A size carries its unit, as a duration does: a bare `32` read as
+      // bytes turns the store off without a word.
+      return typeof raw === 'string' && !/^\d+$/.test(raw) ? parseSize(raw) : null
     case 'bool':
       if (typeof raw === 'boolean') return raw
       return raw === 'true' || raw === '1' ? true : raw === 'false' || raw === '0' ? false : null
@@ -362,7 +364,16 @@ export function settingRefusal(
     // A bare number past the ceiling is past it in either unit it could mean.
     const ms = bare ? n : typeof raw === 'string' ? parseDuration(raw) : null
     if (bare && !(kind.timer === true && n > MAX_TIMEOUT_MS)) {
-      return `${where} takes a duration with its unit, like '${n}ms' or '${Math.max(1, Math.round(n / 1000))}s' (got ${got})`
+      // Below a thousand the number most likely meant seconds (`--timeout
+      // 5`): that reading leads.
+      const like = n < 1000 ? `'${n}s' or '${n}ms'` : `'${n}ms' or '${Math.round(n / 1000)}s'`
+      return `${where} takes a duration with its unit, like ${like} (got ${got})`
+    }
+    // `'0s'` looks like the examples the generic refusal gives.
+    const negative = typeof raw === 'string' && raw.startsWith('-') && parseDuration(raw.slice(1))
+    if (ms === 0 || (negative !== false && negative !== null)) {
+      const none = kind.timer === true ? ' — omit it for no limit' : ''
+      return `${where} must be more than 0${none} (got ${got})`
     }
     if (kind.timer === true && ms !== null && ms > MAX_TIMEOUT_MS) {
       return (
@@ -372,6 +383,18 @@ export function settingRefusal(
       )
     }
   }
+  const bytes =
+    typeof raw === 'number'
+      ? raw
+      : typeof raw === 'string' && /^\d+$/.test(raw)
+        ? Number(raw)
+        : null
+  if (kind.type === 'size' && bytes !== null && Number.isSafeInteger(bytes) && bytes >= 0) {
+    if (bytes === 0 && kind.off === true) return `${where} is false to keep none (got ${got})`
+    // A small number most likely meant KiB (`32`): that reading leads.
+    const like = bytes < 1024 ? `'${bytes}KiB' or '${bytes}B'` : `'${bytes}B'`
+    return `${where} takes a size with its unit, like ${like} (got ${got})`
+  }
   return `${where} must be ${kindHint(kind)} (got ${got})`
 }
 
@@ -387,9 +410,22 @@ export function settingEnv(path: string, env: NodeJS.ProcessEnv = process.env):
   return v
 }
 
-/** Validate every set setting variable once, so a deep reader can trust what it reads. */
-export function checkSettingsEnv(env: NodeJS.ProcessEnv = process.env): void {
-  for (const s of SETTINGS) settingEnv(s.path, env)
+/**
+ * Validate every set setting variable once, so a deep reader can trust what
+ * it reads. One whose flag `args` holds (before a `--`) is left alone: the
+ * flag beats it, so nothing reads it.
+ */
+export function checkSettingsEnv(
+  env: NodeJS.ProcessEnv = process.env,
+  args: readonly string[] = [],
+): void {
+  const end = args.indexOf('--')
+  const given = end === -1 ? args : args.slice(0, end)
+  for (const s of SETTINGS) {
+    const flag = s.flag?.name
+    if (flag !== undefined && given.some((a) => a === flag || a.startsWith(`${flag}=`))) continue
+    settingEnv(s.path, env)
+  }
 }
 
 /** Where a resolved setting came from. */

package/src/ui/components.ts

@@ -6,6 +6,7 @@
 import {
   barWidth,
   identityHue,
+  GUTTER,
   INDENT,
   LABEL_MIN,
   paint,
@@ -13,6 +14,8 @@ import {
   RESET,
   ruleWidth,
   SYMBOL,
+  TABLE_WIDTH,
+  underlined,
   type ColorSupport,
   type Style,
   type Tone,
@@ -31,6 +34,8 @@ export type Inline = string | Token | readonly Inline[]
 /** A laid-out piece of output; `render` and `print` space blocks apart. */
 export interface Block {
   readonly lines: (colors: ColorSupport) => string[]
+  /** A grid's column header: it rides its section's title line, past the gutter. */
+  readonly head?: (colors: ColorSupport) => string
 }
 
 /** A `project` or `project#task` id, each half in its name's hue, the `#` dim. */
@@ -120,24 +125,6 @@ function prose(text: string): Inline {
     .map((p, i) => (i % 2 === 1 ? cmd(p) : p === '' ? p : { style: 'value' as const, text: p }))
 }
 
-/**
- * A panel's top off colour: `─ Title count ──── note ─`, flush with the
- * bars. The same characters a pipe, a test and `grep` read.
- */
-function ruleLine(
-  title: string,
-  count: Inline | undefined,
-  c: ColorSupport,
-  note?: Inline,
-): string {
-  const plain = { enabled: false }
-  const head = `─ ${title}${count === undefined ? '' : ` ${inline(count, plain)}`} `
-  if (note === undefined)
-    return `${head}${'─'.repeat(Math.max(8, ruleWidth(c) - Bun.stringWidth(head)))}`
-  const tail = ` ${inline(note, plain)} ─`
-  return `${head}${'─'.repeat(Math.max(3, ruleWidth(c) - Bun.stringWidth(head) - Bun.stringWidth(tail)))}${tail}`
-}
-
 // ── Panels ──────────────────────────────────────────────────────────
 // vx's screens look like a TUI and are not one: each part is a box drawn
 // line by line into the scrollback, so a pipe, a CI log and a terminal all
@@ -212,33 +199,40 @@ export function wrap(line: string, w: number): string[] {
   return rows
 }
 
-const border = (s: string, c: ColorSupport): string => paint('border', s, c)
+/** A title line's width: the terminal's, so a task's name sits over it too; never under the bars'. */
+const titleWidth = (c: ColorSupport): number => Math.max(ruleWidth(c), c.columns ?? TABLE_WIDTH)
 
 /**
- * A panel's top: the rule `─ Title count ──── note ─`, its title bold in
- * the brand hue, the rule a quiet grey. A panel has no box: its lines sit
- * under the rule as they are, so a terminal, a CI log and a pipe read the
- * same layout (off colour, the same characters unpainted).
+ * A section's title line: the title in the gutter, bold in the brand hue,
+ * a grid's column header past it (`head`), a note flush right, the whole
+ * line underlined in the rule's grey. No rule characters: off colour it is
+ * the same words, unmarked.
  */
-export function panelTop(title: string, c: ColorSupport, count?: Inline, note?: Inline): string {
-  if (!c.enabled) return ruleLine(title, count, c, note)
-  const plain = { enabled: false }
-  const head = `─ ${title}${count === undefined ? '' : ` ${inline(count, plain)}`} `
-  const tail = note === undefined ? '' : ` ${inline(note, plain)} ─`
-  const dashes = Math.max(
-    note === undefined ? 8 : 3,
-    ruleWidth(c) - Bun.stringWidth(head) - Bun.stringWidth(tail),
-  )
-  return (
-    border('─ ', c) +
+export function panelTop(
+  title: string,
+  c: ColorSupport,
+  count?: Inline,
+  note?: Inline,
+  head?: string,
+): string {
+  let line =
+    INDENT +
     paint('heading', title, c) +
-    (count === undefined ? '' : ` ${inline(typeof count === 'string' ? dim(count) : count, c)}`) +
-    ' ' +
-    border('─'.repeat(dashes), c) +
-    (note === undefined
-      ? ''
-      : ` ${inline(typeof note === 'string' ? dim(note) : note, c)} ${border('─', c)}`)
-  )
+    (count === undefined ? '' : ` ${inline(typeof count === 'string' ? dim(count) : count, c)}`)
+  if (head !== undefined) line += ' '.repeat(Math.max(1, GUTTER - Bun.stringWidth(line))) + head
+  const tail = note === undefined ? '' : inline(typeof note === 'string' ? dim(note) : note, c)
+  const used = Bun.stringWidth(line) + Bun.stringWidth(tail)
+  line += ' '.repeat(Math.max(tail === '' ? 0 : 2, titleWidth(c) - used)) + tail
+  return underlined(line, c)
+}
+
+/**
+ * A list's divider: the underline alone, from the grid's first column to the
+ * title lines' end (off colour, a blank line).
+ */
+export function divider(c: ColorSupport): string {
+  if (!c.enabled) return ''
+  return ' '.repeat(GUTTER) + underlined(' '.repeat(titleWidth(c) - GUTTER), c)
 }
 
 /**
@@ -253,7 +247,7 @@ export function section(title: string, ...rest: (Block | Inline)[]): Block {
   const body = (counted ? rest.slice(1) : rest) as Block[]
   return block((c) => {
     const inner = body.flatMap((b, i) => (i === 0 ? b.lines(c) : ['', ...b.lines(c)]))
-    return [panelTop(title, c, count), ...inner]
+    return [panelTop(title, c, count, undefined, body[0]?.head?.(c)), ...inner]
   })
 }
 

package/src/ui/index.ts

@@ -9,6 +9,7 @@ export { ui }
 
 export {
   bar,
+  divider,
   barWidth,
   cmd,
   code,
@@ -50,6 +51,7 @@ export {
 export {
   detectColors,
   dumbTerminal,
+  GUTTER,
   INDENT,
   paint,
   ruleWidth,
@@ -58,7 +60,7 @@ export {
   type Style,
   type Tone,
 } from './theme.js'
-export { colorsOf, data, print, say, transient, type StreamName } from './terminal.js'
+export { colorsOf, data, dataPieces, print, say, transient, type StreamName } from './terminal.js'
 export { endStyle, hasEscape, lastRedraw, leavesStyle, STYLE_END } from './ansi.js'
 export {
   createOutputWriter,

package/src/ui/live-region.ts

@@ -75,11 +75,38 @@ export interface OutputWriterOptions {
   now?: () => number
   /**
    * Off a TTY, hold writes and hand them to the stream once per turn of
-   * the event loop until `settle()`. A warm 476-package run wrote each of
-   * its 952 task lines as its own syscall (item 753). Off by default: a
-   * caller reading its stream right after a write sees it.
+   * the event loop, or once 64 KiB are held, until `settle()`. A warm
+   * 476-package run wrote each of its 952 task lines as its own syscall
+   * (item 753). Off by default: a caller reading its stream right after a
+   * write sees it.
    */
   coalesce?: boolean
+  /** Floor between two coalesced writes; 0 writes once per turn. */
+  coalesceMs?: number
+}
+
+/** What `coalesce` holds before it writes without waiting for the turn's end. */
+const HELD_MAX_CHARS = 64 * 1024
+
+/** The longest piece of a string handed to the stream in one write. */
+const WRITE_SLICE_CHARS = 1024 * 1024
+
+/**
+ * `text` in slices: a stream encodes a string whole before it writes, and
+ * a frame's furniture makes its text two bytes a character, so one 100 MB
+ * frame took ~300 MB more to write than to build.
+ */
+function writeSliced(stream: StatusStream, text: string): void {
+  let at = 0
+  while (text.length - at > WRITE_SLICE_CHARS) {
+    let end = at + WRITE_SLICE_CHARS
+    // Never between the halves of a surrogate pair.
+    const c = text.charCodeAt(end - 1)
+    if (c >= 0xd800 && c <= 0xdbff) end--
+    stream.write(text.slice(at, end))
+    at = end
+  }
+  stream.write(at === 0 ? text : text.slice(at))
 }
 
 export function createOutputWriter(
@@ -90,16 +117,29 @@ export function createOutputWriter(
   const minRedrawMs = opts.minRedrawMs ?? 100
   const forceFloorMs = opts.forceFloorMs ?? 30
   const now = opts.now ?? Date.now
+  const coalesceMs = opts.coalesceMs ?? 25
   // The coalesced writes not yet handed over; null once settled or when
   // not coalescing.
   let held: string[] | null = !enabled && opts.coalesce === true ? [] : null
+  let heldChars = 0
   let flushQueued = false
-  const flushHeld = (): void => {
-    flushQueued = false
+  let flushTimer: ReturnType<typeof setTimeout> | null = null
+  let lastFlush = -Infinity
+  const writeHeld = (): void => {
     if (held === null || held.length === 0) return
     const text = held.join('')
     held.length = 0
-    stream.write(text)
+    heldChars = 0
+    lastFlush = now()
+    writeSliced(stream, text)
+  }
+  const flushHeld = (): void => {
+    flushQueued = false
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer)
+      flushTimer = null
+    }
+    writeHeld()
   }
 
   let current: Region | null = null
@@ -276,13 +316,32 @@ export function createOutputWriter(
     write(chunk) {
       if (!enabled) {
         if (held === null) {
-          stream.write(chunk)
+          writeSliced(stream, chunk)
+          return
+        }
+        // A big write goes as it is: joined with what is held, it was copied.
+        if (chunk.length >= HELD_MAX_CHARS) {
+          writeHeld()
+          writeSliced(stream, chunk)
           return
         }
         held.push(chunk)
+        heldChars += chunk.length
+        // A warm run replays its hits without yielding to the event loop,
+        // so the turn's end came only after every hit's log: 500 hits
+        // printing 1 MiB each were held at once (2 GB of heap).
+        if (heldChars >= HELD_MAX_CHARS) {
+          writeHeld()
+          return
+        }
         if (!flushQueued) {
           flushQueued = true
-          setImmediate(flushHeld)
+          // At most one write per floor: a restore settles its hits over
+          // hundreds of turns, and a write per turn cost the 9,603-task
+          // restore ~100 ms of its main thread (2026-11-07).
+          const wait = lastFlush + coalesceMs - now()
+          if (wait > 0) flushTimer = setTimeout(flushHeld, wait)
+          else setImmediate(flushHeld)
         }
         return
       }

package/src/ui/terminal.ts

@@ -31,6 +31,18 @@ export function data(stream: StreamName, bytes: string): void {
   streamOf(stream).write(bytes)
 }
 
+/**
+ * `data` for bytes too many for one string, written piece by piece. A
+ * pipe that reads slower than vx writes is waited on: unwaited, every
+ * piece queues in memory until the reader catches up.
+ */
+export async function dataPieces(stream: StreamName, pieces: Iterable<string>): Promise<void> {
+  const s = streamOf(stream)
+  for (const piece of pieces) {
+    if (!s.write(piece)) await new Promise((resolve) => s.once('drain', resolve))
+  }
+}
+
 /** Whether a stream paints. */
 export function colorsOf(stream: StreamName): ReturnType<typeof detectColors> {
   return detectColors(streamOf(stream))

package/src/ui/theme.ts

@@ -77,7 +77,11 @@ export const INDENT = '  '
 export const LABEL_MIN = 8
 /** A meter's widest, and the label column beside it (2 indent + 8 label + 2 gap). */
 const BAR_MAX = 50
-const BAR_LABEL = 12
+/** The gutter a section's title sits in: a field's label column, a grid row's lead. */
+export const GUTTER = 12
+/** A title line's width when the terminal's is unknown (a pipe, a CI log): past a task's name. */
+export const TABLE_WIDTH = 120
+const BAR_LABEL = GUTTER
 
 /**
  * Identity hues for the two halves of a `project#task` id, never a status
@@ -194,6 +198,17 @@ export function paintHex(
   return prefix === '' ? text : `${prefix}${text}${RESET}`
 }
 
+// The underline in the rule's grey (SGR 58): a terminal without it underlines in the text's colour.
+const UNDER_RULE = `${UNDERLINE}\x1b[58;2;110;118;129m`
+
+/** A title line underlined end to end, gaps included, each hue kept. */
+export function underlined(line: string, c: ColorSupport): string {
+  if (!c.enabled) return line.trimEnd()
+  // A trailing reset is the line's own end: re-opening the underline there left an empty pair.
+  const body = line.endsWith(RESET) ? line.slice(0, -RESET.length) : line
+  return `${UNDER_RULE}${body.replaceAll(RESET, RESET + UNDER_RULE)}${RESET}`
+}
+
 /** `text` in a style; `bold` adds weight to a hue. */
 export function paint(style: Style, text: string, c: ColorSupport, bold = false): string {
   switch (style) {