quoxcli 0.2.0 → 0.4.0

package/lib/dragon/jobs.js

@@ -0,0 +1,123 @@
+/**
+ * Dragon jobs: each companion dragon has ONE truthful job, and its caption comes from a real read.
+ *   sentinel  WARD state of the last answer's envelope (POST /ward/verify-receipt, the route /proof uses)
+ *   cipher    route health: kuma monitors up/down (the `quox kuma` read)
+ *   seer      the plan: QuoxPlan focus stream and x of y phases
+ *   hyperion  fleet: hosts up of total (the Bastion host read)
+ *   drago     open security findings (the engagement store)
+ *   lucid     recovery: the last failure this session saw, and whether a later turn completed (no network read)
+ * Rules: every read is bounded (timeoutMs); a failed or silent read says "Couldn't check <thing> (<why>)" and never a number;
+ * results (failures too) are cached for JOB_TTL_MS so a dragon that appears often does not hammer the server; nothing here
+ * polls, run() is only called when the dragon is about to be shown; read-only. Pure apart from the injected reads.
+ * A result is { caption, mood } where mood is 'ok' | 'concerned' | null (null = unknown or neutral). The host may pick a
+ * concerned scene for 'concerned'; it never celebrates on null.
+ */
+export const JOB_FOR = Object.freeze({ sentinel: 'ward', cipher: 'routes', seer: 'plan', hyperion: 'fleet', drago: 'findings', lucid: 'recovery' });
+export const JOB_TTL_MS = 30000;
+export const JOB_TIMEOUT_MS = 6000;
+const LABEL = { ward: 'WARD', routes: 'routes', plan: 'plan', fleet: 'fleet', findings: 'findings' };
+const READ_FOR = { ward: 'verifyReceipt', routes: 'routes', plan: 'plan', fleet: 'fleet', findings: 'findings' };
+
+const why = (e) => (e?.status ? `HTTP ${e.status}` : /timed out/i.test(e?.message || '') ? 'timed out' : String(e?.message || 'failed').slice(0, 60));
+const ago = (ms) => { const m = Math.floor(ms / 60000); return m < 1 ? 'under a minute ago' : m < 60 ? `${m} min ago` : m < 1440 ? `${Math.floor(m / 60)} h ago` : `${Math.floor(m / 1440)} d ago`; };
+const failed = (job, reason) => ({ caption: `Couldn't check ${LABEL[job]} (${reason}).`, mood: null });
+
+/** Pure: a read's data -> { caption, mood }. */
+export function captionFor(job, d) {
+  if (job === 'ward') {
+    const r = d?.result || {}, seq = r.entry?.seq;
+    if (r.status === 'WITNESSED') return { caption: `Last answer witnessed by WARD (seq ${seq}, signed tip).`, mood: 'ok' };
+    if (r.status === 'UNTIPPED') return { caption: `Last answer recorded (seq ${seq}) but no signed tip yet.`, mood: null };
+    if (r.status === 'NOT_WITNESSED') return { caption: 'Last answer not witnessed yet.', mood: null };
+    if (r.status) return { caption: `WARD check failed: ${r.status}${r.reason ? ` ${r.reason}` : ''}.`, mood: 'concerned' };
+    return failed('ward', 'no status in the answer');
+  }
+  if (job === 'routes') {
+    if (!d.total) return { caption: 'No monitors to read.', mood: null };
+    const stale = d.ageSeconds > 600 ? ` (snapshot ${Math.round(d.ageSeconds / 60)} min old)` : '';
+    if (d.down > 0) return { caption: `Routes: ${d.up} of ${d.total} up. Down: ${d.downNames.slice(0, 3).join(', ')}${d.downNames.length > 3 ? ` and ${d.downNames.length - 3} more` : ''}.`, mood: 'concerned' };
+    if (d.up < d.total) return { caption: `Routes: ${d.up} of ${d.total} up${stale}.`, mood: null }; // pending, maintenance, unknown: not counted up
+    const ping = Number.isFinite(d.avgPing) && !stale ? `, average ${Math.round(d.avgPing)} ms` : '';
+    return { caption: `Routes: ${d.up} of ${d.total} up${stale || ping}.`, mood: stale ? null : 'ok' };
+  }
+  if (job === 'plan') {
+    if (!d) return { caption: 'Nothing in focus on the plan.', mood: null };
+    if (d.total === 0) return { caption: `Plan: ${d.id} (no phases listed).`, mood: null };
+    return { caption: Number.isFinite(d.total) ? `Plan: ${d.id}, ${d.done} of ${d.total} phases.` : `Plan: ${d.id} (phases not read).`, mood: null };
+  }
+  if (job === 'fleet') {
+    if (!d.total) return { caption: 'No hosts to read.', mood: null };
+    const bits = ['degraded', 'unhealthy', 'offline', 'unknown'].filter(k => d[k]).map(k => `${d[k]} ${k}`);
+    return { caption: `Fleet: ${d.healthy} of ${d.total} hosts up${bits.length ? ` (${bits.join(', ')})` : ''}.`, mood: d.healthy === d.total ? 'ok' : 'concerned' };
+  }
+  if (job === 'findings') {
+    if (!d.open) return { caption: 'No open security findings recorded.', mood: 'ok' };
+    return { caption: `Open findings: ${d.open}${d.severe ? ` (${d.severe} critical or high)` : ''}.`, mood: d.severe ? 'concerned' : null };
+  }
+  return null;
+}
+
+/**
+ * reads: { verifyReceipt(envelopeId), routes(), plan(), fleet(), findings() }, each resolving to data or throwing (verifyReceipt may
+ * resolve { ok:false, error }). context(): { envelopeId } of the last answer. observe(event): the session's own events (lucid).
+ */
+export function createDragonJobs({ reads = {}, context = () => ({}), now = Date.now, ttlMs = JOB_TTL_MS, timeoutMs = JOB_TIMEOUT_MS } = {}) {
+  const cache = new Map(), inflight = new Map();
+  let lastFailure = null, recoveredAt = null;
+  const keyOf = (job) => (job === 'ward' ? `ward:${context()?.envelopeId || ''}` : job);
+
+  function recovery() {
+    if (!lastFailure) return { caption: 'No failures seen in this session.', mood: null };
+    const when = ago(now() - lastFailure.at);
+    return recoveredAt != null
+      ? { caption: `Recovered: ${lastFailure.what} ${when}, a later turn completed.`, mood: 'ok' }
+      : { caption: `Last failure: ${lastFailure.what} ${when}, not recovered yet.`, mood: 'concerned' };
+  }
+  async function fetchOne(job) {
+    const read = reads[READ_FOR[job]];
+    if (typeof read !== 'function') return null;
+    let timer;
+    try {
+      const arg = job === 'ward' ? context()?.envelopeId : undefined;
+      const data = await Promise.race([
+        Promise.resolve().then(() => read(arg)),
+        new Promise((_, rej) => { timer = setTimeout(() => rej(new Error('timed out')), timeoutMs); timer.unref?.(); }),
+      ]);
+      if (job === 'ward' && data && data.ok === false) return failed(job, data.error || 'failed');
+      return captionFor(job, data);
+    } catch (e) { return failed(job, why(e)); }
+    finally { clearTimeout(timer); }
+  }
+
+  return {
+    /** Feed the session's events (turn.finished, error): the only input lucid's job has. */
+    observe(ev) {
+      if (!ev) return;
+      if (ev.type === 'error') { lastFailure = { at: now(), what: 'stream error' }; recoveredAt = null; }
+      else if (ev.type === 'turn.finished') {
+        if (ev.status === 'failed' || ev.status === 'unconfirmed') { lastFailure = { at: now(), what: `turn ${ev.status}` }; recoveredAt = null; }
+        else if (ev.status === 'completed' && lastFailure && recoveredAt == null) recoveredAt = now();
+      }
+    },
+    peek(dragonId) {
+      const job = JOB_FOR[dragonId];
+      if (!job) return null;
+      if (job === 'recovery') return recovery();
+      const hit = cache.get(keyOf(job));
+      return hit && now() - hit.at < ttlMs ? hit.value : null;
+    },
+    /** The dragon's job result, from cache (30 s) or one bounded read. null = this dragon has no job here. */
+    async run(dragonId) {
+      const job = JOB_FOR[dragonId];
+      if (!job) return null;
+      if (job === 'recovery') return recovery();
+      if (job === 'ward' && !context()?.envelopeId) return { caption: 'No receipt to check yet: nothing from this session is witnessed.', mood: null };
+      const key = keyOf(job), hit = cache.get(key);
+      if (hit && now() - hit.at < ttlMs) return hit.value;
+      if (inflight.has(key)) return inflight.get(key);
+      const p = fetchOne(job).then((value) => { if (value) cache.set(key, { at: now(), value }); return value; }).finally(() => inflight.delete(key));
+      inflight.set(key, p);
+      return p;
+    },
+  };
+}

