quoxcli 0.3.1 → 0.4.0

package/lib/quoxon/loopCard.js

@@ -0,0 +1,456 @@
+/**
+ * QLOOP-LIVE: the live loop card. Pure: events in, state out, lines out. No React, no network, no clock of its own,
+ * so every state of the card can be rendered in a test from a recorded stream.
+ *
+ * The event contract is pinned in ~/quoxon-work/qloop-live-design.md section 1:
+ *   loop.started / loop.turn.started / loop.turn.output / loop.turn.tool / loop.turn.completed /
+ *   loop.observe / loop.ward / loop.approval / loop.finished     (each with event_seq, at, objective_id)
+ *
+ * The card is one live region per loop. It reads, top to bottom:
+ *   ∞ LOOP  <title>                                   ◐ turn 3/10 · 1m12s
+ *   ▕✔✔◐·······▏  receipts 2/2 witnessed ✔     host core-local · scope Read,Write
+ *   │ <spool: last 3 lines, wrapped, Enter expands>
+ *   ⋯ milestone: found 214 files
+ * Turn strip glyphs: ✔ ok · ⚠ denied / waiting for you · ✖ error · ◐ running · · pending.
+ * No grey text (house rule): every run uses a readable role. Nothing the user needs is cut: long text wraps.
+ */
+import { graphemes } from './textBuffer.js';
+import { cellWidth } from './cells.js';
+
+/** Below this width the card is one line (the full title is printed once in chat when the loop starts). */
+export const NARROW_COLS = 60;
+export const SPOOL_CAP = 8192;
+export const SPOOL_LINES = 3;
+export const SPOOL_LINES_EXPANDED = 16;
+export const STRIP_MAX = 24;
+export const REDRAW_MIN_MS = 125; // <= 8 redraws per second
+
+export const TERMINAL = new Set(['completed', 'completed_with_errors', 'failed', 'halted', 'interrupted']);
+const FINAL = {
+  completed: { glyph: '✔', role: 'ok', word: 'completed' },
+  completed_with_errors: { glyph: '⚠', role: 'warn', word: 'completed with errors' },
+  failed: { glyph: '✖', role: 'error', word: 'failed' },
+  halted: { glyph: '⚠', role: 'warn', word: 'halted' },
+  interrupted: { glyph: '⚠', role: 'warn', word: 'interrupted' },
+};
+const WITNESSED = new Set(['witnessed', 'signed', 'verified', 'ok']);
+const BAD_WARD = new Set(['failed', 'invalid', 'rejected', 'tampered', 'error']);
+const SPIN = ['◐', '◓', '◑', '◒'];
+
+/* ---- text helpers --------------------------------------------------------------------------- */
+
+const oneLine = (s) => String(s ?? '').replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, '').replace(/\r/g, '');
+const width = (s) => cellWidth(s);
+
+/** Wrap at spaces; a token longer than the line is broken by cells, never dropped. Keeps blank lines. */
+export function wrapText(text, w) {
+  const room = Math.max(4, w);
+  const out = [];
+  for (const raw of oneLine(text).split('\n')) {
+    if (!raw.trim()) { out.push(''); continue; }
+    let line = '';
+    for (const word of raw.split(/ +/)) {
+      if (!word) continue;
+      let rest = word;
+      while (width(rest) > room) { // hard-break an over-long token
+        if (line) { out.push(line); line = ''; }
+        let part = '', used = 0;
+        for (const g of graphemes(rest)) { const gw = width(g.text); if (used + gw > room) break; part += g.text; used += gw; }
+        if (!part) part = graphemes(rest)[0].text;
+        out.push(part); rest = rest.slice(part.length);
+      }
+      if (!line) line = rest;
+      else if (width(line) + 1 + width(rest) <= room) line += ' ' + rest;
+      else { out.push(line); line = rest; }
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+export function fmtElapsed(ms) {
+  const s = Math.max(0, Math.floor((Number(ms) || 0) / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m${String(s % 60).padStart(2, '0')}s`;
+  return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}m`;
+}
+
+/**
+ * A server stop reason for a human: the raw component prefix the spawner puts first (`fleetLoopSpawner: `) is dropped, the
+ * sentence is kept whole. Never shortened: the card wraps it.
+ */
+export function humanReason(r) {
+  return oneLine(r).replace(/^\s*[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*:\s+/, '').trim();
+}
+const STATE_ALIAS = { cancelled: 'halted', aborted: 'interrupted' };
+const isStop = (state) => state === 'failed' || state === 'interrupted';
+
+/* ---- state ---------------------------------------------------------------------------------- */
+
+const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : null);
+const t0 = (v) => { const t = Date.parse(v); return Number.isFinite(t) ? t : null; };
+
+export function initLoop({ id, title = '', agent = null } = {}) {
+  return {
+    id, title: oneLine(title), agent, state: 'running', done: false,
+    turn: 0, maxTurns: null, host: null, backend: null, scope: [],
+    startedAt: null, finishedAt: null, reason: null, turnsTotal: null,
+    turns: {}, // n -> { status: run|ok|warn|err, summary, errors, denied, ms }; n is the stream's `turn`
+    // A runner-driven loop's stream `turn` counts MODEL MESSAGES (several per runner turn: live 2026-10-26 it read "turn 9/5"). The loop's
+    // own turn is the runner's iteration: from the event when the server sends it, else the snapshot (loopCards refreshes it), else the
+    // runner's own "(turn N of M)" in an observe line. null = not a runner loop (or not known yet): the stream's turn is then the turn.
+    iteration: null,
+    receipts: {}, // envelope_id -> witnessed|pending|failed
+    finalReceipts: null, // { total, witnessed } from loop.finished or the snapshot: the server's own count
+    spool: '', spoolTurn: 0,
+    milestone: null, approval: null, stall: null,
+    conn: 'live', connAttempt: 0, connNote: null,
+    lastSeq: 0, lastEventAt: null,
+    observed: [], // lines appended to chat, kept for tests and /loop peek
+  };
+}
+
+const wardOf = (ev) => ev.status ?? (typeof ev.ward === 'string' ? ev.ward : ev.ward?.status) ?? ev.ward_status;
+/** A receipt's status never goes backwards: a late `pending` (the turn's own completion arriving after the ward event) must not un-witness it. */
+const setReceipt = (s, id, cls) => { if (id && !(s.receipts[id] === 'witnessed' && cls === 'pending')) s.receipts[id] = cls; };
+const wardClass = (status) => { const s = String(status || '').toLowerCase(); return WITNESSED.has(s) ? 'witnessed' : BAD_WARD.has(s) ? 'failed' : 'pending'; };
+
+/** A loop that stopped (failed / interrupted) failed at the turn it was on; one that was halted was cut off. The rest did not run. */
+function markStopped(s) {
+  const t = s.turns[s.turn]; if (!t) return;
+  if (isStop(s.state) && t.status !== 'err') s.turns[s.turn] = { ...t, status: 'err' };
+  else if (s.state === 'halted' && t.status === 'run') s.turns[s.turn] = { ...t, status: 'warn' };
+  else if (t.status === 'run') s.turns[s.turn] = { ...t, status: s.state === 'completed' ? 'ok' : 'warn' };
+}
+
+/** The snapshot (GET /api/v1/loops/:id) -> state. Tolerant of field spellings; never invents a field it was not given. */
+export function applySnapshot(st, snap) {
+  if (!snap || typeof snap !== 'object') return st;
+  const s = { ...st, turns: { ...st.turns }, receipts: { ...st.receipts } };
+  const loop = snap.loop && typeof snap.loop === 'object' ? { ...snap, ...snap.loop } : snap;
+  if (loop.title && !s.title) s.title = oneLine(loop.title);
+  const state0 = loop.state || loop.status, state = STATE_ALIAS[state0] || state0;
+  if (state && TERMINAL.has(state)) { s.state = state; s.done = true; s.reason = loop.reason ? humanReason(loop.reason) : s.reason; }
+  const it = num(loop.iteration); if (it != null) s.iteration = Math.max(s.iteration ?? 0, it);
+  const turn = it != null ? null : num(loop.turn ?? loop.current_turn); if (turn != null) s.turn = Math.max(s.turn, turn);
+  const max = num(loop.max_turns ?? loop.max); if (max != null) s.maxTurns = max;
+  if (loop.host) s.host = String(loop.host);
+  if (loop.backend) s.backend = String(loop.backend);
+  if (Array.isArray(loop.scope)) s.scope = loop.scope.map(String);
+  const started = t0(loop.started_at ?? loop.at); if (started != null) s.startedAt = started;
+  const fin = t0(loop.finished_at); if (fin != null) s.finishedAt = fin;
+  const runnerLoop = loop.iteration != null || loop.until != null; // its last_turns are keyed by the message counter: not turns
+  for (const t of runnerLoop ? [] : (Array.isArray(loop.turns) ? loop.turns : (Array.isArray(loop.last_turns) ? loop.last_turns : []))) {
+    const n = num(t.turn ?? t.n); if (n == null || s.turns[n]) continue;
+    const ts = String(t.status || t.state || '').toLowerCase();
+    const tools = Array.isArray(t.tools) ? t.tools : [];
+    const byTools = tools.some((x) => x && x.denied) ? 'warn' : tools.some((x) => x && x.ok === false) ? 'err' : 'ok';
+    s.turns[n] = { status: /err|fail/.test(ts) ? 'err' : /deny|warn|approval/.test(ts) ? 'warn' : /run|start/.test(ts) ? 'run' : byTools, summary: oneLine(t.summary || ''), errors: 0, denied: null };
+    const w = t.ward?.status ?? t.ward_status ?? (typeof t.ward === 'string' ? t.ward : null); if (w && t.envelope_id) setReceipt(s, t.envelope_id, wardClass(w));
+  }
+  // The snapshot's receipts: { total, witnessed, items:[{ envelope_id, status }] }. Items fill the map; the totals are the server's own count.
+  if (loop.receipts && typeof loop.receipts === 'object') {
+    for (const it of Array.isArray(loop.receipts.items) ? loop.receipts.items : []) if (it?.envelope_id) setReceipt(s, it.envelope_id, wardClass(it.status));
+    const total = num(loop.receipts.total), wit = num(loop.receipts.witnessed);
+    if (total != null && wit != null) s.finalReceipts = { total, witnessed: wit };
+  }
+  // NOT done here: the snapshot's last_event_seq is the NEWEST event; adopting it would drop the replayed events the stream is about to send.
+  if (s.done) markStopped(s);
+  return s;
+}
+
+/** A snapshot read only for the runner's progress (its own turn and budget): never changes the loop's state or the replay position. */
+export function applyProgress(st, snap) {
+  const loop = snap && typeof snap === 'object' ? (snap.loop && typeof snap.loop === 'object' ? { ...snap, ...snap.loop } : snap) : null;
+  if (!loop) return st;
+  const it = num(loop.iteration), max = num(loop.max_turns ?? loop.max);
+  if ((it == null || it <= (st.iteration ?? 0)) && (max == null || max === st.maxTurns)) return st;
+  return { ...st, iteration: it != null ? Math.max(st.iteration ?? 0, it) : st.iteration, maxTurns: max ?? st.maxTurns };
+}
+
+/**
+ * One event -> new state. Pure. An event with event_seq <= lastSeq has been seen (a resume replays the boundary): ignored.
+ */
+export function reduceLoop(st, ev) {
+  if (!ev || typeof ev.type !== 'string') return st;
+  const seq = num(ev.event_seq);
+  if (seq != null && seq <= st.lastSeq) return st;
+  const s = { ...st, turns: { ...st.turns }, receipts: { ...st.receipts }, observed: st.observed };
+  if (seq != null) s.lastSeq = seq;
+  const at = t0(ev.at); if (at != null) s.lastEventAt = at;
+  s.conn = 'live'; s.connAttempt = 0; s.connNote = null;
+  const turn = num(ev.turn);
+  const iter = num(ev.iteration ?? ev.loop_turn); if (iter != null) s.iteration = Math.max(s.iteration ?? 0, iter);
+  switch (ev.type) {
+    case 'loop.started':
+      s.startedAt = at ?? s.startedAt; s.host = ev.host ?? s.host; s.backend = ev.backend ?? s.backend;
+      if (Array.isArray(ev.scope)) s.scope = ev.scope.map(String);
+      s.maxTurns = num(ev.max_turns) ?? s.maxTurns; break;
+    case 'loop.turn.started':
+      if (turn != null) { s.turn = turn; s.turns[turn] = { status: 'run', summary: '', errors: 0, denied: null, startedAt: at }; s.spool = ''; s.spoolTurn = turn; }
+      s.stall = null; s.approval = null; break;
+    case 'loop.turn.output': {
+      if (turn != null && turn !== s.spoolTurn) { s.spool = ''; s.spoolTurn = turn; }
+      const joined = s.spool + oneLine(ev.chunk).replace(/\u001b\[[0-9;]*[A-Za-z]/g, '');
+      s.spool = joined.length > SPOOL_CAP ? joined.slice(-SPOOL_CAP) : joined;
+      s.stall = null; s.approval = null; break; // output means it is moving again: no longer waiting for you
+    }
+    case 'loop.turn.tool': {
+      const t = turn != null && s.turns[turn] ? { ...s.turns[turn] } : null;
+      s.stall = null; s.approval = null;
+      if (t) { if (ev.denied) t.denied = String(ev.denied); else if (ev.ok === false) t.errors = (t.errors || 0) + 1; if (ev.note) t.noted = oneLine(ev.note); s.turns[turn] = t; }
+      break;
+    }
+    case 'loop.turn.completed': {
+      if (turn == null) break;
+      const prev = s.turns[turn] || { errors: 0, denied: null };
+      s.turns[turn] = { ...prev, status: prev.errors ? 'err' : (prev.denied || prev.noted) ? 'warn' : 'ok', summary: oneLine(ev.summary || '').slice(0, 200) };
+      setReceipt(s, ev.envelope_id, wardClass(wardOf({ ward: ev.ward, ward_status: ev.ward_status })));
+      break;
+    }
+    case 'loop.ward':
+      setReceipt(s, ev.envelope_id, wardClass(wardOf(ev)));
+      break;
+    case 'loop.observe':
+      { // the runner states its budget and the turn it is about to take in its own words ("next check in 14s (turn 2 of 5)")
+        const m = /\(turn\s+(\d+)\s+of\s+(\d+)\)/i.exec(String(ev.text || ''));
+        if (m) { if (!s.maxTurns) s.maxTurns = Number(m[2]); s.iteration = Math.max(s.iteration ?? 0, Number(m[1]) - 1); }
+      }
+      if (ev.kind === 'milestone') s.milestone = oneLine(ev.text);
+      if (ev.kind === 'stall') s.stall = { text: oneLine(ev.text), at };
+      if (ev.kind === 'error' && turn != null && s.turns[turn]) s.turns[turn] = { ...s.turns[turn], errors: Math.max(1, s.turns[turn].errors || 0) };
+      break;
+    case 'loop.approval':
+      s.approval = { id: ev.checkpoint_id ?? null, what: oneLine(ev.what) };
+      if (s.turn && s.turns[s.turn]) s.turns[s.turn] = { ...s.turns[s.turn], status: s.turns[s.turn].status === 'run' ? 'warn' : s.turns[s.turn].status, waiting: true };
+      break;
+    case 'loop.finished':
+      s.state = TERMINAL.has(STATE_ALIAS[ev.state] || ev.state) ? (STATE_ALIAS[ev.state] || ev.state) : 'failed'; s.done = true; s.finishedAt = at ?? s.finishedAt;
+      s.turnsTotal = num(ev.turns) ?? s.turn; // the server's count; for a runner loop it is a message count, so the renderers prefer `iteration`
+      s.reason = ev.reason ? humanReason(ev.reason) : s.reason;
+      s.approval = null; s.stall = null;
+      if (num(ev.receipts) != null) s.finalReceipts = { total: num(ev.receipts), witnessed: num(ev.witnessed) ?? 0 };
+      markStopped(s);
+      break;
+    default: return st; // unknown event types are ignored, never fatal (forward compatible)
+  }
+  return s;
+}
+
+/** The connection to the stream (not the loop) changed. */
+export const setConn = (st, conn, { attempt = 0, note = null } = {}) => ({ ...st, conn, connAttempt: attempt, connNote: note });
+
+export function receiptCounts(st) {
+  const v = Object.values(st.receipts);
+  const own = { total: v.length, witnessed: v.filter(x => x === 'witnessed').length, failed: v.filter(x => x === 'failed').length };
+  const f = st.finalReceipts; // the server's own count wins when it is higher: a ward event may have been missed, never invented
+  return f && (f.total > own.total || f.witnessed > own.witnessed) ? { ...own, total: Math.max(f.total, own.total), witnessed: Math.max(f.witnessed, own.witnessed) } : own;
+}
+
+/**
+ * Where the card is drawn. A running loop's card (and a finished one you are still on) is PINNED above the composer, so a long
+ * answer or an approval card can never push it off the screen; its history slot is empty until it is let go, and then holds the
+ * frozen card in place, where the story was told.
+ */
+export const loopPinned = (card) => Boolean(card && (!card.state.done || card.focused));
+
+/* ---- chat lines (the loop's story) ---------------------------------------------------------- */
+
+/**
+ * The chat line an event appends beneath the card, or null. -> { text, tone? }. Observer points are the server's decision;
+ * this only formats what it sent. A turn completion with no observer point stays inside the card.
+ */
+export function observerLine(ev, st) {
+  if (!ev) return null;
+  const turn = st?.iteration ?? num(ev.turn) ?? st?.turn ?? 0; // the loop's own turn when it has one
+  if (ev.type === 'loop.observe') {
+    const text = oneLine(ev.text);
+    switch (ev.kind) {
+      case 'milestone': return { text: `∞ turn ${turn} │ milestone: ${text}` };
+      case 'error': return { text: `∞ turn ${turn} │ ${text}`, tone: 'error' };
+      case 'approval': return { text: `∞ turn ${turn} │ waiting for you: ${text}`, tone: 'warn' };
+      case 'stall': return { text: `∞ turn ${turn} │ ${text || 'no progress'}`, tone: 'warn' };
+      default: return { text: `∞ turn ${turn} │ ${text} ✔` };
+    }
+  }
+  if (ev.type === 'loop.approval') return { text: `∞ turn ${turn} │ paused: ${oneLine(ev.what)}. It is in your approvals.`, tone: 'warn' };
+  return null;
+}
+
+/** The finish line: `∞ QLOOP │ <title> │ <state>, n turns, n/n witnessed`. Always followed by the proof command. */
+export function finishLines(st) {
+  const f = FINAL[st.state] || FINAL.failed;
+  const r = receiptCounts(st), n = st.iteration ?? st.turnsTotal ?? st.turn;
+  const witnessed = r.total ? `${r.witnessed}/${r.total} witnessed` : 'no receipts yet';
+  const text = `∞ QLOOP │ ${st.title || st.id} │ ${f.word}, ${n} turn${n === 1 ? '' : 's'}, ${witnessed}${st.reason && st.state !== 'completed' ? ` (${humanReason(st.reason)})` : ''}`;
+  return [{ text, tone: st.state === 'completed' ? 'ok' : st.state === 'failed' ? 'error' : 'warn' }, { text: `Proof: quox loop status ${st.id}` }];
+}
+
+export function startLine(st) {
+  return { text: `∞ QLOOP │ ${st.title || `loop ${st.id}`} │ started${st.host ? ` on ${st.host}` : ''}. /loop peek ${st.id} for detail.` };
+}
+
+/* ---- the card ------------------------------------------------------------------------------- */
+
+const R = (t, role, bold) => ({ t, role, ...(bold ? { bold: true } : {}) });
+const runWidth = (rs) => rs.reduce((n, r) => n + width(r.t), 0);
+
+/** A runner loop knows its own turn (the iteration): turns before it are done, it is the one running, the rest are pending. */
+function runnerCell(st, n, frame) {
+  const it = st.iteration;
+  if (n < it) return R('✔', 'ok');
+  if (n > it) return R('·', 'prose');
+  if (st.done) return st.state === 'completed' ? R('✔', 'ok') : isStop(st.state) ? R('✖', 'error') : R('⚠', 'warn');
+  return st.approval ? R('⚠', 'warn') : R(SPIN[frame % 4], 'sky');
+}
+
+function stripCells(st, frame) {
+  let max = st.maxTurns || Math.max(st.iteration ?? st.turn, 1);
+  if (st.done && st.state === 'completed') max = Math.max(1, Math.min(max, st.iteration ?? (st.turnsTotal || st.turn || 1))); // it finished early: the runway it never used is not shown
+  const shown = Math.min(max, STRIP_MAX);
+  const first = max > STRIP_MAX ? Math.max(1, Math.min((st.iteration ?? st.turn) || 1, max) - Math.floor(STRIP_MAX / 2) + 1) : 1;
+  const start = Math.min(first, max - shown + 1);
+  const out = [];
+  for (let n = start; n < start + shown; n++) {
+    if (st.iteration != null) { out.push(runnerCell(st, n, frame)); continue; }
+    const t = st.turns[n];
+    if (!t) { out.push(R('·', 'prose')); continue; }
+    if (t.status === 'ok') out.push(R('✔', 'ok'));
+    else if (t.status === 'err') out.push(R('✖', 'error'));
+    else if (t.status === 'warn') out.push(R('⚠', 'warn'));
+    else out.push(R(st.done ? '⚠' : SPIN[frame % 4], st.done ? 'warn' : 'sky'));
+  }
+  return { cells: out, hidden: start > 1 };
+}
+
+/** Head status: glyph + words. */
+const pulseRole = (st, frame) => (st.done || frame % 4 < 2 ? 'brand' : 'sky'); // the ∞ breathes while the loop runs and holds still once it is over
+
+function headStatus(st, now, frame) {
+  const elapsed = st.startedAt != null ? fmtElapsed((st.finishedAt ?? now) - st.startedAt) : null;
+  const turn = `turn ${(st.iteration ?? st.turn) || 0}${st.maxTurns ? `/${st.maxTurns}` : ''}`;
+  if (st.done) {
+    const f = FINAL[st.state] || FINAL.failed, n = st.iteration ?? st.turnsTotal ?? st.turn;
+    return [R(`${f.glyph} `, f.role), R(`${f.word} · ${n} turn${n === 1 ? '' : 's'}${elapsed ? ` · ${elapsed}` : ''}`, f.role)];
+  }
+  if (st.startedAt == null && !st.turn) return [R('◐ ', 'sky'), R('waiting to start (approve it in /approvals)', 'warn')];
+  if (st.approval) return [R('⚠ ', 'warn'), R(`waiting for you · ${turn}${elapsed ? ` · ${elapsed}` : ''}`, 'warn')];
+  if (st.stall) return [R('⚠ ', 'warn'), R(`stalled · ${turn}${elapsed ? ` · ${elapsed}` : ''}`, 'warn')];
+  return [R(`${SPIN[frame % 4]} `, 'sky'), R(`${turn}${elapsed ? ` · ${elapsed}` : ''}`, 'text')];
+}
+
+/**
+ * The card as lines of coloured runs: [[{t, role, bold?}, ...], ...]. Width-aware; every line fits `cols`.
+ * opts: { cols, now, frame, expanded, focused, confirm, hint }  (hint: the pinned card says how to reach its keys)
+ */
+export function cardLines(st, { cols = 80, now = Date.now(), frame = 0, expanded = false, focused = false, confirm = false, hint = false } = {}) {
+  const w = Math.max(20, cols - 2); // the view indents the card by 2
+  const r = receiptCounts(st);
+  const lines = [];
+  const rc = r.total ? `${r.witnessed}/${r.total}` : '0/0';
+  const rcRole = r.failed ? 'error' : r.total && r.witnessed === r.total ? 'ok' : 'text';
+  const rcMark = r.failed ? ' ✖' : r.total && r.witnessed === r.total ? ' ✔' : r.total ? ' ◐' : '';
+
+  if (cols < NARROW_COLS) { // one line: the full title was printed when the loop started
+    const head = headStatus(st, now, frame);
+    const tail = [R(` ${rc}${rcMark}`, rcRole)];
+    const used = 2 + runWidth(head) + runWidth(tail) + 1;
+    const title = oneLine(st.title || st.id);
+    const room = Math.max(0, w - used);
+    let shown = title;
+    if (width(title) > room) { // the first cells that fit, then an ellipsis; the full title is one Enter away and in the start line
+      shown = ''; let sw = 0;
+      for (const x of graphemes(title)) { const gw = width(x.text); if (sw + gw > room - 1) break; shown += x.text; sw += gw; }
+      shown = room > 1 ? shown + '…' : '';
+    }
+    lines.push([R('∞ ', pulseRole(st, frame), true), ...head, ...tail, ...(shown ? [R(' ' + shown, 'text')] : [])]);
+    if (expanded) for (const l of wrapText(st.title || st.id, w - 2)) lines.push([R('  ' + l, 'text')]);
+    if (confirm) lines.push([R('Halt this loop? y to halt, any other key cancels', 'warn')]);
+    return lines;
+  }
+
+  // line 1: ∞ LOOP <title> ... status
+  const head = headStatus(st, now, frame);
+  const lead = [R('∞ ', pulseRole(st, frame), true), R('LOOP', 'brand', true), R('  ', 'text')];
+  const title = oneLine(st.title || st.id);
+  if (runWidth(lead) + width(title) + 2 + runWidth(head) <= w) {
+    const pad = w - runWidth(lead) - width(title) - runWidth(head);
+    lines.push([...lead, R(title, 'text', true), R(' '.repeat(pad), 'text'), ...head]);
+  } else { // a long title never shares the line with the status; it wraps under it
+    lines.push([...lead.slice(0, 2), R(' '.repeat(Math.max(1, w - 6 - runWidth(head))), 'text'), ...head]);
+    const wrapped = wrapText(title, w - 2); // capped at 2 lines (Enter expands): a long title is not laid out in full on every frame
+    const tl = expanded ? wrapped : wrapped.slice(0, 2);
+    if (tl.length < wrapped.length) { const last = [...graphemes(tl[1])]; while (last.length && width(last.map((x) => x.text).join('')) > w - 4) last.pop(); tl[1] = last.map((x) => x.text).join('') + '…'; }
+    for (const l of tl) lines.push([R('  ' + l, 'text', true)]);
+  }
+
+  // line 2: strip + receipts + where
+  const { cells, hidden } = stripCells(st, frame);
+  const strip = [R('▕', 'brand'), ...(hidden ? [R('…', 'prose')] : []), ...cells, R('▏', 'brand')];
+  const barN = Math.min(r.total, 8), barFill = r.total ? Math.round((r.witnessed / r.total) * barN) : 0;
+  const receipts = [R('  receipts ', 'label'), R(rc, rcRole, true), R(' witnessed' + rcMark, rcRole), ...(barN ? [R(' ' + '▰'.repeat(barFill) + '▱'.repeat(barN - barFill), rcRole)] : [])]; // fills as the receipts land
+  const where = [];
+  if (st.host) where.push(R('host ', 'label'), R(st.host, 'text'));
+  if (st.scope.length) { if (where.length) where.push(R(' · ', 'prose')); where.push(R('scope ', 'label'), R(st.scope.join(','), 'text')); }
+  const base = [...strip, ...receipts];
+  if (!where.length) lines.push(base);
+  else if (runWidth(base) + 3 + runWidth(where) <= w) lines.push([...base, R('   ', 'text'), ...where]);
+  else { lines.push(base); lines.push([R('  ', 'text'), ...where]); } // the scope list may wrap further
+  if (lines[lines.length - 1].length && runWidth(lines[lines.length - 1]) > w) { // a very long scope: wrap it as plain text
+    const last = lines.pop(); const flat = last.map(x => x.t).join('');
+    for (const l of wrapText(flat.trim(), w - 2)) lines.push([R('  ' + l, 'text')]);
+  }
+
+  // waiting / stalled / connection
+  if (st.approval) for (const l of wrapText(`waiting for you: ${st.approval.what}. Open your approvals to answer.`, w - 2)) lines.push([R('⚠ ', 'warn'), R(l, 'warn')]);
+  if (st.stall && !st.done) for (const l of wrapText(st.stall.text || 'no turn progress', w - 2)) lines.push([R('⚠ ', 'warn'), R(l, 'warn')]);
+  if (st.conn === 'reconnecting') lines.push([R('◐ ', 'sky'), R(`stream dropped, reconnecting (attempt ${st.connAttempt})`, 'warn')]);
+  if (st.conn === 'lost') for (const l of wrapText(`lost the live stream${st.connNote ? `: ${st.connNote}` : ''}. The loop itself may still be running: quox loop status ${st.id}`, w - 2)) lines.push([R('✖ ', 'error'), R(l, 'error')]);
+  if (st.done && st.reason && st.state !== 'completed') for (const l of wrapText(`reason: ${humanReason(st.reason)}`, w - 2)) lines.push([R('  ', 'text'), R(l, FINAL[st.state]?.role || 'text')]);
+
+  // spool
+  // The milestone is said once: the spool's copy of it is dropped (the ticker line below carries it) and, when the loop is over
+  // and the chat story already said it, the ticker goes too.
+  let spoolText = st.spool.replace(/\s+$/g, '');
+  if (st.milestone) {
+    const words = st.milestone.trim().split(/\s+/).map((x) => x.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    if (words.length) spoolText = spoolText.replace(new RegExp(`(?:MILESTONE:\\s*)?${words.join('\\s+')}`, 'i'), '').replace(/\n{3,}/g, '\n\n').replace(/\s+$/g, '');
+  }
+  if (spoolText) {
+    const all = wrapText(spoolText, w - 4).filter((l, i, a) => l || (i > 0 && i < a.length - 1));
+    const keep = expanded ? SPOOL_LINES_EXPANDED : SPOOL_LINES;
+    const tail = all.slice(-keep), cut = all.length - tail.length;
+    if (cut > 0) lines.push([R('│ ', 'brand'), R(`${cut} earlier line${cut === 1 ? '' : 's'}${expanded ? '' : ' (Enter shows more)'}`, 'label')]);
+    tail.forEach((l) => lines.push([R('│ ', 'brand'), R(l, 'text')])); // no per-line prefix beyond the bar: a prefix would push the wrap past the width
+  }
+  if (st.milestone && !(st.done && st.observed.some((l) => String(l).includes(st.milestone)))) for (const l of wrapText(`milestone: ${st.milestone}`, w - 2)) lines.push([R('⋯ ', 'violet'), R(l, 'text')]);
+  if (expanded && !spoolText) lines.push([R('│ ', 'brand'), R(st.done ? 'no output was captured' : 'no output yet this turn', 'label')]);
+
+  if (confirm) lines.push([R('⚠ ', 'warn'), R('Halt this loop? y to halt, any other key cancels', 'warn', true)]);
+  else if (focused && !st.done) lines.push([R('Enter ', 'key'), R('expand output · ', 'label'), R('s ', 'key'), R('halt · ', 'label'), R('Esc ', 'key'), R('collapse', 'label')]);
+  else if (focused) lines.push([R('Enter ', 'key'), R('expand · ', 'label'), R('Esc ', 'key'), R('back', 'label')]);
+  else if (hint && !st.done) lines.push([R('↓ ', 'key'), R('to control this loop (Enter expand · s halt)', 'label')]); // an EMPTY composer + Down focuses it; no letter is ever taken from a draft
+  return lines;
+}
+
+/* ---- redraw throttle ------------------------------------------------------------------------ */
+
+/**
+ * Coalesces calls so `fn` runs at most once per `minMs` (trailing edge kept, so the last state always lands).
+ * `timer(fn, ms)` returns a cancel function; injectable for tests.
+ */
+export const REDRAW_UNFOCUSED_MS = 500; // a card nobody is focused on redraws at most twice a second
+export function createThrottle(fn, { minMs = REDRAW_MIN_MS, now = Date.now, timer = (f, ms) => { const t = setTimeout(f, ms); t.unref?.(); return () => clearTimeout(t); } } = {}) {
+  let last = -Infinity, cancel = null, pending = false;
+  const fire = () => { cancel = null; pending = false; last = now(); fn(); };
+  return {
+    poke() {
+      if (cancel) { pending = true; return; }
+      const wait = last + (typeof minMs === 'function' ? minMs() : minMs) - now();
+      if (wait <= 0) fire(); else { pending = true; cancel = timer(fire, wait); }
+    },
+    dispose() { cancel?.(); cancel = null; pending = false; },
+    get pending() { return pending; },
+  };
+}

package/lib/quoxon/loopCards.js

@@ -0,0 +1,180 @@
+/**
+ * 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);
+  /**
+   * 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.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();
+  }
+
+  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) => { 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) => 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 }); }
+      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 };
+      cards.set(id, c);
+      if (announce) { const l = startLine(c.state); say(l.text, l.tone); } // the start line first, then the card, then the story beneath
+      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.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 };