@tiens.nguyen/gu-cli 1.0.706 → 1.0.708

package/cli-token.mjs

@@ -86,11 +86,13 @@ export function verifyCliToken(token, publicKeyB64) {
     (p.issuedBy !== "refresh" && p.issuedBy !== "account" && p.issuedBy !== "admin") ||
     !(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)
+    !(Number.isInteger(p.deviceLimit) && p.deviceLimit > 0) ||
+    // Missing means OFF — tokens issued before the switch existed (#238) are in CLIs right now.
+    !(p.enforce === undefined || typeof p.enforce === "boolean")
   ) {
     return { ok: false, why: "bad-payload" };
   }
-  return { ok: true, payload: p };
+  return { ok: true, payload: { ...p, enforce: p.enforce === true } };
 }
 
 // ---------------------------------------------------------------------------
@@ -251,7 +253,7 @@ export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempt
     if (Number.isInteger(p.activeDevices) && p.activeDevices > p.deviceLimit) {
       return {
         kind: "over-limit",
-        text: `gu is active on ${p.activeDevices} computers — ${p.plan === "pro" ? "Pro" : "Free"} covers ${p.deviceLimit}`,
+        text: `gu is active on ${p.activeDevices} devices — ${p.plan === "pro" ? "Pro" : "Free"} covers ${p.deviceLimit}`,
       };
     }
     const age = now.getTime() - Date.parse(p.issuedAt);
@@ -277,9 +279,63 @@ export function tokenSummary(payload, now = new Date()) {
   }
   if (Number.isInteger(payload.activeDevices)) {
     const n = payload.activeDevices;
-    lines.push(`Active on ${n} ${n === 1 ? "computer" : "computers"} in the last 30 days — ${payload.plan === "pro" ? "Pro" : "Free"} covers ${payload.deviceLimit}.`);
+    lines.push(`Active on ${n} ${n === 1 ? "device" : "devices"} in the last 30 days — ${payload.plan === "pro" ? "Pro" : "Free"} covers ${payload.deviceLimit}.`);
   }
   lines.push(`Issued ${shortDate(payload.issuedAt)}.`);
   return lines;
 }
 