package/lib/dragon/renderWorker.js

@@ -0,0 +1,15 @@
+/** Worker thread: loads one dragonlab character and renders frames on request, so the TUI thread never does. See frames.js. */
+import { parentPort, workerData } from 'node:worker_threads';
+import { pathToFileURL } from 'node:url';
+
+const { root, id } = workerData;
+const mod = await import(pathToFileURL(`${root}/integration/companions-v1/characters.mjs`).href);
+const actor = await mod.loadCharacter(id);
+parentPort.on('message', ({ seq, req }) => {
+  try {
+    const r = actor.render(req.scene, req.time, { cols: req.cols, rows: req.rows, still: req.still, mono: req.mono, motionTime: req.motionTime });
+    if (!r || !r.ok) parentPort.postMessage({ type: 'error', seq, code: r?.code || 'render failed' });
+    else parentPort.postMessage({ type: 'frame', seq, frame: r.frame });
+  } catch (e) { parentPort.postMessage({ type: 'error', seq, code: e.message }); }
+});
+parentPort.postMessage({ type: 'ready' });

package/lib/dragon/select.js

@@ -0,0 +1,72 @@
+/**
+ * Dragon companions (Lucid, Hyperion, Seer, Sentinel, Drago, Cipher): which one, whether to show it, and where its art lives.
+ * Pure. The art, animation and activity reducer stay in quoxai/dragonlab (integration/companions-v1);
+ * Quox only chooses and loads. See docs/dragons/COMPANION-UX.md for the decisions behind each rule.
+ */
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The dragonlab art bundled with the CLI (cli/vendor/dragonlab, refreshed by scripts/sync-dragonlab.sh). */
+export const VENDORED_DRAGONLAB = fileURLToPath(new URL('../../vendor/dragonlab', import.meta.url));
+
+/** Registry agent ids (and display names) to approved dragon. Others, including quox/commanderq, get none. */
+export const AGENT_DRAGON = Object.freeze({ lucid: 'lucid', hyperion: 'hyperion', atlas: 'hyperion', seer: 'seer', sentinel: 'sentinel', warden: 'sentinel', security_lead: 'drago', drago: 'drago', cipher: 'cipher' });
+export const COMPANION_MODES = ['on', 'greeting', 'off'];
+/** One-line change: the owner decides this after his Mac check (docs/dragons/COMPANION-UX.md section 4). */
+export const DEFAULT_COMPANION_MODE = 'on';
+
+export function dragonForAgent(agent) {
+  const k = String(agent ?? '').trim().toLowerCase();
+  return Object.hasOwn(AGENT_DRAGON, k) ? AGENT_DRAGON[k] : null;
+}
+
+export function normaliseMode(v) {
+  const s = String(v ?? '').trim().toLowerCase();
+  return COMPANION_MODES.includes(s) ? s : null;
+}
+
+/** env QUOX_DRAGON_COMPANION beats the saved profile setting beats the default. */
+export function companionMode(settings = {}, env = process.env) {
+  return normaliseMode(env.QUOX_DRAGON_COMPANION) || normaliseMode(settings?.dragonCompanion) || DEFAULT_COMPANION_MODE;
+}
+
+/**
+ * Motion policy from the existing Quox switches. lite or a dumb terminal = off; reduced motion = still
+ * (no entrance, every channel frozen, captions still update); NO_COLOR = mono render.
+ */
+export function motionPolicy(env = process.env) {
+  const lite = Boolean(env.QUOX_TUI_LITE) || env.TERM === 'dumb';
+  const quiet = env.QUOX_REDUCED_MOTION === '1' || String(env.QUOX_MOTION || '').trim().toLowerCase() === 'quiet';
+  return { off: lite, still: quiet, mono: 'NO_COLOR' in env };
+}
+
+/**
+ * Where dragonlab lives: QUOX_DRAGONLAB beats the saved quoxon.dragonLab beats `bundled` (hosts pass
+ * VENDORED_DRAGONLAB). With no bundled path and no override, null = art not available.
+ */
+export function dragonLabRoot(settings = {}, env = process.env, bundled = null) {
+  const p = env.QUOX_DRAGONLAB || settings?.dragonLab;
+  if (typeof p === 'string' && p.trim()) return resolve(p.trim());
+  return bundled ? resolve(bundled) : null;
+}
+export const companionModuleFile = (root, id) => join(root, 'integration', 'companions-v1', `${id}.mjs`);
+export const viewModuleFile = (root) => join(root, 'integration', 'companions-v1', 'view.mjs');
+
+/**
+ * Everything a host needs, or { enabled:false, why } (the reason is what `/dragon companion status` prints).
+ * `exists` is injected so this stays pure.
+ */
+export function companionPlan({ agent, settings = {}, env = process.env, isTTY = true, exists = () => true, bundled = null }) {
+  const mode = companionMode(settings, env), policy = motionPolicy(env);
+  const id = dragonForAgent(agent);
+  const no = (why) => ({ enabled: false, why, mode, id });
+  if (mode === 'off') return no('companion is off');
+  if (!isTTY) return no('output is not a terminal');
+  if (policy.off) return no('QUOX_TUI_LITE or a dumb terminal turns decoration off');
+  if (!id) return no(agent ? `${agent} has no approved dragon` : 'no agent attached');
+  const root = dragonLabRoot(settings, env, bundled);
+  if (!root) return no('dragon art not found (the bundled copy is missing; set QUOX_DRAGONLAB or quoxon.dragonLab to a dragonlab checkout)');
+  const file = companionModuleFile(root, id);
+  if (!exists(file) || !exists(viewModuleFile(root))) return no(`dragon art not found at ${root}`);
+  return { enabled: true, mode, id, root, file, viewFile: viewModuleFile(root), still: policy.still, mono: policy.mono, persist: mode === 'on' };
+}

