@tiens.nguyen/gu-cli 1.0.686

package/device-login.mjs

@@ -0,0 +1,212 @@
+// Device-pairing login for the gu CLI (task #127, Phase 1). Shared by both bins
+// (gu-cli.mjs and gu-repl.mjs) so `gu login` and the first-run
+// auto-prompt use the exact same flow. No secrets live here — the CLI obtains a worker key
+// only after an authenticated human approves in the browser.
+import { execFile } from "node:child_process";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import dotenv from "dotenv";
+
+export const DEFAULT_API_BASE = "https://chat-api-v2.gomarsic.cc";
+const ENV_FILE = join(homedir(), ".gonext", "worker.env");
+const POLL_INTERVAL_MS = 2500;
+const POLL_TIMEOUT_MS = 10 * 60_000; // matches the server's pairing TTL
+
+/** True when worker.env already has BOTH a key and an API base (task #127 BC1a). */
+export async function hasWorkerConfig() {
+  try {
+    const parsed = dotenv.parse(await readFile(ENV_FILE, "utf8"));
+    return Boolean(
+      String(parsed.GONEXT_WORKER_KEY ?? "").trim() &&
+        String(parsed.GONEXT_API_BASE ?? "").trim()
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write ~/.gonext/worker.env, PRESERVING every other setting already in it.
+ *
+ * This used to rewrite the file from scratch, keeping only GONEXT_POLL_MS — so re-running
+ * login (or saving a key) silently DELETED anything else the user had put there, e.g.
+ * GONEXT_SEARXNG_URL. Only the two values this function is actually responsible for are
+ * overwritten; the rest are read back and re-emitted untouched.
+ */
+async function writeWorkerEnv(apiBase, workerKey) {
+  let prev = {};
+  try {
+    prev = dotenv.parse(await readFile(ENV_FILE, "utf8"));
+  } catch {
+    /* first-time write */
+  }
+  const merged = {
+    ...prev,
+    GONEXT_API_BASE: apiBase.replace(/\/+$/, ""),
+    GONEXT_WORKER_KEY: workerKey,
+    GONEXT_POLL_MS: String(prev.GONEXT_POLL_MS ?? "").trim() || "500",
+  };
+  // Stable order: the three we own first, then whatever else the user had.
+  const head = ["GONEXT_API_BASE", "GONEXT_WORKER_KEY", "GONEXT_POLL_MS"];
+  const body = [
+    ...head.map((k) => `${k}=${merged[k]}`),
+    ...Object.keys(merged)
+      .filter((k) => !head.includes(k))
+      .map((k) => `${k}=${merged[k]}`),
+  ].join("\n");
+  await mkdir(join(homedir(), ".gonext"), { recursive: true });
+  await writeFile(ENV_FILE, `${body}\n`, { encoding: "utf8", mode: 0o600 });
+  return ENV_FILE;
+}
+
+/**
+ * Save a worker key the user already has, WITHOUT a browser round-trip (task #135).
+ *
+ * The pairing flow needs an authenticated browser session; someone who already has a key
+ * (from another machine, or Settings → reveal) shouldn't have to sign in again to reuse it.
+ * Validates against the API before writing, so a typo fails HERE with a clear message
+ * instead of turning into a confusing 403 on the first poll.
+ *
+ * Returns { apiBase, workerKey, envFile }. Throws with .code:
+ *   "KEY_REJECTED"  — the API says this key isn't valid for any account
+ *   "KEY_UNCHECKED" — couldn't reach the API to check (nothing written)
+ */
+export async function saveWorkerKey({ apiBase = DEFAULT_API_BASE, workerKey, log = console.log } = {}) {
+  const base = String(apiBase || DEFAULT_API_BASE).trim().replace(/\/+$/, "");
+  const key = String(workerKey || "").trim();
+  if (!key) {
+    const err = new Error("No worker key given.");
+    err.code = "KEY_REJECTED";
+    throw err;
+  }
+  // GET /api/worker/settings — worker-key authed and READ-ONLY. Deliberately NOT
+  // POST /jobs/next (the daemon's own call): that CLAIMS a pending job, so validating with
+  // it would snatch real work and discard it, leaving that job stuck. A key check must have
+  // no side effects. 200 = valid, 401/403 = wrong key, anything else = server-side, which is
+  // not a verdict on the key.
+  let res;
+  try {
+    res = await fetch(`${base}/api/worker/settings`, {
+      method: "GET",
+      headers: { "X-Worker-Key": key },
+    });
+  } catch (e) {
+    const err = new Error(`Could not reach ${base} to check the key: ${e instanceof Error ? e.message : e}`);
+    err.code = "KEY_UNCHECKED";
+    throw err;
+  }
+  if (res.status === 401 || res.status === 403) {
+    const err = new Error("That worker key was rejected — it isn't registered to any account.");
+    err.code = "KEY_REJECTED";
+    throw err;
+  }
+  if (!res.ok) {
+    // 503 = persistence not configured server-side, 5xx = outage, 404 = an API too old to
+    // have this route. None of those say the KEY is bad, so don't claim it is.
+    const err = new Error(
+      `${base} couldn't verify the key right now (HTTP ${res.status}). Nothing was saved.`
+    );
+    err.code = "KEY_UNCHECKED";
+    throw err;
+  }
+  const envFile = await writeWorkerEnv(base, key);
+  log(`  ✓ Saved ${envFile}`);
+  return { apiBase: base, workerKey: key, envFile };
+}
+
+function openBrowser(url) {
+  const cmd =
+    platform() === "darwin" ? "open" : platform() === "win32" ? "start" : "xdg-open";
+  try {
+    execFile(cmd, [url], () => {}); // best-effort; the URL is also printed
+  } catch {
+    /* the user can open it manually */
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Run the browser device-pairing flow and write worker.env on success.
+ *
+ * Returns { apiBase, workerKey, envFile } on success.
+ * Throws Error with .code === "PAIRING_UNSUPPORTED" when the API has no /pair routes
+ *   (404), so callers can fall back to the manual `set` path (task #127 BC7).
+ * Throws Error with .code === "PAIRING_TIMEOUT" / "PAIRING_EXPIRED" otherwise.
+ *
+ * `log` is an injectable printer (defaults to console.log) so the REPL can style it.
+ */
+export async function deviceLogin({ apiBase = DEFAULT_API_BASE, log = console.log } = {}) {
+  const base = String(apiBase || DEFAULT_API_BASE).trim().replace(/\/+$/, "");
+  let start;
+  try {
+    const res = await fetch(`${base}/api/pair/start`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ apiBase: base }),
+    });
+    if (res.status === 404) {
+      const err = new Error("This API does not support CLI login (device pairing).");
+      err.code = "PAIRING_UNSUPPORTED";
+      throw err;
+    }
+    if (!res.ok) {
+      throw new Error(`pairing start failed (HTTP ${res.status})`);
+    }
+    start = await res.json();
+  } catch (e) {
+    if (e && e.code === "PAIRING_UNSUPPORTED") throw e;
+    // A network failure to a base that has no /pair yet also can't pair — surface as
+    // unsupported so the caller offers manual setup rather than looping.
+    const err = new Error(
+      `Could not reach ${base} to start login: ${e instanceof Error ? e.message : e}`
+    );
+    err.code = "PAIRING_UNSUPPORTED";
+    throw err;
+  }
+
+  const { pairId, pairCode, verificationUrlBase } = start;
+  const url = `${verificationUrlBase || `${base}/link`}?code=${encodeURIComponent(pairCode)}`;
+  log("");
+  log("  To connect this machine, sign in and approve this code in your browser:");
+  log("");
+  log(`      code:  ${pairCode}`);
+  log(`      url:   ${url}`);
+  log("");
+  log("  (opening your browser… if it doesn't, paste the url above)");
+  log("");
+  openBrowser(url);
+
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    let poll;
+    try {
+      const res = await fetch(`${base}/api/pair/poll`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ pairId }),
+      });
+      if (!res.ok) continue; // transient — keep polling
+      poll = await res.json();
+    } catch {
+      continue; // network blip — keep polling
+    }
+    if (poll.status === "approved" && poll.workerApiKey) {
+      const finalBase = String(poll.apiBase || base).trim().replace(/\/+$/, "");
+      const envFile = await writeWorkerEnv(finalBase, poll.workerApiKey);
+      log(`  ✓ Linked. Saved ${envFile}`);
+      return { apiBase: finalBase, workerKey: poll.workerApiKey, envFile };
+    }
+    if (poll.status === "expired") {
+      const err = new Error("Login code expired before it was approved. Run `gu login` again.");
+      err.code = "PAIRING_EXPIRED";
+      throw err;
+    }
+    // "pending" / "consumed" → keep waiting (consumed by a racing poll is unlikely).
+  }
+  const err = new Error("Login timed out waiting for browser approval.");
+  err.code = "PAIRING_TIMEOUT";
+  throw err;
+}

