@semalt-ai/code 1.19.0 → 1.20.1

package/test/defer-detail-band.test.js

@@ -0,0 +1,403 @@
+'use strict';
+
+// Output Refactor · Phase 7b — defer-commit of the collapsed output preview.
+//
+// The most-recent output preview is held in the writer's redrawable detail band
+// until a turn boundary commits it ONCE (no scrollback churn). The preview is
+// static and collapsed — first N lines + a `… M more lines` hint, with no
+// interactive affordance (full viewing is deferred to the transcript viewer).
+//
+// These tests gate: (1) the collapsed commit is byte-identical to addMessage's
+// collapsed commit, (2) boundary commit + ordering at onToolStart / assistant
+// answer / turn-end, (3) resize-during-defer physical erase correctness, (4)
+// caret never coexists with the band, (5) diffs commit immediately (not
+// deferred), (6) the writer detail-region primitives + the 7a single-row
+// byte-identity still hold.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+process.stdout.isTTY = true;
+delete process.env.NO_COLOR;
+
+const { ChatHistory } = require('../lib/ui/chat-history');
+const writer = require('../lib/ui/writer');
+
+const stripAnsi = (s) => String(s).replace(/\x1b\[[0-9;?<>]*[a-zA-Z]/g, '');
+const mkLines = (n, prefix = 'line') => Array.from({ length: n }, (_, i) => `${prefix} ${i + 1}`).join('\n');
+
+// Capture chat-history's three output seams into ONE ordered log so we can
+// assert ordering across scrollback commits, band installs, and band commits.
+function instrument(ch) {
+  const log = [];
+  ch._commit = (t) => log.push({ op: 'scrollback', text: t });
+  ch._setDetail = (lines) => log.push({ op: 'setDetail', lines: lines.slice() });
+  ch._commitDetail = (t) => log.push({ op: 'commitDetail', text: t });
+  ch._notifyLive = () => {};
+  return log;
+}
+
+// ── 1. collapsed commit: byte-identical to addMessage, static hint, no affordance ─
+// The held band commits ONCE, byte-identical to addMessage's collapsed commit for
+// the same output. The hint carries no interactive `(ctrl+o)` affordance — full
+// viewing is deferred to the transcript viewer.
+
+test('collapsed commit: deferred commit == addMessage collapsed commit (byte-identical, static hint)', () => {
+  // Reference: what addMessage commits (immediate scrollback, collapsed, static).
+  const ref = new ChatHistory();
+  const refOut = [];
+  ref._commit = (t) => refOut.push(t);
+  ref._notifyLive = () => {};
+  ref.addMessage({ role: 'tool', tag: 'shell', content: '', output: mkLines(20), previewLines: 5 });
+  const expected = refOut.join('');
+
+  // Deferred: defer, commit at a boundary.
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: mkLines(20), previewLines: 5 });
+  ch.commitDeferredDetail();
+  const commits = log.filter((e) => e.op === 'commitDetail');
+  assert.strictEqual(commits.length, 1, 'commits exactly once (no duplication)');
+  assert.strictEqual(commits[0].text, expected, 'collapsed commit is byte-identical to addMessage');
+  assert.doesNotMatch(stripAnsi(commits[0].text), /ctrl\+o/, 'committed collapsed hint carries no affordance');
+  assert.match(stripAnsi(commits[0].text), /… 15 more lines/, 'hidden count (20 − 5) preserved');
+});
+
+// ── 2. boundary commit + ordering (b: assistant answer text) ──────────────────
+// Guards: when the assistant answer streams, the held band commits BEFORE the
+// answer's first scrollback line (tool output stays above the answer).
+
+test('boundary (b): streamToken auto-commits the held band BEFORE the answer text', () => {
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: mkLines(20), previewLines: 5 });
+  log.length = 0;
+  ch.streamToken('the answer\n');
+  const commitIdx = log.findIndex((e) => e.op === 'commitDetail');
+  const firstScrollIdx = log.findIndex((e) => e.op === 'scrollback');
+  assert.ok(commitIdx >= 0, 'band committed when the answer starts streaming');
+  assert.ok(firstScrollIdx >= 0, 'answer flows to scrollback');
+  assert.ok(commitIdx < firstScrollIdx, 'band commits BEFORE the answer text');
+});
+
+test('boundary (b): a non-streaming finalize also commits the band first', () => {
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: mkLines(20), previewLines: 5 });
+  log.length = 0;
+  ch.finalizeLastMessage('final answer text'); // no stream → synthesises a bubble
+  const commitIdx = log.findIndex((e) => e.op === 'commitDetail');
+  const firstScrollIdx = log.findIndex((e) => e.op === 'scrollback');
+  assert.ok(commitIdx >= 0 && firstScrollIdx >= 0);
+  assert.ok(commitIdx < firstScrollIdx, 'band commits before the assistant bubble');
+});
+
+test('boundary: addMessage (e.g. a system line) auto-commits the held band first', () => {
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: mkLines(20), previewLines: 5 });
+  log.length = 0;
+  ch.addMessage({ role: 'system', content: 'something happened' });
+  const commitIdx = log.findIndex((e) => e.op === 'commitDetail');
+  const firstScrollIdx = log.findIndex((e) => e.op === 'scrollback');
+  assert.ok(commitIdx < firstScrollIdx, 'band commits before the new bubble');
+});
+
+test('single slot: deferring a SECOND preview commits the first held one before installing', () => {
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: mkLines(20), previewLines: 5 });
+  log.length = 0;
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: mkLines(8, 'second'), previewLines: 5 });
+  const commitIdx = log.findIndex((e) => e.op === 'commitDetail');
+  const setIdx = log.findIndex((e) => e.op === 'setDetail');
+  assert.ok(commitIdx >= 0, 'first slot committed');
+  assert.ok(commitIdx < setIdx, 'first commits before the second band is installed (single slot)');
+});
+
+// ── 3b. boundary ordering through the REAL chat-turn callbacks (a + c + diff) ──
+// Drives the actual onToolStart/onToolEnd wiring with a stubbed runAgentLoop so
+// the three commit sites and the diff-immediacy are exercised end-to-end.
+
+function turnHarness() {
+  const { createTurnHandler } = require('../lib/commands/chat-turn');
+  const { TAG_REGISTRY } = require('../lib/constants');
+  const log = [];
+  // Shared writer stub + chat-history seams push into ONE ordered log.
+  const writerModule = {
+    startActivity: (id) => log.push({ op: 'startActivity', id }),
+    updateActivity: () => {},
+    endActivity: (id, line) => log.push({ op: 'endActivity', id, line }),
+    cancelActivity: () => {},
+    scrollback: (t) => log.push({ op: 'scrollback', text: t }),
+  };
+  const chatHistory = new ChatHistory();
+  chatHistory._commit = (t) => log.push({ op: 'scrollback', text: t });
+  chatHistory._setDetail = (lines) => log.push({ op: 'setDetail', lines: lines.slice() });
+  chatHistory._commitDetail = (t) => log.push({ op: 'commitDetail', text: t });
+  chatHistory._notifyLive = () => {};
+  const noop = () => {};
+  const statusBar = { update: noop, addPendingTokens: noop, updateMetrics: noop, setCost: noop };
+  const listeners = {};
+  const inputField = {
+    setDisabled: noop, releaseNavigation: noop,
+    on: (ev, cb) => { listeners[ev] = cb; },
+    removeListener: noop,
+  };
+  const ctx = {
+    inputField, statusBar, chatHistory,
+    getConfig: () => ({ auth_token: 'x', shell_preview_lines: 5, diff_max_lines: 100, max_iterations: 125, system_prompt_mode: 'system_role' }),
+    approxTokens: () => 1,
+    resolveCommand: () => null,
+    opts: {}, TAG_REGISTRY, writerModule,
+    collapseListMsg: noop, handlePendingSelection: noop, showPendingStep: noop,
+    activateNavCapture: noop, finalizeListMsg: noop,
+    createChatIfNeeded: async () => {}, saveTurnToDashboard: async () => {}, saveSession: noop,
+    messages: [], currentModel: 'm', resolvedSystemPrompt: '', planMode: false,
+    debugMode: false, pendingImages: [], resolvedTokenLimit: 100000,
+    runAgentLoop: null, // set per-test
+  };
+  const make = (drive) => {
+    ctx.runAgentLoop = async (messages, model, maxIter, limit, o) => {
+      await drive(o.callbacks);
+      return { messages, metrics: { turns: [] } };
+    };
+    return createTurnHandler(ctx, {});
+  };
+  return { log, make };
+}
+
+const SHELL_OUT = 'Command `ls`:\nExit code: 0\n' + mkLines(20);
+
+test('boundary (a): next op onToolStart commits the held band BEFORE its running line', async () => {
+  const { log, make } = turnHarness();
+  const handler = make(async (cb) => {
+    cb.onToolEnd('shell', SHELL_OUT, 10, { id: 't1', attrs: { command: 'ls' } });
+    cb.onToolStart('shell', 'cat f', { id: 't2', attrs: { command: 'cat f' } });
+    cb.onToolEnd('shell', 'Command `cat f`:\nExit code: 0\n', 5, { id: 't2', attrs: { command: 'cat f' } });
+  });
+  await handler('go');
+  const ops = log.map((e) => e.op);
+  const setIdx = ops.indexOf('setDetail');                       // t1 preview deferred
+  const commitIdx = ops.indexOf('commitDetail');                 // committed at t2 start
+  const startT2 = log.findIndex((e) => e.op === 'startActivity' && e.id === 't2');
+  assert.ok(setIdx >= 0, 't1 output deferred into the band');
+  assert.ok(commitIdx >= 0 && startT2 >= 0);
+  assert.ok(commitIdx < startT2, 'band commits before t2 running line');
+  // And after t1's result line (endActivity t1) — chronological order preserved.
+  const endT1 = log.findIndex((e) => e.op === 'endActivity' && e.id === 't1');
+  assert.ok(endT1 < setIdx, 't1 result line lands before its deferred preview');
+});
+
+test('boundary (c): a trailing op commits the held band at turn-end finally', async () => {
+  const { log, make } = turnHarness();
+  const handler = make(async (cb) => {
+    cb.onToolStart('shell', 'ls', { id: 't1', attrs: { command: 'ls' } });
+    cb.onToolEnd('shell', SHELL_OUT, 10, { id: 't1', attrs: { command: 'ls' } });
+    // turn ends with no following message/op → finally commits the band.
+  });
+  await handler('go');
+  const ops = log.map((e) => e.op);
+  assert.ok(ops.includes('setDetail'), 'trailing op deferred');
+  assert.ok(ops.includes('commitDetail'), 'trailing band committed at turn end');
+});
+
+test('diffs (6): a file-edit diff commits immediately to scrollback — not deferred, not toggleable', async () => {
+  const { log, make } = turnHarness();
+  const handler = make(async (cb) => {
+    cb.onToolEnd('write_file', 'Wrote 2 bytes to f', 5, {
+      id: 'd1', attrs: { path: 'f' }, diff: { before: mkLines(10, 'old'), after: mkLines(10, 'new'), path: 'f' },
+    });
+  });
+  await handler('go');
+  const ops = log.map((e) => e.op);
+  assert.ok(!ops.includes('setDetail'), 'a diff op never installs a detail band');
+  assert.ok(!ops.includes('commitDetail'), 'a diff op never uses the deferred-commit path');
+  // Result line (endActivity) + diff (scrollback) both committed immediately.
+  assert.ok(log.some((e) => e.op === 'endActivity' && e.id === 'd1'), 'result line committed');
+  assert.ok(log.some((e) => e.op === 'scrollback'), 'diff committed straight to scrollback');
+});
+
+// ── 4 + 7. writer detail-region primitives (byte capture) ─────────────────────
+// Guards: setDetail emits the band RAW (un-fitted, multi-row), at the top of the
+// live region, counted by physicalRows; commitDetail atomically erases the band
+// + appends to scrollback + redraws without it; resize recomputes the physical
+// erase (no stranded rows); single-row chrome stays byte-identical (7a).
+
+function withWriter(fn) {
+  const out = process.stdout;
+  const prev = { isTTY: out.isTTY, columns: out.columns, rows: out.rows, write: out.write };
+  let buf = '';
+  out.isTTY = true; out.columns = 80; out.rows = 24;
+  out.write = (s) => { buf += String(s); return true; };
+  const cap = { get: () => buf, reset: () => { buf = ''; }, setCols: (n) => { out.columns = n; } };
+  return (async () => {
+    try { await fn(cap); }
+    finally {
+      await writer.clearLive(); await writer.flush();
+      out.isTTY = prev.isTTY; out.columns = prev.columns; out.rows = prev.rows; out.write = prev.write;
+    }
+  })();
+}
+
+// Minimal ANSI terminal model (same vocabulary the writer emits) — rows.length
+// is the committed physical footprint; an undercounting erase makes it GROW.
+function makeVT() {
+  const rows = [''];
+  let r = 0, c = 0;
+  const ensure = (row) => { while (rows.length <= row) rows.push(''); };
+  const put = (ch) => { ensure(r); rows[r] = rows[r].slice(0, c) + ch + rows[r].slice(c + 1); c++; };
+  function write(s) {
+    let i = 0;
+    while (i < s.length) {
+      const ch = s[i];
+      if (ch === '\x1b' && s[i + 1] === '[') {
+        let j = i + 2, params = '';
+        while (j < s.length && /[0-9;?<>]/.test(s[j])) { params += s[j]; j++; }
+        const final = s[j]; const n = parseInt(params, 10) || 1;
+        if (final === 'A') r = Math.max(0, r - n);
+        else if (final === 'B') { r += n; ensure(r); }
+        else if (final === 'C') c += n;
+        else if (final === 'D') c = Math.max(0, c - n);
+        else if (final === 'J') { ensure(r); rows[r] = rows[r].slice(0, c); rows.length = r + 1; }
+        i = j + 1; continue;
+      }
+      if (ch === '\x1b') { i += 1; continue; }
+      if (ch === '\n') { r++; c = 0; ensure(r); i++; continue; }
+      if (ch === '\r') { c = 0; i++; continue; }
+      put(ch); i++;
+    }
+  }
+  return { rows, write };
+}
+
+test('writer.setDetail: band sits at the TOP of the live region, RAW (un-fitted)', () =>
+  withWriter(async (cap) => {
+    await writer.setLive(['separator', 'status', '› input']);
+    await writer.flush();
+    cap.reset();
+    await writer.setDetail(['detail row A', 'detail row B']);
+    await writer.flush();
+    // Band drawn ABOVE the chrome; height = 2 (band) + 3 (chrome) = 5 rows.
+    assert.strictEqual(writer.getLiveHeight(), 5);
+    const drawn = cap.get();
+    const aIdx = drawn.indexOf('detail row A');
+    const sepIdx = drawn.indexOf('separator');
+    assert.ok(aIdx >= 0 && sepIdx >= 0 && aIdx < sepIdx, 'detail band is emitted above the chrome');
+  }));
+
+test('writer.setDetail: a band line WIDER than cols is NOT fitted (held raw, wraps)', () =>
+  withWriter(async (cap) => {
+    cap.setCols(40);
+    const wide = 'D'.repeat(100); // 100 visible cols at width 40 → 3 physical rows
+    await writer.setDetail([wide]);
+    await writer.flush();
+    assert.ok(cap.get().includes(wide), 'the wide line is emitted verbatim (not truncated to cols-1)');
+    assert.strictEqual(writer.getLiveHeight(), 3, 'physicalRows counts the wrap (ceil(100/40))');
+  }));
+
+test('writer.commitDetail: atomically erases band + appends scrollback + redraws without band', () =>
+  withWriter(async (cap) => {
+    await writer.setLive(['chrome']);
+    await writer.setDetail(['det1', 'det2']);
+    await writer.flush();
+    assert.strictEqual(writer.getLiveHeight(), 3); // 2 detail + 1 chrome
+    cap.reset();
+    await writer.commitDetail('det1\ndet2\n');
+    await writer.flush();
+    // Erase 3 physical rows, append the committed band, redraw only the chrome.
+    assert.strictEqual(cap.get(), '\x1b[?25l\x1b[3A\r\x1b[Jdet1\ndet2\nchrome\n');
+    assert.deepStrictEqual(writer.getDetailLines(), [], 'band cleared after commit');
+    assert.strictEqual(writer.getLiveHeight(), 1, 'only chrome remains');
+  }));
+
+test('writer.commitDetail: no stranded rows after a resize NARROWER during the defer window', () => {
+  const vt = makeVT();
+  const out = process.stdout;
+  const prev = { isTTY: out.isTTY, columns: out.columns, rows: out.rows, write: out.write };
+  out.isTTY = true; out.columns = 80; out.rows = 24;
+  out.write = (s) => { vt.write(String(s)); return true; };
+  return (async () => {
+    try {
+      await writer.setLive(['chrome']);
+      // Band rendered at WIDE width (op-end width 80) — one row each, held verbatim.
+      const held = ['x'.repeat(70), 'y'.repeat(70)];
+      await writer.setDetail(held);
+      await writer.flush();
+      assert.strictEqual(writer.getLiveHeight(), 1 + 2); // 70<80 → 1 row each + chrome
+      // Resize NARROWER: each held 70-col line now wraps to 2 rows at width 40.
+      out.columns = 40;
+      await writer.redrawLive();
+      await writer.flush();
+      assert.strictEqual(writer.getLiveHeight(), 2 + 2 + 1, 'physical erase recomputes for the wrap');
+      const footprint = vt.rows.length;
+      // Commit at the narrow width — erases the recomputed physical height, no leak.
+      await writer.commitDetail(held.join('\n') + '\n');
+      await writer.flush();
+      // The held lines (op-end-width, NOT re-rendered) reached scrollback verbatim.
+      assert.ok(vt.rows.some((r) => r.startsWith('x'.repeat(40))), 'held line committed verbatim');
+      assert.ok(footprint > 0);
+    } finally {
+      await writer.clearLive(); await writer.flush();
+      out.isTTY = prev.isTTY; out.columns = prev.columns; out.rows = prev.rows; out.write = prev.write;
+    }
+  })();
+});
+
+test('7a unchanged: single-row chrome stays byte-identical with no band present', () =>
+  withWriter(async (cap) => {
+    await writer.setLive(['hi']);
+    await writer.flush();
+    assert.strictEqual(cap.get(), '\x1b[?25lhi\n', 'first draw, no band, no erase');
+    cap.reset();
+    await writer.setLive(['bye']);
+    await writer.flush();
+    assert.strictEqual(cap.get(), '\x1b[?25l\x1b[1A\r\x1b[Jbye\n', 'erase up=1, byte-identical to 7a');
+  }));
+
+// ── 5. caret — never coexists with the deferred band ──────────────────────────
+// Guards Step 0 verdict: input is disabled for the whole agent turn, so
+// getCaretPosition() is null while a band is held; the turn-end finally commits
+// the band BEFORE setDisabled(false). The InputField proves the disabled→null
+// caret contract that makes the create-ui caret math safe to leave untouched.
+
+test('caret: a disabled input field yields a null caret (band never coexists with a caret)', () => {
+  const { InputField } = require('../lib/ui/input-field');
+  const field = new InputField({ cols: 80 }, {}, () => {});
+  field.setDisabled(true);
+  assert.strictEqual(field.getCaretPosition(), null, 'disabled input has no caret while the band is held');
+  try { field.destroy(); } catch {}
+});
+
+// ── 8. collapsed-commit invariants (THIS task) ───────────────────────────────
+// The committed band carries no interactive affordance, and small
+// (non-truncatable) output commits byte-identically to addMessage.
+
+// (a) committed hint has NO "(ctrl+o)" affordance.
+test('committed hint carries no (ctrl+o) affordance', () => {
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: mkLines(20), previewLines: 5 });
+  ch.commitDeferredDetail();
+  const text = stripAnsi(log.filter((e) => e.op === 'commitDetail')[0].text);
+  assert.match(text, /… 15 more lines/, 'hidden count remains on committed output');
+  assert.doesNotMatch(text, /ctrl\+o/, 'no interactive affordance once committed');
+});
+
+// (b) small (non-truncatable) output → committed band byte-identical to addMessage.
+test('small output: committed band byte-identical to addMessage (no affordance)', () => {
+  const ref = new ChatHistory();
+  const refOut = [];
+  ref._commit = (t) => refOut.push(t);
+  ref._notifyLive = () => {};
+  ref.addMessage({ role: 'tool', tag: 'shell', content: '', output: mkLines(3), previewLines: 5 });
+  const expected = refOut.join('');
+
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: mkLines(3), previewLines: 5 });
+  ch.commitDeferredDetail();
+  const commits = log.filter((e) => e.op === 'commitDetail');
+  assert.strictEqual(commits[0].text, expected, 'small-output commit is byte-identical to addMessage');
+  assert.doesNotMatch(stripAnsi(commits[0].text), /ctrl\+o/, 'non-truncatable output never carries an affordance');
+});