package/lib/evidence/bundleExport.js

@@ -0,0 +1,47 @@
+/**
+ * Fetch one conversation's signed evidence zip, write it, verify what was written. One implementation for
+ * `quox evidence bundle` and the TUI's /evidence. The server scopes by the caller's org and refuses anything else.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { verifyEvidenceBundle } from './bundleVerify.js';
+
+export function defaultBundlePath(corr, now = new Date()) {
+  const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const safe = String(corr).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 60);
+  return path.join(os.homedir(), 'quox-evidence', `${safe}-${ts}.zip`);
+}
+
+/** -> the id of the caller's newest chat conversation, or null. */
+export async function newestConversationId(client) {
+  const ep = resolveEndpoint('conversations.chat.list');
+  const data = await client.get(ep.path, { service: ep.service, query: { limit: 1 } });
+  const c = (data && data.conversations && data.conversations[0]) || null;
+  return c ? c.id : null;
+}
+
+/**
+ * @returns {Promise<{ path: string, corr: string, bytes: number, envelopes: number, receipts: number, verify: object }>}
+ * @throws Error with the HTTP status named when the server refuses (404 = not your conversation or no evidence).
+ */
+export async function exportConversationBundle({ client, corr, out, now = new Date() }) {
+  const ep = resolveEndpoint('evidence.bundle', { corr });
+  const res = await client.get(ep.path, { service: ep.service, query: { format: 'zip' }, raw: true, timeout: 120000 });
+  if (!res.ok) {
+    let detail = res.statusText;
+    try { const j = await res.json(); detail = j.error || JSON.stringify(j); } catch { /* keep statusText */ }
+    const e = new Error(res.status === 404
+      ? `No evidence for conversation ${corr} in your org (HTTP 404: ${detail}). Tool calls made before this fix are filed under per-command ids and are not part of the conversation.`
+      : `Evidence bundle failed: HTTP ${res.status}: ${detail}`);
+    e.status = res.status;
+    throw e;
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  const file = path.resolve(out || defaultBundlePath(corr, now));
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, buf);
+  const verify = await verifyEvidenceBundle(fs.readFileSync(file)); // what was written, not what was sent
+  return { path: file, corr, bytes: buf.length, envelopes: verify.manifest?.counts?.envelopes ?? 0, receipts: verify.manifest?.counts?.ward_receipts ?? 0, receiptRows: verify.receipts || [], verify };
+}

