quoxcli 0.2.0 → 0.4.0

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

@@ -0,0 +1,130 @@
+/**
+ * /prove: independently verify the last turn's tool calls. Two independent checks per call:
+ *   1. the receipt chain (the same reads as /proof: AEE envelope, the server's own record of the call,
+ *      the WARD inclusion receipt), and
+ *   2. a TRUTH read: for a write whose effect we know how to read back (VERIFIERS below), read it back
+ *      from the system of record and see whether it is really there.
+ * Per call: proven (chain agrees and, for a mapped write, the effect is there), unproven (cannot be shown:
+ * an unmapped write, a read that failed, no receipt) or contradicts (the stream said ok and the server or
+ * the truth read disagrees, or the call failed). An unmapped write is never called proven.
+ *
+ * Extending: push an entry on VERIFIERS: { id, tools: [tool names], keys: [arg names to find in the call
+ * summary], read: (reads, target) -> true | false | null, describe: (target, found) -> text }.
+ */
+import { seg, fit, fitRow, short, boxWidth } from './model.js';
+import { chainLinks } from './proof.js';
+
+export const VERIFIERS = [
+  { id: 'slot_create', tools: ['slot_create'], keys: ['name', 'slot'], read: (r, t) => r.slotExists(t), describe: (t, f) => (f ? `slot "${t}" exists` : `slot "${t}" not found`) },
+  { id: 'memory_save', tools: ['memory_save'], keys: ['content', 'text', 'fact'], read: (r, t) => r.memoryFind(t), describe: (t, f) => (f ? `memory "${fit(t, 24)}" is stored` : `memory "${fit(t, 24)}" not found`) }
+];
+
+export const verifierFor = (tool) => VERIFIERS.find(v => v.tools.includes(tool)) || null;
+
+/** Tools that only read: their receipt chain is the whole proof (nothing changed to read back). */
+const READ_RE = /_(list|read|get|search|stats|history|usage|brief|notes|roadmaps|streams|folders|zones|pending|accounts|blocked|proposals|latest|query|status|show)$/;
+export const isReadTool = (tool) => READ_RE.test(String(tool || ''));
+
+/** The thing to check, from the call summary: key=value, key: "value", else the first quoted string. */
+export function targetOf(tool, summary) {
+  const s = String(summary || '');
+  const v = verifierFor(tool);
+  for (const k of v?.keys || ['name']) {
+    const m = new RegExp(`\\b${k}\\s*[=:]\\s*(?:"([^"]+)"|'([^']+)'|([\\w.\\-]+))`, 'i').exec(s);
+    if (m) return m[1] || m[2] || m[3];
+  }
+  const q = /["“]([^"”]+)["”]/.exec(s);
+  return q ? q[1] : null;
+}
+
+/** -> { mapped:false } | { mapped:true, found: true|false|null, what?, error?, noTarget? }. Never throws. */
+export async function runTruth(call, reads) {
+  const v = verifierFor(call.tool);
+  if (!v) return { mapped: false };
+  const target = targetOf(call.tool, call.summary);
+  if (!target) return { mapped: true, found: null, noTarget: true };
+  try {
+    const found = await v.read(reads, target);
+    return { mapped: true, found: found === true ? true : found === false ? false : null, what: v.describe(target, found === true) };
+  } catch (e) {
+    return { mapped: true, found: null, error: e?.status ? `HTTP ${e.status}` : e?.message || 'failed' };
+  }
+}
+
+/** Settled tool calls after the last user message of `items` (history + live blocks). */
+export function lastTurnCalls(items) {
+  const list = items || [];
+  let from = 0;
+  for (let i = list.length - 1; i >= 0; i--) if (list[i]?.kind === 'user' && !list[i].echo) { from = i + 1; break; }
+  return list.slice(from).filter(b => b && b.kind === 'tool' && b.status !== 'running');
+}
+
+const V = (state, why, call) => ({ state, mark: state === 'proven' ? '✔' : state === 'contradicts' ? '✖' : '⚠', why, envelopeId: call.envelopeId || null });
+
+/** { call, proof, truth } -> { state, mark, why, envelopeId }. Pure. */
+export function verdictFor({ call, proof, truth }) {
+  const bad = !['ok', 'effect_unknown'].includes(call.status);
+  if (bad) return V('contradicts', `the call ${call.status || 'did not finish'}, so the task did not get done`, call);
+  if (!call.envelopeId) return V('unproven', 'no receipt id on this call', call);
+  const links = proof ? chainLinks(proof) : [];
+  const by = Object.fromEntries(links.map(l => [l.name, l]));
+  if (by.TOOL?.ok === false) return V('contradicts', by.TOOL.sub, call);
+  if (by.WARD?.ok === false) return V('contradicts', `WARD: ${by.WARD.sub}`, call);
+  if (by.AEE?.ok !== true) return V('unproven', `receipt not confirmed (${by.AEE?.sub || 'not read'})`, call);
+  if (by.TOOL?.ok !== true) return V('unproven', 'no server record of the call outcome', call);
+  if (truth?.mapped) {
+    if (truth.found === true) return V('proven', `${truth.what || 'effect found'} · server recorded success`, call);
+    if (truth.found === false) return V('contradicts', `${truth.what || 'effect not found'}, though the call reported ok`, call);
+    return V('unproven', truth.noTarget ? 'could not tell which thing to check from the call' : `effect not read back (${truth.error || 'no answer'})`, call);
+  }
+  if (isReadTool(call.tool)) return V('proven', 'read call · receipt chain checked', call);
+  return V('unproven', `no read mapping for ${call.tool}: receipt checked, effect not independently read`, call);
+}
+
+/** d: { items: [{ call, proof, truth }] } -> view { box, rows } */
+export function proveView(d, cols) {
+  const w = boxWidth(cols, 90), inner = w - 4, nw = w < 60;
+  const rows = [];
+  const tally = { proven: 0, unproven: 0, contradicts: 0 };
+  const items = d.items || [];
+  for (const it of items) {
+    const v = verdictFor(it);
+    tally[v.state]++;
+    const role = v.state === 'proven' ? 'ok' : v.state === 'contradicts' ? 'error' : 'warn';
+    rows.push([seg(v.mark, role, true), seg(' '), seg(fit(it.call.tool || 'tool', 14).padEnd(15), 'value', true), seg(v.state.padEnd(12), role, true), ...(nw ? [] : [seg(fit(v.why, inner - 30), 'muted')])]);
+    rows.push([seg('  '), ...(nw ? [seg(fit(v.why, inner - 2), 'muted')] : []), seg(v.envelopeId ? `${nw ? '' : '  '}receipt ${short(v.envelopeId, nw ? 12 : 22)}` : '  no receipt', 'muted')]);
+  }
+  if (!items.length) rows.push([seg('no tool calls to check', 'muted')]);
+  rows.push([seg(`${tally.proven} proven · ${tally.unproven} unproven · ${tally.contradicts} contradicts`, tally.contradicts ? 'error' : tally.unproven ? 'warn' : 'ok', true)]);
+  return { box: { width: w, title: 'Prove · last turn', titleRole: 'indigo', border: 'indigo' }, rows: rows.map(r => fitRow(r, inner)), tally };
+}
+
+/** Fetchers for createObjectsApi. deps: { self (the objects api, for proof), get, listOf, resolveEndpoint } */
+export function proveFetchers({ self, get, listOf, resolveEndpoint }) {
+  const reads = {
+    async slotExists(name) {
+      const ep = resolveEndpoint('v1.slots.list');
+      const rows = listOf(await get('collector', ep.path, undefined, 10000), 'slots');
+      return rows.some(s => String(s.name || '').toLowerCase() === String(name).toLowerCase());
+    },
+    async memoryFind(text) {
+      const d = await get('memory', '/api/memory/search', { q: text, limit: 10 }, 10000);
+      const want = String(text).toLowerCase().slice(0, 60);
+      return listOf(d, 'results', 'memories', 'data').some(m => JSON.stringify(m).toLowerCase().includes(want));
+    }
+  };
+  return {
+    reads,
+    /** calls: tool blocks { tool, status, summary, envelopeId, callId } -> { data: { items } } */
+    async prove(calls) {
+      const items = await Promise.all((calls || []).slice(-12).map(async (call) => {
+        const [proof, truth] = await Promise.all([
+          call.envelopeId ? self.proof({ tool: call.tool, status: call.status, envelopeId: call.envelopeId, callId: call.callId }).then(r => r.data).catch(() => null) : null,
+          runTruth(call, reads)
+        ]);
+        return { call: { tool: call.tool, status: call.status, summary: call.summary, envelopeId: call.envelopeId || null }, proof, truth };
+      }));
+      return { data: { items } };
+    }
+  };
+}

