@tiens.nguyen/gu-cli 1.0.870 → 1.0.871

package/agent-model-command.mjs

@@ -355,73 +355,6 @@ export function agentRecoveryOptions({ keyProblem = false, host = "" } = {}) {
   ];
 }
 
-// ---------------------------------------------------------------------------------------------
-// #43 — /model's "change the Ollama server" flow, when the agent is NOT on an Ollama.
-// ---------------------------------------------------------------------------------------------
-
-/**
- * Is this machine's agent model on an OpenAI-compatible PROVIDER rather than an Ollama?
- *
- * Reported (#43): client mode, /model → change the Ollama server offered the agent's URL —
- * https://api.openai.com — as the "agent + embedding server", probed it for Ollama's /api/tags, got
- * 404, said "check that Ollama is listening", and asked again, with no way forward but typing "no".
- * A provider is known two ways: a provider row for that URL says so, or the URL is one of the hosted
- * APIs everyone knows is not an Ollama.
- */
-const KNOWN_PROVIDER_HOSTS = [
-  "api.openai.com",
-  "openrouter.ai",
-  "api.together.xyz",
-  "api.moonshot.ai",
-  "api.groq.com",
-  "api.deepseek.com",
-  "api.mistral.ai",
-  "generativelanguage.googleapis.com",
-];
-
-export function agentIsOnProvider(settings) {
-  const source = agentListSource(settings);
-  if (!source.url) return false;
-  if (source.dialect === "openai") return true;
-  let host = "";
-  try {
-    host = new URL(String(settings?.agentModelUrl ?? "")).hostname.toLowerCase();
-  } catch {
-    return false;
-  }
-  return KNOWN_PROVIDER_HOSTS.some((h) => host === h || host.endsWith(`.${h}`));
-}
-
-/**
- * The address to offer for the CODING server: the coder's own URL when it is not a known provider,
- * else this machine's Ollama. Never the agent's provider URL — that is what put api.openai.com in an
- * Ollama prompt.
- */
-export function coderServerDefault(settings) {
-  const coder = String(settings?.agentCodingModelUrl ?? "").trim();
-  if (coder && !agentIsOnProvider({ ...settings, agentModelUrl: coder })) return coder;
-  const agent = String(settings?.agentModelUrl ?? "").trim();
-  if (agent && !agentIsOnProvider(settings)) return agent;
-  return "http://127.0.0.1:11434";
-}
-
-/**
- * A server that ANSWERED but has no /api/tags is not an Ollama — an OpenAI-compatible API answers 404
- * there. That is a different fix from "not listening", and saying the wrong one sends people to check
- * a server that is working fine.
- */
-export function describeNotOllama(host, role) {
-  return role === "agent"
-    ? [
-        `${host} answers, but it is not an Ollama server (no /api/tags).`,
-        "an OpenAI-compatible agent is changed with /agent-model — or type 'no' to skip this role.",
-      ]
-    : [
-        `${host} answers, but it is not an Ollama server (no /api/tags).`,
-        "for an OpenAI-compatible coder use /model → add or change an OpenAI-compatible provider — or type 'no' to skip.",
-      ];
-}
-
 // ---------------------------------------------------------------------------------------------
 // #44 — WHAT TO CHANGE comes first.
 // ---------------------------------------------------------------------------------------------

package/client-expert-api.mjs

@@ -1138,39 +1138,3 @@ export async function saveSetupKeys({ apiBase = LOCAL_API_BASE, workerKey, model
   return out;
 }
 
-/**
- * THE NEW OLLAMA SERVER'S ROWS, MERGED INTO WHAT IS ALREADY THERE — never replacing it (#43).
- *
- * Found while fixing #43: choosing a coding server in /model → "change the Ollama server" saved
- * codingBackendsForClientExpert(...) AS the whole list — one Ollama row and the Kimi row — deleting
- * every provider the user had added: an api.openai.com row the AGENT's key is found through, an
- * ollama.com cloud row. Their keys, bound to those row ids, were orphaned.
- *
- * Replaced: the local/LAN Ollama row(s) — that is what "the Ollama server this machine uses" means —
- * with the new one, which keeps the first replaced row's id so anything bound to it still resolves.
- * Kept, ids and all: every OpenAI-compatible row, and any Ollama CLOUD row (a paid provider, not
- * "this machine's server"). The template's default provider row is added only when no row already
- * has its URL.
- */
-export function mergeOllamaServerBackends(existing, fresh, { isCloud } = {}) {
-  const cloud = typeof isCloud === "function" ? isCloud : () => false;
-  const norm = (u) => String(u ?? "").trim().replace(/\/+$/, "").toLowerCase();
-  const rows = Array.isArray(existing) ? existing.filter(Boolean) : [];
-  const freshOllama = (Array.isArray(fresh) ? fresh : []).filter((f) => f.kind === "ollama");
-  const newUrls = new Set(freshOllama.map((f) => norm(f.url)));
-  // A row already at the NEW server's URL is the same provider — the new server takes it over, id and
-  // all, so a key bound to it (the Ollama cloud's own key) keeps working and no twin row appears.
-  const sameServer = rows.filter((b) => newUrls.has(norm(b.url)));
-  const replaced = [...sameServer, ...rows.filter((b) => b.kind === "ollama" && !cloud(b.url) && !sameServer.includes(b))];
-  const kept = rows.filter((b) => !replaced.includes(b));
-  const out = [];
-  for (const f of freshOllama) {
-    const id = (sameServer.find((b) => b.id && norm(b.url) === norm(f.url)) ?? replaced.find((b) => b.id))?.id;
-    out.push(id ? { ...f, id } : f);
-  }
-  out.push(...kept);
-  for (const f of Array.isArray(fresh) ? fresh : []) {
-    if (f.kind !== "ollama" && !out.some((b) => norm(b.url) === norm(f.url))) out.push(f);
-  }
-  return out;
-}

package/doctor-check.mjs

@@ -220,6 +220,13 @@ export async function runDoctor(settings, opts = {}) {
   return { results, ok: results.every((r) => r.status === "ok") };
 }
 
+/** Where an unset role is set from the terminal. */
+const SET_WITH = {
+  chat: "/agent-model",
+  code: "/model → add a provider",
+  embed: "/embed-model",
+};
+
 /** One line per role, for the terminal. Pure, so the wording is testable. */
 export function doctorLines(results) {
   const mark = { ok: "✓", unset: "·", timeout: "✗", unreachable: "✗", error: "✗" };
@@ -233,7 +240,8 @@ export function doctorLines(results) {
       out.push("    could not be scheduled. This is not a network problem.");
       if (r.busy?.hint) out.push(`    ${r.busy.hint}`);
     }
-    if (r.status === "unset") out.push("    set it with /model → change the Ollama server");
+    // Each role has its own command since #412 removed /model's all-in-one Ollama flow.
+    if (r.status === "unset") out.push(`    set it with ${SET_WITH[r.role] ?? "/model"}`);
   }
   return out;
 }

