@tiens.nguyen/gu-cli 1.0.686

package/README.md

@@ -0,0 +1,52 @@
+# @tiens.nguyen/gu-cli
+Run:
+  GONEXT_API_BASE=... GONEXT_WORKER_KEY=... npx -y --package @tiens.nguyen/gu-cli gu-cli
+
+## Agent chat mode
+
+Select **Agent** (instead of Chat) under the composer in the web app. Your
+free-form prompt is handed to a [smolagents](https://github.com/huggingface/smolagents)
+agent running on your local MLX/Ollama model. The agent can call tools (v1:
+`http_request`) and streams its thinking steps + final answer directly into the
+chat thread.
+
+Requires smolagents in the worker's Python environment:
+
+```sh
+pip install smolagents certifi
+```
+
+- `certifi` supplies a trusted CA bundle so the agent's `http_request` tool can
+  verify HTTPS certificates on macOS (where Python's default bundle may be
+  missing). The worker falls back to the system bundle if certifi is absent.
+- Agent mode is blocked for cloud models (the API returns 400). Select a local
+  MLX or Ollama model first.
+- Tool steps appear in the collapsible reasoning (`<think>`) area; the final
+  answer is the message body — no new UI needed.
+
+The agent script is `gonext_agent_chat.py` (reads `{messages, agentBaseURL,
+agentApiKey, agentModelId, tools, maxSteps}` on stdin; emits NDJSON
+`{"type":"step"/"final","text":"..."}` lines on stdout).
+
+## API Check / HTTP probe (Tools & Agents modes)
+
+The worker can run Postman-style HTTP probes queued from the web app
+("Tools" = `tool_only`, "Agents" = `agentic`). The worker always performs the
+actual HTTP request itself (Node `fetch`, so TLS works), measures the
+status/latency/headers/body, and classifies it (2xx/3xx/4xx/5xx/timeout/
+network_error).
+
+- **Tools (`tool_only`)** — no extra setup. The selected local model writes a
+  one-line health summary of the measured result.
+- **Agents (`agentic`)** — a smolagents agent (running on the selected local
+  model) produces the summary. Requires `pip install smolagents`.
+
+  The agent talks to your local MLX OpenAI-compatible server (no cloud calls).
+  The agent only summarizes; the worker's measurement stays the source of truth,
+  so if smolagents or the model is unavailable the probe still returns the
+  measured result with a note.
+
+### Env vars
+
+  GONEXT_PROBE_PYTHON   Python executable for smolagents scripts
+                        (default: GONEXT_MLX_LM_PYTHON or python3)

package/agent-model-command.mjs

@@ -0,0 +1,259 @@
+/**
+ * `/agent-model` — choosing the model that TALKS, from what the Ollama box actually has (#169).
+ *
+ * TERMINAL-ONLY BY NECESSITY, NOT BY PREFERENCE. On a Client Expert machine there is no Firebase
+ * and no web app pointed at the local API, so `PATCH /api/settings` — the route the web app uses
+ * for this — cannot be reached at all. The terminal is the only interface that exists, which is
+ * why the worker-key route had to learn to write agentModelName and why this command exists. The
+ * value lands in the MongoDB on the user's own disk; nothing leaves the machine.
+ *
+ * WHY THIS LIST IS LIVE AND /embed-model's IS HARDCODED. The two look symmetrical and are not.
+ * A chat model is interchangeable: pick a different one and the next answer is different, and
+ * that is the whole effect. An embedder decides the shape of every vector already on disk, so its
+ * list is two known-good options (see embed-model-command.mjs). Here, anything pulled onto the
+ * box should be selectable without waiting for a release — so the list is GET /api/tags, live.
+ *
+ * Which means it can fail, and failing well is most of the code below: a picker that renders
+ * empty reads as "there are no models", which is never what a network error means.
+ */
+
+import { modelRetired, ensureV1Root } from "./coding-provider-setup.mjs";
+
+
+/**
+ * Where to ask. Derived from the configured agent URL rather than hardcoded, so a machine
+ * pointed at its own Ollama lists its own models — for Client Expert this resolves to exactly
+ * the ollama1 box it was seeded with.
+ *
+ * `/v1` is stripped because that is the OpenAI-compatible face of Ollama; /api/tags lives on the
+ * native one, and the settings field may carry either.
+ */
+export function agentTagsUrl(settings) {
+  const raw = String(settings?.agentModelUrl ?? "").trim();
+  if (!raw) return "";
+  const root = raw.replace(/\/+$/, "").replace(/\/v1$/i, "");
+  return `${root}/api/tags`;
+}
+
+/** What is set right now. agentModelName is the field the API reads when a direct URL is set. */
+export function currentAgentModel(settings) {
+  return String(settings?.agentModelName ?? settings?.agentModel ?? "").trim();
+}
+
+/**
+ * An embedder in the chat list is a trap worth labelling.
+ *
+ * /api/tags returns everything pulled onto the box, embedding models included — and nomic-embed-
+ * text sitting between two chat models looks like a choice. Picking it does not fail at the
+ * point of choice: it fails as an agent that answers with garbage. We do not HIDE them (a model
+ * the user pulled and cannot find is its own bug report), we sink them and say what they are.
+ */
+export function isLikelyEmbedder(entry) {
+  const family = String(entry?.family ?? "").toLowerCase();
+  const name = String(entry?.model ?? "").toLowerCase();
+  return family === "bert" || family === "nomic-bert" || /embed/.test(name);
+}
+
+/**
+ * Parse GET /api/tags into rows we can show.
+ *
+ * Tolerant on purpose: a proxy that returns HTML, an empty body, a shape from a future Ollama —
+ * all of them mean "no list", which the caller renders as a failure rather than as an empty box.
+ */
+export function parseOllamaTags(json) {
+  const rows = Array.isArray(json?.models) ? json.models : [];
+  const out = [];
+  for (const m of rows) {
+    const model = String(m?.model ?? m?.name ?? "").trim();
+    if (!model) continue;
+    out.push({
+      model,
+      sizeBytes: Number(m?.size) || 0,
+      family: String(m?.details?.family ?? "").trim(),
+      params: String(m?.details?.parameter_size ?? "").trim(),
+    });
+  }
+  // Chat models first, then embedders, alphabetical within each — a stable order, so the same
+  // box always presents the same list and muscle memory keeps working.
+  return out.sort((a, b) => {
+    const ea = isLikelyEmbedder(a) ? 1 : 0;
+    const eb = isLikelyEmbedder(b) ? 1 : 0;
+    return ea !== eb ? ea - eb : a.model.localeCompare(b.model);
+  });
+}
+
+/**
+ * The picker's rows, with the current model marked (requirement 6).
+ *
+ * A configured model the box does not list still gets a row. It may have been deleted there, or
+ * the list may be from a different host — either way, dropping it would silently misreport what
+ * this machine is set to, and re-picking would look like a no-op when it is a change.
+ */
+export function agentModelRows(models, current) {
+  const cur = String(current ?? "").trim();
+  const rows = (models ?? []).map((m) => ({
+    ...m,
+    current: m.model === cur,
+    embedder: isLikelyEmbedder(m),
+  }));
+  if (cur && !rows.some((r) => r.current)) {
+    rows.unshift({
+      model: cur,
+      sizeBytes: 0,
+      family: "",
+      params: "",
+      current: true,
+      embedder: false,
+      missing: true,
+    });
+  }
+  return rows;
+}
+
+/**
+ * WHAT TO SAY WHEN THE LIST CANNOT BE FETCHED (requirement 3).
+ *
+ * The failure mode this prevents is an empty picker, which reads as "no models exist" — a much
+ * more alarming and completely different claim than "I could not reach the box". The current
+ * model is always named, because that is the one fact still true when the network is not.
+ */
+export function describeTagsFailure({ url, current, error, proxied = false } = {}) {
+  const lines = [
+    `couldn't fetch the model list from ${url || "(no agent model URL configured)"}`,
+  ];
+  if (error) lines.push(`  ${error}`);
+  lines.push(
+    current
+      ? `still using ${current} — unchanged.`
+      : "no agent model is set on this machine, and the list is unavailable."
+  );
+  if (!proxied) {
+    // Task #160: ollama1 is one of the three allowlisted model origins. On a restricted network
+    // the direct route is exactly what fails, and the proxy is the thing that fixes it.
+    lines.push("if this machine needs a proxy to reach it, set one with /proxy.");
+  }
+  return lines;
+}
+
+/** Human size for the picker — a 40GB model on a small box is worth seeing before choosing. */
+export function formatSize(bytes) {
+  const n = Number(bytes) || 0;
+  if (n <= 0) return "";
+  const gb = n / 1e9;
+  return gb >= 1 ? `${gb.toFixed(1)}GB` : `${Math.round(n / 1e6)}MB`;
+}
+
+/**
+ * WHAT KIND OF THING IS THIS MODEL ID, if it is not a chat model?
+ *
+ * Returns a short phrase to LABEL it with, or "" when it looks like something you can talk to.
+ * Deliberately pattern-based on the id: /v1/models reports an id, an object type, a creation
+ * date and an owner, and nothing that says "this one generates images". The vendor's own naming
+ * is the only signal there is, and it is a reliable one for exactly the families that matter.
+ *
+ * ERRING TOWARDS "" IS THE SAFE DIRECTION. An unrecognised id stays unlabelled and sorts with the
+ * chat models, which is right: a new chat model must not be buried on the day it ships, and the
+ * cost of a wrong guess in the other direction is a model that answers badly — visible in one
+ * turn — rather than a model the user cannot find at all.
+ */
+export function nonChatKind(id) {
+  const s = String(id ?? "").toLowerCase();
+  if (!s) return "";
+  if (/embed/.test(s)) return "an embedding model";
+  if (/whisper|tts|audio|speech|transcribe|realtime/.test(s)) return "an audio/speech model";
+  if (/moderation/.test(s)) return "a moderation model";
+  if (/dall-e|^image|-image|imagen|stable-diffusion|sora|video/.test(s)) return "an image/video model";
+  if (/rerank/.test(s)) return "a reranking model";
+  return "";
+}
+
+/**
+ * The agent picker's rows, read from an OpenAI-compatible /v1/models body (task #225 phase 3).
+ *
+ * SHOW EVERYTHING, SINK AND LABEL. The user chose this explicitly, and it is deliberately the
+ * OPPOSITE of what the coding picker does — the same person asked that one to filter hard, and
+ * chose "show everything the provider lists" here. It also matches the rule this file already
+ * applied to embedders in an Ollama list: "We do not HIDE them … we sink them and say what they
+ * are." A model the user can see and was warned about beats one that silently is not there.
+ *
+ * THREE BANDS, in the order of how much you should hesitate:
+ *   0  chat models — unlabelled, alphabetical
+ *   1  live but not for chatting — labelled with what they are
+ *   2  the provider says SHUT DOWN — labelled, and last, because this is the only category that
+ *      cannot work at all rather than merely working badly
+ *
+ * The row shape matches parseOllamaTags so agentModelRows renders both without a special case;
+ * `sizeBytes` is 0 because a hosted provider does not report one and inventing a number would be
+ * worse than showing none.
+ */
+export function agentModelsFromProvider(body, now = Date.now()) {
+  const rows = Array.isArray(body?.data) ? body.data : Array.isArray(body) ? body : null;
+  if (!rows) return [];
+  const out = [];
+  const seen = new Set();
+  for (const r of rows) {
+    const id = typeof r === "string" ? r.trim() : typeof r?.id === "string" ? r.id.trim() : "";
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    // The RETIREMENT rule is shared with the coding flow rather than re-decided here: what
+    // counts as "shut down" must not mean two different things in two pickers.
+    const dead = modelRetired(r, now);
+    const kind = dead ? "" : nonChatKind(id);
+    out.push({
+      model: id,
+      sizeBytes: 0,
+      family: "",
+      params: "",
+      note: dead ? "the provider says this model is shut down" : kind,
+      band: dead ? 2 : kind ? 1 : 0,
+    });
+  }
+  // Stable: band, then alphabetical. The same body always renders the same list, so a position
+  // learned once stays learned.
+  return out.sort((a, b) => (a.band !== b.band ? a.band - b.band : a.model.localeCompare(b.model)));
+}
+
+/**
+ * WHERE DO WE ASK FOR THE AGENT'S MODEL LIST, AND IN WHAT DIALECT? (task #225 phase 3)
+ *
+ * The picker has only ever spoken Ollama — agentTagsUrl builds `${root}/api/tags` and the reply
+ * goes to parseOllamaTags. A hosted provider answers GET /v1/models instead, with a different
+ * body. This is the one decision that tells the two apart, kept pure so both branches can be
+ * tested without a network.
+ *
+ * DECIDED BY THE PROVIDER ROW, not by sniffing the URL. The account already says what each
+ * endpoint IS — the user chose "ollama" or "openai" when they added it — and that stored answer
+ * beats any guess from a hostname. It is also the same rule the API uses to resolve the agent's
+ * key (app.ts), so the list and the credential cannot disagree about which provider is in play.
+ *
+ * NO MATCHING ROW → OLLAMA, which is exactly today's behaviour and therefore safe for every
+ * existing install: they all have a local agent URL and no row for it.
+ *
+ * Returns { url, dialect: "ollama" | "openai", row } — row is the matched provider or null.
+ */
+export function agentListSource(settings) {
+  const direct = String(settings?.agentModelUrl ?? "").trim();
+  if (!direct) return { url: "", dialect: "ollama", row: null };
+  const rows = Array.isArray(settings?.agentCodingBackends) ? settings.agentCodingBackends : [];
+  // Case-folded for the same reason app.ts folds it: normalising does not lower-case the host,
+  // so a URL typed in capitals connects fine and would otherwise fail to match its own row.
+  const want = ensureV1Root(direct).toLowerCase();
+  const row = rows.find(
+    (b) => b && ensureV1Root(String(b.url ?? "")).toLowerCase() === want
+  );
+  if (row && String(row.kind ?? "").trim() === "openai") {
+    // The row's url already ends at the /v1 root, so the models endpoint hangs directly off it.
+    return { url: `${ensureV1Root(String(row.url ?? ""))}/models`, dialect: "openai", row };
+  }
+  return { url: agentTagsUrl(settings), dialect: "ollama", row: row ?? null };
+}
+
+/**
+ * Read a model list in whichever dialect agentListSource named.
+ *
+ * One entry point so the caller does not branch twice — once to choose the URL and again to
+ * choose the parser — which is how the two get out of step.
+ */
+export function agentModelsFromBody(dialect, body, now = Date.now()) {
+  return dialect === "openai" ? agentModelsFromProvider(body, now) : parseOllamaTags(body);
+}

package/agent-model-label.mjs

@@ -0,0 +1,159 @@
+/**
+ * What the banner should CALL the agent's chat model (#170).
+ *
+ * REPORTED: a Host-mode machine showed `model  default_model` — the same on a fresh setup as on
+ * an old one. The account was not missing the name; it was structurally unable to reach it:
+ *
+ *     agentModelUrl  = 'http://127.0.0.1:8090'      ← a direct URL is set
+ *     agentModelName = ''                            ← so THIS is the field that names the model
+ *     agentModel     = 'Qwen3-14B-4bit@@port:8080'   ← the name, in the branch nobody reads
+ *
+ * api/src/app.ts resolves `directAgentName || "default_model"` whenever a direct URL is set, and
+ * the legacy mlx-host key it would otherwise parse the name out of is only consulted when there
+ * is NO direct URL. Client Expert seeds agentModelName during setup, which is why its banner is
+ * right; Host mode never writes that field at all.
+ *
+ * WHY THIS IS A DISPLAY FIX AND NOT A SETTINGS FIX — the important part.
+ *
+ * The tempting repair is to have Host mode seed agentModelName the way Client Expert does. On an
+ * MLX host that BREAKS TURNS. mlx_lm/server.py maps exactly one name:
+ *
+ *     self._model_map["default_model"] = self.cli_args.model        # the ONLY mapping
+ *     model_path = self._model_map.get(model_path, model_path)      # anything else is a PATH
+ *
+ * so asking it for "Qwen3-14B-4bit" makes it treat that as a repo to load — evicting the model it
+ * has and attempting a download — until the agent's model-not-found retry falls back to the
+ * sentinel. Client Expert can seed a name because its backend is OLLAMA, where the name is what
+ * SELECTS the model from many on one port. MLX is the inverse: "default_model" is the correct
+ * thing to send, and only the wrong thing to show a person.
+ *
+ * So: the wire keeps the sentinel, and the human is told what is actually loaded. The authority
+ * for that is the process's own `--model` argument (see inspectModelServers — mlx_lm.server's
+ * /v1/models advertises the whole HF cache, not the loaded model, so it cannot be asked).
+ */
+
+import { modelDisplayName, parsePort } from "./model-doctor.mjs";
+
+/**
+ * Is this URL served by THIS process's machine — the only case where a local `ps` row is
+ * evidence about it?
+ *
+ * DELIBERATELY NOT model-doctor's isLocalModelUrl, which answers a different question: it counts
+ * LAN and tailnet addresses as local because it is deciding whether the doctor *could* start a
+ * server there. Here that would be a mislabel with a straight face — a client machine pointed at
+ * http://192.168.1.50:8090 would get whatever this laptop happens to be running. Loopback only.
+ */
+export function servesFromThisMachine(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;
+  return /^127(\.\d{1,3}){3}$/.test(host);
+}
+
+/**
+ * mlx_lm.server's "whatever I loaded" sentinel, and what the API returns when a direct agent URL
+ * is set with no name beside it. Not a model name, and must never be shown as one.
+ */
+export const LOADED_MODEL_SENTINEL = "default_model";
+
+/** Does this id name a model, or is it a stand-in for one? */
+export function namesAModel(id) {
+  const s = String(id ?? "").trim();
+  return s !== "" && s !== LOADED_MODEL_SENTINEL;
+}
+
+/**
+ * Decide what to call the agent's chat model.
+ *
+ * `servers` is discoverModelServers() output — [{ pid, port, kind, modelPath }] parsed from `ps`.
+ *
+ * Returns { name, known, reason }:
+ *   known:true   → `name` is a real model name, safe to print as one
+ *   known:false  → `reason` says why we cannot name it, so the caller can be honest rather than
+ *                  printing a sentinel: "settings" is never a reason (a named model is known),
+ *                  leaving "remote", "no-server" and "ambiguous".
+ */
+export function agentModelLabel({ configuredId = "", agentUrl = "", servers = [] } = {}) {
+  // A REAL name wins outright. This is the Ollama / Client Expert case, where the name is not
+  // decoration — it selects the model — and second-guessing it with a local process listing is
+  // how you end up labelling someone's remote model with whatever is running on their laptop.
+  if (namesAModel(configuredId)) {
+    return { name: String(configuredId).trim(), known: true, reason: "settings" };
+  }
+  // The sentinel means "ask the server". We can only do that for a server on THIS machine: a
+  // client machine points at another Mac, and a local `ps` row is then somebody else's process.
+  if (!servesFromThisMachine(agentUrl)) {
+    return { name: "", known: false, reason: "remote" };
+  }
+  // NEVER the embedder. It is a model server on this machine with a perfectly good name, and
+  // grabbing it here would put "Qwen3-Embedding-8B-4bit-DWQ" in the chat-model row — a mistake
+  // that looks like data rather than a bug.
+  const chat = (Array.isArray(servers) ? servers : []).filter(
+    (s) => s?.kind === "mlx-lm" && String(s?.modelPath || "").trim()
+  );
+  if (chat.length === 0) return { name: "", known: false, reason: "no-server" };
+  const port = parsePort(agentUrl);
+  const onPort = port ? chat.filter((s) => s.port === port) : [];
+  // The port the agent will actually talk to is the only match that proves anything. Falling
+  // back to "the only mlx server running" is safe precisely because there is nothing to confuse
+  // it with; with several and none on the right port, we genuinely do not know which answers.
+  const pick = onPort[0] ?? (chat.length === 1 ? chat[0] : null);
+  if (!pick) return { name: "", known: false, reason: "ambiguous" };
+  const name = modelDisplayName(pick.modelPath);
+  return name
+    ? { name, known: true, reason: "running" }
+    : { name: "", known: false, reason: "no-server" };
+}
+
+/**
+ * WHAT is actually being served on a port, from `ps` — { name, path } or null.
+ *
+ * `doctor` used to report the chat model as "✓ chat model is up on port 8090", which answers
+ * "is something listening" and not "is it the right thing, from the right folder" — reported by
+ * a user who could not tell whether the server that was already up was even serving the model
+ * they meant. The RAG section had always named its model ("…for Qwen3-Embedding-8B-4bit-DWQ");
+ * the chat section named a port number.
+ */
+export function servedModelAt({ port, servers = [], kind = "mlx-lm" } = {}) {
+  const row = (Array.isArray(servers) ? servers : []).find(
+    (s) => s?.kind === kind && s?.port === port && String(s?.modelPath || "").trim()
+  );
+  if (!row) return null;
+  const name = modelDisplayName(row.modelPath);
+  return name ? { name, path: row.modelPath } : null;
+}
+
+/**
+ * Do these name the same model? Compares the LAST path segment, so a folder and a bare name
+ * agree ("/Users/j/mlx-models/Qwen3-14B-4bit" vs "Qwen3-14B-4bit"), and case-insensitively,
+ * because the account stores what a human typed.
+ *
+ * Used to warn when the server already running is not the model the account asks for — the
+ * mismatch doctor could not previously see, because it never looked at what was loaded.
+ */
+export function sameModelName(a, b) {
+  const norm = (x) => modelDisplayName(String(x ?? "").trim()).toLowerCase();
+  const na = norm(a);
+  return na !== "" && na === norm(b);
+}
+
+/** Plain-text fallback for each reason we cannot name the model. Never a sentinel. */
+export const UNKNOWN_MODEL_TEXT = Object.freeze({
+  remote: "(named by the remote server)",
+  "no-server": "(no model server running)",
+  ambiguous: "(the loaded model)",
+});
+
+/** The banner's text for a label, with no colour applied — `dim` is the caller's business. */
+export function agentModelText(label) {
+  if (label?.known) return label.name;
+  return UNKNOWN_MODEL_TEXT[label?.reason] ?? UNKNOWN_MODEL_TEXT.ambiguous;
+}

package/clear-state.mjs

@@ -0,0 +1,149 @@
+/**
+ * `gu clear` — put this machine back to how it was before gu ran.
+ *
+ * Written for testing the first-run flow, which is otherwise a one-shot: once ~/.gonext/
+ * worker.env exists the machine is paired, the mode question stops being asked, and Client
+ * Expert refuses outright — so there is no way to see the beginning again short of deleting
+ * files by hand and guessing which ones.
+ *
+ * IT ASKS FIRST, ALWAYS, and lists exactly what it will remove with sizes. Some of this is
+ * genuinely valuable — conversation history, RAG indexes that took minutes of GPU time, the
+ * backups the agent's own edits can be reverted from — and a reset command that quietly ate
+ * them would be the last thing anyone trusted with `--yes`.
+ */
+import { readdir, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const GONEXT_DIR = join(homedir(), ".gonext");
+
+/**
+ * What lives in ~/.gonext, and whether a reset should remove it.
+ *
+ * Grouped by what LOSING it costs, because that is the only thing that helps someone decide.
+ * Anything not listed is left alone: a reset that deletes files it does not recognise is not
+ * a reset, it is an accident waiting for the next release to add a directory.
+ */
+export const STATE_ITEMS = [
+  // --- identity and setup: the whole point of the command -----------------------------
+  { path: "worker.env", group: "identity",
+    what: "the account link (worker key + API base)", cost: "you sign in again" },
+  { path: "client-expert.json", group: "identity",
+    what: "Local-mode setup progress and the chosen mode", cost: "setup starts over" },
+  { path: "instance", group: "identity",
+    what: "this machine's id", cost: "it gets a new one" },
+  { path: "prefs.json", group: "identity", what: "CLI preferences", cost: "defaults return" },
+  { path: "wizard-state.json", group: "identity",
+    what: "installer progress", cost: "the wizard starts over" },
+
+  // --- work you may actually want -----------------------------------------------------
+  { path: "sessions", group: "work",
+    what: "per-folder conversation history and choices", cost: "every folder forgets its chat" },
+  { path: "workspaces.json", group: "work",
+    what: "registered workspaces", cost: "folders must be re-registered" },
+  { path: "active-workspace.json", group: "work", what: "the active folder", cost: "-" },
+  { path: "servers.json", group: "work", what: "deploy targets", cost: "re-enter host/user" },
+  { path: "workspace-backups", group: "work",
+    what: "backups of files the agent edited", cost: "past edits can no longer be reverted" },
+
+  // --- expensive to rebuild -----------------------------------------------------------
+  { path: "rag", group: "expensive",
+    what: "local RAG indexes", cost: "re-embedding costs real GPU minutes" },
+  { path: "api", group: "expensive",
+    what: "downloaded API packages", cost: "re-downloaded on next setup" },
+
+  // --- scratch: nobody will miss these ------------------------------------------------
+  { path: "worker.log", group: "scratch", what: "worker log", cost: "-" },
+  { path: "model.log", group: "scratch", what: "model log", cost: "-" },
+  { path: "embed.log", group: "scratch", what: "embedder log", cost: "-" },
+  { path: "run-logs", group: "scratch", what: "command output logs", cost: "-" },
+  { path: "agent-turns", group: "scratch", what: "turn checkpoints", cost: "-" },
+  { path: "rag-work", group: "scratch", what: "RAG scratch space", cost: "-" },
+  { path: "web-agent-work", group: "scratch", what: "web agent scratch space", cost: "-" },
+  { path: "local-api.log", group: "scratch", what: "local API log", cost: "-" },
+  { path: "local-api.pid", group: "scratch", what: "local API pidfile", cost: "-" },
+  { path: "worker.pid", group: "scratch", what: "worker pidfile", cost: "-" },
+  { path: "model.pid", group: "scratch", what: "model pidfile", cost: "-" },
+  { path: "embed.pid", group: "scratch", what: "embedder pidfile", cost: "-" },
+  { path: "logs", group: "scratch", what: "logs", cost: "-" },
+];
+
+/** Bytes on disk for a file or directory, or 0 when it does not exist. */
+export async function sizeOf(p) {
+  try {
+    const s = await stat(p);
+    if (!s.isDirectory()) return s.size;
+    let total = 0;
+    for (const entry of await readdir(p, { withFileTypes: true })) {
+      total += await sizeOf(join(p, entry.name));
+    }
+    return total;
+  } catch {
+    return 0;
+  }
+}
+
+export const human = (n) =>
+  n >= 1024 * 1024 ? `${(n / 1024 / 1024).toFixed(1)}M`
+    : n >= 1024 ? `${Math.round(n / 1024)}K`
+    : `${n}B`;
+
+/**
+ * What is actually present, with sizes — so the confirmation describes THIS machine rather
+ * than a generic list, and an empty group can be left out entirely.
+ */
+export async function surveyState({ groups } = {}) {
+  const wanted = groups ?? ["identity", "work", "expensive", "scratch"];
+  const found = [];
+  for (const item of STATE_ITEMS) {
+    if (!wanted.includes(item.group)) continue;
+    const full = join(GONEXT_DIR, item.path);
+    const bytes = await sizeOf(full);
+    try {
+      await stat(full);
+      found.push({ ...item, full, bytes });
+    } catch {
+      /* not on this machine — nothing to say about it */
+    }
+  }
+  return found;
+}
+
+/** Remove what the survey found. Returns the paths actually removed. */
+export async function clearState(items) {
+  const removed = [];
+  for (const item of items) {
+    try {
+      await rm(item.full, { recursive: true, force: true });
+      removed.push(item.path);
+    } catch {
+      /* a file we cannot remove is reported by its absence from this list */
+    }
+  }
+  return removed;
+}
+
+/* ------------------------------------------------ the local database ------------------- */
+
+/**
+ * On a Client Expert machine the database is state too — and `gu clear` did not touch it.
+ *
+ * The consequence is not obvious and bit a real machine: clear removes worker.env and the
+ * setup notes, so the next `gu` runs setup again — but seeding only fills what is MISSING,
+ * and the old settings row is still there. The machine silently inherits configuration from a
+ * previous version (an agent URL pointing at a local Ollama that was never installed, a coder
+ * nobody chose), while every file on disk says it is a fresh install.
+ *
+ * "Starts from the beginning" has to mean it, or it is worse than not offering the command.
+ */
+export function localDatabaseItem({ apiBase }) {
+  const local = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:|\/|$)/i.test(String(apiBase ?? ""));
+  if (!local) return null;
+  return {
+    group: "work",
+    what: "the local MongoDB database (conversations, settings, worker keys)",
+    // Named plainly: this is the one thing here that a person might genuinely want to keep,
+    // and it is not recoverable.
+    cost: "every conversation on this machine is deleted",
+  };
+}