quoxcli 0.0.0-stage → 0.3.1

package/lib/core/activeSummary.js

@@ -0,0 +1,186 @@
+/**
+ * `quox active` / TUI `/active` (QUOXON-1208, owner: "summary of who is doing what"). ONE simplified list over the
+ * org session index (GET /api/v1/sessions: tmux sessions, held slots, residents, work, working chats), one line per
+ * active worker, newest activity first, grouped Working / Waiting on you / Idle (+ Failing when there is any).
+ * Real data only: a worker's "doing" text is what the index carries (its state reason, slot, agent), never invented;
+ * a source the index could not read is named in one line. Pure: activeLines(index, opts) -> [{ text, tone }].
+ */
+import { formatAge } from './claudeLs.js';
+
+export const ACTIVE_KINDS = ['sessions', 'slots', 'agents'];
+export const PER_GROUP = 10;
+export const ASLEEP_AFTER_S = 6 * 3600; // a resting worker with no activity for this long reads as asleep
+
+const clip = (v, n) => { const a = [...String(v ?? '')]; return a.length > n ? a.slice(0, n - 1).join('') + '…' : String(v ?? ''); };
+const t = (r) => { const x = Date.parse(r.last_active); return Number.isFinite(x) ? x : -Infinity; };
+
+/** Which filter(s) a row belongs to. sessions = terminal sessions, slots = held slots, agents = residents or agent-attached rows. */
+export function rowKinds(r) {
+  const k = new Set();
+  if (r.kind === 'tmux') k.add('sessions');
+  if (r.kind === 'slot') k.add('slots');
+  if (r.kind === 'resident' || r.agent) k.add('agents');
+  return k;
+}
+
+function doing(r) {
+  const bits = [];
+  if (r.state_reason) bits.push(String(r.state_reason).replace(/\s+/g, ' ').trim());
+  if (r.kind === 'tmux' && r.backend) bits.push(`${r.backend} session`);
+  else if (r.kind === 'slot') bits.push('holding a slot');
+  else if (r.kind === 'conversation') bits.push('chat');
+  else if (r.kind) bits.push(r.kind);
+  if (r.slot && r.kind !== 'slot') bits.push(`slot ${r.slot}`);
+  if (r.agent) bits.push(`agent ${r.agent}`);
+  return bits.length ? bits.join(', ') : 'no activity detail recorded';
+}
+
+function stateWord(r, ageS) {
+  if (r.state === 'working') return 'working';
+  if (r.state === 'waiting') return 'waiting on you';
+  if (r.state === 'failing') return 'failing';
+  if (ageS != null && ageS >= ASLEEP_AFTER_S) return 'asleep';
+  return ageS != null ? `idle ${formatAge(ageS)}` : 'idle';
+}
+
+/** -> { rows: [{ name, doing, state, group, since, ts, kinds }], groups: {working, waiting, failing, idle}, down: [..] } */
+export function prepareActive(index, { filter = null, now = Date.now() } = {}) {
+  const rows = (index?.rows || (index?.groups || []).flatMap((g) => g.rows) || [])
+    .filter((r) => r.kind !== 'conversation' || r.state === 'working' || r.state === 'waiting')
+    .filter((r) => !filter || rowKinds(r).has(filter))
+    .sort((a, b) => t(b) - t(a))
+    .map((r) => {
+      const ts = t(r);
+      const ageS = Number.isFinite(ts) ? Math.max(0, (now - ts) / 1000) : null;
+      const group = r.state === 'working' ? 'working' : r.state === 'waiting' ? 'waiting' : r.state === 'failing' ? 'failing' : 'idle';
+      const name = r.kind === 'slot' ? (r.holder_session || r.name || '(unnamed slot)') : (r.name || '(unnamed)');
+      return { name, doing: doing(r), state: stateWord(r, ageS), group, since: ageS == null ? 'no activity recorded' : `${formatAge(ageS)} ago`, ts };
+    });
+  const groups = { working: [], waiting: [], failing: [], idle: [] };
+  for (const r of rows) groups[r.group].push(r);
+  const down = (index?.sources || []).filter((s) => s.state !== 'connected');
+  return { rows, groups, down };
+}
+
+const TITLES = { working: 'Working', waiting: 'Waiting on you', failing: 'Failing', idle: 'Idle' };
+const TONES = { working: 'ok', waiting: 'warn', failing: 'warn', idle: 'dim' };
+
+export function activeLines(index, { filter = null, now = Date.now(), all = false } = {}) {
+  const p = prepareActive(index, { filter, now });
+  const out = [{ text: `Active${filter ? ` ${filter}` : ''}: ${p.rows.length} · ${p.groups.working.length} working · ${p.groups.waiting.length} waiting on you · ${p.groups.idle.length} idle${p.groups.failing.length ? ` · ${p.groups.failing.length} failing` : ''}`, tone: 'accent' }];
+  if (!p.rows.length) out.push({ text: p.down.some((s) => s.state !== 'unavailable') ? 'Nothing to show (see the sources below).' : `No active ${filter || 'workers'} in this org.`, tone: 'dim' });
+  for (const g of ['working', 'waiting', 'failing', 'idle']) {
+    const rs = p.groups[g];
+    if (!rs.length) continue;
+    out.push({ text: `${TITLES[g]} (${rs.length})`, tone: 'accent' });
+    for (const r of all ? rs : rs.slice(0, PER_GROUP)) out.push({ text: `  ${clip(r.name, 28).padEnd(28)} ${clip(r.doing, 44).padEnd(44)} ${r.state}, ${r.since}`, tone: TONES[g] });
+    if (!all && rs.length > PER_GROUP) out.push({ text: `  +${rs.length - PER_GROUP} more`, tone: 'dim' });
+  }
+  // 'unavailable' is a source the server declares it does not list yet (residents): an expected absence, not a failed read.
+  // Only a real fault (error, timeout) is "could not read". Residents that hold a slot already show up as rows above.
+  const failed = p.down.filter((s) => s.state !== 'unavailable');
+  const absent = p.down.filter((s) => s.state === 'unavailable');
+  if (failed.length) out.push({ text: `could not read: ${failed.map((s) => `${s.id} (${s.state}${s.note ? `: ${s.note}` : ''})`).join(' · ')}`, tone: 'warn' });
+  if (absent.length) out.push({ text: `not listed separately yet: ${absent.map((s) => s.id).join(' · ')} (shown above when they hold a slot)`, tone: 'dim' });
+  return out;
+}
+
+// ---- TUI /active: one clean row per session -------------------------------------------------------------
+const GLYPH = { working: '◐', waiting: '⚠', failing: '✖', idle: '·' };
+const RANK = { waiting: 0, failing: 1, working: 2, idle: 3 };
+const TUI_TONES = { working: undefined, waiting: undefined, failing: undefined, idle: undefined }; // the row's own glyph carries status; a tone would prefix a second glyph on every wrapped line
+const GROUP_TITLES = { waiting: 'Waiting on you', failing: 'Failing', working: 'Working', idle: 'Idle' };
+
+/** "resident:hyp-01" -> { name: 'hyp-01', tag: 'resident' }: the machine prefix becomes a readable tag. */
+function readableName(raw) {
+  const m = String(raw).match(/^(resident|agent|slot|tmux):(.+)$/i);
+  return m ? { name: m[2], tag: m[1].toLowerCase() } : { name: String(raw), tag: null };
+}
+const humanReason = (reason) => String(reason || '').replace(/\s+/g, ' ').trim().replace(/^unread slot messages?$/i, 'unread messages');
+
+/** Word-wrap `rest` after `first`; continuation lines get a 4-space hanging indent. Never clips, never exceeds `width`. */
+function wrapHanging(first, rest, width, sep = '  ') {
+  const out = [];
+  let cur = first, fresh = true; // fresh: only the label is on this line so far
+  for (const w of String(rest).split(/\s+/).filter(Boolean)) {
+    const joined = fresh ? `${cur}${sep}${w}` : `${cur} ${w}`;
+    if ([...joined].length <= width) { cur = joined; fresh = false; continue; }
+    out.push(cur); cur = `    ${w}`; fresh = false;
+  }
+  out.push(cur);
+  return out;
+}
+
+/**
+ * The window's /active: one row per session (deduped by readable name; the row that needs you wins), shaped
+ * `  <glyph> <name>  <what it needs> · <age>`, word-wrapped under a hanging indent at `cols`, never clipped, grouped
+ * Waiting on you / Failing / Working / Idle. The `quox active` CLI keeps activeLines(); this is the TUI-only view.
+ */
+export function activeRows(index, { now = Date.now(), cols = 80, filter = null, unread = null } = {}) {
+  const raw = (index?.rows || (index?.groups || []).flatMap((g) => g.rows) || [])
+    .filter((r) => r.kind !== 'conversation' || r.state === 'working' || r.state === 'waiting')
+    .filter((r) => !filter || rowKinds(r).has(filter));
+  const byName = new Map();
+  for (const r of raw) {
+    const base = r.kind === 'slot' ? (r.holder_session || r.name || '(unnamed slot)') : (r.name || '(unnamed)');
+    const { name, tag } = readableName(base);
+    const ts = t(r), ageS = Number.isFinite(ts) ? Math.max(0, (now - ts) / 1000) : null;
+    const group = r.state === 'working' ? 'working' : r.state === 'waiting' ? 'waiting' : r.state === 'failing' ? 'failing' : 'idle';
+    const needs = [];
+    let why = humanReason(r.state_reason);
+    const nUnread = unread && (unread.get?.(r.kind === 'slot' ? (r.name || '') : (r.slot || '')) ?? null); // optional per-slot count from the slots list
+    if (why === 'unread messages' && nUnread > 0) why = `${nUnread} unread message${nUnread === 1 ? '' : 's'}`;
+    if (why) needs.push(why);
+    else needs.push(group === 'idle' ? (ageS != null && ageS >= ASLEEP_AFTER_S ? 'asleep' : 'idle') : group);
+    if (r.kind === 'slot') needs.push('holding a slot'); else if (r.slot) needs.push(`holding slot ${r.slot}`);
+    if (r.agent) needs.push(`agent ${r.agent}`);
+    const cand = { name, tag: tag || (r.kind === 'resident' ? 'resident' : null), group, needs, ageS, ts };
+    const key = name.toLowerCase(), old = byName.get(key);
+    if (!old) { byName.set(key, cand); continue; }
+    const better = RANK[cand.group] < RANK[old.group] || (RANK[cand.group] === RANK[old.group] && cand.ts > old.ts);
+    const win = better ? cand : old, lose = better ? old : cand;
+    const hasUnread = win.needs.some((n) => /unread/.test(n));
+    win.needs = [...new Set([...win.needs, ...lose.needs.filter((n) => !/^(working|idle|asleep|failing)$/.test(n) && !(hasUnread && /unread/.test(n)) && !(/^holding a slot$/.test(n) && win.needs.some((x) => /^holding/.test(x))))])];
+    win.tag = win.tag || lose.tag;
+    byName.set(key, win);
+  }
+  const rows = [...byName.values()].sort((a, b) => RANK[a.group] - RANK[b.group] || b.ts - a.ts);
+  const n = (g) => rows.filter((r) => r.group === g).length;
+  const width = Math.max(30, cols - 4);
+  const hdr = `${rows.length} · ${n('waiting')} need you · ${n('working')} working · ${n('idle')} idle${n('failing') ? ` · ${n('failing')} failing` : ''}`;
+  const out = wrapHanging(`Active${filter ? ` ${filter}` : ''}:`, hdr, width, ' ').map((text) => ({ text, tone: 'accent' }));
+  if (!rows.length) out.push({ text: `No active ${filter || 'workers'} in this org.`, tone: undefined });
+  let last = null;
+  for (const r of rows) {
+    if (r.group !== last) { last = r.group; out.push({ text: `${GROUP_TITLES[r.group]} (${n(r.group)})`, tone: 'accent' }); }
+    const label = `${r.name}${r.tag ? ` (${r.tag})` : ''}`;
+    const what = `${r.needs.join(' · ')}${r.ageS == null ? '' : ` · ${formatAge(r.ageS)} ago`}`;
+    for (const text of wrapHanging(`  ${GLYPH[r.group]} ${label}`, what, width)) out.push({ text, tone: TUI_TONES[r.group] });
+  }
+  // a source that could not be read is never an empty org: name it ('unavailable' is an expected absence, not a fault)
+  const failed = (index?.sources || []).filter((x) => x.state !== 'connected' && x.state !== 'unavailable');
+  if (failed.length) for (const text of wrapHanging('could not read:', failed.map((x) => `${x.id} (${x.state}${x.note ? `: ${x.note}` : ''})`).join(' · '), width, ' ')) out.push({ text, tone: 'warn' });
+  return out;
+}
+
+/** Bare `quox active [sessions|slots|agents] [--json] [--all]`. A failed fetch prints its status and exits 1 (never an empty list). */
+export async function runActive({ filter = null, json = false, all = false, lines = false, cols = null } = {}, over = {}) {
+  const d = { write: (s) => process.stdout.write(s), now: () => Date.now(), ...over };
+  if (filter && !ACTIVE_KINDS.includes(filter)) { d.write(`quox active: unknown filter "${filter}" (sessions, slots or agents)\n`); return 1; }
+  try {
+    const idx = await d.fetchIndex();
+    if (json) {
+      const p = prepareActive(idx, { filter, now: d.now() });
+      d.write(JSON.stringify({ filter, counts: Object.fromEntries(Object.entries(p.groups).map(([k, v]) => [k, v.length])), workers: p.rows.map(({ ts, ...r }) => r), sources_down: p.down }, null, 2) + '\n');
+    } else if (lines) d.write(activeLines(idx, { filter, now: d.now(), all }).map((l) => l.text).join('\n') + '\n');
+    else {
+      let unread = null;
+      if (d.fetchSlots) { try { unread = new Map((await d.fetchSlots() || []).map((x) => [x.name, x.unread_count || 0])); } catch { unread = null; } } // the count is a nicety: a failed slots read never hides the list
+      d.write(activeRows(idx, { filter, now: d.now(), cols: cols || process.stdout.columns || 100, unread }).map((l) => l.text).join('\n') + '\n');
+    }
+    return 0;
+  } catch (e) {
+    d.write(`quox active: ${e && e.status ? `HTTP ${e.status}: ` : ''}${(e && e.message) || 'request failed'}\n`);
+    return 1;
+  }
+}

