quoxcli 0.4.0 → 0.6.0

package/lib/render/planBrief.js

@@ -0,0 +1,614 @@
+/**
+ * Pure renderers for the QuoxPlan one-screen views (QUOXPLAN-TERMINAL):
+ * `quox plan brief` / bare `quox plan`, the capped `quox plan focus`, and the
+ * change ticker for `quox plan watch`. No network, no process globals beyond
+ * a width fallback, so every function here is unit-testable on a fixture.
+ *
+ * Input shape for renderBrief/diffBriefs is the server's brief payload
+ * (GET /api/v1/roadmaps/:id/brief, pinned contract 2026-11-08).
+ *
+ * Layout rule (same as plan.js): pad and truncate the PLAIN text first,
+ * colour it last. Rows are built as segment lists [text, colourFn] and fitted
+ * to the terminal width by fit(), which cuts plain text and only then applies
+ * chalk, so escape bytes never count toward column width.
+ *
+ * Colour rule (owner): content is never dim. Dim is for chrome only
+ * (legends, separators, hints). Ids cyan, decisions magenta, blocked red,
+ * phase bars green on dim.
+ */
+
+import chalk from 'chalk';
+
+// ── glyphs (single source for plan.js too) ───────────────────────────────
+
+export const STATUS_GLYPH = {
+  NOT_STARTED: { glyph: '◇', color: chalk.dim, word: 'not started' },
+  IN_PROGRESS: { glyph: '⬗', color: chalk.yellow, word: 'in progress' },
+  BLOCKED: { glyph: '◆', color: chalk.red, word: 'blocked' },
+  DECISION_NEEDED: { glyph: '◈', color: chalk.magenta, word: 'decision' },
+  // ✔, not ◆: COMPLETE used to share ◆ with BLOCKED, so the only difference
+  // between "done" and "stuck" was red vs dim. Distinct shape now.
+  COMPLETE: { glyph: '✔', color: chalk.dim, word: 'complete' },
+};
+
+export function statusGlyph(status) {
+  return STATUS_GLYPH[status] || { glyph: '◇', color: chalk.dim, word: String(status || 'unknown').toLowerCase() };
+}
+
+export const STATUS_LEGEND = '◇ not started  ⬗ in progress  ◈ decision needed  ◆ blocked  ✔ complete';
+
+// ── text helpers ─────────────────────────────────────────────────────────
+
+export function pad(value, n) {
+  const s = String(value ?? '');
+  return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+
+export function padStart(value, n) {
+  const s = String(value ?? '');
+  return s.length >= n ? s : ' '.repeat(n - s.length) + s;
+}
+
+export function truncate(value, n) {
+  const s = String(value ?? '');
+  if (n <= 0) return '';
+  if (s.length <= n) return s;
+  return s.slice(0, Math.max(0, n - 1)) + '…';
+}
+
+const plain = (s) => s;
+
+/**
+ * Fit a row of [text, colourFn] segments into `width` visible columns.
+ * Truncates the plain text (adding … at the cut) and colours afterwards.
+ */
+export function fit(segments, width) {
+  let used = 0;
+  let out = '';
+  for (const [rawText, color = plain] of segments) {
+    const text = String(rawText ?? '');
+    if (!text) continue;
+    const room = width - used;
+    if (room <= 0) break;
+    if (text.length <= room) {
+      out += color(text);
+      used += text.length;
+    } else {
+      out += color(truncate(text, room));
+      used = width;
+      break;
+    }
+  }
+  return out.replace(/ +$/, '');
+}
+
+/** Terminal width, fallback 100 when not a TTY (pipes, CI, tests). */
+export function termWidth(stream = process.stdout) {
+  const c = stream && stream.columns;
+  return Number.isInteger(c) && c > 20 ? c : 100;
+}
+
+/**
+ * Short relative age: now, 5m, 2h, 3d, 5w, 2y. Anything under 14 days is
+ * shown in days so "last week" reads as 9d, not 1w.
+ */
+export function relativeAge(iso, now = Date.now()) {
+  if (!iso) return '?';
+  const t = typeof iso === 'number' ? iso : Date.parse(iso);
+  if (!Number.isFinite(t)) return '?';
+  const s = Math.floor((now - t) / 1000);
+  if (s < 60) return 'now';
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  const d = Math.floor(h / 24);
+  if (d < 14) return `${d}d`;
+  const w = Math.floor(d / 7);
+  if (w < 52) return `${w}w`;
+  return `${Math.floor(d / 365)}y`;
+}
+
+/** "Sun 8 Nov 2026, 16:35 UTC". Returns the input unchanged if unparseable. */
+export function humanDate(iso) {
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return String(iso ?? '');
+  const d = new Date(t);
+  const days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const hh = String(d.getUTCHours()).padStart(2, '0');
+  const mm = String(d.getUTCMinutes()).padStart(2, '0');
+  return `${days[d.getUTCDay()]} ${d.getUTCDate()} ${months[d.getUTCMonth()]} ${d.getUTCFullYear()}, ${hh}:${mm} UTC`;
+}
+
+function hhmm(iso) {
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return '--:--';
+  const d = new Date(t);
+  return `${String(d.getUTCHours()).padStart(2, '0')}:${String(d.getUTCMinutes()).padStart(2, '0')}`;
+}
+
+/** Id column width from the data, so ids longer than 18 chars never push columns. */
+export function idWidth(items, { min = 8, max = 32 } = {}) {
+  let w = min;
+  for (const it of items || []) {
+    const id = it && (typeof it === 'string' ? it : it.id);
+    if (id) w = Math.max(w, String(id).length);
+  }
+  return Math.min(w, max);
+}
+
+/** Phase mini-bar: 5 cells, green filled on dim empty, e.g. ■■■□□. */
+export function miniBar(done, total, cells = 5) {
+  if (!total || total <= 0) return [['·'.repeat(cells), chalk.dim]];
+  const filled = Math.max(0, Math.min(cells, Math.round((done / total) * cells)));
+  return [['■'.repeat(filled), chalk.green], ['□'.repeat(cells - filled), chalk.dim]];
+}
+
+function wideBar(done, total, cells) {
+  if (!total || total <= 0) return [['░'.repeat(cells), chalk.dim]];
+  const filled = Math.max(0, Math.min(cells, Math.round((done / total) * cells)));
+  return [['█'.repeat(filled), chalk.green], ['░'.repeat(cells - filled), chalk.dim]];
+}
+
+const BAR_ORDER = [
+  ['COMPLETE', '█', chalk.green],
+  ['IN_PROGRESS', '█', chalk.yellow],
+  ['DECISION_NEEDED', '█', chalk.magenta],
+  ['BLOCKED', '█', chalk.red],
+  ['NOT_STARTED', '░', chalk.dim],
+];
+
+/** Stacked status bar (largest-remainder allocation so cells always sum to `cells`). */
+function statusBar(byStatus, cells) {
+  const total = BAR_ORDER.reduce((n, [k]) => n + (byStatus[k] || 0), 0);
+  if (!total) return [['░'.repeat(cells), chalk.dim]];
+  const raw = BAR_ORDER.map(([k]) => ((byStatus[k] || 0) / total) * cells);
+  const alloc = raw.map(Math.floor);
+  let left = cells - alloc.reduce((a, b) => a + b, 0);
+  const order = raw.map((r, i) => [r - Math.floor(r), i]).sort((a, b) => b[0] - a[0]);
+  for (let k = 0; left > 0 && k < order.length; k++, left--) alloc[order[k][1]]++;
+  return BAR_ORDER.map(([, ch, color], i) => [ch.repeat(alloc[i]), color]);
+}
+
+// ── brief ────────────────────────────────────────────────────────────────
+
+export const BRIEF_CAPS = { needsYou: 5, unblockers: 3, recent: 4, staleOldest: 5 };
+
+const LEAD = 5; // "  12 " rank column; non-ranked rows indent the same so ids align
+
+function glyphSeg(status) {
+  const g = statusGlyph(status);
+  return [g.glyph, g.color.bold];
+}
+
+/**
+ * Render the brief payload as one screen (<= 40 lines at the defaults).
+ * opts: { width, now, top, days }
+ */
+export function renderBrief(brief, opts = {}) {
+  const width = opts.width || 100;
+  const now = opts.now ?? Date.now();
+  const days = opts.days || 7;
+  const b = brief || {};
+  const totals = b.totals || {};
+  const byStatus = totals.by_status || {};
+  const top = b.top || [];
+  const needs = b.needs_you || [];
+  const recent = b.recent || [];
+  const unblockers = b.unblockers || [];
+  const stale = b.stale || { count: 0, oldest: [] };
+
+  const needsShown = needs.slice(0, BRIEF_CAPS.needsYou);
+  const unblockShown = unblockers.slice(0, BRIEF_CAPS.unblockers);
+  const recentShown = recent.slice(0, BRIEF_CAPS.recent);
+
+  const idW = idWidth([...top, ...needsShown, ...unblockShown, ...recentShown]);
+  const countW = Math.max(3, ...top.map((s) => `${s.phases_done ?? 0}/${s.phases_total ?? 0}`.length));
+  const depsLen = Math.max(0, ...top.map((s) => depsText(s.unmet_deps).length));
+  const depsReserve = depsLen ? depsLen + 2 : 0;
+  // lead + glyph + space + id + 2 + [name] + 2 + bar(5) + 1 + count + 2 + age(3)
+  const fixed = LEAD + 2 + idW + 2 + 2 + 5 + 1 + countW + 2 + 3;
+  const nameW = Math.max(12, Math.min(48, width - fixed - depsReserve));
+
+  const lines = [];
+
+  // header card
+  const topN = opts.top || top.length;
+  const right = `as of ${hhmm(b.generated_at)} UTC  ·  top ${topN}  ·  moved = last ${days}d`;
+  const left = `  QUOXPLAN  ${b.roadmap_id || ''}`;
+  const gap = Math.max(2, width - left.length - right.length);
+  lines.push(fit([['  QUOXPLAN', chalk.cyan.bold], ['  '], [b.roadmap_id || '', chalk.bold], [' '.repeat(gap)], [right, chalk.dim]], width));
+
+  const barW = Math.max(10, Math.min(30, width - 30));
+  lines.push(fit([['  streams  ', chalk.dim], ...statusBar(byStatus, barW), ['  '], [String(totals.streams ?? 0), chalk.bold], [' streams']], width));
+  const legend = [];
+  for (const k of ['COMPLETE', 'IN_PROGRESS', 'BLOCKED', 'DECISION_NEEDED', 'NOT_STARTED']) {
+    const g = statusGlyph(k);
+    legend.push([g.glyph, g.color.bold], [` ${byStatus[k] || 0} ${g.word}`], ['   ']);
+  }
+  lines.push(fit([['           '], ...legend], width));
+  const pd = totals.phases_done || 0;
+  const pt = totals.phases_total || 0;
+  const pct = pt ? Math.round((pd / pt) * 100) : 0;
+  lines.push(fit([['  phases   ', chalk.dim], ...wideBar(pd, pt, barW), ['  '], [`${pct}%`, chalk.bold], [`  ${pd} of ${pt} done`], ['  (all streams)', chalk.dim]], width));
+  lines.push('');
+
+  // top priorities
+  lines.push(fit([['  TOP PRIORITIES', chalk.cyan.bold], ['   not complete, by priority', chalk.dim]], width));
+  if (top.length === 0) lines.push(fit([['     Nothing open. Every top-level stream is complete.', chalk.green]], width));
+  top.forEach((s, i) => {
+    const count = `${s.phases_done ?? 0}/${s.phases_total ?? 0}`;
+    const deps = depsText(s.unmet_deps);
+    lines.push(fit([
+      [padStart(i + 1, 4) + ' ', chalk.bold],
+      glyphSeg(s.status), [' '],
+      [pad(truncate(s.id, idW), idW), chalk.cyan], ['  '],
+      [pad(truncate(s.name, nameW), nameW)], ['  '],
+      ...miniBar(s.phases_done, s.phases_total), [' '],
+      [padStart(count, countW)], ['  '],
+      [padStart(relativeAge(s.last_activity_at, now), 3)],
+      ...(deps ? [['  '], [deps, chalk.yellow]] : []),
+    ], width));
+  });
+  lines.push('');
+
+  // needs you
+  const needsTotal = b.needs_you_total ?? needs.length;
+  if (needsTotal === 0) {
+    lines.push(fit([['  NEEDS YOU', chalk.cyan.bold], ['   nothing blocked or waiting on a decision', chalk.green]], width));
+  } else {
+    lines.push(fit([
+      ['  NEEDS YOU', chalk.cyan.bold], ['  '], [String(needsTotal), chalk.red.bold],
+      [needsTotal > needsShown.length ? `   showing ${needsShown.length}, all: quox plan focus` : '   blocked or waiting on a decision', chalk.dim],
+    ], width));
+    const nDeps = Math.max(0, ...needsShown.map((s) => depsText(s.unmet_deps).length));
+    const nNameW = Math.max(12, Math.min(48, width - (LEAD + 2 + idW + 2 + 2 + 8 + 2 + 3 + 2 + 3) - (nDeps ? nDeps + 2 : 0)));
+    for (const s of needsShown) {
+      const isDecision = s.status === 'DECISION_NEEDED';
+      const deps = depsText(s.unmet_deps);
+      lines.push(fit([
+        [' '.repeat(LEAD)], glyphSeg(s.status), [' '],
+        [pad(truncate(s.id, idW), idW), chalk.cyan], ['  '],
+        [pad(truncate(s.name, nNameW), nNameW)], ['  '],
+        [pad(isDecision ? 'DECISION' : 'BLOCKED', 8), isDecision ? chalk.magenta.bold : chalk.red.bold], ['  '],
+        [pad(`T${s.tier ?? '?'}`, 3)], ['  '],
+        [padStart(relativeAge(s.last_activity_at, now), 3)],
+        ...(deps ? [['  '], [deps, chalk.yellow]] : []),
+      ], width));
+      const note = s.latest_note;
+      lines.push(fit(note && note.body
+        ? [[' '.repeat(LEAD + 2) + '└ ', chalk.dim], [`${relativeAge(note.created_at, now)}  `, chalk.dim], [oneLine(note.body)]]
+        : [[' '.repeat(LEAD + 2) + '└ no notes yet', chalk.dim]], width));
+    }
+  }
+
+  // unblock these first
+  if (unblockShown.length) {
+    lines.push('');
+    lines.push(fit([['  UNBLOCK THESE FIRST', chalk.cyan.bold], ['   finishing one frees the streams waiting on it', chalk.dim]], width));
+    const freesOf = (s) => (Number.isFinite(s.unblocks_total) ? s.unblocks_total : (s.unblocks || []).length);
+    const uDeps = Math.max(0, ...unblockShown.map((s) => depsText(s.unmet_deps).length));
+    const freesW = Math.max(...unblockShown.map((s) => `frees ${freesOf(s)}: `.length));
+    // leave at least 20 columns for the freed ids and room for "after X"
+    const uNameW = Math.max(12, Math.min(40, width - (LEAD + 2 + idW + 2 + 2) - freesW - 20 - (uDeps ? uDeps + 2 : 0)));
+    for (const s of unblockShown) {
+      // unblocks_chain (server, when present) names every stream the chain frees,
+      // so the count and the names agree; older servers send only the direct list.
+      const list = Array.isArray(s.unblocks_chain) && s.unblocks_chain.length ? s.unblocks_chain : (s.unblocks || []);
+      // unblocks_total = every open stream freed through the downstream chain
+      // (server 984a930); older servers only send the direct list.
+      const frees = freesOf(s);
+      const deps = depsText(s.unmet_deps);
+      const head = LEAD + 2 + idW + 2 + uNameW + 2 + `frees ${frees}: `.length;
+      const room = Math.max(8, width - head - (deps ? deps.length + 2 : 0));
+      lines.push(fit([
+        [' '.repeat(LEAD)], glyphSeg(s.status), [' '],
+        [pad(truncate(s.id, idW), idW), chalk.cyan], ['  '],
+        [pad(truncate(s.name, uNameW), uNameW)], ['  '],
+        ['frees '], [String(frees), chalk.bold], [': '], [truncate(list.join(', '), room), chalk.cyan],
+        ...(deps ? [['  '], [deps, chalk.yellow]] : []),
+      ], width));
+    }
+  }
+  lines.push('');
+
+  // moved this week
+  const recentTotal = b.recent_total ?? recent.length;
+  const movedTitle = days === 7 ? '  MOVED THIS WEEK' : `  MOVED IN THE LAST ${days} DAYS`;
+  if (recentTotal === 0) {
+    lines.push(fit([[movedTitle, chalk.cyan.bold], ['   nothing moved', chalk.yellow]], width));
+  } else {
+    lines.push(fit([
+      [movedTitle, chalk.cyan.bold], ['  '], [String(recentTotal), chalk.bold],
+      [recentTotal > recentShown.length ? ` streams active, newest ${recentShown.length} shown` : ' streams active, newest first', chalk.dim],
+    ], width));
+    const evW = Math.max(...recentShown.map((s) => `${s.events ?? 0} events`.length));
+    const rNameW = Math.max(12, Math.min(48, width - (LEAD + 2 + idW + 2 + 2 + evW + 2 + 3)));
+    for (const s of recentShown) {
+      const ev = `${s.events ?? 0} event${s.events === 1 ? '' : 's'}`;
+      lines.push(fit([
+        [' '.repeat(LEAD)], glyphSeg(s.status), [' '],
+        [pad(truncate(s.id, idW), idW), chalk.cyan], ['  '],
+        [pad(truncate(s.name, rNameW), rNameW)], ['  '],
+        [padStart(ev, evW)], ['  '],
+        [padStart(relativeAge(s.last_activity_at, now), 3)],
+      ], width));
+    }
+  }
+  lines.push('');
+
+  // stale
+  if (stale.count > 0) {
+    const segs = [['  STALE', chalk.yellow.bold], ['  '], [String(stale.count), chalk.bold], [` in-progress stream${stale.count === 1 ? '' : 's'} quiet >14d`]];
+    const oldest = (stale.oldest || []).slice(0, BRIEF_CAPS.staleOldest);
+    if (oldest.length) {
+      let used = segs.reduce((n, [t]) => n + t.length, 0) + '   oldest: '.length;
+      const items = [];
+      for (const o of oldest) {
+        const txt = `${o.id} ${relativeAge(o.last_activity_at, now)}`;
+        if (used + txt.length + 2 > width && items.length) break;
+        items.push(txt);
+        used += txt.length + 2;
+      }
+      segs.push(['   oldest: ', chalk.dim]);
+      items.forEach((t, i) => {
+        const [id, age] = t.split(' ');
+        segs.push([id, chalk.cyan], [` ${age}`], ...(i < items.length - 1 ? [[', ', chalk.dim]] : []));
+      });
+    }
+    lines.push(fit(segs, width));
+  } else {
+    lines.push(fit([['  STALE', chalk.green.bold], ['  none, every in-progress stream moved in the last 14 days', chalk.green]], width));
+  }
+
+  lines.push(fit([['  next  ', chalk.dim], ['quox plan show <id>', chalk.cyan], ['  ·  ', chalk.dim], ['quox plan focus --all', chalk.cyan], ['  ·  ', chalk.dim], ['quox plan watch', chalk.cyan]], width));
+  return lines;
+}
+
+/** Compact unmet-deps label: "after VAULT +1" (first id capped at 14 chars). */
+export function depsText(deps) {
+  if (!deps || deps.length === 0) return '';
+  return `after ${truncate(deps[0], 14)}${deps.length > 1 ? ` +${deps.length - 1}` : ''}`;
+}
+
+function oneLine(text) {
+  return String(text || '').replace(/\s+/g, ' ').trim();
+}
+
+// ── capped focus ─────────────────────────────────────────────────────────
+
+export const FOCUS_IN_FLIGHT_CAP = 12;
+
+const NEEDS_STATUSES = new Set(['BLOCKED', 'DECISION_NEEDED']);
+
+function byTierThenPriority(a, b) {
+  return (a.tier ?? 99) - (b.tier ?? 99) || (a.priority ?? 1e9) - (b.priority ?? 1e9) || String(a.id).localeCompare(String(b.id));
+}
+
+/**
+ * The capped focus lens from the existing `?lens=focus` payload:
+ * Needs you (every blocked + decision, any level), In flight (top 12 of the
+ * rest by priority), and a one-line stale count. opts: { width, now, roadmapId, cap }.
+ */
+export function renderFocusCapped(payload, opts = {}) {
+  const width = opts.width || 100;
+  const now = opts.now ?? Date.now();
+  const cap = opts.cap || FOCUS_IN_FLIGHT_CAP;
+  const streams = (payload && payload.streams) || [];
+
+  const needs = [];
+  const rest = [];
+  // Substreams count everywhere (needs, in flight, stale) so focus agrees with
+  // the brief, whose totals cover every stream in the roadmap.
+  for (const s of streams) {
+    if (NEEDS_STATUSES.has(s.status)) needs.push({ ...s, parent: null });
+    else rest.push({ ...s, parent: null });
+    for (const sub of s.substreams || []) {
+      if (NEEDS_STATUSES.has(sub.status)) needs.push({ ...sub, parent: s.id });
+      else if (sub.status === 'IN_PROGRESS') rest.push({ ...sub, parent: s.id });
+    }
+  }
+  needs.sort(byTierThenPriority);
+  rest.sort((a, b) => (a.priority ?? 1e9) - (b.priority ?? 1e9));
+  const inFlight = rest.slice(0, cap);
+  const staleCount = rest.filter((s) => (s.focus_reasons || []).includes('stale')).length;
+
+  const idW = idWidth([...needs, ...inFlight]);
+  const nameW = Math.max(12, Math.min(48, width - (LEAD + 2 + idW + 2 + 2 + 8 + 2 + 3 + 2 + 3) - 14));
+
+  const lines = [];
+  lines.push(fit([['  QUOXPLAN', chalk.cyan.bold], ['  '], [opts.roadmapId || payload?.roadmap_id || '', chalk.bold], ['  focus', chalk.dim]], width));
+  lines.push('');
+
+  if (needs.length === 0) {
+    lines.push(fit([['  NEEDS YOU', chalk.cyan.bold], ['   nothing blocked or waiting on a decision', chalk.green]], width));
+  } else {
+    lines.push(fit([['  NEEDS YOU', chalk.cyan.bold], ['  '], [String(needs.length), chalk.red.bold], ['   blocked or waiting on a decision', chalk.dim]], width));
+    for (const s of needs) {
+      const isDecision = s.status === 'DECISION_NEEDED';
+      lines.push(fit([
+        [' '.repeat(LEAD)], glyphSeg(s.status), [' '],
+        [pad(truncate(s.id, idW), idW), chalk.cyan], ['  '],
+        [pad(truncate(s.name, nameW), nameW)], ['  '],
+        [pad(isDecision ? 'DECISION' : 'BLOCKED', 8), isDecision ? chalk.magenta.bold : chalk.red.bold], ['  '],
+        [pad(`T${s.tier ?? '?'}`, 3)], ['  '],
+        [padStart(relativeAge(s.updated_at, now), 3)],
+        ...(s.parent ? [['  in ', chalk.dim], [s.parent, chalk.cyan]] : []),
+      ], width));
+    }
+  }
+  lines.push('');
+
+  if (inFlight.length === 0) {
+    lines.push(fit([['  IN FLIGHT', chalk.cyan.bold], ['   nothing in progress', chalk.dim]], width));
+  } else {
+    lines.push(fit([
+      ['  IN FLIGHT', chalk.cyan.bold], ['  '], [String(inFlight.length), chalk.bold],
+      [rest.length > inFlight.length ? ` of ${rest.length} by priority` : ' by priority', chalk.dim],
+    ], width));
+    for (const s of inFlight) {
+      const reasons = (s.focus_reasons || []).filter((r) => r !== 'in_progress');
+      lines.push(fit([
+        [padStart(`#${s.priority ?? '?'}`, LEAD - 1) + ' ', chalk.bold], glyphSeg(s.status), [' '],
+        [pad(truncate(s.id, idW), idW), chalk.cyan], ['  '],
+        [pad(truncate(s.name, nameW), nameW)], ['  '],
+        [pad('', 8)], ['  '],
+        [pad(`T${s.tier ?? '?'}`, 3)], ['  '],
+        [padStart(relativeAge(s.updated_at, now), 3)],
+        ...(s.parent ? [['  in ', chalk.dim], [s.parent, chalk.cyan]] : []),
+        ...reasons.flatMap((r) => [['  '], [r, r === 'stale' ? chalk.yellow : chalk.cyan]]),
+      ], width));
+    }
+  }
+  lines.push('');
+
+  if (staleCount > 0) {
+    lines.push(fit([['  STALE', chalk.yellow.bold], ['  '], [String(staleCount), chalk.bold], [` in-progress stream${staleCount === 1 ? '' : 's'} quiet >14d`], ['   full list: quox plan focus --all', chalk.dim]], width));
+  }
+  lines.push(fit([['  ' + STATUS_LEGEND, chalk.dim]], width));
+  return lines;
+}
+
+// ── watch: diff successive briefs ────────────────────────────────────────
+
+function indexBrief(brief) {
+  const map = new Map();
+  const b = brief || {};
+  const put = (s, extra) => {
+    if (!s || !s.id) return;
+    const cur = map.get(s.id) || { id: s.id };
+    for (const [k, v] of Object.entries({ ...s, ...extra })) if (v !== undefined) cur[k] = v;
+    map.set(s.id, cur);
+  };
+  for (const s of b.top || []) put(s);
+  for (const s of b.needs_you || []) put(s);
+  for (const s of b.recent || []) put(s, { events: s.events });
+  for (const s of b.unblockers || []) put(s);
+  return map;
+}
+
+/**
+ * Changes between two brief payloads: status flips, phase ticks, new notes,
+ * and fresh activity. Returns [{ kind, id, name, from, to, text }].
+ * Kinds: 'status' | 'phase' | 'note' | 'activity'.
+ */
+export function diffBriefs(prev, next) {
+  if (!prev || !next) return [];
+  const a = indexBrief(prev);
+  const b = indexBrief(next);
+  const changes = [];
+  let attributedPhases = 0;
+
+  for (const [id, n] of b) {
+    const p = a.get(id);
+    if (!p) continue;
+    let changed = false;
+    if (p.status && n.status && p.status !== n.status) {
+      changes.push({ kind: 'status', id, name: n.name, from: p.status, to: n.status });
+      changed = true;
+    }
+    if (Number.isFinite(p.phases_done) && Number.isFinite(n.phases_done) && p.phases_done !== n.phases_done) {
+      changes.push({ kind: 'phase', id, name: n.name, from: p.phases_done, to: n.phases_done, total: n.phases_total });
+      attributedPhases += n.phases_done - p.phases_done;
+      changed = true;
+    }
+    const pn = p.latest_note;
+    const nn = n.latest_note;
+    if (nn && nn.created_at && (!pn || pn.created_at !== nn.created_at) && (!pn || Date.parse(nn.created_at) >= Date.parse(pn.created_at))) {
+      changes.push({ kind: 'note', id, name: n.name, text: oneLine(nn.body) });
+      changed = true;
+    }
+    if (!changed && Number.isFinite(n.events) && Number.isFinite(p.events) && n.events > p.events) {
+      changes.push({ kind: 'activity', id, name: n.name, from: p.events, to: n.events });
+    }
+  }
+
+  // Streams that newly need you without being visible before.
+  const prevNeeds = new Set((prev.needs_you || []).map((s) => s.id));
+  for (const s of next.needs_you || []) {
+    if (!prevNeeds.has(s.id) && !a.has(s.id)) {
+      changes.push({ kind: 'status', id: s.id, name: s.name, from: null, to: s.status });
+    }
+  }
+  // New streams in the recent window.
+  for (const s of next.recent || []) {
+    if (!a.has(s.id) && !changes.some((c) => c.id === s.id)) {
+      changes.push({ kind: 'activity', id: s.id, name: s.name, from: 0, to: s.events });
+    }
+  }
+  // Roadmap-wide phase ticks we could not pin on a visible stream.
+  const pd = (next.totals?.phases_done ?? 0) - (prev.totals?.phases_done ?? 0);
+  if (pd - attributedPhases !== 0 && prev.totals && next.totals) {
+    changes.push({ kind: 'phase', id: null, name: null, from: prev.totals.phases_done, to: next.totals.phases_done, total: next.totals.phases_total, delta: pd - attributedPhases });
+  }
+  return changes;
+}
+
+/** One ticker line for a change. `at` is the ISO time it was seen. */
+export function renderChange(change, { at, width = 100 } = {}) {
+  const t = [`  ${hhmm(at)}  `, chalk.dim];
+  const id = change.id ? [[change.id, chalk.cyan], ['  ']] : [];
+  switch (change.kind) {
+    case 'status': {
+      const g = statusGlyph(change.to);
+      return fit([t, [g.glyph, g.color.bold], [' '], ...id,
+        change.from ? [`${change.from} → `] : ['now '],
+        [change.to, change.to === 'BLOCKED' ? chalk.red.bold : change.to === 'DECISION_NEEDED' ? chalk.magenta.bold : change.to === 'COMPLETE' ? chalk.green.bold : chalk.bold],
+      ], width);
+    }
+    case 'phase': {
+      const up = change.id ? change.to > change.from : (change.delta || 0) > 0;
+      const label = change.id
+        ? `phase ${change.from}/${change.total ?? '?'} → ${change.to}/${change.total ?? '?'}`
+        : `roadmap phases ${change.from} → ${change.to} of ${change.total ?? '?'}`;
+      return fit([t, [up ? '■' : '□', up ? chalk.green.bold : chalk.yellow.bold], [' '], ...id, [label]], width);
+    }
+    case 'note':
+      return fit([t, ['✎', chalk.magenta.bold], [' '], ...id, ['new note: ', chalk.dim], [change.text || '']], width);
+    case 'activity':
+    default:
+      return fit([t, ['•', chalk.cyan.bold], [' '], ...id, [`+${(change.to ?? 0) - (change.from ?? 0)} event${(change.to ?? 0) - (change.from ?? 0) === 1 ? '' : 's'}`]], width);
+  }
+}
+
+/** Ticker block: header + newest `max` changes (oldest of them first). */
+export function renderTicker(seen, { since, width = 100, max = 8 } = {}) {
+  const lines = [''];
+  lines.push(fit([['  CHANGES SINCE YOU STARTED WATCHING', chalk.cyan.bold], [`  ${hhmm(since)} UTC`, chalk.dim], ['   Ctrl-C to exit', chalk.dim]], width));
+  if (!seen || seen.length === 0) {
+    lines.push(fit([['  none yet', chalk.dim]], width));
+    return lines;
+  }
+  for (const { change, at } of seen.slice(-max)) lines.push(renderChange(change, { at, width }));
+  if (seen.length > max) lines.push(fit([[`  +${seen.length - max} earlier`, chalk.dim]], width));
+  return lines;
+}
+
+// ── show helpers ─────────────────────────────────────────────────────────
+
+export const SHOW_NOTES_CAP = 5;
+export const SHOW_PLAN_LINES_CAP = 40;
+
+/** Newest-first notes, capped. Returns { notes, hidden }. */
+export function capNotes(notes, { full = false, cap = SHOW_NOTES_CAP } = {}) {
+  const sorted = [...(notes || [])].sort((x, y) => String(y.created_at).localeCompare(String(x.created_at)));
+  if (full) return { notes: sorted, hidden: 0 };
+  return { notes: sorted.slice(0, cap), hidden: Math.max(0, sorted.length - cap) };
+}
+
+/** One note body for `show`: whitespace collapsed and cut at 280 chars unless full. */
+export const SHOW_NOTE_CHARS_CAP = 280;
+export function capNoteBody(body, { full = false, cap = SHOW_NOTE_CHARS_CAP } = {}) {
+  const text = String(body ?? '');
+  if (full) return text;
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length <= cap ? flat : flat.slice(0, cap) + '…';
+}
+
+/** Plan body capped at N lines. Returns { body, hidden }. */
+export function capPlan(body, { full = false, cap = SHOW_PLAN_LINES_CAP } = {}) {
+  const lines = String(body || '').split('\n');
+  if (full || lines.length <= cap) return { body: String(body || ''), hidden: 0 };
+  return { body: lines.slice(0, cap).join('\n'), hidden: lines.length - cap };
+}