quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/extensions.js

@@ -0,0 +1,276 @@
+/**
+ * Extension host (QUOXON, 2026-10-26; contract: EXTENSIONS.md). Optional npm packages that add surfaces to quoxon
+ * (a MIDI pad deck, a status bar, ...). Nothing loads unless the package is installed AND listed in
+ * ~/.quox/extensions.json (`quox ext add <pkg>`, `/ext list|on|off <name>`). Core knows nothing about any one extension:
+ * it pushes one generic snapshot (buildSnapshot) and accepts three emit actions (open_approval, pick, alert_ack).
+ * An extension can OPEN an approval or PRESELECT an answer; it can never resolve one.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+export const THROTTLE_MS = 1000;
+export const notInstalled = (name) => `not installed: npm i -g ${name}`;
+const HEALTH = new Set(['ok', 'warn', 'down']);
+const CHAIN = new Set(['ok', 'broken', 'unknown']);
+const FLEET_MAX = 16;
+
+// ---- the listing: ~/.quox/extensions.json ---------------------------------------------------------------------------
+export const extListPath = (home = os.homedir()) => path.join(home, '.quox', 'extensions.json');
+const validName = (n) => typeof n === 'string' && /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(n);
+
+export function readExtList(file = extListPath()) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return (Array.isArray(j?.extensions) ? j.extensions : []).filter((x) => validName(x?.name)).map((x) => ({ name: x.name, enabled: x.enabled !== false }));
+  } catch { return []; } // no file or unreadable: nothing is listed, so nothing loads
+}
+export function writeExtList(list, file = extListPath()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ extensions: list }, null, 2) + '\n');
+}
+export function extAdd(name, file = extListPath()) {
+  if (!validName(name)) return { ok: false, text: `"${name}" is not a package name.` };
+  const list = readExtList(file);
+  const had = list.find((x) => x.name === name);
+  if (had) had.enabled = true; else list.push({ name, enabled: true });
+  writeExtList(list, file);
+  return { ok: true, text: `${name} is listed. It loads in quoxon once installed (npm i -g ${name}).` };
+}
+export function extRemove(name, file = extListPath()) {
+  const list = readExtList(file);
+  if (!list.some((x) => x.name === name)) return { ok: false, text: `${name} is not listed.` };
+  writeExtList(list.filter((x) => x.name !== name), file);
+  return { ok: true, text: `${name} is no longer listed.` };
+}
+export function extSetEnabled(name, enabled, file = extListPath()) {
+  const list = readExtList(file);
+  const it = list.find((x) => x.name === name);
+  if (!it) return { ok: false, text: `${name} is not listed. quox ext add ${name}` };
+  it.enabled = enabled; writeExtList(list, file);
+  return { ok: true, text: `${name} ${enabled ? 'enabled' : 'disabled'}.` };
+}
+
+// ---- resolution: env override, local, global ------------------------------------------------------------------------
+export const envKey = (name) => `QUOX_EXT_${String(name).replace(/^@/, '').replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()}_MODULE`;
+const defaultImporter = (spec) => import(spec);
+const NOT_FOUND = (e) => e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND';
+
+let npmRootCache; // `npm root -g` runs at most once per process
+export function globalNpmRoot(run = execFileSync) {
+  if (npmRootCache !== undefined) return npmRootCache;
+  try { npmRootCache = String(run('npm', ['root', '-g'], { encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] })).trim() || null; } catch { npmRootCache = null; }
+  return npmRootCache;
+}
+export const _resetNpmRootCache = () => { npmRootCache = undefined; };
+
+/** The file a package directory imports: exports["."] (import/default), module, main, index.js. */
+export function packageEntry(dir) {
+  try {
+    const pj = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const ex = pj.exports;
+    const root = typeof ex === 'string' ? ex : (ex?.['.'] ?? ex);
+    const pick = typeof root === 'string' ? root : (root?.import || root?.default || (typeof root?.import === 'object' ? root.import.default : null));
+    return path.join(dir, pick || pj.module || pj.main || 'index.js');
+  } catch { return path.join(dir, 'index.js'); }
+}
+
+/**
+ * Find and import one extension. Order: QUOX_EXT_<NAME>_MODULE, local import(name), then the global npm root
+ * (dirname(execPath)/../lib/node_modules first, which costs no spawn; `npm root -g` once, cached, only if that misses).
+ * -> { ok:true, mod, where } | { ok:false, notFound:true, tried:[...] } | { ok:false, error }
+ */
+export async function resolveExtension(name, { env = process.env, importer = defaultImporter, execPath = process.execPath, npmRoot = globalNpmRoot, exists = fs.existsSync } = {}) {
+  const tried = [];
+  const ov = env?.[envKey(name)];
+  if (ov) {
+    tried.push(`${envKey(name)}=${ov}`);
+    try { return { ok: true, mod: await importer(path.isAbsolute(ov) ? pathToFileURL(ov).href : ov), where: `env ${envKey(name)} (${ov})` }; }
+    catch (e) { return { ok: false, error: e?.message || String(e), tried }; } // an override that fails is an error, never a silent fall-through
+  }
+  tried.push(`local import('${name}')`);
+  try { return { ok: true, mod: await importer(name), where: `local (${name})` }; }
+  catch (e) { if (!NOT_FOUND(e)) return { ok: false, error: e?.message || String(e), tried }; }
+  const roots = [];
+  const guess = path.join(path.dirname(execPath || ''), '..', 'lib', 'node_modules');
+  roots.push(guess);
+  let spawned = false;
+  for (let i = 0; i < 2; i++) {
+    for (const root of roots.splice(0)) {
+      const dir = path.join(root, name);
+      tried.push(`global ${dir}`);
+      if (!exists(dir)) continue;
+      try { return { ok: true, mod: await importer(pathToFileURL(packageEntry(dir)).href), where: `global (${dir})` }; }
+      catch (e) { return { ok: false, error: e?.message || String(e), tried }; }
+    }
+    if (spawned) break;
+    spawned = true;
+    const g = npmRoot();
+    if (g && path.resolve(g) !== path.resolve(guess)) roots.push(g);
+  }
+  return { ok: false, notFound: true, tried };
+}
+
+/** An extension module -> { name, version, commands, create } or null. Accepts default export or the module itself. */
+export function normalizeExtension(mod, fallbackName) {
+  const ext = mod?.default && typeof mod.default === 'object' ? mod.default : mod;
+  const create = typeof ext?.create === 'function' ? ext.create : (typeof mod?.createDeck === 'function' ? mod.createDeck : null); // createDeck: quoxdeck v1
+  if (!create) return null;
+  const commands = (Array.isArray(ext.commands) ? ext.commands : []).filter((c) => /^\/[a-z][\w-]*$/i.test(c?.name || '') && typeof c.run === 'function');
+  return { name: ext.name || fallbackName, version: ext.version || null, commands, create };
+}
+
+// ---- the snapshot every extension gets ------------------------------------------------------------------------------
+function itemRisk(it) {
+  return it?.privileged === true || it?.payload?.privileged === true || it?.risk === 'high' || it?.payload?.risk === 'high' ? 'high' : 'low';
+}
+const hostState = (s) => (s === 'ok' || s === 'warn' || s === 'down' ? s : (/^(down|offline|failed|unreachable)$/i.test(s || '') ? 'down' : (/^(warn|warning|degraded)$/i.test(s || '') ? 'warn' : 'ok')));
+
+/** Pure. fleet input: [{id|name, health|state}] or null. */
+export function buildFleet(hosts) {
+  if (!Array.isArray(hosts)) return { total: 0, online: 0, offline: 0, warn: 0, hosts: [] };
+  const list = hosts.map((h) => ({ name: String(h.name ?? h.id ?? '').slice(0, 60), state: hostState(h.state ?? h.health) }));
+  return {
+    total: list.length, online: list.filter((h) => h.state !== 'down').length,
+    offline: list.filter((h) => h.state === 'down').length, warn: list.filter((h) => h.state === 'warn').length,
+    hosts: list.slice(0, FLEET_MAX)
+  };
+}
+
+export function buildSnapshot({ org = null, items = [], health = {}, loops = [], event = null, fleet = null, evidence = null, sessions = null } = {}) {
+  const list = (items || []).map((it, i) => {
+    const row = {
+      n: i + 1, id: it.id ?? null, risk: itemRisk(it),
+      title: String(it.title || it.summary || it.payload?.title || it.payload?.question || it.payload?.summary || '').slice(0, 120),
+      agent: it.agent || it.requester || it.payload?.agent || null
+    };
+    const opts = Array.isArray(it.payload?.options) ? it.payload.options.filter((o) => o?.key != null).map((o) => ({ key: String(o.key), label: String(o.label ?? o.key) })) : [];
+    if (opts.length) row.options = opts;
+    return row;
+  });
+  const h = {};
+  for (const [k, v] of Object.entries(health || {})) if (HEALTH.has(v)) h[k] = v;
+  const state = {
+    org: { id: org?.id ?? null, name: org?.name ?? null },
+    approvals: { count: list.length, items: list },
+    health: h,
+    loops: (loops || []).map((l) => ({ id: l.id, title: String(l.title || ''), turn: Number(l.turn) || 0, max: Number(l.max) || 0, status: l.status || 'running' })),
+    fleet: Array.isArray(fleet) ? buildFleet(fleet) : (fleet && typeof fleet === 'object' ? { total: fleet.total | 0, online: fleet.online | 0, offline: fleet.offline | 0, warn: fleet.warn | 0, hosts: (fleet.hosts || []).slice(0, FLEET_MAX) } : buildFleet(null)),
+    evidence: { chain: CHAIN.has(evidence?.chain) ? evidence.chain : 'unknown', checked_at: evidence?.checked_at ?? null },
+    sessions: { active: Math.max(0, Number(sessions?.active) || 0) }
+  };
+  if (event) state.event = { kind: event.kind, text: event.text, level: event.level || 'info' };
+  return state;
+}
+
+/** What the composer is filled with when an extension picks an option; the user still presses Enter. null = nothing to preselect. */
+export function pickDraft(item, n, option) {
+  if (!item) return null;
+  const opt = String(option ?? '').trim();
+  if (!opt) return null;
+  const keys = (item.payload?.options || []).map((o) => String(o.key));
+  if (keys.length) return keys.includes(opt) ? `/answer ${n} ${opt}` : null;
+  if (/^(y|yes|approve)$/i.test(opt)) return `/approve ${n}`;
+  if (/^(n|no|deny)$/i.test(opt)) return `/deny ${n} `;
+  return null;
+}
+
+// ---- the host -------------------------------------------------------------------------------------------------------
+/**
+ * handlers: { openApproval(n), preselect(n, option), changed() } are the window's own actions. getSettings() feeds create().
+ * Loaded extensions all receive the same deduped, 1/s-throttled snapshot.
+ */
+export function createExtensionHost({ importer = defaultImporter, env = process.env, execPath, npmRoot, exists, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout,
+  handlers = {}, log = () => {}, getSettings = () => ({}) } = {}) {
+  const loaded = new Map(); // name -> { ext, inst, where }
+  const starting = new Map();
+  let lastSent = 0; let lastKey = null; let pending = null; let timer = null;
+  let event = null; const prevLoops = new Map(); let prevCount = null;
+
+  const sendAll = (state) => {
+    const key = JSON.stringify(state);
+    if (key === lastKey) return;
+    lastKey = key; lastSent = now();
+    for (const [name, l] of loaded) { try { l.inst?.update?.(state); } catch (e) { log(`extension ${name} update failed: ${e?.message || e}`); } }
+  };
+  const flush = () => { timer = null; if (pending && loaded.size) { const s = pending; pending = null; sendAll(s); } };
+
+  const emitFor = (name) => (msg) => {
+    if (!loaded.has(name) || !msg || typeof msg !== 'object') return false; // ignored unless this extension is loaded
+    try {
+      if (msg.type === 'open_approval' && Number.isInteger(msg.n) && msg.n >= 1) { handlers.openApproval?.(msg.n); return true; }
+      if (msg.type === 'pick' && Number.isInteger(msg.n) && msg.n >= 1) { handlers.preselect?.(msg.n, msg.option); return true; }
+      if (msg.type === 'alert_ack') { event = null; handlers.changed?.(); return true; }
+    } catch (e) { log(`extension ${name} emit failed: ${e?.message || e}`); }
+    return false;
+  };
+
+  const host = {
+    armed: () => loaded.size > 0,
+    isLoaded: (name) => loaded.has(name),
+    loadedNames: () => [...loaded.keys()],
+    where: (name) => loaded.get(name)?.where || null,
+    /** emit as one extension (tests and the shim); extensions get their own bound emit in create(). */
+    emit: (msg, name) => (name ? emitFor(name)(msg) : [...loaded.keys()].some((n) => emitFor(n)(msg))),
+    async load(name) {
+      if (loaded.has(name)) return { ok: true, text: `${name} is already loaded.` };
+      if (starting.has(name)) return starting.get(name);
+      const p = (async () => {
+        try {
+          const r = await resolveExtension(name, { env, importer, execPath, npmRoot, exists });
+          if (!r.ok && r.notFound) return { ok: false, notFound: true, text: `${name} ${notInstalled(name)} (looked in: ${r.tried.join('; ')})`, tried: r.tried };
+          if (!r.ok) return { ok: false, text: `${name} could not load: ${r.error}` };
+          const ext = normalizeExtension(r.mod, name);
+          if (!ext) return { ok: false, text: `${name} could not load: the package has no create().` };
+          let inst;
+          try { inst = ext.create({ emit: emitFor(name), log, settings: getSettings() }); } catch (e) { return { ok: false, text: `${name} could not start: ${e?.message || e}` }; }
+          loaded.set(name, { ext, inst, where: r.where });
+          lastKey = null; lastSent = 0; pending = null; event = null; prevLoops.clear(); prevCount = null;
+          handlers.changed?.();
+          return { ok: true, text: `${ext.name} is on (found: ${r.where}).`, ext };
+        } finally { starting.delete(name); }
+      })();
+      starting.set(name, p);
+      return p;
+    },
+    unload(name) {
+      const l = loaded.get(name);
+      if (!l) return { ok: true, text: `${name} was not loaded.` };
+      loaded.delete(name);
+      if (!loaded.size) { pending = null; lastKey = null; if (timer) { clearTimer(timer); timer = null; } }
+      try { l.inst?.close?.(); } catch (e) { log(`extension ${name} close failed: ${e?.message || e}`); }
+      handlers.changed?.();
+      return { ok: true, text: `${name} is off.` };
+    },
+    unloadAll() { for (const n of [...loaded.keys()]) host.unload(n); },
+    /** Slash commands of loaded extensions only. -> [{ name, help, ext }] */
+    commands: () => [...loaded.values()].flatMap((l) => l.ext.commands.map((c) => ({ name: c.name, help: c.help || '', ext: l.ext.name }))),
+    async runCommand(cmd, args, ctx = {}) {
+      for (const l of loaded.values()) {
+        const c = l.ext.commands.find((x) => x.name === cmd);
+        if (c) { try { return { handled: true, result: await c.run(args, { ...ctx, extension: l.ext.name, loaded: host.loadedNames() }) }; } catch (e) { return { handled: true, error: e?.message || String(e) }; } }
+      }
+      return { handled: false };
+    },
+    /** Push the current snapshot inputs: derives an event from changes, throttles to one update per second. */
+    push(input) {
+      if (!loaded.size) return;
+      const items = input?.items || [];
+      for (const l of input?.loops || []) {
+        const was = prevLoops.get(l.id);
+        if (was && was !== l.status && (l.status === 'done' || l.status === 'failed')) event = { kind: 'loop', text: `${l.title || l.id} ${l.status}`, level: l.status === 'failed' ? 'error' : 'ok' };
+        prevLoops.set(l.id, l.status);
+      }
+      if (prevCount != null && items.length > prevCount) event = { kind: 'approval', text: `${items.length} waiting`, level: 'warn' };
+      prevCount = items.length;
+      const state = buildSnapshot({ ...input, event });
+      const wait = THROTTLE_MS - (now() - lastSent);
+      if (wait <= 0 && !timer) { pending = null; sendAll(state); return; }
+      pending = state;
+      if (!timer) timer = setTimer(flush, Math.max(wait, 0));
+    }
+  };
+  return host;
+}