package/lib/evidence/bundleVerify.js

@@ -0,0 +1,77 @@
+/**
+ * Offline verifier for a conversation evidence bundle (collector lib/conversationEvidenceBundle.js).
+ * Needs nothing but the zip: file hashes against manifest.json, the envelope list hash, the Ed25519 signature
+ * over the canonical manifest, and the counts. Never reaches the network. The collector builds; this only checks.
+ */
+import crypto from 'node:crypto';
+import JSZip from 'jszip';
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+// Same canonical form as services/collector/lib/bundleSigner.js (sorted keys at every level, no whitespace).
+export function canonicalize(val) {
+  if (val === null || val === undefined) return JSON.stringify(val);
+  if (typeof val !== 'object') return JSON.stringify(val);
+  if (Array.isArray(val)) return `[${val.map((v) => canonicalize(v)).join(',')}]`;
+  const keys = Object.keys(val).filter((k) => val[k] !== undefined).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(val[k])}`).join(',')}}`;
+}
+
+const SPKI_ED25519_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+export function envelopesHash(envelopes) {
+  return sha256(Buffer.from(JSON.stringify(
+    envelopes.map((e) => ({ id: e.id ?? null, ts: e.ts ?? null, intent: e.intent ?? null, corr: e.corr ?? null, reply_to: e.reply_to ?? null, from: e.from ?? null, to: e.to ?? null })),
+  ), 'utf8'));
+}
+
+/**
+ * @param {Buffer|Uint8Array} zipBytes
+ * @returns {Promise<{ ok: boolean, checks: {name:string, ok:boolean, detail?:string}[], manifest: object|null, signature: object|null }>}
+ */
+export async function verifyEvidenceBundle(zipBytes) {
+  const checks = [];
+  const add = (name, ok, detail) => { checks.push({ name, ok: !!ok, ...(detail ? { detail } : {}) }); return !!ok; };
+  let zip;
+  try { zip = await JSZip.loadAsync(zipBytes); } catch (e) {
+    add('zip readable', false, e.message);
+    return { ok: false, checks, manifest: null, signature: null };
+  }
+  const read = async (name) => { const f = zip.file(name); return f ? Buffer.from(await f.async('nodebuffer')) : null; };
+  const manifestBuf = await read('manifest.json');
+  const sigBuf = await read('signature.json');
+  if (!add('manifest.json present', manifestBuf)) return { ok: false, checks, manifest: null, signature: null };
+  if (!add('signature.json present', sigBuf)) return { ok: false, checks, manifest: null, signature: null };
+  let manifest; let signature;
+  try { manifest = JSON.parse(manifestBuf.toString('utf8')); signature = JSON.parse(sigBuf.toString('utf8')); } catch (e) {
+    add('manifest and signature parse', false, e.message);
+    return { ok: false, checks, manifest: null, signature: null };
+  }
+
+  // 1. signature over the canonical manifest
+  try {
+    const signed = Buffer.from(canonicalize(manifest), 'utf8');
+    const pub = crypto.createPublicKey({ key: Buffer.concat([SPKI_ED25519_PREFIX, Buffer.from(signature.public_key, 'base64')]), format: 'der', type: 'spki' });
+    const sigOk = signature.alg === 'ed25519' && crypto.verify(null, signed, pub, Buffer.from(signature.signature, 'base64'));
+    add('signature (Ed25519 over the manifest)', sigOk, sigOk ? `key ${signature.key_id}` : 'signature does not match the manifest');
+    add('signed manifest hash', signature.manifest_sha256 === sha256(signed), signature.manifest_sha256 === sha256(signed) ? undefined : 'manifest_sha256 differs');
+  } catch (e) { add('signature (Ed25519 over the manifest)', false, e.message); }
+
+  // 2. every listed file hashes to what the (signed) manifest says
+  const bufs = {};
+  for (const [name, want] of Object.entries(manifest.files || {})) {
+    const b = await read(name);
+    bufs[name] = b;
+    add(`file ${name}`, b && sha256(b) === want, !b ? 'missing from the zip' : (sha256(b) === want ? undefined : 'hash differs from the manifest'));
+  }
+
+  // 3. envelope list hash + counts
+  let envelopes = [];
+  try { envelopes = JSON.parse((bufs['envelopes.json'] || Buffer.from('[]')).toString('utf8')); } catch { envelopes = []; }
+  add('envelope list hash', envelopesHash(envelopes) === manifest.envelopes_sha256, envelopesHash(envelopes) === manifest.envelopes_sha256 ? undefined : 'recomputed hash differs');
+  add('envelope count', envelopes.length === manifest.counts?.envelopes, `${envelopes.length} in envelopes.json, ${manifest.counts?.envelopes} in the manifest`);
+  let receipts = [];
+  try { receipts = JSON.parse((bufs['ward-receipts.json'] || Buffer.from('[]')).toString('utf8')); } catch { receipts = []; }
+  add('receipt count', receipts.length === manifest.counts?.ward_receipts, `${receipts.length} in ward-receipts.json, ${manifest.counts?.ward_receipts} in the manifest`);
+  return { ok: checks.every((c) => c.ok), checks, manifest, signature, receipts };
+}

