quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/resend.js

@@ -0,0 +1,72 @@
+/**
+ * QUOXON-FW3: a message typed while the server is restarting is kept, not dropped (pure helpers).
+ * A send is only retried when the connection failed BEFORE any event arrived (so no turn started and
+ * nothing can run twice); the caller enforces that.
+ */
+export const SERVER_RESTARTING = "Quox server is restarting. I'll send this when it is back. Esc cancels.";
+export const MAX_WAIT_MS = 180000;
+
+/** True for "could not reach the server at all" (refused / fetch failed), never for an HTTP answer. */
+export function isServerDown(e) {
+  if (!e || e.status) return false;
+  const code = e.cause?.code || e.code || '';
+  const msg = String(e.message || '');
+  return /ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|UND_ERR_SOCKET/.test(String(code)) || /Could not connect to|fetch failed|ECONNREFUSED/i.test(msg);
+}
+
+/** gh #1157: resume during a collector restart. Connection-class failures (refused, fetch failed, hang up, 502/503/504) are worth retrying; 401/404 are answers. */
+export function isResumeRetryable(e) {
+  if (!e) return false;
+  if (e.status) return [502, 503, 504].includes(Number(e.status));
+  return isServerDown(e) || /socket hang up|ECONNRESET|other side closed|terminated/i.test(String(e.message || ''));
+}
+/** 2, 4, 8, 15, 30 s, then 30 s steps: about 2 minutes in all before giving up. */
+export const RESUME_RETRY_DELAYS = [2000, 4000, 8000, 15000, 30000, 30000, 30000];
+export const RESUME_RECONNECTING = 'Quox server restarting, reconnecting to your conversation…';
+
+/** 1s, 2s, 4s, 8s, then 10s (capped). */
+export const backoffMs = (i) => Math.min(10000, 1000 * 2 ** i);
+
+const sleepFor = (ms, signal) => new Promise((r) => {
+  if (signal?.aborted) return r();
+  const t = setTimeout(done, ms);
+  function done() { clearTimeout(t); signal?.removeEventListener?.('abort', done); r(); }
+  signal?.addEventListener?.('abort', done, { once: true });
+});
+
+/**
+ * Poll health with backoff until it answers 2xx. -> 'up' | 'cancelled' | 'timeout'.
+ * delays: optional array (tests); else backoffMs. Total waiting is bounded by maxMs of scheduled sleep.
+ */
+export async function waitForServer({ health, signal, delays = null, maxMs = MAX_WAIT_MS }) {
+  let waited = 0;
+  for (let i = 0; ; i++) {
+    if (signal?.aborted) return 'cancelled';
+    const d = delays ? delays[Math.min(i, delays.length - 1)] : backoffMs(i);
+    if (waited >= maxMs || (delays && i >= delays.length * 4)) return 'timeout';
+    await sleepFor(d, signal);
+    waited += d;
+    if (signal?.aborted) return 'cancelled';
+    let r = null;
+    try { r = await health(3000); } catch { r = null; }
+    if (r?.ok) return 'up';
+  }
+}
+
+/**
+ * QUOXON-FW4: a stream that died mid-turn ("terminated" is undici's wording) gets a cause and a way
+ * forward instead of a bare word. Returns null when the error is not a transport/timeout failure.
+ */
+export function explainTermination(e) {
+  if (!e || e.status) return null;
+  const msg = String(e.message || '');
+  const code = String(e.cause?.code || e.code || '');
+  if (e.name === 'TimeoutError' || /timed? ?out|ETIMEDOUT|UND_ERR_(HEADERS|BODY)_TIMEOUT/i.test(`${msg} ${code}`)) return `The turn timed out before the server finished.`;
+  if (/^terminated$/i.test(msg.trim()) || /ECONNRESET|UND_ERR_SOCKET|other side closed|premature close|aborted/i.test(`${msg} ${code}`)) {
+    return `The connection to the server was cut mid-turn (likely a server restart, proxy timeout or provider error).`;
+  }
+  return null;
+}
+
+/** The second line after a cut turn: the message is kept, and what to do next. */
+export const RETRY_HINT = 'Your message is kept: press Up to recall it, then Enter to resend. Anything it started may or may not have finished; check before repeating it.';