package/lib/core/aee.js

@@ -0,0 +1,53 @@
+/**
+ * AEE envelope emitter for CLI commands
+ *
+ * Emits lightweight event envelopes so CLI actions appear in the
+ * AEE audit trail. Fire-and-forget — failures are silently ignored
+ * so they never block the command itself.
+ *
+ * CLI-3 EVIDENCED dimension (quoxai/quox#290)
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const PROTOCOL_VERSION = '1';
+
+function ulid() {
+  const t = Date.now().toString(36).padStart(10, '0');
+  const r = Array.from({ length: 16 }, () => Math.random().toString(36)[2]).join('');
+  return (t + r).toUpperCase();
+}
+
+/**
+ * Emit an AEE event envelope for a CLI command invocation.
+ *
+ * @param {Object} client - The CLI HTTP client (ctx.client)
+ * @param {Object} params
+ * @param {string} params.command - CLI command name (e.g. 'status', 'doctor')
+ * @param {string} params.intent - AEE intent string (e.g. 'quox.cli.status')
+ * @param {Object} [params.payload] - Command-specific result data
+ * @param {string} [params.status] - 'success' | 'error'
+ */
+export async function emitCliEvent(client, { command, intent, payload = {}, status = 'success' }) {
+  try {
+    const envelope = {
+      v: PROTOCOL_VERSION,
+      id: ulid(),
+      ts: new Date().toISOString(),
+      type: 'event',
+      from: 'cli.quox',
+      to: 'system.audit',
+      intent,
+      corr: null,
+      reply_to: null,
+      payload: {
+        command,
+        status,
+        ...payload,
+      },
+    };
+    await client.post(resolveEndpoint('aee.store').path, { service: resolveEndpoint('aee.store').service, body: envelope, timeout: 3000 });
+  } catch {
+    // Fire-and-forget — never block CLI output
+  }
+}

