@semalt-ai/code 1.8.1 → 1.8.4

package/lib/ui/writer.js

@@ -0,0 +1,603 @@
+'use strict';
+
+// Single owner of process.stdout for the TUI. All bubble rendering, status
+// bar ticks, and prompt redraws go through this module so their writes can
+// never interleave mid-frame.
+//
+// Layout (bottom-up):
+//   SCROLLBACK   — everything the writer emits via scrollback(). Immutable
+//                  after the call resolves. Flows into terminal scrollback
+//                  naturally as the cursor advances past the bottom.
+//   MODAL REGION — optional. 0–N lines pushed via setModal(); cleared via
+//                  clearModal(). Used for permission pickers, confirmation
+//                  dialogs, and other modal widgets that must redraw in
+//                  place on every keystroke without landing in scrollback.
+//   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.
+//
+// Invariant: after any operation resolves, the cursor is at column 0 of the
+// row immediately below the status region. Every operation erases the
+// combined modal+status region first (cursor-up + \x1b[J), writes any
+// scrollback content, then redraws modal then status, then leaves the
+// cursor below them.
+//
+// Serialization is a plain Promise chain. process.stdout.write on a TTY is
+// 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');
+
+let _queue = Promise.resolve();
+let _liveLines = [];
+let _modalLines = [];
+// 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.
+//
+// Entry shape:
+//   {
+//     startedAt: number,              // performance clock origin
+//     render:    (elapsedMs) => str,  // rebuilt on every redraw
+//     visible:   boolean,             // false during grace period
+//     graceTimer: Timeout | null,     // cleared on end/cancel
+//   }
+//
+// Grace period: startActivity schedules visibility for graceMs later
+// (default 200 ms) so fast tools complete and land straight in scrollback
+// without flashing a pending line. endActivity before the timer fires
+// cancels visibility; the entry never rendered.
+const _activity = new Map();
+let _liveHeight = 0;
+let _destroyed = false;
+let _previousLiveLineCount;
+// Caret position within the live region, cached across ops so that ticks
+// from the status-bar clock, modal changes, etc. can keep the OS cursor at
+// the input caret without the caller re-sending it every time.
+//   { rowsFromBottom, col }
+//     rowsFromBottom — how many rows up from the "below-live-region" cursor
+//                      position the caret sits. 1 = last live row, 2 = row
+//                      above the last, etc.
+//     col            — 0-indexed display column on that row.
+// null when no caret should be shown (input disabled, nav-capture, etc.).
+let _caret = null;
+
+function _cols() { return process.stdout.columns || 80; }
+
+// 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
+// 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.
+function _fitOneRow(line) {
+  if (!line) return '';
+  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
+  // because stripped length is otherwise only an upper/lower bound
+  // depending on what non-ASCII codepoints are present.
+  const stripped = stripAnsi(line);
+  if (stripped.length <= max) {
+    let ascii = true;
+    for (let i = 0; i < stripped.length; i++) {
+      if (stripped.charCodeAt(i) > 0x7F) { ascii = false; break; }
+    }
+    if (ascii) return line;
+  }
+  return truncateVisible(line, max);
+}
+
+function _eraseLiveSeq() {
+  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".
+  // Cursor-up from there by the full _liveHeight would land above the live
+  // region entirely and erase scrollback. Compensate by subtracting the
+  // known offset so we always land on the first live row.
+  const offset = _caret ? _caret.rowsFromBottom : 0;
+  const up = Math.max(0, _liveHeight - offset);
+  return `${up > 0 ? `\x1b[${up}A` : ''}\r\x1b[J`;
+}
+
+// Collect visible activity entries in insertion order. Entries whose grace
+// period hasn't elapsed are hidden and don't contribute to _liveHeight.
+function _visibleActivity() {
+  const rows = [];
+  if (_activity.size === 0) return rows;
+  const now = Date.now();
+  for (const entry of _activity.values()) {
+    if (!entry.visible) continue;
+    let line = '';
+    try { line = entry.render(now - entry.startedAt); } catch {}
+    rows.push(line);
+  }
+  return rows;
+}
+
+function _drawLiveSeq() {
+  const activityRows = _visibleActivity();
+  const total = activityRows.length + _modalLines.length + _liveLines.length;
+  if (total === 0) { _liveHeight = 0; return ''; }
+  let out = '';
+  for (let i = 0; i < activityRows.length; i++) {
+    out += _fitOneRow(activityRows[i]);
+    out += '\n';
+  }
+  for (let i = 0; i < _modalLines.length; i++) {
+    out += _fitOneRow(_modalLines[i]);
+    out += '\n';
+  }
+  for (let i = 0; i < _liveLines.length; i++) {
+    out += _fitOneRow(_liveLines[i]);
+    out += '\n';
+  }
+  _liveHeight = total;
+  return out;
+}
+
+// Reposition the OS cursor to the cached caret inside the freshly drawn
+// live region. Expects the cursor to start at "below-live-region" (col 0
+// of the row under the last live row) — the normal post-draw state.
+// Returns an empty string when no caret is active, which leaves the cursor
+// where _drawLiveSeq left it (below the region) and keeps it hidden.
+function _positionCaretSeq() {
+  if (!_caret || _liveHeight <= 0) return '';
+  let { rowsFromBottom, col } = _caret;
+  if (rowsFromBottom <= 0 || rowsFromBottom > _liveHeight) return '';
+  // Clamp caret col to fit inside the truncated row. _fitOneRow trims each
+  // rendered line to cols-1 to guarantee a single physical row, so a caret
+  // beyond cols-1 would wrap to the next row — which isn't the input row.
+  const maxCol = Math.max(0, _cols() - 1);
+  if (col > maxCol) col = maxCol;
+  let out = `\x1b[${rowsFromBottom}A\r`;
+  if (col > 0) out += `\x1b[${col}C`;
+  return out;
+}
+
+// Build the cursor-visibility envelope for a redraw: hide at start, and
+// after drawing either position+show (caret active) or leave hidden
+// (caret null — e.g., during a modal or while input is disabled).
+function _caretShowSeq() {
+  if (!_caret || _liveHeight <= 0) return '';
+  return '\x1b[?25h';
+}
+
+function _writeSync(s) {
+  if (!s) return;
+  try { process.stdout.write(s); } catch {}
+}
+
+function _enqueue(task) {
+  _queue = _queue.then(() => {
+    if (_destroyed) return;
+    try { task(); } catch {}
+  });
+  return _queue;
+}
+
+// Hide at the start of every compound write, show only after positioning the
+// cursor at the caret. This is a belt-and-suspenders measure on top of the
+// explicit positioning: intermediate cursor steps during erase/draw can't
+// flash at the wrong column because the cursor is invisible while they run.
+const _HIDE = '\x1b[?25l';
+
+// Append text to scrollback (above the live region). The compound write
+// erases the live region, emits text, redraws the live region — all in a
+// single process.stdout.write so nothing can interleave.
+//
+// Non-TTY fast path: no live region exists when stdout is piped to a script
+// or file — emit the text plain, with no cursor-hide/show envelope, so
+// `--version | head` produces "1.8.3\n" rather than "\x1b[?25l1.8.3\n".
+function scrollback(text) {
+  if (text === undefined || text === null || text === '') return _queue;
+  return _enqueue(() => {
+    let out = String(text);
+    if (!out.endsWith('\n')) out += '\n';
+    if (!process.stdout.isTTY) { _writeSync(out); return; }
+    _writeSync(_HIDE + _eraseLiveSeq() + out + _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq());
+  });
+}
+
+// Replace the live region with `lines` (array of strings, usually 1–10).
+// Each line is truncated to cols-1 and occupies exactly one physical row.
+// `caret` (optional) is `{ rowsFromBottom, col }`: after drawing, the OS
+// cursor is moved up rowsFromBottom rows from below-live-region and right
+// to `col` on that row, then shown. Pass null/undefined to keep the cursor
+// hidden below the live region (used during disabled/modal states).
+function setLive(lines, caret) {
+  return _enqueue(() => {
+    // Erase using the PREVIOUS caret/liveHeight: the cursor is still at the
+    // position the previous burst left it (caret position when _caret was
+    // non-null, below-region otherwise). Updating _caret before _eraseLiveSeq
+    // would compute the up-step from the NEW caret while the cursor still
+    // sits at the OLD position, leaving the top rows of the prior live
+    // region frozen in scrollback whenever the caret transitions in or out
+    // of null (input disabled ↔ enabled across an agent turn).
+    const eraseSeq = _eraseLiveSeq();
+    _liveLines = Array.isArray(lines) ? lines.map((l) => (l == null ? '' : String(l))) : [];
+    _caret = caret && typeof caret === 'object' &&
+             Number.isFinite(caret.rowsFromBottom) && Number.isFinite(caret.col)
+      ? { rowsFromBottom: caret.rowsFromBottom | 0, col: Math.max(0, caret.col | 0) }
+      : null;
+    // The input row's visible position is relative to the bottom of the
+    // viewport; it stays still only while the live region keeps a stable
+    // height. If a code path sneaks in a different-height setLive call the
+    // input jumps one row. Log under DEBUG_TUI so future drift is visible
+    // without leaking into the TUI itself.
+    if (process.env.DEBUG_TUI &&
+        _previousLiveLineCount !== undefined &&
+        _previousLiveLineCount !== _liveLines.length) {
+      try {
+        process.stderr.write(
+          `live region height changed: ${_previousLiveLineCount} → ${_liveLines.length}\n`
+        );
+      } catch {}
+    }
+    _previousLiveLineCount = _liveLines.length;
+    _writeSync(_HIDE + eraseSeq + _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq());
+  });
+}
+
+// Erase the live region entirely — used on teardown and when handing the
+// terminal off to a sub-renderer (e.g. interactive menus). Drops the modal
+// too so the sub-renderer doesn't paint over a ghost modal.
+function clearLive() {
+  return _enqueue(() => {
+    _writeSync(_HIDE + _eraseLiveSeq());
+    _liveLines = [];
+    _modalLines = [];
+    for (const entry of _activity.values()) {
+      if (entry.graceTimer) { try { clearTimeout(entry.graceTimer); } catch {} }
+    }
+    _activity.clear();
+    _liveHeight = 0;
+    _caret = null;
+  });
+}
+
+// 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
+// filling scrollback. Status region is untouched; scrollback is untouched.
+function setModal(lines) {
+  return _enqueue(() => {
+    // Erase first using the previous caret position — see setLive() for why.
+    const eraseSeq = _eraseLiveSeq();
+    _modalLines = Array.isArray(lines) ? lines.map((l) => (l == null ? '' : String(l))) : [];
+    // Modal is active → suppress caret (input is not visible/usable).
+    _caret = null;
+    _writeSync(_HIDE + eraseSeq + _drawLiveSeq());
+  });
+}
+
+// Remove the modal region. Status region stays where it was. Caret stays
+// null here — the next setLive from the orchestrator reattaches it.
+function clearModal() {
+  return _enqueue(() => {
+    if (_modalLines.length === 0) return;
+    // Erase first using the previous caret position — see setLive() for why.
+    const eraseSeq = _eraseLiveSeq();
+    _modalLines = [];
+    _caret = null;
+    _writeSync(_HIDE + eraseSeq + _drawLiveSeq());
+  });
+}
+
+function hasModal() { return _modalLines.length > 0; }
+
+// ── Activity region ─────────────────────────────────────────────────────────
+//
+// Pending tool lines that must update in place with a growing timer. Each
+// call to startActivity adds one row above modal; endActivity atomically
+// removes it and commits a final line to scrollback. cancelActivity drops
+// 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.
+
+const DEFAULT_ACTIVITY_GRACE_MS = 200;
+
+function startActivity(id, render, options) {
+  if (!id || typeof render !== 'function') return _queue;
+  const opts = options || {};
+  const graceMs = Number.isFinite(opts.graceMs) ? Math.max(0, opts.graceMs | 0) : DEFAULT_ACTIVITY_GRACE_MS;
+  return _enqueue(() => {
+    // If an entry with this id is somehow still around, drop its timer
+    // before replacing — don't leak pending timers across invocations.
+    const prev = _activity.get(id);
+    if (prev && prev.graceTimer) { try { clearTimeout(prev.graceTimer); } catch {} }
+    const entry = {
+      startedAt: Date.now(),
+      render,
+      visible: graceMs === 0,
+      graceTimer: null,
+    };
+    _activity.set(id, entry);
+    if (graceMs > 0) {
+      entry.graceTimer = setTimeout(() => {
+        // Promote to visible and trigger a redraw via the writer queue so
+        // the render lands in order with any in-flight scrollback pushes.
+        const current = _activity.get(id);
+        if (!current || current !== entry) return;
+        current.visible = true;
+        current.graceTimer = null;
+        _enqueue(() => {
+          if (!_activity.has(id) || _destroyed) return;
+          _writeSync(_HIDE + _eraseLiveSeq() + _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq());
+        });
+      }, graceMs);
+      // Don't block Node exit on a pending activity timer — the process
+      // should be free to shut down if nothing else is holding it open.
+      if (typeof entry.graceTimer.unref === 'function') entry.graceTimer.unref();
+    } else {
+      _writeSync(_HIDE + _eraseLiveSeq() + _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq());
+    }
+  });
+}
+
+function updateActivity(id, render) {
+  if (!id || typeof render !== 'function') return _queue;
+  return _enqueue(() => {
+    const entry = _activity.get(id);
+    if (!entry) return;
+    entry.render = render;
+    if (!entry.visible) return; // still in grace period
+    _writeSync(_HIDE + _eraseLiveSeq() + _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq());
+  });
+}
+
+// Remove a pending entry and commit `finalLine` to scrollback in a single
+// compound write — the erase, scrollback append, and redraw all land
+// together so a concurrent writer task cannot interleave between them.
+function endActivity(id, finalLine) {
+  return _enqueue(() => {
+    const entry = _activity.get(id);
+    if (entry && entry.graceTimer) { try { clearTimeout(entry.graceTimer); } catch {} }
+    _activity.delete(id);
+    let out = _HIDE + _eraseLiveSeq();
+    if (finalLine !== undefined && finalLine !== null && finalLine !== '') {
+      let line = String(finalLine);
+      if (!line.endsWith('\n')) line += '\n';
+      out += line;
+    }
+    out += _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq();
+    _writeSync(out);
+  });
+}
+
+function cancelActivity(id) {
+  return _enqueue(() => {
+    const entry = _activity.get(id);
+    if (!entry) return;
+    if (entry.graceTimer) { try { clearTimeout(entry.graceTimer); } catch {} }
+    _activity.delete(id);
+    _writeSync(_HIDE + _eraseLiveSeq() + _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq());
+  });
+}
+
+// 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;
+}
+
+// Re-emit the current live region at the current terminal width. Called on
+// resize: the truncation window changes but the underlying line data is the
+// same.
+function redrawLive() {
+  return _enqueue(() => {
+    _writeSync(_HIDE + _eraseLiveSeq() + _drawLiveSeq() + _positionCaretSeq() + _caretShowSeq());
+  });
+}
+
+// Resolve once every enqueued task has run. Used at exit / hand-off points.
+function flush() { return _queue; }
+
+// Enqueue an arbitrary synchronous side-effect so it runs in order with
+// writes. Handy for terminal mode toggles (cursor show/hide, bracketed
+// paste on/off) that must not land inside another task's compound write.
+// The callback can use process.stdout.write directly for raw escapes but
+// must not produce scrollback output — use scrollback() for that.
+function enqueue(fn) {
+  return _enqueue(() => { fn(); });
+}
+
+function getLiveHeight() { return _liveHeight; }
+function getLiveLines()  { return _liveLines.slice(); }
+
+function destroy() { _destroyed = true; }
+
+// Synchronous, single-write cleanup for every exit path. Erases the live
+// region (which is chrome, not content), emits end-of-session artifacts
+// (session summary, resume hint, goodbye message) as regular scrollback
+// content, resets the terminal modes the TUI turned on at startup, and
+// lands the cursor at column 0 of the row immediately below those
+// artifacts — so the shell prompt prints cleanly under the session's last
+// line of output.
+//
+// Artifacts are emitted here rather than via post-destroy console.log for
+// two reasons:
+//   1. Atomicity — they must land in the erased region in a single write,
+//      so nothing (a queued task, a stray signal-handler write, a shell
+//      that reclaims the tty too early) can interleave between "erase" and
+//      "append".
+//   2. Line-ending safety — the TUI has been running in raw mode, which
+//      disables OPOST on some platforms. Inside teardown we emit explicit
+//      CRLF so every artifact line starts at column 0, regardless of
+//      whether ONLCR is still active when the write lands. Post-destroy
+//      console.log relied on ONLCR being restored in time, which is how
+//      artifacts ended up drawn with the cursor drifting to the right of
+//      the previous row (producing "Goodbye!bonus-1.webp" collisions).
+//
+// Must be idempotent: 'exit' fires after handlers that already called
+// teardown manually, and signal handlers may overlap during a fast Ctrl+C.
+// Idempotency is by first-call-wins: the first teardown(...) may receive
+// artifacts and emit them; a subsequent no-arg teardown() from the 'exit'
+// handler is a no-op.
+//
+// Must be a single process.stdout.write of one pre-built string. Anything
+// else risks interleaving with a queued task that hadn't drained yet, or
+// with another writer-bypassing module emitting partial output. Setting
+// _destroyed before the write turns every queued task into a no-op so they
+// can't repaint over our cleanup.
+let _torn = false;
+
+// Convert any bare LF inside an artifact to CRLF. Artifacts arrive built
+// by console.log-style callers that join lines with '\n' — that works when
+// ONLCR translates LF→CRLF at the device, but the live-region TUI runs in
+// raw mode where OPOST may be cleared, so we carriage-return explicitly.
+function _toCrlf(s) {
+  if (!s) return '';
+  // Normalize any \r\n that's already in the input to a single \n first,
+  // so replacing \n → \r\n doesn't produce \r\r\n.
+  return String(s).replace(/\r\n/g, '\n').replace(/\n/g, '\r\n');
+}
+
+function teardown(opts) {
+  if (_torn) return;
+  _torn = true;
+  _destroyed = true;
+
+  const artifacts = opts || {};
+  const summary    = artifacts.summary    ? String(artifacts.summary)    : '';
+  const resumeHint = artifacts.resumeHint ? String(artifacts.resumeHint) : '';
+  const goodbye    = artifacts.goodbye    ? String(artifacts.goodbye)    : '';
+  const hasAny = !!(summary || resumeHint || goodbye);
+
+  // Non-TTY: no escape sequences were ever emitted. Still emit the
+  // artifacts so piped/logged runs show the session summary in their
+  // output stream.
+  if (!process.stdout.isTTY) {
+    if (hasAny) {
+      let out = '';
+      if (summary)    out += summary + '\n';
+      if (resumeHint) out += (summary ? '\n' : '') + resumeHint + '\n';
+      if (goodbye)    out += (summary || resumeHint ? '\n' : '') + goodbye + '\n';
+      try { process.stdout.write(out); } catch {}
+    }
+    return;
+  }
+
+  const parts = [];
+
+  // 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.
+  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');
+  } 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
+    // upstream write left the cursor drifting.
+    parts.push('\r');
+  }
+  _caret = null;
+
+  // Reset SGR before emitting artifacts so chrome styling from the erased
+  // live region can't bleed into the summary box's first row.
+  parts.push('\x1b[0m');
+
+  // Emit artifacts as regular scrollback content. Each artifact starts on
+  // a fresh row at column 0; artifacts are separated from the previous
+  // scrollback and from each other by one blank line. Every newline is
+  // carriage-returned explicitly so nothing depends on the terminal's
+  // current ONLCR state at teardown time.
+  if (hasAny) {
+    const present = [];
+    if (summary)    present.push(_toCrlf(summary));
+    if (resumeHint) present.push(_toCrlf(resumeHint));
+    if (goodbye)    present.push(_toCrlf(goodbye));
+    // Leading blank line: separates artifacts from the last line of the
+    // previous scrollback (which may have been flush against the erased
+    // live region).
+    parts.push('\r\n');
+    // Join with a blank line between each artifact, and terminate the
+    // final artifact so the cursor lands on a fresh row afterward.
+    parts.push(present.join('\r\n\r\n'));
+    parts.push('\r\n');
+  }
+
+  // Terminal mode resets. Non-visible; order doesn't affect layout.
+  parts.push('\x1b[?25h');   // show OS cursor
+  parts.push('\x1b[r');      // reset DECSTBM scroll region (no-op if unset)
+  parts.push('\x1b[<u');     // pop kitty keyboard protocol
+  parts.push('\x1b[>4;0m');  // reset xterm modifyOtherKeys
+  parts.push('\x1b[?2004l'); // disable bracketed paste
+
+  // Scroll the viewport's worth of TUI content off-screen into scrollback so
+  // the shell prompt renders on an empty viewport rather than overlaid on
+  // stale TUI rows. Uses \r\n because we may still be in raw mode (OPOST off)
+  // at this point — plain \n wouldn't return the cursor to column 0.
+  parts.push('\r\n'.repeat(process.stdout.rows || 24));
+
+  _liveLines = [];
+  _modalLines = [];
+  for (const entry of _activity.values()) {
+    if (entry.graceTimer) { try { clearTimeout(entry.graceTimer); } catch {} }
+  }
+  _activity.clear();
+  _liveHeight = 0;
+
+  try { process.stdout.write(parts.join('')); } catch {}
+
+  // Restore stdin to cooked mode so the shell receives keystrokes normally.
+  // Done after the stdout write so a slow/blocking setRawMode can't delay
+  // the visible cleanup.
+  try {
+    if (process.stdin.isTTY && typeof process.stdin.setRawMode === 'function') {
+      process.stdin.setRawMode(false);
+    }
+  } catch {}
+}
+
+module.exports = {
+  scrollback,
+  setLive,
+  clearLive,
+  setModal,
+  clearModal,
+  hasModal,
+  startActivity,
+  updateActivity,
+  endActivity,
+  cancelActivity,
+  refreshActivity,
+  hasActivity,
+  redrawLive,
+  flush,
+  enqueue,
+  getLiveHeight,
+  getLiveLines,
+  destroy,
+  teardown,
+};

