quoxcli 0.2.0 → 0.3.1

package/lib/quoxon/onboarding/credential.js

@@ -15,18 +15,31 @@ export const KEY_PROVIDERS = new Set(['openai', 'anthropic']);
 export const CHATGPT_ENABLED = false;
 
 /**
- * Options in display order. Ollama is always offered (B3): "on this machine" when localhost:11434
- * answered, else "on another machine" (listed last), which asks for its LAN URL.
+ * Options in display order. #1288: the choices that work come first. Sign in with ChatGPT is not built
+ * yet (waiting on OpenAI), so while it is off it is listed LAST as "coming soon", never first; once it
+ * is on it leads (OpenAI-first). Ollama is always offered (B3): "on this machine" first when
+ * localhost:11434 answered, else "on another machine" (asks for its LAN URL) before Skip.
  */
 export function credentialOptions({ ollama = false, chatgpt = CHATGPT_ENABLED } = {}) {
-  // Not detected: "on another machine" goes last, so the familiar numbering (4 = Skip) holds.
-  const order = ollama ? PROVIDERS : [...PROVIDERS.filter(p => p !== 'ollama'), 'ollama'];
+  const working = ollama ? ['ollama', 'openai', 'anthropic', 'skip'] : ['openai', 'anthropic', 'ollama', 'skip'];
+  const order = chatgpt ? ['chatgpt', ...working] : [...working, 'chatgpt'];
   return order.map(id => {
     if (id === 'ollama') return { id, ...(ollama ? CRED_OPTIONS.ollama : CRED_OPTIONS.ollamaLan), detected: Boolean(ollama), disabled: false };
     return { id, ...CRED_OPTIONS[id], disabled: id === 'chatgpt' && !chatgpt };
   });
 }
 
