quoxcli 0.3.1 → 0.5.0

package/lib/quoxon/loopCards.js

@@ -0,0 +1,189 @@
+/**
+ * QLOOP-LIVE: the loop cards in the chat stream. One card per loop, updated in place; observer points and the finish line
+ * append as ordinary chat lines beneath it, so the history reads as the loop's story.
+ *
+ * Glue only (the logic is in loopCard.js and loopStream.js): it owns the watchers, the redraw throttle (<= 8 per second),
+ * the keys of a focused card and the finish moment. The host (app.js) supplies say / addItem / bump / dragon, which keeps this
+ * testable without Ink.
+ */
+import { loopPinned, initLoop, applySnapshot, applyProgress, reduceLoop, setConn, observerLine, finishLines, startLine, createThrottle, REDRAW_MIN_MS, REDRAW_UNFOCUSED_MS, TERMINAL } from './loopCard.js';
+import { watchLoop } from './loopStream.js';
+import { objectiveMoment } from './dragonMoments.js';
+
+const TICK_MS = 250; // a focused card's spinner and clock
+const TICK_UNFOCUSED_EVERY = 4; // nobody on the card: every 4th tick (1 s), so idle cards cost little
+const REFRESH_MIN_MS = 2000; // the runner's own turn is read from the snapshot at most this often per card
+const REFRESH_CAP_MS = 1500; // and the finish never waits longer than this for the last read
+
+/**
+ * The roster sees a loop finish (its row turns done) up to a minute BEFORE the stream's loop.finished reaches the card (the server
+ * drains receipts first), and its dragon then lands on a card that is still running and overflows the screen. A loop with a live card
+ * summons its dragon from the card, once, at its finish: the roster's watch skips those rows.
+ */
+export const rowsWithoutLoopCards = (rows, has) => (rows || []).filter((r) => !(r?.kind === 'loop' && has(r.id)));
+
+export function createLoopCards({ api, say, addItem, bump, dragon = null, now = Date.now, setTick = (f, ms) => { const t = setInterval(f, ms); t.unref?.(); return () => clearInterval(t); }, throttleTimer, watch = watchLoop, sleep } = {}) {
+  const cards = new Map(); // id -> ctrl
+  let focusId = null, cancelTick = null;
+  const throttle = createThrottle(() => bump(), { minMs: () => (focusId ? REDRAW_MIN_MS : REDRAW_UNFOCUSED_MS), now, ...(throttleTimer ? { timer: throttleTimer } : {}) });
+
+  const running = () => [...cards.values()].some((c) => !c.state.done && !c.state.refused);
+  /**
+   * A runner loop's stream `turn` counts model messages; its own turn is the snapshot's `iteration`. Read it again when a turn moves
+   * (at most every REFRESH_MIN_MS; a request inside the window is made by the next tick). -> a promise that settles when the read is over.
+   */
+  function refresh(c, force = false) {
+    if (!api.loopSnapshot || c.refreshing) return c.refreshing || Promise.resolve();
+    if (!force && now() - (c.lastSnapAt ?? -Infinity) < REFRESH_MIN_MS) { c.refreshDue = true; return Promise.resolve(); }
+    c.lastSnapAt = now(); c.refreshDue = false;
+    c.refreshing = Promise.resolve().then(() => api.loopSnapshot(c.id)).then((snap) => { c.state = applyProgress(c.state, snap); throttle.poke(); }, () => {}).finally(() => { c.refreshing = null; });
+    return c.refreshing;
+  }
+  let tickN = 0;
+  function tick() { // elapsed time and the spinner move once per tick, never faster than the throttle allows
+    if (!running()) { cancelTick?.(); cancelTick = null; return; }
+    if (!focusId && ++tickN % TICK_UNFOCUSED_EVERY) return;
+    for (const c of cards.values()) if (!c.state.done && !c.state.refused) { c.frame = (c.frame + 1) % 4; if (c.refreshDue) refresh(c); }
+    throttle.poke();
+  }
+  const ensureTick = () => { if (!cancelTick && running()) cancelTick = setTick(tick, TICK_MS); };
+
+  function finish(c, ev) {
+    if (!c.finishedSaid) { c.finishedSaid = true; for (const l of finishLines(c.state)) say(l.text, l.tone); }
+    c.confirm = false; // a focused card keeps its focus: Enter then expands the final output and Esc lets the frozen card go to scrollback
+    // The moment engine fires the dragon. Same call and same gates as a finished roster row (mode on, not typing, cooldown).
+    const st = c.state;
+    const m = !c.quiet && dragon?.summon && ['completed', 'completed_with_errors', 'failed'].includes(st.state)
+      ? objectiveMoment({ kind: 'loop', state: st.state === 'failed' ? 'failed' : 'done', name: st.title || st.id, activity: st.reason || '' }) : null;
+    if (m) Promise.resolve(dragon.summon(st.agent && typeof st.agent === 'string' ? st.agent : m.dragon, m.caption)).then((shown) => { if (shown) bump(); }, () => {});
+    return ev;
+  }
+
+  function onEvent(c, ev) {
+    const before = c.state;
+    c.state = reduceLoop(before, ev);
+    if (c.state === before) return;
+    const line = c.quiet ? null : observerLine(ev, c.state); // replaying a loop that was already over: the card tells it, the chat does not re-read it
+    if (line) { c.state.observed = [...c.state.observed, line.text].slice(-50); say(line.text, line.tone); }
+    if (ev.type === 'loop.turn.started' || ev.type === 'loop.turn.completed' || ev.type === 'loop.observe') refresh(c);
+    if (ev.type === 'loop.finished') { // the last read of the runner's turn first: "completed, N turns" must be the loop's count
+      c.finishing = true;
+      let t; const cap = new Promise((res) => { t = setTimeout(res, REFRESH_CAP_MS); t.unref?.(); });
+      Promise.race([refresh(c, true), cap]).then(() => { clearTimeout(t); finish(c, ev); throttle.poke(); });
+    }
+    throttle.poke();
+  }
+
+  // The start line is only true once the loop has answered: a refused watch never says "started".
+  function announceStart(c) {
+    if (c.startSaid || !c.announce) return;
+    c.startSaid = true; const l = startLine(c.state); say(l.text, l.tone);
+  }
+
+  async function run(c) {
+    const ctl = c.abort = new AbortController();
+    try {
+      const out = await watch({
+        api, id: c.id, signal: ctl.signal, sleep,
+        onSnapshot: (snap) => { announceStart(c); c.state = applySnapshot(c.state, snap); if (c.state.done) c.quiet = true; throttle.poke(); }, // the finish line waits for the replay: it needs the receipts
+        onEvent: (ev) => { announceStart(c); onEvent(c, ev); },
+        onConn: ({ conn, attempt, note }) => { if (!c.state.done) { c.state = setConn(c.state, conn, { attempt, note }); throttle.poke(); } },
+      });
+      if (out?.lost && !c.state.done) {
+        c.state = setConn(c.state, 'lost', { attempt: 0, note: out.reason });
+        // Refused (403 / 404) before a single event: the loop is not this caller's (or does not exist). Say so; it never started for us.
+        if ((out.status === 403 || out.status === 404) && c.state.startedAt == null && !c.state.turn && !c.startSaid) c.state = { ...c.state, refused: "that loop belongs to another workspace (or doesn't exist)" };
+      }
+      if (c.state.done && !c.finishedSaid && !c.finishing) { c.finishedSaid = true; for (const l of finishLines(c.state)) say(l.text, l.tone); } // finished before we looked (or the replay ended without a finish event)
+    } catch (e) {
+      c.state = setConn(c.state, 'lost', { note: e?.message || 'failed' });
+    } finally { throttle.poke(); }
+  }
+
+  return {
+    /** Put a live card in the chat stream for this loop and start following it. -> the card, or the existing one. */
+    watch(id, { title = '', agent = null, announce = true } = {}) {
+      if (!id) return null;
+      if (cards.has(id)) return cards.get(id);
+      const c = { id, state: initLoop({ id, title, agent }), expanded: false, focused: false, confirm: false, frame: 0, abort: null, finishedSaid: false, startSaid: false, announce };
+      cards.set(id, c);
+      addItem({ id: `loopcard-${id}`, kind: 'loopcard', card: c });
+      ensureTick();
+      run(c).then(() => bump());
+      return c;
+    },
+    /**
+     * A loop the chat just made (its `objective` tool answered `Loop "<title>" created ...`): the tool result carries no id, so look
+     * the loop up in the org's list (newest first) and put a card in this conversation for the live, unwatched one that matches
+     * the title. One retry, because the list can lag the tool's answer. -> ids watched.
+     */
+    async discover({ title = '' } = {}) {
+      if (!api.loopList) return [];
+      const want = String(title || '').replace(/…$/, '').trim().toLowerCase();
+      for (let attempt = 0; attempt < 2; attempt++) {
+        let rows = [];
+        try { const d = await api.loopList(); rows = Array.isArray(d) ? d : (d?.loops || []); } catch { rows = []; }
+        const hit = rows.filter((r) => {
+          const id = r.objective_id || r.id; if (!id || cards.has(id) || TERMINAL.has(r.state)) return false;
+          const age = now() - (Date.parse(String(r.created_at || '').replace(' ', 'T') + (/[zZ]|[+-]\d\d:?\d\d$/.test(String(r.created_at || '')) ? '' : 'Z')) || 0);
+          return age < 20 * 60 * 1000 && (!want || String(r.title || '').toLowerCase().startsWith(want));
+        });
+        if (hit.length) { const r = hit[0]; const id = r.objective_id || r.id; this.watch(id, { title: r.title || title }); return [id]; }
+        if (attempt === 0) await (sleep || ((ms) => new Promise((res) => setTimeout(res, ms))))(1500);
+      }
+      return [];
+    },
+    /** Read the runner's turn now (tests, and a card that was just focused). */
+    refresh: (id) => (cards.has(id) ? refresh(cards.get(id), true) : Promise.resolve()),
+    has: (id) => cards.has(id),
+    get: (id) => cards.get(id) || null,
+    all: () => [...cards.values()],
+    /** True while this history item must stay in the live region (commitLimit): its loop has not finished. */
+    held: (item) => Boolean(item?.kind === 'loopcard' && item.card && ((!item.card.state.done && !item.card.state.refused) || item.card.focused)), // a focused card stays live even when finished, so Enter / Esc work on it
+    anyRunning: running,
+    /** The cards drawn above the composer: running ones, and a finished one you are still on. */
+    pinned: () => [...cards.values()].filter(loopPinned),
+    /** The card the keys act on, or null. */
+    focused: () => (focusId && cards.get(focusId)) || null,
+    /** Focus the newest card that is still running (or the named one). -> the card or null. */
+    focus(id = null) {
+      const pick = id ? cards.get(id) : [...cards.values()].reverse().find((c) => !c.state.done) || [...cards.values()].pop();
+      if (!pick) return null;
+      const old = this.focused(); if (old) { old.focused = false; old.confirm = false; }
+      pick.focused = true; focusId = pick.id; throttle.poke(); bump(); return pick;
+    },
+    blur() { const c = this.focused(); if (c) { c.focused = false; c.confirm = false; } focusId = null; bump(); },
+    /**
+     * Keys while a card is focused. Enter toggles the expanded spool, s asks to halt (y confirms, anything else cancels),
+     * Esc collapses and then leaves. -> true when the key was consumed.
+     */
+    key(name, text) {
+      const c = this.focused(); if (!c) return false;
+      if (c.confirm) {
+        c.confirm = false;
+        if (text === 'y') this.halt(c.id).then(() => bump(), () => bump()); else say('Halt cancelled.');
+        bump(); return true;
+      }
+      if (name === 'enter') { c.expanded = !c.expanded; bump(); return true; }
+      if (name === 'escape') { if (c.expanded) c.expanded = false; else this.blur(); bump(); return true; }
+      if (text === 's' && !c.state.done) { c.confirm = true; bump(); return true; }
+      if (name === 'up' || name === 'down' || name === 'tab') { // cycle between cards when there are several
+        const ids = [...cards.keys()]; if (ids.length > 1) { const i = ids.indexOf(c.id); this.focus(ids[(i + (name === 'up' ? ids.length - 1 : 1)) % ids.length]); }
+        return true;
+      }
+      if (text) { this.blur(); return false; } // ordinary typing goes to the draft
+      return true;
+    },
+    /** The halt goes through the same governed route as the roster's s: after an explicit y from the human, never silently. */
+    async halt(id) {
+      const c = cards.get(id); if (!c) return { ok: false, message: `no loop card for ${id}` };
+      if (!api.stopRow) { say('Halt is not available on this server.', 'warn'); return { ok: false }; }
+      const r = await api.stopRow({ source: 'objectives', kind: 'loop', id, name: c.state.title || id });
+      say(r.message || (r.ok ? 'Halt sent.' : 'Halt refused.'), r.ok ? undefined : 'warn');
+      return r;
+    },
+    dispose() { for (const c of cards.values()) c.abort?.abort(); cards.clear(); cancelTick?.(); cancelTick = null; throttle.dispose(); },
+  };
+}
+
+export { TERMINAL };

