quoxcli 0.2.0 → 0.3.1

package/lib/core/vmTui.js

@@ -0,0 +1,86 @@
+/**
+ * QUOXON `/vm <verb> <target> [args]`: parse the words, call the shared engine
+ * (lib/core/vm.js, same as `quox vm`), return { lines, tone } for say().
+ * A held call becomes the approval hint (tone 'warn'); other failures throw.
+ */
+import {
+  VM_ACTIONS, NODE_ACTIONS, VmPendingError, pendingHint, makeExec,
+  listVms, vmInfo, vmDoctor, doctorLines, vmAction, vmSnapshot, poolStatus, poolLease, poolDone, poolConfig,
+  nodePower, readPubkey, vmListLines, textOf,
+} from './vm.js';
+
+/** Split argv into positionals and --flag value pairs. */
+export function splitFlags(argv) {
+  const pos = []; const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq > 0) flags[a.slice(2, eq)] = a.slice(eq + 1);
+      else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) flags[a.slice(2)] = argv[++i];
+      else flags[a.slice(2)] = true;
+    } else pos.push(a);
+  }
+  return { pos, flags };
+}
+
+const asLines = (t) => String(t).split('\n');
+export const VM_USAGE = 'Usage: /vm <list|info|doctor|start|stop|reboot|shutdown|snapshot|pool|node> <target> [args]';
+
+export async function runVmCommand({ client, orgId, argv, exec: injected }) {
+  const exec = injected || makeExec({ client, orgId });
+  const { pos, flags } = splitFlags(argv || []);
+  const [verb, ...rest] = pos;
+  const reason = typeof flags.reason === 'string' ? flags.reason : undefined;
+  const need = (v, what) => { if (!v) throw new Error(`${what} is required. ${VM_USAGE}`); return v; };
+  try {
+    if (!verb) return { lines: [VM_USAGE], tone: 'warn' };
+    if (verb === 'list') {
+      return { lines: vmListLines(await listVms(exec, { node: flags.node, type: flags.type })) };
+    }
+    if (verb === 'info') {
+      const { vm, resources } = await vmInfo(exec, need(rest[0], 'a VM name or vmid'));
+      return { lines: [`${vm.name || vm.vmid}  vmid ${vm.vmid}  node ${vm.node}  ${vm.type}`, ...asLines(textOf(resources))] };
+    }
+    if (verb === 'doctor') {
+      const report = await vmDoctor(exec, need(rest[0], 'a VM name or vmid'));
+      return { lines: doctorLines(report), tone: report.verdict === 'healthy' ? undefined : 'warn' };
+    }
+    if (VM_ACTIONS.includes(verb)) {
+      const { vm, result } = await vmAction(exec, verb, need(rest[0], 'a VM name or vmid'), { reason });
+      return { lines: [`${verb} ${vm.name || vm.vmid} (vmid ${vm.vmid} on ${vm.node})`, ...asLines(textOf(result))] };
+    }
+    if (verb === 'snapshot') {
+      const { vm, result } = await vmSnapshot(exec, need(rest[0], 'a VM name or vmid'), { name: typeof flags.name === 'string' ? flags.name : undefined, reason });
+      return { lines: [`snapshot ${vm.name || vm.vmid} (vmid ${vm.vmid})`, ...asLines(textOf(result))] };
+    }
+    if (verb === 'pool') {
+      const sub = rest[0];
+      if (sub === 'status') return { lines: asLines(textOf(await poolStatus(exec))) };
+      if (sub === 'lease') {
+        const pubkey = readPubkey(typeof flags['pubkey-file'] === 'string' ? flags['pubkey-file'] : undefined);
+        const p = await poolLease(exec, {
+          lessee: flags.lessee, pubkey, cores: flags.cores, memoryGb: flags['memory-gb'],
+          diskGb: flags['disk-gb'], purpose: flags.purpose, reason,
+        });
+        return { lines: asLines(textOf(p)) };
+      }
+      if (sub === 'done') return { lines: asLines(textOf(await poolDone(exec, need(rest[1], 'a vmid'), { reason }))) };
+      if (sub === 'config') {
+        let input = {};
+        if (flags.set) { try { input = JSON.parse(flags.set); } catch { throw new Error('--set must be a JSON object'); } }
+        return { lines: asLines(textOf(await poolConfig(exec, input, { reason }))) };
+      }
+      return { lines: ['Usage: /vm pool <status|lease|done <vmid>|config>'], tone: 'warn' };
+    }
+    if (verb === 'node') {
+      const [action, name] = rest;
+      if (!NODE_ACTIONS.includes(action)) return { lines: ['Usage: /vm node <reboot|shutdown> <node>'], tone: 'warn' };
+      return { lines: asLines(textOf(await nodePower(exec, action, need(name, 'a node name'), { reason }))) };
+    }
+    return { lines: [`Unknown /vm verb "${verb}". ${VM_USAGE}`], tone: 'warn' };
+  } catch (e) {
+    if (e instanceof VmPendingError) return { lines: [pendingHint(e)], tone: 'warn' };
+    throw e;
+  }
+}

