@tiens.nguyen/gu-cli 1.0.686

package/client-expert-run.mjs

@@ -0,0 +1,892 @@
+/**
+ * Client Expert, the part that touches the machine (task #154).
+ *
+ * The DECISIONS live in client-expert-setup.mjs and are pure. This file is the other half:
+ * looking at the machine, asking the questions, and writing down what happened. Split that way
+ * because the decisions are the part worth testing and the probes are the part that cannot be.
+ *
+ * The walk runs end to end: mode, MongoDB, the API package, its dependencies, the database and
+ * worker key, starting the API, and pointing worker.env at it. The acting parts live in
+ * client-expert-api.mjs.
+ *
+ * ORDER MATTERS in one place: worker.env is written LAST. It is what marks the machine as
+ * paired, so writing it before the API is proven usable leaves a terminal aimed at something
+ * that does not work — and that state is much harder to get out of than an unfinished setup.
+ */
+import { execFile } from "node:child_process";
+import { readFile, writeFile, mkdir, rm, rename } from "node:fs/promises";
+import { writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import {
+  apiDepsInstalled,
+  installApiDeps,
+  seedDatabase,
+  startLocalApi,
+  waitForApi,
+  probeLocalApi,
+  writeWorkerEnv,
+  seedSettings,
+  modelsAlreadyConfigured,
+  CLIENT_EXPERT_MODELS,
+  LOCAL_API_PORT,
+  LOCAL_API_BASE,
+  API_LOG_FILE,
+  LOCAL_MONGO_URI,
+} from "./client-expert-api.mjs";
+import { askOllamaSetup, localOllamaDefault } from "./ollama-setup.mjs";
+import { parseOllamaTags, formatSize } from "./agent-model-command.mjs";
+import {
+  planSetup,
+  recordStep,
+  resumeAction,
+  stepReason,
+  clientExpertAvailable,
+  mongoInstallPlan,
+  mongoDockerPlan,
+  MONGO_DOCKER_NAME,
+} from "./client-expert-setup.mjs";
+
+const run = promisify(execFile);
+const STATE_FILE = join(homedir(), ".gonext", "client-expert.json");
+
+/** Not an error: the machine is already configured, so the question was skipped. */
+class SkipModelQuestion extends Error {}
+
+/**
+ * GET /api/tags, as askOllamaSetup's injected fetcher.
+ *
+ * THROWS on anything that is not a usable list, and that is the contract: the caller
+ * distinguishes "could not reach the box" (this throws) from "reached it and it has nothing"
+ * (this returns []), and those two get different messages because they need different fixes.
+ * A short timeout, because a box that has not answered in eight seconds is not going to.
+ */
+async function fetchOllamaTags(url) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(8000) });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  // parseOllamaTags is tolerant by design — HTML from a proxy, an empty body and a shape from a
+  // future Ollama all become []. That is "reachable but not usable", which the caller reports as
+  // such rather than as a network failure.
+  return parseOllamaTags(await res.json().catch(() => null));
+}
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+
+/** Best-effort: never let a probe throw into the setup flow. */
+async function tryRun(cmd, args, timeout = 5000) {
+  try {
+    const { stdout } = await run(cmd, args, { timeout });
+    return String(stdout || "").trim();
+  } catch {
+    return null;
+  }
+}
+
+/** What this machine IS — enough to decide whether MongoDB can run here at all. */
+export async function probeMachine() {
+  const platform = process.platform;
+  // platform-ok: uname is absent on Windows; tryRun returns null and process.arch answers.
+  const arch = (await tryRun("uname", ["-m"])) ?? process.arch;
+  // The CPU model is what separates a Pi 4 (ARMv8.0, mongod dies) from a Pi 5 (fine).
+  let cpuModel = "";
+  if (platform === "linux") {
+    const info = await tryRun("sh", ["-c", "grep -m1 -i 'model' /proc/cpuinfo || true"]);
+    cpuModel = (info ?? "").replace(/^.*?:\s*/, "");
+    if (!cpuModel) cpuModel = (await tryRun("sh", ["-c", "cat /proc/device-tree/model 2>/dev/null || true"])) ?? "";
+  }
+  return { platform, arch, cpuModel };
+}
+
+/**
+ * Can something be reached at this address? Raw TCP, no driver required.
+ *
+ * The driver lives inside the downloaded API, which does not exist yet at the MongoDB step —
+ * so the only connection check available here is a socket. It proves REACHABILITY, not that
+ * the thing answering speaks MongoDB; the seed step proves that, and fails legibly if not.
+ */
+export function mongoHostPort(uri) {
+  try {
+    // mongodb://user:pass@host:port/db — the URL parser handles the credentials and the path.
+    const u = new URL(String(uri).replace(/^mongodb(\+srv)?:\/\//, "http://"));
+    return { host: u.hostname || "127.0.0.1", port: Number(u.port) || 27017 };
+  } catch {
+    return { host: "127.0.0.1", port: 27017 };
+  }
+}
+
+async function tcpReachable(host, port, timeoutMs = 3000) {
+  const net = await import("node:net");
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port });
+    const done = (ok) => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+/**
+ * Is there a database this machine can USE? Not "is a mongod installed here" — those are
+ * different questions, and answering the second one blocked a machine where the first was
+ * plainly true (see the socket check below).
+ */
+export async function probeMongo() {
+  // The ping first, on every platform: it is the only check that proves the database ANSWERS.
+  // A service marked "running" that refuses connections is the failure this catches.
+  const ping = await tryRun("mongosh", ["--quiet", "--eval", "db.runCommand({ping:1}).ok"], 8000);
+  if (ping && ping.trim().endsWith("1")) return { running: true, how: "mongosh ping" };
+
+  // THEN THE SOCKET, before any process or service lookup.
+  //
+  // Everything below this line asks "is a mongod running ON THIS MACHINE", which is a
+  // different question from the one that matters: "is there a database I can use". A MongoDB
+  // in Docker — a very common way to run one — is reachable on 27017 while being invisible to
+  // both `pgrep` and `mongosh`, so setup declared it missing and refused to continue on a
+  // machine where it worked perfectly. Found exactly that way, in a container, on Linux.
+  const { host, port } = mongoHostPort(LOCAL_MONGO_URI);
+  if (await tcpReachable(host, port)) {
+    return { running: true, how: `listening at ${host}:${port}` };
+  }
+
+  if (process.platform === "win32") {
+    // winget's MongoDB installs a SERVICE, so that is what to ask about — a process lookup
+    // would miss a service that is registered but stopped, which is the state we most want to
+    // tell apart from "not installed".
+    const svc = await tryRun("sc.exe", ["query", "MongoDB"]);
+    if (svc && /STATE\s*:\s*4\s+RUNNING/i.test(svc)) {
+      return { running: true, how: "MongoDB service" };
+    }
+    return { running: false, how: null, installed: Boolean(svc && /SERVICE_NAME/i.test(svc)) };
+  }
+
+  // platform-ok: unreachable on Windows — the win32 branch above returns before this line.
+  const pid = await tryRun("pgrep", ["-x", "mongod"]);
+  if (pid) return { running: true, how: `mongod process ${pid.split("\n")[0]}` };
+  // THE SERVER AND THE SHELL ARE DIFFERENT QUESTIONS, and conflating them sent a user to a
+  // command that could not work. This used to be
+  //     command -v mongod || command -v mongosh
+  // so `mongosh` alone — the CLIENT, which arrives on its own via a standalone download, an
+  // Atlas workflow or some other tool that bundles it — set `installed: true`. The caller then
+  // took the "installed but not answering" branch and printed
+  //     brew services start mongodb-community
+  // on a machine with no server and no tap, which fails with "No available formula with the
+  // name mongodb-community". Reported on a fresh Mac and reproduced on the dev Mac, which is in
+  // exactly that state: mongosh present, mongod absent, untapped.
+  //
+  // `installed` now means THE SERVER. The shell is reported separately because it is worth
+  // saying ("you already have mongosh") and because `verify` runs through it.
+  const serverPath = (await tryRun("sh", ["-c", "command -v mongod || true"])) || "";
+  const shellPath = (await tryRun("sh", ["-c", "command -v mongosh || true"])) || "";
+  return {
+    running: false,
+    how: null,
+    installed: Boolean(serverPath.trim()),
+    shellInstalled: Boolean(shellPath.trim()),
+  };
+}
+
+/**
+ * Is Docker usable right now, and does our container already exist?
+ * → { usable, containerExists }
+ *
+ * `docker ps` rather than `which docker`: Docker Desktop is very often installed and not
+ * running, and "start Docker Desktop" is a different instruction from "install Docker".
+ */
+export async function probeDockerForMongo(name = MONGO_DOCKER_NAME) {
+  const ps = await tryRun("docker", ["ps", "--format", "{{.Names}}"], 8000);
+  if (ps === null) {
+    // WHICH KIND OF "no docker" IS THIS? (reported 2026-08-24, macOS)
+    //
+    // `docker ps` fails identically whether docker is absent or Docker Desktop is merely not
+    // RUNNING, and on macOS the second is overwhelmingly the common case — the CLI is installed,
+    // the daemon is not up, and the fix is to open an app rather than to install anything.
+    // `docker --version` answers from the CLI alone and does not need the daemon, so it
+    // separates the two. Callers use this to say which one it is instead of failing silently.
+    const version = await tryRun("docker", ["--version"], 5000);
+    return {
+      usable: false,
+      containerExists: false,
+      installed: version !== null,
+      daemonDown: version !== null, // installed but `docker ps` failed ⇒ the daemon is not up
+    };
+  }
+  // -a, because a STOPPED container of ours is the case where `docker start` is the answer and
+  // `docker run` would fail on the name conflict.
+  const all = await tryRun(
+    "docker", ["ps", "-a", "--filter", `name=^/${name}$`, "--format", "{{.Names}}"], 8000
+  );
+  return {
+    usable: true,
+    containerExists: Boolean((all || "").trim()),
+    installed: true,
+    daemonDown: false,
+  };
+}
+
+/**
+ * Start MongoDB in a container and wait for it to answer. → true when it is up.
+ *
+ * Waits on the SOCKET rather than on `docker run` returning: run returns as soon as the
+ * container is created, and mongod then takes a few seconds to accept connections. Reporting
+ * success at the wrong moment would fail the very next step of setup.
+ */
+export async function startMongoInDocker(ask, { platform = process.platform } = {}) {
+  const { usable, containerExists, daemonDown } = await probeDockerForMongo();
+  if (!usable) {
+    // SAY WHY, rather than returning false into silence (reported 2026-08-24 on macOS).
+    // The caller has just told the user MongoDB is not reachable and that it must be started
+    // first; returning quietly here left that sentence with no follow-up at all, and the
+    // commonest cause on a Mac — Docker Desktop not running — is a 10-second fix nobody was
+    // told about.
+    console.log(
+      daemonDown
+        ? red("  Docker is installed but not running.") +
+            dim(
+              platform === "darwin"
+                ? "\n    Open Docker Desktop, wait for the whale icon to settle, then re-run this."
+                : "\n    Start the Docker daemon (e.g. `sudo systemctl start docker`), then re-run this."
+            )
+        : red("  Docker is not available here, and MongoDB is what stores your conversations.") +
+            dim(
+              platform === "darwin"
+                ? "\n    Install Docker Desktop (https://docker.com), or a native MongoDB" +
+                  "\n    (`brew tap mongodb/brew && brew install mongodb-community`)."
+                : "\n    Install Docker, or MongoDB itself, then re-run this."
+            )
+    );
+    return false;
+  }
+  const plan = mongoDockerPlan({ exists: containerExists });
+  console.log("\n  " + bold("Docker is available on this machine."));
+  console.log(dim(`  Simplest path: ${plan.summary}.`));
+  console.log(dim("  Your conversation history lives in that volume and survives a restart."));
+  console.log(dim("\n    " + plan.commands[0] + "\n"));
+  const yes = await ask("  Start MongoDB in Docker now? [Y/n]: ");
+  if (String(yes ?? "").trim().toLowerCase().startsWith("n")) return false;
+
+  for (const cmd of plan.commands) {
+    console.log(dim(`  $ ${cmd}`));
+    const out = await tryRun("sh", ["-c", cmd], 180000);
+    if (out === null) {
+      console.log(red("  that command failed — run it yourself to see why, then re-run `gu`."));
+      return false;
+    }
+  }
+  // Up to ~60s: pulling mongo:8 on a fresh machine is the slow part, and it happens inside
+  // `docker run`, so the wait here is only mongod's own start-up.
+  const { host, port } = mongoHostPort(LOCAL_MONGO_URI);
+  process.stdout.write(dim("  waiting for MongoDB to accept connections"));
+  for (let i = 0; i < 30; i++) {
+    if (await tcpReachable(host, port, 2000)) {
+      console.log(cyan("  ✓ MongoDB is up") + dim(` at ${host}:${port} (container ${MONGO_DOCKER_NAME})`));
+      return true;
+    }
+    process.stdout.write(dim("."));
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  console.log(red("\n  it did not start answering — check `docker logs " + MONGO_DOCKER_NAME + "`."));
+  return false;
+}
+
+/**
+ * Where the published API packages live. Overridable so a fork, a staging bucket or an
+ * air-gapped mirror does not need a code change.
+ */
+export const API_PACKAGE_URL =
+  process.env.GONEXT_API_PACKAGE_URL ||
+  "https://gu-api-packages.s3.ap-southeast-1.amazonaws.com/latest.json";
+
+/** Where a downloaded API is unpacked: one directory per version, never overwritten. */
+export const apiInstallDir = (version) =>
+  join(homedir(), ".gonext", "api", String(version));
+
+/**
+ * What the publisher says is current.
+ *
+ * Read EVERY time rather than cached, because "use the latest API" is the whole point: a
+ * machine set up months ago and one set up today must land on the same version.
+ */
+export async function fetchLatestApi(url = API_PACKAGE_URL) {
+  const res = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(20_000) });
+  if (!res.ok) throw new Error(`${res.status} fetching ${url}`);
+  const m = await res.json();
+  for (const field of ["version", "url", "sha256"]) {
+    if (!m?.[field]) throw new Error(`latest.json is missing "${field}"`);
+  }
+  return m;
+}
+
+/** Which API version (if any) is already unpacked here. */
+export async function probeApiInstall(version) {
+  if (!version) return { installed: false, dir: null };
+  const dir = apiInstallDir(version);
+  try {
+    // package.json, not the folder: an interrupted download leaves a directory behind, and a
+    // directory is exactly what a naive "is it installed?" check would accept.
+    await readFile(join(dir, "package.json"), "utf8");
+    return { installed: true, dir };
+  } catch {
+    return { installed: false, dir };
+  }
+}
+
+/**
+ * Download and unpack the published API.
+ *
+ * VERIFIED BEFORE IT IS UNPACKED. A truncated download still produces a file, and a partial
+ * unpack still produces a folder — which the install check would then accept forever. The
+ * checksum is the only thing that distinguishes "downloaded" from "downloaded correctly".
+ */
+export async function downloadApiPackage(manifest, { onProgress = () => {} } = {}) {
+  const dir = apiInstallDir(manifest.version);
+  onProgress(`downloading ${manifest.file ?? manifest.version}…`);
+  const res = await fetch(manifest.url, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(120_000),
+  });
+  if (!res.ok) throw new Error(`${res.status} downloading ${manifest.url}`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+
+  const got = createHash("sha256").update(bytes).digest("hex");
+  if (manifest.sha256 && got !== manifest.sha256) {
+    throw new Error(
+      `checksum mismatch — expected ${manifest.sha256.slice(0, 12)}…, got ${got.slice(0, 12)}…. ` +
+      "The download was corrupted or the published package changed; nothing was installed."
+    );
+  }
+  if (manifest.bytes && bytes.length !== manifest.bytes) {
+    throw new Error(`size mismatch — expected ${manifest.bytes} bytes, got ${bytes.length}`);
+  }
+
+  // Unpack into a TEMP directory and move it into place only once it is whole, so an
+  // interrupted extraction can never leave a half-populated version dir looking installed.
+  const staging = `${dir}.incoming`;
+  await rm(staging, { recursive: true, force: true });
+  await mkdir(staging, { recursive: true });
+  const tmpTar = join(staging, "package.tar.gz");
+  await writeFile(tmpTar, bytes);
+  onProgress(`unpacking ${bytes.length} bytes…`);
+  await run("tar", ["xzf", tmpTar, "-C", staging]);
+  await rm(tmpTar, { force: true });
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(join(homedir(), ".gonext", "api"), { recursive: true });
+  await rename(staging, dir);
+  onProgress(`installed ${manifest.version} → ${dir}`);
+  return { dir, version: manifest.version };
+}
+
+export async function loadState() {
+  try {
+    return JSON.parse(await readFile(STATE_FILE, "utf8")) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+export async function saveState(state) {
+  try {
+    await mkdir(join(homedir(), ".gonext"), { recursive: true });
+    await writeFile(STATE_FILE, JSON.stringify(state, null, 2) + "\n");
+  } catch {
+    /* the walkthrough still works without notes; it just re-verifies more */
+  }
+}
+
+/**
+ * The one question that cannot be probed. Returns "host" | "client" | "client-expert" | null.
+ *
+ * `ask` is injected so this file never owns a readline — the caller is mid-first-run and
+ * already has one open.
+ */
+/** `win32` is a build target, not something to show a person. */
+function platformName(p) {
+  return { win32: "Windows", darwin: "macOS", linux: "Linux" }[p] ?? String(p);
+}
+
+export async function askMode(ask, { expertAvailable, expertWhy, platform = process.platform }) {
+  // HOST IS macOS-ONLY, AND THE MENU HAS TO ENFORCE THAT, not merely mention it. Serving models
+  // to your account means running MLX, which is Apple-silicon only — but option 2 was offered
+  // and accepted everywhere, so a Windows or Linux user could read "macOS only", pick it anyway,
+  // and be put into a mode that cannot work on their machine. Local (option 3) has had a real
+  // availability gate all along; this gives Host the same one, so every line in the menu is now
+  // a promise the menu keeps. Existing machines are unaffected: `chosenMode` is already saved,
+  // and shouldAskMode() never re-asks a settled machine.
+  const hostAvailable = platform === "darwin";
+  console.log("");
+  console.log(bold("  How should this machine run?"));
+  // THE NAMES SAY WHO KEEPS THE CHAT HISTORY, by request. The previous set led with hardware
+  // ("I can share data (> 16GB of VRAM)"), which answered a question nobody asks first: the
+  // thing a person actually decides here is whether their conversations are stored by us or
+  // stay on their machine. So that is the name, and the hardware and platform facts move to
+  // the line underneath, where they still gate the choice.
+  console.log(`    ${bold("1")}  We store chat history for you ${dim("— models and data are hosted; this")}`);
+  console.log(`       ${dim("         machine just runs the agent. Ubuntu, Windows or macOS.")}`);
+  if (hostAvailable) {
+    console.log(`    ${bold("2")}  MLX — We store chat history for you ${dim("— this Mac's GPU serves the")}`);
+    console.log(`       ${dim("         models to your account; the history is still hosted. macOS only.")}`);
+  } else {
+    console.log(`    ${bold("2")}  ${dim(`MLX — We store chat history for you — not on ${platformName(platform)}: serving needs a Mac`)}`);
+    console.log(`       ${dim("         with Apple silicon and 16 GB or more of unified memory.")}`);
+  }
+  if (expertAvailable) {
+    console.log(`    ${bold("3")}  You need private ${dim("— the whole stack (API, database, models) on")}`);
+    console.log(`       ${dim("         this machine; nothing it does is shared. macOS, Ubuntu or Windows.")}`);
+  } else {
+    console.log(`    ${bold("3")}  ${dim(`You need private — not on ${platformName(platform)}: it needs macOS or Ubuntu,`)}`);
+    console.log(`       ${dim(`         ${expertWhy}`)}`);
+  }
+  const typed = (await ask("  choose [1]: ")).trim();
+  // THE RETURNED STRINGS ARE STORAGE, NOT LABELS, and they deliberately did not change with
+  // the names above. `chosenMode` is already on disk on every machine in the field; renaming
+  // the value would make shouldAskMode() stop recognising it and re-ask the mode question on
+  // upgrade — which has happened before, to machines that had been working for months, and is
+  // why client-host-modes.test.mjs exists. A value rename needs a read-side migration first.
+  if (typed === "3") return expertAvailable ? "client-expert" : null;
+  if (typed === "2") return hostAvailable ? "host" : null;
+  return "client";
+}
+
+/**
+ * Walk Client Expert setup as far as it currently goes, printing what is happening.
+ *
+ * Returns { complete, stoppedAt } so the caller knows whether to carry on into the normal
+ * first-run flow or to leave the user with instructions and exit.
+ */
+/**
+ * Remember where we were if the process dies mid-step.
+ *
+ * Every EARLY RETURN records its step — that is the resume mechanism and it is tested. What
+ * nothing recorded was a Ctrl+C, a closed window, or a crash DURING a step: the longest ones
+ * here are a 350-package install and a model download, which is exactly when someone gives up
+ * and walks away. The plan then still said the previous step was the last thing that happened,
+ * so the next run had nothing to say about where it stopped.
+ *
+ * Records the step as INTERRUPTED, not failed: nothing went wrong, and it must not count
+ * toward the give-up-after-three-attempts logic.
+ */
+export function markInterruptedOnExit(getState, stepId) {
+  let done = false;
+  const mark = () => {
+    if (done) return;
+    done = true;
+    try {
+      const state = getState();
+      // Synchronous on purpose: an exit handler gets no await, and a promise here would be
+      // abandoned before it wrote anything.
+      writeFileSync(
+        STATE_FILE,
+        JSON.stringify(
+          { ...recordStep(state, stepId, "interrupted", { reason: "interrupted — gu stopped during this step" }) },
+          null,
+          2
+        ) + "\n"
+      );
+    } catch {
+      /* a best-effort note; never let it interfere with the exit itself */
+    }
+    // AND ACTUALLY STOP. Registering a SIGINT listener REPLACES Node's default behaviour, so
+    // without this the note was written and setup carried straight on — finishing the step and
+    // recording it "done" over the interruption. Ctrl+C during a minute-long install has to
+    // mean what the user meant by it.
+    console.log(
+      "\n  " + yellow("Stopped.") +
+      dim(" Run `gu` again and setup continues from this step.\n")
+    );
+    process.exit(130); // 128 + SIGINT, the conventional code for "killed by Ctrl+C"
+  };
+  process.once("SIGINT", mark);
+  process.once("SIGTERM", mark);
+  return () => {
+    process.off("SIGINT", mark);
+    process.off("SIGTERM", mark);
+  };
+}
+
+export async function runClientExpertSetup({ ask }) {
+  const machine = await probeMachine();
+  const gate = clientExpertAvailable({ workerEnvExists: false, ...machine });
+  if (!gate.available) {
+    console.log("\n  " + red("✗ ") + gate.message + "\n");
+    return { complete: false, stoppedAt: "gate" };
+  }
+
+  let state = await loadState();
+  const mongo = await probeMongo();
+  const probe = {
+    mode: "client-expert",
+    mongoRunning: mongo.running,
+    // Everything below MongoDB is not implemented yet — reported honestly rather than guessed.
+    dbReady: false,
+    apiInstalled: false,
+    apiHealthy: false,
+    contractOk: false,
+    workerEnvPointsLocal: false,
+    modelsConfigured: false,
+  };
+  state = recordStep(state, "mode", "done");
+  await saveState(state);
+
+  const plan = planSetup({ recorded: state, probe });
+  console.log("\n  " + bold("Local mode setup") + dim(`   ${machine.platform}/${machine.arch}`));
+  for (const step of plan.steps) {
+    const mark = step.state === "done" ? cyan("✓") : step.state === "reopened" ? yellow("↻") : dim("·");
+    console.log(`    ${mark} ${step.state === "done" ? dim(step.title) : step.title}`);
+  }
+  if (plan.resuming) {
+    console.log("\n  " + dim(`resuming — you stopped during "${plan.next}" last time`));
+    const why = stepReason(state, plan.next);
+    if (why) console.log("  " + dim(`(${why})`));
+    const resume = resumeAction(state, plan.next);
+    for (const c of resume.cleanup) console.log("  " + dim(`first: ${c}`));
+  }
+
+  if (plan.next === "mongo") {
+    // WE ONLY CHECK. Installing a database is a system-wide change needing sudo, a package
+    // manager and a working repo for this architecture — none of which a terminal should take
+    // on unasked, and all of which the user can do better themselves. An earlier version asked
+    // "Install MongoDB now? [y/N]", which was a question this code could not honour: it prints
+    // commands either way, so "yes" and "no" did the same thing. A choice that changes nothing
+    // is worse than no choice.
+    console.log("\n  " + bold("MongoDB is not running on this machine."));
+    console.log(dim("  Local mode keeps every conversation and token count in a database"));
+    console.log(dim("  on THIS machine, so it needs one before setup can go further."));
+    // DOCKER FIRST, WHERE IT EXISTS. This is the one branch here that can actually finish the
+    // job rather than print homework: one container, no tap, no system service, and the same
+    // mongo:8 the project's own end-to-end tests run against. Only offered when `docker ps`
+    // answers, so a machine with Docker installed-but-not-running is not sent down a dead end.
+    // On success setup CONTINUES in this same run instead of asking the user to start over.
+    if (await startMongoInDocker(ask)) {
+      mongo.running = true;
+      probe.mongoRunning = true;
+    }
+    if (probe.mongoRunning) {
+      // fall through to the rest of setup below — nothing left to instruct.
+    } else if (mongo.installed) {
+      console.log(dim("\n  It looks installed but is not answering. Start it with:\n"));
+      console.log(
+        "    " + (machine.platform === "darwin"
+          ? "brew services start mongodb-community"
+          : machine.platform === "win32"
+            ? "net start MongoDB"
+            : "sudo systemctl enable --now mongod")
+      );
+    } else {
+      const install = mongoInstallPlan(machine.platform);
+      console.log(dim("\n  Install it however you prefer — for reference, the usual way here is:\n"));
+      for (const c of install.commands) console.log(dim("    " + c));
+      console.log("\n  " + dim(`then check it answers:  ${install.verify}`));
+    }
+    // STOP ONLY IF IT IS STILL NOT RUNNING. When Docker started one above there is nothing to
+    // wait for, so setup carries straight on in this run — sending someone away to re-run
+    // `gu` after we have just solved their problem for them is the kind of small
+    // indignity that makes a tool feel unfinished.
+    if (!probe.mongoRunning) {
+      // No "meanwhile this works in CLIENT mode" any more: that fallback signed the user in,
+      // which wrote the worker.env that marks a machine as paired — and then refused Local
+      // mode because the machine was paired. Nothing is configured here yet, so the honest
+      // end of this path is the instruction and an exit.
+      console.log("\n  " + dim("Run `gu` again once it is running — setup continues from here."));
+      // Recorded as interrupted, not failed: nothing went wrong, the user simply has something
+      // to do first. The next run greets them as a resume rather than as a stranger.
+      state = recordStep(state, "mongo", "interrupted", {
+        reason: mongo.installed ? "installed but not answering" : "not installed yet",
+      });
+      await saveState(state);
+      console.log("");
+      return { complete: false, stoppedAt: "mongo" };
+    }
+    // Re-probe rather than trusting the flag: the socket answered, but `how` is what the
+    // success line below reports, and it should say what actually found it.
+    const after = await probeMongo();
+    if (after.running) {
+      mongo.running = true;
+      mongo.how = after.how;
+    }
+  }
+
+  console.log("\n  " + cyan("✓ MongoDB is running") + dim(` (${mongo.how})`));
+  state = recordStep(state, "mongo", "done");
+  await saveState(state);
+
+  // --- the API package -----------------------------------------------------------------
+  // ALWAYS asks the publisher what is current, rather than trusting anything cached: "a new
+  // machine gets the latest API" is the whole promise, and a machine set up months from now
+  // must land on the same version as one set up today.
+  let manifest;
+  try {
+    manifest = await fetchLatestApi();
+  } catch (e) {
+    console.log("\n  " + red("✗ ") + `Could not reach the API package index: ${e.message}`);
+    console.log(dim("  Setup needs it to know which API to install. Check the network and run"));
+    console.log(dim("  `gu` again — nothing has been changed on this machine.\n"));
+    state = recordStep(state, "api-files", "failed", { reason: `index unreachable: ${e.message}` });
+    await saveState(state);
+    return { complete: false, stoppedAt: "api-files" };
+  }
+
+  const have = await probeApiInstall(manifest.version);
+  if (have.installed) {
+    console.log("  " + cyan("✓ API ") + dim(`${manifest.version} already downloaded`));
+  } else {
+    console.log("\n  " + bold(`Downloading the API (${manifest.version})`) +
+      dim(`   ${Math.round((manifest.bytes ?? 0) / 1024)} KB`));
+    const unmark = markInterruptedOnExit(() => state, "api-files");
+    try {
+      await downloadApiPackage(manifest, { onProgress: (m) => console.log(dim("    " + m)) });
+    } catch (e) {
+      // A checksum or size mismatch lands here, and NOTHING was installed — the unpack goes
+      // to a staging dir and is only moved into place once it is whole.
+      console.log("\n  " + red("✗ ") + e.message + "\n");
+      state = recordStep(state, "api-files", "failed", { reason: e.message });
+      await saveState(state);
+      return { complete: false, stoppedAt: "api-files" };
+    } finally {
+      unmark();
+    }
+  }
+  state = recordStep(state, "api-files", "done");
+  await saveState(state);
+
+  // --- dependencies --------------------------------------------------------------------
+  // The package ships source only (~145 KB); its ~360 dependencies are installed here. This
+  // is the slowest step by far, so it says so rather than looking hung.
+  const apiDir = apiInstallDir(manifest.version);
+  if (!(await apiDepsInstalled(apiDir))) {
+    console.log("\n  " + bold("Installing the API's dependencies") + dim("   this takes a minute"));
+    const unmark = markInterruptedOnExit(() => state, "database");
+    try {
+      await installApiDeps(apiDir, {
+        onLine: (l) => l && l.length < 200 && console.log(dim("    " + l)),
+      });
+    } catch (e) {
+      console.log("\n  " + red("✗ ") + e.message + "\n");
+      state = recordStep(state, "database", "failed", { reason: `npm install: ${e.message}` });
+      await saveState(state);
+      return { complete: false, stoppedAt: "database" };
+    } finally {
+      unmark();
+    }
+  }
+
+  // --- database + worker key -----------------------------------------------------------
+  // Reuses the key already minted for this machine when there is one, so re-running setup
+  // does not strand the rows written under the previous identity.
+  let creds;
+  const hadKey = Boolean(state.localWorkerKey);
+  try {
+    creds = await seedDatabase({
+      apiDir,
+      userId: state.localUserId,
+      workerKey: state.localWorkerKey,
+    });
+  } catch (e) {
+    console.log("\n  " + red("✗ ") + `Could not prepare the database: ${e.message}`);
+    console.log(dim("  MongoDB answered a moment ago, so this is usually a permissions or"));
+    console.log(dim("  connection-string problem. Nothing has been changed.\n"));
+    state = recordStep(state, "database", "failed", { reason: e.message });
+    await saveState(state);
+    return { complete: false, stoppedAt: "database" };
+  }
+  // Says what actually happened: on a re-run nothing is created, and claiming otherwise would
+  // make an idempotent step look destructive.
+  console.log(
+    "  " + cyan("✓ Database ready") +
+    dim(` (${creds.dbName}) — worker key ${hadKey ? "reused" : "created"}`)
+  );
+  // Persisted so a later run reuses this identity instead of minting a second one.
+  state = { ...state, localUserId: creds.userId, localWorkerKey: creds.workerKey };
+  state = recordStep(state, "database", "done");
+  await saveState(state);
+
+  // --- the API itself -------------------------------------------------------------------
+  let health = await probeLocalApi(LOCAL_API_PORT);
+  if (!health.ok) {
+    console.log("\n  " + bold(`Starting the local API on port ${LOCAL_API_PORT}`));
+    await startLocalApi({ apiDir });
+    health = await waitForApi({ port: LOCAL_API_PORT });
+  }
+  if (!health.ok) {
+    // apiIsUsable, not a 200: a wrong DATA_BACKEND answers 200 and stores nothing.
+    console.log("\n  " + red("✗ ") + `The API started but is not usable: ${health.why}`);
+    console.log(dim(`  Its log is ${API_LOG_FILE}`));
+    console.log(dim("  Run `gu` again to retry — nothing else has been changed.\n"));
+    state = recordStep(state, "api-running", "failed", { reason: health.why });
+    await saveState(state);
+    return { complete: false, stoppedAt: "api-running" };
+  }
+  console.log("  " + cyan("✓ API answering") + dim(` on ${LOCAL_API_BASE} (mongo, persistence on)`));
+  state = recordStep(state, "api-running", "done");
+  await saveState(state);
+
+  // --- point this terminal at it --------------------------------------------------------
+  // LAST, and only now: worker.env is what makes the machine "paired", so writing it before
+  // the API was proven usable would leave a terminal pointed at something that does not work.
+  const envPath = await writeWorkerEnv({
+    apiBase: LOCAL_API_BASE,
+    workerKey: creds.workerKey,
+  });
+  console.log("  " + cyan("✓ Terminal pointed at the local API") + dim(` (${envPath})`));
+  state = recordStep(state, "worker-env", "done");
+  await saveState(state);
+
+  // RESTART THE DAEMON, because worker.env just changed under it.
+  //
+  // The daemon reads GONEXT_API_BASE and GONEXT_WORKER_KEY ONCE, at startup. A machine that ran
+  // `gu` before choosing Client Expert already has one polling the HOSTED api with the old
+  // key — and daemonStatus() finds a running daemon by scanning processes, so nothing starts a
+  // new one either. The result is a machine where every check passes and no turn ever runs:
+  // questions are enqueued into the local database and the only worker is watching a different
+  // one. "The local API works but actually not working" — reported exactly that way.
+  try {
+    const ctl = await import("./daemon-control.mjs");
+    const status = await ctl.daemonStatus();
+    if (status.running) {
+      await ctl.stopDaemon();
+      const r = await ctl.startDaemon();
+      console.log(
+        "  " + cyan("✓ Background worker restarted") +
+        dim(r.started ? ` (pid ${r.pid}) — it now polls the local API` : " — start it with `gu start`")
+      );
+    }
+  } catch (e) {
+    // Non-fatal, but say so: a stale daemon is the difference between "set up" and "works".
+    console.log("\n  " + yellow("⚠ could not restart the background worker: ") + e.message);
+    console.log(dim("  Run `gu-cli restart` — until you do, turns will be enqueued but"));
+    console.log(dim("  never picked up, because the running worker is still polling the old API.\n"));
+  }
+
+  // --- models -------------------------------------------------------------------------
+  // The LAST step, and the one that was missing entirely: this machine's database is brand
+  // new, so it has no settings row, and the terminal refused to start with "no agent model is
+  // configured for your account yet" — advice that points at the hosted API this machine
+  // deliberately does not use. A normal account gets these defaults seeded when it pairs;
+  // Client Expert never pairs, so it seeds its own.
+  // ASK WHICH BOX (task #220). It used to seed the shared Ollama with no question, because the
+  // alternative at the time was "a URL that answers nothing" — the failure that shipped a
+  // "successfully configured" machine whose first question failed. The question is back, and it
+  // is safe now for one reason: askOllamaSetup PROVES the box answers and lists a usable model
+  // before it returns anything. Enter accepts the shared box, so nobody who does not care has to
+  // think about it, and a machine on a LAN can finally say so.
+  //
+  // A null answer — declined, or a box we could not reach after retries — falls through to the
+  // seeded defaults, which is exactly today's behaviour plus today's Kimi path via `/model`.
+  let chosenModels;
+  try {
+    // DO NOT ASK A QUESTION WE WOULD THEN IGNORE. settingsPatch leaves an already-configured
+    // machine alone (that rule protects anyone who set their models up by hand), so on a re-run
+    // of this step the answer would be collected and silently discarded. Point at `/model`
+    // instead — it is the one path that CAN change a machine that is already set up.
+    const already = await modelsAlreadyConfigured({ apiDir, userId: creds.userId });
+    if (already) {
+      console.log("");
+      console.log(dim("  Models are already configured on this machine — leaving them alone."));
+      console.log(dim("  To point it at a different Ollama server: `/model` → change the Ollama"));
+      console.log(dim("  server this machine uses."));
+      throw new SkipModelQuestion();
+    }
+    console.log("");
+    console.log("  " + bold("Which Ollama server should this machine use?"));
+    // THIS MACHINE FIRST, when it has one. Client Expert is the mode whose whole promise is
+    // "the whole stack on this machine; nothing it does is shared" — and it was offering a
+    // shared server on someone else's hardware as the default, which is the opposite of what
+    // was chosen one question earlier. Probed rather than assumed, so a machine without Ollama
+    // is still offered the shared box exactly as before.
+    const defaultUrl = await localOllamaDefault(
+      CLIENT_EXPERT_MODELS.url,
+      fetchOllamaTags,
+      { log: (l) => console.log(dim(l)) },
+    );
+    const isLocal = defaultUrl !== CLIENT_EXPERT_MODELS.url;
+    console.log(
+      dim(
+        isLocal
+          ? "    Enter uses the one on this machine. Or give another — 192.168.1.40,"
+          : "    Enter keeps the shared one. Or give your own — 192.168.1.40,",
+      ),
+    );
+    console.log(dim("    ollama.local, http://box:11434 — and pick from what it actually has."));
+    chosenModels = await askOllamaSetup(ask, {
+      defaultUrl,
+      fetchTags: fetchOllamaTags,
+      formatSize,
+      // THE SHIPPED DEFAULT WINS WHEN THE BOX HAS IT. Without this a fresh machine falls back to
+      // a size heuristic, and on a box with several similar builds that picks by size alone —
+      // observed on ollama2, where gemma4-quadro:latest and gemma4-quadro-49k:latest are
+      // byte-identical and only the second has the configured 49k context. Every other machine
+      // gets the shipped coder; a new one should not differ because of a tie-break.
+      preferred: { code: CLIENT_EXPERT_MODELS.code },
+    });
+  } catch (e) {
+    // A question that throws must never cost the machine its setup — fall back to the seed.
+    // The skip is not a failure and says nothing extra; it has already printed its own line.
+    if (!(e instanceof SkipModelQuestion)) {
+      console.log(dim(`  (could not ask: ${e.message} — using the shared Ollama)`));
+    }
+    chosenModels = null;
+  }
+
+  try {
+    const written = await seedSettings({
+      apiDir,
+      userId: creds.userId,
+      ...(chosenModels ? { models: chosenModels } : {}),
+    });
+    if (Object.keys(written).length === 0) {
+      console.log("  " + cyan("✓ Models and RAG") + dim(" — already configured, left alone"));
+    } else {
+      console.log(
+        "  " + cyan("✓ Models and RAG configured") +
+        dim(chosenModels ? " — the server you chose" : " — the shared Ollama")
+      );
+      // NAME ALL THREE. Without a key there is no cloud coder, so the machine falls back to
+      // the shared Ollama for everything — and someone who did not choose that should not have
+      // to read the database to find out what their turns are actually using.
+      const host = String(written.agentModelUrl || "").replace(/^https?:\/\//, "").replace(/\/v1\/?$/, "");
+      if (written.agentModelUrl) {
+        console.log(dim(`      chat   ${written.agentModel || "(default)"}  ${dim(`@ ${host}`)}`));
+      }
+      if (written.agentCodingModelName) {
+        console.log(
+          dim(`      code   ${written.agentCodingModelName}  @ ${host}`) +
+          dim("  — change it later with `/model`")
+        );
+      }
+      if (written.ragEmbedModel) {
+        const eh = String(written.ragEmbedUrl).replace(/^https?:\/\//, "").replace(/\/v1\/?$/, "");
+        console.log(dim(`      RAG    ${written.ragEmbedModel}  @ ${eh}`));
+      }
+      console.log(
+        dim("\n      No API key needed. `/model` switches the code model") +
+        dim(chosenModels ? " (and re-runs this setup)." : " (Kimi K3 is listed).")
+      );
+    }
+    state = recordStep(state, "models", "done");
+    await saveState(state);
+  } catch (e) {
+    // NOT fatal: everything else works, and the model can be set from the terminal. But say so
+    // clearly, because the symptom otherwise is the terminal refusing to start.
+    console.log("\n  " + yellow("⚠ could not seed the model settings: ") + e.message);
+    console.log(dim("  The terminal may say no agent model is configured. Set one with `/model`,"));
+    console.log(dim("  or run `gu doctor` to set up a local one.\n"));
+    state = recordStep(state, "models", "failed", { reason: e.message });
+    await saveState(state);
+  }
+
+  console.log(
+    "\n  " + cyan(bold("Local mode is set up.")) +
+    dim("\n  Everything — conversations, token counts, workspaces — stays in MongoDB on this") +
+    dim("\n  machine. The API restarts with `gu-cli api start`; its log is") +
+    dim(`\n  ${API_LOG_FILE}\n`)
+  );
+  return { complete: true, stoppedAt: null };
+}