quoxcli 0.0.0-stage → 0.2.0

package/lib/lucid/deck.js

@@ -0,0 +1,32 @@
+/**
+ * Launcher for the LUCID deck TUI. Alt screen via fullscreen-ink when the
+ * terminal supports raw mode; restores the terminal on every exit path.
+ */
+export async function launchDeck(api, { intervalMs = 10000, noIntro = false } = {}) {
+  if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function' || !process.stdout.isTTY) {
+    console.error('quox lucid deck needs an interactive terminal. Use `quox lucid --sitrep` for a one-shot snapshot.');
+    process.exitCode = 1;
+    return;
+  }
+  const { shouldIntro } = await import('./fmt.js');
+  const intro = shouldIntro({ noIntro: noIntro || process.argv.includes('--no-intro'), isTTY: true });
+  // A long-running TUI must use React's production build: the development build keeps debug
+  // records per render and grew the heap steadily (measured flat at 14MB in production).
+  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 { LucidDeck } = await import('../tui/views/LucidDeck.jsx');
+  const { withFullScreen } = await import('fullscreen-ink');
+  const app = withFullScreen(React.createElement(LucidDeck, { api, intervalMs, intro }), { 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/fmt.js

@@ -0,0 +1,139 @@
+/**
+ * LUCID presentation helpers shared by `quox lucid --sitrep` and the deck TUI.
+ * Pure functions, no I/O. Colour is a parameter, never read from globals, so
+ * renderers are deterministic under test.
+ */
+
+export const GLYPH = { ok: '✔', attention: '⚠', unknown: '?', blind: '✖' };
+export const STATE_HEX = { ok: '#22C55E', attention: '#FBBF24', unknown: '#A1A1AA', blind: '#EF4444' };
+export const URGENCY = {
+  now: { label: 'NOW', hex: '#EF4444' },
+  today: { label: 'TODAY', hex: '#FBBF24' },
+  'this week': { label: 'THIS WEEK', hex: '#38BDF8' },
+  whenever: { label: 'WHENEVER', hex: '#71717A' },
+  fyi: { label: 'FYI', hex: '#71717A' },
+};
+export const PALETTE = {
+  brand: '#38BDF8', accent: '#C084FC', text: '#E4E4E7', muted: '#A1A1AA', dim: '#71717A', code: '#7DD3FC',
+};
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+export const stripAnsi = (s) => String(s).replace(ANSI_RE, '');
+export const vlen = (s) => [...stripAnsi(s)].length;
+
+/** Truncate a plain string to max visible chars with an ellipsis. */
+export function clip(s, max) {
+  const a = [...String(s ?? '')];
+  if (a.length <= max) return a.join('');
+  return max <= 1 ? a.slice(0, max).join('') : a.slice(0, max - 1).join('') + '…';
+}
+
+/** Word-wrap plain text to width; hard-breaks over-long words. Returns lines. */
+export function wrap(text, width) {
+  width = Math.max(4, width);
+  const out = [];
+  for (const para of String(text ?? '').split('\n')) {
+    let cur = '';
+    for (let w of para.split(/\s+/).filter(Boolean)) {
+      while ([...w].length > width) {
+        if (cur) { out.push(cur); cur = ''; }
+        out.push([...w].slice(0, width).join(''));
+        w = [...w].slice(width).join('');
+      }
+      if (!cur) cur = w;
+      else if ([...cur].length + 1 + [...w].length <= width) cur += ' ' + w;
+      else { out.push(cur); cur = w; }
+    }
+    out.push(cur);
+  }
+  return out.length ? out : [''];
+}
+
+export function padEnd(s, width) {
+  const n = width - vlen(s);
+  return n > 0 ? s + ' '.repeat(n) : s;
+}
+
+/** "3m", "2h", "4d" from a ms timestamp (relative to now). */
+export function ageOf(ms, now = Date.now()) {
+  if (ms == null) return '';
+  const s = Math.max(0, Math.floor((now - ms) / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+/** ▰▰▰▰▱ meter, `cells` wide, filled proportionally (never rounds a gap to full). */
+export function meter(live, expected, cells = 5) {
+  if (!expected) return '▱'.repeat(cells);
+  let f = Math.round((live / expected) * cells);
+  if (live < expected && f >= cells) f = cells - 1;
+  if (live > 0 && f === 0) f = 1;
+  return '▰'.repeat(f) + '▱'.repeat(cells - f);
+}
+
+export function clockLondon(ms = Date.now()) {
+  try {
+    return new Intl.DateTimeFormat('en-GB', {
+      timeZone: 'Europe/London', hour: '2-digit', minute: '2-digit', hour12: false,
+    }).format(new Date(ms));
+  } catch { return new Date(ms).toISOString().slice(11, 16); }
+}
+
+/** Plain-words account of a measure for the "do" line. */
+export function firstMeasure(item) {
+  const ms = (item && item.L2 && item.L2.measures) || [];
+  return ms[0] || null;
+}
+
+export function whenText(w, now = Date.now()) {
+  if (!w) return '';
+  const parts = [];
+  if (w.clock) parts.push(w.clock);
+  else if (w.since) parts.push(`${ageOf(w.since, now)} ago`);
+  if (w.waited_ms != null && !w.clock) parts.push(`waiting ${ageOf(now - w.waited_ms, now)}`);
+  return parts.join(' · ');
+}
+
+/** Label for a changed[] entry in plain words. */
+export function changedWords(c) {
+  const o = c.outcome ? `${c.outcome}` : (c.to ? `${c.from ? c.from + ' → ' : ''}${c.to}` : '');
+  return o;
+}
+
+/** Blind spot sentence list from cannot_see, names not counts where we have names. */
+export function blindSpots(cs) {
+  cs = cs || {};
+  const nm = (x) => (typeof x === 'string' ? x : x && (x.feed || x.name || x.id || x.label)) || '';
+  const parts = [];
+  const silent = (cs.silent || []).map(nm).filter(Boolean);
+  const failing = (cs.failing || []).map(nm).filter(Boolean);
+  const stale = (cs.stale || []).map(nm).filter(Boolean);
+  const unwired = (cs.unwired || []).map(nm).filter(Boolean);
+  if (failing.length) parts.push({ k: 'failing', text: `failing: ${failing.join(', ')}` });
+  if (silent.length) parts.push({ k: 'silent', text: `silent: ${silent.join(', ')}` });
+  if (stale.length) parts.push({ k: 'stale', text: `stale: ${stale.join(', ')}` });
+  if (unwired.length) parts.push({ k: 'unwired', text: `not wired up: ${unwired.join(', ')}` });
+  return parts;
+}
+
+/** HH:MM:SS London clock for the living deck header. */
+export function clockLondonSec(ms = Date.now()) {
+  try {
+    return new Intl.DateTimeFormat('en-GB', {
+      timeZone: 'Europe/London', hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false,
+    }).format(new Date(ms));
+  } catch { return new Date(ms).toISOString().slice(11, 19); }
+}
+
+export const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/** Whether the startup intro should play. Pure so it is testable. */
+export function shouldIntro({ noIntro = false, env = process.env, isTTY = true } = {}) {
+  if (noIntro || !isTTY) return false;
+  if (env.NO_COLOR || env.QUOX_TUI_LITE) return false;
+  return true;
+}

package/lib/lucid/sitrep.js

@@ -0,0 +1,173 @@
+/**
+ * `quox lucid --sitrep`: a one-shot, width-aware ANSI snapshot of the LUCID
+ * situation, built to read well in a terminal and when pasted into a chat.
+ * Pure: renderSitrep(situation, opts) -> string. Colour is explicit (opts.color).
+ */
+import {
+  GLYPH, STATE_HEX, URGENCY, PALETTE, wrap, clip, padEnd, vlen, ageOf, meter,
+  clockLondon, firstMeasure, whenText, changedWords, blindSpots,
+} from './fmt.js';
+
+const R = '\x1b[0m';
+
+export function makePainter(color) {
+  const rgb = (hex) => {
+    const n = parseInt(hex.slice(1), 16);
+    return `\x1b[38;2;${(n >> 16) & 255};${(n >> 8) & 255};${n & 255}m`;
+  };
+  const wrapSeq = (seq, s) => (color && s !== '' ? `${seq}${s}${R}` : s);
+  return {
+    color,
+    fg: (hex, s) => wrapSeq(rgb(hex), s),
+    bold: (s) => wrapSeq('\x1b[1m', s),
+    dim: (s) => wrapSeq(rgb(PALETTE.dim), s),
+    muted: (s) => wrapSeq(rgb(PALETTE.muted), s),
+    boldFg: (hex, s) => wrapSeq(`\x1b[1m${rgb(hex)}`, s),
+    pill: (hex, s) => (color ? `\x1b[48;2;${parseInt(hex.slice(1, 3), 16)};${parseInt(hex.slice(3, 5), 16)};${parseInt(hex.slice(5, 7), 16)}m\x1b[38;2;17;24;39m\x1b[1m[${s}]${R}` : `[${s}]`),
+  };
+}
+
+function tile(area, w, p, now) {
+  const inner = w - 4;
+  const hex = STATE_HEX[area.state] || STATE_HEX.unknown;
+  const glyph = GLYPH[area.state] || GLYPH.unknown;
+  const label = clip(area.label || area.area, inner - 3);
+  const topPlain = `─ ${glyph} ${label} `;
+  const top = p.fg(PALETTE.dim, '╭') + p.fg(PALETTE.dim, '─ ') + p.boldFg(hex, glyph) + ' ' + p.bold(label) + ' '
+    + p.fg(PALETTE.dim, '─'.repeat(Math.max(0, w - 2 - [...topPlain].length)) + '╮');
+  let body = wrap(area.L0 || 'No signal yet.', inner);
+  if (body.length > 3) body = [...body.slice(0, 2), clip(body[2] + ' ' + body.slice(3).join(' '), inner)];
+  const rows = body.map((l) => p.fg(area.state === 'ok' ? PALETTE.muted : PALETTE.text, l));
+  const last = area.last;
+  if (last) {
+    const tail = `${last.outcome ? ` (${last.outcome})` : ''} ${ageOf(last.ts, now)} ago`;
+    rows.push(p.dim(`last: ${clip(last.L0, Math.max(6, inner - 6 - [...tail].length))}${tail}`));
+  } else rows.push(p.dim('nothing yet'));
+  const v = p.fg(PALETTE.dim, '│');
+  const mid = rows.map((r) => `${v} ${padEnd(r, inner)} ${v}`);
+  const bot = p.fg(PALETTE.dim, '╰' + '─'.repeat(w - 2) + '╯');
+  return [top, ...mid, bot];
+}
+
+function grid(tiles, width, p, now) {
+  const gap = 1;
+  const tw = Math.floor((width - gap) / 2);
+  const out = [];
+  for (let i = 0; i < tiles.length; i += 2) {
+    const a = tile(tiles[i], tw, p, now);
+    const b = tiles[i + 1] ? tile(tiles[i + 1], tw, p, now) : [];
+    const h = Math.max(a.length, b.length);
+    const fill = (t, idx, wd) => {
+      if (t[idx] !== undefined) return t[idx];
+      // pad short tile with an empty bordered row before its bottom edge
+      return ' '.repeat(wd);
+    };
+    // equalise heights by inserting blank rows before the bottom border
+    const eq = (t) => {
+      if (!t.length) return t;
+      const bottom = t[t.length - 1];
+      const row = `${p.fg(PALETTE.dim, '│')}${' '.repeat(tw - 2)}${p.fg(PALETTE.dim, '│')}`;
+      const body = t.slice(0, -1);
+      while (body.length < h - 1) body.push(row);
+      return [...body, bottom];
+    };
+    const ea = eq(a), eb = eq(b);
+    for (let k = 0; k < h; k++) out.push(`${fill(ea, k, tw)}${' '.repeat(gap)}${eb.length ? fill(eb, k, tw) : ''}`.trimEnd());
+  }
+  return out;
+}
+
+function section(title, width, p, extra = '') {
+  const t = ` ${title}${extra ? ' ' + extra : ''} `;
+  return p.boldFg(PALETTE.accent, title) + (extra ? ' ' + p.dim(extra) : '') + ' ' + p.fg(PALETTE.dim, '─'.repeat(Math.max(2, width - vlen(t))));
+}
+
+export function renderSitrep(data, opts = {}) {
+  const width = Math.max(60, Math.min(opts.width || 100, 140));
+  const now = opts.now ?? Date.now();
+  const p = makePainter(opts.color !== false);
+  const sit = (data && data.situation) || data || {};
+  const cs = sit.cannot_see || {};
+  const cov = cs.coverage || { live: 0, expected: 0 };
+  const lines = [];
+
+  const sep = p.dim('│');
+  const left = `${p.boldFg(PALETTE.brand, '◉ LUCID')} ${sep} ${p.bold('sitrep')} ${sep} ${clockLondon(now)} ${p.dim('·')} `
+    + `${p.fg(cov.live < cov.expected ? STATE_HEX.attention : STATE_HEX.ok, `${cov.live}/${cov.expected}`)} sources`;
+  lines.push(left);
+  lines.push(p.fg(PALETTE.dim, '━'.repeat(width)));
+
+  lines.push('');
+  for (const l of wrap(sit.L0 || 'No briefing available.', width)) lines.push(p.fg(PALETTE.text, l));
+  lines.push('');
+
+  const areas = sit.areas || [];
+  if (areas.length) {
+    lines.push(...grid(areas, width, p, now));
+    lines.push('');
+  }
+
+  const needs = sit.needs_you || [];
+  lines.push(section('NEEDS YOU', width, p, needs.length ? `${needs.length}` : ''));
+  if (!needs.length) {
+    lines.push(p.fg(STATE_HEX.ok, '  Nothing needs you right now.') + (cs.silent && cs.silent.length ? p.dim('  (but see what I can\'t see)') : ''));
+  }
+  const iw = width - 5;
+  needs.forEach((it, i) => {
+    const u = URGENCY[it.urgency] || URGENCY.whenever;
+    const num = String(i + 1).padStart(2);
+    lines.push('');
+    lines.push(`${p.dim(num + '.')} ${p.pill(u.hex, u.label)} ${p.bold(clip(it.L0 || '', width - 8 - u.label.length))}`);
+    const a = it.L1 || {};
+    const field = (k, v) => {
+      if (!v) return;
+      const wl = wrap(v, iw - 6);
+      wl.forEach((l, j) => lines.push(`     ${j === 0 ? p.dim(k.padEnd(5)) : '     '}${p.fg(PALETTE.muted, l)}`));
+    };
+    field('Who', a.who); field('What', a.what); field('Why', a.why); field('When', whenText(a.when, now));
+    const m = firstMeasure(it);
+    if (m) {
+      const say = m.say || m.label;
+      lines.push(`     ${p.boldFg(PALETTE.brand, '→ do:')} ${p.fg(PALETTE.text, clip(say, iw - 8))}`);
+      const cmd = m.command || m.url;
+      if (cmd) lines.push(`          ${p.fg(PALETTE.code, clip(cmd, iw - 5))}`);
+    }
+  });
+  lines.push('');
+
+  const changed = sit.changed || [];
+  lines.push(section('SINCE YOU LOOKED', width, p, changed.length ? `${changed.length}` : ''));
+  if (!changed.length) lines.push(p.dim('  Nothing has changed.'));
+  for (const c of changed.slice(0, 8)) {
+    const o = changedWords(c);
+    const tail = `${o ? o + ' ' : ''}${ageOf(c.ts, now)} ago`;
+    lines.push(`  ${p.dim('•')} ${clip(c.L0 || '', width - 6 - tail.length)} ${p.dim(tail)}`);
+  }
+  if (changed.length > 8) lines.push(p.dim(`  … and ${changed.length - 8} more`));
+  lines.push('');
+
+  const da = sit.doesnt_add_up || [];
+  if (da.length) {
+    lines.push(section("DOESN'T ADD UP", width, p, `${da.length}`));
+    for (const x of da.slice(0, 5)) {
+      lines.push(`  ${p.dim('•')} ${p.bold(clip(x.L0 || '', width - 6))}${x.urgent ? ' ' + p.pill(URGENCY.today.hex, 'TODAY') : ''}`);
+      for (const [k, v] of [['Claimed', x.claimed], ['Observed', x.observed]]) {
+        if (!v) continue;
+        wrap(v, width - 16).forEach((l, j) => lines.push(`     ${j === 0 ? p.dim(k.padEnd(9)) : ' '.repeat(9)}${p.fg(PALETTE.muted, l)}`));
+      }
+    }
+    if (da.length > 5) lines.push(p.dim(`  … and ${da.length - 5} more (quox lucid blind)`));
+    lines.push('');
+  }
+
+  lines.push(section("WHAT I CAN'T SEE", width, p, `${meter(cov.live, cov.expected)} ${cov.live}/${cov.expected}`));
+  const spots = blindSpots(cs);
+  if (!spots.length && cov.live >= cov.expected) lines.push(p.dim('  Every expected source is speaking.'));
+  else if (!spots.length) lines.push(p.fg(STATE_HEX.attention, `  ${cov.expected - cov.live} expected source(s) are not reporting.`));
+  for (const s of spots) {
+    for (const [j, l] of wrap(s.text, width - 4).entries()) {
+      lines.push(`  ${p.fg(s.k === 'failing' ? STATE_HEX.blind : STATE_HEX.attention, l)}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}

package/lib/plugins/loader.js

@@ -0,0 +1,93 @@
+/**
+ * Plugin loader for QuoxCLI
+ *
+ * Discovers and loads plugins from:
+ *   1. ~/.quox/plugins/  (user plugins)
+ *   2. QUOX_PLUGIN_DIR env var (custom path)
+ *
+ * Plugin format: each plugin is a directory with an index.js that exports:
+ *   { name, version, description, register(program, context) }
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+
+function getPluginDirs() {
+  const dirs = [join(homedir(), '.quox', 'plugins')];
+  if (process.env.QUOX_PLUGIN_DIR) {
+    dirs.push(process.env.QUOX_PLUGIN_DIR);
+  }
+  return dirs;
+}
+
+export async function discoverPlugins() {
+  const plugins = [];
+
+  for (const dir of getPluginDirs()) {
+    if (!existsSync(dir)) continue;
+
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+      const pluginPath = join(dir, entry);
+      if (!statSync(pluginPath).isDirectory()) continue;
+
+      const indexPath = join(pluginPath, 'index.js');
+      if (!existsSync(indexPath)) continue;
+
+      plugins.push({
+        name: entry,
+        path: pluginPath,
+        indexPath,
+      });
+    }
+  }
+
+  return plugins;
+}
+
+export async function loadPlugin(pluginInfo) {
+  try {
+    const moduleUrl = pathToFileURL(pluginInfo.indexPath).href;
+    const mod = await import(moduleUrl);
+
+    if (typeof mod.register !== 'function') {
+      throw new Error(`Plugin "${pluginInfo.name}" does not export a register() function`);
+    }
+
+    return {
+      name: mod.name || pluginInfo.name,
+      version: mod.version || '0.0.0',
+      description: mod.description || '',
+      register: mod.register,
+    };
+  } catch (err) {
+    return {
+      name: pluginInfo.name,
+      error: err.message,
+    };
+  }
+}
+
+export async function loadAllPlugins(program, context) {
+  const discovered = await discoverPlugins();
+  const loaded = [];
+  const errors = [];
+
+  for (const pluginInfo of discovered) {
+    const plugin = await loadPlugin(pluginInfo);
+    if (plugin.error) {
+      errors.push({ name: plugin.name, error: plugin.error });
+    } else {
+      try {
+        plugin.register(program, context);
+        loaded.push({ name: plugin.name, version: plugin.version, description: plugin.description });
+      } catch (err) {
+        errors.push({ name: plugin.name, error: err.message });
+      }
+    }
+  }
+
+  return { loaded, errors };
+}

package/lib/quoxon/activity.js

@@ -0,0 +1,104 @@
+/**
+ * What is actually happening right now, as one honest word (CLI-QUOX indicator).
+ * Pure: the reducer feeds every real event through nextActivity and keeps the result on the turn.
+ * Rules: a word exists only because an event said so; between events the last true word stays (never
+ * invented, never rotated); unknown tools fall back to "Working" plus the tool name as detail.
+ * Words are capitalised present participles; the indicator appends the ellipsis.
+ *
+ * State: { word, detail, tone: 'work' | 'wait', flash: ms | null, since: ms }
+ */
+
+const clipD = (s, n = 40) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
+
+// Ordered: first match wins, so specific families come before generic ones. [regex, word, detail?]
+// Tool names are the real registry names (memory_search, bastion_ssh, quoxplan_set_status, ...).
+const TOOL_TABLE = [
+  [/^(memory_(save|update)|brain_save|brain_garden_apply)/, 'Remembering'],
+  [/^memory_forget/, 'Forgetting'],
+  [/^(memory_|brain_|search_wisdom)/, 'Recalling'],
+  [/^(fleet_|bastion_).*(exec|ssh|run|restart|command)|^(bastion_ssh|fleet_exec)/, 'Running', 'host'],
+  [/^(fleet_|bastion_)/, 'Looking up'],
+  [/^(email_send|contacts_send)/, 'Sending'],
+  [/^contacts_dial/, 'Dialling'],
+  [/^(email_draft|inbox_propose|email_reply)/, 'Drafting'],
+  [/^(email_|inbox_)/, 'Checking mail'],
+  [/^(qlarity_|browser_(screenshot|lighthouse|pdf|find_element|list_tabs|monitor))/, 'Inspecting'],
+  [/^(browser_|http_|fetch_|web_)/, 'Fetching'],
+  [/^(seo_|quoxseo)/, 'Analysing'],
+  [/^(delegate|agent_handoff|agent_delegate|ask_agent|agent_call)|handoff/, 'Delegating', 'target'],
+  [/^(quoxflow_|workflow_)/, 'Orchestrating'],
+  [/^(quoxplan_|plan_)/, 'Planning'],
+  [/^(ward_|volt_|receipt|verify)/, 'Verifying'],
+  [/^approval/, 'Checking approvals'],
+  [/^calendar_/, 'Scheduling'],
+  [/^(search_|query_)|_search$|_find$/, 'Searching'],
+  [/(^|_)(write|edit|create)_(file|doc)|^file_(write|save)|^plan_doc/, 'Writing'],
+  [/(^|_)read(_|$)|^file_(read|get|open)/, 'Reading'],
+  [/(^|_)(list|get|status)$|^contacts_/, 'Looking up'],
+];
+
+/** { 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();
+  for (const [re, word, d] of TOOL_TABLE) {
+    if (re.test(name)) return { word, detail: d ? (clipD(ev[d] ?? ev.target ?? ev.host) || null) : null };
+  }
+  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 });
+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. */
+function traceWord(ev) {
+  const label = String(ev.label || '').toLowerCase();
+  if (ev.protocol === 'aee' && /envelope opened/.test(label)) return ['Recording', 'envelope'];
+  if (ev.protocol === 'aocl') {
+    if (/\bl1\b|identity/.test(label)) return ['Verifying', 'L1 identity'];
+    if (/\bl3\b|policy/.test(label)) return ['Governing', 'L3 policy'];
+    return null;
+  }
+  if (ev.protocol === 'ward' && /witness/.test(label)) return ['Witnessing', null];
+  return null;
+}
+
+/**
+ * Next activity for a stream event. ctx = { hasText } (has any answer text arrived yet).
+ * Returns prev unchanged for events that say nothing new.
+ */
+export function nextActivity(prev, ev, now = 0, ctx = {}) {
+  const p = prev || initialActivity(now);
+  switch (ev?.type) {
+    case 'thinking': {
+      const stage = String(ev.stage || ''), msg = String(ev.message || '').replace(/[.…\s]+$/u, '');
+      if (stage === 'routing') return mk('Routing', (msg.match(/\bto\s+(.+)$/i) || [])[1] || null, now);
+      if (stage === 'routing_detail') return mk('Routing', msg || p.detail, now);
+      if (stage === 'processing') return mk('Reading', null, now);
+      if (stage === 'api_call') {
+        if (ctx.hasText) return p;
+        return mk('Thinking', (msg.match(/Calling (.+?) API/i) || [])[1] || null, now);
+      }
+      if (stage.includes('tool') && msg) { const t = toolWord(msg); return mk(t.word, t.detail, now); }
+      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.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);
+    case 'steer.accepted': return mk('Adjusting', null, now);
+    case 'text.delta': case 'chunk': return p.word === 'Writing' && p.tone === 'work' ? p : mk('Writing', null, now);
+    case 'retry': case 'reconnecting': return mk('Reconnecting', null, now);
+    case 'resumed': return mk('Resuming', 'reattached', now);
+    case 'done': return mk('Confirming', 'waiting for the server', now);
+    case 'error': return { ...p, flash: now };
+    default: return p;
+  }
+}
+
+/** Client-side actions that are also true events (the human pressed Esc). */
+export function actionActivity(prev, action, now = 0) {
+  if (action?.type === 'turn.begin') return initialActivity(action.now ?? now);
+  if (action?.type === 'interrupt.requested') return mk('Stopping', null, action.now ?? now);
+  return prev;
+}