package/gu-cli.mjs

@@ -1799,6 +1799,25 @@ if (args[0] === "mongo") {
   process.exit(0);
 }
 
+/** The gu-service check (#413), as lines — shared by `gu doctor` and the terminal's /doctor. */
+async function guServiceLines() {
+  const sc = await import("./service-check.mjs");
+  const { hostedApiBase } = await import("./client-expert-api.mjs");
+  const { isLocalApiBase } = await import("./terminal-layout.mjs");
+  const { loadProxy } = await import("./proxy-store.mjs");
+  const { dispatcherFor } = await import("./proxy-dispatcher.mjs");
+  const apiBase = String(process.env.GONEXT_API_BASE ?? "").trim();
+  const { lines } = await sc.checkGuService({
+    hostedBase: hostedApiBase(),
+    apiBase,
+    workerKey: String(process.env.GONEXT_WORKER_KEY ?? "").trim(),
+    localApi: isLocalApiBase(apiBase),
+    proxy: await loadProxy().catch(() => null),
+    dispatcherFor,
+  });
+  return lines;
+}
+
 if (args[0] === "doctor") {
   // Task #304: a Mac whose MongoDB runs in Docker is told the native option, once, up front —
   // a working Docker MongoDB is left alone (it is a choice), a silent one is named as stuck.
@@ -2001,6 +2020,15 @@ if (args[0] === "doctor") {
         console.log(`  (local stack check skipped: ${e.message})`);
       }
     }
+    // CAN A CODING TURN START? (#413) Last, after the local API: its instructions come from the
+    // gu service, through that API. Reported on a Windows VM where doctor passed everything, "hi"
+    // worked, and every coding turn failed — this was the one thing doctor never looked at.
+    try {
+      console.log("\n  Checking the gu service (a coding turn needs it)…");
+      for (const l of await guServiceLines()) console.log(`  ${l}`);
+    } catch (e) {
+      console.log(`  (gu service check skipped: ${e?.message ?? e})`);
+    }
   } finally {
     rl0.close();
   }

package/gu-repl.mjs

@@ -157,6 +157,7 @@ import { globalPrefixOf } from "./install-path.mjs";
 import { indentBlock, commandBlockRows } from "./terminal-layout.mjs"; // every line of an Allow-prompt detail indented (#189); wrapped + collapsible command (#204)
 import { firstGuOnPath, pathGuMismatch, guOnPathIsCurrent, updateAttemptRecord, repeatUpdateNotice } from "./update-verify.mjs";
 import { embedNotice, embedState, setupNoticeRows } from "./embed-model-command.mjs";