package/doctor-check.mjs

@@ -0,0 +1,239 @@
+/**
+ * `/doctor` — does each configured model actually ANSWER? (task #224)
+ *
+ * WHY A PROBE IS NOT ENOUGH, which is the whole reason this exists. Everything that checked
+ * models before this asked "is the server reachable": GET /api/tags, a TCP connect, a 200 from
+ * the root. On 2026-09-05 every one of those passed while the embedder was completely blocked —
+ * ollama2 answered /api/tags instantly, and a single embed of the word "hello" returned NOTHING
+ * IN 180 SECONDS, because a 30GB coder was pinned in VRAM `UNTIL: Forever` and there was no room
+ * to load a 274MB embedding model. Ollama queued the request rather than evicting.
+ *
+ * The user found out the way you always find that out: several minutes into a real turn, when
+ * the agent decided it wanted a knowledge base. Their words: "add a slash doctor to check if the
+ * embed is working because it will take some steps to trigger the model to call the embed."
+ *
+ * So every check here SENDS THE REAL REQUEST the agent would send, and every check has a
+ * deadline. A model that cannot answer in the budget is reported as such — not as "unreachable",
+ * which sends the reader to their network, and not as a hang.
+ *
+ * PURE-ISH: `fetchImpl` and the clock are injected, so every branch — including the ones that
+ * need a server that never answers — runs offline in a test.
+ */
+
+/** The three roles a machine configures, in the order a turn uses them. */
+export const ROLES = ["chat", "code", "embed"];
+
+/** Ollama's native face, from an OpenAI-compatible base ("…/v1" → "…"). */
+export function nativeRoot(url) {
+  return String(url ?? "").trim().replace(/\/+$/, "").replace(/\/v1$/i, "");
+}
+
+/**
+ * What this machine is configured to use, per role — read from the settings row, never
+ * defaulted here.
+ *
+ * A check that supplies its own URL passes happily on a machine where the agent cannot reach
+ * anything, which is the failure rag-selftest's header already warns about. If a role is not
+ * configured, that IS the finding.
+ */
+export function rolesFromSettings(s) {
+  const str = (v) => String(v ?? "").trim();
+  return [
+    {
+      role: "chat",
+      label: "chat model",
+      why: "answers and routes every turn",
+      url: str(s?.agentModelUrl),
+      model: str(s?.agentModelName) || str(s?.agentModel),
+    },
+    {
+      role: "code",
+      label: "coding model",
+      why: "writes the code",
+      url: str(s?.agentCodingModelUrl) || str(s?.agentModelUrl),
+      model: str(s?.agentCodingModelName),
+    },
+    {
+      role: "embed",
+      label: "embedder",
+      why: "RAG — only called once a turn needs a knowledge base",
+      url: str(s?.ragEmbedUrl),
+      model: str(s?.ragEmbedModel),
+    },
+  ];
+}
+
+/**
+ * WHY a model that will not answer is not answering, when the host is an Ollama.
+ *
+ * The single most useful thing this whole command does, because the answer is invisible from
+ * the outside: /api/ps says what is RESIDENT, and a box whose VRAM is full of something else
+ * cannot load what you just asked for — it queues you instead. That reads identically to a slow
+ * model, a bad URL and a wrong model name, and it is none of them.
+ *
+ * Returns null when the question does not apply (not an Ollama, or it will not say).
+ */
+export async function diagnoseOllamaBusy(url, { fetchImpl = fetch, timeoutMs = 8000 } = {}) {
+  const root = nativeRoot(url);
+  if (!root) return null;
+  let body;
+  try {
+    const res = await fetchImpl(`${root}/api/ps`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return null;
+    body = await res.json();
+  } catch {
+    return null; // not an Ollama, or it is not answering either — the caller already knows
+  }
+  const models = Array.isArray(body?.models) ? body.models : [];
+  if (!models.length) return { loaded: [], hint: "" };
+  const loaded = models.map((m) => ({
+    name: String(m?.name ?? m?.model ?? ""),
+    gb: Math.round(((Number(m?.size) || 0) / 1e9) * 10) / 10,
+    vramGb: Math.round(((Number(m?.size_vram) || 0) / 1e9) * 10) / 10,
+  }));
+  const biggest = [...loaded].sort((a, b) => b.vramGb - a.vramGb)[0];
+  return {
+    loaded,
+    // Named, with its size, and with the ONE command that frees it. "The GPU is busy" is a
+    // diagnosis; `ollama stop <name>` is a fix.
+    hint: biggest?.vramGb
+      ? `${biggest.name} is holding ${biggest.vramGb}GB of VRAM — nothing else can load ` +
+        `until it is released. On that host: \`ollama stop ${biggest.name}\` ` +
+        "(and set a finite OLLAMA_KEEP_ALIVE so it does not pin itself again)."
+      : "",
+  };
+}
+
+/**
+ * Send the request the agent would send, and time it.
+ *
+ * `kind` picks the endpoint, because the roles are not interchangeable: an embedder does not
+ * answer /chat/completions and a chat model does not answer /embeddings. Asking the wrong one
+ * reports a healthy model as broken, which is the mistake this command exists to stop making.
+ */
+export function requestFor(kind, model) {
+  if (kind === "embed") {
+    return { path: "/embeddings", body: { model, input: ["gu doctor"] } };
+  }
+  return {
+    path: "/chat/completions",
+    body: { model, messages: [{ role: "user", content: "Reply with OK." }], max_tokens: 4,
+            stream: false },
+  };
+}
+
+/** Did the body actually carry what that endpoint is supposed to return? */
+export function bodyIsUsable(kind, body) {
+  if (kind === "embed") {
+    const v = body?.data?.[0]?.embedding ?? body?.embeddings?.[0];
+    return Array.isArray(v) && v.length > 0 ? { ok: true, detail: `${v.length}-dim vector` } : {
+      ok: false, detail: "answered, but returned no vector",
+    };
+  }
+  const text = body?.choices?.[0]?.message?.content;
+  return typeof text === "string"
+    ? { ok: true, detail: "answered" }
+    : { ok: false, detail: "answered, but returned no message" };
+}
+
+/**
+ * One role, one real round trip.
+ *
+ * The status is deliberately finer than ok/failed, because the four causes need four different
+ * actions and were previously all reported as "isn't responding":
+ *
+ *   ok           it answered, with something usable
+ *   unset        nothing is configured for this role — not a failure, a gap
+ *   timeout      it accepted the request and did not answer inside the budget. THE case this
+ *                command was built for: a full GPU queues rather than refuses.
+ *   unreachable  nothing answered at all — DNS, a dead port, a proxy
+ *   error        it answered with a refusal (a 404 model name, a 401 key, a 400 shape)
+ */
+export async function checkRole(
+  r,
+  { fetchImpl = fetch, timeoutMs = 25_000, now = () => Date.now() } = {},
+) {
+  const base = { role: r.role, label: r.label, why: r.why, url: r.url, model: r.model };
+  if (!r.url) return { ...base, status: "unset", ms: 0, detail: "no server configured" };
+  if (!r.model) return { ...base, status: "unset", ms: 0, detail: "no model name configured" };
+
+  const kind = r.role === "embed" ? "embed" : "chat";
+  const { path, body } = requestFor(kind, r.model);
+  const root = String(r.url).replace(/\/+$/, "");
+  const endpoint = /\/v1$/i.test(root) ? `${root}${path}` : `${root}/v1${path}`;
+  const t0 = now();
+  let res;
+  try {
+    res = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    const ms = now() - t0;
+    // A TIMEOUT IS NOT AN OUTAGE, and conflating them is what sent the last investigation to
+    // the network for an hour. The connection was accepted; the model never got scheduled.
+    const timedOut =
+      e?.name === "TimeoutError" || e?.name === "AbortError" || /timed?\s?out/i.test(String(e?.message));
+    return timedOut
+      ? { ...base, status: "timeout", ms, detail: `no answer in ${Math.round(ms / 1000)}s` }
+      : { ...base, status: "unreachable", ms, detail: String(e?.cause?.code || e?.message || e) };
+  }
+  const ms = now() - t0;
+  if (!res.ok) {
+    let extra = "";
+    try {
+      extra = (await res.text()).slice(0, 120).replace(/\s+/g, " ").trim();
+    } catch { /* a body we cannot read is not worth failing over */ }
+    return { ...base, status: "error", ms, detail: `HTTP ${res.status}${extra ? ` — ${extra}` : ""}` };
+  }
+  let parsed;
+  try {
+    parsed = await res.json();
+  } catch {
+    return { ...base, status: "error", ms, detail: "answered with something that is not JSON" };
+  }
+  const usable = bodyIsUsable(kind, parsed);
+  return { ...base, status: usable.ok ? "ok" : "error", ms, detail: usable.detail };
+}
+
+/**
+ * Every role, in turn, plus a reason when one of them stalled.
+ *
+ * SEQUENTIAL, NOT PARALLEL, and that is a real decision rather than laziness: these share one
+ * GPU. Three concurrent requests make them queue behind each other and every one of them looks
+ * slow — the command would manufacture the symptom it is trying to measure.
+ */
+export async function runDoctor(settings, opts = {}) {
+  const roles = rolesFromSettings(settings);
+  const results = [];
+  for (const r of roles) {
+    const res = await checkRole(r, opts);
+    // Only ask WHY when something actually stalled. /api/ps on a healthy box is noise, and on a
+    // busy one it is the answer.
+    if (res.status === "timeout") {
+      res.busy = await diagnoseOllamaBusy(r.url, opts);
+    }
+    results.push(res);
+  }
+  return { results, ok: results.every((r) => r.status === "ok") };
+}
+
+/** One line per role, for the terminal. Pure, so the wording is testable. */
+export function doctorLines(results) {
+  const mark = { ok: "✓", unset: "·", timeout: "✗", unreachable: "✗", error: "✗" };
+  const out = [];
+  for (const r of results) {
+    const secs = r.ms >= 1000 ? ` ${(r.ms / 1000).toFixed(1)}s` : r.ms ? ` ${r.ms}ms` : "";
+    out.push(`${mark[r.status] ?? "?"} ${r.label}  ${r.model || "(no model)"}${secs} — ${r.detail}`);
+    if (r.status === "timeout") {
+      // The distinction that took an hour to find, said in one line.
+      out.push("    it ACCEPTED the request and never answered — the server is up, the model");
+      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");
+  }
+  return out;
+}

package/embed-model-command.mjs

@@ -0,0 +1,157 @@
+/**
+ * `/embed-model` — choosing the embedder, and dealing with what that does to the index (#169).
+ *
+ * SEPARATE FROM THE REPL because the interesting part is not the picker, it is the CONSEQUENCE.
+ * Everything here is a pure function of (what is set, what was chosen, what is on disk); the REPL
+ * keeps only the fetch, the write and the printing. That split is what lets the case that matters
+ * — "you are about to make four knowledge bases unreadable" — be tested without indexing anything.
+ *
+ * WHY THE LIST IS HARDCODED AND /agent-model's IS NOT. An embedder is not interchangeable the way
+ * a chat model is: it decides the shape of every vector already on disk. Offering everything
+ * GET /api/tags returns would invite picking a chat model as an embedder — which does not fail at
+ * the point of choice, where the mistake is obvious, but much later at retrieval, as slightly
+ * worse answers. Two known-good embedders, named here, is the whole list on purpose.
+ */
+
+/**
+ * The embedders we support, most capable first.
+ *
+ * `dims` is what each model actually returns, recorded so a plan can say "768 → 4096" rather than
+ * the vaguer "the vectors are not comparable". It is documentation, not a probe: the manifest on
+ * disk carries the real number for an index that already exists.
+ */
+export const EMBED_CHOICES = [
+  {
+    model: "qwen3-embedding:8b",
+    dims: 4096,
+    note: "best recall, ~18× slower to index",
+  },
+  {
+    model: "nomic-embed-text:latest",
+    dims: 768,
+    note: "same recall on code, far faster (default)",
+  },
+];
+
+/** The one Client Expert seeds, and the one to fall back on when nothing is set. */
+export const DEFAULT_EMBED_MODEL = "nomic-embed-text:latest";
+
+/**
+ * Are these the same model to Ollama?
+ *
+ * "nomic-embed-text" and "nomic-embed-text:latest" name one model, and the settings field may
+ * carry the tag or not depending on who wrote it. Comparing raw strings would report a change
+ * that never happened — and then invalidate a perfectly good index over it. Mirrors _same_model
+ * in gonext_agent_chat.py (_rag_index_model_matches), which is the check that actually refuses a
+ * mismatched index at search time; if one of the two ever moves, the other has to move with it.
+ */
+export function sameEmbedModel(a, b) {
+  const norm = (x) => {
+    const s = String(x ?? "").trim();
+    return s.endsWith(":latest") ? s.slice(0, -":latest".length) : s;
+  };
+  const na = norm(a);
+  const nb = norm(b);
+  return na !== "" && na === nb;
+}
+
+/** What is set right now, as the settings row reports it (empty → the seeded default). */
+export function currentEmbedModel(settings) {
+  return String(settings?.ragEmbedModel ?? "").trim() || DEFAULT_EMBED_MODEL;
+}
+
+/**
+ * The picker's rows: every supported embedder, with the active one marked (requirement 6 — a
+ * picker that does not say where you are makes a no-op indistinguishable from a change).
+ *
+ * A model that is configured but NOT one of ours still gets a row, marked as current. Dropping it
+ * would mean the list silently disagrees with the machine, and re-picking would look like a
+ * change when it is not. Someone set it deliberately; show it.
+ */
+export function embedChoiceRows(current) {
+  const rows = EMBED_CHOICES.map((c) => ({ ...c, current: sameEmbedModel(c.model, current) }));
+  if (!rows.some((r) => r.current) && String(current ?? "").trim()) {
+    rows.push({
+      model: String(current).trim(),
+      dims: 0,
+      note: "configured on this machine",
+      current: true,
+    });
+  }
+  return rows;
+}
+
+/**
+ * WHAT SWITCHING EMBEDDERS DOES TO WHAT IS ALREADY INDEXED — the half of this command that is
+ * not a menu.
+ *
+ * Vectors from two models are not in the same space, and usually not even the same length. The
+ * failure is not an error: cosine over mismatched lengths returns a number, rag_search still
+ * prints its top-k with scores, and the model still reasons from them. So the question a plan has
+ * to answer is not "did the setting change" but "which knowledge bases stop being readable".
+ *
+ * `indexes` is listLocalRagIndexes() output — [{ source, model, dims, chunks, ... }]. An index
+ * whose manifest never recorded a model (`model: "?"`) counts as STALE rather than kept: unknown
+ * provenance is exactly the case that cannot be verified, and guessing "it is probably fine" is
+ * how a silent failure survives.
+ *
+ * Returns { changed, from, to, stale, kept, unknownProvenance } — the REPL turns it into prose.
+ */
+export function embedChangePlan({ current, chosen, indexes = [] } = {}) {
+  const from = String(current ?? "").trim();
+  const to = String(chosen ?? "").trim();
+  const changed = Boolean(to) && !sameEmbedModel(from, to);
+  const rows = Array.isArray(indexes) ? indexes : [];
+  const stale = [];
+  const kept = [];
+  for (const r of rows) {
+    const builtWith = String(r?.model ?? "").trim();
+    // Not "no chunks, no problem": a manifest with zero chunks still keys a directory that the
+    // next index writes into, and reporting it keeps the count honest against `gu status`.
+    if (!changed) {
+      kept.push(r);
+      continue;
+    }
+    (sameEmbedModel(builtWith, to) ? kept : stale).push(r);
+  }
+  return {
+    changed,
+    from,
+    to,
+    stale,
+    kept,
+    unknownProvenance: stale.filter((r) => !String(r?.model ?? "").trim() || r.model === "?"),
+  };
+}
+
+/**
+ * The plan as lines a human reads before committing to it.
+ *
+ * Deliberately concrete — source, model, chunk count — because the abstract version ("your index
+ * will be invalidated") is the one people click through. Says what will HAPPEN to each index, and
+ * never claims the data is gone when it is only unreadable.
+ */
+export function describeEmbedChange(plan) {
+  if (!plan?.changed) return [`already using ${plan?.to || plan?.from || "(none)"} — nothing to do.`];
+  const lines = [`embedding model  ${plan.from || "(unset)"} → ${plan.to}`];
+  if (plan.stale.length === 0) {
+    lines.push("nothing indexed with the old model — no knowledge base is affected.");
+    return lines;
+  }
+  const chunks = plan.stale.reduce((n, r) => n + (Number(r?.chunks) || 0), 0);
+  lines.push(
+    `${plan.stale.length} knowledge base${plan.stale.length === 1 ? "" : "s"} ` +
+      `(${chunks} chunk${chunks === 1 ? "" : "s"}) were built with a different embedder:`
+  );
+  for (const r of plan.stale.slice(0, 8)) {
+    const built = String(r?.model ?? "").trim() || "?";
+    const dims = Number(r?.dims) || 0;
+    lines.push(`  ${r?.source ?? "?"}  · built with ${built}${dims ? ` (${dims}d)` : ""}`);
+  }
+  if (plan.stale.length > 8) lines.push(`  …and ${plan.stale.length - 8} more`);
+  // The truthful description of what the code already does: _rag_index_model_matches makes
+  // rag_search treat a mismatched index as ABSENT, and the auto-index path then rebuilds it on
+  // the next search. Not "your data is deleted", and not "it still works".
+  lines.push("They will be ignored at search time and rebuilt on the next search.");
+  return lines;
+}