package/lib/quoxon/loopStream.js

@@ -0,0 +1,98 @@
+/**
+ * QLOOP-LIVE: the client for a running loop. Reads GET /api/v1/loops/:id (snapshot) and
+ * GET /api/v1/loops/:id/events (SSE; ?since=<event_seq> resumes; a heartbeat comment every 15 s; ends after loop.finished).
+ * Contract: ~/quoxon-work/qloop-live-design.md section 1. Every event carries a monotonic event_seq.
+ *
+ * Reconnect is the part that must not lie. A drop is counted, backed off (500 ms doubling to 10 s, reset by any event) and
+ * reported to the card as 'reconnecting'; after MAX_FAILS drops in a row with no event between, or at once on 401/403/404,
+ * the watcher stops and says 'lost' with the reason. It never reports a lost stream as a finished loop.
+ */
+export const BACKOFF_START_MS = 500;
+export const BACKOFF_CAP_MS = 10000;
+export const MAX_FAILS = 8;
+export const QUIET_START_MS = 2000, QUIET_CAP_MS = 60000, QUIET_AFTER = 10, QUIET_RETIRE_AFTER = 20; // (retire: the snapshot still says running after this many empty closes in a row -> stop watching) // empty-close reconnects while the snapshot says running
+const FATAL = new Set([401, 403, 404]);
+const TERMINAL_STATES = new Set(['completed', 'completed_with_errors', 'failed', 'interrupted', 'halted', 'cancelled', 'aborted', 'stopped']);
+const isTerminal = (snap) => Boolean(snap && (snap.finished === true || TERMINAL_STATES.has(snap.state)));
+
+const sleepFor = (ms, signal) => new Promise((resolve) => {
+  if (signal?.aborted) return resolve();
+  const t = setTimeout(done, ms); t.unref?.();
+  function done() { signal?.removeEventListener?.('abort', done); clearTimeout(t); resolve(); }
+  signal?.addEventListener?.('abort', done, { once: true });
+});
+
+/**
+ * Follow one loop until loop.finished, abort, or a fatal failure.
+ *
+ * api: { loopSnapshot(id) -> object, loopEvents(id, { since }, signal) -> async iterable of events }
+ * handlers: { onSnapshot(snap), onEvent(ev), onConn({ conn: 'live'|'reconnecting'|'lost', attempt, note }) }
+ * -> { finished: boolean, lost: boolean, lastSeq, reason? }
+ */
+export async function watchLoop({ api, id, signal, since = 0, onSnapshot = () => {}, onEvent = () => {}, onConn = () => {}, sleep = sleepFor, backoffStart = BACKOFF_START_MS, backoffCap = BACKOFF_CAP_MS, maxFails = MAX_FAILS, quietStart = QUIET_START_MS, quietCap = QUIET_CAP_MS, quietAfter = QUIET_AFTER, quietRetireAfter = QUIET_RETIRE_AFTER, now = Date.now }) {
+  let quietRuns = 0, quietSince = 0, quietSaid = false;
+  let lastSeq = Number(since) || 0, fails = 0, delay = backoffStart, finished = false;
+  try { onSnapshot(await api.loopSnapshot(id)); }
+  catch (e) { // the snapshot is a head start, not a gate: the replayed events carry the same facts. A fatal status still stops.
+    if (FATAL.has(e?.status)) { onConn({ conn: 'lost', attempt: 0, note: describe(e) }); return { finished: false, lost: true, lastSeq, status: e?.status, reason: describe(e) }; }
+  }
+  while (!signal?.aborted && !finished) {
+    let sawEvent = false;
+    try {
+      for await (const ev of api.loopEvents(id, { since: lastSeq || undefined }, signal)) {
+        if (signal?.aborted) break;
+        if (!ev || typeof ev.type !== 'string') continue;
+        const seq = Number(ev.event_seq);
+        if (Number.isFinite(seq) && seq <= lastSeq) continue; // the boundary event of a resume
+        if (Number.isFinite(seq)) lastSeq = seq;
+        if (!sawEvent) { sawEvent = true; fails = 0; quietRuns = 0; quietSaid = false; delay = backoffStart; onConn({ conn: 'live', attempt: 0, note: null }); }
+        onEvent(ev);
+        if (ev.type === 'loop.finished') { finished = true; break; }
+      }
+      if (!finished && !signal?.aborted && !sawEvent) {
+        // A clean close with no events is not a failure: a loop's silent final turn, or a loop that already finished, ends this way.
+        // Ask the snapshot. Terminal: finish quietly with the final state. Still running: reconnect with ?since, failures reset.
+        // Only a snapshot read that itself fails counts (a real error).
+        let snap = null;
+        try { snap = await api.loopSnapshot(id); }
+        catch (e) {
+          if (FATAL.has(e?.status)) { onConn({ conn: 'lost', attempt: fails, note: describe(e) }); return { finished: false, lost: true, lastSeq, status: e?.status, reason: describe(e) }; }
+          fails += 1;
+          if (fails >= maxFails) { onConn({ conn: 'lost', attempt: fails, note: describe(e) }); return { finished: false, lost: true, lastSeq, status: e?.status, reason: describe(e) }; }
+          onConn({ conn: 'reconnecting', attempt: fails, note: describe(e) });
+          await sleep(delay, signal); delay = Math.min(delay * 2, backoffCap);
+          continue;
+        }
+        if (isTerminal(snap)) { onSnapshot(snap); return { finished: true, lost: false, lastSeq, final: snap }; }
+        fails = 0; // still running: quiet, not a failure, but counted: capped backoff, and one honest line after quietAfter
+        if (quietRuns === 0) quietSince = now();
+        quietRuns += 1;
+        if (quietRuns >= quietRetireAfter) { // retirement: the snapshot (just re-read) still says running but nothing streams. Stop, say so plainly, never spin.
+          const reason = `the loop says running but its stream is silent; /loop ${id} to check, or it may have ended`;
+          onConn({ conn: 'silent', attempt: quietRuns, note: reason });
+          return { finished: false, lost: false, silent: true, lastSeq, reason };
+        }
+        if (quietRuns >= quietAfter && !quietSaid) { quietSaid = true; onConn({ conn: 'quiet', attempt: quietRuns, note: fmtDur(now() - quietSince) }); }
+        await sleep(Math.min(quietStart * 2 ** (quietRuns - 1), quietCap), signal);
+        continue;
+      }
+      else if (!finished && sawEvent) fails = 0;
+    } catch (e) {
+      if (signal?.aborted) break;
+      if (FATAL.has(e?.status)) { onConn({ conn: 'lost', attempt: fails, note: describe(e) }); return { finished: false, lost: true, lastSeq, status: e?.status, reason: describe(e) }; }
+      fails += 1;
+      if (fails >= maxFails) { onConn({ conn: 'lost', attempt: fails, note: describe(e) }); return { finished: false, lost: true, lastSeq, status: e?.status, reason: describe(e) }; }
+      onConn({ conn: 'reconnecting', attempt: fails, note: describe(e) });
+      await sleep(delay, signal); delay = Math.min(delay * 2, backoffCap);
+      continue;
+    }
+    if (finished || signal?.aborted) break;
+    if (fails >= maxFails) { onConn({ conn: 'lost', attempt: fails, note: 'the stream keeps closing' }); return { finished: false, lost: true, lastSeq, reason: 'the stream keeps closing' }; }
+    onConn({ conn: 'reconnecting', attempt: Math.max(1, fails), note: null });
+    await sleep(delay, signal); delay = Math.min(delay * 2, backoffCap);
+  }
+  return { finished, lost: false, lastSeq };
+}
+
+const fmtDur = (ms) => { const m = Math.round(ms / 60000); return m >= 1 ? `${m} min` : `${Math.round(ms / 1000)}s`; };
+const describe = (e) => `${e?.status ? `HTTP ${e.status} ` : ''}${e?.message || 'failed'}`.trim();