package/lib/quoxon/roster.js

@@ -0,0 +1,307 @@
+/**
+ * QUOXON roster: what is actually running on this instance for this org. Pure
+ * functions only (normalise server rows, build the view); fetching lives in api.js.
+ * Rows come from real list endpoints; a source that cannot answer contributes
+ * nothing (never a placeholder row).
+ */
+import { clip } from './theme.js';
+
+export const GLYPH = { running: '◐', waiting: '⏸', done: '✔', failed: '✖' };
+/** A row that ended without finishing says HOW: failed is the only error; the rest are neutral (no error colour). */
+export const OUTCOME_GLYPH = { failed: '✖', cancelled: '○', expired: '○', rejected: '⊘' };
+export const FRESH_MS = 10 * 60 * 1000;      // finished rows linger this long
+export const USER_DONE_MS = 20 * 1000;       // a user-started completion vanishes quickly: rows come and go
+export const PENDING_FRESH_MS = 24 * 3600 * 1000; // an older "pending" is stale, not waiting
+export const MAX_ROWS = 4;
+export const MIN_FULL_COLS = 60;
+export const MIN_FULL_ROWS = 24;
+
+/** Server timestamps: epoch ms, ISO, or SQLite "YYYY-MM-DD HH:MM:SS" (UTC, no zone). */
+export function parseTime(v) {
+  if (v == null || v === '') return null;
+  if (typeof v === 'number') return v;
+  const s = String(v);
+  const t = Date.parse(/^\d{4}-\d\d-\d\d \d\d:\d\d(:\d\d)?$/.test(s) ? s.replace(' ', 'T') + 'Z' : s);
+  return Number.isFinite(t) ? t : null;
+}
+
+export function elapsed(ms) {
+  if (ms == null || !Number.isFinite(ms)) return '';
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h${String(m % 60).padStart(2, '0')}`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+const ACTIVE_RE = /^(running|planning|decompos|executing|in_progress|active)/;
+const WAITING_RE = /^(paused|awaiting|blocked|plan_review|pending_approval|waiting)/;
+const FAILED = new Set(['failed', 'error', 'halted', 'cancelled', 'canceled', 'timed_out', 'timeout', 'expired', 'rejected']);
+/** The word for how an ended row ended (state stays 'failed' for the ended-badly group; this says which). */
+export function outcomeOf(status) {
+  const st = String(status || '').toLowerCase();
+  if (st === 'cancelled' || st === 'canceled') return 'cancelled';
+  if (st === 'expired') return 'expired';
+  if (st === 'rejected') return 'rejected';
+  return 'failed';
+}
+/** Word, glyph and whether it is an error, for a row. Non-failed states return their own state. */
+export function endWord(r) { return r.state === 'failed' ? outcomeOf(r.status) : r.state; }
+export const glyphOf = (r) => (r.state === 'failed' ? OUTCOME_GLYPH[endWord(r)] : GLYPH[r.state]);
+
+/** How long a finished row lingers before it leaves the roster (null while running/waiting). */
+const expiryFor = (state, doneMs) => state === 'done' ? doneMs : state === 'failed' ? FRESH_MS : null;
+
+/** -> state or null (not shown). */
+function stateOf(status, { startedAt, createdAt, finishedAt, now, doneMs = FRESH_MS }) {
+  const st = String(status || '').toLowerCase();
+  if (ACTIVE_RE.test(st)) return 'running';
+  if (WAITING_RE.test(st)) return 'waiting';
+  if (st === 'pending' || st === 'queued') {
+    const t = createdAt ?? startedAt;
+    return t != null && now - t < PENDING_FRESH_MS ? 'waiting' : null;
+  }
+  if (st === 'completed' || st === 'complete' || st === 'succeeded' || FAILED.has(st)) {
+    if (finishedAt == null) return null;
+    const ok = st === 'completed' || st === 'complete' || st === 'succeeded';
+    if (now - finishedAt > (ok ? doneMs : FRESH_MS)) return null;
+    return ok ? 'done' : 'failed';
+  }
+  return null;
+}
+
+const latest = (...ts) => { const v = ts.filter((t) => t != null); return v.length ? Math.max(...v) : null; };
+
+export function fromObjective(o, now = Date.now()) {
+  const startedAt = parseTime(o.started_at);
+  const createdAt = parseTime(o.created_at);
+  const finishedAt = parseTime(o.completed_at);
+  // Objectives and loops are always user-started work.
+  const state = stateOf(o.status, { startedAt, createdAt, finishedAt, now, doneMs: USER_DONE_MS });
+  if (!state) return null;
+  const loop = o.execution_mode === 'loop';
+  let activity = '';
+  if (state === 'failed' && o.error_message) activity = String(o.error_message);
+  else if (loop && o.max_iterations) activity = `iter ${o.iteration_count || 0}/${o.max_iterations}`;
+  else if (o.task_count) activity = `${o.tasks_completed || 0}/${o.task_count} tasks`;
+  else if (state === 'waiting') activity = 'waiting to start';
+  const from = startedAt ?? createdAt;
+  return {
+    key: `objective:${o.id}`, id: o.id, source: 'objectives', background: false, kind: loop ? 'loop' : 'objective', state,
+    name: o.title || o.id, activity, status: o.status,
+    startedAt: from, finishedAt, ageMs: from != null ? (state === 'done' || state === 'failed' ? (finishedAt ?? now) - from : now - from) : null,
+    expiryMs: expiryFor(state, USER_DONE_MS),
+    progressAt: latest(parseTime(o.updated_at), parseTime(o.last_progress_at), parseTime(o.last_heartbeat_at)),
+    detail: { description: o.description, error: o.error_message, tokens: o.tokens_used, toolCalls: o.tool_calls_used }
+  };
+}
+
+const USER_TRIGGERS = new Set(['manual', 'chat', 'cli', 'user']);
+const BACKGROUND_BY = /^(schedule|cron|interval|webhook|event|system)\b/i;
+/**
+ * Is this workflow execution background work (hidden from the roster by default)?
+ * Fields relied on (live /api/executions rows, checked 2026-10-12): `triggerData.trigger`
+ * ('schedule' on every live row) and `triggeredBy` ('schedule:trigger', 'event:<node>',
+ * 'webhook:<node>' set by quoxflow's trigger-bootstrap). Rule: a background-looking triggeredBy
+ * always wins; otherwise user-started only if the trigger is manual/chat/cli/user OR triggeredBy
+ * equals the signed-in user's id. Unknown trigger with no such evidence is background.
+ */
+export function isBackgroundExecution(e, userId = null) {
+  const by = e?.triggeredBy == null ? '' : String(e.triggeredBy);
+  if (BACKGROUND_BY.test(by)) return true;
+  // quoxflow records a person-started run as user:<id> (RunActor); a bare id is an older row
+  if (userId && by && (by === String(userId) || by === `user:${userId}`)) return false;
+  return !USER_TRIGGERS.has(String(e?.triggerData?.trigger || '').toLowerCase());
+}
+
+export function fromExecution(e, now = Date.now(), { userId = null } = {}) {
+  const startedAt = parseTime(e.startedAt);
+  const finishedAt = parseTime(e.completedAt);
+  const background = isBackgroundExecution(e, userId);
+  const state = stateOf(e.status, { startedAt, createdAt: startedAt, finishedAt, now, doneMs: background ? FRESH_MS : USER_DONE_MS });
+  if (!state) return null;
+  let activity = '';
+  if (state === 'failed' && e.error) activity = typeof e.error === 'string' ? e.error : (e.error.message || JSON.stringify(e.error));
+  else if (e.nodeCount) activity = `${e.nodeCount} node${e.nodeCount === 1 ? '' : 's'}`;
+  else if (e.triggerData?.trigger) activity = `via ${e.triggerData.trigger}`;
+  return {
+    key: `execution:${e.id}`, id: e.id, source: 'executions', kind: 'workflow', background, state,
+    name: e.workflowName || e.workflowId || e.id, activity, status: e.status,
+    startedAt, finishedAt, ageMs: startedAt != null ? (state === 'done' || state === 'failed' ? (finishedAt ?? now) - startedAt : now - startedAt) : null,
+    expiryMs: expiryFor(state, background ? FRESH_MS : USER_DONE_MS),
+    progressAt: latest(parseTime(e.updatedAt), parseTime(e.lastHeartbeatAt)),
+    detail: { workflowId: e.workflowId, correlationId: e.correlationId, trigger: e.triggerData?.trigger, error: e.error }
+  };
+}
+
+/** A pending approval (inbox item) for this user/org -> amber waiting row, always shown. */
+export function fromApproval(it, now = Date.now()) {
+  if (!it || !it.id) return null;
+  const m = it.payload?.approval_context?.method || {};
+  const name = m.tool ? (m.target ? `${m.tool} on ${m.target}` : m.tool) : String(it.title || it.summary || it.id);
+  const createdAt = parseTime(it.created_at ?? it.createdAt);
+  return { key: `approval:${it.id}`, id: it.id, source: 'approvals', kind: 'approval', state: 'waiting', background: false, name, activity: '/approvals', status: 'pending',
+    startedAt: createdAt, finishedAt: null, ageMs: createdAt != null ? now - createdAt : null, detail: { description: it.title } };
+}
+
+/** Heartbeat style system work: nobody wants a row or a notification for it, working or failing. */
+export const NOISE_NAME = /heartbeat|health[ _-]?check|keep[ _-]?alive|\bping\b/i;
+export const isNoise = (r) => Boolean(r.background) && NOISE_NAME.test(String(r.name || ''));
+
+/** Rows the user should see: background rows only with `all` (/roster all). */
+export function selectRows(rows, { all = false } = {}) {
+  return all ? rows : rows.filter(r => !r.background && !isNoise(r));
+}
+
+/** One line per workflow that is failing in the background (deduped); these feed the notifications bar. */
+export function backgroundAlerts(rows) {
+  const by = new Map();
+  for (const r of rows) if (r.background && !isNoise(r) && r.state === 'failed') by.set(r.name, (by.get(r.name) || 0) + 1);
+  return [...by].map(([name, n]) => `✖ ${name} failing (${n} in ${FRESH_MS / 60000}m) · /roster all`);
+}
+
+/** When the row last changed state: it started, or it finished (done/failed). */
+export const changedAt = (r) => (r.state === 'done' || r.state === 'failed' ? r.finishedAt : null) ?? r.startedAt ?? 0;
+
+/** Approvals pinned on top (oldest first, they need action); everything else most recent change first. */
+export function sortRows(rows) {
+  const ap = (r) => (r.kind === 'approval' ? 0 : 1);
+  return [...rows].sort((a, b) => ap(a) - ap(b) || (ap(a) === 0 ? (a.startedAt ?? 0) - (b.startedAt ?? 0) : changedAt(b) - changedAt(a)));
+}
+
+export const isExpired = (r, now = Date.now()) => r.expiryMs != null && r.finishedAt != null && now - r.finishedAt > r.expiryMs;
+
+/** Tone steps, brightest first (theme colour names). Position among non-approval rows, and for finished rows age toward expiry. */
+export const TONES = ['text', 'placeholder', 'dim', 'faint'];
+export function toneName(r, pos, now = Date.now()) {
+  if (r.kind === 'approval') return TONES[0];
+  let step = Math.min(Math.max(0, pos), TONES.length - 1);
+  if (r.expiryMs && r.finishedAt != null) {
+    const frac = Math.max(0, now - r.finishedAt) / r.expiryMs;
+    step = Math.max(step, frac < 0.25 ? 0 : frac < 0.5 ? 1 : frac < 0.75 ? 2 : 3);
+  }
+  return TONES[step];
+}
+
+/** Live age text: a clock for running/waiting rows, recency ("done 3s ago") for finished ones. */
+export function ageText(r, now = Date.now()) {
+  if (r.state === 'done' || r.state === 'failed') return r.finishedAt != null ? `${endWord(r)} ${elapsed(now - r.finishedAt)} ago` : '';
+  return r.startedAt != null ? elapsed(now - r.startedAt) : '';
+}
+
+/* ---- pulse: is it moving? ---------------------------------------------------------------- */
+
+export const PULSE_MOVING_MS = 2 * 60 * 1000;   // progress this recently = moving
+export const PULSE_STALL_MS = 15 * 60 * 1000;   // running with no progress this long = stalled
+export const SPIN = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export const SPIN_MS = 120;
+
+const sigOf = (r) => `${r.state}|${r.status}|${r.activity}`;
+
+/**
+ * Remember what each row looked like at the last poll so "state changed / iteration advanced" is noticed.
+ * Sets r.progressAt (newest of the API's own timestamp and the change we saw; null = nothing seen yet) and
+ * r.watchSince (when we first saw the row). Mutates rows and memo (key -> { sig, watchSince, changedAt }).
+ */
+export function applyProgress(rows, memo, now = Date.now()) {
+  const keep = new Set();
+  for (const r of rows) {
+    keep.add(r.key);
+    const sig = sigOf(r);
+    let m = memo.get(r.key);
+    if (!m) { m = { sig, watchSince: now, changedAt: null }; memo.set(r.key, m); }
+    else if (m.sig !== sig) { m.sig = sig; m.changedAt = now; }
+    r.progressAt = latest(r.progressAt, m.changedAt);
+    r.watchSince = m.watchSince;
+  }
+  for (const k of [...memo.keys()]) if (!keep.has(k)) memo.delete(k);
+  return rows;
+}
+
+/** -> { kind: 'moving' | 'idle' | 'stalled' | 'none', glyph, role }. motion=false gives static glyphs. */
+export function pulseOf(r, now = Date.now(), { motion = false } = {}) {
+  if (r.kind === 'approval' || r.state === 'done' || r.state === 'failed') return { kind: 'none', glyph: ' ', role: 'dim' };
+  if (r.state !== 'running') return { kind: 'idle', glyph: '·', role: 'dim' };
+  const last = latest(r.progressAt, r.startedAt != null && now - r.startedAt < PULSE_MOVING_MS ? r.startedAt : null);
+  if (last != null && now - last < PULSE_MOVING_MS) return { kind: 'moving', glyph: motion ? SPIN[Math.floor(now / SPIN_MS) % SPIN.length] : '●', role: 'sky' };
+  const ref = last ?? r.watchSince;
+  if (ref != null && now - ref > PULSE_STALL_MS) return { kind: 'stalled', glyph: '!', role: 'warn' };
+  return { kind: 'idle', glyph: '·', role: 'dim' };
+}
+
+export function countsLine(rows) {
+  const n = (s) => rows.filter(r => r.state === s).length;
+  const o = (w) => rows.filter(r => r.state === 'failed' && endWord(r) === w).length;
+  return [['running', 'running', n('running'), GLYPH.running], ['waiting', 'waiting', n('waiting'), GLYPH.waiting],
+    ['failed', 'failed', o('failed'), OUTCOME_GLYPH.failed], ['cancelled', 'cancelled', o('cancelled'), OUTCOME_GLYPH.cancelled],
+    ['expired', 'expired', o('expired'), OUTCOME_GLYPH.expired], ['rejected', 'rejected', o('rejected'), OUTCOME_GLYPH.rejected], ['done', 'finished', n('done'), GLYPH.done]]
+    .filter(([, , k]) => k).map(([, w, k, g]) => `${g} ${k} ${w}`).join(' · ');
+}
+
+/**
+ * View model. mode: 'hidden' (off or nothing running) | 'summary' (narrow or short terminal) | 'full'.
+ * lines: [{ state, text, selected }] where text is already clipped to cols.
+ */
+/**
+ * Two or more waiting approvals are ONE row ("⏸ 4 approvals waiting · oldest 41m · newest: <title>… · /approvals"), not
+ * one row each plus a summary line (owner, live 05:29): the bottom area must never grow with the inbox. A single approval
+ * keeps its own row. Focus (the user is walking the roster) shows the real rows so selection stays truthful.
+ */
+export function collapseApprovals(rows, now = Date.now()) {
+  const aps = rows.filter(r => r.kind === 'approval' && r.state === 'waiting');
+  if (aps.length < 2) return rows;
+  const started = aps.map(r => r.startedAt).filter(x => x != null);
+  const newest = aps.reduce((a, b) => ((b.startedAt ?? -Infinity) > (a.startedAt ?? -Infinity) ? b : a));
+  const one = { key: 'approval:*', id: '*', source: 'approvals', kind: 'approval', state: 'waiting', background: false, collapsed: true, count: aps.length,
+    name: `${aps.length} approvals waiting`, activity: '/approvals', status: 'pending', startedAt: started.length ? Math.min(...started) : null, finishedAt: null,
+    oldestMs: started.length ? now - Math.min(...started) : null, newestTitle: String(newest.detail?.description || newest.name || ''), detail: {} };
+  let placed = false;
+  return rows.flatMap(r => (aps.includes(r) ? (placed ? [] : (placed = true, [one])) : [r]));
+}
+
+export function rosterView({ rows, cols, termRows = 40, max = MAX_ROWS, on = true, sel = 0, focus = false, now = Date.now(), motion = false }) {
+  if (!on || !rows.length) return { mode: 'hidden', lines: [], more: 0 };
+  if (!focus) rows = collapseApprovals(rows, now);
+  if (cols < MIN_FULL_COLS || termRows < MIN_FULL_ROWS) {
+    return { mode: 'summary', lines: [], more: 0, summary: clip(' ' + countsLine(rows) + ' · /roster', cols - 1) };
+  }
+  const shown = rows.slice(0, max);
+  const ageW = Math.max(5, ...shown.map(r => [...ageText(r, now)].length));
+  let pos = 0;
+  const kindW = Math.min(9, Math.max(...shown.map(r => r.kind.length)));
+  const lines = shown.map((r, i) => {
+    const el = ageText(r, now).padStart(ageW);
+    const tone = toneName(r, pos, now); if (r.kind !== 'approval') pos++;
+    const actW = Math.min(18, Math.max(0, ...shown.map(x => [...(x.activity || '')].length)));
+    const act = clip(r.activity || '', actW).padEnd(actW);
+    const fixed = 1 + 1 + 1 + kindW + 1 + 1 + actW + 1 + ageW + 2; // pulse column (space + glyph); marker glyph kind name act elapsed
+    const nameW = Math.max(8, cols - 2 - fixed - 1);
+    const name = clip(r.name, nameW).padEnd(nameW);
+    const marker = focus && i === sel ? '›' : ' ';
+    if (r.collapsed) { // one summary row: count, oldest age, newest title, where to go; clipped to the line
+      const head = `${r.count} approvals waiting · oldest ${elapsed(r.oldestMs)} · newest: `, tail = ' · /approvals';
+      const room = cols - 5 - [...head].length - [...tail].length;
+      const text = room >= 12 ? `${head}${clip(r.newestTitle, room)}${tail}` : clip(`${r.count} approvals waiting · oldest ${elapsed(r.oldestMs)}${tail}`, cols - 4); // too narrow for a title
+      return { key: r.key, kind: 'approval', state: r.state, tone: toneName(r, pos, now), selected: false, marker: ' ', glyph: GLYPH[r.state], rest: ' ' + text, pulse: '', pulseRole: 'dim', pulseKind: 'none', text: ` ${GLYPH[r.state]} ${text}` };
+    }
+    const rest = `${r.kind.padEnd(kindW)} ${name} ${act} ${el}`;
+    const p = pulseOf(r, now, { motion });
+    return { key: r.key, kind: r.kind, state: r.state, tone, selected: focus && i === sel, marker, glyph: glyphOf(r), glyphRole: r.state === 'failed' && endWord(r) !== 'failed' ? 'dim' : null, rest: ' ' + rest, pulse: ' ' + p.glyph, pulseRole: p.role, pulseKind: p.kind, text: `${marker}${glyphOf(r)} ${rest} ${p.glyph}` };
+  });
+  return { mode: 'full', lines, more: Math.max(0, rows.length - shown.length) };
+}
+
+export function peekLines(row, now = Date.now()) {
+  if (!row) return [];
+  const age = ageText(row, now);
+  const out = [`${row.kind} ${row.id}`, `status ${row.status} · ${endWord(row)}${age ? ` · ${age}` : ''}`, `name ${row.name}`];
+  if (row.activity) out.push(`activity ${row.activity}`);
+  const d = row.detail || {};
+  if (d.description) out.push(`goal ${d.description}`);
+  if (d.workflowId) out.push(`workflow ${d.workflowId}`);
+  if (d.trigger) out.push(`trigger ${d.trigger}`);
+  if (d.error && row.state === 'failed') out.push(`error ${typeof d.error === 'string' ? d.error : JSON.stringify(d.error)}`);
+  return out;
+}

package/lib/quoxon/route.js

@@ -0,0 +1,39 @@
+/**
+ * Bare `quox` is the conversation. Decide, from argv alone, whether this
+ * invocation belongs to the QUOXON client (no subcommand, only client flags).
+ * Anything with a subcommand, --help or --version stays with commander.
+ */
+const VALUE_FLAGS = new Set(['-p', '--profile', '-n', '--name']);
+const LEVELS = new Set(['off', 'on', 'full']); // `--verbose` alone means on; it only takes a value that is a level
+const PRINT_VALUE_FLAGS = new Set(['--output', '--conversation', '--turn-id', '--timeout', '--provider', '--model', '--agent', '--prompt-profile']);
+const BOOL_FLAGS = new Set(['--demo', '--autoplay', '--demo-onboarding', '--no-clear', '--color', '--service-key']);
+const ALL_FLAGS = new Set([...VALUE_FLAGS, ...PRINT_VALUE_FLAGS, ...BOOL_FLAGS, '--print', '--resume', '--autoplay-exit', '-h', '--help', '--']);
+
+export function routesToQuoxon(argv, isTTY) {
+  let print = false;
+  let help = false;
+  const dd = argv.indexOf('--');
+  const head = dd === -1 ? argv : argv.slice(0, dd);
+  const hasPrint = head.some(a => a === '--print' || a.startsWith('--print='));
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { return print; } // everything after -- is the prompt
+    if (a === '--print') { print = true; const n = argv[i + 1]; if (n !== undefined && !ALL_FLAGS.has(n) && !/^--(profile|verbose|output|conversation|turn-id|timeout|print|provider|model|agent|prompt-profile)=/.test(n)) i++; }
+    else if (a.startsWith('--print=')) print = true;
+    else if (a === '-h' || a === '--help') help = true;
+    else if (a === '--verbose') { if (LEVELS.has(argv[i + 1])) i++; }
+    else if (a === '--resume') { const n = argv[i + 1]; if (n !== undefined && !n.startsWith('-')) i++; } // optional id or name
+    else if (a === '--autoplay-exit') { if (/^\d+(\.\d+)?$/.test(argv[i + 1] || '')) i++; } // optional seconds
+    else if (a.startsWith('--resume=')) { /* inline value */ }
+    else if (VALUE_FLAGS.has(a)) i++;
+    else if (/^--(profile|verbose|name)=/.test(a)) { /* inline value */ }
+    else if (BOOL_FLAGS.has(a)) { /* no value */ }
+    else if (PRINT_VALUE_FLAGS.has(a)) i++;
+    else if (/^--(output|conversation|turn-id|timeout|provider|model|agent|prompt-profile)=/.test(a)) { /* inline value */ }
+    else if (hasPrint && !a.startsWith('-')) { print = true; } // the prompt, wherever it sits among the flags
+    else return false; // subcommand, positional, --help, --version, unknown flag
+  }
+  if (print) return true;
+  if (help) return false; // plain `quox --help` is commander's
+  return Boolean(isTTY); // interactive client needs a terminal; scripts keep the banner
+}