package/lib/ui.js

@@ -4,12 +4,13 @@ const ansi     = require('./ui/ansi');
 const utils    = require('./ui/utils');
 const diff     = require('./ui/diff');
 const stream   = require('./ui/stream');
-const legacy   = require('./ui/legacy');
+const select   = require('./ui/select');
 const layout   = require('./ui/layout');
 const history  = require('./ui/chat-history');
 const statusB  = require('./ui/status-bar');
 const input    = require('./ui/input-field');
 const createUi = require('./ui/create-ui');
+const terminal = require('./ui/terminal');
 
 module.exports = {
   // ANSI constants
@@ -21,9 +22,9 @@ module.exports = {
 
   // Utilities
   getCols: utils.getCols, getRows: utils.getRows, stripAnsi: utils.stripAnsi,
-  hr: utils.hr, boxLine: utils.boxLine,
+  boxLine: utils.boxLine,
   insertCharAt: utils.insertCharAt, removeCharAt: utils.removeCharAt,
-  isPrintableKey: utils.isPrintableKey,
+  isPrintableKey: utils.isPrintableKey, approxTokens: utils.approxTokens,
 
   // Diff + Markdown
   renderDiff: diff.renderDiff, renderMarkdown: diff.renderMarkdown,
@@ -31,9 +32,9 @@ module.exports = {
   // Stream renderer
   StreamRenderer: stream.StreamRenderer,
 
-  // Legacy (still-active) components
-  StatusBar: legacy.StatusBar, interactiveSelect: legacy.interactiveSelect,
-  SelectMenu: legacy.SelectMenu,
+  // Modal-region select menu (used by cmdModels, captureSelect, and the
+  // non-TUI permission picker fallback).
+  interactiveSelect: select.interactiveSelect,
 
   // TUI components
   LayoutManager: layout.LayoutManager,
@@ -44,4 +45,8 @@ module.exports = {
 
   // Factory
   createUI: createUi.createUI,
+
+  // Terminal teardown
+  teardownTerminal: terminal.teardownTerminal,
+  registerTerminalCleanup: terminal.registerTerminalCleanup,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semalt-ai/code",
-  "version": "1.8.1",
+  "version": "1.8.4",
   "description": "Self-hosted AI Coding Assistant CLI",
   "main": "index.js",
   "bin": {