quoxcli 0.4.0 → 0.5.0

package/lib/quoxon/main.js

@@ -12,7 +12,7 @@ import { loadRules, rulesContext } from './rules.js';
 import { createTranscript } from './transcript.js';
 import { createScreenRecorder, screenFramesEnabled } from './screenFrames.js';
 import { applySettings } from './slash/settings.js';
-import { headOf, RUNNING_ROOT, execRestart, restartPlan, checkRestart, startBuildWatch, settleMsFrom, minGapMsFrom, restoreTerminal, RESTART_SLOT_ENV, RESTART_ATTACH_ENV, RESTART_NOTE_ENV, RESTART_MODE_ENV } from './slash/restart.js';
+import { headOf, RUNNING_ROOT, execRestart, restartPlan, checkRestart, startBuildWatch, settleMsFrom, minGapMsFrom, restoreTerminal, RESTART_SLOT_ENV, RESTART_ATTACH_ENV, RESTART_NOTE_ENV, RESTART_MODE_ENV, RESTART_DECLINED_ENV } from './slash/restart.js';
 import { readLastSeen, writeLastSeen } from './away.js';
 import { fileHistory } from './promptHistory.js';
 import { takeLauncherHandoff, writeRestartHandoff, RESTART_EXIT_CODE } from './launcher.js';
@@ -21,6 +21,7 @@ export { parseArgs, USAGE, pickProfile, choosePick, chatCredentialProblem, noSer
 import { parseArgs, USAGE, noServerConfigured, mainPrint, pickProfile, chatCredentialProblem } from './headless.js';
 
 export { captureEarlyInput } from './earlyInput.js';
+import { isNeverAnswered, healthyStamp } from './neverAnswered.js';
 
 /**
  * Clear the screen before the chat client? Never right after Getting started: its finale (the one-time
@@ -39,7 +40,7 @@ export async function main(argv = process.argv.slice(2)) {
   if (opts.errors.length) { early?.release(); process.stderr.write(`quox: ${opts.errors.join('; ')}\n${USAGE}\n`); process.exitCode = 1; return; }
   const cwd = process.cwd().replace(process.env.HOME || '\0', '~');
   const { resolveCliVersion } = await import('../core/version.js');
-  let version = '0.4.0';
+  let version = '0.5.0';
   try { version = resolveCliVersion?.() || version; } catch { /* keep default */ }
   if (opts.print) return mainPrint(opts);
   let replay = null;
@@ -104,6 +105,9 @@ export async function main(argv = process.argv.slice(2)) {
       if (problem) return problem.message;
       if (pick.note) return pick.note;
       const hl = await api.health(8000);
+      if (hl.ok && !missing) { // ONBOARD-P2: remember that this profile's server has answered, so a later outage keeps the reconnect spinner
+        try { const stamp = healthyStamp(config.getProfile?.(pname), Date.now()); if (stamp) config.upsertProfile?.(pname, { lastHealthyAt: stamp }); } catch { /* history is best effort */ }
+      }
       return hl.ok ? null : hl.absent ? `No QuoxCORE running at ${hl.url}` : `QuoxCORE at ${hl.url} is not answering (${hl.status}); messages may be slow`;
     };
     // /restart hand-over: re-enter the predecessor window's org in this window only (the profile is untouched).
@@ -127,7 +131,7 @@ export async function main(argv = process.argv.slice(2)) {
       return { ok: true, api: a2, agentLogin: residentNames().includes(name), orgName: (c && !c.error && c.name) || c2.getAuth?.()?.org_name || null, note };
     };
     const loginCandidates = profiles.filter(p => !p.loggedIn && !residentNames().includes(p.name)).map(p => p.name);
-    props = { api, switchProfile, loginCandidates, away: { read: readLastSeen, write: writeLastSeen }, modelChoice: opts.provider, resume: opts.resume ?? null, onRestart: (r) => { restart = r; }, onDemo: () => { restart = { demo: true }; }, restartCheck: checkRestart, buildWatch: (o) => startBuildWatch({ ...o, settleMs: settleMsFrom(), minGapMs: minGapMsFrom() }), startSha: headOf(RUNNING_ROOT), rules: loadRules(), profile: pname, agentLogin: (probe.listResidentProfiles?.() || []).some(r => r.name === pname), humanProfiles: profiles.filter(p => p.loggedIn && !(probe.listResidentProfiles?.() || []).some(r => r.name === p.name)).map(p => p.name), org: missing ? null : ((carried && !carried.error && carried.name) || config.getAuth?.()?.org_name || null), startup: startupCarry, healthRecheck: () => api.health(8000), blocked: problem && !signedOut ? problem.message : null, signedOut, autoplay: replay };
+    props = { api, switchProfile, loginCandidates, startupSwitchOffer: true, away: { read: readLastSeen, write: writeLastSeen }, modelChoice: opts.provider, resume: opts.resume ?? null, onRestart: (r) => { restart = r; }, onDemo: () => { restart = { demo: true }; }, restartCheck: checkRestart, buildWatch: (o) => startBuildWatch({ ...o, settleMs: settleMsFrom(), minGapMs: minGapMsFrom() }), startSha: headOf(RUNNING_ROOT), rules: loadRules(), profile: pname, agentLogin: (probe.listResidentProfiles?.() || []).some(r => r.name === pname), humanProfiles: profiles.filter(p => p.loggedIn && !(probe.listResidentProfiles?.() || []).some(r => r.name === p.name)).map(p => p.name), org: missing ? null : ((carried && !carried.error && carried.name) || config.getAuth?.()?.org_name || null), startup: startupCarry, neverAnswered: !missing && !signedOut && !problem && !pick.note && !opts.serviceKey && isNeverAnswered(config.getProfile?.(pname)), onConnect: (url) => { restart = { connect: url }; }, healthRecheck: () => api.health(8000), blocked: problem && !signedOut ? problem.message : null, signedOut, autoplay: replay };
   }
   // Interactive start: a clean screen under the intro (never when piped; NO_COLOR still clears),
   // except straight after Getting started, whose finale must stay readable.