package/lib/core/agentAlias.js

@@ -0,0 +1,163 @@
+/**
+ * Agent display-name alias resolution — DEVSUITE-GRIPE-P7 / quox#567 (CLI
+ * half only; server-side alias resolution stays open in #567).
+ *
+ * `quox agent attach vulcan` failed because the registry id is `forge` —
+ * "VULCAN" is only the agent's display name (identity.name in
+ * src/config/entities/assistants/forge.json), never sent to any API. This
+ * module resolves a non-matching agent id case-insensitively against the
+ * core assistants roster BEFORE the attach/detach/attach-status/
+ * attach-heartbeat/exec/grant-attach commands call the real API, so the
+ * canonical registry id is always what goes over the wire.
+ *
+ * Two sources, combined:
+ *   - the collector's no-auth-gate `/api/v1/tools/agents` route, which is
+ *     the live, authoritative list of agent ids this deployment currently
+ *     recognises (but carries NO display names — it's a tool-permission
+ *     map keyed by id);
+ *   - the bundled assistants roster (src/config/entities/assistants/*.json,
+ *     shipped inside this same repo checkout) for identity.name /
+ *     identity.shortName, the only source of display names.
+ * A live-roster failure (network down, route not deployed yet) degrades to
+ * the bundled roster's own id set rather than blocking alias resolution
+ * entirely.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// cli/lib/core/agentAlias.js -> cli/lib -> cli -> repo root -> src/config/...
+const DEFAULT_ASSISTANTS_DIR = path.resolve(__dirname, '../../../src/config/entities/assistants');
+
+/**
+ * Read the bundled assistants roster. Tolerant of a missing directory (a
+ * standalone CLI install without the dashboard source tree alongside it)
+ * and of individual malformed files — one bad entry must never break alias
+ * resolution for every other agent.
+ *
+ * @returns {Array<{id: string, name: string|null, shortName: string|null}>}
+ */
+export function loadBundledAssistantsRoster(dir = DEFAULT_ASSISTANTS_DIR) {
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+
+  const roster = [];
+  for (const file of files) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+      if (raw?.id) {
+        roster.push({
+          id: raw.id,
+          name: raw.identity?.name || null,
+          shortName: raw.identity?.shortName || null,
+        });
+      }
+    } catch {
+      // Skip an unreadable/malformed file rather than failing the whole load.
+    }
+  }
+  return roster;
+}
+
+/**
+ * Pure resolver, exported for unit tests: no filesystem or network access.
+ *
+ * @param {string} requestedId - what the user typed
+ * @param {Set<string>} validIds - agent ids this deployment currently recognises
+ * @param {Array<{id: string, name: string|null, shortName: string|null}>} roster
+ * @returns {{id: string, aliasLabel: string|null}} aliasLabel is the display
+ *   name to print (`alias: <aliasLabel> -> <id>`), or null when the input
+ *   was already a valid id (no alias happened).
+ */
+export function resolveAgentAliasPure(requestedId, validIds, roster) {
+  if (!requestedId || typeof requestedId !== 'string') {
+    throw new Error('Agent id is required.');
+  }
+
+  // Exact, case-sensitive match against a known id: pass through untouched.
+  // This is the common case and must never be affected by alias lookup.
+  if (validIds.has(requestedId)) {
+    return { id: requestedId, aliasLabel: null };
+  }
+
+  const lower = requestedId.toLowerCase();
+  for (const entry of roster) {
+    // Never alias to an id this deployment doesn't currently recognise.
+    if (!validIds.has(entry.id)) continue;
+    const name = entry.name?.toLowerCase();
+    const shortName = entry.shortName?.toLowerCase();
+    if (name === lower || shortName === lower) {
+      return { id: entry.id, aliasLabel: entry.name || entry.shortName || requestedId.toUpperCase() };
+    }
+  }
+
+  throw new Error(
+    `Unknown agent "${requestedId}": not a registry id, and no matching display name in the assistants roster. `
+    + 'Run `quox agent list` to see valid ids.'
+  );
+}
+
+/**
+ * Resolve a possibly-display-name agent id against the live collector
+ * roster plus the bundled assistants roster, printing exactly one
+ * `alias: <NAME> -> <id>` line on a hit. Callers must use the RETURNED
+ * canonical id for every subsequent call — the display name is never sent
+ * to the API.
+ *
+ * Printed unconditionally (never suppressed under -o json/quiet, unlike
+ * printInfo): a silent semantic remap of what agent id you are talking to
+ * is exactly the kind of thing a scripted/JSON caller most needs to see.
+ *
+ * @param {object} client - the CLI's HTTP client (ctx.client)
+ * @param {string} requestedId
+ * @param {{print?: (line: string) => void, rosterDir?: string}} [opts]
+ * @returns {Promise<string>} the canonical agent id
+ */
+export async function resolveAgentId(client, requestedId, opts = {}) {
+  const print = opts.print || ((line) => console.log(line));
+  const roster = loadBundledAssistantsRoster(opts.rosterDir);
+
+  // CORTEX-BENCH: an exact core id resolves to itself whatever the live list
+  // says (absent from it, it passes through as a custom id and the server
+  // decides), so skip the round trip that cost every exec 60ms-1.4s.
+  if (roster.some((r) => r.id === requestedId)) return requestedId;
+
+  let validIds = null;
+  try {
+    const ep = resolveEndpoint('v1.tools.agents.list');
+    const data = await client.get(ep.path, { service: ep.service, noAuth: true });
+    const ids = Object.keys(data?.agentTools || {});
+    if (ids.length > 0) validIds = new Set(ids);
+  } catch {
+    // Live lookup is an optimisation, not a hard requirement -- fall
+    // through to the bundled roster's own id set below.
+  }
+  if (!validIds) validIds = new Set(roster.map((r) => r.id));
+
+  let resolved;
+  try {
+    resolved = resolveAgentAliasPure(requestedId, validIds, roster);
+  } catch (err) {
+    // A non-empty id that matches neither a core-registry id nor a display
+    // name may be a user/org-created custom assistant (auth `assistants`
+    // table) — the core roster this resolver knows never lists those.
+    // QUOXIDENTITY custom-attach (CLI half): the client must not gate an id
+    // the server can now resolve. Pass it through and let the server be the
+    // authority — the attach-kit endpoint resolves a custom assistant
+    // org-scoped, or returns a clean 404 for a genuine typo. (An empty id
+    // still throws the original 'Agent id is required.' error.)
+    if (!requestedId || typeof requestedId !== 'string') throw err;
+    print(`note: "${requestedId}" is not a core registry agent, trying it as a custom/org assistant (server resolves or rejects).`);
+    return requestedId;
+  }
+  if (resolved.aliasLabel) print(`alias: ${resolved.aliasLabel} -> ${resolved.id}`);
+  return resolved.id;
+}