package/lib/quoxon/mailView.js

@@ -0,0 +1,71 @@
+/**
+ * TUI-MAIL (owner 2026-10-30): read triaged InboxQ mail in the terminal. Pure helpers, read only; app.js owns the calls.
+ * Same data as `quox mail list` (GET /api/v1/inboxq/messages) and the message read behind `quox notes from-email`.
+ */
+import { ageOf } from './inboxView.js';
+const clip = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, Math.max(0, n - 1))}…` : t; };
+const pad = (s, n) => { const t = clip(s, n); return t + ' '.repeat(Math.max(0, n - [...t].length)); };
+export const MAIL_ZONES = ['focus', 'fyi', 'auto', 'screened'];
+export const MAIL_USAGE = 'Usage: /mail | /mail focus|fyi|auto|screened (one zone) | /mail N (read one). Read only.';
+export const BODY_MAX_LINES = 40;
+
+const whenMs = (m) => { const v = Number(m?.dateTs); if (Number.isFinite(v) && v > 0) return v < 1e12 ? v * 1000 : v; const t = Date.parse(m?.createdAt || ''); return Number.isFinite(t) ? t : 0; };
+const fromOf = (m) => m.fromName || m.fromAddr || 'unknown';
+const newestFirst = (items) => [...(Array.isArray(items) ? items : [])].filter((m) => m && m.id).sort((a, b) => whenMs(b) - whenMs(a));
+export { newestFirst as mailNewestFirst };
+
+/** '' | list | N | #N | show N | <zone> -> { kind:'list', zone? } | { kind:'show', n } | { kind:'usage' } */
+export function parseMail(arg) {
+  const a = String(arg || '').trim().toLowerCase();
+  if (!a || a === 'list' || a === 'latest') return { kind: 'list' };
+  if (MAIL_ZONES.includes(a)) return { kind: 'list', zone: a };
+  const m = /^(?:show\s+)?#?(\d+)$/.exec(a);
+  if (m && Number(m[1]) >= 1) return { kind: 'show', n: Number(m[1]) };
+  return { kind: 'usage' };
+}
+
+/** No mailbox connected: one line, the exact command, no secret asked for here. */
+export const noMailboxLines = () => [{ text: 'No mailbox connected. Connect one with: quox mail connect --provider gmail --email you@example.com --password-env MAIL_PASSWORD (the password is read from that env var, not typed here).', tone: 'warn' }];
+
+/** The newest messages as a table. -> [{ text, tone }] */
+export function mailTable(items, now = Date.now(), cols = 100, max = 10) {
+  const rows = newestFirst(items).slice(0, max);
+  if (!rows.length) return [{ text: 'No triaged mail yet.', tone: 'dim' }];
+  const tw = Math.max(16, Math.min(60, cols - 44));
+  const out = [{ text: `  ${pad('#', 3)}${pad('when', 6)}${pad('from', 18)}${pad('subject', tw)} zone`, tone: 'dim' }];
+  rows.forEach((m, i) => out.push({ text: `${m.seen === false ? '●' : ' '} ${pad(i + 1, 3)}${pad(ageOf(whenMs(m) ? new Date(whenMs(m)).toISOString() : '', now), 6)}${pad(fromOf(m), 18)}${pad(m.subject || '(no subject)', tw)} ${m.zone || '?'}`, tone: m.seen === false ? 'accent' : 'dim' }));
+  out.push({ text: '/mail N read one · /mail focus|fyi|auto|screened filter · full list: quox mail list', tone: 'dim' });
+  return out;
+}
+
+const htmlToText = (h) => String(h)
+  .replace(/<(script|style)[\s\S]*?<\/\1>/gi, '').replace(/<br\s*\/?>/gi, '\n').replace(/<\/(p|div|li|tr|h[1-6])>/gi, '\n')
+  .replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/\n{3,}/g, '\n\n');
+
+/** One message: from, to, date, subject, a plain-text body excerpt, the triage reason. -> [{ text, tone }] */
+export function mailDetail(m, now = Date.now(), n = 0) {
+  const from = m.fromName && m.fromAddr ? `${m.fromName} <${m.fromAddr}>` : fromOf(m);
+  const t = whenMs(m);
+  const to = m.toAddr || m.toAddrs || m.to;
+  const out = [{ text: m.subject || '(no subject)', tone: 'accent' },
+    { text: `from ${from}`, tone: 'dim' }];
+  if (to) out.push({ text: `to ${Array.isArray(to) ? to.join(', ') : to}`, tone: 'dim' });
+  out.push({ text: `${t ? new Date(t).toISOString().slice(0, 16).replace('T', ' ') + ' UTC' : 'date unknown'} (${t ? ageOf(new Date(t).toISOString(), now) + ' ago' : '?'})`, tone: 'dim' });
+  const bits = [`triage: ${m.zone || 'untriaged'}`];
+  if (m.classifiedBy) bits.push(`by ${m.classifiedBy}`);
+  if (typeof m.confidence === 'number') bits.push(`${Math.round(m.confidence * 100)}% sure`);
+  if (Array.isArray(m.flags) && m.flags.length) bits.push(`flags: ${m.flags.join(', ')}`);
+  if (m.phishingRisk > 0) bits.push('phishing risk flagged');
+  out.push({ text: bits.join(' · '), tone: 'dim' });
+  let body = typeof m.bodyText === 'string' && m.bodyText.trim() ? m.bodyText : (typeof m.bodyHtml === 'string' && m.bodyHtml.trim() ? htmlToText(m.bodyHtml) : '');
+  if (body) {
+    const lines = body.trim().split('\n');
+    for (const l of lines.slice(0, BODY_MAX_LINES)) out.push({ text: l.replace(/\s+$/, ''), tone: 'text' });
+    if (lines.length > BODY_MAX_LINES) out.push({ text: `… ${lines.length - BODY_MAX_LINES} more lines. Full message: quox mail list -o json`, tone: 'dim' });
+  } else if (m.snippet) {
+    out.push({ text: m.snippet, tone: 'text' });
+    out.push({ text: '(preview only: the full body has not been fetched from the mailbox yet)', tone: 'dim' });
+  } else out.push({ text: '(no body stored)', tone: 'dim' });
+  if (n) out.push({ text: `/mail for the list · read only: nothing is sent, moved or deleted here`, tone: 'dim' });
+  return out;
+}

package/lib/quoxon/main.js

@@ -12,7 +12,7 @@ import { loadRules, rulesContext } from './rules.js';
 import { createTranscript } from './transcript.js';
 import { createScreenRecorder, screenFramesEnabled } from './screenFrames.js';
 import { applySettings } from './slash/settings.js';
-import { headOf, RUNNING_ROOT, execRestart, restartPlan, checkRestart, startBuildWatch, settleMsFrom, restoreTerminal, RESTART_SLOT_ENV, RESTART_ATTACH_ENV, RESTART_NOTE_ENV, RESTART_MODE_ENV } from './slash/restart.js';
+import { headOf, RUNNING_ROOT, execRestart, restartPlan, checkRestart, startBuildWatch, settleMsFrom, minGapMsFrom, restoreTerminal, RESTART_SLOT_ENV, RESTART_ATTACH_ENV, RESTART_NOTE_ENV, RESTART_MODE_ENV, RESTART_DECLINED_ENV } from './slash/restart.js';
 import { readLastSeen, writeLastSeen } from './away.js';
 import { fileHistory } from './promptHistory.js';
 import { takeLauncherHandoff, writeRestartHandoff, RESTART_EXIT_CODE } from './launcher.js';
@@ -21,6 +21,7 @@ export { parseArgs, USAGE, pickProfile, choosePick, chatCredentialProblem, noSer
 import { parseArgs, USAGE, noServerConfigured, mainPrint, pickProfile, chatCredentialProblem } from './headless.js';
 
 export { captureEarlyInput } from './earlyInput.js';
+import { isNeverAnswered, healthyStamp } from './neverAnswered.js';
 
 /**
  * Clear the screen before the chat client? Never right after Getting started: its finale (the one-time
@@ -39,7 +40,7 @@ export async function main(argv = process.argv.slice(2)) {
   if (opts.errors.length) { early?.release(); process.stderr.write(`quox: ${opts.errors.join('; ')}\n${USAGE}\n`); process.exitCode = 1; return; }
   const cwd = process.cwd().replace(process.env.HOME || '\0', '~');
   const { resolveCliVersion } = await import('../core/version.js');
-  let version = '0.3.1';
+  let version = '0.5.0';
   try { version = resolveCliVersion?.() || version; } catch { /* keep default */ }
   if (opts.print) return mainPrint(opts);
   let replay = null;
@@ -56,6 +57,15 @@ export async function main(argv = process.argv.slice(2)) {
     // and a fresh install replays the original request as the first real turn
     replay = r.replay || null;
     fromGettingStarted = true;
+    // QUOXON-Q: ONE offer for a short `q` command, asked once (answer kept in the CLI config)
+    if (process.stdin.isTTY && process.stdout.isTTY && !opts.demoOnboarding) {
+      try {
+        const { offerShortcut } = await import('./onboarding/shortcutOffer.js');
+        const { createInterface } = await import('node:readline/promises');
+        const config = (await import('../core/config.js')).loadConfig();
+        await offerShortcut({ config, ask: async (line) => { const rl = createInterface({ input: process.stdin, output: process.stdout }); try { return await rl.question(`\n${line} `); } finally { rl.close(); } } });
+      } catch { /* an offer must never block the first conversation */ }
+    }
   }
   let props;
   let restart = null; // set by /restart: run the installed quox here once the app has let go of the terminal
@@ -95,6 +105,9 @@ export async function main(argv = process.argv.slice(2)) {
       if (problem) return problem.message;
       if (pick.note) return pick.note;
       const hl = await api.health(8000);
+      if (hl.ok && !missing) { // ONBOARD-P2: remember that this profile's server has answered, so a later outage keeps the reconnect spinner
+        try { const stamp = healthyStamp(config.getProfile?.(pname), Date.now()); if (stamp) config.upsertProfile?.(pname, { lastHealthyAt: stamp }); } catch { /* history is best effort */ }
+      }
       return hl.ok ? null : hl.absent ? `No QuoxCORE running at ${hl.url}` : `QuoxCORE at ${hl.url} is not answering (${hl.status}); messages may be slow`;
     };
     // /restart hand-over: re-enter the predecessor window's org in this window only (the profile is untouched).
@@ -118,7 +131,7 @@ export async function main(argv = process.argv.slice(2)) {
       return { ok: true, api: a2, agentLogin: residentNames().includes(name), orgName: (c && !c.error && c.name) || c2.getAuth?.()?.org_name || null, note };
     };
     const loginCandidates = profiles.filter(p => !p.loggedIn && !residentNames().includes(p.name)).map(p => p.name);
-    props = { api, switchProfile, loginCandidates, away: { read: readLastSeen, write: writeLastSeen }, modelChoice: opts.provider, resume: opts.resume ?? null, onRestart: (r) => { restart = r; }, onDemo: () => { restart = { demo: true }; }, restartCheck: checkRestart, buildWatch: (o) => startBuildWatch({ ...o, settleMs: settleMsFrom() }), startSha: headOf(RUNNING_ROOT), rules: loadRules(), profile: pname, agentLogin: (probe.listResidentProfiles?.() || []).some(r => r.name === pname), humanProfiles: profiles.filter(p => p.loggedIn && !(probe.listResidentProfiles?.() || []).some(r => r.name === p.name)).map(p => p.name), org: missing ? null : ((carried && !carried.error && carried.name) || config.getAuth?.()?.org_name || null), startup: startupCarry, healthRecheck: () => api.health(8000), blocked: problem && !signedOut ? problem.message : null, signedOut, autoplay: replay };
+    props = { api, switchProfile, loginCandidates, startupSwitchOffer: true, away: { read: readLastSeen, write: writeLastSeen }, modelChoice: opts.provider, resume: opts.resume ?? null, onRestart: (r) => { restart = r; }, onDemo: () => { restart = { demo: true }; }, restartCheck: checkRestart, buildWatch: (o) => startBuildWatch({ ...o, settleMs: settleMsFrom(), minGapMs: minGapMsFrom() }), startSha: headOf(RUNNING_ROOT), rules: loadRules(), profile: pname, agentLogin: (probe.listResidentProfiles?.() || []).some(r => r.name === pname), humanProfiles: profiles.filter(p => p.loggedIn && !(probe.listResidentProfiles?.() || []).some(r => r.name === p.name)).map(p => p.name), org: missing ? null : ((carried && !carried.error && carried.name) || config.getAuth?.()?.org_name || null), startup: startupCarry, neverAnswered: !missing && !signedOut && !problem && !pick.note && !opts.serviceKey && isNeverAnswered(config.getProfile?.(pname)), onConnect: (url) => { restart = { connect: url }; }, healthRecheck: () => api.health(8000), blocked: problem && !signedOut ? problem.message : null, signedOut, autoplay: replay };
   }
   // Interactive start: a clean screen under the intro (never when piped; NO_COLOR still clears),
   // except straight after Getting started, whose finale must stay readable.
@@ -144,13 +157,24 @@ export async function main(argv = process.argv.slice(2)) {
   const restartSlot = opts.demo ? null : (process.env[RESTART_SLOT_ENV] || null); delete process.env[RESTART_SLOT_ENV]; // one hand-over only
   const restartAttach = opts.demo ? null : (process.env[RESTART_ATTACH_ENV] || null); delete process.env[RESTART_ATTACH_ENV];
   const restartMode = opts.demo ? null : (process.env[RESTART_MODE_ENV] === 'plan' ? 'plan' : null); delete process.env[RESTART_MODE_ENV]; // PLAN MODE: window-scoped, carried once
+  const restartDeclined = opts.demo ? null : (process.env[RESTART_DECLINED_ENV] || null); delete process.env[RESTART_DECLINED_ENV]; // a slot this window said no to: not re-asked after the restart
   const restartNote = opts.demo ? null : (process.env[RESTART_NOTE_ENV] || null); delete process.env[RESTART_NOTE_ENV]; // e.g. a failed /update, said once in the restarted client
   if (restartNote && !props.introNote) props.introNote = restartNote;
-  const app = render(React.createElement(App, { ...props, restartSlot, restartAttach, ...(restartMode ? { mode: restartMode } : {}), welcome, tipStartup: !fromGettingStarted && !opts.demo && Boolean(process.stdout.isTTY), whatsNewStartup: !opts.demo && Boolean(process.stdout.isTTY), version, cwd, verbose: opts.verbose, earlyInput: early, sessionName: opts.name, resumeConversation: opts.conversation || null, invite: Boolean(process.stdout.isTTY) && !opts.name, slotsAvailable, transcript, historyStore: opts.demo ? null : fileHistory() }), inkRenderOptions(process.stdout, { tap: screenRec?.tap }));
+  const app = render(React.createElement(App, { ...props, restartSlot, restartAttach, restartDeclined, ...(restartMode ? { mode: restartMode } : {}), welcome, tipStartup: !fromGettingStarted && !opts.demo && Boolean(process.stdout.isTTY), whatsNewStartup: !opts.demo && Boolean(process.stdout.isTTY), version, cwd, verbose: opts.verbose, earlyInput: early, sessionName: opts.name, resumeConversation: opts.conversation || null, invite: Boolean(process.stdout.isTTY) && !opts.name, slotsAvailable, transcript, historyStore: opts.demo ? null : fileHistory() }), inkRenderOptions(process.stdout, { tap: screenRec?.tap }));
   try { await app.waitUntilExit(); screenRec?.stop(); transcript?.end(restart ? 'restart' : 'exit'); }
   catch (e) { screenRec?.stop(); transcript?.end(`crash: ${e?.message || e}`); throw e; }
   finally { screenRec?.stop(); process.stdout.off('resize', onResize); }
   if (!restart) return;
+  if (restart.connect) { // ONBOARD-P2: "Connect to a different server?" said y; the connect flow owns the terminal (certificate card, sign-in)
+    restoreTerminal();
+    const { connectServer } = await import('./onboarding/connectServer.js');
+    const { profileNameForUrl } = await import('../core/profileTrust.js');
+    const { confirmInteractive } = await import('../core/confirm.js');
+    const profile = profileNameForUrl(restart.connect);
+    const c = await connectServer(restart.connect, { profile, trust: () => confirmInteractive(`Trust this server's certificate for profile "${profile}" only?`, { flag: '--trust-cert', purpose: 'trust it' }), loadConfigImpl: (await import('../core/config.js')).loadConfig });
+    if (c.action !== 'connected') { process.exitCode = 1; return; }
+    restart = { profile };
+  }
   if (restart.update) { // /update said y: the update owns the terminal (npm prompts, sudo), then the same restart either way
     const { runUpdate } = await import('../core/selfUpdate.js');
     const plan = restart.update;
@@ -165,7 +189,7 @@ export async function main(argv = process.argv.slice(2)) {
     }
   }
   // The app preflighted the installed quox before letting go, so a failure here is rare (it changed in between).
