@tiens.nguyen/gu-cli 1.0.686

package/client-expert-setup.mjs

@@ -0,0 +1,616 @@
+/**
+ * First-run setup for CLIENT EXPERT mode — the whole stack on the user's machine (task #154).
+ *
+ * WHAT THIS FILE IS. The ORDER of setup and the decision "what happens next", separated from
+ * the doing of it. Installing MongoDB, downloading a release and starting a server are all
+ * slow, destructive and impossible to unit-test; deciding which of them is next is neither.
+ * Everything here is pure: it takes what we RECORDED last time and what we can SEE right now,
+ * and returns the next step. The installer supplies the probes and performs the actions.
+ *
+ * THE RULE THAT SHAPES IT: a remembered "done" is never trusted on its own.
+ *
+ * Setup spans several runs of `gu` — the user quits, reboots, comes back tomorrow. Between
+ * those runs mongod gets stopped, a port gets taken, a folder gets deleted. A resume that
+ * believed its own notes would sail past a step whose result no longer exists and fail later,
+ * somewhere unrelated, with a message about something else. So each step carries a cheap
+ * VERIFICATION, and a step counts as done only when the note AND the world agree. That is why
+ * `planSetup` takes both `recorded` and `probe`, and why the two are never merged.
+ */
+
+/**
+ * In order. Each step depends on every step before it, which is what makes "the first one not
+ * satisfied" the right answer rather than "the first one not recorded".
+ */
+export const CLIENT_EXPERT_STEPS = [
+  {
+    id: "mode",
+    title: "Choose how this machine runs",
+    // The one question that cannot be probed — it is a decision, not a state.
+    satisfied: (p) => p.mode === "client-expert",
+  },
+  {
+    id: "mongo",
+    title: "MongoDB installed and running",
+    satisfied: (p) => p.mongoRunning === true,
+  },
+  {
+    id: "database",
+    title: "Database, collections, indexes and worker key created",
+    satisfied: (p) => p.dbReady === true,
+  },
+  {
+    id: "api-files",
+    title: "Local API downloaded",
+    satisfied: (p) => p.apiInstalled === true,
+  },
+  {
+    id: "api-running",
+    title: "Local API answering on its port",
+    // Healthy is not enough: an API too old for this terminal is a silent-failure machine
+    // (fields it does not store simply come back missing), so the contract is part of "up".
+    satisfied: (p) => p.apiHealthy === true && p.contractOk === true,
+  },
+  {
+    id: "worker-env",
+    title: "Terminal pointed at the local API",
+    satisfied: (p) => p.workerEnvPointsLocal === true,
+  },
+  {
+    id: "models",
+    title: "Coding model and RAG settings",
+    // From here Client Expert is exactly Client mode — same questions, same answers, only the
+    // API and database happen to be local. Nothing below this line should be mode-aware.
+    satisfied: (p) => p.modelsConfigured === true,
+  },
+];
+
+export const STEP_IDS = CLIENT_EXPERT_STEPS.map((s) => s.id);
+
+/** Platforms the walkthrough can actually install MongoDB on (task #154 scope). */
+export const SUPPORTED_PLATFORMS = ["darwin", "linux", "win32"];
+
+/**
+ * May this machine enter Client Expert at all?
+ *
+ * Only a machine that has never been paired. `worker.env` holds the hosted API base and the
+ * worker key, so its presence means conversations, token history and workspaces already exist
+ * on the hosted side under an identity that does not exist locally. Switching such a machine
+ * would strand that data or demand a migration, and a half-migrated user cannot tell which
+ * store an answer came from. A PARTIAL file counts as existing — that is a paired machine in
+ * a bad state, not a fresh one, and overwriting it would destroy the link it still has.
+ */
+/**
+ * Can MongoDB actually run on this hardware? (Found when the first Pi test was attempted.)
+ *
+ * "linux" is not specific enough, and both ways it fails do so AFTER the user has committed:
+ *   · MongoDB ships NO 32-bit ARM packages — on armv7l `apt install mongodb-org` finds nothing;
+ *   · MongoDB 5.0+ needs ARMv8.2-A with LSE atomics. A Raspberry Pi 4 is ARMv8.0, so mongod
+ *     installs happily and then dies with "Illegal instruction". 4.4 was the last that ran on
+ *     it; a Pi 5 (ARMv8.2) is fine.
+ * Refusing up front with the reason beats walking someone through an install that cannot work.
+ */
+export function mongoSupported({ platform, arch, cpuModel = "" }) {
+  if (platform === "darwin") return { supported: true, reason: null, message: "" };
+  // MongoDB ships a native Windows server; there is no ARM story to worry about because the
+  // Windows build is x64 only, and an ARM Windows box runs it under emulation.
+  if (platform === "win32") return { supported: true, reason: null, message: "" };
+  if (platform !== "linux") {
+    return { supported: false, reason: "platform", message: `MongoDB setup is not scripted for ${platform}.` };
+  }
+  if (arch === "arm" || /armv[67]l?/i.test(String(arch))) {
+    return {
+      supported: false,
+      reason: "arch32",
+      message:
+        "This is a 32-bit ARM system, and MongoDB publishes no 32-bit ARM packages — there is " +
+        "nothing to install. A 64-bit OS (aarch64) is required.",
+    };
+  }
+  // Pi 4 and earlier are ARMv8.0; MongoDB 5.0+ needs 8.2's LSE atomics and dies on them.
+  if (arch === "arm64" || arch === "aarch64") {
+    if (/raspberry pi [1-4]\b/i.test(cpuModel)) {
+      return {
+        supported: false,
+        reason: "armv8.0",
+        message:
+          `${cpuModel.trim() || "This Pi"} is ARMv8.0, and MongoDB 5.0+ requires ARMv8.2 — ` +
+          "mongod would install and then exit with 'Illegal instruction'. MongoDB 4.4 was the " +
+          "last release that ran on it; a Pi 5 or an x86_64 machine works.",
+      };
+    }
+  }
+  return { supported: true, reason: null, message: "" };
+}
+
+/**
+ * Is there a Client Expert setup this machine started and has not finished?
+ *
+ * The whole point is to tell "this user is signed in to the hosted API" apart from "this user
+ * chose Client Expert, is partway through, and gu signed them in meanwhile so the machine
+ * would be usable". Those produce an identical worker.env, so the plan on disk is the ONLY
+ * thing that distinguishes them.
+ *
+ * Reversible by design: answering the mode question with anything else overwrites chosenMode,
+ * so a user who gives up lands in an ordinary paired state instead of being asked forever.
+ */
+export function expertPlanPending(state) {
+  if (!state || typeof state !== "object") return false;
+  if (state.chosenMode !== "client-expert") return false;
+  // Finished plans are not pending — a completed machine IS Client Expert, not mid-setup.
+  return !STEP_IDS.every((id) => state[id] === "done");
+}
+
+export function clientExpertAvailable({
+  workerEnvExists,
+  expertPending = false,
+  platform,
+  arch,
+  cpuModel,
+}) {
+  // A pairing gu performed ITSELF, as the stopgap the walkthrough promised, must not be
+  // read as "the user already chose the hosted API". Client Expert stops at MongoDB and says
+  // "until then this machine works in CLIENT mode" — which means signing in, which writes
+  // worker.env. Without this clause the very next question told the user Client Expert was
+  // unavailable because the machine was paired, seconds after they picked it and while their
+  // half-finished plan sat on disk. Reported live on Windows 11.
+  if (workerEnvExists && !expertPending) {
+    return {
+      available: false,
+      reason: "paired",
+      message:
+        "This machine is already signed in to the hosted API (~/.gonext/worker.env). " +
+        "Local mode sets up its own database and identity, so it only runs on a machine " +
+        "that has never been paired. To switch, remove ~/.gonext/worker.env first — you will " +
+        "lose the link to your hosted history.",
+    };
+  }
+  if (!SUPPORTED_PLATFORMS.includes(platform)) {
+    return {
+      available: false,
+      reason: "platform",
+      message:
+        `Local mode supports macOS, Ubuntu and Windows for now; this is ${platform}. ` +
+        "Cloud mode works here and keeps the API and database hosted.",
+    };
+  }
+  // The OS is not the whole question — the CPU has to be able to run the database.
+  if (arch !== undefined) {
+    const mongo = mongoSupported({ platform, arch, cpuModel });
+    if (!mongo.supported) {
+      return {
+        available: false,
+        reason: mongo.reason,
+        message: `${mongo.message} Cloud mode works here and keeps the database hosted.`,
+      };
+    }
+  }
+  return { available: true, reason: null, message: "" };
+}
+
+/**
+ * The next thing to do, and why.
+ *
+ * `recorded` — what a previous run wrote down (the notes).
+ * `probe`    — what is true right now (the world).
+ *
+ * A step is complete only when BOTH agree. When they disagree the step reopens, and the plan
+ * says so: "recorded, but no longer true" is a different situation from "never done", and a
+ * user who is told which one it is can act on it.
+ */
+export function planSetup({ recorded = {}, probe = {} } = {}) {
+  const steps = CLIENT_EXPERT_STEPS.map((step) => {
+    const noted = recorded[step.id] === "done";
+    const real = step.satisfied(probe) === true;
+    return {
+      id: step.id,
+      title: step.title,
+      state: real ? "done" : noted ? "reopened" : "pending",
+    };
+  });
+  const next = steps.find((s) => s.state !== "done") ?? null;
+  // "You stopped during this" reads very differently from "this failed" or "this is new", and
+  // a resume that cannot tell them apart greets everyone with the same blank prompt.
+  const nextWas = next ? recorded[next.id] ?? null : null;
+  return {
+    steps,
+    next: next ? next.id : null,
+    nextWas,
+    resuming: nextWas === "interrupted",
+    complete: next === null,
+    // Surfaced so the caller can say "MongoDB was set up before but is not running now" rather
+    // than starting the install walkthrough again from scratch, which reads as no progress.
+    regressed: steps.filter((s) => s.state === "reopened").map((s) => s.id),
+    done: steps.filter((s) => s.state === "done").map((s) => s.id),
+  };
+}
+
+/**
+ * Record a step's outcome. Kept tiny and separate from the file it lives in, so the shape of
+ * the notes is one thing and their storage another.
+ *
+ * A FAILURE CARRIES ITS REASON AND ITS COUNT. "failed" alone sends the user round the same
+ * loop with the same result and no idea why; setup that cannot say "this failed three times,
+ * because the port is in use" is setup that traps people.
+ */
+export function recordStep(recorded, id, outcome, detail = {}) {
+  if (!STEP_IDS.includes(id)) throw new Error(`unknown setup step: ${id}`);
+  const prior = recorded[`${id}:attempts`] ?? 0;
+  const next = {
+    ...recorded,
+    [id]: outcome,
+    updatedAt: new Date().toISOString(),
+  };
+  if (outcome === "failed") {
+    next[`${id}:attempts`] = prior + 1;
+    if (detail.reason) next[`${id}:reason`] = detail.reason;
+  } else if (outcome === "done") {
+    // ONLY success clears the history — otherwise a step that failed twice and then worked
+    // would keep offering to give up.
+    delete next[`${id}:attempts`];
+    delete next[`${id}:reason`];
+  } else {
+    // Everything else — "interrupted" (Ctrl+C), "declined" (the user said no) — keeps its
+    // reason and does NOT count as an attempt. Neither is evidence that the step cannot work:
+    // one means they went to lunch, the other that they chose not to. Counting either would
+    // offer to abandon Client Expert to someone who simply answered a question.
+    //
+    // This branch used to test for "interrupted" specifically, so "declined" fell into the
+    // success path and silently dropped the reason — the next run could not say why it had
+    // stopped, which is the one thing that makes a resume feel like a continuation.
+    if (detail.reason) next[`${id}:reason`] = detail.reason;
+  }
+  return next;
+}
+
+/** How many times this step has failed since it last succeeded. */
+export function stepAttempts(recorded, id) {
+  return recorded?.[`${id}:attempts`] ?? 0;
+}
+
+/** Why it failed last time, for showing above the retry. */
+export function stepReason(recorded, id) {
+  return recorded?.[`${id}:reason`] ?? null;
+}
+
+/**
+ * After a few identical failures, stop pretending the next attempt is different.
+ *
+ * The alternative — retry forever — is how a user ends up running the same brew command five
+ * times. Offering the way out is not giving up on them; it is admitting that something here
+ * needs a human, and that they should not be stuck in Client Expert to find out.
+ */
+export function shouldOfferGiveUp(recorded, id, max = 3) {
+  return stepAttempts(recorded, id) >= max;
+}
+
+/**
+ * Is the local API's wire contract compatible, and if not, WHICH SIDE is behind?
+ *
+ * The two skews need opposite advice, and telling someone to update the wrong one wastes an
+ * afternoon. In this mode the user owns both, so we cannot fix either for them — only say
+ * plainly which one to move.
+ */
+export function describeContract({ apiContract, terminalNeeds }) {
+  if (!Number.isFinite(apiContract)) {
+    return {
+      ok: false,
+      skew: "unknown",
+      message:
+        "The local API did not report a contract version. It is probably older than this " +
+        "feature — update it with `gu client-expert update`.",
+    };
+  }
+  if (apiContract === terminalNeeds) return { ok: true, skew: null, message: "" };
+  if (apiContract < terminalNeeds) {
+    return {
+      ok: false,
+      skew: "api-old",
+      message:
+        `Your local API speaks contract ${apiContract}; this terminal needs ${terminalNeeds}. ` +
+        "Run `gu client-expert update` to download the matching API.",
+    };
+  }
+  return {
+    ok: false,
+    skew: "terminal-old",
+    message:
+      `Your local API speaks contract ${apiContract}; this terminal only understands ` +
+      `${terminalNeeds}. Update the terminal: \`npm i -g @tiens.nguyen/gu-cli\`.`,
+  };
+}
+
+/**
+ * Steps that can leave a HALF-FINISHED artifact behind when interrupted, and what to clear.
+ *
+ * The danger of cancelling mid-step is not the lost work — it is the debris that LOOKS like
+ * finished work. A partial download is still a folder; a folder is what a naive "is it
+ * installed?" check sees. Anything listed here must be cleared before the retry, so the probe
+ * that follows is answering about a clean slate.
+ *
+ * Steps NOT listed are safely re-runnable as-is: `brew install` and `apt-get install` are
+ * idempotent, and creating collections/indexes that already exist is a no-op.
+ */
+const CLEANUP_ON_INTERRUPT = {
+  "api-files": [
+    "Delete the partially downloaded API folder (a partial download still looks like an install)",
+  ],
+  "api-running": [
+    "Stop any API process left holding the port (it will refuse the next start as 'port in use')",
+  ],
+};
+
+/**
+ * How to pick a step back up after it was interrupted.
+ *
+ * Returns the action AND whether anything must be swept first, so the caller never has to know
+ * which steps are dirty-on-interrupt.
+ */
+export function resumeAction(recorded = {}, id) {
+  if (!STEP_IDS.includes(id)) throw new Error(`unknown setup step: ${id}`);
+  const state = recorded[id];
+  const cleanup = state === "interrupted" ? CLEANUP_ON_INTERRUPT[id] ?? [] : [];
+  return {
+    action: cleanup.length ? "retry-after-cleanup" : "retry",
+    interrupted: state === "interrupted",
+    cleanup,
+  };
+}
+
+/**
+ * What leaving Client Expert has to undo, given how far setup got.
+ *
+ * A mode that cannot be exited is worse than one that is never entered, and the exit has to be
+ * derived from PROGRESS: telling someone to stop a MongoDB they never installed is noise, and
+ * failing to mention a worker.env we wrote leaves the terminal pointing at an API that is no
+ * longer running. Nothing here is destructive by itself — it is the list a human confirms.
+ */
+export function abandonPlan(recorded = {}) {
+  const done = (id) => recorded[id] === "done";
+  const actions = [];
+  if (done("worker-env")) {
+    actions.push({
+      id: "worker-env",
+      what: "Remove ~/.gonext/worker.env",
+      why: "it points this terminal at a local API that will no longer be running",
+    });
+  }
+  if (done("api-running")) {
+    actions.push({ id: "api-running", what: "Stop the local API", why: "it holds its port" });
+  }
+  if (done("api-files")) {
+    actions.push({
+      id: "api-files",
+      what: "Delete the downloaded API folder",
+      why: "nothing else uses it",
+    });
+  }
+  if (done("database")) {
+    actions.push({
+      id: "database",
+      what: "Drop the local database (OPTIONAL — this deletes your conversations)",
+      why: "it is the only copy; keep it if you may come back",
+      destructive: true,
+    });
+  }
+  if (done("mongo")) {
+    actions.push({
+      id: "mongo",
+      what: "Leave MongoDB installed (OPTIONAL to remove)",
+      why: "you may be using it for something else",
+    });
+  }
+  return actions;
+}
+
+/** The container this owns, and the volume its data lives in. */
+export const MONGO_DOCKER_NAME = "gu-mongo";
+export const MONGO_DOCKER_VOLUME = "gu-mongo-data";
+export const MONGO_DOCKER_IMAGE = "mongo:8";
+
+/**
+ * Run MongoDB in Docker instead of installing it. → { commands, summary }
+ *
+ * WHY THIS IS OFFERED FIRST WHERE DOCKER EXISTS. The alternative on macOS is
+ * `brew tap mongodb/brew` → `brew install mongodb-community` → `brew services start …`: three
+ * commands, a tap most people do not know they need, and a system-wide service. A user who
+ * skipped the tap got `No available formula with the name "mongodb-community"`, which is where
+ * this task started. One container is less to install, less to undo, and it is the same
+ * mongo:8 the project's own end-to-end tests already run against.
+ *
+ * TWO THINGS THAT ARE NOT OPTIONAL HERE:
+ *   · A NAMED VOLUME. This database holds the user's conversation history and token counts —
+ *     the whole point of Local mode. Without `-v`, `docker rm` throws it away, and a container
+ *     is exactly the thing people remove while tidying up.
+ *   · `--restart unless-stopped`, so it comes back after a reboot. A database that quietly
+ *     stops existing on Tuesday is worse than one that was never offered.
+ *
+ * `exists` distinguishes creating from starting: `docker run` on a name that is already taken
+ * fails with a conflict, and the useful action then is `docker start`.
+ */
+export function mongoDockerPlan({ exists = false, port = 27017 } = {}) {
+  if (exists) {
+    return {
+      commands: [`docker start ${MONGO_DOCKER_NAME}`],
+      summary: `start the existing ${MONGO_DOCKER_NAME} container`,
+    };
+  }
+  return {
+    commands: [
+      // One line, so a user who would rather run it themselves can copy it whole.
+      `docker run -d --name ${MONGO_DOCKER_NAME} --restart unless-stopped ` +
+        `-p ${port}:27017 -v ${MONGO_DOCKER_VOLUME}:/data/db ${MONGO_DOCKER_IMAGE}`,
+    ],
+    summary: `run ${MONGO_DOCKER_IMAGE} on port ${port}, data kept in the ` +
+      `${MONGO_DOCKER_VOLUME} volume`,
+  };
+}
+
+/** The install commands for a platform, or null when we do not support it. */
+export function mongoInstallPlan(platform) {
+  if (platform === "darwin") {
+    return {
+      platform,
+      commands: [
+        "brew tap mongodb/brew",
+        "brew install mongodb-community",
+        "brew services start mongodb-community",
+      ],
+      verify: "mongosh --eval 'db.runCommand({ ping: 1 })'",
+    };
+  }
+  if (platform === "win32") {
+    return {
+      platform,
+      commands: [
+        // winget ships with Windows 11. The installer registers a SERVICE named MongoDB and
+        // starts it, which is why the probe below looks for a service rather than a process.
+        "winget install --id MongoDB.Server --accept-package-agreements --accept-source-agreements",
+        "winget install --id MongoDB.Shell --accept-package-agreements --accept-source-agreements",
+      ],
+      verify: "mongosh --eval \"db.runCommand({ ping: 1 })\"",
+    };
+  }
+  if (platform === "linux") {
+    return {
+      platform,
+      commands: [
+        "sudo apt-get install -y gnupg curl",
+        "curl -fsSL https://pgp.mongodb.com/server-7.0.asc | sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg",
+        'echo "deb [signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list',
+        "sudo apt-get update && sudo apt-get install -y mongodb-org",
+        "sudo systemctl enable --now mongod",
+      ],
+      verify: "mongosh --eval 'db.runCommand({ ping: 1 })'",
+    };
+  }
+  return null;
+}
+
+
+/**
+ * How far `doctor` may go to fix each step on its own (task #154).
+ *
+ * The classification is about CONSEQUENCE, not difficulty. Starting a service we installed, on
+ * a port we chose, is reversible and boring — doing it silently saves the user a lookup.
+ * Installing system packages, downloading tens of megabytes, or creating an IDENTITY are not
+ * things a status command should decide to do.
+ */
+export const STEP_FIX = {
+  mode: { mode: "manual", action: null, why: "which mode this machine runs is the user's choice" },
+  mongo: {
+    mode: "auto",
+    action: "start MongoDB",
+    why: "starting a service that is already installed is reversible and expected",
+    // Only when it was installed before. A machine that never had MongoDB needs the
+    // walkthrough, sudo and a package manager — not a status command quietly installing it.
+    autoOnlyIfPreviouslyDone: true,
+  },
+  database: {
+    mode: "auto",
+    action: "recreate missing collections and indexes",
+    why: "creating what already exists is a no-op, so this is safe to repeat",
+    // THE TRAP. Re-seeding must ENSURE structure, never mint a new worker key: worker.env
+    // already holds one, and a fresh key would authenticate against nothing, leaving a
+    // terminal that fails every request with "Invalid worker API key" and no clue why.
+    neverRegenerateIdentity: true,
+  },
+  "api-files": {
+    mode: "confirm",
+    action: "re-download the API release",
+    why: "tens of megabytes over someone's network is not a side effect of `status`",
+  },
+  "api-running": {
+    mode: "auto",
+    action: "start the local API",
+    why: "it is our process, on the port we chose, and it holds no state",
+    autoOnlyIfPreviouslyDone: true,
+  },
+  "worker-env": {
+    mode: "confirm",
+    action: "rewrite ~/.gonext/worker.env to point at the local API",
+    why: "this file is how the terminal finds its API; rewriting it silently is how a machine ends up pointing somewhere the user did not choose",
+  },
+  models: { mode: "manual", action: null, why: "model choices are the user's" },
+};
+
+/**
+ * The API and database health lines for `status` / `doctor`.
+ *
+ * Built from the same plan the installer uses, deliberately: a second implementation of "is
+ * the API up?" would drift from the first, and then `status` would say healthy while setup
+ * said broken. One source, two renderings.
+ *
+ * Returns nothing to fix when this machine is not in Client Expert — a Client-mode user has no
+ * local API or database, and reporting them as "down" would be inventing a fault.
+ */
+export function healthReport({ recorded = {}, probe = {} } = {}) {
+  if (probe.mode !== "client-expert") {
+    return { applicable: false, ok: true, problems: [], summary: "hosted API and database" };
+  }
+  const plan = planSetup({ recorded, probe });
+  const problems = plan.steps
+    .filter((s) => s.state !== "done")
+    .map((s) => {
+      const fix = STEP_FIX[s.id] ?? { mode: "manual", action: null, why: "" };
+      const everWorked = recorded[s.id] === "done" || s.state === "reopened";
+      // "Auto" is conditional for anything whose first-time version is heavy: restarting a
+      // service is not the same act as installing one.
+      const canAuto =
+        fix.mode === "auto" && (!fix.autoOnlyIfPreviouslyDone || everWorked);
+      return {
+        id: s.id,
+        title: s.title,
+        state: s.state,
+        fixMode: canAuto ? "auto" : fix.mode === "auto" ? "manual" : fix.mode,
+        action: fix.action,
+        why: fix.why,
+      };
+    });
+  // ONLY THE FIRST PROBLEM MAY BE FIXED. Everything after it depends on it, so "fixing" a later
+  // one is meaningless work against a broken prerequisite — seeding collections into a MongoDB
+  // that is not running, or starting an API with no database to serve from. Caught by a test
+  // that expected an uninstalled MongoDB to leave nothing auto-fixable, and found `database`
+  // volunteering to run anyway. Fix the root, re-probe, and the next becomes eligible in turn —
+  // which is also exactly what a person would do.
+  const blocked = problems.length ? problems[0].id : null;
+  for (let i = 1; i < problems.length; i += 1) {
+    problems[i] = {
+      ...problems[i],
+      fixMode: "blocked",
+      why: `nothing to do until ${blocked} is fixed — this depends on it`,
+    };
+  }
+  return {
+    applicable: true,
+    ok: problems.length === 0,
+    problems,
+    // The FIRST problem is the one to act on: the rest are usually its consequences.
+    rootCause: problems.length ? problems[0].id : null,
+    summary: problems.length === 0
+      ? "local API and database healthy"
+      : `${problems.length} thing(s) need attention, starting with ${problems[0].id}`,
+  };
+}
+
+/** The problems `doctor` may fix without asking, in order. */
+export function autoFixable(report) {
+  return (report?.problems ?? []).filter((p) => p.fixMode === "auto");
+}
+
+/**
+ * Should gu ASK which mode this machine runs in?
+ *
+ * Only when the answer can change something. `chosenMode` is read by exactly one thing — is a
+ * Client Expert plan in progress — so on a machine that is already paired, where Client Expert
+ * is refused anyway, the question offers Client vs Host: a pair that changes NOTHING, because
+ * client mode is derived from settings by isClientMode(), not from this answer.
+ *
+ * Asking an established machine to re-pick its mode on the first run after an upgrade implies
+ * that choosing Host would do something. It would not. Reported live on a machine that had
+ * been working for months and was asked to choose again after an update.
+ */
+export function shouldAskMode({ chosenMode, isTty, expertAvailable }) {
+  if (chosenMode) return false; // already settled, however it was settled
+  if (!isTty) return false; // a pipe or CI has nobody to answer
+  return Boolean(expertAvailable);
+}