package/lib/core/approvalContext.js

@@ -0,0 +1,61 @@
+/**
+ * HITL-CONTEXT (owner 2026-10-07): render an approval item's
+ * payload.approval_context (built server-side by the collector at request
+ * time) for `quox inbox list` / `quox inbox show`. Pure, so it is testable.
+ */
+
+function clip(text, n) {
+  const s = String(text == null ? '' : text).replace(/\s+/g, ' ').trim();
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
+export function getApprovalContext(item) {
+  const c = item && item.payload && item.payload.approval_context;
+  return c && typeof c === 'object' ? c : null;
+}
+
+/** Ordered [label, value] pairs: Source, On behalf of, Reason, Method, Command, Why approval, Risk, Expires. */
+export function approvalContextFields(c) {
+  if (!c) return [];
+  const rows = [];
+  const rb = c.requested_by || {};
+  let source = c.source_label || rb.agent_label || 'unknown';
+  if (rb.profile) source += ` · profile ${rb.profile}`;
+  rows.push(['Source', source]);
+  if (c.on_behalf_of) {
+    const ob = c.on_behalf_of;
+    let v = ob.user_name || ob.user_id || 'unknown user';
+    if (ob.request_excerpt) v += `, asked: "${ob.request_excerpt}"`;
+    if (ob.conversation_id) v += ` (conversation ${ob.conversation_id})`;
+    rows.push(['On behalf of', v]);
+  }
+  const r = c.reason || {};
+  rows.push(['Reason', r.text ? `${r.text}${r.source === 'inferred' ? ' (inferred, not stated by the caller)' : ''}` : 'none given']);
+  const m = c.method || {};
+  rows.push(['Method', `${m.tool || '?'} via ${m.transport || '?'}${m.target ? ` on ${m.target}` : ''}`]);
+  if (m.command) rows.push(['Command', m.command]);
+  else if (m.args) rows.push(['Args', m.args]);
+  if (c.why_approval && c.why_approval.label) rows.push(['Why approval', c.why_approval.label]);
+  if (c.risk) rows.push(['Risk', c.risk]);
+  if (c.expires_at) rows.push(['Expires', c.expires_at]);
+  return rows;
+}
+
+/** Plain-text block for `quox inbox show`. */
+export function formatApprovalContext(c) {
+  const rows = approvalContextFields(c);
+  if (rows.length === 0) return '';
+  const w = Math.max(...rows.map(([k]) => k.length));
+  return ['Approval context', ...rows.map(([k, v]) => `  ${k.padEnd(w)}  ${v}`)].join('\n');
+}
+
+/** Short columns for `quox inbox list`. */
+export function approvalListColumns(item) {
+  const c = getApprovalContext(item);
+  if (!c) return { source: '', reason: '' };
+  const r = c.reason || {};
+  return {
+    source: clip(c.source_label || '', 40),
+    reason: r.text ? clip(`${r.text}${r.source === 'inferred' ? ' (inferred)' : ''}`, 60) : '',
+  };
+}

package/lib/core/aside.js

@@ -0,0 +1,54 @@
+/**
+ * ASIDE: a read-only side question. `quox aside "<question>"` and the TUI /aside share this.
+ *
+ * It goes to the collector's no-tools invoke (POST /api/internal/agents/invoke with no_tools: true): the model
+ * gets no tools at all, and no conversation or session id is sent, so the main conversation's history is never
+ * touched. The TUI passes the last few exchanges as plain read-only context so "what did it just say about X?"
+ * works; nothing is written back.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export const ASIDE_MAX_CONTEXT = 6000;
+
+const ASIDE_NOTE = 'This is a read-only side question. You have no tools: answer from what you know and from the conversation excerpt below. Do not offer to run anything. Be brief.';
+
+/** Recent [{ role: 'user'|'assistant', text }] -> one plain excerpt, newest kept when it is too long. */
+export function asideExcerpt(turns, max = ASIDE_MAX_CONTEXT) {
+  const lines = (Array.isArray(turns) ? turns : [])
+    .filter(t => t && typeof t.text === 'string' && t.text.trim())
+    .map(t => `${t.role === 'assistant' ? 'Quox' : 'User'}: ${t.text.trim()}`);
+  let out = '';
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const next = out ? `${lines[i]}\n\n${out}` : lines[i];
+    if (next.length > max) { if (!out) out = lines[i].slice(-max); break; }
+    out = next;
+  }
+  return out;
+}
+
+/** The request body: never a session or conversation id, always no_tools. */
+export function asideBody({ question, turns = [], agent = 'quox', maxTokens = 1024 }) {
+  const q = String(question ?? '').trim();
+  const excerpt = asideExcerpt(turns);
+  return {
+    agent_id: agent || 'quox',
+    task: q,
+    no_tools: true,
+    max_tokens: maxTokens,
+    context: excerpt ? `${ASIDE_NOTE}\n\nConversation so far (read only):\n${excerpt}` : ASIDE_NOTE,
+  };
+}
+
+/**
+ * -> { text, model, provider, tools } . Throws the client error (with .status) on a non-2xx, and an error
+ * with code 'aside_used_tools' if the server reports any tool use (it must not happen; we say so if it does).
+ */
+export async function askAside(client, { question, turns, agent, timeoutMs = 120000 }) {
+  if (!String(question ?? '').trim()) { const e = new Error('Ask a question: aside <question>'); e.code = 'usage'; throw e; }
+  const ep = resolveEndpoint('agents.invoke.notools');
+  const r = await client.post(ep.path, { service: ep.service, body: asideBody({ question, turns, agent }), retries: 0, timeout: timeoutMs });
+  if (r && r.success === false) { const e = new Error(r.error || 'the server could not answer'); e.status = 502; throw e; }
+  const tools = Array.isArray(r?.tools_used) ? r.tools_used : [];
+  if (tools.length) { const e = new Error(`the server reported tool use (${tools.join(', ')}) on a no-tools aside`); e.code = 'aside_used_tools'; throw e; }
+  return { text: String(r?.result ?? '').trim(), model: r?.usage?.model || null, provider: r?.provider || r?.usage?.provider || null, tools };
+}