package/test/detail-band-tab-flatten.test.js

@@ -0,0 +1,242 @@
+'use strict';
+
+// Detail-band TAB flattening — the "1 logical line == 1 physical row" invariant.
+//
+// The writer's erase/commit math (_liveHeight via displayRows) assumes each
+// emitted preview line is exactly one physical row, so the band's logical-line
+// count equals its physical-row count. That invariant is FALSE for raw shell
+// output containing TABs (and other C0 controls): the detail band is emitted RAW
+// (writer _drawLiveSeq, bypassing _fitOneRow — the only place embedded TAB/C0/DEL
+// are flattened to spaces), and truncateVisible/termWidth count a TAB as 1 column
+// while the terminal advances it to the next 8-col tab stop. So a body line
+// "fitted to cols-1" still renders WIDER than cols and WRAPS to ≥2 physical rows,
+// and the writer's cursor-up erase math under-counts → stranded/duplicated rows.
+//
+// THE FIX (option a): restore "1 logical line == 1 physical row" by flattening the
+// detail band's lines the same way every other live row already is. Applied at the
+// single seam _renderOutputPreviewLines (the source for the live band, the
+// immediate/committed scrollback, and replay), so all render paths are consistent:
+//   1. C0/DEL controls (TAB included) → space (1:1, width preserved).
+//   2. stray non-SGR escapes (e.g. \x1b[K) dropped, closing the stripAnsi-only-'m'
+//      over-count gap. SGR color is preserved.
+//
+// These tests gate: (a) a TAB-bearing band line == exactly 1 physical row;
+// (b) the real writer renders a large TAB band at its true physical height and the
+// one-shot commit clears it with no wide/stranded rows (real writer + TAB/wrap-aware
+// VT); (c) a stray \x1b[K line counts as 1 row (no over-count); (d) plain-ASCII
+// output is byte-identical (flatten is a no-op); (e) live vs committed render of the
+// same TAB output stay consistent (both flattened).
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+process.stdout.isTTY = true;
+delete process.env.NO_COLOR;
+
+const { ChatHistory } = require('../lib/ui/chat-history');
+const writer = require('../lib/ui/writer');
+const { displayRows } = require('../lib/ui/utils');
+
+// Strip EVERY escape (SGR + non-SGR CSI + bare ESC) so we can measure visible
+// content the way the real terminal renders it.
+const stripAllEsc = (s) =>
+  String(s).replace(/\x1b\[[0-9;?<>]*[A-Za-z]/g, '').replace(/\x1b./g, '');
+
+// Ground-truth physical-row count for a single emitted line on a REAL terminal:
+// expand TABs to the next 8-col tab stop and autowrap at `cols`. This is what
+// displayRows/termWidth CANNOT see (they count a TAB as 1), so it is the honest
+// oracle the fix must satisfy.
+function realPhysicalRows(line, cols) {
+  const plain = stripAllEsc(line);
+  let col = 0;
+  let rows = 1;
+  const advance = () => { col++; if (col >= cols) { rows++; col = 0; } };
+  for (const ch of plain) {
+    if (ch === '\t') {
+      const target = (Math.floor(col / 8) + 1) * 8;
+      for (let k = col; k < target; k++) advance();
+    } else {
+      advance();
+    }
+  }
+  return rows;
+}
+
+function instrument(ch) {
+  const log = [];
+  ch._commit = (t) => log.push({ op: 'scrollback', text: t });
+  ch._setDetail = (lines) => log.push({ op: 'setDetail', lines: lines.slice() });
+  ch._commitDetail = (t) => log.push({ op: 'commitDetail', text: t });
+  ch._notifyLive = () => {};
+  return log;
+}
+
+const lastSetDetail = (log) => log.filter((e) => e.op === 'setDetail').pop().lines;
+
+// A line whose TAB=1 width is ≤ the fit budget (so formatOutputPreview keeps the
+// TABs in the "fitted" line) but whose tab-EXPANDED width blows far past cols.
+// "x\t" × 37 = 74 cols counted (cols-6 budget at 80), but expands to ~300 cols.
+const TAB_LINE = 'x\t'.repeat(37);
+const tabOutput = (n) => Array.from({ length: n }, () => TAB_LINE).join('\n');
+
+// ── (a) a TAB-bearing band line occupies EXACTLY one physical row ─────────────
+
+test('(a) TAB flatten: every preview band line is exactly one physical row; TABs become spaces', () => {
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: tabOutput(10), previewLines: 5 });
+  const band = lastSetDetail(log);
+
+  // Sanity: the RAW (pre-flatten) line would have wrapped — prove the test bites.
+  assert.ok(realPhysicalRows(`     ${TAB_LINE}`, 80) > 1,
+    'precondition: a raw TAB line tab-expands past cols (would wrap without the fix)');
+
+  const bodyRows = band.filter((l) => /x/.test(stripAllEsc(l)));
+  assert.ok(bodyRows.length >= 5, 'the preview TAB lines surfaced');
+  for (const line of bodyRows) {
+    assert.ok(!stripAllEsc(line).includes('\t'), 'TAB flattened to spaces in the band line');
+    assert.strictEqual(realPhysicalRows(line, 80), 1, 'tab-aware: line is exactly one physical row');
+    assert.strictEqual(displayRows(line, 80), 1, 'writer-side displayRows agrees it is one row');
+  }
+  // Logical-line count == physical-row count → the writer's erase math is honest.
+  assert.strictEqual(writer.physicalRows(band, 80), band.length,
+    'band logical line count equals its physical-row total (the restored invariant)');
+});
+
+// ── (b) the real writer renders the band at its true height; commit clears it ──
+
+// Minimal terminal model that expands TABs to 8-col tab stops AND autowraps at
+// `cols` — so a band line that wraps shows up as MULTIPLE physical rows, exactly
+// what the writer's TAB=1 _liveHeight cannot see. rows.length is the committed
+// physical footprint; an undercounting erase makes it GROW.
+function makeTabVT(cols) {
+  const rows = [''];
+  let r = 0, c = 0;
+  const ensure = (row) => { while (rows.length <= row) rows.push(''); };
+  const putChar = (ch) => {
+    if (c >= cols) { r++; c = 0; ensure(r); }
+    ensure(r);
+    rows[r] = rows[r].slice(0, c) + ch + rows[r].slice(c + 1);
+    c++;
+  };
+  function write(s) {
+    let i = 0;
+    while (i < s.length) {
+      const ch = s[i];
+      if (ch === '\x1b' && s[i + 1] === '[') {
+        let j = i + 2, params = '';
+        while (j < s.length && /[0-9;?<>]/.test(s[j])) { params += s[j]; j++; }
+        const final = s[j]; const n = parseInt(params, 10) || 1;
+        if (final === 'A') r = Math.max(0, r - n);
+        else if (final === 'B') { r += n; ensure(r); }
+        else if (final === 'C') c += n;
+        else if (final === 'D') c = Math.max(0, c - n);
+        else if (final === 'J') { ensure(r); rows[r] = rows[r].slice(0, c); rows.length = r + 1; }
+        i = j + 1; continue;
+      }
+      if (ch === '\x1b') { i += 1; continue; }
+      if (ch === '\n') { r++; c = 0; ensure(r); i++; continue; }
+      if (ch === '\r') { c = 0; i++; continue; }
+      if (ch === '\t') {
+        const target = (Math.floor(c / 8) + 1) * 8;
+        for (let k = c; k < target; k++) putChar(' ');
+        i++; continue;
+      }
+      putChar(ch); i++;
+    }
+  }
+  return { rows, write };
+}
+
+test('(b) real writer: large TAB band renders at its true physical height; commit clears it, no wide rows', () => {
+  const vt = makeTabVT(80);
+  const out = process.stdout;
+  const prev = { isTTY: out.isTTY, columns: out.columns, rows: out.rows, write: out.write };
+  out.isTTY = true; out.columns = 80; out.rows = 24;
+  out.write = (s) => { vt.write(String(s)); return true; };
+  const ch = new ChatHistory();
+  ch._notifyLive = () => {};
+  return (async () => {
+    try {
+      await writer.setLive(['separator', 'status', '> input']); // 3 single-row chrome lines
+      await writer.flush();
+      // Install the deferred band once (no toggling — the band is a one-shot static
+      // path now). Every emitted band line is flattened to a single physical row.
+      ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: tabOutput(8), previewLines: 5 });
+      await writer.flush();
+      const band = writer.getDetailLines();
+      for (const l of band) assert.strictEqual(realPhysicalRows(l, 80), 1, 'each emitted band row is one physical row');
+      assert.strictEqual(writer.getLiveHeight(), band.length + 3,
+        '_liveHeight equals the true physical height (band + chrome)');
+
+      // Commit once → band moves to scrollback, the live region is back to chrome.
+      ch.commitDeferredDetail();
+      await writer.flush();
+      assert.deepStrictEqual(writer.getDetailLines(), [], 'band cleared after commit');
+      assert.ok(vt.rows.every((row) => stripAllEsc(row).length <= 80), 'no row wider than cols remains on screen');
+    } finally {
+      await writer.clearLive(); await writer.flush();
+      out.isTTY = prev.isTTY; out.columns = prev.columns; out.rows = prev.rows; out.write = prev.write;
+    }
+  })();
+});
+
+// ── (c) a stray non-SGR escape (\x1b[K) counts/renders as one row, no over-count ─
+
+test('(c) stray escape: a band line with \\x1b[K is one physical row (no displayRows over-count)', () => {
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  // Visible content sized to the fit budget (cols-6 = 74), then a stray \x1b[K.
+  // truncateVisible keeps the (0-width) CSI; pre-fix displayRows' SGR-only strip
+  // counts ESC[K as 3 cols → 5(indent)+74+3 = 82 > 80 → a phantom 2nd row.
+  const noisy = 'z'.repeat(74) + '\x1b[K';
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: Array(8).fill(noisy).join('\n'), previewLines: 5 });
+  const band = lastSetDetail(log);
+  const bodyRows = band.filter((l) => /z/.test(stripAllEsc(l)));
+  assert.ok(bodyRows.length >= 5, 'the preview lines surfaced');
+  for (const line of bodyRows) {
+    assert.ok(!/\x1b\[K/.test(line), 'stray non-SGR escape dropped from the band line');
+    assert.strictEqual(displayRows(line, 80), 1, 'no over-count: exactly one physical row');
+    assert.strictEqual(realPhysicalRows(line, 80), 1, 'tab/wrap-aware oracle agrees');
+  }
+});
+
+// ── (d) plain-ASCII output is byte-identical — flatten is a no-op ──────────────
+
+test('(d) plain ASCII: flatten is a no-op — committed band byte-identical to addMessage', () => {
+  const mkLines = (n) => Array.from({ length: n }, (_, i) => `line ${i + 1}`).join('\n');
+  // Reference: the immediate addMessage commit for the same clean output.
+  const ref = new ChatHistory();
+  const refOut = [];
+  ref._commit = (t) => refOut.push(t);
+  ref._notifyLive = () => {};
+  ref.addMessage({ role: 'tool', tag: 'shell', content: '', output: mkLines(20), previewLines: 5 });
+  const expected = refOut.join('');
+
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: mkLines(20), previewLines: 5 });
+  ch.commitDeferredDetail();
+  const commit = log.filter((e) => e.op === 'commitDetail')[0].text;
+  assert.strictEqual(commit, expected, 'clean output commit is byte-identical to addMessage (flatten no-op)');
+});
+
+// ── (e) live vs committed render of the same TAB output stay consistent ────────
+
+test('(e) live/replay consistency: live band and committed text are BOTH flattened and agree on body', () => {
+  const ch = new ChatHistory();
+  const log = instrument(ch);
+  ch.deferToolOutput({ role: 'tool', tag: 'shell', content: '', output: tabOutput(10), previewLines: 5 });
+  const liveBand = lastSetDetail(log);
+  ch.commitDeferredDetail();             // committed (replay) text
+  const committed = log.filter((e) => e.op === 'commitDetail')[0].text;
+
+  assert.ok(!liveBand.some((l) => l.includes('\t')), 'live band carries no raw TABs');
+  assert.ok(!committed.includes('\t'), 'committed/replay text carries no raw TABs');
+
+  // The flattened body rows match between the live band and the commit (the band is
+  // committed verbatim — installed once, committed once).
+  const liveBody = liveBand.map(stripAllEsc).filter((l) => /x/.test(l));
+  const commitBody = committed.split('\n').map(stripAllEsc).filter((l) => /x/.test(l));
+  assert.deepStrictEqual(commitBody, liveBody, 'live and committed body rows are identical (both flattened)');
+});