package/lib/hyperion/deck.js

@@ -0,0 +1,29 @@
+/**
+ * Launcher for the HYPERION deck TUI (`quox hyperion deck`). Same shape as lucid/deck.js: alt screen via
+ * fullscreen-ink when the terminal supports raw mode; the terminal is restored on every exit path.
+ */
+export async function launchHyperionDeck(api, { intervalMs = 10000 } = {}) {
+  if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function' || !process.stdout.isTTY) {
+    console.error('quox hyperion deck needs an interactive terminal. Use `quox hyperion` for a one-shot view.');
+    process.exitCode = 1;
+    return;
+  }
+  // A long-running TUI must use React's production build (the development build grows the heap per render).
+  if (!process.env.NODE_ENV) process.env.NODE_ENV = 'production';
+  await import('../tui/index.js'); // registers the .jsx loader hook
+  const React = (await import('react')).default;
+  const { HyperionDeck } = await import('../tui/views/HyperionDeck.jsx');
+  const { withFullScreen } = await import('fullscreen-ink');
+  const app = withFullScreen(React.createElement(HyperionDeck, { api, intervalMs }), { exitOnCtrlC: true });
+  const restore = () => { try { process.stdout.write('\x1b[?1049l\x1b[?25h'); } catch { /* best effort */ } };
+  process.once('SIGTERM', () => { restore(); process.exit(143); });
+  process.once('SIGHUP', () => { restore(); process.exit(129); });
+  process.once('exit', restore);
+  process.once('uncaughtException', (e) => { restore(); console.error(e); process.exit(1); });
+  try {
+    await app.start();
+    await app.waitUntilExit();
+  } finally {
+    restore();
+  }
+}

