quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/approvalFacts.js

@@ -0,0 +1,94 @@
+// APPROVAL-WWWH (owner 2026-10-16 "why? what command for 17 hosts! insufficient info to authorise. who?? what? why???"):
+// the four facts an approver needs, read from the item and nothing else: WHAT (the exact command or tool input), WHERE
+// (host count and names), WHO (the delegation chain and the human it acts for) and WHY (reason, the user's own words,
+// when). Pure, so the card, the /approvals row and /approvals N detail cannot drift apart.
+
+export const CMD_CARD_MAX = 400;
+const str = (v) => (typeof v === 'string' ? v : v == null ? '' : (() => { try { return JSON.stringify(v); } catch { return String(v); } })());
+
+/** Text cut at `max` with a visible, honest tail. `n` is the /approvals number when known. */
+export function clipVisible(text, max, n = null) {
+  const s = String(text ?? '');
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)} (+${s.length - max} chars, /approvals ${n ?? 'N'} detail for full)`;
+}
+
+/** The exact command or tool input, verbatim: method.command, else the reach request, else args. */
+export function commandOf(it) {
+  const p = it?.payload || {}; const c = p.approval_context || {}; const m = c.method || {};
+  if (typeof m.command === 'string' && m.command) return { text: m.command, kind: 'command' };
+  const rq = (p.reach?.requests || []).find(r => r && r.kind === 'command' && typeof r.id === 'string' && r.id);
+  if (rq) return { text: rq.id, kind: 'command' };
+  const a = m.args ?? c.args ?? p.args ?? null;
+  if (a != null && a !== '') return { text: str(a), kind: 'input' };
+  return null;
+}
+
+/** Hosts (or other comma-separated targets) with the count. The full target string wins over the clipped what.target. */
+export function hostsOf(it) {
+  const p = it?.payload || {}; const c = p.approval_context || {};
+  const raw = [c.method?.target, c.target, p.targetId, p.what?.target].find(v => typeof v === 'string' && v.trim() && !v.trim().endsWith('…')) || p.what?.target || '';
+  const list = String(raw).split(',').map(x => x.trim()).filter(Boolean);
+  return { list, count: list.length };
+}
+
+/** "17 hosts: a, b, c (+14 more, /approvals N detail for all)". `all` lists every name. */
+export function whereText(it, { all = false, first = 3, n = null } = {}) {
+  const { list, count } = hostsOf(it);
+  if (!count) return null;
+  if (count === 1) return list[0];
+  const tool = String(it?.payload?.toolName || it?.payload?.approval_context?.method?.tool || '');
+  const w = /ssh|exec|host|shell/i.test(tool) ? 'hosts' : 'targets';
+  if (all) return `${count} ${w}: ${list.join(', ')}`;
+  const shown = list.slice(0, first).join(', ');
+  return count > first ? `${count} ${w}: ${shown} (+${count - first} more, /approvals ${n ?? 'N'} detail for all)` : `${count} ${w}: ${shown}`;
+}
+
+/** Read-only or write, only as the server classified it. Null when it did not say. */
+export function accessOf(it) {
+  const c = it?.payload?.approval_context || {};
+  const k = c.method?.access || c.access;
+  if (k === 'read_only' || k === 'read') return 'read-only';
+  if (k === 'write') return 'write';
+  const lab = String(c.why_approval?.label || '');
+  if (/not on the read-only allowlist/i.test(lab)) return 'NOT read-only: not on the read-only allowlist, so it may change things';
+  return null;
+}
+
+/** WHO: "QUOX → SENTINEL (session claude in app) for Adam DEV SERVER". */
+export function whoText(it) {
+  const c = it?.payload?.approval_context || {}; const rb = c.requested_by || {}; const ob = c.on_behalf_of || {};
+  const chain = Array.isArray(rb.delegation_chain) && rb.delegation_chain.length ? rb.delegation_chain.join(' → ') : (rb.agent_label || c.source_label || null);
+  const caller = rb.caller?.name || rb.session_label || null;
+  const via = [caller && `via ${rb.caller?.kind === 'session' || rb.session_label ? 'session ' : ''}${caller}`, rb.surface_label && `${rb.surface_label}`, rb.profile && `profile ${rb.profile}`].filter(Boolean).join(', ');
+  const forWhom = ob.user_name || ob.user_id || null;
+  const head = [chain, via && `(${via})`].filter(Boolean).join(' ');
+  if (!head && !forWhom) return null;
+  return `${head || 'unknown requester'}${forWhom ? ` acting for ${forWhom}` : ''}`;
+}
+
+/** WHY: the reason text (marked inferred when the caller did not state it). */
+export function whyText(it) {
+  const c = it?.payload?.approval_context || {}; const r = c.reason;
+  if (r && typeof r === 'object') return r.text ? `${r.text}${r.source === 'inferred' ? ' (inferred, not stated by the caller)' : ''}` : null;
+  return r || it?.payload?.reason || null;
+}
+
+/** The user's own words that started this, when the server kept them. */
+export const excerptOf = (it) => it?.payload?.approval_context?.on_behalf_of?.request_excerpt || null;
+
+/** One bag of the facts, for the card. */
+export function approvalFacts(it, { n = null } = {}) {
+  const cmd = commandOf(it);
+  const when = it?.payload?.approval_context?.created_at || it?.created_at || it?.createdAt || null;
+  return {
+    command: cmd ? { ...cmd, shown: clipVisible(cmd.text, CMD_CARD_MAX, n) } : null,
+    where: whereText(it, { n }),
+    hostList: hostsOf(it).list,
+    who: whoText(it),
+    why: whyText(it),
+    asked: excerptOf(it),
+    when: when ? String(when).replace('T', ' ').slice(0, 16) + ' UTC' : null,
+    access: accessOf(it)
+  };
+}

package/lib/quoxon/approvalsView.js

@@ -0,0 +1,325 @@
+// QUOXON-APPROVALS: pure helpers for /approvals rows, filters, detail and /approve|/deny argument parsing.
+import { describeInboxItem, approvalSourceLabel, isPrivileged } from './events.js';
+import { commandOf, hostsOf, whereText, whoText, whyText, excerptOf, accessOf, clipVisible } from './approvalFacts.js';
+
+// quox ask: a decision request is an inbox item of kind question with payload.type 'decision'.
+export const isDecision = (it) => it?.payload?.type === 'decision' && Array.isArray(it.payload.options);
+/** Who stands behind a recommendation: an explicit recommended_by, else the asking session or agent, else Quox. Never invented when there is no recommendation. */
+export const recommenderOf = (p) => String(p.recommended_by || p.session || p.agent || 'Quox');
+/** Display order only: the recommended option first, the rest in their original order. Keys never move with it. No recommendation = original order. */
+export const displayOptions = (p) => { const rec = p.options.find(o => o.key === p.recommend); return rec ? [rec, ...p.options.filter(o => o !== rec)] : p.options.slice(); };
+const left = (it, now) => { const t = Date.parse(it?.due_at ?? it?.payload?.expires_at); if (!Number.isFinite(t)) return null; const ms = t - now; if (ms <= 0) return { text: 'expired', soon: true }; const m = Math.round(ms / 60000); return { text: m >= 120 ? `${Math.round(m / 60)}h left` : m >= 1 ? `${m}m left` : '<1m left', soon: ms <= 15 * 60000 }; };
+
+/** One line for a decision: [3] SEER asks: Publish the guide now? (a) Ship now (b) Wait (c) Drop · recommends a · 2h left. The tail never gets clipped away; the middle gives way. */
+export function decisionRow(it, n, { cols = 100, now = Date.now() } = {}) {
+  const p = it.payload;
+  const head = `  [${n}] ${p.session || approvalSourceLabel(it)} asks: ${cleanTitle(it)}`;
+  const opts = p.options.map((o) => `(${o.key}) ${o.label}`).join(' ');
+  const l = left(it, now);
+  const tail = [p.recommend ? `recommends ${p.recommend}` : null, l ? `${l.soon ? '⚠ ' : ''}${l.text}` : null, p.high_risk ? 'high risk' : null].filter(Boolean).join(' · ');
+  const body = `${head} ${opts}`;
+  const room = cols - (tail ? tail.length + 3 : 0);
+  const mid = body.length > room ? body.slice(0, Math.max(10, room - 1)) + '…' : body;
+  return tail ? `${mid} · ${tail}` : mid;
+}
+
+/** Full detail for a decision: who, what, why, every option. */
+export function decisionDetail(it, n, { now = Date.now() } = {}) {
+  const p = it.payload; const l = left(it, now);
+  const rows = [
+    ['item', `[${n}] ${it.title || it.id}`],
+    ['id', it.id],
+    ['from', [p.session, p.profile && `profile ${p.profile}`, p.agent && `agent ${p.agent}`].filter(Boolean).join(', ')],
+    ['why', p.why],
+    ...displayOptions(p).map((o, i) => [i === 0 ? 'options' : '', `${o.key === p.recommend ? '★ ' : ''}(${o.key}) ${o.label}${o.key === p.recommend ? `   ★ recommended by ${recommenderOf(p)}` : ''}${o.key === p.default ? '   default' : ''}`]),
+    ['expires', l ? `${l.soon ? '⚠ ' : ''}${l.text} (${it.due_at || p.expires_at})` : null],
+    ['risk', p.high_risk ? 'high risk: answering needs your step-up PIN' : null],
+  ].filter((r) => r[1]);
+  return rows.map(([k, v]) => `  ${String(k).padEnd(8)}${v}`);
+}
+
+/**
+ * /answer arguments after the command word: "3 b after Friday", or "b after Friday" when an item is focused.
+ * Returns { n (null = the only open decision), key, note, bad }. A quoted note loses its quotes.
+ */
+/**
+ * QUOXON-1191b: pair syntax "1 y 2 n", "1 y, 2 n", "1y 2n". Returns [{ k, key }] (key lowercase y|n), null when the
+ * words are not entirely pairs, or { bad: true } for a 0 or a repeated number.
+ */
+export function parsePairs(words) {
+  const text = words.join(' ').trim();
+  if (!/^(\d+\s*[yn](\s*,\s*|\s+|$))+$/i.test(text)) return null;
+  const pairs = [...text.matchAll(/(\d+)\s*([yn])/gi)].map(m => ({ k: Number(m[1]), key: m[2].toLowerCase() }));
+  if (!pairs.length) return null;
+  if (pairs.some(x => x.k < 1) || new Set(pairs.map(x => x.k)).size !== pairs.length) return { bad: true };
+  return pairs;
+}
+
+export function parseAnswer(words, { focusN = null, raw = null } = {}) {
+  const out = { n: null, key: null, note: '', bad: false };
+  let w = words.slice();
+  const pr = parsePairs(w);
+  if (pr && (pr.bad || pr.length >= 2 || (w.length === 1 && /^\d+[yn]$/i.test(w[0])))) {
+    if (pr.bad) { out.bad = true; return out; }
+    out.ns = pr.map(x => x.k); out.n = out.ns[0]; out.keys = Object.fromEntries(pr.map(x => [x.k, x.key])); out.key = pr[0].key;
+    return out;
+  }
+  if (w[0] && /^\d+$/.test(w[0])) { out.n = Number(w[0]); w = w.slice(1); }
+  else if (w[0] && /^\d+(-\d+)?(,\d+(-\d+)?)+$|^\d+-\d+$/.test(w[0])) { // QUOXON-1191: /answer 1-5 y, /answer 1,3,4 y
+    const ns = [];
+    for (const part of w[0].split(',')) { const m = /^(\d+)(?:-(\d+))?$/.exec(part); const a = Number(m[1]); const b = Number(m[2] ?? m[1]); if (a < 1 || b < a || b - a > 199) { out.bad = true; return out; } for (let k = a; k <= b; k++) if (!ns.includes(k)) ns.push(k); }
+    out.ns = ns; out.n = ns[0]; w = w.slice(1);
+  }
+  else if (w.length >= 2 && /^n$/i.test(w[0])) w = w.slice(1); // the hint's literal "N" is the same as no number
+  else out.n = focusN;
+  if (!w[0]) { out.bad = true; return out; }
+  out.key = w[0].toLowerCase();
+  const noteWords = w.slice(1);
+  out.note = raw != null && noteWords.length
+    ? cleanNote(rawTail(raw, words.length - noteWords.length))
+    : cleanNote(noteWords.join(' '));
+  return out;
+}
+
+const ctxOf = (it) => it?.payload?.approval_context || {};
+const obOf = (it) => ctxOf(it).on_behalf_of || {};
+
+/** Every name an item answers to as its requester (agent, session, source label). */
+export function requesterNames(it) {
+  const ob = obOf(it); const c = ctxOf(it);
+  return [ob.agent, ob.agent_id, ob.session_name, ob.session, c.requested_by?.agent_label, c.source_label, it?.payload?.source, it?.source]
+    .filter(Boolean).map(String);
+}
+export const isAgentItem = (it) => { const ob = obOf(it); return Boolean(ob.agent || ob.agent_id || ob.session_name || ob.session || ctxOf(it).requested_by?.agent_label); };
+export const matchesAgent = (it, name) => { const n = String(name || '').toLowerCase(); return Boolean(n) && requesterNames(it).some(x => x.toLowerCase() === n || x.toLowerCase().includes(n)); };
+
+export function ageText(iso, now = Date.now()) {
+  const t = typeof iso === 'number' ? iso : Date.parse(iso);
+  if (!Number.isFinite(t)) return '?';
+  const m = Math.max(0, Math.round((now - t) / 60000));
+  return m < 1 ? 'now' : m < 60 ? `${m}m` : m < 2880 ? `${Math.round(m / 60)}h` : `${Math.round(m / 1440)}d`;
+}
+
+/** 'mine' | 'agents' | 'old' | <agent name> | null -> predicate. */
+export function filterPredicate(f, { userId = null, conversationId = null, now = Date.now(), oldMs = 24 * 3600 * 1000 } = {}) {
+  if (!f) return () => true;
+  const k = String(f).toLowerCase();
+  if (k === 'mine') return (it) => { const ob = obOf(it); return Boolean((userId && ob.user_id && String(ob.user_id) === String(userId)) || (conversationId && ob.conversation_id === conversationId)); };
+  if (k === 'agents') return isAgentItem;
+  if (k === 'old') return (it) => { const t = Date.parse(it?.created_at ?? it?.createdAt); return Number.isFinite(t) && now - t > oldMs; };
+  return (it) => matchesAgent(it, f);
+}
+
+/** One line: [N] age  who  what  (risk). Clipped to `cols`. */
+export function approvalRow(it, n, { cols = 100, now = Date.now() } = {}) {
+  if (isDecision(it)) return decisionRow(it, n, { cols, now });
+  const d = describeInboxItem(it);
+  const who = requesterNames(it)[0] || approvalSourceLabel(it);
+  let what = [d.tool, d.target && d.target !== d.tool ? d.target : null].filter(Boolean).join(' ') || d.title || it.id;
+  const risk = ctxOf(it).risk ? ` (${ctxOf(it).risk})` : '';
+  const priv = isPrivileged({ tool: d.tool, risk: ctxOf(it).risk, flag: it?.payload?.privileged === true || ctxOf(it).privileged === true, title: it.title }) ? ' [privileged]' : '';
+  const cmd = commandOf(it);
+  if (cmd && cmd.kind === 'command') { // APPROVAL-WWWH: the exact command and the host count, never just the tool name; the command gives way last, with a visible tail
+    const { count, list } = hostsOf(it);
+    const on = count > 1 ? ` on ${count} ${/ssh|exec|host|shell/i.test(String(d.tool || it?.payload?.toolName || '')) ? 'hosts' : 'targets'} (${list.slice(0, 2).join(', ')}, +${count - 2} more)` : (count === 1 ? ` on ${list[0]}` : '');
+    const one = cmd.text.replace(/\s*\n\s*/g, ' ; ');
+    const head = `  [${n}] ${ageText(d.at, now).padStart(3)}  ${String(who).slice(0, 18).padEnd(18)}  ${d.tool || 'run'} `;
+    const room = Math.max(24, cols - head.length - on.length - risk.length - priv.length - 2);
+    return `${head}\`${clipVisible(one, room, n)}\`${on}${risk}${priv}`;
+  }
+  const line = `  [${n}] ${ageText(d.at, now).padStart(3)}  ${String(who).slice(0, 18).padEnd(18)}  ${what}${risk}${priv}`;
+  return line.length > cols ? line.slice(0, Math.max(10, cols - 1)) + '…' : line;
+}
+
+/** Full detail for /approvals N: one line per fact. */
+export function approvalDetail(it, n, { now = Date.now() } = {}) {
+  if (isDecision(it)) return decisionDetail(it, n, { now });
+  const d = describeInboxItem(it); const c = ctxOf(it); const m = c.method || {}; const p = it?.payload || {};
+  const args = m.argv ?? m.args ?? c.argv ?? c.args ?? p.args ?? null;
+  const cmdFull = commandOf(it);
+  const why = whyText(it) || c.why || p.reason || it?.summary || it?.description || null;
+  const rc = it?.receipt || p.receipt || c.receipt || null;
+  const receipt = rc ? (typeof rc === 'string' ? rc : (rc.ward_seq != null ? `ward seq ${rc.ward_seq}${rc.verified ? ' verified' : ''}` : JSON.stringify(rc).slice(0, 100))) : (it?.aee_correlation_id || p.approval_id || null);
+  const rows = [
+    ['item', `[${n}] ${it.title || it.id}`],
+    ['id', it.id],
+    ['tool', d.tool], ['target', hostsOf(it).count > 1 ? null : d.target],
+    ['command', cmdFull && cmdFull.kind === 'command' ? cmdFull.text : null],
+    ['args', cmdFull && cmdFull.kind === 'command' ? null : (args == null ? null : (typeof args === 'string' ? args : JSON.stringify(args)).slice(0, 300))],
+    ['where', hostsOf(it).count ? whereText(it, { all: true }) : null],
+    ['who', whoText(it)],
+    ['why', why ? String(why) : null],
+    ['request', excerptOf(it) ? `"${excerptOf(it)}"` : null],
+    ['class', accessOf(it)],
+    ['from', requesterNames(it).join(', ') || approvalSourceLabel(it)],
+    ['asked', d.at ? `${ageText(d.at, now)} ago (${String(d.at)})` : null],
+    ['risk', c.risk || null],
+    ['receipt', receipt],
+    ['url', it.dashboard_url || null]
+  ].filter(r => r[1]);
+  return rows.flatMap(([k, v]) => String(v).split('\n').map((line, i) => `  ${(i ? '' : k).padEnd(8)}${line}`));
+}
+
+/**
+ * /approve|/deny arguments after the command word. Forms: N, 1,2, 1-3, all, agent <name>; deny may end with a free-text
+ * reason. 'confirm' (approve only) is stripped. Returns { nums, all, agent, reason, confirm, bad }.
+ */
+export const NOTE_MAX = 4000;
+/** The raw text after the first `skip` whitespace-separated tokens, whitespace and line breaks kept. */
+export function rawTail(raw, skip) {
+  const m = new RegExp(`^\\s*(?:\\S+\\s+){${Math.max(0, skip - 1)}}\\S+\\s*`).exec(String(raw ?? ''));
+  return skip > 0 ? (m ? String(raw).slice(m[0].length) : '') : String(raw ?? '');
+}
+/** A typed note: a balanced pair of quotes is removed; an opening quote with no close just goes, and the rest stays. Nothing else is dropped. */
+export function cleanNote(t) {
+  let s = String(t ?? '').trim();
+  const q = s[0];
+  if (q === '"' || q === "'" || q === '\u201c') {
+    const close = q === '\u201c' ? '\u201d' : q;
+    s = s.slice(1);
+    if (s.endsWith(close)) s = s.slice(0, -1);
+  }
+  return s.trim().slice(0, NOTE_MAX);
+}
+
+export function parseDecision(words, verb, { raw = null } = {}) {
+  const out = { nums: [], all: false, agent: null, reason: '', confirm: false, bad: false };
+  let w = words.slice();
+  if (verb === 'approve') { out.confirm = w.includes('confirm'); w = w.filter(x => x !== 'confirm'); }
+  let i = 0;
+  if (w[0] && w[0].toLowerCase() === 'agent') {
+    if (!w[1]) { out.bad = true; return out; }
+    out.agent = w[1]; i = 2;
+  } else {
+    for (; i < w.length; i++) {
+      const tok = w[i];
+      if (tok.toLowerCase() === 'all') { out.all = true; continue; }
+      if (!/^[\d,\-]+$/.test(tok)) break;
+      let ok = false;
+      for (const part of tok.split(',').filter(Boolean)) {
+        const m = /^(\d+)(?:-(\d+))?$/.exec(part);
+        if (m && Number(m[1]) >= 1 && Number(m[2] ?? m[1]) >= Number(m[1]) && Number(m[2] ?? m[1]) - Number(m[1]) < 200) { ok = true; for (let k = Number(m[1]); k <= Number(m[2] ?? m[1]); k++) out.nums.push(k); }
+        else { out.bad = true; return out; }
+      }
+      if (!ok) { out.bad = true; return out; }
+      if (out.all) break;
+    }
+  }
+  const restWords = w.slice(i);
+  const rest = restWords.join(' ').trim();
+  if (rest) {
+    if (verb === 'reject') out.reason = raw != null ? cleanNote(rawTail(raw, words.length - restWords.length)) : rest.slice(0, NOTE_MAX);
+    else out.bad = true;
+  }
+  if (!out.all && !out.agent && !out.nums.length) out.bad = true;
+  return out;
+}
+
+/**
+ * WALKTHROUGH (owner 2026-10-17: "guide me simply one at a time, explain, advise"). One decision as one plain card.
+ * Identity is the decision id, never a position. -> { lines, choices:[{key,label,word}], recommendKey, source }.
+ */
+const isLabelled = (o) => o.label && String(o.label).toLowerCase() !== String(o.key).toLowerCase();
+const optWord = (o) => (isLabelled(o) ? o.label : `option ${o.key} (no label given)`);
+/** "Type 1: <label> · Type 2: <label>" plus s to skip, for a non-yes/no decision. */
+export function walkChoicesLine(it) {
+  return it.payload.options.map(o => `Type ${o.key}: ${optWord(o)}`).join(' · ') + ' · Type s to skip';
+}
+export function walkNotYesNo(it) {
+  return `This one isn't yes/no. ${walkChoicesLine(it).replace(/ · Type s to skip$/, '')}, or s to skip.`;
+}
+export function walkNoCatch(it) {
+  const ks = it.payload.options.map(o => o.key);
+  const keys = ks.length > 1 ? `${ks.slice(0, -1).join(', ')} or ${ks[ks.length - 1]}` : ks.join('');
+  return `I did not catch a choice. Type ${keys}. ${walkChoicesLine(it)} (? asks about it, Esc stops).`;
+}
+/** A title without the asker's own name in front of it ("SEER: Publish?" asked by SEER -> "Publish?"), whitespace and line breaks folded. */
+export function cleanTitle(it) {
+  const p = it.payload || {}; const t = String(it.title || it.id || '').replace(/\s+/g, ' ').trim();
+  for (const name of [p.session, p.agent].filter(Boolean).map(String)) {
+    if (t.toLowerCase().startsWith(name.toLowerCase() + ':')) { const rest = t.slice(name.length + 1).trim(); if (rest) return rest; }
+  }
+  return t;
+}
+/** Word-wrap `text` into lines no wider than `cols`, the label on the first line and a hanging indent of the same width under it. */
+export function hang(label, text, cols) {
+  const lead = '  ' + label.padEnd(8); const pad = ' '.repeat(lead.length);
+  if (!cols) return [lead + text];
+  const room = Math.max(20, cols - lead.length - 1); const out = []; let cur = '';
+  for (const w of String(text).split(' ')) {
+    if (cur && cur.length + 1 + w.length > room) { out.push(cur); cur = w; } else cur = cur ? cur + ' ' + w : w;
+  }
+  if (cur || !out.length) out.push(cur);
+  return out.map((l, k) => (k ? pad : lead) + l);
+}
+/** Owner 2026-10-17: a test or guard loosening needs a plain justification. True when the title, kind or tags say the ask would make a check easier to pass. */
+export const LOOSEN_RE = /loosen|weaken|relax|widen|(?:delete|remove|skip|disable|replace|rewrite|change|edit|update)\w*\s+(?:\w+\s+){0,3}?(?:tests?|guards?|checks?|assertions?|proof cases?)\b|test.?pin|goal ?post/i;
+export const isLoosening = (it) => { const p = it?.payload || {}; return p.loosening === true || LOOSEN_RE.test([it?.title, p.kind, p.category, ...(Array.isArray(p.tags) ? p.tags : [])].filter(Boolean).join(' ')); };
+export const NO_REASON = 'No reason given: ask the session, or say no.';
+export const NO_JUSTIFICATION = 'No plain justification given: ask the session, or say no.';
+const justificationOf = (p) => String(p.justification || p.plain_justification || '').replace(/\s+/g, ' ').trim();
+export function walkCard(it, i, total, { cols = 0 } = {}) {
+  const p = it.payload; const who = p.session || p.agent || 'A session';
+  const loose = isLoosening(it); const just = justificationOf(p); // JUSTIFY shows whenever the asker gave one, loosening title or not
+  const bareLoose = loose && !just; // no clear justification: "no" is the safe default and nothing is starred
+  const yn = p.options.some(o => o.key === 'y') && p.options.some(o => o.key === 'n');
+  const rec = bareLoose ? null : (p.options.find(o => o.key === p.recommend) || null);
+  const dflt = bareLoose ? (p.options.find(o => o.key === 'n') || null) : (p.options.find(o => o.key === p.default) || null);
+  const why = String(p.why || '').replace(/\s+/g, ' ').trim();
+  const what = yn
+    ? `Yes lets ${who} go ahead with this; no stops it.${p.high_risk ? ' High risk: a yes needs your PIN.' : ''}`
+    : `${who} needs you to choose how to settle this.${p.high_risk ? ' High risk: a yes needs your PIN.' : ''}`;
+  const advice = bareLoose
+    ? `${yn ? 'I would say no' : 'Do not approve this yet'}: this makes a check easier to pass and nothing explains why that is safe.${dflt ? ` Safe default: ${optWord(dflt)} (${dflt.key}).` : ''}`
+    : rec
+    ? `I would ${yn ? (rec.key === 'y' ? 'say yes' : 'say no') : `go with ${optWord(rec)} (${rec.key})`}. The asker recommended it.`
+    : `${who} gave no recommendation, and I will not guess one.${dflt ? ` If nobody answers it would take ${optWord(dflt)} (${dflt.key}).` : ''}`;
+  const keyClash = (k) => p.options.some(o => o.key === k);
+  const choices = [
+    ...p.options.map(o => ({ key: o.key, label: optWord(o), word: yn ? (o.key === 'y' ? 'Yes' : o.key === 'n' ? 'No' : optWord(o)) : optWord(o) })),
+    { key: keyClash('s') ? 'skip' : 's', label: 'Skip for now', defer: true },
+    { key: keyClash('?') ? 'ask' : '?', label: 'Ask about it', ask: true },
+  ];
+  const lines = [
+    `Decision ${i} of ${total} · ${who} asks`,
+    ...hang('', cleanTitle(it), cols).map(l => l.slice(8)),
+    ...hang('WHAT', what, cols),
+    ...(why ? hang('WHY', why, cols) : []),
+    ...(loose || just ? hang('JUSTIFY', just || NO_JUSTIFICATION, cols) : []),
+    ...(!why && !just && !loose ? hang('WHY', NO_REASON, cols) : []),
+    ...hang('ADVICE', advice, cols),
+  ];
+  // RECO-HIGHLIGHT: a real recommendation is its own first line (the TUI paints it bold in the accent colour), marked in text so a no-colour terminal still sees it.
+  let recoLine = null;
+  if (rec) { recoLine = lines.length; lines.push(`  ★ [${rec.key}] ${optWord(rec)}  ★ recommended by ${recommenderOf(p)}`); }
+  lines.push('  ' + choices.filter(c => !(rec && c.key === rec.key)).map(c => `[${c.key}] ${c.label}`).join('  ')); // the recommended key is on the star line above: each key is offered once
+  return { lines, choices, recommendKey: rec ? rec.key : null, recoLine, displayKeys: displayOptions(p).map(o => o.key), source: rec ? 'asker' : null };
+}
+
+/** The reply to a walkthrough card -> { key, note } | { defer:true } | { ask:true } | null. "y because X": text after the choice is the note, kept in full. */
+export function walkReply(it, text) {
+  const p = it.payload; const raw = String(text ?? '').trim();
+  if (!raw) return null;
+  const yn = p.options.some(o => o.key === 'y') && p.options.some(o => o.key === 'n');
+  const notYesNo = !yn;
+  const first = raw.split(/\s+/)[0]; const f = first.toLowerCase().replace(/[.!,]+$/, '');
+  const note = () => cleanNote(rawTail(raw, 1));
+  const hasKey = (k) => p.options.some(o => o.key.toLowerCase() === k);
+  if (hasKey(f)) return { key: p.options.find(o => o.key.toLowerCase() === f).key, note: note() };
+  if (/^(skip|s|later|next)$/.test(f)) return { defer: true };
+  if (f === '?' || /^(ask|why|explain|help)$/.test(f)) return { ask: true };
+  if (/^(yes|yep|yeah|ok|okay)$/.test(f)) return yn ? { key: 'y', note: note() } : (notYesNo ? { notYesNo: true } : null);
+  if (/^(no|nope)$/.test(f)) return yn ? { key: 'n', note: note() } : { notYesNo: true };
+  const t = raw.toLowerCase().replace(/[.!]+$/, '');
+  const hit = p.options.find(o => isLabelled(o) && t.startsWith(String(o.label).toLowerCase()));
+  return hit ? { key: hit.key, note: cleanNote(raw.slice(String(hit.label).length)) } : null;
+}
+
+/** The end summary of a walkthrough. state = { answered:[{title,word}], skipped:[title], left:[title] } */
+export function walkSummary(st) {
+  const out = [`Walkthrough done: ${st.answered.length} answered, ${st.skipped.length} skipped, ${st.left.length} left.`];
+  for (const a of st.answered) out.push(`  ✔ ${a.title}: ${a.word}`);
+  for (const t of st.skipped) out.push(`  ↷ skipped: ${t}`);
+  for (const t of st.left) out.push(`  · still waiting: ${t}`);
+  return out;
+}

