@semalt-ai/code 1.19.0 → 1.20.1

package/lib/ui/tool-operation.js

@@ -0,0 +1,190 @@
+'use strict';
+
+// ToolOperation descriptor (Output Refactor — Phase 1).
+//
+// The single, immutable description of one tool invocation's display state,
+// produced ONCE from the normalized `[action, ...opts]` tuple the agent loop
+// already computes (so it covers the XML and native rails identically — the
+// tuple is their convergence point). It is the display analogue of the
+// `boundToolOutput` token chokepoint: every chrome line for a tool call is
+// rendered from this one descriptor by `render-operation.js`, instead of each
+// call site assembling its own formatToolLine arguments.
+//
+// Phase 1 is a pure RE-ROUTING — the descriptor carries exactly the data the
+// existing formatters consume, so the renderer can reproduce today's output
+// byte-for-byte. Later phases collapse duplicates and fold in web/MCP/replay.
+//
+// Shape (all fields are plain data — no ANSI, no IO):
+//   {
+//     id         invocation id (writer activity-region key), or null
+//     category   short tag for the line ("file", "cmd", "net", …) — display only
+//     glyph      indicator glyph for the status ('●' | '✓' | '✗')
+//     tag        the ORIGINAL tool tag (formatToolLine normalizes it itself)
+//     target     the thing acted on — command / path / url / arg, stated once
+//     attrs      parsed tuple options (the operation detail source)
+//     status     'pending' | 'running' | 'ok' | 'error'
+//     durationMs elapsed/total ms, or null
+//     meta       category-specific tail (exit_code, bytes, count, status_code)
+//     error      error shape ({ message, code }), or null
+//     noDuration suppress the duration segment (blocking tools, e.g. ask_user)
+//     detail     optional body, COLLAPSED per the Phase 5 detail policy:
+//                  { kind: 'diff',   payload: { before, after, path } }
+//                    — file edits; rendered EXPANDED to diff_max_lines.
+//                  { kind: 'output', payload: { body, category } }
+//                    — shell/MCP/subagent SUCCESS output; rendered as a
+//                      shell_preview_lines preview + `… N more lines`.
+//                or null. Errors carry NO detail here — the error body renders
+//                EXPANDED on the existing chat-history error path (unchanged).
+//   }
+
+const { UI_ICONS, categoryForTag } = require('./theme');
+const { extractDisplayBody } = require('./format');
+
+// Category resolution (incl. action→tag normalization and the git_*/mcp__
+// prefix rules) lives in theme.js so the descriptor's `category` and the
+// rendered line's category can never diverge.
+function _categoryFor(tag) {
+  return categoryForTag(tag);
+}
+
+// Normalize an incoming status (runtime forms 'success'/'failure' OR descriptor
+// forms 'ok'/'error') to the descriptor vocabulary. `error` present forces error.
+function _normalizeStatus(status, error) {
+  if (status === 'pending') return 'pending';
+  if (status === 'running') return 'running';
+  if (status === 'error' || status === 'failure' || error) return 'error';
+  return 'ok';
+}
+
+function _glyphFor(status) {
+  if (status === 'pending' || status === 'running') return UI_ICONS.pending;
+  if (status === 'error') return UI_ICONS.error;
+  return UI_ICONS.success;
+}
+
+// Build the detail body per the Phase 5 policy. Order matters: errors carry no
+// preview detail (the error body renders expanded elsewhere); a file edit's diff
+// always wins over an output preview; otherwise a shell/MCP/subagent success
+// with non-empty output gets an output-preview detail.
+function _detailFor(spec, category, status) {
+  if (status === 'error') return null;
+  const { diff } = spec;
+  if (diff && typeof diff.before === 'string' && typeof diff.after === 'string') {
+    return { kind: 'diff', payload: { before: diff.before, after: diff.after, path: diff.path || '' } };
+  }
+  const previewable = category === 'shell' || category === 'mcp' || spec.tag === 'spawn_agent';
+  if (previewable && typeof spec.output === 'string') {
+    const body = extractDisplayBody(spec.output);
+    if (body && body.trim()) return { kind: 'output', payload: { body, category } };
+  }
+  return null;
+}
+
+// Produce the immutable descriptor. `spec` mirrors the data already available
+// at the onToolStart/onToolEnd callbacks:
+//   { id, tag, arg, attrs, status, durationMs, meta, error, diff, noDuration }
+// `tag`/`arg`/`attrs` are the parsed tuple (call[0], call[1], _attrsFromCall).
+function buildToolOperation(spec) {
+  const s = spec || {};
+  const tag = s.tag || 'tool';
+  const status = _normalizeStatus(s.status, s.error);
+  const category = _categoryFor(tag);
+  const descriptor = {
+    id: s.id != null ? s.id : null,
+    category,
+    glyph: _glyphFor(status),
+    tag,
+    target: s.arg != null ? s.arg : '',
+    attrs: s.attrs || null,
+    status,
+    durationMs: Number.isFinite(s.durationMs) ? s.durationMs : null,
+    meta: s.meta || null,
+    error: s.error || null,
+    noDuration: !!s.noDuration,
+    detail: _detailFor(s, category, status),
+  };
+  return Object.freeze(descriptor);
+}
+
+// ── Serialization for replay (Output Refactor — Phase 6) ─────────────────────
+//
+// A built descriptor is transient: it exists only for the duration of one live
+// tool turn. To replay a saved session (/history, /chats, --resume) with the
+// SAME fidelity a fresh turn shows — real diff, real duration, real status —
+// the *terminal-state* core of the descriptor is persisted next to the tool
+// result message (as a sibling `_display` key, see agent.js) and rebuilt here
+// on load. Both helpers are pure data transforms (no ANSI, no IO).
+//
+// `serializeOperation(op)` extracts the plain-data core `renderOperation` reads
+// for a COMPLETED (non-animating) op. The two live/animation-only fields are
+// dropped:
+//   - id    — the live activity-region key, meaningless once the turn ended.
+//   - glyph — recomputed from `status` by the renderer (formatToolLine).
+// Everything the renderer DOES read for phase 'result' / 'detail' is kept:
+// tag, target, attrs (the operation text is derived from attrs by _operation()
+// in format.js — NOT in §1's field list, added here because the result line is
+// not byte-identical without it), category, status, durationMs, meta, error,
+// noDuration (suppresses the duration segment for blocking tools — also beyond
+// §1's list, kept for the same byte-identity reason), and the collapsed detail.
+const DISPLAY_FORMAT_VERSION = 1;
+
+// `operationCore(op)` is the SINGLE descriptor→plain-data mapping shared by
+// `serializeOperation` (persistence/replay) and `renderOperation`'s json/event
+// modes (embeddable output — Phase 6d). It emits the descriptor's own vocabulary
+// (tag/target/attrs/category/status/durationMs/meta/error/noDuration/detail) and
+// nothing else — no `v` version tag (that is a persistence concern added by
+// serializeOperation), no ANSI, no IO, no live/animation fields (id, glyph). The
+// two live-only fields are dropped exactly as serializeOperation always dropped
+// them: `id` (the activity-region key) and `glyph` (recomputed from `status`).
+// Returns null for a non-object op so callers degrade gracefully.
+function operationCore(op) {
+  if (!op || typeof op !== 'object') return null;
+  return {
+    tag: op.tag,
+    target: op.target,
+    attrs: op.attrs || null,
+    category: op.category,
+    status: op.status,
+    durationMs: Number.isFinite(op.durationMs) ? op.durationMs : null,
+    meta: op.meta || null,
+    error: op.error || null,
+    noDuration: !!op.noDuration,
+    detail: op.detail || null,
+  };
+}
+
+function serializeOperation(op) {
+  const core = operationCore(op);
+  if (!core) return null;
+  // `v` first, then the shared core — byte-identical key order to the pre-6d
+  // hand-rolled object (replay/persistence depend on this exact shape).
+  return { v: DISPLAY_FORMAT_VERSION, ...core };
+}
+
+// Rebuild a renderable descriptor from a persisted core. Returns null when the
+// core is absent OR its version is unknown (`v` missing / not 1) — the caller
+// then falls back to the legacy summarizeToolResult path, so old sessions and
+// any future format degrade gracefully instead of crashing. The returned object
+// mirrors buildToolOperation's output shape so renderOperation treats it
+// identically to a fresh descriptor (it is not frozen — replay never mutates it).
+function descriptorFromStored(core) {
+  if (!core || typeof core !== 'object') return null;
+  if (core.v !== DISPLAY_FORMAT_VERSION) return null;
+  const status = core.status || 'ok';
+  return {
+    id: null,
+    category: core.category,
+    glyph: _glyphFor(status),
+    tag: core.tag || 'tool',
+    target: core.target != null ? core.target : '',
+    attrs: core.attrs || null,
+    status,
+    durationMs: Number.isFinite(core.durationMs) ? core.durationMs : null,
+    meta: core.meta || null,
+    error: core.error || null,
+    noDuration: !!core.noDuration,
+    detail: core.detail || null,
+  };
+}
+
+module.exports = { buildToolOperation, operationCore, serializeOperation, descriptorFromStored };