+import { HINTS, pickHint, hintRow, hintFits, HINT_AFTER_SECONDS } from "./hints.mjs";
 import { normalizeQuick, quickReady, quickTarget, quickBarHint, quickWarning, QUICK_MAX } from "./quick-models.mjs";
 import {
   MODELFALLBACK_PREFIX, fallbackAfterTurn, fallbackHistoryLine, fallbackNotice, keyMissingNotice,
@@ -518,6 +519,7 @@ const THINKING_WORDS = (() => {
  * file is missing is playful too, and the last-resort default is a real word rather than the
  * one word the list is designed to avoid.
  */
+let lastHintIdx = -1; // the tip the previous turn showed (#234)
 const pickWord = () =>
   THINKING_WORDS[Math.floor(Math.random() * THINKING_WORDS.length)] || "Shaving the yak";
 
@@ -6126,9 +6128,25 @@ async function runModelDoctor() {
     "\n" + GUTTER +
       (bad.length === 0
         ? accent("✓ every configured model answered.")
-        : red(`✗ ${bad.length} of ${results.length} did not answer.`)) +
-      "\n"
+        : red(`✗ ${bad.length} of ${results.length} did not answer.`))
+  );
+  // THE GU SERVICE TOO (#413): every model can answer and a coding turn still fail, because its
+  // instructions come from the gu service — reported on a Windows VM where only "hi" worked.
+  const sc = await import("./service-check.mjs");
+  const verdict = await withPendingStatus("the gu service", async () =>
+    sc.checkGuService({
+      hostedBase: (await import("./client-expert-api.mjs")).hostedApiBase(),
+      apiBase,
+      workerKey,
+      localApi: isLocalApiBase(apiBase),
+      proxy: await (await import("./proxy-store.mjs")).loadProxy().catch(() => null),
+      dispatcherFor: (await import("./proxy-dispatcher.mjs")).dispatcherFor,
+    })
   );
+  for (const [i, l] of verdict.lines.entries()) {
+    console.log(GUTTER + (i === 0 ? (verdict.ok ? accent(l) : red(l)) : dim(l)));
+  }
+  console.log("");
 }
 
 /** THROUGH THE PROXY (#160), like every other model call — a bare fetch is what fails on a
@@ -6138,410 +6156,6 @@ async function doctorFetch(url, init) {
   return proxyFetch(url, init);
 }
 
-async function reconfigureOllamaServer() {
-  const os = await import("./ollama-setup.mjs");
-  const am = await import("./agent-model-command.mjs");
-  const md = await import("./model-doctor.mjs");
-  const { proxyFetch } = await import("./proxy-dispatcher.mjs");
-
-  const settings = await withPendingStatus("reading your model settings", fetchWorkerSettings);
-  if (!settings) {
-    console.log(red("   couldn't reach the API to read your current settings.\n"));
-    return;
-  }
-
-  /** Load a box's models THROUGH THE PROXY (#160) — a bare fetch is what fails on a restricted
-   *  network, and it fails as "no models", which is the wrong story entirely. */
-  const load = async (n, key = "") => {
-    const res = await withPendingStatus(`loading models from ${n.host}`, () =>
-      proxyFetch(os.tagsUrlFor(n), {
-        signal: AbortSignal.timeout(8000),
-        // #301: the key typed for this server; absent → the request is what it always was.
-        ...(key ? { headers: { Authorization: `Bearer ${key}` } } : {}),
-      })
-    );
-    // The status is kept: a 404 here means "answered, but not an Ollama" (#43), not "unreachable".
-    if (!res.ok) throw Object.assign(new Error(`HTTP ${res.status}`), { httpStatus: res.status });
-    return am.parseOllamaTags(await res.json().catch(() => null));
-  };
-
-  // #301: the way out, said under every server question (full once, short after), and the keys
-  // typed for servers, by host — saved against their rows once the settings are written.
-  const ui = await import("./model-setup-ui.mjs");
-  const hint = ui.createHinter();
-  const typedKeys = new Map();
-  const askKeyFor = async (host) => {
-    if (typedKeys.has(host)) return typedKeys.get(host); // same server for both roles → asked once
-    console.log(dim(`    ${hint()}`));
-    // askSecret: masked, kept out of history; Esc throws PromptCancelled → /model is cancelled
-    // with nothing changed, which is what "skip all" means here.
-    const k = (await askSecret(`   API key for ${host} (Enter for none): `)).trim();
-    typedKeys.set(host, k);
-    console.log(GUTTER + dim(ui.keyConfirmation(host, k)));
-    return k;
-  };
-
-  /** Ask for one server and load it. Returns {normalized, models} or null (declined/failed). */
-  const askServer = async (label, dflt, { require = false, short = "server", role = "coder" } = {}) => {
-    for (let attempt = 0; attempt < 3; attempt++) {
-      // The address goes ABOVE, in full — it is long, it is the thing Enter accepts, and the
-      // frozen row is too narrow to hold it without truncating exactly that. The row itself
-      // carries a short label so it is obvious WHAT is being asked for.
-      // Shown WITHOUT /v1 (task #220 follow-up): the suffix in a default reads as an
-      // instruction, leaving the reader unsure whether their own address needs it. It does not
-      // — normalizeOllamaUrl adds it — and displayUrl round-trips, so what is shown can be fed
-      // straight back as the default.
-      console.log(dim(`   ${label} — Enter keeps ${os.displayUrl(dflt)}`));
-      console.log(dim(`    ${hint()}`));
-      // THE ROW MUST SAY WHICH SERVER IT IS ASKING FOR. It said a bare "server:" — chosen to
-      // fit the frozen row, which traded away the one thing the label was for. Two questions
-      // in a row, both reading "server:", and the reader cannot tell which one they are
-      // answering (reported: "it should say 'Agent + Embedder server' then 'Coding Server',
-      // it only says 'server:'"). `short` is the role in the fewest words that still name it.
-      const typed = (await ask(`  ${short}: `)).trim();
-      // "s" is the advertised skip (#301); the older words still work.
-      if (ui.readStepAnswer(typed).kind === "skip") return null;
-      // EVERY READING OF A BARE HOSTNAME, in order. Typing "ollama2.getmarsic.cc" means
-      // https://…:443 behind a proxy, while "192.168.1.40" means http://…:11434 — one guess
-      // is right for one of them and produces a timeout that looks like a dead server for the
-      // other. See urlCandidates; the load decides, not the heuristic.
-      const candidates = os.urlCandidates(typed || dflt);
-      if (!candidates.length) {
-        console.log(dim("   that is not a server address — try 192.168.1.40 or a full URL"));
-        continue;
-      }
-      let n = null;
-      let models = null;
-      let lastErr = null;
-      // #301: a TYPED public address may need a key — asked before listing, so a server that
-      // needs one can list its models. A LAN box is never asked.
-      let key = "";
-      if (ui.shouldAskKey({ typed, host: candidates[0].host })) key = await askKeyFor(candidates[0].host);
-      const tryAll = async () => {
-        for (const cand of candidates) {
-          try {
-            models = await load(cand, key);
-            n = cand;
-            if (candidates.length > 1) console.log(dim(`   using ${os.displayUrl(cand.url)}`));
-            return;
-          } catch (err) {
-            lastErr = err;
-          }
-        }
-      };
-      await tryAll();
-      // Refused for want of credentials: ask now, whatever the address looked like, and list again.
-      if (!n && ui.needsKeyAfterStatus(lastErr?.httpStatus) && !key) {
-        console.log(yellow(`   ${candidates[0].host} needs an API key to list its models.`));
-        typedKeys.delete(candidates[0].host);
-        key = await askKeyFor(candidates[0].host);
-        if (key) await tryAll();
-      }
-      if (!n && ui.needsKeyAfterStatus(lastErr?.httpStatus)) {
-        console.log(red(`   ${candidates[0].host} refused the request (HTTP ${lastErr.httpStatus})${key ? " — that key was not accepted" : ""}.`));
-        continue;
-      }
-      if (!n) {
-        if (lastErr?.httpStatus === 404) {
-          // IT ANSWERED — it is simply not an Ollama (#43). "Couldn't reach … is Ollama listening"
-          // sent people to debug a server that was working.
-          for (const l of am.describeNotOllama(candidates[0].host, role)) console.log(yellow(`   ${l}`));
-          continue;
-        }
-        // One address typed, one failure reported — naming every candidate would be two errors
-        // for one mistake, and neither would be the address they gave.
-        console.log(red(`   couldn't reach ${candidates[0].host}: ${os.networkReason(lastErr)}`));
-        console.log(dim("   check the address, that Ollama is listening on the network, and /proxy."));
-        continue;
-      }
-      const usable = os.usableModelList(models);
-      if (!usable.ok) {
-        for (const l of os.describeUnusableList(usable.why, n.host)) console.log(dim(`   ${l}`));
-        continue;
-      }
-      if (require) {
-        // THE AGENT AND THE EMBEDDER ARE NOT A FREE CHOICE. A box without them is "not ready",
-        // not "wrong" — it can still be a perfectly good coder host, so this refuses the ROLE
-        // rather than the server.
-        const need = os.checkRequired(models);
-        if (!need.ok) {
-          for (const l of os.describeNotReady(n.host, need.missing)) console.log(yellow(`   ${l}`));
-          console.log(dim("   (or type s to skip — you can set it later with /model)"));
-          continue;
-        }
-        console.log(dim(` ✓ ${n.host} has the ${os.REQUIRED_AGENT_PREFIX} family and the embedder`));
-      }
-      console.log(dim(`   found ${models.length} model${models.length === 1 ? "" : "s"} on ${n.host}`));
-      return { normalized: n, models };
-    }
-    return null;
-  };
-
-  // AN AGENT ON A PROVIDER IS NOT ASKED ABOUT HERE (#43). This flow is for Ollama boxes; offering
-  // https://api.openai.com as the "agent + embedding server" could only fail its /api/tags probe and
-  // ask again. Keep it, say where it is changed, and go on to the coder.
-  const agentOnProvider = am.agentIsOnProvider(settings);
-  const curAgent =
-    String(settings.agentModelUrl ?? "").trim() || "https://ollama1.getmarsic.cc/v1";
-  const curCode = am.coderServerDefault(settings);
-
-  let agent = null;
-  if (agentOnProvider) {
-    const host = hostOf(String(settings.agentModelUrl ?? ""));
-    console.log(dim(`   The agent model is on ${host} (OpenAI-compatible) — kept as it is; change it with /agent-model.`));
-    console.log(dim("   Enter keeps the current address."));
-  } else {
-    console.log(dim("   TWO servers may be used: the agent + embedder on one, the coder on another."));
-    console.log(dim("   Enter keeps the current address."));
-    agent = await askServer("Agent + embedding server", curAgent, {
-      require: true,
-      short: "agent + embed server",
-      role: "agent",
-    });
-  }
-  const coder = await askServer("Coding-model server", agent?.normalized?.url ?? curCode, {
-    short: "coding server",
-    role: "coder",
-  });
-
-  // Task #14: skipping is a real answer, not a failure — but the bottom bar must keep saying
-  // what it cost. Declining the AGENT + embed server leaves both roles unset → both warnings.
-  if (!agent && !agentOnProvider) {
-    agentMissing = true; // no agent model chosen → the agent falls back to the coding model
-    embedMissing = true; // the embedder lives on the agent server → RAG is off until /embed-model
-  }
-
-  if (!agent && !coder) {
-    console.log(dim("   nothing set — models stay as they are.\n"));
-    return;
-  }
-
-  // THE AGENT IS CHOSEN TOO (user, 2026-09-06). checkRequired now gates on the gemma4 FAMILY
-  // rather than one exact tag, so "the box is ready" no longer names a single model — which of
-  // its gemma4s routes every turn is a real decision, and a box commonly holds a small one for
-  // speed beside a larger one for quality. Skipped when there is only one candidate: a picker
-  // with a single row is a question with one answer.
-  let chat = "";
-  if (agent) {
-    // Task #36: the saved agent stays a choice (and the default) even when it is not a gemma4.
-    const { cands, current: agentDefault } = os.agentChoices(
-      agent.models,
-      String(settings.agentModelName ?? "").trim()
-    );
-    if (cands.length <= 1) {
-      chat = agentDefault;
-    } else {
-      const labels = cands.map((m) => {
-        const size = am.formatSize(m.sizeBytes);
-        return `${m.model}${size ? dim(`  ${size}`) : ""}${m.model === agentDefault ? dim("  (current)") : ""}`;
-      });
-      console.log(dim(`   AGENT model — routes every turn, writes the plain replies  (${PICK_HINT}):`));
-      const pick = await pickFromList(
-        labels,
-        Math.max(0, cands.findIndex((m) => m.model === agentDefault))
-      );
-      if (pick < 0) {
-        console.log(dim("   (cancelled — nothing changed)\n"));
-        return;
-      }
-      chat = cands[pick].model;
-    }
-  }
-
-  // The CODER is chosen from whatever its box has; the EMBEDDER is not a choice at all.
-  let code = "";
-  let extras = [];
-  if (coder) {
-    const roles = os.defaultRoles(coder.models, {
-      preferred: { code: String(settings.agentCodingModelName ?? "").trim() },
-    });
-    const labels = coder.models.map((m) => {
-      const size = am.formatSize(m.sizeBytes);
-      const kind = am.isLikelyEmbedder(m) ? dim("  · embedder") : "";
-      return `${m.model}${size ? dim(`  ${size}`) : ""}${kind}${m.model === roles.code ? dim("  (current)") : ""}`;
-    });
-    console.log(dim(`   CODING model — writes the code; worth waiting for  (${PICK_HINT}):`));
-    const idx = await pickFromList(labels, Math.max(0, coder.models.findIndex((m) => m.model === roles.code)));
-    if (idx < 0) {
-      console.log(dim("   (cancelled — nothing changed)\n"));
-      return;
-    }
-    code = coder.models[idx].model;
-
-    const rest = coder.models.filter((m) => !am.isLikelyEmbedder(m) && m.model !== code);
-    if (rest.length) {
-      // Pre-ticked from what /model already offers, so re-running starts from what is saved
-      // rather than from empty — otherwise every re-run silently drops the extras you had.
-      const already = new Set(
-        (Array.isArray(settings.agentCodingBackends) ? settings.agentCodingBackends : [])
-          .filter((b) => (b?.kind ?? "") === "ollama")
-          .flatMap((b) => (Array.isArray(b.models) ? b.models : []))
-      );
-      console.log(
-        dim(`   Also offer these in /model?  (up to ${MAX_ALT_CODERS} · ${PICK_MANY_HINT}):`)
-      );
-      const ticks = await pickManyFromList(
-        rest.map((m) => `${m.model}${am.formatSize(m.sizeBytes) ? dim(`  ${am.formatSize(m.sizeBytes)}`) : ""}`),
-        rest.map((m, i) => (already.has(m.model) ? i : -1)).filter((i) => i >= 0),
-        { max: Math.max(MAX_ALT_CODERS, rest.filter((m) => already.has(m.model)).length) }
-      );
-      // null is Escape and cancels the command; an EMPTY list is a legitimate "offer none".
-      if (ticks === null) {
-        console.log(dim("   (cancelled — nothing changed)\n"));
-        return;
-      }
-      extras = ticks.map((i) => rest[i].model);
-    }
-  }
-
-  // WRITE ONLY THE HALVES THAT WERE SET. Someone who configured a coder but skipped the agent
-  // box must not have their existing agent model wiped — half-configured is a real state and
-  // clobbering the other half is the opposite of what skipping asked for.
-  const patch = {};
-  if (agent) {
-    Object.assign(patch, {
-      agentModelUrl: agent.normalized.url,
-      agentModelName: chat,
-      agentModel: chat,
-      ragEnabled: true,
-      ragEmbedUrl: agent.normalized.url,
-      ragEmbedModel: os.defaultEmbedModel?.(agent.models) ?? os.REQUIRED_EMBED_MODEL,
-    });
-  }
-  if (coder) {
-    Object.assign(patch, {
-      agentCodingModelUrl: coder.normalized.url,
-      agentCodingModelName: code,
-      agentCodingModelKind: "ollama",
-      agentCodingDefaultKind: "ollama",
-      // MERGED, not replaced (#43): the providers already configured — and the keys bound to them —
-      // survive choosing a new Ollama server.
-      agentCodingBackends: (await import("./client-expert-api.mjs")).mergeOllamaServerBackends(
-        (await import("./coding-provider-setup.mjs")).existingBackendRows(settings),
-        (await import("./client-expert-api.mjs")).codingBackendsForClientExpert({
-          url: coder.normalized.url,
-          chat: agent ? chat : code,
-          code,
-          altCoders: extras,
-        }),
-        { isCloud: (await import("./coding-key-prompt.mjs")).isOllamaCloudUrl }
-      ),
-    });
-  }
-
-  const saved = await withPendingStatus("saving", () =>
-    md.saveWorkerSettings(apiBase, workerKey, patch)
-  );
-  if (!saved) {
-    console.log(red("   couldn't save that to this machine — nothing changed."));
-    console.log(GUTTER + dim("if this machine's local API is old, restart it with `gu api restart`.\n"));
-    return;
-  }
-  // #301: THE KEYS TYPED FOR THE SERVERS, bound to their rows now that the rows exist (the API
-  // refuses a key for a row it does not have). Before the cloud check below, so a key typed for
-  // the Ollama cloud is not asked for a second time. Reported by host, never by value.
-  {
-    const used = [agent?.normalized?.url, coder?.normalized?.url].filter(Boolean);
-    // By HOSTNAME: the key was asked for urlCandidates' host, which carries no port, while a URL's
-    // .host does — box.example.com:8443 would otherwise never match its own key.
-    const hostnameOf = (u) => { try { return new URL(u).hostname; } catch { return ""; } };
-    const pending = [...typedKeys].filter(([host, k]) => k && used.some((u) => hostnameOf(u) === host));
-    if (pending.length) {
-      const fresh = await withPendingStatus("storing the key", fetchWorkerSettings);
-      const ps = await import("./coding-provider-setup.mjs");
-      for (const [host, k] of pending) {
-        const url = used.find((u) => hostnameOf(u) === host);
-        const found = ps.providerRowForUrl(ps.existingBackendRows(fresh ?? {}), url);
-        if (!found) {
-          console.log(yellow(`   no server row holds ${host} yet — add its key with ctrl+k in /model.`));
-          continue;
-        }
-        const ok = await withPendingStatus("saving the key", () => addCodingKey(host, k, found.id));
-        console.log(ok
-          ? GUTTER + dim(`✓ key stored for ${host} — the server's default key`)
-          : red(`   couldn't store the key for ${host} — add it with ctrl+k.`));
-      }
-    }
-  }
-  // THE OLLAMA CLOUD NEEDS ITS OWN KEY. Reported: choosing https://ollama.com here listed its 20 models
-  // (that list is public) and saved, without a key — and the next turn failed "REJECTED the coding API
-  // key", having borrowed an unrelated sk-… key. Asked for now, bound to the row just saved.
-  {
-    const cloudUrls = [coder?.normalized?.url, agent?.normalized?.url].filter(
-      (u, i, all) => u && all.indexOf(u) === i && isOllamaCloudUrl(u)
-    );
-    if (cloudUrls.length) {
-      const fresh = await withPendingStatus("checking the Ollama cloud key", fetchWorkerSettings);
-      const keys = await fetchCodingKeys();
-      const ps = await import("./coding-provider-setup.mjs");
-      for (const u of cloudUrls) {
-        const found = ps.providerRowForUrl(ps.existingBackendRows(fresh ?? {}), u);
-        if (found && !am.boundKeyFor(keys, found.id)) {
-          console.log(yellow(`   ${hostOf(u)} is the Ollama cloud — it needs its own API key (the model list worked without one).`));
-          // The shared key prompt (task #245); the server's first key becomes its default.
-          const { name, secret } = await askServerKey({ host: hostOf(u) });
-          if (secret && !(await withPendingStatus("saving the key", () => addCodingKey(name, secret, found.id)))) {
-            console.log(red("   couldn't save the key — add it with ctrl+k.\n"));
-          }
-        }
-      }
-    }
-  }
-  // THE ACCOUNT DEFAULT JUST CHANGED — say so in memory, or the bar reports the old one.
-  //
-  // The override is cleared just below, correctly: what was picked here IS the account default
-  // now, so an override would be a duplicate of it. But the bar reads
-  // `sessionCodingLabel || defaultCodingModel`, and defaultCodingModel was read from the
-  // startup payload and never touched again. Clearing one while the other stayed stale is why
-  // the confirmation said gemma4 and the footer kept showing the old coder (reported
-  // 2026-09-05). Both halves of that expression have to be current, not one.
-  if (coder) {
-    defaultCodingModel = code;
-    defaultCodingUrl = coder.normalized.url;
-  }
-  // The session override names a model on the OLD box; leaving it set would send a name the new
-  // host has never heard of, with the settings now correct — the most confusing shape of all.
-  sessionCodingModel = "";
-  sessionCodingLabel = "";
-  sessionCodingUrl = "";
-  // Persist the CLEARING too. The stored override names a model on the OLD box; leaving it on
-  // disk would resurrect it at the next launch, against a server that has never heard of it.
-  await saveSessionCoding(resolve(process.cwd()));
-  await syncActiveCoderWhere(); // the bar now names the account default — with ITS host (#263)
-  // The GLOBAL output-token total is keyed to the coding backend (task #125), and the backend
-  // just moved — re-fetch it for the new one, exactly as /model does after a pick, or the
-  // footer keeps counting against the box that is no longer in use.
-  if (coder) {
-    const t = await fetchOutputTokenTotals(resolve(process.cwd()));
-    const g = pickGlobalTotal(t);
-    if (g !== null) globalOutputTokens = g;
-  }
-  paintBar(); // …and show all of it now, not at the next keystroke
-  console.log(accent(" ✓ models saved"));
-  if (agent) {
-    console.log(dim(`      chat   ${chat}  @ ${agent.normalized.host}`));
-    console.log(dim(`      RAG    ${os.defaultEmbedModel?.(agent.models) ?? os.REQUIRED_EMBED_MODEL}  @ ${agent.normalized.host}`));
-  } else {
-    console.log(dim("      chat   — not set (agent server skipped)"));
-  }
-  console.log(
-    coder
-      ? dim(`      code   ${code}  @ ${coder.normalized.host}`)
-      : dim("      code   — not set (coding server skipped)")
-  );
-  if (extras.length) console.log(dim(`      also   ${extras.join(", ")}  — offered by /model`));
-  // Compare to the embedder this box was seeded with — an accepted OTHER embedder (a
-  // qwen3-embedding-only box) was written to settings above, so REQUIRED_EMBED_MODEL would
-  // falsely scream "changed" while the seeded value is exactly what settings now hold.
-  const seededEmbed = agent ? (os.defaultEmbedModel?.(agent.models) ?? os.REQUIRED_EMBED_MODEL) : "";
-  // Only a CHANGE when there was an embedder before — from none it is simply set (task #36).
-  const prevEmbed = String(settings.ragEmbedModel ?? "").trim();
-  if (agent && prevEmbed && prevEmbed !== seededEmbed) {
-    console.log(dim("   the embedder changed — existing RAG indexes need rebuilding (/rag)."));
-  }
-  console.log(dim("   takes effect on your next question.\n"));
-}
-
 // ---------- fetch the ready-to-run agent payload from user settings ----------
 // /model command: fetch the allowed coding models (default + web-curated whitelist),
 // show a numbered picker, and set sessionCodingModel to the choice for this session.