package/lib/quoxon/asideView.js

@@ -0,0 +1,40 @@
+/**
+ * /aside in the TUI (pure parts). The answer is a history note with tone 'aside'; its text is
+ *   "aside: <question>\n<answer...>\n· <footer>"
+ * so the transcript and /share read naturally, and NoteView draws it as a separate block: a violet bar down
+ * the left, the question as the header, a read-only footer. Nothing here touches the conversation.
+ */
+import { asideExcerpt } from '../core/aside.js';
+
+export const ASIDE_FOOTER = 'read only: no tools, not added to this conversation';
+
+/** History + live items -> the last `max` user/assistant exchanges, assistant chunks merged; /commands and !lines skipped. */
+export function turnsFromItems(items, max = 10) {
+  const out = [];
+  for (const it of Array.isArray(items) ? items : []) {
+    if (!it || typeof it.text !== 'string') continue;
+    if (it.kind === 'user' && !it.queued) { if (!/^[/!]/.test(it.text.trim())) out.push({ role: 'user', text: it.text }); } // a /command or !shell line is not conversation
+    else if (it.kind === 'text') {
+      const last = out[out.length - 1];
+      if (last?.role === 'assistant') last.text += it.text; else out.push({ role: 'assistant', text: it.text });
+    }
+  }
+  return out.slice(-max);
+}
+
+/** The note text for one aside answer. */
+export function asideNoteText(question, answer, meta = {}) {
+  const who = meta.model ? ` · ${meta.provider ? `${meta.provider}/` : ''}${meta.model}` : '';
+  return `aside: ${String(question).trim()}\n${String(answer || '(no answer)').trim()}\n· ${ASIDE_FOOTER}${who}`;
+}
+
+/** -> { head, body: [lines], foot } from a note text (tolerant of a hand-made one). */
+export function parseAsideNote(text) {
+  const lines = String(text ?? '').split('\n');
+  const head = lines[0] || 'aside';
+  const footAt = lines.length > 1 && lines[lines.length - 1].startsWith('· ') ? lines.length - 1 : -1;
+  const body = lines.slice(1, footAt === -1 ? undefined : footAt);
+  return { head, body, foot: footAt === -1 ? null : lines[footAt] };
+}
+
+export { asideExcerpt };

