@tiens.nguyen/gu-cli 1.0.791 → 1.0.793

package/gu-repl.mjs

@@ -110,6 +110,8 @@ import {
   workspaceScopeWarning,
   isLocalApiBase,
   modeRow,
+  nothingToAnswerWith,
+  NO_MODEL_LINES,
   resizeRepaintTarget,
   workspaceSyncQuestion,
   workspaceSyncLabel,
@@ -128,6 +130,7 @@ import {
 } from "./terminal-layout.mjs";
 import { completedFlush, splitLiveStream } from "./completed-flush.mjs";
 import { isScaffoldStep, isGroupableStep, stepGroupRows, relativizePaths } from "./step-group.mjs";
+import { clearLogsNoticeText } from "./clear-logs.mjs";
 import { discoverSkills, matchSkillCommand } from "./skills.mjs";
 import { appendNew, archivePathFor, archivedWorkspaceKey, markReset, seedArchive } from "./conversation-archive.mjs";
 import { addAllowRule, listServers as listMcpServers } from "./mcp-config.mjs";
@@ -664,6 +667,26 @@ if (!workerKey || !apiBase) {
         input: process.stdin,
         output: process.stdout,
       });
+      // Ctrl+C AND Ctrl+D MUST END THE RUN CLEANLY (task #333). readline swallows Ctrl+C in raw
+      // mode: with no listener it only pauses, the pending question never settles, and Node
+      // exits with "Warning: Detected unsettled top-level await" and a stack line — at the
+      // models menu of a first install. It also meant the "stopped during <step>" record
+      // (markInterruptedOnExit listens on the PROCESS) never fired for a Ctrl+C typed here.
+      let rl0Done = false;
+      const { stopFirstRun } = await import("./first-run-steps.mjs");
+      const endFirstRun = (reason) =>
+        stopFirstRun({
+          reason,
+          hasProcessListener: process.listenerCount("SIGINT") > 0,
+          emitSigint: () => process.emit("SIGINT"),
+          log: (t) => console.log(t),
+          exit: (code) => process.exit(code),
+          style: { yellow, dim },
+        });
+      rl0.on("SIGINT", () => endFirstRun("interrupt"));
+      rl0.on("close", () => {
+        if (!rl0Done) endFirstRun("eof");
+      });
       const ask0 = (q) =>
         new Promise((res) => rl0.question(accent(q), (a) => res(String(a || ""))));
       let typed = "";
