flint-agent 1.14.0

package/src/ui/output.js

@@ -0,0 +1,399 @@
+// Output formatting module
+// Single source of truth for all chat output styling and indentation
+//
+// Hierarchy:
+//   USER     "  > message"                    (highlighted bg)
+//   AGENT    "  text"                         (normal, 2-space indent)
+//   TOOL     "    tool -> result"             (dim, 4-space indent)
+//   CHILD    "  ✦ Agent@port:"               (cyan, with box drawing)
+//   CHILD    "  │ response line"              (cyan border)
+//   PROCESS  "  ┌ [bg:1] command"            (dim, with box drawing)
+//   PROCESS  "  │ output line"               (dim)
+//   PROCESS  "  └ [bg:1] exit 0"             (dim)
+//   SYSTEM   "  italic system info"          (gray)
+//   STATS    "  --- cost | session"           (dim)
+
+import chalk from "chalk";
+import { processLedgerLine } from "./tool-ledger.js";
+import { highlight as hlHighlight } from "cli-highlight";
+import { createLogger } from "../logging/logger.js";
+
+const log = createLogger("ui-output");
+
+let _store = null;
+
+export function initOutput(store) {
+  log.debug("initOutput", { hasStore: !!store });
+  _store = store;
+}
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function addLine(text) {
+  const plain = (text || "").replace(ANSI_RE, "").slice(0, 80);
+  log.debug("addLine", { len: (text || "").length, preview: plain });
+  _store.getState().addLine(text);
+}
+
+// Word-wrap text to fit terminal width, preserving indent on wrapped lines
+function wrapLines(indent, text, cols) {
+  const maxWidth = cols - indent.length;
+  if (maxWidth <= 10) { addLine(indent + text); return; }
+  const plain = text.replace(ANSI_RE, "");
+  if (plain.length <= maxWidth) { addLine(indent + text); return; }
+  // Split on words, re-wrap
+  const words = text.split(" ");
+  let line = "";
+  let lineLen = 0;
+  for (const word of words) {
+    const wordLen = word.replace(ANSI_RE, "").length;
+    if (lineLen > 0 && lineLen + 1 + wordLen > maxWidth) {
+      addLine(indent + line);
+      line = word;
+      lineLen = wordLen;
+    } else {
+      line = lineLen > 0 ? line + " " + word : word;
+      lineLen = lineLen > 0 ? lineLen + 1 + wordLen : wordLen;
+    }
+  }
+  if (line) addLine(indent + line);
+}
+
+// --- User message (highlighted bar) ---
+export function printUser(text) {
+  const cols = process.stdout.columns || 80;
+  const ANSI_RE = /\x1b\[[0-9;]*m/g;
+  const plain = text.replace(ANSI_RE, "");
+  const pad = Math.max(0, cols - plain.length - 2);
+  addLine("");
+  addLine(chalk.bgGray.whiteBright(` ${text}${" ".repeat(pad)} `));
+  addLine("");
+}
+
+// --- Inline markdown rendering ---
+function renderMarkdown(text) {
+  // Code blocks (``` ... ```) — already handled line-by-line in printAgent
+  // Inline code `text`
+  text = text.replace(/`([^`]+)`/g, (_, code) => chalk.cyan(code));
+  // Bold **text** or __text__
+  text = text.replace(/\*\*([^*]+)\*\*/g, (_, b) => chalk.bold(b));
+  text = text.replace(/__([^_]+)__/g, (_, b) => chalk.bold(b));
+  // Italic *text* or _text_ (but not inside words like file_name)
+  text = text.replace(/(?<!\w)\*([^*]+)\*(?!\w)/g, (_, i) => chalk.italic(i));
+  text = text.replace(/(?<!\w)_([^_]+)_(?!\w)/g, (_, i) => chalk.italic(i));
+  return text;
+}
+
+// Track code block state across calls
+let _inCodeBlock = false;
+let _codeBlockLang = "";
+let _codeBlockLines = [];
+
+// Track markdown table buffering across calls
+let _tableBuffer = [];
+
+// Markdown table line: starts and ends with |, has at least one inner |
+const TABLE_LINE_RE = /^\s*\|.+\|\s*$/;
+// Separator line: | --- | --- | (with optional colons for alignment)
+const TABLE_SEP_RE = /^\s*\|[\s:]*-{2,}[\s:]*\|/;
+
+function flushTable() {
+  if (_tableBuffer.length < 2) {
+    // Not enough lines for a table — dump as plain text
+    for (const line of _tableBuffer) {
+      wrapLines("  ", renderMarkdown(line), process.stdout.columns || 80);
+    }
+    _tableBuffer = [];
+    return;
+  }
+
+  // Find separator row
+  let sepIdx = _tableBuffer.findIndex((l) => TABLE_SEP_RE.test(l));
+  let headerRow, dataRows;
+
+  if (sepIdx === 1) {
+    // Standard: header, separator, data rows
+    headerRow = _tableBuffer[0];
+    dataRows = _tableBuffer.slice(2);
+  } else if (sepIdx === 0) {
+    // Separator first — treat first data row as header
+    headerRow = _tableBuffer[1] || "";
+    dataRows = _tableBuffer.slice(2);
+  } else {
+    // No separator — first row is header, rest are data
+    headerRow = _tableBuffer[0];
+    dataRows = _tableBuffer.slice(1);
+  }
+
+  const parseRow = (line) =>
+    line.split("|").slice(1, -1).map((c) => c.trim());
+
+  const columns = parseRow(headerRow);
+  const rows = dataRows
+    .filter((l) => !TABLE_SEP_RE.test(l)) // skip any extra separators
+    .map(parseRow);
+
+  if (columns.length > 0 && rows.length > 0) {
+    _store.getState().addTable({ columns, rows });
+  } else {
+    // Fallback: dump as text
+    for (const line of _tableBuffer) {
+      wrapLines("  ", renderMarkdown(line), process.stdout.columns || 80);
+    }
+  }
+
+  _tableBuffer = [];
+}
+
+// --- Agent (main) response line ---
+export function printAgent(text) {
+  const cols = process.stdout.columns || 80;
+
+  // Markdown table lines — buffer and flush as Table component
+  if (!_inCodeBlock && TABLE_LINE_RE.test(text)) {
+    _tableBuffer.push(text);
+    return;
+  }
+  // Non-table line after table buffer — flush table first
+  if (_tableBuffer.length > 0) {
+    flushTable();
+  }
+
+  // Code block fence
+  if (/^```/.test(text)) {
+    if (!_inCodeBlock) {
+      _inCodeBlock = true;
+      _codeBlockLang = text.slice(3).trim();
+      _codeBlockLines = [];
+      return;
+    } else {
+      // Closing fence — flush buffered code with syntax highlighting
+      flushCodeBlock();
+      return;
+    }
+  }
+
+  // Inside code block — buffer lines for syntax highlighting
+  if (_inCodeBlock) {
+    _codeBlockLines.push(text);
+    return;
+  }
+
+  // Markdown headings
+  const headingMatch = text.match(/^(#{1,3})\s+(.+)$/);
+  if (headingMatch) {
+    const level = headingMatch[1].length;
+    const content = headingMatch[2];
+    if (level === 1) { addLine(""); addLine("  " + chalk.bold.underline(content)); addLine(""); }
+    else if (level === 2) { addLine(""); addLine("  " + chalk.bold(content)); }
+    else { addLine("  " + chalk.bold(content)); }
+    return;
+  }
+
+  // Horizontal rule
+  if (/^[-*_]{3,}\s*$/.test(text)) {
+    addLine("  " + chalk.dim("-".repeat(Math.min(40, cols - 4))));
+    return;
+  }
+
+  // Unordered list items
+  const listMatch = text.match(/^(\s*)[*-]\s+(.+)$/);
+  if (listMatch) {
+    const depth = Math.floor(listMatch[1].length / 2);
+    const indent = "  " + "  ".repeat(depth);
+    wrapLines(indent, chalk.dim("-") + " " + renderMarkdown(listMatch[2]), cols);
+    return;
+  }
+
+  // Ordered list items
+  const olMatch = text.match(/^(\s*)\d+\.\s+(.+)$/);
+  if (olMatch) {
+    const depth = Math.floor(olMatch[1].length / 2);
+    const indent = "  " + "  ".repeat(depth);
+    wrapLines(indent, renderMarkdown(olMatch[2]), cols);
+    return;
+  }
+
+  // Regular text with inline markdown
+  wrapLines("  ", renderMarkdown(text), cols);
+}
+
+// Flush buffered code block with syntax highlighting
+function flushCodeBlock() {
+  const code = _codeBlockLines.join("\n");
+  const lang = _codeBlockLang || "";
+  _inCodeBlock = false;
+  _codeBlockLines = [];
+  _codeBlockLang = "";
+
+  addLine("  " + chalk.dim("─".repeat(3) + " " + (lang || "code") + " " + "─".repeat(Math.max(0, 40 - (lang || "code").length))));
+
+  try {
+    const opts = lang ? { language: lang, ignoreIllegals: true } : { ignoreIllegals: true };
+    const highlighted = hlHighlight(code, opts);
+    for (const line of highlighted.split("\n")) {
+      addLine("  " + line);
+    }
+  } catch {
+    // Fallback to cyan if highlighting fails
+    for (const line of code.split("\n")) {
+      addLine("  " + chalk.cyan(line));
+    }
+  }
+
+  addLine("  " + chalk.dim("─".repeat(44)));
+}
+
+// Flush any buffered state (call at end of agent response)
+export function flushAgentState() {
+  log.debug("flushAgentState", { tableBufferLen: _tableBuffer.length, inCodeBlock: _inCodeBlock });
+  if (_tableBuffer.length > 0) flushTable();
+  if (_inCodeBlock && _codeBlockLines.length > 0) flushCodeBlock();
+  _inCodeBlock = false;
+}
+
+// --- Agent streaming placeholder (shown during tool execution) ---
+export function setAgentStream(text) {
+  const plain = (text || "").replace(ANSI_RE, "").slice(0, 60);
+  log.debug("setAgentStream", { len: (text || "").length, preview: plain });
+  _store.getState().setStreamText(text ? `  ${text}` : "");
+}
+
+// --- Background process streaming (one updating line per process) ---
+export function setProcessStream(procId, text) {
+  _store.getState().setProcessStream(procId, text ? `    ${chalk.dim("|")} ${chalk.dim(text)}` : "");
+}
+
+// --- Tool result (compact, dim) ---
+export function printTool(toolName, argsShort, resultShort) {
+  addLine(`    ${chalk.dim(toolName)} ${chalk.dim(argsShort)} ${chalk.dim("->")} ${chalk.gray(resultShort)}`);
+}
+
+export function printToolDenied(toolName, argsShort) {
+  addLine(`    ${chalk.yellow(toolName)} ${chalk.dim(argsShort)} ${chalk.red("DENIED")}`);
+}
+
+
+// --- Child agent response (box with cyan border) ---
+export function printChildAgent(port, response, maxLines = 20, label) {
+  const name = label || `Agent@${port}`;
+  const lines = response.split("\n");
+  const cols = process.stdout.columns || 80;
+  addLine(`  ${chalk.cyan("*")} ${chalk.cyan(`${name}:`)}`);
+  const show = lines.slice(0, maxLines);
+  const border = `  ${chalk.cyan("|")} `;
+
+  // Detect and render markdown tables within child response
+  let tableBuf = [];
+  const flushChildTable = () => {
+    if (tableBuf.length < 2) {
+      for (const tl of tableBuf) wrapLines(border, renderMarkdown(tl), cols);
+      tableBuf = [];
+      return;
+    }
+    const sepIdx = tableBuf.findIndex((l) => TABLE_SEP_RE.test(l));
+    const headerRow = sepIdx === 1 ? tableBuf[0] : tableBuf[0];
+    const dataStart = sepIdx >= 0 ? Math.max(sepIdx + 1, 2) : 1;
+    const parseRow = (l) => l.split("|").slice(1, -1).map((c) => c.trim());
+    const columns = parseRow(headerRow);
+    const rows = tableBuf.slice(dataStart).filter((l) => !TABLE_SEP_RE.test(l)).map(parseRow);
+    if (columns.length > 0 && rows.length > 0) {
+      _store.getState().addTable({ columns, rows });
+    } else {
+      for (const tl of tableBuf) wrapLines(border, renderMarkdown(tl), cols);
+    }
+    tableBuf = [];
+  };
+
+  for (const line of show) {
+    if (TABLE_LINE_RE.test(line)) {
+      tableBuf.push(line);
+      continue;
+    }
+    if (tableBuf.length > 0) flushChildTable();
+    wrapLines(border, renderMarkdown(line), cols);
+  }
+  if (tableBuf.length > 0) flushChildTable();
+
+  if (lines.length > maxLines) {
+    addLine(`  ${chalk.cyan("|")} ${chalk.dim(`... +${lines.length - maxLines} lines`)}`);
+  }
+  addLine(`  ${chalk.cyan("\\-")}`);
+}
+
+// --- Child agent status ---
+export function printChildSpawn(port, pid, label) {
+  const name = label || `agent@${port}`;
+  addLine(`  ${chalk.cyan("*")} ${chalk.cyan(`Spawned ${name} on port ${port}`)} ${chalk.dim(`(pid ${pid})`)}`);
+}
+
+export function printChildEvent(port, text, label) {
+  const name = label || `Agent@${port}`;
+  addLine(`  ${chalk.cyan("*")} ${chalk.dim(`${name} ${text}`)}`);
+}
+
+// --- Background process output (dim, box drawing, 4-space indent) ---
+// A background process's start is the ledger's "sh start" line (its outcome
+// column names the process); only its end and the all-finished summary are
+// printed here, in the ledger's style (owner, 2026-10-01: the start used to be
+// printed twice, once here and once by the ledger).
+export function printProcessEnd(procId, cmd, exitCode, elapsed, status) {
+  // Stopped with /kill: say so, not the exit code taskkill left behind.
+  const how = status === "killed" ? "killed" : exitCode === 0 ? "done" : `exit ${exitCode ?? "?"}`;
+  // After a kill, what is still running and what the next Esc would stop, on
+  // the same line (owner, 2026-10-01: Esc used to print a line of its own and
+  // then this one, two lines for one press).
+  const left = status === "killed"
+    ? (_store?.getState().processes || []).filter((p) => p.status === "running").length
+    : 0;
+  const hint = left ? chalk.dim(`  · ${left} still running, Esc stops the newest`) : "";
+  addLine(processLedgerLine({ verb: how, cmd, procId, elapsed }) + hint);
+}
+
+export function printProcessSummary(total, done, failed, killed) {
+  const parts = [];
+  if (done) parts.push(`${done} done`);
+  if (failed) parts.push(`${failed} failed`);
+  if (killed) parts.push(`${killed} killed`);
+  addLine(chalk.dim(`      ── all ${total} background processes finished: ${parts.join(", ")} ──`));
+}
+
+// --- Stats line ---
+export function printStats(iters, costStr, sessionCost) {
+  addLine(`  ${chalk.dim(`--- ${iters}${costStr} | session $${sessionCost}`)}`);
+}
+
+// --- System / info messages ---
+export function printSystem(text) {
+  addLine(`  ${chalk.gray(text)}`);
+}
+
+export function printWarning(text) {
+  addLine(`  ${chalk.yellow(text)}`);
+}
+
+export function printError(text) {
+  addLine(`  ${chalk.red(text)}`);
+}
+
+// --- Confirmation prompt ---
+/**
+ * One history line for an answered approval. The question itself is shown
+ * only in the live zone while it waits (components/LiveZone.js).
+ */
+export function printConfirmResult(type, toolName = "", argsText = "") {
+  const what = `${toolName}${argsText ? " " + argsText : ""}`.slice(0, 100);
+  if (type === "allow") addLine(chalk.green("  + ") + chalk.dim(what));
+  else if (type === "always") addLine(chalk.green("  + ") + chalk.dim(what) + chalk.green(" (always)"));
+  else addLine(chalk.red("  x denied ") + chalk.dim(what));
+}
+
+// --- Table rendering ---
+export function printTable(columns, rows, title, footer) {
+  _store.getState().addTable({ columns, rows, title, footer });
+}
+
+// --- Blank line ---
+export function printBlank() {
+  addLine("");
+}

package/src/ui/paste-tokens.js

@@ -0,0 +1,131 @@
+// Pasted text and images stand in the input as short tokens (owner,
+// 2026-10-01): a big paste shows as "[Pasted text #1 · 42 lines]", a picture
+// as "[Image #1]". The full text is put back when the message is sent; the
+// history line keeps the token.
+
+// A single input event this big is a paste worth hiding behind a token.
+// Typing and dictation arrive a character or a word at a time, and a paste of
+// two or three lines reads fine as it is.
+const PASTE_MIN_CHARS = 300;
+const PASTE_MIN_LINES = 4;
+// Further chunks of the same paste arrive within this window.
+export const PASTE_MERGE_MS = 150;
+
+const TOKEN_RE = /\[Pasted text #(\d+)[^\]]*\]/g;
+const IMAGE_TOKEN_RE = /\[Image #(\d+)\]/g;
+
+/** Does one inserted chunk look like a paste? */
+export function isPasteChunk(added) {
+  const s = String(added || "");
+  if (s.length < 2) return false;
+  return s.split("\n").length >= PASTE_MIN_LINES || s.length >= PASTE_MIN_CHARS;
+}
+
+/** The token that stands for pasted text in the input. */
+export function pasteToken(id, text) {
+  const s = String(text || "");
+  const lines = s.split("\n").length;
+  const size = lines > 1 ? `${lines} lines` : `${s.length} chars`;
+  return `[Pasted text #${id} · ${size}]`;
+}
+
+// How much of a paste is shown, top lines first (owner, 2026-10-01: "show two
+// or three lines vertically, then +15 more").
+export const PREVIEW_LINES = 3;
+
+/** The first lines of a paste and how many more there are. */
+export function previewLines(text, max = PREVIEW_LINES) {
+  const lines = String(text || "").replace(/\n+$/, "").split("\n");
+  return { shown: lines.slice(0, max), more: Math.max(0, lines.length - max) };
+}
+
+/**
+ * The input as the history should show it: each paste token opened into its
+ * first lines and a "+N more lines" note, so what was pasted can be seen
+ * without the whole of it.
+ */
+export function previewPastes(input, pastes, max = PREVIEW_LINES) {
+  return String(input || "").replace(TOKEN_RE, (whole, id) => {
+    const text = pastes.get(Number(id));
+    if (text == null) return whole;
+    const { shown, more } = previewLines(text, max);
+    const tail = more ? [`… +${more} more line${more === 1 ? "" : "s"}`] : [];
+    return ["", ...shown.map((l) => `  ${l}`), ...tail.map((l) => `  ${l}`)].join("\n");
+  });
+}
+
+/**
+ * Rows for the block above the input while composing: for each paste token in
+ * the input, a header and its first lines. At most `maxPastes` blocks, so the
+ * live zone stays small.
+ */
+export function composeRows(input, pastes, { max = PREVIEW_LINES, maxPastes = 2 } = {}) {
+  const rows = [];
+  let count = 0;
+  for (const m of String(input || "").matchAll(TOKEN_RE)) {
+    const id = Number(m[1]);
+    const text = pastes.get(id);
+    if (text == null) continue;
+    if (count === maxPastes) { rows.push("… more pasted text in the input"); break; }
+    count++;
+    const { shown, more } = previewLines(text, max);
+    rows.push(`┌ pasted #${id}`);
+    for (const l of shown) rows.push(`│ ${l}`);
+    rows.push(more ? `└ +${more} more line${more === 1 ? "" : "s"}` : "└");
+  }
+  return rows;
+}
+
+/** The input with every paste token replaced by the text it stands for. */
+export function expandPastes(input, pastes) {
+  return String(input || "").replace(TOKEN_RE, (whole, id) => {
+    const text = pastes.get(Number(id));
+    return text == null ? whole : text;
+  });
+}
+
+/** The image numbers referenced in the input, in order, each once. */
+export function imageIds(input) {
+  const ids = [];
+  for (const m of String(input || "").matchAll(IMAGE_TOKEN_RE)) {
+    const id = Number(m[1]);
+    if (!ids.includes(id)) ids.push(id);
+  }
+  return ids;
+}
+
+/**
+ * Text arriving at the cursor (typed, pasted, or Ctrl+V), given the paste
+ * state. A big chunk becomes a token; the next chunk of the same paste, if it
+ * arrives right after that token within PASTE_MERGE_MS, grows it.
+ *
+ * @param {object} a
+ * @param {string} a.value   the input
+ * @param {number} a.cursor  where the text goes
+ * @param {string} a.chunk   the text (normalized)
+ * @param {Map}    a.pastes  id -> text, mutated when a paste is made or grown
+ * @param {object} a.state   { nextId, last: {id, token, at} | null }, mutated
+ * @param {number} [a.now]
+ * @returns {{value: string, cursor: number}}
+ */
+export function applyInsert({ value, cursor, chunk, pastes, state, now = Date.now() }) {
+  const before = value.slice(0, cursor);
+  const after = value.slice(cursor);
+  const last = state.last;
+  if (last && now - last.at < PASTE_MERGE_MS && chunk.length > 1 && before.endsWith(last.token)) {
+    const text = pastes.get(last.id) + chunk;
+    pastes.set(last.id, text);
+    const token = pasteToken(last.id, text);
+    state.last = { id: last.id, token, at: now };
+    const head = before.slice(0, before.length - last.token.length) + token;
+    return { value: head + after, cursor: head.length };
+  }
+  if (isPasteChunk(chunk)) {
+    const id = state.nextId++;
+    pastes.set(id, chunk);
+    const token = pasteToken(id, chunk);
+    state.last = { id, token, at: now };
+    return { value: before + token + after, cursor: before.length + token.length };
+  }
+  return { value: before + chunk + after, cursor: cursor + chunk.length };
+}

package/src/ui/prompt-attention.js

@@ -0,0 +1,134 @@
+// Make an open prompt noticeable from outside the window.
+//
+// The owner's report on 2026-09-29: an approval prompt for edit_file sat
+// untouched for about seven minutes. The console looked idle — "thinking #28
+// 458s" — and the conclusion was that Flint had hung. It had not; it was
+// waiting, and the only visible sign of waiting was a line of text in a window
+// nobody was looking at.
+//
+// Two channels, because they fail differently:
+//
+//   BEL (\x07)      Windows Terminal (and most terminals) flash the taskbar
+//                   entry. A bell in a window you cannot see is the one signal
+//                   that reaches you at all. Guarded on isTTY: in a pipe or a
+//                   log file, \x07 is a stray control character, not an alert,
+//                   and it is worse than nothing — it corrupts captured output.
+//   window title    "[!] Flint needs you", restored when answered. Survives
+//                   scrollback, is visible from Alt+Tab, and works in hosts
+//                   that swallow the bell.
+//
+// Both are started and stopped as a pair, and stop() is idempotent, because the
+// call sites are a promise boundary: the prompt can be answered, timed out, or
+// abandoned by a reset, and a title left saying "needs you" after the question
+// is gone is worse than never having set it — it trains the operator to ignore
+// the one word that should have been trusted.
+
+import process from "node:process";
+
+const BELL = "\x07";
+
+/**
+ * The title shown while a prompt is open.
+ *
+ * "Flint needs you" is the spec's wording and the title bar has room for it.
+ * "waiting for approval" is added because a title has to work as a scan target:
+ * read out of context from an Alt+Tab list, "needs you" is a sentence that
+ * could mean anything, and "waiting for approval" cannot be mistaken for
+ * anything else. Both are in it so neither reading is lost.
+ */
+export const ATTENTION_TITLE = "[!] Flint needs you — waiting for approval";
+
+/**
+ * Note that a prompt is open.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.isTTY] — defaults to this process's stdout
+ * @param {string}  [opts.previousTitle] — the title to restore; read from the
+ *   terminal if not given
+ * @param {(title: string) => void} [opts.setTitle] — injectable so this is
+ *   testable without a terminal; defaults to writing the OSC 0 sequence
+ * @param {(char: string) => void} [opts.write] — injectable, same reason
+ * @returns {{active: boolean, rings: boolean, previousTitle: string|null}}
+ */
+export function promptAttentionStart({
+  isTTY = Boolean(process.stdout?.isTTY),
+  previousTitle,
+  setTitle = defaultSetTitle,
+  write = defaultWrite,
+} = {}) {
+  const previous = previousTitle ?? readTitle();
+
+  // Ring first. The title change alone is easy to absorb without noticing, and
+  // this call is the one that reaches a window that is not in front.
+  let rings = false;
+  if (isTTY) {
+    try {
+      write(BELL);
+      rings = true;
+    } catch {
+      // A terminal that cannot take the bell is not a reason to skip the title.
+      rings = false;
+    }
+  }
+
+  try {
+    setTitle(ATTENTION_TITLE);
+  } catch {}
+
+  return { active: true, rings, previousTitle: previous, setTitle };
+}
+
+/**
+ * The prompt is answered (or gone). Put the window back the way it was.
+ *
+ * Idempotent, and safe to call with nothing — the call sites race the timeout
+ * against the answer, and "stop an attention signal that is not running" has to
+ * be a no-op rather than a second restore.
+ *
+ * The `setTitle` used to restore comes from the state returned by start, not
+ * from a second argument. An earlier version took it as an argument, which meant
+ * a caller that had injected one (every test, and any host embedding the TUI)
+ * had to pass it twice, and the ones that did not got the real terminal instead
+ * of the one they were watching. The title was then set on the injected sink
+ * and restored on the real terminal: the test saw the title never change, and
+ * the operator's actual window was left reading "[!] Flint needs you" after the
+ * question was answered. A leaked "[!]" is worse than no signal at all.
+ *
+ * @returns {boolean} whether anything was actually restored
+ */
+export function promptAttentionStop(state, { setTitle } = {}) {
+  if (!state || !state.active) return false;
+  state.active = false;
+  const restore = state.setTitle || setTitle || defaultSetTitle;
+  try {
+    restore(state.previousTitle ?? "");
+  } catch {}
+  return true;
+}
+
+function defaultWrite(str) {
+  process.stdout.write(str);
+}
+
+/** Read the current title from the terminal, when the host tracks one. */
+function readTitle() {
+  return process.stdout?.title ?? null;
+}
+
+/**
+ * Set the terminal/window title.
+ *
+ * OSC 0 sets both the icon name and the window title, which is the one Windows
+ * Terminal puts in the taskbar entry — the place the signal has to land.
+ * process.stdout.title is tried first because on Windows it goes through the
+ * console API, and a terminal that supports it does the taskbar flash for us.
+ */
+export function defaultSetTitle(title) {
+  if (process.stdout && "title" in process.stdout) {
+    process.stdout.title = title;
+    return;
+  }
+  if (process.stdout?.isTTY) {
+    process.stdout.write(`\x1b]0;${title}\x07`);
+  }
+}

package/src/ui/render-options.js

@@ -0,0 +1,13 @@
+// Ink render options for the console, shared by index.js and the screen test
+// (tests/unit/components/console-screen.test.js), so the test renders exactly
+// what the operator gets.
+//
+// incrementalRendering stays off. It was turned on to stop the live zone
+// flickering and, on 2026-10-01, every spinner frame was left behind in the
+// scrollback ("/ thinking..." stacked line after line). Rendering the real App
+// into a headless xterm reproduced it with the option on and showed a clean
+// screen with it off.
+export const RENDER_OPTIONS = Object.freeze({
+  exitOnCtrlC: false,
+  incrementalRendering: false,
+});