package/lib/quoxon/ask.js

@@ -0,0 +1,121 @@
+/**
+ * QUOXON-ASK (owner 2026-10-15): one shape for everything that needs the human's answer, so it is learnt once.
+ *
+ *   ▶ <reason> <question> <keys>
+ *
+ * A fixed glyph first, the reason (why it is asking) next, the question, and the answer keys LAST. Rendered in the
+ * 'ask' tone (bold, the ask colour on the glyph and keys; never dim). Approval cards end in the same line.
+ * Every y/N the TUI says goes through askText; a test fails on a raw "y/N" anywhere else.
+ */
+export const ASK_GLYPH = '▶';
+export const ASK_KEYS = 'y/N/c'; // y: do it · n or Enter: don't · c or any other text: chat about it first (owner 2026-10-15)
+
+// The structured ask behind each line askText made, so the renderer can draw the card (who, action, why, keys)
+// from the text a module said. Bounded; an unknown line is parsed back instead.
+const MADE = new Map();
+const MADE_MAX = 200;
+
+/**
+ * The ask line's text (the transcript form; the TUI draws it as a card). reason is said first (a trailing "." is
+ * added when it has no end stop). who: who is asking (QUOX, an agent, a slot sender; default this terminal).
+ * action: exactly what a yes does, shown in full on the card.
+ */
+export function askText(question, { keys = ASK_KEYS, reason = '', who = '', action = '', title = '', plain = false } = {}) {
+  const r = String(reason || '').trim();
+  const q = String(question || '').trim();
+  const lead = r ? `${/[.!?:)]$/.test(r) ? r : `${r}.`} ` : '';
+  const text = `${ASK_GLYPH} ${lead}${q}${keys ? ` ${keys}` : ''}`;
+  MADE.set(text, { question: q, reason: r, keys: keys || '', who: String(who || '').trim(), action: String(action || '').trim(), title: String(title || '').trim(), plain: Boolean(plain) });
+  if (MADE.size > MADE_MAX) MADE.delete(MADE.keys().next().value);
+  return text;
+}
+
+/** An ask line -> { question, reason, keys, who, action } (what askText was given; parsed back when unknown). */
+export function parseAsk(text) {
+  const t = String(text ?? '');
+  if (MADE.has(t)) return { ...MADE.get(t) };
+  const question = askQuestion(t);
+  const body = t.replace(new RegExp(`^\\s*${ASK_GLYPH}\\s*`), '');
+  const qi = body.lastIndexOf(question);
+  const reason = qi > 0 ? body.slice(0, qi).trim() : '';
+  const keys = qi >= 0 ? body.slice(qi + question.length).trim() : '';
+  return { question, reason, keys, who: '', action: '' };
+}
+
+/** The card footer's keys, spelled out the way approvals show theirs. */
+export function keysLabel(keys) {
+  const k = String(keys || '').trim();
+  if (k === 'y/N/c') return 'y yes · n no · c chat';
+  if (k === 'y/N' || k === 'y/n') return 'y yes · n no';
+  if (/^\(?Y\/n\)?$/.test(k)) return 'y yes · n no (Enter is yes)';
+  return k;
+}
+
+/** The question part of an ask line ("▶ reason. Question? keys" -> "Question?"), for "Tell me more about: ...". */
+export function askQuestion(line) {
+  const s = String(line || '').replace(new RegExp(`^\\s*${ASK_GLYPH}\\s*`), '');
+  const end = s.lastIndexOf('?');
+  if (end < 0) return s.trim();
+  const head = s.slice(0, end + 1);
+  let start = 0;
+  for (const m of head.matchAll(/[.;!)] (?=[A-Z])/g)) start = m.index + 2; // the last sentence before the "?"
+  return head.slice(start).trim();
+}
+
+/** y/N/c: what an answer line means. 'yes' | 'no' (n, no, empty) | 'command' (a slash line) | 'chat' (c, or any other text). */
+export function askAnswer(text) {
+  const t = String(text ?? '').trim();
+  if (/^y(es)?$/i.test(t)) return 'yes';
+  if (!t || /^no?$/i.test(t)) return 'no';
+  if (t.startsWith('/')) return 'command';
+  return 'chat';
+}
+
+/** The chat turn an ask's c/free text sends. Bare c (or "chat"): "Tell me more about: <question>, before I decide". */
+export function askChatMessage(text, question) {
+  const t = String(text ?? '').trim();
+  if (/^c(hat)?$/i.test(t)) return `Tell me more about: ${question.replace(/\?$/, '')}, before I decide`;
+  return `${t}\n\n(The terminal is waiting for my y/N answer to: "${question}". I have not answered it yet.)`;
+}
+
+// ASK-SETTLE (owner 2026-10-17: "questions should go once answered, or change to answer"): an open ask is a live
+// card; once answered, expired or no longer open it leaves the screen and ONE line stays in the scrollback.
+/** HH:MM of a timestamp, in this terminal's local time. */
+export function askClock(at = Date.now()) {
+  const d = new Date(at);
+  return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+}
+
+/** The one line an ask leaves behind. outcome.kind: yes | no | run | skipped (outcome.cmd) | expired | closed. */
+export function settledAskLine(question, outcome, at = Date.now()) {
+  const q = String(question || '').trim();
+  const t = askClock(at);
+  switch (outcome?.kind) {
+    case 'yes': return `✔ ${q} yes (${t})`;
+    case 'run': return `✔ ${q} run (${t})`;
+    case 'no': return `✔ ${q} no (${t})`;
+    case 'skipped': return `✔ ${q} skipped, you ran ${String(outcome.cmd || 'a command').split(/\s/)[0]} (${t})`;
+    case 'dismissed': return `↷ ${q} offer dismissed (${t})`;
+    case 'expired': return `⌛ ${q} expired, not answered (${t})`;
+    default: return `↷ ${q} no longer open (${t})`;
+  }
+}
+/** The note tone a settled line is shown in (never dim: no grey text). */
+export const settledAskTone = (kind) => (kind === 'yes' || kind === 'run' ? 'ok' : 'plain');
+
+/** What a submitted line does to an open ask: { kind } for an answer, or null (c / free text keeps it open). */
+export function askOutcomeOf(text, { runWord = false } = {}) {
+  const t = String(text ?? '').trim();
+  if (runWord && /^run$/i.test(t)) return { kind: 'run' };
+  const a = askAnswer(t);
+  if (a === 'yes') return { kind: 'yes' };
+  if (a === 'no') return { kind: 'no' };
+  if (a === 'command') return { kind: 'skipped', cmd: t };
+  return null;
+}
+
+/** A chat line that asks about the open offer (so the card stays): a question, "c", or a why/what/how/explain opener. Anything else is the user moving on, which dismisses the offer. */
+export function isAskClarification(text) {
+  const t = String(text ?? '').trim();
+  return /^c(hat)?$/i.test(t) || /\?\s*$/.test(t) || /^(why|what|how|which|who|when|where|explain|tell me|can you|could you|does|is it|is this)\b/i.test(t);
+}

