quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/slash/automate.js

@@ -0,0 +1,89 @@
+/**
+ * /automate [task]: turn the conversation (or the task you name) into a persistent workflow.
+ * Real: the draft is ONE model call (draft.js); creation uses the quoxflow workflow store (POST /api/workflows) and
+ * activation registers its trigger (POST /api/workflows/:id/activate), the same calls as `quox workflow apply` and
+ * `quox trigger workflow-activate`. The model only fills a small, validated shape; node types are an allowlist.
+ */
+import { draftJson, transcriptText } from './draft.js';
+
+const STEP_TYPES = new Set(['agent:invoke', 'approval:gate', 'notification:deliver', 'util:log']);
+const CRON_RE = /^\s*\S+(\s+\S+){4}\s*$/;
+const why = (e) => `${e?.status ? `HTTP ${e.status}: ` : ''}${e?.message || 'failed'}`;
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'workflow';
+
+export const automatePrompt = (context) => [
+  'Draft a persistent automation from the conversation below. Reply with ONE JSON object and nothing else. Use no tools.',
+  'Shape: {"name":str,"description":str,"trigger":{"type":"schedule","cron":"5-field cron","timezone":"UTC"} or {"type":"webhook","path":"/name"},',
+  ' "steps":[{"id":str,"type":"agent:invoke"|"approval:gate"|"notification:deliver"|"util:log","label":str,"prompt":str (agent:invoke) or "message":str (others)}],',
+  ' "recovery":{"onFailure":"stop"|"continue","retry":bool}}.',
+  'Infer the trigger and schedule from what the user wants; add an approval:gate before anything irreversible or external; keep 2 to 6 steps.',
+  '', '--- conversation ---', context, '--- end ---'
+].join('\n');
+
+/** Validate the model draft and build the quoxflow workflow definition. -> { def, card[] } or { error } */
+export function buildWorkflow(d, now = Date.now()) {
+  if (!d || typeof d.name !== 'string' || !d.name.trim()) return { error: 'the draft has no name' };
+  const t = d.trigger || {};
+  let trigger;
+  if (t.type === 'schedule' && typeof t.cron === 'string' && CRON_RE.test(t.cron)) trigger = { id: 'trigger', type: 'trigger:schedule', config: { cron: t.cron.trim(), timezone: t.timezone || 'UTC' } };
+  else if (t.type === 'webhook' && typeof t.path === 'string' && t.path.trim()) trigger = { id: 'trigger', type: 'trigger:webhook', config: { path: t.path.trim(), method: 'POST' } };
+  else return { error: 'the draft has no valid trigger (a 5-field cron schedule or a webhook path)' };
+  const steps = Array.isArray(d.steps) ? d.steps : [];
+  if (!steps.length || steps.length > 8) return { error: 'the draft needs between 1 and 8 steps' };
+  const nodes = [trigger];
+  for (const [i, s] of steps.entries()) {
+    if (!s || !STEP_TYPES.has(s.type)) return { error: `step ${i + 1} has a type that is not allowed (${s?.type})` };
+    const id = `s${i + 1}`, label = String(s.label || s.type);
+    const text = String(s.prompt || s.message || '').trim();
+    if (!text) return { error: `step ${i + 1} (${label}) has no prompt or message` };
+    const config = s.type === 'agent:invoke' ? { agent_id: 'quox', prompt: text, label }
+      : s.type === 'approval:gate' ? { label, message: text, approvers: ['*'], expiresIn: '48h' }
+        : s.type === 'notification:deliver' ? { title: label, message: text }
+          : { level: 'info', message: text, label };
+    nodes.push({ id, type: s.type, config });
+  }
+  const edges = nodes.slice(1).map((n, i) => ({ source: nodes[i].id, target: n.id }));
+  const stop = (d.recovery?.onFailure || 'stop') !== 'continue';
+  const retry = d.recovery?.retry === true;
+  const def = {
+    id: `${slug(d.name)}-${now.toString(36)}`, name: d.name.trim(), description: String(d.description || '').slice(0, 500),
+    nodes, edges, settings: { errorBehavior: stop ? 'stop' : 'continue', retryOnFailure: retry, saveEvidence: true },
+    metadata: { source: 'quoxon /automate' }
+  };
+  const when = trigger.type === 'trigger:schedule' ? `schedule  ${trigger.config.cron} (${trigger.config.timezone})` : `webhook  POST ${trigger.config.path}`;
+  const gates = nodes.filter((n) => n.type === 'approval:gate').map((n) => n.config.label);
+  const card = [
+    ['Workflow draft (nothing is created until you answer):', 'accent'],
+    `  Name       ${def.name}`,
+    `  Trigger    ${when}`,
+    `  Steps      ${nodes.slice(1).map((n) => n.config.label || n.type).join(' > ')}`,
+    `  Approvals  ${gates.length ? gates.join(', ') : 'none (it runs without asking)'}`,
+    `  Recovery   ${stop ? 'stop on failure' : 'continue on failure'}${retry ? ', retry on' : ''}`
+  ];
+  return { def, card };
+}
+
+export function createAutomateCmd({ api, say, confirm, getState, getFields }) {
+  return {
+    async handle(arg) {
+      if (!api.workflowCreate) return say('Workflows are not available in this mode.', 'warn');
+      const ctx = [transcriptText(getState()), String(arg || '').trim() ? `User wants to automate: ${String(arg).trim()}` : ''].filter(Boolean).join('\n');
+      if (!ctx) return say('Nothing to automate yet. Do the task with Quox first, or say what: /automate every monday send me a signup digest.');
+      say('Drafting the workflow…', 'dim');
+      let d;
+      try { d = await draftJson({ api, prompt: automatePrompt(ctx), fields: getFields() }); }
+      catch (e) { return say(`Could not draft a workflow: ${e.message}. Nothing was created.`, 'warn'); }
+      const b = buildWorkflow(d);
+      if (b.error) return say(`Could not draft a usable workflow: ${b.error}. Nothing was created.`, 'warn');
+      confirm.ask(b.card, async () => {
+        let c;
+        try { c = await api.workflowCreate(b.def); } catch (e) { return say(`Could not create the workflow: ${why(e)}`, 'warn'); }
+        const id = c?.id || b.def.id;
+        try { await api.workflowActivate(id); } catch (e) { say(`Workflow ${id} was created but NOT activated (${why(e)}), so it will not run on its own. quox trigger workflow-activate ${id}`, 'warn'); return say(`  See it: /workflow ${id}`); }
+        say(`✔ Workflow "${b.def.name}" created and active (id ${id}).`, 'ok');
+        say(`  See it: /workflow ${id}`);
+      }, { prompt: 'Create and activate this workflow?' });
+      return undefined;
+    }
+  };
+}