package/lib/core/walkthrough.js

@@ -0,0 +1,35 @@
+/**
+ * WALKTHROUGH for a plain terminal (`quox approvals walkthrough`, `quox inbox walkthrough`): the waiting decisions one
+ * card at a time, using the same card and reply rules as the TUI (quoxon/approvalsView.js). Identity is the decision id.
+ * io = { readLine(prompt) -> Promise<string|null>, write(line), answer(item, key, note) -> Promise<void> }.
+ */
+import { isDecision, walkCard, walkReply, walkNotYesNo, walkNoCatch, walkSummary } from '../quoxon/approvalsView.js';
+
+export async function runWalkthrough(items, io) {
+  const decs = (items || []).filter(isDecision);
+  if (!decs.length) { io.write('No question is waiting for you.'); return { answered: [], skipped: [], left: [] }; }
+  const st = { answered: [], skipped: [], left: [] };
+  io.write(`${decs.length} question${decs.length === 1 ? '' : 's'} waiting for you. One at a time: a choice, then an optional note.`);
+  for (let i = 0; i < decs.length; i++) {
+    const it = decs[i]; const card = walkCard(it, i + 1, decs.length);
+    io.write(''); card.lines.forEach((l) => io.write(l));
+    for (;;) {
+      const line = await io.readLine('Your choice? ');
+      if (line == null) { for (let j = i; j < decs.length; j++) st.left.push(decs[j].title || decs[j].id); io.write(''); walkSummary(st).forEach((l) => io.write(l)); return st; }
+      const rep = walkReply(it, line);
+      if (!rep) { io.write(walkNoCatch(it)); continue; }
+      if (rep.notYesNo) { io.write(walkNotYesNo(it)); continue; }
+      if (rep.defer) { st.skipped.push(it.title || it.id); break; }
+      if (rep.ask) { io.write(`  Asked by ${it.payload.session || 'a session'} (id ${it.id}). ${it.payload.why || 'No further reason was given.'}`); continue; }
+      if (it.payload.high_risk === true && rep.key !== 'n') { io.write('  High risk: a yes needs your PIN, which this plain terminal cannot take. Answer it in `quox` with /approvals walkthrough, or skip it here.'); continue; }
+      try { await io.answer(it, rep.key, rep.note || null); }
+      catch (e) { io.write(`  Not answered (${e.message}). The question stays open.`); continue; }
+      const label = it.payload.options.find((o) => o.key === rep.key).label;
+      io.write(`✔ ${it.title || it.id}: ${label}`);
+      st.answered.push({ title: it.title || it.id, word: label });
+      break;
+    }
+  }
+  io.write(''); walkSummary(st).forEach((l) => io.write(l));
+  return st;
+}

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>
   );
 }

package/lib/lucid/cards.js

