quoxcli 0.4.0 → 0.5.0

package/lib/quoxon/approvalBatch.js

@@ -0,0 +1,117 @@
+// APPROVAL-BURST (owner 2026-10-28; 2026-10-27 09:53 VIGIL filed nine wire_alerts approvals in a minute as nine cards).
+// 2+ pending approvals from the same agent for the same tool, arriving within 5 minutes of each other, are ONE card.
+// A destructive, risky, privileged or step-up item is NEVER part of a batch: it keeps its own card and its own confirm.
+// Pure helpers; app.js owns the keys and the calls.
+import { describeInboxItem } from './events.js';
+import { isDestructive } from './destructive.js';
+import { heldReason } from './bulkRisk.js';
+
+/** Tools that restart, reboot, run commands or change a running system: one keypress must never do that on several hosts. */
+export const DISRUPTIVE_TOOL = /(^|_|\.)(restart|reboot|shutdown|poweroff|stop|kill|exec|shell|run_command|ssh|deploy|rollback|migrate|upgrade)(_|\.|$)/i;
+export const isDisruptiveTool = (tool) => DISRUPTIVE_TOOL.test(String(tool ?? '').trim());
+const flagged = (o) => Boolean(o && o.disruptive === true);
+/** True when the server marks the item disruptive, else when its tool name matches the list. */
+export function isDisruptive(it) {
+  const p = it?.payload || {}; const c = p.approval_context || {};
+  return flagged(it) || flagged(p) || flagged(c) || flagged(c.method) || flagged(p.what) || isDisruptiveTool(describeInboxItem(it).tool);
+}
+
+export const BATCH_WINDOW_MS = 5 * 60 * 1000;
+export const BATCH_MAX_LINES = 8;
+
+const ms = (v) => { const t = Date.parse(String(v ?? '').includes('T') || !v ? v : `${String(v).replace(' ', 'T')}Z`); return Number.isFinite(t) ? t : null; };
+const clip = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, Math.max(0, n - 1))}…` : t; };
+const key = (agent, tool) => `${String(agent).trim().toLowerCase()}\u0000${String(tool).trim().toLowerCase()}`;
+
+/** Chain by time: the members of `list` ({ t }) whose gaps to a neighbour inside the chain are <= window, starting from `from`. */
+function chainFrom(list, from, window) {
+  const sorted = [...list].sort((a, b) => a.t - b.t);
+  const at = sorted.indexOf(from); if (at < 0) return [from];
+  let lo = at; let hi = at;
+  while (lo > 0 && sorted[lo].t - sorted[lo - 1].t <= window) lo--;
+  while (hi < sorted.length - 1 && sorted[hi + 1].t - sorted[hi].t <= window) hi++;
+  return sorted.slice(lo, hi + 1);
+}
+
+/** What the owner sees on a card of the batch: the item's target, else what it is, else a short id. */
+export const batchLabel = (c) => clip(c.target || c.what || String(c.inboxItemId || c.callId || 'item').slice(0, 8), 120);
+
+// ---- cards (the live approval queue) ---------------------------------------------------------
+const cardTime = (c) => ms(c.askedAt) ?? c.shownAt ?? 0;
+const cardAgent = (c) => c.askedBy || null;
+const cardHeld = (c) => Boolean(c.destructive) || Boolean(c.privileged) || Boolean(c.undescribable) || Boolean(c.plan) || Boolean(c.held) || Boolean(c.disruptive) || isDisruptiveTool(c.tool) || /high|critical/i.test(String(c.risk || ''));
+const cardBatchable = (c) => Boolean(c && c.inboxItemId && c.tool && cardAgent(c) && !cardHeld(c));
+
+/**
+ * The batch the head card belongs to, or null (a lone card). `cards` is the queue in the order shown.
+ * -> { head, agent, tool, cards, heldDeletes, heldOther }. heldDeletes / heldOther count the same agent's destructive
+ * and other risky cards inside the same window: they are NOT in `cards` and keep their own card.
+ */
+export function batchFor(cards, head) {
+  if (!cardBatchable(head)) return null;
+  const k = key(cardAgent(head), head.tool);
+  const mates = cards.filter(c => cardBatchable(c) && key(cardAgent(c), c.tool) === k).map(c => ({ c, t: cardTime(c) }));
+  const me = mates.find(m => m.c === head) || mates.find(m => m.c.callId === head.callId);
+  if (!me) return null;
+  const chain = chainFrom(mates, me, BATCH_WINDOW_MS);
+  if (chain.length < 2) return null;
+  const members = chain.map(m => m.c);
+  const lo = chain[0].t - BATCH_WINDOW_MS; const hi = chain[chain.length - 1].t + BATCH_WINDOW_MS;
+  const held = cards.filter(c => c !== head && !members.includes(c) && cardAgent(c) && String(cardAgent(c)).trim().toLowerCase() === String(cardAgent(head)).trim().toLowerCase() && cardHeld(c) && cardTime(c) >= lo && cardTime(c) <= hi);
+  return { head, agent: cardAgent(head), tool: head.tool, cards: members, heldDeletes: held.filter(c => c.destructive).length, heldOther: held.filter(c => !c.destructive).length };
+}
+
+/** The card's text: title, the item lines (at most 8, then "+K more"), the held-back note and the footer. */
+export function batchModel(b) {
+  const n = b.cards.length;
+  const lines = b.cards.slice(0, BATCH_MAX_LINES).map(batchLabel);
+  const more = n - lines.length;
+  const notes = [];
+  if (b.heldDeletes) notes.push(`+${b.heldDeletes} delete${b.heldDeletes === 1 ? '' : 's'} held for you one by one`);
+  if (b.heldOther) notes.push(`+${b.heldOther} held for you one by one (risky)`);
+  return { n, title: `⚠ ${b.agent} wants to run ${b.tool} on ${n} items`, lines, more: more > 0 ? `+${more} more · p to see all` : null, notes, keys: `y approve all ${n} · n deny all ${n} · p pick one by one · Tab later` };
+}
+
+// ---- raw inbox items (the arrival bar) -------------------------------------------------------
+const isApproval = (it) => Boolean(it?.payload?.approval_context) && it?.payload?.type !== 'decision';
+const itemInfo = (it) => { const d = describeInboxItem(it); return { agent: d.by, tool: d.tool }; };
+const itemBatchable = (it) => { if (!isApproval(it)) return false; const i = itemInfo(it); return Boolean(i.agent && i.tool) && !isDestructive(it) && !isDisruptive(it) && heldReason(it) === null && !/high|critical/i.test(String(it.payload?.approval_context?.risk || '')); };
+
+/**
+ * Raw approval items grouped into bursts: [{ agent, tool, items }] for each run of 2+ from one agent and tool inside the window.
+ * Held, destructive and non-approval items are never in a burst.
+ */
+export function bursts(items) {
+  const by = new Map();
+  for (const it of items || []) {
+    if (!itemBatchable(it)) continue;
+    const i = itemInfo(it); const k = key(i.agent, i.tool);
+    (by.get(k) || by.set(k, []).get(k)).push({ it, t: ms(it.created_at ?? it.createdAt) ?? 0, agent: i.agent, tool: i.tool });
+  }
+  const out = [];
+  for (const list of by.values()) {
+    const seen = new Set();
+    for (const m of [...list].sort((a, b) => a.t - b.t)) {
+      if (seen.has(m)) continue;
+      const chain = chainFrom(list, m, BATCH_WINDOW_MS); chain.forEach(x => seen.add(x));
+      if (chain.length >= 2) out.push({ agent: m.agent, tool: m.tool, items: chain.map(x => x.it) });
+    }
+  }
+  return out;
+}
+
+/** The one arrival line for a burst. */
+export const burstLine = (b) => `📨 ${clip(b.agent, 30)}: ${b.items.length} ${clip(b.tool, 40)} waiting · /approvals`;
+
+/** Arrival lines for fresh items: a burst collapses into one line, everything else keeps its own (`lineOf(item)`). */
+export function collapseArrivals(items, numOf, lineOf = null) {
+  const bs = bursts(items); const inBurst = new Map();
+  bs.forEach(b => b.items.forEach(it => inBurst.set(it, b)));
+  const out = []; const done = new Set();
+  for (const it of items || []) {
+    const b = inBurst.get(it);
+    if (!b) { out.push(lineOf ? lineOf(it, numOf(it)) : `📨 ${clip(it.title || it.kind || 'untitled', 70)} · /inbox${numOf(it) ? ` ${numOf(it)}` : ''}`); continue; }
+    if (done.has(b)) continue; done.add(b); out.push(burstLine(b));
+  }
+  return out;
+}

package/lib/quoxon/approvalFacts.js

@@ -3,6 +3,8 @@
 // (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.
 
+import { startsBackgroundWork } from './backgroundWork.js';
+
 export const CMD_CARD_MAX = 400;
 /** Server text can arrive HTML-escaped ("2>/dev/null"); decode for display. Never renders HTML. */
 const dec = (t) => (typeof t === 'string' ? t.replace(/&(amp|lt|gt|quot|apos|#39|#x27);/gi, (_, e) => ({ amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", '#39': "'", '#x27': "'" })[e.toLowerCase()]) : t);
@@ -79,17 +81,69 @@ export function whyText(it) {
 /** The user's own words that started this, when the server kept them. */
 export const excerptOf = (it) => dec(it?.payload?.approval_context?.on_behalf_of?.request_excerpt) || null;
 
+/** The user's full ask when the server kept it (request_full), else the 300-char excerpt. */
+const fullAskOf = (it) => dec(it?.payload?.approval_context?.on_behalf_of?.request_full) || excerptOf(it);
+
+export const ASKED_BUDGET = 300;
+const VERBS = [
+  [/delet|remov|destroy|drop|purge|wipe/, /\b(delet|remov|destroy|drop|purge|wipe|clean\s?up|tear\s?down|get rid)/i],
+  [/creat|build|add|new|make|install|register/, /\b(creat|build|add|make|set\s?up|install|register|new)/i],
+  [/run|exec|ssh|shell|start|trigger|invoke/, /\b(run|exec|ssh|start|trigger|invoke|launch|restart)/i],
+  [/updat|edit|modif|patch|chang|set|config/, /\b(updat|edit|modif|patch|chang|set|config|rename)/i],
+  [/restart|reboot|stop|kill/, /\b(restart|reboot|stop|kill|shut)/i],
+  [/send|post|publish|email|notify/, /\b(send|post|publish|email|notify)/i]
+];
+const STOP = new Set(['tool', 'the', 'and', 'for', 'get', 'list', 'with', 'true', 'false', 'null']);
+
+/** The sentences (and ", then"/"and finally" clauses) of an ask, in order. */
+function clausesOf(ask) {
+  return ask.split(/(?<=[.!?])\s+|\n+/).flatMap(sn => sn.length > 160 ? sn.split(/,\s+(?=(?:and\s+)?(?:then|finally|after that|lastly)\b)/i) : [sn]).map(x => x.trim()).filter(Boolean);
+}
+
+/**
+ * Long ask: opening sentence (clipped) plus the clause that best matches the tool's verb and object and any id/name in its
+ * input, quoted in full. Null when the ask fits the budget. { text, none }: none = nothing in the ask matches the action.
+ */
+export function askedFor(it, budget = ASKED_BUDGET) {
+  const ask = fullAskOf(it);
+  if (!ask || ask.length <= budget) return null;
+  const p = it?.payload || {}; const tool = String(p.toolName || p.approval_context?.method?.tool || '').toLowerCase();
+  const input = commandOf(it)?.text || '';
+  const parts = tool.split(/[^a-z0-9]+/).filter(w => w.length > 2);
+  const verbRe = (VERBS.find(([t]) => parts.some(w => t.test(w))) || [])[1] || null;
+  const objs = parts.filter(w => !STOP.has(w) && !VERBS.some(([t]) => t.test(w)));
+  const ids = [...new Set((input.match(/[A-Za-z0-9][A-Za-z0-9_.:-]{3,}/g) || []).filter(t => /[\d_-]/.test(t) && !STOP.has(t.toLowerCase())))];
+  const cl = clausesOf(ask);
+  const clip = (t, n) => (t.length > n ? `${t.slice(0, n - 1).trimEnd()}…` : t);
+  let best = -1; let bi = -1;
+  cl.forEach((c, i) => {
+    if (!verbRe || !verbRe.test(c)) return; // the action's own verb must be in the clause
+    const lc = c.toLowerCase();
+    const sc = 2 + objs.filter(o => lc.includes(o)).length + 3 * ids.filter(id => lc.includes(id.toLowerCase())).length;
+    if (sc > best) { best = sc; bi = i; }
+  });
+  const open = `"${clip(cl[0] || ask, 120)}"`;
+  if (bi < 0) return { text: open, none: true };
+  if (bi === 0) return { text: `"${clip(cl[0], 240)}" (the part that asks for this)`, none: false };
+  return { text: `${open} … "${clip(cl[bi], 200)}" (the part that asks for this)`, none: false };
+}
+
 /** One bag of the facts, for the card. */
 export function approvalFacts(it, { n = null } = {}) {
   const cmd = commandOf(it);
+  const af = askedFor(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,
+    // Only a command the server classed read-only may be clipped; anything else (write, or unclassified) is shown whole, so no part of it is hidden from the approver.
+    command: cmd ? { ...cmd, shown: accessOf(it) === 'read-only' ? clipVisible(cmd.text, CMD_CARD_MAX, n) : cmd.text } : null,
+    background: Boolean(cmd && cmd.kind === 'command' && startsBackgroundWork(cmd.text)),
     where: whereText(it, { n }),
     hostList: hostsOf(it).list,
     who: whoText(it),
     why: whyText(it),
-    asked: excerptOf(it),
+    asked: af ? af.text : excerptOf(it),
+    askedNone: Boolean(af && af.none),
+    askedRich: Boolean(af),
     when: when ? String(when).replace('T', ' ').slice(0, 16) + ' UTC' : null,
     access: accessOf(it)
   };

package/lib/quoxon/approvalSentence.js

@@ -19,6 +19,9 @@ export function shortWho(raw) {
 
 const clean = (s) => String(s || '').replace(/\s+/g, ' ').replace(/[.\s]+$/, '').trim();
 
+/** "4 hosts: a, b, c (+1 more, /approvals 3 detail for all)" -> "4 hosts: a, b, c (+1 more)": the hint is for the card, not the sentence. */
+const tidyWhere = (w) => String(w || '').replace(/\s*\(\+(\d+) more[^)]*\)/, ' (+$1 more)');
+
 function whatOf(a) {
   const plain = PLAIN[a.tool];
   if (plain) return plain;
@@ -32,13 +35,14 @@ function whatOf(a) {
 export function approvalSentence(a, approved) {
   const who = shortWho(a.who);
   const [inf, ger] = whatOf(a);
-  const where = clean(a.where || a.target);
+  const where = tidyWhere(clean(a.where || a.target));
   const said = (t) => where && new RegExp(`\\bon ${where.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'i').test(t); // WHAT already ends "on <where>"