package/lib/lucid/LucidCard.jsx

@@ -0,0 +1,68 @@
+/**
+ * <LucidCard/>: draws a Quoxon object-card view ({ box, rows }, see cards.js) for the deck.
+ *
+ * Same geometry and roles as quoxon/objects/view.js, plus what a navigable list needs:
+ *   box.sel 'focus' | 'dim'   the title sits on a bar (and inverse under NO_COLOR) so the selected card is unmistakable
+ *   role 'sel'                the highlighted action bar
+ *   t (seconds)               drop-in reveal: rows decode through half-width katakana, then a short colour
+ *                             afterglow on the real characters. Infinity = settled (what idle always shows).
+ * Colour comes from the theme roles (light/dark, 256-colour, NO_COLOR); the characters never change.
+ */
+import React from 'react';
+import { Text } from 'ink';
+import { c, mono } from '../quoxon/theme.js';
+import { agentColor } from '../quoxon/theme.js';
+import { decodeRow, padRow, fit, len } from '../quoxon/objects/model.js';
+import { rowStart } from '../quoxon/objects/view.js';
+import { hexRgb, mix, rgbStr } from '../quoxon/motion/color.js';
+
+const h = React.createElement;
+export const BAR = { focus: '#1E3A8A', dim: '#27272A' }; // selection bars (white text on both)
+
+function roleColor(role) {
+  if (mono()) return undefined;
+  if (typeof role === 'string' && role.startsWith('agent:')) return agentColor(role.slice(6));
+  return c(role || 'value');
+}
+/** A role colour lifted towards white by the afterglow (hex colours only; anything else stays as is). */
+function glowColor(role, g) {
+  const base = roleColor(role);
+  return typeof base === 'string' && base[0] === '#' ? rgbStr(mix(hexRgb(base), [255, 255, 255], 0.65 * g)) : base;
+}
+
+function runs(cells, key) {
+  const out = [];
+  let run = '', col, bold = false, bg, k = 0;
+  const flush = () => { if (run) out.push(h(Text, { key: `${key}-${k++}`, color: col, bold, backgroundColor: bg }, run)); run = ''; };
+  for (const cl of cells) {
+    let color, back;
+    if (cl.role === 'sel') { color = mono() ? undefined : '#FFFFFF'; back = mono() ? undefined : BAR.focus; }
+    else if (cl.glyph) color = roleColor('teal'); // the katakana flicker
+    else color = cl.glow > 0.05 ? glowColor(cl.role, cl.glow) : roleColor(cl.role);
+    const b = Boolean(cl.bold);
+    if (color !== col || b !== bold || back !== bg) { flush(); col = color; bold = b; bg = back; }
+    run += cl.ch;
+  }
+  flush();
+  return out;
+}
+
+export function LucidCard({ view, t = Infinity }) {
+  const b = view.box, w = b.width, inner = w - 4;
+  const rows = view.rows || [];
+  const bc = roleColor(b.border || 'faint');
+  const right = b.right ? ` ${b.right} ` : '';
+  const title = b.title ? ` ${fit(b.title, Math.max(4, w - 6 - (right ? len(right) + 1 : 0)))} ` : '';
+  const fill = Math.max(0, w - 3 - len(title) - len(right) - 1);
+  const bar = b.sel ? BAR[b.sel] : null;
+  const top = h(Text, { key: 'top', wrap: 'truncate' },
+    h(Text, { color: bc }, '╭─'),
+    h(Text, { color: bar && !mono() ? '#FFFFFF' : roleColor(b.titleRole || 'value'), backgroundColor: bar && !mono() ? bar : undefined, inverse: Boolean(bar) && mono(), bold: true }, title),
+    h(Text, { color: bc }, '─'.repeat(fill)),
+    h(Text, { color: roleColor(b.rightRole || 'muted') }, right),
+    h(Text, { color: bc }, '─╮'));
+  const body = rows.map((r, i) => h(Text, { key: `b${i}`, wrap: 'truncate' },
+    h(Text, { color: bc }, '│ '), ...runs(decodeRow(padRow(r, inner), t, rowStart(i, rows.length), 0.25, 70 + i), `b${i}`), h(Text, { color: bc }, ' │')));
+  const bottom = h(Text, { key: 'bot', color: bc }, '╰' + '─'.repeat(w - 2) + '╯');
+  return h(React.Fragment, null, top, ...body, bottom);
+}