@@ -0,0 +1,86 @@
+/**
+ * LUCID object cards: pure views for the deck, in the Quoxon object-card shape ({ box, rows } of
+ * { text, role } segments, see quoxon/objects/model.js). An area is a tile card; a Needs-you item is a card
+ * that opens in place into who / what / why / when and the actions. Nothing here reads a clock or does I/O.
+ *
+ * Roles are theme roles; the renderer (LucidCard.jsx) also understands 'sel' (the selected action bar).
+ * Text is WRAPPED to the card, never clipped, except for a single action line and the command line.
+ */
+import { seg, fit, padRow } from '../quoxon/objects/model.js';
+import { wrap, whenText, ageOf, GLYPH, clip } from './fmt.js';
+
+export const URGENCY_ROLE = { now: 'error', today: 'warn', 'this week': 'sky', whenever: 'muted', fyi: 'muted' };
+export const URGENCY_LABEL = { now: 'NOW', today: 'TODAY', 'this week': 'THIS WEEK', whenever: 'WHENEVER', fyi: 'FYI' };
+export const STATE_ROLE = { ok: 'ok', attention: 'warn', unknown: 'muted', blind: 'error' };
+export const STATE_WORD = { ok: 'ok', attention: 'attention', unknown: 'no signal', blind: 'blind' };
+
+const nm = (x) => (typeof x === 'string' ? x : (x && (x.label || x.name || x.L0 || x.id)) || '');
+const LW = 8; // label column of the open card
+
+/**
+ * An area tile. d: { area, label, state, L0, last, n (needs), active (filter on), selected, focused,
+ * expanded, now }. A tile is one status row; the selected tile in a focused pane opens to its sentence.
+ */
+export function lucidArea(d, cols) {
+  const w = Math.max(18, cols), inner = w - 4;
+  const all = d.area == null;
+  const glyph = all ? '◉' : (GLYPH[d.state] || '?');
+  const role = all ? 'sky' : (STATE_ROLE[d.state] || 'muted');
+  const right = `${d.active ? '● ' : ''}${d.n ? d.n : '·'}`;
+  const rows = [];
+  const word = all ? 'everything' : (STATE_WORD[d.state] || 'unknown');
+  const age = d.last && d.last.ts != null && d.now != null ? `last ${ageOf(d.last.ts, d.now)}` : '';
+  const line = age && [...`${word} · ${age}`].length <= inner ? `${word} · ${age}` : word;
+  rows.push([seg(line, d.selected ? 'value' : role === 'ok' ? 'muted' : role)]);
+  if (d.expanded && d.L0) for (const ln of wrap(d.L0, inner)) rows.push([seg(ln, 'value')]);
+  const mark = d.selected ? '▶ ' : '';
+  return {
+    box: {
+      width: w, title: `${mark}${glyph} ${fit(d.label || d.area || 'All areas', Math.max(4, inner - 8))}`, titleRole: role,
+      right, rightRole: d.n ? 'warn' : 'muted', border: d.selected ? 'sky' : 'faint', sel: d.selected ? (d.focused ? 'focus' : 'dim') : null,
+    },
+    rows,
+  };
+}
+
+/**
+ * A Needs-you card. d: { item, areaLabel, isNew, selected, focused, open, mSel, now }.
+ * Collapsed: the wrapped sentence. Open: the sentence, who/what/why/when, affects, then the actions with
+ * the highlighted one as a bar and its exact command beneath.
+ */
+export function lucidNeed(d, cols) {
+  const it = d.item, w = Math.max(24, cols), inner = w - 4;
+  const urg = it.urgency || 'whenever';
+  const a = it.L1 || {};
+  const ms = (it.L2 && it.L2.measures) || [];
+  const mark = d.selected ? '▶ ' : '';
+  const rows = [];
+  const text = (d.isNew ? '● ' : '') + (it.L0 || '');
+  wrap(text, inner).forEach((ln, i) => rows.push([seg(ln, d.isNew ? 'ok' : d.selected ? 'value' : 'text', d.selected)]));
+  if (d.open) {
+    const detail = (lbl, v) => wrap(v, inner - LW).forEach((ln, i) => rows.push([seg(i ? ' '.repeat(LW) : lbl.padEnd(LW), i ? 'muted' : 'label'), seg(ln, 'text')]));
+    for (const [lbl, v] of [['Who', a.who], ['What', a.what], ['Why', a.why], ['When', whenText(a.when, d.now)]]) if (v) detail(lbl, v);
+    if ((a.affected || []).length) rows.push([seg('Affects'.padEnd(LW), 'label'), seg(clip(a.affected.map(nm).filter(Boolean).join(', '), inner - LW), 'muted')]);
+    rows.push(ms.length ? [seg('What you can do', 'key', true)] : [seg('No actions to offer here. Esc closes.', 'muted')]);
+    ms.forEach((m, mi) => {
+      const on = mi === d.mSel;
+      const risk = ` ${m.risk}`;
+      const label = fit(m.say || m.label, Math.max(8, inner - 2 - risk.length));
+      if (on) rows.push([seg(`❯ ${label}${risk}`.padEnd(inner, ' '), 'sel', true)]);
+      else rows.push([seg('  ', 'muted'), seg(label, 'text'), seg(risk, m.risk === 'dangerous' ? 'error' : m.risk === 'gated' ? 'warn' : 'muted')]);
+    });
+    const cmd = ms[d.mSel] && ms[d.mSel].command;
+    if (cmd) rows.push([seg('  $ ', 'muted'), seg(clip(cmd, inner - 4), 'code')]);
+    else if (ms.some((m) => m.command)) rows.push([seg(' ', 'muted')]);
+  }
+  return {
+    box: {
+      width: w, title: `${mark}${URGENCY_LABEL[urg] || String(urg).toUpperCase()} · ${it.kind || 'item'}`, titleRole: URGENCY_ROLE[urg] || 'muted',
+      right: d.areaLabel || '', rightRole: 'muted', border: d.selected ? 'sky' : (urg === 'now' ? 'error' : 'faint'), sel: d.selected ? (d.focused ? 'focus' : 'dim') : null,
+    },
+    rows,
+  };
+}
+
+export const cardHeight = (view) => view.rows.length + 2;
+export { padRow };