package/lib/quoxon/feedback.js

@@ -0,0 +1,50 @@
+/**
+ * /feedback: tell the Quox team something, through the public quox.ai feedback API
+ * (POST https://api.quox.ai/api/feedback, anonymous, 5 per hour per IP; lands in the quox.ai admin feedback view).
+ * /gripe stays the GitHub path. What is sent is type + message (the CLI version is appended to the message)
+ * and nothing else: no name, email, org, profile or token. The user sees the exact payload and says y first.
+ */
+export const FEEDBACK_URL = 'https://api.quox.ai/api/feedback';
+const MIN = 5, MAX = 5000; // the endpoint refuses outside these (api/routes/feedback.js in quox-website)
+const TIMEOUT_MS = 15000;
+
+/** -> { type:'feedback', message } | null when the endpoint would refuse it. */
+export function feedbackPayload(text, version) {
+  const body = String(text || '').trim();
+  if (body.length < MIN) return null;
+  const message = `${body}\n\n(sent with /feedback from quox CLI ${version || 'unknown'})`;
+  if (message.length > MAX) return null;
+  return { type: 'feedback', message };
+}
+
+/** The lines shown before asking: where it goes and exactly what is in the body. */
+export function feedbackPreview(payload, url = FEEDBACK_URL) {
+  return [
+    `POST ${url}  (the Quox team at quox.ai, not your Quox server)`,
+    'type: feedback',
+    'message:',
+    ...String(payload.message).split('\n').map(l => `  ${l}`),
+    'Nothing else: no name, email, org or token.',
+  ];
+}
+
+/** -> { ok:true, id, url } | { ok:false, message }. Status is checked before the body is trusted. */
+export async function sendFeedback(payload, { fetchImpl = globalThis.fetch, url = FEEDBACK_URL, version = null, timeoutMs = TIMEOUT_MS } = {}) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': `quox-cli/${version || 'unknown'}` },
+      body: JSON.stringify({ type: payload.type, message: payload.message }),
+      signal: ctl.signal,
+    });
+    let data = null;
+    try { data = await res.json(); } catch { data = null; }
+    if (!res.ok) return { ok: false, message: `HTTP ${res.status}: ${(data && data.error) || 'the feedback API refused it'}` };
+    if (!data || data.success !== true) return { ok: false, message: `HTTP ${res.status} but the reply did not confirm it was stored` };
+    return { ok: true, id: data.id ?? null, url };
+  } catch (e) {
+    return { ok: false, message: e?.name === 'AbortError' ? `no answer from ${url} within ${Math.round(timeoutMs / 1000)} s` : (e?.message || 'failed') };
+  } finally { clearTimeout(t); }
+}