+/** The next selectable row from `sel` in direction dir (1 down, -1 up), wrapping; disabled rows are skipped. */
+export function nextSelectable(options, sel, dir) {
+  const n = options.length;
+  if (!n) return 0;
+  for (let k = 1; k <= n; k++) {
+    const i = (((sel + dir * k) % n) + n) % n;
+    if (!options[i].disabled) return i;
+  }
+  return sel;
+}
+
 /** A typed Ollama URL -> normalised http(s) URL (bare host gets http:// and :11434) | null. */
 export function normaliseOllamaUrl(text) {
   let v = String(text || '').trim();

package/lib/quoxon/onboarding/dockerOffer.js

@@ -0,0 +1,45 @@
+/**
+ * FIRSTRUN (2026-10-19): the guide OFFERS to fix Docker instead of saying "install Docker, then press r".
+ *
+ *   install   Docker missing (Linux): Docker's official script, then add this user to the docker group
+ *   group     Docker installed, this user not in the docker group: add them
+ *   relaunch  in the group, but this terminal started before that: nothing to run with sudo
+ *
+ * A yes leaves the Ink view (the journey is saved at preflight), runs the command with the real terminal
+ * attached so sudo can ask for a password, then starts quox again under `sg docker`, so the new group applies
+ * without logging out. The relaunched quox picks up where the guide left off.
+ */
+import { spawnSync } from 'node:child_process';
+import { askText } from '../ask.js';
+import * as T from './copy.js';
+
+export const DOCKER_INSTALL_CMD = 'curl -fsSL https://get.docker.com | sudo sh && sudo usermod -aG docker "$USER"';
+export const DOCKER_GROUP_CMD = 'sudo usermod -aG docker "$USER"';
+const COMMANDS = { install: DOCKER_INSTALL_CMD, group: DOCKER_GROUP_CMD, relaunch: null };
+
+/** rows -> { kind, command, ask } for the first row the guide can fix, or null. */
+export function dockerOffer(rows) {
+  const r = (rows || []).find(x => x?.status === 'fail' && x.offer && x.offer in COMMANDS);
+  if (!r) return null;
+  const kind = r.offer;
+  const command = COMMANDS[kind];
+  const q = T.DOCKER_OFFER_QUESTION[kind];
+  const action = command ? `run: ${command}  then start quox again with the docker group` : 'start quox again with the docker group (sg docker), no sudo';
+  return { kind, command, ask: askText(q, { keys: 'y/N', who: 'Quox', action }) };
+}
+
+const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+/** Runs the offer with the terminal attached. -> { action: 'exit', status } */
+export function runDockerOffer(kind, { spawn = spawnSync, out = (s) => process.stdout.write(s), node = process.execPath, bin } = {}) {
+  const command = COMMANDS[kind];
+  if (command) {
+    out(`\n${T.DOCKER_OFFER_RUNNING}\n  ${command}\n\n`);
+    const r = spawn('sh', ['-c', command], { stdio: 'inherit' });
+    if (r?.status !== 0) { out(`\n${T.DOCKER_OFFER_FAILED}\n`); return { action: 'exit', status: r?.status ?? 1 }; }
+  }
+  out(`\n${T.DOCKER_OFFER_RELAUNCH}\n`);
+  const again = spawn('sg', ['docker', '-c', `exec ${shq(node)} ${shq(bin)}`], { stdio: 'inherit' });
+  if (again?.error) { out(`${T.CHECK.docker.permStaleFix}\n`); return { action: 'exit', status: 1 }; }
+  return { action: 'exit', status: again?.status ?? 0 };
+}

package/lib/quoxon/onboarding/failureCause.js

@@ -0,0 +1,33 @@
+/**
+ * FIRSTRUN (2026-10-19): a failed install says WHY in one plain line, for the causes a stranger can act on.
+ * Input: installer output plus the tail of the build log setup.sh names. Output: { kind, host?, message } | null.
+ * Prebuilt images being unavailable ("error from registry: denied") is never a cause: the installer builds instead.
+ */
+const RETRY = 'then press r to try again.';
+
+const NETWORK = [
+  /Could not connect to ([a-z0-9.-]+\.[a-z]{2,}):\d+/i,
+  /Temporary failure resolving '([^']+)'/i,
+  /Failed to fetch https?:\/\/([a-z0-9.-]+\.[a-z]{2,})\/\S*\s+(?:Could not connect|Unable to connect|Connection failed|Temporary failure)/i,
+  /request to https?:\/\/([a-z0-9.-]+\.[a-z]{2,})\/\S* failed, reason: (?:connect )?(?:ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN|ENOTFOUND)/i,
+  /getaddrinfo (?:EAI_AGAIN|ENOTFOUND) ([a-z0-9.-]+\.[a-z]{2,})/i
+];
+
+export function explainInstallFailure(text) {
+  const t = String(text ?? '');
+  if (!t.trim()) return null;
+  for (const re of NETWORK) {
+    const m = re.exec(t);
+    if (m) {
+      const host = m[1].toLowerCase();
+      return { kind: 'network', host, message: `The build could not reach ${host}, a package server. Check this machine's internet connection, firewall or proxy, ${RETRY}` };
+    }
+  }
+  if (/no space left on device/i.test(t)) {
+    return { kind: 'disk', message: `The disk filled up during the build. Free some space (docker system prune -f frees old build cache), ${RETRY}` };
+  }
+  if (/heap out of memory|exit code: 137\b|\bOOMKilled\b|Cannot allocate memory/i.test(t)) {
+    return { kind: 'memory', message: `The build ran out of memory. Close other programs or give this machine more RAM (8 GB is recommended), ${RETRY}` };
+  }
+  return null;
+}

package/lib/quoxon/onboarding/finish.js

@@ -107,6 +107,21 @@ export async function createFinisher({ profileUrl = LOCAL_PROFILE_URL, fetchImpl
       }
     },
 
