quoxcli 0.3.1 → 0.5.0

package/lib/quoxon/objectiveOffer.js

@@ -0,0 +1,82 @@
+/**
+ * QUOXON objective offer (owner, live 2026-10-25 19:47). Attached to SEER (advisory, no image/X/site tools) the owner asked
+ * for a blog article, an image, a publish and a tweet draft, and got "I couldn't". Offer, don't give up: the server sends
+ * turn.objective_suggested (from the turn's tool selection and the shape of the ask, never the answer text) and the TUI
+ * asks once. It REPLACES the single-turn handoff card (one ask, not two):
+ *
+ *   ⚠ SEER asks: Make this an objective that runs until done?
+ *     do     create objective "<the user's words>"; you approve the plan, then each publish/post step
+ *     why    SEER can't run x post.
+ *   ▶ Make this an objective that runs until done? y yes · n no
+ *
+ * y = `quox objective create <goal>` + start (the plan decomposes and lands as an approval card). n does nothing.
+ */
+import { askText } from './ask.js';
+
+const clipQ = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t; };
+
+/** The suggestion from a turn event, when it applies to THIS window (attached to the agent it names). Else null. */
+export function objectiveFromEvent(ev, attachedAgent) {
+  if (!ev || ev.type !== 'turn.objective_suggested') return null;
+  const o = ev.objective_suggested;
+  const at = String(attachedAgent || '').toLowerCase();
+  if (!o || typeof o !== 'object' || !o.from || !o.goal || !at) return null;
+  if (String(o.from).toLowerCase() !== at) return null; // a suggestion about some other agent
+  const loop = o.mode === 'loop' && o.loop && Array.isArray(o.loop.capability_scope) && o.loop.capability_scope.length ? { goal_condition: String(o.loop.goal_condition || o.goal), capability_scope: o.loop.capability_scope.map(String), ...(o.loop.plain ? { plain: true } : {}), ...(Number.isInteger(o.loop.max_iterations) ? { max_iterations: o.loop.max_iterations } : {}), ...(o.loop.summary ? { summary: String(o.loop.summary) } : {}), ...(o.loop.until ? { until: String(o.loop.until) } : {}), ...(Number.isInteger(o.loop.every_seconds) ? { every_seconds: o.loop.every_seconds } : {}), ...(Number.isInteger(o.loop.max_duration_seconds) ? { max_duration_seconds: o.loop.max_duration_seconds } : {}), ...(Array.isArray(o.loop.done_check) && o.loop.done_check.length ? { done_check: o.loop.done_check } : {}) } : null; // QLOOP: a ready, engine-valid loop spec
+  return { from: at, fromName: String(o.from_name || at.toUpperCase()), goal: String(o.goal), reason: String(o.reason || '').trim(), tools: Array.isArray(o.tools) ? o.tools : [], ...(loop ? { loop } : {}) };
+}
+
+/** The ask line (drawn as the approval-style card). The goal is clipped for the card only, never in what yes creates. */
+export function objectiveAskText(o, cols = 100) {
+  if (o.loop && o.loop.plain) { // the user never said "loop": say what it does, in plain words, whole (it wraps; never clipped)
+    const mins = o.loop.max_duration_seconds ? Math.max(1, Math.round(o.loop.max_duration_seconds / 60)) : null;
+    const q = o.loop.summary ? `${o.loop.summary}?` : `This needs repeated checks: keep going until ${String(o.loop.goal_condition || o.goal).replace(/\s+/g, ' ').trim()}${mins ? `, up to ${mins} minute${mins === 1 ? '' : 's'}` : ''}?`;
+    return askText(q, { keys: 'y yes · n just once', who: o.fromName, reason: '', action: `keep going${o.loop.every_seconds ? `, checking about every ${o.loop.every_seconds} seconds,` : ''} using only ${o.loop.capability_scope.join(', ')}; you approve it before it starts` });
+  }
+  if (o.loop) return askText('Run this as a loop until it is done?', { keys: 'y/N', who: o.fromName, reason: o.reason, action: `create a loop "${clipQ(o.goal, Math.max(20, cols - 70))}" that may use only ${o.loop.capability_scope.join(', ')}; you approve it before it starts` });
+  const action = `create objective "${clipQ(o.goal, Math.max(20, cols - 60))}"; you approve the plan, then each publish/post step`;
+  return askText('Make this an objective that runs until done?', { keys: 'y/N', who: o.fromName, reason: o.reason, action });
+}
+
+export const objectiveStartedNote = (id) => `▶ Objective ${id} started. The plan will land as an approval card.`;
+export const objectiveWatchLine = (id) => `Watch it: quox objective get ${id}`;
+export const objectiveFailedNote = (goal, err) => `Objective not created: ${String(err?.message || err || 'unknown error')}. Retry: quox objective create ${JSON.stringify(goal)} --checkpoint`;
+
+// ---- report back into the conversation (owner 2026-10-26) ----
+const TERMINAL = new Set(['completed', 'completed_with_errors', 'failed', 'cancelled', 'aborted']);
+// A finished step's result is the node output JSON; its text is completion.value.
+const textOf = (r) => { const s = String(r ?? ''); if (!s.trimStart().startsWith('{')) return s; try { const o = JSON.parse(s); return typeof o?.completion?.value === 'string' ? o.completion.value : s; } catch { return s; } };
+const reportOf = (tasks) => {
+  const done = (tasks || []).filter(t => t.status === 'completed' && textOf(t.result).trim()).sort((a, b) => (a.sequence_num || 0) - (b.sequence_num || 0));
+  const pick = [...done].reverse().find(t => /report/i.test(String(t.title || ''))) || done[done.length - 1];
+  const text = pick ? textOf(pick.result).trim() : '';
+  return text.length > 1500 ? `${text.slice(0, 1499)}…` : text;
+};
+
+/** The lines the chat prints when an objective ends: the glyph line, then its report (or what did not complete). */
+export function objectiveFinishedLines(o) {
+  const tasks = Array.isArray(o.tasks) ? o.tasks : [];
+  const done = tasks.filter(t => t.status === 'completed').length;
+  const title = String(o.title || o.id || '').replace(/\s+/g, ' ').slice(0, 80);
+  const lines = [`◎ OBJECTIVE │ ${title} │ ${o.status}, ${done}/${tasks.length} steps`];
+  const report = reportOf(tasks);
+  if (report) lines.push(...report.split('\n').map(l => l.trimEnd()).filter(Boolean));
+  if (o.status !== 'completed' && o.error_message) lines.push(String(o.error_message).slice(0, 400));
+  return lines;
+}
+
+/**
+ * Poll an objective while this window is open and say how it ended. get() -> the objective with its tasks; a failed read is
+ * retried, never fatal. Resolves { finished, status }. Gives up quietly at maxMs or when stopped() (the inbox item covers a closed window).
+ */
+export async function watchObjective({ get, say, intervalMs = 8000, maxMs = 6 * 3600 * 1000, stopped = () => false } = {}) {
+  const t0 = Date.now();
+  while (Date.now() - t0 < maxMs && !stopped()) {
+    try {
+      const o = await get();
+      if (o && TERMINAL.has(o.status)) { for (const l of objectiveFinishedLines(o)) say(l); return { finished: true, status: o.status }; }
+    } catch { /* a transient read: try again */ }
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  return { finished: false };
+}

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/objects/index.js

@@ -11,6 +11,7 @@ import { agentCard } from './agent.js';
 import { memoryFacts } from './memory.js';
 import { rulesLadder } from './ladder.js';
 import { proofChain, reconcileView } from './proof.js';
+import { wrapHang } from './model.js';
 import { awayCard } from './away.js';
 import { sitrepCard } from './sitrep.js';
 import { fleetView } from './fleet.js';
@@ -91,10 +92,27 @@ export async function runObjectCommand(cmd, arg, ctx) {
       });
     }
     case '/proof': {
-      const calls = toolCalls(ctx.items).filter(b => b.envelopeId);
-      const t = a ? calls.find(b => b.envelopeId === a || b.callId === a) : calls[calls.length - 1];
-      if (!t) return { note: a ? `No tool call "${a}" with an envelope in this session.` : 'No tool call with an envelope id in this session yet.', tone: 'warn' };
-      return wrap('proof', () => o.proof({ tool: t.tool, status: t.status, envelopeId: t.envelopeId, callId: t.callId }));
+      const all = toolCalls(ctx.items);
+      const calls = all.filter(b => b.envelopeId);
+      const newest = [...calls].reverse(); // 1 = newest
+      const num = /^\d{1,3}$/.test(a) ? Number(a) : 0;
+      const pick = (b) => wrap('proof', () => o.proof({ tool: b.tool, status: b.status, envelopeId: b.envelopeId, callId: b.callId }));
+      if (num >= 1 && newest[num - 1]) return pick(newest[num - 1]);
+      const t = a && !num ? calls.find(b => b.envelopeId === a || b.callId === a) : (calls.length === 1 ? calls[0] : null);
+      if (t) return pick(t);
+      if (a) return { note: `No tool call "${a}" with an envelope in this session. /proof lists them; /evidence exports the whole conversation.`, tone: 'warn' };
+      if (!calls.length) {
+        const ran = all.length ? ` ${all.length} tool call${all.length === 1 ? '' : 's'} ran, but the server reported no envelope id for ${all.length === 1 ? 'it' : 'them'}.` : '';
+        return { note: `No tool call with an envelope id in this session yet.${ran} /evidence exports what the server filed for this conversation.`, tone: 'warn' };
+      }
+      // Several calls: list the envelope ids, newest first (ten), then how many more.
+      const shown = newest.slice(0, 10);
+      const W = Math.max(20, (ctx.cols || 1e9) - 4);
+      const lines = [...wrapHang(`${calls.length} tool call${calls.length === 1 ? '' : 's'} with an envelope in this conversation (newest first):`, W, 2),
+        ...shown.flatMap((b, i) => wrapHang(`  ${i + 1}. ${b.envelopeId}  ${b.tool || 'tool'} ${b.status || ''}`.trimEnd(), W, 5))];
+      if (newest.length > shown.length) lines.push(`  ${newest.length - shown.length} more (older)`);
+      lines.push(...wrapHang('/proof <number or id> shows one chain. /evidence exports the signed bundle of all of them.', W, 2));
+      return { note: lines.join('\n'), lines, tone: 'dim' };
     }
     case '/reconcile': {
       const unk = toolCalls(ctx.items).filter(b => b.status === 'effect_unknown');

package/lib/quoxon/objects/model.js

@@ -21,6 +21,39 @@ export const fit = (s, n) => {
   return g.length > n ? g.slice(0, Math.max(0, n - 1)).join('') + '…' : g.join('');
 };
 
+/**
+ * Wrap a string to `width` display chars, never clipping: breaks at spaces, indents each continuation by `hang`
+ * spaces beyond the line's own leading indent, and hard-splits a token longer than the line (an id stays whole
+ * across rows, no ellipsis). -> string[]
+ */
+export function wrapHang(text, width, hang = 4) {
+  const src = String(text ?? '');
+  const lead = (src.match(/^ */) || [''])[0];
+  const words = src.trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return [src];
+  const w = Math.max(8, width);
+  const lines = [];
+  let cur = lead;
+  let curHas = false;
+  const pad = () => lead + ' '.repeat(hang);
+  const push = () => { lines.push(cur); cur = pad(); curHas = false; };
+  for (let word of words) {
+    while (len(cur) + (curHas ? 1 : 0) + len(word) > w) {
+      if (curHas) { push(); continue; }
+      const room = Math.max(1, w - len(cur));
+      const g = [...word];
+      if (g.length <= room) break;
+      cur += g.slice(0, room).join('');
+      word = g.slice(room).join('');
+      push();
+    }
+    cur += (curHas ? ' ' : '') + word;
+    curHas = true;
+  }
+  if (curHas) lines.push(cur);
+  return lines;
+}
+
 /** Clip a row of segments to n chars total; later segments shrink first, the last one gets the ellipsis. */
 export function fitRow(row, n) {
   const out = [];

package/lib/quoxon/objects/proof.js

@@ -10,7 +10,7 @@
  * D3: a tool that ended effect_unknown is reconciled against the server's own record of the call
  * (the ops.tool envelope's payload.success). No envelope id means it cannot be reconciled from here.
  */
-import { seg, fit, short, plural } from './model.js';
+import { seg, fit, plural, wrapHang } from './model.js';
 
 const LINKS = ['AEE', 'AOCL', 'TOOL', 'WARD'];
 
@@ -19,7 +19,7 @@ export function chainLinks(d) {
   const t = d.tool || {};
   const env = d.envelope?.ok ? d.envelope.env : null;
   const out = [];
-  out.push(env ? { name: 'AEE', ok: true, sub: `envelope ${short(env.id || t.envelopeId, 14)}` }
+  out.push(env ? { name: 'AEE', ok: true, sub: 'envelope read, id above' }
     : { name: 'AEE', ok: d.envelope?.status === 404 ? false : null, sub: d.envelope?.status === 404 ? 'envelope not found' : `envelope not read${d.envelope?.error ? ` (${fit(d.envelope.error, 24)})` : ''}` });
   const aocl = d.aocl?.ok ? d.aocl.list || [] : null;
   if (aocl && aocl.length) {
@@ -52,7 +52,13 @@ const markOf = (ok) => (ok === true ? ['✔', 'ok'] : ok === false ? ['✖', 'er
 export function proofChain(d, cols) {
   const links = chainLinks(d);
   const rows = [];
-  rows.push([seg('proof ', 'muted'), seg(fit(`${d.tool?.tool || 'tool call'}${d.tool?.envelopeId ? ` · ${short(d.tool.envelopeId, 18)}` : ''}`, cols - 10), 'value', true)]);
+  const envId = d.tool?.envelopeId || (d.envelope?.ok ? d.envelope.env?.id : null);
+  rows.push([seg('proof ', 'muted'), seg(fit(d.tool?.tool || 'tool call', cols - 10), 'value', true)]);
+  // The full id on its own row, never clipped, so it can be selected and copied whole.
+  if (envId) {
+    wrapHang(envId, cols - 7, 0).forEach((l, i) => rows.push([seg(i ? '   ' : 'id ', 'muted'), seg(l, 'value', true)]));
+    for (const t of [`read it back: quox aee get ${envId}`, 'check a bundle: quox evidence verify <file>']) for (const l of wrapHang(t, cols - 4, 2)) rows.push([seg(l, 'muted')]);
+  }
   if (cols >= 90) {
     const head = [], sub = [], cw = Math.max(23, Math.floor((cols - 4) / 4));
     links.forEach((l, i) => {
@@ -69,7 +75,9 @@ export function proofChain(d, cols) {
     links.forEach((l, i) => {
       const role = `proto:${l.name.toLowerCase() === 'tool' ? 'volt' : l.name.toLowerCase()}`;
       const [m, mr] = markOf(l.ok);
-      rows.push([seg(m, mr), seg(' '), seg(l.name.padEnd(5), l.name === 'TOOL' ? 'value' : role, true), seg(fit(l.sub, cols - 12), l.ok === false ? 'error' : 'muted')]);
+      const subs = wrapHang(l.sub, cols - 11, 0);
+      rows.push([seg(m, mr), seg(' '), seg(l.name.padEnd(5), l.name === 'TOOL' ? 'value' : role, true), seg(subs[0], l.ok === false ? 'error' : 'muted')]);
+      for (const more of subs.slice(1)) rows.push([seg(' '.repeat(7)), seg(more, l.ok === false ? 'error' : 'muted')]);
       if (i < 3) rows.push([seg(l.ok === true && links[i + 1].ok === true ? '┃' : '╎', l.ok === true && links[i + 1].ok === true ? 'indigo' : 'faint')]);
     });
   }

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/shortcutOffer.js

@@ -0,0 +1,28 @@
+/**
+ * QUOXON-Q: after first-run onboarding succeeds, ONE offer (y/N, default No, asked once) to make `q` run quox.
+ * The answer is remembered in the CLI config (shortcutOffer = 'yes' | 'no'). A yes runs the same code as
+ * `quox shortcut add`. Nothing is offered when q already resolves to something (ours or not): never shadow.
+ */
+import { askText } from '../ask.js';
+import { addShortcut, whichOnPath, DEFAULT_NAME } from '../../core/shortcut.js';
+
+export const SHORTCUT_QUESTION = 'Want a shorter command? Type `q` instead of `quox`.';
+export const shortcutOfferLine = () => askText(SHORTCUT_QUESTION, { keys: 'y/N', who: 'Quox', action: `make \`${DEFAULT_NAME}\` a link to quox in a folder you own (no sudo, no shell edits); undo with: quox shortcut remove` });
+
+/** -> true when the offer should be shown now. */
+export function shouldOfferShortcut({ config, env = process.env, which = whichOnPath } = {}) {
+  if (config?.get?.('shortcutOffer')) return false; // asked once
+  return !which(DEFAULT_NAME, env);
+}
+
+/** Runs the offer. ask(line) -> string answer. -> { offered, accepted, result? } */
+export async function offerShortcut({ config, ask, out = (s) => process.stdout.write(s), env = process.env, add = addShortcut, which = whichOnPath } = {}) {
+  if (!shouldOfferShortcut({ config, env, which })) return { offered: false };
+  const answer = String(await ask(shortcutOfferLine()) ?? '').trim();
+  const accepted = /^y(es)?$/i.test(answer);
+  config.set('shortcutOffer', accepted ? 'yes' : 'no');
+  if (!accepted) return { offered: true, accepted: false };
+  const result = add({ name: DEFAULT_NAME, env });
+  out(`${result.ok ? '✔' : '✖'} ${result.message}\n`);
+  return { offered: true, accepted: true, result };
+}