package/lib/quoxon/away.js

@@ -0,0 +1,52 @@
+/**
+ * E5 local state: when this profile was last seen in the client (~/.config/quox/away.json, keyed by
+ * profile). Only a timestamp is kept; the digest itself always comes from the server. Writes are
+ * best-effort: a read-only home must never break the client.
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+export const AWAY_AFTER_MS = 2 * 3600000;
+export const awayStatePath = () => join(homedir(), '.config', 'quox', 'away.json');
+
+function readAll(path) {
+  try { const j = JSON.parse(readFileSync(path, 'utf8')); return j && typeof j === 'object' && !Array.isArray(j) ? j : {}; } catch { return {}; }
+}
+
+/** -> epoch ms or null (never seen, or unreadable). */
+export function readLastSeen(profile, path = awayStatePath()) {
+  const v = readAll(path)[profile || 'default'];
+  const t = typeof v === 'number' ? v : Date.parse(v);
+  return Number.isFinite(t) ? t : null;
+}
+
+export function writeLastSeen(profile, ts = Date.now(), path = awayStatePath()) {
+  try {
+    const all = readAll(path);
+    all[profile || 'default'] = new Date(ts).toISOString();
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(all) + '\n');
+    renameSync(tmp, path);
+    return true;
+  } catch { return false; }
+}
+
+/** Show the launch card only when the last session ended more than 2 h ago (never on a first launch). */
+export const awayDue = (lastSeen, now = Date.now()) => lastSeen != null && now - lastSeen > AWAY_AFTER_MS;
+
+/**
+ * /away [since]: a window (90m, 3h, 2d), an ISO time, or nothing (last seen, else 24 h).
+ * -> { ok: true, since: iso } | { ok: false, error }
+ */
+export function parseSince(arg, { now = Date.now(), lastSeen = null } = {}) {
+  const a = String(arg || '').trim();
+  if (!a) return { ok: true, since: new Date(lastSeen ?? now - 24 * 3600000).toISOString() };
+  const m = a.match(/^(\d+)\s*([mhd])$/i);
+  if (m) return { ok: true, since: new Date(now - Number(m[1]) * { m: 60000, h: 3600000, d: 86400000 }[m[2].toLowerCase()]).toISOString() };
+  const t = /^\d{4}-\d\d-\d\d/.test(a) ? Date.parse(a) : NaN;
+  if (!Number.isFinite(t)) return { ok: false, error: `Usage: /away [since]  (e.g. /away 3h, /away 2d, /away 2026-10-13T08:00:00Z)` };
+  if (t > now) return { ok: false, error: 'That time is in the future.' };
+  return { ok: true, since: new Date(t).toISOString() };
+}