@tiens.nguyen/gu-cli 1.0.768 → 1.0.770

package/model-setup-ui.mjs

@@ -0,0 +1,114 @@
+/**
+ * THE WAY OUT OF THE MODEL QUESTIONS, and the key question that follows a typed server (#301).
+ *
+ * Reported: at "Agent + embedding server [https://ollama1.gomarsic.cc]:" there was no visible way
+ * to NOT choose. Enter takes the default server; a decline existed ("n", "no", "skip", "-") but no
+ * prompt said so, and one hint even claimed "press Enter with no address to skip", which was the
+ * opposite of what Enter does. Some people want no model setup at all and to load a saved preset.
+ *
+ * The decisions, agreed with the user (2026-09-29):
+ *   · ASK ONCE, UP FRONT — guided / load a preset / skip. Enter = guided, so today's flow is one
+ *     keypress away and unchanged.
+ *   · TWO WAYS OUT, NOT FIVE — "s" skips a step, Esc skips all model setup. The old words still
+ *     work, silently.
+ *   · FULL HINT ONCE, THEN SHORT — a hint under every prompt is noise by the fourth.
+ *   · A KEY ONLY WHEN ONE MAY BE NEEDED — a LAN Ollama box never needs one, a public https
+ *     address may, and a server that answers 401/403 certainly does.
+ *   · CONFIRM THE KEY WITHOUT SHOWING IT — a masked prompt gives no sign it took anything.
+ *
+ * PURE. Everything here is strings in, strings out, so the whole table is a test.
+ */
+import { hostLocality } from "./coding-provider-setup.mjs";
+
+/**
+ * What an Esc-aware prompt resolves to when Esc is pressed. A string no one can type (it starts
+ * with NUL), so it can travel through every `ask` that returns strings without a new type.
+ */
+export const SKIP_ALL = "\u0000skip-all";
+
+/** Esc, as readline reports it: name "escape" (meta:true on most terminals — accept either). */
+export function isEscapeKey(key) {
+  return Boolean(key) && (key.name === "escape" || (key.meta && key.sequence === "\x1b"));
+}
+
+/**
+ * One answer at a model prompt → what it means.
+ *   { kind: "all" }          Esc: skip all model setup
+ *   { kind: "skip" }         "s" (or the older n / no / skip / -): skip this step
+ *   { kind: "answer", text } anything else, including "" (= the default)
+ */
+export function readStepAnswer(raw) {
+  if (raw === SKIP_ALL) return { kind: "all" };
+  const text = String(raw ?? "").trim();
+  if (/^(s|n|no|skip|-)$/i.test(text)) return { kind: "skip" };
+  return { kind: "answer", text };
+}
+
+export const FULL_HINT = "Enter = use this · s = skip this step · Esc = skip all model setup";
+export const SHORT_HINT = "s skip · esc skip all";
+
+/** A hinter: the full hint the first time it is asked for, the short one after. */
+export function createHinter() {
+  let shown = false;
+  return () => {
+    if (shown) return SHORT_HINT;
+    shown = true;
+    return FULL_HINT;
+  };
+}
+
+/**
+ * Should typing THIS address be followed by "API key for <host>"?
+ *
+ * Only for an address that was TYPED (Enter on the default is today's path and stays one key),
+ * and only when the host is public: a LAN box (192.168.x, 10.x, *.local, a bare hostname,
+ * localhost) is an Ollama that takes no key, and asking there is a question with one answer.
+ * A server that answers 401/403 is asked regardless — see needsKeyAfterStatus.
+ */
+export function shouldAskKey({ typed, host }) {
+  if (!String(typed ?? "").trim()) return false;
+  return hostLocality(host) === "public";
+}
+
+/** The server refused to list its models without credentials. */
+export function needsKeyAfterStatus(status) {
+  return status === 401 || status === 403;
+}
+
+/** The last 4 characters, in the bar's own style — enough to tell keys apart, not to use one. */
+export function keyTail(key) {
+  const k = String(key ?? "").trim();
+  return k.length > 4 ? `····${k.slice(-4)}` : "····";
+}
+
+/** The line printed after the masked prompt, so the person knows whether it took anything. */
+export function keyConfirmation(host, key) {
+  return String(key ?? "").trim()
+    ? `✓ key saved for ${host} (${keyTail(key)})`
+    : `no key for ${host}`;
+}
+
+/**
+ * The up-front question. `presets` = how many saved presets there are: with none, option 2 still
+ * shows (so the feature is discoverable) but says how to make one instead of offering nothing.
+ */
+export function modelSetupMenu({ presets = 0 } = {}) {
+  return [
+    "How do you want to set up the models?",
+    "  1  Guided — pick the servers and models   (Enter)",
+    presets > 0
+      ? `  2  Load a saved preset   (${presets} saved)`
+      : "  2  Load a saved preset   (none saved yet — /save-preset makes one)",
+    "  3  Skip for now — set them later with /model",
+  ];
+}
+
+/** An answer to the up-front question → "guided" | "preset" | "skip", or null to ask again. */
+export function parseModelSetupChoice(raw) {
+  if (raw === SKIP_ALL) return "skip";
+  const t = String(raw ?? "").trim().toLowerCase();
+  if (t === "" || t === "1" || t === "guided" || t === "g") return "guided";
+  if (t === "2" || t === "preset" || t === "p") return "preset";
+  if (t === "3" || t === "s" || t === "skip" || t === "n" || t === "no" || t === "-") return "skip";
+  return null;
+}

