@tiens.nguyen/gonext-local-worker 1.0.337 → 1.0.346

package/daemon-control.mjs

@@ -0,0 +1,228 @@
+// Worker-daemon lifecycle for the gonext CLI (task #127, Phase 2). Lets a plain terminal
+// keep the polling worker running WITHOUT the GoTerminal desktop app: `gonext-local-worker
+// start|stop|status|logs`, and `gonext` (the REPL) auto-ensures it on startup.
+//
+// BC4 (task #127): NEVER double-spawn. A second polling daemon would race the first for
+// jobs. We detect an already-running daemon two ways — our own pidfile AND a `ps` scan that
+// also catches a daemon started by GoTerminal or by hand (which never wrote our pidfile) —
+// and refuse to start when either says one is alive.
+import { spawn, execFile } from "node:child_process";
+import { readFile, writeFile, unlink, mkdir, open, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DIR = join(homedir(), ".gonext");
+export const PID_FILE = join(DIR, "worker.pid");
+export const LOG_FILE = join(DIR, "worker.log");
+const LOCK_FILE = join(DIR, "worker.start.lock");
+const LOCK_STALE_MS = 30_000; // a lock older than this is from a crashed start → steal it
+const DAEMON_SCRIPT = fileURLToPath(new URL("./gonext-local-worker.mjs", import.meta.url));
+
+// Any cmdline containing one of these is a SUBCOMMAND invocation (login, start, …), not the
+// polling daemon — so it must not be mistaken for a running worker in the ps scan.
+const SUBCOMMANDS = [
+  "login", "set", "start", "stop", "status", "logs", "restart",
+  "ws-ping-test", "simulate-chat", "embed", "workspace",
+];
+
+function pidAlive(pid) {
+  if (!pid || !Number.isFinite(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM = the process exists but we can't signal it (still "alive" for our purposes).
+    return e && e.code === "EPERM";
+  }
+}
+
+function psList() {
+  return new Promise((resolve) => {
+    execFile(
+      "ps",
+      ["-A", "-o", "pid=,command="],
+      { maxBuffer: 8 * 1024 * 1024 },
+      (err, stdout) => {
+        if (err) return resolve([]);
+        const rows = [];
+        for (const line of String(stdout).split("\n")) {
+          const m = line.trim().match(/^(\d+)\s+(.*)$/);
+          if (m) rows.push({ pid: Number(m[1]), cmd: m[2] });
+        }
+        resolve(rows);
+      }
+    );
+  });
+}
+
+/**
+ * PIDs of polling worker daemons currently running (excluding THIS process and any
+ * subcommand invocation). Catches a daemon started by GoTerminal / by hand, not just ours.
+ */
+export async function findRunningDaemonPids() {
+  const rows = await psList();
+  const self = process.pid;
+  return rows
+    .filter((r) => r.pid !== self)
+    .filter((r) => /gonext-local-worker\.mjs(\s|$)/.test(r.cmd))
+    .filter((r) => !SUBCOMMANDS.some((sc) => new RegExp(`(\\s|/)${sc}(\\s|$)`).test(r.cmd)))
+    .map((r) => r.pid);
+}
+
+/**
+ * True when `pid` is actually a gonext polling daemon (not an unrelated process that reused
+ * the PID). Reads that one pid's command line — cheap and exact (review M1).
+ */
+function pidIsGonextDaemon(pid) {
+  if (!pid || !Number.isFinite(pid)) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    execFile("ps", ["-p", String(pid), "-o", "command="], (err, stdout) => {
+      const cmd = String(stdout || "").trim();
+      resolve(
+        !err &&
+          /gonext-local-worker\.mjs(\s|$)/.test(cmd) &&
+          !SUBCOMMANDS.some((sc) => new RegExp(`(\\s|/)${sc}(\\s|$)`).test(cmd))
+      );
+    });
+  });
+}
+
+async function readPidFile() {
+  try {
+    const n = Number(String(await readFile(PID_FILE, "utf8")).trim());
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * { running, pids, pidFilePid }. The `ps` scan is the primary signal. The pidfile is trusted
+ * ONLY after VERIFYING that its PID is genuinely a gonext daemon (review M1) — this both
+ * rescues the case where the full-table scan missed it and rejects a stale pidfile whose PID
+ * was reused by an unrelated process (which would otherwise wrongly suppress auto-start).
+ */
+export async function daemonStatus() {
+  const [pids, pidFilePid] = await Promise.all([findRunningDaemonPids(), readPidFile()]);
+  const pidFileIsDaemon =
+    pidFilePid != null && (pids.includes(pidFilePid) || (await pidIsGonextDaemon(pidFilePid)));
+  const allPids = pidFileIsDaemon && !pids.includes(pidFilePid) ? [...pids, pidFilePid] : pids;
+  return {
+    running: allPids.length > 0,
+    pids: allPids,
+    pidFilePid: pidFileIsDaemon ? pidFilePid : null,
+  };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Acquire an exclusive single-flight lock over the check→spawn window (review L2). O_EXCL
+ * (`wx`) is atomic, so of two concurrent starts exactly one wins. A lock left by a crashed
+ * start is stolen once it's older than LOCK_STALE_MS so it can never wedge startup.
+ * Returns a handle whose .release() removes the lock, or null if another start holds it.
+ */
+async function acquireStartLock() {
+  await mkdir(DIR, { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fh = await open(LOCK_FILE, "wx");
+      await fh.writeFile(String(process.pid), "utf8");
+      return {
+        release: async () => {
+          await fh.close().catch(() => {});
+          await unlink(LOCK_FILE).catch(() => {});
+        },
+      };
+    } catch (e) {
+      if (!e || e.code !== "EEXIST") throw e;
+      // Held by someone else — steal it only if it's stale (a crashed start), then retry.
+      let age = 0;
+      try {
+        age = Date.now() - (await stat(LOCK_FILE)).mtimeMs;
+      } catch {
+        age = LOCK_STALE_MS + 1; // vanished between EEXIST and stat → treat as free
+      }
+      if (age > LOCK_STALE_MS) {
+        await unlink(LOCK_FILE).catch(() => {});
+        continue; // retry the atomic create
+      }
+      return null; // a fresh lock → another start is genuinely in progress
+    }
+  }
+  return null;
+}
+
+/**
+ * Start the polling daemon DETACHED (survives the launching shell, logs to ~/.gonext/
+ * worker.log). No-op when one is already running (BC4). Concurrency-safe (L2): a lock
+ * serializes the check→spawn window so two simultaneous starts can't both spawn.
+ * Returns { started, pid?, pids }.
+ */
+export async function startDaemon() {
+  // Fast path: already running → no lock needed.
+  const pre = await daemonStatus();
+  if (pre.running) return { started: false, ...pre };
+  const lock = await acquireStartLock();
+  if (!lock) {
+    // A concurrent start holds the lock — let it win, then report the resulting state.
+    await sleep(700);
+    const s = await daemonStatus();
+    return { started: false, ...s };
+  }
+  try {
+    // Re-check UNDER the lock — the winner of a race must see the loser's daemon if it
+    // spawned in the gap (and vice-versa this is where the second caller no-ops).
+    const status = await daemonStatus();
+    if (status.running) return { started: false, ...status };
+    const out = await open(LOG_FILE, "a");
+    try {
+      const child = spawn(process.execPath, [DAEMON_SCRIPT], {
+        detached: true,
+        stdio: ["ignore", out.fd, out.fd],
+        env: process.env,
+      });
+      await writeFile(PID_FILE, String(child.pid ?? ""), "utf8");
+      child.unref();
+      return { started: true, pid: child.pid, pids: [] };
+    } finally {
+      await out.close();
+    }
+  } finally {
+    await lock.release();
+  }
+}
+
+/** Stop every running daemon (ours + any ps-found) and clear the pidfile. */
+export async function stopDaemon() {
+  const status = await daemonStatus();
+  const targets = new Set(status.pids);
+  if (status.pidFilePid) targets.add(status.pidFilePid);
+  let killed = 0;
+  for (const pid of targets) {
+    try {
+      process.kill(pid, "SIGTERM");
+      killed++;
+    } catch {
+      /* already gone */
+    }
+  }
+  try {
+    await unlink(PID_FILE);
+  } catch {
+    /* no pidfile */
+  }
+  return { killed };
+}
+
+/** Last `n` lines of the daemon log (empty string when none yet). */
+export async function tailLog(n = 40) {
+  try {
+    const txt = await readFile(LOG_FILE, "utf8");
+    const lines = txt.split("\n");
+    return lines.slice(Math.max(0, lines.length - n)).join("\n");
+  } catch {
+    return "";
+  }
+}

package/device-login.mjs

@@ -0,0 +1,141 @@
+// Device-pairing login for the gonext CLI (task #127, Phase 1). Shared by both bins
+// (gonext-local-worker.mjs and gonext-repl.mjs) so `gonext login` and the first-run
+// auto-prompt use the exact same flow. No secrets live here — the CLI obtains a worker key
+// only after an authenticated human approves in the browser.
+import { execFile } from "node:child_process";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import dotenv from "dotenv";
+
+export const DEFAULT_API_BASE = "https://chat-api-v2.gomarsic.cc";
+const ENV_FILE = join(homedir(), ".gonext", "worker.env");
+const POLL_INTERVAL_MS = 2500;
+const POLL_TIMEOUT_MS = 10 * 60_000; // matches the server's pairing TTL
+
+/** True when worker.env already has BOTH a key and an API base (task #127 BC1a). */
+export async function hasWorkerConfig() {
+  try {
+    const parsed = dotenv.parse(await readFile(ENV_FILE, "utf8"));
+    return Boolean(
+      String(parsed.GONEXT_WORKER_KEY ?? "").trim() &&
+        String(parsed.GONEXT_API_BASE ?? "").trim()
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Write ~/.gonext/worker.env, preserving any existing GONEXT_POLL_MS. */
+async function writeWorkerEnv(apiBase, workerKey) {
+  let pollMs = "500";
+  try {
+    const prev = dotenv.parse(await readFile(ENV_FILE, "utf8"));
+    if (String(prev.GONEXT_POLL_MS ?? "").trim()) pollMs = String(prev.GONEXT_POLL_MS).trim();
+  } catch {
+    /* first-time write */
+  }
+  await mkdir(join(homedir(), ".gonext"), { recursive: true });
+  await writeFile(
+    ENV_FILE,
+    `GONEXT_API_BASE=${apiBase.replace(/\/+$/, "")}\nGONEXT_WORKER_KEY=${workerKey}\nGONEXT_POLL_MS=${pollMs}\n`,
+    { encoding: "utf8", mode: 0o600 }
+  );
+  return ENV_FILE;
+}
+
+function openBrowser(url) {
+  const cmd =
+    platform() === "darwin" ? "open" : platform() === "win32" ? "start" : "xdg-open";
+  try {
+    execFile(cmd, [url], () => {}); // best-effort; the URL is also printed
+  } catch {
+    /* the user can open it manually */
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Run the browser device-pairing flow and write worker.env on success.
+ *
+ * Returns { apiBase, workerKey, envFile } on success.
+ * Throws Error with .code === "PAIRING_UNSUPPORTED" when the API has no /pair routes
+ *   (404), so callers can fall back to the manual `set` path (task #127 BC7).
+ * Throws Error with .code === "PAIRING_TIMEOUT" / "PAIRING_EXPIRED" otherwise.
+ *
+ * `log` is an injectable printer (defaults to console.log) so the REPL can style it.
+ */
+export async function deviceLogin({ apiBase = DEFAULT_API_BASE, log = console.log } = {}) {
+  const base = String(apiBase || DEFAULT_API_BASE).trim().replace(/\/+$/, "");
+  let start;
+  try {
+    const res = await fetch(`${base}/api/pair/start`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ apiBase: base }),
+    });
+    if (res.status === 404) {
+      const err = new Error("This API does not support CLI login (device pairing).");
+      err.code = "PAIRING_UNSUPPORTED";
+      throw err;
+    }
+    if (!res.ok) {
+      throw new Error(`pairing start failed (HTTP ${res.status})`);
+    }
+    start = await res.json();
+  } catch (e) {
+    if (e && e.code === "PAIRING_UNSUPPORTED") throw e;
+    // A network failure to a base that has no /pair yet also can't pair — surface as
+    // unsupported so the caller offers manual setup rather than looping.
+    const err = new Error(
+      `Could not reach ${base} to start login: ${e instanceof Error ? e.message : e}`
+    );
+    err.code = "PAIRING_UNSUPPORTED";
+    throw err;
+  }
+
+  const { pairId, pairCode, verificationUrlBase } = start;
+  const url = `${verificationUrlBase || `${base}/link`}?code=${encodeURIComponent(pairCode)}`;
+  log("");
+  log("  To connect this machine, sign in and approve this code in your browser:");
+  log("");
+  log(`      code:  ${pairCode}`);
+  log(`      url:   ${url}`);
+  log("");
+  log("  (opening your browser… if it doesn't, paste the url above)");
+  log("");
+  openBrowser(url);
+
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    let poll;
+    try {
+      const res = await fetch(`${base}/api/pair/poll`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ pairId }),
+      });
+      if (!res.ok) continue; // transient — keep polling
+      poll = await res.json();
+    } catch {
+      continue; // network blip — keep polling
+    }
+    if (poll.status === "approved" && poll.workerApiKey) {
+      const finalBase = String(poll.apiBase || base).trim().replace(/\/+$/, "");
+      const envFile = await writeWorkerEnv(finalBase, poll.workerApiKey);
+      log(`  ✓ Linked. Saved ${envFile}`);
+      return { apiBase: finalBase, workerKey: poll.workerApiKey, envFile };
+    }
+    if (poll.status === "expired") {
+      const err = new Error("Login code expired before it was approved. Run `gonext login` again.");
+      err.code = "PAIRING_EXPIRED";
+      throw err;
+    }
+    // "pending" / "consumed" → keep waiting (consumed by a racing poll is unlikely).
+  }
+  const err = new Error("Login timed out waiting for browser approval.");
+  err.code = "PAIRING_TIMEOUT";
+  throw err;
+}

package/gonext-local-worker.mjs

@@ -61,7 +61,11 @@ gonext-local-worker
 
 Usage:
   gonext-local-worker
+  gonext-local-worker login [--api-base <url>]   # browser sign-in → writes ~/.gonext/worker.env
   gonext-local-worker set <workerKey> [--api-base <url>]
+  gonext-local-worker start | stop | status | restart   # run the polling daemon in the background
+  gonext-local-worker logs [--lines N]                  # tail the background daemon log
+  gonext-local-worker doctor                            # download + start the base chat model if needed
   gonext-local-worker ws-ping-test   # POST /api/worker/ws-ping-test (needs GONEXT_* env)
   gonext-local-worker simulate-chat [text...]   # claim next chat job, fake reply (stop normal worker first)
 
@@ -127,6 +131,108 @@ if (args[0] === "set") {
   await setConfig();
   process.exit(0);
 }
+if (args[0] === "login") {
+  // Task #127, Phase 1: browser device-pairing → writes worker.env. `--api-base` overrides
+  // which API to pair against (defaults to the production API).
+  const { deviceLogin, DEFAULT_API_BASE } = await import("./device-login.mjs");
+  const apiBaseFlag = parseFlag("--api-base");
+  try {
+    await deviceLogin({
+      apiBase:
+        apiBaseFlag ||
+        (process.env.GONEXT_API_BASE ?? "").trim() ||
+        DEFAULT_API_BASE,
+    });
+    process.exit(0);
+  } catch (e) {
+    console.error(`[gonext-worker] login failed: ${e instanceof Error ? e.message : e}`);
+    if (e && e.code === "PAIRING_UNSUPPORTED") {
+      console.error(
+        "Set it manually instead: gonext-local-worker set <workerKey> --api-base <url>"
+      );
+    }
+    process.exit(1);
+  }
+}
+// Task #127, Phase 2: daemon lifecycle from a plain terminal (no GoTerminal). start runs
+// the polling worker DETACHED; stop/status/logs manage it. All no-op-safe (BC4: never
+// double-spawn a second poller).
+if (["start", "stop", "status", "logs", "restart"].includes(args[0])) {
+  const ctl = await import("./daemon-control.mjs");
+  if (args[0] === "status") {
+    const s = await ctl.daemonStatus();
+    if (s.running) {
+      const who = s.pidFilePid ? `pid ${s.pidFilePid}` : `pid ${s.pids.join(", ")}`;
+      console.log(`[gonext-worker] daemon RUNNING (${who}). Logs: ${ctl.LOG_FILE}`);
+    } else {
+      console.log("[gonext-worker] daemon is NOT running. Start it with: gonext-local-worker start");
+    }
+    process.exit(0);
+  }
+  if (args[0] === "logs") {
+    const n = Number(parseFlag("--lines")) || 60;
+    const txt = await ctl.tailLog(n);
+    console.log(txt || `(no daemon log yet at ${ctl.LOG_FILE})`);
+    process.exit(0);
+  }
+  if (args[0] === "stop") {
+    const { killed } = await ctl.stopDaemon();
+    console.log(killed ? `[gonext-worker] stopped ${killed} daemon process(es).` : "[gonext-worker] no daemon was running.");
+    process.exit(0);
+  }
+  // start / restart both ensure exactly one daemon is running, config permitting.
+  if (args[0] === "restart") await ctl.stopDaemon();
+  // Don't spawn a daemon that would just exit(1): require a complete worker.env first.
+  const { hasWorkerConfig } = await import("./device-login.mjs");
+  if (!(await hasWorkerConfig())) {
+    console.error(
+      "[gonext-worker] not configured — run `gonext-local-worker login` (or `set`) first."
+    );
+    process.exit(1);
+  }
+  const r = await ctl.startDaemon();
+  if (r.started) {
+    console.log(`[gonext-worker] daemon started (pid ${r.pid}). Logs: ${ctl.LOG_FILE}`);
+  } else {
+    console.log("[gonext-worker] daemon already running — nothing to do.");
+  }
+  process.exit(0);
+}
+// Task #127, Phase 3: ensure the base chat model is downloaded + running (no GoTerminal).
+if (args[0] === "doctor") {
+  const { hasWorkerConfig } = await import("./device-login.mjs");
+  if (!(await hasWorkerConfig())) {
+    console.error("[gonext-worker] not configured — run `gonext-local-worker login` first.");
+    process.exit(1);
+  }
+  const { runDoctor } = await import("./model-doctor.mjs");
+  const rl0 = (await import("node:readline")).createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+  const confirm = (q, defYes) =>
+    // Non-interactive: never download GBs / start a server unattended — probe + advise only.
+    interactive
+      ? new Promise((res) =>
+          rl0.question(`  ${q} [${defYes ? "Y/n" : "y/N"}] `, (a) => {
+            const s = a.trim().toLowerCase();
+            res(s ? s === "y" || s === "yes" : Boolean(defYes));
+          })
+        )
+      : Promise.resolve(false);
+  try {
+    await runDoctor({
+      apiBase: String(process.env.GONEXT_API_BASE ?? "").trim(),
+      workerKey: String(process.env.GONEXT_WORKER_KEY ?? "").trim(),
+      log: (s) => console.log(s),
+      confirm,
+    });
+  } finally {
+    rl0.close();
+  }
+  process.exit(0);
+}
 
 const apiBase = String(process.env.GONEXT_API_BASE ?? "")
   .trim()
@@ -3068,6 +3174,32 @@ async function pollOnce() {
 }
 
 async function main() {
+  // Task #127, Phase 2: record our own pidfile so `status`/`stop` find us whether we were
+  // launched by `start` (detached), by the REPL's auto-ensure, or run in the foreground.
+  // Best-effort; a failure here must not stop the worker from polling.
+  try {
+    const { PID_FILE } = await import("./daemon-control.mjs");
+    const { unlinkSync } = await import("node:fs");
+    await writeFile(PID_FILE, String(process.pid), "utf8");
+    const cleanup = () => {
+      try {
+        unlinkSync(PID_FILE);
+      } catch {
+        /* already gone */
+      }
+    };
+    process.on("SIGTERM", () => {
+      cleanup();
+      process.exit(0);
+    });
+    process.on("SIGINT", () => {
+      cleanup();
+      process.exit(0);
+    });
+    process.on("exit", cleanup);
+  } catch {
+    /* pidfile is a convenience; polling works without it */
+  }
   console.log(
     `[gonext-worker] polling ${apiBase} every ${pollMs}ms (local_health concurrency=${localHealthConcurrency})`
   );

package/gonext-repl.mjs

@@ -170,15 +170,42 @@ if (argv.includes("-v") || argv.includes("--verbose")) {
 // ---------- auth: worker key + API base from ~/.gonext/worker.env ----------
 dotenv.config({ path: ENV_FILE });
 dotenv.config();
-const workerKey = String(process.env.GONEXT_WORKER_KEY ?? "").trim();
-const apiBase = String(process.env.GONEXT_API_BASE ?? "").trim().replace(/\/+$/, "");
+let workerKey = String(process.env.GONEXT_WORKER_KEY ?? "").trim();
+let apiBase = String(process.env.GONEXT_API_BASE ?? "").trim().replace(/\/+$/, "");
+// Task #127 (BC1a): "configured" = BOTH key AND api-base present. When either is missing,
+// first-run login instead of a dead end — but ONLY interactively; a piped/CI invocation
+// still fails fast with guidance (so scripts don't hang on a browser prompt). An EXISTING
+// user with a full worker.env skips all of this and behaves exactly as before (BC1).
 if (!workerKey || !apiBase) {
-  console.error(
-    red("gonext: no worker key / API base found.") +
-      `\nExpected ${ENV_FILE} (written by the Installation Wizard), or configure manually:` +
-      "\n  gonext-local-worker set <workerKey> --api-base https://chat-api-v2.gomarsic.cc"
-  );
-  process.exit(1);
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    try {
+      const { deviceLogin, DEFAULT_API_BASE } = await import("./device-login.mjs");
+      console.log(
+        dim("gonext: first-time setup — let's connect this machine to your account.")
+      );
+      const r = await deviceLogin({
+        apiBase: apiBase || DEFAULT_API_BASE,
+        log: (s) => console.log(s),
+      });
+      workerKey = r.workerKey;
+      apiBase = r.apiBase;
+    } catch (e) {
+      console.error(red(`gonext: login failed: ${e instanceof Error ? e.message : e}`));
+      if (e && e.code === "PAIRING_UNSUPPORTED") {
+        console.error(
+          "Configure manually: gonext-local-worker set <workerKey> --api-base https://chat-api-v2.gomarsic.cc"
+        );
+      }
+      process.exit(1);
+    }
+  } else {
+    console.error(
+      red("gonext: no worker key / API base found.") +
+        `\nRun ${cyan("gonext-local-worker login")} to sign in, or configure manually:` +
+        "\n  gonext-local-worker set <workerKey> --api-base https://chat-api-v2.gomarsic.cc"
+    );
+    process.exit(1);
+  }
 }
 
 // Line intake: attach the listener IMMEDIATELY so lines that arrive while startup
@@ -350,6 +377,9 @@ function slashRestoreHistory() {
 // which the earlier relative-cursor overlay hit whenever readline refreshed or the
 // menu was near the bottom of the screen and scrolled).
 let slashOverlayActive = false;
+// While true, readline's echo + line-refresh are muted so a typed secret (an API key) never
+// reaches the terminal or scrollback (task #127 — see askSecret + the _writeToOutput guards).
+let secretInput = false;
 
 // Visible width of PROMPT (">> ") — used to put the caret back on the input line by
 // COLUMN, since the string itself carries color escapes that don't occupy cells.
@@ -581,6 +611,20 @@ const ask = async (q) => {
 // re-uses the default. This replaces a fragile `(await ask()) || "y"` idiom where any
 // leftover character (a stray escape byte, a stray space) silently defeated the
 // default — the reported "[Y/n] + Enter registered as No" bug.
+// Masked prompt for a secret (an API key). Mutes readline's echo/refresh (secretInput)
+// so the typed value never hits the terminal or scrollback (task #127). Returns "" on a
+// bare Enter (skip).
+const askSecret = async (q) => {
+  process.stdout.write(q);
+  secretInput = true;
+  try {
+    const a = await nextLine();
+    return (a ?? "").trim();
+  } finally {
+    secretInput = false;
+    process.stdout.write("\n"); // the muted Enter left the cursor mid-line
+  }
+};
 const askYesNo = async (question, defaultYes) => {
   const suffix = defaultYes ? " [Y/n] " : " [y/N] ";
   const raw = (await ask(question + suffix)).trim().toLowerCase();
@@ -741,6 +785,22 @@ async function addOutputTokens(cwd, delta) {
   }
 }
 
+// Save the agent coding-model API key (task #127): the terminal prompts for the Kimi K3 key
+// when the default cloud coder has none, and POSTs it here (worker-key authed). Returns true
+// on success. Best-effort — a failure just leaves the reminder for next startup.
+async function saveCodingKey(apiKey) {
+  try {
+    const r = await fetch(`${apiBase}/api/worker/coding-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
+      body: JSON.stringify({ apiKey }),
+    });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
 async function resetGlobalOutputTokens() {
   try {
     const r = await fetch(`${apiBase}/api/worker/output-tokens/reset-global`, {
@@ -1053,6 +1113,17 @@ async function fetchAgentPayload(messages) {
         "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 `gonext-local-worker login` to sign in again, or update it with " +
+          "`gonext-local-worker set <workerKey> --api-base <url>`."
+      );
+    }
     throw new Error(data?.error || `agent-payload failed (HTTP ${res.status})`);
   }
   return data;
@@ -1357,6 +1428,9 @@ rl._writeToOutput = (s) => {
   // slashOverlayActive: the slash-command overlay owns drawing (input line + menu), so
   // readline's own echo must be swallowed or it fights the overlay (bug #109).
   if (following || listPickerActive || slashOverlayActive) return;
+  // secretInput (task #127): the user is typing an API key — swallow the echo so it never
+  // appears in the terminal or scrollback.
+  if (secretInput) return;
   if (_origWriteToOutput) _origWriteToOutput(s);
   else process.stdout.write(s);
 };
@@ -1369,6 +1443,7 @@ rl._refreshLine = () => {
   // Suppress readline's line refresh (which does clearScreenDown → would wipe our menu)
   // while the slash overlay owns the screen. We redraw the input line ourselves (#109).
   if (following || listPickerActive || slashOverlayActive) return;
+  if (secretInput) return; // don't redraw the typed key (task #127)
   if (_origRefreshLine) _origRefreshLine();
 };
 
@@ -2198,6 +2273,19 @@ async function runAgentTurn(history) {
 // ---------- REPL ----------
 async function main() {
   console.log(cyan("GoNext agent REPL") + dim(` v${REPL_VERSION} · API ${apiBase} · key ${workerKey.slice(0, 8)}…`));
+  // Task #127, Phase 2: the REPL enqueues jobs that the polling DAEMON executes, so ensure
+  // one is running — no GoTerminal needed. Idempotent + BC4-safe: startDaemon() no-ops when
+  // a daemon (ours, GoTerminal's, or a manual one) is already alive. Best-effort; a failure
+  // here shouldn't block the REPL (the user can `gonext-local-worker start` manually).
+  try {
+    const ctl = await import("./daemon-control.mjs");
+    const r = await ctl.startDaemon();
+    if (r.started) {
+      console.log(dim(`  started background worker (pid ${r.pid}) · logs ${ctl.LOG_FILE}`));
+    }
+  } catch {
+    /* non-fatal — jobs just won't run until a daemon is started */
+  }
   await ensureWorkspace();
   // Restore this folder's remembered auto-test + deploy-target so the banner + agent-ask
   // reflect them (both survive a fresh terminal in the same project).
@@ -2239,8 +2327,76 @@ async function main() {
           (selectedServer ? ` · deploy: ${selectedServer.name} (${selectedServer.user}@${selectedServer.host})` : "")
       ) + (sessionTestAuto ? "" : dim(" (/test-auto to enable)"))
     );
+    // Task #127, Phase 3: if the base chat model server isn't answering, offer to set it up
+    // (download + start mlx_lm.server). BC3: only runs when NOTHING answers — an already-up
+    // model is left untouched, and this is skipped entirely. Interactive TTYs only.
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      try {
+        const md = await import("./model-doctor.mjs");
+        const chatUrl = String(p.agentBaseURL || "").trim() || `http://127.0.0.1:${md.DEFAULT_CHAT_PORT}`;
+        if (!(await md.probeModelServer(chatUrl))) {
+          console.log(
+            dim(`\ngonext: the chat model server (${md.modelRoot(chatUrl)}) isn't responding.`)
+          );
+          const go = await askYesNo("Set up the base model now (download if needed + start)?", true);
+          if (go) {
+            await md.runDoctor({
+              apiBase,
+              workerKey,
+              log: (s) => console.log(s),
+              confirm: (q, defYes) => askYesNo(q, defYes),
+            });
+          } else {
+            console.log(dim("  Skipped. Run `gonext-local-worker doctor` anytime to set it up.\n"));
+          }
+        }
+      } catch {
+        /* doctor is best-effort — never block the REPL from starting */
+      }
+      // Task #127: the default coding model is a cloud coder (Kimi K3) with no API key yet.
+      // Ask for it. If skipped, the account stays in this "waiting" state (server-side:
+      // coder configured, no key) and we ASK AGAIN on every startup until it's set. Until
+      // then the agent falls back to the chat model for coding, so the terminal still works.
+      if (p.codingKeyMissing) {
+        const model = String(p.codingKeyModel || "the coding model").trim();
+        console.log(
+          dim(`\ngonext: your agent coding model (`) + cyan(model) + dim(`) needs an API key.`)
+        );
+        console.log(
+          dim("  Until it's set, coding falls back to your local model. Enter the key now,")
+        );
+        console.log(dim("  or press Enter to skip (I'll ask again next time).\n"));
+        const key = await askSecret(`  ${model} API key: `);
+        if (key) {
+          const ok = await saveCodingKey(key);
+          console.log(
+            ok
+              ? green(`  ✓ saved — ${model} is now your coding model.\n`)
+              : red("  couldn't save the key — try again next start, or set it in web Settings → Agent.\n")
+          );
+        } else {
+          console.log(
+            dim("  ⏳ waiting for your ") + cyan(model) + dim(" API key — I'll ask again next time.\n")
+          );
+        }
+      }
+    }
   } catch (err) {
-    console.error(red(`gonext: ${err.message}`));
+    // Task #127 (zero-config): a freshly-paired account is seeded with a default local
+    // agent model, so this "no model" path is normally unreachable. An account paired
+    // BEFORE that change has none — point them at re-login, which now seeds it, rather than
+    // only the raw web-Settings instruction.
+    if (/no agent model configured/i.test(err?.message ?? "")) {
+      console.error(
+        red("gonext: no agent model is configured for your account yet.") +
+          dim(
+            "\n  Run `gonext-local-worker login` to re-connect — new logins set up a local" +
+              "\n  default automatically. Or set the Agent model URL in the web app → Settings → Agent."
+          )
+      );
+    } else {
+      console.error(red(`gonext: ${err.message}`));
+    }
     process.exit(1);
   }
   console.log(dim("Ask about this repo. Type / to see commands (Tab completes). Ctrl-C aborts a running turn.\n"));

package/model-doctor.mjs

@@ -0,0 +1,571 @@
+// Model bootstrap for the gonext CLI (task #127, Phase 3). Ensures the base CHAT model
+// (mlx_lm.server) is downloaded and RUNNING so a fresh Mac can answer without GoTerminal or
+// the Wizard doing it. The agent CODE model (Ollama) is probed + guided, not auto-pulled.
+//
+// BC3 (task #127): NEVER touch a model that is already running. The doctor probes first and
+// does nothing when a server answers — it will not kill, restart, re-port, or re-download a
+// model the user already runs (many run mlx_lm.server themselves on 8090, or point at a
+// remote box). Downloads happen only when the model dir is genuinely absent AND the user
+// opts in.
+import { spawn, execFile } from "node:child_process";
+import { open, mkdir, readdir, writeFile } from "node:fs/promises";
+import { homedir, totalmem } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Minimum RAM to run the default 14B-4bit chat model comfortably on Apple Silicon.
+const MIN_CHAT_RAM_GB = 16;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+// The RAG embedding model + server (task #127 — parity with the Wizard's model-embed step).
+// EMBED_PID_FILE / EMBED_LOG_FILE (which need DIR) are defined below, after DIR.
+export const EMBED_REPO = "mlx-community/Qwen3-Embedding-8B-4bit-DWQ";
+export const EMBED_DIR = join(homedir(), "mlx-models", "Qwen3-Embedding-8B-4bit-DWQ");
+export const EMBED_PORT = 8085;
+const EMBED_SCRIPT = fileURLToPath(new URL("./gonext_mlx_embed.py", import.meta.url));
+
+/** The python3 the worker uses to run its agent / model tooling (mirrors the daemon). */
+function python3Bin() {
+  return (
+    (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "").trim() ||
+    "python3"
+  );
+}
+
+/** True when `python3 -c "import <mod>"` succeeds — i.e. the module is installed. */
+function pyHasModule(mod) {
+  return new Promise((resolve) => {
+    execFile(python3Bin(), ["-c", `import ${mod}`], (err) => resolve(!err));
+  });
+}
+
+/** pip install -U <pkgs> with live progress (inherit stdio). Rejects on non-zero exit. */
+function pipInstall(pkgs, log) {
+  log(`  installing ${pkgs.join(" ")} … (pip, this can take a minute)`);
+  return new Promise((resolve, reject) => {
+    const child = spawn(python3Bin(), ["-m", "pip", "install", "-U", ...pkgs], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error(`pip install ${pkgs.join(" ")} exited ${code}`))
+    );
+    child.on("error", reject);
+  });
+}
+
+/**
+ * The yellow RAM notice shown before the multi-GB model download (user request): the
+ * default 14B-4bit model wants a Mac with ≥16 GB. When the machine has less, add a plain
+ * line stating its detected amount. Pure (RAM passed in) so it's unit-testable.
+ * Returns already-colored lines; empty array only if `repo` is falsy.
+ */
+export function chatRamWarningLines(repo, totalBytes) {
+  if (!repo) return [];
+  const ramGb = Math.round((Number(totalBytes) || 0) / 1024 ** 3);
+  const name = String(repo).split("/").pop();
+  const out = [
+    yellow(`  ⚠ ${name} needs a Mac with at least ${MIN_CHAT_RAM_GB} GB of RAM to run well.`),
+  ];
+  if (ramGb > 0 && ramGb < MIN_CHAT_RAM_GB) {
+    out.push(
+      yellow(
+        `    This machine has about ${ramGb} GB — the model may run very slowly or fail to load.`
+      )
+    );
+  }
+  return out;
+}
+
+const DIR = join(homedir(), ".gonext");
+export const MODEL_PID_FILE = join(DIR, "model.pid");
+export const MODEL_LOG_FILE = join(DIR, "model.log");
+const EMBED_PID_FILE = join(DIR, "embed.pid");
+const EMBED_LOG_FILE = join(DIR, "embed.log");
+
+// The default base chat model (task #127 decision): matches the Wizard's model-chat step.
+export const DEFAULT_CHAT_REPO = "mlx-community/Qwen3-14B-4bit";
+export const DEFAULT_CHAT_DIR = join(homedir(), "mlx-models", "Qwen3-14B-4bit");
+export const DEFAULT_CHAT_PORT = 8082;
+
+// ---- pure helpers (unit-tested offline) -------------------------------------------------
+
+/** The port from a base URL, or null. "http://127.0.0.1:8082/v1" → 8082. */
+export function parsePort(baseUrl) {
+  try {
+    const u = new URL(String(baseUrl || "").includes("://") ? baseUrl : `http://${baseUrl}`);
+    if (u.port) return Number(u.port);
+    return u.protocol === "https:" ? 443 : 80;
+  } catch {
+    const m = String(baseUrl || "").match(/:(\d{2,5})(?:\/|$)/);
+    return m ? Number(m[1]) : null;
+  }
+}
+
+/** True when the URL points at this machine (loopback/LAN) — only then can we START it. */
+export function isLocalModelUrl(baseUrl) {
+  let host = "";
+  try {
+    host = new URL(String(baseUrl || "").includes("://") ? baseUrl : `http://${baseUrl}`)
+      .hostname.toLowerCase()
+      .replace(/\.$/, "");
+  } catch {
+    return false;
+  }
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  if (!host) return false;
+  if (["localhost", "0.0.0.0", "::", "::1"].includes(host)) return true;
+  if (/^127(\.\d{1,3}){3}$/.test(host)) return true;
+  if (
+    /^(10(\.\d{1,3}){3}|192\.168(\.\d{1,3}){2}|172\.(1[6-9]|2\d|3[01])(\.\d{1,3}){2}|169\.254(\.\d{1,3}){2})$/.test(
+      host
+    )
+  )
+    return true;
+  if (host.includes(":") && (host.startsWith("fe80:") || /^f[cd]/.test(host))) return true;
+  if (/\.(local|localdomain|lan|home|internal)$/.test(host)) return true;
+  return !host.includes(".") && !host.includes(":");
+}
+
+/** Normalize a base URL to its root (strip a trailing /v1 and slashes). */
+export function modelRoot(baseUrl) {
+  return String(baseUrl || "").replace(/\/+$/, "").replace(/\/v1$/i, "");
+}
+
+// ---- probing + process control ----------------------------------------------------------
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** True when an OpenAI-compatible model server answers GET {base}/v1/models. */
+export async function probeModelServer(baseUrl, { timeoutMs = 3000 } = {}) {
+  const root = modelRoot(baseUrl);
+  if (!root) return false;
+  try {
+    const res = await fetch(`${root}/v1/models`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function which(cmd) {
+  return new Promise((resolve) => {
+    execFile("command", ["-v", cmd], { shell: "/bin/sh" }, (err, stdout) =>
+      resolve(!err && Boolean(String(stdout).trim()))
+    );
+  });
+}
+
+/** True when the model directory exists and is non-empty. */
+export async function modelDirReady(dir) {
+  try {
+    const entries = await readdir(dir);
+    return entries.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Start mlx_lm.server for `modelDir` on `port`, DETACHED (logs to model.log, pidfile). Waits
+ * until the server answers /v1/models (up to waitMs). No-op + { started:false } when a
+ * server already answers on that port (BC3). Returns { started, ready, pid?, reason? }.
+ */
+export async function startChatModelServer({ modelDir, port, waitMs = 120_000, log = () => {} }) {
+  const base = `http://127.0.0.1:${port}`;
+  if (await probeModelServer(base, { timeoutMs: 1500 })) {
+    return { started: false, ready: true, reason: "already-running" };
+  }
+  if (!(await which("mlx_lm.server"))) {
+    return {
+      started: false,
+      ready: false,
+      reason: "mlx_lm.server not found — install it: pip install mlx-lm",
+    };
+  }
+  await mkdir(DIR, { recursive: true });
+  const out = await open(MODEL_LOG_FILE, "a");
+  let pid;
+  try {
+    const child = spawn("mlx_lm.server", ["--model", modelDir, "--port", String(port)], {
+      detached: true,
+      stdio: ["ignore", out.fd, out.fd],
+      env: process.env,
+    });
+    pid = child.pid;
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(MODEL_PID_FILE, String(pid ?? ""), "utf8");
+    child.unref();
+  } finally {
+    await out.close();
+  }
+  log(`  starting mlx_lm.server (pid ${pid}) on port ${port} — waiting for it to load…`);
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    await sleep(2500);
+    if (await probeModelServer(base, { timeoutMs: 2000 })) {
+      return { started: true, ready: true, pid };
+    }
+  }
+  return {
+    started: true,
+    ready: false,
+    pid,
+    reason: `model server did not answer within ${Math.round(waitMs / 1000)}s (still loading? see ${MODEL_LOG_FILE})`,
+  };
+}
+
+/**
+ * Download an MLX model repo to a local dir via the Hugging Face CLI. Streams progress to
+ * the terminal (inherit stdio) because it's a multi-GB, several-minute step. Resolves
+ * { ok } / rejects with guidance when `hf` is missing.
+ */
+export async function downloadModel({ repo, dir, log = () => {} }) {
+  if (!(await which("hf"))) {
+    throw new Error(
+      "the Hugging Face CLI (hf) is required to download the model. Install it with: pip install huggingface_hub"
+    );
+  }
+  log(`  downloading ${repo} → ${dir} (multi-GB, keep this open)…`);
+  return new Promise((resolve, reject) => {
+    const child = spawn("hf", ["download", repo, "--local-dir", dir], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("exit", (code) =>
+      code === 0 ? resolve({ ok: true }) : reject(new Error(`hf download exited ${code}`))
+    );
+    child.on("error", (e) => reject(e));
+  });
+}
+
+/** Fetch the account's resolved model config from /agent-payload (best-effort). */
+async function fetchModelConfig(apiBase, workerKey) {
+  try {
+    const res = await fetch(`${apiBase.replace(/\/+$/, "")}/api/worker/agent-payload`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
+      body: JSON.stringify({ messages: [{ role: "user", content: "ping" }] }),
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data?.payload ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The Phase-3 orchestration (task #127). Ensures the base CHAT model is running (starting a
+ * local mlx_lm.server, downloading first if the dir is missing and the user opts in), and
+ * probes the CODE model, giving guidance for a remote one. BC3-safe throughout: an
+ * already-answering server is left untouched.
+ *
+ * `log(str)` prints; `confirm(question, defaultYes)→bool` gates the multi-GB download and
+ * the model-server start (non-interactive callers pass a confirm that returns false, so the
+ * doctor only PROBES + advises and never downloads/starts unattended).
+ */
+export async function runDoctor({ apiBase, workerKey, log, confirm }) {
+  const p = (await fetchModelConfig(apiBase, workerKey)) ?? {};
+
+  // Step 0: the agent's PYTHON deps must be present or every agent turn crashes at import
+  // — and the model download/start needs `hf`/`mlx-lm`. Ensure these FIRST (task #127:
+  // parity with the Wizard's pip-mlx-lm / pip-agent-libs / hf-cli steps). Fatal-ish: if the
+  // core framework is missing, say so, but keep going so the model steps still run.
+  const deps = await ensureAgentDeps({ log, confirm });
+
+  // Chat model: prefer the account's configured URL; fall back to the default local one.
+  const configuredChat = String(p.agentBaseURL || "").trim();
+  const chatUrl = configuredChat || `http://127.0.0.1:${DEFAULT_CHAT_PORT}`;
+  const chatPort = parsePort(chatUrl) || DEFAULT_CHAT_PORT;
+  // Review H2: never serve a model the account didn't configure. Only the KNOWN default is
+  // auto-downloadable; for a specifically-named other model we start its dir if present but
+  // won't substitute Qwen3-14B. "default_model" is the direct-URL sentinel (the loaded
+  // model), which we treat as the default. modelId empty (fresh account) → default too.
+  const modelId = String(p.agentModelId || "").trim();
+  const isDefaultModel =
+    !modelId || modelId === "default_model" || /qwen3-?14b/i.test(modelId);
+  const chatDir = isDefaultModel
+    ? DEFAULT_CHAT_DIR
+    : join(homedir(), "mlx-models", modelId.replace(/[^A-Za-z0-9._-]/g, "-"));
+  const chatRepo = isDefaultModel ? DEFAULT_CHAT_REPO : null; // null = not auto-downloadable
+
+  // The chat handling sets `chat` but never returns early — the code-model check below is
+  // independent and must run even when the user declines the chat-model setup.
+  let chat = "checked";
+  log("");
+  log("  Checking the base chat model…");
+  if (await probeModelServer(chatUrl)) {
+    log(`  ✓ chat model already running at ${modelRoot(chatUrl)} — leaving it alone.`);
+    chat = "already-running";
+  } else if (configuredChat && !isLocalModelUrl(chatUrl)) {
+    // Configured but REMOTE and not answering — we can't start a model on another machine.
+    log(`  ⚠ your chat model server (${modelRoot(chatUrl)}) isn't answering.`);
+    log("    It's remote, so start it there — this machine can't launch it.");
+    chat = "remote";
+  } else {
+    // Local (or unconfigured → default local): ensure the RIGHT model, then offer to start.
+    const dir = chatDir;
+    let dirReady = await modelDirReady(dir);
+    if (!dirReady && !chatRepo) {
+      // A specifically-named, non-default model we don't know how to fetch — DON'T
+      // substitute the default. Tell the user how to bring their own (review H2).
+      log(`  ⚠ your account uses the chat model "${modelId}", which isn't the built-in`);
+      log(`    default, so I can't auto-download it. Put it at ${dir} (or any dir) and run:`);
+      log(`      mlx_lm.server --model <that dir> --port ${chatPort}`);
+      chat = "unknown-model";
+    } else if (!dirReady) {
+      // Yellow RAM notice before the multi-GB download, THEN the confirm (user request).
+      for (const line of chatRamWarningLines(chatRepo, totalmem())) log(line);
+      const yes = await confirm(
+        `Download the base chat model ${chatRepo} (~8 GB) to ${dir}?`,
+        true
+      );
+      if (!yes) {
+        log("  Skipped. To do it yourself:");
+        log(`      hf download ${chatRepo} --local-dir ${dir}`);
+        log(`      mlx_lm.server --model ${dir} --port ${chatPort}`);
+        chat = "skipped";
+      } else {
+        try {
+          await downloadModel({ repo: chatRepo, dir, log });
+          dirReady = true;
+        } catch (e) {
+          log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+          chat = "download-failed";
+        }
+      }
+    }
+    if (dirReady && chat === "checked") {
+      const yes = await confirm(`Start the chat model server on port ${chatPort} now?`, true);
+      if (!yes) {
+        log(`  Skipped. Start it later: mlx_lm.server --model ${dir} --port ${chatPort}`);
+        chat = "not-started";
+      } else {
+        // Review M2: don't block the caller (the REPL) for a full cold model load — that's
+        // minutes. Wait only long enough to confirm the server launched and didn't crash
+        // (~20s); if it's still loading, say so and return. The first agent turn will wait
+        // for it. A missing binary / immediate exit still surfaces as an error.
+        const r = await startChatModelServer({
+          modelDir: dir,
+          port: chatPort,
+          waitMs: 20_000,
+          log,
+        });
+        if (r.ready) {
+          log(`  ✓ chat model is up on port ${chatPort}.`);
+          chat = "started";
+        } else if (r.started) {
+          log(`  … chat model is loading in the background on port ${chatPort} (large model —`);
+          log(`    the first answer may take a minute). Watch it: gonext-local-worker logs`);
+          chat = "loading";
+        } else {
+          log(`  ⚠ ${r.reason}`);
+          chat = "start-failed";
+        }
+      }
+    }
+  }
+
+  // Code model (Ollama): probe + guide only — never auto-pull (BC3 + bounded scope).
+  const codeUrl = String(p.codingBaseURL || "").trim();
+  const codeModel = String(p.codingModelId || "").trim();
+  if (codeUrl) {
+    log("");
+    log("  Checking the agent code model…");
+    if (await probeModelServer(codeUrl)) {
+      log(`  ✓ code model server is up at ${modelRoot(codeUrl)}.`);
+    } else if (isLocalModelUrl(codeUrl)) {
+      log(`  ⚠ local code model server (${modelRoot(codeUrl)}) isn't answering.`);
+      if (codeModel) log(`    Start Ollama and pull it:  ollama serve &  ollama pull ${codeModel}`);
+    } else {
+      log(`  ⚠ your code model runs on a remote server (${modelRoot(codeUrl)}) that isn't`);
+      log(`    answering. Start it there${codeModel ? ` (ollama pull ${codeModel})` : ""}.`);
+    }
+  }
+
+  // RAG (task #127: the user wants the terminal RAG-ready). Ensure the embedding model +
+  // server so rag_index / rag_search work. Uses the account's configured embed URL when
+  // local, else the default local one on EMBED_PORT.
+  const rag = await ensureRag({ p, log, confirm });
+
+  return { chat, deps, rag };
+}
+
+/**
+ * Ensure the agent's required runtime deps (task #127 — parity with the Wizard's pip steps).
+ * python3 can't be auto-installed (guidance only); hf / mlx-lm / smolagents+openai are
+ * offered via pip. Each install is confirmed. Returns a status map; missing deps are
+ * reported, never silently ignored — the agent hard-fails without smolagents+openai.
+ */
+export async function ensureAgentDeps({ log, confirm }) {
+  const out = {};
+  log("");
+  log("  Checking the agent's dependencies…");
+  // python3 — the whole agent runs on it; we can't install it for the user.
+  if (!(await pyHasModule("sys"))) {
+    log(`  ⚠ ${python3Bin()} not found. Install Python 3 (Xcode Command Line Tools or`);
+    log("    python.org), then run `gonext-local-worker doctor` again.");
+    out.python3 = "missing";
+    return out; // nothing else can be installed without python
+  }
+  out.python3 = "ok";
+
+  const ensurePkg = async (key, probeMod, pkgs, question) => {
+    if (await probeMod()) {
+      out[key] = "present";
+      return;
+    }
+    if (!(await confirm(question, true))) {
+      out[key] = "skipped";
+      log(`  Skipped ${pkgs.join(" ")} — install later: ${python3Bin()} -m pip install -U ${pkgs.join(" ")}`);
+      return;
+    }
+    try {
+      await pipInstall(pkgs, log);
+      out[key] = "installed";
+    } catch (e) {
+      log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+      out[key] = "failed";
+    }
+  };
+
+  // hf CLI (model downloads). `huggingface_hub` provides the `hf` command.
+  await ensurePkg(
+    "hf",
+    () => which("hf"),
+    ["huggingface_hub"],
+    "Install the Hugging Face CLI (needed to download models)?"
+  );
+  // mlx-lm — runs the local chat + embedding model servers.
+  await ensurePkg("mlxLm", () => pyHasModule("mlx_lm"), ["mlx-lm"], "Install mlx-lm (runs the local model servers)?");
+  // The agent framework itself — WITHOUT this every agent turn crashes at import.
+  await ensurePkg(
+    "agentLibs",
+    async () => (await pyHasModule("smolagents")) && (await pyHasModule("openai")),
+    ["smolagents", "openai"],
+    "Install the agent framework (smolagents + openai) — required to run the agent?"
+  );
+  if (out.agentLibs === "skipped" || out.agentLibs === "failed") {
+    log(yellow("  ⚠ Without smolagents + openai the agent can't run — install them before asking a question."));
+  }
+  return out;
+}
+
+/**
+ * Start the MLX embeddings server (gonext_mlx_embed.py) DETACHED on `port` for `modelDir`,
+ * with its own pidfile/log. No-op + { ready:true } when one already answers (BC3). Waits up
+ * to waitMs for /v1/models to respond. Mirrors startChatModelServer.
+ */
+export async function startEmbedServer({ modelDir, port, waitMs = 60_000, log = () => {} }) {
+  const base = `http://127.0.0.1:${port}`;
+  if (await probeModelServer(base, { timeoutMs: 1500 })) {
+    return { started: false, ready: true, reason: "already-running" };
+  }
+  if (!(await pyHasModule("mlx_lm"))) {
+    return { started: false, ready: false, reason: "mlx-lm not installed (pip install mlx-lm)" };
+  }
+  await mkdir(DIR, { recursive: true });
+  const outLog = await open(EMBED_LOG_FILE, "a");
+  let pid;
+  try {
+    const child = spawn(
+      python3Bin(),
+      [EMBED_SCRIPT, "--model", modelDir, "--port", String(port), "--host", "127.0.0.1"],
+      { detached: true, stdio: ["ignore", outLog.fd, outLog.fd], env: process.env }
+    );
+    pid = child.pid;
+    await writeFile(EMBED_PID_FILE, String(pid ?? ""), "utf8");
+    child.unref();
+  } finally {
+    await outLog.close();
+  }
+  log(`  starting embeddings server (pid ${pid}) on port ${port} — waiting for it to load…`);
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    await sleep(2500);
+    if (await probeModelServer(base, { timeoutMs: 2000 })) return { started: true, ready: true, pid };
+  }
+  return { started: true, ready: false, pid, reason: `embeddings server still loading (see ${EMBED_LOG_FILE})` };
+}
+
+/**
+ * Ensure RAG is ready for the agent terminal (task #127): boto3 (cloud/S3 storage), the
+ * embedding model, and a running embeddings server. Uses the account's configured embed URL
+ * when it's local; otherwise the default local server on EMBED_PORT. BC3: an already-running
+ * embed server is left alone. Returns a status map.
+ */
+export async function ensureRag({ p, log, confirm }) {
+  const out = {};
+  log("");
+  log("  Checking RAG (agent knowledge base)…");
+  // boto3 — needed only for CLOUD (S3) RAG; local RAG stores on disk. Cheap + harmless, so
+  // offer it so cloud RAG works later without another setup pass.
+  if (!(await pyHasModule("boto3"))) {
+    if (await confirm("Install boto3 (needed only if you use cloud/S3 RAG)?", true)) {
+      try {
+        await pipInstall(["boto3"], log);
+        out.boto3 = "installed";
+      } catch (e) {
+        log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+        out.boto3 = "failed";
+      }
+    } else out.boto3 = "skipped";
+  } else out.boto3 = "present";
+
+  // Embed server URL: the account's configured local one, else the default local server.
+  const configuredEmbed = String(p?.ragEmbedUrl || "").trim();
+  const embedUrl =
+    configuredEmbed && isLocalModelUrl(configuredEmbed)
+      ? configuredEmbed
+      : `http://127.0.0.1:${EMBED_PORT}`;
+  const embedPort = parsePort(embedUrl) || EMBED_PORT;
+
+  if (await probeModelServer(embedUrl)) {
+    log(`  ✓ embeddings server already running at ${modelRoot(embedUrl)} — leaving it alone.`);
+    out.embed = "already-running";
+    return out;
+  }
+  if (configuredEmbed && !isLocalModelUrl(configuredEmbed)) {
+    log(`  ⚠ your embeddings server (${modelRoot(configuredEmbed)}) is remote and isn't`);
+    log("    answering. Start it there — this machine can't launch it.");
+    out.embed = "remote";
+    return out;
+  }
+  // Download the embed model if missing.
+  if (!(await modelDirReady(EMBED_DIR))) {
+    if (!(await confirm(`Download the RAG embedding model ${EMBED_REPO.split("/").pop()} (~4 GB)?`, true))) {
+      log("  Skipped. To do it yourself:");
+      log(`      hf download ${EMBED_REPO} --local-dir ${EMBED_DIR}`);
+      log(`      gonext-local-worker embed --model ${EMBED_DIR} --port ${embedPort}`);
+      out.embed = "skipped-model";
+      return out;
+    }
+    try {
+      await downloadModel({ repo: EMBED_REPO, dir: EMBED_DIR, log });
+    } catch (e) {
+      log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+      out.embed = "download-failed";
+      return out;
+    }
+  }
+  if (!(await confirm(`Start the RAG embeddings server on port ${embedPort} now?`, true))) {
+    log(`  Skipped. Start it later: gonext-local-worker embed --model ${EMBED_DIR} --port ${embedPort}`);
+    out.embed = "not-started";
+    return out;
+  }
+  const r = await startEmbedServer({ modelDir: EMBED_DIR, port: embedPort, log });
+  if (r.ready) {
+    log(`  ✓ embeddings server is up on port ${embedPort}.`);
+    out.embed = "started";
+  } else if (r.started) {
+    log(`  … embeddings server is loading in the background on port ${embedPort}.`);
+    out.embed = "loading";
+  } else {
+    log(`  ⚠ ${r.reason}`);
+    out.embed = "start-failed";
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gonext-local-worker",
-  "version": "1.0.337",
+  "version": "1.0.346",
   "description": "Polls GoNext cloud API for async local LLM jobs and runs them against Ollama/OpenAI-compatible servers on this Mac",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,8 @@
     "gonext": "./gonext-repl.mjs"
   },
   "scripts": {
-    "test": "python3 -m unittest discover tests -v",
+    "test": "python3 -m unittest discover tests -v && node --test tests/*.test.mjs",
+    "test:js": "node --test tests/*.test.mjs",
     "deploy:local": "npm install -g .",
     "run": "gonext-local-worker",
     "publish:org": "npm publish --access public"
@@ -25,6 +26,9 @@
   "files": [
     "gonext-local-worker.mjs",
     "gonext-repl.mjs",
+    "device-login.mjs",
+    "daemon-control.mjs",
+    "model-doctor.mjs",
     "gonext_probe_agent.py",
     "gonext_agent_chat.py",
     "gonext_transcribe.py",