@tiens.nguyen/gu-cli 1.0.686

package/model-doctor.mjs

@@ -0,0 +1,1494 @@
+// Model bootstrap for the gu CLI (task #127, Phase 3). Ensures the base CHAT model
+// (mlx_lm.server) is downloaded and RUNNING so a fresh Mac can answer without GoTerminal or
+// the Wizard doing it. The agent CODE model (Ollama) is probed + guided, not auto-pulled.
+//
+// BC3 (task #127): NEVER touch a model that is already running. The doctor probes first and
+// does nothing when a server answers — it will not kill, restart, re-port, or re-download a
+// model the user already runs (many run mlx_lm.server themselves on 8090, or point at a
+// remote box). Downloads happen only when the model dir is genuinely absent AND the user
+// opts in.
+import { spawn, execFile } from "node:child_process";
+import { open, mkdir, readdir, writeFile } from "node:fs/promises";
+import { arch, homedir, platform, totalmem } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Minimum RAM to run the default 14B-4bit chat model comfortably on Apple Silicon.
+const MIN_CHAT_RAM_GB = 16;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+// The RAG embedding model + server (task #127 — parity with the Wizard's model-embed step).
+// EMBED_PID_FILE / EMBED_LOG_FILE (which need DIR) are defined below, after DIR.
+export const EMBED_REPO = "mlx-community/Qwen3-Embedding-8B-4bit-DWQ";
+export const EMBED_DIR = join(homedir(), "mlx-models", "Qwen3-Embedding-8B-4bit-DWQ");
+export const EMBED_PORT = 8085;
+const EMBED_SCRIPT = fileURLToPath(new URL("./gonext_mlx_embed.py", import.meta.url));
+
+/**
+ * The python the worker uses to run its agent / model tooling (mirrors the daemon).
+ *
+ * Windows has no `python3`, and the name that IS on PATH there is usually the Microsoft Store
+ * alias stub, which exits without running anything. `py` is the launcher the official
+ * installer registers. Reported live: `gu-cli doctor` on Windows 11 said "python3 not
+ * found" on a machine with a working Python.
+ *
+ * platform-ok: this is a SYNC default, deliberately — python3Bin() is called inline from a
+ * dozen places. resolvePython() in platform-tools.mjs is the authoritative version and PROVES
+ * the interpreter runs; this only has to stop naming one that cannot exist.
+ */
+function python3Bin() {
+  const explicit = (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "").trim();
+  if (explicit) return explicit;
+  return process.platform === "win32" ? "py" : "python3";
+}
+
+/**
+ * How to install Python HERE. The advice used to say "Xcode Command Line Tools" on every
+ * platform, which a Windows user cannot act on at all.
+ */
+export function pythonInstallHint(platform = process.platform) {
+  if (platform === "win32") return "winget install Python.Python.3.12, or python.org";
+  if (platform === "darwin") return "Xcode Command Line Tools, or python.org";
+  return "your package manager, e.g. sudo apt install python3";
+}
+
+/** True when `python3 -c "import <mod>"` succeeds — i.e. the module is installed. */
+function pyHasModule(mod) {
+  return new Promise((resolve) => {
+    execFile(python3Bin(), ["-c", `import ${mod}`], (err) => resolve(!err));
+  });
+}
+
+/**
+ * True when the agent framework can actually be imported. Checked INDEPENDENTLY of any model
+ * server (task #134): the deps offer used to be reached only when the chat model was down, so
+ * a client pointing at a healthy REMOTE model was never offered them and every turn died with
+ * "No module named 'smolagents'".
+ */
+export async function hasAgentLibs() {
+  return (await pyHasModule("smolagents")) && (await pyHasModule("openai"));
+}
+
+/**
+ * The ABSOLUTE path of the interpreter `python3Bin()` resolves to right now (sys.executable).
+ * "python3" is resolved from PATH at spawn time, and the interactive shell's PATH is often
+ * NOT the detached daemon's — with conda active, `gu doctor` installs into
+ * ~/miniconda3/.../site-packages while the daemon runs /usr/bin/python3 and still reports
+ * "No module named 'smolagents'" (observed live on a client machine). Pinning the exact
+ * interpreter that received the packages is what makes the install stick.
+ */
+export function resolvePythonPath() {
+  return new Promise((resolve) => {
+    execFile(python3Bin(), ["-c", "import sys; print(sys.executable)"], (err, stdout) =>
+      resolve(err ? "" : String(stdout).trim())
+    );
+  });
+}
+
+/**
+ * Persist that interpreter into ~/.gonext/worker.env as GONEXT_PROBE_PYTHON, so every future
+ * daemon uses it regardless of the PATH it happens to start with. Merges — never rewrites the
+ * file from scratch. Returns the path written, or "" when nothing needed doing.
+ */
+export async function pinPythonForDaemon({ log = () => {} } = {}) {
+  const exe = await resolvePythonPath();
+  if (!exe) return "";
+  const envFile = join(DIR, "worker.env");
+  let prev = "";
+  try {
+    prev = await (await import("node:fs/promises")).readFile(envFile, "utf8");
+  } catch {
+    /* not configured yet — nothing to pin into */
+  }
+  if (!prev) return "";
+  if (new RegExp(`^GONEXT_PROBE_PYTHON=${exe.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "m").test(prev)) {
+    return exe; // already pinned to this interpreter
+  }
+  const withoutOld = prev.replace(/^GONEXT_PROBE_PYTHON=.*$\n?/m, "");
+  const next = `${withoutOld.replace(/\n*$/, "\n")}GONEXT_PROBE_PYTHON=${exe}\n`;
+  await (await import("node:fs/promises")).writeFile(envFile, next, { encoding: "utf8", mode: 0o600 });
+  log(`  · pinned the agent's python to ${exe}`);
+  log("    (the background worker must use the SAME interpreter these packages went into)");
+  return exe;
+}
+
+/**
+ * Is this pip failure PEP 668 — a python the OS manages and refuses to let pip touch?
+ *
+ * Ubuntu 24.04, Debian 12+ and Fedora 38+ all ship one. `pip install` there exits non-zero with
+ * "error: externally-managed-environment" and installs nothing, which is why doctor's own advice
+ * ("python3 -m pip install -U smolagents openai") could not work on any current Linux: the
+ * command it printed was the command that fails. Found by running a real Ubuntu 24.04 container.
+ *
+ * Pure and exported so the branch is testable without a distro that has the marker file.
+ */
+export function isExternallyManaged(output) {
+  // BOTH wordings, because pip prints the words in opposite orders in the same failure: the
+  // machine-readable "error: externally-managed-environment" and the human "× This environment
+  // is externally managed". Matching only the first passed a test written from memory and
+  // missed half of the real output.
+  return /externally[\s-]?managed/i.test(String(output ?? ""));
+}
+
+/** Run pip once. Resolves { code, err } — never rejects, so the caller owns the policy. */
+function runPip(python, pkgs, extraArgs = []) {
+  return new Promise((resolve) => {
+    const child = spawn(python, ["-m", "pip", "install", "-U", ...extraArgs, ...pkgs], {
+      // stderr is PIPED so the PEP 668 marker can be recognised, and echoed as it arrives so
+      // the user still watches a real install rather than a frozen line.
+      stdio: ["ignore", "inherit", "pipe"],
+      env: process.env,
+    });
+    let err = "";
+    child.stderr?.on("data", (d) => {
+      const s = String(d);
+      err += s;
+      process.stderr.write(s);
+    });
+    child.on("exit", (code) => resolve({ code: code ?? 1, err }));
+    child.on("error", (e) => resolve({ code: -1, err: String(e?.message ?? e) }));
+  });
+}
+
+/**
+ * A private virtualenv at ~/.gonext/venv, created on demand. → its python, or "".
+ *
+ * THE RIGHT ANSWER TO PEP 668, and the machinery for it already existed: the daemon's
+ * interpreter is pinned through GONEXT_PROBE_PYTHON precisely so the packages and the process
+ * that imports them cannot drift apart. A venv is that same idea, one step earlier.
+ *
+ * Preferred over --break-system-packages because pip's own message is right — writing into a
+ * distro-managed python can conflict with apt's copies of the same libraries and leave the
+ * system's own tooling broken. A venv is removable; a mangled system python is a reinstall.
+ */
+async function ensureVenv(log) {
+  const { existsSync } = await import("node:fs");
+  const venvDir = join(DIR, "venv");
+  const py = join(venvDir, process.platform === "win32" ? "Scripts" : "bin",
+                  process.platform === "win32" ? "python.exe" : "python");
+  if (existsSync(py)) return py;
+  log(`  creating a private virtualenv at ${venvDir} …`);
+  const made = await new Promise((resolve) => {
+    const child = spawn(python3Bin(), ["-m", "venv", venvDir], { stdio: ["ignore", "inherit", "inherit"], env: process.env });
+    child.on("exit", (code) => resolve(code === 0));
+    child.on("error", () => resolve(false));
+  });
+  if (made && existsSync(py)) return py;
+  // Debian/Ubuntu split venv into its own package, so this is a real and common outcome.
+  log("  ⚠ could not create a virtualenv (on Debian/Ubuntu: sudo apt install python3-venv)");
+  return "";
+}
+
+/**
+ * pip install -U <pkgs>, on a python that may refuse to be written to.
+ *
+ * Three attempts, in the order of least damage: the plain install; then a private venv, whose
+ * interpreter is PINNED so the daemon uses the same one the packages went into; and only if a
+ * venv cannot be built, --break-system-packages, which is announced rather than done quietly.
+ */
+async function pipInstall(pkgs, log) {
+  log(`  installing ${pkgs.join(" ")} … (pip, this can take a minute)`);
+  let r = await runPip(python3Bin(), pkgs);
+  if (r.code === 0) return;
+  if (!isExternallyManaged(r.err)) {
+    throw new Error(`pip install ${pkgs.join(" ")} exited ${r.code}`);
+  }
+
+  log("  this python is managed by your OS (PEP 668) — it will not accept packages directly.");
+  const venvPy = await ensureVenv(log);
+  if (venvPy) {
+    r = await runPip(venvPy, pkgs);
+    if (r.code === 0) {
+      // Pin it NOW, not at the end of doctor: the packages live in this interpreter and
+      // nothing else can import them, so a daemon started meanwhile would still see none.
+      process.env.GONEXT_PROBE_PYTHON = venvPy;
+      await pinPythonForDaemon({ log });
+      log(`  installed into the virtualenv and pinned the agent's python to ${venvPy}`);
+      return;
+    }
+  }
+
+  log("  falling back to --break-system-packages (no virtualenv available)");
+  r = await runPip(python3Bin(), pkgs, ["--break-system-packages"]);
+  if (r.code === 0) return;
+  throw new Error(`pip install ${pkgs.join(" ")} exited ${r.code}`);
+}
+
+/**
+ * The yellow RAM notice shown before the multi-GB model download (user request): the
+ * default 14B-4bit model wants a Mac with ≥16 GB. When the machine has less, add a plain
+ * line stating its detected amount. Pure (RAM passed in) so it's unit-testable.
+ * Returns already-colored lines; empty array only if `repo` is falsy.
+ */
+export function chatRamWarningLines(repo, totalBytes) {
+  if (!repo) return [];
+  const ramGb = Math.round((Number(totalBytes) || 0) / 1024 ** 3);
+  const name = String(repo).split("/").pop();
+  const out = [
+    yellow(`  ⚠ ${name} needs a Mac with at least ${MIN_CHAT_RAM_GB} GB of RAM to run well.`),
+  ];
+  if (ramGb > 0 && ramGb < MIN_CHAT_RAM_GB) {
+    out.push(
+      yellow(
+        `    This machine has about ${ramGb} GB — the model may run very slowly or fail to load.`
+      )
+    );
+  }
+  return out;
+}
+
+const DIR = join(homedir(), ".gonext");
+export const MODEL_PID_FILE = join(DIR, "model.pid");
+export const MODEL_LOG_FILE = join(DIR, "model.log");
+const EMBED_PID_FILE = join(DIR, "embed.pid");
+const EMBED_LOG_FILE = join(DIR, "embed.log");
+
+// The default base chat model (task #127 decision): matches the Wizard's model-chat step.
+export const DEFAULT_CHAT_REPO = "mlx-community/Qwen3-14B-4bit";
+export const DEFAULT_CHAT_DIR = join(homedir(), "mlx-models", "Qwen3-14B-4bit");
+export const DEFAULT_CHAT_PORT = 8082;
+
+// ---- pure helpers (unit-tested offline) -------------------------------------------------
+
+/** The port from a base URL, or null. "http://127.0.0.1:8082/v1" → 8082. */
+export function parsePort(baseUrl) {
+  try {
+    const u = new URL(String(baseUrl || "").includes("://") ? baseUrl : `http://${baseUrl}`);
+    if (u.port) return Number(u.port);
+    return u.protocol === "https:" ? 443 : 80;
+  } catch {
+    const m = String(baseUrl || "").match(/:(\d{2,5})(?:\/|$)/);
+    return m ? Number(m[1]) : null;
+  }
+}
+
+/** True when the URL points at this machine (loopback/LAN) — only then can we START it. */
+export function isLocalModelUrl(baseUrl) {
+  let host = "";
+  try {
+    host = new URL(String(baseUrl || "").includes("://") ? baseUrl : `http://${baseUrl}`)
+      .hostname.toLowerCase()
+      .replace(/\.$/, "");
+  } catch {
+    return false;
+  }
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  if (!host) return false;
+  if (["localhost", "0.0.0.0", "::", "::1"].includes(host)) return true;
+  if (/^127(\.\d{1,3}){3}$/.test(host)) return true;
+  if (
+    /^(10(\.\d{1,3}){3}|192\.168(\.\d{1,3}){2}|172\.(1[6-9]|2\d|3[01])(\.\d{1,3}){2}|169\.254(\.\d{1,3}){2})$/.test(
+      host
+    )
+  )
+    return true;
+  if (host.includes(":") && (host.startsWith("fe80:") || /^f[cd]/.test(host))) return true;
+  if (/\.(local|localdomain|lan|home|internal)$/.test(host)) return true;
+  return !host.includes(".") && !host.includes(":");
+}
+
+/** Normalize a base URL to its root (strip a trailing /v1 and slashes). */
+export function modelRoot(baseUrl) {
+  return String(baseUrl || "").replace(/\/+$/, "").replace(/\/v1$/i, "");
+}
+
+/**
+ * Expand a leading "~" to the home directory. The web app asks for a model FOLDER (task
+ * #133) and people type "~/mlx-models/…" — the shell would expand that, but a value coming
+ * from a settings field never passes through a shell, so it must be expanded here or the
+ * folder check fails on a path that is perfectly correct.
+ */
+export function expandHome(p) {
+  const s = String(p || "").trim();
+  if (!s) return "";
+  if (s === "~") return homedir();
+  if (s.startsWith("~/")) return join(homedir(), s.slice(2));
+  return s;
+}
+
+// ---- running-model discovery (task #133: `gu-cli status`) ---------------------------
+// Everything below is parsed from `ps`, NOT from a hand-maintained port list or our own
+// pidfiles — so a server the user started themselves (the BC3 case: `mlx_lm.server` on 8090,
+// a second coder model, …) shows up in the table exactly like one the doctor started.
+
+/**
+ * Parse `ps -Ao pid=,etime=,args=` output into local model-server rows.
+ * Pure (takes the text) so it can be unit-tested without spawning anything.
+ * Returns [{ pid, etime, port, kind, modelPath }], one per PID, sorted by port.
+ */
+export function parseModelServerRows(psOutput) {
+  const rows = [];
+  const seen = new Set();
+  for (const raw of String(psOutput || "").split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const m = line.match(/^(\d+)\s+(\S+)\s+(.*)$/);
+    if (!m) continue;
+    const [, pidStr, etime, cmd] = m;
+    // Our own `ps`/grep invocations mention these strings without being servers.
+    if (/\bgrep\b/.test(cmd)) continue;
+    // `mlx_lm.server` or `mlx_lm server` (python -m mlx_lm server); the embed server is our
+    // own script. Anything else on the box is not ours to list.
+    const isEmbed = /gonext_mlx_embed\.py/.test(cmd);
+    const isMlx = /mlx_lm[.\s]server\b/.test(cmd);
+    if (!isEmbed && !isMlx) continue;
+    const pid = Number(pidStr);
+    if (seen.has(pid)) continue;
+    seen.add(pid);
+    const portMatch = cmd.match(/--port(?:=|\s+)(\d{2,5})/);
+    // Defaults when --port is omitted: mlx_lm.server → 8080, our embed script → 8085.
+    const port = portMatch ? Number(portMatch[1]) : isEmbed ? EMBED_PORT : 8080;
+    const modelMatch = cmd.match(/--model(?:=|\s+)(\S+)/);
+    rows.push({
+      pid,
+      etime,
+      port,
+      kind: isEmbed ? "embed" : "mlx-lm",
+      modelPath: modelMatch ? modelMatch[1] : "",
+    });
+  }
+  return rows.sort((a, b) => a.port - b.port || a.pid - b.pid);
+}
+
+/**
+ * The ROLE a server plays for gu. When the account's settings are known (fetched from
+ * the DB — what the user picked in the web app, Settings → Agent) the roles come from THOSE
+ * ports, which is the only correct answer: a user who runs their agent model on 8090 has a
+ * chat server on 8090, not a nameless one. Falls back to the seeded default ports when the
+ * settings couldn't be loaded (offline / not signed in).
+ */
+export function roleForServer({ port, kind }, configured = null) {
+  if (configured) {
+    if (configured.embed?.local && port === configured.embed.port) return "embed";
+    if (configured.agent?.local && port === configured.agent.port) return "chat";
+    if (configured.coder?.local && port === configured.coder.port) return "coder";
+    // A server that isn't any configured role is genuinely the user's own.
+    if (kind === "embed") return "embed";
+    return "-";
+  }
+  if (kind === "embed" || port === EMBED_PORT) return "embed";
+  if (port === DEFAULT_CHAT_PORT) return "chat";
+  return "-";
+}
+
+/** Strip a provider prefix and location suffix from a model key: "mlx:Foo@@port:8080" → "Foo". */
+function modelKeyName(key) {
+  return String(key || "")
+    .split("@@")[0]
+    .replace(/^(mlx|ollama|openai|anthropic|groq|deepseek):/i, "")
+    .trim();
+}
+
+/**
+ * What the WEB APP says this account's models are, reduced to something the CLI can check
+ * against the local machine. Mirrors the API's own resolveConfiguredAgentModel order: an
+ * explicit agentModelUrl wins; otherwise the picked model key carries its own location
+ * ("Qwen3-14B-4bit@@port:8080"); otherwise the account's MLX base URL; otherwise our default.
+ *
+ * Takes the GET /api/worker/settings body. Returns null when settings couldn't be loaded, so
+ * callers can fall back to port-based guessing instead of asserting something false.
+ */
+export function resolveConfiguredModels(settings) {
+  if (!settings) return null;
+  const s = settings;
+  const hostBase =
+    String(s.mlxOpenAiBaseUrl || "").trim() ||
+    String(s.hosts?.[0]?.mlxOpenAiBaseUrl || "").trim();
+
+  const directAgent = String(s.agentModelUrl || "").trim();
+  const agentKey = String(s.agentModel || "").trim();
+  const agentPortInKey = agentKey.match(/@@port:(\d{2,5})/)?.[1];
+  let agentUrl = "";
+  let agentSource = "";
+  if (directAgent) {
+    agentUrl = directAgent;
+    agentSource = "Settings → Agent (model URL)";
+  } else if (agentPortInKey) {
+    agentUrl = `http://127.0.0.1:${agentPortInKey}`;
+    agentSource = "Settings → Agent (model)";
+  } else if (hostBase) {
+    agentUrl = hostBase;
+    agentSource = "Settings (MLX server URL)";
+  } else {
+    agentUrl = `http://127.0.0.1:${DEFAULT_CHAT_PORT}`;
+    agentSource = "built-in default";
+  }
+
+  const coderUrl = String(s.agentCodingModelUrl || "").trim();
+  // The RAG embedder is ALWAYS an HTTP endpoint — the agent's _embed() only ever POSTs to
+  // {base}/v1/embeddings, then Ollama's /api/embed, then /api/embeddings; it never embeds
+  // in-process. But it is NOT necessarily a dedicated port of ours: mirror the agent's own
+  // fallback chain (gonext_agent_chat.py: rag_embed_base = ragEmbedUrl or coding_base_url or
+  // agent_base_url) instead of assuming our 8085 server, or status reports a URL the agent
+  // would never call. Only when nothing at all is set is 8085 (what `doctor` seeds) the
+  // honest answer.
+  // NO fallback (task #133). There used to be a chain: embed URL → CODE model URL → AGENT
+  // model URL. But those serve completions, not embeddings — mlx_lm.server has no
+  // /v1/embeddings endpoint at all — so the chain could only ever end in a confusing failure
+  // against an unrelated server. Either the account configures an embedder (a model folder,
+  // or a server URL) or there ISN'T one, and every surface says so plainly.
+  const agentIsConfigured = Boolean(directAgent || agentKey || hostBase);
+  const explicitEmbed = String(s.ragEmbedUrl || "").trim();
+  // A configured model FOLDER means the embedder is the server we run for it on the standard
+  // port — the same URL the API derives (resolveRagEmbedUrl), so the user never types a port.
+  const embedPath = String(s.ragEmbedModelPath || "").trim();
+  const embedUrl = explicitEmbed || (embedPath ? `http://127.0.0.1:${EMBED_PORT}` : "");
+  const embedSource = explicitEmbed
+    ? "Settings → Agent → RAG (server URL)"
+    : embedPath
+      ? "Settings → Agent → RAG (model folder)"
+      : "NOT CONFIGURED — no embedding model set";
+
+  const entry = (url, name, source, set) => ({
+    url: modelRoot(url),
+    port: parsePort(url),
+    local: isLocalModelUrl(url),
+    model: name,
+    source,
+    configured: set,
+  });
+
+  return {
+    agent: entry(
+      agentUrl,
+      modelKeyName(agentKey) || String(s.agentModelName || "").trim(),
+      agentSource,
+      agentIsConfigured
+    ),
+    embed: {
+      ...entry(
+        embedUrl,
+        // A model FOLDER names itself; the free-text name only matters for Ollama (one
+        // process serves many models). Left EMPTY when unset — no "nomic-embed-text" default,
+        // which used to show a model the user never chose as if it were in use.
+        modelDisplayName(embedPath) || String(s.ragEmbedModel || "").trim(),
+        embedSource,
+        Boolean(explicitEmbed || embedPath)
+      ),
+      path: expandHome(embedPath),
+    },
+    coder: coderUrl
+      ? entry(coderUrl, String(s.agentCodingModelName || "").trim(), "Settings → Agent (code model)", true)
+      : null,
+  };
+}
+
+/**
+ * POST /api/worker/settings — save a choice made in the terminal back to the ACCOUNT, so it
+ * appears in the web app too (task #133). Narrow by design: the API only accepts the fields
+ * the CLI setup flow asks about. Returns true on success; never throws (a failed save must
+ * not abort setup — the model still gets served from the chosen folder this session).
+ */
+export async function saveWorkerSettings(apiBase, workerKey, patch, { timeoutMs = 6000 } = {}) {
+  if (!apiBase || !workerKey || !patch || !Object.keys(patch).length) return false;
+  try {
+    const res = await fetch(`${String(apiBase).replace(/\/+$/, "")}/api/worker/settings`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
+      body: JSON.stringify(patch),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Is an OpenAI-compatible model endpoint REACHABLE from this machine?
+ *
+ * Distinct from probeModelServer, which demands a 200 and so reports an authenticated
+ * endpoint (a hosted Ollama behind a key, a cloud API) as down. Here ANY HTTP response —
+ * including 401/403/404 — proves something is listening and routable; only a connection
+ * failure means unreachable. That is the question a client machine actually needs answered:
+ * "can I get to my model from here?" (task #134).
+ *
+ * Returns { reachable, status, error }.
+ */
+export async function probeReachable(baseUrl, { timeoutMs = 4000 } = {}) {
+  const root = modelRoot(baseUrl);
+  if (!root) return { reachable: false, error: "no URL configured" };
+  for (const path of ["/v1/models", "/api/tags", "/"]) {
+    try {
+      const res = await fetch(`${root}${path}`, {
+        method: "GET",
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      return { reachable: true, status: res.status };
+    } catch (e) {
+      // Only a transport failure counts as unreachable; try the next shape first.
+      var last = e?.name === "TimeoutError" ? `no response in ${timeoutMs / 1000}s` : e?.message || String(e);
+    }
+  }
+  return { reachable: false, error: last };
+}
+
+/**
+ * True when a base URL is an OLLAMA server rather than our MLX embed server. Ollama answers
+ * /api/tags; the MLX server does not. Matters because the two need completely different
+ * setup: Ollama serves the embedding model itself (`ollama pull qwen3-embedding:8b`) and
+ * needs only a model NAME, while MLX needs a downloaded folder and a server we start.
+ */
+export async function isOllamaEmbedder(baseUrl, { timeoutMs = 2500 } = {}) {
+  return (await classifyEmbedder(baseUrl, { timeoutMs })) === "ollama";
+}
+
+/**
+ * "ollama" | "other" | "unreachable" | "none" — and the third value is the whole point.
+ *
+ * isOllamaEmbedder answers a live probe with a boolean, so a box that is DOWN is
+ * indistinguishable from a box that is not Ollama. That is not a rounding error, it changes
+ * what the doctor does with the machine: seeing `false`, it concludes there is no Ollama
+ * embedder, falls through to the MLX branch, asks "Where should the RAG embedding model be
+ * stored?" and SAVES an MLX model path onto an account whose embedder is a remote Ollama.
+ *
+ * Observed exactly that way (2026-09-05): ollama2 was not answering for a moment, and a Client
+ * Expert machine came out of `gu` configured with
+ * ragEmbedModelPath=/Users/joseph/mlx-models/Qwen3-Embedding-8B-4bit-DWQ — a model that server
+ * does not have and never will. Host-mode setup leaking into a machine that is not a host.
+ *
+ * "I could not tell" must therefore be its own answer, and the caller must not treat it as "no".
+ */
+export async function classifyEmbedder(baseUrl, { timeoutMs = 2500 } = {}) {
+  const root = modelRoot(baseUrl);
+  if (!root) return "none";
+  try {
+    const res = await fetch(`${root}/api/tags`, { signal: AbortSignal.timeout(timeoutMs) });
+    // A REPLY that is not /api/tags is a real "not Ollama": something is serving this URL and
+    // it is not an Ollama. Only a failure to reach it at all is unknowable.
+    return res.ok ? "ollama" : "other";
+  } catch {
+    return "unreachable";
+  }
+}
+
+/** GET /api/worker/settings — the account's model config from the DB. null on any failure. */
+export async function fetchWorkerSettings(apiBase, workerKey, { timeoutMs = 4000 } = {}) {
+  if (!apiBase || !workerKey) return null;
+  try {
+    const res = await fetch(`${String(apiBase).replace(/\/+$/, "")}/api/worker/settings`, {
+      headers: { "X-Worker-Key": workerKey },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/** `ps` etime ("1-02:14:33", "02:14:33", "14:33") → a compact "1d2h" / "2h14m" / "14m33s". */
+export function formatEtime(etime) {
+  const m = String(etime || "").match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
+  if (!m) return String(etime || "-");
+  const [, d, h, mi, s] = m.map((x) => (x == null ? 0 : Number(x)));
+  if (d) return `${d}d${h}h`;
+  if (h) return `${h}h${mi}m`;
+  if (mi) return `${mi}m${s}s`;
+  return `${s}s`;
+}
+
+/** Local model servers running right now, from `ps`. macOS/Linux; [] if ps fails. */
+export async function discoverModelServers() {
+  return new Promise((resolve) => {
+    execFile(
+      "ps",
+      ["-Ao", "pid=,etime=,args="],
+      { maxBuffer: 8 * 1024 * 1024 },
+      (err, stdout) => resolve(err ? [] : parseModelServerRows(stdout))
+    );
+  });
+}
+
+/**
+ * The display name for a served model: the LAST path segment of whatever the server was
+ * launched with, so "/Users/me/mlx-models/Qwen3-14B-4bit" and "mlx-community/Qwen3-14B-4bit"
+ * both read "Qwen3-14B-4bit" — the name used everywhere else (modelKey, Settings, the Wizard).
+ */
+export function modelDisplayName(modelPath) {
+  const p = String(modelPath || "").replace(/\/+$/, "");
+  if (!p) return "";
+  return p.split("/").filter(Boolean).pop() || p;
+}
+
+/**
+ * Add live detail to each discovered row: does it ANSWER (`up`) or is it still loading the
+ * weights (`loading`)? Probes all rows in parallel.
+ *
+ * The model NAME comes from the process's own `--model` argument, never from /v1/models:
+ * mlx_lm.server advertises every model it can see in the HF cache, not the one it loaded, so
+ * reading the id off that endpoint reports a model this server isn't running (observed live:
+ * a server started on Qwen3-14B-4bit listing mlx-community/Llama-3.2-3B-Instruct-4bit first).
+ * `--model` is what the process was actually launched with, so it's the only authority.
+ */
+export async function inspectModelServers(rows, configured = null) {
+  return Promise.all(
+    rows.map(async (r) => {
+      const base = `http://127.0.0.1:${r.port}`;
+      let up = false;
+      let probed = "";
+      try {
+        const res = await fetch(`${base}/v1/models`, { signal: AbortSignal.timeout(2000) });
+        up = res.ok;
+        if (res.ok && !r.modelPath) {
+          // Only when the command line didn't say (a server launched some other way). Prefer
+          // a local PATH here — that's the one mlx_lm.server registers for what it loaded.
+          const j = await res.json().catch(() => null);
+          const ids = (j?.data ?? []).map((d) => d?.id).filter(Boolean);
+          probed = ids.find((id) => id.startsWith("/") || id.startsWith("~")) || ids[0] || "";
+        }
+      } catch {
+        up = false;
+      }
+      return {
+        ...r,
+        role: roleForServer(r, configured),
+        status: up ? "up" : "loading",
+        uptime: formatEtime(r.etime),
+        model: modelDisplayName(r.modelPath) || modelDisplayName(probed) || "-",
+      };
+    })
+  );
+}
+
+/**
+ * Parse `lsof -p <pid> -a -d 1 -Ftn` output → the file the process's STDOUT is writing to,
+ * or "" when it isn't a regular file. Pure, so the (macOS-specific) parsing is testable.
+ *
+ * Reading fd 1 rather than assuming our own log path is what makes `logs <port>` work for a
+ * server we didn't start: a redirected one (`… > my.log`) is just as readable, and a server
+ * attached to a terminal correctly reports nothing instead of us pointing at the wrong file.
+ */
+export function parseLsofStdout(out) {
+  let type = "";
+  let path = "";
+  for (const line of String(out || "").split("\n")) {
+    if (line.startsWith("t")) type = line.slice(1).trim();
+    else if (line.startsWith("n")) path = line.slice(1).trim();
+  }
+  return type === "REG" && path ? path : "";
+}
+
+/** The log file a running server writes to, or "" when its output isn't going to a file. */
+export async function serverLogFile(pid) {
+  if (!pid || !Number.isFinite(Number(pid))) return "";
+  return new Promise((resolve) => {
+    execFile("lsof", ["-p", String(pid), "-a", "-d", "1", "-Ftn"], (err, stdout) =>
+      resolve(err ? "" : parseLsofStdout(stdout))
+    );
+  });
+}
+
+// ---- RAG self-test (task #133) -----------------------------------------------------------
+// "Is RAG working?" cannot be answered from settings: the name in the config is free text,
+// the model field is ignored by our MLX embedder, and the rag_* tools only run mid-task. The
+// only honest answer is to actually EMBED something and see what comes back.
+
+/**
+ * Round-trip a real embedding request. Tries the OpenAI-compatible endpoint first, then
+ * Ollama's — the same order the agent's _embed() uses, so a pass here means the agent will
+ * work. Returns { ok, dims, ms, endpoint, error }.
+ */
+export async function testEmbeddings(baseUrl, model, { timeoutMs = 20000 } = {}) {
+  const root = modelRoot(baseUrl).replace(/\/(api\/embed|api\/embeddings|api)$/i, "");
+  if (!root) return { ok: false, error: "no embedding server URL configured" };
+  const attempts = [
+    { path: "/v1/embeddings", body: { model: model || "", input: ["gu embedding self-test"] },
+      dims: (j) => j?.data?.[0]?.embedding?.length },
+    { path: "/api/embed", body: { model: model || "", input: ["gu embedding self-test"] },
+      dims: (j) => j?.embeddings?.[0]?.length },
+  ];
+  let lastError = "";
+  for (const a of attempts) {
+    const started = Date.now();
+    try {
+      const res = await fetch(`${root}${a.path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(a.body),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!res.ok) {
+        lastError = `${a.path} → HTTP ${res.status}`;
+        continue;
+      }
+      const j = await res.json().catch(() => null);
+      const dims = a.dims(j);
+      if (!dims) {
+        lastError = `${a.path} → 200 but no embedding in the response`;
+        continue;
+      }
+      return { ok: true, dims, ms: Date.now() - started, endpoint: `${root}${a.path}` };
+    } catch (e) {
+      lastError = `${a.path} → ${e?.name === "TimeoutError" ? `no response in ${timeoutMs / 1000}s` : e?.message || e}`;
+    }
+  }
+  return { ok: false, error: lastError };
+}
+
+/**
+ * Every LOCAL knowledge base on this machine, read from the manifests the agent writes.
+ * Keyed by hashes on disk, so the manifest is the only place the human-readable source lives.
+ */
+export async function listLocalRagIndexes() {
+  const { readdir, readFile: rf, stat: st } = await import("node:fs/promises");
+  const root = join(homedir(), ".gonext", "rag");
+  const out = [];
+  let folders = [];
+  try {
+    folders = await readdir(root);
+  } catch {
+    return out; // never indexed anything
+  }
+  for (const f of folders) {
+    let sources = [];
+    try {
+      sources = await readdir(join(root, f));
+    } catch {
+      continue;
+    }
+    for (const srcHash of sources) {
+      const dir = join(root, f, srcHash);
+      let manifest = null;
+      try {
+        manifest = JSON.parse(await rf(join(dir, "manifest.json"), "utf8"));
+      } catch {
+        /* a shard dir with no manifest — still report what we can */
+      }
+      let shards = 0;
+      let bytes = 0;
+      try {
+        for (const name of await readdir(dir)) {
+          if (!name.startsWith("chunks") || !name.endsWith(".jsonl")) continue;
+          shards += 1;
+          bytes += (await st(join(dir, name))).size;
+        }
+      } catch {
+        /* unreadable — reported as 0 */
+      }
+      if (!manifest && !shards) continue;
+      out.push({
+        source: manifest?.sourceUrl ?? `(unknown — ${srcHash.slice(0, 8)}…)`,
+        chunks: manifest?.chunks ?? 0,
+        files: manifest?.files ?? 0,
+        model: manifest?.embedModel ?? "?",
+        dims: manifest?.dims ?? 0,
+        updatedAt: manifest?.updatedAt ?? "?",
+        shards,
+        bytes,
+      });
+    }
+  }
+  return out.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+}
+
+/** Stop model servers by pid. Returns the pids actually signalled. */
+export function stopModelServers(rows) {
+  const killed = [];
+  for (const r of rows) {
+    try {
+      process.kill(r.pid, "SIGTERM");
+      killed.push(r.pid);
+    } catch {
+      /* already gone */
+    }
+  }
+  return killed;
+}
+
+// ---- probing + process control ----------------------------------------------------------
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** True when an OpenAI-compatible model server answers GET {base}/v1/models. */
+export async function probeModelServer(baseUrl, { timeoutMs = 3000 } = {}) {
+  const root = modelRoot(baseUrl);
+  if (!root) return false;
+  try {
+    const res = await fetch(`${root}/v1/models`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function which(cmd) {
+  return new Promise((resolve) => {
+    execFile("command", ["-v", cmd], { shell: "/bin/sh" }, (err, stdout) =>
+      resolve(!err && Boolean(String(stdout).trim()))
+    );
+  });
+}
+
+/** True when the model directory exists and is non-empty. */
+export async function modelDirReady(dir) {
+  try {
+    const entries = await readdir(dir);
+    return entries.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Start mlx_lm.server for `modelDir` on `port`, DETACHED (logs to model.log, pidfile). Waits
+ * until the server answers /v1/models (up to waitMs). No-op + { started:false } when a
+ * server already answers on that port (BC3). Returns { started, ready, pid?, reason? }.
+ */
+export async function startChatModelServer({ modelDir, port, waitMs = 120_000, log = () => {} }) {
+  const base = `http://127.0.0.1:${port}`;
+  if (await probeModelServer(base, { timeoutMs: 1500 })) {
+    return { started: false, ready: true, reason: "already-running" };
+  }
+  if (!(await which("mlx_lm.server"))) {
+    return {
+      started: false,
+      ready: false,
+      reason: "mlx_lm.server not found — install it: pip install mlx-lm",
+    };
+  }
+  await mkdir(DIR, { recursive: true });
+  const out = await open(MODEL_LOG_FILE, "a");
+  let pid;
+  try {
+    const child = spawn("mlx_lm.server", ["--model", modelDir, "--port", String(port)], {
+      detached: true,
+      stdio: ["ignore", out.fd, out.fd],
+      env: process.env,
+    });
+    pid = child.pid;
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(MODEL_PID_FILE, String(pid ?? ""), "utf8");
+    child.unref();
+  } finally {
+    await out.close();
+  }
+  log(`  starting mlx_lm.server (pid ${pid}) on port ${port} — waiting for it to load…`);
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    await sleep(2500);
+    if (await probeModelServer(base, { timeoutMs: 2000 })) {
+      return { started: true, ready: true, pid };
+    }
+  }
+  return {
+    started: true,
+    ready: false,
+    pid,
+    reason: `model server did not answer within ${Math.round(waitMs / 1000)}s (still loading? see ${MODEL_LOG_FILE})`,
+  };
+}
+
+/**
+ * Download an MLX model repo to a local dir via the Hugging Face CLI. Streams progress to
+ * the terminal (inherit stdio) because it's a multi-GB, several-minute step. Resolves
+ * { ok } / rejects with guidance when `hf` is missing.
+ */
+export async function downloadModel({ repo, dir, log = () => {} }) {
+  if (!(await which("hf"))) {
+    throw new Error(
+      "the Hugging Face CLI (hf) is required to download the model. Install it with: pip install huggingface_hub"
+    );
+  }
+  log(`  downloading ${repo} → ${dir} (multi-GB, keep this open)…`);
+  return new Promise((resolve, reject) => {
+    const child = spawn("hf", ["download", repo, "--local-dir", dir], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("exit", (code) =>
+      code === 0 ? resolve({ ok: true }) : reject(new Error(`hf download exited ${code}`))
+    );
+    child.on("error", (e) => reject(e));
+  });
+}
+
+/** Fetch the account's resolved model config from /agent-payload (best-effort). */
+async function fetchModelConfig(apiBase, workerKey) {
+  try {
+    const res = await fetch(`${apiBase.replace(/\/+$/, "")}/api/worker/agent-payload`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
+      body: JSON.stringify({ messages: [{ role: "user", content: "ping" }] }),
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data?.payload ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The Phase-3 orchestration (task #127). Ensures the base CHAT model is running (starting a
+ * local mlx_lm.server, downloading first if the dir is missing and the user opts in), and
+ * probes the CODE model, giving guidance for a remote one. BC3-safe throughout: an
+ * already-answering server is left untouched.
+ *
+ * `log(str)` prints; `confirm(question, defaultYes)→bool` gates the multi-GB download and
+ * the model-server start (non-interactive callers pass a confirm that returns false, so the
+ * doctor only PROBES + advises and never downloads/starts unattended).
+ */
+/**
+ * `prompt(question, defaultValue) → string` asks for a VALUE (a folder path), unlike
+ * `confirm` which asks yes/no. Optional: a non-interactive caller omits it and the setup
+ * quietly uses the default location instead of blocking on an answer nobody can give.
+ */
+export async function runDoctor({ apiBase, workerKey, log, confirm, prompt, modelHost }) {
+  // A CLIENT machine (task #134) installs the agent framework and stops: the models live on
+  // another machine and are reached over HTTP. Default to what the hardware can actually do,
+  // so a Linux box or an Intel Mac never gets offered mlx-lm.
+  const isModelHost = modelHost === undefined ? canHostMlxModels() : Boolean(modelHost);
+  const p = (await fetchModelConfig(apiBase, workerKey)) ?? {};
+
+  // Step 0: the agent's PYTHON deps must be present or every agent turn crashes at import
+  // — and the model download/start needs `hf`/`mlx-lm`. Ensure these FIRST (task #127:
+  // parity with the Wizard's pip-mlx-lm / pip-agent-libs / hf-cli steps). Fatal-ish: if the
+  // core framework is missing, say so, but keep going so the model steps still run.
+  const deps = await ensureAgentDeps({ log, confirm, modelHost: isModelHost });
+  // ALWAYS pin here, not just after an install (task #134). `doctor` is an explicit "fix my
+  // setup" action, and the common broken case is packages that are ALREADY installed — into
+  // a different interpreter than the daemon resolves. The REPL's own check can't see this:
+  // it runs in the user's shell (conda active), the daemon runs elsewhere, so smolagents
+  // looks present to one and missing to the other. Observed live on a client machine.
+  if (deps.python3 === "ok") {
+    const pinned = await pinPythonForDaemon({ log });
+    if (pinned) deps.python = pinned;
+  }
+
+  // Chat model: prefer the account's configured URL; fall back to the default local one.
+  const configuredChat = String(p.agentBaseURL || "").trim();
+  const chatUrl = configuredChat || `http://127.0.0.1:${DEFAULT_CHAT_PORT}`;
+  const chatPort = parsePort(chatUrl) || DEFAULT_CHAT_PORT;
+  // Review H2: never serve a model the account didn't configure. Only the KNOWN default is
+  // auto-downloadable; for a specifically-named other model we start its dir if present but
+  // won't substitute Qwen3-14B. "default_model" is the direct-URL sentinel (the loaded
+  // model), which we treat as the default. modelId empty (fresh account) → default too.
+  const modelId = String(p.agentModelId || "").trim();
+  const isDefaultModel =
+    !modelId || modelId === "default_model" || /qwen3-?14b/i.test(modelId);
+  const chatDir = isDefaultModel
+    ? DEFAULT_CHAT_DIR
+    : join(homedir(), "mlx-models", modelId.replace(/[^A-Za-z0-9._-]/g, "-"));
+  const chatRepo = isDefaultModel ? DEFAULT_CHAT_REPO : null; // null = not auto-downloadable
+
+  // The chat handling sets `chat` but never returns early — the code-model check below is
+  // independent and must run even when the user declines the chat-model setup.
+  let chat = "checked";
+  log("");
+  if (!isModelHost) {
+    // CLIENT machine (task #134): the agent runs here, the models don't. Skip the
+    // MLX-specific download/start entirely — but ONLY that. The code-model check below still
+    // runs, because a coder is usually remote (a cloud endpoint or another box) and matters
+    // on every machine, client or not.
+    if (await hasLocalOllama()) {
+      // An Ollama host: it DOES serve models here, just not MLX ones. Don't tell it
+      // otherwise — only the MLX-specific setup is skipped.
+      log("  Ollama is answering on this machine (127.0.0.1:11434) — skipping the MLX model");
+      log("  setup (mlx is Apple-Silicon only).");
+      // The same advice on every machine now. A client used to be told it "already uses" a
+      // constant this code no longer substitutes — advice that was wrong the moment the
+      // override went, and misleading before that, since the account's model was what it had
+      // been asked to run and not what this line named.
+      log("  Point the Agent model URL at your Ollama server if you want to use it.");
+      chat = "ollama-host";
+    } else {
+      log("  This machine runs the AGENT, not the models — skipping the local model setup.");
+      log("  Point the Agent model URL (web app → Settings → Agent) at ANY OpenAI-compatible");
+      log("  endpoint this machine can reach:");
+      log("    · a public/hosted Ollama    → https://your-ollama.example.com/v1");
+      log("    · another Mac over a tunnel → http://<tailnet-name>:8090/v1");
+      log("    · a cloud endpoint          → the same way the code model already works");
+      log("  For Ollama, also set the Agent model NAME (it serves many models from one port).");
+      log("  `gu status` checks whether that URL answers FROM HERE.");
+      chat = "client";
+    }
+  } else if (await probeModelServer(chatUrl)) {
+    // "Something is listening" is not the question a person is asking here (task #170). They
+    // want to know WHICH model, from WHERE — and this branch leaves a server alone precisely
+    // because it is already up, so if it is serving the wrong thing, this is the last moment
+    // anyone would notice. Name it from `ps`, the same authority `gu status` uses.
+    const { servedModelAt, sameModelName, namesAModel } = await import("./agent-model-label.mjs");
+    const served = servedModelAt({ port: chatPort, servers: await discoverModelServers() });
+    log(`  ✓ chat model already running at ${modelRoot(chatUrl)} — leaving it alone.`);
+    if (served) {
+      log(`      ${served.name}`);
+      log(`      from ${served.path}`);
+      // Only a REAL configured name is an expectation. "default_model" is mlx_lm's "whatever I
+      // loaded" sentinel, so it agrees with anything by construction.
+      if (namesAModel(modelId) && !sameModelName(modelId, served.name)) {
+        log(`  ⚠ your account asks for "${modelId}", but that server is running`);
+        log(`    "${served.name}". Stop it and re-run doctor, or change the model in the web app.`);
+      }
+    } else {
+      // A server we cannot see in `ps`: someone else's process, a container, or a tunnel to
+      // another machine. Say that rather than implying we checked.
+      log(`      (not started from an mlx_lm.server process here — can't say which model)`);
+    }
+    chat = "already-running";
+  } else if (configuredChat && !isLocalModelUrl(chatUrl)) {
+    // Configured but REMOTE and not answering — we can't start a model on another machine.
+    log(`  ⚠ your chat model server (${modelRoot(chatUrl)}) isn't answering.`);
+    log("    It's remote, so start it there — this machine can't launch it.");
+    chat = "remote";
+  } else {
+    // Local (or unconfigured → default local): ensure the RIGHT model, then offer to start.
+    const dir = chatDir;
+    let dirReady = await modelDirReady(dir);
+    if (!dirReady && !chatRepo) {
+      // A specifically-named, non-default model we don't know how to fetch — DON'T
+      // substitute the default. Tell the user how to bring their own (review H2).
+      log(`  ⚠ your account uses the chat model "${modelId}", which isn't the built-in`);
+      log(`    default, so I can't auto-download it. Put it at ${dir} (or any dir) and run:`);
+      log(`      mlx_lm.server --model <that dir> --port ${chatPort}`);
+      chat = "unknown-model";
+    } else if (!dirReady) {
+      // Yellow RAM notice before the multi-GB download, THEN the confirm (user request).
+      for (const line of chatRamWarningLines(chatRepo, totalmem())) log(line);
+      const yes = await confirm(
+        `Download the base chat model ${chatRepo} (~8 GB) to ${dir}?`,
+        true
+      );
+      if (!yes) {
+        log("  Skipped. To do it yourself:");
+        log(`      hf download ${chatRepo} --local-dir ${dir}`);
+        log(`      mlx_lm.server --model ${dir} --port ${chatPort}`);
+        chat = "skipped";
+      } else {
+        try {
+          await downloadModel({ repo: chatRepo, dir, log });
+          dirReady = true;
+        } catch (e) {
+          log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+          chat = "download-failed";
+        }
+      }
+    }
+    if (dirReady && chat === "checked") {
+      // Name the model in the QUESTION, the way the RAG prompt below always has. "Start the
+      // chat model server on port 8090?" asks someone to approve a multi-GB load without
+      // saying what is being loaded or from where.
+      const chatName = modelDisplayName(dir);
+      const yes = await confirm(
+        `Start the chat model server for ${chatName} (${dir}) on port ${chatPort} now?`,
+        true
+      );
+      if (!yes) {
+        log(`  Skipped. Start it later: mlx_lm.server --model ${dir} --port ${chatPort}`);
+        chat = "not-started";
+      } else {
+        // Review M2: don't block the caller (the REPL) for a full cold model load — that's
+        // minutes. Wait only long enough to confirm the server launched and didn't crash
+        // (~20s); if it's still loading, say so and return. The first agent turn will wait
+        // for it. A missing binary / immediate exit still surfaces as an error.
+        const r = await startChatModelServer({
+          modelDir: dir,
+          port: chatPort,
+          waitMs: 20_000,
+          log,
+        });
+        if (r.ready) {
+          log(`  ✓ chat model is up: ${chatName} on port ${chatPort}`);
+          log(`      from ${dir}`);
+          chat = "started";
+        } else if (r.started) {
+          log(`  … ${chatName} is loading in the background on port ${chatPort} (large model —`);
+          log(`    the first answer may take a minute). Watch it: gu-cli logs`);
+          chat = "loading";
+        } else {
+          log(`  ⚠ ${r.reason}`);
+          chat = "start-failed";
+        }
+      }
+    }
+  }
+
+  // Code model (Ollama): probe + guide only — never auto-pull (BC3 + bounded scope).
+  const codeUrl = String(p.codingBaseURL || "").trim();
+  const codeModel = String(p.codingModelId || "").trim();
+  if (codeUrl) {
+    log("");
+    log("  Checking the agent code model…");
+    // A REMOTE coder is normally a cloud API behind a key: it answers 401 to an
+    // unauthenticated probe, which probeModelServer (200-only) reports as DOWN. Use
+    // reachability there — any HTTP answer proves it's up — or the doctor cries wolf about a
+    // perfectly healthy endpoint and then suggests `ollama pull` for a cloud service.
+    const codeIsLocal = isLocalModelUrl(codeUrl);
+    const codeOk = codeIsLocal
+      ? await probeModelServer(codeUrl)
+      : (await probeReachable(codeUrl)).reachable;
+    if (codeOk) {
+      log(`  ✓ code model server is up at ${modelRoot(codeUrl)}.`);
+    } else if (codeIsLocal) {
+      log(`  ⚠ local code model server (${modelRoot(codeUrl)}) isn't answering.`);
+      if (codeModel) log(`    Start Ollama and pull it:  ollama serve &  ollama pull ${codeModel}`);
+    } else {
+      // Unreachable AND remote: this machine can't start it, and `ollama pull` is only
+      // meaningful if that server is actually Ollama — don't assume it is.
+      log(`  ⚠ your code model (${modelRoot(codeUrl)}) is not reachable from this machine.`);
+      log("    It's remote, so start it there / check the network — this machine can't launch it.");
+    }
+  }
+
+  // RAG (task #127: the user wants the terminal RAG-ready). Ensure the embedding model +
+  // server so rag_index / rag_search work.
+  //
+  // The embedding model is configured in the web app as a FOLDER, not a port (task #133), and
+  // that field lives on the settings row — the agent payload only carries RAG config when
+  // cloud RAG is fully set up (enabled + AWS creds). Read it from /api/worker/settings so the
+  // doctor serves the folder the user chose even on a local-RAG-only account.
+  const ws = await fetchWorkerSettings(apiBase, workerKey);
+  const ragCfg = {
+    ...p,
+    ragEmbedModelPath: String(ws?.ragEmbedModelPath || p?.ragEmbedModelPath || "").trim(),
+    ragEmbedUrl: String(ws?.ragEmbedUrl || p?.ragEmbedUrl || "").trim(),
+  };
+  const rag = isModelHost
+    ? await ensureRag({ p: ragCfg, log, confirm, prompt, apiBase, workerKey })
+    : { embed: "client" };
+  if (!isModelHost) {
+    log("");
+    log("  RAG: this machine doesn't serve the embedding model either — point the RAG");
+    log("  embedding URL at the machine that does (`gu rag` tests it from here).");
+  }
+
+  return { chat, deps, rag };
+}
+
+/**
+ * Ensure the agent's required runtime deps (task #127 — parity with the Wizard's pip steps).
+ * python3 can't be auto-installed (guidance only); hf / mlx-lm / smolagents+openai are
+ * offered via pip. Each install is confirmed. Returns a status map; missing deps are
+ * reported, never silently ignored — the agent hard-fails without smolagents+openai.
+ */
+/**
+ * True when this machine can actually RUN an MLX model server: mlx is Apple-Silicon only.
+ * Anywhere else (a Linux box, an Intel Mac) mlx-lm either fails to install or installs
+ * something that can't work — so it must never be offered there.
+ */
+export function canHostMlxModels() {
+  return platform() === "darwin" && arch() === "arm64";
+}
+
+/**
+ * True when a local OLLAMA is serving models here. Matters because canHostMlxModels() is
+ * false on an Intel Mac or a Linux box, yet such a machine may well host models via Ollama —
+ * calling it "a machine that runs the agent, not the models" would be plainly wrong. MLX
+ * setup still doesn't apply (mlx is Apple-Silicon only); only the WORDING changes.
+ */
+export async function hasLocalOllama({ timeoutMs = 1200 } = {}) {
+  for (const url of ["http://127.0.0.1:11434/api/tags", "http://127.0.0.1:11434/v1/models"]) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+      if (res.ok) return true;
+    } catch {
+      /* not there */
+    }
+  }
+  return false;
+}
+
+/**
+ * `modelHost` (default: whether this machine COULD host models) decides whether the
+ * model-serving packages are offered at all. A client machine — the terminal runs here, the
+ * models live on another machine (task #134) — needs ONLY the agent framework: the agent
+ * imports no mlx/torch/transformers and reaches the model over HTTP, exactly as it already
+ * reaches a cloud coder.
+ */
+export async function ensureAgentDeps({ log, confirm, modelHost = canHostMlxModels() }) {
+  const out = {};
+  log("");
+  log("  Checking the agent's dependencies…");
+  // python3 — the whole agent runs on it; we can't install it for the user.
+  if (!(await pyHasModule("sys"))) {
+    log(`  ⚠ ${python3Bin()} not found. Install Python 3 — ${pythonInstallHint()} —`);
+    log("    then run `gu-cli doctor` again.");
+    out.python3 = "missing";
+    return out; // nothing else can be installed without python
+  }
+  out.python3 = "ok";
+
+  const ensurePkg = async (key, probeMod, pkgs, question) => {
+    if (await probeMod()) {
+      out[key] = "present";
+      return;
+    }
+    if (!(await confirm(question, true))) {
+      out[key] = "skipped";
+      log(`  Skipped ${pkgs.join(" ")} — install later: ${python3Bin()} -m pip install -U ${pkgs.join(" ")}`);
+      return;
+    }
+    try {
+      await pipInstall(pkgs, log);
+      out[key] = "installed";
+    } catch (e) {
+      log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+      out[key] = "failed";
+    }
+  };
+
+  // Model-SERVING packages — only where models are actually served. On a client machine
+  // they're dead weight at best: mlx-lm is Apple-Silicon-only and `hf` exists to download
+  // weights this machine will never hold.
+  if (modelHost) {
+    // hf CLI (model downloads). `huggingface_hub` provides the `hf` command.
+    await ensurePkg(
+      "hf",
+      () => which("hf"),
+      ["huggingface_hub"],
+      "Install the Hugging Face CLI (needed to download models)?"
+    );
+    // mlx-lm — runs the local chat + embedding model servers.
+    await ensurePkg("mlxLm", () => pyHasModule("mlx_lm"), ["mlx-lm"], "Install mlx-lm (runs the local model servers)?");
+  } else {
+    out.hf = "skipped-client";
+    out.mlxLm = "skipped-client";
+    log("  · this machine doesn't serve models — skipping mlx-lm / hf (not needed here).");
+  }
+  // The agent framework itself — WITHOUT this every agent turn crashes at import.
+  await ensurePkg(
+    "agentLibs",
+    async () => (await pyHasModule("smolagents")) && (await pyHasModule("openai")),
+    ["smolagents", "openai"],
+    "Install the agent framework (smolagents + openai) — required to run the agent?"
+  );
+  if (out.agentLibs === "skipped" || out.agentLibs === "failed") {
+    log(yellow("  ⚠ Without smolagents + openai the agent can't run — install them before asking a question."));
+  }
+  if (out.agentLibs === "installed") {
+    // Make the daemon use the interpreter these packages actually landed in. ONLY after a
+    // real install: rewriting worker.env when the libs were already there is a side effect
+    // nobody asked for (it fired during a test run against the developer's own config).
+    out.python = await pinPythonForDaemon({ log });
+  }
+  return out;
+}
+
+/**
+ * Start the MLX embeddings server (gonext_mlx_embed.py) DETACHED on `port` for `modelDir`,
+ * with its own pidfile/log. No-op + { ready:true } when one already answers (BC3). Waits up
+ * to waitMs for /v1/models to respond. Mirrors startChatModelServer.
+ */
+export async function startEmbedServer({ modelDir, port, waitMs = 60_000, log = () => {} }) {
+  const base = `http://127.0.0.1:${port}`;
+  if (await probeModelServer(base, { timeoutMs: 1500 })) {
+    return { started: false, ready: true, reason: "already-running" };
+  }
+  if (!(await pyHasModule("mlx_lm"))) {
+    return { started: false, ready: false, reason: "mlx-lm not installed (pip install mlx-lm)" };
+  }
+  await mkdir(DIR, { recursive: true });
+  const outLog = await open(EMBED_LOG_FILE, "a");
+  let pid;
+  try {
+    const child = spawn(
+      python3Bin(),
+      [EMBED_SCRIPT, "--model", modelDir, "--port", String(port), "--host", "127.0.0.1"],
+      { detached: true, stdio: ["ignore", outLog.fd, outLog.fd], env: process.env }
+    );
+    pid = child.pid;
+    await writeFile(EMBED_PID_FILE, String(pid ?? ""), "utf8");
+    child.unref();
+  } finally {
+    await outLog.close();
+  }
+  log(`  starting embeddings server (pid ${pid}) on port ${port} — waiting for it to load…`);
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    await sleep(2500);
+    if (await probeModelServer(base, { timeoutMs: 2000 })) return { started: true, ready: true, pid };
+  }
+  return { started: true, ready: false, pid, reason: `embeddings server still loading (see ${EMBED_LOG_FILE})` };
+}
+
+/**
+ * Ensure RAG is ready for the agent terminal (task #127): boto3 (cloud/S3 storage), the
+ * embedding model, and a running embeddings server. Uses the account's configured embed URL
+ * when it's local; otherwise the default local server on EMBED_PORT. BC3: an already-running
+ * embed server is left alone. Returns a status map.
+ */
+export async function ensureRag({
+  p,
+  log,
+  confirm,
+  prompt,
+  apiBase,
+  workerKey,
+  // INJECTED so a test can prove nothing is WRITTEN, not merely that nothing is asked. The
+  // account write is the damaging half — a prompt is a question you can ignore, a saved
+  // ragEmbedModelPath outlives the session and follows the account to every machine. Without
+  // this seam a test could only spy on the question, and a regression that stopped asking but
+  // still wrote would pass.
+  saveSettings = saveWorkerSettings,
+}) {
+  const out = {};
+  log("");
+  log("  Checking RAG (agent knowledge base)…");
+  // boto3 — needed only for CLOUD (S3) RAG; local RAG stores on disk. Cheap + harmless, so
+  // offer it so cloud RAG works later without another setup pass.
+  if (!(await pyHasModule("boto3"))) {
+    if (await confirm("Install boto3 (needed only if you use cloud/S3 RAG)?", true)) {
+      try {
+        await pipInstall(["boto3"], log);
+        out.boto3 = "installed";
+      } catch (e) {
+        log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+        out.boto3 = "failed";
+      }
+    } else out.boto3 = "skipped";
+  } else out.boto3 = "present";
+
+  // An OLLAMA embedder needs nothing local: Ollama already serves the model on its own port
+  // (`ollama pull qwen3-embedding:8b`), so there is no folder to download and no server for
+  // us to start. Probe it and stop — offering an MLX setup here would be busywork.
+  const configuredEmbedUrl = String(p?.ragEmbedUrl || "").trim();
+  const embedKind = configuredEmbedUrl ? await classifyEmbedder(configuredEmbedUrl) : "none";
+  if (configuredEmbedUrl && embedKind === "ollama") {
+    const reach = await probeReachable(configuredEmbedUrl);
+    log(`  ✓ using an OLLAMA embedder at ${modelRoot(configuredEmbedUrl)}` +
+        (reach.reachable ? "" : " — NOT reachable from here"));
+    log(`    Model name: ${String(p?.ragEmbedModel || "").trim() || "(NOT SET — required for Ollama)"}`);
+    log("    Nothing to install locally: Ollama serves the embedding model itself.");
+    out.embed = reach.reachable ? "ollama" : "ollama-unreachable";
+    return out;
+  }
+  // A REMOTE EMBEDDER IS SETTLED HERE, BEFORE ANY LOCAL SETUP RUNS. This check also exists
+  // further down, but it ran AFTER the "Where should the RAG embedding model be stored?"
+  // prompt — so a configured remote embedder that was merely DOWN FOR A MOMENT got asked
+  // where to keep a local MLX model, and the answer was SAVED TO THE ACCOUNT.
+  //
+  // Observed exactly that way (2026-09-05): ollama2 did not answer for a few seconds, and a
+  // Client Expert machine came out of `gu` carrying
+  // ragEmbedModelPath=/Users/joseph/mlx-models/Qwen3-Embedding-8B-4bit-DWQ — a model that
+  // server does not have and never will. Host-mode setup, written onto a machine that is not
+  // a host, because a probe timed out.
+  //
+  // A LOCAL embedder that is down is the opposite case and must still fall through: setting
+  // one up is precisely what the doctor is for.
+  if (configuredEmbedUrl && !isLocalModelUrl(configuredEmbedUrl)) {
+    log(`  ⚠ your embeddings server (${modelRoot(configuredEmbedUrl)}) is remote and isn't`);
+    log("    answering. Start it there — this machine can't launch it.");
+    log("    Leaving the setting alone — nothing here can serve a remote embedder.");
+    out.embed = "remote";
+    return out;
+  }
+
+  // WHICH model to serve: the folder the user named in the web app (Settings → Agent → RAG,
+  // task #133) if any, else the built-in one we know how to download. A user-supplied folder
+  // is never auto-downloaded — we can only serve what's already on disk.
+  let configuredDir = expandHome(String(p?.ragEmbedModelPath || "").trim());
+  let embedIsCustom = Boolean(configuredDir);
+  // FIRST-TIME setup: nothing is configured yet. Don't silently pick a folder and start
+  // downloading GBs into it — offer the standard location and let the user redirect it (a
+  // Mac with a small boot disk often keeps models on an external drive). Whatever they pick
+  // is saved to the ACCOUNT, so the web app shows the same path this machine is using.
+  if (!configuredDir && prompt) {
+    const answer = String(
+      (await prompt("Where should the RAG embedding model be stored?", EMBED_DIR)) || ""
+    ).trim();
+    const chosen = expandHome(answer) || EMBED_DIR;
+    configuredDir = chosen;
+    // Still NOT "custom" in the don't-auto-download sense: the user just told us where to put
+    // the model we already know how to fetch. That guard exists for a folder configured on the
+    // web that names some OTHER model — downloading ours into it would serve the wrong thing.
+    embedIsCustom = false;
+    const savedToAccount = await saveSettings(apiBase, workerKey, {
+      ragEmbedModelPath: chosen,
+    });
+    log(
+      savedToAccount
+        ? `  ✓ saved to your account — visible in the web app under Settings → Agent → RAG.`
+        : `  ⚠ couldn't save that path to your account (using it for this machine anyway).`
+    );
+  }
+  const embedDir = configuredDir || EMBED_DIR;
+  // WHERE to serve it: an explicit URL still wins (Ollama, another machine); otherwise the
+  // standard embed port, which is exactly what the API derives from the folder. The user
+  // never has to think about the port.
+  const configuredEmbed = String(p?.ragEmbedUrl || "").trim();
+  const embedUrl =
+    configuredEmbed && isLocalModelUrl(configuredEmbed)
+      ? configuredEmbed
+      : `http://127.0.0.1:${EMBED_PORT}`;
+  const embedPort = parsePort(embedUrl) || EMBED_PORT;
+
+  // A REMOTE embedder that's down must be reported as such — check it BEFORE the local
+  // probe. embedUrl falls back to the default local port when the configured one isn't
+  // local, so probing embedUrl first let a locally-running server mask a dead remote one
+  // and report "already running" for a machine the user can't even reach.
+  if (configuredEmbed && !isLocalModelUrl(configuredEmbed)) {
+    log(`  ⚠ your embeddings server (${modelRoot(configuredEmbed)}) is remote and isn't`);
+    log("    answering. Start it there — this machine can't launch it.");
+    out.embed = "remote";
+    return out;
+  }
+  if (await probeModelServer(embedUrl)) {
+    // Same as the chat model: a server left alone because it is up is the one nobody will
+    // check again, and an embedder serving the wrong model silently poisons every index.
+    {
+      const { servedModelAt } = await import("./agent-model-label.mjs");
+      const served = servedModelAt({
+        port: embedPort,
+        servers: await discoverModelServers(),
+        kind: "embed",
+      });
+      log(`  ✓ embeddings server already running at ${modelRoot(embedUrl)} — leaving it alone.`);
+      if (served) {
+        log(`      ${served.name}`);
+        log(`      from ${served.path}`);
+      } else {
+        log(`      (not one of our embed servers here — can't say which model)`);
+      }
+    }
+    out.embed = "already-running";
+    return out;
+  }
+  // Download the embed model if missing. A folder the USER named can't be downloaded — we
+  // don't know what it is — so say what's wrong instead of silently serving a different model.
+  if (!(await modelDirReady(embedDir))) {
+    if (embedIsCustom) {
+      log(`  ⚠ the embedding model folder you set in the web app doesn't exist here:`);
+      log(`      ${embedDir}`);
+      log("    Fix the path in Settings → Agent → RAG, or download the model into it:");
+      log(`      hf download <repo> --local-dir ${embedDir}`);
+      out.embed = "missing-model-dir";
+      return out;
+    }
+    if (!(await confirm(`Download the RAG embedding model ${EMBED_REPO.split("/").pop()} (~4 GB)?`, true))) {
+      log("  Skipped. To do it yourself:");
+      log(`      hf download ${EMBED_REPO} --local-dir ${embedDir}`);
+      log(`      gu-cli embed --model ${embedDir} --port ${embedPort}`);
+      out.embed = "skipped-model";
+      return out;
+    }
+    try {
+      await downloadModel({ repo: EMBED_REPO, dir: embedDir, log });
+    } catch (e) {
+      log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+      out.embed = "download-failed";
+      return out;
+    }
+  }
+  if (!(await confirm(`Start the RAG embeddings server for ${embedDir.split("/").pop()} now?`, true))) {
+    log(`  Skipped. Start it later: gu-cli embed --model ${embedDir} --port ${embedPort}`);
+    out.embed = "not-started";
+    return out;
+  }
+  const r = await startEmbedServer({ modelDir: embedDir, port: embedPort, log });
+  if (r.ready) {
+    // Named for the same reason as the chat model above: the question said which model, so the
+    // confirmation has to as well, or the two lines cannot be checked against each other.
+    log(`  ✓ embeddings server is up: ${modelDisplayName(embedDir)} on port ${embedPort}`);
+    log(`      from ${embedDir}`);
+    out.embed = "started";
+  } else if (r.started) {
+    log(`  … ${modelDisplayName(embedDir)} is loading in the background on port ${embedPort}.`);
+    out.embed = "loading";
+  } else {
+    log(`  ⚠ ${r.reason}`);
+    out.embed = "start-failed";
+  }
+  return out;
+}