package/ollama-setup.mjs

@@ -21,6 +21,14 @@
 import { isLikelyEmbedder } from "./agent-model-command.mjs";
 import { EMBED_CHOICES } from "./embed-model-command.mjs";
 import { isCancelWord } from "./coding-provider-setup.mjs";
+import {
+  SKIP_ALL,
+  createHinter,
+  keyConfirmation,
+  needsKeyAfterStatus,
+  readStepAnswer,
+  shouldAskKey,
+} from "./model-setup-ui.mjs";
 
 /** Ollama's native port, used when someone types a bare host or an IP with no port. */
 export const OLLAMA_DEFAULT_PORT = 11434;
@@ -649,21 +657,83 @@ export async function askOllamaSetup(
     // Injected so the tests can drive it; defaults to a real request with a short deadline,
     // because this runs while someone is waiting at a prompt.
     probeStatus = defaultProbeStatus,
+    // #301: the MASKED prompt for an API key. Without one no key is ever asked — a secret is
+    // never read through a prompt that echoes it.
+    askSecret = null,
+    // #301: the hint under each model prompt — full the first time, short after.
+    hint = createHinter(),
   } = {},
 ) {
+  // #301: every key typed for a server, by its HOSTNAME. "" = asked, left empty. Not by URL: the
+  // key is asked before listing, for the first reading of what was typed, and a different reading
+  // (another port or scheme) may be the one that answers.
+  const keys = new Map();
+  const SKIPPED = { skipped: true, keys: [] };
+  // #301: a step SKIPPED ON PURPOSE, as against a server that never answered. Nothing chosen
+  // because of a skip means "leave the models unset"; nothing chosen because nothing answered
+  // stays null, and the caller falls back to the shared box as it always has.
+  let declined = false;
+  // Dim, like the other guidance lines under a question; one line, above the prompt it explains.
+  const say = (h) => log(`    \x1b[2m${h}\x1b[0m`);
+
+  /**
+   * The key question for a TYPED address, before its models are listed (so a server that needs
+   * one can list them). Returns the key, "" for none, or SKIP_ALL.
+   */
+  const askKeyFor = async (host) => {
+    if (keys.has(host)) return keys.get(host); // same server for both roles → asked once
+    if (typeof askSecret !== "function") return "";
+    say(hint());
+    const raw = await askSecret(`  API key for ${host} (Enter for none): `);
+    if (raw === SKIP_ALL) return SKIP_ALL;
+    const key = String(raw ?? "").trim();
+    keys.set(host, key);
+    log(`  ${keyConfirmation(host, key)}`);
+    return key;
+  };
+
+  /**
+   * List the models of what was typed (or the default), asking for a key when the address is
+   * public or the server refuses without one. { ok, normalized, models } | { failed } | SKIP_ALL.
+   */
+  const loadServer = async (typed, fallbackUrl, reuse) => {
+    const raw = typed || fallbackUrl;
+    const first = urlCandidates(raw)[0];
+    if (reuse && first && reuse.normalized.url === first.url) return reuse;
+    let key = "";
+    if (first && shouldAskKey({ typed, host: first.host })) {
+      key = await askKeyFor(first.host);
+      if (key === SKIP_ALL) return SKIP_ALL;
+    }
+    let tried = await loadFirstThatAnswers(raw, fetchTags, log, key);
+    // A server that refused for want of credentials: ask now, whatever the address looked like,
+    // and list again with the key. Once — a second refusal is a wrong key, reported as such.
+    if (tried?.failed && needsKeyAfterStatus(tried.status) && !key && first) {
+      log(`  ${first.host} needs an API key to list its models.`);
+      keys.delete(first.host);
+      key = await askKeyFor(first.host);
+      if (key === SKIP_ALL) return SKIP_ALL;
+      if (key) tried = await loadFirstThatAnswers(raw, fetchTags, log, key);
+    }
+    return tried;
+  };
+
   // ---- SERVER 1: the agent model and the embedder -------------------------------------
   // These two are REQUIRED and not a free choice (see REQUIRED_AGENT_MODEL). A box without
   // them is "not ready" rather than "wrong": it may still be a perfectly good coder host, which
   // is why this refusal does not end the flow.
   let agent = null;
   for (let attempt = 0; attempt < attempts && !agent; attempt++) {
-    const typed = (await ask(`  Agent + embedding server [${displayUrl(defaultUrl)}]: `)).trim();
-    if (isDecline(typed)) break;
-    const tried = await loadFirstThatAnswers(typed || defaultUrl, fetchTags, log);
+    say(hint());
+    const a = readStepAnswer(await ask(`  Agent + embedding server [${displayUrl(defaultUrl)}]: `));
+    if (a.kind === "all") return SKIPPED;
+    if (a.kind === "skip") { declined = true; break; }
+    const tried = await loadServer(a.text, defaultUrl, null);
+    if (tried === SKIP_ALL) return SKIPPED;
     if (!tried || tried.failed) {
       // One explanation, the best one available: the provider message when we recognise the
       // address, otherwise the reachability advice we were going to give anyway.
-      const explained = await explainIfOpenAi(typed || defaultUrl, probeStatus, log, describeOpenAiAgent);
+      const explained = await explainIfOpenAi(a.text || defaultUrl, probeStatus, log, describeOpenAiAgent);
       if (!explained) for (const l of tried?.failed ?? []) log(`  ${l}`);
       continue;
     }
@@ -676,7 +746,9 @@ export async function askOllamaSetup(
     const need = checkRequired(models);
     if (!need.ok) {
       for (const l of describeNotReady(normalized.host, need.missing)) log(`  ${l}`);
-      log("  (or press Enter with no address to skip — you can set it later with /model)");
+      // #301: this used to tell people to press Enter to skip — but Enter takes the DEFAULT
+      // server. "s" is the skip.
+      log("  (or type s to skip — you can set it later with /model)");
       continue;
     }
     log(`  ✓ ${normalized.host} has the ${REQUIRED_AGENT_PREFIX} family and the embedder`);
@@ -690,18 +762,21 @@ export async function askOllamaSetup(
   const coderDefault = agent?.normalized?.url ?? defaultUrl;
   let coder = null;
   for (let attempt = 0; attempt < attempts && !coder; attempt++) {
-    const typed = (await ask(`  Coding-model server [${displayUrl(coderDefault)}]: `)).trim();
-    if (isDecline(typed)) break;
+    say(hint());
+    const a = readStepAnswer(await ask(`  Coding-model server [${displayUrl(coderDefault)}]: `));
+    if (a.kind === "all") return SKIPPED;
+    if (a.kind === "skip") { declined = true; break; }
     // Same box as the agent server → reuse the list we already have rather than fetching twice.
-    const same = normalizeOllamaUrl(typed || coderDefault);
+    const same = normalizeOllamaUrl(a.text || coderDefault);
     const tried =
       agent && same && same.url === agent.normalized.url
         ? { normalized: same, models: agent.models }
-        : await loadFirstThatAnswers(typed || coderDefault, fetchTags, log);
+        : await loadServer(a.text, coderDefault, agent);
+    if (tried === SKIP_ALL) return SKIPPED;
     if (!tried || tried.failed) {
       // One explanation, the best one available: the provider message when we recognise the
       // address, otherwise the reachability advice we were going to give anyway.
-      const explained = await explainIfOpenAi(typed || coderDefault, probeStatus, log, describeOpenAiCoder);
+      const explained = await explainIfOpenAi(a.text || coderDefault, probeStatus, log, describeOpenAiCoder);
       if (!explained) for (const l of tried?.failed ?? []) log(`  ${l}`);
       continue;
     }
@@ -718,7 +793,7 @@ export async function askOllamaSetup(
   // A real answer, not a failure. The machine finishes setup unconfigured, the bar shows the
   // roles as unset, and the first question says so instead of hanging — which is the entire
   // reason declining is allowed to be this easy.
-  if (!agent && !coder) return null;
+  if (!agent && !coder) return declined ? SKIPPED : null;
 
   // ---- PICK THE MODELS -----------------------------------------------------------------
   // THE AGENT IS CHOSEN, not assumed (user, 2026-09-06). The gate above proved the family is
@@ -729,7 +804,6 @@ export async function askOllamaSetup(
   // Seed the embedder the box ACTUALLY has: the shipped default when present, else whichever
   // accepted embedder passed the gate — a qwen3-embedding-only box must not be told it now
   // embeds with a model it never had.
-  const embed = agent ? defaultEmbedModel(agent.models) || REQUIRED_EMBED_MODEL : null;
   let chat = "";
   if (agent) {
     const cands = agentCandidates(agent.models);
@@ -741,13 +815,18 @@ export async function askOllamaSetup(
       log("  AGENT model — routes every turn and writes the plain replies");
       for (const row of renderModelMenu(cands, { defaultModel: agentDefault, formatSize })) log(row);
       for (let t = 0; t < attempts && !chat; t++) {
-        const answer = await ask(`  agent [${agentDefault}]: `);
-        chat = parseMenuChoice(answer, cands, agentDefault) ?? "";
+        say(hint());
+        const a = readStepAnswer(await ask(`  agent [${agentDefault}]: `));
+        if (a.kind === "all") return SKIPPED;
+        // #301: "s" here skips the AGENT role — its server was chosen, its model is not.
+        if (a.kind === "skip") { agent = null; break; }
+        chat = parseMenuChoice(a.text, cands, agentDefault) ?? "";
         if (!chat) log(`  no model called that — type its number, or Enter for ${agentDefault}`);
       }
-      chat = chat || agentDefault;
+      if (agent) chat = chat || agentDefault;
     }
   }
+  const embed = agent ? defaultEmbedModel(agent.models) || REQUIRED_EMBED_MODEL : null;
   let code = "";
   let extras = [];
   if (coder) {
@@ -756,20 +835,37 @@ export async function askOllamaSetup(
     log("  CODING model — writes the code; worth waiting for");
     for (const row of renderModelMenu(coder.models, { defaultModel: roles.code, formatSize })) log(row);
     for (let t = 0; t < attempts && !code; t++) {
-      const answer = await ask(`  code [${roles.code}]: `);
-      code = parseMenuChoice(answer, coder.models, roles.code) ?? "";
+      say(hint());
+      const a = readStepAnswer(await ask(`  code [${roles.code}]: `));
+      if (a.kind === "all") return SKIPPED;
+      if (a.kind === "skip") { coder = null; break; }
+      code = parseMenuChoice(a.text, coder.models, roles.code) ?? "";
       if (!code) log(`  no model called that — type its number, or Enter for ${roles.code}`);
     }
-    code = code || roles.code;
+    if (coder) code = code || roles.code;
 
-    const rest = coder.models.filter((m) => !isLikelyEmbedder(m) && m.model !== code);
+    const rest = coder ? coder.models.filter((m) => !isLikelyEmbedder(m) && m.model !== code) : [];
     if (rest.length) {
       log("");
       log("  Also offer in /model?  (numbers separated by commas, or Enter for none)");
       for (const row of renderModelMenu(rest, { formatSize })) log(row);
-      extras = parseMultiChoice(await ask("  also: "), rest);
+      say(hint());
+      const a = readStepAnswer(await ask("  also: "));
+      if (a.kind === "all") return SKIPPED;
+      extras = a.kind === "skip" ? [] : parseMultiChoice(a.text, rest);
     }
   }
+  // Both roles skipped at the model menus: as much a decision as skipping both servers.
+  if (!agent && !coder) return SKIPPED;
+
+  // #301: the keys typed, only for the servers actually used, never the empty ones — each under
+  // the URL that ANSWERED, which is the one the settings rows are written with.
+  const used = [agent?.normalized, coder?.normalized].filter(Boolean);
+  const keyList = [];
+  for (const [host, key] of keys) {
+    const n = key && used.find((u) => u.host === host);
+    if (n && !keyList.some((k) => k.url === n.url)) keyList.push({ url: n.url, key });
+  }
 
   // HALF-CONFIGURED IS A REAL STATE and must be representable. Someone with an agent box but no
   // coder yet, or a coder but no agent box, has made progress worth keeping — forcing both or
@@ -786,6 +882,7 @@ export async function askOllamaSetup(
     ...(embed ? { embed } : {}),
     altCoders: (extras ?? []).filter((n) => n !== code),
     ready: Boolean(agent && coder),
+    ...(keyList.length ? { keys: keyList } : {}),
   };
 }
 
@@ -848,7 +945,7 @@ async function explainIfOpenAi(raw, probeStatus, log, describe) {
   return true;
 }
 
-async function loadFirstThatAnswers(raw, fetchTags, log) {
+async function loadFirstThatAnswers(raw, fetchTags, log, apiKey = "") {
   const candidates = urlCandidates(raw);
   if (!candidates.length) {
     return { failed: ["that is not a server address — try 192.168.1.40, ollama.local, or a full URL"] };
@@ -856,7 +953,10 @@ async function loadFirstThatAnswers(raw, fetchTags, log) {
   let last = null;
   for (const normalized of candidates) {
     try {
-      const models = await fetchTags(tagsUrlFor(normalized));
+      // #301: the key goes along only when there is one — a keyless call stays byte-identical.
+      const models = apiKey
+        ? await fetchTags(tagsUrlFor(normalized), { apiKey })
+        : await fetchTags(tagsUrlFor(normalized));
       // Say WHICH reading answered, but only when we had to guess — otherwise it is noise
       // repeating what the user just typed.
       if (candidates.length > 1) log(`  using ${displayUrl(normalized.url)}`);
@@ -869,6 +969,11 @@ async function loadFirstThatAnswers(raw, fetchTags, log) {
   // NOT PRINTED HERE ANY MORE. "check that Ollama is running there" is exactly the wrong thing
   // to say about a correct address for a hosted provider, and the caller is the only one that
   // knows whether it found a better explanation. It prints one message or the other, never both.
-  return { failed: [`could not reach ${candidates[0].host}: ${networkReason(last)}`,
+  // #301: an HTTP status (401/403 = needs a key) travels with the failure so the caller can ask.
+  const status = Number(last?.status ?? last?.httpStatus) || 0;
+  if (needsKeyAfterStatus(status)) {
+    return { status, failed: [`${candidates[0].host} refused the request (HTTP ${status}) — ${apiKey ? "that key was not accepted" : "it needs an API key"}.`] };
+  }
+  return { status, failed: [`could not reach ${candidates[0].host}: ${networkReason(last)}`,
                     "check the address, or that Ollama is running there and listening on the network."] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.768",
+  "version": "1.0.770",
   "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",
@@ -50,6 +50,10 @@
     "gu-cli.mjs",
     "gu-repl.mjs",
     "step-tokens.mjs",
+    "model-setup-ui.mjs",
+    "setup-prompts.mjs",
+    "turn-stop.mjs",
+    "workspace-revert.mjs",
     "terminal-hover.mjs",
     "terminal-layout.mjs",
     "terminal-viewport.mjs",

package/setup-prompts.mjs

@@ -0,0 +1,82 @@
+/**
+ * THE FIRST-RUN PROMPTS THAT PLAIN rl.question CANNOT BE (#301, #300).
+ *
+ * First-run setup runs before the REPL exists, on its own readline (gu-repl.mjs `rl0`), and every
+ * question there was `rl0.question` — which echoes. Two things need more than that:
+ *
+ *   · ESC. The model questions offer "Esc = skip all model setup". Esc submits nothing in readline,
+ *     so the pending question is cancelled through its AbortSignal and resolved with SKIP_ALL.
+ *   · A SECRET. An API key, or the MongoDB password (#300), must never reach the screen or the
+ *     scrollback. Readline's echo and line refresh are muted for the question, one "•" per
+ *     character is drawn instead (the only proof a keystroke registered), and the answer is taken
+ *     back out of readline's history — which keeps every submitted line, so the secret would
+ *     otherwise come back in plain text on the next press of Up.
+ *
+ * The REPL has its own askSecret with the same guarantees (task #127/#191); this is the version for
+ * the one stretch of the program that runs before it.
+ */
+import { SKIP_ALL, isEscapeKey } from "./model-setup-ui.mjs";
+
+/**
+ * One question on `rl`. Options: `secret` (mask + keep out of history), `esc` (Esc → SKIP_ALL).
+ * `style` decorates the label (the accent colour). Resolves with the answer string, or SKIP_ALL.
+ */
+export function askOn(rl, q, { secret = false, esc = false, style = (s) => s, input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    const shown = style(q);
+    const ac = new AbortController();
+    const origWrite = rl._writeToOutput;
+    const origRefresh = rl._refreshLine;
+    let done = false;
+
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      input.removeListener?.("keypress", onKey);
+      if (secret) {
+        rl._writeToOutput = origWrite;
+        rl._refreshLine = origRefresh;
+        if (Array.isArray(rl.history) && value && rl.history[0] === value) rl.history.shift();
+        rl.historyIndex = -1;
+      }
+      // A muted Enter printed no newline, and an Esc left the caret on the prompt's row.
+      if (secret || value === SKIP_ALL) output.write("\n");
+      resolve(value);
+    };
+
+    // Runs AFTER readline's own keypress handler (registered when rl was created), so rl.line is
+    // already the updated text when the bullets are drawn.
+    function onKey(_s, key) {
+      if (done) return;
+      if (esc && isEscapeKey(key)) {
+        ac.abort();
+        // The cancelled question leaves what was typed in rl.line; the next question must not
+        // start with it.
+        rl.line = "";
+        rl.cursor = 0;
+        finish(SKIP_ALL);
+        return;
+      }
+      if (secret && output.isTTY) {
+        output.write(`\r\x1b[2K${shown}${"•".repeat(String(rl.line ?? "").length)}`);
+      }
+    }
+
+    input.on?.("keypress", onKey);
+    // question() draws the label synchronously — mute only AFTER, or the label is muted too.
+    rl.question(shown, { signal: ac.signal }, (a) => finish(String(a ?? "")));
+    if (secret) {
+      rl._writeToOutput = () => {};
+      rl._refreshLine = () => {};
+    }
+  });
+}
+
+/** The three readers setup takes: plain, Esc-aware (model questions), masked (keys, passwords). */
+export function setupPrompts(rl, { style = (s) => s, input = process.stdin, output = process.stdout } = {}) {
+  return {
+    ask: (q) => askOn(rl, q, { style, input, output }),
+    askStep: (q) => askOn(rl, q, { esc: true, style, input, output }),
+    askSecret: (q) => askOn(rl, q, { secret: true, esc: true, style, input, output }),
+  };
+}

package/terminal-layout.mjs

@@ -468,6 +468,27 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
  * `identity` is optional so callers that have nothing to put there (and the tests that predate
  * it) keep producing the same rows as before.
  */
+/**
+ * HOW TO PASTE, for this platform (issue #67). Two different things share the word: TEXT is pasted
+ * by the terminal app (gu only sees the result), an IMAGE by gu's own keys (#284).
+ *
+ *   macOS    text ⌘V            image ctrl+v — a terminal's ⌘V sends nothing for an image
+ *   Windows  text ctrl+v        image alt+v  — Windows Terminal keeps ctrl+v for itself
+ *   Linux    text ctrl+shift+v  image ctrl+v
+ *
+ * The image half only when the coder can take one (a Claude coder); offering a key that then
+ * answers "images need a Claude coder" would be a hint that leads to a warning.
+ */
+export function pasteHint({ platform = process.platform, images = false } = {}) {
+  const text = platform === "darwin" ? "⌘V" : platform === "win32" ? "ctrl+v" : "ctrl+shift+v";
+  if (!images) return `${text} to paste`;
+  const image = platform === "win32" ? "alt+v" : "ctrl+v";
+  return `${text} paste · ${image} image`;
+}
+
+/** At least this many spaces between the mode text and the hint, or the hint is left out. */
+const HINT_MIN_GAP = 3;
+
 export function buildFooterRows({
   width,
   gutter = "   ",
@@ -475,16 +496,25 @@ export function buildFooterRows({
   identity = "",
   token = "",
   mode = "",
+  // Right-aligned on the mode row (issue #67), dim. DROPPED WHOLE when it does not fit: every
+  // footer row must stay one physical row (#109/#132/#138), and half a key name is worse than none.
+  modeHint = "",
   notice = "",
   missing = "",
 }) {
   const w = Math.max(20, width || 80);
+  const modeLeft = gutter + mode;
+  const hintGap = modeHint ? w - 1 - visibleLen(modeLeft) - visibleLen(modeHint) : -1;
+  const modeRow =
+    hintGap >= HINT_MIN_GAP
+      ? modeLeft + " ".repeat(hintGap) + dim(modeHint)
+      : clipVisible(modeLeft, w - 1);
   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),
+    modeRow,
     // A passing notice (the image-paste warning, #54) gets its OWN row, under the mode row — it
     // used to be appended to that row and was clipped at the right edge ("…pick one with /mo").
     // Present only while it shows; paintBar re-cuts the frozen zone when the count changes.

package/turn-stop.mjs

@@ -0,0 +1,78 @@
+/**
+ * AFTER Ctrl+C STOPS A TURN — the question goes back in the input, and what the turn changed is
+ * named (task #302). Pure helpers; gu-repl.mjs does the drawing.
+ *
+ * Asked for: "for a couple of seconds the thinking is still in process and the user thinks again
+ * and wants to change the question" — as Claude Code does. The screen keeps what the turn printed
+ * (the record of what it did); files are NOT reverted by themselves (part of the work may be
+ * wanted, and a command that ran cannot be undone) — /undo offers that as a choice.
+ */
+
+const PASTE_TOKEN_RE = /\[Pasted text #\d+(?: \+\d+ lines)?\]/g;
+const IMAGE_TOKEN_RE = /\[Image #\d+\]/g;
+
+/**
+ * What was TYPED, captured at the moment the line is submitted — before the pasted blocks and the
+ * images are expanded for the model and their stores are cleared. Only the entries whose
+ * placeholder is actually in the line are kept.
+ */
+export function snapshotInput(raw, { pastes = new Map(), images = new Map() } = {}) {
+  const text = String(raw ?? "");
+  const keep = (re, store) => {
+    const present = new Set(text.match(re) ?? []);
+    return [...store].filter(([token]) => present.has(token));
+  };
+  return { raw: text, pastes: keep(PASTE_TOKEN_RE, pastes), images: keep(IMAGE_TOKEN_RE, images) };
+}
+
+/**
+ * Put a snapshot back: its placeholders' payloads return to the stores, and the typed text is
+ * returned for the input line. Nothing is renumbered — the text is shown exactly as it was.
+ */
+export function restoreInput(snap, { pasteStore, imageStore } = {}) {
+  if (!snap) return "";
+  for (const [token, text] of snap.pastes ?? []) pasteStore?.set(token, text);
+  for (const [token, path] of snap.images ?? []) imageStore?.restore?.(token, path);
+  return String(snap.raw ?? "");
+}
+
+/**
+ * The restored question was EDITED and sent: that is a change of mind, so the abandoned version
+ * must not stay in history beside the new one (the model would take both as asks). Only when the
+ * last entry IS that stopped question; returns whether it replaced it.
+ *
+ * Sending it UNCHANGED is not handled here — the existing pending-question path re-runs it. And a
+ * question cleared and replaced by something else keeps its "still stands" tag (task #247).
+ */
+export function replaceStoppedQuestion(history, oldTask, newTask) {
+  const last = Array.isArray(history) ? history[history.length - 1] : null;
+  const was = String(oldTask ?? "").trim();
+  const now = String(newTask ?? "").trim();
+  if (!last || last.role !== "user" || !last.status || !was || !now || was === now) return false;
+  if (String(last.content ?? "").trim() !== was) return false;
+  last.content = now;
+  delete last.status;
+  return true;
+}
+
+/** Short relative names for the stop note: the last two path parts. */
+function shortPath(p) {
+  const parts = String(p ?? "").split(/[\\/]/).filter(Boolean);
+  return parts.slice(-2).join("/") || String(p ?? "");
+}
+
+/**
+ * The lines under a stopped turn. `files` = the paths the turn changed (from its run's manifest),
+ * `command` = the command it was in the middle of, if any.
+ */
+export function stopNoteLines({ files = [], command = "", restored = true } = {}) {
+  const out = [];
+  if (command) out.push(`stopped while running \`${command}\` — it may be incomplete; run it again if you need it`);
+  const uniq = [...new Set(files)];
+  if (uniq.length) {
+    const shown = uniq.slice(0, 3).map(shortPath).join(", ") + (uniq.length > 3 ? ` +${uniq.length - 3} more` : "");
+    out.push(`this turn changed ${uniq.length} file${uniq.length === 1 ? "" : "s"}: ${shown} — /undo puts ${uniq.length === 1 ? "it" : "them"} back`);
+  }
+  if (restored) out.push("your question is back in the input — edit it and press Enter, or Ctrl+C to clear it");
+  return out;
+}