package/lib/quoxon/objects/replay.js

@@ -0,0 +1,125 @@
+/**
+ * /replay [run | conversation id] [page]: reconstruct a previous agent run from the audit trail, in order:
+ * the decisions (turn messages), each tool with an args summary, its output and its receipt. Read-only:
+ * nothing is re-executed (sandbox re-execution is not available). Default is the last turn of this
+ * conversation. Sources: the conversation's saved turns, this session's tool calls, and AEE envelopes
+ * (GET /aee/:id, GET /aee/query?corr=). A conversation id replays the messages only: the server does not link
+ * tool envelopes to a conversation, so the view says so and points at /replay <envelope id> for a tool run.
+ */
+import { seg, fit, fitRow, short, dur, boxWidth, parseTs } from './model.js';
+
+export const PAGE = 6;
+
+/** '' | '2' | 'abc' | 'abc 3' | 'abc page 3' | 'page 3' -> { ref, page } */
+export function parseReplayArg(arg) {
+  let t = String(arg || '').trim();
+  let page = 1;
+  const m = /(?:^|\s)(?:page\s+)?(\d{1,4})$/i.exec(t);
+  const pm = /(?:^|\s)page\s+(\d{1,4})$/i.exec(t);
+  if (pm) { page = Number(pm[1]); t = t.slice(0, pm.index).trim(); }
+  else if (m && (m.index > 0 || t === m[1]) && !/^\d{5,}$/.test(t)) { page = Number(m[1]); t = t.slice(0, m.index).trim(); }
+  return { ref: t || null, page: Math.max(1, page) };
+}
+
+const receiptOf = (c) => `${c.envelopeId ? `receipt ${c.envelopeId}` : 'no receipt id'}${c.receipt?.verified && c.receipt.ward_seq != null ? ` · WARD seq ${c.receipt.ward_seq}` : ''}`;
+
+/** { messages: [{ role, content }], calls: [tool blocks] } -> steps: the question, each tool, then the answer. */
+export function buildTurnSteps({ messages = [], calls = [] }) {
+  const steps = [];
+  const users = messages.filter(m => m.role === 'user'), agents = messages.filter(m => m.role !== 'user');
+  for (const m of users) steps.push({ kind: 'user', text: String(m.content ?? '') });
+  for (const c of calls) steps.push({ kind: 'tool', tool: c.tool, args: c.summary || '', status: c.status, out: c.resultSummary || '', ms: c.durationMs, receipt: receiptOf(c), id: c.envelopeId || null });
+  for (const m of agents) steps.push({ kind: 'agent', text: String(m.content ?? '') });
+  return steps;
+}
+
+/** AEE envelopes of one correlation id -> steps in time order. */
+export function buildEnvelopeSteps(envs = []) {
+  const sorted = [...envs].sort((a, b) => (parseTs(a.ts) ?? 0) - (parseTs(b.ts) ?? 0));
+  return sorted.map((e) => {
+    const p = e.payload || {};
+    const intent = String(e.intent || '');
+    if (/^ops\.tool\./.test(intent)) {
+      const ok = p.success !== false && !/\.failed$|\.denied$/.test(intent);
+      return { kind: 'tool', id: e.id, tool: p.tool_name || intent, args: p.input_summary || p.summary || '', status: /\.denied$/.test(intent) ? 'denied' : ok ? 'ok' : 'failed', out: ok ? (p.result_summary || '') : (p.error || intent), ms: p.duration_ms, receipt: `receipt ${e.id}` };
+    }
+    if (intent === 'aocl.policy.evaluated') return { kind: 'policy', id: e.id, text: p.allPassed === false ? 'policy blocked' : 'policy passed', receipt: `receipt ${e.id}` };
+    if (intent === 'aocl.identity.verified') return { kind: 'policy', id: e.id, text: 'identity verified', receipt: `receipt ${e.id}` };
+    return { kind: 'event', id: e.id, text: `${intent || 'envelope'}${e.from ? ` from ${e.from}` : ''}`, receipt: `receipt ${e.id}` };
+  });
+}
+
+const MARK = { ok: ['✔', 'ok'], failed: ['✖', 'error'], denied: ['✖', 'error'] };
+
+/** d: { steps, page, size, title, notes } -> view { box, rows } */
+export function replayView(d, cols) {
+  const w = boxWidth(cols, 96), inner = w - 4, nw = w < 60;
+  const size = d.size || PAGE;
+  const steps = d.steps || [];
+  const pages = Math.max(1, Math.ceil(steps.length / size));
+  const page = Math.min(Math.max(1, d.page || 1), pages);
+  const rows = [];
+  if (!steps.length) rows.push([seg('nothing recorded for this run', 'muted')]);
+  const base = (page - 1) * size;
+  steps.slice(base, base + size).forEach((s, i) => {
+    const n = String(base + i + 1).padStart(2);
+    const label = s.kind === 'user' ? 'you' : s.kind === 'agent' ? 'agent' : s.kind === 'tool' ? 'tool' : s.kind === 'policy' ? 'guard' : 'event';
+    const lrole = s.kind === 'user' ? 'sky' : s.kind === 'agent' ? 'violet' : s.kind === 'tool' ? 'indigo' : 'muted';
+    if (s.kind === 'tool') {
+      const [m, mr] = MARK[s.status] || ['○', 'muted'];
+      rows.push([seg(n + ' ', 'muted'), seg(label.padEnd(6), lrole, true), seg(`${s.tool} `, 'value', true), seg(m, mr), seg(` ${s.status || 'unknown'}${s.ms != null ? ` ${dur(s.ms)}` : ''}`, mr)]);
+      if (s.args) rows.push([seg('     args    ', 'muted'), seg(s.args, 'value')]);
+      if (s.out) rows.push([seg('     output  ', 'muted'), seg(s.out, s.status === 'ok' ? 'value' : 'warn')]);
+      rows.push([seg('     ', 'muted'), seg(s.receipt || 'no receipt id', 'muted')]);
+    } else {
+      rows.push([seg(n + ' ', 'muted'), seg(label.padEnd(6), lrole, true), seg(s.text || '', s.kind === 'event' ? 'muted' : 'value')]);
+      if (s.receipt && s.kind !== 'user' && s.kind !== 'agent') rows.push([seg('     ', 'muted'), seg(s.receipt, 'muted')]);
+    }
+  });
+  for (const n of d.notes || []) rows.push([seg(`note: ${n}`, 'warn')]);
+  rows.push([seg(`page ${page} of ${pages}`, 'value', true), seg(page < pages ? `${nw ? '' : ' · '}${nw ? ' ' : ''}/replay${d.ref ? ` ${short(d.ref, 12)}` : ''} ${page + 1} for the next` : '', 'muted')]);
+  rows.push([seg('read-only: rebuilt from the audit trail, nothing is re-run', 'muted')]);
+  return { box: { width: w, title: `Replay · ${d.title || 'last turn'}`, titleRole: 'violet', border: 'violet' }, rows: rows.map(r => fitRow(r, inner)) };
+}
+
+/** Fetchers for createObjectsApi. deps: { get, listOf, why, verifyReceipt, aeeGet } */
+export function replayFetchers({ get, listOf, why, verifyReceipt, aeeGet }) {
+  const turns = async (id) => listOf(await get('collector', `/api/v1/conversations/${encodeURIComponent(id)}/turns`, { limit: 200 }, 12000), 'turns');
+  const corrList = async (corr) => listOf(await get('collector', '/aee/query', { corr, limit: 100 }, 12000), 'envelopes');
+  return {
+    /** a: { ref, page, conversationId, calls } -> { data } | { error, tone } */
+    async replay(a) {
+      const page = a.page || 1;
+      if (!a.ref) {
+        const calls = await Promise.all((a.calls || []).slice(-12).map(async (c) => {
+          if (!c.envelopeId || (c.receipt?.verified && c.receipt.ward_seq != null)) return c;
+          const r = await verifyReceipt(c.envelopeId, 6);
+          const res = r.ok ? r.result : null;
+          return res?.status === 'WITNESSED' ? { ...c, receipt: { verified: true, ward_seq: res.entry?.seq } } : c;
+        }));
+        let messages = [], notes = [];
+        try {
+          const rows = await turns(a.conversationId);
+          let from = 0;
+          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].role === 'user') { from = i; break; }
+          messages = rows.slice(from).filter(r => r.role === 'user' || r.role === 'assistant');
+        } catch (e) { notes.push(`the saved turn messages could not be read (${why(e)}); showing tool calls only`); }
+        return { data: { steps: buildTurnSteps({ messages, calls }), page, title: 'last turn', notes } };
+      }
+      let rows = null;
+      try { rows = await turns(a.ref); } catch (e) { if (e?.status && e.status !== 404 && e.status !== 400) return { error: `replay: ${why(e)}`, tone: 'warn' }; }
+      if (rows && rows.length) {
+        const steps = rows.filter(r => r.role === 'user' || r.role === 'assistant').map(r => ({ kind: r.role === 'user' ? 'user' : 'agent', text: String(r.content ?? '') }));
+        return { data: { steps, page, ref: a.ref, title: `conversation ${short(a.ref, 12)}`, notes: ['tool calls are not linked to a conversation id on the server: /replay <envelope id> replays a tool run'] } };
+      }
+      let corr = a.ref, seen = null;
+      const env = await aeeGet(a.ref);
+      if (env.ok && env.env) { seen = env.env; corr = env.env.corr || a.ref; }
+      let list = [];
+      try { list = await corrList(corr); } catch (e) { return { error: `replay: ${why(e)}`, tone: 'warn' }; }
+      if (seen && !list.some(e => e.id === seen.id)) list = [...list, seen];
+      if (!list.length) return { error: `No run, conversation or envelope called "${a.ref}".`, tone: 'warn' };
+      return { data: { steps: buildEnvelopeSteps(list), page, ref: a.ref, title: `run ${short(corr, 14)}`, notes: [] } };
+    }
+  };
+}

