quoxcli 0.2.0 → 0.4.0

package/lib/core/actionItems.js

@@ -0,0 +1,115 @@
+/**
+ * Action Tracker item writes and open-item reads, shared by `quox actions
+ * add|done` and the Quox TUI /todo and /todos. One core, so chat, CLI and TUI
+ * create the same item through the same collector route
+ * (POST /api/v1/actions, PATCH /api/v1/actions/:id), as the logged-in user.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxError } from './errors.js';
+
+export const PRIORITIES = ['low', 'medium', 'high', 'urgent'];
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+
+const pad = (n) => String(n).padStart(2, '0');
+const dayOf = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+
+/** "today", "tomorrow" or YYYY-MM-DD -> YYYY-MM-DD. Anything else is a usage error, never guessed. */
+export function parseDue(value, now = new Date()) {
+  if (value === undefined || value === null || value === '') return null;
+  const v = String(value).trim().toLowerCase();
+  if (v === 'today') return dayOf(now);
+  if (v === 'tomorrow') return dayOf(new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1));
+  if (ISO_DAY.test(v) && !Number.isNaN(Date.parse(`${v}T00:00:00Z`))) return v;
+  throw new QuoxError(`--due must be YYYY-MM-DD, today or tomorrow (got "${value}")`, 2);
+}
+
+/** Words typed after the verb -> a title. Empty or blank is a usage error. */
+export function titleFromWords(words) {
+  const title = (Array.isArray(words) ? words.join(' ') : String(words || '')).trim();
+  if (!title) throw new QuoxError('Usage: quox actions add <text...> [--due <date>] [--priority low|medium|high|urgent]', 2);
+  return title;
+}
+
+/** Throw unless the response carries an item with an id: an error body is never a created item. */
+function itemOf(res, what) {
+  const item = res && res.item;
+  if (!item || !item.id || res.success === false) {
+    throw new QuoxError(`${what} failed: ${(res && (res.error || res.message)) || 'the server returned no item'}`);
+  }
+  return item;
+}
+
+/** Create one Action Tracker item (status todo) as the logged-in user. -> the item. */
+export async function addActionItem(client, { title, due, priority, description } = {}) {
+  const t = titleFromWords(title);
+  if (priority && !PRIORITIES.includes(priority)) {
+    throw new QuoxError(`--priority must be one of ${PRIORITIES.join(', ')}`, 2);
+  }
+  const body = { title: t };
+  const dueDate = parseDue(due);
+  if (dueDate) body.due_date = dueDate;
+  if (priority) body.priority = priority;
+  if (description) body.description = description;
+  const ep = resolveEndpoint('actions.create');
+  return itemOf(await client.post(ep.path, { service: ep.service, body }), 'Adding the action item');
+}
+
+export const STATUS_COLUMNS = ['todo', 'doing', 'done'];
+
+/** Move one item to todo, doing or done. -> the item. */
+export async function moveActionItem(client, id, status) {
+  const clean = String(id || '').trim();
+  if (!clean) throw new QuoxError('Usage: quox actions move <id> <todo|doing|done>', 2);
+  if (!STATUS_COLUMNS.includes(status)) throw new QuoxError(`status must be one of ${STATUS_COLUMNS.join(', ')}`, 2);
+  const ep = resolveEndpoint('actions.update', { id: clean });
+  return itemOf(await client.patch(ep.path, { service: ep.service, body: { status } }), 'Moving the action item');
+}
+
+/** Mark one item done. -> the item. */
+export async function completeActionItem(client, id) {
+  if (!String(id || '').trim()) throw new QuoxError('Usage: quox actions done <id>', 2);
+  return moveActionItem(client, id, 'done');
+}
+
+/** Every item in one column (or all), paged to the end; never a silent cap. -> [{id,title,status,priority,due_date}]. */
+export async function listActionItems(client, status = 'all', { pageSize = 100, maxPages = 50 } = {}) {
+  const ep = resolveEndpoint('actions.list');
+  const out = [];
+  for (let page = 1; page <= maxPages; page++) {
+    const query = { limit: pageSize, page };
+    if (status !== 'all') query.status = status;
+    const res = await client.get(ep.path, { service: ep.service, query, retries: 0 });
+    if (!res || !Array.isArray(res.items)) {
+      throw new QuoxError(`Listing action items failed: ${(res && (res.error || res.message)) || 'unexpected response'}`);
+    }
+    out.push(...res.items);
+    if (!(res.pagination && res.pagination.has_more)) return out;
+  }
+  throw new QuoxError(`More than ${maxPages * pageSize} action items; narrow with quox actions list --status.`);
+}
+
+/** The board by column. -> { backlog (status todo), doing, done } each a full list. */
+export async function listBoard(client) {
+  const backlog = await listActionItems(client, 'todo');
+  const doing = await listActionItems(client, 'doing');
+  const done = await listActionItems(client, 'done');
+  return { backlog, doing, done };
+}
+
+/** Open items (todo then doing), all of them. */
+export async function listOpenActionItems(client) {
+  return [...(await listActionItems(client, 'todo')), ...(await listActionItems(client, 'doing'))];
+}
+
+/** Delete one item (server soft-deletes; creator or admin only). Checks the status before trusting the body. -> { id, title }. */
+export async function deleteActionItem(client, id) {
+  const clean = String(id || '').trim();
+  if (!clean) throw new QuoxError('Usage: quox actions delete <id> --yes', 2);
+  const ep = resolveEndpoint('actions.delete', { id: clean });
+  const res = await client.delete(ep.path, { service: ep.service });
+  if (!res || res.success === false || res.deleted !== true) {
+    throw new QuoxError(`Deleting the action item failed: ${(res && (res.error || res.message)) || 'the server did not confirm the delete'}`);
+  }
+  return { id: clean, title: res.title || '' };
+}

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/agentAlias.js

@@ -58,6 +58,8 @@ export function loadBundledAssistantsRoster(dir = DEFAULT_ASSISTANTS_DIR) {
           id: raw.id,
           name: raw.identity?.name || null,
           shortName: raw.identity?.shortName || null,
+          // AGENT-TAXONOMY: present only when the file declares one.
+          ...(raw.family ? { family: raw.family } : {}),
         });
       }
     } catch {

package/lib/core/agentFamilies.js

@@ -0,0 +1,7 @@
+// Agent family ids, mirrored from src/config/agentFamilies.js (the authority).
+// The published CLI does not ship src/config, so it keeps this copy;
+// cli/test/core/agentFamilies.test.js fails if the two drift.
+export const AGENT_FAMILY_IDS = [
+  'command', 'devops', 'monitoring', 'secops', 'development',
+  'assistantq', 'knowledge', 'marketing', 'voice', 'governance',
+];

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