package/lib/lucid/markdown.js

@@ -0,0 +1,81 @@
+/**
+ * The sitrep as chat Markdown (Discord, Matrix, slots): short, scannable, under one Discord message.
+ * Owner 2026-10-17: "Format your sitrep" after the spoken paragraph was posted to Discord as a wall of text.
+ * Pure: data in, string out. No colour codes, no box drawing (chat clients mangle both).
+ */
+
+const URGENCY = { now: '🔴', today: '🟠', this_week: '🟡', week: '🟡', whenever: '⚪', fyi: '⚪' };
+const STATE = { attention: '⚠️', ok: '✅', partial: '🟡', unknown: '❔', blind: '⛔' };
+export const MAX_CHARS = 1900; // Discord's limit is 2000 per message
+
+const clip = (s, n) => {
+  const t = String(s || '').replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+};
+
+function age(ms) {
+  if (!(ms > 0)) return '';
+  const m = Math.floor(ms / 60000);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+function clockLondon(now) {
+  try {
+    return new Intl.DateTimeFormat('en-GB', { timeZone: 'Europe/London', hour: '2-digit', minute: '2-digit', timeZoneName: 'short' }).format(new Date(now));
+  } catch { return new Date(now).toISOString().slice(11, 16) + ' UTC'; }
+}
+
+/** opts: { now, maxNeeds (default 6), maxChars (default MAX_CHARS) } */
+export function renderSitrepMarkdown(data, opts = {}) {
+  const sit = (data && data.situation) || data || {};
+  const now = opts.now ?? Date.now();
+  const maxNeeds = opts.maxNeeds ?? 6;
+  const maxChars = opts.maxChars ?? MAX_CHARS;
+  const cov = sit.coverage || (sit.cannot_see && sit.cannot_see.coverage) || { live: 0, expected: 0 };
+  const missing = sit.coverage && Array.isArray(sit.coverage.missing) ? sit.coverage.missing : [];
+  const needs = Array.isArray(sit.needs_you) ? sit.needs_you : [];
+  const low = needs.filter((n) => n.urgency === 'whenever' || n.urgency === 'fyi').length;
+
+  const out = [];
+  out.push(`**◉ LUCID sitrep** · ${clockLondon(now)} · ${cov.live}/${cov.expected} sources`);
+  out.push('');
+  if (!needs.length) {
+    out.push('**Needs you:** nothing right now.');
+  } else {
+    out.push(`**Needs you (${needs.length}${low ? `, ${low} low priority` : ''})**`);
+    needs.slice(0, maxNeeds).forEach((n, i) => {
+      const w = n.L1 && n.L1.when && n.L1.when.waited_ms;
+      const tail = [n.area, age(w)].filter(Boolean).join(', ');
+      out.push(`${i + 1}. ${URGENCY[n.urgency] || '•'} ${clip(n.L0, 90)}${tail ? ` _(${tail})_` : ''}`);
+    });
+    if (needs.length > maxNeeds) out.push(`…and ${needs.length - maxNeeds} more: \`quox sitrep\``);
+  }
+
+  const areas = Array.isArray(sit.areas) ? sit.areas : [];
+  if (areas.length) {
+    out.push('');
+    out.push('**At a glance**');
+    for (const a of areas) out.push(`${STATE[a.state] || '•'} **${a.label || a.area}**: ${clip(a.L0, 80)}`);
+  }
+
+  const dau = Array.isArray(sit.doesnt_add_up) ? sit.doesnt_add_up : [];
+  if (dau.length) {
+    out.push('');
+    out.push(`**Doesn't add up (${dau.length}):** ${clip(dau[0].L0, 90)}${dau.length > 1 ? ' …' : ''}`);
+  }
+  out.push('');
+  out.push(missing.length ? `**Can't see:** ${missing.join(', ')}` : `**Can't see:** nothing, every source is reporting.`);
+
+  // Stay inside one chat message: drop "at a glance" rows from the bottom, then needs, never the header.
+  let text = out.join('\n');
+  while (text.length > maxChars && out.length > 3) {
+    const i = out.findLastIndex((l) => /^(✅|⚠️|🟡|❔|⛔|•) \*\*/.test(l));
+    if (i < 0) break;
+    out.splice(i, 1);
+    text = out.join('\n');
+  }
+  return text.length > maxChars ? `${text.slice(0, maxChars - 1)}…` : text;
+}

package/lib/lucid/motion.js

@@ -0,0 +1,56 @@
+/**
+ * LUCID deck motion: pure helpers for the deck's ONE clock (quoxon/motion/clock.js).
+ *
+ * Idle is still. The deck declares a demand each render; the clock keeps one timer for the soonest demand and
+ * none at all when nothing asks. Frames (~12 fps) are demanded ONLY while something is visibly moving: a fetch
+ * in flight (the Q works), the Q settling after a state change (a short window, then still colour), or a
+ * card dropping in. Everything else is a one-shot wake (toast expiry, ghost expiry, the minute tick).
+ *
+ * LUCID state -> Q state (qglyph.js): needs you = waiting, fetching = working, unreachable = failing,
+ * quiet = resting. Failing wins over working so an outage never reads as busy.
+ */
+import { FRAME_MS } from '../quoxon/motion/clock.js';
+
+export { FRAME_MS };
+/** After a state change the Q animates this long, then holds a still colour (no timer, no writes). */
+export const SETTLE_MS = 2400;
+/** A card dropping in is revealing for this long from its start (rows decode, then a short afterglow). */
+export const REVEAL_MS = 1500;
+/** Cards of one load start this far apart so the board fills top to bottom. */
+export const STAGGER_MS = 70;
+
+export function glyphStateOf({ err = null, fetching = false, needs = 0 } = {}) {
+  if (err) return 'failing';
+  if (fetching) return 'working';
+  return needs > 0 ? 'waiting' : 'resting';
+}
+
+/** Is the Q moving at `now`? Working moves while it lasts; every other state settles after SETTLE_MS. */
+export function glyphAnimating({ state, since, now, motion }) {
+  if (!motion) return false;
+  if (state === 'working') return true;
+  return since != null && now - since < SETTLE_MS;
+}
+
+/** Seconds into a card's reveal, or Infinity when settled (or motion is off). A future start is negative. */
+export function revealT(startAt, now, motion) {
+  if (!motion || startAt == null) return Infinity;
+  const ms = now - startAt;
+  return ms >= REVEAL_MS ? Infinity : ms / 1000;
+}
+
+/**
+ * The demands for this render. frames: something is moving right now. at: epoch ms of one-shot wakes
+ * (past or null entries are ignored). Without motion there are no frame demands at all.
+ */
+export function deckDemands({ motion = false, frames = false, at = [], now = Date.now() } = {}) {
+  const d = [];
+  if (motion && frames) d.push({ every: FRAME_MS });
+  let soonest = null;
+  for (const a of at) if (Number.isFinite(a) && a > now && (soonest == null || a < soonest)) soonest = a;
+  if (soonest != null) d.push({ at: soonest });
+  return d;
+}
+
+/** Next wall-clock minute boundary for a displayed time (the injected clock, so tests stay deterministic). */
+export const nextMinuteAt = (wall, shown) => wall + (60000 - (shown % 60000));

package/lib/quoxon/activity.js

@@ -37,6 +37,13 @@ const TOOL_TABLE = [
   [/(^|_)(list|get|status)$|^contacts_/, 'Looking up'],
 ];
 
+/** QUOXON-FW3: "Delegating <Agent> · <task gist>" instead of an anonymous delegate_to_agent. */
+function delegateTarget(ev) {
+  const id = ev.agent_id || (String(ev.summary || '').match(/\bagent_id=(\S+)/) || [])[1] || '';
+  const name = ev.agent_name || id;
+  return { ...ev, target: [name, ev.task_gist].filter(Boolean).join(' \u00b7 ') };
+}
+
 /** { word, detail } for a tool call. Unknown tools are "Working" with the tool name, never a guess. */
 export function toolWord(tool, ev = {}) {
   const name = String(tool || '').toLowerCase();
@@ -46,7 +53,7 @@ export function toolWord(tool, ev = {}) {
   return { word: 'Working', detail: name || null };
 }
 
-const mk = (word, detail = null, now = 0, tone = 'work', flash = null) => ({ word, detail: detail ? clipD(detail) : null, tone, flash, since: now });
+const mk = (word, detail = null, now = 0, tone = 'work', flash = null, tool = null) => ({ word, detail: detail ? clipD(detail) : null, tone, flash, since: now, ...(tool ? { tool: clipD(tool, 40) } : {}) });
 export const initialActivity = (now = 0) => mk('Sending', null, now); // the request was dispatched: true from turn.begin
 
 /** Trace lines from the governance chain. Labels as the server sends them. */
@@ -82,7 +89,12 @@ export function nextActivity(prev, ev, now = 0, ctx = {}) {
       return p;
     }
     case 'trace': { const t = traceWord(ev); return t ? mk(t[0], t[1], now) : p; }
-    case 'tool.started': { const t = toolWord(ev.tool, ev); return mk(t.word, t.detail, now); }
+    case 'tool.started': { const t = toolWord(ev.tool, ev.tool === 'delegate_to_agent' ? delegateTarget(ev) : ev); return mk(t.word, t.detail, now, 'work', null, ev.tool || null); }
+    case 'delegation.progress': { // QUOXON 2026-10-17: a specialist's real tool call, forwarded by the server
+      if (!ev.tool) return p;
+      const who = ev.agent_name || ev.agent_id || 'specialist';
+      return mk('Delegating', `${who} \u00b7 ${ev.tool}${ev.detail ? ` (${ev.detail})` : ''}`, now, 'work', null, ev.tool);
+    }
     case 'tool.finished': return ev.status === 'failed' ? { ...p, flash: now } : p; // keep the word, flash the Q only
     case 'approval.requested': return mk('Waiting', 'for your approval', now, 'wait');
     case 'approval.resolved': return mk('Resuming', null, now);