package/lib/quoxon/gallery.js

@@ -1,17 +1,19 @@
 /**
  * `quox motion`: the product version of the animation lab (~/quoxon-work/intro/lab). Plays every Q motion
- * with a caption: Orbit & Lock, Portal, Particle collapse, the Dragon's Eye, the perpetual status Q in its
+ * with a caption: Orbit & Lock, Portal, Particle collapse, the perpetual status Q in its
  * four states, the hello, the composer ring and the reveal effects. No server, no account, nothing sent.
  *
  * Scenes are pure: galleryScenes() returns { id, title, caption, ms, frame(t) -> ANSI lines }. runGallery()
  * is the only part that touches a terminal (cursor, timers, signals).
  */
 import {
-  labSize, orbitCellsAt, portalCellsAt, particleCellsAt, eyeCellsAt, cellsToAnsi, qCells,
-  INTRO_MS, PORTAL_MS, EYE_MS, SKY, VIOLET, AMBER,
+  labSize, orbitCellsAt, portalCellsAt, particleCellsAt, cellsToAnsi, qCells,
+  INTRO_MS, PORTAL_MS, SKY, VIOLET, AMBER,
 } from './qart.js';
 import { qGlyph, glyphAnsi, GLYPH_STATES } from './qglyph.js';
 import { helloCells, helloAnsi, helloGradient, helloMs } from './qhello.js';