+    /** QUOXON-Z2H lane R: the owner said yes at the credential step; record it as their own act. -> { ok } | { ok: false, error } */
+    async grantConsent(provider) {
+      try { await createApi({ client, config, auth }).grantConsent(provider); return { ok: true }; }
+      catch (e) { return { ok: false, error: apiError(e, 'consent not recorded') }; }
+    },
+
+    /** Z2H-R5 E: can this server serve its host installer? -> { ok, status } | null (unknown). Reads only. */
+    async hostInstaller() {
+      try {
+        const api = createApi({ client, config, auth });
+        const base = await api.hostsBaseUrl();
+        return await api.hostInstallCheck(base);
+      } catch { return null; }
+    },
+
     /** -> { ok: true, url, expiresAt, ttlSeconds } | { ok: false, error } */
     async loginLink(dashboardUrl) {
       try {

package/lib/quoxon/onboarding/index.js

@@ -7,6 +7,10 @@ import React from 'react';
 import { render } from 'ink';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { probeQuoxCore, probeMessage } from './probe.js';
 import { GettingStarted } from './view.js';
 import { inkStdout } from '../term.js';
 import { createCredentialBroker, createRequestCredential } from './credential.js';
@@ -15,6 +19,7 @@ import { createInstallRunner, defaultInstallDir, probeAuthHealth } from './insta
 import { createFinisher } from './finish.js';
 import { journeyPath as defaultJourneyPath, clearJourney, loadJourney } from './journey.js';
 import * as T from './copy.js';
+import { runDockerOffer } from './dockerOffer.js';
 
 const QUOX_BIN = fileURLToPath(new URL('../../../bin/quox.js', import.meta.url));
 
@@ -49,19 +54,41 @@ export async function runGettingStarted({ version, cwd, welcome = false, earlyIn
   await app.waitUntilExit();
   broker.cancel();
   if (result.action === 'connect') return connectServer(result.url, { demo });
+  if (result.action === 'docker' && !demo) return runDockerOffer(result.kind, { bin: QUOX_BIN }); // FIRSTRUN
   return result;
 }
 
-/** /connect server <url>: point the active profile at it and run the existing login. Restores the URL on failure. */
-export async function connectServer(url, { demo = false, spawn = spawnSync, out = (s) => process.stdout.write(s) } = {}) {
+/**
+ * /connect server <url>: check the URL is a real QuoxCORE (#1101), point the active profile at it and run the
+ * existing login. Any outcome but a completed sign-in (failure, Ctrl-C at Email or Password) puts the previous
+ * URL and the last-good config.json.bak back, so no half-saved profile is left behind.
+ */
+export async function connectServer(url, {
+  demo = false, spawn = spawnSync, out = (s) => process.stdout.write(s),
+  probe = probeQuoxCore, loadConfigImpl = null, bakFile = join(homedir(), '.config', 'quox', 'config.json.bak'),
+  localCertPath = join(defaultInstallDir(), 'quox', 'ssl', 'quox.crt') // the guided install's own certificate, if this is the server
+} = {}) {
   if (demo) { out(`${T.connectHandoff(url)}\n(demo: not connecting)\n`); return { action: 'exit' }; }
-  const { loadConfig } = await import('../../core/config.js');
-  const config = loadConfig();
+  const p = await probe(url);
+  if (!p?.ok) { out(`${probeMessage(url, p, { localCert: existsSync(localCertPath) ? localCertPath : null })}\n`); return { action: 'connect-failed' }; }
+  const load = loadConfigImpl || (await import('../../core/config.js')).loadConfig;
+  const config = load();
   const prev = config.getActiveProfile()?.url || null;
+  let bak = null;
+  try { bak = readFileSync(bakFile); } catch { /* no backup yet */ }
   config.setProfileConnection({ url });
-  const r = spawn(process.execPath, [QUOX_BIN, 'login'], { stdio: 'inherit' });
-  if (r.status === 0) { clearJourney(); out(`${T.CONNECT_DONE}\n`); return { action: 'connected' }; }
-  if (prev) loadConfig().setProfileConnection({ url: prev });
+  out(`${T.connectHandoff(url)}\n`);
+  // Ctrl-C reaches the whole foreground group: the login child handles it, the parent must live to restore.
+  const hold = () => {};
+  process.on('SIGINT', hold);
+  let r;
+  try { r = spawn(process.execPath, [QUOX_BIN, 'login'], { stdio: 'inherit' }); } finally { process.removeListener('SIGINT', hold); }
+  if (r?.status === 0) { clearJourney(); out(`${T.CONNECT_DONE}\n`); return { action: 'connected' }; }
+  const cfg = load();
+  if (prev) cfg.setProfileConnection({ url: prev });
+  else { const prof = cfg.getActiveProfile(); if (prof) { delete prof.url; cfg.save(); } }
+  if (bak) { try { writeFileSync(bakFile, bak, { mode: 0o600 }); } catch { /* best effort */ } }
+  if (r?.status === 130 || r?.signal === 'SIGINT') { out(`\x1b[?25h${T.CONNECT_CANCELLED}\n`); return { action: 'connect-cancelled' }; }
   out(`${T.connectFailed(url)}\n`);
   return { action: 'connect-failed' };
 }

package/lib/quoxon/onboarding/installRunner.js

@@ -22,13 +22,17 @@
  */
 import { spawn as defaultSpawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync, appendFileSync, openSync, readSync, fstatSync, closeSync } from 'node:fs';
+import { explainInstallFailure } from './failureCause.js';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { STAGE_IDS, stageList } from './runner.js';
 
+import { BUILD_LABELS } from './copy.js';
 export const INSTALLER_URL = 'https://get.quox.ai';
 export const defaultInstallDir = (home = homedir()) => join(home, 'quox-install');
+/** Where the full install log lives: the user's quox state dir, ~/.local/state/quox/install-logs. */
+export const defaultInstallLogDir = (home = homedir()) => join(home, '.local', 'state', 'quox', 'install-logs');
 
 const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
 const RED = /^\x1b\[(0;)?31m/;
@@ -44,7 +48,7 @@ const MARKS = [
  * push(rawLine) -> { line: cleaned text | null, moves: [[stageId, 'ok'|'running']] }
  */
 export function createStageParser() {
-  const state = { current: 'fetch', ready: false, degraded: false, dashboardUrl: null, lastError: null };
+  const state = { current: 'fetch', buildMode: null, ready: false, degraded: false, dashboardUrl: null, lastError: null };
   return {
     state,
     push(raw, { stderr = false } = {}) {
@@ -61,6 +65,9 @@ export function createStageParser() {
         state.current = next;
         break;
       }
+      // Z2H-IMAGES: setup.sh either downloads prebuilt images or builds them; the build stage says which.
+      if (/Downloading prebuilt images/.test(line)) state.buildMode = 'download';
+      else if (/Building images/.test(line)) state.buildMode = 'build';
       if (/QuoxCORE full platform is ready/.test(line)) state.ready = true;
       if (/core shell is up, but platform features are degraded/.test(line)) state.degraded = true;
       const open = /^\s*Open:\s+(https?:\/\/\S+)/.exec(line);
@@ -88,6 +95,7 @@ export function createInstallRunner({
   env = process.env,
   url = env.QUOX_INSTALLER_URL || INSTALLER_URL,
   installDir = defaultInstallDir(),
+  logDir = defaultInstallLogDir(),
   fetchImpl = globalThis.fetch,
   spawnImpl = defaultSpawn,
   tmpRoot = tmpdir(),
@@ -118,7 +126,44 @@ export function createInstallRunner({
     installDir,
     stages: stageList(),
     /** Per-run overrides (the view passes the journey's checkpoint): resumeFrom, resumeDashboardUrl, onCheckpoint. */
-    async run({ onEvent = () => {}, signal, resumeFrom: rf = resumeFrom, resumeDashboardUrl: rd = resumeDashboardUrl, onCheckpoint: oc = onCheckpoint } = {}) {
+    /**
+     * Every run also writes the full stage log (each line the installer printed) to a file under the
+     * user's quox state dir; the result carries `logPath` so the UI can show it on failure and at the end.
+     */
+    async run(opts = {}) {
+      const { onEvent = () => {} } = opts;
+      let logPath = null;
+      try {
+        mkdirSync(logDir, { recursive: true, mode: 0o700 });
+        logPath = join(logDir, `install-${new Date(now()).toISOString().replace(/[:.]/g, '-')}.log`);
+        writeFileSync(logPath, `# quox install log, started ${new Date(now()).toISOString()}\n`, { mode: 0o600 });
+      } catch { logPath = null; } // best effort: a log that cannot be written never fails the install
+      const recent = []; // FIRSTRUN: the last lines, so a failure can say its cause
+      const tee = (e) => {
+        if (e.type === 'log') { recent.push(e.line); if (recent.length > 400) recent.shift(); }
+        if (logPath) {
+          try {
+            if (e.type === 'log') appendFileSync(logPath, e.line + '\n');
+            else if (e.type === 'stage') appendFileSync(logPath, `-- stage ${e.id} ${e.status}\n`);
+          } catch { /* best effort */ }
+        }
+        onEvent(e);
+      };
+      const res = await runCore({ ...opts, onEvent: tee });
+      if (!res.ok && !res.interrupted) {
+        const named = recent.map(l => /Full build log:\s*(\S+)/.exec(l)?.[1]).filter(Boolean).pop();
+        const cause = explainInstallFailure(`${recent.join('\n')}\n${res.error || ''}\n${named ? tailOf(named) : ''}`);
+        if (cause) res.cause = cause;
+      }
+      if (!res.ok && !res.interrupted && logPath) {
+        // Z2H-R2: a failed run always says where the full log is and what to do next.
+        res.hint = `Full log: ${logPath}. It is safe to run the installer again; finished steps are kept and the build is cached.`;
+      }
+      if (logPath) { try { appendFileSync(logPath, `-- result ${res.ok ? 'ok' : `failed at ${res.failedStage || '?'}: ${res.error || ''}`}\n`); } catch { /* best effort */ } }
+      return logPath ? { ...res, logPath } : res;
+    }
+  };
+  async function runCore({ onEvent = () => {}, signal, resumeFrom: rf = resumeFrom, resumeDashboardUrl: rd = resumeDashboardUrl, onCheckpoint: oc = onCheckpoint } = {}) {
       const resumeAfterStart = rf === 'start' || rf === 'health';
       const started = {};
       const stage = (id, status) => {
@@ -185,11 +230,13 @@ export function createInstallRunner({
             };
           };
           const take = (raw, stderr) => {
+            const modeBefore = parser.state.buildMode;
             const { line, moves } = parser.push(raw, { stderr });
             for (const [id, status] of moves) {
               if (status === 'ok') { stage(id, 'ok'); if (id !== 'health') oc(id, {}); }
               else stage(id, 'running');
             }
+            if (parser.state.buildMode !== modeBefore) emit({ type: 'stage-label', id: 'build', label: BUILD_LABELS[parser.state.buildMode] });
             if (line) emit({ type: 'log', line });
           };
           child.stdout.on('data', feed(false));
@@ -220,6 +267,18 @@ export function createInstallRunner({
       } finally {
         try { rmSync(dir, { recursive: true, force: true }); } catch { /* temp cleanup only */ }
       }
-    }
-  };
+  }
+}
+
+/** The last `max` bytes of a file, '' when it cannot be read (a cause is best effort, never a new failure). */
+function tailOf(path, max = 256 * 1024) {
+  let fd = null;
+  try {
+    fd = openSync(path, 'r');
+    const size = fstatSync(fd).size;
+    const len = Math.min(size, max);
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, size - len);
+    return buf.toString('utf8');
+  } catch { return ''; } finally { if (fd != null) try { closeSync(fd); } catch { /* closed */ } }
 }

package/lib/quoxon/onboarding/preflight.js

@@ -8,7 +8,7 @@
  */
 import { execFile } from 'node:child_process';
 import { statfs } from 'node:fs/promises';
-import { totalmem, homedir } from 'node:os';
+import { totalmem, homedir, userInfo } from 'node:os';
 import { createConnection } from 'node:net';
 import { CHECK } from './copy.js';
 
@@ -55,13 +55,27 @@ export const defaultDeps = () => ({
 const gb = (bytes) => Math.floor(bytes / 1024 ** 3);
 const row = (id, status, body, extra = {}) => ({ id, name: CHECK[id].name, status, body, ...extra });
 
+const safeUser = () => { try { return userInfo().username; } catch { return ''; } };
+
 export async function checkDocker(d) {
   const v = await d.run('docker', ['--version'], 5000);
-  if (v.missing || v.code !== 0) return row('docker', 'fail', CHECK.docker.missing, { fix: CHECK.docker.missingFix, link: CHECK.docker.missingLink });
+  const linux = (d.platform || process.platform) === 'linux'; // FIRSTRUN: the guide can fix these itself (dockerOffer.js)
+  const offer = (kind) => (linux ? { offer: kind } : {});
+  if (v.missing || v.code !== 0) return row('docker', 'fail', CHECK.docker.missing, { fix: CHECK.docker.missingFix, link: CHECK.docker.missingLink, ...offer('install') });
   const ver = (/version\s+([0-9][\w.\-+]*)/i.exec(v.stdout) || [])[1] || '';
   const info = await d.run('docker', ['info', '--format', '{{.ServerVersion}}'], 10000);
   if (info.code === 0 && info.stdout.trim()) return row('docker', 'ok', CHECK.docker.ok(ver || info.stdout.trim()));
-  if (/permission denied/i.test(info.stderr)) return row('docker', 'fail', CHECK.docker.perm, { fix: CHECK.docker.permFix, link: CHECK.docker.link });
+  if (/permission denied/i.test(info.stderr)) {
+    // Z2H-R5 D: the group was added after this terminal started. `id -nG` shows the groups of THIS process,
+    // `id -nG <user>` the account database; in the second but not the first, "press r" can never pass.
+    const user = d.user || safeUser();
+    if (user) {
+      const [mine, db] = await Promise.all([d.run('id', ['-nG'], 3000), d.run('id', ['-nG', user], 3000)]);
+      const has = (r) => r.code === 0 && r.stdout.trim().split(/\s+/).includes('docker');
+      if (has(db) && !has(mine)) return row('docker', 'fail', CHECK.docker.permStale, { fix: CHECK.docker.permStaleFix, link: CHECK.docker.link, stale: true, ...offer('relaunch') });
+    }
+    return row('docker', 'fail', CHECK.docker.perm, { fix: CHECK.docker.permFix, link: CHECK.docker.link, ...offer('group') });
+  }
   return row('docker', 'fail', CHECK.docker.down, { fix: CHECK.docker.downFix, link: CHECK.docker.link });
 }
 

package/lib/quoxon/onboarding/probe.js

@@ -0,0 +1,65 @@
+/**
+ * #1101: is this URL a real QuoxCORE? One cheap unauthenticated GET of the edge's /health (nginx.conf answers
+ * {"status":"ok","service":"dashboard"} on both the HTTP and HTTPS servers), run BEFORE /connect server asks for
+ * an email and password. An error body is not data: only a 2xx JSON answer of that exact shape passes.
+ *
+ * -> { ok: true } | { ok: false, kind: 'url'|'unreachable'|'tls'|'not-quoxcore', code?, status?, detail? }
+ */
+const TLS_CODES = /^(SELF_SIGNED_CERT_IN_CHAIN|DEPTH_ZERO_SELF_SIGNED_CERT|UNABLE_TO_VERIFY_LEAF_SIGNATURE|UNABLE_TO_GET_ISSUER_CERT(_LOCALLY)?|CERT_HAS_EXPIRED|CERT_NOT_YET_VALID|ERR_TLS_.*|ERR_SSL_.*|EPROTO)$/;
+const PLAINTEXT_CODES = new Set(['ERR_SSL_WRONG_VERSION_NUMBER', 'EPROTO']);
+
+export async function probeQuoxCore(url, { fetchImpl = globalThis.fetch, timeout = 5000 } = {}) {
+  let base;
+  try {
+    base = new URL(String(url || ''));
+    if (base.protocol !== 'http:' && base.protocol !== 'https:') return { ok: false, kind: 'url', detail: 'the address must start with https:// or http://' };
+  } catch { return { ok: false, kind: 'url', detail: 'the address must start with https:// or http://' }; }
+  const target = `${base.href.replace(/\/+$/, '')}/health`;
+  let res;
+  try {
+    res = await fetchImpl(target, { signal: AbortSignal.timeout(timeout), headers: { accept: 'application/json' } });
+  } catch (e) {
+    const code = e?.cause?.code || e?.code || null;
+    if (code && TLS_CODES.test(code)) return { ok: false, kind: 'tls', code };
+    if (e?.name === 'TimeoutError' || e?.name === 'AbortError') return { ok: false, kind: 'unreachable', code: 'TIMEOUT', detail: `no answer within ${Math.round(timeout / 1000)} s` };
+    return { ok: false, kind: 'unreachable', code, detail: e?.message || 'no answer' };
+  }
+  if (res?.status === 400 && base.protocol === 'http:') {
+    let t = ''; try { t = await res.text(); } catch { /* no body */ }
+    if (/plain HTTP request was sent to HTTPS port/i.test(t)) return { ok: false, kind: 'tls', code: 'HTTP_TO_HTTPS_PORT' };
+  }
+  if (!res || !(res.status >= 200 && res.status < 300)) return { ok: false, kind: 'not-quoxcore', status: res?.status, detail: `HTTP ${res?.status} from /health` };
+  let body;
+  try { body = JSON.parse(await res.text()); } catch { return { ok: false, kind: 'not-quoxcore', status: res.status, detail: '/health did not answer JSON' }; }
+  if (!body || body.status !== 'ok' || body.service !== 'dashboard') return { ok: false, kind: 'not-quoxcore', status: res.status, detail: '/health answered, but not as QuoxCORE does' };
+  return { ok: true };
+}
+
+// A new QuoxCORE serves its own self-signed certificate (setup.sh writes ssl/quox.crt, CA:TRUE, SAN = localhost +
+// the LAN IP). Trusting exactly that file is the sanctioned fix; these are the codes it fixes. An expired or
+// wrong-name certificate is a different problem: trusting a file would not cure it, so it is not suggested.
+const SELF_SIGNED_CODES = new Set(['DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'UNABLE_TO_GET_ISSUER_CERT', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY']);
+export const SERVER_CERT_DEFAULT = '~/quox-install/quox/ssl/quox.crt';
+
+/**
+ * One plain message per failure kind, naming the address and the next step.
+ * opts.localCert: the absolute path of a QuoxCORE certificate on THIS machine (the server is here), if any.
+ */
+export function probeMessage(url, r, { localCert = null } = {}) {
+  const again = 'Check the address, then try /connect server <url> again.';
+  switch (r?.kind) {
+    case 'url': return `"${url}" is not a server address (${r.detail}). Example: /connect server https://quox.example.com`;
+    case 'unreachable': return `No answer from ${url}${r.code ? ` (${r.code})` : ''}. Nothing was saved and no password was asked for. ${again}`;
+    case 'tls':
+      if (r.code === 'HTTP_TO_HTTPS_PORT') return `${url} is an HTTPS port spoken to in plain HTTP. Did you mean ${String(url).replace(/^http:/i, 'https:')} ? Nothing was saved.`;
+      if (PLAINTEXT_CODES.has(r.code)) return `${url} answered plain HTTP to an https:// request (${r.code}). Did you mean ${String(url).replace(/^https:/i, 'http:')} ? Nothing was saved.`;
+      if (SELF_SIGNED_CODES.has(r.code)) {
+        const lead = `${url} answered with its own self-signed certificate (${r.code}), which is normal for a new QuoxCORE. Trust that server's certificate, then start quox again.`;
+        const tail = 'Never turn TLS checks off. Nothing was saved.';
+        if (localCert) return `${lead} It is on this machine, so run: NODE_EXTRA_CA_CERTS=${localCert} quox   ${tail}`;
+        return `${lead} Copy it from the server (by default ${SERVER_CERT_DEFAULT}) to this machine, then run: NODE_EXTRA_CA_CERTS=~/quox.crt quox   ${tail}`;
+      }
+      return `${url} answered, but its TLS certificate is not trusted (${r.code}). For a self-signed edge, trust its CA with NODE_EXTRA_CA_CERTS=<ca.pem> and try again; never turn TLS checks off. Nothing was saved.`;
+    default: return `${url} answered, but it is not a QuoxCORE server (${r?.detail || 'unexpected answer'}). Nothing was saved and no password was asked for. ${again}`;
+  }
+}