@tiens.nguyen/gu-cli 1.0.686

package/terminal-layout.mjs

@@ -0,0 +1,2507 @@
+/**
+ * Pure terminal-layout arithmetic for the `gu` REPL — no I/O, so every rule below is
+ * testable without a terminal (see tests/terminal-layout.test.mjs, which replays the
+ * sequences through a small ANSI screen emulator).
+ *
+ * THE ONE INVARIANT (task #109, hit live at 40 cols; task #138): every row of an in-place
+ * block — the bottom bar, the live status block, a picker — must occupy exactly ONE physical
+ * terminal row, because every redraw walks the caret with ESC[nA / ESC[nB and `n` counts
+ * PHYSICAL rows. A row that wraps makes the walk land on the wrong line, the next erase
+ * clears the wrong row, and the block stacks/duplicates.
+ *
+ * A RESIZE breaks that invariant retroactively: rows were clipped to the width they were
+ * DRAWN at, and the terminal reflows them at the new width. So nothing here may cache a row
+ * count — `physicalRows(rows, width)` re-derives it from the row strings that are actually on
+ * screen, which is what makes a post-resize erase clear the right number of rows.
+ */
+
+/**
+ * COLUMNS, not characters. `"✅ Done!".length` is 7 and a terminal draws it in 8 cells — an
+ * emoji is one code point and two columns wide, and CJK text is two columns per character.
+ * Counting UTF-16 units instead was a silent off-by-one-per-wide-char in every row/column sum
+ * here: a row we believed fit exactly soft-wrapped in the terminal, which breaks THE ONE
+ * INVARIANT above and desynchronises every later erase and repaint.
+ *
+ * Emoji PRESENTATION is the test, not "is it a symbol": ✅ 😊 🔥 default to emoji rendering and
+ * take two cells, while the glyphs this UI is built from — ✓ ✗ ● ◑ ↑ ↓ → └ ▝ ✎ — are text
+ * presentation and take one. Combining marks and zero-width joiners take none.
+ */
+const WIDE_RANGES =
+  /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏ꥠ-꥿가-힣豈-﫿︐-︙︰-﹯＀-｠￠-￦]/u;
+const ZERO_WIDTH = /[\p{Mn}\p{Me}​-‏⁠]/u;
+export function charWidth(ch) {
+  if (!ch) return 0;
+  if (ZERO_WIDTH.test(ch)) return 0;
+  if (WIDE_RANGES.test(ch)) return 2;
+  if (/\p{Emoji_Presentation}/u.test(ch)) return 2;
+  return 1;
+}
+
+// Visible width of a string: SGR colour escapes (and any other CSI) occupy no cells.
+export function visibleLen(s) {
+  const plain = String(s ?? "").replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");
+  let n = 0;
+  for (const ch of plain) n += charWidth(ch); // by CODE POINT — an emoji is one iteration
+  return n;
+}
+
+// Truncate to `max` VISIBLE columns, keeping the ANSI colour escapes intact. A wide character
+// that would straddle the limit is dropped whole rather than half-drawn.
+export function clipVisible(s, max) {
+  if (max <= 0) return "";
+  let out = "", seen = 0, sawEscape = false;
+  const chars = [...String(s ?? "")];
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === "\x1b") {
+      const m = /^\x1b\[[0-9;]*m/.exec(chars.slice(i).join(""));
+      if (m) { out += m[0]; i += [...m[0]].length - 1; sawEscape = true; continue; }
+    }
+    const w = charWidth(chars[i]);
+    if (seen + w > max) return out + (sawEscape ? "\x1b[0m" : "");
+    out += chars[i];
+    seen += w;
+  }
+  return out;
+}
+
+/**
+ * The prompt breakdown as rows to print (task #142) — WHERE the coding model's context went.
+ *
+ * The ordering is deliberate: the two things the user can act on (their question, and what RAG
+ * pulled in) sit above the two they cannot (the static prompt, the model's own echoed code).
+ *
+ * ZERO IS AN ANSWER. RAG is a tool the model chooses to call, so `rag 0` means it never asked —
+ * the single most useful reading this table offers — and the row must therefore be rendered,
+ * with that explanation, rather than dropped for being empty.
+ */
+/**
+ * WHY the RAG number is zero — the difference between a choice and a breakage.
+ *
+ * "rag 0" reads as "RAG did nothing", which is true but useless: the model declining to search
+ * an indexed project is a completely different situation from an embedder that is down, and
+ * only one of them is fixed by the user. Reported live: three turns of `rag 0` where the real
+ * causes were an empty index AND an unreachable embedder — neither visible in the number.
+ */
+export function ragZeroReason(state) {
+  switch (state) {
+    case "unreachable":
+      return "the embedding server is DOWN — indexing and search would both fail";
+    case "no-index":
+      return "nothing indexed for this project yet — run rag_index_workspace()";
+    case "unavailable":
+      return "RAG is not configured for this workspace";
+    case "ready":
+      return "indexed and reachable — the model chose not to search";
+    default:
+      return "the model never called rag_search this turn";
+  }
+}
+
+/** The short form for the always-on token row: a state, or the share when it was used. */
+export function ragSegmentLabel(b) {
+  if (!b || typeof b !== "object") return "";
+  const rag = Number.isFinite(b.rag) ? b.rag : 0;
+  if (rag > 0) return null; // …the caller renders the number + percent instead
+  switch (b.ragState) {
+    case "unreachable":
+      return "rag ✗ embedder down";
+    case "no-index":
+      return "rag — not indexed";
+    case "unavailable":
+      return "rag — off";
+    // BOTH OF THESE WERE FALLING THROUGH TO "rag 0" — python has computed them all along and the
+    // row threw them away. Each is a COMPLETE explanation of the zero, and showing the bare
+    // number instead is what made this read as "RAG is broken" when nothing was wrong.
+    case "too-small":
+      return "rag — project too small to index";
+    // NOT "not indexed", which reads as "still working on it". This folder will never have an
+    // index until it is re-scoped, and the row is the only place that says so — the user watched
+    // "rag — not indexed" for two hours while a 64-day job ran against a home directory.
+    case "too-big":
+      return "rag — folder too large; register a project folder";
+    case "indexing-later":
+      return "rag — indexing after this turn";
+    // Nothing has been measured yet (the state before any turn has run). "0" is a claim we
+    // cannot support; a dash says "no figure", which is the truth.
+    case "unknown":
+    case "":
+    case undefined:
+      return "rag —";
+    default:
+      // "ready" with nothing retrieved is an honest zero: RAG was available and the model either
+      // did not search or found nothing. Any NEW state python invents also lands here — visibly
+      // wrong rather than silently plausible, which is how "too-small" hid for so long.
+      return "rag 0";
+  }
+}
+
+// The six origin buckets. They are scaled to sum to the server's prompt_tokens for ONE
+// request, so their sum IS the size of the newest context — the number to compare against
+// the model's window. Deliberately excludes ragFresh/ragCarried (shares OF rag, not extra)
+// and ragCalls/ragState (not tokens at all).
+const PROMPT_BUCKETS = ["scaffold", "task", "code", "rag", "tools", "other"];
+
+/**
+ * Tokens in the LATEST request to the coding model, from its breakdown.
+ *
+ * Distinct from the turn's running total, which sums every step and so climbs to many times
+ * the window: a turn showing "sent 65.3k" against a 49k model had a largest single request of
+ * about 10k. One number is what the turn COST; this one is what the model is actually HOLDING.
+ */
+export function promptTotal(b) {
+  if (!b || typeof b !== "object") return 0;
+  return PROMPT_BUCKETS.reduce((sum, k) => sum + (Number.isFinite(b[k]) ? b[k] : 0), 0);
+}
+
+/**
+ * The token figures on the bottom bar's number row, from the raw measurements.
+ *
+ * TRUE NUMBERS, DELIBERATELY — nothing here is netted, offset or clamped. See
+ * tests/token-row-figures.test.mjs for the bug that rule replaces: each figure used to have a
+ * "scaffolding floor" subtracted so the row would show what the CONVERSATION added rather than
+ * the overhead every request pays, and the result was a row nobody could act on.
+ *
+ * Three reasons the subtraction had to go, in the order they bite:
+ *
+ *   · A netted figure can be compared to NOTHING. The only reason to watch a context number is
+ *     to ask "how close am I to being compacted?", which is a question about the model's
+ *     window. A number whose zero point moves per folder and per resume cannot answer it, and
+ *     cannot be compared to yesterday either.
+ *   · The floor was read from the breakdown RESTORED FROM DISK at startup — a previous
+ *     session's mature turn, not this session's scaffold — so it was several times too large.
+ *   · `sent` is a SUM over N requests, so it lost N floors and clamped to 0 forever. The clamp
+ *     is what hid all of this: max(0, …) renders a broken figure as a plausible one.
+ *
+ * The misreading the floor was invented to fix — "ctx 7.3k" read as "your question cost 7.3k"
+ * — is a labelling problem. It is answered by naming the figure (`ctx` is what the model HOLDS,
+ * `sent` is what the turn COST) and by showing the composition in /tokens, not by altering the
+ * measurement until it matches the misreading.
+ *
+ * Non-finite input becomes 0: the row is redrawn on every keystroke, and "NaNk" on the bar is
+ * worse than a figure that admits it has not been measured.
+ */
+const finite = (n) => (Number.isFinite(n) && n > 0 ? n : 0);
+export function tokenRowFigures({ ctxTrue, turnTrue, peakTrue } = {}) {
+  return { ctx: finite(ctxTrue), turn: finite(turnTrue), peak: finite(peakTrue) };
+}
+
+/**
+ * How THIS FOLDER's coding key should be described in /model (task #222).
+ *
+ * WHY IT IS NOT JUST THE STORED KEY. The line used to render whatever GET /coding-key returned
+ * with no job named — which is the ACCOUNT DEFAULT, not the folder's choice. So after picking
+ * "accounting" the next /model still read "API key sk-…3E66", the key it had replaced. Nothing
+ * was wrong underneath; the display simply asked a question whose answer could not depend on
+ * the folder, and the user reasonably concluded the selection had not taken.
+ *
+ * Returns { text, verb }. The verb matters as much as the text: "replace it" is the honest word
+ * when there is one key and choosing means overwriting, and the wrong one once several exist,
+ * where ctrl+k changes which is used and destroys nothing.
+ *
+ * Pure, so every branch can be asserted without a terminal or an API.
+ */
+export function codingKeyLine({
+  keys = null,
+  selectedId = "",
+  storedMask = "",
+  backendId = "",
+  host = "",
+} = {}) {
+  const fallback = { text: storedMask || "stored", verb: "replace" };
+  // No list means an older API: it cannot answer which key this folder uses, so say the only
+  // true thing available rather than inventing a name.
+  if (!Array.isArray(keys) || keys.length === 0) return fallback;
+  const verb = keys.length > 1 ? "change" : "replace";
+  /**
+   * IS THIS KEY EVEN FOR THIS PROVIDER? (task #223 follow-up.)
+   *
+   * REPORTED: a fresh folder on a newly added OpenAI provider showed
+   *     API key Unknown  ····exit  ·  ctrl+k to change it
+   * and the turn died on a 401. The line was telling the truth — that key WAS the one used —
+   * but "Unknown ····exit" was the account's old ollama.com credential, and nothing on screen
+   * said so. The user could not have known, and the credential went to api.openai.com.
+   *
+   * An UNBOUND key is still legitimately usable anywhere (every key predating #223 is one), so
+   * this is a note and not a refusal. It fires only when there is something to notice: the key
+   * belongs to a DIFFERENT provider, or it belongs to none while this provider has one of its own.
+   */
+  const noteFor = (key) => {
+    if (!backendId || !key) return "";
+    const where = host || "this provider";
+    if (key.backendId && key.backendId !== backendId) return `that key is for another provider`;
+    if (key.backendId) return "";
+    // The key is UNBOUND. On an account where nothing is bound to anything — every account that
+    // predates #223 — that is simply how keys work, and a warning would fire on every /model
+    // while naming no action. Say something only where binding is actually in use.
+    if (keys.some((k) => k.backendId === backendId)) return `not tied to ${where} — one of your keys is`;
+    if (keys.some((k) => k.backendId)) return `not tied to ${where}`;
+    return "";
+  };
+  if (!selectedId) {
+    // NEVER PICKED — AND THAT IS WORTH SAYING OUT LOUD (reported). This folder rides the account
+    // default, which is simply the FIRST key in the list. With several stored, the one being used
+    // was chosen by ordering, not by anybody: the reporter's folder showed "Unknown ····exit",
+    // which was the account's old ollama.com credential, against an OpenAI coder — and the line
+    // read like a setting rather than a fallback. `isDefault` was already computed here and
+    // thrown away by every caller.
+    //
+    // Silent with ONE key, because there is then nothing to choose and "not chosen" would be
+    // noise on a correct setup.
+    const first = keys[0];
+    const notes = [];
+    if (keys.length > 1) notes.push("not chosen for this folder — using the first key");
+    const provider = noteFor(first);
+    if (provider) notes.push(provider);
+    return {
+      text: `${first.name}  ····${first.tail}`,
+      verb,
+      isDefault: true,
+      ...(notes.length ? { note: notes.join(" · ") } : {}),
+    };
+  }
+  const hit = keys.find((k) => k.id === selectedId);
+  // THE SELECTED KEY IS GONE. Saying nothing would leave the folder looking correctly
+  // configured while every turn quietly used a different credential.
+  if (!hit) {
+    const first = keys[0];
+    return {
+      text: `${first.name}  ····${first.tail}`,
+      verb,
+      missing: true,
+      note: "the key this folder chose has been removed",
+    };
+  }
+  return {
+    text: `${hit.name}  ····${hit.tail}`,
+    verb,
+    ...(noteFor(hit) ? { note: noteFor(hit) } : {}),
+  };
+}
+
+export function promptBreakdownRows(b) {
+  if (!b || typeof b !== "object") return [];
+  const n = (k) => (Number.isFinite(b[k]) ? b[k] : 0);
+  const total = promptTotal(b);
+  if (!total) return [];
+  const rows = [
+    { key: "task", label: "your question", note: "" },
+    {
+      key: "rag",
+      label: "RAG chunks",
+      note: n("rag")
+        ? `${n("ragFresh")} fetched now · ${n("ragCarried")} carried from earlier steps`
+        : ragZeroReason(b.ragState),
+    },
+    { key: "tools", label: "other tool output", note: "greps, file reads, command output" },
+    { key: "scaffold", label: "static prompt", note: "tools + rules; mostly served from the model's prefix cache" },
+    { key: "code", label: "the model's own code", note: "" },
+    { key: "other", label: "unattributed", note: "" },
+  ];
+  return rows
+    .filter((r) => r.key === "rag" || n(r.key) > 0) // …but never hide the RAG row
+    .map((r) => ({
+      label: r.label,
+      tokens: n(r.key),
+      percent: Math.round((n(r.key) * 100) / total),
+      note: r.note,
+    }));
+}
+
+/**
+ * A MOUSE REPORT IS NOT TYPING — the window in which keypress events belong to the mouse.
+ *
+ * readline parses `\x1b[<` as the key code "[<" and then hands the REST of the report through
+ * as ordinary characters ("6", "4", ";", …, "M"), so one wheel notch arrives as a dozen
+ * keypresses. Listeners that react to typing must sit them out: the REPL's first rule is
+ * "typing means the user has finished reading, so come back to the live tail", and with the
+ * wheel counted as typing every notch scrolled up three lines and immediately jumped back —
+ * the view could never get further than one notch from the bottom.
+ *
+ * `track` is called ONCE per event by the first listener in the chain; `active` reports whether
+ * the current event was part of a report, so later listeners agree without re-advancing it.
+ * The terminator closes the run but is itself part of it, which is why the two are separate.
+ */
+export function createMouseKeyWindow({ maxRun = 24 } = {}) {
+  let run = 0;
+  let current = false;
+  return {
+    track(str, key) {
+      if (key?.code === "[<") {
+        run = 1;
+        return (current = true);
+      }
+      if (!run) return (current = false);
+      run = str === "M" || str === "m" || run > maxRun ? 0 : run + 1;
+      return (current = true);
+    },
+    /** Was the event just tracked part of a mouse report? */
+    active: () => current,
+  };
+}
+
+/**
+ * A failed turn's message, as something a person can act on.
+ *
+ * The worker hands back whatever killed the Python agent, and that is usually a full traceback:
+ * ten lines of OUR file paths and line numbers, ending in the one line that says what actually
+ * went wrong ("TimeoutError: Request timed out."). Printing all of it buries the cause and the
+ * frames tell the user nothing — so keep the final exception line plus the context before the
+ * traceback ("agent chat exited 1"), and leave the frames to `gu logs`.
+ *
+ * Lives here rather than in the REPL because the REPL runs `main()` on import — a pure function
+ * that cannot be imported cannot be tested.
+ *
+ * `authored:true` IS A DIFFERENT KIND OF MESSAGE and gets a different rule. Everything above
+ * describes an ACCIDENT — a Python exception nobody wrote for a reader — where the last line is
+ * the useful part and 300 characters is generous. A __TURN_FAILED__:: message is the opposite:
+ * the worker composed it FOR this moment, and its later sentences are the ones that say what to
+ * do about it. Clipping those is not tidying, it is deleting the answer.
+ *
+ * Reported live (2026-09-01): a coding model that could not answer inside its budget produced
+ *   "…That pairing is too slow for this prompt: pick a smaller coding model in Settings →
+ *    Agent, or raise the per-request budget with GONEXT_CODE_TIMEOUT_SECONDS."
+ * and the screen showed it cut dead at "Settings → Agent," — character 300 — so the two fixes
+ * were both gone and the user asked why the message was short. There is no traceback hunt for
+ * these either: they are prose, and searching them for an "Error:" line can only misfire.
+ *
+ * The cap does not disappear, it just stops being a sentence-length limit: 2000 characters is
+ * far more than any message we write and still bounds a bug that hands this a whole log.
+ */
+const AUTHORED_MAX = 2000;
+export function summarizeError(message, { authored = false } = {}) {
+  const text = String(message ?? "").trim();
+  if (!text) return { reason: "the turn failed", hasTrace: false };
+  if (authored) return { reason: text.slice(0, AUTHORED_MAX), hasTrace: false };
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  // The LAST "SomeError: …" line is the exception that actually ended the run, so a chained one
+  // ("During handling of the above exception…") wins — that is the one the user is facing.
+  const exc = [...lines]
+    .reverse()
+    .find((l) => /^[A-Za-z_][\w.]*(Error|Exception|Interrupt|Exit|Warning)\b\s*[:(]?/.test(l));
+  const at = text.search(/Traceback \(most recent call last\)/);
+  const hasTrace = at >= 0 || /^\s*File ".*", line \d+/m.test(text);
+  if (!hasTrace) return { reason: (exc || lines[0]).slice(0, 300), hasTrace: false };
+  const context = (at >= 0 ? text.slice(0, at) : "").replace(/[:\s]+$/, "").trim();
+  // A TRUNCATED traceback has no exception line at all — the tail is where it lives. Rather
+  // than quote whatever fragment came last (the "^^^^" caret marker under a frame, or half a
+  // line of source), name the deepest FRAME: the file, line and function that died.
+  let reason = exc;
+  if (!reason) {
+    const frame = [...lines].reverse().find((l) => /^File ".*", line \d+/.test(l));
+    const m = frame && /^File "(.*)", line (\d+)(?:, in (\S+))?/.exec(frame);
+    reason = m
+      ? `crashed in ${m[3] || "the agent"} (${m[1].split("/").pop()}:${m[2]}) — the error text was cut off`
+      : "the agent crashed";
+  }
+  return { reason: (context ? `${context} — ` : "") + reason.slice(0, 300), hasTrace: true };
+}
+
+/**
+ * How many PHYSICAL rows the given drawn rows occupy at `width` — i.e. how far up an erase
+ * has to walk. Equal to `rows.length` for a block drawn at the current width (everything is
+ * clipped), and larger once a resize has reflowed rows that no longer fit. A row exactly
+ * `width` wide still counts as one: the terminal defers the wrap (pending-wrap) instead of
+ * moving to the next row, which is why the full-width separator rule is safe.
+ */
+export function physicalRows(rows, width) {
+  const w = Math.max(1, width || 80);
+  let n = 0;
+  for (const r of rows) n += Math.max(1, Math.ceil(visibleLen(r) / w));
+  return n;
+}
+
+// Physical rows the prompt + typed line occupies (it wraps past the terminal width).
+export function inputPhysicalRows({ promptCols, lineLength, width }) {
+  const w = Math.max(20, width || 80);
+  return Math.floor((promptCols + lineLength) / w) + 1;
+}
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+/**
+ * The bottom bar's rows as printable strings, one PHYSICAL row each, laid out for `width`.
+ * The rule spans the FULL width (it is the visual split); the text rows are clipped to
+ * width-1 because they can genuinely exceed it (the mode line is ~44 columns, the token row
+ * carries a model name) and would then wrap. Callers pass the already-styled text; `rag` is
+ * optional (verbose only), so the row COUNT is derived from the returned array — never
+ * hard-coded, or a resize/verbose toggle would move the caret by the wrong amount.
+ */
+/**
+ * `identity` (who and where) is its OWN ROW, above the numbers (user, 2026-09-05: "can we add
+ * another line for ctx and turn and peak and out and total or so? it is so tight here").
+ *
+ * They were one row doing two jobs, and the numbers lost. Five measurements plus a coder name
+ * and a folder name is ~110 columns; every row here is clipped to width-1 to keep it ONE
+ * PHYSICAL row (#109/#132/#138 — a wrapped footer row corrupts every later ESC[nA walk), and
+ * the clip falls on the RIGHT, so on any normal window the totals were the part being cut. The
+ * identity was deliberately placed first for exactly that reason — it must never be the thing
+ * that vanishes — which meant the numbers were living on whatever was left.
+ *
+ * Splitting them costs one row of transcript and gives the measurements the full width. Both
+ * rows stay clipped: this is a layout change, not a licence to wrap.
+ *
+ * `identity` is optional so callers that have nothing to put there (and the tests that predate
+ * it) keep producing the same rows as before.
+ */
+export function buildFooterRows({
+  width,
+  gutter = "   ",
+  rag = "",
+  identity = "",
+  token = "",
+  mode = "",
+}) {
+  const w = Math.max(20, width || 80);
+  return [
+    dim("─".repeat(w)),
+    ...(rag ? [clipVisible(gutter + rag, w - 1)] : []),
+    ...(identity ? [clipVisible(gutter + identity, w - 1)] : []),
+    clipVisible(gutter + token, w - 1),
+    clipVisible(gutter + mode, w - 1),
+  ];
+}
+
+/**
+ * Bytes that draw the bar below the input line and put the caret back exactly where readline
+ * left it. Relative moves only: the block must survive the terminal scrolling — writing past
+ * the last screen row scrolls the input line up TOO, so the matching up-move still lands on
+ * it. The up-move counts `rows.length`, so the count can never drift from what was drawn.
+ */
+export function footerDrawSeq({ rows, caretRows, caretCols, inputRows }) {
+  const down = Math.max(0, inputRows - 1 - caretRows); // caret row → last input row
+  return (
+    (down ? `\x1b[${down}B` : "") +
+    rows.map((r) => "\r\n\x1b[2K" + r).join("") +
+    "\x1b[J" +                              // nothing stale below the bar
+    `\x1b[${rows.length + down}A\r` +       // back to the caret's row
+    (caretCols > 0 ? `\x1b[${caretCols}C` : "")
+  );
+}
+
+// Bytes that wipe the bar (and anything under it) WITHOUT touching the input line.
+export function footerEraseSeq({ caretRows, caretCols, inputRows }) {
+  const down = Math.max(0, inputRows - 1 - caretRows) + 1; // first footer row
+  return `\x1b[${down}B\r\x1b[J\x1b[${down}A\r` + (caretCols > 0 ? `\x1b[${caretCols}C` : "");
+}
+
+/**
+ * Bytes that wipe an in-place block the caret is sitting at the END of (the live status
+ * block, a picker): clear this row, then move-up-and-clear for each row above, leaving the
+ * caret at the block's origin ready for a redraw. `rows` are the exact strings on screen, so
+ * after a resize the walk covers the rows they have REFLOWED into rather than the count they
+ * were drawn with.
+ */
+export function clearBlockSeq(rows, width) {
+  const n = physicalRows(rows, width);
+  let seq = "\r\x1b[K";
+  for (let i = 1; i < n; i++) seq += "\x1b[1A\r\x1b[K";
+  return seq;
+}
+
+/**
+ * The INPUT ZONE: the rows that live in the frozen area above the bar — a separator and the
+ * prompt line itself (task #141, second phase).
+ *
+ * Once the input line is frozen, readline can no longer draw it: readline draws wherever the
+ * caret happens to be, and the caret has to be inside the scrolling area for output to work.
+ * So gu renders the line and reports where the caret belongs, and readline is reduced to
+ * what it is actually good at — editing the string.
+ *
+ * THE LINE WRAPS (task #179). It used to scroll horizontally on one row, because a wrapped row
+ * changes the height of the frozen zone — and therefore the reserved-row count — on a keystroke.
+ * That turned out to be a cost worth paying rather than a reason not to: a long question was
+ * only ever visible through an 80-column porthole, so you could not read back what you had
+ * written, which is most of what an input line is for. paintBar already re-cut the region when
+ * the zone changed height (the --verbose RAG row does it), so the machinery was there.
+ *
+ * Continuation rows are indented by promptCols, so the text keeps ONE left edge under the
+ * prompt instead of stepping back to column 0.
+ *
+ * EVERY offset↔column conversion lives in here, against ONE set of wrap boundaries: the caret,
+ * a click, a double-click and a drag-selection are the same arithmetic asked four ways, and
+ * anywhere they disagree the user selects one thing and copies another. `spans` is that single
+ * source — each row's [from, to) offsets into the line.
+ *
+ * A row filled exactly to the edge is followed by an EMPTY row, which is what puts the caret on
+ * a fresh line the moment you type past the last column — the behaviour this was asked for.
+ *
+ * `maxRows` caps the height: past it the zone scrolls VERTICALLY to keep the caret in view,
+ * because a pasted essay must not eat the conversation it is about.
+ */
+/**
+ * Rows the zone puts ABOVE the typed line: the separator rule, and — only when it carries a
+ * CONTROL — one blank under it.
+ *
+ * THE BLANK EARNS ITS PLACE OR IT DOES NOT GET ONE (2026-08-25, narrowed 2026-09-05). The rule
+ * used to sit directly on top of the input, so the affordance it carries — "⭯ update gu …",
+ * "2 agents running", "↓ jump to bottom" — was pressed against the line being typed and read as
+ * part of it. One row of air fixed that.
+ *
+ * But the rule is PLAIN most of the time, and then the air is lifting nothing: it just pushes
+ * the separator a row further from the input than it needs to be, which is how it was reported
+ * ("the top line above the input location is too far on top… seems like you accidentally add a
+ * new line above the input line?"). So the blank now appears only when there is a control to
+ * lift off the input, and the plain rule sits directly above it.
+ *
+ * INPUT_HEAD_ROWS is the MAXIMUM (rule + blank) and stays the number used to RESERVE capacity —
+ * promising less than the zone may need is how a row gets stolen from the transcript. The
+ * ACTUAL count is published as `headRows` on the returned object, and every offset must be
+ * computed from that; a caller still using the constant for arithmetic would put the caret on
+ * the blank and hit-test clicks one row out, the #109 family this constant exists to prevent.
+ *
+ * EXPORTED BECAUSE THE REPL DOES ARITHMETIC WITH IT. paintBar derives the input's absolute row
+ * from the zone's top, frozenRowCount reserves the region, and maxInputRows subtracts the head
+ * before handing what is left to the typed line. All three used a hand-written 1 for "the
+ * separator"; a second head row that only some of them knew about would put the caret on the
+ * blank, hit-test clicks one row out and reserve a row short — the #109 family of bug, which
+ * is what a single exported count exists to prevent.
+ */
+export const INPUT_HEAD_ROWS = 2;
+
+export function inputZoneRows({
+  width, prompt = ">> ", promptCols = 3, line = "", cursor = 0, rule,
+  maxRows = 10, selection = null, highlight = null,
+  // Does the separator carry a control this time? Defaults TRUE so any caller that has not been
+  // told about this keeps the old, roomier layout rather than silently losing a row.
+  headControl = true,
+}) {
+  const w = Math.max(20, width || 80);
+  const avail = Math.max(8, w - 1 - promptCols); // text columns per row
+  const text = String(line ?? "");
+  const cur = Math.max(0, Math.min(cursor, text.length));
+
+  // Wrap by VISIBLE COLUMNS, walking by code point: an emoji is two cells and one iteration,
+  // and splitting it across rows would print half a character (the #109 width lesson).
+  //
+  // AT WORD BOUNDARIES where there is one — a sentence broken mid-word is markedly harder to
+  // read back, which is the whole reason the line stopped scrolling horizontally. A run with no
+  // space in it (a path, a URL, a base64 blob) still breaks at the edge, because the
+  // alternative is a row that overflows and the ONE-PHYSICAL-ROW invariant is not negotiable.
+  //
+  // The break keeps the space at the END of the row it belongs to rather than swallowing it, so
+  // the spans stay contiguous: every offset in the line is on exactly one row, which is what
+  // lets a selection be held as offsets and painted per row without a gap.
+  const spans = [];
+  let from = 0;
+  let cols = 0;
+  let off = 0;
+  let lastSpace = -1; // offset just AFTER the most recent space on this row
+  for (const ch of text) {
+    const cw = charWidth(ch);
+    if (cols + cw > avail) {
+      if (lastSpace > from) {
+        spans.push({ from, to: lastSpace });
+        cols = visibleLen(text.slice(lastSpace, off)); // the tail travels down with the caret
+        from = lastSpace;
+      } else {
+        spans.push({ from, to: off });
+        from = off;
+        cols = 0;
+      }
+      lastSpace = -1;
+    }
+    cols += cw;
+    off += ch.length;
+    if (ch === " ") lastSpace = off;
+  }
+  spans.push({ from, to: off });
+  // …and the empty row after a row that ends exactly at the edge — see above.
+  if (cols === avail && text.length) spans.push({ from: off, to: off });
+
+  // The row an offset belongs to. Searched from the BOTTOM so an offset sitting on a wrap
+  // boundary resolves to the row that STARTS there — which is how the caret moves down onto
+  // the new row rather than hanging off the end of the old one.
+  const rowOf = (o) => {
+    for (let r = spans.length - 1; r >= 0; r--) if (o >= spans[r].from) return r;
+    return 0;
+  };
+  const colOf = (o, r) => promptCols + visibleLen(text.slice(spans[r].from, o)) + 1; // 1-based
+
+  const caretRowAll = rowOf(cur);
+  // Vertical window: keep the caret on screen, and never show more than maxRows.
+  const cap = Math.max(1, maxRows | 0);
+  const top = spans.length > cap ? Math.min(Math.max(0, caretRowAll - cap + 1), spans.length - cap) : 0;
+  const shown = spans.slice(top, top + cap);
+
+  const rows = shown.map((s, i) => {
+    const head = top + i === 0 ? prompt : " ".repeat(promptCols);
+    let row = clipVisible(head + text.slice(s.from, s.to), w - 1);
+    // The selection is held in TEXT OFFSETS, so it survives a rewrap: the same characters stay
+    // selected at any width. Each row paints only its own slice of it.
+    if (selection && highlight && selection.to > selection.from) {
+      const a = Math.max(selection.from, s.from);
+      const b = Math.min(selection.to, s.to);
+      if (b > a) row = highlight(row, colOf(a, top + i) - 1, colOf(b, top + i) - 1);
+    }
+    return row;
+  });
+
+  const head = headControl ? [rule(w), ""] : [rule(w)];
+  return {
+    rows: [...head, ...rows],
+    // The ACTUAL count, not the constant — see INPUT_HEAD_ROWS.
+    headRows: head.length,
+    rowCount: rows.length,
+    caretRow: caretRowAll - top,                    // 0-based, within the TEXT rows
+    caretCol: Math.max(1, Math.min(w, colOf(cur, caretRowAll))),
+    /** Text offset a click at 1-based `col` on 0-based text `row` lands on. */
+    offsetAt: (row, col) => {
+      const s = shown[Math.max(0, Math.min(row | 0, shown.length - 1))];
+      if (!s) return 0;
+      const want = Math.max(0, (col | 0) - 1 - promptCols);
+      let o = s.from;
+      let c = 0;
+      for (const ch of text.slice(s.from, s.to)) {
+        if (c >= want) break;
+        c += charWidth(ch);
+        o += ch.length;
+      }
+      return o;
+    },
+    /** The [from, to) offsets shown on 0-based text `row` — the caller's row→text map. */
+    spanAt: (row) => shown[Math.max(0, Math.min(row | 0, shown.length - 1))] ?? { from: 0, to: 0 },
+  };
+}
+
+/**
+ * ---- Reserved rows at the bottom of the window (task #141) -----------------------------
+ *
+ * A DECSTBM scrolling region (`ESC [ top ; bottom r`) makes everything printed normally scroll
+ * INSIDE rows 1..bottom; the rows below the margin are never scrolled by anything, so the bar
+ * painted there simply stays. The region's TOP is always row 1, which is what keeps the
+ * terminal's own scrollback fed (a line enters scrollback when it scrolls off the FIRST row).
+ *
+ * Two details that corrupt the screen when missed:
+ *  · Setting or resetting a region HOMES THE CURSOR, so every sequence here brackets itself
+ *    with DECSC/DECRC (ESC 7 / ESC 8) — safe precisely because nothing scrolls in between.
+ *  · Reserving rows does not move the content already in them, so `reserveRowsSeq` scrolls the
+ *    screen up by N lines first and the bar lands on blank rows instead of eating output.
+ */
+export function scrollRegionSeq(rows, reserved, { preserveCaret = true } = {}) {
+  const bottom = Math.max(1, rows - reserved);
+  // preserveCaret:false — for the caller that keeps its OUTPUT POSITION in the DECSC slot (the
+  // slot is a single register: saving the caret here would throw that position away). Such a
+  // caller repaints and re-parks the caret itself right after, so the homing DECSTBM does
+  // costs it nothing.
+  return preserveCaret ? `\x1b7\x1b[1;${bottom}r\x1b8` : `\x1b[1;${bottom}r`;
+}
+
+/** Give the whole screen back to scrolling (every exit path must send this). */
+export const scrollRegionResetSeq = () => "\x1b7\x1b[r\x1b8";
+
+/**
+ * Make room for the bar and reserve it: push existing content up by `reserved` lines, set the
+ * region, and leave the caret on the LAST usable row (the bottom of the region).
+ */
+export function reserveRowsSeq(rows, reserved) {
+  return "\n".repeat(reserved) + `\x1b[1;${Math.max(1, rows - reserved)}r` +
+    `\x1b[${Math.max(1, rows - reserved)};1H`;
+}
+
+/**
+ * Paint rows at the BOTTOM of the window, absolutely positioned, caret restored. Each row is
+ * placed on its own — never joined with "\n", which at the last screen line is exactly the
+ * ambiguous case (a linefeed below the bottom margin) terminals disagree about.
+ */
+export function paintFrozenRowsSeq(rows, viewportRows, { preserveCaret = true } = {}) {
+  const top = Math.max(1, viewportRows - rows.length + 1);
+  // DECSC/DECRC is ONE slot per terminal. A caller that keeps the output position in that slot
+  // (see the region-write discipline in the REPL) must pass preserveCaret:false and park the
+  // caret itself — otherwise this paint quietly overwrites where output was going, and the next
+  // printed line lands in the frozen rows instead of the scrolling area.
+  //
+  // AUTOWRAP OFF FOR THE WHOLE PAINT (DECAWM, \x1b[?7l … \x1b[?7h).
+  //
+  // Every row here is placed at an ABSOLUTE position, so wrapping is never wanted — and when it
+  // happens it does not merely look wrong, it MOVES THE SCREEN: a row one column too wide wraps
+  // onto the row below and overwrites it, and on the LAST row of the viewport the terminal
+  // scrolls everything up to make room. Repainted ~8×/second by the thinking ticker, that reads
+  // as the transcript jumping (reported on Windows 11, 2026-09-06).
+  //
+  // The rows are already clipped to width-1 by their callers, but that clip trusts charWidth(),
+  // and charWidth() cannot be right everywhere: `●  …  ·  ↓  ◐  ░` and most of the spinner
+  // glyphs are East Asian AMBIGUOUS width — one column in most terminals, TWO in others — so
+  // the same string measured here occupies a different number of cells there. No width table
+  // fixes that, because the answer legitimately differs per terminal and per font. Turning
+  // wrapping off makes the invariant hold without needing to know: an over-wide row is
+  // truncated at the right edge by the terminal instead of pushing the screen around.
+  let out = (preserveCaret ? "\x1b7" : "") + "\x1b[?7l";
+  rows.forEach((r, i) => {
+    out += `\x1b[${top + i};1H\x1b[2K` + r;
+  });
+  return out + "\x1b[?7h" + (preserveCaret ? "\x1b8" : "");
+}
+
+/**
+ * Hand the reserved rows back: reset the region, wipe the rows the bar used, and leave the
+ * caret on the first of them so a shell prompt continues cleanly from there.
+ */
+export function releaseRowsSeq(rows, reserved) {
+  return `\x1b[r\x1b[${Math.max(1, rows - reserved + 1)};1H\x1b[J`;
+}
+
+/**
+ * Reader for the terminal's answer to a `\x1b[6n` cursor-position probe (`ESC [ row ; col R`).
+ *
+ * The answer is INPUT: every byte of it that reaches readline is TYPED INTO THE LINE. Node
+ * usually hands the whole thing over as ONE key (`key.code === "[38;3R"`), which is easy to
+ * drop — but only usually. When its parser doesn't recognise the exact shape it consumes the
+ * PREFIX it does recognise and re-emits the leftovers as ordinary characters, and terminals
+ * differ in shape. Observed against a real readline:
+ *
+ *     ESC [ 38;3 R   → key "[38;3 "  then "R"        ← a bare "R" in the line (reported live:
+ *     ESC [ 38;3;1R  → key "[38;3;"  then "1", "R"      a window drag stamped one per resize)
+ *     ESC [ ?38;3R   → key "[?"      then "38;3R"
+ *     ESC (timed out) [38;3R → "escape" then every character
+ *
+ * So this reader does not try to recognise a shape. While a probe is outstanding it HOLDS
+ * anything that still fits the reply's grammar (an unrecognised CSI head, then digits / ";" /
+ * "?" / " ") and consumes the run at its "R". The instant something doesn't fit, everything
+ * held is REPLAYED verbatim — a keystroke is only ever delayed, never lost.
+ *
+ * Pure and self-contained so the shapes above can be regression-tested (see
+ * tests/terminal-layout.test.mjs); the caller owns the terminal I/O and the flush timer.
+ */
+export function createProbeReplyReader({ now = () => Date.now(), windowMs = 1200 } = {}) {
+  let held = null;      // [str, key] pairs held back while a reply may still be forming
+  let deadline = 0;     // a reply is expected until this timestamp
+  const rowOf = (text) => {
+    const m = /\[\??(\d+);/.exec(text);
+    return m ? Number(m[1]) : 0;
+  };
+  // What a held piece contributes to the reply text: a plain character, or the CSI prefix
+  // node already swallowed into a key of its own.
+  const textOf = (str, key) => (typeof str === "string" ? str : key?.code ?? "");
+  const looksLikeReply = (text) => /^\x1b?\[?[\d;? ]*$/.test(text);
+  const isHead = (str, key) =>
+    key?.name === "escape" || (key?.code != null && /^\[[\d;? ]*$/.test(key.code));
+
+  return {
+    /** A probe was just written: expect its answer. */
+    expect() {
+      deadline = now() + windowMs;
+    },
+    /** True while pieces are being held (the caller arms its flush timer on the transition). */
+    holding: () => held !== null,
+    /**
+     * Feed one keypress. Returns one of:
+     *   { action: "pass" }                       — hand it to readline unchanged
+     *   { action: "consume", row }               — it was the reply (row = 0 if unreadable)
+     *   { action: "hold" }                       — might be the reply; nothing to do yet
+     *   { action: "replay", keys: [[str, key]] } — not a reply: replay these, in order
+     */
+    feed(str, key) {
+      // The whole answer as one key — the common shape.
+      if (key?.code && /^\[(\d+);\d+R$/.test(key.code)) {
+        const row = Number(key.code.match(/^\[(\d+);/)[1]);
+        const stale = held;
+        held = null;
+        deadline = 0;
+        // Anything held was NOT part of this answer; give it back before reporting.
+        return stale
+          ? { action: "replay", keys: stale, row }
+          : { action: "consume", row };
+      }
+      if (held) {
+        held.push([str, key]);
+        const text = held.map(([s, k]) => textOf(s, k)).join("");
+        if (text.endsWith("R")) {
+          const row = rowOf(text);
+          held = null;
+          deadline = 0;
+          return { action: "consume", row };
+        }
+        if (looksLikeReply(text) && held.length < 16) return { action: "hold" };
+        const keys = held;
+        held = null;
+        deadline = 0;
+        return { action: "replay", keys };
+      }
+      if (now() < deadline && isHead(str, key)) {
+        held = [[str, key]];
+        return { action: "hold" };
+      }
+      return { action: "pass" };
+    },
+    /** Timer fired / probe abandoned: hand back whatever is still held. */
+    flush() {
+      const keys = held ?? [];
+      held = null;
+      deadline = 0;
+      return keys;
+    },
+  };
+}
+
+/**
+ * Correct readline's own row bookkeeping before it repaints after a resize (task #138).
+ *
+ * readline redraws by moving up `prevRows` — the caret's row offset within the input, as
+ * measured at the width of the LAST refresh — then clearing to the end of the screen. After a
+ * reflow that number is stale in both directions: too small on a shrink (the walk stops inside
+ * the input and leaves an orphan half of it above), too large on a widen (it walks up into
+ * scrollback and erases a line that isn't ours). `getCursorPos()` recomputes the offset at the
+ * CURRENT width, and a reflowing terminal keeps the caret on the same character — so this is
+ * where the caret actually is. Called from the resize handler BEFORE readline's own listener
+ * runs, which makes readline's refresh land on the input's first row exactly.
+ */
+export function syncPrevRowsForResize(rl) {
+  if (!rl || typeof rl.getCursorPos !== "function") return;
+  try {
+    rl.prevRows = rl.getCursorPos().rows;
+  } catch {
+    /* a readline without cursor tracking (terminal:false) has nothing to correct */
+  }
+}
+
+
+// The agent streams two kinds of out-of-fence line. A STEP SUMMARY is smolagents' own
+// "tool(args) | → observation" trace: swallowed, because every tool emits its own
+// readable line and printing both showed each action twice. The pipe-arrow is the whole
+// signature — a tool's own line never contains it.
+export const isToolStepSummary = (line) => / \| → /.test(line);
+
+// Glyph vocabulary for an action line: a FAILURE pops (✗, full-bright), a completed
+// action recedes (✓, dim), anything else is neutral (●, dim). Returns the KIND only —
+// the REPL owns the colours, so this stays pure and testable.
+export function bulletKind(text) {
+  if (/\bfail(ed|s|ure)?\b|\berror(ed)?\b|→\s*(?:HTTP\s*)?[45]\d\d\b/i.test(text)) return "fail";
+  if (/^(?:Command finished|Server up|App launched)\b|→\s*(?:HTTP\s*)?2\d\d\b|\b(?:passed|succeeded|ready)\b/i.test(text))
+    return "ok";
+  return "info";
+}
+
+
+// ---------------------------------------------------------------------------
+// The model's THOUGHT, printed into the transcript (task #148).
+//
+// The web app's token-usage page shows each step's full reply — the `Thought:` prose, then
+// the <code> block. The terminal showed neither: the raw stream arrives inside a ~~~ fence
+// that is suppressed from scrollback, leaving only a one-line live clause that vanishes when
+// the step ends. So the reasoning existed everywhere except where the work was happening.
+// ---------------------------------------------------------------------------
+
+// Escaped newlines, braces, arrows, hex colours, a leading call — the shapes that mean this
+// is code or a data blob, not a sentence. Same test the live one-liner uses, so the printed
+// block and the blinking line never disagree about what counts as prose.
+/**
+ * Does this read as code rather than reasoning?
+ *
+ * THE STRUCTURAL MARKERS ARE JUDGED ON THE OPENING, not the whole string. A thought routinely
+ * QUOTES code — "I see the mistake in my previous `run_command`…", "`db:prepare => db:load_config`
+ * failed" — and testing every character meant one `=>` anywhere in a paragraph discarded the
+ * paragraph. 43 real responses were lost that way, all of them prose a person would want.
+ *
+ * What a thing IS shows in how it starts: reasoning opens with words, code opens with syntax.
+ * So the markers are checked against the first sentence, while the anchored tests — starts with
+ * a bracket, ends with a semicolon — still see the whole string, because those already describe
+ * its shape rather than its contents.
+ */
+const CODE_OPENING_CHARS = 120;
+const _codey = (s) => {
+  // BACKTICKED SPANS ARE QUOTATIONS, not structure. Prose reasons ABOUT code and names it the
+  // way a person would — "`db:prepare => db:load_config` failed" — so the markers inside a
+  // `…` span say what is being discussed, not what this text is. Removed before the opening is
+  // judged; the surrounding sentence still gets tested on its own merits.
+  // …AND SO IS INLINE MATH. Found by running a real turn on the shared Ollama rather than by
+  // reading the corpus: gemma4:e4b reasons in LaTeX — "computing a mathematical expression:
+  // $2^{20} - 24$" — and the braces inside that span tripped the `[{}]` rule below, so BOTH of
+  // its thoughts were discarded and the turn showed no reasoning at all. Same mistake as the
+  // backticks, one notation along: `$…$` is how prose WRITES mathematics, not a sign that the
+  // text is code.
+  //
+  // BOUNDED AT 120 CHARS, and that bound is the only thing standing between this and a way to
+  // smuggle code past the judgement: "$" is common in shell and in prices, so two unrelated ones
+  // will pair up, and an unbounded span between them would delete every marker in between. A
+  // real inline formula is short. (No newline bound is needed — the only caller collapses
+  // whitespace before this runs, so there are none left to cross.)
+  const opening = String(s)
+    .replace(/`[^`]*`/g, " ")
+    .replace(/\$[^$]{1,120}\$/g, " ")
+    .slice(0, CODE_OPENING_CHARS);
+  return (
+    /\\n|[{}]|=>|="|#[0-9a-fA-F]{3,6}\b|-webkit-/.test(opening) ||
+    /;\s*$|^\s*[<([]/.test(s) ||
+    /^\s*[a-z_]\w*\s*\(/i.test(s) ||
+    (s.length > 24 && (s.split(" ").length - 1) / s.length < 0.06)
+  );
+};
+
+/**
+ * The prose a step reasoned in, or "" when there is none worth showing.
+ *
+ * Everything up to `<code` — the code itself is already rendered as edit cards and action
+ * bullets, and printing it twice is exactly what the bullet list replaced. Unlike the live
+ * line's version this is NOT capped to one clause: the whole point is the paragraphs the
+ * terminal was dropping.
+ */
+/**
+ * A THOUGHT-OPENING TAG, which is not a code-opening tag.
+ *
+ * Models label their reasoning, and they do not agree on how. Measured over 1,279 real stored
+ * responses, the openers that carry prose behind them are `<thought>`, `<thought` (unclosed),
+ * `<code_thought` and `<codethought` — 188, and then a tail of variants.
+ *
+ * These were being DISCARDED. `_codey` treats a leading "<" as markup, correctly for a snippet
+ * of HTML and disastrously here: the tag is a label on the reasoning, not the reasoning. 221 of
+ * 1,279 responses — every one of them prose a person would want to read — printed nothing at
+ * all. Whole turns showed no reasoning in the terminal.
+ *
+ * DELIBERATELY NOT `<code>`. That IS a code boundary, handled below by cutting the string
+ * there, and the 533 responses opening with it correctly produce no prose — there is no thought
+ * in them to show. `code[_-]?` only matches when `thought` follows, so `<code>` cannot reach
+ * this. Task #144's lesson: check what the model ACTUALLY writes.
+ */
+// `[^>\n]*`, NOT `[^>]*`: an unclosed `<thought` is followed by a newline and the reasoning,
+// and a class that crosses newlines swallows everything up to the next ">" ANYWHERE in the
+// text — which for prose containing no ">" is the whole thought. That mistake ate 82 of these
+// on the first attempt, and it fails silently: the tag is gone and so is the sentence.
+export const THOUGHT_TAG_OPEN = /^\s*<\/?(?:code[_-]?)?thoughts?[^>\n]*>?[ \t]*\r?\n?/i;
+/** …and its closing form, wherever it turns up: `</thought>`, `</code_thought>`. */
+const THOUGHT_TAG_CLOSE = /<\/(?:code[_-]?)?thoughts?\s*>/gi;
+
+export function thoughtProse(buf) {
+  const t = String(buf || "");
+  const ci = t.search(/<code[\s>]/i);
+  const head = (ci >= 0 ? t.slice(0, ci) : t)
+    // The label comes off BEFORE anything judges whether this looks like code — that judgement
+    // is what the tag was failing.
+    .replace(THOUGHT_TAG_OPEN, "")
+    .replace(THOUGHT_TAG_CLOSE, " ")
+    // A leading pipe or quote survives some streams ("| Thought: …").
+    .replace(/^\s*[|>\-]+\s*/, "")
+    .replace(/^\s*Thought:\s*/i, "")
+    .replace(/```[a-z]*\n?/gi, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (head.length < 6) return "";
+  if (head.split(/\s+/).length < 2) return "";
+  if (_codey(head)) return "";
+  return head;
+}
+
+/**
+ * The rows to print for one thought block: plain text, no ANSI, no gutter — the caller owns
+ * colour and indentation.
+ *
+ * Collapsed by default because this is ON by default: a turn is many steps, and a page of
+ * reasoning per step would bury the action list and the answer under it. The last row carries
+ * the affordance, so the block always says it has more to give.
+ */
+export function thoughtBlockRows(prose, { width = 76, collapsed = true, lines = 2 } = {}) {
+  const text = String(prose || "").trim();
+  if (!text) return [];
+  const w = Math.max(20, width);
+  const words = text.split(/\s+/);
+  const rows = [];
+  let cur = "";
+  for (const word of words) {
+    const next = cur ? cur + " " + word : word;
+    if (next.length <= w) cur = next;
+    else {
+      if (cur) rows.push(cur);
+      cur = word.length > w ? word.slice(0, w) : word;
+    }
+  }
+  if (cur) rows.push(cur);
+  if (!collapsed || rows.length <= lines) {
+    // Nothing hidden ⇒ no affordance. A "click to expand" on a block with nothing more to
+    // show is a promise the block cannot keep.
+    return rows.length > lines ? [...rows, "(click to collapse)"] : rows;
+  }
+  const shown = rows.slice(0, Math.max(1, lines));
+  const hidden = rows.length - shown.length;
+  // Make ROOM for the affordance instead of appending past the width: a row that overflows is
+  // a row the terminal soft-wraps, and an unaccounted wrapped row pushes the whole viewport
+  // down by one (the lesson from the overlay work — rows must never wrap).
+  //
+  // In a narrow window the full wording cannot fit beside any useful amount of text, so it
+  // steps down to a short form and finally onto a row of its own. It never wins an argument
+  // with the text: the reasoning is the content, the hint is a label for it.
+  const fitWith = (suffix) => {
+    let last = shown[shown.length - 1];
+    while (last.length + suffix.length > w && last.includes(" ")) {
+      last = last.slice(0, last.lastIndexOf(" "));
+    }
+    return last.length + suffix.length <= w && last.length >= 12 ? last + suffix : null;
+  };
+  for (const suffix of [` … (+${hidden} more — click to expand)`, ` … (+${hidden} more)`, " …"]) {
+    const row = fitWith(suffix);
+    if (row) {
+      shown[shown.length - 1] = row;
+      return shown;
+    }
+  }
+  return [...shown, `(+${hidden} more)`.slice(0, w)];
+}
+
+
+/**
+ * What a submitted line should actually run, given a task left unfinished by the previous turn.
+ *
+ * A turn that ends without an answer — Ctrl+C, a provider refusal, a thrown error — pops its
+ * question from history, because nothing answered it and a failure notice must never persist as
+ * an assistant turn. That leaves "continue" meaning nothing, so the question is remembered here
+ * instead and one bare continue-word re-runs it.
+ *
+ * Bare ONLY: a message carrying real instructions is a new task, not a resume. And one-shot —
+ * the caller clears the pending task as it reads it, so "continue" twice does not run it twice.
+ *
+ * NOTHING TO RESUME IS NOT A TASK (task #201). "continue" with no pending question used to be
+ * handed to the model AS THE QUESTION, and the failure path then remembered the word as the
+ * unfinished task — so every later "continue" resumed the task "continue", forever:
+ *
+ *     continue #1: task sent to model = "continue"  resumed=false
+ *     continue #2: task sent to model = "continue"  resumed=true   <- self-referential
+ *
+ * Observed live: given no task, the model invented one, ran a setup script and EDITED a file
+ * nobody asked it to touch. The word that should do the LEAST did the most. So a resume word
+ * with nothing behind it now runs nothing, and `pending` is re-checked here as well — a
+ * session file poisoned by the old build must not be able to restart the loop.
+ */
+const RESUME_WORDS = /^(continue|resume|go on|keep going|carry on|proceed)\.?$/i;
+
+/** Is this line a bare resume word? Shared so the guards cannot drift from the reader. */
+export function isResumeWord(line) {
+  return RESUME_WORDS.test(String(line ?? "").trim());
+}
+
+export function resumeTask(line, pending) {
+  const text = String(line ?? "").trim();
+  if (!RESUME_WORDS.test(text)) return { task: text, resumed: false, nothingToResume: false };
+  // A pending task that is ITSELF a resume word is the poisoned state; treat it as absent.
+  const real = isResumeWord(pending) ? "" : String(pending ?? "").trim();
+  if (!real) return { task: "", resumed: false, nothingToResume: true };
+  return { task: real, resumed: true, nothingToResume: false };
+}
+
+
+/**
+ * Commands that still WORK but are no longer offered (task #153).
+ *
+ * Hiding and deleting are different promises. These keep their handlers — typing one does
+ * exactly what it always did — they are simply absent from /help and Tab completion while the
+ * command surface is trimmed. Kept as data rather than deleted lines so the contract is
+ * assertable: the risk of "hidden" is that someone later removes the handler believing the
+ * command is gone, and a test can catch that.
+ */
+/**
+ * Is this folder too broad to be a workspace? (home directory incident, 2026-08-12)
+ *
+ * WHAT HAPPENED. `gu` was run from `~`, the prompt asked "Register it?" defaulting to YES,
+ * and the answer was yes. That made the workspace 243,516 files / ~4.5GB — every repo the user
+ * owns, under one root. RAG then planned a 1,490,193-chunk index (≈64.8 days), the between-turns
+ * pass started it, and it ran for hours against a SHARED embedder while the bar read
+ * "rag — not indexed". Every downstream guard (an index ceiling, a clearer bar state) is a
+ * mitigation; this is the place the mistake is actually made.
+ *
+ * DELIBERATELY A PATH TEST, NOT A FILE COUNT. Counting files under a home directory to decide
+ * whether to warn about counting files under a home directory takes exactly as long as the thing
+ * being warned about — and the prompt has to answer instantly. A path comparison is free and
+ * catches the case that actually occurred.
+ *
+ * Returns a warning string, or "" when the folder looks like an ordinary project.
+ */
+export function workspaceScopeWarning(cwd, home) {
+  // An ABSENT path is not the root. `"" || "/"` collapsed the two, so a missing cwd warned
+  // "this is the whole filesystem" and flipped the register default to No for nothing. Strip
+  // trailing separators, but only call it "/" when that is what was actually passed.
+  const norm = (p) => {
+    const s = String(p ?? "").trim();
+    if (!s) return "";
+    return s.replace(/[\\/]+$/, "") || "/";
+  };
+  const c = norm(cwd);
+  const h = norm(home);
+  if (!c) return "";
+  if (c === "/" || /^[A-Za-z]:$/.test(c)) {
+    return "this is the whole filesystem — indexing and file tools would cover every file on this machine";
+  }
+  if (h && c === h) {
+    return "this is your HOME directory — it contains every project you own, not one project";
+  }
+  // A parent of home (/Users, /home, C:\Users): broader still, and the same mistake one level up.
+  if (h && h.startsWith(c + "/")) {
+    return `this contains your home directory (${h}) — far broader than one project`;
+  }
+  return "";
+}
+
+/**
+ * ---- WHERE A FOLDER'S RAG INDEX LIVES (task #133 / #180) -------------------------------
+ *
+ * One choice with three answers, and the ONE place it becomes wire fields. It used to be two
+ * independent booleans set by two commands that toggled the same flag — three states expressed
+ * as two, whose fourth combination (cloud + mirror) is meaningless and had to be caught by a
+ * guard in python. Deriving both from a single id means that combination cannot be built.
+ *
+ * Out here rather than in gu-repl.mjs because that file cannot be imported by a test, and
+ * "does each of the three modes send the right thing" is precisely the question that has to be
+ * answerable without a terminal.
+ */
+export const RAG_STORAGE = [
+  { id: "local", label: "local", note: "on this machine only (~/.gonext) — no AWS keys needed" },
+  { id: "cloud", label: "cloud", note: "on your S3 bucket only — same index as the web app; needs RAG AWS keys" },
+  { id: "both", label: "local + cloud", note: "local is read; each shard also mirrored to S3 — needs RAG AWS keys" },
+];
+export const RAG_STORAGE_IDS = RAG_STORAGE.map((r) => r.id);
+export const ragStorageLabel = (id) =>
+  RAG_STORAGE.find((r) => r.id === id)?.label ?? String(id ?? "");
+
+/** The two fields /agent-ask carries, derived together so they can never contradict. */
+export function ragWireFields(id) {
+  return { ragMode: id === "cloud" ? "cloud" : "local", ragCloudSync: id === "both" };
+}
+
+/**
+ * The stored choice for a folder, from whatever shape its session file is in.
+ *
+ * THREE GENERATIONS live on disk. `ragStorage` is current. `ragCloudSync` (a bool) came with
+ * #133 and wins over the oldest, because a folder carrying both was last written by that
+ * version. `ragMode: "cloud"` is the ORIGINAL exclusive choice — and it deliberately reads back
+ * as "both", not "cloud": #133 made the terminal local-first, so such a folder has been running
+ * as local+mirror ever since and its index is on this disk NOW. Honouring what was typed years
+ * ago would strand that index behind a credentials check.
+ */
+export function ragStorageFromSession(raw) {
+  if (RAG_STORAGE_IDS.includes(raw?.ragStorage)) return raw.ragStorage;
+  if (typeof raw?.ragCloudSync === "boolean") return raw.ragCloudSync ? "both" : "local";
+  return raw?.ragMode === "cloud" ? "both" : "local";
+}
+
+/**
+ * The UNFINISHED task a bare "continue" should resume, out of a folder's session file (#189).
+ *
+ * Read back at startup so the resume survives closing the terminal. It used to live only in a
+ * `let` inside the REPL loop, and the failure path that arms it POPS the user's question out of
+ * conversation history (correct — nothing answered it, and a persisted failure banner gets
+ * re-sent to the model for the rest of the session, task #144). Between those two facts, a
+ * failed question existed in exactly one place, in memory, and closing the terminal destroyed
+ * it. The reported symptom was the next session's "continue" having nothing to continue.
+ *
+ * Anything that is not a non-empty string reads back as "" — an older session file simply has
+ * no such field, and resumeTask treats "" as "nothing pending", which is the right default for
+ * every malformed case too.
+ */
+/**
+ * What the frozen input row should SHOW — the typed line, a mask, or nothing (task #191).
+ *
+ * The row is not readline's: gu renders it from rl.line, so readline's echo muting (which
+ * is what keeps a secret out of the scrollback, task #127) has no reach here at all. While the
+ * API-key prompt was up, the key was therefore painted into this row in plain text.
+ *
+ * MASKED, NOT BLANK. The prompt text sits up in the scrolling output while the caret lives in
+ * this row, so blanking it would leave a terminal that reacts to a keystroke nowhere on screen
+ * — which is exactly what got reported as confusing. One bullet per character says "you are
+ * typing, and it is going in" without the row being able to carry the key.
+ */
+export function inputLineFor({ line = "", visible = false, secret = false } = {}) {
+  if (!visible) return "";
+  return secret ? "\u2022".repeat(String(line).length) : String(line);
+}
+
+/**
+ * Drop a just-entered secret from readline's history (task #191).
+ *
+ * Muting the echo says nothing about rl.history, and readline unshifts every submitted line
+ * onto it in terminal mode — so an API key came straight back, in plain text, on the next press
+ * of Up at the ">> " prompt, and stayed there for the session.
+ *
+ * Only ever removes the entry that IS the secret, and only at the head where readline just put
+ * it: a blind shift() would eat a real command whenever the secret was not recorded (an empty
+ * entry, or a repeat of the previous line, both of which readline skips).
+ */
+export function dropSecretFromHistory(history, secret) {
+  if (!Array.isArray(history) || !secret) return history;
+  if (history[0] === secret) history.shift();
+  return history;
+}
+
+export function unfinishedTaskFromSession(raw) {
+  const t = raw?.unfinishedTask;
+  if (typeof t !== "string" || !t.trim()) return "";
+  // Never resume a stored resume word (task #201). The disk copy deliberately outlives the
+  // in-memory one, so without this a session file written by an older build keeps the
+  // "continue retries continue" loop alive across restarts — the failure survives the fix.
+  return isResumeWord(t) ? "" : t;
+}
+
+/**
+ * Did this turn die because the BACKEND could not answer, rather than because the task was
+ * bad? (task #201)
+ *
+ * The distinction changes the advice completely: a task that failed may be worth retrying as
+ * typed, while a coder whose backend is refusing will fail identically however many times it
+ * is retried. The observed shape was three "Streaming unavailable — retrying without
+ * streaming…" lines and then AgentGenerationError, with no steps run at all.
+ *
+ * That wording is GONE from the worker as of the streaming-fallback narrowing: it now says
+ * "Streaming unavailable" only when a server genuinely refuses a streamed request, which is
+ * the one case an unstreamed retry fixes. Timeouts, gateway errors, overloads and auth/billing
+ * failures all keep streaming and are classified upstream on their own merits — see
+ * _is_request_timeout / _is_backend_unavailable / _is_backend_overloaded / _is_auth_failure in
+ * gonext_agent_chat.py. Do not relabel any of them here; they arrive with their own wording.
+ */
+/**
+ * The model name a server said it does not have → "'gemma4:e4b'", or "" when it did not say.
+ *
+ * Quoted back with its own quotes kept, because the exact string IS the diagnosis: ":latest"
+ * dropped, "qwen3.8" typed as "qwen3", a model pulled on the wrong box. Paraphrasing it would
+ * throw away the only part of the message worth reading.
+ */
+export function modelNameNotFound(message) {
+  const t = String(message ?? "");
+  // Ollama: model 'gemma4:e4b' not found
+  const ollama = /model ['"“”]([^'"“”\n]+)['"“”] not found/i.exec(t);
+  if (ollama) return `'${ollama[1]}'`;
+  // OpenAI, which BACKTICKS the name and says what became of it (task #223 follow-up, reported):
+  //   The model `gpt-5.1-codex-mini` has been deprecated, learn more here: …
+  //   The model `x` does not exist or you do not have access to it.
+  const openai = /\bmodel [`'"“”]([^`'"“”\n]+)[`'"“”](?= (?:has been deprecated|does not exist|is not))/i.exec(t);
+  return openai ? `'${openai[1]}'` : "";
+}
+
+/** Was the name rejected because the provider RETIRED it, rather than never having had it?
+ *  Same action either way — pick another — but "deprecated" is the fact that explains it. */
+export function modelDeprecated(message) {
+  return /has been deprecated/i.test(String(message ?? ""));
+}
+
+
+export function classifyTurnFailure(message) {
+  const t = String(message ?? "");
+  // BUDGET FIRST — and this ORDER is the whole point. The first version of this file matched
+  // /timed out/ for the backend and so labelled "agent chat timed out after 3600000 ms" — the
+  // agent's OWN 60-minute budget (gu-cli.mjs:1973, task #81) — as a backend failure. A user
+  // whose turn had just done an hour of real work was told "the coding model's backend failed
+  // … retrying will not help", and retrying was in fact exactly what worked. Anchored to the
+  // budget's literal shape so the model client's own "Request timed out." still reads as the
+  // backend.
+  if (/timed out after \d+\s*ms|the time budget/i.test(t)) return "budget";
+  // INFRASTRUCTURE — gu's own machinery, not the model and not the question (task #207
+  // requirement 4, first needed by #209). Without this kind these fell into "task" and inherited
+  // advice about coders: "Worker key lookup failed" — the API's Mongo lookup throwing — was
+  // answered with "e.g. /model to switch coder", which cannot help and sends the reader looking
+  // in the wrong place entirely. Checked BEFORE the backend patterns, since a stopped worker and
+  // a database that will not answer are neither the coder's fault nor the user's.
+  if (
+    /worker was stopped|background worker was stopped|Worker key lookup failed|cannot reach its database|MongoNetworkError|MongoServerSelectionError/i.test(
+      t
+    )
+  ) {
+    return "infra";
+  }
+  // CONFIG — the server is up and answering; it just has no model by that name (task #213).
+  // Ollama says: model 'gemma4:e4b' not found  (and "…, try pulling it first" for embeddings).
+  // Checked BEFORE the backend patterns because it arrives as a 404 from a perfectly healthy
+  // box, and "the backend failed, retrying will not help" is both wrong and unactionable: the
+  // backend is fine, and one picker away is a model that works. The name the box rejected is
+  // the single most useful thing in the whole message, so the advice repeats it back.
+  if (/model ['"“”]?[^'"“”\n]+['"“”]? not found|model .* not found, try pulling it first/i.test(t)) {
+    return "config";
+  }
+  // …AND THE SAME FACT IN OPENAI'S WORDS (task #223 follow-up). Reported from a live turn:
+  //   404 - {'error': {'message': 'The model `gpt-5.1-codex-mini` has been deprecated, …',
+  //                    'code': 'model_not_found'}}
+  // The provider is healthy and the key is good; the model was RETIRED. That fell through to
+  // "backend", so the terminal said the backend had failed and invited a retry — which could
+  // never work, and sent the reader to look at a server that was answering perfectly. The
+  // `model_not_found` code is the unambiguous signal; the prose forms are for endpoints that
+  // send one without the other.
+  if (/model_not_found|has been deprecated|model [`'"“”][^`'"“”\n]+[`'"“”] does not exist/i.test(t)) {
+    return "config";
+  }
+  if (/AgentGenerationError|Error in generating model output|APIConnectionError|Connection error|Request timed out|Bad Gateway|Service Unavailable|\b50[234]\b/i.test(t)) {
+    return "backend";
+  }
+  return "task";
+}
+
+/**
+ * A run budget in words. → "6 hours", "45 minutes", "1 hour"; "" for nothing.
+ *
+ * Exists because the budget stopped being a round hour: at 360 minutes both the mid-run picker
+ * ("The agent has run for 360 min") and the advice under a stopped turn ("its 360-minute time
+ * budget") read as machine output. Whole hours are said as hours.
+ *
+ * `hyphenated` gives the adjectival form for "its 6-hour time budget"; the plain form is for
+ * "has run for 6 hours". Shared by the CLI's picker and the REPL's advice so the two cannot
+ * describe the same number differently.
+ */
+export function formatBudget(minutes, { hyphenated = false } = {}) {
+  const m = Math.max(0, Math.round(Number(minutes) || 0));
+  if (!m) return "";
+  if (m % 60 === 0) {
+    const h = m / 60;
+    return hyphenated ? `${h}-hour` : `${h} hour${h === 1 ? "" : "s"}`;
+  }
+  return hyphenated ? `${m}-minute` : `${m} minute${m === 1 ? "" : "s"}`;
+}
+
+/** How long the budget was, in minutes, from the timeout message. 0 when it cannot be read. */
+export function budgetMinutes(message) {
+  const m = /timed out after (\d+)\s*ms/i.exec(String(message ?? ""));
+  return m ? Math.round(Number(m[1]) / 60000) : 0;
+}
+
+/** Kept as the narrow question the name asks; the classifier is the single source of truth. */
+export function isBackendFailure(message) {
+  return classifyTurnFailure(message) === "backend";
+}
+
+/**
+ * What to say under a failed turn — the retry invitation, or the admission that retrying is
+ * not working. (task #201)
+ *
+ * WHY THIS STOPS BEING AN INVITATION. The old line was unconditional: *type "continue" to
+ * retry the same question*. Nothing counted how often the same task had already failed the
+ * same way, so a user typed "continue" four times against a backend that was down; the third
+ * attempt produced no steps whatsoever. Advice that cannot notice it is not working is not
+ * advice.
+ *
+ * `failures` counts CONSECUTIVE failures of THIS task, so the second one is what changes the
+ * message — the first failure genuinely might be transient, the second in a row is a pattern.
+ * Returns null when the turn is not resumable at all.
+ *
+ * A BUDGET STOP IS NOT A FAILURE and must never be talked about as one. Hitting the time
+ * budget means the turn was working and ran out of clock; "continue" is the DESIGNED response,
+ * and the escalation that tells people to stop retrying would be advice to abandon work that
+ * is progressing. Observed exactly that way: four budget stops in a row, each making real
+ * progress, and the task completed once the user kept going.
+ */
+export function retryAdvice({ resumable = true, failures = 1, kind = "task", minutes = 0, message = "" } = {}) {
+  const rawMessage = message;
+  if (!resumable) return null;
+  const budget = formatBudget(minutes, { hyphenated: true });
+  if (kind === "budget") {
+    // Counted separately from failures: repetition here means the TASK is too big for one
+    // turn, which is a different problem from a task that keeps breaking.
+    return failures >= 3
+      ? `the agent has hit its ${budget} budget ${failures} times on this task — it is too large for one turn. "continue" still resumes it; a smaller step each time will get there sooner, or raise agentTimeoutMinutes.`
+      : `the agent hit its ${budget} time budget — it was still working, so "continue" picks up where it stopped.`;
+  }
+  if (kind === "infra") {
+    // The question was fine and the coder was fine — something under both of them stopped. The
+    // work is resumable (#201 remembers the question), so lead with that; only name where to
+    // look once it has happened more than once, because a single restart needs no diagnosis.
+    return failures >= 2
+      ? `gu's own machinery has failed ${failures} times in a row — not your question, and not the coding model. Check it before retrying: gu-cli api status, and gu-cli start if the worker is not running.`
+      : 'that was gu\'s own machinery stopping, not your question — "continue" runs it again';
+  }
+  if (kind === "config") {
+    // Not resumable by repetition, and saying "continue" here would be a lie — the same
+    // question with the same model name fails identically every time. Retry count is
+    // irrelevant for the same reason, so this branch sits above it.
+    const named = modelNameNotFound(rawMessage);
+    // RETIRED IS NOT THE SAME STORY AS NEVER-EXISTED, even though the action is identical. A
+    // model that worked yesterday and is gone today reads as a gu fault unless the reason is
+    // said out loud — and the provider is the one that changed, not this machine.
+    if (modelDeprecated(rawMessage)) {
+      return (
+        (named
+          ? `${named} has been RETIRED by the provider — nothing here is broken, and retrying cannot bring it back.`
+          : "that model has been RETIRED by the provider — nothing here is broken, and retrying cannot bring it back.") +
+        ' Pick another: /provider to change this provider\'s model, or /model to switch coder. Then "continue".'
+      );
+    }
+    return (
+      (named
+        ? `the model server has no model called ${named} — nothing is broken, it is the name.`
+        : "the model server does not have the model that was asked for — nothing is broken, it is the name.") +
+      ' Pick one it does have: /agent-model for the chat model, /model for the coder, /provider to change a provider\'s model. Then "continue".'
+    );
+  }
+  if (failures >= 2) {
+    return kind === "backend"
+      ? `this task has now failed ${failures} times in a row and the coding model's backend is what is failing — not your question. Retrying will not help until it answers: /model to switch coder.`
+      : `this task has now failed ${failures} times in a row, the same way. Another "continue" will most likely do the same — change something first: /model to switch coder, or ask for a smaller step.`;
+  }
+  return kind === "backend"
+    ? 'the coding model\'s backend failed, not your question — type "continue" to retry it, or /model to switch coder'
+    : 'type "continue" to retry the same question — fix the cause first (e.g. /model to switch coder)';
+}
+
+/**
+ * `gu <something>` — is that a subcommand, a typo, or the REPL? (task #181)
+ *
+ * `gu logz` used to START THE REPL. Silently: the argument was not in the subcommand list,
+ * so it fell through to "no subcommand given" and a full agent session opened in that folder.
+ * That is the same failure the CLI_SUBCOMMANDS list was added to fix for `gu status` —
+ * the list caught the KNOWN names and left every unknown one falling through the same hole.
+ *
+ * Returns { kind: "run" } for a real subcommand, { kind: "repl" } for no arguments or flags,
+ * and { kind: "unknown", typed, suggestion } otherwise. Pure, so every row below is a test
+ * rather than something to try at a prompt.
+ *
+ * The suggestion is a PREFIX match first, then a one-edit neighbour. Both are conservative on
+ * purpose: "did you mean X?" is only useful if it is usually right, and a wrong guess in front
+ * of the correct list is worse than no guess at all.
+ */
+export function classifyCliArg(argv, subcommands) {
+  const args = Array.isArray(argv) ? argv : [];
+  const first = String(args[0] ?? "");
+  if (!first || first.startsWith("-")) return { kind: "repl" };
+  const known = Array.isArray(subcommands) ? subcommands : [];
+  if (known.includes(first)) return { kind: "run" };
+  const typed = first.toLowerCase();
+  const suggestion =
+    known.find((c) => c.startsWith(typed) || typed.startsWith(c)) ??
+    known.find((c) => _editDistance(c, typed) <= (typed.length <= 4 ? 1 : 2)) ??
+    "";
+  return { kind: "unknown", typed: first, suggestion };
+}
+
+/** Levenshtein, small and iterative — the inputs are single words. */
+function _editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (!m || !n) return Math.max(m, n);
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const cur = [i];
+    for (let j = 1; j <= n; j++) {
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    prev = cur;
+  }
+  return prev[n];
+}
+
+/**
+ * The "something newer exists" control, right-aligned on the separator row above the input.
+ *
+ * ONLY WHEN SOMETHING IS ACTUALLY NEWER (task #181). With nothing available this returns null
+ * and the row stays the plain rule it has always been — a permanent control there would be a
+ * standing claim on the one row separating the conversation from the input, for a thing that
+ * is true a few times a year.
+ *
+ * IT NAMES WHICH ONE, because the two have different consequences: the API upgrade restarts the
+ * local API and drops what it was serving; the CLI upgrade rewrites the files of the program
+ * currently running, so it cannot take effect until gu is restarted. One label saying
+ * "update available" would hide exactly the distinction the user needs to decide.
+ *
+ * Returns { text, from, to } like jumpToBottomRow — the same shape, because it lands on the
+ * same row and the caller hit-tests both by COLUMN. `from`/`to` are visible columns, 0-based.
+ */
+export function updateRow({ cli = "", api = "", width = 80, rule = "─" } = {}) {
+  const w = Math.max(20, width | 0);
+  const label =
+    cli && api ? `⭯ updates: gu ${cli} · API ${api} (click)`
+    : cli ? `⭯ update gu ${cli} (click)`
+    : api ? `⭯ update API ${api} (click)`
+    : "";
+  if (!label) return null;
+  // Right-aligned, with the rule running up to it so the row still reads as a separator rather
+  // than as a floating fragment. One space of air each side so the glyph is not welded to it.
+  const len = visibleLen(label);
+  if (len + 4 > w - 1) return null; // …too narrow to say it honestly: say nothing
+  const from = w - 1 - len;
+  return {
+    text: String(rule).repeat(Math.max(0, from - 1)) + " " + label,
+    from,
+    to: from + len,
+  };
+}
+
+/**
+ * The arrow-key picker's two byte sequences — drawing the block, and taking it away.
+ *
+ * Extracted from gu-repl.mjs so a screen emulator can replay them (tests/ansi-screen.mjs).
+ * This is row ARITHMETIC, which is the thing that cannot be checked by reading: the bytes
+ * always look plausible and only the resulting grid shows a block erased one row short, or an
+ * output position parked below where the next line should start. Every "#109 family" bug in
+ * this codebase has had that shape.
+ *
+ * THE INVARIANT BOTH HALVES EXIST TO KEEP: after the wipe, the cursor is back exactly where
+ * the block began — same row, COLUMN 0 — because the caller saves that spot as the position
+ * the next printed line starts from. One column off indents the next line; one row off leaves
+ * a gap above it.
+ */
+export function listBlockSeq({ items, sel = 0, width = 80, gutter = "", redraw = false, prevRows = [] } = {}) {
+  const w = Math.max(20, width | 0);
+  // Clipped so no row can WRAP: the walk back up counts logical rows, so a row occupying two
+  // physical ones would land the next redraw a row short of where it started.
+  const rows = items.map((it, i) =>
+    clipVisible(gutter + (i === sel ? `▸ ${it}` : `  ${it}`), w - 1)
+  );
+  const up = redraw ? physicalRows(prevRows, w) : 0;
+  const seq =
+    (up ? `\x1b[${up}A` : "") +
+    rows.map((r) => "\r\x1b[K" + r).join("\n") +
+    "\x1b[J" +
+    "\n";
+  return { seq, rows };
+}
+
+/** Take the block away and leave the cursor where it began. */
+export function listWipeSeq({ prevRows = [], width = 80 } = {}) {
+  const up = physicalRows(prevRows, Math.max(20, width | 0));
+  // \r is not decoration: ESC[nA preserves the COLUMN, so without it the cursor keeps whatever
+  // column the last row left it on and the next printed line starts there.
+  return (up ? `\x1b[${up}A` : "") + "\r\x1b[J";
+}
+
+/**
+ * Does this action bullet open the FINAL phase of a turn? → boolean.
+ *
+ * NO LONGER CALLED BY THE REPL (2026-08-22). It existed because action bullets were one tight
+ * group (task #41) with a single blank above "Composing answer…" — the moment the turn stops
+ * working and starts producing the reply. Every bullet now gets that blank (openBullet in
+ * gu-repl.mjs), so this one's blank is no longer special and the call site is gone.
+ *
+ * Kept, not deleted: the predicate is still the honest answer to "is this the answer phase",
+ * it is pure and tested, and the spacing decision it encodes has now been reversed twice
+ * (#129 spaced → #41 tight → 2026-08-22 spaced again). If it goes tight a third time this is
+ * what comes back. Anything that needs to KNOW about the phase — not just space it — should
+ * call this rather than re-derive the string match.
+ */
+export function opensAnswerPhase(line) {
+  return /^\s*composing answer/i.test(String(line ?? ""));
+}
+
+/**
+ * The end-of-turn answer block: how long it took, then the reply. → { text, rows }
+ *
+ * `rows` is returned rather than recounted by the caller, and that is the point of the
+ * function existing at all: the copy map (task #158) translates SCREEN ROWS back to the
+ * source text so a double-click yields something runnable, and it used to be maintained by
+ * hand right next to the template string that laid the block out — `rendered.split("\n").length
+ * + 1`, where the `+ 1` was the "thought for" row. Add a row to the layout and forget the
+ * count and nothing looks wrong; the copy range is just silently off by one. One function now
+ * owns both.
+ *
+ * THE EMPTY LINE BESIDE "thought for …" is the change this was extracted for. That line is a
+ * FOOTNOTE about the turn that has just ended, and the reply is the thing being read. Touching,
+ * they read as one paragraph — reported from a real screen, where "thought for 17s" sat directly
+ * on top of "Hello! How can I assist you today?".
+ *
+ * THE FOOTNOTE GOES UNDER THE REPLY (user, 2026-09-06). It was above it, which put a fact about
+ * the turn in the position the eye starts from — you read the cost before the thing you asked
+ * for. Below, the reply leads and the timings close it out, which is also where a reader looks
+ * for "when did this finish".
+ *
+ * `doneAt` is a parameter rather than a Date.now() inside, so the block a test asserts on is the
+ * same block at any hour — otherwise the wall clock makes the output untestable.
+ */
+export function answerBlock({
+  elapsedMs = 0,
+  answer = "",
+  worked = false,
+  gutter = "",
+  dim = (x) => x,
+  render = (x) => x,
+  doneAt = Date.now(),
+} = {}) {
+  const rendered = render(worked ? `recap: ${answer}` : answer);
+  const clock = formatClockTime(doneAt);
+  // The stamp is DROPPED, not defaulted, when the time is unusable — "done Invalid Date" beside
+  // a correct duration is worse than no stamp at all.
+  const foot =
+    gutter + dim(`thought for ${formatThinkTime(elapsedMs)}${clock ? ` · done ${clock}` : ""}`);
+  const text = `${rendered}\n\n${foot}`;
+  return { text, rows: text.split("\n").length };
+}
+
+/** The one command that installs a newer gu. One definition, so the notice and any
+ *  documentation of it cannot drift from what the update control actually runs. */
+export const CLI_INSTALL_COMMAND = "npm install -g @tiens.nguyen/gu-cli@latest";
+
+/**
+ * The "a newer gu exists" notice, as transcript lines. → [{ text, kind }] (empty = say
+ * nothing), where kind is `head` | `cmd` | `note` and the caller owns the colour.
+ *
+ * WHY A NOTICE AND NOT JUST THE BAR CONTROL (task #181 follow-up). The clickable `⭯ update`
+ * on the separator row is easy to miss and impossible to act on if you do not already know
+ * it is a button — it never says what it would do, and nothing tells you a new version
+ * exists at all if you do not look down there. The complaint was exactly that: the terminal
+ * knew and did not say.
+ *
+ * THREE LINES, because the user needs three different facts and they are not interchangeable:
+ *   · WHAT — a newer version exists, and which, against the one running. "An update is
+ *     available" without the numbers cannot be checked or reported.
+ *   · HOW — the literal command. Printed on its OWN line with nothing else on it, so that a
+ *     double-click copies the command and not a sentence wrapped around it. This is also the
+ *     escape hatch: the click control needs npm to be writable by this user, and when a
+ *     global install needs sudo the command is the only route that works.
+ *   · WHEN — that it takes effect only after a restart. Omitting this is how "I updated and
+ *     nothing changed" happens: npm rewrites the files of the program currently running, and
+ *     the running process keeps its own copy until it is started again.
+ *
+ * Shown once per session, by the caller. A notice that reappears on a timer is an
+ * interruption; this one is a fact that does not change until acted on.
+ */
+export function updateNotice({ cli = "", running = "", platform = process.platform } = {}) {
+  if (!cli) return [];
+  const have = running ? ` (you have ${running})` : "";
+  return [
+    { kind: "head", text: `gu ${cli} is available${have}` },
+    { kind: "cmd", text: CLI_INSTALL_COMMAND },
+    { kind: "note", text: updateRestartNote(platform) },
+  ];
+}
+
+/**
+ * Did the install actually happen, and if not, what does the user need to know?
+ * → null when it succeeded, otherwise the sentence to show.
+ *
+ * THIS EXISTS BECAUSE spawnSync DOES NOT THROW ON A FAILED COMMAND. It returns a status,
+ * which nothing checked — so `✓ gu installed` printed whether npm had worked or not.
+ * Rare on macOS; the NORMAL outcome on Windows, where a global install cannot replace the
+ * files of the running program, and common on Linux, where a non-root `npm install -g`
+ * hits EACCES on a root-owned prefix. Three platforms, one silent lie.
+ *
+ * THE REASON IS KEPT, and that is the point of the parsing. "The update failed" leaves the
+ * user with nothing to act on, while the codes name completely different fixes: EACCES
+ * wants sudo or a user-owned prefix, EPERM/EBUSY wants gu closed first, ETARGET means
+ * the version does not exist, ENOTFOUND means no network. npm puts that line on stderr and
+ * buries it in banner noise, so the last couple of substantive lines are what survive.
+ */
+export function describeInstallFailure({ status = 0, stderr = "", error = null } = {}) {
+  // The command could not be started at all (npm not on PATH) — `error` is set and there is
+  // no status to read. Distinct from "npm ran and refused".
+  if (error) return `could not run npm — ${error.message ?? error}`;
+  if (status === 0) return null;
+
+  // SEARCH FOR THE CAUSE, DO NOT TAKE THE TAIL. This used to keep the last two substantive
+  // lines, which is wrong for the npm people actually have: verified against npm 10 in an
+  // Ubuntu container, a permission failure ends with EIGHT lines of generic advice ("The
+  // operation was rejected by your operating system", "You can rerun the command with
+  // --loglevel=verbose"), so the tail is boilerplate and the cause is ~14 lines up. The
+  // prefix moved too — `npm ERR!` became `npm error` in npm 10 — which is exactly the drift
+  // a parser built from recorded strings cannot notice.
+  const lines = String(stderr ?? "")
+    .split("\n")
+    .map((l) => l.replace(/^npm\s+(ERR!|error|WARN|warn)\s*/i, "").trim())
+    .filter(Boolean);
+
+  // The code names the FIX, and the codes mean different ones: EACCES → sudo or a user-owned
+  // prefix; EPERM/EBUSY → close gu first; ETARGET/E404 → that version does not exist;
+  // ENOTFOUND/ETIMEDOUT → no network. Taken from `code EACCES` or `code: 'EACCES'`.
+  let code = lines.map((l) => /^code:?\s*'?([A-Z][A-Z0-9_]{2,})'?,?$/.exec(l)?.[1])
+    .find(Boolean);
+  // npm 11 DOES NOT ALWAYS EMIT A `code X` LINE. Verified on Windows 11 / npm 11.19.0: a
+  // missing version prints `npm error notarget No matching version found …` with the code as a
+  // lowercase per-line PREFIX and no code line at all, so the reason lost the one token that
+  // names the fix. Recovered from a known set rather than "any leading lowercase word", which
+  // would promote ordinary prose into a code.
+  if (!code) {
+    const known = new Set(["notarget", "eresolve", "enoent", "eacces", "eperm", "ebusy",
+                           "etarget", "e404", "enotfound", "elifecycle", "enospc", "enotempty"]);
+    const hit = lines.map((l) => /^([a-z0-9]{4,12})\s+\S/.exec(l)?.[1]).find((w) => w && known.has(w));
+    if (hit) code = hit.toUpperCase().replace(/^NOTARGET$/, "ETARGET");
+  }
+  // The one human sentence npm writes about what went wrong, minus the stack and the advice.
+  const detail = lines.map((l) => l.replace(/^(notarget|nospc|enoent)\s+/i, ""))
+    .find((l) =>
+      /^Error: |permission denied|operation not permitted|No matching version|not found|EACCES|EPERM|EBUSY/i.test(l) &&
+      // …but never the code line itself, or the reason reads "EACCES: code EACCES".
+      !/^code:?\s*'?[A-Z][A-Z0-9_]{2,}'?,?$/.test(l) &&
+      !/^(errno|syscall|path):?\s/i.test(l) &&
+      !/^at /.test(l) &&
+      !/rejected by your operating system/i.test(l) &&
+      !/do not have the permissions to access this file/i.test(l) &&
+      !/^If you believe this might be/i.test(l));
+
+  // Never say the code twice. npm's own sentence usually LEADS with it ("EBUSY: resource busy
+  // or locked, rename …"), which read back as "EBUSY: EBUSY: resource busy or locked".
+  const dup = code && detail && new RegExp(`^${code}\\b:?\\s*`, "i").test(detail);
+  const why = [code, detail && detail !== code && !dup ? detail
+                    : dup ? detail.replace(new RegExp(`^${code}\\b:?\\s*`, "i"), "") : ""]
+    .filter(Boolean).join(": ");
+  return `npm exited ${status}${why ? ` — ${_clipReason(why)}` : ""}`;
+}
+
+/** One line, bounded — a reason is for reading, and npm's can carry a whole stack frame. */
+function _clipReason(s, max = 160) {
+  const one = String(s).replace(/\s+/g, " ").trim();
+  return one.length > max ? one.slice(0, max - 1) + "…" : one;
+}
+
+/**
+ * The last line of the notice — and it is NOT the same sentence on every platform (#157).
+ *
+ * On macOS and Linux a global install replaces files that are open, because unlink there
+ * detaches the name from an inode the running process keeps. Install now, restart when
+ * convenient; the order does not matter.
+ *
+ * WINDOWS CANNOT DO THAT. A file that is in use cannot be replaced, so `npm install -g`
+ * against the gu that is currently running is liable to fail outright — EPERM/EBUSY,
+ * partway through, with the shims possibly already rewritten. The steps are therefore in a
+ * REQUIRED ORDER there: close it, install, reopen. Printing the POSIX sentence on Windows
+ * tells the user to do the one thing that breaks, which is worse than saying nothing.
+ */
+export function updateRestartNote(platform = process.platform) {
+  return platform === "win32"
+    ? "Close gu first (Windows can't replace files in use), run that, then reopen."
+    : "Then restart gu for it to take effect.";
+}
+
+/**
+ * A stored API key, shown as enough to TELL IT APART and no more — `sk-…4f2a`.
+ *
+ * The point is the one question a user actually has: "is the key in there the one I think it
+ * is?" A bare "stored" cannot answer it, which is exactly what made a rejected key confusing —
+ * you could see that something was saved and not whether it was the stale one.
+ *
+ * NEVER THE WHOLE KEY. It would land in scrollback, in a screenshot, in a pasted transcript —
+ * all places a live credential should not be. The prefix is kept because providers put meaning
+ * there (`sk-`, `sk-ant-`), the tail because that is what people compare against.
+ */
+export function maskKey(key) {
+  const k = String(key ?? "").trim();
+  if (!k) return "";
+  // Too short to split safely: anything under ~10 chars would leak most of itself, so it gets
+  // no tail at all rather than a nearly-complete key.
+  if (k.length < 10) return "\u2022".repeat(k.length);
+  // BOUNDED, and this is the whole difficulty: a greedy `^sk-[a-z-]*` swallows every lowercase
+  // character of a key like "sk-abcdefghijklmnop4f2a" and prints nearly all of it. The prefix
+  // is `sk-` plus at most ONE short vendor segment ("sk-ant-"), which is where the meaning is;
+  // anything longer is key material, not a label.
+  const head = /^sk-(?:[a-z]{2,4}-)?/i.exec(k)?.[0] ?? k.slice(0, 3);
+  return `${head}\u2026${k.slice(-4)}`;
+}
+
+/**
+ * ---- OTHER RUNNING AGENTS (task #195) -------------------------------------------------
+ *
+ * The same account's turns running somewhere else — another terminal, another machine, the web
+ * app. They are real today and invisible from here. It began as a MONITOR; since task #211 the
+ * list also hands each agent to an action — stop it, or switch this terminal to following it —
+ * which is what agentPickerItems below exists for.
+ */
+
+/** A coarse, relative age — "9s", "12m", "3d". The exact second is never the question. */
+export function shortAge(fromIso, now = Date.now()) {
+  const t = Date.parse(String(fromIso ?? ""));
+  if (!Number.isFinite(t)) return "";
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.round(s / 60)}m`;
+  if (s < 86400) return `${Math.round(s / 3600)}h`;
+  return `${Math.round(s / 86400)}d`;
+}
+
+/**
+ * The jobs to SHOW, from what the API returned. → [{ id, status, title, detail, age }]
+ *
+ * `mine` is this terminal's own jobId and is excluded: counting the turn you are watching as
+ * "another agent" makes the number read as duplicated work the moment you ask anything.
+ */
+export function otherAgentRows(jobs, { mine = "", now = Date.now() } = {}) {
+  return (Array.isArray(jobs) ? jobs : [])
+    .filter((j) => j && j.jobId && j.jobId !== mine)
+    .map((j) => ({
+      id: j.jobId,
+      status: String(j.jobStatus ?? ""),
+      title: String(j.title ?? "").trim() || "(no question recorded)",
+      detail: String(j.modelKey ?? "").trim(),
+      age: shortAge(j.updatedAt || j.createdAt, now),
+    }));
+}
+
+/**
+ * The indicator for the separator row: "2 agents", or "" when there is nothing to say.
+ *
+ * Conditional on purpose — that row is scarce, and "0 agents" is noise. Singular/plural because
+ * "1 agents" is the kind of small wrongness that makes a UI feel unfinished.
+ */
+export function agentsIndicator(rows) {
+  const n = Array.isArray(rows) ? rows.length : 0;
+  return n ? `${n} agent${n === 1 ? "" : "s"}` : "";
+}
+
+/**
+ * The list itself, as rows to print — grouped by what the reader can act on.
+ *
+ * RUNNING first, then WAITING (queued, nobody has claimed it). A job that is merely queued is a
+ * different situation from one a worker is executing, and the screenshot's grouping is what
+ * makes that legible at a glance.
+ *
+ * Every row is clipped to ONE physical row (#109/#138): title elided from the right, the age
+ * right-aligned, and the middle detail given whatever is left over — dropped entirely when the
+ * window is too narrow to carry it honestly.
+ */
+export function agentListRows(rows, { width = 80, gutter = "   " } = {}) {
+  const w = Math.max(20, width | 0);
+  const groups = [
+    ["Running", (r) => r.status === "running" || r.status === "claimed"],
+    ["Waiting", (r) => r.status === "pending"],
+  ];
+  const out = [];
+  for (const [label, match] of groups) {
+    const hit = (rows ?? []).filter(match);
+    if (!hit.length) continue;
+    out.push({ kind: "header", text: label });
+    for (const r of hit) {
+      const age = r.age ?? "";
+      // Columns: gutter + marker + title + detail + age. The age is the only part that must
+      // never be cut — it is the reason to look.
+      const fixed = gutter.length + 2 + age.length + 2;
+      const room = Math.max(8, w - 1 - fixed);
+      const titleW = Math.max(8, Math.floor(room * (room > 40 ? 0.55 : 1)));
+      const detailW = room - titleW - (room > 40 ? 2 : 0);
+      const cut = (t, n) => (t.length > n ? t.slice(0, Math.max(1, n - 1)) + "\u2026" : t);
+      out.push({
+        kind: "row",
+        id: r.id,
+        // Carried through so a caller acting on the row (stop / switch to) can tell a job a
+        // worker is EXECUTING from one still queued, without re-deriving it from the header.
+        status: r.status ?? "",
+        marker: "\u2022",
+        title: cut(r.title, titleW),
+        detail: detailW > 4 ? cut(r.detail ?? "", detailW) : "",
+        age,
+        titleW,
+        detailW: detailW > 4 ? detailW : 0,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * The same agents, as PICKER items — one line each, so they can be acted on (task #211).
+ *
+ * A picker has no group headers (drawList paints a flat list), and losing the Running/Waiting
+ * distinction would be losing the most important thing on the row: stopping a queued job and
+ * stopping one that is halfway through a deploy are different decisions. So the group is
+ * carried on each item and shown inline on the ones that need it — "queued" is stated, and
+ * "running" is the unmarked default, because marking both makes neither stand out.
+ *
+ * Returns [{ id, status, group, label }] in the same order agentListRows lays out.
+ */
+export function agentPickerItems(rows, { width = 80 } = {}) {
+  const QUEUED = "  ·  queued";
+  // The picker's own chrome — drawList adds a gutter and a 2-column "▸ " marker to every row —
+  // plus the widest suffix, so the columns are laid out inside the room that is actually left
+  // rather than the full width. Getting this wrong does not wrap (drawList clips), it TRUNCATES
+  // the age off the right-hand end, which is the one column the reader came for.
+  const room = Math.max(20, (width | 0) - 5 - QUEUED.length);
+  const out = [];
+  let group = "";
+  for (const r of agentListRows(rows, { width: room, gutter: "" })) {
+    if (r.kind === "header") {
+      group = r.text;
+      continue;
+    }
+    const label =
+      r.title.padEnd(r.titleW) +
+      (r.detail ? "  " + r.detail.padEnd(r.detailW) : "") +
+      "  " + r.age +
+      (group === "Waiting" ? QUEUED : "");
+    out.push({ id: r.id, status: r.status ?? "", group, label });
+  }
+  return out;
+}
+
+export const HIDDEN_COMMANDS = [
+  "/provider",                  // and /providers — /model's picker carries "add or change an
+  "/providers",                 // OpenAI-compatible provider…" in every branch, so listing this
+                                // too offered two doors into one setting (reported as confusing)
+  "/rag-local",                 // superseded by /rag's picker; still work, still mean what
+  "/rag-cloud",                 // they say — unlisted so /help offers one way into the setting
+  "/thought",                   // the reasoning display stays ON; only the toggle is unlisted
+  "/hover",                     // in-turn mouse capture — behaviour unchanged, just hidden
+  "/reset",
+  "/new",
+  "/reset-output-token-global", // pending a rename to /reset-global-token that also resets
+                                // the INPUT total — which does not exist yet as a counter
+];
+
+/**
+ * Does this API base point at a server on THIS machine? (task #154)
+ *
+ * That is the definition of Client Expert — the API and database are local — and it is read
+ * from the live configuration rather than the setup notes on disk, so it stays true after a
+ * `gu clear` of the notes and false on a machine that was only ever pointed at the hosted
+ * API. The banner previously said plain "client" on a fully set-up Client Expert box, which is
+ * the one thing that line exists to make explicit.
+ */
+export function isLocalApiBase(apiBase) {
+  return /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:|\/|$)/i.test(String(apiBase ?? "").trim());
+}
+
+/**
+ * The banner's "mode" row, or null when there is nothing worth saying.
+ *
+ * ORDER IS THE WHOLE POINT: a Client Expert machine is ALSO a client for models, so testing
+ * `clientMode` first makes it read as an ordinary client and the local API + database — the
+ * entire distinction — go unmentioned. Reported live on a fully set-up Ubuntu box that said
+ * plain "client".
+ */
+export function modeRow({ clientExpert, clientMode }) {
+  if (clientExpert) {
+    return { label: "client expert", detail: "(API + database here · models remote)" };
+  }
+  if (clientMode) {
+    return { label: "client", detail: "(agent runs here · models remote)" };
+  }
+  return null;
+}
+
+/**
+ * After a window resize settles, WHO repaints the transcript — and with which painter?
+ *
+ * "scrollback" = the user is scrolled back, repaint that slice. "live" = repaint the tail.
+ * null = leave the screen alone, because someone else owns it.
+ *
+ * The ownership rules are the point, and this must agree with the resize handler's own
+ * early-returns — a test is cheaper than remembering that it should.
+ *
+ * A MODAL draws itself and the handler already redrew it, so repainting under it is the race
+ * the early-returns exist to prevent.
+ *
+ * A BUSY TURN used to decline for the same reason, and that was the bug (reported live:
+ * resizing while the agent thinks corrupts the screen, resizing at the prompt does not). The
+ * live status block is drawn in place and erased by walking the caret up from the saved output
+ * position — an absolute row recorded BEFORE the reflow, which the resize invalidates. Nothing
+ * else repainted during a turn, so the damage stayed. The handler now forgets that block
+ * without erasing it and leaves the healing here: the repaint rewrites every row of the
+ * scrolling area, so the stale block goes with it, and the 120ms ticker draws a fresh one.
+ */
+export function resizeRepaintTarget({ barPinned, modal, busy, scrolledBack }) {
+  // Not pinned = gu is not rendering the view at all; the terminal owns the screen.
+  if (!barPinned) return null;
+  if (modal) return null;
+  return scrolledBack ? "scrollback" : "live";
+}
+
+/**
+ * Should the workspace "sync chat history to the cloud?" question be ASKED? (task #154)
+ *
+ * Not on a Client Expert machine. There is no cloud there: the API and the database are on
+ * this box, "your account" is a local row, and there is no web app to see it on — so every
+ * clause of the question is false. Asking a question whose premise is wrong is worse than not
+ * asking, because the answer cannot mean what the reader thinks it means.
+ *
+ * The sync itself still happens — it writes to the local database, which is where that
+ * machine's conversations already live — so the value is true and it is stated rather than
+ * asked. Reported live: a Client Expert machine on Windows offering to send chat to a cloud
+ * it does not have.
+ */
+export function workspaceSyncQuestion({ clientExpert }) {
+  return clientExpert
+    ? {
+        ask: false,
+        value: true,
+        note: "chat history is kept in the local database on this machine (Local mode)",
+      }
+    : { ask: true, value: null, note: "" };
+}
+
+/**
+ * A counter that CLIMBS to its new value instead of jumping (user, 2026-09-05: "lets make it
+ * dynamically going up so we can see it increase slowly… like 400 then 410, then 440, then 470
+ * then 550, better right?").
+ *
+ * For the "↓ N" output-token figure beside the thinking line. Eases by a FRACTION of the
+ * remaining distance, so it moves fast when the jump is big and settles as it arrives — the
+ * shape that reads as counting rather than as a progress bar. The status block is already
+ * redrawn ~8x/second for its spinner while the agent is thinking, so this costs no extra
+ * repaints; it gives the ones already happening something to say.
+ *
+ * THREE RULES IT MUST NOT BREAK, because this is a MEASUREMENT and not decoration:
+ *
+ *  · NEVER OVERSTATE. The eased value approaches from below and is clamped to the target, so
+ *    what is on screen is always tokens that have genuinely been produced. A counter that
+ *    overshot and settled back would be inventing output.
+ *  · ALWAYS ARRIVE. A pure fraction converges without reaching, leaving "549" on screen forever
+ *    against a real 550. minStep guarantees a whole token of progress per tick, so it lands
+ *    exactly on the target.
+ *  · SNAP DOWNWARD. A target BELOW the shown value is a new turn resetting to 0, not a decrease
+ *    to animate — easing that would show the previous question's tail draining away.
+ */
+export function easeCount(shown, target, { rate = 0.3, minStep = 0 } = {}) {
+  const from = Math.max(0, Math.floor(Number(shown) || 0));
+  const to = Math.max(0, Math.floor(Number(target) || 0));
+  if (to <= from) return to; // arrived, or reset by a new turn
+  // THE FLOOR SCALES WITH THE TARGET, so the tail does not crawl. A flat minimum of 1 made the
+  // last stretch of a 550-token climb take six ticks to cover seven tokens — visibly fussy, and
+  // at four figures fmtTokens rounds them all to the same "0.5k" anyway, so those ticks paint a
+  // number that never changes. 1% of the target lands the same climb in nine ticks (~1s) with
+  // the ease-out shape intact.
+  const floor = minStep || Math.max(1, Math.ceil(to / 100));
+  const step = Math.max(floor, Math.ceil((to - from) * rate));
+  return Math.min(to, from + step);
+}
+
+/**
+ * WHICH CODER IS ACTIVE — the one and only answer, for every place that shows it.
+ *
+ * THIS EXISTS BECAUSE THE RULE WAS WRITTEN THREE TIMES AND DRIFTED THREE WAYS. The bar said
+ * `sessionCodingLabel || defaultCodingModel`, the banner said `override || payload.codingModelId`,
+ * and the stale-pick warning said `sessionCodingLabel || sessionCodingModel` — mixing the label
+ * with the raw id. Each was right on its own and they disagreed with each other, so the screen
+ * showed two different coders at once (2026-09-05, twice: the banner naming the account default
+ * while the bar named the folder's pick, then the bar naming the old coder after a reconfigure
+ * had changed it).
+ *
+ * Three sites re-deriving one rule is three chances to update two of them. A fourth display
+ * would have been a fourth bug. So: one function, and a test that nothing re-derives it.
+ *
+ * THE ORDER, and why each step is there:
+ *   1. the /model pick's LABEL — this folder's choice, and what the next turn will use;
+ *   2. its raw ID — a session saved before labels were stored still has one, and a qualified
+ *      "ollama::qwen3:14b" beats showing nothing;
+ *   3. the ACCOUNT DEFAULT — no pick, so the account's coder is the answer;
+ *   4. "" — genuinely unknown. The caller decides how to render that; inventing a name here
+ *      would put a model on screen that nothing is configured to use.
+ */
+export function activeCoderName({
+  sessionLabel = "",
+  sessionModel = "",
+  accountDefault = "",
+} = {}) {
+  const s = (v) => String(v ?? "").trim();
+  return s(sessionLabel) || s(sessionModel) || s(accountDefault) || "";
+}
+
+/**
+ * The bar's identity row — "coder | folder", plus a mark when no key has been chosen.
+ *
+ * REPORTED: "can we show this warning outside, like at the bottom bar, need to notify the user
+ * BEFORE HAND, not only when user do slash model." Correct — a warning you have to go looking for
+ * is one you find after the turn that needed it.
+ *
+ * IT GOES INSIDE THE EXISTING ROW, NOT ON A NEW ONE. The bar lives in the frozen zone, and a zone
+ * whose height changes is what broke every screen-row mapping in task #222 — so the mark rides
+ * beside the coder, where the reader is already looking to answer "what is this pointed at".
+ *
+ * SHORT ON PURPOSE. The row is clipped to the terminal width and the folder name sits after it;
+ * a sentence here would push the folder off a narrow screen. The bar says THAT something is
+ * unchosen, /model and ctrl+k say what to do about it.
+ */
+const passthrough = (v) => v;
+
+export function identityRow(
+  { coder = "", folder = "", keyUnchosen = false } = {},
+  { orange = passthrough, cyan = passthrough, dim = passthrough, red = passthrough } = {},
+) {
+  const name = String(coder ?? "").trim();
+  const where = String(folder ?? "").trim();
+  // The mark only means anything beside a named coder: with none shown there is nothing for it
+  // to be about, and it would read as a fault in the folder.
+  const mark = name && keyUnchosen ? red(" ⚠ key not chosen") : "";
+  return (name ? orange(name) + mark + dim(" | ") : "") + cyan(where);
+}
+
+/**
+ * What to say about syncing, next to a registered workspace.
+ *
+ * ON CLIENT EXPERT, NOTHING. That mode's whole promise is that the machine keeps everything —
+ * API, database, models — and shares none of it, so "cloud sync on" is not merely noise, it
+ * contradicts the mode the user chose (reported 2026-09-04). workspaceSyncQuestion already
+ * knows this and stores `true` meaning "persist it", but the LABEL read that value as "to the
+ * cloud", which is the one place it does not go.
+ *
+ * The chat history is still saved — to the local MongoDB on that machine, which the setup
+ * banner already says. Saying nothing here is therefore not hiding anything: it is declining to
+ * repeat a fact under a name that is wrong.
+ */
+export function workspaceSyncLabel({ allowSync, clientExpert }) {
+  if (clientExpert) return "";
+  return allowSync ? " · cloud sync on" : " · cloud sync off";
+}
+
+// ---------------------------------------------------------------------------
+// The blinking status line's text — what the agent is doing RIGHT NOW (#68, #170 follow-up).
+//
+// The model often emits <code> with NO "Thought:" prose (or degenerates into a runaway), so
+// the raw stream is a create_file(...) blob or escaped CSS, which used to render verbatim on
+// the line ("◐ , #94a3b8);\n -webkit-background-clip…"). Show a genuine thought ONLY when the
+// model actually wrote prose; otherwise name the TOOL it is calling; otherwise show nothing
+// and let the caller fall back to "Thinking…". Never raw code.
+//
+// Moved here from gu-repl.mjs so it can be tested: that file starts a REPL on import.
+// ---------------------------------------------------------------------------
+
+const _baseName = (p) => (String(p || "").split(/[\\/]/).pop() || "").trim();
+
+/** Trim a long argument for a one-line status without cutting mid-word where avoidable. */
+const _arg = (s, limit = 48) => {
+  const t = String(s || "").trim();
+  if (t.length <= limit) return t;
+  const cut = t.slice(0, limit).replace(/\s+\S*$/, "");
+  return (cut.length >= limit * 0.6 ? cut : t.slice(0, limit)) + "…";
+};
+
+/**
+ * WHAT the tool is doing, said in the terms the user cares about.
+ *
+ * The SEARCH tools quote their argument. They used to be bare ("Searching the code"), which
+ * told you the agent was busy and nothing about what it was looking for — the one detail worth
+ * having while you wait, and the one that makes a wrong search obvious before it finishes.
+ * Reads and commands already did this; grep and RAG were the odd ones out.
+ */
+export const THOUGHT_TOOL_LABELS = {
+  create_file: (a) => `Writing ${_baseName(a) || "a file"}`,
+  create_folder: (a) => `Creating ${_baseName(a) || "a folder"}`,
+  edit_lines: (a) => `Editing ${_baseName(a) || "a file"}`,
+  edit_file: (a) => `Editing ${_baseName(a) || "a file"}`,
+  read_file_lines: (a) => `Reading ${_baseName(a) || "a file"}`,
+  read_text_file: (a) => `Reading ${_baseName(a) || "a file"}`,
+  list_dir: (a) => `Listing ${_baseName(a) || "files"}`,
+  grep_repo: (a) => (a ? `Searching the code for ${_arg(a)}` : "Searching the code"),
+  run_command: (a) => `Running ${_arg(a, 60) || "a command"}`,
+  stop_server: () => "Stopping the server",
+  deploy_web: () => "Deploying",
+  fetch_url: (a) => `Fetching ${_baseName(a) || "a page"}`,
+  web_search: (a) => (a ? `Searching the web for ${_arg(a)}` : "Searching the web"),
+  http_request: () => "Calling an API",
+  create_pdf: () => "Building a PDF",
+  rag_search: (a) => (a ? `Searching the knowledge base for ${_arg(a)}` : "Searching the knowledge base"),
+  rag_search_workspace: (a) =>
+    a ? `Searching the knowledge base for ${_arg(a)}` : "Searching the knowledge base",
+  rag_index: () => "Indexing the knowledge base",
+  index_project: () => "Indexing the knowledge base",
+  download_file: () => "Downloading a file",
+  unzip_file: () => "Unzipping",
+  send_email: () => "Preparing an email",
+  open_url: (a) => `Opening ${a || "a link"}`,
+  final_answer: () => "Composing the answer",
+};
+
+// Does this candidate look like CODE / a data blob rather than a human thought? (Escaped
+// newlines, braces, hex colors, -webkit-, a leading function call, or too few spaces.)
+const _thoughtLooksCodey = (s) =>
+  /\\n|[{}]|=>|="|#[0-9a-fA-F]{3,6}\b|-webkit-|;\s*$|^\s*[<([]/.test(s) ||
+  /^\s*[a-z_]\w*\s*\(/i.test(s) ||
+  (s.length > 24 && (s.split(" ").length - 1) / s.length < 0.06);
+
+/**
+ * The FIRST argument of a tool call, whether it was passed positionally or by keyword.
+ *
+ * The old pattern only understood a bare quoted value or `path=`, so every OTHER keyword fell
+ * through and captured the keyword itself: `grep_repo(pattern="Route|Router")` yielded the
+ * string "pattern=", which is why quoting the argument had to wait for this. Any `name=` is
+ * accepted now, and the value is read whether it is single-quoted, double-quoted or bare.
+ */
+export function firstToolArg(codePart) {
+  const m = /\b([a-z_]\w*)\s*\(\s*(?:[a-z_]\w*\s*=\s*)?(?:"([^"\n]*)"|'([^'\n]*)'|([^"'\n,)]*))/i
+    .exec(String(codePart || ""));
+  if (!m) return null;
+  const value = m[2] ?? m[3] ?? m[4] ?? "";
+  return { name: m[1], arg: String(value).trim() };
+}
+
+/**
+ * Raw in-fence stream → a short, meaningful status: a real Thought clause if the model wrote
+ * one, else a label naming the tool it is calling, else "" (the caller shows "Thinking…").
+ */
+export function normalizeThought(buf) {
+  const t = String(buf || "");
+  const ci = t.search(/<code[\s>]/i);
+  const head = ci >= 0 ? t.slice(0, ci) : t;
+  // 1) a genuine Thought prose line (before the code) — only if it isn't itself code AND
+  //    reads like an actual clause. A streaming token boundary can leave the first
+  //    non-empty line as a single bare word (e.g. "string", when the model is rambling
+  //    about "multi-line strings"); shown alone on the blinking line it's meaningless and,
+  //    because liveThought only updates on a truthy value, it can FREEZE there through a
+  //    long silent prompt-eval ("string… (777s)"). Require ≥2 words and a little length so
+  //    a lone fragment falls through to the tool label / "Thinking…" instead.
+  const prose = head
+    .replace(/^\s*Thought:\s*/i, "")
+    .split(/\n/)
+    .map((x) => x.trim())
+    .find(Boolean);
+  const proseIsClause = !!prose && prose.length >= 6 && prose.trim().split(/\s+/).length >= 2;
+  if (proseIsClause && !_thoughtLooksCodey(prose)) return prose.slice(0, 100);
+  // 2) otherwise name the tool being called (from the code part).
+  const codePart = ci >= 0 ? t.slice(ci) : t;
+  const call = firstToolArg(codePart);
+  if (call && THOUGHT_TOOL_LABELS[call.name]) {
+    return THOUGHT_TOOL_LABELS[call.name](call.arg).slice(0, 100);
+  }
+  // 3) nothing human to show.
+  return "";
+}
+
+/**
+ * Should the status block be REBUILT this tick, or held frozen? (#170 follow-up)
+ *
+ * While tokens flow the block is deliberately parked: `lastContentAt` is bumped by nearly every
+ * stream line, so a live rebuild would run 8×/second and the playful word would strobe. Freezing
+ * the last rendered rows is what stopped that.
+ *
+ * But the thought line lives in that same frozen block, so freezing it also froze the ONE place
+ * that says what the agent is doing. A step that starts and finishes inside the quiet window
+ * never repainted at all: measured on a live turn, 24 consecutive samples all read "Thinking…"
+ * while the model was in fact running a grep whose pattern was already computed and sitting in
+ * `liveThought`, unpainted.
+ *
+ * So: park, EXCEPT when the thought itself changed. That fires a handful of times per step
+ * rather than eight times a second, so it cannot strobe — the spinner and word are keyed to the
+ * wall clock and do not re-roll on an extra repaint.
+ */
+export function statusNeedsLiveRepaint({
+  msSinceContent = 0,
+  quietMs = 700,
+  liveThought = "",
+  paintedThought = "",
+} = {}) {
+  if (msSinceContent >= quietMs) return true; // quiet: the normal animated path
+  return String(liveThought ?? "") !== String(paintedThought ?? "");
+}
+
+/**
+ * The FULLER thought behind the live line (#96 click-to-expand).
+ *
+ * NOT clipped to one clause/100 chars — collapsed to a single spaced string and capped so the
+ * expanded view has a few lines to show. Returns "" when the live line is only a tool label
+ * (nothing extra to unfold). Bounded by fenceThought's own 400-char cap.
+ *
+ * Lives here, beside _thoughtLooksCodey, because it SHARES that gate with normalizeThought.
+ * It was left behind in gu-repl.mjs when the rest moved, and since that file cannot be
+ * imported, nothing caught the dangling reference: `node --check` validates syntax, not
+ * resolution, and this line only runs once a stream fence is open. It reached a user as
+ * "✗ _thoughtLooksCodey is not defined" on a live turn.
+ */
+export function thoughtFull(buf) {
+  const t = String(buf || "");
+  const ci = t.search(/<code[\s>]/i);
+  const head = (ci >= 0 ? t.slice(0, ci) : t)
+    .replace(/^\s*Thought:\s*/i, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  // Only worth expanding when there's a genuine prose clause (same gate as normalizeThought
+  // path 1) — a bare fragment or pure code has nothing meaningful to unfold.
+  const first = head.split(/\s+/).length;
+  if (head.length < 6 || first < 2 || _thoughtLooksCodey(head)) return "";
+  return head.slice(0, 400);
+}
+
+/**
+ * The LEXICAL half of the token row: "grep 2", beside the rag segment (asked for directly).
+ *
+ * Both routes find code and they behave nothing alike — RAG is semantic and approximate, grep is
+ * lexical and exact — so a row naming only one of them invites the reading that the other never
+ * happens. A turn that answered entirely by grep showed "rag 0" and nothing else, which looks
+ * like a turn that found nothing at all.
+ *
+ * COUNTS OF SEARCHES, not tokens, and deliberately not folded into PROMPT_BUCKETS: those must
+ * sum to the size of the newest request, and an action count is not a share of anything. Returns
+ * "" when nothing was searched, so a chat turn keeps its short row.
+ */
+export function searchSegmentLabel(b) {
+  if (!b || typeof b !== "object") return "";
+  const n = (k) => (Number.isFinite(b[k]) ? b[k] : 0);
+  const grep = n("grepCalls");
+  if (!grep) return "";
+  // WIDTH IS THE CONSTRAINT HERE, not information. The row is clipped to the terminal width so
+  // it can never wrap (the #109/#138 invariant), and a first cut carrying "grep 1 · 10 hits ·
+  // read 5" pushed "↓ out" and the coder name straight off the edge — measured on a real turn.
+  // So the bar shows the COUNT only, and annotates just the case a bare count cannot express:
+  // searches that found NOTHING, the signature of a model guessing patterns. Hits and file
+  // reads stay on the inline "Found code by →" line, which has a whole row to itself.
+  return n("grepHits") ? `grep ${grep}` : `grep ${grep} · no hits`;
+}
+
+/**
+ * The detail row(s) under the live status line: WHAT is executing right now (task #177).
+ *
+ * run_command has always shown its command while it ran ("◑ Running ls …"); every other tool
+ * announced itself only after finishing, because the bullet carries the result count. So the
+ * pattern was invisible during the one stretch where someone is watching and wondering. Asked
+ * for directly: "show the grep command before it actually run".
+ *
+ * ONE detail on screen, belonging to whatever is running. When the tool returns, the live block
+ * is erased and replaced by the finished bullet, so nothing accumulates and there is nothing to
+ * click.
+ *
+ * THE ROWS MUST NOT WRAP. This block is redrawn in place by walking the caret with ESC[nA, and
+ * `n` counts PHYSICAL rows — a soft-wrapped row desynchronises every later erase (#109, #138).
+ * Hence a hard cap of two rows and a clip to the width, with the break preferring an argument
+ * boundary so a split call still reads as a call.
+ */
+export function runningDetailRows(detail, { width = 80, indent = 5, maxRows = 2 } = {}) {
+  const text = String(detail || "").replace(/\s+/g, " ").trim();
+  if (!text) return [];
+  const pad = " ".repeat(Math.max(0, indent));
+  const room = Math.max(12, width - pad.length - 1);
+  if (text.length <= room) return [pad + text];
+  if (maxRows <= 1) return [pad + text.slice(0, room - 1) + "…"];
+  // Prefer breaking after an argument separator, so row 2 starts at `name=` rather than
+  // mid-token. Only accept a break that is not absurdly early, or a long first argument would
+  // strand the rest on one over-full row.
+  let cut = -1;
+  for (const sep of [", ", "="]) {
+    const at = text.lastIndexOf(sep, room);
+    if (at > room * 0.45) { cut = at + (sep === ", " ? 2 : 1); break; }
+  }
+  if (cut < 0) cut = room;
+  const rest = text.slice(cut);
+  return [
+    pad + text.slice(0, cut).replace(/\s+$/, ""),
+    pad + "  " + (rest.length <= room - 2 ? rest : rest.slice(0, room - 3) + "…"),
+  ];
+}
+
+/**
+ * How long the turn took, for the line above the answer (task #178).
+ *
+ * Minutes only once there are any: "12s" reads better than "0m 12s", and an hour-long turn
+ * should not be reported as "63m".
+ */
+/**
+ * A wall-clock stamp for the end of a turn: 1546003800000 → "3:30 PM".
+ *
+ * Written out rather than delegated to toLocaleTimeString, which varies by ICU build and by the
+ * machine's locale — a Vietnamese box would render this in 24-hour form, and the format was
+ * asked for by name. Returns "" for a time that is not one, so a caller can omit the segment
+ * rather than print "Invalid Date" beside a real duration.
+ */
+export function formatClockTime(at = Date.now()) {
+  const d = at instanceof Date ? at : new Date(at);
+  if (Number.isNaN(d.getTime())) return "";
+  const suffix = d.getHours() >= 12 ? "PM" : "AM";
+  // 0 and 12 are both "12" — midnight is 12 AM, noon is 12 PM.
+  const hour = d.getHours() % 12 || 12;
+  return `${hour}:${String(d.getMinutes()).padStart(2, "0")} ${suffix}`;
+}
+
+export function formatThinkTime(ms) {
+  const total = Math.max(0, Math.round(Number(ms) || 0) / 1000);
+  if (total < 60) return `${Math.round(total)}s`;
+  const mins = Math.floor(total / 60);
+  const secs = Math.round(total - mins * 60);
+  if (mins < 60) return secs ? `${mins}m ${secs}s` : `${mins}m`;
+  const hrs = Math.floor(mins / 60);
+  const rem = mins - hrs * 60;
+  return rem ? `${hrs}h ${rem}m` : `${hrs}h`;
+}
+
+// Emoji, variation selectors, skin-tone modifiers, the joiner AND regional indicators, plus
+// ONE following space so "✅ Done" becomes "Done" rather than " Done".
+//
+// Regional indicators are the easy miss: a flag is two of them and matches neither
+// Extended_Pictographic nor Emoji_Modifier, so 🇬🇧 sailed straight through the first version.
+const _PICTOGRAPH =
+  /[\p{Extended_Pictographic}\p{Emoji_Modifier}\p{Regional_Indicator}️‍]+[ \t]?/gu;
+
+/**
+ * The answer as PLAIN TEXT: decorative emoji removed (task #178).
+ *
+ * Asked for directly — "remove all the special icon like WEb icon or a Big check icon, in
+ * general just text in the summary". A model reaching for 🌐 and ✅ is decorating, and the
+ * decoration competes with this UI's own glyph vocabulary, where ✓ and ✗ and ● each mean one
+ * specific thing (#41: a red ✗ is "the one thing you must not miss"). Borrowed emphasis from
+ * the model dilutes the marks the terminal itself uses.
+ *
+ * CODE IS NEVER TOUCHED — neither fenced blocks nor inline spans. An emoji inside a string
+ * literal is data: removing it changes what the code does, and the answer is routinely copied
+ * straight out of the transcript (#158 exists because a copied answer must still run).
+ */
+export function plainAnswer(text) {
+  const src = String(text ?? "");
+  // Odd indices are fenced blocks — kept verbatim.
+  return src
+    .split(/(```[\s\S]*?```)/g)
+    .map((part, i) =>
+      i % 2
+        ? part
+        : // …and within prose, odd indices are inline code spans.
+          part
+            .split(/(`[^`\n]*`)/g)
+            .map((seg, j) => (j % 2 ? seg : seg.replace(_PICTOGRAPH, "")))
+            .join("")
+    )
+    .join("")
+    .replace(/[ \t]+$/gm, "");
+}
+
+/**
+ * Which slice of a long picker list to draw, and how far it has scrolled (task #223 follow-up).
+ *
+ * REPORTED: choosing a model from OpenAI's /v1/models — about eighty ids — rendered EVERY row.
+ * The block was taller than the terminal, so the screen scrolled, the highlighted row was off
+ * the top, and the `ESC[nA` walk that redraws the block in place then counted rows that were no
+ * longer where it thought. From the outside: "cannot scroll up or down, stuck here."
+ *
+ * THE BLOCK HEIGHT IS CONSTANT WHILE WINDOWING, and that is deliberate rather than tidy. Every
+ * redraw walks up exactly as many rows as it drew; a block that changed height as the ends came
+ * into view would leave that walk one or two rows out, which is precisely the class of bug this
+ * file's physicalRows() exists to prevent. So the two indicator rows are always present once the
+ * list is windowed — they simply render empty at the ends.
+ *
+ *   total   how many items there are
+ *   sel     the highlighted index
+ *   top     the first visible index from the previous draw (0 on open)
+ *   height  rows available for the WHOLE block, indicators included
+ *
+ * Returns { windowed, top, from, to, above, below } — `from`/`to` a half-open range.
+ */
+export function listWindow(total, sel, top, height) {
+  const n = Math.max(0, Math.floor(total));
+  const h = Math.max(1, Math.floor(height));
+  if (n <= h) return { windowed: false, top: 0, from: 0, to: n, above: 0, below: 0 };
+  // Two rows go to the indicators, so at least one item is always visible even on a tiny screen.
+  const itemRows = Math.max(1, h - 2);
+  const last = n - itemRows;
+  let t = Math.min(Math.max(0, Math.floor(top) || 0), last);
+  // FOLLOW THE SELECTION, INCLUDING A WRAP. Arrowing up from the first row jumps to the last,
+  // and a window that only ever crept by one would take eighty presses to catch up.
+  const s = Math.min(Math.max(0, Math.floor(sel) || 0), n - 1);
+  if (s < t) t = s;
+  else if (s >= t + itemRows) t = s - itemRows + 1;
+  t = Math.min(Math.max(0, t), last);
+  return { windowed: true, top: t, from: t, to: t + itemRows, above: t, below: n - (t + itemRows) };
+}
+
+/**
+ * THE LINE THAT MEANS "the reader pressed Esc instead of answering".
+ *
+ * A NUL-prefixed sentinel for the same reason the attach sentinel is one: nothing that can be
+ * typed, pasted or recalled from history produces a NUL, so it can never collide with a real
+ * answer to a real question. Exported so the REPL and its tests agree on the value rather than
+ * each spelling it out.
+ */
+export const CANCEL_LINE = "\u0000cancel";
+
+/**
+ * Should this keypress cancel the question that is waiting? (reported live)
+ *
+ * "it should allow user to escape ... also make sure that the user can cancel in any screen like
+ * this" - the pickers have offered Esc since PICK_HINT was written; the TYPED prompts offered
+ * nothing, except the one that said `type "no"`, which you had to already know.
+ *
+ * A FUNCTION RATHER THAN A CONDITION INLINE IN _ttyWrite, because three separate paths have to
+ * reach the identical answer - the live keypress, the keys the CPR reader replays when they turn
+ * out not to be a probe answer, and the ones its timer flushes 300ms later - and a rule written
+ * three times is a rule that will differ in one of them. It is also the only part of this that
+ * can be tested without a terminal.
+ *
+ * THE SEQUENCE IS THE TEST, NOT `meta` — and this cost a working feature to learn. Node sets
+ * `meta: true` on a LONE Esc (it is how its parser marks "this began with ESC"), so the obvious
+ * rule, `!key.ctrl && !key.meta`, rejects the one key the whole feature exists to catch. Written
+ * that way it passed a unit test built from a hand-made `{name:"escape"}` object and would have
+ * done nothing whatsoever in a terminal. MEASURED against a real pty, node emits:
+ *
+ *     lone Esc      name=escape  sequence="\u001b"        meta=true
+ *     alt+Esc       name=escape  sequence="\u001b\u001b" meta=true
+ *     up arrow      name=up      sequence="\u001b[A"      meta=false
+ *     alt+a         name=a       sequence="\u001ba"       meta=true
+ *     Home          name=home    sequence="\u001b[H"      meta=false
+ *     F1            name=f1      sequence="\u001bOP"      meta=false
+ *     CPR reply     name=undefined                         meta=false
+ *
+ * So: `escape` names the lone key and alt+Esc alike, `meta` cannot separate them, and only the
+ * SEQUENCE — exactly one ESC byte and nothing else — identifies the key a person pressed.
+ *
+ * WHAT IS DELIBERATELY NOT A CANCEL:
+ *  - anything at all while no question is waiting. The main ">> " prompt parks on the same
+ *    queue, and Esc there has always meant nothing; making it throw would abort a turn.
+ *  - alt+Esc and ctrl+Esc. A terminal may send those for something else, and a cancel should be
+ *    the key the reader meant rather than one they passed through.
+ *  - every other key. The arrows, Home/End and the function keys all BEGIN with ESC but reach
+ *    readline already parsed into named keys, so none of them can be mistaken for this one.
+ */
+export function shouldCancelPrompt(awaiting, key) {
+  if (!awaiting) return false;
+  if (key?.name !== "escape") return false;
+  if (key.ctrl) return false;
+  return key.sequence === "\u001b";
+}