+import { CLIPS, MOOD_CLIPS, clipCells, clipCaption } from './qdragonScenes.js';
+import { isLight } from './theme.js';
 
 const RESET = '\x1b[0m';
 const fg = (rgb) => `\x1b[38;2;${rgb.map((v) => Math.max(0, Math.min(255, Math.round(v)))).join(';')}m`;
@@ -125,8 +127,12 @@ export const PERP_MS = 2600;
  * The gallery's scenes for a terminal. narrow forces the 40-column layout (the compact particle Q).
  * Each scene: { id, title, caption, ms, frame(t, { mono }) -> string[] }.
  */
-export function galleryScenes({ cols = 100, rows = 30, narrow = false } = {}) {
+export function galleryScenes({ cols = 100, rows = 30, narrow = false, theme = isLight() ? 'light' : 'dark' } = {}) {
   const W = narrow ? 40 : cols;
+  // the dragon (qdragonScenes.js): eyes as quadrant blocks with a background colour, the lab's light palette on light terminals
+  const fit = (str) => (str.length > W ? str.slice(0, W - 1) + '…' : str);
+  const dragon = (name, t, o) => [...art(clipCells(name, t, { cols: W, theme, mono: o.mono })), '', paint(fit(clipCaption(name, t)), MUTED, o.mono)];
+  const MOOD_SPAN = MOOD_CLIPS.map((m) => CLIPS[m].dur + 400);
   const size = narrow ? 'small' : labSize(W, rows);
   const big = size === 'small' ? 'small' : size;
   const art = (cells) => cellsToAnsi(cells);
@@ -138,8 +144,6 @@ export function galleryScenes({ cols = 100, rows = 30, narrow = false } = {}) {
       frame: (t, o) => art(portalCellsAt(big, t, { color: !o.mono })) },
     { id: 'particle', title: 'Particle collapse', caption: 'density rises on a circle, then collapses into the compact Q', ms: 1100 + 500,
       frame: (t, o) => art(particleCellsAt('small', t, { color: !o.mono })) },
-    { id: 'eye', title: "The Dragon's Eye", caption: 'a slit-pupil eye opens in the bowl, blinks once, and dissolves back into the Q (/eye; rarely on launch)', ms: EYE_MS + 500,
-      frame: (t, o) => art(eyeCellsAt(big, t, { color: !o.mono })) },
     { id: 'hello', title: 'Hello', caption: 'the Q locks, then says hello: the line decodes in from katakana with a short afterglow', ms: INTRO_MS + helloMs(hello) + 600,
       frame: (t, o) => {
         const q = art(t < INTRO_MS ? orbitCellsAt(big, t, { color: !o.mono }) : qCells(big, { color: !o.mono }));
@@ -162,9 +166,19 @@ export function galleryScenes({ cols = 100, rows = 30, narrow = false } = {}) {
       frame: (t, o) => ringLines(Math.min(W - 2, 72), ringState(t), o.mono) },
     { id: 'fx', title: 'Reveal effects', caption: 'tool row, answer drop-in, approval arming, receipt seal, ProofFlow, closing line', ms: FX_MS,
       frame: (t, o) => fxLines(t, Math.min(W - 2, 78), o.mono) },
+    { id: 'dragon', title: CLIPS.pick.title, caption: CLIPS.pick.caption, ms: CLIPS.pick.dur, frame: (t, o) => dragon('pick', t, o) },
+    { id: 'dragon-fire', title: CLIPS.fire.title, caption: CLIPS.fire.caption, ms: CLIPS.fire.dur, frame: (t, o) => dragon('fire', t, o) },
+    { id: 'dragon-moods', title: 'Dragon moods', caption: 'at the cinematic motion level the dragon reacts: wide eyes and an amber glint while it waits for you, a wink when done, a puff of smoke on failure, and a greeting on launch',
+      ms: MOOD_SPAN.reduce((a, b) => a + b, 0),
+      frame: (t, o) => {
+        let i = 0, s0 = 0;
+        while (i < MOOD_CLIPS.length - 1 && t >= s0 + MOOD_SPAN[i]) s0 += MOOD_SPAN[i++];
+        const m = MOOD_CLIPS[i];
+        return [...art(clipCells(m, t - s0, { cols: Math.min(W, 64), theme, mono: o.mono })), '', paint(fit(`${m}: ${CLIPS[m].caption.split(':')[1].replace(/\s*\(.*\)$/, '').trim()}`), MUTED, o.mono)];
+      } },
   ];
 }
-export const SCENE_IDS = ['orbit', 'portal', 'particle', 'eye', 'hello', 'perpetual', 'ring', 'fx'];
+export const SCENE_IDS = ['orbit', 'portal', 'particle', 'hello', 'perpetual', 'ring', 'fx', 'dragon', 'dragon-fire', 'dragon-moods'];
 
 // ---- runner (the only impure part) ---------------------------------------------------------------------------
 const visible = (s) => s.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');  // eslint-disable-line no-control-regex

package/lib/quoxon/handoffOffer.js

@@ -0,0 +1,78 @@
+/**
+ * QUOXON handoff offer (owner, live 2026-10-17 19:51). Attached to TRIAGE-Q, the owner asked which VMs use the most CPU
+ * and memory; TRIAGE-Q had no fleet tools and told him to detach and ask CommanderQ. Offer, don't instruct: the server
+ * sends turn.handoff_suggested (from the turn's tool selection, never the answer text) and the TUI asks once:
+ *
+ *   ⚠ TRIAGE-Q asks: Hand this question to CommanderQ?
+ *     do     ask CommanderQ "which VMs use the most CPU and memory" once; you stay attached to TRIAGE-Q
+ *     why    TRIAGE-Q can't read VM stats.
+ *   ▶ Hand this question to CommanderQ? y yes · n no
+ *
+ * y sends the SAME question to CommanderQ for that one turn; the window stays attached. n does nothing.
+ */
+import { askText } from './ask.js';
+
+const clipQ = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t; };
+
+/** The suggestion from a turn event, when it applies to THIS window (attached to the agent it names). Else null. */
+export function handoffFromEvent(ev, attachedAgent) {
+  if (!ev || ev.type !== 'turn.handoff_suggested') return null;
+  const h = ev.handoff_suggested;
+  const at = String(attachedAgent || '').toLowerCase();
+  if (!h || typeof h !== 'object' || !h.agent || !at) return null;
+  if (String(h.agent).toLowerCase() === at) return null; // already talking to the target
+  if (h.from && String(h.from).toLowerCase() !== at) return null; // a suggestion about some other agent
+  return { agent: String(h.agent), name: String(h.name || h.agent), from: at, fromName: String(h.from_name || at.toUpperCase()), reason: String(h.reason || '').trim() };
+}
+
+/** The ask line (drawn as the approval-style card). question: the user's own words being handed over. */
+export function handoffAskText(h, question, cols = 100) {
+  const action = `ask ${h.name} "${clipQ(question, Math.max(20, cols - 60))}" once; you stay attached to ${h.fromName}`;
+  return askText(`Hand this question to ${h.name}?`, { keys: 'y/N', who: h.fromName, reason: h.reason, action });
+}
+
+/** The one line after a yes-path answer: who answered, and that nothing about the attach changed. */
+export const handoffAnsweredNote = (h) => `↪ ${h.name} answered that one. Still attached to ${h.fromName}.`;
+
+/** The agent's own suggested command, dropped because the handoff answers the question (never silently). */
+export const handoffSupersededNote = (h, line) => `↷ ${h.fromName} also suggested ${line || 'a command'}; not offered, because ${h.name} can answer the question itself.`;
+
+/** A handoff that could not be offered because a plan card is open (never silently). */
+export const handoffSkippedNote = (h) => `↷ ${h.name} could answer this, but the plan card is open, so the handoff is not offered.`;
+
+/**
+ * QUOXON handoff streak (owner, live 05:10-05:17): attached to TRIAGE-Q he asked three infra questions and every one ended
+ * in "Hand this question to CommanderQ?". When the SAME attached agent has suggested a handoff on 2 turns in a row, the
+ * card offers the bigger move (back to CommanderQ) instead of the same small one. c ("keep asking") silences the bigger
+ * offer until a new streak starts; a turn with no suggestion, or a different agent, breaks the streak.
+ */
+export function createHandoffStreak() {
+  let agent = null, count = 0, muted = false;
+  return {
+    /** A turn ended with a handoff suggestion from `from`. -> { count, escalate } */
+    offered(from) {
+      const f = String(from || '').toLowerCase();
+      if (f === agent) count += 1; else { agent = f; count = 1; muted = false; }
+      return { count, escalate: count >= 2 && !muted };
+    },
+    /** A turn ended without a suggestion (or the window moved agents): the streak is over. */
+    clear() { agent = null; count = 0; muted = false; },
+    /** n (just this one): the bigger offer needs a fresh run of two before it returns. */
+    restart() { count = 0; },
+    /** c (keep asking): no bigger offer until a new streak starts. */
+    mute() { muted = true; },
+    peek: () => ({ agent, count, muted }),
+  };
+}
+
+export const HANDOFF_BIG_KEYS = (h) => `y switch · n just this one · c keep asking ${h.fromName}`;
+
+/** The bigger card: offer to move the whole window back instead of handing over one more question. */
+export function handoffBiggerAskText(h, count) {
+  return askText(`Switch this window back to ${h.name}?`, {
+    keys: HANDOFF_BIG_KEYS(h),
+    who: h.fromName,
+    reason: `${h.fromName} has handed off your last ${count} questions`,
+    action: `/detach: this window stops being attached to ${h.fromName} and talks to ${h.name}`,
+  });
+}

package/lib/quoxon/hatSwitch.js

@@ -0,0 +1,37 @@
+/**
+ * /hat helpers (pure), quox#1183. Match a hat the way a person names it (key, display name, "the DevOps hat", a unique
+ * prefix) and the lines /hat prints. Never guesses between ties; an unknown name is { none: true }.
+ */
+const norm = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().replace(/^the /, '').replace(/ hat$/, '').trim();
+
+export const isPrivileged = (hat) => hat?.definition?.transitions?.privileged === true || hat?.privileged === true;
+
+/** -> { hat } | { ambiguous: [hats] } | { none: true } */
+export function matchHat(query, hats) {
+  const rows = Array.isArray(hats) ? hats.filter(Boolean) : [];
+  const raw = String(query ?? '').trim();
+  const q = norm(raw);
+  if (!q) return { none: true };
+  const byId = rows.filter((h) => h.id && h.id === raw);
+  if (byId.length === 1) return { hat: byId[0] };
+  const exact = rows.filter((h) => norm(h.key) === q || norm(h.name) === q);
+  if (exact.length === 1) return { hat: exact[0] };
+  if (exact.length > 1) return { ambiguous: exact };
+  const pre = rows.filter((h) => norm(h.key).startsWith(q) || norm(h.name).startsWith(q));
+  if (pre.length === 1) return { hat: pre[0] };
+  if (pre.length > 1) return { ambiguous: pre };
+  return { none: true };
+}
+
+/** "key (Name)" for each hat, for an error that tells you what to type. */
+export const hatChoices = (hats) => (Array.isArray(hats) ? hats : []).map((h) => (h.name && h.name !== h.key ? `${h.key} (${h.name})` : h.key)).join(', ');
+
+/** One line per hat; the active one is marked with *. */
+export function hatLines(hats, activeKey) {
+  const rows = Array.isArray(hats) ? hats : [];
+  const w = Math.min(28, Math.max(4, ...rows.map((h) => [...String(h.name || h.key)].length)));
+  return rows.map((h) => `${h.key === activeKey ? '* ' : '  '}${String(h.name || h.key).padEnd(w)}  ${h.key}${isPrivileged(h) ? '  (privileged: asks you first)' : ''}`);
+}
+
+/** A conversation id in the collector's own shape (turnStream ensureConversationId), for a window with none yet. */
+export const mintConversationId = (uuid) => `QXC_${uuid}`;