+// ---------------------------------------------------------------------------
+// ENFORCEMENT (#238) — decided ONCE, when gu starts
+// ---------------------------------------------------------------------------
+
+/**
+ * May this session send turns?
+ *
+ * The switch lives on the server and rides in the token (payload.enforce). This is read ONCE at
+ * startup, by the owner's requirement — a session that began is never interrupted by a later renewal,
+ * and nothing asks the network again per turn.
+ *
+ * WITH THE SWITCH OFF (the default and what ships today) the answer is always yes: the licence stays
+ * soft — barNotice() says its one line and nothing is blocked.
+ *
+ * WITH IT ON, a session may send turns when the token is valid, the plan is Pro, its paid time has not
+ * run out, and the account is within its computer limit. Otherwise gu says why and refuses to SEND
+ * TURNS — `gu login`, `gu token`, /model and every other command keep working, because the person has
+ * to be able to fix it from where they are.
+ */
+export function enforcementDecision({ token, publicKeyB64, now = new Date(), site = DEFAULT_SITE }) {
+  if (!publicKeyB64) return { enforced: false, allowed: true, why: "" };
+  const check = token ? verifyCliToken(token, publicKeyB64) : { ok: false, why: "missing" };
+  // An unreadable or missing token cannot say whether enforcement is on, and this must not be a way
+  // to switch it off by deleting a file — but it is also not a reason to block someone whose server
+  // has enforcement OFF. Unknown means soft, exactly like a server that cannot be reached.
+  if (!check.ok) return { enforced: false, allowed: true, why: "" };
+  const p = check.payload;
+  if (!p.enforce) return { enforced: false, allowed: true, why: "" };
+
+  const host = site.replace(/^https?:\/\//, "");
+  const pricingUrl = `${host}/pricing`;
+  const accountUrl = `${host}/account`;
+  const ended = p.paidUntil && Date.parse(p.paidUntil) <= now.getTime();
+  if (p.plan !== "pro" || ended) {
+    return {
+      enforced: true,
+      allowed: false,
+      why: 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.`,
+    };
+  }
+  if (Number.isInteger(p.activeDevices) && p.activeDevices > p.deviceLimit) {
+    return {
+      enforced: true,
+      allowed: false,
+      why:
+        `This account is active on ${p.activeDevices} devices and Pro covers ${p.deviceLimit}. ` +
+        `Sign out of one, or remove it at ${accountUrl}.`,
+    };
+  }
+  return { enforced: true, allowed: true, why: "" };
+}
+

package/credential-recovery.mjs

@@ -0,0 +1,82 @@
+/**
+ * WHEN THE CREDENTIALS ON THIS MACHINE NO LONGER WORK (task #240).
+ *
+ * THE DEAD END THIS EXISTS TO CLOSE, reproduced in a clean Ubuntu container: a machine whose
+ * ~/.gonext/worker.env holds a key the API rejects (rotated, revoked, pasted from another
+ * account, or written by the wizard for a different server) could not reach the first-run flow
+ * at all. `gu` printed one red line and exited — every time, forever. The questions a first run
+ * asks were unreachable, and the only route back was `gu clear`, which is a RESET: it deletes
+ * conversation history, registered workspaces, deploy targets, the agent's edit backups and the
+ * RAG indexes. Reported as "first run question doesn't appear … I then needed gu clear then gu
+ * again", and that is exactly what the user had been driven to.
+ *
+ * A REJECTED KEY IS THE SAME SITUATION AS NO KEY. Both mean this machine is not connected to an
+ * account, and the answer to both is the sign-in that the first run already offers. So gu offers
+ * it here too, in place, keeping everything else on the machine.
+ *
+ * WHY A MODULE AND NOT AN `if` IN THE REPL: so the rule can be called by a test. The conduct
+ * being pinned is "which situations offer a sign-in", and open-coded it could only be guarded by
+ * a regex over gu-repl.mjs — which pins the WORDING and lets the conduct change underneath.
+ *
+ * THE CODE, NOT THE WORDING, decides. payloadError() stamps `code` on the error the API call
+ * throws; nothing downstream matches on the message text, which is free to be reworded.
+ */
+
+/** The error an agent-payload call failed with, carrying a code the recovery can switch on. */
+export function payloadError(status, data) {
+  const message = (data && typeof data === "object" && data.error) || "";
+  if (status === 404) {
+    const e = new Error(
+      "the API does not have POST /api/worker/agent-payload yet — deploy the latest API (sam build && sam deploy)."
+    );
+    e.code = "API_TOO_OLD";
+    return e;
+  }
+  // 401/403: the key is present and WRONG. We never re-validate a stored key proactively, so
+  // this is where a rotated or revoked one surfaces — the first thing gu does on startup.
+  if (status === 401 || status === 403) {
+    const e = new Error(
+      "your worker key was rejected (it may have been rotated or revoked). " +
+        "Run `gu login` to sign in again, or update it with `gu set <workerKey> --api-base <url>`."
+    );
+    e.code = "KEY_REJECTED";
+    return e;
+  }
+  const e = new Error(message || `agent-payload failed (HTTP ${status})`);
+  e.code = "API_ERROR";
+  return e;
+}
+
+/**
+ * What should happen when the startup probe fails?
+ *
+ *   "offer-signin" — ask, here and now, and carry on with the session when it works.
+ *   "report"       — print what is wrong and stop. The caller's existing message.
+ *
+ * ONLY a rejected key, and only with somebody there to answer. A network failure is not a
+ * credential problem (the key may be perfect and the wifi off), and a pipe or CI job has nobody
+ * at the keyboard — offering there would hang a script on a prompt no one can see, which is the
+ * failure mode that made `gu` unusable in the deploy app's stages.
+ *
+ * NOT ON A CLIENT EXPERT MACHINE. Its API is local and issues its own key; a hosted device-login
+ * there points the terminal away from the very stack it was set up to use. The same reasoning
+ * that made first-run setup skip the sign-in after Client Expert applies to the recovery.
+ */
+export function recoveryPlan({ code, isTty, clientExpert } = {}) {
+  if (code !== "KEY_REJECTED") return { action: "report" };
+  if (!isTty) return { action: "report" };
+  if (clientExpert) return { action: "report" };
+  return {
+    action: "offer-signin",
+    // What it says matters as much as that it asks: someone who has just been told their key is
+    // bad needs to know that answering will not cost them their work.
+    lines: [
+      "gu: this machine's worker key was rejected — it may have been rotated or revoked.",
+      "  Sign in again to reconnect this machine to an account.",
+      "  Nothing else is touched: your folders, chat history and RAG indexes stay as they are.",
+    ],
+    // UN-INDENTED, like every other ask() caller: ask() insets by the gutter itself, and a
+    // prompt carrying its own spaces comes out sitting two columns right of every other question.
+    prompt: "worker key (or Enter to sign in): ",
+  };
+}

package/gu-repl.mjs

@@ -24,13 +24,13 @@
  * Commands: /exit  /model  /reset  /help   Ctrl-C stops following the current run.
  */
 import { readFile, mkdir, writeFile, unlink, rename } from "node:fs/promises";
-import { existsSync, statSync, readFileSync } from "node:fs";
+import { existsSync, statSync, readFileSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 // FIRST, before anything that could itself fail on an old runtime: npm only WARNS about
 // `engines`, so an unsupported Node installs fine and then breaks somewhere unrelated.
 import { requireSupportedNode } from "./node-version.mjs";
 requireSupportedNode();
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { dirname, join, resolve, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { PassThrough } from "node:stream";
@@ -137,6 +137,9 @@ import { REQUIRED_AGENT_MODEL, REQUIRED_AGENT_PREFIX, REQUIRED_EMBED_MODEL } fro
 // plain SGR code: terminals disagree about colour, so accent.mjs picks 24-bit, 256 or the
 // sixteen-colour magenta from what this one actually claims to support.
 import { accent } from "./accent.mjs";
+// Task #240: what a failed agent-payload call means, and when a rejected key may be recovered
+// from in place instead of ending the session.
+import { payloadError, recoveryPlan } from "./credential-recovery.mjs";
 import { isNoCodeRetry, splitVerboseLine, stepHasCode } from "./verbose-lines.mjs";
 import {
   createTranscript,
@@ -792,6 +795,8 @@ const COMMANDS = [
   { name: "/proxy", usage: "/proxy [show|set|on|off|clear|test]", desc: "route MODEL calls through an HTTP proxy (local calls always go direct)" },
   { name: "/s3", usage: "/s3 [test]", desc: "set up the S3 bucket the RAG index lives in, and check the AWS keys work" },
   { name: "/context-window", usage: "/context-window [tokens|auto]", desc: "tell gu how big the coding model's context is — hosted models cannot be probed" },
+  { name: "/save-settings", usage: "/save-settings [path]", desc: "write this account's coding providers, models and key NAMES to a file (no secrets)" },
+  { name: "/load-settings", usage: "/load-settings [path]", desc: "read that file back on another machine — asks before it replaces anything" },
   { 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: "/help", desc: "list these commands" },
@@ -1863,6 +1868,13 @@ async function refreshAvailableUpdates() {
 let tokenNotice = null;
 let tokenBusy = false;
 let startupRenewDone = false;
+/**
+ * THE ENFORCEMENT DECISION (#238) — taken ONCE, on the first refresh after gu starts, and never
+ * revisited. The owner's requirement: check when gu starts, not repeatedly. A session already running
+ * is never cut off by a switch flipped elsewhere, and a later renewal only updates the bar's line.
+ */
+let licenceBlock = null;
+let licenceDecided = false;
 async function refreshCliToken() {
   if (tokenBusy) return;
   tokenBusy = true;
@@ -1902,6 +1914,17 @@ async function refreshCliToken() {
       await ct.writeState(dir, state).catch(() => {});
       tokenNotice = noticeNow();
     }
+    if (!licenceDecided) {
+      licenceDecided = true;
+      const d = ct.enforcementDecision({ token: state.token, publicKeyB64: pk, site });
+      licenceBlock = d.enforced && !d.allowed ? d.why : null;
+      if (licenceBlock) {
+        console.log("");
+        console.log(GUTTER + orange("gu cannot run turns on this account.") );
+        console.log(GUTTER + dim("  " + licenceBlock));
+        console.log(GUTTER + dim("  Everything else still works: /model, gu token, gu login.") + "\n");
+      }
+    }
   } catch {
     /* never a reason to disturb a session */
   } finally {
@@ -6072,6 +6095,138 @@ async function chooseModel() {
 // The settings row as the WORKER sees it (X-Worker-Key, no Firebase). This is the only route a
 // Client Expert machine has to its own settings — there is no web app pointed at that API — so
 // anything a command needs to show or change has to come through here.
+/**
+ * `/save-settings [path]` and `/load-settings [path]` — move a setup between machines (#244).
+ *
+ * WHAT TRAVELS: the coding providers and their model lists, the agent model, and the NAMES of the
+ * API keys. What does not travel is the keys themselves — the API will not hand them over (see
+ * settings-transfer.mjs for why, and why that is right), so loading asks for the ones the target
+ * account is missing. The file is therefore safe to copy about, which is the whole point of it.
+ *
+ * NOT THE CURRENT CHOICE. Which model this account codes with stays as it is on the machine being
+ * loaded into: a file that moves your models should not quietly move your coder too.
+ */
+const SETTINGS_FILE_DEFAULT = join(homedir(), "gu-settings.json");
+
+/** The path a command was given, or the default. Quotes stripped: people paste paths with them. */
+function settingsPathFrom(line, word) {
+  const typed = line.slice(word.length).trim().replace(/^['"]|['"]$/g, "");
+  if (!typed) return SETTINGS_FILE_DEFAULT;
+  const expanded = typed.startsWith("~/") ? join(homedir(), typed.slice(2)) : typed;
+  return resolve(expanded);
+}
+
+async function runSaveSettingsCommand(line) {
+  const st = await import("./settings-transfer.mjs");
+  const file = settingsPathFrom(line, "/save-settings");
+  console.log("");
+  const settings = await withPendingStatus("reading your model settings", fetchWorkerSettings);
+  if (!settings) {
+    console.log(GUTTER + red(`  couldn't reach the API at ${apiBase} — nothing was written.\n`));
+    return;
+  }
+  const keys = (await fetchCodingKeys()) ?? [];
+  const doc = st.buildTransfer({ settings, keys, host: hostname() });
+  if (!doc.codingBackends.length && !doc.agentModel.url && !doc.agentModel.name) {
+    console.log(GUTTER + dim("  this account has no coding providers and no agent model set — nothing to save.\n"));
+    return;
+  }
+  // ASK BEFORE OVERWRITING. The default path is one everybody shares, so the second machine to
+  // save would otherwise eat the first machine's file without a word.
+  if (existsSync(file)) {
+    const ok = (await ask(`${file} exists — overwrite it? [y/N] `)).trim().toLowerCase();
+    if (ok !== "y" && ok !== "yes") {
+      console.log(GUTTER + dim("  left it alone.\n"));
+      return;
+    }
+  }
+  try {
+    // 0600: it names your providers and your key names. Not secret, but nobody else's business.
+    writeFileSync(file, JSON.stringify(doc, null, 2) + "\n", { mode: 0o600 });
+  } catch (e) {
+    console.log(GUTTER + red(`  could not write ${file}: ${e instanceof Error ? e.message : e}\n`));
+    return;
+  }
+  const models = doc.codingBackends.reduce((n, b) => n + b.models.length, 0);
+  console.log(GUTTER + accent(`  saved to ${file}`));
+  console.log(
+    GUTTER +
+      dim(`  ${doc.codingBackends.length} provider${doc.codingBackends.length === 1 ? "" : "s"}, ${models} model${models === 1 ? "" : "s"}, ${doc.keys.length} key name${doc.keys.length === 1 ? "" : "s"} — no secrets.`),
+  );
+  console.log(GUTTER + dim("  load it on the other machine with  /load-settings " + file + "\n"));
+}
+
+async function runLoadSettingsCommand(line) {
+  const st = await import("./settings-transfer.mjs");
+  const file = settingsPathFrom(line, "/load-settings");
+  console.log("");
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    console.log(GUTTER + red(`  no file at ${file}`));
+    console.log(GUTTER + dim("  /load-settings <path>, or save one first with /save-settings.\n"));
+    return;
+  }
+  // VALIDATED BEFORE ANYTHING IS TOUCHED: a settings file applied halfway is worse than one
+  // refused, because the half that landed is the half nobody re-reads.
+  const parsed = st.validateTransfer(text);
+  if (!parsed.ok) {
+    console.log(GUTTER + red(`  ${parsed.problem}`));
+    console.log(GUTTER + dim(`  file: ${file}\n`));
+    return;
+  }
+  const current = await withPendingStatus("reading your model settings", fetchWorkerSettings);
+  if (!current) {
+    console.log(GUTTER + red(`  couldn't reach the API at ${apiBase} — nothing was changed.\n`));
+    return;
+  }
+  const keys = (await fetchCodingKeys()) ?? [];
+  const plan = st.planLoad(parsed.value, { ...current, keys });
+  console.log(GUTTER + dim(`  from ${file}${parsed.value.savedOn ? ` (saved on ${parsed.value.savedOn})` : ""}`));
+  for (const l of plan.lines) console.log(GUTTER + dim("  " + l));
+  if (parsed.carriesSecrets) {
+    console.log(GUTTER + yellow("  this file contains API keys in plain text — delete it when you are done."));
+  }
+  console.log("");
+  const go = (await ask("  apply this? [y/N] ")).trim().toLowerCase();
+  if (go !== "y" && go !== "yes") {
+    console.log(GUTTER + dim("  nothing changed.\n"));
+    return;
+  }
+  const md = await import("./model-doctor.mjs");
+  // `current` so a provider this account already has keeps its row id — see toSettingsPatch.
+  const patch = st.toSettingsPatch(parsed.value, current);
+  const saved = Object.keys(patch).length
+    ? await md.saveWorkerSettings(apiBase, workerKey, patch)
+    : true;
+  if (!saved) {
+    console.log(GUTTER + red("  the API refused the settings — nothing was changed.\n"));
+    return;
+  }
+  console.log(GUTTER + accent(`  applied: ${plan.adds} provider${plan.adds === 1 ? "" : "s"}.`));
+
+  // THE KEYS, AFTER the settings — each needs the row it belongs to, and the rows only exist
+  // once the API has minted their ids.
+  const fresh = (await fetchWorkerSettings()) ?? {};
+  const rows = Array.isArray(fresh.agentCodingBackends) ? fresh.agentCodingBackends : [];
+  const rowIdForUrl = (url) => {
+    const hit = rows.find((r) => String(r?.url ?? "").trim().toLowerCase() === String(url).trim().toLowerCase());
+    return hit?.id ?? "";
+  };
+  for (const k of plan.missingKeys) {
+    const where = k.backendUrl ? ` for ${k.backendUrl}` : "";
+    const typed = k.key || (await ask(`  key "${k.name}"${k.tail ? ` (…${k.tail})` : ""}${where} — paste it, or Enter to skip: `)).trim();
+    if (!typed) {
+      console.log(GUTTER + dim(`  skipped ${k.name} — add it later with ctrl+k.`));
+      continue;
+    }
+    const id = await addCodingKey(k.name, typed, k.backendUrl ? rowIdForUrl(k.backendUrl) : "");
+    console.log(GUTTER + (id ? accent(`  added ${k.name}.`) : red(`  could not add ${k.name}.`)));
+  }
+  console.log(GUTTER + dim("  pick a coding model with /model.\n"));
+}
+
 async function fetchWorkerSettings() {
   try {
     const r = await fetch(`${apiBase}/api/worker/settings`, {
@@ -7624,27 +7779,65 @@ async function fetchAgentPayload(messages, codingModelOverride = "") {
     data = {};
   }
   if (!res.ok) {
-    if (res.status === 404) {
-      throw new Error(
-        "the API does not have POST /api/worker/agent-payload yet — deploy the latest API (sam build && sam deploy)."
-      );
-    }
     // Task #127 (BC1b): a present-but-INVALID worker key (rotated/revoked while worker.env
-    // kept the stale one) shows up as 401/403. Point the user at re-login rather than a
-    // generic error — we don't proactively re-validate the key, so the first rejection is
-    // where this surfaces.
-    if (res.status === 401 || res.status === 403) {
-      throw new Error(
-        "your worker key was rejected (it may have been rotated or revoked). " +
-          "Run `gu-cli login` to sign in again, or update it with " +
-          "`gu-cli set <workerKey> --api-base <url>`."
-      );
-    }
-    throw new Error(data?.error || `agent-payload failed (HTTP ${res.status})`);
+    // kept the stale one) shows up as 401/403. We don't proactively re-validate the key, so
+    // the first rejection is where this surfaces.
+    //
+    // THE MESSAGES AND THE CODES NOW LIVE IN credential-recovery.mjs (task #240), because the
+    // startup probe does more than print them: a rejected key there OFFERS THE SIGN-IN rather
+    // than exiting, and that decision must switch on a code, not on a regex over wording.
+    throw payloadError(res.status, data);
   }
   return data;
 }
 
+/**
+ * The STARTUP probe, with one way back from a rejected key (task #240).
+ *
+ * Reproduced in a clean Ubuntu container: with a key the API rejects, `gu` printed one red line
+ * and exited — every time. The first-run questions were unreachable from that state, so the only
+ * route back was `gu clear`, which also deletes chat history, workspaces, edit backups and RAG
+ * indexes. A rejected key means this machine is not connected to an account, which is the same
+ * situation a first run is for; so the sign-in is offered here, keeping everything else.
+ *
+ * EXACTLY ONE OFFER. The retry is outside the recovery, so a key that is rejected AGAIN (the
+ * account has no worker, the API is confused) falls through to the normal error and exit instead
+ * of asking in a loop.
+ *
+ * Only the startup probe recovers. The other fetchAgentPayload callers run mid-session, where a
+ * sign-in prompt would interrupt work in progress; they keep their existing error handling.
+ */
+async function probeWithRecovery() {
+  const ping = [{ role: "user", content: "ping" }];
+  try {
+    return await fetchAgentPayload(ping);
+  } catch (err) {
+    const plan = recoveryPlan({
+      code: err?.code,
+      isTty: IS_TTY,
+      clientExpert: isClientExpert(),
+    });
+    if (plan.action !== "offer-signin") throw err;
+    console.log("");
+    console.log(red(plan.lines[0]));
+    for (const line of plan.lines.slice(1)) console.log(dim(line));
+    console.log("");
+    const { deviceLogin, saveWorkerKey, DEFAULT_API_BASE } = await import("./device-login.mjs");
+    const typed = (await ask(plan.prompt)).trim();
+    const r = typed
+      ? await saveWorkerKey({
+          apiBase: apiBase || DEFAULT_API_BASE,
+          workerKey: typed,
+          log: (s) => console.log(s),
+        })
+      : await deviceLogin({ apiBase: apiBase || DEFAULT_API_BASE, log: (s) => console.log(s) });
+    // worker.env is written by those two; this process is still holding the rejected values.
+    workerKey = r.workerKey;
+    apiBase = r.apiBase;
+    return await fetchAgentPayload(ping);
+  }
+}
+
 // ---------- run one agent turn via the JOB QUEUE (the daemon executes it) ----------
 // The question is enqueued exactly like a web question, so the RUNNING
 // gu-cli daemon claims + executes it — its terminal shows the full
@@ -8357,6 +8550,12 @@ const wrapThought = (s, width, maxLines) => {
  * own conversation.
  */
 async function runAgentTurn(history, { attachJobId = "" } = {}) {
+  // #238: when the licence is ENFORCED and this account is not entitled, no turn is sent. Decided at
+  // startup (see licenceBlock) — never re-checked here, so a turn cannot die halfway through.
+  if (licenceBlock) {
+    console.log(GUTTER + orange("Not sent.") + dim(" " + licenceBlock) + "\n");
+    return;
+  }
   const attached = Boolean(attachJobId);
   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
@@ -9783,7 +9982,7 @@ async function main() {
   }
   // Show which models will answer, straight from user settings (also validates auth).
   try {
-    const probe = await fetchAgentPayload([{ role: "user", content: "ping" }]);
+    const probe = await probeWithRecovery();
     const p = probe?.payload ?? {};
     // Remember the default coder id for the token footer's global-total label, and the
     // default backend's coding URL so the GLOBAL output-token total is keyed to it (task
@@ -10178,6 +10377,12 @@ async function main() {
                 dim("\n  If that fails, check MongoDB is running and see ~/.gonext/local-api.log\n")
         );
       }
+    } else if (err?.code === "KEY_REJECTED") {
+      // WE REACHED THE API PERFECTLY WELL — it told us the key is no good (task #240). Wrapping
+      // that in "couldn't reach the API" sends the reader off debugging DNS, a proxy and their
+      // wifi for a problem the server already named. Seen in the container: a second bad key
+      // pasted at the recovery prompt produced exactly that sentence.
+      console.error(red("gu: " + err.message));
     } else {
       // The SAME bare "fetch failed" the Client Expert branch above was written to fix — that
       // one names the host and offers a next step, this one printed node's four words and
@@ -10465,6 +10670,14 @@ async function main() {
       await runS3Command(line);
       continue;
     }
+    if (line === "/save-settings" || line.startsWith("/save-settings ")) {
+      await runSaveSettingsCommand(line);
+      continue;
+    }
+    if (line === "/load-settings" || line.startsWith("/load-settings ")) {
+      await runLoadSettingsCommand(line);
+      continue;
+    }
     if (line === "/test-auto") {
       sessionTestAuto = !sessionTestAuto;
       await saveSession(cwd, history); // persist the choice for this folder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.706",
+  "version": "1.0.708",
   "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",
@@ -52,6 +52,8 @@
     "version-check.mjs",
     "rag-selftest.mjs",
     "cli-token.mjs",
+    "credential-recovery.mjs",
+    "settings-transfer.mjs",
     "device-login.mjs",
     "daemon-control.mjs",
     "poll-errors.mjs",

package/settings-transfer.mjs

@@ -0,0 +1,253 @@
+/**
+ * MOVING A SETUP BETWEEN MACHINES — the file /save-settings writes and /load-settings reads (#244).
+ *
+ * WHAT IT CARRIES: the coding backends (the list /model picks from), the agent model, and the
+ * IDENTITY of each API key. What it deliberately does not carry is the keys themselves.
+ *
+ * WHY NO SECRETS, since this is the first question anyone asks of a "save my settings" file: the API
+ * will not give them to us. GET /api/worker/coding-keys returns maskCodingKeys() — id, name, last
+ * four characters — and says why on the route: it is the one place that lists credentials, so it is
+ * the one place that could turn a leaked worker key into "dump every key I own". The only route that
+ * returns a real secret returns exactly one, the key a given job or provider would be handed. A save
+ * could walk that route once per provider and harvest the lot, which is precisely the thing the
+ * masking exists to prevent — and it would put them in a file that then sits in Downloads.
+ *
+ * So the file names the keys and loading asks for the ones the target account is missing. The
+ * side-effect is the good kind: this file is safe to copy, email, or commit.
+ *
+ * ROW IDS NEVER TRAVEL. They identify a row WITHIN one account — a folder's saved pick, a job's
+ * record of which key it used, the account default all name one — so another account's ids would
+ * either collide with a row already there or silently re-point a folder at a different provider.
+ * The file therefore names providers by URL, which means the same thing on every machine.
+ *
+ * ON LOADING, A PROVIDER THIS ACCOUNT ALREADY HAS KEEPS ITS OWN ID (see toSettingsPatch). Minting a
+ * fresh one would strand every key bound to the old row: a key whose row is gone is ineligible
+ * everywhere and filtered out of every picker, so it can never be selected, used or deleted again.
+ *
+ * THE CURRENT CHOICE IS NOT SAVED, by instruction and by safety: agentCodingDefaultKind and
+ * agentCodingDefaultBackendId stay as they are on the machine being loaded into. A file that moves
+ * your models should not also decide which one you are coding with.
+ */
+
+/** Bumped only when an older gu could not read a newer file correctly. */
+export const FILE_VERSION = 1;
+
+/** The kinds the API's own type allows (CodingBackendKind). */
+const KINDS = ["", "ollama", "openai", "local"];
+
+const isHttpUrl = (v) => typeof v === "string" && /^https?:\/\/\S+$/i.test(v.trim());
+const isStr = (v) => typeof v === "string";
+const clean = (v) => (typeof v === "string" ? v.trim() : "");
+
+/**
+ * The object /save-settings writes.
+ *
+ * `settings` is the account's settings as the API returns them; `keys` is the masked list. Neither
+ * is trusted to be well-formed — a machine that has never set a coder has no backends at all.
+ */
+export function buildTransfer({ settings = {}, keys = [], now = new Date(), host = "" } = {}) {
+  const rows = Array.isArray(settings.agentCodingBackends) ? settings.agentCodingBackends : [];
+  const backends = rows
+    .filter((r) => r && typeof r === "object")
+    .map((r) => ({
+      kind: KINDS.includes(r.kind) ? r.kind : "",
+      url: clean(r.url),
+      defaultModel: clean(r.defaultModel),
+      models: Array.isArray(r.models) ? r.models.filter(isStr).map((m) => m.trim()).filter(Boolean) : [],
+      enabled: r.enabled !== false,
+    }));
+  // A key's row id means nothing on another account; the provider's URL means the same everywhere.
+  const urlForRowId = new Map(rows.filter((r) => r?.id).map((r) => [r.id, clean(r.url)]));
+  const keyList = (Array.isArray(keys) ? keys : [])
+    .filter((k) => k && typeof k === "object" && clean(k.name))
+    .map((k) => ({
+      name: clean(k.name),
+      tail: clean(k.tail),
+      ...(urlForRowId.get(k.backendId) ? { backendUrl: urlForRowId.get(k.backendId) } : {}),
+    }));
+  return {
+    gu: "settings",
+    version: FILE_VERSION,
+    // Said in the file, because someone will open it and wonder.
+    note: "Models and providers only. This file contains NO API keys — gu asks for those when you load it.",
+    savedAt: new Date(now).toISOString(),
+    ...(host ? { savedOn: host } : {}),
+    codingBackends: backends,
+    agentModel: { url: clean(settings.agentModelUrl), name: clean(settings.agentModelName) },
+    keys: keyList,
+  };
+}
+
+/**
+ * Read a file's text and say either what it means or what is wrong with it.
+ *
+ * ONE PROBLEM, NAMED. Everything is checked before anything is applied, and the first real problem
+ * refuses the whole file: a settings file applied halfway is worse than one rejected, because the
+ * half that landed is the half nobody reads back.
+ */
+export function validateTransfer(text) {
+  let doc;
+  try {
+    doc = JSON.parse(String(text));
+  } catch {
+    return { ok: false, problem: "that file is not JSON — is it the file gu saved?" };
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    return { ok: false, problem: "that file is not a gu settings file (expected a JSON object)." };
+  }
+  if (doc.gu !== "settings") {
+    return { ok: false, problem: 'that file is not a gu settings file (no "gu": "settings" marker).' };
+  }
+  if (doc.version !== FILE_VERSION) {
+    return {
+      ok: false,
+      problem: `that file is version ${JSON.stringify(doc.version)}; this gu writes and reads version ${FILE_VERSION}. Update gu, or save it again from the machine that wrote it.`,
+    };
+  }
+  const rows = doc.codingBackends;
+  if (rows !== undefined && !Array.isArray(rows)) {
+    return { ok: false, problem: "codingBackends must be a list." };
+  }
+  const backends = [];
+  const seen = new Set();
+  for (const [i, r] of (rows ?? []).entries()) {
+    const at = `codingBackends[${i}]`;
+    if (!r || typeof r !== "object" || Array.isArray(r)) return { ok: false, problem: `${at} is not an object.` };
+    if (!KINDS.includes(r.kind)) {
+      return { ok: false, problem: `${at} has kind ${JSON.stringify(r.kind)} — expected one of ${KINDS.filter(Boolean).join(", ")}.` };
+    }
+    if (r.url !== undefined && r.url !== "" && !isHttpUrl(r.url)) {
+      return { ok: false, problem: `${at} has a url that is not http(s): ${JSON.stringify(r.url)}.` };
+    }
+    if (r.models !== undefined && (!Array.isArray(r.models) || !r.models.every(isStr))) {
+      return { ok: false, problem: `${at}.models must be a list of model names.` };
+    }
+    if (r.defaultModel !== undefined && !isStr(r.defaultModel)) {
+      return { ok: false, problem: `${at}.defaultModel must be text.` };
+    }
+    // "false" as a STRING is truthy — the exact trap the API's own settings writer documents.
+    if (r.enabled !== undefined && typeof r.enabled !== "boolean") {
+      return { ok: false, problem: `${at}.enabled must be true or false, not ${JSON.stringify(r.enabled)}.` };
+    }
+    const dup = `${r.kind}|${clean(r.url).toLowerCase()}`;
+    if (seen.has(dup)) return { ok: false, problem: `${at} repeats a provider already in the file (${r.kind} ${clean(r.url) || "no url"}).` };
+    seen.add(dup);
+    backends.push({
+      kind: r.kind,
+      url: clean(r.url),
+      defaultModel: clean(r.defaultModel),
+      models: (r.models ?? []).map((m) => m.trim()).filter(Boolean),
+      enabled: r.enabled !== false,
+    });
+  }
+  const am = doc.agentModel;
+  if (am !== undefined && (!am || typeof am !== "object" || Array.isArray(am))) {
+    return { ok: false, problem: "agentModel must be an object with a url and a name." };
+  }
+  if (am?.url !== undefined && am.url !== "" && !isHttpUrl(am.url)) {
+    return { ok: false, problem: `agentModel.url is not http(s): ${JSON.stringify(am.url)}.` };
+  }
+  if (am?.name !== undefined && !isStr(am.name)) {
+    return { ok: false, problem: "agentModel.name must be text." };
+  }
+  if (doc.keys !== undefined && !Array.isArray(doc.keys)) {
+    return { ok: false, problem: "keys must be a list." };
+  }
+  const keys = [];
+  for (const [i, k] of (doc.keys ?? []).entries()) {
+    const at = `keys[${i}]`;
+    if (!k || typeof k !== "object" || Array.isArray(k)) return { ok: false, problem: `${at} is not an object.` };
+    if (!clean(k.name)) return { ok: false, problem: `${at} has no name — a key is identified by its name.` };
+    if (k.key !== undefined && !isStr(k.key)) return { ok: false, problem: `${at}.key must be text.` };
+    if (k.backendUrl !== undefined && k.backendUrl !== "" && !isHttpUrl(k.backendUrl)) {
+      return { ok: false, problem: `${at}.backendUrl is not http(s): ${JSON.stringify(k.backendUrl)}.` };
+    }
+    keys.push({
+      name: clean(k.name),
+      tail: clean(k.tail),
+      ...(clean(k.backendUrl) ? { backendUrl: clean(k.backendUrl) } : {}),
+      // Present only when a person put it there by hand; gu never writes one.
+      ...(clean(k.key) ? { key: clean(k.key) } : {}),
+    });
+  }
+  return {
+    ok: true,
+    value: { backends, agentModel: { url: clean(am?.url), name: clean(am?.name) }, keys, savedAt: clean(doc.savedAt), savedOn: clean(doc.savedOn) },
+    // Loading a file someone hand-edited to carry live credentials is allowed, but it is not
+    // allowed to be quiet: that file is now a secret on disk.
+    carriesSecrets: keys.some((k) => k.key),
+  };
+}
+
+/**
+ * What loading this file would do to the machine it is loaded on.
+ *
+ * REPLACES, DOES NOT MERGE. Two providers with the same URL are the same provider, and merging
+ * would leave a machine holding both the file's idea of a provider and its own — which is how a
+ * /model list ends up with two rows that look identical and behave differently. The plan says so
+ * plainly, because "replace" is the part a person needs to agree to.
+ */
+export function planLoad(file, current = {}) {
+  const currentRows = Array.isArray(current.agentCodingBackends) ? current.agentCodingBackends : [];
+  const currentKeys = Array.isArray(current.keys) ? current.keys : [];
+  const have = new Set(currentKeys.map((k) => clean(k.name).toLowerCase()).filter(Boolean));
+  const missingKeys = file.keys.filter((k) => !have.has(k.name.toLowerCase()) && !k.key);
+  const lines = [];
+  lines.push(
+    file.backends.length
+      ? `${file.backends.length} coding provider${file.backends.length === 1 ? "" : "s"}${currentRows.length ? `, replacing the ${currentRows.length} on this account` : ""}:`
+      : "no coding providers in the file — the ones on this account stay as they are.",
+  );
+  for (const b of file.backends) {
+    const models = b.models.length ? `${b.models.length} model${b.models.length === 1 ? "" : "s"}` : "no models";
+    lines.push(`  ${b.kind || "?"}  ${b.url || "(no url)"}  ${models}${b.defaultModel ? `, default ${b.defaultModel}` : ""}${b.enabled ? "" : "  (disabled)"}`);
+  }
+  if (file.agentModel.url || file.agentModel.name) {
+    lines.push(`agent model: ${file.agentModel.name || "(server default)"}${file.agentModel.url ? ` at ${file.agentModel.url}` : ""}`);
+  }
+  if (missingKeys.length) {
+    lines.push(`${missingKeys.length} API key${missingKeys.length === 1 ? "" : "s"} this account does not have — gu will ask for ${missingKeys.length === 1 ? "it" : "them"} after:`);
+    for (const k of missingKeys) lines.push(`  ${k.name}${k.tail ? ` (…${k.tail})` : ""}${k.backendUrl ? ` for ${k.backendUrl}` : ""}`);
+  }
+  // The account default is NOT in the file and is not touched — said out loud, because someone
+  // loading "their models" onto a machine reasonably expects the coder to change too.
+  lines.push("your current coding model choice is not changed — pick one with /model.");
+  return { lines, missingKeys, replaces: currentRows.length, adds: file.backends.length };
+}
+
+/**
+ * The POST body for /api/worker/settings. Only fields a worker key may write.
+ *
+ * A PROVIDER THIS ACCOUNT ALREADY HAS KEEPS ITS ROW ID, and that is not a detail. An API key is
+ * bound to a row BY ID; a key whose row has gone is, in this codebase's own words, "ineligible
+ * everywhere AND filtered out of every picker" — it can never be selected, used or deleted again.
+ * Folder picks and job records name rows the same way. So loading a file onto a machine that
+ * already has api.openai.com must reuse that row rather than mint a second one: matched on
+ * kind + url, which is what makes two rows the same provider. Genuinely new rows carry no id and
+ * the API mints one, which is what keeps ids unique per account instead of imported from someone
+ * else's.
+ */
+export function toSettingsPatch(file, current = {}) {
+  const patch = {};
+  const existing = Array.isArray(current.agentCodingBackends) ? current.agentCodingBackends : [];
+  const idFor = (kind, url) =>
+    existing.find(
+      (r) => r?.id && r.kind === kind && clean(r.url).toLowerCase() === clean(url).toLowerCase(),
+    )?.id ?? "";
+  if (file.backends.length) {
+    patch.agentCodingBackends = file.backends.map((b) => {
+      const id = idFor(b.kind, b.url);
+      return {
+        ...(id ? { id } : {}),
+        kind: b.kind,
+        url: b.url,
+        defaultModel: b.defaultModel,
+        models: b.models,
+        enabled: b.enabled,
+      };
+    });
+  }
+  if (file.agentModel.url) patch.agentModelUrl = file.agentModel.url;
+  if (file.agentModel.name) patch.agentModelName = file.agentModel.name;
+  return patch;
+}