@tiens.nguyen/gu-cli 1.0.792 → 1.0.793

package/clear-state.mjs

@@ -30,6 +30,10 @@ export const STATE_ITEMS = [
     what: "the account link (worker key + API base)", cost: "you sign in again" },
   { path: "client-expert.json", group: "identity",
     what: "Local-mode setup progress and the chosen mode", cost: "setup starts over" },
+  // With the setup it belongs to (#337): a leftover port file would send a fresh setup to a
+  // port chosen for a clash that may no longer exist.
+  { path: "local-api.port", group: "identity",
+    what: "the port the local API moved to (4100 was taken)", cost: "setup picks again" },
   { path: "instance", group: "identity",
     what: "this machine's id", cost: "it gets a new one" },
   { path: "cli-token.json", group: "identity",

package/cli-token.mjs

@@ -328,6 +328,10 @@ export async function readState(dir) {
     return {
       token: typeof s.token === "string" ? s.token : "",
       lastAttemptAt: isIso(s.lastAttemptAt) ? s.lastAttemptAt : null,
+      // Why the last automatic fetch failed (absent when it worked) — so the bar can tell "the gu
+      // service had a problem" from "this machine is not signed in" (#102).
+      // Present only when the last try failed: the shape is unchanged for a state that never did.
+      ...(typeof s.lastAttemptWhy === "string" && s.lastAttemptWhy ? { lastAttemptWhy: s.lastAttemptWhy } : {}),
     };
   } catch {
     return { token: "", lastAttemptAt: null };
@@ -339,7 +343,7 @@ export async function writeState(dir, state) {
   const file = join(dir, STATE_FILE);
   await mkdir(dirname(file), { recursive: true });
   const tmp = `${file}.${process.pid}.tmp`;
-  await writeFile(tmp, JSON.stringify({ token: state.token ?? "", lastAttemptAt: state.lastAttemptAt ?? null }, null, 2) + "\n", {
+  await writeFile(tmp, JSON.stringify({ token: state.token ?? "", lastAttemptAt: state.lastAttemptAt ?? null, ...(state.lastAttemptWhy ? { lastAttemptWhy: state.lastAttemptWhy } : {}) }, null, 2) + "\n", {
     encoding: "utf8",
     mode: 0o600,
   });
@@ -450,7 +454,7 @@ export function shortDate(iso) {
  *
  * Never the word "licence". Returns null when the feature is off (no public key).
  */
-export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempted = false, site = DEFAULT_SITE }) {
+export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempted = false, site = DEFAULT_SITE, why = "" }) {
   if (!publicKeyB64) return null;
   const host = site.replace(/^https?:\/\//, "");
   // Shown without the scheme — shorter on a narrow bar, and still what a person types.
@@ -506,6 +510,12 @@ export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempt
     return null;
   } else {
     // Hosted client, its automatic fetch has failed: the bar is the only place this is said.
+    //
+    // SAY WHICH FAILURE (#102). "gu isn't signed in · run gu login" was shown on a machine that WAS
+    // signed in — its worker key worked and turns ran — because the gu service answered HTTP 502 to
+    // the token fetch. `gu login` does not fix a server error; the next automatic try does.
+    const trouble = fetchTrouble(why);
+    if (trouble) return { kind: "unchecked", urgent: false, text: `plan not checked — ${trouble} · gu will try again` };
     return { kind: "missing", urgent: false, text: "gu isn't signed in · run gu login" };
   }
 
@@ -515,6 +525,19 @@ export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempt
     : { kind: "stale", urgent: false, text: "gu token is old · run gu login" };
 }
 
+/**
+ * A failed token fetch that is the SERVICE's or the network's doing, in words — or "" when it is
+ * this machine's (a refused key: http-401/403), or unknown. `why` is renewToken's.
+ */
+export function fetchTrouble(why) {
+  const w = String(why ?? "");
+  const http = /^http-(\d{3})$/.exec(w);
+  if (http) return Number(http[1]) >= 500 ? `the gu service had an error (HTTP ${http[1]})` : "";
+  if (w === "network" || w === "timeout" || w === "no-api") return "the gu service could not be reached";
+  if (w === "bad-response") return "the gu service sent an unexpected answer";
+  return "";
+}
+
 /** "Free plan" / "Pro plan" — the name a person uses. */
 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. */

package/client-expert-api.mjs

@@ -27,9 +27,64 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-/** Where the local API listens. 4100 keeps clear of the hosted API and of Vite's 5173. */
-export const LOCAL_API_PORT = Number(process.env.GONEXT_LOCAL_API_PORT ?? "4100") || 4100;
-export const LOCAL_API_BASE = `http://127.0.0.1:${LOCAL_API_PORT}`;
+/** Where the local API listens by default. 4100 keeps clear of the hosted API and of Vite's 5173. */
+export const DEFAULT_LOCAL_API_PORT = 4100;
+/** The port setup had to move to, when 4100 belonged to another program (task #337). */
+export const API_PORT_FILE = join(homedir(), ".gonext", "local-api.port");
+
+const validPort = (v) => {
+  const n = Number.parseInt(String(v ?? "").trim(), 10);
+  return Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
+};
+
+/**
+ * WHICH PORT THE LOCAL API USES, and why (task #337).
+ *
+ *   env   — GONEXT_LOCAL_API_PORT: someone chose it; gu never moves away from it on its own.
+ *   saved — ~/.gonext/local-api.port: 4100 was taken by ANOTHER PROGRAM when the API was first
+ *           started, and gu moved. Every later process — `gu`, `gu-cli api …`, the worker's
+ *           terminal — reads the same file, so they all follow the move.
+ *   default — 4100. A machine where 4100 was free has no file and behaves exactly as before.
+ *
+ * Pure: the file's text is passed in.
+ */
+export function resolveApiPort({ env = process.env, saved = "" } = {}) {
+  const fromEnv = validPort(env.GONEXT_LOCAL_API_PORT);
+  if (fromEnv) return { port: fromEnv, source: "env" };
+  const fromFile = validPort(saved);
+  if (fromFile) return { port: fromFile, source: "saved" };
+  return { port: DEFAULT_LOCAL_API_PORT, source: "default" };
+}
+
+function readSavedPort() {
+  try {
+    return readFileSync(API_PORT_FILE, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * LIVE BINDINGS, not constants: thirty readers across gu take the port from these two names. When
+ * setup moves the API in THIS process they must all see the new port at once — an ES module's
+ * exported `let` does exactly that for every importer, and a default parameter reads it at call
+ * time. Other processes get it from the file when they start.
+ */
+export let LOCAL_API_PORT = resolveApiPort({ saved: readSavedPort() }).port;
+export let LOCAL_API_BASE = `http://127.0.0.1:${LOCAL_API_PORT}`;
+
+/** Use `port` from now on in this process (and, with save, in every later one). */
+export async function useApiPort(port, { save = true } = {}) {
+  const n = validPort(port);
+  if (!n) throw new Error(`not a port: ${port}`);
+  LOCAL_API_PORT = n;
+  LOCAL_API_BASE = `http://127.0.0.1:${n}`;
+  if (save) {
+    await mkdir(join(homedir(), ".gonext"), { recursive: true });
+    await writeFile(API_PORT_FILE, `${n}\n`, "utf8");
+  }
+  return n;
+}
 export const LOCAL_MONGO_URI = process.env.GONEXT_LOCAL_MONGO_URI || "mongodb://127.0.0.1:27017";
 export const LOCAL_DB_NAME = process.env.GONEXT_LOCAL_DB_NAME || "gu";
 
@@ -189,7 +244,39 @@ export function npmInstallCommand(platform = process.platform) {
   };
 }
 
-export function installApiDeps(apiDir, { onLine } = {}) {
+/**
+ * A DROPPED CONNECTION IS NOT A FAILED INSTALL (task #333). The Windows 11 test box fetched
+ * single packages in 30 s and then got "npm error network read ECONNRESET" — twice in a row, on
+ * the first install, which then stopped with "Run `gu` again". A rerun went through. npm keeps
+ * what it already downloaded, so trying again in place is cheap and is what the user would do.
+ * Only NETWORK failures are retried: a real error (a bad package, a full disk) fails the same way
+ * every time, and three copies of it would only bury it.
+ */
+export function isNetworkNpmError(text) {
+  return /\b(ECONNRESET|ETIMEDOUT|ECONNREFUSED|EAI_AGAIN|ENOTFOUND|ENETUNREACH|EPIPE|ERR_SOCKET_TIMEOUT)\b|socket hang up|network (read|request)/i.test(
+    String(text ?? "")
+  );
+}
+
+/** npm on Windows exits with a NEGATIVE errno that arrives unsigned: 4294963219 is -4077. */
+export function signedExitCode(code) {
+  return typeof code === "number" && code > 0x7fffffff ? code - 0x100000000 : code;
+}
+
+export const API_DEPS_ATTEMPTS = 3;
+
+export async function installApiDeps(apiDir, { onLine, attempts = API_DEPS_ATTEMPTS, once = installApiDepsOnce } = {}) {
+  for (let i = 1; ; i++) {
+    try {
+      return await once(apiDir, { onLine });
+    } catch (e) {
+      if (i >= attempts || !isNetworkNpmError(`${e?.output ?? ""}\n${e?.message ?? ""}`)) throw e;
+      onLine?.(`network error — trying again (${i + 1} of ${attempts}); what was downloaded is kept`);
+    }
+  }
+}
+
+function installApiDepsOnce(apiDir, { onLine } = {}) {
   const { cmd, args, shell, line } = npmInstallCommand();
   return new Promise((resolve, reject) => {
     let child;
@@ -212,7 +299,11 @@ export function installApiDeps(apiDir, { onLine } = {}) {
     });
     child.on("error", (e) => reject(new Error(`could not run ${cmd} in ${apiDir}: ${e.message}`)));
     child.on("exit", (code) =>
-      code === 0 ? resolve() : reject(new Error(`npm install failed (exit ${code}) ${err.slice(-400)}`))
+      code === 0
+        ? resolve()
+        : // `output` keeps ALL of stderr: the 400-char tail in the message had already lost the
+          // "ECONNRESET" line on the real Windows failure, so the retry never saw it.
+          reject(Object.assign(new Error(`npm install failed (exit ${signedExitCode(code)}) ${err.slice(-400)}`), { output: err }))
     );
   });
 }
@@ -257,6 +348,150 @@ export async function seedDatabase({
   }
 }
 
+/**
+ * WHO IS ON A PORT → "free" | "gu" | "other" (task #337).
+ *
+ * "gu" is anything that answers /api/health the way this API does — usable or not, this home's
+ * or another's: it is our program and moving away from it would start a second one. "other" is a
+ * port that accepts a connection and is not that: someone else's server. Only "other" is a
+ * reason to move.
+ */
+export async function whoHoldsPort(port, { fetchImpl = fetch, connects = tcpConnects } = {}) {
+  try {
+    const res = await fetchImpl(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(2500) });
+    const body = await res.json().catch(() => null);
+    if (body && typeof body === "object" && ("dataBackend" in body || "persistence" in body)) return "gu";
+    return "other";
+  } catch {
+    return (await connects(port)) ? "other" : "free";
+  }
+}
+
+/** Does anything accept a TCP connection on 127.0.0.1:port? */
+async function tcpConnects(port, timeoutMs = 1500) {
+  const net = await import("node:net");
+  return new Promise((resolve) => {
+    const sock = net.connect({ host: "127.0.0.1", port });
+    const done = (v) => {
+      sock.destroy();
+      resolve(v);
+    };
+    sock.setTimeout(timeoutMs, () => done(false));
+    sock.once("connect", () => done(true));
+    sock.once("error", () => done(false));
+  });
+}
+
+/** Can a server be opened on `port` right now? The only honest test of "free". */
+async function canListen(port) {
+  const net = await import("node:net");
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(false));
+    srv.listen(port, () => srv.close(() => resolve(true)));
+  });
+}
+
+/** How many ports after the taken one are tried before asking the system for any free one. */
+export const API_PORT_TRIES = 10;
+
+/** The first port after `taken` that a server can open — else one the system picks. */
+export async function findFreePort(taken, { isFree = canListen, tries = API_PORT_TRIES, anyFree = systemFreePort } = {}) {
+  for (let p = taken + 1; p <= taken + tries && p < 65536; p++) {
+    if (await isFree(p)) return p;
+  }
+  return anyFree();
+}
+
+async function systemFreePort() {
+  const net = await import("node:net");
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.once("error", reject);
+    srv.listen(0, () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * What to do about the port before starting the API. Pure.
+ *   use    — it is free, or gu's own API is already there.
+ *   move   — another program has it and nobody insisted on this port.
+ *   refuse — another program has it and GONEXT_LOCAL_API_PORT asked for exactly this port:
+ *            an explicit choice is not overridden, it is reported.
+ */
+export function portDecision({ holder, source }) {
+  if (holder !== "other") return "use";
+  return source === "env" ? "refuse" : "move";
+}
+
+/**
+ * MAKE SURE THE API HAS A PORT IT CAN OPEN, moving off one that belongs to another program.
+ *
+ * The first install used to end in "The API started but is not usable: not up yet" when 4100
+ * was somebody else's — the API could not bind, and nothing said why. Now gu says which program
+ * has the port, takes the next free one, REMEMBERS it (API_PORT_FILE), and re-points worker.env
+ * when there is one, so the terminal and the worker follow.
+ *
+ * → { moved, port, from?, holder? }. Never throws: a port problem must not hide the real error.
+ */
+export async function settleApiPort({
+  log = (l) => console.log(l),
+  env = process.env,
+  holds = whoHoldsPort,
+  nameOf = null,
+  freePort = findFreePort,
+} = {}) {
+  const from = LOCAL_API_PORT;
+  try {
+    const source = resolveApiPort({ env, saved: readSavedPort() }).source;
+    const holder = await holds(from);
+    const action = portDecision({ holder, source });
+    if (action === "use") return { moved: false, port: from };
+    // The program's name when the system gives it; on Windows it often does not (seen live),
+    // and "another program (another program)" is not a sentence.
+    const name = (await (nameOf ?? (await import("./mongo-native.mjs")).portHolder)(from).catch(() => null)) || "";
+    const who = name || "another program";
+    if (action === "refuse") {
+      log(`  Port ${from} (set by GONEXT_LOCAL_API_PORT) is in use by ${who}.`);
+      log("  Stop that program, or choose another port, then run gu again.");
+      return { moved: false, port: from, holder: who, refused: true };
+    }
+    const to = await freePort(from);
+    await useApiPort(to);
+    log(`  Port ${from} is used by another program${name ? ` (${name})` : ""} — gu's API uses ${to}.`);
+    // An install that was already working: its terminal and its worker read worker.env. The
+    // worker read it ONCE, at start, so it is restarted — or it would poll the old port forever.
+    if (await repointWorkerEnv(from, to)) {
+      try {
+        const ctl = await import("./daemon-control.mjs");
+        if ((await ctl.daemonStatus()).running) {
+          await ctl.stopDaemon();
+          await ctl.startDaemon();
+          log("  · restarted the background worker so it uses the new port");
+        }
+      } catch {
+        log("  · restart the background worker to pick up the new port: gu-cli restart");
+      }
+    }
+    return { moved: true, port: to, from, holder: who };
+  } catch {
+    return { moved: false, port: from };
+  }
+}
+
+/** worker.env pointed at the local API on the old port → point it at the new one. */
+async function repointWorkerEnv(from, to) {
+  const path = join(GONEXT_DIR, "worker.env");
+  const text = await readFile(path, "utf8").catch(() => "");
+  const re = new RegExp(`^(GONEXT_API_BASE=https?://(?:127\\.0\\.0\\.1|localhost)):${from}\\b`, "m");
+  if (!re.test(text)) return false;
+  await writeFile(path, text.replace(re, `$1:${to}`));
+  return true;
+}
+
 /**
  * Start the API so it OUTLIVES this terminal — including an SSH session.
  *
@@ -271,8 +506,16 @@ export async function startLocalApi({
   port = LOCAL_API_PORT,
   mongoUri = localMongoUri(),
   dbName = LOCAL_DB_NAME,
+  log = (l) => console.log(l),
 } = {}) {
   await mkdir(GONEXT_DIR, { recursive: true });
+  // Every start goes through here — setup, `gu-cli api start|restart|upgrade`, doctor, the
+  // terminal's own restart — so this is where a port taken by another program is noticed.
+  // A caller that named a port keeps it.
+  if (port === LOCAL_API_PORT) {
+    const settled = await settleApiPort({ log });
+    port = settled.port;
+  }
   const res = await spawnSurviving({
     cmd: process.execPath,
     args: ["index.js"],
@@ -286,7 +529,7 @@ export async function startLocalApi({
   // we spawned. Recorded after the server is up, by the caller's waitForApi.
   const pid = res.pid ?? null;
   if (pid) await writeFile(API_PID_FILE, String(pid) + "\n").catch(() => {});
-  return { pid, how: res.how };
+  return { pid, how: res.how, port };
 }
 
 /** Record whoever is serving the port, so `api stop` has something to stop. */

package/client-expert-run.mjs

@@ -20,11 +20,13 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { createHash } from "node:crypto";
+import { localModeNodeProblem } from "./node-version.mjs";
 import {
   apiDepsInstalled,
   installApiDeps,
   seedDatabase,
   startLocalApi,
+  settleApiPort,
   waitForApi,
   probeLocalApi,
   writeWorkerEnv,
@@ -515,7 +517,7 @@ export async function preflightLocalMongo({
   log("\n  " + red("gu: MongoDB is not answering") + dim(` at ${host}:${port}`) +
     red(mongo.installed || mongo.silentPort || !local ? "." : " — it is not installed on this machine."));
   log(dim("  Local mode keeps your conversations, models and keys in that database, so"));
-  log(dim("  nothing can start without it. The API on :4100 is fine — it is waiting on this."));
+  log(dim(`  nothing can start without it. The API on :${LOCAL_API_PORT} is fine — it is waiting on this.`));
   if (!local) {
     log(dim(`\n  That database is on another machine (${host}). Start it there, then run gu again.\n`));
     return { ok: false, fixed: false, installed: false };
@@ -925,6 +927,16 @@ export function markInterruptedOnExit(getState, stepId) {
   };
 }
 
+/** The last few non-empty lines of the API log, clipped to the screen — [] when there is none. */
+export async function apiLogTail(file, { lines = 3, width = 72 } = {}) {
+  try {
+    const all = (await readFile(file, "utf8")).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    return all.slice(-lines).map((l) => (l.length > width ? l.slice(0, width - 1) + "…" : l));
+  } catch {
+    return [];
+  }
+}
+
 export async function runClientExpertSetup({
   ask,
   // #301/#300: a MASKED line reader (API keys, the MongoDB password). Absent → no key is asked.
@@ -940,6 +952,15 @@ export async function runClientExpertSetup({
     return { complete: false, stoppedAt: "gate" };
   }
 
+  // BEFORE ANYTHING IS INSTALLED (task #333): the API needs a newer Node than gu does. Not part
+  // of the gate on purpose — a gate "no" makes the first run settle on Cloud mode for good,
+  // while the fix here is a Node upgrade, after which `gu` must resume Local setup.
+  const nodeProblem = localModeNodeProblem(process.version, machine.platform);
+  if (nodeProblem) {
+    console.log("\n  " + red("✗ ") + nodeProblem + "\n");
+    return { complete: false, stoppedAt: "node" };
+  }
+
   let state = await loadState();
   const mongo = await probeMongo();
   const probe = {
@@ -1165,13 +1186,27 @@ export async function runClientExpertSetup({
   // --- the API itself -------------------------------------------------------------------
   let health = await probeLocalApi(LOCAL_API_PORT);
   if (!health.ok) {
-    console.log("\n  " + bold(`Starting the local API on port ${LOCAL_API_PORT}`));
-    await startLocalApi({ apiDir, mongoUri });
-    health = await waitForApi({ port: LOCAL_API_PORT });
+    // THE PORT FIRST (task #337): 4100 may belong to another program on this machine. Settled
+    // before the "Starting…" line so that line names the port the API will really use —
+    // LOCAL_API_PORT and LOCAL_API_BASE are live and change with it.
+    console.log("");
+    const settled = await settleApiPort({ log: (l) => console.log(l) });
+    console.log("  " + bold(`Starting the local API on port ${LOCAL_API_PORT}`));
+    if (!settled.refused) {
+      await startLocalApi({ apiDir, mongoUri });
+      health = await waitForApi({ port: LOCAL_API_PORT });
+    }
   }
   if (!health.ok) {
     // apiIsUsable, not a 200: a wrong DATA_BACKEND answers 200 and stores nothing.
     console.log("\n  " + red("✗ ") + `The API started but is not usable: ${health.why}`);
+    // WHAT THE API SAID, not only where it said it (task #333): on Windows the whole log was
+    // one line, "Access is denied.", and the screen showed only a path to go and open.
+    const said = await apiLogTail(API_LOG_FILE);
+    if (said.length) {
+      console.log(dim("  The last thing its log says:"));
+      for (const l of said) console.log(dim("    " + l));
+    }
     console.log(dim(`  Its log is ${API_LOG_FILE}`));
     console.log(dim("  Run `gu` again to retry — nothing else has been changed.\n"));
     state = recordStep(state, "api-running", "failed", { reason: health.why });

package/client-expert-setup.mjs

@@ -834,12 +834,30 @@ export function validateLicenseVerdict({ licenseToken, expertAvailable }, result
  * validateLicenseToken by default; injectable for tests. Never throws — a validation that errors
  * is treated as unverifiable, not a crash.
  */
+/**
+ * What to say when a license token could not be CONFIRMED (#102) — it is still used: the licence
+ * is soft, and an outage never blocks a paid user. But "couldn't reach the license server" was
+ * printed when the server had been reached and answered HTTP 502; say which it was.
+ * `detail` is validateLicenseToken's: "http-NNN" | "timeout" | "network" | "bad-response" | …
+ */
+export function licenseUnverifiedLine(detail) {
+  const http = /^http-(\d{3})$/.exec(String(detail ?? ""));
+  if (http) return `The license server answered with an error (HTTP ${http[1]}), so the token was not confirmed — showing the menu anyway.`;
+  if (detail === "bad-response") return "The license server sent an unexpected answer, so the token was not confirmed — showing the menu anyway.";
+  return "Couldn't reach the license server to confirm the token — showing the menu anyway.";
+}
+
 export async function promptForLicenseToken(ask, initialToken, {
   validate = validateLicenseToken,
   validateOpts = {},
   warn = (msg) => console.log(msg),
   maxTries = 5,
+  // A MASKED reader (#100). A license token is a credential — whoever holds one can renew it —
+  // and the plain reader echoed it into the terminal and its scrollback (and into a test log).
+  // The first run and the REPL both have one; without it (a caller that has none) it is `ask`.
+  askSecret = null,
 } = {}) {
+  const read = typeof askSecret === "function" ? askSecret : ask;
   let token = String(initialToken ?? "").trim();
   for (let attempt = 0; attempt < maxTries; attempt += 1) {
     // Format gate first — a malformed token is warned about WITHOUT a network round-trip.
@@ -851,7 +869,9 @@ export async function promptForLicenseToken(ask, initialToken, {
       if (result.ok || result.reason === "unverified") return { token, result, declined: false };
       warn(`  That license token was not accepted (${result.detail ?? result.reason}).`);
     }
-    const again = String(await ask("  Paste a pro license token to choose a hosted mode, or press Enter to keep this machine private: ") ?? "").trim();
+    // Esc in the masked reader resolves with a symbol (SKIP_ALL): that is "no token", like Enter.
+    const typed = await read("  Paste a pro license token to choose a hosted mode, or press Enter to keep this machine private: ");
+    const again = typeof typed === "string" ? typed.trim() : "";
     if (!again) return { token: "", result: null, declined: true };
     token = again;
   }

package/first-run-steps.mjs

@@ -169,3 +169,29 @@ export function truncateDetail(detail, max = 160) {
   if (oneLine.length <= max) return oneLine;
   return "…" + oneLine.slice(oneLine.length - (max - 1));
 }
+
+/**
+ * Ctrl+C or Ctrl+D while a first-run question is waiting (task #333).
+ *
+ * `interrupt` (Ctrl+C): when setup has a step in progress it registered a SIGINT listener on the
+ * process (markInterruptedOnExit) that records where it stopped and exits — hand over to it.
+ * Otherwise say so and exit 130 here. `eof` (Ctrl+D): input is over; nothing more can be asked.
+ *
+ * Everything it touches is passed in, so the branches are tested without a terminal.
+ */
+export function stopFirstRun({ reason, hasProcessListener, emitSigint, log, exit, style = {} }) {
+  const yellow = style.yellow ?? ((t) => t);
+  const dim = style.dim ?? ((t) => t);
+  if (reason === "interrupt") {
+    if (hasProcessListener) {
+      emitSigint();
+      return;
+    }
+    log("\n\n  " + yellow("Stopped.") + dim(" Run `gu` again and setup continues from this step.\n"));
+    exit(130); // 128 + SIGINT
+    return;
+  }
+  log("\n\n  " + dim("input ended (Ctrl+D) — nothing further will be asked or started."));
+  log("  " + dim("Run `gu` again and setup continues from this step.\n"));
+  exit(0);
+}

package/gu-cli.mjs

@@ -134,6 +134,8 @@ Usage:
   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-path                          # macOS/Linux: put npm's global bin folder on PATH
+                                               #   (what the install does, if npm skipped it)
   gu-cli fix-powershell [--check]          # Windows: drop PowerShell's built-in \`gu\` alias
                                                #   (it is Get-Unique and shadows this CLI)
   gu-cli rag plan [path]                   # is RAG worth it here? files/chars/chunks → estimated index time
@@ -1054,6 +1056,42 @@ if (args[0] === "token-usage" || args[0] === "tokens") {
   process.exit(0);
 }
 
+// `gu-cli fix-path` — put npm's global bin folder on PATH (task #333). The same repair the
+// postinstall does, for when npm did not run it: run through install-path.mjs itself, with the
+// prefix worked out from where this file is installed, so there is one implementation.
+if (args[0] === "fix-path") {
+  if (process.platform === "win32") {
+    console.log("  Nothing to fix here — on Windows npm's folder is on PATH through the registry.");
+    console.log("  If `gu` is not found in PowerShell: gu-cli fix-powershell");
+    process.exit(0);
+  }
+  const { globalPrefixOf } = await import("./install-path.mjs");
+  const { fileURLToPath } = await import("node:url");
+  const { dirname, join } = await import("node:path");
+  const here = dirname(fileURLToPath(import.meta.url));
+  const prefix = globalPrefixOf(here);
+  if (!prefix) {
+    console.log(`  This gu is not a global npm install (${here}) — there is no PATH to fix.`);
+    process.exit(0);
+  }
+  const binDir = join(prefix, "bin");
+  if ((process.env.PATH || "").split(":").includes(binDir)) {
+    console.log(`  Nothing to fix — ${binDir} is already on PATH.`);
+    process.exit(0);
+  }
+  const { spawnSync } = await import("node:child_process");
+  const { CI: _ci, ...env } = process.env;
+  const r = spawnSync(process.execPath, [join(here, "install-path.mjs")], {
+    encoding: "utf8",
+    env: { ...env, npm_config_prefix: prefix, npm_config_global: "true" },
+  });
+  const said = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
+  // It prints only when it wrote something. Silence means the line is already in the profile
+  // and this terminal simply predates it.
+  console.log(said || `  Your shell profile already adds ${binDir} to PATH — open a new terminal.`);
+  process.exit(r.status ?? 0);
+}
+
 // `gu-cli fix-powershell` — drop PowerShell's built-in `gu` alias so the command works there.
 // ASKS FIRST and never runs as part of an install: a PowerShell profile is the user's file, and
 // a CLI that edits it unannounced is one that surprises people. --check only reports.

package/gu-repl.mjs

@@ -110,6 +110,8 @@ import {
   workspaceScopeWarning,
   isLocalApiBase,
   modeRow,
+  nothingToAnswerWith,
+  NO_MODEL_LINES,
   resizeRepaintTarget,
   workspaceSyncQuestion,
   workspaceSyncLabel,
@@ -665,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 = "";
@@ -682,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 });
@@ -701,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,
             },
@@ -710,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;
@@ -782,6 +806,7 @@ if (!workerKey || !apiBase) {
           typed = (await ask0("  worker key (or Enter to sign in): ")).trim();
         }
       } finally {
+        rl0Done = true;
         rl0.close();
       }
       if (stopAfterSetup) {
@@ -1599,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.
@@ -2277,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;
@@ -2296,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();
     }
@@ -10453,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;
   }
@@ -10786,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
@@ -12274,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,
           },
@@ -12503,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
@@ -12596,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)];
@@ -12693,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"

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.792",
+  "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",

package/platform-tools.mjs

@@ -298,23 +298,68 @@ export function windowsLauncherScript({ cmd, args = [], cwd, env = {}, logFile }
   return lines.join("\r\n") + "\r\n";
 }
 
+/**
+ * WHAT THE TASK RUNS — the launcher script, with NO WINDOW (task #334).
+ *
+ * The task used to run the .cmd itself. A task runs in the user's desktop session, so cmd.exe got
+ * a console window there, and `start /b` keeps node attached to that console: the window stayed
+ * for as long as the API or the worker lived. One per launch — the API, the worker, a worker
+ * restart, an API restart — "3-4 command windows" on a Windows 11 desktop after a first install,
+ * each of which kills its process when closed. Measured on the box: two visible windows titled
+ * C:\WINDOWS\SYSTEM32\cmd.exe, owned by the two node processes.
+ *
+ * `conhost.exe --headless` is Windows' own way to give a console program a console with no
+ * window (Windows 10 1809 and later). Not wscript/VBScript — it is being removed from Windows —
+ * and not `powershell -WindowStyle Hidden`, which flashes a window before hiding it.
+ *
+ * THE QUOTES ARE THE OTHER FIX. The bare script path was split by schtasks at the first space,
+ * so from a home like C:\Users\Jo Smith nothing started at all (measured: no log, no process).
+ */
+export function hiddenTaskAction(scriptPath, systemRoot) {
+  const root = String(systemRoot || "C:\\Windows").replace(/[\\/]+$/, "");
+  return `"${root}\\System32\\conhost.exe" --headless cmd.exe /c "${scriptPath}"`;
+}
+
 /**
  * Register → run → deregister. The task is a LAUNCH MECHANISM, not a persistent registration:
  * it exists only to start the process outside our job, and is removed immediately afterwards
  * so nothing is left scheduled on the user's machine. The started process keeps running —
  * deleting a task does not kill what it launched (verified).
  */
-export function schtasksCommands(taskName, scriptPath) {
+export function schtasksCommands(taskName, scriptPath, { elevated = false, systemRoot = process.env.SystemRoot } = {}) {
   return {
     create: {
       cmd: "schtasks.exe",
-      args: ["/create", "/tn", taskName, "/tr", scriptPath, "/sc", "once", "/st", "00:00", "/f"],
+      // `/rl highest` ONLY from an elevated terminal — see isElevatedGroups. From an ordinary one
+      // it is refused for an administrator ("Access is denied") and the task is never created.
+      args: [
+        "/create", "/tn", taskName, "/tr", hiddenTaskAction(scriptPath, systemRoot), "/sc", "once", "/st", "00:00",
+        ...(elevated ? ["/rl", "highest"] : []),
+        "/f",
+      ],
     },
     run: { cmd: "schtasks.exe", args: ["/run", "/tn", taskName] },
     remove: { cmd: "schtasks.exe", args: ["/delete", "/tn", taskName, "/f"] },
   };
 }
 
+/**
+ * IS THIS TERMINAL ELEVATED? — from `whoami /groups` (task #333).
+ *
+ * A scheduled task runs with the user's ORDINARY token unless it is created `/rl highest`, even
+ * when the terminal that created it is elevated — and an SSH session of an administrator always
+ * is. So the background process had FEWER rights than the `gu` that started it. On the Windows
+ * 11 test box node.exe belongs to another user's nvm and only Administrators may run it: `gu`
+ * ran, the API it launched got "Access is denied.", and setup stopped at "not up yet".
+ * A background process should have the rights of the terminal that started it — as it does on
+ * macOS and Linux, where it is simply a child.
+ *
+ * S-1-16-12288 is the High Mandatory Level label (S-1-16-16384 = System). Pure, so it is testable.
+ */
+export function isElevatedGroups(whoamiGroups) {
+  return /S-1-16-(12288|16384)\b/.test(String(whoamiGroups ?? ""));
+}
+
 /**
  * Which pid owns a listening port, from `netstat -ano`.
  *
@@ -382,7 +427,8 @@ export async function spawnSurviving({ cmd, args = [], cwd, env = {}, logFile, t
     "utf8"
   );
 
-  const t = schtasksCommands(taskName, script);
+  const elevated = isElevatedGroups(await run("whoami.exe", ["/groups"]));
+  const t = schtasksCommands(taskName, script, { elevated });
   const created = await run(t.create.cmd, t.create.args);
   if (created === null) {
     // No scheduler (or no rights): fall back to a plain detached spawn. It dies with an SSH

package/terminal-layout.mjs

@@ -2156,6 +2156,24 @@ export const HIDDEN_COMMANDS = [
                                 // the INPUT total — which does not exist yet as a counter
 ];
 
+/**
+ * NOTHING TO ANSWER WITH (#99): an agent payload with no model server in it at all.
+ *
+ * A missing AGENT model alone is fine — the API puts the coding model in its place (and sets
+ * `agentMissing`). With no coder either, `agentBaseURL` is empty: there is no server to send a
+ * question to. The API (from 1.0.220) refuses such a question in words; this lets the terminal
+ * say the same against an API that still queues a job nothing can read ("✗ Job not found.").
+ */
+export function nothingToAnswerWith(payload) {
+  if (!payload || typeof payload !== "object") return false; // unknown is not "none"
+  return !String(payload.agentBaseURL ?? "").trim();
+}
+
+export const NO_MODEL_LINES = [
+  "No model is set for this account, so there is nothing to answer with.",
+  "Pick a coding model with /model (and an agent model with /agent-model), then ask again.",
+];
+
 /**
  * Does this API base point at a server on THIS machine? (task #154)
  *
@@ -2177,9 +2195,20 @@ export function isLocalApiBase(apiBase) {
  * entire distinction — go unmentioned. Reported live on a fully set-up Ubuntu box that said
  * plain "client".
  */
-export function modeRow({ clientExpert, clientMode }) {
+export function modeRow({ clientExpert, clientMode, modelUrls = [], coderWhere }) {
   if (clientExpert) {
-    return { label: "client expert", detail: "(API + database here · models remote)" };
+    // "models remote" WAS A CONSTANT (task #333): a box running its own Ollama on 127.0.0.1 —
+    // the whole stack on one machine — was told its models were somewhere else. Said only when
+    // EVERY configured model server is this machine; one cloud coder is still "remote".
+    const urls = modelUrls.map((u) => String(u ?? "").trim()).filter(Boolean);
+    // `coderWhere` is the active coder's "host[:port]" label (coding-choice-tags.mjs), which
+    // names this machine as 127.0.0.1. Passed but empty = not known → not claimed to be here.
+    const coderHere = coderWhere === undefined || /^127\.0\.0\.1(:|$)/.test(String(coderWhere));
+    const allHere = urls.length > 0 && urls.every(isLocalApiBase) && coderHere;
+    return {
+      label: "client expert",
+      detail: allHere ? "(API, database and models here)" : "(API + database here · models remote)",
+    };
   }
   if (clientMode) {
     return { label: "client", detail: "(agent runs here · models remote)" };