@@ -153,13 +157,24 @@ export async function main(argv = process.argv.slice(2)) {
   const restartSlot = opts.demo ? null : (process.env[RESTART_SLOT_ENV] || null); delete process.env[RESTART_SLOT_ENV]; // one hand-over only
   const restartAttach = opts.demo ? null : (process.env[RESTART_ATTACH_ENV] || null); delete process.env[RESTART_ATTACH_ENV];
   const restartMode = opts.demo ? null : (process.env[RESTART_MODE_ENV] === 'plan' ? 'plan' : null); delete process.env[RESTART_MODE_ENV]; // PLAN MODE: window-scoped, carried once
+  const restartDeclined = opts.demo ? null : (process.env[RESTART_DECLINED_ENV] || null); delete process.env[RESTART_DECLINED_ENV]; // a slot this window said no to: not re-asked after the restart
   const restartNote = opts.demo ? null : (process.env[RESTART_NOTE_ENV] || null); delete process.env[RESTART_NOTE_ENV]; // e.g. a failed /update, said once in the restarted client
   if (restartNote && !props.introNote) props.introNote = restartNote;
-  const app = render(React.createElement(App, { ...props, restartSlot, restartAttach, ...(restartMode ? { mode: restartMode } : {}), welcome, tipStartup: !fromGettingStarted && !opts.demo && Boolean(process.stdout.isTTY), whatsNewStartup: !opts.demo && Boolean(process.stdout.isTTY), version, cwd, verbose: opts.verbose, earlyInput: early, sessionName: opts.name, resumeConversation: opts.conversation || null, invite: Boolean(process.stdout.isTTY) && !opts.name, slotsAvailable, transcript, historyStore: opts.demo ? null : fileHistory() }), inkRenderOptions(process.stdout, { tap: screenRec?.tap }));
+  const app = render(React.createElement(App, { ...props, restartSlot, restartAttach, restartDeclined, ...(restartMode ? { mode: restartMode } : {}), welcome, tipStartup: !fromGettingStarted && !opts.demo && Boolean(process.stdout.isTTY), whatsNewStartup: !opts.demo && Boolean(process.stdout.isTTY), version, cwd, verbose: opts.verbose, earlyInput: early, sessionName: opts.name, resumeConversation: opts.conversation || null, invite: Boolean(process.stdout.isTTY) && !opts.name, slotsAvailable, transcript, historyStore: opts.demo ? null : fileHistory() }), inkRenderOptions(process.stdout, { tap: screenRec?.tap }));
   try { await app.waitUntilExit(); screenRec?.stop(); transcript?.end(restart ? 'restart' : 'exit'); }
   catch (e) { screenRec?.stop(); transcript?.end(`crash: ${e?.message || e}`); throw e; }
   finally { screenRec?.stop(); process.stdout.off('resize', onResize); }
   if (!restart) return;
+  if (restart.connect) { // ONBOARD-P2: "Connect to a different server?" said y; the connect flow owns the terminal (certificate card, sign-in)
+    restoreTerminal();
+    const { connectServer } = await import('./onboarding/connectServer.js');
+    const { profileNameForUrl } = await import('../core/profileTrust.js');
+    const { confirmInteractive } = await import('../core/confirm.js');
+    const profile = profileNameForUrl(restart.connect);
+    const c = await connectServer(restart.connect, { profile, trust: () => confirmInteractive(`Trust this server's certificate for profile "${profile}" only?`, { flag: '--trust-cert', purpose: 'trust it' }), loadConfigImpl: (await import('../core/config.js')).loadConfig });
+    if (c.action !== 'connected') { process.exitCode = 1; return; }
+    restart = { profile };
+  }
   if (restart.update) { // /update said y: the update owns the terminal (npm prompts, sudo), then the same restart either way
     const { runUpdate } = await import('../core/selfUpdate.js');
     const plan = restart.update;
@@ -174,7 +189,7 @@ export async function main(argv = process.argv.slice(2)) {
     }
   }
   // The app preflighted the installed quox before letting go, so a failure here is rare (it changed in between).
-  const how = { argv: restart.demo ? ['--demo', '--autoplay'] : argv, conversationId: restart.demo ? null : restart.conversationId, profile: opts.demo ? null : (restart.profile || props.profile), name: restart.name || opts.name || null, slot: restart.demo ? null : (restart.slot || null), attach: restart.demo ? null : (restart.attach || null), org: restart.demo ? null : (restart.org || null), mode: restart.demo ? null : (restart.mode || null), bin: restart.bin || undefined };
+  const how = { argv: restart.demo ? ['--demo', '--autoplay'] : argv, conversationId: restart.demo ? null : restart.conversationId, profile: opts.demo ? null : (restart.profile || props.profile), name: restart.name || opts.name || null, slot: restart.demo ? null : (restart.slot || null), attach: restart.demo ? null : (restart.attach || null), org: restart.demo ? null : (restart.org || null), mode: restart.demo ? null : (restart.mode || null), declined: restart.demo ? null : (restart.declined || null), bin: restart.bin || undefined };
   // QUOXON-RESTART-LEAK: under the launcher this process EXITS and the launcher runs the successor, so exactly one
   // client stays alive per terminal. Without one (QUOX_NO_LAUNCHER=1) it falls back to waiting on a nested child.
   const launched = takeLauncherHandoff();

package/lib/quoxon/markdown.js

@@ -63,7 +63,7 @@ export function inlineText(tokens = []) {
   return tokens.map(t => {
     if (t.tokens) return inlineText(t.tokens);
     if (t.type === 'br') return ' ';
-    return t.text ?? t.raw ?? '';
+    return typeof t.text === 'string' ? t.text : typeof t.raw === 'string' ? t.raw : ''; // never an object: it would print [object Object]
   }).join('').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
 }
 

package/lib/quoxon/model.js

@@ -90,6 +90,21 @@ export const choiceId = (ch) => (ch ? rowOf(ch)?.id || null : null);
 export const connectedChoices = (res, caps = null) =>
   CHOICES.filter(c => c.served !== false && availability(res, c, caps).state === 'connected');
 
+/** Health states that mean a provider refuses turns right now. */
+const REFUSING = new Set(['limited', 'no_credits']);
+/**
+ * The active model's provider is limited / out of credits: the first CHOICES row the server reports ready whose
+ * provider health does not also refuse turns. -> { id, label, why } | null (no usable alternative = no offer).
+ */
+export function limitedOffer(health, current, res, caps = null, mine = null) {
+  const bad = new Set((Array.isArray(health) ? health : []).filter(e => REFUSING.has(e?.state)).map(e => String(e.provider || '').toLowerCase()));
+  const active = String(current?.provider || mine || '').toLowerCase();
+  if (!active || !bad.has(active)) return null;
+  const alt = connectedChoices(res, caps).find(c => !bad.has(c.provider) && c.provider !== active);
+  if (!alt) return null;
+  return { id: alt.id, label: alt.name, why: alt.id === 'ollama' ? 'local Ollama, ready on this server' : 'ready on this server' };
+}
+
 const same = (a, b) => (a?.provider || null) === (b?.provider || null) && (a?.via || null) === (b?.via || null);
 
 /** -> [[text, tone?]] lines for /model. `caps` = api.capabilities() (the server's word on each provider). */

package/lib/quoxon/neverAnswered.js

@@ -0,0 +1,20 @@
+/**
+ * ONBOARD-P2: has this profile's server ever answered from this machine?
+ * A profile that has not (no recorded health success, never signed in) and whose server is dead is a first-run
+ * problem (wrong address), not an outage, so the TUI offers to connect elsewhere instead of spinning "restarting".
+ */
+const HOUR = 3600 * 1000;
+
+export function isNeverAnswered(profile) {
+  if (!profile) return false;
+  if (profile.lastHealthyAt) return false;
+  if (profile.auth?.access_token) return false; // a sign-in worked once, so the server answered
+  return true;
+}
+
+/** The ISO time to record after a successful health probe, or null when a recent stamp already exists. */
+export function healthyStamp(profile, now = Date.now()) {
+  const prev = Date.parse(profile?.lastHealthyAt || '');
+  if (Number.isFinite(prev) && now - prev < HOUR) return null;
+  return new Date(now).toISOString();
+}

package/lib/quoxon/objects/away.js

@@ -4,7 +4,7 @@
  * server could not read, or that went silent, come back in `blind` and are always named ("Can't see"),
  * so an empty list never reads as an all clear it cannot vouch for.
  */
-import { seg, fit, hhmm, plural, boxWidth, parseTs } from './model.js';
+import { seg, fit, hhmm, day, plural, boxWidth, parseTs } from './model.js';
 
 /** Importance: approvals waiting first (they block work), then alerts, failures, then outcomes. */
 export const RANK = {
@@ -32,19 +32,52 @@ export function awayFor(sinceTs, now) {
   return h < 48 ? `${h}h` : `${Math.round(h / 24)}d`;
 }
 
+/** Short stamp: the time when it is today, else "Oct 12 09:00" so an old item is never mistaken for a new one. */
+export function stamp(ts, now) {
+  const t = parseTs(ts);
+  if (t == null) return 'time unknown';
+  if (day(t) === day(now)) return hhmm(t);
+  const d = new Date(t).toISOString();
+  return `${['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'][Number(d.slice(5, 7)) - 1]} ${Number(d.slice(8, 10))} ${d.slice(11, 16)}`;
+}
+
+/** Who an item is from: its sender when it has one (mail), else the source that reported it. */
+const whoOf = (it) => {
+  const w = it.sender || it.from || it.source || '?';
+  return w === 'lucid' ? 'LUCID' : w;
+};
+export function breakdown(items) {
+  const n = new Map();
+  for (const it of items) n.set(whoOf(it), (n.get(whoOf(it)) || 0) + 1);
+  return [...n].sort((a, b) => b[1] - a[1] || String(a[0]).localeCompare(String(b[0]))).map(([k, c]) => `${k}: ${c}`).join(' · ');
+}
+
+/** Newer than the away start (or the last /back) is "since you left"; anything else, or untimed, is old. */
+export function splitItems(items, since) {
+  const s = parseTs(since);
+  const fresh = [], old = [];
+  for (const it of items || []) {
+    const t = parseTs(it.ts);
+    (s == null || (t != null && t >= s) ? fresh : old).push(it);
+  }
+  return { fresh, old };
+}
+
 /** d: { since, items, blind, activity, compact?, max?, now } */
 export function awayCard(d, cols) {
   const now = d.now ?? Date.now();
   const w = boxWidth(cols, 96), inner = w - 4;
-  const items = rankItems(d.items);
+  const { fresh, old } = splitItems(d.items, d.since);
+  const items = rankItems(fresh);
   const max = d.compact ? (d.max ?? 5) : items.length;
   const shown = items.slice(0, max);
   const rows = [];
-  const win = awayFor(d.since, now);
-  if (!items.length) rows.push([seg(d.standing && d.standing.count > 0 ? 'Nothing new needed you.' : 'Nothing needed you.', 'muted')]);
+  const win = awayFor(d.since, parseTs(d.endedAt) ?? now); // endedAt: another window already ended this away, so every window reports the same span
+  if (!items.length) rows.push([seg(old.length || (d.standing && d.standing.count > 0) ? 'Nothing new since you left.' : 'Nothing needed you.', 'muted')]);
+  else if (old.length) rows.push([seg(fit(`Since you left (${items.length})`, inner), 'value', true)]);
   for (const it of shown) {
     const [g, role] = GLYPH[it.kind] || ['· ', 'muted'];
-    const meta = `${it.source || '?'} · ${hhmm(it.ts) || 'time unknown'}`;
+    const meta = `${it.source || '?'} · ${stamp(it.ts, now)}`;
     if (d.compact) {
       rows.push([seg(g, role), seg(fit(it.title, Math.max(8, inner - 2 - meta.length - 2)), 'value'), seg(`  ${meta}`, 'muted')]);
     } else {
@@ -53,6 +86,11 @@ export function awayCard(d, cols) {
     }
   }
   if (items.length > shown.length) rows.push([seg(`+${items.length - shown.length} more · /away`, 'muted')]);
+  if (items.length) rows.push([seg(fit(breakdown(items), inner), 'muted')]);
+  if (old.length) {
+    const oldest = old.map(i => parseTs(i.ts)).filter(t => t != null).sort((a, b) => a - b)[0];
+    rows.push([seg(fit(`${old.length} still open from before${oldest != null ? ` (oldest ${stamp(oldest, now)})` : ''} · ${breakdown(old)}`, inner), 'muted')]);
+  }
   if (d.standing && d.standing.count > 0) rows.push([seg(fit(`${plural(d.standing.count, 'older item')} still need${d.standing.count === 1 ? 's' : ''} you · quox lucid`, inner), 'muted')]);
   const act = d.activity;
   if (act && act.total > 0 && !d.compact) {

package/lib/quoxon/onboarding/connectServer.js

@@ -0,0 +1,162 @@
+/**
+ * Connect this machine to a QuoxCORE server: the one implementation behind the TUI's `/connect server <url>` and
+ * the CLI's `quox connect <url>` (ONBOARD-P1).
+ */
+import { spawn as nodeSpawn } 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 { clearJourney } from './journey.js';
+import { defaultInstallDir } from './installRunner.js';
+import { isTrustFixable, readPeerChain, untrustableReason, certCard, storeProfileCert, removeProfileCert, fetchTrusting } from '../../core/profileTrust.js';
+import * as T from './copy.js';
+
+/**
+ * H5: run the sign-in child so it can NEVER outlive this process. Resolves { status, signal } like spawnSync.
+ * The child is killed on every way out: this process receiving SIGTERM/SIGHUP (cancel from a script or chat),
+ * SIGINT (forwarded; in a terminal the child also gets it from the foreground group), an exit of this process,
+ * a spawn error, and a final belt-and-braces kill once settled. Listeners are always removed.
+ * opts.input: text written to the child's stdin (the password for --password-stdin), then stdin is closed.
+ */
+export function runSignInChild(exe, args, { input = null, spawnFn = nodeSpawn, proc = process } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    let settled = false;
+    const kill = (sig = 'SIGTERM') => { try { if (child && child.exitCode == null && child.signalCode == null) child.kill(sig); } catch { /* already gone */ } };
+    const handlers = {};
+    const finish = (r) => {
+      if (settled) return;
+      settled = true;
+      for (const [ev, h] of Object.entries(handlers)) proc.removeListener(ev, h);
+      kill('SIGTERM');
+      resolve(r);
+    };
+    // The parent must live through Ctrl-C to restore the profile, so SIGINT is held and forwarded, not fatal.
+    // A child sitting at a prompt may ignore a lone SIGINT (only a terminal's group Ctrl-C reaches it reliably):
+    // after a short grace, end it and settle as cancelled so connect exits 130 with nothing saved.
+    handlers.SIGINT = () => {
+      kill('SIGINT');
+      const t = setTimeout(() => { if (!settled) { kill('SIGTERM'); finish({ status: null, signal: 'SIGINT' }); } }, 1500);
+      t.unref?.();
+    };
+    handlers.SIGTERM = () => { kill('SIGTERM'); finish({ status: null, signal: 'SIGTERM' }); };
+    handlers.SIGHUP = () => { kill('SIGTERM'); finish({ status: null, signal: 'SIGHUP' }); };
+    handlers.exit = () => kill('SIGKILL');
+    for (const [ev, h] of Object.entries(handlers)) proc.on(ev, h);
+    try {
+      child = spawnFn(exe, args, { stdio: [input == null ? 'inherit' : 'pipe', 'inherit', 'inherit'] });
+    } catch (e) { return finish({ status: null, signal: null, error: e }); }
+    child.on('error', (error) => finish({ status: null, signal: null, error }));
+    child.on('close', (status, signal) => finish({ status, signal }));
+    if (input != null && child.stdin) {
+      child.stdin.on('error', () => { /* child closed stdin early: its exit tells the story */ });
+      child.stdin.end(`${input}\n`);
+    }
+  });
+}
+
+const QUOX_BIN = fileURLToPath(new URL('../../../bin/quox.js', import.meta.url));
+
+/**
+ * /connect server <url>: check the URL is a real QuoxCORE (#1101), point a 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 profile
+ * state and the last-good config.json.bak back, so no half-saved profile is left behind.
+ *
+ * ONBOARD-P1:
+ *   profile  a NAMED profile to create or update (the sign-in then runs as `quox -p <profile> login`). Without
+ *            it the active profile is pointed at the URL, as before.
+ *   trust    async (card) => boolean. When the server answers with its own untrusted certificate, the certificate
+ *            is read and shown; if trust() says yes it is stored ON THAT PROFILE (never the global environment,
+ *            never with TLS checks off). Without trust() the old message is printed and nothing is saved.
+ */
+export async function connectServer(url, {
+  demo = false, spawn = (exe, a, o) => runSignInChild(exe, a, o), 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
+  profile = null, trust = null, email = null, password = null,
+  readChain = readPeerChain, storeCert = storeProfileCert, removeCert = removeProfileCert, trustingFetch = fetchTrusting
+} = {}) {
+  if (demo) { out(`${T.connectHandoff(url)}\n(demo: not connecting)\n`); return { action: 'exit' }; }
+  const load = loadConfigImpl || (await import('../../core/config.js')).loadConfig;
+  const config = load();
+  const name = profile || config.getActiveProfileName?.() || null;
+  let p = await probe(url);
+  let trusted = null; // { file } once this run stored a certificate for the profile
+  const hadCert = profile ? Boolean(config.getProfile?.(profile)?.caCert) : false;
+  if (!p?.ok && p?.kind === 'tls' && isTrustFixable(p.code) && typeof trust === 'function') {
+    const r = await trustServerCert(url, name, { readChain, storeCert, removeCert, trustingFetch, probe, trust, out });
+    if (!r.ok) return { action: 'connect-failed' };
+    trusted = { file: r.file };
+    p = { ok: true };
+  }
+  if (!p?.ok) { out(`${probeMessage(url, p, { localCert: existsSync(localCertPath) ? localCertPath : null })}\n`); return { action: 'connect-failed' }; }
+  const snapshot = profile ? JSON.parse(JSON.stringify(config.getProfile?.(profile) ?? null)) : null;
+  const prev = profile ? null : (config.getActiveProfile()?.url || null);
+  const prevCert = profile ? null : (config.getActiveProfile()?.caCert || null);
+  let bak = null;
+  try { bak = readFileSync(bakFile); } catch { /* no backup yet */ }
+  if (profile) config.upsertProfile(profile, { url, ...(trusted ? { caCert: trusted.file } : {}) });
+  else {
+    config.setProfileConnection({ url });
+    if (trusted) { const ap = config.getActiveProfile(); ap.caCert = trusted.file; config.save(); }
+  }
+  out(`${T.connectHandoff(url)}\n`);
+  // H1: --email/--password-stdin make the sign-in non-interactive; the password goes to the child's stdin, never argv.
+  const loginArgs = [...(profile ? ['-p', profile, 'login'] : ['login']), ...(email ? ['--email', email] : []), ...(email && password ? ['--password-stdin'] : [])];
+  // H5: runSignInChild kills the child on every exit path (the default spawn); a spawn override may return sync or async.
+  // 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 = await spawn(process.execPath, [QUOX_BIN, ...loginArgs], email && password ? { stdio: 'inherit', input: password } : { stdio: 'inherit' }); } finally { process.removeListener('SIGINT', hold); }
+  const cfg = load();
+  // A named profile must really hold a sign-in: `quox login` exits 0 when its prompt is closed without an answer.
+  const signedIn = !profile || Boolean(cfg.getProfile?.(profile)?.auth?.access_token);
+  if (r?.status === 0 && signedIn) { clearJourney(); out(`${T.CONNECT_DONE}\n`); return { action: 'connected', profile: name }; }
+  if (profile) {
+    cfg.restoreProfile(profile, snapshot);
+    if (trusted && !hadCert) removeCert(profile);
+  } else {
+    if (prev) cfg.setProfileConnection({ url: prev });
+    else { const prof = cfg.getActiveProfile(); if (prof) { delete prof.url; cfg.save(); } }
+    if (trusted) {
+      const prof = cfg.getActiveProfile();
+      if (prof) { if (prevCert) prof.caCert = prevCert; else delete prof.caCert; cfg.save(); }
+      if (!prevCert) removeCert(name);
+    }
+  }
+  if (bak) { try { writeFileSync(bakFile, bak, { mode: 0o600 }); } catch { /* best effort */ } }
+  if (r?.status === 130 || r?.signal === 'SIGINT' || r?.signal === 'SIGTERM' || r?.signal === 'SIGHUP') { out(`\x1b[?25h${T.CONNECT_CANCELLED}\n`); return { action: 'connect-cancelled' }; }
+  out(`${T.connectFailed(url)}\n`);
+  return { action: 'connect-failed' };
+}
+
+/**
+ * The untrusted-certificate step: read it, refuse what trusting cannot fix, show the card, ask, store it for the
+ * profile, then prove the server is a QuoxCORE when that certificate (and only it) is trusted.
+ * -> { ok: true, file } | { ok: false }. Prints why on every refusal; stores nothing unless it verified.
+ */
+async function trustServerCert(url, name, { readChain, storeCert, removeCert, trustingFetch, probe, trust, out }) {
+  let peer;
+  try { peer = await readChain(url); } catch (e) {
+    out(`Could not read the certificate from ${url}: ${e.message}. Nothing was saved.\n`);
+    return { ok: false };
+  }
+  const reason = untrustableReason(peer, peer.host);
+  if (reason) { out(`${url} cannot be trusted: ${reason} Nothing was saved.\n`); return { ok: false }; }
+  const card = certCard(url, peer);
+  out(`${card}\n`);
+  const yes = await trust(card, peer);
+  if (!yes) { out('Not trusted. Nothing was saved and no password was asked for.\n'); return { ok: false }; }
+  const file = storeCert(name, peer);
+  const check = await probe(url, { fetchImpl: trustingFetch(peer.chain.map((c) => c.pem).join('')) });
+  if (!check?.ok) {
+    removeCert(name);
+    out(`${url} still did not answer as a QuoxCORE with that certificate trusted (${check?.kind || 'unknown'}${check?.code ? ` ${check.code}` : ''}). The certificate was removed. Nothing was saved.\n`);
+    return { ok: false };
+  }
+  out(`Trusted for profile "${name}" only (stored at ${file}).\n`);
+  return { ok: true, file };
+}

package/lib/quoxon/onboarding/copy.js

@@ -35,6 +35,12 @@ export const DEFERRAL = 'I can answer that properly once your Quox is running.';
 export const OFFER = "To do that I need a QuoxCORE, the engine your agents run in. It runs here in Docker, it's free for your own use, and the first install builds from source, so it takes a while.";
 export const OFFER_ASK = askText('Set it up now?', { keys: '(Y/n)', who: 'Quox', action: 'connect an AI and install the Quox server, step by step' });
 export const ALREADY = 'Already have one? /connect server <url>';
+// ONBOARD-P1: the owner's one plain first-run choice (plan section 13). a is the default and runs `quox server install`.
+export const CHOICES = 'a install Quox here (recommended) · b use a Quox already on this machine · c connect to another server';
+export const LOCAL_CHECKING = 'Looking for a Quox on this machine (localhost only)...';
+export const localFound = (url) => `Found a Quox at ${url}.`;
+export const LOCAL_NONE = 'No Quox answered on this machine (looked at https://localhost:3000 and http://localhost:3000). Type a to install one here, or c to connect to another server.';
+export const CONNECT_ELSEWHERE = 'To use a Quox on another machine, give me its address: /connect server <url>   (the same as: quox connect <url>)';
 export const DECLINED = 'No problem. Run quox any time and we will pick up here.';
 export const DECLINED_HINT = 'Type yes to set up now, /connect server <url> to use one you have, or /exit.';
 

package/lib/quoxon/onboarding/index.js

@@ -5,33 +5,28 @@
  */
 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 { connectServer } from './connectServer.js';
 import { GettingStarted } from './view.js';
 import { inkStdout } from '../term.js';
 import { createCredentialBroker, createRequestCredential } from './credential.js';
 import { createDryRunRunner } from './runner.js';
 import { createInstallRunner, defaultInstallDir, probeAuthHealth } from './installRunner.js';
 import { createFinisher } from './finish.js';
-import { journeyPath as defaultJourneyPath, clearJourney, loadJourney } from './journey.js';
-import * as T from './copy.js';
+import { journeyPath as defaultJourneyPath, loadJourney } from './journey.js';
 import { runDockerOffer } from './dockerOffer.js';
 
 const QUOX_BIN = fileURLToPath(new URL('../../../bin/quox.js', import.meta.url));
 
 /** The real install: get.quox.ai -> scripts/setup.sh, health = the new instance's auth service on loopback. */
-export async function realInstall({ env = process.env } = {}) {
+export async function realInstall({ env = process.env, installDir = null } = {}) {
   // The CLI's own service resolution (honours the per-service overrides); with no server configured
   // yet it derives auth on loopback 127.0.0.1:3101, where the new instance's auth service listens.
   const { loadConfig } = await import('../../core/config.js');
   const authUrl = loadConfig().getServiceUrl('auth');
   const saved = loadJourney();
   return {
-    runner: createInstallRunner({ env, installDir: saved?.installDir || defaultInstallDir(), probeHealth: () => probeAuthHealth(authUrl) }),
+    runner: createInstallRunner({ env, installDir: installDir || saved?.installDir || defaultInstallDir(), probeHealth: () => probeAuthHealth(authUrl) }),
     finisher: await createFinisher()
   };
 }
@@ -58,37 +53,4 @@ export async function runGettingStarted({ version, cwd, welcome = false, earlyIn
   return result;
 }
 
-/**
- * /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 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 });
-  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' };
-}
+export { connectServer };

package/lib/quoxon/onboarding/probe.js

@@ -5,6 +5,7 @@
  *
  * -> { ok: true } | { ok: false, kind: 'url'|'unreachable'|'tls'|'not-quoxcore', code?, status?, detail? }
  */
+import { tlsFailureSentence } from '../../core/profileTrust.js';
 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']);
 
@@ -19,7 +20,7 @@ export async function probeQuoxCore(url, { fetchImpl = globalThis.fetch, timeout
   try {
     res = await fetchImpl(target, { signal: AbortSignal.timeout(timeout), headers: { accept: 'application/json' } });
   } catch (e) {
-    const code = e?.cause?.code || e?.code || null;
+    const code = e?.cause?.code || e?.cause?.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' };
@@ -59,7 +60,25 @@ export function probeMessage(url, r, { localCert = null } = {}) {
         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}`;
       }
+      if (tlsFailureSentence(r.code, url)) return `${tlsFailureSentence(r.code, url)} Never turn TLS checks off. Nothing was saved.`;
       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}`;
   }
 }
+
+/** The only places a Quox already on THIS machine is looked for (owner decision 2026-10-28: no LAN or mDNS scan). */
+export const LOCAL_QUOX_URLS = ['https://localhost:3000', 'http://localhost:3000'];
+
+/**
+ * Read-only: one bounded GET of /health on each known local URL. A self-signed certificate counts as found
+ * (it is how a new Quox answers); the connect step then says how to trust it.
+ * -> { found: true, url, tls?: true } | { found: false }
+ */
+export async function probeLocalQuox({ urls = LOCAL_QUOX_URLS, probe = probeQuoxCore, timeout = 1500 } = {}) {
+  for (const url of urls) {
+    const r = await probe(url, { timeout });
+    if (r?.ok) return { found: true, url };
+    if (r?.kind === 'tls' && /SELF_SIGNED|UNABLE_TO_VERIFY/.test(r.code || '')) return { found: true, url, tls: true };
+  }
+  return { found: false };
+}

package/lib/quoxon/onboarding/view.js

@@ -18,6 +18,7 @@ import * as T from './copy.js';
 import { matchIntent, yesNo, parseConnect } from './intent.js';
 import { loadJourney, saveJourney, clearJourney, resumeStep } from './journey.js';
 import { pendingRows, runPreflight, preflightPassed, detectOllama, defaultDeps } from './preflight.js';
+import { probeLocalQuox } from './probe.js';
 import { credentialOptions, KEY_PROVIDERS, normaliseOllamaUrl, nextSelectable } from './credential.js';
 import { needsConsent, providerLabel } from '../consent.js';
 import { HelloIntro, helloIntroMs } from '../qmotion.js';
@@ -101,8 +102,8 @@ const Hint = ({ text, cols }) => h(Box, { paddingLeft: 2 }, h(Text, { color: c('
 
 // ---- the view ---------------------------------------------------------------------------------
 export function GettingStarted({
-  columns, version = '0.4.0', cwd = '', welcome = false, animateIntro, earlyInput = null,
-  journeyPath, dryRun = false, runner = null, preflightDeps, runChecks = runPreflight, findOllama = detectOllama,
+  columns, version = '0.5.0', cwd = '', welcome = false, animateIntro, earlyInput = null,
+  journeyPath, dryRun = false, runner = null, preflightDeps, runChecks = runPreflight, findLocal = probeLocalQuox, findOllama = detectOllama,
   requestCredential, broker = null, finisher = null, onExit = () => {}, now = () => Date.now()
 }) {
   const { stdin, setRawMode, isRawModeSupported } = useStdin();
@@ -179,7 +180,7 @@ export function GettingStarted({
 
   function offerLines() {
     const items = [{ kind: 'guide', text: T.OFFER }];
-    items.push({ kind: 'ask', text: T.OFFER_ASK }, { kind: 'dim', text: T.ALREADY });
+    items.push({ kind: 'ask', text: T.OFFER_ASK }, { kind: 'dim', text: T.CHOICES }, { kind: 'dim', text: T.ALREADY });
     push(...items);
     set({ step: 'offer' });
     persist();
@@ -218,6 +219,10 @@ export function GettingStarted({
     if (text.startsWith('/')) { onSlash(text); return; }
     if (s.step === 'ask') return onRequest(text);
     if (s.step === 'offer' || s.step === 'declined') {
+      const pick = text.toLowerCase();
+      if (pick === 'a') { push({ kind: 'user', text }); startPreflight(); return; } // install here: the same flow as yes
+      if (pick === 'b') { push({ kind: 'user', text }, { kind: 'dim', text: T.LOCAL_CHECKING }); useLocal(); return; }
+      if (pick === 'c') { push({ kind: 'user', text }, { kind: 'guide', text: T.CONNECT_ELSEWHERE }); return; }
       const yn = yesNo(text);
       if (yn === true) { push({ kind: 'user', text: text || 'yes' }); startPreflight(); return; }
       if (yn === false) { push({ kind: 'user', text }, { kind: 'guide', text: T.DECLINED }, { kind: 'dim', text: T.DECLINED_HINT }); set({ step: 'declined' }); persist(); return; }
@@ -225,6 +230,14 @@ export function GettingStarted({
     }
   }
 
+  async function useLocal() {
+    const f = await findLocal();
+    if (!live.current || S.current.done) return;
+    if (!f.found) { push({ kind: 'guide', tone: 'warn', text: T.LOCAL_NONE }); return; }
+    push({ kind: 'guide', tone: 'ok', text: T.localFound(f.url) }, { kind: 'guide', text: T.connectChecking(f.url) });
+    exit({ action: 'connect', url: f.url });
+  }
+
   async function startPreflight() {
     set({ step: 'preflight', rows: pendingRows(), fixNote: null });
     persist();

package/lib/quoxon/orgSwitch.js

@@ -8,7 +8,29 @@ export const orgRows = (list) => (Array.isArray(list) ? list : []).map((o) => ({
  * query found in the name or slug (so "acme widgets" finds "Acme Widgets Ltd"). Never guesses between ties.
  * -> { org } | { ambiguous: [orgs] } | { none: true }
  */
+const VERBS = new Set(['switch', 'swith', 'swich', 'sw', 'to', 'go', 'use']);
+/** Drop ONE leading verb-ish token ("swith quox dev" -> "quox dev"); a lone verb is kept (it may be the name). */
+export function stripOrgVerb(query) {
+  const m = /^(\S+)\s+(\S[\s\S]*)$/.exec(String(query ?? '').trim());
+  return m && VERBS.has(m[1].toLowerCase()) ? m[2].trim() : String(query ?? '').trim();
+}
+
+/** Orgs for a picker when nothing matched uniquely: those hitting the most query words (verb stripped), at least one. */
+export function orgCandidates(query, list) {
+  const words = norm(stripOrgVerb(query)).split(' ').filter(Boolean);
+  const scored = orgRows(list).map((o) => { const hay = `${norm(o.name)} ${norm(o.slug)}`; return { o, n: words.filter((w) => hay.includes(w)).length }; });
+  const best = Math.max(0, ...scored.map((x) => x.n));
+  return best ? scored.filter((x) => x.n === best).map((x) => x.o) : [];
+}
+
 export function matchOrg(query, list) {
+  const first = matchOrgExact(query, list);
+  if (!first.none) return first;
+  const stripped = stripOrgVerb(query);
+  return stripped !== String(query ?? '').trim() ? matchOrgExact(stripped, list) : first;
+}
+
+function matchOrgExact(query, list) {
   const rows = orgRows(list);
   const q = norm(query);
   if (!q) return { none: true };

package/lib/quoxon/print.js

@@ -4,6 +4,7 @@
  * Exit codes: 0 completed, 2 held for approval, 3 interrupted, 4 auth, 5 unconfirmed
  * (stream closed without turn.finished), 1 other.
  */
+import { eventLine } from '../core/announce.js';
 import { textGate } from './events.js';
 import { streamFields, fallbackNote } from './model.js';
 import { connectOfferFor } from './connect.js';
@@ -60,6 +61,7 @@ export async function runPrint({ api, prompt, agent = 'quox', output = 'text', c
       else if (ev.type === 'done' && !text && ev.full_response) text = ev.full_response;
       else if (ev.type === 'tool.started' && !seen.has(ev.call_id)) { seen.add(ev.call_id); sum.tools++; }
       else if (ev.type === 'tool.finished') { if (!seen.has(ev.call_id)) { seen.add(ev.call_id); sum.tools++; } if (ev.receipt?.ward_seq != null) sum.receipts.push(ev.receipt.ward_seq); }
+      else if (ev.type === 'quox_event') { if (output !== 'json') { const q = eventLine(ev); if (q) err(`${q}\n`); } } // QUOX-ANNOUNCE A2: stdout stays the answer
       else if (ev.type === 'approval.requested') { sawApproval = true; sum.approvals++; }
       else if (ev.type === 'approval.resolved') sawApproval = false;
       else if (ev.type === 'turn.objective_suggested' && ev.objective_suggested?.goal) objective = ev.objective_suggested; // QUOXON objective offer

package/lib/quoxon/profileSwitch.js

@@ -23,6 +23,13 @@ export const switchAskLine = (profile, human) => askText('Switch?', {
   action: `switch this window to your login '${human}' (same conversation, attach, slot and groups)`,
 });
 
+/** The startup offer on an agent login (owner 2026-10-28): restart as the human profile; /profile lists the rest. */
+export const startupSwitchAskLine = (profile, human, others = 0) => askText(`Restart as you (${human})?`, {
+  title: `This window would run as the agent '${profile}'.`,
+  action: `restart this window as '${human}' (same directory, nothing else changes)`,
+  reason: others > 0 ? `${others} other signed-in profile${others === 1 ? '' : 's'}: /profile lists them` : '',
+});
+
 /** The ask card for a /slot name that does not exist (the near misses are said on the line above). */
 export const slotCreateAskLine = (nm) => askText('Create it?', { title: `No slot ${nm}.`, action: `create and hold slot ${nm}` });