@tiens.nguyen/gu-cli 1.0.793 → 1.0.795

package/gonext_agent_chat.py

@@ -992,6 +992,80 @@ def _web_search_impl(query, max_results=5, searxng_url="",
 # the text still reaches both UIs, the prefix tells them it is a failure, not a reply.
 TURN_FAILED = "__TURN_FAILED__::"
 
+# ANOTHER MODEL STOOD IN (task #343). Reported live: the coding model had a problem, a different
+# model answered, and nothing on screen said so — the turn "worked", only with a model nobody
+# picked. Every place in this file where one model takes over from another now says so with ONE
+# event, a step carrying this prefix and a JSON body, so the terminal can hold it in yellow on the
+# bottom bar. A step, like __RAGSTATE__::, so it rides the job's chunk stream and still arrives
+# when the agent runs on a different machine than the terminal.
+#
+# What is NOT a fallback and must never be reported as one: a retry on the SAME model, and the
+# 429 / 502 exits below — those end the turn as failed, no other model answers.
+MODEL_FALLBACK = "__MODELFALLBACK__::"
+
+
+def _fallback_reason(err) -> str:
+    """Why a model was given up on, in a few words that fit a status bar — never a stack of
+    exception text (an nginx error is a whole HTML page). The status code when there is one,
+    else the kind of failure, else the first line clipped."""
+    if err is None:
+        return ""
+    status = _http_status_of(err)
+    text = str(err)
+    low = text.lower()
+    if status in (401, 403):
+        return f"{status} key refused"
+    if status == 404:
+        return "404 model not found"
+    if status == 429 or "overloaded" in low or "rate limit" in low:
+        return "429 overloaded"
+    if status and status >= 500:
+        return f"{status} server error"
+    if "timed out" in low or "timeout" in low:
+        return "timed out"
+    if "empty response" in low:
+        return "empty reply"
+    if "context" in low and ("length" in low or "window" in low or "too long" in low or "exceed" in low):
+        return "context too large"
+    if "connection" in low or "connect" in low or "refused" in low or "unreachable" in low:
+        return "could not connect"
+    if status:
+        return f"HTTP {status}"
+    first = next((ln.strip() for ln in text.splitlines() if ln.strip()), "")
+    first = re.sub(r"<[^>]+>", " ", first)
+    first = re.sub(r"\s+", " ", first).strip()
+    return first if len(first) <= 48 else first[:47].rstrip() + "…"
+
+
+def _fallback_event(role, from_model, to_model, reason, *, tools=True, answered=True) -> str:
+    """The step text for one fallback. Pure.
+
+      role      "coder" — the coding model was given up on;  "chat" — the chat model was
+      from/to   the model that had the problem, and the one used instead
+      reason    a few words (see _fallback_reason)
+      tools     False when the stand-in answered as a bare chat reply — no files, no commands
+      answered  False when the stand-in failed too: "fell back" is only said when it answered
+    """
+    body = {
+        "role": "chat" if role == "chat" else "coder",
+        "from": str(from_model or "").strip(),
+        "to": str(to_model or "").strip(),
+        "reason": str(reason or "").strip(),
+        "tools": bool(tools),
+        "answered": bool(answered),
+    }
+    return MODEL_FALLBACK + json.dumps(body, ensure_ascii=False)
+
+
+def _report_fallback(role, from_model, to_model, reason, *, tools=True, answered=True) -> None:
+    """Tell the terminal another model stood in. Logged too, so a run log shows it."""
+    _log(
+        f"model fallback: {role} {from_model!r} -> {to_model!r} ({reason or 'no reason'})"
+        f"{'' if tools else ' — no tools'}{'' if answered else ' — it failed too'}"
+    )
+    _emit({"type": "step", "text": _fallback_event(
+        role, from_model, to_model, reason, tools=tools, answered=answered)})
+
 
 class _AgentConfigError(RuntimeError):
     """Deterministic setup error (e.g. wrong model name/URL). Not retryable and not
@@ -1473,6 +1547,24 @@ def _resolve_coding_target(agent_base_url, agent_model_id, raw_coding_base, raw_
     return agent_base_url, agent_model_id
 
 
+def _coder_fell_back_to_chat(agent_base_url, raw_coding_base, resolved_base) -> bool:
+    """Did _resolve_coding_target give the chat model a job a DIFFERENT coding server was chosen
+    for? Pure. False when no coder is set, and false for a coder on the chat model's own server
+    with no name — that is "use the chat model", chosen, not a fallback."""
+    raw = (raw_coding_base or "").rstrip("/")
+    if not raw or raw == (agent_base_url or "").rstrip("/"):
+        return False
+    return (resolved_base or "").rstrip("/") != raw
+
+
+def _coder_label(model_id, base_url) -> str:
+    """What to call a coder on the bar: its name, or — when it never told us one — its host."""
+    if (model_id or "").strip():
+        return model_id.strip()
+    host = re.sub(r"^[a-z]+://", "", (base_url or "").strip(), flags=re.I).split("/")[0]
+    return host or "the coding model"
+
+
 def _coding_backend_flags(backend):
     """Everything the resolved backend decides, derived in ONE place (task #117 → #123).
 
@@ -2943,6 +3035,7 @@ def _plain_reply(messages: list, base_url: str, api_key: str, model_id: str,
         targets.append((fallback_base_url, fallback_model_id, fallback_api_key or api_key))
 
     last_err = None
+    first_err = None
     for i, (b, mid, key) in enumerate(targets):
         emitted_here = False
 
@@ -2981,12 +3074,22 @@ def _plain_reply(messages: list, base_url: str, api_key: str, model_id: str,
             last_err = RuntimeError(f"{mid} returned an empty response")
         except Exception as e:  # noqa: BLE001
             last_err = e
+        if i == 0:
+            first_err = last_err  # why the model that was ASKED gave nothing
+        else:
+            # The stand-in did not answer either (#343) — take back "it answered".
+            _report_fallback("chat", targets[0][1], mid, _fallback_reason(first_err),
+                             tools=False, answered=False)
         if emitted_here:
             # Part of THIS attempt's answer already streamed to the user — don't
             # silently splice a DIFFERENT model's output after a partial one.
             break
         if i + 1 < len(targets):
             nb, nmid, _ = targets[i + 1]  # the model we're about to try next
+            # SAID AT THE SWITCH (#343), before the stand-in streams: a step that arrived after
+            # its answer would reopen the reasoning block under the reply. Corrected just above
+            # if it fails too.
+            _report_fallback("chat", mid, nmid, _fallback_reason(last_err), tools=False)
             _log(f"plain reply: {mid} @ {b} failed ({last_err}); "
                  f"falling back to {nmid} @ {nb}")
     # Every target failed or returned nothing — raise rather than return a sentinel
@@ -7671,6 +7774,11 @@ def run_agent_chat(cfg):
         agent_base_url, agent_model_id, raw_coding_base, raw_coding_model,
         agent_api_key=agent_api_key, coding_api_key=coding_api_key,
     )
+    # A coder WAS chosen and the chat model is doing its work (#343): its server would not say
+    # which model it serves. Said when the agent path starts — a plain chat turn does no coding,
+    # so there is nothing to have fallen back from.
+    _coder_unresolved = _coder_fell_back_to_chat(
+        agent_base_url, raw_coding_base, coding_base_url)
     # Task #108: an OpenAI-compatible coder REQUIRES an explicit model name (its
     # /v1/chat/completions needs a `model` id, and we won't silently reuse the MLX chat
     # model's name against a cloud endpoint). Fail with a clear, actionable message.
@@ -8490,6 +8598,9 @@ def run_agent_chat(cfg):
     # Agent path — from here all step events go into <think>.
     _log("router: agent (HTTP tool use needed)")
     _emit({"type": "step", "text": "Choosing a tool…"})
+    if _coder_unresolved:
+        _report_fallback("coder", _coder_label(raw_coding_model, raw_coding_base), agent_model_id,
+                         "its server named no model")
 
     # Prepend explicit tool instructions so small models pick the right tool, never
     # fabricate URLs/responses, and always terminate with final_answer().
@@ -11293,12 +11404,19 @@ def run_agent_chat(cfg):
                 # No usable tool output (e.g. every step's code failed to parse).
                 # Don't dead-end on a canned apology — answer from the conversation.
                 _log("max-steps fallback → plain reply over conversation")
+                # Every step was unusable and the chat model now answers from the conversation
+                # alone (#343). Said BEFORE it streams — a step after the answer would reopen
+                # the reasoning block under it — and corrected below if it fails too.
+                _report_fallback("coder", coding_model_id, agent_model_id,
+                                 "no usable step", tools=False)
                 try:
                     text = _plain_reply(
                         messages, agent_base_url, agent_api_key, agent_model_id
                     ).strip()
                 except Exception as e:  # noqa: BLE001
                     _log(f"plain-reply fallback error: {e}")
+                    _report_fallback("coder", coding_model_id, agent_model_id,
+                                     "no usable step", tools=False, answered=False)
                     text = ""
                 if not text:
                     text = ("I couldn't complete that within the step budget. Please "
@@ -13427,10 +13545,16 @@ def run_agent_chat(cfg):
         # answer from the conversation rather than surfacing a raw error to the user —
         # but only when the fallback ACTUALLY has something useful to say.
         _log(f"agent error: {e} — degrading to plain reply")
+        # The tool-capable loop failed and the chat model answers instead, with no tools (#343).
+        # Said BEFORE it streams; corrected in the except if it fails too.
+        _report_fallback("coder", coding_model_id, agent_model_id, _fallback_reason(e), tools=False)
         try:
             fallback = _plain_reply(messages, agent_base_url, agent_api_key, agent_model_id).strip()
         except Exception as e2:  # noqa: BLE001
             _log(f"plain-reply degrade error: {e2}")
+            # The stand-in failed too (#343): say THAT, never "fell back".
+            _report_fallback("coder", coding_model_id, agent_model_id, _fallback_reason(e),
+                             tools=False, answered=False)
             # Nothing useful to say — re-raise the ORIGINAL (more relevant) agent
             # failure so this becomes a genuine job failure: a red error the REPL/web
             # already handle correctly, NOT persisted to conversation history. Emitting

package/gu-repl.mjs

@@ -138,6 +138,11 @@ import { unapprovedProjectServers } from "./mcp-command.mjs";
 import { readHooks } from "./hooks-config.mjs";
 import { readSkillSource, sourceLabel, SKILL_SOURCE_KEY } from "./skill-source.mjs";
 import { codingBannerLabel, isOllamaCloudUrl, SECRET_KEY_HINT } from "./coding-key-prompt.mjs";
+import { thoughtPrintSeq } from "./terminal-layout.mjs";
+import {
+  MODELFALLBACK_PREFIX, fallbackAfterTurn, fallbackHistoryLine, fallbackNotice, keyMissingNotice,
+  parseModelFallback,
+} from "./model-fallback.mjs";
 import { codingChoiceTags, coderDisplayName, coderWhere, whereOfActiveCoder } from "./coding-choice-tags.mjs";
 import { IMAGE_NEEDS_CLAUDE, coderTakesImagesFor, clipboardImageToFile, fitImageNotice, imageMarkersForDisplay, createImageStore, imagePasteKey, imagePathFromPaste, isClaudeCoderUrl, isImagePasteKey, storeImageFile } from "./image-paste.mjs";
 import {
@@ -1635,6 +1640,28 @@ const missingNoticeRows = () => [
   ...(embedMissing ? ["⚠ no embed model — RAG is off · /embed-model"] : []),
 ];
 
+// ANOTHER MODEL STOOD IN (task #343). The agent reports it as a __MODELFALLBACK__:: step; it is
+// held here and shown in YELLOW on the bar — from the moment it happens, through the rest of the
+// turn, and on while it stays true: until a turn is answered with no fallback (the model works
+// again) or another model is picked. `turnFallback` is the one reported during the CURRENT turn.
+let modelFallback = null;
+let turnFallback = null;
+function setModelFallback(fb) {
+  modelFallback = fb;
+  if (barPinned()) paintBar();
+}
+// Its rows: the reported fallback, and — the one fallback the agent cannot report, because it
+// never sees the coder the API dropped — a coding model with no API key (task #222).
+const fallbackNoticeRows = () => {
+  const width = process.stdout.columns || 80;
+  return [
+    ...(modelFallback ? [fallbackNotice(modelFallback, { width, gutter: GUTTER })] : []),
+    ...(codingKeyMissingKnown === true
+      ? [keyMissingNotice({ coder: activeCodingModelId(), width, gutter: GUTTER })]
+      : []),
+  ];
+};
+
 // #307: the calm note after a quick change of mind — dim, not the ⚠ orange of a warning, and in the
 // bar rather than the transcript (which the whole point is to leave untouched).
 let stopNotice = "";
@@ -2213,6 +2240,9 @@ const UPDATE_CHECK_MS =
     ? Number(process.env.GONEXT_UPDATE_CHECK_MS)
     : 60 * 60 * 1000;
 async function refreshAvailableUpdates() {
+  // The terminal UI tests (tests/ui) run with no network and compare whole screens: an update
+  // notice that depends on what npm holds today would make every golden screen a coin toss.
+  if (process.env.GU_NO_UPDATE_CHECK === "1") return;
   const { updatesAvailable } = await import("./version-check.mjs");
   const cliLatest = await (async () => {
     try {
@@ -2597,7 +2627,9 @@ const footerRows = () =>
         ? dim(clipVisible(stopNotice, (process.stdout.columns || 80) - visibleLen(GUTTER) - 1))
         : "",
     // Task #14: the skipped-setup warning — persistent (not a timed notice), red, its own row.
-    missing: missingNoticeRows().map((r) => red(r)),
+    // …then the fallback rows (#343), YELLOW: a different model is doing the work — a warning,
+    // where the red rows above mean something is not set up at all.
+    missing: [...missingNoticeRows().map((r) => red(r)), ...fallbackNoticeRows().map((r) => yellow(r))],
   });
 // An ask()'s hint lines (#305), drawn in yellow under its input while it waits. Plain text.
 let askHint = [];
@@ -3357,7 +3389,7 @@ const thoughtWidth = () =>
  * Progress recedes and the answer is the only full-bright thing on screen — a page of bright
  * reasoning per step would bury the deliverable it is supposed to lead up to.
  */
-function printThoughtBlock(raw, before) {
+function printThoughtBlock(raw, before, { gap = false } = {}) {
   if (!sessionShowThought) return false;
   const prose = thoughtProse(raw);
   if (!prose) return false; // a bare tool label or pure code — not what anyone means by a thought
@@ -3404,8 +3436,14 @@ function printThoughtBlock(raw, before) {
     }
     // Scrolled out of the buffer — fall through and print a new block rather than lose it.
   }
-  process.stdout.write(rows.map((r) => GUTTER + dim(r)).join("\n") + "\n");
-  // Record where it landed. Measured AFTER the write so a trim during it cannot skew the
+  // ONE EMPTY LINE ABOVE A NEW THOUGHT (#344) when the row above it is not already blank.
+  // Reported with a screenshot: "The download is moving…" sat directly under "✓ Command finished
+  // → python3 -c …" and read as that command's OUTPUT — and under a bright "✗ Command failed" row,
+  // as its error text. A thought is printed when its step's reasoning ends, BEFORE that step's
+  // tools report: it introduces what comes next, it does not belong to the row above. Only for a
+  // NEW block — a continuation is merged into the previous one above and never gets here.
+  process.stdout.write(thoughtPrintSeq(rows.map((r) => GUTTER + dim(r)), { gap }));
+  // Record where it landed. The blank is above `from`, so the block is still exactly its rows. Measured AFTER the write so a trim during it cannot skew the
   // range: the last completed line is length-2 (the final entry is the still-open line).
   const endAbs = transcript.dropped() + transcript.length() - 2;
   thoughtBlocks.push({ from: endAbs - rows.length + 1, to: endAbs, prose, collapsed: true });
@@ -6721,6 +6759,7 @@ async function useCoderInThisFolder({ ps, rows, beforeChoices, url, host, locali
     console.log(GUTTER + dim("restart it with `gu api restart`, then add that provider again.\n"));
   }
   sessionCodingModel = offered.id;
+  setModelFallback(null); // #343
   sessionCodingLabel = model;
   sessionCodingUrl = url;
   // …and the host the bar puts in front of it (#263): left alone, the PREVIOUS coder's
@@ -6860,6 +6899,7 @@ async function chooseModel() {
   // Empty override means "use the account default" — so don't send an override when the
   // user picks the default (keeps the payload clean and lets a later default change win).
   sessionCodingModel = chosen.id === def ? "" : chosen.id;
+  setModelFallback(null); // #343: the warning named the coder that was just replaced
   // Remember the friendly name for the token footer, which should never show a raw
   // "<kind>::<model>" wire id.
   sessionCodingLabel = chosen.id === def ? "" : chosen.model;
@@ -11060,7 +11100,7 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
     if (heldThought === null) return;
     const raw = heldThought;
     heldThought = null;
-    if (printThoughtBlock(raw, onContent)) lastWasBlank = false;
+    if (printThoughtBlock(raw, onContent, { gap: !lastWasBlank })) lastWasBlank = false;
   };
   let hoverRow = -1; // last mouse viewport row (from motion events) → highlight when it's on the thought line
   let thoughtRow = -1; // absolute viewport row of the thought line (line 1), learned via \x1b[6n
@@ -11485,10 +11525,13 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
   // changed since is the VOLUME: a long turn now prints dozens of bullets interleaved with
   // collapsed thought prose, and with no blanks anywhere the two run together into a wall.
   //
-  // Above rather than below, for two reasons: a trailing blank would collide with the seam the
-  // caller owns before the bright answer (LINE_SPACING), and leading the group means the
-  // thought prose that FOLLOWS a bullet still sits tight against it — which is right, since
-  // that prose is the bullet's own reasoning, not the next step.
+  // Above rather than below: a trailing blank would collide with the seam the caller owns
+  // before the bright answer (LINE_SPACING).
+  //
+  // A THOUGHT GETS THE SAME BLANK ABOVE IT (#344, see printThoughtBlock). This comment used to say
+  // the prose after a bullet "sits tight against it — which is right, since that prose is the
+  // bullet's own reasoning". It is not: the thought is printed when the NEXT step's reasoning
+  // ends, so glued under "Command finished → …" it read as that command's output.
   //
   // `lastWasBlank` makes it idempotent: nothing doubles a blank that is already there.
   const openBullet = () => {
@@ -11509,7 +11552,10 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
     const at = thoughtBlocks.indexOf(stepGroup);
     if (at < 0) return false; // dropped from the registry (it is capped): no longer ours to rewrite
     for (let i = at + 1; i < thoughtBlocks.length; i++) {
-      if (thoughtBlocks[i].from !== end + 1) return false;
+      // Directly under, or under the ONE blank a thought now opens with (#344) — the look-up
+      // group must stay open across it, or every thought would start a new counted row.
+      const step = thoughtBlocks[i].from - end;
+      if (step !== 1 && step !== 2) return false;
       end = thoughtBlocks[i].to;
     }
     return end === transcriptTail();
@@ -11612,6 +11658,18 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
         lastContentAt = Date.now();
         continue;
       }
+      // Task #343: another model took over. Swallowed from the action list — it goes on the
+      // BAR, now, in yellow — and the turn leaves one line about it once it has ended (see the
+      // caller), so a fallback that lasted a single step can still be found afterwards.
+      if (line.startsWith(MODELFALLBACK_PREFIX)) {
+        const fb = parseModelFallback(line);
+        if (fb) {
+          turnFallback = fb;
+          setModelFallback(fb);
+        }
+        lastContentAt = Date.now();
+        continue;
+      }
       // A fence opening starts a fresh step's raw stream → reset the harvested Thought
       // so the blinking line doesn't carry last step's clause into this one.
       if (isFenceLine(line)) {
@@ -11625,7 +11683,7 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
           // says what it intends, then the actions it took appear under it.
           if (!REPL_VERBOSE && stepThought.trim() && !stepHasCode(stepThought)) {
             heldThought = stepThought; // #45: decided by the next line — see releaseHeldThought
-          } else if (printThoughtBlock(stepThought, onContent)) {
+          } else if (printThoughtBlock(stepThought, onContent, { gap: !lastWasBlank })) {
             lastWasBlank = false;
           }
           stepThought = "";
@@ -13355,6 +13413,7 @@ async function main() {
     if (line === "/agent-model") {
       await chooseAgentModel();
       agentMissing = false; // Task #14: an agent model was just chosen → clear its warning
+      setModelFallback(null); // #343: so is the stand-in a fallback warning named
       continue;
     }
     if (line === "/embed-model") {
@@ -13706,6 +13765,7 @@ async function main() {
       // #323: priced by the coder this turn STARTS on — a /model switch afterwards must not put
       // another model's price on it.
       const turnCoder = { url: activeCodingUrl(), model: activeCodingModelId() };
+      turnFallback = null; // #343: nothing has fallen back in THIS turn yet
       if (reattach) console.log(GUTTER + dim("following the turn that was running when the connection went…\n"));
       const turn = await runAgentTurn(history, reattach ? { attachJobId: reattach.jobId, ownJob: true } : {});
       // NOT SENT (licence block, or the token prompt declined): runAgentTurn already said so.
@@ -13720,6 +13780,15 @@ async function main() {
       // Detached: the agent keeps running on the worker, so the question is neither answered
       // nor stopped — leave it untagged, and say nothing contradicting "the job keeps running".
       if (detached) continue;
+      // #343: the bar after this turn — a fallback reported in it stays; an answered turn with
+      // none means the model works again and the warning goes; a failed or stopped turn proves
+      // nothing and leaves it.
+      const fellBack = turnFallback;
+      setModelFallback(fallbackAfterTurn({
+        current: modelFallback,
+        reportedThisTurn: fellBack,
+        answered: Boolean(answer) && !answer.startsWith(TURN_FAILED_PREFIX),
+      }));
       // Feed the bottom bar's token row (task #104). Assigned for EVERY turn — including one
       // that ended without an answer — so the row never shows a stale count from an older
       // turn. It replaces the print-once-per-turn footer that used to live here: the bar is
@@ -13749,6 +13818,7 @@ async function main() {
           failures: noteTaskFailure(taskLine, classifyTurnFailure(_failText)),
           authored: true,
         });
+        if (fellBack) printFallbackLine(fellBack);
       } else if (answer) {
         noteTaskSuccess();
         history.push({ role: "assistant", content: answer });
@@ -13792,6 +13862,9 @@ async function main() {
           // builder, so a change to the block's shape can no longer leave this behind.
           registerCopyBlock(block.rows, plain, 1);
         }
+        // #343: the turn's own record of the fallback, under its answer — the bar's row can be
+        // gone by the next turn, and the scrollback is where "which model wrote this?" is asked.
+        if (fellBack) printFallbackLine(fellBack);
       } else {
         // A turn that ended WITHOUT an answer (Ctrl+C cancel, or an abort/failure) must not
         // silently launch another turn. Any keystrokes the user typed DURING the dead turn
@@ -13841,6 +13914,12 @@ async function main() {
   process.exit(0);
 }
 
+/** One yellow line in the transcript saying which model stood in for which (task #343). */
+function printFallbackLine(fb) {
+  const rows = wrapBlock(fallbackHistoryLine(fb), GUTTER, process.stdout.columns || 80);
+  console.log(rows.map((r) => GUTTER + yellow(r)).join("\n") + "\n");
+}
+
 /**
  * Give the screen back to the shell with its prompt RIGHT UNDER the last output (#314). unpinBar()
  * parks the caret at the zone's top row, which is where the shell then printed its prompt: seven

package/model-fallback.mjs

@@ -0,0 +1,127 @@
+/**
+ * ANOTHER MODEL STOOD IN — and the screen says so (task #343).
+ *
+ * Reported: "When the coding model has an issue and it falls back to another model it should show
+ * a warning at the bottom bar in yellow." Until now a fallback was a line in the worker's log: the
+ * turn "worked", only with a model nobody picked, and worse code or an answer with no tools was
+ * the only evidence.
+ *
+ * The agent reports each fallback as one step — `__MODELFALLBACK__::{json}` (see MODEL_FALLBACK in
+ * gonext_agent_chat.py) — and this module turns it into the bar's row and the turn's history line.
+ * Pure: no terminal, no colour. The caller paints it yellow.
+ *
+ * WHAT IS A FALLBACK. Only "a different model did the work, or answered". A retry on the same
+ * model is not one, and a turn that failed outright (429 overloaded, 502) is not one either —
+ * nothing answered, and the failure notice already says that.
+ */
+
+export const MODELFALLBACK_PREFIX = "__MODELFALLBACK__::";
+
+const text = (v) => String(v ?? "").replace(/\s+/g, " ").trim();
+
+/** One step line → the fallback it reports, or null when it is not one (or is malformed). */
+export function parseModelFallback(line) {
+  const s = String(line ?? "");
+  if (!s.startsWith(MODELFALLBACK_PREFIX)) return null;
+  let body;
+  try {
+    body = JSON.parse(s.slice(MODELFALLBACK_PREFIX.length));
+  } catch {
+    return null;
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const from = text(body.from);
+  const to = text(body.to);
+  // Without the model that was used instead there is nothing true to say.
+  if (!from && !to) return null;
+  return {
+    role: body.role === "chat" ? "chat" : "coder",
+    from,
+    to,
+    reason: text(body.reason),
+    // Absent = the stand-in had tools / did answer: only an explicit false changes the wording.
+    tools: body.tools !== false,
+    answered: body.answered !== false,
+  };
+}
+
+const clipName = (name, max) => (name.length <= max ? name : name.slice(0, Math.max(1, max - 1)) + "…");
+
+/** A model name is never shortened below this — fewer characters no longer identify it. */
+const NAME_FLOOR = 5;
+
+/** The sentence's three parts, so the fitting below can shorten each on its own. */
+function parts(fb, { fromMax = Infinity, toMax = Infinity } = {}) {
+  const from = clipName(fb.from || (fb.role === "chat" ? "the chat model" : "the coding model"), fromMax);
+  const to = clipName(fb.to || "another model", toMax);
+  const same = Boolean(fb.from) && fb.from === fb.to;
+  const subject = fb.role === "chat" ? `chat model ${from}` : same ? from : `coder ${from}`;
+  // "unavailable": it never started (its server named no model). "failed": it was asked and broke.
+  const verb = fb.tools && fb.answered ? "unavailable" : "failed";
+  let outcome;
+  if (!fb.answered) outcome = same ? "and its plain reply failed too" : `${to} failed too`;
+  else if (fb.role === "chat") outcome = `${to} answered`;
+  else if (fb.tools) outcome = `coding with ${to}`;
+  else outcome = same ? "answered without tools" : `${to} answered without tools`;
+  return { subject, verb, outcome };
+}
+
+const join = ({ subject, verb, outcome }, reason) =>
+  `⚠ ${subject} ${verb}${reason ? ` (${reason})` : ""} — ${outcome}`;
+
+/**
+ * The bar's row for a fallback, FITTED to `width` columns (after the gutter): every bar row must
+ * stay one physical row (#109), and a row clipped mid-name hides the one thing it is for. So the
+ * REASON is shortened first, then dropped, and only then are the model names shortened — the
+ * longer one first.
+ */
+export function fallbackNotice(fb, { width = 80, gutter = "   " } = {}) {
+  if (!fb) return "";
+  const room = Math.max(20, (width || 80) - 1 - gutter.length);
+  const full = join(parts(fb), fb.reason);
+  if (full.length <= room) return full;
+  const bare = join(parts(fb), "");
+  if (fb.reason) {
+    const left = room - bare.length - 3; // " (" + ")"
+    if (left >= 6) return join(parts(fb), clipName(fb.reason, left));
+  }
+  if (bare.length <= room) return bare;
+  let fromMax = Math.max(NAME_FLOOR, (fb.from || "").length);
+  let toMax = Math.max(NAME_FLOOR, (fb.to || "").length);
+  while (join(parts(fb, { fromMax, toMax }), "").length > room && (fromMax > NAME_FLOOR || toMax > NAME_FLOOR)) {
+    if (fromMax >= toMax && fromMax > NAME_FLOOR) fromMax -= 1;
+    else toMax -= 1;
+  }
+  // A window too narrow even for that: cut the row rather than let it wrap onto a second one.
+  return clipName(join(parts(fb, { fromMax, toMax }), ""), room);
+}
+
+/** The line a fallback leaves in the turn's history — whole, wrapped by the caller. */
+export function fallbackHistoryLine(fb) {
+  return fb ? join(parts(fb), fb.reason) : "";
+}
+
+/**
+ * THE CODER WAS DROPPED FOR WANT OF A KEY (task #222): the API omits a coding backend whose API
+ * key is missing and the chat model does the coding. Nothing failed, so the agent has nothing to
+ * report — the terminal knows it from the payload and says it on the same row.
+ */
+export function keyMissingNotice({ coder = "", width = 80, gutter = "   " } = {}) {
+  const room = Math.max(20, (width || 80) - 1 - gutter.length);
+  const tail = " — coding with the chat model · ctrl+k";
+  const named = `⚠ no API key for coder ${text(coder)}${tail}`;
+  if (text(coder) && named.length <= room) return named;
+  const plain = `⚠ no API key for the coding model${tail}`;
+  if (plain.length <= room) return plain;
+  return clipName("⚠ no coder API key — on the chat model · ctrl+k", room);
+}
+
+/**
+ * What the bar shows after a turn ended. A fallback reported THIS turn stays; a turn that was
+ * answered with none reported means the model works again, so the warning goes; a turn that
+ * failed or was stopped proves nothing either way and leaves it as it was.
+ */
+export function fallbackAfterTurn({ current = null, reportedThisTurn = null, answered = false } = {}) {
+  if (reportedThisTurn) return reportedThisTurn;
+  return answered ? null : current;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.793",
+  "version": "1.0.795",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -21,6 +21,9 @@
     "postinstall": "node install-path.mjs",
     "test": "python3 -m unittest discover tests -v && node --test",
     "test:js": "node --test",
+    "test:ui": "node --test --test-concurrency=1 tests/ui/ui.test.mjs",
+    "ui:show": "node tests/ui/show.mjs",
+    "ui:accept": "UPDATE_UI=1 node --test --test-concurrency=1 tests/ui/ui.test.mjs",
     "test:keys": "node --test tests/key-choice-regression.test.mjs tests/coding-key-line.test.mjs tests/coding-key-picker.test.mjs tests/coding-key-prompt.test.mjs tests/coding-key-notice.test.mjs tests/coding-key-fallback-line.test.mjs tests/manage-coding-providers.test.mjs tests/add-coding-provider.test.mjs tests/coding-provider-setup.test.mjs",
     "deploy:local": "npm install -g .",
     "run": "gu-cli",
@@ -105,6 +108,7 @@
     "proxy-dispatcher.mjs",
     "model-doctor.mjs",
     "coding-key-prompt.mjs",
+    "model-fallback.mjs",
     "server-keys.mjs",
     "add-server.mjs",
     "powershell-alias.mjs",

package/terminal-layout.mjs

@@ -528,6 +528,21 @@ export function buildFooterRows({
   ];
 }
 
+/**
+ * The bytes that print a NEW thought block into the transcript (task #344): its painted rows,
+ * with ONE empty line above when the row above is not already blank (`gap`).
+ *
+ * A thought used to go directly under whatever was last printed. Under "✓ Command finished → …"
+ * it then read as that command's output, and under a bright "✗ Command failed → …" as its error
+ * text — but a thought is printed when its step's reasoning ends, before that step's tools
+ * report: it introduces what follows. Never two blanks: the caller passes gap=false when the
+ * last row is already empty. No blank BELOW either — the next bullet opens its own.
+ */
+export function thoughtPrintSeq(paintedRows, { gap = false } = {}) {
+  if (!paintedRows.length) return "";
+  return (gap ? "\n" : "") + paintedRows.join("\n") + "\n";
+}
+
 /**
  * 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