-  const how = { argv: restart.demo ? ['--demo', '--autoplay'] : argv, conversationId: restart.demo ? null : restart.conversationId, profile: opts.demo ? null : (restart.profile || props.profile), name: restart.name || opts.name || null, slot: restart.demo ? null : (restart.slot || null), attach: restart.demo ? null : (restart.attach || null), org: restart.demo ? null : (restart.org || null), mode: restart.demo ? null : (restart.mode || null), bin: restart.bin || undefined };
+  const how = { argv: restart.demo ? ['--demo', '--autoplay'] : argv, conversationId: restart.demo ? null : restart.conversationId, profile: opts.demo ? null : (restart.profile || props.profile), name: restart.name || opts.name || null, slot: restart.demo ? null : (restart.slot || null), attach: restart.demo ? null : (restart.attach || null), org: restart.demo ? null : (restart.org || null), mode: restart.demo ? null : (restart.mode || null), declined: restart.demo ? null : (restart.declined || null), bin: restart.bin || undefined };
   // QUOXON-RESTART-LEAK: under the launcher this process EXITS and the launcher runs the successor, so exactly one
   // client stays alive per terminal. Without one (QUOX_NO_LAUNCHER=1) it falls back to waiting on a nested child.
   const launched = takeLauncherHandoff();

