@tiens.nguyen/gu-cli 1.0.722 → 1.0.724

package/add-server.mjs

@@ -14,7 +14,10 @@
  * server kind ("dialect": an Ollama's /api/tags vs an OpenAI-compatible /v1/models) lives in
  * serverTarget() and listRequest().
  */
-import { defaultProviderUrl, ensureV1Root, hostLocality, normalizeProviderUrl, parseProviderModels, MAX_MODELS_PER_SERVER } from "./coding-provider-setup.mjs";
+import { defaultProviderUrl, ensureV1Root, hostLocality, isCancelWord, normalizeProviderUrl, parseProviderModels, MAX_MODELS_PER_SERVER } from "./coding-provider-setup.mjs";
+
+// Re-exported: the add-server screen's own name for the rule every URL prompt shares.
+export { isCancelWord };
 import { agentModelsFromProvider, isLikelyEmbedder, ollamaAgentDefault, ollamaAgentUrl, parseOllamaTags } from "./agent-model-command.mjs";
 
 /**
@@ -76,6 +79,9 @@ export function serverRole(role) {
 export function serverTarget(dialect, typed) {
   const raw = String(typed ?? "").trim();
   if (!raw) return { ok: false, why: "empty" };
+  // A command word is never a server. Reported: /embed-model showed "on exit" — "exit" typed at
+  // the URL prompt had been saved as http://exit, a perfectly valid-looking single-label host.
+  if (isCancelWord(raw)) return { ok: false, why: "a command, not a server" };
   if (/^[a-z][a-z0-9+.-]*:\/\/[^/]*@/i.test(raw)) {
     return { ok: false, why: "carrying credentials — keys go in the key prompt" };
   }

package/client-expert-api.mjs

@@ -20,6 +20,7 @@
 import { createRequire } from "node:module";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { spawnSurviving, pidOnPort } from "./platform-tools.mjs";
+import { DEFAULT_API_BASE as HOSTED_API_BASE } from "./device-login.mjs";
 import { spawn } from "node:child_process";
 import { writeFile, mkdir, readFile, access } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -64,6 +65,8 @@ export function apiEnv({
   mongoUri = LOCAL_MONGO_URI,
   dbName = LOCAL_DB_NAME,
   base = {},
+  hostedBase = hostedApiBase(),
+  home = homedir(),
 } = {}) {
   return {
     ...base,
@@ -71,9 +74,20 @@ export function apiEnv({
     DATA_BACKEND: "mongo",
     MONGODB_URI: mongoUri,
     MONGODB_DB: dbName,
+    // THE AGENT'S PROMPT SCAFFOLD IS NOT ON THIS MACHINE (task #246). The local API forwards the
+    // worker's request to the hosted API, signed with this machine's gu CLI token, and keeps the
+    // answer in memory only — so private mode needs internet for a turn, and says so when it has
+    // none. No local copy exists to fall back to, by design.
+    PROMPT_SCAFFOLD_UPSTREAM: hostedBase,
+    GU_CLI_TOKEN_FILE: join(home, ".gonext", "cli-token.json"),
   };
 }
 
+/** The hosted gu API — where a Client Expert machine's token is renewed and its scaffold fetched. */
+export function hostedApiBase(env = process.env) {
+  return String(env.GU_TOKEN_API_BASE ?? "").trim() || HOSTED_API_BASE;
+}
+
 /**
  * Is this health body a usable API?
  *

package/coding-provider-setup.mjs

@@ -84,9 +84,19 @@ export function hostLocality(hostname) {
  * addresses" wholesale is meaningless — but 169.254.169.254 and metadata.google.internal are
  * never a model server, and they are what an SSRF probe asks for first.
  */
+/**
+ * Words that mean "get me out of here" at a prompt, not a hostname. Every URL prompt refuses them
+ * as a server. Reported: /embed-model showed "on exit" — "exit" typed at a URL prompt had been
+ * saved as http://exit, a perfectly valid-looking single-label host.
+ */
+export function isCancelWord(typed) {
+  return /^(no|n|skip|-|exit|quit|q|cancel|back|esc)$/i.test(String(typed ?? "").trim());
+}
+
 export function normalizeProviderUrl(raw) {
   const text = String(raw ?? "").trim();
   if (!text) return { ok: false, why: "empty" };
+  if (isCancelWord(text)) return { ok: false, why: "command" };
   if (/\s/.test(text)) return { ok: false, why: "spaces" };
 
   const hadScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text);
@@ -159,6 +169,8 @@ export function describeUrlProblem(why, typed = "") {
       return ["type the provider's base URL, e.g. https://api.openai.com/v1"];
     case "spaces":
       return ["that has a space in it — a URL cannot"];
+    case "command":
+      return ["that is a command, not a server — press Esc to cancel, or type the server's URL"];
     case "scheme":
       return ["only http:// and https:// addresses work here"];
     case "credentials":

package/gonext_agent_chat.py

@@ -1308,7 +1308,7 @@ def _render_numbered_tool_list(tools) -> str:
     when RAG or a workspace is enabled/disabled) and the numbering is always exactly
     correct, unlike the old manually-incremented counter it replaces. Kept intentionally
     terse — first docstring line only, bare arg names — since the system prompt's own
-    `tool.to_code_prompt()` rendering (see _COMPACT_CODE_SYSTEM_PROMPT) already shows the
+    `tool.to_code_prompt()` rendering (in the API-served prompt scaffold) already shows the
     full typed signature on every model call; this is just a quick-reference index."""
     lines = []
     for i, t in enumerate(tools, 1):
@@ -1722,81 +1722,73 @@ def _looks_like_scratchpad(stripped: str) -> bool:
     return len(_DELIBERATION_RE.findall(stripped)) >= 3
 
 
-# Compact replacement for smolagents' default CodeAgent system prompt. The stock template
-# is ~9.9k chars, dominated by ~6k chars of GENERIC few-shot examples (image captions,
-# Wikipedia, etc.) that are irrelevant to our HTTP/file tools and cost real prompt-eval
-# time every step on a slow coding model. This keeps everything FUNCTIONALLY required —
-# the Thought→Code→Observation loop, the code-blob format + closing tag, the {{tools}}
-# rendering (so exact signatures survive), authorized imports, custom_instructions — plus
-# ONE short worked example, and trims the rest. Jinja vars must match the stock template.
-_COMPACT_CODE_SYSTEM_PROMPT = (
-    "You are an expert assistant who solves the task by writing Python code that calls "
-    "tools. You work in a loop of Thought → Code → Observation.\n\n"
-    "At EACH step:\n"
-    "- Write one 'Thought:' line: what you'll do and which tool.\n"
-    "- Then a code block that OPENS with {{code_block_opening_tag}} and CLOSES with "
-    "{{code_block_closing_tag}}, containing simple Python that calls the tools you need "
-    "and print()s what you want to see.\n"
-    "- BATCH INDEPENDENT CALLS INTO ONE BLOCK. If you already know the arguments for "
-    "several lookups, do them in ONE step and print each under a header — up to about 8 at "
-    "a time, then continue in the next step. Split into separate steps only when an "
-    "argument DEPENDS on a previous Observation.\n"
-    "- Batch LOOKUPS, not changes. If a line raises, the lines after it never run — so "
-    "keep edits, file writes and commands to one per block.\n"
-    "- You then receive the 'Observation:'. Use it to decide the next step. When you have "
-    "the answer, call final_answer(answer) inside a code block.\n\n"
-    "Example — arguments already known, so ONE step does all of it:\n"
-    "Thought: I need these three files before I can change anything.\n"
-    "{{code_block_opening_tag}}\n"
-    'for p in ["src/main.js", "src/api.js", "test/main.test.js"]:\n'
-    '    print("=====", p)\n'
-    "    print(read_file_lines(path=p))\n"
-    "{{code_block_closing_tag}}\n"
-    "Observation: \"===== src/main.js … ===== src/api.js … \"\n\n"
-    "Example — the next call DEPENDS on this result, so it is a separate step:\n"
-    "Thought: I'll read the page the user gave.\n"
-    "{{code_block_opening_tag}}\n"
-    'text = fetch_url("https://example.com")\n'
-    "print(text)\n"
-    "{{code_block_closing_tag}}\n"
-    "Observation: \"Example Domain … \"\n"
-    "Thought: I have the content, so I'll answer.\n"
-    "{{code_block_opening_tag}}\n"
-    'final_answer("The page is Example Domain, a placeholder site.")\n'
-    "{{code_block_closing_tag}}\n\n"
-    "You have access to these tools — call them as plain Python functions with the exact "
-    "signatures shown:\n"
-    "{{code_block_opening_tag}}\n"
-    "{%- for tool in tools.values() %}\n"
-    "{{ tool.to_code_prompt() }}\n"
-    "{% endfor %}\n"
-    "{{code_block_closing_tag}}\n"
-    "{%- if managed_agents and managed_agents.values() | list %}\n"
-    "You can also delegate to team members by calling them like a tool with a 'task' "
-    "string argument:\n"
-    "{{code_block_opening_tag}}\n"
-    "{%- for agent in managed_agents.values() %}\n"
-    "def {{ agent.name }}(task: str) -> str:\n"
-    '    """{{ agent.description }}"""\n'
-    "{% endfor %}\n"
-    "{{code_block_closing_tag}}\n"
-    "{%- endif %}\n\n"
-    "Rules:\n"
-    "1. ALWAYS write a 'Thought:' line, then a code block opening with "
-    "{{code_block_opening_tag}} and closing with {{code_block_closing_tag}} — or you fail.\n"
-    "2. Pass tool arguments directly: calculate(expression=\"2+2\"), NOT as a dict.\n"
-    "3. Use only variables you have defined; state persists between steps.\n"
-    "4. Never re-run a tool call with the exact same parameters.\n"
-    "5. Don't name a variable after a tool (e.g. 'final_answer').\n"
-    "6. Imports are allowed ONLY from: {{authorized_imports}}\n"
-    "7. Don't give up — you are in charge of solving the task.\n"
-    "{%- if custom_instructions %}\n"
-    "{{custom_instructions}}\n"
-    "{%- endif %}\n\n"
-    "Now Begin!"
+# THE CODE-AGENT SCAFFOLD IS NOT IN THIS FILE (task #246). The fixed system prompt — the
+# Thought → Code → Observation rules that replace smolagents' stock ~9.9k-char template — is served
+# by the API (GET /api/worker/prompt-scaffold) and never shipped in the gu package. The worker
+# fetches it once per job; if it cannot, the turn stops with the reason. There is deliberately NO
+# local copy to fall back to: the point is that the text is not on the user's machine.
+#
+# What a scaffold must keep, checked again here after the API checked it: without the code-block
+# tags the model's code is never parsed, without the tool loop no signature is shown, without
+# custom_instructions the per-turn hint is dropped — each fails silently, every turn.
+_SCAFFOLD_REQUIRED = (
+    "{{code_block_opening_tag}}",
+    "{{code_block_closing_tag}}",
+    "tool.to_code_prompt()",
+    "{{authorized_imports}}",
+    "custom_instructions",
 )
 
 
+# The version of the scaffold this job is running — for the log and the prompt record, never the text.
+_PROMPT_SCAFFOLD_VERSION = {"v": None}
+
+
+def _fetch_prompt_scaffold(api_base: str, worker_key: str, name: str = "code-agent"):
+    """The agent's prompt scaffold from the API → (template, version).
+
+    Raises _AgentConfigError with a message the USER reads (it becomes a TURN_FAILED line) when
+    the API cannot be asked, refuses, or sends something unusable. Never returns a default. The
+    message never contains the template itself."""
+    base = (api_base or "").rstrip("/")
+    if not base or not worker_key:
+        raise _AgentConfigError(
+            "The agent's prompt could not be loaded: this worker has no API address or key.")
+    from urllib.parse import urlencode
+    req = urllib.request.Request(
+        f"{base}/api/worker/prompt-scaffold?{urlencode({'name': name})}",
+        headers={"X-Worker-Key": worker_key}, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=15, context=_ssl_context()) as resp:
+            data = json.loads(resp.read().decode("utf-8", "replace") or "{}")
+    except urllib.error.HTTPError as he:
+        detail = ""
+        try:
+            detail = str(json.loads(he.read().decode("utf-8", "replace") or "{}").get("error") or "")
+        except Exception:  # noqa: BLE001
+            pass
+        if he.code == 404 and not detail:
+            detail = ("this API is older than the prompt service — update it "
+                      "(`gu api upgrade` on a private-mode machine)")
+        raise _AgentConfigError(
+            f"The agent's prompt could not be loaded (HTTP {he.code})"
+            + (f": {detail}" if detail else ".")) from None
+    except Exception as e:  # noqa: BLE001
+        raise _AgentConfigError(
+            f"The agent's prompt could not be loaded — the API at {base} did not answer "
+            f"({type(e).__name__}). Check that it is running and reachable.") from None
+    template = data.get("template") if isinstance(data, dict) else None
+    version = data.get("version") if isinstance(data, dict) else None
+    if not isinstance(template, str) or not template.strip():
+        raise _AgentConfigError("The agent's prompt could not be loaded: the API sent an empty one.")
+    missing = [p for p in _SCAFFOLD_REQUIRED if p not in template]
+    if missing:
+        raise _AgentConfigError(
+            "The agent's prompt could not be used: it is missing " + ", ".join(missing) + ".")
+    _PROMPT_SCAFFOLD_VERSION["v"] = version
+    return template, version
+
+
 def _usage_field(obj, name):
     """One field off a usage object that may be an attribute bag OR a plain dict — both
     shapes come back from OpenAI-compatible clients depending on the transport."""
@@ -2300,6 +2292,14 @@ def _render_prompt(messages, max_chars: int = 400_000) -> str:
     out = []
     for m in messages or []:
         role, text = _message_role_text(m)
+        if role == "system":
+            # THE SCAFFOLD IS NEVER RECORDED (task #246). The system message IS the API-served
+            # prompt scaffold (rendered with the tool signatures), and this record is stored by
+            # the API and shown on the token-usage page — so it would hand the hidden text to
+            # anyone who opens a step. Its size stays visible, the text does not.
+            v = _PROMPT_SCAFFOLD_VERSION["v"]
+            text = (f"[prompt scaffold{f' v{v}' if v is not None else ''} with the tool signatures — "
+                    f"{len(text)} characters, not shown]")
         out.append(f"───── {role or 'message'} ─────\n{text}")
     rendered = "\n\n".join(out)
     if len(rendered) > max_chars:
@@ -12111,21 +12111,25 @@ def run_agent_chat(cfg):
             agent_kwargs["additional_authorized_imports"] = [
                 "json", "base64", "urllib", "urllib.request", "urllib.error"
             ]
-            # Trim smolagents' ~6k-char generic few-shot examples from the system prompt
-            # (they dominate prompt-eval on a slow coding model) while keeping the tool
-            # rendering + format rules intact. Load the stock templates and swap only the
-            # system_prompt; fall back to the default on any error.
+            # THE SYSTEM PROMPT IS THE API'S SCAFFOLD (task #246): the stock templates are loaded
+            # for everything else (planning, final-answer, managed agents) and ONLY system_prompt
+            # is swapped. No fallback in either direction — a missing scaffold, or stock
+            # templates that will not load, stop the turn with the reason (_AgentConfigError →
+            # TURN_FAILED) instead of quietly running on a different prompt. The version is
+            # logged; the text never is.
+            _scaffold, _scaffold_version = _fetch_prompt_scaffold(worker_api_base, worker_api_key)
             try:
                 import yaml as _yaml
                 import os as _os
                 import smolagents as _sm
-                _tpl = _yaml.safe_load(open(_os.path.join(
-                    _os.path.dirname(_sm.__file__), "prompts", "code_agent.yaml")))
-                _tpl["system_prompt"] = _COMPACT_CODE_SYSTEM_PROMPT
-                agent_kwargs["prompt_templates"] = _tpl
-                _log("using compact CodeAgent system prompt (trimmed few-shot examples)")
+                with open(_os.path.join(_os.path.dirname(_sm.__file__), "prompts", "code_agent.yaml")) as _f:
+                    _tpl = _yaml.safe_load(_f)
             except Exception as _e:  # noqa: BLE001
-                _log(f"compact system prompt unavailable ({_e}); using smolagents default")
+                raise _AgentConfigError(
+                    f"The agent's prompt templates could not be loaded ({type(_e).__name__}).") from None
+            _tpl["system_prompt"] = _scaffold
+            agent_kwargs["prompt_templates"] = _tpl
+            _log(f"prompt scaffold code-agent v{_scaffold_version}")
         agent = _ToolAgent(**agent_kwargs)
         _agent_ref["a"] = agent  # let step_callback trim this agent's step memory (#63)
         # At the step budget the run ends WITHOUT final_answer (_maxsteps_partial hit). Offer

package/gu-repl.mjs

@@ -24,7 +24,7 @@
  * Commands: /exit  /model  /reset  /help   Ctrl-C stops following the current run.
  */
 import { readFile, mkdir, writeFile, unlink, rename } from "node:fs/promises";
-import { existsSync, statSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, statSync, readFileSync, writeFileSync, readdirSync, openSync, readSync, closeSync } from "node:fs";
 import { spawn } from "node:child_process";
 // FIRST, before anything that could itself fail on an old runtime: npm only WARNS about
 // `engines`, so an unsupported Node installs fine and then breaks somewhere unrelated.
@@ -73,6 +73,10 @@ import {
   answerBlock,
   updateRestartNote,
   describeInstallFailure,
+  CLI_UPDATE_SHELL_COMMAND,
+  isFreshPublishMiss,
+  freshPublishNote,
+  lazyModuleNames,
   inputZoneRows,
   INPUT_HEAD_ROWS,
   RAG_STORAGE,
@@ -795,8 +799,8 @@ const COMMANDS = [
   { name: "/proxy", usage: "/proxy [show|set|on|off|clear|test]", desc: "route MODEL calls through an HTTP proxy (local calls always go direct)" },
   { name: "/s3", usage: "/s3 [test]", desc: "set up the S3 bucket the RAG index lives in, and check the AWS keys work" },
   { name: "/context-window", usage: "/context-window [tokens|auto]", desc: "tell gu how big the coding model's context is — hosted models cannot be probed" },
-  { name: "/save-settings", usage: "/save-settings [path]", desc: "write this account's coding providers, models and key NAMES to a file (no secrets)" },
-  { name: "/load-settings", usage: "/load-settings [path]", desc: "read that file back on another machine — asks before it replaces anything" },
+  { name: "/save-settings", usage: "/save-settings [name|path]", desc: "write this account's providers, models and key NAMES to a file in your home folder (no secrets) — asks for a name, Enter keeps gu-settings.json" },
+  { name: "/load-settings", usage: "/load-settings [name|path]", desc: "read that file back on another machine — picks from the settings files in your home folder, asks before it replaces anything" },
   { name: "/doctor", desc: "check every configured model ANSWERS — especially the embedder, which a turn only reaches after several steps" },
   { name: "/tokens", desc: "break down the last prompt sent to the coding model — how much of it was RAG" },
   { name: "/help", desc: "list these commands" },
@@ -1962,6 +1966,9 @@ function announceCliUpdate() {
  * The picker names the consequence rather than the version, because the version is already on
  * the button and the consequence is what the answer turns on.
  */
+/** How long to wait before retrying an install that hit a just-published version (ETARGET). */
+const UPDATE_RETRY_WAIT_MS = 15_000;
+
 async function runUpdate() {
   const { cli, api } = availableUpdates;
   const rows = [];
@@ -2013,8 +2020,17 @@ async function runUpdate() {
         // stderr is captured rather than discarded so the reason can be shown. npm puts the
         // useful line (EPERM, EACCES, ETARGET) there, and "it failed" without it leaves the
         // user with nothing to act on — sudo and "close gu first" are different fixes.
-        const r = spawnSync("npm", ["i", "-g", "@tiens.nguyen/gu-cli@latest"],
-                            { stdio: ["ignore", "ignore", "pipe"], shell: true, encoding: "utf8" });
+        const install = () => spawnSync(CLI_UPDATE_SHELL_COMMAND,
+                                        { stdio: ["ignore", "ignore", "pipe"], shell: true, encoding: "utf8" });
+        let r = install();
+        // JUST PUBLISHED: the update check sees a new version the moment it lands, npm's cache and
+        // CDN a few minutes later — ETARGET in between. Wait once and retry before calling it a
+        // failure; if npm still has not caught up, say THAT, not a raw npm error.
+        if (isFreshPublishMiss(r)) {
+          await new Promise((res) => setTimeout(res, UPDATE_RETRY_WAIT_MS));
+          r = install();
+          if (isFreshPublishMiss(r)) throw new Error(freshPublishNote(cli));
+        }
         const failed = describeInstallFailure(r);
         if (failed) throw new Error(failed);
       });
@@ -5645,7 +5661,7 @@ async function addServer({ role = "coding", dialect = "openai", url: presetUrl =
     console.log(dim(dflt ? `  Enter uses ${dflt}  ·  Esc cancels\n` : "  Esc cancels.\n"));
     for (let attempt = 0; attempt < 3 && !target; attempt++) {
       const typed = await ask("  server URL: ");
-      if (typed === null || /^(no|n|skip|-)$/i.test(typed.trim())) break;
+      if (typed === null || as.isCancelWord(typed)) break;
       const raw = typed.trim() || dflt;
       if (!raw) break;
       const t = as.serverTarget(dialect, raw);
@@ -6133,20 +6149,31 @@ async function chooseModel() {
  * NOT THE CURRENT CHOICE. Which model this account codes with stays as it is on the machine being
  * loaded into: a file that moves your models should not quietly move your coder too.
  */
-const SETTINGS_FILE_DEFAULT = join(homedir(), "gu-settings.json");
-
-/** The path a command was given, or the default. Quotes stripped: people paste paths with them. */
-function settingsPathFrom(line, word) {
-  const typed = line.slice(word.length).trim().replace(/^['"]|['"]$/g, "");
-  if (!typed) return SETTINGS_FILE_DEFAULT;
-  const expanded = typed.startsWith("~/") ? join(homedir(), typed.slice(2)) : typed;
-  return resolve(expanded);
+/** What followed the command word, or "" — the name/path rules are settingsFilePath's. */
+function settingsArg(line, word) {
+  return line.slice(word.length).trim();
 }
 
 async function runSaveSettingsCommand(line) {
   const st = await import("./settings-transfer.mjs");
-  const file = settingsPathFrom(line, "/save-settings");
+  const home = homedir();
   console.log("");
+  // THE FILE NAME, IN THE DEFAULT FOLDER. The home directory is where it goes; all anyone should
+  // have to type is a name — and Enter keeps gu-settings.json, as before.
+  let typed = settingsArg(line, "/save-settings");
+  if (!typed) {
+    const answer = await ask(`  file name in ${home}  [${st.DEFAULT_SETTINGS_NAME}]: `);
+    if (answer === null) {
+      console.log(GUTTER + dim("  (cancelled — nothing was written)\n"));
+      return;
+    }
+    typed = answer.trim();
+  }
+  let file = st.settingsFilePath(typed, home);
+  if (!file) {
+    console.log(GUTTER + dim("  (cancelled — nothing was written)\n"));
+    return;
+  }
   const settings = await withPendingStatus("reading your model settings", fetchWorkerSettings);
   if (!settings) {
     console.log(GUTTER + red(`  couldn't reach the API at ${apiBase} — nothing was written.\n`));
@@ -6154,18 +6181,23 @@ async function runSaveSettingsCommand(line) {
   }
   const keys = (await fetchCodingKeys()) ?? [];
   const doc = st.buildTransfer({ settings, keys, host: hostname() });
-  if (!doc.codingBackends.length && !doc.agentModel.url && !doc.agentModel.name) {
-    console.log(GUTTER + dim("  this account has no coding providers and no agent model set — nothing to save.\n"));
+  if (!doc.codingBackends.length && !doc.agentModel.url && !doc.agentModel.name && !doc.embedModel.url && !doc.embedModel.name) {
+    console.log(GUTTER + dim("  this account has no coding providers, agent model or embedding model set — nothing to save.\n"));
     return;
   }
-  // ASK BEFORE OVERWRITING. The default path is one everybody shares, so the second machine to
-  // save would otherwise eat the first machine's file without a word.
-  if (existsSync(file)) {
-    const ok = (await ask(`${file} exists — overwrite it? [y/N] `)).trim().toLowerCase();
-    if (ok !== "y" && ok !== "yes") {
+  // ASK BEFORE OVERWRITING — and let a NEW NAME be the answer. The default path is one everybody
+  // shares, so the second machine to save would otherwise eat the first machine's file; "no" alone
+  // left nowhere to go but typing the whole command again with a path.
+  while (existsSync(file)) {
+    const answer = await ask(`  ${file} exists — overwrite it? [y/N], or type a new name: `);
+    const a = String(answer ?? "").trim();
+    if (/^(y|yes)$/i.test(a)) break;
+    const next = a && !/^(n|no)$/i.test(a) ? st.settingsFilePath(a, home) : "";
+    if (!next) {
       console.log(GUTTER + dim("  left it alone.\n"));
       return;
     }
+    file = next;
   }
   try {
     // 0600: it names your providers and your key names. Not secret, but nobody else's business.
@@ -6174,19 +6206,36 @@ async function runSaveSettingsCommand(line) {
     console.log(GUTTER + red(`  could not write ${file}: ${e instanceof Error ? e.message : e}\n`));
     return;
   }
-  const models = doc.codingBackends.reduce((n, b) => n + b.models.length, 0);
   console.log(GUTTER + accent(`  saved to ${file}`));
-  console.log(
-    GUTTER +
-      dim(`  ${doc.codingBackends.length} provider${doc.codingBackends.length === 1 ? "" : "s"}, ${models} model${models === 1 ? "" : "s"}, ${doc.keys.length} key name${doc.keys.length === 1 ? "" : "s"} — no secrets.`),
-  );
+  // Counted by the tested rule — the default model included (it once read "0 models").
+  console.log(GUTTER + dim(`  ${st.transferSummary(doc)}`));
   console.log(GUTTER + dim("  load it on the other machine with  /load-settings " + file + "\n"));
 }
 
 async function runLoadSettingsCommand(line) {
   const st = await import("./settings-transfer.mjs");
-  const file = settingsPathFrom(line, "/load-settings");
+  const home = homedir();
   console.log("");
+  // A NAME IN THE DEFAULT FOLDER, like /save-settings. With none given and more than one settings
+  // file there, pick from them rather than silently taking gu-settings.json.
+  let typed = settingsArg(line, "/load-settings");
+  if (!typed) {
+    const found = st.settingsFilesIn(listJsonFiles(home));
+    if (found.length > 1) {
+      console.log(dim(`  Settings files in ${home}  (${PICK_HINT}):`));
+      const i = await pickFromList(found, 0);
+      if (i < 0) {
+        console.log(GUTTER + dim("  (cancelled — nothing changed)\n"));
+        return;
+      }
+      typed = found[i];
+    }
+  }
+  const file = st.settingsFilePath(typed, home);
+  if (!file) {
+    console.log(GUTTER + dim("  (cancelled — nothing changed)\n"));
+    return;
+  }
   let text;
   try {
     text = readFileSync(file, "utf8");
@@ -6231,16 +6280,16 @@ async function runLoadSettingsCommand(line) {
     console.log(GUTTER + red("  the API refused the settings — nothing was changed.\n"));
     return;
   }
-  console.log(GUTTER + accent(`  applied: ${plan.adds} provider${plan.adds === 1 ? "" : "s"}.`));
+  console.log(GUTTER + accent(`  applied: ${plan.adds} provider${plan.adds === 1 ? "" : "s"}${patch.ragEmbedUrl || patch.ragEmbedModel ? ", the embedding model" : ""}.`));
 
   // THE KEYS, AFTER the settings — each needs the row it belongs to, and the rows only exist
   // once the API has minted their ids.
   const fresh = (await fetchWorkerSettings()) ?? {};
-  const rows = Array.isArray(fresh.agentCodingBackends) ? fresh.agentCodingBackends : [];
-  const rowIdForUrl = (url) => {
-    const hit = rows.find((r) => String(r?.url ?? "").trim().toLowerCase() === String(url).trim().toLowerCase());
-    return hit?.id ?? "";
-  };
+  const ps = await import("./coding-provider-setup.mjs");
+  const rows = ps.existingBackendRows(fresh);
+  // One server however it is spelled (task #245) — a raw compare missed "…/v1" and saved the key
+  // tied to NO server, where it can never be used.
+  const rowIdForUrl = (url) => ps.providerRowForUrl(rows, url)?.id ?? "";
   for (const k of plan.missingKeys) {
     const where = k.backendUrl ? ` for ${k.backendUrl}` : "";
     const typed = k.key || (await ask(`  key "${k.name}"${k.tail ? ` (…${k.tail})` : ""}${where} — paste it, or Enter to skip: `)).trim();
@@ -6248,12 +6297,42 @@ async function runLoadSettingsCommand(line) {
       console.log(GUTTER + dim(`  skipped ${k.name} — add it later with ctrl+k.`));
       continue;
     }
-    const id = await addCodingKey(k.name, typed, k.backendUrl ? rowIdForUrl(k.backendUrl) : "");
+    const rowId = k.backendUrl ? rowIdForUrl(k.backendUrl) : "";
+    const id = await addCodingKey(k.name, typed, rowId);
     console.log(GUTTER + (id ? accent(`  added ${k.name}.`) : red(`  could not add ${k.name}.`)));
+    // The key that was its server's DEFAULT on the saving machine is the default here too.
+    if (id && rowId && k.default) await setServerDefaultKey(rowId, id);
   }
   console.log(GUTTER + dim("  pick a coding model with /model.\n"));
 }
 
+/** The .json files directly in a folder, with enough of each to recognise a settings file. */
+function listJsonFiles(dir) {
+  try {
+    return readdirSync(dir)
+      .filter((n) => /\.json$/i.test(n))
+      .slice(0, 200)
+      .map((name) => {
+        try {
+          const p = join(dir, name);
+          const st = statSync(p);
+          // The marker is near the top; 4 KB is plenty and keeps a huge JSON from being read whole.
+          if (!st.isFile() || st.size > 5_000_000) return null;
+          const fd = openSync(p, "r");
+          const buf = Buffer.alloc(Math.min(4096, st.size));
+          readSync(fd, buf, 0, buf.length, 0);
+          closeSync(fd);
+          return { name, text: buf.toString("utf8"), mtimeMs: st.mtimeMs };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 async function fetchWorkerSettings() {
   try {
     const r = await fetch(`${apiBase}/api/worker/settings`, {
@@ -9925,7 +10004,35 @@ async function runAgentTurn(history, { attachJobId = "" } = {}) {
 }
 
 // ---------- REPL ----------
+/**
+ * LOAD EVERY LAZILY-IMPORTED MODULE NOW, so this process never reads one from disk later.
+ *
+ * REPORTED: "✓ gu 1.0.722 installed — Then restart gu", then /embed-model in the SAME terminal
+ * crashed it with ERR_MODULE_NOT_FOUND …/ollama-host-snippets.mjs. The running process was still
+ * 1.0.721; its /embed-model lazily imported ollama-host-snippets.mjs, and npm had just
+ * replaced the package directory with 1.0.722, which no longer ships that file. A module that
+ * still EXISTS is worse, not better: the old REPL silently runs against the new helper, two
+ * versions mixed in one process.
+ *
+ * The ESM loader caches a module by its resolved URL, so once each one is loaded here every later
+ * lazy import of that name gets THIS version back without touching the disk — whatever an in-app update
+ * wrote there. The list is read from this file's own source, so a new lazy import is covered
+ * without anyone remembering to add it. gu-cli.mjs is excluded: importing it RUNS the CLI.
+ * Fire-and-forget: each import is ~5 ms, verified side-effect free (no output, no files).
+ */
+function preloadLazyModules() {
+  let text = "";
+  try {
+    text = readFileSync(fileURLToPath(import.meta.url), "utf8");
+  } catch {
+    return;
+  }
+  for (const name of lazyModuleNames(text)) import(`./${name}`).catch(() => {});
+}
+
+
 async function main() {
+  preloadLazyModules();
   // The startup banner (logo + status facts) is printed AFTER the payload fetch below, once the
   // model/coder/RAG are known — see renderBanner (task #131). Nothing prints here so the banner
   // lands as one clean block.

package/ollama-setup.mjs

@@ -20,6 +20,7 @@
  */
 import { isLikelyEmbedder } from "./agent-model-command.mjs";
 import { EMBED_CHOICES } from "./embed-model-command.mjs";
+import { isCancelWord } from "./coding-provider-setup.mjs";
 
 /** Ollama's native port, used when someone types a bare host or an IP with no port. */
 export const OLLAMA_DEFAULT_PORT = 11434;
@@ -190,6 +191,8 @@ export function describeNotReady(host, missing) {
 export function normalizeOllamaUrl(raw) {
   const text = String(raw ?? "").trim();
   if (!text) return null;
+  // "exit", "quit", "cancel"… are commands, never hosts (they were once saved as http://exit).
+  if (isCancelWord(text)) return null;
   // A path, a query, or whitespace inside means this is not a host we can reason about.
   if (/\s/.test(text)) return null;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.722",
+  "version": "1.0.724",
   "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",

package/settings-transfer.mjs

@@ -29,13 +29,100 @@
  * your models should not also decide which one you are coding with.
  */
 
-/** Bumped only when an older gu could not read a newer file correctly. */
+import { basename, extname, isAbsolute, join, resolve } from "node:path";
+import { ensureV1Root, isCancelWord, MAX_MODELS_PER_SERVER } from "./coding-provider-setup.mjs";
+
+/** The file name used when none is given — in the default folder (the home directory). */
+export const DEFAULT_SETTINGS_NAME = "gu-settings.json";
+
+/**
+ * What was typed → the file to use. The DEFAULT FOLDER is the home directory, so a bare NAME is
+ * all anyone has to type ("work" → ~/work.json); a real path still works as one.
+ *   ""                 → ~/gu-settings.json
+ *   "work"             → ~/work.json            (".json" added when there is no extension)
+ *   "work.json"        → ~/work.json
+ *   "~/dir/x.json"     → ~/dir/x.json
+ *   "./x.json", "/abs" → that path exactly (relative ones from the current folder, as a shell would)
+ * Quotes around the whole thing are stripped — people paste paths with them. Returns "" for a
+ * command word ("exit", "cancel", …), which the caller treats as a cancel.
+ */
+export function settingsFilePath(typed, home) {
+  const t = String(typed ?? "").trim().replace(/^['"]|['"]$/g, "").trim();
+  if (!t) return join(home, DEFAULT_SETTINGS_NAME);
+  if (isCancelWord(t)) return "";
+  if (t === "~") return join(home, DEFAULT_SETTINGS_NAME);
+  if (t.startsWith("~/")) return withJson(join(home, t.slice(2)));
+  // An explicit path is taken exactly as typed — no ".json" guessed onto a name someone spelled out.
+  if (isAbsolute(t) || t.startsWith("./") || t.startsWith("../") || /[\\/]/.test(t)) return resolve(t);
+  return withJson(join(home, t));
+}
+
+const withJson = (p) => (extname(basename(p)) ? p : `${p}.json`);
+
+/**
+ * The settings files in the default folder, newest first — what /load-settings offers when it is
+ * given no name. Only files that ARE gu settings files (the "gu": "settings" marker), so a
+ * package.json in the home directory is never offered. `entries` = [{ name, text, mtimeMs }].
+ */
+export function settingsFilesIn(entries) {
+  return (Array.isArray(entries) ? entries : [])
+    .filter((e) => e && /\.json$/i.test(e.name) && /"gu"\s*:\s*"settings"/.test(String(e.text ?? "")))
+    .sort((a, b) => (b.mtimeMs ?? 0) - (a.mtimeMs ?? 0))
+    .map((e) => e.name);
+}
+
+/**
+ * Bumped only when an older gu could not read a newer file correctly. Task #245 ADDED optional
+ * fields (embedModel, keys[].default) — an older gu ignores them and still loads the rest, so the
+ * version stays 1.
+ */
 export const FILE_VERSION = 1;
 
 /** The kinds the API's own type allows (CodingBackendKind). */
 const KINDS = ["", "ollama", "openai", "local"];
 
 const isHttpUrl = (v) => typeof v === "string" && /^https?:\/\/\S+$/i.test(v.trim());
+
+/** Two spellings of one server are one server — the rule the API and providerRowForUrl use. */
+const sameServerUrl = (a, b) =>
+  Boolean(clean(a) && clean(b)) && ensureV1Root(clean(a)).toLowerCase() === ensureV1Root(clean(b)).toLowerCase();
+
+/** A server's models, the default counted once: what "N models" means everywhere a person reads it. */
+export function modelsOf(b) {
+  return [...new Set([clean(b?.defaultModel), ...(Array.isArray(b?.models) ? b.models.map(clean) : [])].filter(Boolean))];
+}
+
+/**
+ * The line /save-settings prints. REPORTED: "4 providers, 0 models" for four providers that each
+ * had a model — the count read only the EXTRA models and never the default one.
+ */
+export function transferSummary(doc) {
+  const n = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+  const backends = Array.isArray(doc?.codingBackends) ? doc.codingBackends : [];
+  const models = backends.reduce((sum, b) => sum + modelsOf(b).length, 0);
+  const parts = [n(backends.length, "provider"), n(models, "model"), n(Array.isArray(doc?.keys) ? doc.keys.length : 0, "key name")];
+  if (doc?.agentModel?.name || doc?.agentModel?.url) parts.push("the agent model");
+  if (doc?.embedModel?.name || doc?.embedModel?.url) parts.push("the embedding model");
+  return `${parts.join(", ")} — no secrets.`;
+}
+
+/**
+ * A server's models within MAX_MODELS_PER_SERVER (task #245) — the API refuses a row that grows
+ * past it, and a file saved before the cap may hold more. The default stays; extras are kept in
+ * order up to the cap, or up to what this account's row ALREADY holds (a row stored before the cap
+ * keeps what it has). Returns { defaultModel, models, dropped }.
+ */
+export function capServerModels(b, keepAtLeast = 0) {
+  const all = modelsOf(b);
+  const defaultModel = clean(b?.defaultModel) || "";
+  const limit = Math.max(MAX_MODELS_PER_SERVER, keepAtLeast);
+  const kept = all.slice(0, limit);
+  return {
+    defaultModel,
+    models: kept.filter((m) => m !== defaultModel),
+    dropped: all.slice(limit),
+  };
+}
 const isStr = (v) => typeof v === "string";
 const clean = (v) => (typeof v === "string" ? v.trim() : "");
 
@@ -64,6 +151,9 @@ export function buildTransfer({ settings = {}, keys = [], now = new Date(), host
       name: clean(k.name),
       tail: clean(k.tail),
       ...(urlForRowId.get(k.backendId) ? { backendUrl: urlForRowId.get(k.backendId) } : {}),
+      // Task #245: which key is its server's DEFAULT, so loading makes the same one the default
+      // (otherwise it would be whichever key happened to be added first).
+      ...(k.default === true ? { default: true } : {}),
     }));
   return {
     gu: "settings",
@@ -74,6 +164,8 @@ export function buildTransfer({ settings = {}, keys = [], now = new Date(), host
     ...(host ? { savedOn: host } : {}),
     codingBackends: backends,
     agentModel: { url: clean(settings.agentModelUrl), name: clean(settings.agentModelName) },
+    // Task #245: the third role. Its KEY travels like the others — by name, bound to its server.
+    embedModel: { url: clean(settings.ragEmbedUrl), name: clean(settings.ragEmbedModel) },
     keys: keyList,
   };
 }
@@ -150,6 +242,16 @@ export function validateTransfer(text) {
   if (am?.name !== undefined && !isStr(am.name)) {
     return { ok: false, problem: "agentModel.name must be text." };
   }
+  const em = doc.embedModel;
+  if (em !== undefined && (!em || typeof em !== "object" || Array.isArray(em))) {
+    return { ok: false, problem: "embedModel must be an object with a url and a name." };
+  }
+  if (em?.url !== undefined && em.url !== "" && !isHttpUrl(em.url)) {
+    return { ok: false, problem: `embedModel.url is not http(s): ${JSON.stringify(em.url)}.` };
+  }
+  if (em?.name !== undefined && !isStr(em.name)) {
+    return { ok: false, problem: "embedModel.name must be text." };
+  }
   if (doc.keys !== undefined && !Array.isArray(doc.keys)) {
     return { ok: false, problem: "keys must be a list." };
   }
@@ -159,6 +261,9 @@ export function validateTransfer(text) {
     if (!k || typeof k !== "object" || Array.isArray(k)) return { ok: false, problem: `${at} is not an object.` };
     if (!clean(k.name)) return { ok: false, problem: `${at} has no name — a key is identified by its name.` };
     if (k.key !== undefined && !isStr(k.key)) return { ok: false, problem: `${at}.key must be text.` };
+    if (k.default !== undefined && typeof k.default !== "boolean") {
+      return { ok: false, problem: `${at}.default must be true or false.` };
+    }
     if (k.backendUrl !== undefined && k.backendUrl !== "" && !isHttpUrl(k.backendUrl)) {
       return { ok: false, problem: `${at}.backendUrl is not http(s): ${JSON.stringify(k.backendUrl)}.` };
     }
@@ -166,13 +271,21 @@ export function validateTransfer(text) {
       name: clean(k.name),
       tail: clean(k.tail),
       ...(clean(k.backendUrl) ? { backendUrl: clean(k.backendUrl) } : {}),
+      ...(k.default === true ? { default: true } : {}),
       // Present only when a person put it there by hand; gu never writes one.
       ...(clean(k.key) ? { key: clean(k.key) } : {}),
     });
   }
   return {
     ok: true,
-    value: { backends, agentModel: { url: clean(am?.url), name: clean(am?.name) }, keys, savedAt: clean(doc.savedAt), savedOn: clean(doc.savedOn) },
+    value: {
+      backends,
+      agentModel: { url: clean(am?.url), name: clean(am?.name) },
+      embedModel: { url: clean(em?.url), name: clean(em?.name) },
+      keys,
+      savedAt: clean(doc.savedAt),
+      savedOn: clean(doc.savedOn),
+    },
     // Loading a file someone hand-edited to carry live credentials is allowed, but it is not
     // allowed to be quiet: that file is now a secret on disk.
     carriesSecrets: keys.some((k) => k.key),
@@ -190,8 +303,19 @@ export function validateTransfer(text) {
 export function planLoad(file, current = {}) {
   const currentRows = Array.isArray(current.agentCodingBackends) ? current.agentCodingBackends : [];
   const currentKeys = Array.isArray(current.keys) ? current.keys : [];
-  const have = new Set(currentKeys.map((k) => clean(k.name).toLowerCase()).filter(Boolean));
-  const missingKeys = file.keys.filter((k) => !have.has(k.name.toLowerCase()) && !k.key);
+  // A KEY BELONGS TO ITS SERVER (task #245): "work" on api.openai.com says nothing about a "work"
+  // key for ollama.com. So a same-named key counts as present when it is ON THE SAME SERVER, or
+  // tied to NO server (a pre-#245 key — the resolver still falls back to it, so asking for it
+  // again would be asking for a key the account already uses). The same name on ANOTHER server
+  // is a different key.
+  const urlOfRow = (id) => clean(currentRows.find((r) => r?.id === id)?.url);
+  const present = (k) =>
+    currentKeys.some((c) => {
+      if (clean(c.name).toLowerCase() !== k.name.toLowerCase()) return false;
+      if (!c.backendId) return true;
+      return Boolean(k.backendUrl) && sameServerUrl(urlOfRow(c.backendId), k.backendUrl);
+    });
+  const missingKeys = file.keys.filter((k) => !k.key && !present(k));
   const lines = [];
   lines.push(
     file.backends.length
@@ -199,12 +323,25 @@ export function planLoad(file, current = {}) {
       : "no coding providers in the file — the ones on this account stay as they are.",
   );
   for (const b of file.backends) {
-    const models = b.models.length ? `${b.models.length} model${b.models.length === 1 ? "" : "s"}` : "no models";
+    const n = modelsOf(b).length;
+    const models = n ? `${n} model${n === 1 ? "" : "s"}` : "no models";
     lines.push(`  ${b.kind || "?"}  ${b.url || "(no url)"}  ${models}${b.defaultModel ? `, default ${b.defaultModel}` : ""}${b.enabled ? "" : "  (disabled)"}`);
+    const mine = currentRows.find((r) => sameServerUrl(r?.url, b.url));
+    const capped = capServerModels(b, mine ? modelsOf(mine).length : 0);
+    if (capped.dropped.length) {
+      lines.push(`    a server offers at most ${MAX_MODELS_PER_SERVER} models — not loading ${capped.dropped.join(", ")}`);
+    }
   }
   if (file.agentModel.url || file.agentModel.name) {
     lines.push(`agent model: ${file.agentModel.name || "(server default)"}${file.agentModel.url ? ` at ${file.agentModel.url}` : ""}`);
   }
+  if (file.embedModel?.url || file.embedModel?.name) {
+    const same = sameServerUrl(file.embedModel.url, current.ragEmbedUrl) && file.embedModel.name === clean(current.ragEmbedModel);
+    lines.push(`embedding model: ${file.embedModel.name || "(unchanged)"}${file.embedModel.url ? ` at ${file.embedModel.url}` : ""}${same ? "  (already set)" : ""}`);
+    if (!same && file.embedModel.name && file.embedModel.name !== clean(current.ragEmbedModel)) {
+      lines.push("  a different embedder: every knowledge base rebuilds on its next search.");
+    }
+  }
   if (missingKeys.length) {
     lines.push(`${missingKeys.length} API key${missingKeys.length === 1 ? "" : "s"} this account does not have — gu will ask for ${missingKeys.length === 1 ? "it" : "them"} after:`);
     for (const k of missingKeys) lines.push(`  ${k.name}${k.tail ? ` (…${k.tail})` : ""}${k.backendUrl ? ` for ${k.backendUrl}` : ""}`);
@@ -230,24 +367,30 @@ export function planLoad(file, current = {}) {
 export function toSettingsPatch(file, current = {}) {
   const patch = {};
   const existing = Array.isArray(current.agentCodingBackends) ? current.agentCodingBackends : [];
-  const idFor = (kind, url) =>
-    existing.find(
-      (r) => r?.id && r.kind === kind && clean(r.url).toLowerCase() === clean(url).toLowerCase(),
-    )?.id ?? "";
+  // Matched as ONE SERVER however it is spelled (task #245) — "https://ollama.com" and
+  // "https://ollama.com/v1" are the same row, and a raw compare would mint a twin and strand the
+  // keys bound to the original.
+  const mineFor = (kind, url) => existing.find((r) => r?.id && r.kind === kind && sameServerUrl(r.url, url));
   if (file.backends.length) {
     patch.agentCodingBackends = file.backends.map((b) => {
-      const id = idFor(b.kind, b.url);
+      const mine = mineFor(b.kind, b.url);
+      const capped = capServerModels(b, mine ? modelsOf(mine).length : 0);
       return {
-        ...(id ? { id } : {}),
+        ...(mine?.id ? { id: mine.id } : {}),
         kind: b.kind,
         url: b.url,
-        defaultModel: b.defaultModel,
-        models: b.models,
+        defaultModel: capped.defaultModel,
+        models: capped.models,
         enabled: b.enabled,
       };
     });
   }
   if (file.agentModel.url) patch.agentModelUrl = file.agentModel.url;
   if (file.agentModel.name) patch.agentModelName = file.agentModel.name;
+  if (file.embedModel?.url) patch.ragEmbedUrl = file.embedModel.url;
+  if (file.embedModel?.name) patch.ragEmbedModel = file.embedModel.name;
+  // The embedder's key is resolved through its server's keys (task #245); the pre-#245
+  // account-wide pick would only shadow them.
+  if (file.embedModel?.url || file.embedModel?.name) patch.ragEmbedKeyId = "";
   return patch;
 }

package/terminal-layout.mjs

@@ -1715,6 +1715,46 @@ export function describeInstallFailure({ status = 0, stderr = "", error = null }
   return `npm exited ${status}${why ? ` — ${_clipReason(why)}` : ""}`;
 }
 
+/**
+ * The command the in-app update RUNS — one string, run through a shell.
+ *
+ * ONE STRING, NOT AN ARGS ARRAY. A shell is needed (Windows finds npm as npm.cmd only through
+ * one), and Node 24 warns DEP0190 whenever args are passed WITH `shell: true` — they are joined,
+ * not escaped — and that warning landed in the middle of the transcript on every update.
+ *
+ * --prefer-online: npm REVALIDATES its cached package document instead of trusting it. The update
+ * check reads registry.npmjs.org/<pkg>/latest, which knows a new version the moment it is
+ * published; `npm install` reads the full document from npm's own cache and CDN, which catch up
+ * minutes later. Without this, a version announced seconds after publishing failed with ETARGET.
+ */
+export const CLI_UPDATE_SHELL_COMMAND = `${CLI_INSTALL_COMMAND} --prefer-online`;
+
+/**
+ * Did the install fail only because npm has not caught up with a JUST-published version?
+ * (ETARGET / notarget — "No matching version found".) Worth one retry after a short wait, and
+ * worth saying plainly rather than as a raw npm error: nothing is wrong with the release.
+ */
+export function isFreshPublishMiss({ status = 0, stderr = "" } = {}) {
+  if (status === 0) return false;
+  return /\b(ETARGET|notarget)\b|No matching version found/i.test(String(stderr ?? ""));
+}
+
+/** What to say when npm still has not caught up after the retry. */
+export function freshPublishNote(version = "") {
+  return `gu ${version || "the new version"} was published moments ago and npm's mirrors are still catching up — ` +
+    "try the update again in a few minutes.";
+}
+
+/**
+ * The local modules a source text imports LAZILY (a dynamic import of "./name.mjs"), minus the CLI entry
+ * (importing gu-cli.mjs RUNS the CLI). gu-repl preloads these at startup so an in-app update that
+ * replaces the package on disk can never be read into the still-running old process.
+ */
+export function lazyModuleNames(text) {
+  return [...new Set([...String(text ?? "").matchAll(/import\("\.\/([\w.-]+\.mjs)"\)/g)].map((m) => m[1]))]
+    .filter((m) => m !== "gu-cli.mjs");
+}
+
 /** 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();