package/lib/lucid/LucidIntro.jsx

@@ -1,8 +1,8 @@
 /**
- * LucidIntro: the ~1.2s startup for `quox lucid deck`.
+ * LucidIntro: the ~1.6s startup for `quox lucid deck`.
  *
- * Frames (50ms): the QUOX block wordmark is revealed by a gradient sweep, the
- * ◉ LUCID mark fades in under it, then "tuning in…" resolves into
+ * Frames (50ms): the Quoxon particle collapse (particles swarm in and lock into the horned Q, tail last),
+ * the ◉ LUCID mark fades in under it, then "tuning in…" resolves into
  * "◉ LUCID │ N sources live · M need you" once the first fetch has landed.
  * The fetch is owned by the deck and runs in parallel, never gated on this.
  * onDone fires once: at the natural end, on a hard 2.5s cap, or on a key
@@ -10,38 +10,25 @@
  */
 import React, { useState, useEffect, useRef } from 'react';
 import { Box, Text } from 'ink';
-import chalk from 'chalk';
-import { BLOCK_FONT, gradientColor } from '../tui/intro/Intro.jsx';
-import { PALETTE, STATE_HEX } from './fmt.js';
+import { c, gradient, mono } from '../quoxon/theme.js';
+import { QGlyph } from '../quoxon/qmotion.js';
+import { Clock } from '../quoxon/motion/clock.js';
+import { particleCellsAt, qCells, cellsToAnsi, labSize } from '../quoxon/qart.js';
 
 export const FRAME_MS = 50;
-const SWEEP_FRAMES = 12;
-const MIN_FRAMES = 24;   // 1.2s
-const MAX_FRAMES = 50;   // 2.5s cap if the fetch never lands
+const PARTICLE_MS = 1100; // the collapse; the Q is fully settled ~470ms later
+const MIN_FRAMES = 32;    // 1.6s: the Q settles, then the live line shows
+const MAX_FRAMES = 50;    // 2.5s cap if the fetch never lands
 