@@ -6805,8 +6419,7 @@ async function changeProviderModel(ps, rows, p) {
     return;
   }
   // THE FOLDER'S PICK NAMES THE OLD MODEL. Leaving it would send a name this provider no longer
-  // offers, with the settings now correct — the most confusing shape there is (the same trap
-  // reconfigureOllamaServer clears its override for).
+  // offers, with the settings now correct — the most confusing shape there is.
   if (sessionCodingLabel === p.model || sessionCodingModel.endsWith(`::${p.model}`)) {
     sessionCodingModel = "";
     sessionCodingLabel = "";
@@ -7407,35 +7020,24 @@ async function chooseModel() {
     // through to add when there is genuinely nothing there.
     console.log(dim("   No coding model configured."));
     const go = await pickFromList(
-      [dim("leave it"), "add or change a provider — Claude API, OpenAI, Kimi…", "change the Ollama server this machine uses…"],
+      [dim("leave it"), "add or change a provider — Claude API, OpenAI, Kimi…"],
       1
     );
     if (go === 1) await manageCodingProviders();
-    else if (go === 2) await reconfigureOllamaServer();
     else console.log("");
     return;
   }
-  // ONE ENTRY THAT IS NOT A MODEL (task #220 req 6): re-point this machine at a different Ollama
-  // box. Offered HERE because /model is where someone already is when they discover the coder is
-  // wrong — and on a Client Expert machine there is no web app to go and change it in. Appended
-  // last so it never shifts the index of a model anyone has muscle memory for.
-  // …and shown even when there is only ONE model, because "only one is available" is often the
-  // symptom of being pointed at the wrong box, and the old message sent people to a web app a
-  // Client Expert machine does not have.
+  // Shown even with ONE model: "only one is available" often means the wrong server, and the
+  // provider manager is where another one is added (an Ollama box is "another URL…").
+  // #412 removed "change the Ollama server this machine uses…" from all three menus: it re-asked
+  // the agent, embedder and coder servers in one go, which confused people picking a model.
   if (choices.length === 1) {
     console.log(dim(`   Only one coding model is available: ${choices[0].model}.`));
-    // APPENDED AFTER the existing entry, here and below, so that entry keeps the index anyone
-    // who has used it already reaches for.
     const go = await pickFromList(
-      [
-        dim("keep it"),
-        "change the Ollama server this machine uses…",
-        "add or change a provider — Claude API, OpenAI, Kimi…",
-      ],
+      [dim("keep it"), "add or change a provider — Claude API, OpenAI, Kimi…"],
       0
     );
-    if (go === 1) await reconfigureOllamaServer();
-    else if (go === 2) await manageCodingProviders();
+    if (go === 1) await manageCodingProviders();
     else console.log("");
     return;
   }
@@ -7447,9 +7049,8 @@ async function chooseModel() {
   // OpenAI-compatible providers are both "OpenAI-compatible", so the kind names neither.
   const { labels, tags, showTag } = codingChoiceLabels(choices, def);
   const activeIdx = choices.findIndex((c) => c.id === active);
-  labels.push("change the Ollama server this machine uses…");
-  // Task #223. Appended LAST, after the #220 entry, for the same reason that one is appended
-  // after the models: a new row must never shift an index someone already has muscle memory for.
+  // Task #223. Appended LAST, after the models: a new row must never shift an index someone
+  // already has muscle memory for.
   //
   // "add or change" rather than "add", because add-only was a one-way door: a model id typed
   // wrong could not be corrected from anywhere, here or in web Settings. The entry leads to the
@@ -7470,11 +7071,9 @@ async function chooseModel() {
     console.log(dim("   (cancelled)\n"));
     return;
   }
-  // The appended entries sit past the last model, so they are the only indices without a choice.
-  // Their ORDER here must match the order they were pushed in, or a pick runs the other flow.
+  // The one appended entry sits past the last model.
   if (idx >= choices.length) {
-    if (idx === choices.length) await reconfigureOllamaServer();
-    else await manageCodingProviders();
+    await manageCodingProviders();
     return;
   }
   await applyChosenCoder(choices[idx], { def, tag: showTag ? tags[idx] : "" });
@@ -12389,6 +11988,10 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
   let thinking = false;
   let thinkingSince = 0;
   let thinkWord = pickWord(); // playful word shown UNDER the in-progress line (flavor)
+  // ONE TIP PER TURN (#234), under the word: stable for the whole turn (a tip that changed every few
+  // seconds would be read as flicker), never the one the previous turn showed.
+  const hintIdx = (lastHintIdx = pickHint(Math.random, lastHintIdx));
+  let blockHintRows = 0; // 1 while the tip row is part of the live block (see the click arithmetic)
   let lastWordBucket = -1; // 12s window index → rotate the word once per window (task: 30-spinner)
   let almostDone = false; // set from the worker's "…almost completed thinking…" heartbeat
   let runningCmd = null; // the command currently executing (from a "Running → …" event)
@@ -12657,7 +12260,13 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
     // redrawn continuously, so a blank written into the transcript would either accumulate one
     // per redraw or be stranded above a block that has since moved. Owned by the block, they
     // are erased with it — always exactly one, wherever it currently is. See LEAD_ROWS/WORD_GAP.
-    const drawn = 2 + LEAD_ROWS + WORD_GAP + expLines.length + detailRows.length;
+    // THE TIP (#234): after a few seconds of waiting, one dim row under the word. Not on a very
+    // short terminal, not with the animation off, and never wrapped.
+    const hintText = !stillStatus && hintIdx >= 0 && secs >= HINT_AFTER_SECONDS && hintFits(process.stdout.rows)
+      ? hintRow(HINTS[hintIdx], { width: Math.max(20, process.stdout.columns || 80), indent: visibleLen(GUTTER) })
+      : "";
+    blockHintRows = hintText ? 1 : 0;
+    const drawn = 2 + LEAD_ROWS + WORD_GAP + expLines.length + detailRows.length + blockHintRows;
     // The bottom bar rides along UNDER the live status while a turn runs, so it stays on screen
     // the whole time the agent is thinking instead of only at the prompt. It's part of the same
     // in-place block: the ticker redraws it every 120ms and clearStatus wipes it with the rest,
@@ -12728,6 +12337,7 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
     contentRows.push(
       clipRow(`${markLine(waitPaint(wc, glyph))}${waitPaint(wc, `${thinkWord}…`)}${outLabel}`)
     );
+    if (hintText) contentRows.push(clipRow(GUTTER + dim(hintText)));
     // PINNED → the block IS frozen rows; unpinned (a window too short to reserve any) there is
     // no zone, so it keeps the old in-place draw at the output position.
     if (barPinned()) {
@@ -12772,7 +12382,7 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
     //   LEAD_ROWS · thought · detail… · expansion… · WORD_GAP · word
     // so the responding rows run from `top` to the last expansion row — statusContentLines less
     // the fixed rows around them (the two gaps, the thought line and the word row).
-    if (row < top || row > top + statusContentLines - LEAD_ROWS - WORD_GAP - 2) return;
+    if (row < top || row > top + statusContentLines - LEAD_ROWS - WORD_GAP - 2 - blockHintRows) return;
     // Only meaningful when there IS a fuller thought to reveal; otherwise ignore the click
     // so we don't flicker an empty expand.
     if (!thoughtExpanded && !liveExpandable) return;
@@ -13979,7 +13589,7 @@ async function main() {
       void syncEmbedWarning({ repair: true });
     }
     // A RESTORED PICK MUST STILL EXIST. The stored id names a model on the box this folder was
-    // last pointed at — and the box can change (`/model` → change the Ollama server), a model
+    // last pointed at — and the server can change (`/model` → add or change a provider), a model
     // can be removed, or the folder can be opened on another machine entirely. Sending a name
     // the account no longer allows fails the FIRST TURN with "not in your allowed coding
     // models", which reads as a broken agent rather than as a stale preference.
@@ -14390,7 +14000,8 @@ async function main() {
           red("gu: this machine has no models set up yet.") +
             dim(
               "\n  Nothing can run until it knows which Ollama server to use." +
-                "\n  Start `gu`, then `/model` → change the Ollama server this machine uses." +
+                "\n  Start `gu`, then `/agent-model` → use an Ollama server, `/embed-model` for RAG," +
+                "\n  and `/model` → add a provider → another URL… for the coding model." +
                 `\n  The agent server needs a ${REQUIRED_AGENT_PREFIX} model (e.g. ${REQUIRED_AGENT_MODEL})` +
                 `\n  and any ONE of these embedders: ${ACCEPTED_EMBED_MODELS.map((m) => m.replace(/:latest$/, "")).join(", ")};` +
                 "\n  the agent and coding models are then yours to pick."

package/hints.mjs

@@ -0,0 +1,67 @@
+/**
+ * TIPS UNDER THE THINKING WORD (#234) — one line that teaches a command or a key while the model
+ * works, the way Claude Code's "⎿ Tip: …" does.
+ *
+ * Pure: the REPL picks one per turn and draws it under the playful word. Every "/command" named
+ * here must be a real one (hints.test.mjs checks them against the REPL's COMMANDS list), because a
+ * tip that names a command that does not exist is worse than no tip.
+ */
+
+export const HINTS = [
+  "/model switches the coding model for this session",
+  "/quick-models picks two models; then ← / → at the prompt flips between them",
+  "/agent-model switches the model that talks to you (the agent model)",
+  "Type / then Tab to complete a command; /help lists them all",
+  "shift+tab switches between accept edits and manually edit",
+  "ctrl+t opens the model's full thought while it works",
+  "ctrl+c stops the turn; type continue to pick it up again",
+  "ctrl+k replaces the coding model's API key without leaving the terminal",
+  "/new starts a new conversation in this folder — the old one is kept",
+  "/doctor checks that every configured model really answers",
+  "/tokens shows how big the last prompt was and how much of it was RAG",
+  "/prices shows what the last turn and this session cost",
+  "/context-window tells gu how big your coding model's context is",
+  "/mcp lists the MCP servers and adds one step by step",
+  "/hooks lists the commands gu runs on start, ask and turn end",
+  "/shells shows long commands the agent left running in the background",
+  "/budget shows your API provider balances (Pro)",
+  "/browser checks the gu Chrome extension the agent uses to click web pages",
+  "/support sends the gu team a request with your logs attached (secrets masked)",
+  "/clear-logs shows what gu's logs and indexes take on disk, then asks what to clear",
+  "/switch-skill chooses whose skills and MCP servers this folder uses: Claude's or gu's",
+  "/use-presets applies a saved setup after showing what changes",
+  "/save-settings writes your providers and models to a file you can load on another machine",
+];
+
+/**
+ * One tip index, never `last` when there is a choice (so two turns in a row do not repeat).
+ * `rand` is injectable (0 <= rand() < 1) for tests.
+ */
+export function pickHint(rand = Math.random, last = -1, list = HINTS) {
+  if (list.length === 0) return -1;
+  if (list.length === 1) return 0;
+  let i = Math.floor(rand() * list.length) % list.length;
+  if (i === last) i = (i + 1) % list.length;
+  return i;
+}
+
+/** The glyph and label in front of a tip — plain text, painted dim by the caller. */
+export const HINT_PREFIX = "⎿ Tip: ";
+
+/**
+ * The tip as ONE row no wider than `width` - 1 columns including `indent` spaces: cut with "…" and
+ * never wrapped (a wrapped row in the live block is the #109/#138 failure). "" when there is no room
+ * for anything readable.
+ */
+export function hintRow(text, { width = 80, indent = 3 } = {}) {
+  const room = Math.max(0, (width || 80) - 1 - indent);
+  const full = HINT_PREFIX + String(text ?? "").trim();
+  if (!String(text ?? "").trim() || room < 20) return "";
+  return full.length <= room ? full : full.slice(0, room - 1).replace(/\s+$/, "") + "…";
+}
+
+/** How long the model must have been working before the tip appears, in seconds. */
+export const HINT_AFTER_SECONDS = 4;
+
+/** Is there room for the tip row? Not on a very short terminal, where every row counts. */
+export const hintFits = (rows) => (rows || 24) >= 16;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.870",
+  "version": "1.0.871",
   "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",
@@ -114,6 +114,7 @@
     "ollama-setup.mjs",
     "s3-setup.mjs",
     "doctor-check.mjs",
+    "service-check.mjs",
     "embed-model-command.mjs",
     "proxy-command.mjs",
     "proxy-selftest.mjs",
@@ -123,6 +124,7 @@
     "coding-key-prompt.mjs",
     "model-fallback.mjs",
     "quick-models.mjs",
+    "hints.mjs",
     "terminal-title.mjs",
     "gu-relaunch.mjs",
     "server-keys.mjs",

package/service-check.mjs

@@ -0,0 +1,181 @@
+/**
+ * Can this machine reach the gu service — and if not, why? (task #413, GH #240)
+ *
+ *     node --test tests/service-check.test.mjs
+ *
+ * Reported on a Windows VM: the agent model answered "hi", but every coding turn failed with
+ * "the gu service couldn't be reached". The coding turn is the only one that needs the gu service:
+ * the local API fetches the agent's instructions from it first, with Node's plain fetch. The
+ * Python agent and the terminal's model calls reach the internet by other routes (the proxy,
+ * the system certificates), so "the internet works" and "the local API can't get out" are both
+ * true at once. The usual causes on a work machine need different fixes:
+ *
+ *   · a network that inspects HTTPS — Node does not trust its certificate, Python does
+ *   · a network that needs a proxy — the local API does not use gu's /proxy
+ *   · an address that is blocked or cannot be looked up
+ *
+ * So the check makes the request the local API makes, then the variations that tell the causes
+ * apart, and says which one it is. The decisions are pure (serviceVerdict) so they are tested
+ * without a network; checkGuService only gathers the facts.
+ */
+import { spawn } from "node:child_process";
+
+/** Why a fetch failed, as a kind, a code and words. Node says "fetch failed" and keeps the reason in `cause`. */
+export function describeNetError(err) {
+  if (err?.name === "TimeoutError" || err?.name === "AbortError") {
+    return { kind: "timeout", code: "TIMEOUT", words: "no answer in time" };
+  }
+  const code = String(err?.cause?.code ?? err?.code ?? "");
+  if (/CERT|SELF_SIGNED|UNABLE_TO_(GET|VERIFY)|ERR_TLS/i.test(code)) {
+    return { kind: "cert", code, words: "this computer doesn't trust the certificate it was shown" };
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") return { kind: "dns", code, words: "the address could not be looked up" };
+  if (["ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT", "ENETUNREACH", "EHOSTUNREACH"].includes(code)) {
+    return { kind: "blocked", code, words: code === "ECONNREFUSED" ? "the connection was refused" : code === "ECONNRESET" ? "the connection was cut" : "the connection didn't go through" };
+  }
+  return { kind: "other", code, words: code || String(err?.cause?.message ?? err?.message ?? err ?? "network error") };
+}
+
+/** One GET; any HTTP answer means the server was reached (401 included — no token was sent). */
+async function reach(url, { fetchImpl = fetch, dispatcher, timeoutMs = 10_000 } = {}) {
+  try {
+    const r = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs), ...(dispatcher ? { dispatcher } : {}) });
+    return { ok: true, status: r.status };
+  } catch (err) {
+    return { ok: false, ...describeNetError(err) };
+  }
+}
+
+/**
+ * The same request from a NODE STARTED WITH --use-system-ca: does trusting this computer's own
+ * certificates (Windows' store, macOS' keychain) fix it? A Node without the flag says "bad option".
+ */
+export function reachWithSystemCa(url, { execPath = process.execPath, timeoutMs = 15_000, spawnImpl = spawn } = {}) {
+  const script =
+    `fetch(${JSON.stringify(url)},{signal:AbortSignal.timeout(${timeoutMs - 3000})})` +
+    `.then(r=>process.stdout.write("ok "+r.status))` +
+    `.catch(e=>process.stdout.write("err "+((e.cause&&e.cause.code)||e.name||e.message)))`;
+  return new Promise((resolveP) => {
+    let out = "";
+    let err = "";
+    let child;
+    try {
+      child = spawnImpl(execPath, ["--use-system-ca", "-e", script], { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (e) {
+      resolveP({ ok: false, unsupported: false, words: e?.message ?? String(e) });
+      return;
+    }
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout?.on("data", (d) => { out += d; });
+    child.stderr?.on("data", (d) => { err += d; });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      resolveP({ ok: false, unsupported: false, words: e?.message ?? String(e) });
+    });
+    child.on("close", () => {
+      clearTimeout(timer);
+      if (/bad option|unknown option/i.test(err)) resolveP({ ok: false, unsupported: true, words: "" });
+      else if (out.startsWith("ok ")) resolveP({ ok: true, status: Number(out.slice(3)) });
+      else resolveP({ ok: false, unsupported: false, words: out.replace(/^err /, "") || err.trim().split("\n").pop() || "no answer" });
+    });
+  });
+}
+
+/**
+ * THE VERDICT, from the facts. Pure.
+ *
+ *   direct    { ok, status } | { ok:false, kind, words }   Node's plain fetch (what the local API does)
+ *   viaProxy  same, or null when no proxy is set
+ *   systemCa  { ok } | { ok:false, unsupported, words }, or null when not tried
+ *   localApi  { ok, version } | { ok:false, error }, or null when this machine has no local API
+ *
+ * Returns { ok, lines }: lines are for the terminal, a ✓ / ✗ line first and the reason after.
+ */
+export function serviceVerdict({ host, direct, viaProxy = null, systemCa = null, localApi = null, nodeVersion = process.version }) {
+  const lines = [];
+  if (localApi?.ok) {
+    lines.push(`✓ gu service — private mode can fetch the agent's instructions (v${localApi.version})`);
+    return { ok: true, lines };
+  }
+  if (direct.ok) {
+    if (!localApi) {
+      lines.push(`✓ gu service — ${host} answers`);
+      return { ok: true, lines };
+    }
+    lines.push(`✗ gu service — ${host} answers this computer, but the local API couldn't get the agent's instructions:`);
+    lines.push(`    ${localApi.error}`);
+    // A token problem says its own fix; anything else is most often a local API started before
+    // the network came up, or an older one.
+    if (!/gu token/.test(localApi.error)) lines.push("    restart the local API (`gu api restart`) and try again.");
+    return { ok: false, lines };
+  }
+  lines.push(`✗ gu service — ${host} can't be reached: ${direct.words}`);
+  lines.push("    a coding turn needs it (the agent's instructions come from it); a plain reply like \"hi\" does not.");
+  if (direct.kind === "cert") {
+    if (systemCa?.ok) {
+      lines.push("    It works when Node trusts this computer's own certificates: this network inspects HTTPS.");
+      lines.push("    gu doesn't start its local API that way yet (#413) — ask IT, or use another network meanwhile.");
+    } else if (systemCa?.unsupported) {
+      lines.push(`    This network probably inspects HTTPS. Node ${nodeVersion} can't use the system certificates;`);
+      lines.push("    Node 22.15 or newer can. Ask IT, or use another network.");
+    } else {
+      lines.push("    Even with this computer's own certificates it fails — ask IT which certificate the network uses.");
+    }
+  } else if (viaProxy?.ok) {
+    lines.push("    It works through your /proxy: this network needs it, and the local API doesn't use it yet (#413).");
+  } else if (viaProxy && !viaProxy.ok) {
+    lines.push(`    Through your /proxy it fails too: ${viaProxy.words}. Check the proxy settings with /proxy.`);
+  } else if (direct.kind === "dns") {
+    lines.push("    Check this computer's DNS, or whether the network blocks the address.");
+  } else {
+    lines.push(`    Allow ${host} on this network (firewall), or set /proxy if the network needs one.`);
+  }
+  if (localApi && !localApi.ok) lines.push(`    the local API says: ${localApi.error}`);
+  return { ok: false, lines };
+}
+
+/**
+ * Gather the facts and judge them. `hostedBase` is where the local API forwards to; `apiBase` +
+ * `workerKey` reach this machine's local API, asked only when `localApi` is true (Client Expert).
+ */
+export async function checkGuService({
+  hostedBase,
+  apiBase = "",
+  workerKey = "",
+  localApi = false,
+  proxy = null,
+  dispatcherFor = null,
+  fetchImpl = fetch,
+  systemCaImpl = reachWithSystemCa,
+  timeoutMs = 10_000,
+} = {}) {
+  const base = String(hostedBase ?? "").replace(/\/+$/, "");
+  const host = (() => { try { return new URL(base).host; } catch { return base; } })();
+  const url = `${base}/api/health`;
+  const direct = await reach(url, { fetchImpl, timeoutMs });
+
+  let viaProxy = null;
+  if (!direct.ok && proxy?.enabled && typeof dispatcherFor === "function") {
+    const dispatcher = await dispatcherFor(proxy).catch(() => null);
+    if (dispatcher) viaProxy = await reach(url, { fetchImpl, dispatcher, timeoutMs });
+  }
+  const systemCa = !direct.ok && direct.kind === "cert" ? await systemCaImpl(url) : null;
+
+  let local = null;
+  if (localApi && apiBase) {
+    try {
+      const r = await fetchImpl(`${apiBase.replace(/\/+$/, "")}/api/worker/prompt-scaffold/refresh`, {
+        method: "POST",
+        headers: { "X-Worker-Key": workerKey },
+        signal: AbortSignal.timeout(timeoutMs + 5000),
+      });
+      const body = await r.json().catch(() => null);
+      local = body?.ok
+        ? { ok: true, version: body.version }
+        : { ok: false, error: String(body?.error ?? `HTTP ${r.status}`) };
+    } catch (err) {
+      local = { ok: false, error: `the local API didn't answer (${describeNetError(err).words})` };
+    }
+  }
+  return serviceVerdict({ host, direct, viaProxy, systemCa, localApi: local });
+}