@defrex/autobuild 0.8.0

package/packages/core/src/cli/dashboard/render.ts

@@ -0,0 +1,1568 @@
+/**
+ * The dashboard's other pure half: model → `string[]`. No terminal, no state,
+ * no I/O — `live.ts` owns the writer, this owns the pixels.
+ *
+ * Two constraints shape every choice here:
+ *
+ * **Never color-only for pipeline and row state.** Color is additive emphasis:
+ * every step also carries a glyph (`[x]` `[>]` `[~]` `[ ]`) and every status
+ * its literal word (`RUNNING` / `PAUSED` / `BLOCKED`). Auto-merge is the one
+ * deliberate presentation exception: token presence carries on/off intent,
+ * while color distinguishes requested, enabled, and cancelling. Strip the
+ * escapes — as `--plain` and every pipe do — and the actionable intent remains.
+ *
+ * **Cell-honest Unicode.** Printable text is segmented into whole grapheme
+ * clusters and measured in terminal display cells. Control bytes remain
+ * visible escapes, so dynamic text cannot inject terminal traffic.
+ *
+ * The ~40 lines of ANSI are hand-rolled for the same reason: this repo has
+ * four runtime deps and none is terminal-related; `chalk`/`ink` would be a
+ * posture change to win a color map.
+ */
+import { basename } from 'node:path'
+import type {
+  DashboardBuild,
+  DashboardHarvest,
+  DashboardModel,
+  DashboardSelection,
+  PipelineStep,
+} from './model'
+import { dashboardBuildControl } from './actions'
+import type { DashboardSession } from './detail'
+import type { TranscriptPresentation, TranscriptTurn } from './transcript'
+import { projectSessionDocument, projectSessionParts } from './session-view'
+import type { SessionDashboardView } from './model'
+import { dashboardSelections, sameSelection } from './selection'
+import { displayText, layoutComposer, packAtomic, wrapDisplay } from './composer'
+import { cellWidth, graphemes, padEndCells } from './cells'
+
+export interface RenderOpts {
+  /** ANSI on. False ⇒ not a single `\x1b` in the output (the `--plain` AC). */
+  color: boolean
+  /** Hard cap per line; one rendered line must be one physical row. */
+  width: number
+  /**
+   * The render-time clock (epoch ms). A running step's elapsed is
+   * `timing.accumulatedMs + (now - timing.runningSince)`, so painting the same
+   * cached model against a moving `now` is what makes the elapsed tick without
+   * recomputing the model (AC 8). Steps with no open interval ignore it.
+   */
+  now: number
+  /**
+   * Hard cap on the NUMBER of lines — the screen's paintable rows.
+   *
+   * The live region clears its alternate display and anchors this frame at
+   * terminal row 1 on every effective paint. The cap still matters: every
+   * rendered line has a trailing newline, so a frame as tall as the screen
+   * scrolls its own top away even on a freshly cleared display.
+   *
+   * This is a cap on LINES, and it is NOT the screen's row count: the region
+   * needs a row for the cursor to rest on, so a caller painting a terminal
+   * must pass `paintableRows(rows)`, not `rows`. This module cannot enforce
+   * that — it counts lines and knows nothing of the region's trailing newline.
+   *
+   * Absent ⇒ unbounded, for callers that are not painting a screen.
+   */
+  height?: number
+}
+
+/** A dashboard presentation implementation. Kept as a named dependency so the
+ * repo-local dev entry can replace presentation without replacing the live
+ * dispatch loop that owns runners, input, timers, and leases. */
+export type DashboardRenderer = (model: DashboardModel, opts: RenderOpts) => string[]
+
+/** Resolve at paint time rather than capturing one renderer at loop startup. */
+export type DashboardRendererResolver = () => DashboardRenderer
+
+// ── ANSI ─────────────────────────────────────────────────────────────────────
+
+const ESC = '\x1b['
+const RESET = `${ESC}0m`
+/** Closes an OSC 8 hyperlink. `RESET` does NOT: it is an SGR reset, and the
+ * two families are independent — only this ends the link. */
+const LINK_OFF = '\x1b]8;;\x07'
+const CODES = {
+  dim: 2,
+  red: 31,
+  green: 32,
+  yellow: 33,
+  blue: 34,
+  cyan: 36,
+  bold: 1,
+} as const
+type ColorName = keyof typeof CODES
+
+function paint(text: string, color: ColorName, on: boolean): string {
+  return on ? `${ESC}${CODES[color]}m${text}${RESET}` : text
+}
+
+/** OSC 8: the escape common terminals turn into a real hyperlink. In plain
+ * mode we emit the bare URL, which those same terminals linkify on sight —
+ * so "PR URLs are recognized as a link" holds on both paths. */
+function link(url: string, text: string, on: boolean): string {
+  if (!/^https?:\/\//.test(url)) return text === url ? url : `${text} ${url}`
+  return on ? `\x1b]8;;${url}\x07${text}${LINK_OFF}` : url
+}
+
+/** Visible length: what the operator's eye counts, not what `.length` does. */
+function visibleLength(text: string): number {
+  return cellWidth(stripAnsi(text))
+}
+
+export function stripAnsi(text: string): string {
+  // CSI (colors) and OSC 8 (hyperlinks) — the only two families we emit.
+  return text.replace(/\x1b\][^\x07]*\x07/g, '').replace(/\x1b\[[0-9;]*m/g, '')
+}
+
+/**
+ * Truncate to `width` VISIBLE columns without ever splitting an escape, and
+ * without leaving any mode it cut through switched ON.
+ *
+ * Walking the string escape-aware (rather than slicing and hoping) is the
+ * whole point: a cut mid-sequence leaks raw escape bytes onto the screen, and
+ * a cut that drops a closer leaves the mode running down the rest of the
+ * frame. Escapes are copied through and cost zero columns.
+ *
+ * BOTH families this file emits are stateful, and both must be closed — the
+ * SGR colors with `RESET`, and an OSC 8 hyperlink with `LINK_OFF`. `RESET` does
+ * not close a hyperlink. Getting this wrong is not cosmetic: `renderBuild` puts
+ * the PR link LAST, so it is the first thing truncation eats, and an unclosed
+ * OSC 8 makes every line painted afterwards — the progress row, the blockers,
+ * every later build — clickable to that one PR. `finish()` deliberately leaves
+ * the final frame up, so the state would outlive the process and land on the
+ * operator's shell prompt.
+ */
+function truncate(text: string, width: number): string {
+  if (width <= 0) return ''
+  if (visibleLength(text) <= width) return text
+  let out = ''
+  let visible = 0
+  let sawSgr = false
+  let linkOpen = false
+  const budget = Math.max(0, width - 1)
+
+  for (let i = 0; i < text.length; ) {
+    if (text[i] === '\x1b') {
+      const osc = text[i + 1] === ']'
+      const end = osc ? text.indexOf('\x07', i) : text.slice(i).search(/[A-Za-z]/) + i
+      const stop = end === -1 || end < i ? text.length - 1 : end
+      const seq = text.slice(i, stop + 1)
+      out += seq
+      i = stop + 1
+      if (osc) linkOpen = seq !== LINK_OFF
+      else sawSgr = true
+      continue
+    }
+
+    const nextEscape = text.indexOf('\x1b', i)
+    const stop = nextEscape === -1 ? text.length : nextEscape
+    let cut = false
+    for (const cluster of graphemes(text.slice(i, stop))) {
+      if (cluster.width > budget || visible + cluster.width > budget) {
+        cut = true
+        break
+      }
+      out += cluster.text
+      visible += cluster.width
+    }
+    if (cut) break
+    i = stop
+  }
+  out += '~'
+  // Close what we cut through — the link first, so the `~` stays inside it.
+  if (linkOpen) out += LINK_OFF
+  return sawSgr ? `${out}${RESET}` : out
+}
+
+/**
+ * Greedily pack pre-rendered tokens into `indent`-prefixed lines of at most
+ * `width` VISIBLE columns.
+ *
+ * Why wrap rather than truncate: truncation is mandatory for redraw
+ * correctness (one rendered line must be one physical row, or the painted-line
+ * count under-counts and the redraw leaves fragments) — but a truncated
+ * progress row loses `finalize` and `merge waiting` off the right edge, i.e.
+ * exactly the steps the ACs require and the ones the operator is waiting on.
+ * Both hold at once because WE do the wrapping: every line we emit is within
+ * the width, so the row count stays honest AND nothing is dropped.
+ *
+ * A single token wider than the line is truncated — it cannot be helped, and
+ * it keeps the width guarantee absolute.
+ */
+function packLines(tokens: string[], width: number, indent: string): string[] {
+  const lines: string[] = []
+  let line = ''
+  for (const token of tokens) {
+    const candidate = line === '' ? `${indent}${token}` : `${line} ${token}`
+    if (line !== '' && visibleLength(candidate) > width) {
+      lines.push(line)
+      line = `${indent}${token}`
+    } else {
+      line = candidate
+    }
+  }
+  if (line !== '') lines.push(line)
+  return lines.map((l) => truncate(l, width))
+}
+
+// ── Steps ────────────────────────────────────────────────────────────────────
+
+const GLYPH: Record<PipelineStep['state'], string> = {
+  done: '[x]',
+  current: '[>]',
+  provisional: '[~]',
+  pending: '[ ]',
+}
+
+const STEP_COLOR: Record<PipelineStep['state'], ColorName> = {
+  done: 'green',
+  current: 'cyan',
+  provisional: 'yellow',
+  pending: 'dim',
+}
+
+/**
+ * Elapsed duration, ASCII only: `Xs` under a minute, `MmSSs` under an hour,
+ * `HhMMm` above — seconds/minutes zero-padded when a larger unit precedes, so
+ * the field width is stable as it ticks (`38s`, `4m12s`, `1h04m`).
+ */
+export function formatDuration(ms: number): string {
+  const totalSec = Math.max(0, Math.floor(ms / 1000))
+  if (totalSec < 60) return `${totalSec}s`
+  const totalMin = Math.floor(totalSec / 60)
+  if (totalMin < 60) return `${totalMin}m${String(totalSec % 60).padStart(2, '0')}s`
+  return `${Math.floor(totalMin / 60)}h${String(totalMin % 60).padStart(2, '0')}m`
+}
+
+function renderStep(step: PipelineStep, color: boolean, now: number): string {
+  const parts: string[] = []
+  if (step.qualifier !== undefined) parts.push(step.qualifier)
+  // The elapsed segment can only be composed here — it depends on the
+  // render-time clock. A running step's open interval grows with `now`; a
+  // frozen or done step has none, so its elapsed is stable across repaints.
+  // `count` rides the time as `/n` (AC 7); with no time in scope it is not
+  // shown (a fresh/restarted step should not carry a stale round).
+  if (step.timing !== undefined) {
+    const { accumulatedMs, runningSince } = step.timing
+    const elapsedMs =
+      accumulatedMs + (runningSince !== undefined ? Math.max(0, now - runningSince) : 0)
+    const count = step.count !== undefined && step.count > 1 ? `/${step.count}` : ''
+    parts.push(`${formatDuration(elapsedMs)}${count}`)
+  }
+  const note = parts.length > 0 ? `(${parts.join(', ')})` : ''
+  const text = `${GLYPH[step.state]} ${step.label}${note}`
+  const painted = paint(text, STEP_COLOR[step.state], color)
+  return step.state === 'current' ? paint(painted, 'bold', color) : painted
+}
+
+// ── Builds ───────────────────────────────────────────────────────────────────
+
+const STATUS_COLOR: Record<DashboardBuild['status'] | DashboardHarvest['status'], ColorName> = {
+  queued: 'cyan',
+  running: 'green',
+  pausing: 'yellow',
+  paused: 'yellow',
+  resuming: 'cyan',
+  blocked: 'red',
+  aborting: 'red',
+  cleaning: 'yellow',
+  escalated: 'yellow',
+  failed: 'red',
+}
+
+/** The marker is one shared visual grammar for every selectable row. */
+function selectionMarker(selected: boolean, selecting: boolean, color: boolean): string {
+  // The marker owns a fixed two-column lane even when keyboard selection is
+  // unavailable. No identity or detail text may drift into those columns.
+  return selecting && selected ? paint('> ', 'cyan', color) : '  '
+}
+
+/** Pin a right cluster to the frame edge while keeping exactly one flexible,
+ * truncatable segment on the left. */
+function rightPinnedLine(prefix: string, flexible: string, right: string, width: number): string {
+  const budget = width - visibleLength(prefix) - visibleLength(right) - 2
+  const left = truncate(flexible, Math.max(0, budget))
+  const used = visibleLength(prefix) + visibleLength(left)
+  const gap = ' '.repeat(Math.max(1, width - used - visibleLength(right)))
+  return truncate(`${prefix}${left}${gap}${right}`, width)
+}
+
+function reviewRoundCeilingText(build: DashboardBuild): string | undefined {
+  if (build.reviewRoundCeilings === undefined) return undefined
+  const values = [
+    ...(build.reviewRoundCeilings.plan !== undefined
+      ? [`plan ${build.reviewRoundCeilings.plan}`]
+      : []),
+    ...(build.reviewRoundCeilings.code !== undefined
+      ? [`code ${build.reviewRoundCeilings.code}`]
+      : []),
+  ]
+  return values.length === 0 ? undefined : `review round ceiling: ${values.join(', ')}`
+}
+
+function renderBuild(
+  build: DashboardBuild,
+  repositoryPaused: boolean,
+  opts: RenderOpts,
+  widths: Widths,
+  selected: boolean,
+  selecting: boolean,
+): string[] {
+  const { color, width, now } = opts
+
+  // ── The slug line: TICKET-ID  slug  …  <right cluster> ──────────────────────
+  //
+  // Explicit left / flexible / right layout, NOT "join then truncate the whole
+  // line" — the latter eats the rightmost token (the status, the PR link) first,
+  // exactly what this change moves away from. Ticket id is the left column,
+  // the slug is the flexible/truncatable identity segment, and the right
+  // cluster hugs `width` so status ends at the same column on every row.
+
+  // Left column: ticket id, padded frame-wide so slugs align even for a build
+  // with no ticket (AC 2). No column at all when the frame has zero ticket ids.
+  const marker = selectionMarker(selected, selecting, color)
+  const ticketCol =
+    widths.ticket > 0 ? paint(padEndCells(build.ticketId ?? '', widths.ticket), 'blue', color) : ''
+  const leftPrefix = `${marker}${ticketCol === '' ? '' : `${ticketCol}  `}`
+
+  // Right cluster, rightmost last: [PR] [(paused)] STATUS. `padStart`
+  // right-justifies the status word so it is never truncated and always ends at
+  // the frame's right edge (AC 3, AC 5).
+  const rightTokens: string[] = []
+  if (build.autoMerge !== 'off') {
+    const autoColor: ColorName =
+      build.autoMerge === 'enabled' ? 'green' : build.autoMerge === 'requested' ? 'cyan' : 'yellow'
+    rightTokens.push(paint('auto merge', autoColor, color))
+  }
+  if (build.pr !== undefined) rightTokens.push(link(build.pr.url, `PR ${build.pr.state}`, color))
+  // A repository hold changes no build lifecycle state. Keep QUEUED literal
+  // and annotate only the rows the hold prevents from launching.
+  if (repositoryPaused && build.status === 'queued') {
+    rightTokens.push(paint('(held)', 'yellow', color))
+  }
+  // Blocked overrides paused visually, but the pause is still a fact the
+  // operator needs — so it rides along rather than being overwritten.
+  if (build.alsoPaused) rightTokens.push(paint('(paused)', 'yellow', color))
+  rightTokens.push(
+    paint(build.status.toUpperCase().padStart(widths.status), STATUS_COLOR[build.status], color),
+  )
+  const rightStr = rightTokens.join('  ')
+
+  // The slug is the sole flexible segment; narrow frames truncate it before
+  // the right-pinned lifecycle status.
+  const lines = [rightPinnedLine(leftPrefix, paint(build.slug, 'bold', color), rightStr, width)]
+  const ceiling = reviewRoundCeilingText(build)
+  if (ceiling !== undefined) lines.push(truncate(`  ${ceiling}`, width))
+
+  if (build.abortProgress !== undefined) {
+    for (const line of wrappedText(build.abortProgress, width - 4, '')) {
+      lines.push(truncate(paint(`  ! ${line}`, STATUS_COLOR[build.status], color), width))
+    }
+  } else if (build.dispatch !== undefined) {
+    for (const line of wrappedText(build.dispatch, width - 4, '')) {
+      lines.push(truncate(paint(`  ! ${line}`, STATUS_COLOR[build.status], color), width))
+    }
+  } else {
+    // The progress row wraps rather than truncating: the tail is `finalize` and
+    // `merge waiting`, which the ACs require and the operator is waiting on.
+    lines.push(
+      ...packLines(
+        build.steps.map((s) => renderStep(s, color, now)),
+        width,
+        '  ',
+      ),
+    )
+  }
+  // Setup failures and blocker questions are dense-list previews. Their model
+  // strings remain untouched; newline-aware wrapping and capping happen only
+  // at this presentation seam.
+  if (build.setupError !== undefined) {
+    lines.push(...prefixedMessagePreview(build.setupError, width, 'red', color, true))
+  }
+  for (const blocker of build.blockers) {
+    lines.push(...prefixedMessagePreview(blocker, width, 'red', color, true))
+  }
+  return lines
+}
+
+function renderHarvest(
+  harvest: DashboardHarvest,
+  opts: RenderOpts,
+  widths: Widths,
+  selected: boolean,
+  selecting: boolean,
+): string[] {
+  const { color, width, now } = opts
+  const marker = selectionMarker(selected, selecting, color)
+  // Harvest has no ticket id, so its title takes the ticket column itself —
+  // aligned with the ids, not the slugs — and the observation count sits in
+  // the flexible slug slot, keeping one row grammar across mixed frames.
+  const title = widths.ticket > 0 ? padEndCells(HARVEST_TITLE, widths.ticket) : HARVEST_TITLE
+  const leftPrefix = `${marker}${paint(title, 'bold', color)}  `
+  const identity = paint(`${harvest.observations} observations`, 'dim', color)
+  const statusColor = STATUS_COLOR[harvest.status]
+  const status = paint(harvest.status.toUpperCase().padStart(widths.status), statusColor, color)
+  const lines = [rightPinnedLine(leftPrefix, identity, status, width)]
+  lines.push(
+    ...packLines(
+      harvest.steps.map((item) => renderStep(item, color, now)),
+      width,
+      '  ',
+    ),
+  )
+  if (harvest.detail !== undefined) {
+    lines.push(...prefixedMessagePreview(harvest.detail, width, statusColor, color, false))
+  }
+  return lines
+}
+
+interface Widths {
+  ticket: number
+  status: number
+}
+
+const HARVEST_TITLE = 'Harvest'
+
+/** Pad ticket id and status to the widest in the FRAME, so columns line up down
+ * the whole dashboard rather than per-row. `ticket` is 0 when no build in the
+ * frame has a ticket id — then there is no ticket column at all. The Harvest
+ * title lives in the ticket column, so when that column exists it must also fit
+ * the title; Harvest joins the status-width calculation even in a mixed frame. */
+function frameWidths(builds: DashboardBuild[], harvest: DashboardHarvest | undefined): Widths {
+  const ticketIds = builds.map((b) => cellWidth(b.ticketId ?? ''))
+  const hasTicketColumn = ticketIds.some((length) => length > 0)
+  return {
+    ticket: Math.max(
+      0,
+      ...ticketIds,
+      ...(harvest !== undefined && hasTicketColumn ? [cellWidth(HARVEST_TITLE)] : []),
+    ),
+    status: Math.max(
+      0,
+      ...builds.map((b) => cellWidth(b.status)),
+      ...(harvest !== undefined ? [cellWidth(harvest.status)] : []),
+    ),
+  }
+}
+
+// ── The frame ────────────────────────────────────────────────────────────────
+
+export const DASHBOARD_GLOBAL_LEGEND =
+  'Keys: Up/Down select  h harvest  m auto-merge  i intake  p pause all  r resume all  Ctrl-C quit'
+export const DASHBOARD_HARVEST_LEGEND = 'Keys: Up/Down select  Ctrl-C quit'
+export const DASHBOARD_HARVEST_RESUME_LEGEND = 'Keys: Up/Down select  p resume  Ctrl-C quit'
+export const DASHBOARD_HARVEST_ACKNOWLEDGE_LEGEND =
+  'Keys: Up/Down select  p acknowledge  Ctrl-C quit'
+export const DASHBOARD_BUILD_LEGEND =
+  'Keys: Up/Down select  Enter details  m auto-merge  p pause  a abort  Ctrl-C quit'
+export const DASHBOARD_QUEUED_BUILD_LEGEND =
+  'Keys: Up/Down select  Enter details  d discard  a abort  Ctrl-C quit'
+/** The session view offers ONLY scrolling, back, and quit — it is read-only,
+ * and the legend says so by naming nothing else. */
+export const DASHBOARD_SESSION_LIVE_LEGEND =
+  'Keys: Up/Down scroll (following tail)  Esc back  Ctrl-C quit'
+export const DASHBOARD_SESSION_PAUSED_LEGEND =
+  'Keys: Up/Down scroll (paused)  Esc back  Ctrl-C quit'
+
+function buildLegend(build: DashboardBuild, detail: boolean): string {
+  if (build.status === 'aborting' || build.status === 'cleaning') {
+    return detail
+      ? 'Keys: Up/Down select session  Enter transcript  Esc back  Ctrl-C quit'
+      : 'Keys: Up/Down select  Enter details  Ctrl-C quit'
+  }
+  if (build.status === 'queued') {
+    return detail
+      ? 'Keys: d discard  a abort  Esc back  Ctrl-C quit'
+      : DASHBOARD_QUEUED_BUILD_LEGEND
+  }
+  const control = dashboardBuildControl(build.status)
+  const action = control === undefined ? '' : `  ${control.key} ${control.label}`
+  return detail
+    ? `Keys: Up/Down scroll  Left/Right select session  Enter transcript  m auto-merge${action}  a abort  Esc back  Ctrl-C quit`
+    : `Keys: Up/Down select  Enter details  m auto-merge${action}  a abort  Ctrl-C quit`
+}
+
+const MESSAGE_PREVIEW_ROWS = 3
+
+/** Preserve authored line structure while limiting display-only blank runs to
+ * one row. Two newline separators make one paragraph row; longer runs do not
+ * consume more dense-list space. */
+function messageDisplayRows(value: string, width: number, collapseBlankRuns: boolean): string[] {
+  if (width <= 0) return []
+  const logical = value.split(/\r?\n/)
+  const normalized: string[] = []
+  let previousBlank = false
+  for (const line of logical) {
+    const blank = line.trim().length === 0
+    if (!collapseBlankRuns || !blank || !previousBlank) normalized.push(line)
+    previousBlank = blank
+  }
+  return normalized.flatMap((line) => wrapDisplay(line, width))
+}
+
+function previewMessageRows(value: string, width: number, expandable: boolean): string[] {
+  const rows = messageDisplayRows(value, width, true)
+  if (rows.length <= MESSAGE_PREVIEW_ROWS) return rows
+  const remaining = rows.length - MESSAGE_PREVIEW_ROWS
+  const noun = remaining === 1 ? 'row' : 'rows'
+  const hint = expandable ? ' - Enter details' : ''
+  return [
+    ...rows.slice(0, MESSAGE_PREVIEW_ROWS),
+    ...wrapDisplay(`... ${remaining} more ${noun}${hint}`, width),
+  ]
+}
+
+function prefixedMessagePreview(
+  value: string,
+  width: number,
+  colorName: ColorName,
+  color: boolean,
+  expandable: boolean,
+): string[] {
+  const contentWidth = Math.max(0, width - 4)
+  return previewMessageRows(value, contentWidth, expandable).map((line, index) =>
+    truncate(paint(`${index === 0 ? '  ! ' : '    '}${line}`, colorName, color), width),
+  )
+}
+
+/** Each process warning is independently capped. Unlike build-owned messages,
+ * the warning slot has no selectable row, so its notice promises no expansion
+ * action. */
+function warningRows(lines: readonly string[], width: number): string[] {
+  const contentWidth = Math.max(0, width - 2)
+  return lines.flatMap((line) =>
+    previewMessageRows(line, contentWidth, false).map((row) => truncate(`  ${row}`, width)),
+  )
+}
+
+/**
+ * Wrap prose for the legacy frame elements — build rows, harvest detail,
+ * detail view, transcripts.
+ *
+ * Deliberately unchanged, and deliberately NOT the composer's `wrapDisplay`:
+ * this truncates a token wider than the line with a `~`, which every existing
+ * frame's byte-stable output depends on. Operator-facing prose that must
+ * survive in full — the resume panel's questions and hint — goes through
+ * `wrapDisplay` instead, and short labels that must stay whole go through
+ * `packAtomic`.
+ */
+function wrappedText(value: string, width: number, indent = ''): string[] {
+  if (width <= 0) return []
+  const paragraphs = value.split(/\r?\n/)
+  const lines: string[] = []
+  for (const paragraph of paragraphs) {
+    const safe = displayText(paragraph)
+    if (safe.length === 0) {
+      lines.push(indent)
+      continue
+    }
+    const wrapped = packLines(safe.split(/\s+/), width, indent)
+    lines.push(...(wrapped.length > 0 ? wrapped : [indent]))
+  }
+  return lines
+}
+
+function detailStep(step: PipelineStep, opts: RenderOpts): string {
+  const { color, now } = opts
+  const notes: string[] = []
+  if (step.qualifier !== undefined) notes.push(step.qualifier)
+  if (step.count !== undefined) {
+    const kind =
+      step.label.startsWith('verify:') || step.label === 'reconcile' ? 'attempt' : 'round'
+    notes.push(`${kind} ${step.count}`)
+  }
+  if (step.timing !== undefined) {
+    const elapsed =
+      step.timing.accumulatedMs +
+      (step.timing.runningSince !== undefined ? Math.max(0, now - step.timing.runningSince) : 0)
+    notes.push(formatDuration(elapsed))
+  }
+  const note = notes.length > 0 ? ` (${notes.join(', ')})` : ''
+  return paint(`${GLYPH[step.state]} ${step.label}${note}`, STEP_COLOR[step.state], color)
+}
+
+function sessionLines(session: DashboardSession, selected: boolean, opts: RenderOpts): string[] {
+  const usage = session.usage
+  const tokens = [
+    session.role,
+    `phase ${session.phase}`,
+    ...(session.round !== undefined ? [`round ${session.round}`] : []),
+    `runtime ${session.runtime}`,
+    ...(session.model !== undefined ? [`model ${session.model}`] : []),
+    session.status,
+    ...(session.stream !== undefined ? [`stream ${session.stream} (${session.streamStatus})`] : []),
+    ...(session.reclaimedBy !== undefined
+      ? [
+          `by ${session.reclaimedBy.instance} at resume boundary ${session.reclaimedBy.resumedFromSeq}`,
+          'transcript unavailable',
+        ]
+      : []),
+    ...(usage !== undefined
+      ? [`tokens ${usage.inputTokens} in/${usage.outputTokens} out, ${usage.turns} turns`]
+      : []),
+  ]
+  const wrapped = packLines(tokens.map(displayText), Math.max(1, opts.width - 4), '')
+  return wrapped.map((line, index) =>
+    truncate(
+      `${index === 0 ? selectionMarker(selected, true, opts.color) : '  '}  ${line}`,
+      opts.width,
+    ),
+  )
+}
+
+function viewport(lines: string[], capacity: number, focus: number, scroll = 0): string[] {
+  if (capacity <= 0) return []
+  const maxStart = Math.max(0, lines.length - capacity)
+  const wanted = scroll > 0 ? scroll : Math.max(0, focus - Math.floor(capacity / 2))
+  const start = Math.min(maxStart, wanted)
+  return lines.slice(start, start + capacity)
+}
+
+interface DetailBodyLayout {
+  body: string[]
+  sessionFocus: number | undefined
+  messageFocus: number | undefined
+}
+
+export type DetailFocusTarget = 'session' | 'message'
+
+function detailBody(
+  build: DashboardBuild,
+  view: Extract<NonNullable<DashboardModel['view']>, { kind: 'detail' }>,
+  opts: RenderOpts,
+): DetailBodyLayout {
+  const { color, width } = opts
+  const body: string[] = []
+  if (build.ticketId !== undefined) body.push(`  ticket ${displayText(build.ticketId)}`)
+  body.push(`  auto merge ${build.autoMerge}`)
+  const ceiling = reviewRoundCeilingText(build)
+  if (ceiling !== undefined) body.push(`  ${ceiling}`)
+  if (build.pr !== undefined)
+    body.push(`  PR ${build.pr.state}  ${link(build.pr.url, build.pr.url, color)}`)
+  if (build.abortProgress !== undefined) {
+    body.push('', paint('Abort progress', 'bold', color))
+    body.push(...wrappedText(build.abortProgress, width, '  '))
+  } else if (build.dispatch !== undefined) {
+    body.push('', paint('Dispatch', 'bold', color), ...wrappedText(build.dispatch, width, '  '))
+  } else {
+    body.push('', paint('Pipeline', 'bold', color))
+    body.push(...build.steps.map((item) => `  ${detailStep(item, opts)}`))
+  }
+  if (build.setupError !== undefined) {
+    body.push('', paint('Setup failure', 'bold', color))
+    body.push(
+      ...wrapDisplay(build.setupError, width, '  ').map((line) => paint(line, 'red', color)),
+    )
+  }
+  if (build.blockers.length > 0) {
+    body.push('', paint('Unresolved blockers', 'bold', color))
+    for (const blocker of build.blockers) {
+      body.push(
+        ...wrapDisplay(`! ${blocker}`, width, '  ').map((line) => paint(line, 'red', color)),
+      )
+    }
+    for (const note of [
+      'The r field records guidance, or a bare retry when empty.',
+      `CLI only: ab answer ${build.slug} --dismiss`,
+      `CLI only: ab answer ${build.slug} --revise-spec <file>`,
+    ]) {
+      body.push(...wrappedText(note, width, '  ').map((line) => paint(line, 'dim', color)))
+    }
+  }
+  body.push('', paint('Sessions', 'bold', color))
+  const sessions = build.sessions ?? []
+  let sessionFocus: number | undefined
+  if (sessions.length === 0) body.push('  no agent sessions recorded')
+  for (const session of sessions) {
+    if (session.id === view.sessionId) sessionFocus = body.length
+    body.push(...sessionLines(session, session.id === view.sessionId, opts))
+  }
+  let messageFocus: number | undefined
+  if (view.message !== undefined) {
+    const messageLines = wrappedText(view.message, width, '  ').map((line) =>
+      paint(line, 'yellow', color),
+    )
+    body.push('')
+    if (messageLines.length > 0) messageFocus = body.length
+    body.push(...messageLines)
+  }
+  return { body, sessionFocus, messageFocus }
+}
+
+interface DetailGeometry extends DetailBodyLayout {
+  capacity: number
+  limit: number
+}
+
+function upgradeNoticeLine(
+  model: DashboardModel,
+  color: boolean,
+  width: number,
+): string | undefined {
+  return model.availableUpgrade === undefined
+    ? undefined
+    : truncate(
+        paint(
+          `  Autobuild v${displayText(model.availableUpgrade)} is available — run ab upgrade`,
+          'cyan',
+          color,
+        ),
+        width,
+      )
+}
+
+function detailGeometry(
+  model: DashboardModel,
+  width: number,
+  height: number,
+): DetailGeometry | undefined {
+  const view = model.view
+  if (view?.kind !== 'detail') return undefined
+  const build = model.builds.find((candidate) => candidate.slug === view.slug)
+  if (build === undefined) return undefined
+  const layout = detailBody(build, view, { color: false, width, height, now: 0 })
+  const topLength = 2 + (model.availableUpgrade === undefined ? 0 : 1)
+  const controls =
+    model.resumeInput !== undefined || model.abortConfirmation !== undefined
+      ? dashboardControls(model, false, width, controlsCapacity(height, topLength))
+      : [buildLegend(build, true)]
+  const capacity = Math.max(0, height - topLength - 2 - controls.length)
+  return { ...layout, capacity, limit: Math.max(0, layout.body.length - capacity) }
+}
+
+export function detailScrollLimit(model: DashboardModel, width: number, height: number): number {
+  return detailGeometry(model, width, height)?.limit ?? 0
+}
+
+export function moveDetailScroll(
+  model: DashboardModel,
+  width: number,
+  height: number,
+  current: number,
+  delta: number,
+): number {
+  const limit = detailScrollLimit(model, width, height)
+  return Math.max(0, Math.min(limit, Math.min(current, limit) + delta))
+}
+
+/** Reveal one action-selected detail target without making retained display
+ * content a standing focus. Incoming and resulting offsets are always clamped. */
+export function revealDetailFocus(
+  model: DashboardModel,
+  width: number,
+  height: number,
+  target: DetailFocusTarget,
+  current: number,
+): number {
+  const geometry = detailGeometry(model, width, height)
+  if (geometry === undefined) return 0
+  const scroll = Math.max(0, Math.min(geometry.limit, current))
+  const focus = target === 'session' ? geometry.sessionFocus : geometry.messageFocus
+  if (focus === undefined || geometry.capacity <= 0) return scroll
+  if (focus < scroll) return focus
+  if (focus >= scroll + geometry.capacity) {
+    return Math.min(geometry.limit, focus - Math.max(0, geometry.capacity - 1))
+  }
+  return scroll
+}
+
+function renderDetail(model: DashboardModel, opts: RenderOpts): string[] {
+  const view = model.view
+  if (view?.kind !== 'detail') return []
+  const build = model.builds.find((candidate) => candidate.slug === view.slug)
+  if (build === undefined) return []
+  const { color, width, height } = opts
+  const paused = build.alsoPaused ? ' (also paused)' : ''
+  const notice = upgradeNoticeLine(model, color, width)
+  const top = [
+    truncate(`${paint('Build', 'bold', color)}  ${displayText(build.slug)}`, width),
+    truncate(
+      `  status ${paint(build.status.toUpperCase(), STATUS_COLOR[build.status], color)}${paused}`,
+      width,
+    ),
+    ...(notice === undefined ? [] : [notice]),
+  ]
+  const { body } = detailBody(build, view, opts)
+  const controls =
+    model.resumeInput !== undefined || model.abortConfirmation !== undefined
+      ? dashboardControls(model, color, width, controlsCapacity(height, top.length))
+      : [truncate(paint(buildLegend(build, true), 'dim', color), width)]
+  if (height !== undefined && height <= 0) return []
+  if (height !== undefined && height <= top.length) return top.slice(0, height)
+  if (height !== undefined && height === top.length + 1) return [...top, ...controls]
+  if (height !== undefined && height === top.length + 2) return [...top, '', ...controls]
+  const capacity =
+    height === undefined ? body.length : Math.max(0, height - top.length - 2 - controls.length)
+  const limit = Math.max(0, body.length - capacity)
+  const start = Math.max(0, Math.min(limit, view.scroll))
+  return [
+    ...top,
+    '',
+    ...body.slice(start, start + capacity).map((line) => truncate(line, width)),
+    '',
+    ...controls,
+  ].slice(0, height === undefined ? Number.POSITIVE_INFINITY : height)
+}
+
+function transcriptContent(presentation: TranscriptPresentation, width: number): string[] {
+  if (presentation.kind === 'raw') {
+    return [
+      'Unrecognized transcript format - raw content:',
+      '',
+      ...presentation.text.split(/\r?\n/).flatMap((line) => wrappedText(line, width, '  ')),
+    ]
+  }
+  const lines: string[] = []
+  if (presentation.kind === 'producer-boundary') {
+    lines.push(...wrappedText(presentation.notice, width, ''), '')
+  }
+  for (const [index, turn] of presentation.turns.entries()) {
+    lines.push(`Turn ${index + 1}`)
+    lines.push(...turnContent(turn, width), '')
+  }
+  return lines
+}
+
+/** Convert a terminal's width to the dashboard's inset composition width. */
+export function dashboardContentWidth(terminalWidth: number): number {
+  return Math.max(0, Math.max(0, terminalWidth) - 2)
+}
+
+/** Maximum process-local transcript offset for the current wrapped viewport. */
+export function transcriptScrollLimit(
+  presentation: TranscriptPresentation,
+  terminalWidth: number,
+  height: number,
+  hasUpgradeNotice = false,
+): number {
+  const contentLines = transcriptContent(presentation, dashboardContentWidth(terminalWidth)).length
+  // Transcript chrome is two header rows, the optional upgrade row, two
+  // separators, and controls. Keep this in lockstep with renderTranscript.
+  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0))
+  return Math.max(0, contentLines - capacity)
+}
+
+export function moveTranscriptScroll(
+  presentation: TranscriptPresentation,
+  terminalWidth: number,
+  height: number,
+  current: number,
+  delta: number,
+  hasUpgradeNotice = false,
+): number {
+  const limit = transcriptScrollLimit(presentation, terminalWidth, height, hasUpgradeNotice)
+  // Clamp current first because a resize, or state from an older controller,
+  // may leave it beyond the freshly wrapped viewport's end.
+  return Math.max(0, Math.min(limit, Math.min(current, limit) + delta))
+}
+
+function turnContent(turn: TranscriptTurn, width: number): string[] {
+  const lines = [
+    ...wrappedText(`Prompt: ${turn.prompt}`, width, '  '),
+    ...wrappedText(`Agent: ${turn.text}`, width, '  '),
+  ]
+  if (turn.usage !== undefined) {
+    lines.push(
+      `  Usage: ${turn.usage.inputTokens} input, ${turn.usage.outputTokens} output${
+        turn.usage.turns !== undefined ? `, ${turn.usage.turns} turns` : ''
+      }`,
+    )
+  }
+  if (turn.failure !== undefined)
+    lines.push(...wrappedText(`Failure: ${turn.failure}`, width, '  '))
+  return lines
+}
+
+function renderTranscript(model: DashboardModel, opts: RenderOpts): string[] {
+  const view = model.view
+  if (view?.kind !== 'transcript') return []
+  const { color, width, height } = opts
+  const notice = upgradeNoticeLine(model, color, width)
+  const top = [
+    truncate(`${paint('Transcript', 'bold', color)}  ${displayText(view.slug)}`, width),
+    truncate(`  session ${displayText(view.sessionId)}`, width),
+    ...(notice === undefined ? [] : [notice]),
+  ]
+  const content = transcriptContent(view.transcript, width).map((line) => truncate(line, width))
+  const controls = truncate(
+    paint('Keys: Up/Down scroll  Esc back  Ctrl-C quit', 'dim', color),
+    width,
+  )
+  if (height !== undefined && height <= 0) return []
+  if (height !== undefined && height <= top.length) return top.slice(0, height)
+  const capacity = height === undefined ? content.length : Math.max(0, height - top.length - 3)
+  return [...top, '', ...viewport(content, capacity, 0, view.scroll), '', controls].slice(
+    0,
+    height === undefined ? Number.POSITIVE_INFINITY : height,
+  )
+}
+
+/** The session view's full scrollable content: the shared projection's lines,
+ * or the error message in place of them, plus the closed stream's outcome
+ * line. ONE shared derivation for the renderer and the scroll limit so the
+ * tail math cannot drift from the paint. */
+export function sessionContentLines(view: SessionDashboardView, width: number): string[] {
+  if (view.error !== undefined) return wrappedText(view.error, width, '')
+  const lines =
+    view.source.kind === 'parts'
+      ? projectSessionParts(view.source.parts, width)
+      : projectSessionDocument(view.source.document, width)
+  if (view.status === 'closed') {
+    lines.push(`Stream closed: ${view.outcome ?? 'completed'}`)
+  }
+  return lines
+}
+
+/** Maximum process-local session-view offset for the current wrapped viewport.
+ * Mirrors the transcript pair; the session view's chrome is identical. */
+export function sessionScrollLimit(
+  view: SessionDashboardView,
+  terminalWidth: number,
+  height: number,
+  hasUpgradeNotice = false,
+): number {
+  const contentLines = sessionContentLines(view, dashboardContentWidth(terminalWidth)).length
+  // Session chrome is two header rows, the optional upgrade row, two
+  // separators, and controls — the transcript's exact arithmetic.
+  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0))
+  return Math.max(0, contentLines - capacity)
+}
+
+export function moveSessionScroll(
+  view: SessionDashboardView,
+  terminalWidth: number,
+  height: number,
+  current: number,
+  delta: number,
+  hasUpgradeNotice = false,
+): number {
+  const limit = sessionScrollLimit(view, terminalWidth, height, hasUpgradeNotice)
+  // Clamp current first: a resize, a feed apply, or state from an older
+  // controller may leave it beyond the freshly wrapped viewport's end.
+  return Math.max(0, Math.min(limit, Math.min(current, limit) + delta))
+}
+
+function renderSessionView(model: DashboardModel, opts: RenderOpts): string[] {
+  const view = model.view
+  if (view?.kind !== 'session') return []
+  const { color, width, height } = opts
+  const notice = upgradeNoticeLine(model, color, width)
+  const top = [
+    truncate(`${paint('Session', 'bold', color)}  ${displayText(view.slug)}`, width),
+    truncate(
+      `  session ${displayText(view.sessionId)} · ${displayText(view.stream)} · ${
+        view.status === 'open' ? 'live' : 'closed'
+      }`,
+      width,
+    ),
+    ...(notice === undefined ? [] : [notice]),
+  ]
+  const content = sessionContentLines(view, width).map((line) => truncate(line, width))
+  const controls = truncate(
+    paint(
+      view.follow ? DASHBOARD_SESSION_LIVE_LEGEND : DASHBOARD_SESSION_PAUSED_LEGEND,
+      'dim',
+      color,
+    ),
+    width,
+  )
+  if (height !== undefined && height <= 0) return []
+  if (height !== undefined && height <= top.length) return top.slice(0, height)
+  const capacity = height === undefined ? content.length : Math.max(0, height - top.length - 3)
+  // While following, the view pins to the limit so the tail is tracked as new
+  // content lands; otherwise the stored process-local offset rules.
+  const limit = Math.max(0, content.length - capacity)
+  const scroll = view.follow ? limit : Math.max(0, Math.min(limit, view.scroll))
+  return [...top, '', ...viewport(content, capacity, 0, scroll), '', controls].slice(
+    0,
+    height === undefined ? Number.POSITIVE_INFINITY : height,
+  )
+}
+
+// ── The blocked-build resume panel ───────────────────────────────────────────
+//
+// Answering a blocked build is the ONLY thing that can happen while the prompt
+// is open, so the controls region has nothing else to say and the panel takes
+// it over whole. It is a block of rows, not a line: a title, a hint, the
+// blocker being answered, a real multi-line field with a caret, and its own key
+// bindings.
+//
+// The panel is bounded from OUTSIDE (a capacity the frame grants) and from
+// INSIDE (its own per-block row caps), which is what makes graceful degradation
+// a property of the allocation rather than a special case per element.
+
+const FIELD_MAX_ROWS = 6
+const KEYS_MAX_ROWS = 6
+const HINT_MAX_ROWS = 4
+const QUESTION_MAX_ROWS = 4
+/** The caret is an inserted ASCII glyph, not reverse video: `frame-image.ts`
+ * rejects any SGR outside the dashboard's palette, and this file's opening rule
+ * is that stripping escapes must leave the actionable state intact — which a
+ * colour-only cursor does not. */
+const RESUME_CARET = '|'
+
+interface ResumeBinding {
+  key: string
+  /** A shorter key form, used only when it saves a ROW. Dropping the alias
+   * costs a convenience; dropping an action word would cost the panel its
+   * meaning. */
+  keyShort?: string
+  action: string
+}
+
+/**
+ * The panel's key bindings, held as data rather than baked into format strings
+ * so the invariant is visible at the definition site:
+ *
+ *   >>> A rendered binding ALWAYS reads `<key> <action>`, action spelled out.
+ *
+ * Narrow widths are paid for in ROWS — by wrapping a binding across two — never
+ * in words. `Ctrl-J nl` fits where `Ctrl-J newline` does not, and stops naming
+ * the action, which was the entire point of the row.
+ */
+const RESUME_BINDINGS: readonly ResumeBinding[] = [
+  { key: 'Enter', action: 'submit' },
+  { key: 'Ctrl-J or Shift+Enter', keyShort: 'Ctrl-J', action: 'newline' },
+  { key: 'Esc', action: 'cancel' },
+]
+
+/** Lay one set of key forms out at `width`, or `undefined` when some binding
+ * cannot be named at all — its key or its action alone overflows the row. */
+function layoutBindings(
+  bindings: ReadonlyArray<{ key: string; action: string }>,
+  width: number,
+): string[] | undefined {
+  const blocks: string[][] = []
+  let allSingleRow = true
+  for (const binding of bindings) {
+    const single = `${binding.key} ${binding.action}`
+    if (single.length <= width) {
+      blocks.push([single])
+      continue
+    }
+    if (binding.key.length > width || binding.action.length > width) return undefined
+    allSingleRow = false
+    // The continuation indent is the first thing to go; the action word is not.
+    const indent = 2 + binding.action.length <= width ? '  ' : ''
+    blocks.push([binding.key, `${indent}${binding.action}`])
+  }
+  if (!allSingleRow) return blocks.flat()
+  const tokens = blocks.map((block) => block[0]!)
+  // The `Keys: ` prefix earns its columns only when all three still share one
+  // row with it.
+  const prefixed = `Keys: ${tokens.join('  ')}`
+  if (prefixed.length <= width) return [prefixed]
+  return packAtomic(tokens, width)
+}
+
+/**
+ * The keys block: 0…`KEYS_MAX_ROWS` rows naming submit, newline, and cancel.
+ *
+ * Below the width where `newline` fits a row at all the block is dropped
+ * WHOLE. Rendering the other two while silently omitting newline would
+ * misrepresent what the prompt accepts, which is worse than saying nothing.
+ */
+export function resumeKeysRows(width: number): string[] {
+  if (width <= 0) return []
+  const long = layoutBindings(
+    RESUME_BINDINGS.map((b) => ({ key: b.key, action: b.action })),
+    width,
+  )
+  const short = layoutBindings(
+    RESUME_BINDINGS.map((b) => ({ key: b.keyShort ?? b.key, action: b.action })),
+    width,
+  )
+  // Fewer rows wins; a tie goes to the long form, so `Shift+Enter` is named
+  // whenever it is free.
+  const chosen =
+    long === undefined ? short : short !== undefined && short.length < long.length ? short : long
+  return (chosen ?? []).slice(0, KEYS_MAX_ROWS)
+}
+
+/**
+ * The hint's rungs, widest first.
+ *
+ *   >>> EVERY rung states both facts: guidance is optional, and submitting an
+ *   >>> empty field resumes the build without it.
+ *
+ * The rungs shorten the connective tissue, never the content. A future edit
+ * that shortens one past both facts is visible right here.
+ */
+const RESUME_HINTS: readonly string[] = [
+  'Guidance is optional -- Enter on an empty field resumes without it',
+  'Guidance is optional -- Enter alone resumes without it',
+  'Guidance optional; Enter alone resumes without it',
+  'Guidance optional; Enter alone resumes',
+]
+
+/** The widest rung that fits one row, else the narrowest rung WRAPPED — because
+ * wrapping costs rows while shortening cost meaning. Past the row cap the block
+ * is dropped whole: half a sentence states neither fact. */
+export function resumeHintRows(width: number): string[] {
+  if (width <= 0) return []
+  for (const rung of RESUME_HINTS) if (rung.length <= width) return [rung]
+  const wrapped = wrapDisplay(RESUME_HINTS.at(-1)!, width)
+  return wrapped.length <= HINT_MAX_ROWS ? wrapped : []
+}
+
+/**
+ * Rows the controls region may claim.
+ *
+ * Exactly `1` at every height where today's frame has room for only the
+ * legend — so a one-line legend spends exactly what it always did and every
+ * non-prompt frame stays byte-identical — and otherwise at least one body row
+ * is reserved for the build list.
+ */
+export function controlsCapacity(
+  height: number | undefined,
+  topLength: number,
+  separatorCount = 2,
+): number {
+  if (height === undefined) return Number.POSITIVE_INFINITY
+  const below = height - topLength - separatorCount
+  return Math.max(1, Math.min(below - 1, Math.max(4, Math.floor(below / 2))))
+}
+
+/** One field row with the caret inserted at `caret`, painted but never wider
+ * than `width`. The composer reserves a column for the glyph, so the clip is a
+ * no-op for every `width >= 2`; at width 1 it keeps the caret visible. */
+function renderFieldRow(
+  row: string,
+  caret: { offset: number; column: number } | undefined,
+  width: number,
+  color: boolean,
+): string {
+  if (caret === undefined) return truncate(row, width)
+  if (width <= 1) return paint(RESUME_CARET, 'cyan', color)
+  const before = row.slice(0, caret.offset)
+  const after = row.slice(caret.offset)
+  // layoutComposer reserves the caret's one cell. Keep insertion in UTF-16
+  // space and geometry in cell space so a wide cluster is never sliced at a
+  // display column.
+  return truncate(`${before}${paint(RESUME_CARET, 'cyan', color)}${after}`, width)
+}
+
+/**
+ * The panel, assembled and allocated.
+ *
+ * Against a granted capacity, rows go out in this flat order while capacity
+ * remains — the field and its bindings are the LAST things to go and the
+ * blocker text is the first:
+ *
+ *   1. the first field row,
+ *   2. every keys row, in order,
+ *   3. the title row,
+ *   4. every hint row, in order,
+ *   5. question rows, up to `min(desired, QUESTION_MAX_ROWS, ceil(rest / 2))`,
+ *   6. further field rows, up to `FIELD_MAX_ROWS`,
+ *   7. any capacity still unspent, back to questions.
+ *
+ * >>> That order is a PREFIX under WIDTH exactly as it is under capacity. <<<
+ *
+ * A block the granted width cannot represent at all — the keys below content
+ * width 7, the hint below 11 — HALTS the order rather than yielding its rows to
+ * whatever comes next. Without that, a six-column panel printed a truncated
+ * title and a wrapped blocker while naming none of its keys, which is the
+ * degradation order run exactly backwards. Only the field is exempt, because it
+ * outranks every block that can halt: leftover rows still make it taller.
+ */
+export function resumePanel(
+  model: DashboardModel,
+  color: boolean,
+  width: number,
+  capacity: number,
+): string[] {
+  const prompt = model.resumeInput!
+  // A frame that granted NO content columns can render nothing at all. This is
+  // not the same as running out of capacity: `renderDashboard` reserves its
+  // one-column gutter BEFORE calling in, so a one-column terminal arrives here
+  // as width 0, and a field that clamped itself up to one column would emit a
+  // physical row two columns wide. The panel never manufactures a column the
+  // frame did not grant — which is what makes every `fieldWidth` below at
+  // least 1 without a clamp.
+  if (width <= 0) return []
+  const questions = model.builds.find((candidate) => candidate.slug === prompt.slug)?.blockers ?? []
+
+  const title = truncate(
+    paint(paint(`Resume ${displayText(prompt.slug)}`, 'cyan', color), 'bold', color),
+    width,
+  )
+  const hintRows = resumeHintRows(width)
+  const keysRows = resumeKeysRows(width)
+  // Questions go through the NON-truncating wrap: an 80-character URL in a
+  // blocker occupies three rows rather than losing its tail to a `~`. Content
+  // leaves the panel only in whole-row units, which is what the omission
+  // notice accounts for.
+  const questionRows: string[] = []
+  for (const question of questions) {
+    const wrapped = wrapDisplay(question, width - 4)
+    for (const [index, line] of wrapped.entries()) {
+      questionRows.push(
+        truncate(paint(`${index === 0 ? '  ! ' : '    '}${line}`, 'red', color), width),
+      )
+    }
+  }
+  // The indent is dropped before it could eat the field's last column, so this
+  // is at least 1 for every width the early return above lets through.
+  const fieldIndent = width >= 6 ? '  ' : ''
+  const fieldWidth = width - fieldIndent.length
+  const field = layoutComposer(prompt.value, prompt.cursor, fieldWidth)
+
+  let rest = capacity
+  const spend = (want: number): number => {
+    const granted = Math.max(0, Math.min(want, rest))
+    rest -= granted
+    return granted
+  }
+  // Both blocks are built from constants, so an empty one means the width
+  // cannot represent it — never that there was nothing to say. Each halts every
+  // block BELOW it in the priority order.
+  const keysDropped = keysRows.length === 0
+  const hintDropped = keysDropped || hintRows.length === 0
+
+  let fieldGrant = spend(1)
+  const keysGrant = spend(keysRows.length)
+  const titleGrant = keysDropped ? 0 : spend(1)
+  const hintGrant = spend(hintRows.length)
+  let questionGrant = hintDropped
+    ? 0
+    : spend(Math.min(questionRows.length, QUESTION_MAX_ROWS, Math.ceil(Math.max(0, rest) / 2)))
+  // Ungated: the field outranks every block that can halt the order, so rows a
+  // halt freed up are exactly what a taller field is for.
+  fieldGrant += spend(Math.min(field.rows.length, FIELD_MAX_ROWS) - fieldGrant)
+  questionGrant += hintDropped
+    ? 0
+    : spend(Math.min(questionRows.length, QUESTION_MAX_ROWS) - questionGrant)
+
+  const rows: string[] = []
+  if (titleGrant > 0) rows.push(title)
+  for (const line of hintRows.slice(0, hintGrant)) {
+    rows.push(truncate(paint(line, 'dim', color), width))
+  }
+  if (questionGrant > 0) {
+    const shown = questionRows.slice(0, questionGrant)
+    const omitted = questionRows.length - questionGrant
+    // Whole-row loss is accounted for explicitly rather than cut silently. At
+    // zero granted rows the blocker is absent entirely — AC 7's drop order,
+    // with no row left to carry a notice.
+    if (omitted > 0) {
+      shown[shown.length - 1] = overflowNotice(`and ${omitted + 1} more lines`, color, width)
+    }
+    rows.push(...shown)
+  }
+  // The visible window is the granted slice containing the cursor row, biased
+  // to keep that row last while typing.
+  const start = Math.max(
+    0,
+    Math.min(field.cursorRow - fieldGrant + 1, Math.max(0, field.rows.length - fieldGrant)),
+  )
+  for (const [offset, row] of field.rows.slice(start, start + fieldGrant).entries()) {
+    const index = start + offset
+    rows.push(
+      `${fieldIndent}${renderFieldRow(
+        row,
+        index === field.cursorRow
+          ? { offset: field.cursorOffset, column: field.cursorColumn }
+          : undefined,
+        fieldWidth,
+        color,
+      )}`,
+    )
+  }
+  for (const line of keysRows.slice(0, keysGrant)) {
+    rows.push(truncate(paint(line, 'dim', color), width))
+  }
+  return rows
+}
+
+function dashboardControls(
+  model: DashboardModel,
+  color: boolean,
+  width: number,
+  capacity: number,
+): string[] {
+  if (model.abortConfirmation !== undefined) {
+    return [
+      truncate(
+        paint(
+          `Abort ${displayText(model.abortConfirmation.slug)} and delete its workspace, PR, and branches?  Enter confirm  Esc cancel`,
+          'red',
+          color,
+        ),
+        width,
+      ),
+    ]
+  }
+  if (model.resumeInput === undefined) {
+    const legend =
+      model.selection?.kind === 'build'
+        ? (() => {
+            const build = model.builds.find(
+              (candidate) =>
+                candidate.slug === (model.selection?.kind === 'build' ? model.selection.slug : ''),
+            )
+            return build === undefined ? DASHBOARD_BUILD_LEGEND : buildLegend(build, false)
+          })()
+        : model.selection?.kind === 'harvest'
+          ? model.harvest?.action === 'resume'
+            ? DASHBOARD_HARVEST_RESUME_LEGEND
+            : model.harvest?.action === 'acknowledge'
+              ? DASHBOARD_HARVEST_ACKNOWLEDGE_LEGEND
+              : DASHBOARD_HARVEST_LEGEND
+          : DASHBOARD_GLOBAL_LEGEND
+    return [truncate(paint(legend, 'dim', color), width)]
+  }
+  return resumePanel(model, color, width, capacity)
+}
+
+function overflowNotice(text: string, color: boolean, width: number): string {
+  return truncate(paint(`  ... ${text}`, 'dim', color), width)
+}
+
+interface RenderedDashboardRow {
+  selection: DashboardSelection
+  lines: string[]
+}
+
+function flattenRows(rows: readonly RenderedDashboardRow[]): string[] {
+  const lines: string[] = []
+  for (const [index, row] of rows.entries()) {
+    if (index > 0) lines.push('')
+    lines.push(...row.lines)
+  }
+  return lines
+}
+
+function renderDashboardContent(model: DashboardModel, opts: RenderOpts): string[] {
+  if (model.view?.kind === 'detail') return renderDetail(model, opts)
+  if (model.view?.kind === 'transcript') return renderTranscript(model, opts)
+  if (model.view?.kind === 'session') return renderSessionView(model, opts)
+
+  const { color, width, height } = opts
+  const selecting = model.selection !== undefined
+  const globalSelection = { kind: 'global' } as const
+  const marker = selectionMarker(sameSelection(globalSelection, model.selection), selecting, color)
+  const intake = model.drained
+    ? paint('intake OFF', 'yellow', color)
+    : paint('intake ON', 'green', color)
+  // "default" is implicit at the top level — the header is repo-wide state,
+  // while a build row's own `auto merge` token is that build's setting.
+  const autoMergeDefault = model.defaultAutoMerge
+    ? paint('auto merge ON', 'green', color)
+    : paint('auto merge OFF', 'yellow', color)
+  const harvestGate = model.harvestPaused
+    ? paint('harvest OFF', 'yellow', color)
+    : paint('harvest ON', 'green', color)
+  const repositoryPause = model.repositoryPaused
+    ? paint('repository PAUSED', 'yellow', color)
+    : undefined
+  const summary = truncate(
+    `${marker}${[
+      paint('Autobuild', 'bold', color),
+      displayText(basename(model.repo)),
+      paint(
+        `queue ${model.queued} | active ${model.active.current}/${model.active.limit} | ` +
+          `observations ${model.observations.current}/${model.observations.limit}`,
+        'dim',
+        color,
+      ),
+    ].join('  ')}`,
+    width,
+  )
+  // The global controls live on their own mandatory line. Its fixed blank
+  // marker prefix aligns the first toggle with the title while keeping the
+  // selection lane empty.
+  const toggles = truncate(
+    `  ${[intake, autoMergeDefault, harvestGate, repositoryPause]
+      .filter((token): token is string => token !== undefined)
+      .join('  ')}`,
+    width,
+  )
+  const upgradeNotice = upgradeNoticeLine(model, color, width)
+  // Warnings are conditional chrome, not a reserved log slot. Each notice is
+  // capped to the configured three-row content preview, followed by the
+  // overflow/count notice when content remains; notices are not dropped by
+  // count. The resulting rows join `top`, so `top.slice` limits what short
+  // frames paint and `controlsCapacity` budgets proportionally fewer controls
+  // rows as warnings increase `top.length`.
+  const warnings = warningRows(model.warningLines ?? [], width)
+  const top = [
+    summary,
+    toggles,
+    ...(upgradeNotice === undefined ? [] : [upgradeNotice]),
+    ...warnings,
+  ]
+  // Both structural separators are fixed frame chrome: one between the
+  // completed top section and body, and one between body and controls.
+  const separatorCount = 2
+  const controls = dashboardControls(
+    model,
+    color,
+    width,
+    controlsCapacity(height, top.length, separatorCount),
+  )
+
+  // No paintable height at all (a 1-row screen — see `paintableRows`): paint
+  // nothing. Its trailing newline would scroll a single line off even on the
+  // alternate display, which is worse than an empty region. The two mandatory
+  // header lines outrank warning/body/controls as height disappears.
+  if (height !== undefined && height <= 0) return []
+  if (height !== undefined && height <= top.length) return top.slice(0, height)
+  // Once the complete top section fits, retain controls before spending rows
+  // on body content. Chrome-only remainder is spent on the two structural
+  // separators; a visible body is not admitted until both gaps fit.
+  if (height !== undefined && height <= top.length + separatorCount + controls.length) {
+    const available = height - top.length
+    if (available <= controls.length) return [...top, ...controls.slice(0, available)]
+    return [...top, ...Array.from({ length: available - controls.length }, () => ''), ...controls]
+  }
+
+  const widths = frameWidths(model.builds, model.harvest)
+  const rows: RenderedDashboardRow[] = dashboardSelections(model).flatMap(
+    (selection): RenderedDashboardRow[] => {
+      // The global selection is fixed frame chrome above the body. It still
+      // participates in navigation/reconciliation, but never enters viewport
+      // clamping because its header is always visible.
+      if (selection.kind === 'global') return []
+      if (selection.kind === 'harvest') {
+        return [
+          {
+            selection,
+            lines: renderHarvest(
+              model.harvest!,
+              opts,
+              widths,
+              sameSelection(selection, model.selection),
+              selecting,
+            ),
+          },
+        ]
+      }
+      const build = model.builds.find((candidate) => candidate.slug === selection.slug)!
+      return [
+        {
+          selection,
+          lines: renderBuild(
+            build,
+            model.repositoryPaused,
+            opts,
+            widths,
+            sameSelection(selection, model.selection),
+            selecting,
+          ),
+        },
+      ]
+    },
+  )
+
+  // Both frame composers derive their body budget from `controls.length`, so a
+  // one-line legend reduces to exactly today's arithmetic and a prompt panel
+  // grows into rows the body gives up.
+  const bodyBudget =
+    height === undefined
+      ? Number.POSITIVE_INFINITY
+      : Math.max(0, height - top.length - separatorCount - controls.length)
+  let body: string[]
+  if (rows.length === 0) {
+    body = bodyBudget >= 1 ? [truncate(paint('  no active builds', 'dim', color), width)] : []
+  } else {
+    const allRows = flattenRows(rows)
+    if (allRows.length <= bodyBudget) {
+      body = allRows
+    } else if (bodyBudget <= 0) {
+      body = []
+    } else {
+      const selectedIndex = Math.max(
+        0,
+        rows.findIndex((row) => sameSelection(row.selection, model.selection)),
+      )
+      const prefix = [0]
+      for (const row of rows) prefix.push(prefix.at(-1)! + row.lines.length)
+
+      // Brute force is intentional and tiny (dashboard row counts are bounded
+      // by operator workload): choose the largest contiguous whole-row window
+      // containing selection, with explicit omission notices. Harvest and
+      // builds participate identically.
+      let best: { start: number; end: number; count: number; used: number } | undefined
+      for (let start = 0; start <= selectedIndex; start += 1) {
+        for (let end = selectedIndex; end < rows.length; end += 1) {
+          const rowLines = prefix[end + 1]! - prefix[start]! + (end - start)
+          const notices = (start > 0 ? 1 : 0) + (end < rows.length - 1 ? 1 : 0)
+          const used = rowLines + notices
+          if (used > bodyBudget) continue
+          const count = end - start + 1
+          if (
+            best === undefined ||
+            count > best.count ||
+            (count === best.count && used > best.used)
+          ) {
+            best = { start, end, count, used }
+          }
+        }
+      }
+
+      if (best !== undefined) {
+        body = []
+        if (best.start > 0) {
+          body.push(overflowNotice(`${best.start} more above`, color, width))
+        }
+        body.push(...flattenRows(rows.slice(best.start, best.end + 1)))
+        const below = rows.length - best.end - 1
+        if (below > 0) {
+          body.push(overflowNotice(`and ${below} more below`, color, width))
+        }
+      } else {
+        // A detailed selected row itself cannot fit. Keep its selectable
+        // identity visible, then spend remaining rows on detail and omission.
+        const selectedLines = rows[selectedIndex]!.lines
+        const above = selectedIndex
+        const below = rows.length - selectedIndex - 1
+        let noticeLines = 0
+        if (bodyBudget > 1 && (above > 0 || below > 0)) {
+          noticeLines = bodyBudget > 2 && above > 0 && below > 0 ? 2 : 1
+        }
+        const detailCapacity = Math.max(1, bodyBudget - noticeLines)
+        body = []
+        if (noticeLines === 2 && above > 0) {
+          body.push(overflowNotice(`${above} more above`, color, width))
+        }
+        body.push(...selectedLines.slice(0, detailCapacity))
+        if (noticeLines === 2 && below > 0) {
+          body.push(overflowNotice(`and ${below} more below`, color, width))
+        } else if (noticeLines === 1) {
+          body.push(
+            overflowNotice(
+              above > 0 && below > 0
+                ? `${above} above, ${below} below`
+                : above > 0
+                  ? `${above} more above`
+                  : `and ${below} more below`,
+              color,
+              width,
+            ),
+          )
+        }
+        body = body.slice(0, bodyBudget)
+      }
+    }
+  }
+
+  // Both blanks are structural frame chrome, independent of warning/upgrade
+  // content, and are charged exactly once in the body budget above.
+  return [...top, '', ...body, '', ...controls]
+}
+
+/** Render the dashboard inside a fixed one-column horizontal gutter.
+ *
+ * All composition happens against the inset content width so wrapping,
+ * truncation, and right-pinning share one geometry. Prefixing only after the
+ * frame is composed preserves its logical line count (including truly blank
+ * separators) and therefore leaves vertical budgeting unchanged. */
+export function renderDashboard(model: DashboardModel, opts: RenderOpts): string[] {
+  const terminalWidth = Math.max(0, opts.width)
+  const contentWidth = dashboardContentWidth(terminalWidth)
+  const lines = renderDashboardContent(model, { ...opts, width: contentWidth })
+  const leftGutter = terminalWidth > 0 ? ' ' : ''
+
+  return lines.map((line) => (line === '' ? '' : `${leftGutter}${line}`))
+}