package/coding-choice-tags.mjs

@@ -0,0 +1,69 @@
+/**
+ * Which tag tells two entries in the /model picker apart (task #223).
+ *
+ * THE PROBLEM. A choice is a (backend, model) pair, and the picker has always tagged each row
+ * with its BACKEND KIND when more than one kind was in play:
+ *
+ *     qwen3:14b    · Ollama
+ *     kimi-k3      · OpenAI-compatible
+ *
+ * #223 lets the user add their own OpenAI-compatible provider beside the built-in Kimi K3 one.
+ * Both rows are kind "openai", so the kind prints THE SAME WORDS beside two different servers:
+ *
+ *     kimi-k3       · OpenAI-compatible
+ *     qwen3-coder   · OpenAI-compatible      ← a different company, a different key, a different bill
+ *
+ * THE RULE, in order:
+ *   1. Kinds all distinct → use the kind. "Ollama" and "local MLX" say more about what a row IS
+ *      than a hostname does, and this is the picker people already know.
+ *   2. Otherwise → use the PROVIDER tag the API derives from each URL ("moonshot",
+ *      "openrouter", "192.168.1.45:11434"), which is unique within a list by construction.
+ *   3. No label from the API → fall back to the kind. An older API sends no `label` field, and
+ *      a blank tag would be worse than the slightly-ambiguous one it replaced.
+ *
+ * WHY THE TAG IS NOT THE ID, and why this module only computes something to DRAW: the provider
+ * tag comes from the URL, so it changes the moment someone fixes a typo in their endpoint. The
+ * row id a folder stores is minted and opaque for exactly that reason. Nothing here is saved.
+ */
+
+/** How each backend kind is spelled for a human. "" is the legacy Auto marker. */
+export const KIND_LABEL = {
+  ollama: "Ollama",
+  openai: "OpenAI-compatible",
+  local: "local MLX",
+  "": "auto",
+};
+
+/** What a single choice's kind is called, with the raw kind as a last resort. */
+export function kindLabel(choice) {
+  const kind = choice?.kind ?? "";
+  return KIND_LABEL[kind] ?? kind ?? "";
+}
+
+/**
+ * The tag for each choice, and whether tags are worth showing at all.
+ *
+ * Returns { tags: string[], show: boolean } — `tags` parallel to `choices`, and `show` false
+ * when every row would carry the same tag, because a tag that is identical on every line is
+ * noise in a list whose job is to tell them apart.
+ */
+export function codingChoiceTags(choices) {
+  const list = Array.isArray(choices) ? choices : [];
+  const kinds = new Set(list.map((c) => c?.kind ?? ""));
+  // CAN THE KIND STILL SEPARATE THE BACKENDS? Counted against distinct BACKENDS, not distinct
+  // rows — one backend commonly offers several models, and counting rows would conclude "the
+  // kinds cannot separate these" for an Ollama box with two allowed models beside Kimi K3,
+  // changing a display that was never ambiguous. A backend is identified by its provider tag
+  // (unique per backend by construction), falling back to its URL for an API that sends none.
+  const backends = new Set(
+    list.map((c) => (typeof c?.label === "string" && c.label.trim()) || c?.url || c?.kind || "")
+  );
+  const kindsDiffer = kinds.size === backends.size;
+  const tags = list.map((c) => {
+    const byKind = kindLabel(c);
+    if (kindsDiffer) return byKind;
+    const label = typeof c?.label === "string" ? c.label.trim() : "";
+    return label || byKind;
+  });
+  return { tags, show: new Set(tags).size > 1 };
+}