package/lib/quoxon/slash/broadcast.js

@@ -0,0 +1,140 @@
+/**
+ * QUOXON-BROADCAST: pure helpers for /broadcast, /page and /ack (and `quox slot broadcast`).
+ * No I/O. v1 scope: all held slots or --slots, --priority urgent, --ack, /page. Scheduling, voice,
+ * fleet and org reach, bulletins and drafting are not built.
+ */
+export const BROADCAST_USAGE = 'Usage: /broadcast [--slots a,b] [--priority urgent] [--ack] <text>';
+export const PAGE_USAGE = 'Usage: /page <slot> <text>';
+const NOT_YET = new Set(['--fleet', '--org', '--voice', '--at']);
+
+/**
+ * -> { ok:true, text, slots|null, priority, ack } | { ok:false, message }.
+ * Flags may come before the text; `--all` is accepted (the default). `--priority=urgent` also works.
+ */
+export function parseBroadcastArgs(arg) {
+  const toks = String(arg || '').trim().split(/\s+/).filter(Boolean);
+  let slots = null; let priority = 'normal'; let ack = false;
+  let i = 0;
+  for (; i < toks.length && toks[i].startsWith('--'); i += 1) {
+    const [flag, inline] = toks[i].split(/=(.*)/s);
+    if (NOT_YET.has(flag)) return { ok: false, message: `${flag} is not available yet (v1 sends to held slots in this org: --slots, --priority, --ack).` };
+    if (flag === '--all') { slots = null; continue; }
+    if (flag === '--ack') { ack = true; continue; }
+    const val = inline !== undefined ? inline : toks[++i];
+    if (flag === '--slots') {
+      const list = String(val || '').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+      if (!list.length) return { ok: false, message: '--slots needs a comma-separated list, e.g. --slots provisioner,quox2' };
+      slots = list; continue;
+    }
+    if (flag === '--priority') {
+      if (val !== 'urgent' && val !== 'normal') return { ok: false, message: '--priority is urgent or normal' };
+      priority = val; continue;
+    }
+    return { ok: false, message: `unknown flag ${flag}. ${BROADCAST_USAGE}` };
+  }
+  const text = toks.slice(i).join(' ');
+  if (!text) return { ok: false, message: BROADCAST_USAGE };
+  return { ok: true, text, slots, priority, ack };
+}
+
+/** `/page <slot> <text>` -> urgent, ack-required, one recipient. */
+export function parsePageArgs(arg) {
+  const m = /^(\S+)\s+([\s\S]*\S[\s\S]*)$/.exec(String(arg || '').trim());
+  if (!m || m[1].startsWith('--')) return { ok: false, message: PAGE_USAGE };
+  return { ok: true, text: m[2].trim(), slots: [m[1].toLowerCase()], priority: 'urgent', ack: true };
+}
+
+const plural = (n) => (n === 1 ? 'session' : 'sessions');
+const NAMES_SHOWN = 5;
+const okSlots = (r) => (r.deliveries || []).filter((d) => d.status === 'delivered' || d.status === 'queued'); // RESTORE-TUI: queued has it (older servers)
+const badSlots = (r) => (r.deliveries || []).filter((d) => d.status === 'failed' || d.status === 'unknown');
+const roomC = (r) => ({ sent: 0, sending: 0, failed: 0, ...(r?.counts?.room || {}) });
+const isAck = (r) => !!(r?.ack ?? r?.ack_required);
+const namesRow = (r) => {
+  const n = okSlots(r).map((d) => d.slot);
+  return n.length > NAMES_SHOWN ? `${n.slice(0, NAMES_SHOWN).join(' ')} +${n.length - NAMES_SHOWN}` : n.join(' ');
+};
+const roomText = (rc, sep) => [rc.sent && `${rc.sent} sent`, rc.sending && `${rc.sending} sending`, rc.failed && `${rc.failed} failed`].filter(Boolean).join(sep);
+const failText = (d) => `${d.slot}: ${d.status}${d.detail ? ` (${d.detail})` : ''}`;
+const titleWord = (r) => {
+  const c = r?.counts || {};
+  if (!c.total) return 'not sent';
+  if (!c.delivered) return 'not sent';
+  return c.failed ? 'partly sent' : 'sent';
+};
+
+/**
+ * The sender's delivery card as data: { title, tone, rows: [[[text, role], ...], ...], foot }.
+ * Roles are theme roles: ok (green), warn (gold), error (red), prose. Rendered by render.js (framed) or
+ * flattened to text. "delivered" means the line is in the slot; the chat-room copy is its own row.
+ */
+export function broadcastCard(r, { kind = 'broadcast' } = {}) {
+  const c = r?.counts || {};
+  const rc = roomC(r);
+  const rows = [];
+  if (!c.total) rows.push([['\u26A0 no held slots in this org to hear it', 'warn']]);
+  else if (c.delivered) {
+    rows.push([[`\u2714 ${c.delivered} ${c.delivered === 1 ? 'session has' : 'sessions have'} it`, 'ok']]);
+    if (namesRow(r)) rows.push([[namesRow(r), 'prose']]); // an older server sends no per-slot list: no empty row
+  }
+  for (const d of badSlots(r).slice(0, 3)) rows.push([[`\u2716 ${failText(d)}`, 'error']]);
+  if (badSlots(r).length > 3) rows.push([[`\u2716 +${badSlots(r).length - 3} more failed`, 'error']]);
+  if (c.delivered && roomText(rc, ' ')) rows.push([[`chat rooms: ${roomText(rc, ' \u00B7 ')}`, rc.failed ? 'error' : rc.sending ? 'warn' : 'ok']]);
+  if (isAck(r) && c.delivered) rows.push([[`acknowledged ${c.acknowledged || 0} / ${c.delivered}`, c.awaiting ? 'warn' : 'ok']]);
+  const tone = !c.total || (!c.delivered && !c.failed) ? 'warn' : c.failed || !c.delivered ? 'error' : 'ok';
+  return {
+    title: `\u{1F4E3} ${kind === 'page' ? 'PAGE' : 'BROADCAST'} ${titleWord(r)}`,
+    tone, rows, foot: `${r.id} \u00B7 /broadcast status <id>`,
+    narrow: broadcastNarrow(r),
+  };
+}
+
+/** One line for narrow terminals. */
+export function broadcastNarrow(r) {
+  const c = r?.counts || {};
+  const rc = roomC(r);
+  if (!c.total) return '\u{1F4E3} no held slots to hear it \u26A0';
+  const rooms = `(rooms ${rc.sent}/${c.delivered})`;
+  if (c.failed) return `\u{1F4E3} sent to ${c.delivered} of ${c.total} ${plural(c.total)} \u2716 ${c.failed} failed ${rooms}`;
+  const ack = isAck(r) ? ` \u00B7 acked ${c.acknowledged || 0}/${c.delivered}` : '';
+  return `\u{1F4E3} sent to ${c.delivered} ${plural(c.delivered)} \u2714 ${rooms}${ack}`;
+}
+
+/** The same facts as plain text lines [[text, tone]] (CLI output, and the TUI when no card surface is wired). */
+export function broadcastSummary(r) {
+  const c = r?.counts || {};
+  const rc = roomC(r);
+  const lines = [];
+  if (!c.total) return [[`Broadcast ${r.id}: no held slots in this org to hear it.`, 'warn']];
+  lines.push([`Broadcast ${r.id} ${titleWord(r)}: ${(c.delivered || 0) + (c.queued || 0)} of ${c.total} ${plural(c.total)} have it${okSlots(r).length ? ` (${okSlots(r).map((d) => d.slot).join(', ')})` : ''}`, c.failed ? 'warn' : 'plain']);
+  if (c.delivered && roomText(rc, ', ')) lines.push([`  chat rooms: ${roomText(rc, ', ')}`, rc.failed ? 'warn' : 'plain']);
+  for (const d of badSlots(r)) lines.push([`  ${failText(d)}`, 'warn']);
+  if (isAck(r) && c.delivered) lines.push([`  acknowledged ${c.acknowledged || 0} / ${c.delivered}. Check: quox slot broadcast-status ${r.id}`, 'plain']);
+  return lines;
+}
+
+/** The sender's live line: "Broadcast delivery: delivered N / acknowledged M / awaiting K". */
+export function deliveryLine(st) {
+  const c = st?.counts || {};
+  const base = `Broadcast delivery: delivered ${(c.delivered || 0) + (c.queued || 0)}`; // RESTORE-TUI: an older server still counts queued separately; queued has it too
+  return st?.ack_required ? `${base} / acknowledged ${c.acknowledged || 0} / awaiting ${c.awaiting || 0}` : base;
+}
+
+/** `/broadcast status <id>` -> { id } | null (anything else after "status" is just message text). */
+export function parseStatusArgs(arg) {
+  const m = /^status\s+(bc_[0-9a-f]+)\s*$/.exec(String(arg || '').trim());
+  return m ? { id: m[1] } : null;
+}
+
+const BC_RE = /^(\u{1F6A8} URGENT|\u{1F4E3}) BROADCAST from ([^\n]*?): ([\s\S]*?)(?:\n\(ack with \/ack (bc_[0-9a-f]+)\))?$/u;
+/** Recognise a broadcast line in the slot stream -> { urgent, sender, text, ackId } | null. */
+export function parseBroadcastText(text) {
+  const m = BC_RE.exec(String(text || ''));
+  return m ? { urgent: m[1] !== '\u{1F4E3}', sender: m[2], text: m[3], ackId: m[4] || null } : null;
+}
+
+export const ACK_USAGE = 'Usage: /ack <broadcast id>';
+export function parseAckArgs(arg) {
+  const id = String(arg || '').trim();
+  return /^bc_[0-9a-f]+$/.test(id) ? { ok: true, id } : { ok: false, message: ACK_USAGE };
+}