package/lib/quoxon/objects/sitrep.js

@@ -0,0 +1,58 @@
+/**
+ * /sitrep: the situation NOW, from persisted data only (no model call): approvals waiting (auth inbox),
+ * what needs you (LUCID needs_you, by urgency), running work (LUCID in_motion), and what Quox cannot see
+ * (LUCID silent / failing / unconnected feeds, plus any source this card could not read). /away is the
+ * "since you were last here" digest; this is the present tense.
+ */
+import { seg, fit, plural, boxWidth, parseTs, ago } from './model.js';
+
+const URG = { now: 0, today: 1, 'this week': 2, whenever: 3, fyi: 4 };
+const hrs = (ms) => { const m = Math.round((ms || 0) / 60000); return m < 60 ? `${m}m` : m < 2880 ? `${Math.round(m / 60)}h` : `${Math.round(m / 1440)}d`; };
+
+/** sit/appr: { ok, v | error } parts. -> { approvals: [..]|null, needs, running, blind } */
+export function sitrepData(sit, appr, now = Date.now()) {
+  const blind = [];
+  let needs = [], running = [];
+  if (sit?.ok) {
+    const s = sit.v?.situation || sit.v || {};
+    needs = (s.needs_you || []).filter(n => n.kind !== 'approval')
+      .map(n => ({ title: n.L0 || n.ref, urgency: n.urgency, ts: n.L1?.when?.since ?? n.status_since ?? null, ref: n.ref }))
+      .sort((a, b) => (URG[a.urgency] ?? 5) - (URG[b.urgency] ?? 5) || (parseTs(b.ts) ?? 0) - (parseTs(a.ts) ?? 0));
+    running = (s.in_motion || []).map(m => ({ title: m.L0 || m.ref, ref: m.ref }));
+    const cs = s.cannot_see || {};
+    for (const x of cs.silent || []) blind.push({ source: `lucid:${x.feed}`, reason: `silent ${hrs(x.silent_ms)}` });
+    for (const x of cs.failing || []) blind.push({ source: `lucid:${x.feed}`, reason: `failing: ${x.error}` });
+    for (const n of cs.unwired || []) blind.push({ source: `lucid:${n}`, reason: 'not connected' });
+  } else blind.push({ source: 'lucid', reason: sit?.error || 'not read' });
+  let approvals = null;
+  if (appr?.ok) approvals = (appr.v || []).map(a => ({ title: a.title || a.summary || a.id, ts: a.created_at, ref: a.id }));
+  else blind.push({ source: 'approvals', reason: appr?.error || 'not read' });
+  return { approvals, needs, running, blind, now };
+}
+
+/** d: sitrepData(...) + now */
+export function sitrepCard(d, cols, { maxNeeds = 5, maxRunning = 3, maxApprovals = 3 } = {}) {
+  const now = d.now ?? Date.now();
+  const w = boxWidth(cols, 96), inner = w - 4;
+  const rows = [];
+  const ap = d.approvals || [], needs = d.needs || [], run = d.running || [];
+  const line = (g, role, title, meta) => {
+    const m = meta ? `  ${meta}` : '';
+    return [seg(g, role), seg(fit(title, Math.max(8, inner - 2 - m.length)), 'value'), seg(m, 'muted')];
+  };
+  for (const a of ap.slice(0, maxApprovals)) rows.push(line('⚠ ', 'warn', `Approval: ${a.title}`, a.ts ? `waiting ${ago(a.ts, now)}` : ''));
+  if (ap.length > maxApprovals) rows.push([seg(`+${ap.length - maxApprovals} more approvals · /approvals`, 'muted')]);
+  for (const n of needs.slice(0, maxNeeds)) rows.push(line(n.urgency === 'now' ? '⚠ ' : '◐ ', n.urgency === 'now' ? 'warn' : 'muted', n.title, n.urgency || ''));
+  if (needs.length > maxNeeds) rows.push([seg(`+${needs.length - maxNeeds} more · quox lucid`, 'muted')]);
+  if (!ap.length && !needs.length) rows.push([seg('Nothing needs you right now.', 'muted')]);
+  if (run.length) {
+    rows.push([seg(' ')]);
+    for (const r of run.slice(0, maxRunning)) rows.push(line('◐ ', 'indigo', r.title, ''));
+    if (run.length > maxRunning) rows.push([seg(`+${run.length - maxRunning} more running · /roster all`, 'muted')]);
+  }
+  if ((d.blind || []).length) rows.push([seg(fit(`Can't see: ${d.blind.map(b => (b.reason ? `${b.source} (${b.reason})` : b.source)).join(', ')}`, inner), 'faint')]);
+  const right = w < 60
+    ? [d.approvals ? `${ap.length} ap` : null, `${needs.length} need`, `${run.length} run`].filter(Boolean).join(' · ')
+    : [d.approvals ? plural(ap.length, 'approval') : null, `${needs.length} need you`, `${run.length} running`].filter(Boolean).join(' · ');
+  return { box: { width: w, title: 'Situation now', titleRole: 'value', right, rightRole: 'muted', border: ap.length || needs.some(n => n.urgency === 'now') ? 'warn' : 'muted' }, rows };
+}

