quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/motion/ring.js

@@ -0,0 +1,79 @@
+/**
+ * Composer ring (owner-approved lab prototype `quox-intro-lab rules`, plus the green writing sweep from
+ * `quox-intro-lab fx`). The two composer rules are one light ring: top rule left to right is the first half
+ * of the perimeter, bottom rule right to left the second. The gradient is the quox.ai panel ring:
+ * conic(cyan .85, purple .8 @35%, transparent @60%, teal .55 @85%, cyan .85). ~1 revolution / 2.5 s.
+ * Modes: work (cyan/purple), write (greens, while answer text streams), wait (slower amber, approval held).
+ * When the turn ends the sweep eases to a stop over ~400 ms. Pure state stepping; no timers here.
+ */
+import { mix, smooth, hexRgb } from './color.js';
+
+export const PALS = {
+  work: [[0x38, 0xbd, 0xf8], [0xa8, 0x55, 0xf7], [0x06, 0xb6, 0xd4]],
+  write: [[0x22, 0xc5, 0x5e], [0x4a, 0xde, 0x80], [0x16, 0xa3, 0x4a]],
+  wait: [[0xf5, 0x9e, 0x0b], [0xea, 0x58, 0x0c], [0xb4, 0x53, 0x09]],
+};
+const STOPS = [[0, 0, 0.85], [0.35, 1, 0.8], [0.6, 0, 0], [0.85, 2, 0.55], [1, 0, 0.85]];
+export const DIM = [58, 66, 82];
+export const OMEGA = 360 / 2.5;             // deg/s while working
+export const SPEED = { work: 1, write: 1, wait: 0.3 };
+export const SETTLE_S = 0.4, RAMP_S = 0.15, BLEND_S = 0.2;
+
+export const initialRing = () => ({ phase: 'idle', angle: 0, k: 0, om: 0, wt: { work: 1, write: 0, wait: 0 }, at: null, settleAt: null, from: null });
+
+/** Colour + alpha of the ring at perimeter position u in [0,1) for palette weights wt. */
+export function ringAt(u, wt) {
+  let i = 0; while (i < STOPS.length - 2 && u > STOPS[i + 1][0]) i++;
+  const [p0, c0, a0] = STOPS[i], [p1, c1, a1] = STOPS[i + 1];
+  const t = (u - p0) / (p1 - p0 || 1);
+  const col = (c) => [0, 1, 2].map((ch) => wt.work * PALS.work[c][ch] + wt.write * PALS.write[c][ch] + wt.wait * PALS.wait[c][ch]);
+  const A = a0 + (a1 - a0) * t;
+  const pm = mix(col(c0).map((v) => v * a0), col(c1).map((v) => v * a1), t); // premultiplied: the clear stop does not tint
+  return [A ? pm.map((v) => v / A) : col(c0), A];
+}
+
+/**
+ * Advance the ring to time `now` (ms). active = a turn is running; mode = 'work' | 'write' | 'wait'.
+ * Returns a new state; `animating` tells the clock whether frames are still wanted.
+ */
+export function ringStep(prev, { active, mode = 'work', now }) {
+  const s = { ...(prev || initialRing()), wt: { ...(prev || initialRing()).wt } };
+  const dt = s.at == null ? 0 : Math.max(0, Math.min(0.25, (now - s.at) / 1000));
+  s.at = now;
+  if (active) {
+    if (s.phase !== 'run') s.phase = 'run';
+    s.om = OMEGA * (SPEED[mode] ?? 1);
+    s.k = Math.min(1, s.k + dt / RAMP_S);
+    for (const m of Object.keys(s.wt)) s.wt[m] += ((m === mode ? 1 : 0) - s.wt[m]) * Math.min(1, dt / BLEND_S);
+  } else if (s.phase === 'run') {
+    s.phase = 'settle'; s.settleAt = now; s.from = { om: s.om, k: s.k };
+  }
+  if (s.phase === 'settle') {
+    const p = (now - s.settleAt) / 1000 / SETTLE_S;
+    if (p >= 1) { s.phase = 'idle'; s.k = 0; s.om = 0; } else { s.om = s.from.om * (1 - p) ** 2; s.k = s.from.k * (1 - smooth(p)); }
+  }
+  s.angle = (s.angle + s.om * dt) % 360;
+  return s;
+}
+export const ringAnimating = (s) => Boolean(s) && s.phase !== 'idle';
+
+/** Per-cell rgb for one rule of `cols` cells. base = the rule's static colour (hex or rgb). Pure. */
+export function ruleColors(cols, top, s, base) {
+  const b = Array.isArray(base) ? base : hexRgb(base);
+  const out = new Array(cols);
+  for (let x = 0; x < cols; x++) {
+    if (!s || s.k <= 0) { out[x] = b; continue; }
+    const pos = top ? (x + 0.5) / (2 * cols) : (cols + (cols - 1 - x) + 0.5) / (2 * cols);
+    const u = (((pos - s.angle / 360) % 1) + 1) % 1;
+    const [c, a] = ringAt(u, s.wt);
+    out[x] = mix(b, mix(DIM, c, a), s.k);
+  }
+  return out;
+}
+
+/** Which ring mode a live turn is in, from what the client actually knows. */
+export function ringMode({ approvals = 0, act = null } = {}) {
+  if (approvals > 0 || act?.tone === 'wait') return 'wait';
+  if (act?.word === 'Writing') return 'write';
+  return 'work';
+}