package/lib/quoxon/slash/broadcastRun.js

@@ -0,0 +1,108 @@
+/**
+ * QUOXON-BROADCAST: the I/O half of /broadcast, /page and /ack. app.js adds only switch cases that call these.
+ * One server call fans out (POST /api/v1/slots/broadcast); with --ack the sender then sees the delivery line
+ * update as recipients acknowledge. The poll is display only: the broadcast and its acks live on the server.
+ */
+import { parseBroadcastArgs, parsePageArgs, parseAckArgs, parseStatusArgs, broadcastSummary, broadcastCard, BROADCAST_USAGE } from './broadcast.js';
+
+const roomC = (r) => ({ sent: 0, sending: 0, failed: 0, ...(r?.counts?.room || {}) });
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function runBroadcast({ api, kind, arg, from, say, card = null, isClosed = () => false, pollMs = 4000, maxPolls = 30 }) {
+  if (!api.slotBroadcast) return say('Broadcast is not available in this mode.', 'warn');
+  const show = (data) => {
+    if (card) return card(broadcastCard(data, { kind }));
+    for (const [line, tone] of broadcastSummary(data)) say(line, tone);
+    return undefined;
+  };
+  const st0 = kind === 'page' ? null : parseStatusArgs(arg);
+  if (st0) {
+    const st = api.slotBroadcastStatus ? await api.slotBroadcastStatus(st0.id) : { ok: false, message: 'not available in this mode' };
+    return st.ok ? show(st.data) : say(`Broadcast status failed: ${st.message}`, 'warn');
+  }
+  const parsed = kind === 'page' ? parsePageArgs(arg) : parseBroadcastArgs(arg);
+  if (!parsed.ok) return say(parsed.message, parsed.message === BROADCAST_USAGE ? 'plain' : 'warn');
+  const r = await api.slotBroadcast({ text: parsed.text, slots: parsed.slots, priority: parsed.priority, ack: parsed.ack, from });
+  if (!r.ok) return say(`${kind === 'page' ? 'Page' : 'Broadcast'} failed: ${r.message}`, 'warn');
+  show(r.data);
+  // PRESENCE: it reached a human slot whose human is away; approvals to them will queue.
+  if (r.data?.human_presence?.away && r.data.human_presence.notice) say(`⏸ ${r.data.human_presence.notice}`, 'warn');
+  // POKE-WAKE: a page also asks each delivered slot's keeper to wake its idle session, so the page is read now,
+  // not at the session's next prompt. Runs beside the ack display; the page stands whatever the wake says.
+  const wakes = kind === 'page' && api.slotControl
+    ? Promise.all((r.data.deliveries || []).filter((d) => d.status === 'delivered').map((d) => runWake({ api, slot: d.slot, say, isClosed, pollMs: Math.max(pollMs, 1), maxPolls: 15 }).catch(() => {})))
+    : null;
+  const done = async (v) => { if (wakes) await wakes; return v; };
+  if (!api.slotBroadcastStatus || !r.data.counts?.delivered) return done(undefined);
+  // The card is history (printed once), so what changes afterwards arrives as short lines: acks as they come in,
+  // and one line when the chat-room copies settle. Display only: the broadcast and its acks live on the server.
+  let lastAck = r.data.counts.acknowledged ?? null;
+  let roomsDone = !roomC(r.data).sending;
+  const ackWanted = parsed.ack && r.data.counts.awaiting > 0;
+  if (roomsDone && !ackWanted) return done(undefined);
+  for (let i = 0; i < maxPolls && !isClosed(); i += 1) {
+    await sleep(pollMs);
+    let st = null;
+    try { st = await api.slotBroadcastStatus(r.data.id); } catch { st = null; }
+    if (!st?.ok) continue;
+    const c = st.data.counts || {};
+    const rc = roomC(st.data);
+    if (!roomsDone && !rc.sending) {
+      roomsDone = true;
+      say(rc.failed ? `chat rooms: ${rc.sent} sent, ${rc.failed} failed` : `chat rooms: all ${rc.sent} sent`, rc.failed ? 'warn' : 'ok');
+    }
+    if (parsed.ack && c.acknowledged !== undefined && c.acknowledged !== lastAck) {
+      lastAck = c.acknowledged;
+      say(`acknowledged ${c.acknowledged} / ${c.delivered}`, c.awaiting ? 'plain' : 'ok');
+    }
+    if (roomsDone && !(parsed.ack && c.awaiting)) return done(undefined);
+  }
+  return done(undefined);
+}
+
+/**
+ * FORCE-WAKE: `/poke|/wake|/slap|/nudge <slot> [text]`. `--force` is accepted anywhere as a no-op (every human
+ * wake already sets an unsent draft aside and puts it back) and is never page text. null = no slot given.
+ */
+export function parsePokeArgs(restArg) {
+  const s = String(restArg || '').replace(/(^|\s)--force(?=\s|$)/g, '$1').trim();
+  const m = /^(\S+)(?:\s+([\s\S]+))?$/.exec(s);
+  return m ? { slot: m[1], text: m[2] ? m[2].trim() : null } : null;
+}
+
+/**
+ * POKE-WAKE: ask the slot's keeper to wake its session (slot control `wake`, human admin only, server-side).
+ * The keeper types one fixed "read your slot" line at an empty prompt; never the page text. Display only.
+ */
+export async function runWake({ api, slot, say, isClosed = () => false, pollMs = 4000, maxPolls = 15 }) {
+  const r = await api.slotControl(slot, 'wake');
+  if (!r?.ok) {
+    if (r?.status === 403) return say(`${slot}: waking a session needs an org owner or admin; the page waits for its next check`, 'warn');
+    if (r?.status === 400) return say(`${slot}: this server does not support wake yet; the page waits for its next check`, 'warn');
+    if (r?.status === 409) return say(`${slot}: nobody holds this slot, so there is no session to wake`, 'warn');
+    return say(`${slot}: wake request failed (${r?.message || 'failed'}); the page waits for its next check`, 'warn');
+  }
+  const id = r.data?.control_id;
+  if (!id || !api.slotControlGet) return say(`${slot}: wake requested`, 'plain');
+  for (let i = 0; i < maxPolls && !isClosed(); i += 1) {
+    await sleep(pollMs);
+    let g = null;
+    try { g = await api.slotControlGet(slot, id); } catch { g = null; }
+    const st = g?.ok ? g.data?.status : null;
+    // WAKE-REAL: the waker is told which happened: a turn started, or Claude Code queued it mid-turn.
+    if (st === 'done' && /^queued\b/.test(String(g.data.result || ''))) return say(`${slot} ${g.data.result}`, 'ok');
+    if (st === 'done') return say(`${slot} woken: ${g.data.result || 'done'}`, 'ok');
+    if (st === 'failed') return say(`${slot} not woken: ${String(g.data.result || 'failed').replace(/^not woken:\s*/, '')}`, 'warn');
+  }
+  return say(`${slot} not woken yet: it is mid-turn, so its keeper wakes it as soon as the turn ends (retrying up to 10m), or its keeper is not running (/slot status ${slot})`, 'warn');
+}
+
+export async function runAck({ api, arg, slot, say }) {
+  const a = parseAckArgs(arg);
+  if (!a.ok) return say(a.message, 'warn');
+  if (!slot) return say('/ack answers as the slot this window holds; hold one with /slot <name>.', 'warn');
+  if (!api.slotAck) return say('Broadcast is not available in this mode.', 'warn');
+  const r = await api.slotAck(a.id, slot);
+  if (!r.ok) return say(`ack failed: ${r.message}`, 'warn');
+  return say(`Acknowledged ${a.id} as ${slot}.`, 'plain');
+}