package/lib/quoxon/objects/view.js

@@ -62,6 +62,17 @@ export function ObjectView({ item, cols, fx = null, t = fx && fx.e != null ? fx.
   return h(Box, { flexDirection: 'column', marginTop: 1, paddingLeft: 1 }, top, ...body, bottom);
 }
 
+/**
+ * TUI-UX #5: would this card (rows + border + margin) be taller than the terminal? Ink cannot erase rows that already scrolled
+ * off the top of a live region, so a decode-in on such a card leaves a half-decoded copy in scrollback. Callers skip the
+ * animation for it and commit it settled.
+ */
+export function cardTallerThanScreen(item, cols, termRows, now) {
+  if (!Number.isFinite(termRows) || termRows <= 0) return false;
+  const view = buildObject(item.obj || item, cols, now);
+  return (view.rows || []).length + (view.box ? 3 : 1) + 2 >= termRows; // top + bottom border, marginTop, plus the composer line
+}
+
 /** Plain text of a view at a width (tests, transcripts, --print): the box drawn with the same geometry. */
 export function objectText(item, cols, now) {
   const view = buildObject(item.obj || item, cols, now);

package/lib/quoxon/onboarding/copy.js

@@ -5,6 +5,7 @@
  *
  * Functions take the facts they print (a URL, a size, a provider name); nothing here computes anything.
  */
+import { askText } from '../ask.js';
 
 export const LABEL = 'Getting started';
 export const LABEL_SUB = 'setup guide · no AI yet, every line here is scripted';
@@ -12,7 +13,7 @@ export const LABEL_SUB = 'setup guide · no AI yet, every line here is scripted'
 // The Q says HELLO itself, decoded in beside the mark right after the intro (qmotion.js HelloIntro); the
 // guide then carries on with GREETING_REST. GREETING is the whole sentence, for anywhere that shows it at once.
 export const HELLO = "Hi, I'm Quox.";
-export const GREETING_REST = 'I run AI agents for you on your own machine, and I keep proof of everything they do.';
+export const GREETING_REST = 'I run AI agents for you on your own machine, and I keep receipts you can check for what they do.';
 export const GREETING = `${HELLO} ${GREETING_REST}`;
 export const QUESTION = 'What would you like help with?';
 export const EXAMPLES = ['watch my servers', 'automate something', 'code with agents', 'sort my email', 'just look around'];
@@ -32,7 +33,7 @@ export const DEFERRAL = 'I can answer that properly once your Quox is running.';
 
 // The install time is NOT promised as a number until it has been measured on a clean machine (C2 exit).
 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 = 'Set it up now? (Y/n)';
+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>';
 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.';
@@ -45,10 +46,22 @@ export const CONNECT_USAGE = 'Usage: /connect server <url>   for example /connec
 export const connectBadUrl = (u) => `That does not look like a server address: ${u}. Use the full URL, starting with https://`;
 export const connectHandoff = (url) => `Connecting to ${url}. Sign in with your QuoxCORE email and password.`;
 export const CONNECT_DONE = 'Signed in. Starting Quox.';
+export const connectChecking = (url) => `Checking ${url} is a QuoxCORE server...`;
+export const CONNECT_CANCELLED = 'Cancelled. Nothing was saved: the previous server address is back.';
 export const connectFailed = (url) => `Sign-in to ${url} did not complete. Check the address, then try /connect server again.`;
 export const CONNECT_INTENT_LINE = 'Great. Point me at it with /connect server <url> and sign in, and we go straight to your agents.';
 
 // ---- preflight ---------------------------------------------------------------------------------
+// FIRSTRUN: the guide offers to fix Docker itself (dockerOffer.js), so nobody has to leave it to do so.
+export const DOCKER_OFFER_QUESTION = {
+  install: 'Install Docker for you now?',
+  group: 'Add you to the docker group now?',
+  relaunch: 'Carry on now with the docker group, without logging out?'
+};
+export const DOCKER_OFFER_HINT = 'y yes · r check again · q stop';
+export const DOCKER_OFFER_RUNNING = 'Running (sudo may ask for your password):';
+export const DOCKER_OFFER_FAILED = 'That did not finish. Fix what it said, then run quox to pick up where you left off.';
+export const DOCKER_OFFER_RELAUNCH = 'Starting quox again with the docker group.';
 export const PREFLIGHT_TITLE = 'Checking this machine';
 export const PREFLIGHT_RETRY = 'r to check again · q to stop';
 export const PREFLIGHT_RETRY_DRY = 'r to check again · c to continue anyway (dry run) · q to stop';
@@ -66,6 +79,8 @@ export const CHECK = {
     missingLink: 'https://docs.docker.com/get-docker/',
     perm: 'Docker is installed, but this user cannot reach the daemon',
     permFix: 'Run: sudo usermod -aG docker $USER && newgrp docker   then press r.',
+    permStale: 'Docker is installed, and you are in the docker group, but this terminal started before that',
+    permStaleFix: 'Pressing r cannot fix this: a running terminal never gains a new group. Run: newgrp docker   (or open a new terminal), then run: quox',
     down: 'Docker is installed, but the daemon is not running',
     downFix: 'Start Docker (Docker Desktop, or: sudo systemctl start docker), then press r.',
     link: 'https://docs.docker.com/engine/install/'
@@ -128,6 +143,12 @@ export const CRED_OPTIONS = {
 export const credPrompt = (label) => `Paste your ${label}. It stays in memory only: never written to disk, history or the transcript.`;
 export const CRED_INPUT_HINT = 'Enter to use it · Esc to go back';
 export const credHeld = (label, fp) => `${label} held in memory (fingerprint ${fp}). It is stored in your Quox vault after install, never on disk here.`;
+export const credConsent = (label) => `${label} is a cloud AI: your messages and tool results are sent to it, so Quox needs your OK once. Say no and nothing goes to it until you give it later with /consent grant openai (or Settings > Privacy in the dashboard). A local model (Ollama) needs no consent.`;
+// QUOXON-Z2H lane R: the one consent question at the credential step. Default No: cloud processing stays opt-in.
+export const credConsentAsk = (who) => askText(`Allow Quox to send your conversations to ${who}?`, { keys: 'y/N', who: 'Quox', action: `send your messages and any tool results to ${who}, a third party, when it answers` });
+export const CRED_CONSENT_HINT = 'y yes · n or Enter no';
+export const credConsentYes = (who) => `Yes. Your OK for ${who} is recorded as soon as your owner account exists. Withdraw it any time in Settings > Privacy.`;
+export const credConsentNo = (who, provider) => `No. ${who} receives nothing until you give your OK: /consent grant ${provider}, or Settings > Privacy in the dashboard.`;
 export const CRED_EMPTY = 'Nothing was pasted. Paste the key, or Esc to choose again.';
 export const CRED_OLLAMA = 'Ollama it is. The Quox server runs in Docker and cannot reach "localhost", so after install connect it by this machine\'s LAN address: start Ollama with OLLAMA_HOST=0.0.0.0, then /connect ollama http://<lan-ip>:11434';
 export const OLLAMA_URL_PROMPT = 'The Ollama URL on your network, for example http://<lan-ip>:11434. Not a secret. On that machine, start Ollama with OLLAMA_HOST=0.0.0.0 and allow port 11434.';
@@ -148,6 +169,10 @@ export const STAGES = {
   start: 'Start the services',
   health: 'Wait until healthy'
 };
+/** Z2H-IMAGES: the build stage relabels itself once setup.sh says whether it is downloading or building. */
+export const BUILD_LABELS = { download: 'Download the images', build: 'Build the images' };
+export const INSTALL_RERUN_HINT = 'It is safe to run the installer again: finished steps are kept and the build is cached.';
+export const INSTALL_LOG_PATH = (p) => `Full install log: ${p}`;
 export const INSTALL_FAILED = (stage) => `The install stopped at: ${stage}. Press v for the log, r to try again.`;
 export const INSTALL_NOT_YET = 'Installing from here arrives in the next release. For now, run this in another terminal:';
 export const INSTALL_COMMAND = 'curl -fsSL https://get.quox.ai | sh';
@@ -156,7 +181,7 @@ export const INSTALL_KEY_GONE = 'Your key was not kept: it only ever lived in me
 export const installWhere = (dir) => `Installing into ${dir}`;
 export const installScriptLead = (url, bytes) => `Installer ${url} (${Math.max(1, Math.round(bytes / 1024))} KB), SHA256`;
 export const installScript = (url, sha, bytes) => `${installScriptLead(url, bytes)} ${sha}`;
-export const INSTALL_STOP_ASK = 'Stop the install? You can pick it up next time. (y/N)';
+export const INSTALL_STOP_ASK = askText('Stop the install?', { reason: 'You can pick it up next time.', keys: 'y/N' });
 export const INSTALL_STOP_KEEP = 'Carrying on.';
 export const INSTALL_STOPPED = 'Install stopped. Run quox to pick up where you left off.';
 export const INSTALL_EARLIER = 'done earlier';
@@ -184,6 +209,7 @@ export const FIN = {
     name: 'AI KEY', running: (label) => `testing your ${label}, then storing it in your vault`,
     skipped: 'no key to store', ollama: 'Ollama: add it to your vault with quox vault create --type ollama'
   },
+  consent: { name: 'CONSENT', running: (who) => `recording your OK for ${who}`, ok: (who) => `OK recorded for ${who}`, fail: (e, provider) => `not recorded (${e}), later: /consent grant ${provider}` },
   link: { name: 'DASHBOARD', running: 'making your one-time sign-in link', ok: 'one-time link ready (10 minutes, single use)', fail: (e) => `no link (${e}), sign in with your owner account instead` }
 };
 export const KEY_GONE_AFTER = 'The key is gone from this terminal\'s memory now.';
@@ -214,13 +240,14 @@ TIPS.offscript = TIPS.explore;
 export const FINALE_TIPS = TIPS.explore; // the dry run and any intent without its own set
 // K2: one gentle, honest next connection that fits what they said they wanted.
 export const K2 = {
-  servers: 'You said you want to watch your servers. None are connected yet, and adding one from the terminal is not built yet: add your first host on the dashboard Fleet page.',
+  servers: 'You said you want to watch your servers. None are connected yet. Add your first with /hosts add (it needs no AI), or on the dashboard Fleet page.',
   automate: 'You said you want to automate something. Already use n8n? Bring a workflow across with: quox workflow import-n8n --file <path>',
   code: 'You said you want to code with agents. Connect GitHub so they can see your repos: quox vault create --type github',
   email: 'You said you want help with email. Connect your mailbox: quox mail connect --provider gmail (or outlook, icloud)',
   explore: 'Want your agents to do more? /connect shows what is connected and what you can add.'
 };
 K2.offscript = K2.explore;
+export const K2_SERVERS_NO_INSTALLER = 'You said you want to watch your servers. None are connected yet, and this install cannot enrol hosts yet because its host installer is not available.';
 export const k2NoAi = (provider) => `Your agents have no AI yet, so they cannot answer for themselves. Connect one now? /connect ${provider}`;
 export const FINALE_EXIT = 'Enter to start talking to your Quox';
 export const FINALE_EXIT_DRY = 'Enter to finish';
@@ -233,3 +260,4 @@ export const HELP = [
 export const SLASH_UNKNOWN = 'Only /connect server, /help and /exit work until your Quox is running.';
 export const BYE = 'See you soon. Run quox to pick up where you left off.';
 export const NO_SERVER_PRINT = 'Run quox (without --print) to get started.';
+export const FINALE_HOSTS_NO_AI = 'No AI needed to add a host: /hosts add shows the one command to run on that machine.';

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;
+}