-const LETTERS = ['Q', 'U', 'O', 'X'];
-const rgb = (c, s) => chalk.rgb(c[0], c[1], c[2])(s);
-
-function titleRow(row, frame, colsRevealed) {
-  let out = ''; let col = 0;
-  const total = LETTERS.reduce((n, ch) => n + BLOCK_FONT[ch][0].length + 1, 0);
-  for (const ch of LETTERS) {
-    const g = BLOCK_FONT[ch][row];
-    for (let i = 0; i < g.length; i++) {
-      const x = col + i;
-      const lit = g[i] !== ' ';
-      if (x > colsRevealed) { out += '  '; continue; }
-      if (!lit) { out += '  '; continue; }
-      const edge = colsRevealed - x < 2 && colsRevealed < total;
-      out += edge ? chalk.white('██') : rgb(gradientColor(x / total + frame * 0.02), '██');
-    }
-    out += '  ';
-    col += g.length + 1;
-  }
-  return out;
+/** Rows of the particle Q at frame `frame` (motion off: the settled Q). Under 12 rows the compact Q. */
+export function introQ(cols, rows, frame, motion = true) {
+  const size = labSize(cols, Math.max(0, rows - 8));
+  const color = !mono();
+  const t = frame * FRAME_MS;
+  return cellsToAnsi(motion ? particleCellsAt(size, t, { dur: PARTICLE_MS, color }) : qCells(size, { color }));
 }
 
-export function LucidIntro({ data, err, onDone, rows = 24 }) {
+export function LucidIntro({ data, err, onDone, rows = 24, cols = 100, motion = true }) {
   const [frame, setFrame] = useState(0);
   const doneRef = useRef(false);
   const readyAt = useRef(null);
@@ -49,10 +36,11 @@ export function LucidIntro({ data, err, onDone, rows = 24 }) {
 
   if (sit && readyAt.current == null) readyAt.current = frame;
 
-  useEffect(() => {
-    const id = setInterval(() => setFrame((f) => f + 1), FRAME_MS);
-    return () => clearInterval(id);
-  }, []);
+  // The deck's shared clock drives the intro too: one timer, armed only while the intro still has frames to play.
+  const clockRef = useRef(null);
+  if (!clockRef.current) clockRef.current = new Clock(() => setFrame((f) => f + 1));
+  useEffect(() => { if (!doneRef.current) clockRef.current.schedule([{ every: FRAME_MS }]); });
+  useEffect(() => () => clockRef.current.stop(), []);
 
   const finishAt = readyAt.current != null
     ? Math.max(MIN_FRAMES, readyAt.current + 6)
@@ -62,44 +50,43 @@ export function LucidIntro({ data, err, onDone, rows = 24 }) {
     if (frame >= finishAt && !doneRef.current) { doneRef.current = true; onDone(); }
   }, [frame, finishAt, onDone]);
 
-  const tall = rows >= 16;
-  const total = LETTERS.reduce((n, ch) => n + BLOCK_FONT[ch][0].length + 1, 0);
-  const revealed = Math.round((Math.min(frame, SWEEP_FRAMES) / SWEEP_FRAMES) * (total + 2)) - 1;
-  const markOn = frame >= 6;
-  const resolved = sit && frame >= 14 && frame >= (readyAt.current ?? 0) + 2;
+  const qRows = introQ(cols, rows, frame, motion);
+  const markOn = frame >= 14;
+  const resolved = sit && frame >= 22 && frame >= (readyAt.current ?? 0) + 2;
   const cov = (sit && sit.cannot_see && sit.cannot_see.coverage) || { live: 0, expected: 0 };
   const dots = '.'.repeat((frame % 3) + 1).padEnd(3, ' ');
 
-  const mark = [...'◉ LUCID'].map((ch, i) => (
-    <Text key={i} bold color={'#' + gradientColor((i / 7) + frame * 0.03).map((v) => v.toString(16).padStart(2, '0')).join('')}>{ch}</Text>
-  ));
+  const mark = (
+    <Text>
+      <QGlyph state="working" ms={Date.now()} quiet={!motion} />
+      <Text> </Text>
+      {gradient('LUCID').map((g, i) => <Text key={i} bold color={g.color}>{g.ch}</Text>)}
+    </Text>
+  );
 
   return (
     <Box flexDirection="column" alignItems="center" justifyContent="center" flexGrow={1} paddingY={1}>
-      {tall ? (
-        <Box flexDirection="column" alignItems="center">
-          {Array.from({ length: 5 }, (_, r) => <Text key={r}>{titleRow(r, frame, revealed)}</Text>)}
-        </Box>
-      ) : (
-        <Text bold color={PALETTE.brand}>Q U O X</Text>
-      )}
+      <Box flexDirection="column" alignItems="center">
+        {qRows.map((l, r) => <Text key={r} wrap="truncate">{l}</Text>)}
+      </Box>
       <Box marginTop={1}>{markOn ? mark : <Text> </Text>}</Box>
       <Box marginTop={1}>
-        {frame < 10 ? <Text> </Text> : resolved ? (
+        {frame < 16 ? <Text> </Text> : resolved ? (
           <Text>
-            <Text bold color={PALETTE.brand}>◉ LUCID</Text>
-            <Text color={PALETTE.dim}> │ </Text>
-            <Text color={STATE_HEX.ok}>{cov.live} sources live</Text>
-            <Text color={PALETTE.dim}> · </Text>
-            <Text bold color={(sit.needs_you || []).length ? STATE_HEX.attention : STATE_HEX.ok}>{(sit.needs_you || []).length} need you</Text>
+            <QGlyph state={(sit.needs_you || []).length ? 'waiting' : 'resting'} ms={Date.now()} quiet />
+            <Text bold color={c('sky')}> LUCID</Text>
+            <Text color={c('muted')}> │ </Text>
+            <Text color={c('ok')}>{cov.live} sources live</Text>
+            <Text color={c('muted')}> · </Text>
+            <Text bold color={(sit.needs_you || []).length ? c('warn') : c('ok')}>{(sit.needs_you || []).length} need you</Text>
           </Text>
         ) : err && !sit ? (
-          <Text color={STATE_HEX.blind}>LUCID unreachable, still trying</Text>
+          <Text color={c('error')}>LUCID unreachable, still trying</Text>
         ) : (
-          <Text color={PALETTE.muted}>tuning in{dots}</Text>
+          <Text color={c('muted')}>tuning in{dots}</Text>
         )}
       </Box>
-      <Box marginTop={1}><Text color={PALETTE.dim}>any key to skip</Text></Box>
+      <Box marginTop={1}><Text color={c('muted')}>any key to skip</Text></Box>
     </Box>
   );
 }