@@ -681,7 +704,7 @@ if (!workerKey || !apiBase) {
         const {
           probeMachine, askMode, runClientExpertSetup, loadState, saveState,
         } = await import("./client-expert-run.mjs");
-        const { clientExpertAvailable, parseLicenseFlag, resolveFirstRunMode, promptForLicenseToken } =
+        const { clientExpertAvailable, parseLicenseFlag, resolveFirstRunMode, licenseUnverifiedLine, promptForLicenseToken } =
           await import("./client-expert-setup.mjs");
         const machine0 = await probeMachine();
         const gate0 = clientExpertAvailable({ workerEnvExists: false, ...machine0 });
@@ -700,7 +723,9 @@ if (!workerKey || !apiBase) {
           // (task #13). Format is checked first (no network), then offline signature, then the
           // live API. Empty Enter declines → the private default. Unreachable API still opens
           // the menu (soft licence: an outage never blocks a paid user).
+          const { setupPrompts: tokenPrompts } = await import("./setup-prompts.mjs");
           const pick = await promptForLicenseToken(ask0, licenseToken0, {
+            askSecret: tokenPrompts(rl0, { style: accent }).askSecret,
             validateOpts: {
               hostedBase: String(process.env.GU_TOKEN_API_BASE ?? "").trim() || DEFAULT_API_BASE,
             },
@@ -709,7 +734,7 @@ if (!workerKey || !apiBase) {
           if (pick.declined || !pick.token) {
             plan0 = resolveFirstRunMode({ licenseToken: "", expertAvailable: gate0.available });
           } else if (pick.result && pick.result.reason === "unverified") {
-            console.log(dim("\n  Couldn't reach the license server to confirm the token — showing the menu anyway."));
+            console.log(dim("\n  " + licenseUnverifiedLine(pick.result.detail)));
           }
         }
         let mode0;
@@ -781,6 +806,7 @@ if (!workerKey || !apiBase) {
           typed = (await ask0("  worker key (or Enter to sign in): ")).trim();
         }
       } finally {
+        rl0Done = true;
         rl0.close();
       }
       if (stopAfterSetup) {
@@ -891,6 +917,7 @@ const COMMANDS = [
   { name: "/use-presets", usage: "/use-presets [name]", desc: "pick a saved preset and apply it — shows what changes, backs up your setup, asks first" },
   { name: "/doctor", desc: "check every configured model ANSWERS — especially the embedder, which a turn only reaches after several steps" },
   { name: "/tokens", desc: "break down the last prompt sent to the coding model — how much of it was RAG" },
+  { name: "/clear-logs", desc: "show what gu's logs, RAG indexes and old API versions take on disk, then ask what to clear — the logs first" },
   { name: "/prices", usage: "/prices [update]", desc: "the price table and the cache table, and what the last turn and this session cost — \"update\" applies gu's newest published tables" },
   // ONE name, /new (user, #278). /reset and /clear still work (HIDDEN_COMMANDS) for habit and
   // for Claude Code users — not to be confused with `gu clear` in a shell, which wipes gu's state.
@@ -1462,6 +1489,11 @@ function applyClick({ row, col }) {
     void runPricesUpdate();
     return;
   }
+  if (logsRowTarget && row === updateRowAbs &&
+      col - 1 >= logsRowTarget.from && col - 1 < logsRowTarget.to) {
+    void runClearLogs();
+    return;
+  }
   if (agentsRowTarget && row === updateRowAbs &&
       col - 1 >= agentsRowTarget.from && col - 1 < agentsRowTarget.to) {
     void showOtherAgents(); // async now — it offers stop / switch-to (task #211)
@@ -1592,6 +1624,9 @@ let imageNoticeTimer = null;
 // its own model is unset, and choosing that model (/agent-model, /embed-model, /setup, or the
 // API seeding one) clears only that one.
 let agentMissing = false; // no agent model chosen → agent falls back to the coding model
+// NO MODEL AT ALL (#99): neither an agent model nor a coder — there is no server to send a
+// question to. Seeded from the startup payload; re-checked before a question is refused.
+let noModelAtAll = false;
 let embedMissing = false; // no embed model chosen → RAG is off until /embed-model picks one
 // One footer row; the two halves are independent so a model that IS set is never named.
 // ONE SHORT ROW EACH (#317): joined, they ran past 80 columns and were cut mid-word.
@@ -2270,7 +2305,7 @@ async function refreshCliToken() {
     let 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 });
+      ct.barNotice({ token: state.token, publicKeyB64: pk, mode, now: new Date(), attempted: Boolean(state.lastAttemptAt), site, why: state.lastAttemptWhy ?? "" });
     tokenNotice = noticeNow();
 
     const early = Boolean(tokenNotice) && !startupRenewDone;
@@ -2289,7 +2324,8 @@ async function refreshCliToken() {
       // A reply is only kept if it checks out here — a proxy's HTML page or another server's token
       // must not replace a good one.
       const fresh = r.ok && ct.verifyCliToken(r.token, pk).ok ? r.token : state.token;
-      state = { token: fresh, lastAttemptAt: now.toISOString() };
+      // WHY it failed is kept with the attempt, for the bar (#102).
+      state = { token: fresh, lastAttemptAt: now.toISOString(), lastAttemptWhy: r.ok ? "" : String(r.why ?? "") };
       await ct.writeState(dir, state).catch(() => {});
       tokenNotice = noticeNow();
     }
@@ -2680,6 +2716,9 @@ function zoneNotice(width) {
   if (tokenNotice?.text) items.push({ key: "token", paint: tokenNotice.urgent ? yellow : dim, text: tokenNotice.text });
   const agents = agentsIndicator(otherAgents);
   if (agents) items.push({ key: "agents", clickable: true, paint: accent, text: `${agents} running (click)` });
+  // LAST, so it is the first to give way on a narrow window: housekeeping, never urgent (#329).
+  const logs = clearLogsNoticeText(logsBytes);
+  if (logs) items.push({ key: "logs", clickable: true, paint: dim, text: logs });
   return noticeRow(items, { width, gutter: GUTTER });
 }
 
@@ -2760,6 +2799,7 @@ function frozenZone() {
   updateRowTarget = notice?.spans.update ?? null;
   agentsRowTarget = notice?.spans.agents ?? null;
   pricesRowTarget = notice?.spans.prices ?? null;
+  logsRowTarget = notice?.spans.logs ?? null;
   jumpSpan = notice?.spans.jump ?? null;
   return { ...zone, rows, statusRows: sep, noticeRow: Boolean(notice) };
 }
@@ -2829,7 +2869,7 @@ function paintBar() {
   // THE NOTICE ROW is the one directly above the separator (#318) — never the separator itself.
   const noticeAbs = zone.noticeRow ? sepAbs - 1 : 0;
   jumpRowTarget = scrolledBack() && jumpSpan ? { row: noticeAbs, ...jumpSpan } : null;
-  updateRowAbs = updateRowTarget || agentsRowTarget || pricesRowTarget ? noticeAbs : 0;
+  updateRowAbs = updateRowTarget || agentsRowTarget || pricesRowTarget || logsRowTarget ? noticeAbs : 0;
   // preserveCaret:false — the save slot holds the OUTPUT position (see regionUi), and the caret
   // is parked on the input line right after, so there is nothing to preserve here.
   ui(
@@ -2991,6 +3031,8 @@ let updateRowAbs = 0;
 let agentsRowTarget = null;
 // …and "new prices updated <date>" (#323).
 let pricesRowTarget = null;
+// …and "clear logs · 175 MB" (#329), shown only once the logs are worth a row.
+let logsRowTarget = null;
 // A terminal left with a scrolling region is a broken shell — a hard guarantee, like the
 // bracketed-paste and mouse-reporting teardowns.
 process.on("exit", () => {
@@ -7071,6 +7113,16 @@ function writePresetFile(pr, file, name, parsed) {
     const v = pr.validatePresetFile(JSON.stringify(out));
     console.log(GUTTER + `Preset "${name}" saved to ${file}:`);
     if (v.ok && v.full) for (const l of pr.fullPresetSummary(v.value, v.codingDefault)) console.log(GUTTER + dim(l));
+    // SAY WHAT IS ACTUALLY IN IT (reported 2026-10-02). This line used to read "It CONTAINS API
+    // keys" under a summary that said "no key" four times: the pasted text held key NAMES only, and
+    // the person carried the file to another machine believing the keys were inside.
+    const n = pr.presetKeyCounts(out);
+    if (!n.withValue) {
+      console.log(GUTTER + yellow("It contains NO API keys") + dim(n.nameOnly ? ` — only the names of ${n.nameOnly}. Using it will ask you to paste each one.` : "."));
+      console.log(GUTTER + dim("To carry keys: on the computer that HAS them run /open-presets and copy (keys included)."));
+      return;
+    }
+    if (n.nameOnly) console.log(GUTTER + yellow(`${n.nameOnly} of its keys ${n.nameOnly === 1 ? "is" : "are"} a name only`) + dim(" — their values are not in the file."));
   } else {
     writeFileSync(file, JSON.stringify(pr.buildPreset({ name, preset: parsed.preset, host: hostname() }), null, 2) + "\n", { mode: 0o600 });
     console.log(GUTTER + `Preset "${name}" saved to ${file}`);
@@ -7879,6 +7931,128 @@ async function runPricesUpdate() {
   }
 }
 
+// ---------------------------------------------------------------------------------------------
+// "CLEAR LOGS" (#329): a quiet item at the right of the notice row once gu's logs are worth a row,
+// and /clear-logs for where there is no mouse. A click deletes nothing: it MEASURES — the logs,
+// and beside them the two things that are actually big, the RAG indexes and the downloaded API
+// versions — shows that with a total, then asks about each. What each "clear" may and may not
+// touch is decided in clear-logs.mjs; this is the terminal half only.
+// ---------------------------------------------------------------------------------------------
+let logsBytes = 0; // what the notice shows; only the logs are measured for it (a handful of stats)
+let clearLogsBusy = false;
+
+async function refreshLogsSize() {
+  try {
+    const { surveyLogs } = await import("./clear-logs.mjs");
+    const was = clearLogsNoticeText(logsBytes);
+    logsBytes = (await surveyLogs()).bytes;
+    if (clearLogsNoticeText(logsBytes) !== was && barPinned()) paintBar();
+  } catch {
+    /* a housekeeping notice is never worth an error */
+  }
+}
+
+async function runClearLogs() {
+  // ONE AT A TIME, and never over a turn or another picker — reached from a fire-and-forget click
+  // (see showOtherAgents for what a second picker over the first one does).
+  if (clearLogsBusy || listPickerActive || approvalActive || following) return;
+  clearLogsBusy = true;
+  try {
+    const cl = await import("./clear-logs.mjs");
+    const { LOCAL_API_PORT } = await import("./client-expert-api.mjs");
+    const width = Math.max(20, process.stdout.columns || 80);
+    console.log("\n" + GUTTER + dim("Measuring ~/.gonext…"));
+    // Which API version is ANSWERING decides what "old" means — ask it, do not infer it.
+    const runningVersion = await fetch(`http://127.0.0.1:${LOCAL_API_PORT}/api/health`, { signal: AbortSignal.timeout(2000) })
+      .then((r) => r.json())
+      .then((j) => String(j?.version ?? ""))
+      .catch(() => "");
+    const survey = await cl.surveyDisk({ runningVersion });
+    console.log("");
+    for (const row of cl.summaryRows(survey, { width: width - GUTTER.length - 1 })) {
+      console.log(GUTTER + (row.startsWith("Total") ? bold(row) : row));
+    }
+    const freed = [];
+    // A question never wraps: at 80 columns over SSH the picker hint goes on a row of its own.
+    const question = (q) => {
+      const hint = `(${PICK_HINT}):`;
+      console.log("");
+      if (2 + q.length + 2 + hint.length < width) console.log(dim(`  ${q}  ${hint}`));
+      else console.log(dim(`  ${q}\n  ${hint}`));
+    };
+    const cancelled = () => {
+      console.log(dim(`  (stopped — nothing ${freed.length ? "further " : ""}removed)\n`));
+      paintBar();
+    };
+
+    // 1. THE LOGS — what was asked for, so Yes is the first row.
+    if (survey.logs.bytes > 0) {
+      question(`Clear the logs — ${cl.humanSize(survey.logs.bytes)}?`);
+      const go = await pickFromList(["Yes — clear the logs" + dim("  · the worker and the API keep running"), "No"], 0);
+      if (go < 0) return cancelled();
+      if (go === 0) {
+        const r = await cl.clearLogs(survey.logs);
+        freed.push({ what: "logs", ...r });
+        console.log(GUTTER + accent(`✓ logs cleared — ${cl.humanSize(r.freed)} freed`) +
+          (r.failed.length ? yellow(`  (still in use, left alone: ${r.failed.join(", ")})`) : ""));
+      } else {
+        console.log(GUTTER + dim("logs kept"));
+      }
+    } else {
+      console.log("\n" + GUTTER + dim("No logs to clear."));
+    }
+
+    // 2. RAG — costs a re-index, so No is the first row.
+    if (survey.rag.indexes.length) {
+      const gone = survey.rag.indexes.filter((i) => i.missing);
+      const goneBytes = gone.reduce((n, i) => n + i.bytes, 0);
+      const choices = [{ id: "no", label: "No — keep them" }];
+      if (gone.length && gone.length < survey.rag.indexes.length) {
+        choices.push({ id: "gone", label: `Only the ${gone.length} whose folder no longer exists — ${cl.humanSize(goneBytes)}` });
+      }
+      choices.push({ id: "all", label: `Yes — all ${survey.rag.indexes.length}` + dim("  · a folder is indexed again when it is next used") });
+      question(`Also clear the RAG indexes — ${cl.humanSize(survey.rag.bytes)}?`);
+      const pick = await pickFromList(choices.map((c) => c.label), 0);
+      if (pick < 0) return cancelled();
+      if (choices[pick].id !== "no") {
+        const r = await cl.clearRagIndexes(choices[pick].id === "gone" ? gone : survey.rag.indexes);
+        freed.push({ what: "rag", ...r });
+        console.log(GUTTER + accent(`✓ ${r.removed} RAG index${r.removed === 1 ? "" : "es"} cleared — ${cl.humanSize(r.freed)} freed`) +
+          (r.failed.length ? yellow(`  (could not remove: ${r.failed.join(", ")})`) : ""));
+      } else {
+        console.log(GUTTER + dim("RAG indexes kept"));
+      }
+    }
+
+    // 3. THE API — only ever the OLDER versions; the one in use is not on offer.
+    if (survey.api.old.length) {
+      const n = survey.api.old.length;
+      question(`Also remove the ${n} older API version${n === 1 ? "" : "s"} — ${cl.humanSize(survey.api.oldBytes)}?`);
+      const go = await pickFromList(["No — keep them", `Yes — remove the ${n} older one${n === 1 ? "" : "s"}` +
+        dim(survey.api.inUse ? `  · ${survey.api.inUse}, the one in use, stays` : "")], 0);
+      if (go < 0) return cancelled();
+      if (go === 1) {
+        console.log(GUTTER + dim("Removing…"));
+        const r = await cl.clearOldApiVersions(survey.api.old);
+        freed.push({ what: "api", ...r });
+        console.log(GUTTER + accent(`✓ ${r.removed} older API version${r.removed === 1 ? "" : "s"} removed — ${cl.humanSize(r.freed)} freed`) +
+          (r.failed.length ? yellow(`  (could not remove: ${r.failed.join(", ")})`) : ""));
+      } else {
+        console.log(GUTTER + dim("older API versions kept"));
+      }
+    }
+
+    const total = freed.reduce((n, f) => n + f.freed, 0);
+    console.log("\n" + GUTTER + (freed.length ? bold(`${cl.humanSize(total)} freed in all.`) : dim("Nothing removed.")) + "\n");
+  } catch (e) {
+    console.log(GUTTER + red(`couldn't finish — ${e?.message ?? e}`) + "\n");
+  } finally {
+    clearLogsBusy = false;
+    await refreshLogsSize();
+    if (barPinned()) paintBar();
+  }
+}
+
 /**
  * `/embed-model` — switch the RAG embedder, the embed server, or the embed key (task #169).
  *
@@ -10308,8 +10482,13 @@ async function tryStartLocalApi() {
     );
     const version = versions.pop();
     if (!version) return false; // nothing installed — setup never got that far
+    const portBefore = ce.LOCAL_API_PORT;
     await ce.startLocalApi({ apiDir: join(base, version) });
-    return (await ce.waitForApi({ timeoutMs: 30_000 })).ok;
+    const up = (await ce.waitForApi({ timeoutMs: 30_000 })).ok;
+    // The port can move here (#337: the saved one now belongs to another program). worker.env
+    // was re-pointed; THIS terminal still holds the old address until it reads the file again.
+    if (ce.LOCAL_API_PORT !== portBefore) reloadWorkerEnv();
+    return up;
   } catch {
     return false;
   }
@@ -10641,6 +10820,22 @@ async function runAgentTurn(history, { attachJobId = "", ownJob = false } = {})
   // from the gu service with it. Asked for HERE, before anything is sent, with the steps — rather
   // than letting the turn fail and leaving the user to decode why.
   if (!skipAsk && !(await ensureTokenForTurn())) return;
+  // NOTHING TO ANSWER WITH (#99). On an account with no models at all the question used to be
+  // sent, sat at "queued — waiting for the worker…", and ended in "✗ Job not found." — the job
+  // had no model server in it, so nothing could read or claim it. Say what is missing instead.
+  // Asked again first: /model or /agent-model may have set one since gu started.
+  if (!skipAsk && noModelAtAll) {
+    try {
+      noModelAtAll = nothingToAnswerWith((await fetchAgentPayload([{ role: "user", content: "." }]))?.payload);
+    } catch {
+      /* cannot ask → keep what startup saw */
+    }
+    if (noModelAtAll) {
+      for (const l of NO_MODEL_LINES) console.log(GUTTER + (l === NO_MODEL_LINES[0] ? red("✗ ") + l : dim("  " + l)));
+      console.log("");
+      return;
+    }
+  }
   inputVisible = false; // the frozen zone shows an empty prompt for the duration (#141)
   // Something on screen from the FIRST moment (task #140): Enter has just wiped the bar, and
   // the next thing to draw itself is the turn's ticker — which stays silent until the daemon
@@ -12129,6 +12324,7 @@ async function main() {
         // private (task #13); empty Enter declines to the private default.
         const { DEFAULT_API_BASE } = await import("./device-login.mjs");
         const pick1 = await promptForLicenseToken(ask, licenseToken1, {
+          askSecret,
           validateOpts: {
             hostedBase: String(process.env.GU_TOKEN_API_BASE ?? "").trim() || DEFAULT_API_BASE,
           },
@@ -12358,6 +12554,7 @@ async function main() {
     // the local setup answers — OR them in, never clear a local "missing" on a maybe, because
     // private mode's local API can itself be unconfigured.
     if (p.agentMissing === true) agentMissing = true;
+    noModelAtAll = nothingToAnswerWith(p);
     if (p.ragEnabled !== true) embedMissing = true;
     // A RESTORED PICK MUST STILL EXIST. The stored id names a model on the box this folder was
     // last pointed at — and the box can change (`/model` → change the Ollama server), a model
@@ -12451,7 +12648,14 @@ async function main() {
         // Task #136/#154: mode changes WHERE things run — too important to leave implicit.
         // The precedence lives in modeRow() with its tests; see the note there.
         ...(() => {
-          const m = modeRow({ clientExpert: isClientExpert(), clientMode: clientModeBanner });
+          const m = modeRow({
+            clientExpert: isClientExpert(),
+            clientMode: clientModeBanner,
+            modelUrls: [p.agentBaseURL],
+            // The coder IN USE in this folder, not the account default (the raw payload field
+            // is the default only — key-choice-regression.test.mjs).
+            coderWhere: activeCoderWhere,
+          });
           if (!m) return [];
           const name = m.label === "client expert" ? accent(m.label + " ") : m.label + " ";
           return [lbl("mode") + name + dim(m.detail)];
@@ -12548,6 +12752,8 @@ async function main() {
                 confirm: (q, defYes) => askYesNo(q, defYes),
                 // A client installs ONLY the framework — never mlx-lm/hf.
                 modelHost: clientModeBanner ? false : undefined,
+                // The yes two lines up IS the answer — do not ask the same thing again (#333).
+                agreed: ["agentLibs"],
               });
               // The worker reads worker.env ONCE at startup, so a daemon that is already
               // running still has the OLD python — the packages would look "not installed"
@@ -12844,6 +13050,8 @@ async function main() {
   // #323: gu's newest published price + cache tables — same cadence, same silent failure.
   void refreshPriceUpdate();
   setInterval(() => void refreshPriceUpdate(), UPDATE_CHECK_MS).unref();
+  void refreshLogsSize();
+  setInterval(() => void refreshLogsSize(), UPDATE_CHECK_MS).unref();
   // The gu token (#232): same arrangement — background, never delays the prompt, unref'd.
   startupTokenRefresh = refreshCliToken();
   setInterval(() => void refreshCliToken(), TOKEN_TICK_MS).unref();
@@ -13304,6 +13512,10 @@ async function main() {
       await runPricesCommand(line);
       continue;
     }
+    if (line === "/clear-logs") {
+      await runClearLogs();
+      continue;
+    }
     if (line === "/tokens") {
       // Task #142: WHERE the last request's prompt went. The bar answers "how much is RAG";
       // this answers "and what displaced it", which is the part that tells you whether RAG is

package/install-path.mjs

@@ -56,11 +56,33 @@ if (isEntryPoint) {
     main();
   } catch (e) {
     // A postinstall that throws uninstalls the package. Report, swallow, succeed.
-    console.log(`gu-cli: PATH setup skipped (${e.message}) — see \`gu-cli doctor\` if \`gu\` is not found.`);
+    console.log(`gu-cli: PATH setup skipped (${e.message}) — run \`gu-cli fix-path\` if \`gu\` is not found.`);
   }
   process.exit(0);
 }
 
+/**
+ * The npm global prefix this package is installed under, from where its own files are — or "".
+ *
+ * For `gu-cli fix-path` (task #333): the same PATH repair as this postinstall, WITHOUT npm
+ * running it. npm 11 already prints "install scripts not yet covered by allowScripts" for this
+ * package on every install; it still runs the script today (checked on 11.19.1), but the day it
+ * stops, a custom-prefix user is back to "gu: command not found" with nothing to run. A global
+ * install lives at <prefix>/lib/node_modules/@tiens.nguyen/gu-cli; anything else (a checkout,
+ * `npm link`, a project's node_modules) is not one, and gets no PATH edit.
+ */
+export function globalPrefixOf(packageDir) {
+  const parts = resolve(String(packageDir ?? "")).split("/");
+  const n = parts.length;
+  if (n < 5 || parts[n - 3] !== "node_modules" || parts[n - 4] !== "lib") return "";
+  if (!parts[n - 2].startsWith("@")) return "";
+  // A project-local install is <project>/node_modules/… — never <x>/lib/node_modules, but a
+  // nested one could be; a prefix inside another node_modules tree is not a global prefix.
+  const prefix = parts.slice(0, n - 4);
+  if (prefix.includes("node_modules")) return "";
+  return prefix.join("/") || "/";
+}
+
 function main() {
   if (platform() === "win32") return;                 // registry PATH + PowerShell alias: not here
   if (process.env.CI) return;                          // no user shell to help in CI

package/model-doctor.mjs

@@ -130,6 +130,17 @@ export function isExternallyManaged(output) {
   return /externally[\s-]?managed/i.test(String(output ?? ""));
 }
 
+/**
+ * Is there no pip on this python at all? (task #333)
+ *
+ * A stock Ubuntu 24.04 ships python3 WITHOUT pip (python3-pip is a separate package), so the
+ * first install said "/usr/bin/python3: No module named pip" and gave up — although
+ * python3-venv was installed and a venv brings its own pip. Same remedy as PEP 668: a venv.
+ */
+export function isPipMissing(output) {
+  return /No module named pip\b/i.test(String(output ?? ""));
+}
+
 /** Run pip once. Resolves { code, err } — never rejects, so the caller owns the policy. */
 function runPip(python, pkgs, extraArgs = []) {
   return new Promise((resolve) => {
@@ -190,11 +201,16 @@ async function pipInstall(pkgs, log) {
   log(`  installing ${pkgs.join(" ")} … (pip, this can take a minute)`);
   let r = await runPip(python3Bin(), pkgs);
   if (r.code === 0) return;
-  if (!isExternallyManaged(r.err)) {
+  const noPip = isPipMissing(r.err);
+  if (!noPip && !isExternallyManaged(r.err)) {
     throw new Error(`pip install ${pkgs.join(" ")} exited ${r.code}`);
   }
 
-  log("  this python is managed by your OS (PEP 668) — it will not accept packages directly.");
+  log(
+    noPip
+      ? "  this python has no pip — using a private virtualenv, which brings its own."
+      : "  this python is managed by your OS (PEP 668) — it will not accept packages directly."
+  );
   const venvPy = await ensureVenv(log);
   if (venvPy) {
     r = await runPip(venvPy, pkgs);
@@ -208,6 +224,13 @@ async function pipInstall(pkgs, log) {
     }
   }
 
+  // Without pip AND without venv nothing here can install anything; --break-system-packages
+  // would only fail again with the same "No module named pip". Say what to install instead.
+  if (noPip) {
+    throw new Error(
+      "this python has no pip and no venv module — on Debian/Ubuntu: sudo apt install -y python3-venv, then gu doctor"
+    );
+  }
   log("  falling back to --break-system-packages (no virtualenv available)");
   r = await runPip(python3Bin(), pkgs, ["--break-system-packages"]);
   if (r.code === 0) return;
@@ -1246,7 +1269,13 @@ export async function ensureClaudeSdk({ log, confirm }) {
   return (await pyHasModule("anthropic")) ? "installed" : "failed";
 }
 
-export async function ensureAgentDeps({ log, confirm, modelHost = canHostMlxModels() }) {
+/**
+ * `agreed` names packages the caller has ALREADY asked about (task #333): `gu` asks "Install the
+ * agent framework now?" and then called this, which asked "Install the agent framework
+ * (smolagents + openai) — required to run the agent?" — the same question twice in a row on
+ * every first install. A yes that was just given is not asked for again.
+ */
+export async function ensureAgentDeps({ log, confirm, modelHost = canHostMlxModels(), agreed = [] }) {
   const out = {};
   log("");
   log("  Checking the agent's dependencies…");
@@ -1264,7 +1293,7 @@ export async function ensureAgentDeps({ log, confirm, modelHost = canHostMlxMode
       out[key] = "present";
       return;
     }
-    if (!(await confirm(question, true))) {
+    if (!agreed.includes(key) && !(await confirm(question, true))) {
       out[key] = "skipped";
       log(`  Skipped ${pkgs.join(" ")} — install later: ${python3Bin()} -m pip install -U ${pkgs.join(" ")}`);
       return;

package/node-version.mjs

@@ -17,7 +17,7 @@ export const MIN_NODE_MAJOR = 18;
 /** The message for a too-old runtime, or "" when this one is fine. Pure, so it is testable. */
 export function nodeVersionProblem(version = process.version) {
   const major = Number.parseInt(String(version).replace(/^v/, "").split(".")[0], 10);
-  if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR) return "";
+  if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR) {return "";}
   return (
     `gu needs Node ${MIN_NODE_MAJOR} or newer — this is ${version}.\n` +
     `  Node ${major} has no global fetch, which the setup and update paths rely on.\n` +
@@ -30,10 +30,58 @@ export function nodeVersionProblem(version = process.version) {
   );
 }
 
+/**
+ * LOCAL MODE NEEDS MORE THAN GU DOES (task #333). The Local API ships the mongodb 7 driver, whose
+ * floor is Node 20.19 — and setup loads that driver IN THIS PROCESS to seed the database, then
+ * starts the API with this same node. On Node 18 the first sign was "Could not prepare the
+ * database: crypto is not defined", halfway through a first install, after MongoDB and the API
+ * were already in place. Found on a stock Ubuntu 24.04, whose own `nodejs` package is 18.19.
+ *
+ * Kept apart from MIN_NODE_MAJOR on purpose: the CLI itself (Cloud mode) still runs on 18.
+ */
+export const LOCAL_API_MIN_NODE = "20.19.0";
+
+/** True when `version` is at least `min` (both "x.y.z", a leading v allowed). */
+export function nodeAtLeast(version, min) {
+  const parts = (v) => String(v).replace(/^v/, "").split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const a = parts(version);
+  const b = parts(min);
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) {return (a[i] ?? 0) > (b[i] ?? 0);}
+  }
+  return true;
+}
+
+/** Why Local mode cannot run on this node, with what to do — or "" when it can. Pure. */
+export function localModeNodeProblem(version = process.version, platform = process.platform) {
+  if (nodeAtLeast(version, LOCAL_API_MIN_NODE)) {return "";}
+  const how =
+    platform === "win32"
+      ? ["  winget install OpenJS.NodeJS.LTS      (or: nvm install lts with nvm-windows)"]
+      : platform === "darwin"
+        ? ["  brew install node                     (or: nvm install --lts)"]
+        : [
+            "  nvm install --lts && nvm alias default lts/*",
+            "  or NodeSource:",
+            "    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -",
+            "    sudo apt install -y nodejs",
+          ];
+  return (
+    `Local mode needs Node ${LOCAL_API_MIN_NODE} or newer — this is ${version}.\n` +
+    "  Its API uses the MongoDB 7 driver, which does not run on older Node.\n" +
+    (platform === "linux" ? "  (Ubuntu 24.04's own nodejs package is 18.)\n" : "") +
+    "\n" +
+    how.join("\n") +
+    "\n\n" +
+    "  Then reinstall gu with that Node: npm i -g @tiens.nguyen/gu-cli\n" +
+    "  Nothing was installed or changed."
+  );
+}
+
 /** Print the problem and exit, or return quietly. */
 export function requireSupportedNode() {
   const problem = nodeVersionProblem();
-  if (!problem) return;
+  if (!problem) {return;}
   // console.error, not the REPL's own writer: this runs before any of that exists.
   console.error("\n" + problem + "\n");
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.791",
+  "version": "1.0.793",
   "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",
@@ -77,6 +77,7 @@
     "poll-errors.mjs",
     "node-version.mjs",
     "clear-state.mjs",
+    "clear-logs.mjs",
     "platform-tools.mjs",
     "job-pools.mjs",
     "agent-stop.mjs",