package/lib/core/askDecision.js

@@ -0,0 +1,60 @@
+/**
+ * quox ask helpers: parse the option list and durations, and wait (bounded long-poll) for a human's answer.
+ * Pure of the CLI framework so the exit codes are unit-testable. Exit codes: 0 answered, 2 expired or denied.
+ */
+
+export const EXIT_ANSWERED = 0;
+export const EXIT_NO_ANSWER = 2;
+
+/** "a: Ship now|b: Wait|c: Drop" -> [{key,label}]. A bare "a|b" gives key=label. Throws with a usable message. */
+export function parseOptions(text) {
+  const parts = String(text || '').split('|').map((s) => s.trim()).filter(Boolean);
+  if (parts.length < 2) throw new Error('--options needs at least two, e.g. "a: Ship now|b: Wait for review|c: Drop it" (or use --yn)');
+  return parts.map((p) => {
+    const m = /^([A-Za-z0-9]{1,8})\s*[:=]\s*(.*)$/.exec(p);
+    if (m) return { key: m[1].toLowerCase(), label: m[2].trim() || m[1] };
+    if (/^[A-Za-z0-9]{1,8}$/.test(p)) return { key: p.toLowerCase(), label: p };
+    throw new Error(`could not read option "${p}": write it as key: label, e.g. "a: Ship now"`);
+  });
+}
+
+export const YN_OPTIONS = [{ key: 'y', label: 'Yes' }, { key: 'n', label: 'No' }];
+
+/** "90s" | "10m" | "2h" | "1d" | bare seconds -> seconds. */
+export function parseDuration(text) {
+  const m = /^(\d+(?:\.\d+)?)\s*([smhd]?)$/i.exec(String(text || '').trim());
+  if (!m) throw new Error(`could not read duration "${text}": use 90s, 10m, 2h or 1d`);
+  const mult = { '': 1, s: 1, m: 60, h: 3600, d: 86400 }[m[2].toLowerCase()];
+  return Math.round(Number(m[1]) * mult);
+}
+
+const fmtLeft = (ms) => { const m = Math.max(0, Math.round(ms / 60000)); return m >= 120 ? `${Math.round(m / 60)}h` : m >= 1 ? `${m}m` : '<1m'; };
+
+/**
+ * Long-poll a decision until it is no longer pending.
+ * @param {{poll:(waitSeconds:number)=>Promise<object>, log:(s:string)=>void, sleep?:Function, now?:()=>number, maxWaitMs?:number|null, pollSeconds?:number}} o
+ * @returns {Promise<{code:number, stdout:string, decision:object|null}>} stdout = chosen option key (+ note line) only when answered.
+ */
+export async function waitForDecision({ poll, log, now = Date.now, maxWaitMs = null, pollSeconds = 25 }) {
+  const start = now();
+  let errors = 0;
+  for (;;) {
+    let d;
+    try { d = (await poll(pollSeconds)).decision; errors = 0; }
+    catch (e) {
+      if (e?.status === 404 || e?.status === 403 || e?.status === 401) throw e; // not a blip: a decision we cannot see
+      if (++errors >= 5) throw e;
+      log(`could not reach the server (${e?.message || 'failed'}), retrying (${errors}/5)`);
+      await new Promise((r) => setTimeout(r, 2000));
+      continue;
+    }
+    if (!d) throw new Error('the server returned no decision');
+    if (d.state === 'answered') return { code: EXIT_ANSWERED, stdout: `${d.answer?.option ?? ''}${d.answer?.note ? `\n${d.answer.note}` : ''}`, decision: d };
+    if (d.state === 'denied') { log(`denied${d.answer?.note ? `: ${d.answer.note}` : ''}`); return { code: EXIT_NO_ANSWER, stdout: '', decision: d }; }
+    if (d.state === 'expired' || d.state === 'cancelled') { log(`${d.state}, no answer${d.default ? ` (default was ${d.default}; not applied)` : ''}`); return { code: EXIT_NO_ANSWER, stdout: '', decision: d }; }
+    const elapsed = now() - start;
+    const left = d.expires_at ? Date.parse(d.expires_at) - now() : null;
+    log(`still waiting for a human (${d.session || 'session'}, ${fmtLeft(elapsed)} elapsed${left != null ? `, ${fmtLeft(left)} left` : ''})`);
+    if (maxWaitMs != null && elapsed >= maxWaitMs) { log('gave up waiting (--timeout); the question is still open: quox ask wait ' + d.id); return { code: EXIT_NO_ANSWER, stdout: '', decision: d }; }
+  }
+}