package/lib/quoxon/markdown.js

@@ -63,7 +63,7 @@ export function inlineText(tokens = []) {
   return tokens.map(t => {
     if (t.tokens) return inlineText(t.tokens);
     if (t.type === 'br') return ' ';
-    return t.text ?? t.raw ?? '';
+    return typeof t.text === 'string' ? t.text : typeof t.raw === 'string' ? t.raw : ''; // never an object: it would print [object Object]
   }).join('').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
 }
 

package/lib/quoxon/model.js

@@ -90,6 +90,21 @@ export const choiceId = (ch) => (ch ? rowOf(ch)?.id || null : null);
 export const connectedChoices = (res, caps = null) =>
   CHOICES.filter(c => c.served !== false && availability(res, c, caps).state === 'connected');
 
+/** Health states that mean a provider refuses turns right now. */
+const REFUSING = new Set(['limited', 'no_credits']);
+/**
+ * The active model's provider is limited / out of credits: the first CHOICES row the server reports ready whose
+ * provider health does not also refuse turns. -> { id, label, why } | null (no usable alternative = no offer).
+ */
+export function limitedOffer(health, current, res, caps = null, mine = null) {
+  const bad = new Set((Array.isArray(health) ? health : []).filter(e => REFUSING.has(e?.state)).map(e => String(e.provider || '').toLowerCase()));
+  const active = String(current?.provider || mine || '').toLowerCase();
+  if (!active || !bad.has(active)) return null;
+  const alt = connectedChoices(res, caps).find(c => !bad.has(c.provider) && c.provider !== active);
+  if (!alt) return null;
+  return { id: alt.id, label: alt.name, why: alt.id === 'ollama' ? 'local Ollama, ready on this server' : 'ready on this server' };
+}
+
 const same = (a, b) => (a?.provider || null) === (b?.provider || null) && (a?.via || null) === (b?.via || null);
 
 /** -> [[text, tone?]] lines for /model. `caps` = api.capabilities() (the server's word on each provider). */