package/lib/ui/utils.js

@@ -45,13 +45,17 @@ function termWidth(str) {
 // Walks the string once; CSI escape sequences (`\x1b[…final`) are copied
 // through verbatim without consuming any visible width. Visible-width math
 // uses _cpWidth, so a 2-col CJK glyph or emoji counts as 2 and combining
-// marks count as 0. Always terminates with `\x1b[0m` so the terminal isn't
-// left in a colored state at the truncation point (safe when no escape
-// preceded the cut — a redundant reset is a no-op).
+// marks count as 0. Terminates with `\x1b[0m` ONLY when the (possibly
+// truncated) output actually contains an escape, so a cut that left an SGR
+// span open is closed without leaving the terminal colored at the cut point.
+// When the output is escape-free we append nothing: a trailing reset on
+// escape-free text is a stray escape that leaks through NO_COLOR. The gate is
+// content-driven (out.indexOf('\x1b')), not flag-driven, so a preview body
+// line carrying a child process's own ANSI is still closed defensively.
 function truncateVisible(str, maxCols) {
   if (!str) return '';
   const max = Math.max(0, maxCols | 0);
-  if (max === 0) return '\x1b[0m';
+  if (max === 0) return '';
   const s = String(str);
   const len = s.length;
   let out = '';
@@ -82,7 +86,7 @@ function truncateVisible(str, maxCols) {
     cols += w;
     i += clen;
   }
-  return out + '\x1b[0m';
+  return out.indexOf('\x1b') !== -1 ? out + '\x1b[0m' : out;
 }
 
 // Repeat a single-column glyph so the visible row is exactly `width` columns.

package/lib/ui/web-activity.js

@@ -18,7 +18,7 @@
 // before. Scope: `web_search` + `http_get`. `download` is a file-save, not a page
 // read for the search→fetch flow, so it keeps its own line.
 
-const { UI_THEME, UI_ICONS } = require('./theme');
+const { UI_THEME, UI_ICONS, resolveLineColors } = require('./theme');
 const { RST, DIM } = require('./ansi');
 const { formatDuration } = require('./format');
 
@@ -45,6 +45,54 @@ function opSucceeded(op) {
   return true;
 }
 
+// ── Web-op persistence core (Output Refactor — Phase 6c-i) ───────────────────
+//
+// Web tools (`web_search`/`http_get`) are intercepted in chat-turn.js BEFORE
+// they become a normal ToolOperation descriptor (they collapse into the live
+// web-activity summary instead). So the per-call `_display` slot the agent loop
+// persists would be `null` for a web op, and on replay the whole turn drops to
+// the legacy summary. 6c-i closes that gap WITHOUT changing any pixel: the
+// interception now returns a dedicated web-op core (below) which is persisted
+// into the slot, while every replay reader is taught to treat a web-core as
+// "no descriptor → fallback" (see isWebCore + chat-history/chat-session). 6c-ii
+// will later flip the readers to aggregate these cores into a replayed summary.
+//
+// The core is a SEPARATE shape from serializeOperation's normal core, with a
+// MANDATORY `kind:'web'` discriminator: a normal core buries `query` in `attrs`
+// and `status` in `meta`, whereas aggregateWebOps reads `op.query/url/status/
+// bytes/error/tag` FLAT — so these cores can feed aggregateWebOps directly in
+// 6c-ii. `kind:'web'` is mandatory because descriptorFromStored accepts any
+// `v===1` object and would otherwise render a web-core as a broken descriptor.
+const WEB_DISPLAY_FORMAT_VERSION = 1;
+
+// Build a persistable web-op core from the tool ctx (NOT the tracker's mutable
+// ended[]/current state), mirroring exactly what web-activity.end() reads from
+// ctx (`:180-191`): query/url from ctx.attrs, status/bytes from ctx.meta, error
+// from ctx.error. Decoupling persistence from live-region state keeps the two
+// independent.
+function serializeWebOp(ctx, tag, durationMs) {
+  const meta = ctx && ctx.meta;
+  const attrs = ctx && ctx.attrs;
+  return {
+    v: WEB_DISPLAY_FORMAT_VERSION,
+    kind: 'web',
+    tag,
+    query: (attrs && attrs.query) || undefined,
+    url: (attrs && attrs.url) || undefined,
+    status: meta && typeof meta.status_code === 'number' ? meta.status_code : undefined,
+    bytes: meta && typeof meta.bytes === 'number' ? meta.bytes : undefined,
+    error: ctx && ctx.error ? (ctx.error.message || String(ctx.error)) : undefined,
+    durationMs: Number.isFinite(durationMs) ? durationMs : null,
+  };
+}
+
+// Predicate: a persisted display core is a web-op core (vs a normal descriptor
+// core). Replay readers use this to route web-cores to the legacy fallback so
+// 6c-i is invisible. Tolerant of any non-object input.
+function isWebCore(core) {
+  return !!core && typeof core === 'object' && core.v === WEB_DISPLAY_FORMAT_VERSION && core.kind === 'web';
+}
+
 // Pure: fold the recorded op list into the counts the summary needs.
 function aggregateWebOps(ops) {
   const state = {
@@ -99,20 +147,22 @@ function webSummaryText(state) {
 // summary reads as a peer of the other tool lines, not a foreign widget.
 function formatWebSummaryLine(state, opts) {
   const { pending = false, durationMs = 0 } = opts || {};
+  // Glyph/label/duration colour resolves through the single theme resolver so
+  // the web summary reads as a peer of the other tool lines (web → cyan 44,
+  // running glyph cyan not gray, duration subtle not muted).
+  const colors = resolveLineColors('web', pending ? 'pending' : 'success');
   const glyph = pending ? UI_ICONS.pending : UI_ICONS.success;
-  const glyphColor = pending ? UI_THEME.muted : UI_THEME.success;
   const cat = 'web'.padEnd(5);
-  const catColor = (UI_THEME.categories && UI_THEME.categories.web) || UI_THEME.accent;
   const sep = ` ${DIM}·${RST} `;
 
-  const out = [`  ${glyphColor}${glyph}${RST} ${catColor}${cat}${RST}`];
+  const out = [`  ${colors.glyph}${glyph}${RST} ${colors.label}${cat}${RST}`];
   for (const seg of webSummarySegments(state)) {
     let color = UI_THEME.subtle;
-    if (seg.kind === 'lead') color = UI_THEME.default;
+    if (seg.kind === 'lead') color = colors.op;
     else if (seg.kind === 'fail') color = UI_THEME.warning;
     out.push(`${color}${seg.text}${RST}`);
   }
-  if (pending) out.push(`${UI_THEME.muted}${formatDuration(durationMs)}…${RST}`);
+  if (pending) out.push(`${colors.dur}${formatDuration(durationMs)}…${RST}`);
   return out.join(sep);
 }
 
@@ -208,6 +258,8 @@ function createWebActivityTracker(deps) {
 module.exports = {
   WEB_TOOLS,
   isWebTool,
+  serializeWebOp,
+  isWebCore,
   opSucceeded,
   aggregateWebOps,
   webSummarySegments,

package/lib/ui/writer.js

@@ -15,8 +15,10 @@
 //   STATUS REGION— 1–N lines at the bottom of the viewport. Redrawn in
 //                  place whenever setLive() is called. Each live line is
 //                  truncated to (cols − 1) so it occupies exactly one
-//                  physical row; combined height is modalLines.length +
-//                  statusLines.length and precise.
+//                  physical row; combined height is the physical-row sum
+//                  (displayRows over each emitted entry) — equal to the entry
+//                  count while every entry stays single-row, wrap-aware once
+//                  Phase 7b emits multi-row detail.
 //
 // Invariant: after any operation resolves, the cursor is at column 0 of the
 // row immediately below the status region. Every operation erases the
@@ -28,12 +30,21 @@
 // synchronous, so each task's compound write is emitted in one burst and
 // can't interleave with another task's writes.
 
-const { stripAnsi, termWidth, truncateVisible } = require('./utils');
+const { stripAnsi, termWidth, truncateVisible, displayRows } = require('./utils');
 const dbg = require('../debug');
 
 let _queue = Promise.resolve();
 let _liveLines = [];
 let _modalLines = [];
+// Deferred-detail band (Output Refactor — Phase 7b). The redrawable pseudo-tail
+// at the TOP of the live region (below committed scrollback, above the activity
+// / modal / status rows) that holds the most-recent output-preview detail until
+// a turn boundary commits it. Emitted RAW — NOT through _fitOneRow — so the lines
+// held at op-end width wrap naturally to multiple physical rows on a narrower
+// terminal; physicalRows counts their real height so the erase math stays
+// correct. The band is installed once (setDetail) and committed once
+// (commitDetail moves it into scrollback atomically) — never redrawn in place.
+let _detailLines = [];
 // Activity region: currently-executing tools with live timers. Sits above
 // modal and status (scrollback | activity | modal | status). Entries keyed
 // by invocation id so concurrent tools each get their own slot.
@@ -67,17 +78,39 @@ let _caret = null;
 
 function _cols() { return process.stdout.columns || 80; }
 
+// Match embedded control chars that would break the one-logical=one-physical
+// invariant: a bare \n forces a second physical row, \r jumps to column 0
+// mid-row, \t and other C0/DEL controls move the cursor unpredictably. ESC
+// (0x1B) is deliberately EXCLUDED so legitimate ANSI/SGR sequences survive —
+// every other byte of an SGR sequence (`[`, digits, `m`) is printable, so
+// stripping the rest of the C0 range can't corrupt color chrome.
+const _CONTROL_CHARS = /[\x00-\x1A\x1C-\x1F\x7F]/g; // eslint-disable-line no-control-regex
+
 // ANSI-aware, display-width-aware truncate to (cols-1) visible columns so
 // each rendered live line occupies exactly one physical terminal row — no
-// wrap, no height mis-count. Wrap-induced row-count drift is the root cause
-// of stale-line residue in scrollback: if a single logical line wraps to
-// two physical rows, _liveHeight (which tracks logical lines) undercounts,
-// and the next _eraseLiveSeq leaves the top wrapped row behind. Using
+// wrap, no height mis-count. This keeps every single-row caller's emitted
+// entry at displayRows == 1, so the physical-row height (Phase 7a) equals the
+// entry count for them and the erase math stays byte-identical. Un-fitted
+// multi-row callers (Phase 7b) are counted by their real physical rows. Using
 // termWidth for column counting (rather than a raw char count that treats
 // wide chars and combining marks as 1) keeps the guarantee honest for
 // non-ASCII chrome.
+//
+// Structural guard (Phase 4 fix-A, Part 2): embedded control chars are
+// replaced with a space BEFORE width truncation, so a single fitted row is
+// guaranteed exactly one physical row regardless of caller discipline. No
+// future live-row source can desync the erase math by passing un-flattened
+// content (e.g. a heredoc command that slipped its newlines through).
 function _fitOneRow(line) {
   if (!line) return '';
+  // Sanitize control chars first — before the fast path, since control chars
+  // are ASCII (≤0x7F) and would otherwise ride through the ASCII fast path
+  // unchanged. truncateVisible treats \n as a width-1 char and copies it
+  // verbatim, so sanitizing here is the only place the invariant is enforced.
+  if (_CONTROL_CHARS.test(line)) {
+    _CONTROL_CHARS.lastIndex = 0; // reset; .test on a /g regex is stateful
+    line = line.replace(_CONTROL_CHARS, ' ');
+  }
   const max = Math.max(0, _cols() - 1);
   // Fast path: pure ASCII (and thus display width == stripped length) and
   // already within budget — skip the parse. The ASCII gate is important
@@ -94,7 +127,20 @@ function _fitOneRow(line) {
   return truncateVisible(line, max);
 }
 
-function _eraseLiveSeq() {
+// The single source of truth for the live-region erase sequence. Returns the
+// cursor-up + carriage-return + clear-to-end-of-screen string that lands the
+// cursor on the first live row (or below it when there is no region). Both the
+// per-frame erase (_eraseLiveSeq) and teardown call this — consolidated in
+// Phase 4 fix-A (Part 3) so the deferred (B) wrap-aware physical-row rewrite
+// changes ONE site instead of two divergent copies.
+//
+// NOTE: _liveHeight is now a PHYSICAL-row total (Phase 7a / fix (B)) — the sum
+// of displayRows() over each emitted live entry at the current cols (see
+// physicalRows + _drawLiveSeq). For today's all-single-row content (each entry
+// fitted to ≤cols-1 by _fitOneRow) that physical sum equals the old logical
+// line count, so this erase math is byte-identical to before; the wrap-aware
+// count only diverges once Phase 7b emits un-truncated multi-row detail.
+function _eraseSeqForHeight() {
   if (_liveHeight <= 0) return '';
   // When the previous frame repositioned the OS cursor up to the caret, the
   // cursor is sitting _caret.rowsFromBottom rows ABOVE "below-live-region".
@@ -106,6 +152,10 @@ function _eraseLiveSeq() {
   return `${up > 0 ? `\x1b[${up}A` : ''}\r\x1b[J`;
 }
 
+function _eraseLiveSeq() {
+  return _eraseSeqForHeight();
+}
+
 // Collect visible activity entries in insertion order. Entries whose grace
 // period hasn't elapsed are hidden and don't contribute to _liveHeight.
 function _visibleActivity() {
@@ -121,24 +171,57 @@ function _visibleActivity() {
   return rows;
 }
 
+// (B) wrap-aware physical-row height primitive. Sums displayRows() — the true
+// physical-row count at `cols` — over each ALREADY-EMITTED live entry, so an
+// entry that wraps to N physical rows contributes N (not 1). It MUST be fed the
+// exact strings written to the terminal: _drawLiveSeq passes the post-_fitOneRow
+// lines, each fitted to ≤cols-1 → displayRows == 1 → the sum equals the entry
+// count, i.e. numerically identical to the old logical `array.length` height for
+// all single-row content today. When Phase 7b emits an un-truncated multi-row
+// detail entry, this counts its real physical rows so _eraseSeqForHeight()
+// cursor-ups by the correct physical total (and recomputes on resize, since the
+// count is taken at the current `cols`). Exported for direct unit coverage.
+function physicalRows(lines, cols) {
+  if (!Array.isArray(lines)) return 0;
+  const c = cols || _cols();
+  let h = 0;
+  for (let i = 0; i < lines.length; i++) h += displayRows(lines[i], c);
+  return h;
+}
+
 function _drawLiveSeq() {
   const activityRows = _visibleActivity();
-  const total = activityRows.length + _modalLines.length + _liveLines.length;
+  const total = _detailLines.length + activityRows.length + _modalLines.length + _liveLines.length;
   if (total === 0) { _liveHeight = 0; return ''; }
+  // Collect each entry exactly as written, so the height is measured on the
+  // same bytes the terminal receives — the (B) correctness rule.
+  const cols = _cols();
+  const emitted = [];
   let out = '';
+  // Deferred-detail band first (Phase 7b): emitted RAW (no _fitOneRow) so a held
+  // op-end-width line wraps to its real physical rows on a narrower terminal;
+  // physicalRows() counts that wrap so _eraseSeqForHeight() cursor-ups by the
+  // correct physical total. Sits at the very top of the live region.
+  for (let i = 0; i < _detailLines.length; i++) {
+    emitted.push(_detailLines[i]);
+    out += _detailLines[i] + '\n';
+  }
   for (let i = 0; i < activityRows.length; i++) {
-    out += _fitOneRow(activityRows[i]);
-    out += '\n';
+    const fitted = _fitOneRow(activityRows[i]);
+    emitted.push(fitted);
+    out += fitted + '\n';
   }
   for (let i = 0; i < _modalLines.length; i++) {
-    out += _fitOneRow(_modalLines[i]);
-    out += '\n';
+    const fitted = _fitOneRow(_modalLines[i]);
+    emitted.push(fitted);
+    out += fitted + '\n';
   }
   for (let i = 0; i < _liveLines.length; i++) {
-    out += _fitOneRow(_liveLines[i]);
-    out += '\n';
+    const fitted = _fitOneRow(_liveLines[i]);
+    emitted.push(fitted);
+    out += fitted + '\n';
   }
-  _liveHeight = total;
+  _liveHeight = physicalRows(emitted, cols);
   return out;
 }
 
@@ -254,11 +337,51 @@ function clearLive() {
       if (entry.graceTimer) { try { clearTimeout(entry.graceTimer); } catch {} }
     }
     _activity.clear();
+    _detailLines = [];
     _liveHeight = 0;
     _caret = null;
   });
 }
 
+// Replace the deferred-detail band (Phase 7b) and redraw in place. The band sits
+// at the TOP of the live region and is emitted RAW (un-fitted, may wrap). Used to
+// install the held output-preview detail without touching scrollback. _caret is
+// left as-is (the band only exists while input is disabled, so the caret is null
+// anyway); this mirrors redrawLive rather than setModal (which suppresses the
+// caret).
+function setDetail(lines) {
+  return _enqueue(() => {
+    // Erase using the previous caret/liveHeight (the band's rows are part of the
+    // current _liveHeight) — see setLive() for why erase precedes the state swap.
+    const eraseSeq = _eraseLiveSeq();
+    _detailLines = Array.isArray(lines) ? lines.map((l) => (l == null ? '' : String(l))) : [];
+    _writeSync(_HIDE + eraseSeq + _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq());
+  });
+}
+
+// Commit the deferred-detail band to scrollback and clear it, in ONE compound
+// write: erase the live region (the band's physical rows are included via the
+// current _liveHeight), append the held lines as immutable scrollback, then
+// redraw the live region with the band gone. Mirrors endActivity's atomic
+// erase+commit+redraw so there is no duplicate-band frame and no stranded rows
+// (the live-row race the discovery flagged). A no-op (plain erase+redraw) when
+// `text` is empty.
+function commitDetail(text) {
+  return _enqueue(() => {
+    let out = _HIDE + _eraseLiveSeq();
+    // Drop the band BEFORE _drawLiveSeq so the redraw omits it; the erase above
+    // already used the pre-clear _liveHeight (band included).
+    _detailLines = [];
+    if (text !== undefined && text !== null && text !== '') {
+      let t = String(text);
+      if (!t.endsWith('\n')) t += '\n';
+      out += t;
+    }
+    out += _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq();
+    _writeSync(out);
+  });
+}
+
 // Replace the modal region with `lines`. Modal sits above status and below
 // scrollback. Used for permission pickers, confirm dialogs, text input
 // prompts, etc. — any widget that must redraw on every keystroke without
@@ -297,9 +420,11 @@ function hasModal() { return _modalLines.length > 0; }
 // the row without a scrollback commit (used by aborts where the final line
 // is already written elsewhere, or for tools that produced no output).
 //
-// refreshActivity() forces a redraw so the lazy `render(elapsedMs)` on
-// each entry picks up a new elapsed time. Called by the status-bar ticker;
-// a no-op when nothing is visible.
+// The lazy `render(elapsedMs)` on each entry picks up a fresh elapsed time on
+// every live-region repaint. Phase 3: those periodic repaints are driven by the
+// single animation driver (lib/ui/anim.js) via the status bar's coordinated
+// _notify → setLive, which re-runs each entry's render here — so the per-tool
+// elapsed meter + running glyph animate without a second timer of their own.
 
 const DEFAULT_ACTIVITY_GRACE_MS = 200;
 
@@ -381,23 +506,6 @@ function cancelActivity(id) {
   });
 }
 
-// Ticker hook: re-emit the live region so each activity entry's
-// `render(elapsedMs)` is re-invoked with a fresh elapsed time. No-op when
-// nothing is visible (avoids burning cycles when idle).
-function refreshActivity() {
-  if (_activity.size === 0) return _queue;
-  let anyVisible = false;
-  for (const entry of _activity.values()) { if (entry.visible) { anyVisible = true; break; } }
-  if (!anyVisible) return _queue;
-  return _enqueue(() => {
-    if (_destroyed) return;
-    let stillAnyVisible = false;
-    for (const entry of _activity.values()) { if (entry.visible) { stillAnyVisible = true; break; } }
-    if (!stillAnyVisible) return;
-    _writeSync(_HIDE + _eraseLiveSeq() + _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq());
-  });
-}
-
 function hasActivity() {
   for (const entry of _activity.values()) { if (entry.visible) return true; }
   return false;
@@ -426,6 +534,7 @@ function enqueue(fn) {
 
 function getLiveHeight() { return _liveHeight; }
 function getLiveLines()  { return _liveLines.slice(); }
+function getDetailLines() { return _detailLines.slice(); }
 
 function destroy() { _destroyed = true; }
 
@@ -504,15 +613,16 @@ function teardown(opts) {
 
   // Erase the live region. The cursor may be sitting inside the region —
   // _caret.rowsFromBottom rows above the "below-live-region" baseline —
-  // because the last setLive positioned it at the input caret. Subtract
-  // that offset so cursor-up lands on the FIRST live row, not above the
-  // live region (which would erase scrollback). After \x1b[J the cursor
-  // sits at column 0 of the row immediately after the last scrollback
-  // line — exactly where new scrollback content should begin.
+  // because the last setLive positioned it at the input caret. The shared
+  // _eraseSeqForHeight() helper subtracts that offset so cursor-up lands on
+  // the FIRST live row, not above the live region (which would erase
+  // scrollback). After \x1b[J the cursor sits at column 0 of the row
+  // immediately after the last scrollback line — exactly where new
+  // scrollback content should begin. (Consolidated with _eraseLiveSeq in
+  // Phase 4 fix-A Part 3 so Phase 7a's (B) physical-row rewrite touched one
+  // site — _liveHeight is now that physical-row total.)
   if (_liveHeight > 0) {
-    const offset = _caret ? _caret.rowsFromBottom : 0;
-    const up = Math.max(0, _liveHeight - offset);
-    parts.push(up > 0 ? `\x1b[${up}A\r\x1b[J` : '\r\x1b[J');
+    parts.push(_eraseSeqForHeight());
   } else {
     // No live region active: ensure cursor is at column 0 so artifacts
     // (and any eventual shell prompt) don't print mid-line if some
@@ -564,6 +674,7 @@ function teardown(opts) {
     if (entry.graceTimer) { try { clearTimeout(entry.graceTimer); } catch {} }
   }
   _activity.clear();
+  _detailLines = [];
   _liveHeight = 0;
 
   try { process.stdout.write(parts.join('')); } catch {}
@@ -582,6 +693,8 @@ module.exports = {
   scrollback,
   setLive,
   clearLive,
+  setDetail,
+  commitDetail,
   setModal,
   clearModal,
   hasModal,
@@ -589,13 +702,14 @@ module.exports = {
   updateActivity,
   endActivity,
   cancelActivity,
-  refreshActivity,
   hasActivity,
   redrawLive,
   flush,
   enqueue,
   getLiveHeight,
   getLiveLines,
+  getDetailLines,
+  physicalRows,
   destroy,
   teardown,
 };

package/lib/ui.js

@@ -27,7 +27,7 @@ module.exports = {
   isPrintableKey: utils.isPrintableKey, approxTokens: utils.approxTokens,
 
   // Diff + Markdown
-  renderDiff: diff.renderDiff, renderMarkdown: diff.renderMarkdown,
+  renderDiff: diff.renderDiff, buildExecutionDiff: diff.buildExecutionDiff, renderMarkdown: diff.renderMarkdown,
 
   // Stream renderer
   StreamRenderer: stream.StreamRenderer,