package/lib/quoxon/mouse.js

@@ -0,0 +1,211 @@
+/**
+ * QUOXON-MOUSE (owner 2026-10-15: "when I click on '◆ QLOOP-ENGINE' enter /say [slot]", "select a chunk of text I
+ * typed and delete it"). Optional, OFF by default: mouse tracking makes the terminal send clicks to Quox, so
+ * selecting or copying text then needs Shift+drag in most terminals (said when it is turned on).
+ *
+ * Pure parts only (the app wires them):
+ * - MOUSE_ON / MOUSE_OFF: SGR button tracking with drag (1000 + 1002 + 1006). Never any-motion (1003).
+ * - createScreenMirror: what Ink has put on the screen, as plain lines. Fed every string Ink writes (term.js), it
+ *   models exactly Ink's output: text, newlines, eraseLines (frame repaints) and clear-terminal. The live frame is
+ *   the last write; everything above it is static history. Wrapping is applied at the current width when read, so
+ *   a resize reflows it the way the terminal does.
+ * - screenHit: a click's screen row -> the mirror line under it. Rows are counted up from the cursor (which Ink
+ *   always leaves on the line after the frame), read with a cursor position report (DSR) at click time, so the
+ *   map holds whether the frame sits at the bottom of a full screen or halfway down a fresh one.
+ * - classifyClick: what that line is (a ◆ sender, a card's answer key label, the shared ask's y/N/c).
+ * - composerIndexAt: a click in the composer rows -> a buffer index, through Ink's word wrap.
+ */
+import { graphemes, composerFrom } from './textBuffer.js';
+
+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';
+/** Two presses on the same cell within this window are a double-click. */
+export const DOUBLE_MS = 400;
+/** How long a click waits for the terminal's cursor report before it is dropped. */
+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.';
+}
+
+// ---- cell widths --------------------------------------------------------------------------------
+const WIDE = /\p{Extended_Pictographic}/u;
+const EAW = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/u;
+/** Terminal cells one grapheme takes: 2 for emoji presentation and East Asian wide, else 1. */
+export function cellWidth(g) {
+  const cp = g.codePointAt(0);
+  if (EAW.test(g)) return 2;
+  if (WIDE.test(g) && (cp >= 0x1f000 || g.includes('️'))) return 2;
+  return 1;
+}
+const cellsOf = (s) => graphemes(String(s)).reduce((n, x) => n + cellWidth(x.text), 0);
+/** Grapheme index in `gs` covering 0-based cell `col` (gs.length when past the end). */
+function cellToIndex(gs, col) {
+  let at = 0;
+  for (let i = 0; i < gs.length; i++) { const w = cellWidth(gs[i].text); if (col < at + w) return i; at += w; }
+  return gs.length;
+}
+/** 1-based start cell of grapheme index `i`. */
+function indexToCell(gs, i) { let at = 1; for (let k = 0; k < i && k < gs.length; k++) at += cellWidth(gs[k].text); return at; }
+
+// ---- screen mirror ------------------------------------------------------------------------------
+const ANSI_RE = /\x1b\[[0-9;?<>=]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[()][0-9A-Za-z]|\x1b[=>78]/g;
+const ERASE_RE = /^((?:\x1b\[2K\x1b\[1A)*\x1b\[2K\x1b\[G)/;
+const CLEAR_RE = /\x1b\[2J|\x1bc/;
+
+/** Wrap one plain line into rows of at most `cols` cells (what the terminal shows). */
+function wrapRows(line, cols) {
+  if (!(cols > 0)) return [line];
+  const gs = graphemes(line);
+  if (!gs.length) return [''];
+  const out = []; let row = ''; let w = 0;
+  for (const g of gs) {
+    const cw = cellWidth(g.text);
+    if (w + cw > cols) { out.push(row); row = ''; w = 0; }
+    row += g.text; w += cw;
+  }
+  out.push(row);
+  return out;
+}
+
+export function createScreenMirror({ columns = () => null, cap = 3000 } = {}) {
+  let lines = ['']; // logical lines; the last one is the cursor line
+  let frameLen = 0; // logical lines written by the last write (the live frame, once Ink has written it)
+  const append = (text) => {
+    const parts = text.replace(ANSI_RE, '').replace(/\r/g, '').split('\n');
+    lines[lines.length - 1] += parts[0];
+    for (let i = 1; i < parts.length; i++) lines.push(parts[i]);
+    if (lines.length > cap) lines = lines.slice(lines.length - cap);
+    return parts.length - 1;
+  };
+  const m = {
+    /** One string Ink wrote, before any diffing. */
+    write(chunk) {
+      let s = String(chunk);
+      const clear = s.search(CLEAR_RE);
+      if (clear >= 0) {
+        const all = [...s.matchAll(/\x1b\[2J|\x1b\[3J|\x1b\[H|\x1bc/g)];
+        const last = all[all.length - 1];
+        s = s.slice(last.index + last[0].length);
+        lines = ['']; frameLen = 0;
+      }
+      const e = ERASE_RE.exec(s);
+      if (e) {
+        const n = (e[1].match(/\x1b\[2K/g) || []).length;
+        const drop = Math.min(n - 1, lines.length - 1);
+        lines.length -= drop;
+        lines[lines.length - 1] = '';
+        s = s.slice(e[1].length);
+      }
+      const plain = s.replace(ANSI_RE, '');
+      if (!plain) return;
+      const rows = append(s);
+      if (rows > 0) frameLen = rows;
+    },
+    /** Test helper: Ink repainting its frame as these lines. */
+    frame(fl) { m.write(`\x1b[2K\x1b[G${fl.join('\n')}\n`); },
+    /** Raw output we cannot place (a hand-over, a child on the terminal): forget what is above. */
+    reset() { lines = ['']; frameLen = 0; },
+    /** -> { rows, frameStart, staticRows, frameRows }: wrapped at the current width, cursor line excluded. */
+    snapshot() {
+      const cols = columns();
+      const body = lines.slice(0, -1);
+      const fl = Math.min(frameLen, body.length);
+      const stat = body.slice(0, body.length - fl).flatMap(l => wrapRows(l, cols));
+      const fr = body.slice(body.length - fl).flatMap(l => wrapRows(l, cols));
+      return { rows: [...stat, ...fr], frameStart: stat.length, staticRows: stat, frameRows: fr };
+    }
+  };
+  return m;
+}
+
+/** A click at 1-based (x, y) with the cursor on screen row `cursorRow` -> the line under it, or null. */
+export function screenHit(snap, cursorRow, x, y) {
+  if (!snap || !(cursorRow > 0)) return null;
+  const idx = snap.rows.length - (cursorRow - y);
+  if (y >= cursorRow || idx < 0 || idx >= snap.rows.length) return null;
+  return {
+    text: snap.rows[idx], col: x, inFrame: idx >= snap.frameStart,
+    frameRow: idx - snap.frameStart, frameLines: snap.rows.slice(snap.frameStart), rowsBelow: snap.rows.slice(idx + 1)
+  };
+}
+
+// ---- what was clicked ---------------------------------------------------------------------------
+const SENDER_RE = /^\s*◆ (\S+)( \(no reply address\))?/;
+const CARD_KEY_RE = /(?<![\w/])([ync]) (approve|deny|chat|yes)(?![\w])/g;
+const ASK_KEYS_RE = /(?<![\w/])(y|run)\/(N)\/(c)\s*$/;
+const isAskRow = (r) => /^\s*▶ /.test(r) && (ASK_KEYS_RE.test(r) || /\b[ync] (approve|deny|chat)\b/.test(r));
+
+/**
+ * -> { kind: 'sender', slot, who? } | { kind: 'key', key: 'y'|'n'|'c'|'run', source: 'approval'|'ask' } | null.
+ * A key needs the click ON its label. A card's labels count only in the live frame (a card is never answered from
+ * scrollback); an ask's y/N/c only when no newer ask sits below it on screen.
+ */
+export function classifyClick(hit) {
+  if (!hit || typeof hit.text !== 'string') return null;
+  const t = hit.text;
+  const gs = graphemes(t);
+  const s = SENDER_RE.exec(t);
+  if (s) return s[2] ? { kind: 'sender', slot: null, who: s[1] } : { kind: 'sender', slot: s[1].toLowerCase() };
+  const within = (from, len) => {
+    const gi = graphemes(t.slice(0, from)).length;
+    const a = indexToCell(gs, gi); const b = a + cellsOf(t.slice(from, from + len));
+    return hit.col >= a && hit.col < b;
+  };
+  if (hit.inFrame) {
+    CARD_KEY_RE.lastIndex = 0;
+    let m;
+    while ((m = CARD_KEY_RE.exec(t))) if (within(m.index, m[0].length)) return { kind: 'key', key: m[1], source: 'approval' };
+  }
+  const k = ASK_KEYS_RE.exec(t);
+  if (k && /^\s*▶ /.test(t)) {
+    if ((hit.rowsBelow || []).some(isAskRow)) return null;
+    const base = k.index + k[0].indexOf(k[1]);
+    const yPos = base, nPos = yPos + k[1].length + 1, cPos = nPos + 2;
+    if (within(yPos, k[1].length)) return { kind: 'key', key: k[1] === 'run' ? 'run' : 'y', source: 'ask' };
+    if (within(nPos, 1)) return { kind: 'key', key: 'n', source: 'ask' };
+    if (within(cPos, 1)) return { kind: 'key', key: 'c', source: 'ask' };
+  }
+  return null;
+}
+
+// ---- the composer -------------------------------------------------------------------------------
+const isRule = (r) => /^\s*─/.test(r || '');
+const isPrompt = (r) => /^› /.test(r || '') || r === '›';
+
+/**
+ * A click on frame row `row` (0-based), 1-based column `col` -> the buffer index under it, or null when the row is
+ * not one of the composer's. The composer is the "› " row right under a rule, down to the next rule.
+ */
+export function composerIndexAt(frameLines, row, col, buf) {
+  let top = -1;
+  for (let i = frameLines.length - 1; i >= 1; i--) if (isPrompt(frameLines[i]) && isRule(frameLines[i - 1])) { top = i; break; }
+  if (top < 0 || row < top) return null;
+  let bottom = top;
+  while (bottom < frameLines.length && !isRule(frameLines[bottom])) bottom++;
+  if (row >= bottom) return null;
+  if (!buf.text) return 0;
+  const lines = buf.text.split('\n');
+  const starts = []; { let o = 0; for (const l of lines) { starts.push(o); o += l.length + 1; } }
+  const from = composerFrom(buf);
+  let r = top;
+  for (let li = from; li < lines.length && r < bottom; li++) {
+    const T = graphemes(lines[li]);
+    let p = 0; let first = true;
+    const rest = () => T.slice(p).some(g => !/\s/.test(g.text)); // trailing spaces never take a row of their own
+    while (r < bottom && (first || rest())) {
+      const R = graphemes(String(frameLines[r]).replace(/\s+$/, '')).slice(2);
+      while (!first && p < T.length && /\s/.test(T[p].text) && R.length && !/\s/.test(R[0].text)) p++;
+      const take = Math.min(R.length, T.length - p);
+      if (r === row) {
+        const gi = Math.min(T.length, p + Math.min(cellToIndex(R, Math.max(0, col - 3)), take));
+        return starts[li] + (gi < T.length ? T[gi].index : lines[li].length);
+      }
+      p += Math.max(take, 0); r++; first = false;
+      if (take <= 0) break;
+    }
+  }
+  return buf.text.length;
+}
+

package/lib/quoxon/noai.js

@@ -0,0 +1,57 @@
+/**
+ * Z2H-R2B: what Quox does when NO AI provider is connected. A turn is answered locally (no server call),
+ * with a full friendly card; nothing here names one vendor as the default. "add a host" has a deterministic
+ * path that needs no AI.
+ */
+import { CHOICES } from './model.js';
+import { providerState } from './providers.js';
+
+export const NO_AI_STATUS = 'no AI connected';
+export const NO_AI_CARD = [
+  'No AI is connected yet. Pick one:',
+  '/connect openai (recommended), /connect anthropic, /connect ollama <host>, or /connect for the list.'
+];
+export const HOSTS_USAGE = '/hosts add';
+
+/** -> true when at least one provider is connected, false when readable and none is, null when nothing could be read. */
+export function anyProviderConnected(vault, caps) {
+  let known = false;
+  for (const c of CHOICES) {
+    const st = providerState({ cap: c.cap || c.id, vault: c.vault }, caps, vault).state;
+    if (st === 'connected') return true;
+    if (st !== 'unknown') known = true;
+  }
+  return known ? false : null;
+}
+
+export const asksAddHost = (text) => /^\s*(?:please\s+)?(?:(?:i\s+(?:want|need)\s+to|can\s+you|help\s+me|let'?s)\s+)?(?:add|connect|enrol+|enroll|register|onboard)\s+(?:a|my|another|the)?\s*(?:new\s+)?(?:host|server|machine|node|box)s?\b/i.test(String(text || '').replace(/[.?!]+\s*$/, ''));
+
+/** Z2H-R4: "watch my servers" and friends; watching starts with adding a host, which needs no AI. */
+export const asksWatchHosts = (text) => /^\s*(?:please\s+)?(?:(?:i\s+(?:want|need)\s+(?:you\s+)?to|can\s+you|help\s+me)\s+)?(?:watch|monitor|keep\s+an\s+eye\s+on|look\s+after|keep\s+watch\s+(?:on|over))\s+(?:my|our|the)\s+(?:\w+\s+)?(?:servers?|hosts?|machines?|nodes?|boxes|fleet|homelab|infrastructure|infra)\b/i.test(String(text || '').replace(/[.?!]+\s*$/, ''));
+
+/**
+ * The deterministic add-a-host lines. `base` = the server URL when known. `check` = the result of probing
+ * `${base}/install` ({ ok, status }) or null when it could not be read. Z2H-3c: a public install answered 503
+ * there (no QuoxAgent bundled), so the curl line we printed failed on the user's host; a failed probe now says
+ * so plainly instead of handing out a command that cannot work. Unreadable (null) keeps the old lines.
+ */
+export function addHostLines(base, check = null) {
+  const b = String(base || '').replace(/\/+$/, '') || '<your-quox-url>';
+  if (check && check.ok === false && Number(check.status) >= 400) {
+    return [
+      `This Quox cannot enrol hosts yet: its host installer is not available (${b}/install answered HTTP ${check.status}).`,
+      'The QuoxAgent installer is not bundled in this install, so the add-a-host command would fail on your machine.',
+      'Nothing was changed on either machine.'
+    ];
+  }
+  return [
+    'To add a host, no AI needed. On the machine you want to add, run:',
+    // REL-423: never `curl | sudo bash`: that pipe exits 0 when the download fails (TLS error, HTTP error) and runs
+    // whatever partial body arrived. Download to a temp file with curl -f, then run it, so a failure stops loudly.
+    // Two lines (shell continuation) so the TUI, which clips long lines, never cuts the command short.
+    `( f=$(mktemp) && trap 'rm -f "$f"' EXIT && curl -fsSL ${b}/install -o "$f" && \\`,
+    `  sudo bash "$f" --host-id <name> )`,
+    'Self-signed certificate? Run quox fleet enrol <name>: it prints this with the certificate pinned.',
+    'Then check it arrived with: quox fleet hosts'
+  ];
+}

package/lib/quoxon/objects/agent.js

@@ -0,0 +1,61 @@
+/**
+ * E4 agent card. Sources: the shipped assistant identity (name, tagline), the org agent record
+ * (description, status, model when its config carries one), the collector's agent -> tools map
+ * (GET /api/v1/tools/agents), slots (GET /api/v1/slots: a slot named after the agent, or assigned
+ * to it), and the agent's last AEE envelope (GET /aee/query?from=agent.<id>&limit=1) with its WARD
+ * receipt when verify-receipt answered. There is no per-agent model in the shipped config (models
+ * are routed per turn), so the model row appears only when the server record names one.
+ */
+import { seg, fit, ago, short, boxWidth } from './model.js';
+import { providerOf } from '../theme.js';
+
+/** The model an org agent record names, if any: config_json.{model,provider}. */
+export function modelOf(record) {
+  let cfg = record?.config_json ?? record?.config ?? null;
+  if (typeof cfg === 'string') { try { cfg = JSON.parse(cfg); } catch { cfg = null; } }
+  const model = cfg?.model || cfg?.llm?.model || null;
+  const provider = cfg?.provider || cfg?.llm?.provider || null;
+  return model || provider ? { model, provider } : null;
+}
+
+/** A slot belongs to an agent when it is named after it or assigned to it. */
+export function slotFor(slots, id) {
+  const n = String(id || '').toLowerCase();
+  return (slots || []).find(s => String(s.name || '').toLowerCase() === n || String(s.assigned_to || '').toLowerCase() === n) || null;
+}
+
+/**
+ * d: { id, name, tagline, description, status, record, tools: [] | null, slot, last: envelope | null,
+ *      lastErr, receipt: { ok, result } | null, now }
+ */
+export function agentCard(d, cols) {
+  const now = d.now ?? Date.now();
+  const w = boxWidth(cols, 72), inner = w - 4, nw = w < 56;
+  const nm = String(d.name || d.id || 'agent');
+  const tag = d.tagline ? (nw ? '' : ` · ${d.tagline}`) : '';
+  const right = d.slot ? (nw ? `slot ${d.slot.name}` : `slot ${d.slot.name} · ${d.slot.state || 'unknown'}`) : '';
+  const rows = [];
+  const L = (label, value, role = 'value') => [seg(label.padEnd(6), 'muted'), ...(Array.isArray(value) ? value : [seg(fit(value, inner - 6), role)])];
+  if (d.description) rows.push(L('role', d.description));
+  if (d.status && d.status !== 'active') rows.push(L('state', d.status, 'warn'));
+  const m = modelOf(d.record);
+  if (m) {
+    const p = providerOf(m.provider, m.model);
+    rows.push(L('model', [seg(fit(m.model || m.provider, inner - 6), p ? `provider:${p}` : 'value')]));
+  }
+  if (Array.isArray(d.tools)) rows.push(L('tools', d.tools.length ? `${d.tools.length}: ${d.tools.join(', ')}` : 'none assigned'));
+  else if (d.toolsErr) rows.push(L('tools', `could not read (${d.toolsErr})`, 'warn'));
+  if (d.slot?.holder_session && d.slot.state === 'held') rows.push(L('held', `by ${d.slot.holder_session}${d.slot.last_heartbeat_at ? ` · heartbeat ${ago(d.slot.last_heartbeat_at, now)} ago` : ''}`, 'muted'));
+  if (d.last) {
+    const what = d.last.payload?.tool_name || d.last.intent || 'action';
+    const when = d.last.ts ? `${ago(d.last.ts, now)} ago` : '';
+    const r = d.receipt?.ok ? d.receipt.result : null;
+    if (r?.status === 'WITNESSED') rows.push(L('last', [seg('◉ ', 'proto:ward'), seg(fit(`${what} · WARD seq ${r.entry?.seq} witnessed · ${when}`, inner - 8), 'muted')]));
+    else {
+      const w8 = r?.status === 'NOT_WITNESSED' ? 'not witnessed yet' : r?.status === 'UNTIPPED' ? `WARD seq ${r.entry?.seq}, no signed tip yet` : d.receipt && !d.receipt.ok ? 'WARD did not answer' : 'witness not checked';
+      rows.push(L('last', [seg('· ', 'muted'), seg(fit(`${what} · ${w8} · ${when} · ${short(d.last.id, 14)}`, inner - 8), 'muted')]));
+    }
+  } else if (d.lastErr) rows.push(L('last', `could not read (${d.lastErr})`, 'warn'));
+  else rows.push(L('last', 'no recorded action', 'muted'));
+  return { box: { width: w, title: `● ${nm.toUpperCase()}${tag}`, titleRole: `agent:${d.id || nm}`, right, rightRole: 'muted', border: 'violet' }, rows };
+}

package/lib/quoxon/objects/away.js

@@ -0,0 +1,72 @@
+/**
+ * E5 "While you were away": a factual digest since a moment, from GET /api/v1/away (collector). Every
+ * item carries the source that reported it and its time; nothing is summarised by a model. Sources the
+ * server could not read, or that went silent, come back in `blind` and are always named ("Can't see"),
+ * so an empty list never reads as an all clear it cannot vouch for.
+ */
+import { seg, fit, hhmm, plural, boxWidth, parseTs } from './model.js';
+
+/** Importance: approvals waiting first (they block work), then alerts, failures, then outcomes. */
+export const RANK = {
+  approval_waiting: 0, alert: 1, turn_failed: 2, objective_failed: 2, workflow_failed: 2,
+  approval_resolved: 3, objective_finished: 4, workflow_finished: 4, decision: 5
+};
+const GLYPH = {
+  approval_waiting: ['⚠ ', 'warn'], alert: ['⚠ ', 'warn'], turn_failed: ['✖ ', 'error'], objective_failed: ['✖ ', 'error'],
+  workflow_failed: ['✖ ', 'error'], approval_resolved: ['✔ ', 'ok'], objective_finished: ['✔ ', 'ok'],
+  workflow_finished: ['✔ ', 'ok'], decision: ['◆ ', 'indigo']
+};
+const rankOf = (it) => RANK[it?.kind] ?? 6;
+
+export function rankItems(items) {
+  return [...(items || [])].sort((a, b) => rankOf(a) - rankOf(b) || (parseTs(b.ts) ?? 0) - (parseTs(a.ts) ?? 0));
+}
+
+/** "5h", "45m", "2d" for the away window. */
+export function awayFor(sinceTs, now) {
+  const t = parseTs(sinceTs);
+  if (t == null) return '';
+  const m = Math.max(0, Math.round((now - t) / 60000));
+  if (m < 60) return `${m}m`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h}h` : `${Math.round(h / 24)}d`;
+}
+
+/** d: { since, items, blind, activity, compact?, max?, now } */
+export function awayCard(d, cols) {
+  const now = d.now ?? Date.now();
+  const w = boxWidth(cols, 96), inner = w - 4;
+  const items = rankItems(d.items);
+  const max = d.compact ? (d.max ?? 5) : items.length;
+  const shown = items.slice(0, max);
+  const rows = [];
+  const win = awayFor(d.since, now);
+  if (!items.length) rows.push([seg(d.standing && d.standing.count > 0 ? 'Nothing new needed you.' : 'Nothing needed you.', 'muted')]);
+  for (const it of shown) {
+    const [g, role] = GLYPH[it.kind] || ['· ', 'muted'];
+    const meta = `${it.source || '?'} · ${hhmm(it.ts) || 'time unknown'}`;
+    if (d.compact) {
+      rows.push([seg(g, role), seg(fit(it.title, Math.max(8, inner - 2 - meta.length - 2)), 'value'), seg(`  ${meta}`, 'muted')]);
+    } else {
+      rows.push([seg(g, role), seg(fit(it.title, inner - 2), 'value', rankOf(it) === 0)]);
+      rows.push([seg('  '), seg(fit(meta, inner - 2), 'muted')]);
+    }
+  }
+  if (items.length > shown.length) rows.push([seg(`+${items.length - shown.length} more · /away`, 'muted')]);
+  if (d.standing && d.standing.count > 0) rows.push([seg(fit(`${plural(d.standing.count, 'older item')} still need${d.standing.count === 1 ? 's' : ''} you · quox lucid`, inner), 'muted')]);
+  const act = d.activity;
+  if (act && act.total > 0 && !d.compact) {
+    const top = (act.agents || []).slice(0, 4).map(a => `${a.agent} ${a.count}`).join(', ');
+    rows.push([seg(' ')]);
+    rows.push([seg(fit(`${act.partial ? 'at least ' : ''}${plural(act.total, 'agent action')}${top ? `: ${top}` : ''}${act.source ? ` (${act.source})` : ''}`, inner), 'muted')]);
+  }
+  const blind = d.blind || [];
+  if (blind.length && d.compact) {
+    const what = blind.map(b => (b.reason ? `${b.source} (${b.reason})` : b.source)).join(', ');
+    rows.push([seg(fit(`Can't see: ${what}`, inner), 'faint')]);
+  } else if (blind.length) {
+    rows.push([seg("Can't see:", 'faint')]);
+    for (const b of blind) rows.push([seg('  '), seg(fit(`${b.source}${b.reason ? `: ${b.reason}` : ''}`, inner - 2), 'faint')]);
+  }
+  return { box: { width: w, title: `While you were away${win ? ` (${win})` : ''}`, titleRole: 'value', right: d.compact ? '' : `since ${hhmm(d.since)}`, rightRole: 'muted', border: items.some(i => rankOf(i) === 0) ? 'warn' : 'muted' }, rows };
+}

package/lib/quoxon/objects/crystal.js

@@ -0,0 +1,100 @@
+/**
+ * E3 Crystal eligibility, computed from a workflow's REAL execution history against quoxflow's
+ * crystalliser gate. There is no read-only eligibility route (POST /api/skills/from-execution is the
+ * check AND the crystallisation, a write), so the rule is ported here verbatim from
+ * quoxflow/src/pipeline/crystalliser.ts (analyseExecutionHistory + extractVariables):
+ *   >= 3 executions, >= 80% success, and every successful run follows one action sequence.
+ * Input mirrors that route's legacy path: completed + failed executions; a run's action log is
+ * output.action_log when the run recorded one, else the workflow definition's nodes (the route's
+ * synthetic log). The quoxflow route also reads its own execution-history table, which this
+ * client cannot see, so the card says what it counted.
+ */
+import { seg, fit, short, boxWidth, plural } from './model.js';
+
+export const MIN_EXECUTIONS = 3;
+export const MIN_SUCCESS_RATE = 0.8;
+
+/** crystalliser.ts analyseExecutionHistory, same order of checks and same reasons. */
+export function analyseExecutionHistory(executions) {
+  const count = executions.length;
+  const successCount = executions.filter(e => e.success).length;
+  const successRate = count > 0 ? successCount / count : 0;
+  if (count < MIN_EXECUTIONS) return { ready: false, reason: `Insufficient executions (${count}/${MIN_EXECUTIONS} required)`, confidence: 0, executionCount: count, successRate };
+  if (successRate < MIN_SUCCESS_RATE) return { ready: false, reason: `Low success rate (${(successRate * 100).toFixed(0)}% < ${MIN_SUCCESS_RATE * 100}% required)`, confidence: 0, executionCount: count, successRate };
+  const signatures = new Set(executions.filter(e => e.success).map(e => e.actionLog.map(a => a.action).join(',')));
+  if (signatures.size > 1) return { ready: false, reason: `Inconsistent action structure across runs (${signatures.size} different patterns)`, confidence: 0, executionCount: count, successRate };
+  const confidence = Math.min(Math.min(count / 10, 1) * 0.3 + successRate * 0.5 + 0.2, 1.0);
+  return { ready: true, confidence, executionCount: count, successRate };
+}
+
+/** crystalliser.ts extractVariables: params that vary between successful runs, by action position. */
+export function extractVariables(executions) {
+  const ok = executions.filter(e => e.success && e.actionLog.length > 0);
+  if (ok.length < 2) return [];
+  const vars = [];
+  ok[0].actionLog.forEach((first, idx) => {
+    for (const key of Object.keys(first.params || {})) {
+      const values = ok.map(e => e.actionLog[idx]?.params?.[key]).filter(v => v !== undefined);
+      if (new Set(values.map(v => JSON.stringify(v))).size > 1) vars.push({ name: key, values });
+    }
+  });
+  return vars;
+}
+
+/** Real executions (+ optional definition) -> crystalliser ExecutionRecords. */
+export function toRecords(executions, def) {
+  const synthetic = Array.isArray(def?.nodes) ? def.nodes.map(n => ({ action: n.type, params: n.config ?? n.data ?? {} })) : null;
+  return executions
+    .filter(e => e && (e.status === 'completed' || e.status === 'failed'))
+    .map(e => {
+      const log = Array.isArray(e.output?.action_log) ? e.output.action_log.map(a => ({ action: a.action, params: a.params || {} })) : synthetic;
+      return { id: e.id, success: e.status === 'completed', actionLog: log || [], logKnown: Array.isArray(e.output?.action_log) };
+    });
+}
+
+/** Successful runs still needed so both the count and the rate pass (consecutive successes from now). */
+export function runsNeeded(count, successes) {
+  for (let k = 0; k < 10000; k++) {
+    const n = count + k, s = successes + k;
+    if (n >= MIN_EXECUTIONS && s / n >= MIN_SUCCESS_RATE) return k;
+  }
+  return null;
+}
+
+/**
+ * d: { workflow: { id, name }, executions: [...completed and failed], def }
+ * -> view { box, rows }
+ */
+export function crystalCard(d, cols) {
+  const w = boxWidth(cols, 66), inner = w - 4, nw = w < 58;
+  const wf = d.workflow || {};
+  const recs = toRecords(d.executions || [], d.def);
+  const a = analyseExecutionHistory(recs);
+  const n = recs.length, s = recs.filter(r => r.success).length;
+  const pct = n ? Math.round((s / n) * 100) : 0;
+  const okRuns = recs.filter(r => r.success);
+  const sigs = new Set(okRuns.map(r => r.actionLog.map(x => x.action).join(',')));
+  const unknownLogs = okRuns.some(r => !r.logKnown);
+  const rows = [];
+  const check = (pass, name, value) => [seg(pass === null ? '○' : pass ? '✔' : '✖', pass === null ? 'faint' : pass ? 'ok' : 'warn'), seg(' '), seg(name.padEnd(nw ? 10 : 14), pass === null ? 'muted' : 'value'), seg(fit(value, inner - (nw ? 12 : 16)), 'muted')];
+  rows.push(check(n >= MIN_EXECUTIONS, 'runs', nw ? `${n} (needs ≥ ${MIN_EXECUTIONS})` : `${n}`.padEnd(11) + `needs ≥ ${MIN_EXECUTIONS}`));
+  rows.push(check(n ? s / n >= MIN_SUCCESS_RATE : false, nw ? 'success' : 'success rate', nw ? `${pct}% ${s}/${n} (≥ 80%)` : `${pct}%  ${s}/${n}  needs ≥ 80%`));
+  if (!okRuns.length) rows.push(check(null, 'structure', 'no successful run to compare'));
+  else if (unknownLogs && sigs.size === 1) rows.push(check(true, 'structure', nw ? `${okRuns.length}/${okRuns.length} same steps` : `${okRuns.length}/${okRuns.length} same steps (definition, no run log)`));
+  else rows.push(check(sigs.size === 1, 'structure', sigs.size === 1 ? (nw ? `${okRuns.length}/${okRuns.length} identical` : `${okRuns.length}/${okRuns.length} runs, identical action sequence`) : `${sigs.size} different action patterns`));
+  const vars = a.ready ? extractVariables(recs) : [];
+  if (a.ready) rows.push(check(true, 'variables', vars.length ? `${vars.map(v => v.name).join(', ')}${nw ? '' : ' (vary between runs)'}` : 'none vary between runs'));
+
+  const crystal = (d.executions || []).find(e => e?.output?.crystal_id);
+  let verdict;
+  if (crystal) verdict = [seg(fit(`Already runs as Crystal ${short(crystal.output.crystal_id, 10)}${crystal.output.execution_mode ? ` (${crystal.output.execution_mode} replay)` : ''}`, inner), 'teal', true)];
+  else if (a.ready) verdict = [seg(nw ? 'Eligible · meets the gate' : 'Eligible · meets the crystalliser gate', 'teal', true)];
+  else if (/Inconsistent/.test(a.reason || '')) verdict = [seg(fit(`Not eligible: runs follow ${sigs.size} different action patterns`, inner), 'warn', true)];
+  else {
+    const k = runsNeeded(n, s);
+    verdict = [seg(fit(k == null ? `Not eligible yet: ${a.reason}` : `Not eligible yet: needs ${plural(k, 'more successful run')}`, inner), 'warn', true)];
+  }
+  rows.push(verdict);
+  rows.push([seg(fit(nw ? `from ${plural(n, 'recorded run')}` : `from ${plural(n, 'recorded run')} · quoxflow's rule, ≤ 500 per status`, inner), 'faint')]);
+  return { box: { width: w, title: nw ? 'Crystal candidate' : `Crystal candidate · ${wf.name || wf.id || ''}`, right: '', border: 'teal' }, rows, analysis: a };
+}