package/lib/quoxon/slash/card.js

@@ -0,0 +1,30 @@
+/**
+ * One card, one y/n. The answer is the next composer line (the /approve "y/N" pattern); a slash command typed
+ * instead drops the card. A direct human ask is already the authorization, so the card is the only gate.
+ * (Own copy for /undo and /wish; kept in this file so it does not depend on another branch's helper.)
+ */
+import { askText } from '../ask.js';
+export function createCard({ say, now = () => Date.now(), ttlMs = 120000 }) {
+  let pending = null;
+  return {
+    pending: () => Boolean(pending),
+    /** y/N/c: a chat about the ask keeps it open with a fresh window. */
+    touch() { if (pending) pending.at = now(); },
+    ask(lines, onYes, cancelText, { question = 'Go ahead?', reason = '', who = '', action = '' } = {}) {
+      pending = { onYes, at: now(), cancelText };
+      for (const l of lines) say(l);
+      say(askText(question, { reason, who, action }), 'ask'); // QUOXON-ASK: one shape (live 22:41: /wish ended in a bare "y/n")
+    },
+    /** -> true when this line was the answer (consumed). */
+    answer(text) {
+      if (!pending) return false;
+      const q = pending; pending = null;
+      const t = String(text || '').trim();
+      if (t.startsWith('/')) return false;
+      if (now() - q.at > ttlMs) { say('That card expired, so nothing was done. Run the command again.', 'dim'); return true; }
+      if (/^y(es)?$/i.test(t)) { Promise.resolve(q.onYes()).catch((e) => say(`Failed: ${e?.message || e}`, 'warn')); return true; }
+      say(q.cancelText, 'dim');
+      return true;
+    }
+  };
+}