package/lib/quoxon/mouse.js

@@ -17,6 +17,17 @@
  */
 import { graphemes, composerFrom } from './textBuffer.js';
 
+/** The logical line (between newlines) holding buffer index `idx` -> { from, to }; a triple-click selects it. */
+export function lineAt(text, idx) {
+  const t = String(text);
+  const i = Math.max(0, Math.min(idx, t.length));
+  const from = t.lastIndexOf('\n', i - 1) + 1;
+  const nl = t.indexOf('\n', i);
+  return { from, to: nl < 0 ? t.length : nl };
+}
+
+export const MOUSE_HINT = 'Click your draft to place the cursor, drag to select (copies), double-click a word, triple-click a line. Shift+drag uses your terminal\'s own selection in most terminals. /mouse off gives native selection back.';
+
 export const MOUSE_ON = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
 export const MOUSE_OFF = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
 export const DSR = '\x1b[6n';
@@ -26,7 +37,7 @@ export const DOUBLE_MS = 400;
 export const DSR_TIMEOUT_MS = 400;
 
 export function mouseOnNote() {
-  return 'Mouse on. Click a ◆ sender to reply, click a card\'s y / n / c to answer, click or drag in your draft to place the cursor or select (Backspace deletes, typing replaces, double-click selects a word). While it is on your terminal sends clicks and the wheel to Quox: hold Shift to select or copy text (Option on macOS Terminal and iTerm2), and use Shift+wheel or the scrollbar to scroll back. /mouse off returns all of it.';
+  return 'Mouse on. Click a ◆ sender to reply, click a card\'s y / n / c to answer, click or drag in your draft to place the cursor or select (Backspace deletes, typing replaces, double-click selects a word, triple-click a line). While it is on your terminal sends clicks and the wheel to Quox: hold Shift to select or copy text (Option on macOS Terminal and iTerm2), and use Shift+wheel or the scrollbar to scroll back. /mouse off returns all of it.';
 }
 
 // ---- cell widths --------------------------------------------------------------------------------

package/lib/quoxon/neverAnswered.js

@@ -0,0 +1,20 @@
+/**
+ * ONBOARD-P2: has this profile's server ever answered from this machine?
+ * A profile that has not (no recorded health success, never signed in) and whose server is dead is a first-run
+ * problem (wrong address), not an outage, so the TUI offers to connect elsewhere instead of spinning "restarting".
+ */
+const HOUR = 3600 * 1000;
+
+export function isNeverAnswered(profile) {
+  if (!profile) return false;
+  if (profile.lastHealthyAt) return false;
+  if (profile.auth?.access_token) return false; // a sign-in worked once, so the server answered
+  return true;
+}
+
+/** The ISO time to record after a successful health probe, or null when a recent stamp already exists. */
+export function healthyStamp(profile, now = Date.now()) {
+  const prev = Date.parse(profile?.lastHealthyAt || '');
+  if (Number.isFinite(prev) && now - prev < HOUR) return null;
+  return new Date(now).toISOString();
+}