@tiens.nguyen/gu-cli 1.0.771 → 1.0.772

package/cli-token.mjs

@@ -80,10 +80,10 @@ export function verifyCliToken(token, publicKeyB64) {
     !p || typeof p !== "object" ||
     p.v !== 1 ||
     typeof p.sub !== "string" || !p.sub ||
-    (p.plan !== "pro" && p.plan !== "free") ||
+    (p.plan !== "pro" && p.plan !== "free" && p.plan !== "trial") ||
     !(p.paidUntil === null || isIso(p.paidUntil)) ||
     !isIso(p.issuedAt) ||
-    (p.issuedBy !== "refresh" && p.issuedBy !== "account" && p.issuedBy !== "admin") ||
+    (p.issuedBy !== "refresh" && p.issuedBy !== "account" && p.issuedBy !== "admin" && p.issuedBy !== "trial") ||
     !(p.device === null || (typeof p.device === "string" && /^[0-9a-f]{64}$/.test(p.device))) ||
     !(p.activeDevices === null || (Number.isInteger(p.activeDevices) && p.activeDevices >= 0)) ||
     !(Number.isInteger(p.deviceLimit) && p.deviceLimit > 0) ||
@@ -132,6 +132,59 @@ export async function osMachineId({ platform = process.platform, read = (p) => r
   return "";
 }
 
+/**
+ * This computer for a FREE TRIAL (#305) — or null. Only the OS machine id counts here: the fallback
+ * thisDevice() uses when it is missing (~/.gonext/instance) changes with `gu clear`, which would make
+ * the trial once-per-install instead of once-per-computer. No stable id, no trial.
+ */
+export async function trialDevice(opts = {}) {
+  const raw = opts.machineId ?? (await osMachineId({ platform: opts.platform }));
+  if (!raw) return null;
+  return thisDevice({ ...opts, machineId: raw });
+}
+
+/**
+ * Ask the gu service for this computer's free trial (#305). → one of:
+ *   { ok: true, token, endsAt, created }   — a new trial, or the one this computer already has
+ *   { ok: false, why: "used", endedAt }    — this computer's trial has ended; never a second one
+ *   { ok: false, why: "no-device" | "unreachable" | "http-NNN" | "bad-response" }
+ * Never throws.
+ */
+export async function claimTrial({ hostedBase, device, fetchImpl = fetch, timeoutMs = 8000 }) {
+  if (!device) return { ok: false, why: "no-device" };
+  const base = String(hostedBase ?? "").replace(/\/+$/, "");
+  if (!base) return { ok: false, why: "unreachable" };
+  try {
+    const res = await fetchImpl(`${base}/api/billing/cli-token/trial`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ device }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const data = await res.json().catch(() => null);
+    if (res.status === 409) return { ok: false, why: "used", endedAt: data?.endedAt ?? null };
+    if (!res.ok) return { ok: false, why: `http-${res.status}` };
+    return typeof data?.token === "string"
+      ? { ok: true, token: data.token, endsAt: data.endsAt ?? null, created: data.created === true }
+      : { ok: false, why: "bad-response" };
+  } catch {
+    return { ok: false, why: "unreachable" };
+  }
+}
+
+/** Whole days left until an ISO date (rounded up; 0 when past). */
+export function daysLeft(iso, now = new Date()) {
+  const ms = Date.parse(iso ?? "") - now.getTime();
+  return Number.isFinite(ms) && ms > 0 ? Math.ceil(ms / 86_400_000) : 0;
+}
+
+/** The one line a first install sees instead of a token question (#305). */
+export function trialStartedLine(endsAt, site = DEFAULT_SITE) {
+  const accountUrl = `${String(site).replace(/^https?:\/\//, "")}/account`;
+  return `Free trial on this computer: 10 days, until ${shortDate(endsAt)}. ` +
+    `Then get a free token for 1 computer at ${accountUrl} — gu token <paste> links it.`;
+}
+
 /** What renewals send about this computer. The raw OS id never leaves the machine — only a salted hash. */
 export async function thisDevice({ platform = process.platform, hostName = osHostname(), machineId, instanceId } = {}) {
   const raw = machineId ?? (await osMachineId({ platform }));
@@ -289,6 +342,15 @@ export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempt
   if (check.ok) {
     const p = check.payload;
     const ended = p.paidUntil && Date.parse(p.paidUntil) <= now.getTime();
+    // THE FREE TRIAL (#305): its days, and the way on — a FREE account token covers one computer
+    // (the owner's wording: "go to <site> to get a free token for your 1 free machine"). Every start,
+    // quietly; urgent only once the trial has ended.
+    if (p.plan === "trial") {
+      const way = `free token for 1 computer at ${accountUrl}`;
+      if (ended) return { kind: "trial-ended", urgent: true, text: `free trial ended · ${way}` };
+      const left = daysLeft(p.paidUntil, now);
+      return { kind: "trial", urgent: false, text: `trial · ${left} day${left === 1 ? "" : "s"} left · ${way}` };
+    }
     // SHORT AND CALM (#292: "make it simpler … seems so serious"): the fact, then the one thing to
     // do. `urgent` is what the bar colours by — only these two need the user to act.
     if (ended) return { kind: "plan-ended", urgent: true, text: `Pro ended ${shortDate(p.paidUntil)} · renew at ${pricingUrl}` };
@@ -324,7 +386,7 @@ export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempt
 }
 
 /** "Free plan" / "Pro plan" — the name a person uses. */
-const planName = (plan) => (plan === "pro" ? "Pro plan" : "Free plan");
+const planName = (plan) => (plan === "pro" ? "Pro plan" : plan === "trial" ? "free trial" : "Free plan");
 /** "1 computer" / "4 computers" — "computer", not "device": a device is also a phone. */
 const computers = (n) => `${n} ${n === 1 ? "computer" : "computers"}`;
 
@@ -351,6 +413,10 @@ export function accountLine({ payload = null, settingsEmail = "", now = new Date
     if (payload.plan === "pro" && Number.isFinite(until) && until > now.getTime()) {
       plan = `Pro until ${shortDate(payload.paidUntil)}`;
       pro = true;
+    } else if (payload.plan === "trial") {
+      plan = Number.isFinite(until) && until > now.getTime()
+        ? `Free trial until ${shortDate(payload.paidUntil)}`
+        : `Free trial ended ${shortDate(payload.paidUntil)}`;
     } else if (payload.paidUntil) {
       plan = `Free — Pro ended ${shortDate(payload.paidUntil)}`;
     } else {
@@ -364,6 +430,10 @@ export function tokenSummary(payload, now = new Date()) {
   const lines = [];
   if (payload.plan === "pro" && payload.paidUntil && Date.parse(payload.paidUntil) > now.getTime()) {
     lines.push(`Pro until ${shortDate(payload.paidUntil)}.`);
+  } else if (payload.plan === "trial") {
+    lines.push(Date.parse(payload.paidUntil) > now.getTime()
+      ? `Free trial on this computer — ${daysLeft(payload.paidUntil, now)} day(s) left, until ${shortDate(payload.paidUntil)}.`
+      : `The free trial on this computer ended on ${shortDate(payload.paidUntil)}.`);
   } else if (payload.paidUntil) {
     lines.push(`Free — the Pro plan ended on ${shortDate(payload.paidUntil)}.`);
   } else {
@@ -410,11 +480,14 @@ export function enforcementDecision({ token, publicKeyB64, now = new Date(), sit
   const pricingUrl = `${host}/pricing`;
   const accountUrl = `${host}/account`;
   const ended = p.paidUntil && Date.parse(p.paidUntil) <= now.getTime();
-  if (p.plan !== "pro" || ended) {
+  // A running free trial (#305) is entitled like Pro, for its ten days.
+  if ((p.plan !== "pro" && p.plan !== "trial") || ended) {
     return {
       enforced: true,
       allowed: false,
-      why: ended
+      why: ended && p.plan === "trial"
+        ? `The free trial on this computer ended on ${shortDate(p.paidUntil)}. Go Pro at ${pricingUrl} to keep using the agent.`
+        : ended
         ? `Your gu Pro plan ended on ${shortDate(p.paidUntil)}. Renew at ${pricingUrl} to keep using the agent.`
         : `gu needs a Pro plan on this account. See ${pricingUrl} — the rest of gu still works.`,
     };

package/client-expert-run.mjs

@@ -193,8 +193,15 @@ export async function probeMongo() {
   // 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);
+  // A HANDSHAKE, NOT AN OPEN PORT (task #304). "The port accepts a connection" also passes when
+  // Docker Desktop is stuck: its forwarder keeps 27017 open while nothing behind it answers, so
+  // setup used to call that "running" and every API call then timed out. A MongoDB `hello` is
+  // answered with or without a password; silence means nothing usable is there.
   if (await tcpReachable(host, port)) {
-    return { running: true, how: `listening at ${host}:${port}` };
+    const { mongoAnswers, portHolder } = await import("./mongo-native.mjs");
+    const state = await mongoAnswers(host, port);
+    if (state === "answers") return { running: true, how: `answering at ${host}:${port}` };
+    return { running: false, how: null, silentPort: true, holder: await portHolder(port), installed: false };
   }
 
   if (process.platform === "win32") {
@@ -272,6 +279,58 @@ export async function probeDockerForMongo(name = MONGO_DOCKER_NAME) {
   };
 }
 
+/**
+ * macOS: make a native MongoDB answer on 27017 (task #304). → { ok, explained }.
+ * `explained` = it printed its own guidance, so the caller adds none.
+ */
+export async function ensureNativeMongoMac(ask, mongo, { log = (l) => console.log(l) } = {}) {
+  const mn = await import("./mongo-native.mjs");
+  const brew = mn.findBrew();
+  const { action, holder } = mn.macMongoAction({
+    state: mongo.silentPort ? "silent" : "closed",
+    holder: mongo.holder,
+    serverInstalled: Boolean(mongo.installed),
+    brew,
+  });
+  if (action === "docker-stuck" || action === "port-silent") {
+    log("");
+    for (const l of mn.silentPortLines({ action, holder })) log("  " + (l.startsWith("  ") ? l : dim(l)));
+    return { ok: false, explained: true };
+  }
+  if (action === "no-brew") {
+    log("");
+    for (const l of mn.noBrewLines()) log(dim("  " + l));
+    return { ok: false, explained: true };
+  }
+  const installing = action === "brew-install";
+  const yes = await ask(
+    installing
+      ? "  Install MongoDB Community with Homebrew now? [Y/n]: "
+      : "  MongoDB is installed but not running. Start it now (brew services)? [Y/n]: "
+  );
+  if (String(yes ?? "").trim().toLowerCase().startsWith("n")) {
+    log(dim("\n  Not installed. To do it yourself:"));
+    for (const s of installing ? mn.BREW_INSTALL_STEPS : mn.BREW_START_STEPS) log(dim(`    brew ${s.join(" ")}`));
+    return { ok: false, explained: true };
+  }
+  log("\n  " + bold(installing ? "Installing MongoDB Community" : "Starting MongoDB") + dim("   Homebrew, a minute or two"));
+  const done = await mn.runBrewSteps(brew, installing ? mn.BREW_INSTALL_STEPS : mn.BREW_START_STEPS, {
+    onLine: (l) => l.length < 200 && log(dim("    " + l)),
+  });
+  if (!done) {
+    log("\n  " + red("✗ ") + "Homebrew did not finish — the lines above say why.");
+    return { ok: false, explained: true };
+  }
+  const { host, port } = mongoHostPort(LOCAL_MONGO_URI);
+  if (!(await mn.waitForMongo(host, port, { timeoutMs: 60000 }))) {
+    log("\n  " + red("✗ ") + `MongoDB was started but is not answering at ${host}:${port} yet.`);
+    log(dim("  Its log: /opt/homebrew/var/log/mongodb/mongo.log — then run gu again."));
+    return { ok: false, explained: true };
+  }
+  log("  " + cyan("✓ MongoDB Community is running") + dim(` at ${host}:${port} (brew services — it starts at login)`));
+  return { ok: true, explained: true };
+}
+
 /**
  * Start MongoDB in a container and wait for it to answer. → true when it is up.
  *
@@ -684,6 +743,19 @@ export async function runClientExpertSetup({
     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."));
+    // A MAC GETS NATIVE MONGODB, NOT DOCKER (task #304): Homebrew's mongodb-community as a brew
+    // service. Docker on a Mac puts every call through its VM, and a stuck Docker Desktop keeps
+    // 27017 open while nothing answers — the failure that stopped this project's own Mac. The
+    // Docker branch below stays for Linux and Windows.
+    let explained = false;
+    if (machine.platform === "darwin") {
+      const r = await ensureNativeMongoMac(ask, mongo);
+      if (r.ok) {
+        mongo.running = true;
+        probe.mongoRunning = true;
+      }
+      explained = r.explained;
+    } else
     // 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`
@@ -693,8 +765,8 @@ export async function runClientExpertSetup({
       mongo.running = true;
       probe.mongoRunning = true;
     }
-    if (probe.mongoRunning) {
-      // fall through to the rest of setup below — nothing left to instruct.
+    if (probe.mongoRunning || explained) {
+      // fall through — running, or the Mac branch has already said what to do.
     } else if (mongo.installed) {
       console.log(dim("\n  It looks installed but is not answering. Start it with:\n"));
       console.log(

package/gonext_agent_chat.py

@@ -1004,6 +1004,13 @@ class _AgentOffline(_AgentConfigError):
     which would need the network anyway and would answer as if the work had been done."""
 
 
+class _StreamStalled(RuntimeError):
+    """A streamed reply STOPPED mid-way: tokens had started, then nothing arrived for the stall
+    window (task #306). What a connection that died silently looks like — the internet dropped
+    during the reply and the dead TCP connection never errored. Handled as a lost connection
+    (_is_offline): the same step is sent again on a fresh connection."""
+
+
 class _AgentBackendOverloaded(RuntimeError):
     """The coding backend refused every attempt with 429/rate-limit (task #114). Carries
     the user-facing explanation; like a gateway outage it must NOT degrade to a plain
@@ -3572,7 +3579,16 @@ def _is_offline(err, host: str = "") -> bool:
 
     Something that answered with a status is never offline, and a timeout is its own class
     (openai's APITimeoutError subclasses APIConnectionError, so it is excluded by name)."""
-    if err is None or _http_status_of(err) is not None or _is_request_timeout(err):
+    if err is None:
+        return False
+    # A stream that died mid-reply (#306) — whatever the host: the reply had started, so the
+    # server was up, and only the connection can have gone.
+    cur, depth = err, 0
+    while cur is not None and depth < 6:
+        if isinstance(cur, _StreamStalled):
+            return True
+        cur, depth = (getattr(cur, "__cause__", None) or getattr(cur, "__context__", None)), depth + 1
+    if _http_status_of(err) is not None or _is_request_timeout(err):
         return False
     local = _host_locality_is_local(host)
     cur, depth = err, 0
@@ -3604,6 +3620,68 @@ def _host_locality_is_local(host: str) -> bool:
     return "." not in h or h.endswith((".local", ".lan", ".internal", ".home"))
 
 
+def _stream_stall_seconds() -> float:
+    """How long a STARTED stream may go silent before it is treated as a dead connection
+    (GONEXT_STREAM_STALL_S, default 60s). Only after the first token: before it, a slow box may
+    legitimately spend many minutes in prompt-eval (see _code_request_timeout)."""
+    try:
+        v = float(os.environ.get("GONEXT_STREAM_STALL_S", "") or 60)
+    except ValueError:
+        v = 60.0
+    return max(5.0, v)
+
+
+def _iter_with_stall(stream, started, stall_s: float, on_data=None, poll: float = 0.5):
+    """Yield the stream's chunks, raising _StreamStalled when it goes quiet mid-reply (#306).
+
+    WHY A READER THREAD. `for chunk in stream` blocks inside a socket read; when the connection
+    died silently that read never returns, and closing the socket from another thread does not
+    reliably wake it on every OS. So a helper thread does the blocking reads and hands chunks over
+    a queue, and this side waits on the queue with a timeout it controls. On a stall the stream is
+    closed best-effort and the reader is abandoned (a daemon thread on a dead socket, gone with the
+    process) — the step is then sent again on a new connection.
+
+    `started()` says whether the reply has begun; silence before that is prompt-eval, not a stall."""
+    import queue as _queue
+    import threading as _threading
+    q = _queue.Queue()
+
+    def _reader():
+        try:
+            for c in stream:
+                q.put(("chunk", c))
+            q.put(("end", None))
+        except BaseException as e:  # noqa: BLE001
+            q.put(("error", e))
+
+    _threading.Thread(target=_reader, name="gu-stream-reader", daemon=True).start()
+    last = time.monotonic()
+    while True:
+        try:
+            kind, val = q.get(timeout=poll)
+        except _queue.Empty:
+            if started() and time.monotonic() - last > stall_s:
+                try:
+                    stream.close()
+                except Exception:  # noqa: BLE001
+                    pass
+                raise _StreamStalled(
+                    f"the reply stopped: no data for {stall_s:.0f}s after it had started")
+            continue
+        last = time.monotonic()
+        if on_data is not None:
+            try:
+                on_data()
+            except Exception:  # noqa: BLE001
+                pass
+        if kind == "chunk":
+            yield val
+        elif kind == "end":
+            return
+        else:
+            raise val
+
+
 def _offline_wait_budget() -> float:
     """How long a turn waits for the network before giving up (GONEXT_OFFLINE_WAIT_S, default 10 min)."""
     try:
@@ -10086,7 +10164,16 @@ def run_agent_chat(cfg):
                     # Separate this step's live thinking from the previous step summary.
                     _emit({"type": "stream", "text": "\n"})
 
-            for chunk in stream:
+            # #306: the stream goes through the stall watchdog — a reply that stops mid-way (the
+            # connection died silently) raises _StreamStalled instead of hanging for the hour-long
+            # request budget. `_last_data_at` feeds the heartbeat's "no data for Ns".
+            self._last_data_at = time.monotonic()
+            for chunk in _iter_with_stall(
+                stream,
+                started=lambda: first_token_at is not None,
+                stall_s=_stream_stall_seconds(),
+                on_data=lambda: setattr(self, "_last_data_at", time.monotonic()),
+            ):
                 usage = getattr(chunk, "usage", None)
                 if usage is not None:
                     self._last_usage_seen = True
@@ -10488,8 +10575,17 @@ def run_agent_chat(cfg):
                     # and the call is in its finishing phase, not stuck waiting.
                     word = (_STATUS_ALMOST_DONE if getattr(self, "_first_token_seen", False)
                             else f"{_thinking_word()}…")
-                    _emit({"type": "step", "text": f"{word} ({waited}s)"})
-                    _log(f"heartbeat: model call in flight {waited}s")
+                    # #306: after the first token, SAY when nothing is arriving. "Almost done"
+                    # kept counting for 20 minutes over a stream that had died.
+                    gap = 0.0
+                    if getattr(self, "_first_token_seen", False):
+                        gap = time.monotonic() - getattr(self, "_last_data_at", time.monotonic())
+                    if gap >= 20:
+                        _emit({"type": "step", "text": f"No data from the model for {gap:.0f}s — watching the connection…"})
+                        _log(f"heartbeat: model call in flight {waited}s — no data for {gap:.0f}s")
+                    else:
+                        _emit({"type": "step", "text": f"{word} ({waited}s)"})
+                        _log(f"heartbeat: model call in flight {waited}s")
 
             hb = threading.Thread(target=_heartbeat, daemon=True)
             hb.start()
@@ -10586,7 +10682,10 @@ def run_agent_chat(cfg):
                             now = time.monotonic()
                             if offline["since"] is None:
                                 offline.update(since=now, n=0, said=now)
+                                _stalled = isinstance(e, _StreamStalled)
                                 _emit({"type": "step", "text": (
+                                    f"The connection to {_host} stopped mid-reply — reconnecting…"
+                                    if _stalled else
                                     f"Lost the connection to {_host} — waiting for it to come back…")})
                             waited = now - offline["since"]
                             budget = _offline_wait_budget()

package/gu-cli.mjs

@@ -132,6 +132,7 @@ Usage:
                                                #   terminal's update row to notice
   gu-cli rag                               # test the embedder end-to-end + list knowledge bases
   gu-cli workspace revert [runId]          # undo an agent run's file edits from its backups
+  gu-cli mongo migrate-from-docker         # macOS: move a Docker MongoDB to native (Homebrew)
   gu-cli clear [--scratch|--keep-history] [--yes]  # back to a fresh machine (asks first)
   gu-cli fix-powershell [--check]          # Windows: drop PowerShell's built-in \`gu\` alias
                                                #   (it is Get-Unique and shadows this CLI)
@@ -1480,7 +1481,151 @@ if (args[0] === "rag") {
   process.exit(0);
 }
 // Task #127, Phase 3: ensure the base chat model is downloaded + running (no GoTerminal).
+/**
+ * gu-cli mongo migrate-from-docker [--container <name>] — move a Docker MongoDB's data to a
+ * native Homebrew MongoDB on this Mac (task #304). The steps done by hand on 2026-09-30, made
+ * repeatable: nothing about the Docker container changes until the copy has been VERIFIED
+ * collection by collection, and even then it is stopped, never deleted.
+ */
+if (args[0] === "mongo") {
+  const mn = await import("./mongo-native.mjs");
+  const sub = args[1] || "";
+  if (sub !== "migrate-from-docker") {
+    console.log("\n  Usage: gu-cli mongo migrate-from-docker [--container <name>]\n");
+    process.exit(sub ? 1 : 0);
+  }
+  // The container publishing 27017, detected — setup's name has changed over time, and a machine
+  // keeps the name it was set up with.
+  const ci = args.indexOf("--container");
+  const container = ci >= 0 && args[ci + 1] ? args[ci + 1] : ((await mn.dockerContainerOnPort(27017)) || "");
+  const TEMP = 27018;
+  const DBPATH = "/opt/homebrew/var/mongodb";
+  const plan = mn.migrationPlan({ container, tempPort: TEMP, dbPath: DBPATH });
+  const say = (id, ok, extra = "") => {
+    const step = plan.find((p) => p.id === id);
+    console.log(`  ${ok ? "✓" : "✗"} ${step.says}${extra ? ` — ${extra}` : ""}`);
+  };
+  const fail = (id, why) => {
+    say(id, false, why);
+    console.log("\n  Nothing about the Docker container was changed.\n");
+    process.exit(1);
+  };
+  if (process.platform !== "darwin") fail("install", "this command is for macOS (Homebrew)");
+  console.log("");
+  // 1) the source answers
+  if ((await mn.mongoAnswers("127.0.0.1", 27017)) !== "answers") {
+    fail("source", "nothing answers on 27017 — start Docker Desktop (or restart it if stuck) first");
+  }
+  const holder = await mn.portHolder(27017);
+  if (!mn.isDockerHolder(holder)) fail("source", `27017 is served by ${holder || "something"} — not Docker, nothing to migrate`);
+  if (!container) fail("source", "no running Docker container publishes 27017 — name it with --container");
+  say("source", true, container);
+  // 2) Homebrew MongoDB installed
+  const brew = mn.findBrew();
+  if (!brew) fail("install", "Homebrew is not installed (https://brew.sh)");
+  const hasMongod = (await mn.captureOutput("sh", ["-c", "command -v mongod || true"])).trim();
+  if (!hasMongod) {
+    const ok = await mn.runBrewSteps(brew, mn.BREW_INSTALL_STEPS.slice(0, 2), { onLine: (l) => console.log(`      ${l}`) });
+    if (!ok) fail("install", "brew install failed (see above)");
+  }
+  say("install", true);
+  // 3) native mongod on the temp port, its own process (MongoDB 9 refuses --fork on macOS)
+  const { mkdirSync } = await import("node:fs");
+  mkdirSync(DBPATH, { recursive: true });
+  const temp = spawn("mongod", ["--dbpath", DBPATH, "--port", String(TEMP), "--bind_ip", "127.0.0.1",
+    "--logpath", "/opt/homebrew/var/log/mongodb/mongo-migrate.log"], { stdio: "ignore", detached: true });
+  temp.unref();
+  const stopTemp = async () => {
+    await mn.captureOutput("mongosh", ["--quiet", "--port", String(TEMP), "admin", "--eval", "try{db.adminCommand({shutdown:1})}catch(e){}"], 15000);
+  };
+  if (!(await mn.waitForMongo("127.0.0.1", TEMP, { timeoutMs: 60000 }))) fail("temp", "it did not start (log: /opt/homebrew/var/log/mongodb/mongo-migrate.log)");
+  say("temp", true);
+  const counts = async (port) => {
+    try {
+      return JSON.parse((await mn.captureOutput("mongosh", ["--quiet", "--port", String(port), "--eval", mn.COUNTS_SCRIPT], 120000)).trim() || "{}");
+    } catch {
+      return null;
+    }
+  };
+  // 4) the native one must be empty — never merge into data we did not put there
+  const already = await counts(TEMP);
+  if (already === null || Object.keys(already).length) {
+    await stopTemp();
+    fail("empty", already === null ? "could not read it" : `it already holds ${Object.keys(already).length} collection(s) — move them away first`);
+  }
+  say("empty", true);
+  // 5) pause the API
+  const self = process.argv[1];
+  await mn.runStreaming(process.execPath, [self, "api", "stop"]);
+  say("api-stop", true);
+  // 6) copy: mongodump | mongorestore
+  const copied = await new Promise((resolve) => {
+    const dump = spawn("mongodump", ["--uri", "mongodb://127.0.0.1:27017", "--archive", "--quiet"], { stdio: ["ignore", "pipe", "inherit"] });
+    const restore = spawn("mongorestore", ["--uri", `mongodb://127.0.0.1:${TEMP}`, "--archive", "--nsExclude", "admin.system.version", "--quiet"], { stdio: ["pipe", "inherit", "inherit"] });
+    dump.stdout.pipe(restore.stdin);
+    let codes = [];
+    const end = () => codes.length === 2 && resolve(codes.every((c) => c === 0));
+    dump.on("close", (c) => { codes.push(c); end(); });
+    restore.on("close", (c) => { codes.push(c); end(); });
+    dump.on("error", () => resolve(false));
+    restore.on("error", () => resolve(false));
+  });
+  if (!copied) {
+    await stopTemp();
+    await mn.runStreaming(process.execPath, [self, "api", "start"]);
+    fail("copy", "mongodump / mongorestore failed (see above)");
+  }
+  say("copy", true);
+  // 7) verify
+  const before = await counts(27017);
+  const after = await counts(TEMP);
+  const diff = before && after ? mn.compareCounts(before, after) : [{ ns: "(could not read counts)" }];
+  if (diff.length) {
+    await stopTemp();
+    await mn.runStreaming(process.execPath, [self, "api", "start"]);
+    for (const d of diff.slice(0, 10)) console.log(`      ${d.ns}: ${d.before} → ${d.after}`);
+    fail("verify", `${diff.length} collection(s) differ — the Docker MongoDB stays in use`);
+  }
+  say("verify", true, `${Object.keys(before).length} collections`);
+  // 8) the container: stopped, not restarting, KEPT
+  await mn.captureOutput("docker", ["update", "--restart=no", container], 30000);
+  await mn.captureOutput("docker", ["stop", container], 60000);
+  say("container", true);
+  // 9) switch: temp down, the brew service on 27017
+  await stopTemp();
+  const started = await mn.runBrewSteps(brew, mn.BREW_START_STEPS, { onLine: (l) => console.log(`      ${l}`) });
+  if (!started || !(await mn.waitForMongo("127.0.0.1", 27017, { timeoutMs: 60000 }))) {
+    console.log(`  ✗ ${plan.find((p) => p.id === "switch").says}`);
+    console.log(`\n  The data is copied, but the native MongoDB is not answering on 27017.`);
+    console.log(`  Put Docker back while you look:  docker start ${container}\n`);
+    process.exit(1);
+  }
+  say("switch", true);
+  // 10) API back
+  await mn.runStreaming(process.execPath, [self, "api", "start"]);
+  say("api-start", true);
+  console.log(`\n  Done. The old container ${container} is stopped and kept as a backup —`);
+  console.log(`  remove it when you are happy:  docker rm ${container}\n`);
+  process.exit(0);
+}
+
 if (args[0] === "doctor") {
+  // Task #304: a Mac whose MongoDB runs in Docker is told the native option, once, up front —
+  // a working Docker MongoDB is left alone (it is a choice), a silent one is named as stuck.
+  if (process.platform === "darwin") {
+    try {
+      const mn = await import("./mongo-native.mjs");
+      const holder = await mn.portHolder(27017);
+      if (mn.isDockerHolder(holder)) {
+        const state = await mn.mongoAnswers("127.0.0.1", 27017);
+        console.log(state === "answers"
+          ? "\n  MongoDB runs in Docker here. A native one is faster and needs no Docker Desktop:\n    gu-cli mongo migrate-from-docker\n"
+          : "\n  ✗ Port 27017 is Docker's, but no MongoDB answers — Docker Desktop looks stuck.\n    Restart it (killall Docker && open -a Docker), then: gu-cli mongo migrate-from-docker\n");
+      }
+    } catch {
+      /* a note, never a reason for doctor to fail */
+    }
+  }
   /**
    * Should doctor set up MODELS on this machine? → true | false | undefined (decide by hardware)
    *

package/gu-repl.mjs

@@ -1004,7 +1004,43 @@ const regionUi = (seq) => {
  * parked — on the frozen input line, where the very next paintBar() erases it. That is how a
  * failed turn came out as `>> hi` followed by nothing at all.
  */
+/**
+ * THE QUESTION IS COMMITTED ON THE TURN'S FIRST OUTPUT (task #307, the user's design).
+ *
+ * A submitted question used to be printed into the transcript the moment Enter was pressed — so a
+ * change of mind a second later (Ctrl+C, edit, resend) left the abandoned ">> eys" in the
+ * scrollback, above the corrected question, where nothing can take it back out. Now the echo is
+ * HELD (pendingEcho) and shown in the live block above the status line, and it is written for real
+ * only when the turn prints something — the first line through contentWrite below, so it always
+ * lands above that output, never after it.
+ *
+ *   · Ctrl+C BEFORE any output: nothing reached the transcript. The question goes back into the
+ *     input to be edited, and there is no trace to clean up.
+ *   · Ctrl+C AFTER output: the question is committed — it happened, and what the turn did is below
+ *     it. A plain stop: no editing, the question stands, "continue" resumes it (#247).
+ */
+let pendingEcho = null;
+let echoCommitted = true;
+/** The held question as live rows: at most 3 lines of it, each clipped to the width, then a blank. */
+function pendingEchoRows() {
+  if (pendingEcho === null) return [];
+  const width = Math.max(20, process.stdout.columns || 80);
+  const lines = String(pendingEcho).replace(/\n+$/, "").split("\n");
+  const shown = lines.slice(0, 3).map((l) => clipVisible(l, width - 1));
+  if (lines.length > 3) shown.push(dim(`${GUTTER}… ${lines.length - 3} more line(s)`));
+  return [...shown, ""];
+}
+function flushPendingEcho() {
+  if (pendingEcho === null) return;
+  const text = pendingEcho;
+  pendingEcho = null;
+  echoCommitted = true;
+  process.stdout.write(text);
+}
+
 const contentWrite = (raw, chunk, enc, cb) => {
+  // Any real output commits a held question first (see pendingEcho above).
+  if (_uiDepth === 0 && pendingEcho !== null) flushPendingEcho();
   if (_uiDepth === 0 && (typeof chunk === "string" || Buffer.isBuffer(chunk))) {
     transcript.append(String(chunk));
     // ALWAYS FOLLOW THE BOTTOM. New output means there is something newer to see, so a view
@@ -1538,6 +1574,21 @@ const missingNoticeText = () => {
   return parts.length ? "⚠ " + parts.join("  ·  ") : "";
 };
 
+// #307: the calm note after a quick change of mind — dim, not the ⚠ orange of a warning, and in the
+// bar rather than the transcript (which the whole point is to leave untouched).
+let stopNotice = "";
+let stopNoticeTimer = null;
+function showStopNotice(text) {
+  stopNotice = text;
+  if (stopNoticeTimer) clearTimeout(stopNoticeTimer);
+  stopNoticeTimer = setTimeout(() => {
+    stopNotice = "";
+    stopNoticeTimer = null;
+    if (barPinned()) paintBar();
+  }, 15_000);
+  stopNoticeTimer.unref?.();
+  if (barPinned()) paintBar();
+}
 function showImageNotice(text) {
   imageNotice = text;
   if (imageNoticeTimer) clearTimeout(imageNoticeTimer);
@@ -2134,6 +2185,32 @@ let startupRenewDone = false;
  */
 let licenceBlock = null;
 let licenceDecided = false;
+
+/**
+ * THE FREE TRIAL (#305): a first install gets ten days on this computer instead of a "paste your
+ * token" stop. Once per computer — the gu service decides, keyed on the OS machine id's hash. → true
+ * when a trial token is now saved. Tried at most once per start by the startup refresh, and again
+ * right before the token question (a first start may have been offline).
+ */
+let trialTried = false;
+let trialEndedAt = ""; // this computer's trial has ended — the token question says so
+async function tryTrialToken(ct, dir, { announce = true } = {}) {
+  const device = await ct.trialDevice().catch(() => null);
+  if (!device) return false; // no stable machine id → no trial (see trialDevice)
+  const { DEFAULT_API_BASE } = await import("./device-login.mjs");
+  const hostedBase = String(process.env.GU_TOKEN_API_BASE ?? "").trim() || DEFAULT_API_BASE;
+  const r = await ct.claimTrial({ hostedBase, device });
+  if (r.ok && ct.verifyCliToken(r.token, ct.publicKey()).ok) {
+    await ct.writeState(dir, { token: r.token, lastAttemptAt: new Date().toISOString() });
+    if (announce) {
+      console.log(GUTTER + accent(r.created ? ct.trialStartedLine(r.endsAt, ct.siteUrl()) : `Free trial on this computer until ${ct.shortDate(r.endsAt)}.`));
+    }
+    return true;
+  }
+  if (r.why === "used" && r.endedAt) trialEndedAt = r.endedAt;
+  return false;
+}
+
 async function refreshCliToken() {
   if (tokenBusy) return;
   tokenBusy = true;
@@ -2148,6 +2225,11 @@ async function refreshCliToken() {
     const mode = isClientExpert() ? "expert" : "client";
     const site = ct.siteUrl();
     let state = await ct.readState(dir);
+    // #305: private mode with no usable token → this computer's free trial, before anything asks.
+    if (mode === "expert" && !trialTried && !(state.token && ct.verifyCliToken(state.token, pk).ok)) {
+      trialTried = true;
+      if (await tryTrialToken(ct, dir)) state = await ct.readState(dir);
+    }
     const now = new Date();
     const noticeNow = () =>
       ct.barNotice({ token: state.token, publicKeyB64: pk, mode, now: new Date(), attempted: Boolean(state.lastAttemptAt), site });
@@ -2423,7 +2505,9 @@ const footerRows = () =>
     // Its own row (#54), sized to the window so the fix it names is never the part cut off.
     notice: imageNotice
       ? orange("⚠ " + fitImageNotice(imageNotice, (process.stdout.columns || 80) - visibleLen(GUTTER) - 1))
-      : "",
+      : stopNotice
+        ? dim(clipVisible(stopNotice, (process.stdout.columns || 80) - visibleLen(GUTTER) - 1))
+        : "",
     // Task #14: the skipped-setup warning — persistent (not a timed notice), red, its own row.
     missing: missingNoticeText() ? red(missingNoticeText()) : "",
   });
@@ -2510,7 +2594,9 @@ function frozenZone() {
   // (reported: "the input line somehow now too high, mostly 2 lines"). Rather than trust every
   // teardown path to have cleared it — there are four, and clearStatus early-returns when
   // statusShown is already false — the prompt simply refuses to render any.
-  const status = footerActive ? [] : liveStatusRows;
+  // #307: a question held until its turn prints anything sits on top of the status block — where
+  // it will land once committed, so nothing moves when it does.
+  const status = footerActive ? [] : [...pendingEchoRows(), ...liveStatusRows];
   // DECIDED BEFORE THE LAYOUT, because the head's height depends on it: the blank under the
   // separator exists to lift a CONTROL off the typed line, so with no control there is nothing
   // to lift. The same three conditions the rows[sep] writes below test — kept adjacent so they
@@ -6689,7 +6775,7 @@ async function runSavePresetCommand(line) {
  *
  * What the turn printed stays on screen: it is the record of what it did.
  */
-async function afterStoppedTurn({ taskLine, submittedInput, turnStartMs, stoppedCommand = "", typed = "" }) {
+async function afterStoppedTurn({ taskLine, submittedInput, turnStartMs, stoppedCommand = "", typed = "", committed = true }) {
   let files = [];
   try {
     const ws = await import("./workspace-revert.mjs");
@@ -6702,13 +6788,25 @@ async function afterStoppedTurn({ taskLine, submittedInput, turnStartMs, stopped
   } catch {
     /* no backups readable — nothing to name */
   }
-  // A bare "continue" was the typed line: giving THAT back is no help, so only the note.
-  const canRestore = Boolean(submittedInput?.raw) && !isResumeWord(typed);
-  for (const l of stopNoteLines({ files, command: stoppedCommand, restored: canRestore })) {
-    console.log(GUTTER + dim(l));
+  // #307 — THE USER'S RULE: the question can be edited again only if it was never committed (the
+  // turn printed nothing). A turn that changed files had something to say, so it counts as
+  // committed; its held question is written now, above the note about those files.
+  if (!committed && files.length) {
+    flushPendingEcho();
+    committed = true;
   }
-  console.log("");
+  if (committed) {
+    for (const l of stopNoteLines({ files, command: stoppedCommand, restored: false })) console.log(GUTTER + dim(l));
+    console.log("");
+    return;
+  }
+  // Never committed: drop the held echo — it never reached the transcript — and give it back.
+  pendingEcho = null;
+  echoCommitted = true;
+  // A bare "continue" was the typed line: giving THAT back is no help.
+  const canRestore = Boolean(submittedInput?.raw) && !isResumeWord(typed);
   if (!canRestore) return;
+  showStopNotice("stopped — your question is back in the input; edit it and press Enter, or Ctrl+C to clear it");
   const text = restoreInput(submittedInput, { pasteStore, imageStore });
   rl.line = text;
   rl.cursor = text.length;
@@ -9661,6 +9759,12 @@ async function ensureTokenForTurn() {
   const state = await ct.readState(dir);
   if (!ct.turnNeedsToken({ privateMode: true, token: state.token })) return true;
   console.log("");
+  // #305: the free trial first — a first start that was offline gets it here, with no question.
+  if (await tryTrialToken(ct, dir)) {
+    console.log("");
+    return true;
+  }
+  if (trialEndedAt) console.log(GUTTER + dim(`The free trial on this computer ended on ${ct.shortDate(trialEndedAt)}.`));
   for (const l of ct.tokenAskLines()) console.log(GUTTER + (l.startsWith("  ") ? dim(l) : yellow(l)));
   for (let attempt = 0; attempt < 2; attempt++) {
     const pasted = String((await ask("  gu token: ")) ?? "").trim();
@@ -10940,8 +11044,10 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
         // killed the Python agent. Print a quiet note and return an empty, non-persisted
         // turn (main() drops it from history).
         clearStatus();
-        process.stdout.write("\n" + GUTTER + dim("(cancelled — the agent was stopped)") + "\n");
-        return { text: "", shown: false, cancelled: true, started: reachedModel, stoppedCommand: runningCmd || "" };
+        // #307: `committed` — did the question reach the transcript (the turn printed something)?
+        const committed = pendingEcho === null;
+        if (committed) process.stdout.write("\n" + GUTTER + dim("(cancelled — the agent was stopped)") + "\n");
+        return { text: "", shown: false, cancelled: true, started: reachedModel, stoppedCommand: runningCmd || "", committed };
       }
       if (job.jobStatus === "failed") {
         clearStatus();
@@ -11827,7 +11933,9 @@ async function main() {
         // agent; the poll loop then returns cleanly with the "(cancelled)" note.
         cancelRequested = true;
         const jobId = currentJobId;
-        process.stdout.write("\n" + GUTTER + red("^C ") + dim("stopping the agent…\n"));
+        // #307: while the question is still held (nothing printed yet), nothing goes to the
+        // transcript either — a quick change of mind leaves no trace.
+        if (pendingEcho === null) process.stdout.write("\n" + GUTTER + red("^C ") + dim("stopping the agent…\n"));
         fetch(`${apiBase}/api/worker/jobs/cancel`, {
           method: "POST",
           headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
@@ -11839,7 +11947,7 @@ async function main() {
         // Second Ctrl+C (or no jobId yet): give up waiting locally. The worker keeps
         // trying to stop, but we stop following.
         followAborted = true;
-        process.stdout.write("\n" + GUTTER + red("^C "));
+        if (pendingEcho === null) process.stdout.write("\n" + GUTTER + red("^C ")); // #307
       }
     } else {
       // Ctrl+C at a prompt with the slash overlay open = dismiss the overlay first (#109).
@@ -11880,6 +11988,9 @@ async function main() {
   }
 
   for (;;) {
+    // #307: a held question whose turn ended without printing anything (and was not a quick
+    // change of mind) is written now — it was asked, and the transcript should say so.
+    if (pendingEcho !== null) flushPendingEcho();
     stopPendingStatus(); // nothing from a previous turn may still be animating (task #140)
     // The bar and the input line live in the frozen rows at the bottom of the window (task
     // #141); `footerActive` only governs the fallback drawing used when the window is too
@@ -11962,7 +12073,20 @@ async function main() {
       // TRANSCRIPT: the echo is written exactly once per submitted line and never repainted,
       // so there is nothing here for a blank to accumulate against.
       // As typed, not as sent: "[Image #1]", never the file path the agent needs (#51).
-      process.stdout.write(PROMPT_PAST + imageMarkersForDisplay(line) + "\n\n");
+      const echo = PROMPT_PAST + imageMarkersForDisplay(line) + "\n\n";
+      if (stopNotice) {
+        stopNotice = "";
+        if (stopNoticeTimer) clearTimeout(stopNoticeTimer);
+      }
+      // #307: a QUESTION (not a /command or !shell line) is held until the turn prints something;
+      // unpinned there is no live block to hold it in, so it is written at once, as before.
+      if (barPinned() && !line.startsWith("/") && !line.startsWith("!")) {
+        pendingEcho = echo;
+        echoCommitted = false;
+        paintBar();
+      } else {
+        process.stdout.write(echo);
+      }
     }
     // ESC AT ANY QUESTION LANDS HERE (see PromptCancelled). Every command below is wrapped as
     // one block rather than each flow catching for itself, because the request was to be able to
@@ -12287,7 +12411,8 @@ async function main() {
             const block = answerBlock({
               elapsedMs, answer: plain, worked: (turnOutputTokens ?? 0) > 0,
               gutter: GUTTER, dim, render: renderAnswer,
-              inputLabel: inputTokens > 0 ? fmtTokens(inputTokens) : "",
+              // No "(↑ N)" here (task #310, the user's call): it was this turn's input total —
+              // the very number the bar's "sent" shows one row below.
             });
             console.log(`${LINE_SPACING}${block.text}\n`);
             registerCopyBlock(block.rows, plain, 1);
@@ -12365,7 +12490,7 @@ async function main() {
         continue;
       }
       const { text: answer, shown, cancelled, started, detached, inputTokens, outputTokens,
-              turnOutputTokens, elapsedMs, stoppedCommand } = turn;
+              turnOutputTokens, elapsedMs, stoppedCommand, committed } = turn;
       // Detached: the agent keeps running on the worker, so the question is neither answered
       // nor stopped — leave it untagged, and say nothing contradicting "the job keeps running".
       if (detached) continue;
@@ -12430,7 +12555,7 @@ async function main() {
           // two must come from one place, and for the empty line under "thought for …".
           const block = answerBlock({
             elapsedMs, answer: plain, worked, gutter: GUTTER, dim, render: renderAnswer,
-            inputLabel: inputTokens > 0 ? fmtTokens(inputTokens) : "",
+            // No "(↑ N)" (task #310): the bar's "sent" already shows this turn's input.
           });
           console.log(`${LINE_SPACING}${block.text}\n`);
           // Register the SOURCE, not the rendering (task #158): renderAnswer hard-wraps the
@@ -12462,7 +12587,7 @@ async function main() {
           // Stopped AFTER the model was called = too slow or stuck, never a change of mind: the
           // request still stands (task #247, the user's rule). Before that, nothing had begun.
           await markInterrupted(cwd, history, taskLine, started ? "stopped" : "cancelled");
-          await afterStoppedTurn({ taskLine, submittedInput, turnStartMs, stoppedCommand, typed: line });
+          await afterStoppedTurn({ taskLine, submittedInput, turnStartMs, stoppedCommand, typed: line, committed: committed !== false });
         } else {
           await markInterrupted(cwd, history, taskLine, "failed");
           // The turn ended cleanly but empty — no exception to summarize, so say exactly that.

package/mongo-native.mjs

@@ -0,0 +1,275 @@
+/**
+ * MONGODB ON A MAC: NATIVE, NOT DOCKER (task #304).
+ *
+ * Client Expert setup used to start MongoDB in Docker first wherever Docker answered. On a Mac that
+ * costs twice: every database call crosses Docker Desktop's VM and port forwarder, and when Docker
+ * Desktop hangs (seen 2026-09-29, after the disk filled) its forwarder keeps 27017 OPEN while
+ * nothing behind it answers — so the API timed out on every request instead of failing fast, gu
+ * said "Worker key lookup failed", and Docker did not recover by itself. The fix that worked was
+ * Homebrew's mongodb-community as a brew service, the data copied across. This module is that fix,
+ * made the default:
+ *
+ *   · probe with a real MongoDB handshake, never "the port accepts a connection"
+ *   · a Mac with no answering MongoDB gets Homebrew's mongodb-community (asked once), and setup
+ *     continues in the same run
+ *   · a Mac whose 27017 belongs to a stuck Docker is TOLD so, and `gu-cli mongo migrate-from-docker`
+ *     moves a working Docker MongoDB's data to the native one (verified collection by collection;
+ *     the container is stopped, never deleted)
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+
+// ---------------------------------------------------------------------------------------------
+// Does something MongoDB answer — not merely accept a TCP connection?
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * An OP_MSG `{ hello: 1, $db: "admin" }` — the first thing every driver sends, answered without
+ * authentication, so it tells a live server (with or without a password) from a port that only
+ * accepts connections. Pure: the exact bytes, built by hand to need no driver.
+ */
+export function helloMessage(requestId = 1) {
+  const cstr = (s) => Buffer.concat([Buffer.from(s, "utf8"), Buffer.from([0])]);
+  const int32 = (n) => {
+    const b = Buffer.alloc(4);
+    b.writeInt32LE(n);
+    return b;
+  };
+  const db = "admin";
+  const elements = Buffer.concat([
+    Buffer.from([0x10]), cstr("hello"), int32(1),
+    Buffer.from([0x02]), cstr("$db"), int32(Buffer.byteLength(db) + 1), cstr(db),
+  ]);
+  const doc = Buffer.concat([int32(4 + elements.length + 1), elements, Buffer.from([0])]);
+  const body = Buffer.concat([int32(0) /* flagBits */, Buffer.from([0]) /* section kind 0 */, doc]);
+  const header = Buffer.concat([int32(16 + body.length), int32(requestId), int32(0), int32(2013)]);
+  return Buffer.concat([header, body]);
+}
+
+/**
+ * → "answers" | "silent" (the port accepts, nothing replies — a stuck forwarder) | "closed".
+ * A reply is any well-formed message header coming back.
+ */
+export async function mongoAnswers(host = "127.0.0.1", port = 27017, timeoutMs = 3000) {
+  const net = await import("node:net");
+  return new Promise((resolve) => {
+    let connected = false;
+    let got = Buffer.alloc(0);
+    const socket = net.connect({ host, port });
+    const done = (v) => {
+      socket.destroy();
+      resolve(v);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => {
+      connected = true;
+      socket.write(helloMessage());
+    });
+    socket.on("data", (d) => {
+      got = Buffer.concat([got, d]);
+      if (got.length >= 16) done(got.readInt32LE(12) === 2013 || got.readInt32LE(12) === 1 ? "answers" : "silent");
+    });
+    socket.once("timeout", () => done(connected ? "silent" : "closed"));
+    socket.once("error", () => done(connected ? "silent" : "closed"));
+    socket.once("close", () => done(connected ? (got.length ? "answers" : "silent") : "closed"));
+  });
+}
+
+/** Wait until MongoDB answers, or give up. → true when it answered. */
+export async function waitForMongo(host, port, { timeoutMs = 60000, check = mongoAnswers, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const until = Date.now() + timeoutMs;
+  while (Date.now() < until) {
+    if ((await check(host, port, 2000)) === "answers") return true;
+    await sleep(1000);
+  }
+  return false;
+}
+
+/**
+ * The process holding a TCP port, by its program's name — null when unknown or none. Through
+ * platform-tools (pidOnPort / processCommand), where the per-OS lookups live.
+ */
+export async function portHolder(port, { pidOf, commandOf } = {}) {
+  const pt = await import("./platform-tools.mjs");
+  const pid = await (pidOf ?? pt.pidOnPort)(port);
+  if (!pid) return null;
+  const cmd = await (commandOf ?? pt.processCommand)(pid);
+  const exe = String(cmd || "").trim().split(/\s+/)[0] || "";
+  return exe ? exe.split(/[\\/]/).pop() : null;
+}
+
+/**
+ * The Docker container publishing a port — detected, not assumed: the container setup creates has
+ * been renamed over time, and a machine keeps the name it was set up with. null when none.
+ */
+export async function dockerContainerOnPort(port, { runCapture = captureOutput } = {}) {
+  const out = await runCapture("docker", ["ps", "--filter", `publish=${port}`, "--format", "{{.Names}}"], 15000);
+  return String(out || "").trim().split("\n")[0].trim() || null;
+}
+
+/** Is that holder Docker's port forwarder? (Docker Desktop: com.docker.backend / vpnkit.) */
+export function isDockerHolder(name) {
+  return /docker|vpnkit|com\.docker/i.test(String(name ?? ""));
+}
+
+// ---------------------------------------------------------------------------------------------
+// What setup should do on a Mac — pure
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * @param state  mongoAnswers() at the database's address
+ * @param holder portHolder() — who owns the port when it is silent
+ * @param serverInstalled a `mongod` is on PATH
+ * @param brew   the Homebrew binary, or ""
+ * → { action, ... }:
+ *   use           a MongoDB answers — use it (a working Docker one included: that is a choice)
+ *   docker-stuck  Docker holds the port and nothing answers — say so; never install over it
+ *   port-silent   something else holds the port and nothing answers
+ *   brew-start    mongod is installed (via brew) but not running — start the service
+ *   brew-install  nothing is there — install mongodb-community with Homebrew
+ *   no-brew       nothing is there and there is no Homebrew — say how to get one
+ */
+export function macMongoAction({ state, holder = null, serverInstalled = false, brew = "" }) {
+  if (state === "answers") return { action: "use" };
+  if (state === "silent") return { action: isDockerHolder(holder) ? "docker-stuck" : "port-silent", holder };
+  if (!brew) return { action: "no-brew" };
+  if (serverInstalled) return { action: "brew-start" };
+  return { action: "brew-install" };
+}
+
+export const BREW_INSTALL_STEPS = [
+  ["tap", "mongodb/brew"],
+  ["install", "mongodb/brew/mongodb-community"],
+  ["services", "start", "mongodb/brew/mongodb-community"],
+];
+export const BREW_START_STEPS = [["services", "start", "mongodb/brew/mongodb-community"]];
+
+/** Where Homebrew is, or "". Apple Silicon first, then Intel. */
+export function findBrew({ exists = existsSync } = {}) {
+  for (const p of ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"]) if (exists(p)) return p;
+  return "";
+}
+
+/** The lines a Mac with no Homebrew is shown. */
+export function noBrewLines() {
+  return [
+    "MongoDB is installed with Homebrew on a Mac, and Homebrew is not here.",
+    "Install Homebrew (https://brew.sh), then run gu again — setup installs MongoDB from there.",
+    "Or install MongoDB Community yourself: https://www.mongodb.com/try/download/community",
+  ];
+}
+
+/** The lines a Mac whose 27017 is a stuck Docker (or another silent program) is shown. */
+export function silentPortLines({ action, holder, port = 27017 }) {
+  if (action === "docker-stuck") {
+    return [
+      `Port ${port} belongs to Docker (${holder}), but no MongoDB answers there — Docker Desktop looks stuck.`,
+      "Restart it: quit Docker Desktop (or run: killall Docker && open -a Docker).",
+      "Once its MongoDB answers, move the data to a native MongoDB (faster, and no Docker needed):",
+      "  gu-cli mongo migrate-from-docker",
+    ];
+  }
+  return [
+    `Port ${port} is held by ${holder || "another program"}, but no MongoDB answers there.`,
+    "Stop that program (or free the port), then run gu again.",
+  ];
+}
+
+// ---------------------------------------------------------------------------------------------
+// Running commands with their output shown
+// ---------------------------------------------------------------------------------------------
+
+/** Run a command, streaming each output line to onLine. → exit code (null if it could not start). */
+export function runStreaming(cmd, args, { onLine = () => {}, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], env });
+    } catch {
+      resolve(null);
+      return;
+    }
+    const lines = (b) => String(b).split("\n").map((l) => l.trim()).filter(Boolean).forEach(onLine);
+    child.stdout.on("data", lines);
+    child.stderr.on("data", lines);
+    child.on("error", () => resolve(null));
+    child.on("close", (code) => resolve(code));
+  });
+}
+
+/** Run a command and return its stdout, or "" — for lookups. */
+export function captureOutput(cmd, args, timeoutMs = 10000) {
+  return new Promise((resolve) => {
+    let out = "";
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      resolve("");
+      return;
+    }
+    const t = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.stdout.on("data", (b) => (out += b));
+    child.on("error", () => {
+      clearTimeout(t);
+      resolve("");
+    });
+    child.on("close", () => {
+      clearTimeout(t);
+      resolve(out);
+    });
+  });
+}
+
+/**
+ * Homebrew steps, one after another, output shown. → true when all succeeded. HOMEBREW_NO_AUTO_UPDATE
+ * keeps `brew install` from first updating every formula on the machine — minutes nobody asked for.
+ */
+export async function runBrewSteps(brew, steps, { onLine = () => {}, run = runStreaming } = {}) {
+  for (const s of steps) {
+    onLine(`$ brew ${s.join(" ")}`);
+    const code = await run(brew, s, { onLine, env: { ...process.env, HOMEBREW_NO_AUTO_UPDATE: "1" } });
+    if (code !== 0) return false;
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Moving a Docker MongoDB's data to the native one
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Per collection "docs/indexes", old vs new → the ones that differ. Pure. A migration is only
+ * finished when this is empty — the old one is not touched until then.
+ */
+export function compareCounts(before, after) {
+  const keys = [...new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})])].sort();
+  return keys.filter((k) => (before ?? {})[k] !== (after ?? {})[k]).map((k) => ({ ns: k, before: before?.[k] ?? null, after: after?.[k] ?? null }));
+}
+
+/** The mongosh script that prints every user collection's "documents/indexes" as JSON. */
+export const COUNTS_SCRIPT =
+  'const o={};db.adminCommand({listDatabases:1}).databases.map(d=>d.name)' +
+  '.filter(n=>!["admin","config","local"].includes(n)).forEach(n=>{const d=db.getSiblingDB(n);' +
+  'd.getCollectionNames().forEach(c=>{o[n+"."+c]=d[c].countDocuments({})+"/"+d[c].getIndexes().length})});' +
+  "print(JSON.stringify(o))";
+
+/**
+ * The migration, as named steps (`gu-cli mongo migrate-from-docker`). Pure: the orchestration lives
+ * in the CLI, which runs these in order and stops at the first that fails — before the Docker
+ * container is touched, if the copy did not verify.
+ */
+export function migrationPlan({ container = "the MongoDB container", tempPort = 27018, dbPath = "/opt/homebrew/var/mongodb" } = {}) {
+  return [
+    { id: "source", says: "the Docker MongoDB answers on 27017" },
+    { id: "install", says: "MongoDB Community installed with Homebrew" },
+    { id: "temp", says: `the native MongoDB started on ${tempPort} (data in ${dbPath})` },
+    { id: "empty", says: "the native MongoDB holds no user databases yet" },
+    { id: "api-stop", says: "gu's local API paused — nothing writes during the copy" },
+    { id: "copy", says: "every database copied (mongodump | mongorestore)" },
+    { id: "verify", says: "every collection's documents and indexes match" },
+    { id: "container", says: `the Docker container ${container} stopped and set not to restart (kept, not deleted)` },
+    { id: "switch", says: "the native MongoDB serving 27017 as a brew service" },
+    { id: "api-start", says: "gu's local API started again" },
+  ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.771",
+  "version": "1.0.772",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,7 @@
     "setup-prompts.mjs",
     "turn-stop.mjs",
     "workspace-revert.mjs",
+    "mongo-native.mjs",
     "terminal-hover.mjs",
     "terminal-layout.mjs",
     "terminal-viewport.mjs",

package/terminal-layout.mjs

@@ -472,7 +472,7 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
  * HOW TO PASTE, for this platform (issue #67). Two different things share the word: TEXT is pasted
  * by the terminal app (gu only sees the result), an IMAGE by gu's own keys (#284).
  *
- *   macOS    text ⌘V            image ctrl+v — a terminal's ⌘V sends nothing for an image
+ *   macOS    text ⌘+V           image ctrl+v — a terminal's ⌘+V sends nothing for an image
  *   Windows  text ctrl+v        image alt+v  — Windows Terminal keeps ctrl+v for itself
  *   Linux    text ctrl+shift+v  image ctrl+v
  *
@@ -480,7 +480,7 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
  * answers "images need a Claude coder" would be a hint that leads to a warning.
  */
 export function pasteHint({ platform = process.platform, images = false } = {}) {
-  const text = platform === "darwin" ? "⌘V" : platform === "win32" ? "ctrl+v" : "ctrl+shift+v";
+  const text = platform === "darwin" ? "⌘+V" : platform === "win32" ? "ctrl+v" : "ctrl+shift+v";
   if (!images) return `${text} to paste`;
   const image = platform === "win32" ? "alt+v" : "ctrl+v";
   return `${text} paste · ${image} image`;