-  const at = where && !(said(inf) || said(ger) || new RegExp(`\\b${where.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i').test(inf)) ? ` on ${where}` : '';
+  const multi = /^\d+ hosts?:/i.test(where || '');
+  const at = where && !(multi && (/\bon \d+ hosts?:/i.test(inf) || /\bon \d+ hosts?:/i.test(ger))) && !(said(inf) || said(ger) || new RegExp(`\\b${where.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i').test(inf)) ? ` on ${where}` : '';
   if (approved) {
-    const tail = a.foreign ? ' It runs now; its result isn\'t tracked here.' : '';
+    const tail = a.foreign && !a.approvalId ? ' It runs now; its result isn\'t tracked here.' : '';
     const head = who ? `${who}${inf ? ` to ${inf}` : ''}` : (ger || 'the request');
-    return `\u2714 You approved ${head}${at}.${tail}`;
+    return `\u2714 You approved ${head}${at}.${tail || (a.foreign ? ' It runs now; the result follows here.' : '')}`;
   }
   return `\u2716 You denied ${who ? `${who} ` : ''}${ger || 'the request'}${at}.`;
 }

package/lib/quoxon/approvalsView.js

@@ -1,8 +1,11 @@
 // QUOXON-APPROVALS: pure helpers for /approvals rows, filters, detail and /approve|/deny argument parsing.
 import { describeInboxItem, approvalSourceLabel, isPrivileged } from './events.js';
+import { startsBackgroundWork, BACKGROUND_NOTE } from './backgroundWork.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'.
+/** The ONE rule for "a yes needs the step-up PIN": approval_context.risk high or a high_risk flag. `quox approvals approve` and the walkthrough both use it. */
+export const needsPin = (it) => it?.payload?.approval_context?.risk === 'high' || it?.payload?.high_risk === true;
 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');
@@ -134,13 +137,30 @@ export function contentRows(it) {
   ].filter(r => r[1]);
 }
 
+export const INFERRED_WHY = '(guessed from the command, not stated by the caller)';
+/** The exact command or tool input in full (never clipped), broken inside a token that cannot fit, one block under the label. */
+function commandRows(label, text, cols) {
+  const lead = '  ' + label.padEnd(8); const pad = ' '.repeat(lead.length);
+  const room = cols ? Math.max(20, cols - lead.length - 1) : 0;
+  const out = [];
+  for (const raw of String(text).split('\n')) {
+    if (!room) { out.push(raw); continue; }
+    let l = raw; if (!l.length) { out.push(''); continue; }
+    while (l.length > room) { let cut = l.lastIndexOf(' ', room); if (cut < room / 2) cut = room; out.push(l.slice(0, cut)); l = l.slice(cut).replace(/^ /, ''); }
+    out.push(l);
+  }
+  return out.map((l, k) => (k ? pad : lead) + l);
+}
+
 /** A plain approval (not a quox ask) shaped as a y/n card so the walkthrough can show it. The original id stays, so /approve N routes by the same list. */
 export function approvalAsWalkItem(it) {
   if (isDecision(it)) return it;
   const p = it?.payload || {}; const c = p.approval_context || {};
   const dw = distinctWhat(it); const d = describeInboxItem(it);
   const body = contentRows(it).filter(r => r[0] !== 'summary').map(r => `${r[0]}: ${r[1]}`).join('\n');
-  const why = [whyText(it) || c.why || p.reason || '', body].filter(Boolean).join('\n');
+  const inferred = c.reason && typeof c.reason === 'object' && c.reason.source === 'inferred' && c.reason.text;
+  const whyHead = inferred ? `${INFERRED_WHY}\n${decodeEntities(c.reason.text)}` : (whyText(it) || c.why || p.reason || '');
+  const why = [whyHead, body].filter(Boolean).join('\n');
   return { ...it, __approval: true, title: dw || d.title || it.title || it.id,
     payload: { ...p, type: 'decision', session: requesterNames(it)[0] || approvalSourceLabel(it), why, high_risk: c.risk === 'high' || p.high_risk === true,
       options: [{ key: 'y', label: 'Approve' }, { key: 'n', label: 'Deny' }] } };
@@ -161,8 +181,9 @@ export function approvalRow(it, n, { cols = 100, now = Date.now() } = {}) {
     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 bg = startsBackgroundWork(cmd.text) ? ' · runs in background' : '';
+    const room = Math.max(24, cols - head.length - on.length - risk.length - priv.length - bg.length - 2);
+    return `${head}\`${clipVisible(one, room, n)}\`${on}${risk}${priv}${bg}`;
   }
   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;
@@ -290,20 +311,37 @@ export function hang(label, text, cols) {
   if (cur || !out.length) out.push(cur);
   return out.map((l, k) => (k ? pad : lead) + l);
 }
+/** Word-wrap `text` to `width`, breaking a token longer than the width inside it, so no line is ever wider than `width`. */
+function wrapWords(text, width) {
+  const w = Math.max(1, width); const out = []; let cur = '';
+  for (let tok of String(text).split(' ')) {
+    while (tok.length > w) { // a token that can never fit: break it, never let it outdent or overflow
+      if (cur) { out.push(cur); cur = ''; }
+      out.push(tok.slice(0, w)); tok = tok.slice(w);
+    }
+    if (cur && cur.length + 1 + tok.length > w) { out.push(cur); cur = tok; } else cur = cur ? cur + ' ' + tok : tok;
+  }
+  if (cur || !out.length) out.push(cur);
+  return out;
+}
+/** A "Files (3): - a - b - c" that arrived with its line breaks flattened becomes a header line plus one "- item" line each. */
+function unflattenList(text) {
+  const t = String(text ?? '');
+  if (t.includes('\n')) return t;
+  const m = /^(.*?\(\d+\):)\s+- (.+)$/.exec(t.trim());
+  return m ? [m[1], ...m[2].split(/\s+- /).map(x => '- ' + x)].join('\n') : t;
+}
 /** Like hang, but keeps the text's own line breaks: each line (a "- " list item too) starts a fresh line under the label, wrapped items indented past the dash. */
 export function hangBlock(label, text, cols) {
-  const segs = String(text ?? '').split('\n').map(l => l.replace(/\s+/g, ' ').trim()).filter(Boolean);
+  const segs = unflattenList(text).split('\n').map(l => l.replace(/\s+/g, ' ').trim()).filter(Boolean);
   if (segs.length <= 1) return hang(label, segs[0] || '', cols);
   const lead = '  ' + label.padEnd(8); const pad = ' '.repeat(lead.length);
   const room = Math.max(20, (cols || 0) - lead.length - 1); const out = [];
   for (const seg of segs) {
     if (!cols) { out.push(seg); continue; }
-    const ind = /^[-*] /.test(seg) ? '  ' : '';
-    let cur = '';
-    for (const w of seg.split(' ')) {
-      if (cur && cur.length + 1 + w.length > room) { out.push(cur); cur = ind + w; } else cur = cur ? cur + ' ' + w : w;
-    }
-    if (cur) out.push(cur);
+    const item = /^[-*] /.test(seg);
+    const lines = item ? wrapWords(seg.slice(2), room - 2).map((l, k) => (k ? '  ' : seg.slice(0, 2)) + l) : wrapWords(seg, room);
+    out.push(...lines);
   }
   return out.map((l, k) => (k ? pad : lead) + l);
 }
@@ -317,6 +355,20 @@ export const isLoosening = (it) => { const p = it?.payload || {}; return p.loose
 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();
+/** ADVICE for a test-edit (loosening) card: only facts the card carries (payload.diff_stats), never the asker's own recommendation, which has its own star line. */
+export const NO_INDEPENDENT_VIEW = 'No independent view: judge the JUSTIFY text and the diff (/diff or the files listed).';
+/** The `quox ask loosening` verb titles its card "Approve test edits: <paths>", which isLoosening does not match. */
+const TEST_EDIT_RE = /approve\s+(?:loosening|test)\b/i;
+function looseAdvice(p) {
+  const d = p.diff_stats || p.diff; if (!d || typeof d !== 'object') return NO_INDEPENDENT_VIEW;
+  const rm = Number(d.assertions_removed), ad = Number(d.assertions_added), fc = Number(d.files_changed);
+  const bits = [];
+  if (Number.isFinite(rm) && Number.isFinite(ad)) bits.push(rm === 0 ? `nothing removed, ${ad} added` : `${rm} assertion${rm === 1 ? '' : 's'} removed, ${ad} added`);
+  else if (Number.isFinite(rm)) bits.push(`${rm} assertion${rm === 1 ? '' : 's'} removed`);
+  if (d.new_test) bits.unshift('a new test');
+  if (Number.isFinite(fc)) bits.push(`${fc} file${fc === 1 ? '' : 's'} changed`);
+  return bits.length ? `From the diff: ${bits.join(', ')}. Judge the JUSTIFY text against that.` : NO_INDEPENDENT_VIEW;
+}
 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
@@ -326,10 +378,12 @@ export function walkCard(it, i, total, { cols = 0 } = {}) {
   const dflt = bareLoose ? (p.options.find(o => o.key === 'n') || null) : (p.options.find(o => o.key === p.default) || null);
   const why = decodeEntities(String(p.why || '')).split('\n').map(l => l.replace(/\s+/g, ' ').trim()).filter(Boolean).join('\n');
   const what = yn
-    ? `Yes lets ${who} go ahead with this; no stops it.${p.high_risk ? ' High risk: a yes needs your PIN.' : ''}`
+    ? `Yes lets ${who} go ahead with this; no stops it.${it.__approval && commandOf(it)?.kind === 'command' && startsBackgroundWork(commandOf(it).text) ? ` This ${BACKGROUND_NOTE}.` : ''}${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 && (loose || TEST_EDIT_RE.test(String(it.title || '')))
+    ? looseAdvice(p)
     : 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}).` : ''}`;
@@ -339,10 +393,14 @@ export function walkCard(it, i, total, { cols = 0 } = {}) {
     { key: keyClash('s') ? 'skip' : 's', label: 'Skip for now', defer: true },
     { key: keyClash('?') ? 'ask' : '?', label: 'Ask about it', ask: true },
   ];
+  const cmdFact = it.__approval ? commandOf(it) : null; // the same facts the single approval card shows (approvalFacts), here in full
+  const whereFact = it.__approval ? whereText(it, { all: true }) : null;
   const lines = [
     `${p.__approval ? 'Approval' : 'Decision'} ${i} of ${total} · ${who} asks`,
     ...hang('', cleanTitle(it), cols).map(l => l.slice(8)),
     ...hang('WHAT', what, cols),
+    ...(cmdFact ? commandRows(cmdFact.kind === 'input' ? 'INPUT' : 'COMMAND', cmdFact.text, cols) : []),
+    ...(whereFact ? hang('WHERE', whereFact, cols) : []),
     ...(why ? hangBlock('WHY', why, cols) : []),
     ...(loose || just ? hang('JUSTIFY', just || NO_JUSTIFICATION, cols) : []),
     ...(!why && !just && !loose ? hang('WHY', NO_REASON, cols) : []),

package/lib/quoxon/autoOpen.js

@@ -0,0 +1,94 @@
+// APPROVALS-AUTO (owner 2026-11-06: "just make approvals pop up, i am tired of opening them"): pure rules for opening a
+// newly arrived approval or decision BY ITSELF as the /approvals walkthrough card. It only ever OPENS a card; it never
+// answers one. Keystrokes are never stolen: a draft in the box, typing in the last TYPING_PAUSE_MS, a streaming turn or
+// another ask on screen holds it, and it opens at the next idle point. A walkthrough already open simply gains the card.
+import { matchesAgent } from './approvalsView.js';
+
+export const TYPING_PAUSE_MS = 2000;
+/** How long after a "N more arrived" notice a bare y/n still belongs to the card, not the chat. */
+export const STRAY_WINDOW_MS = 30000;
+
+/** The /approvals auto setting: ON unless the profile explicitly says false. */
+export const autoOn = (settings) => !(settings && settings.approvalsAuto === false);
+
+const keyOf = (orgId, id) => `${orgId || ''}|${id}`;
+
+/** @returns {{ enabled: boolean, seen: Set<string>, seeded: Set<string>, queue: object[] }} */
+export function createAutoOpen({ enabled = true } = {}) {
+  return { enabled, seen: new Set(), seeded: new Set(), queue: [] };
+}
+
+/**
+ * One poll of open items for one org (orgId null = the window's own org). The first read of each org only seeds what was
+ * already waiting (nothing pops at launch). New ids queue once; ids in skipIds (shown inline as this conversation's card,
+ * or answered here) never queue; a queued item the server no longer lists leaves the queue. While switched off, arrivals
+ * are marked seen so turning it on never replays them.
+ * Cross-org items carry __orgId and __orgName. seed overrides the first-read rule (false: queue even on a first read).
+ */
+export function noteArrivals(st, items, { skipIds = null, orgId = null, orgName = null, seed = null } = {}) {
+  const list = (Array.isArray(items) ? items : []).filter((x) => x && x.id);
+  const org = orgId || '';
+  const first = seed === null ? !st.seeded.has(org) : Boolean(seed); // seed:false = an org first read after launch: what it has is new
+  st.seeded.add(org);
+  const live = new Set(list.map((x) => keyOf(orgId, x.id)));
+  st.queue = st.queue.filter((x) => (x.__orgId || '') !== org || live.has(keyOf(orgId, x.id)));
+  const added = [];
+  for (const it of list) {
+    const k = keyOf(orgId, it.id);
+    if (st.seen.has(k)) continue;
+    st.seen.add(k);
+    if (first || !st.enabled || (skipIds && skipIds.has(it.id))) continue;
+    const item = orgId ? { ...it, __orgId: orgId, __orgName: orgName || orgId } : it;
+    st.queue.push(item); added.push(item);
+  }
+  return { added };
+}
+
+/**
+ * Whether to open now: 'open' | 'join' (a walk is on screen: append, its own order shows it) | 'wait-draft' |
+ * 'wait-typing' | 'wait-turn' | 'wait-ask' | null (nothing queued, or switched off).
+ */
+export function openDecision(st, { draft = '', lastKeyAt = 0, now = Date.now(), streaming = false, walkOpen = false, askOpen = false } = {}) {
+  if (!st.enabled || !st.queue.length) return null;
+  if (walkOpen) return 'join';
+  if (String(draft || '') !== '') return 'wait-draft';
+  if (now - (lastKeyAt || 0) < TYPING_PAUSE_MS) return 'wait-typing';
+  if (streaming) return 'wait-turn';
+  if (askOpen) return 'wait-ask';
+  return 'open';
+}
+
+/** Hands the queued items over once. */
+export function takeQueue(st) { const q = st.queue; st.queue = []; return q; }
+
+/**
+ * A submitted line that is a bare yes/no while a card is queued (or just after a "more arrived" notice) belongs to that
+ * card: the caller opens the card and keeps the key for it. Never chat.
+ */
+export function strayAnswer(text, { queued = 0, walkOpen = false, noticeAt = 0, now = Date.now() } = {}) {
+  if (walkOpen) return false;
+  if (!/^(y|n|yes|no)$/i.test(String(text ?? '').trim())) return false;
+  return queued > 0 || (noticeAt > 0 && now - noticeAt < STRAY_WINDOW_MS);
+}
+
+export const APPROVALS_OPTIONS = 'help, walkthrough, N, mine, agents, old, <agent name>, auto on|off';
+
+/** /approvals arguments -> { kind: list|help|walkthrough|detail|filter|auto|unknown }. An unknown word says so, never lists. */
+export function parseApprovalsArg(arg, { items = [] } = {}) {
+  const t = String(arg ?? '').trim();
+  if (!t) return { kind: 'list' };
+  if (/^help$/i.test(t)) return { kind: 'help' };
+  if (/^walkthrough$/i.test(t)) return { kind: 'walkthrough' };
+  if (/^\d+$/.test(t)) return { kind: 'detail', n: Number(t) };
+  const m = /^auto(?:\s+(\S+))?$/i.exec(t);
+  if (m) {
+    if (!m[1]) return { kind: 'auto', set: null };
+    if (/^on$/i.test(m[1])) return { kind: 'auto', set: true };
+    if (/^off$/i.test(m[1])) return { kind: 'auto', set: false };
+    return { kind: 'unknown', word: t };
+  }
+  const k = t.toLowerCase();
+  if (k === 'mine' || k === 'agents' || k === 'old') return { kind: 'filter', f: k };
+  if ((items || []).some((it) => matchesAgent(it, t))) return { kind: 'filter', f: t };
+  return { kind: 'unknown', word: t };
+}

package/lib/quoxon/backgroundWork.js

@@ -0,0 +1,59 @@
+// Does a shell command start detached work? Then the approver's "it ran fine" only covers the launch. Pure: text in, boolean out.
+// Quote-aware: '&' inside quotes, '&&', redirects (2>&1, >&2, &>f), '|&', a backslash-escaped '\&' and '# comments' are not background.
+
+export const BACKGROUND_NOTE = 'starts background work: the result you see is only the launch, not the outcome';
+
+const WRAPPERS = new Set(['sudo', 'env', 'command', 'exec', 'time', 'nice', 'ionice', 'doas', 'stdbuf', 'timeout']);
+const DETACHERS = new Set(['nohup', 'setsid', 'disown', 'at', 'batch']);
+
+/** One command's words (quotes removed) -> true when its command word detaches. */
+function segmentDetaches(words) {
+  let i = 0;
+  while (i < words.length) {
+    const w = words[i];
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(w)) { i++; continue; } // FOO=1 cmd
+    if (WRAPPERS.has(w)) { i++; while (i < words.length && /^-/.test(words[i])) i++; continue; }
+    break;
+  }
+  const cmd = (words[i] || '').replace(/^.*\//, '');
+  const rest = words.slice(i + 1);
+  if (DETACHERS.has(cmd)) return true;
+  if (cmd === 'systemd-run') return !rest.some(a => /^(--wait|--pipe|--pty|--scope|--shell|-P|-t|-S)$/.test(a)); // these wait for the unit; plain systemd-run returns at once
+  if (cmd === 'screen') return rest.some(a => /^-[A-Za-z]*d[A-Za-z]*m?[A-Za-z]*$/.test(a) && /^-[A-Za-z]+$/.test(a) && (/d/.test(a)) && (/m/.test(a) || rest.includes('-m'))); // screen -d -m / -dm / -dmS
+  if (cmd === 'tmux') return /^(new|new-session)$/.test(rest[0] || '') && rest.slice(1).some(a => /^-[A-Za-z]*d[A-Za-z]*$/.test(a));
+  if (cmd === 'docker') {
+    const sub = rest.filter(a => !/^-/.test(a));
+    if (sub[0] === 'run') return rest.some(a => a === '--detach' || /^-[A-Za-z]*d[A-Za-z]*$/.test(a));
+    if (sub[0] === 'compose' && rest.includes('up')) return rest.some(a => a === '--detach' || /^-[A-Za-z]*d[A-Za-z]*$/.test(a));
+    return false;
+  }
+  if (cmd === 'docker-compose') return rest[0] === 'up' && rest.some(a => a === '--detach' || /^-[A-Za-z]*d[A-Za-z]*$/.test(a));
+  if (cmd === 'systemctl') return rest.includes('--no-block') && rest.some(a => /^(start|restart|reload|try-restart|reload-or-restart|stop|isolate)$/.test(a));
+  return false;
+}
+
+export function startsBackgroundWork(text) {
+  const s = typeof text === 'string' ? text : '';
+  if (!s) return false;
+  let words = []; let cur = null; let q = null; let found = false;
+  const endWord = () => { if (cur !== null) { words.push(cur); cur = null; } };
+  const endSeg = () => { endWord(); if (words.length && segmentDetaches(words)) found = true; words = []; };
+  for (let i = 0; i < s.length && !found; i++) {
+    const ch = s[i];
+    if (q) { if (ch === q) q = null; else if (q === '"' && ch === '\\' && i + 1 < s.length) { cur += s[++i]; } else cur += ch; continue; }
+    if (ch === '\\') { cur = (cur ?? '') + (s[++i] ?? ''); continue; }
+    if (ch === "'" || ch === '"') { q = ch; cur = cur ?? ''; continue; }
+    if (ch === '#' && cur === null) { while (i < s.length && s[i] !== '\n') i++; endSeg(); continue; }
+    if (/\s/.test(ch)) { if (ch === '\n') endSeg(); else endWord(); continue; }
+    if (ch === '&') {
+      if (s[i + 1] === '&') { endSeg(); i++; continue; }
+      const prev = s[i - 1];
+      if (s[i + 1] === '>' || prev === '>' || prev === '<' || prev === '|') { cur = (cur ?? '') + ch; continue; } // &>f, 2>&1, <&3, |&
+      endSeg(); found = true; break; // a lone '&' detaches the command before it
+    }
+    if (ch === ';' || ch === '|' || ch === '(' || ch === ')' || ch === '{' || ch === '}') { endSeg(); continue; }
+    cur = (cur ?? '') + ch;
+  }
+  if (!found) endSeg();
+  return found;
+}

package/lib/quoxon/bang.js

@@ -187,7 +187,7 @@ export function runBang(plan, { cwd = process.cwd(), env = process.env, timeoutM
 /** The "exit N · 1.2s" footer, plus the plain-words reasons. */
 export function footer(r, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   const secs = `${(r.ms / 1000).toFixed(1)}s`;
-  if (r.timedOut) return `timed out after ${Math.round(timeoutMs / 1000)}s and was stopped · ${secs} (QUOX_BANG_TIMEOUT_MS changes the limit)`;
+  if (r.timedOut) return `timed out after ${Math.round(timeoutMs / 1000)}s · stopped; anything it already started may have completed. Run long commands in a terminal, or set QUOX_BANG_TIMEOUT_MS · ${secs}`;
   if (r.killed) return `stopped (Ctrl+C) · ${secs}`;
   if (r.signal) return `killed by ${r.signal} · ${secs}`;
   return `exit ${r.code} · ${secs}`;

package/lib/quoxon/capabilities.js

@@ -45,6 +45,11 @@ export function offerFor(capabilityId, res) {
   }
 }
 
+/** -> display names of every requires_setup capability, in server order. */
+export function needsSetupNames(caps) {
+  return (Array.isArray(caps) ? caps : []).filter(c => c.availability === 'requires_setup').map(capabilityName);
+}
+
 /** -> [[text, tone?]] for /capabilities. */
 export function capabilityLines(res) {
   if (!res?.ok || !Array.isArray(res.capabilities)) {
@@ -59,7 +64,7 @@ export function capabilityLines(res) {
   if (!installed.length) out.push(['  nothing is ready yet']);
   const setup = of('requires_setup');
   if (setup.length) {
-    out.push(['Needs setup:']);
+    out.push([`Needs setup (${setup.length}): ${needsSetupNames(caps).join(', ')}`]);
     for (const c of setup) out.push([`◐ ${capabilityName(c)}  ${c.reason || 'needs setup'}${c.setup ? ` · ${c.setup}` : ''}`, 'warn']);
   }
   const unk = caps.filter(statusUnreadable);
@@ -70,7 +75,7 @@ export function capabilityLines(res) {
   const off = of('unavailable').filter(c => !statusUnreadable(c));
   if (off.length) {
     out.push(['Not available here:']);
-    for (const c of off) out.push([`○ ${capabilityName(c)}  ${c.reason || 'unavailable'}${c.setup ? ` · ${c.setup}` : ''}`]);
+    for (const c of off) out.push([`○ ${capabilityName(c)}  ${c.reason === 'No signal to check' ? 'not checked: nothing here reports on it yet' : (c.reason || 'unavailable')}${c.setup ? ` · ${c.setup}` : ''}`]);
   }
   const planned = of('planned');
   if (planned.length) {

package/lib/quoxon/commandShort.js

@@ -8,6 +8,7 @@ export const SHORT_MAX = 54;
 export const SHORT = {
   walkthrough: 'a guided pass: what it does, why, my advice',
   inbox: 'your Quox inbox: latest items, read, open',
+  mail: 'your triaged email, read only: latest, or N to read',
   approvals: 'the questions waiting for you, one at a time',
   peek: 'look up an envelope, item, run or receipt by id',
   aside: 'a read-only side question, kept out of the chat',
@@ -17,6 +18,7 @@ export const SHORT = {
   answer: 'answer a question a session asked you',
   authenticate: 'enter your PIN once, good for 10 minutes',
   override: 'override one blocked action (PIN, witnessed)',
+  'verify-email': 'mark a user email verified (admin, PIN, audited)',
   skills: 'list your org\'s governed skills, or show one',
   skill: 'ask Quox to run a skill (approvals still apply)',
   rules: 'which rules win: QUOX.md, dev pack, server policy',
@@ -50,6 +52,8 @@ export const SHORT = {
   demo: 'play the simulated demo; nothing real runs',
   feedback: 'tell the Quox team something (you see it first)',
   gripe: 'file a GitHub issue; /gripe! files at once',
+  gripes: 'gripes waiting to be filed, and recent ones',
+  outbox: 'messages waiting for QuoxCORE to answer',
   sessions: 'everything live in your org, and where it runs',
   active: 'who is doing what, one line per worker',
   dashboard: 'open the web dashboard already signed in',
@@ -97,6 +101,9 @@ export const SHORT = {
   org: 'list your orgs, switch to one, or go back',
   r: 'reply to whoever last messaged you (also /reply)',
   poke: 'wake a session with an urgent page (also /wake)',
+  donotdisturb: 'sleep means sleep: collect quietly, read at morning',
+  morningreport: 'what came in while do not disturb was on',
+  callmeforapprovals: 'phone me when a high-risk approval sits unanswered',
   afk: 'tell sessions you are away; approvals still queue',
   back: 'mark yourself present and show what you missed',
   observe: 'post a note to the session watching your window',