package/lib/quoxon/slash/challenge.js

@@ -0,0 +1,114 @@
+/**
+ * /challenge [focus]: brutaloop on demand. One read-only adversarial review turn over the last answer and the
+ * last turn's tool calls, on a different provider when one is connected (else another model on the same
+ * provider, and it says which). Costs one extra model turn. "Resolve these? y/N" sends the findings back to
+ * the original agent as a normal turn.
+ *
+ * deps: api, say(text, tone), getState() -> the events state, sendTurn(text) -> a normal turn to the original agent.
+ */
+import { askText } from '../ask.js';
+import { connectedChoices } from '../model.js';
+import { lastOutput } from '../dragonModes.js';
+import { textGate } from '../events.js';
+
+const MAX_FINDING_LINES = 40;
+const newTurnId = () => `QXN_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+/** Tool items of the last turn: everything after the last user item. */
+export function collectTools(s) {
+  const all = [...(s?.history || []), ...(s?.blocks || [])];
+  let from = 0;
+  for (let i = all.length - 1; i >= 0; i--) if (all[i].kind === 'user' && !all[i].echo) { from = i + 1; break; }
+  return all.slice(from).filter((it) => it.kind === 'tool');
+}
+
+const toolLine = (t) => {
+  const r = t.receipt?.ward_seq != null ? ` receipt ward:${t.receipt.ward_seq}` : '';
+  return `- ${t.tool}${t.target ? ` ${t.target}` : ''} [${t.status || 'unknown'}]${t.resultSummary || t.summary ? ` ${String(t.resultSummary || t.summary).slice(0, 200)}` : ''}${r}`;
+};
+
+export function reviewPrompt({ answer, tools = [], focus = '' }) {
+  return [
+    'You are an adversarial reviewer. Another agent gave the answer below. Review it; do not call tools.',
+    'Find: factual errors, unsupported claims, missed failures, unsafe actions.',
+    'Output one finding per line as: SEVERITY | finding | evidence it rests on. SEVERITY is HIGH, MEDIUM or LOW.',
+    'Every finding must cite its evidence (a tool call, a receipt, or the text of the answer). Do not rewrite the answer.',
+    'If you find nothing, say "No findings" and why.',
+    focus ? `Focus especially on: ${focus}` : '',
+    '',
+    'ANSWER UNDER REVIEW:', answer, '',
+    tools.length ? `TOOL CALLS AND RECEIPTS FROM THAT TURN:\n${tools.map(toolLine).join('\n')}` : 'No tool calls in that turn.',
+  ].filter((x) => x !== '').join('\n');
+}
+
+export const resolvePrompt = (findings) => `An independent reviewer challenged your last answer. For each finding below, fix it or rebut it with evidence, one by one:\n\n${findings}`;
+
+/** -> { provider, model?, note } | null. connected: [{ provider }]; models: ids on the answering provider. */
+export function pickReviewer({ connected, answered, models = [] }) {
+  const other = (connected || []).find((c) => c.provider && c.provider !== answered?.provider);
+  if (other) return { provider: other.provider, note: `Reviewer: ${other.provider} (a different provider from ${answered?.provider || 'the answerer'}).` };
+  const same = (connected || []).some((c) => c.provider === answered?.provider);
+  const alt = same ? (models || []).find((m) => m && m !== answered?.model) : null;
+  if (alt) return { provider: answered.provider, model: alt, note: `Reviewer: ${answered.provider} ${alt} (same provider, different model: no other provider is connected).` };
+  return null;
+}
+
+export function createChallengeCmd({ api, say, getState, sendTurn, now = Date.now }) {
+  const st = { pending: null, busy: false };
+
+  async function run(focus = '') {
+    const s = getState();
+    if (st.busy) return say('A challenge is already running.', 'warn');
+    if (s.turn) return say('Wait for the current turn or press Esc first.', 'warn');
+    const o = lastOutput(s);
+    if (!o || o.kind !== 'answer') return say('Nothing to challenge yet: ask something first.', 'warn');
+    if (!api.connections) return say('/challenge is not available in this mode.', 'warn');
+    st.pending = null;
+    const answered = { provider: s.ctx?.provider || null, model: s.ctx?.model || null };
+    const res = await api.connections();
+    const caps = api.capabilities ? await api.capabilities() : null;
+    const connected = connectedChoices(res, caps);
+    let models = [];
+    if (!connected.some((c) => c.provider !== answered.provider) && api.providerModels && answered.provider) {
+      const r = await api.providerModels(answered.provider);
+      models = r?.ok ? (r.models || []).map((m) => m.id || m) : [];
+    }
+    const pick = pickReviewer({ connected, answered, models });
+    if (!pick) return say('No other provider or model is connected to review with, so /challenge would only ask the same model. /connect another provider first.', 'warn');
+    say(`${pick.note} One extra model turn.`, 'dim');
+    st.busy = true;
+    let text = '', gate = null, failed = null;
+    try {
+      for await (const ev of api.stream({ turnId: newTurnId(), message: reviewPrompt({ answer: o.text, tools: collectTools(s), focus: String(focus || '').trim() }), agent: 'quox', provider: pick.provider, ...(pick.model ? { model: pick.model } : {}) })) {
+        if (ev.type === 'chunk' || ev.type === 'text.delta' || ev.type === 'turn.started') { const g = textGate(gate, ev); gate = g.st; if (g.append) text += ev.content; }
+        else if (ev.type === 'done' && !text && ev.full_response) text = ev.full_response;
+        else if (ev.type === 'error') failed = ev.error || 'stream error';
+      }
+    } catch (e) { failed = e?.message || 'failed'; }
+    finally { st.busy = false; }
+    if (failed && !text.trim()) return say(`Challenge failed: ${failed}`, 'warn');
+    const body = text.trim();
+    if (!body) return say('The reviewer returned nothing.', 'warn');
+    const lines = body.split('\n').map((l) => l.trimEnd()).filter(Boolean);
+    for (const l of lines.slice(0, MAX_FINDING_LINES)) say(l, /^high\b/i.test(l) ? 'error' : /^medium\b/i.test(l) ? 'warn' : undefined);
+    if (lines.length > MAX_FINDING_LINES) say(`... ${lines.length - MAX_FINDING_LINES} more lines not shown.`, 'dim');
+    if (/^no findings/i.test(body)) return undefined;
+    st.pending = { findings: body, at: now() };
+    return say(askText('Resolve these?'), 'ask');
+  }
+
+  /** y/N to the resolve offer. true when the input was consumed. */
+  function answer(text) {
+    const p = st.pending;
+    if (!p) return false;
+    const t = String(text || '').trim();
+    if (t.startsWith('/')) { st.pending = null; return false; }
+    st.pending = null;
+    if (now() - p.at > 600000) return false;
+    if (/^y(es)?$/i.test(t)) { sendTurn(resolvePrompt(p.findings)); return true; }
+    say('Left the findings alone.', 'dim');
+    return /^no?$/i.test(t) ? true : false;
+  }
+
+  return { run, answer, get pending() { return st.pending; } };
+}

package/lib/quoxon/slash/cliCommand.js

@@ -0,0 +1,53 @@
+/**
+ * QUOXON-FW: a slash line whose words name a real `quox` CLI leaf (`/plans list`, `/notes new "x"`) is that command.
+ * Pure resolution only; app.js runs it (read: in-window like a ! command; write: asks "Run it? y/N"; never: refuses).
+ * LEAVES is cliLeaves.json: path -> read|write|never, vendored from docs/matrix/sources/cli-leaf-policy.json
+ * (a test fails if they drift; regenerate with the one-liner in that test's failure message).
+ */
+import { createRequire } from 'node:module';
+import { tokenize } from '../bang.js';
+
+export const LEAVES = createRequire(import.meta.url)('./cliLeaves.json');
+
+// verbs people type that the CLI spells differently (only used when the result is a real leaf)
+const ALIASES = { ls: 'list', lists: 'list', rm: 'remove', del: 'delete', new: 'add', create: 'add', info: 'show', get: 'show', aware: 'lucid', neighbors: 'neighbours' };
+
+function variants(w) {
+  const lw = w.toLowerCase();
+  const out = new Set([lw]);
+  if (lw.endsWith('ies')) out.add(`${lw.slice(0, -3)}y`);
+  if (lw.endsWith('es')) out.add(lw.slice(0, -2));
+  if (lw.endsWith('s')) out.add(lw.slice(0, -1)); else out.add(`${lw}s`);
+  if (ALIASES[lw]) out.add(ALIASES[lw]);
+  for (const v of [...out]) if (ALIASES[v]) out.add(ALIASES[v]);
+  return [...out];
+}
+
+const MAX_DEPTH = 4;
+
+/** -> { path, cls, args, display } | null. args is the full argv after `quox` (quoted args preserved). */
+export function resolveCliSlash(cmd, restArg, leaves = LEAVES) {
+  const first = String(cmd || '').replace(/^\//, '');
+  if (!first || first.startsWith('-')) return null;
+  const rest = tokenize(String(restArg || ''));
+  const words = [first, ...rest];
+  const walk = (n) => { // all path spellings for the first n words
+    let acc = [[]];
+    for (let i = 0; i < n; i++) {
+      if (words[i].startsWith('-')) return [];
+      const vs = variants(words[i]);
+      acc = acc.flatMap(p => vs.map(v => [...p, v]));
+    }
+    return acc;
+  };
+  for (let n = Math.min(MAX_DEPTH, words.length); n >= 1; n--) {
+    for (const p of walk(n)) {
+      const path = p.join(' ');
+      if (Object.prototype.hasOwnProperty.call(leaves, path)) {
+        const args = [...p, ...words.slice(n)];
+        return { path, cls: leaves[path], args, display: `quox ${args.map(a => (/[\s"']/.test(a) || a === '' ? JSON.stringify(a) : a)).join(' ')}` };
+      }
+    }
+  }
+  return null;
+}