quoxcli 0.3.1 → 0.5.0

package/lib/dragon/frames.js

@@ -0,0 +1,118 @@
+/**
+ * Smooth companion playback. Rendering a dragonlab frame costs 100 ms to over a second (Hyperion), and the old path did it
+ * synchronously inside every Ink render, so the whole TUI hitched and the dragon juddered. The classic Q dragon is smooth
+ * because its frames are cheap and the shared clock paces them. This does the same for companions: time is quantised to
+ * the clock's frame step, frames are rendered OFF the main thread (a worker, see renderWorker.js) a few steps ahead of the
+ * playhead into a cache, and the renderer only ever READS the cache. A frame that is not ready yet is held (the last one
+ * shown stays), never rendered inline. The same quantised time returns the same frame object, so an unchanged frame costs
+ * Ink no output at all.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/** One animation step, the shared clock's FRAME_MS (about 12 fps). */
+export const STEP_MS = 83;
+/** How many steps ahead of the playhead the worker is asked to fill. */
+export const LOOKAHEAD = 3;
+const CACHE_MAX = 240;
+
+export const quantise = (ms) => Math.max(0, Math.round((Number(ms) || 0) / STEP_MS) * STEP_MS);
+
+/**
+ * Where the art goes. Sized to the classic dragon's footprint (15 rows when the terminal is short, 22 when it is tall
+ * enough that the live region still fits), not the old 39x11 cap. Below ART_MIN a one-line label is used instead.
+ */
+export const ART_MIN_COLS = 64, ART_MIN_ROWS = 30;
+export function companionSlot(cols, rows) {
+  const big = cols >= ART_MIN_COLS && rows >= ART_MIN_ROWS;
+  if (!big) return { showArt: false, cols: 0, rows: 0 };
+  const tall = rows >= 40;
+  return { showArt: true, cols: Math.max(28, Math.min(tall ? 66 : 52, cols - 26)), rows: tall ? 22 : 15 };
+}
+
+/**
+ * Cache + playhead. `backend.render(req) -> Promise<frame>` does the real work somewhere else; at most one request is in
+ * flight, and the next one asked for is always the soonest frame not cached yet (current step first, then lookahead).
+ */
+export function createPlayhead(backend, { onFirst = () => {}, lookahead = LOOKAHEAD, clock = () => Date.now() } = {}) {
+  const cache = new Map(), pending = new Set();
+  const conc = Math.max(1, backend.size || 1); // the backend may be a pool: keep every worker busy
+  let last = null, disposed = false, failed = null, renders = 0, ema = 100;
+  const keyOf = (r) => `${r.scene}|${r.time}|${r.motionTime}|${r.cols}x${r.rows}`;
+  const put = (k, f) => { cache.set(k, f); if (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value); };
+  function pump(wants) {
+    for (const next of wants) {
+      if (pending.size >= conc || disposed || failed) return;
+      const k = keyOf(next);
+      if (cache.has(k) || pending.has(k)) continue;
+      pending.add(k); renders++;
+      const began = clock();
+      Promise.resolve().then(() => backend.render(next)).then((f) => {
+        ema = ema * 0.7 + (clock() - began) * 0.3;
+        if (f) { put(k, f); const first = !last; last = f; if (first) onFirst(); }
+      }, (e) => { failed = e; }).finally(() => { pending.delete(k); });
+    }
+  }
+  return {
+    /**
+     * The frame to draw for this scene/time: the cached one for this step, else the newest earlier one (held), else the last
+     * one shown. null before the first ever arrives. The worker is asked for the step the playhead will be at when the
+     * render lands (now + the measured render time), so a slow character still plays at the rate it can render, never stalls the TUI.
+     */
+    frame(req, { still = false } = {}) {
+      const base = (i) => ({ ...req, time: quantise(req.time) + i * STEP_MS, motionTime: quantise(req.motionTime) + i * STEP_MS });
+      const lead = still ? 0 : Math.min(6, Math.ceil(ema / STEP_MS));
+      pump(still ? [base(0)] : Array.from({ length: Math.max(lookahead, conc * 2) + 1 }, (_, i) => base(lead + i)));
+      for (let back = 0; back <= 4; back++) {
+        const hit = cache.get(keyOf(base(-back)));
+        if (hit) { last = hit; return hit; }
+      }
+      return last;
+    },
+    get error() { return failed; },
+    get renders() { return renders; },
+    get size() { return cache.size; },
+    get busy() { return pending.size; },
+    get lead() { return Math.min(6, Math.ceil(ema / STEP_MS)); },
+    dispose() { disposed = true; cache.clear(); backend.dispose?.(); },
+  };
+}
+
+/**
+ * The real backend: worker threads that load the character once and render on request (a small pool, because the heavier
+ * characters take several frame steps to render and the pool renders upcoming steps in parallel). Rejects if no worker can start.
+ */
+export async function createWorkerBackend({ root, id, still = false, mono = false, size = null }, { Worker, cpus = null } = {}) {
+  const W = Worker || (await import('node:worker_threads')).Worker;
+  const avail = cpus ?? (await import('node:os')).availableParallelism?.() ?? 2;
+  const n = Math.max(1, Math.min(size ?? 3, avail - 1));
+  const file = fileURLToPath(new URL('./renderWorker.js', import.meta.url));
+  const waiting = new Map();
+  let seq = 0, dead = null;
+  const fail = (e) => { dead = e; for (const w of waiting.values()) w.reject(e); waiting.clear(); };
+  const spawn = () => new Promise((resolve, reject) => {
+    const worker = new W(file, { workerData: { root, id } });
+    worker.unref?.();
+    worker.once('error', (e) => { fail(e); reject(e); });
+    worker.on('message', (m) => {
+      if (m.type === 'ready') return resolve({ worker, load: 0 });
+      const w = waiting.get(m.seq); if (!w) return;
+      waiting.delete(m.seq); w.slot.load--;
+      if (m.type === 'frame') w.resolve(m.frame); else w.reject(new Error(m.code || 'render failed'));
+    });
+    worker.once('exit', (c) => { fail(new Error(`render worker exited (${c})`)); reject(dead); });
+  });
+  const slots = await Promise.all(Array.from({ length: n }, spawn));
+  return {
+    size: n,
+    render: (req) => new Promise((resolve, reject) => {
+      if (dead) return reject(dead);
+      const slot = slots.reduce((a, b) => (b.load < a.load ? b : a));
+      const s = ++seq; slot.load++; waiting.set(s, { resolve, reject, slot });
+      slot.worker.postMessage({ seq: s, req: { ...req, still, mono } });
+    }),
+    dispose() { fail(new Error('disposed')); for (const s of slots) s.worker.terminate(); },
+  };
+}
+
+/** Test/fallback helper: path-to-URL for a dragonlab module. */
+export const labModule = (root, ...p) => pathToFileURL([root, 'integration', 'companions-v1', ...p].join('/')).href;

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, Vulcan, Quoxperticus): 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', vulcan: 'vulcan', forge: 'vulcan', quoxperticus: 'quoxperticus' });
+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/quoxon/EXTENSIONS.md

@@ -0,0 +1,146 @@
+# quoxon extensions: contract v1
+
+Optional npm packages that add a surface to quoxon (a MIDI pad deck, a status bar, a fleet board). Core ships none and knows none by name.
+An extension can OPEN an approval or PRESELECT an answer. It can never resolve one, and it never polls Quox: data is pushed to it.
+
+## Loading
+
+Nothing loads unless the package is installed AND listed in `~/.quox/extensions.json`
+(`quox ext add|remove|list <pkg>`; `/ext list|on|off <name>` inside quoxon). Install with `npm i -g <pkg>`.
+Set env `QUOX_EXT_LIST=<path>` to use another list file (default `~/.quox/extensions.json`), for `quox ext` and quoxon alike (dev and tests).
+Resolution order: env `QUOX_EXT_<NAME>_MODULE` (name upper-cased, non-alphanumerics to `_`), a local `import(name)`,
+then the global npm root. `/ext list` names where each was found; a miss lists where it looked.
+
+**contractVersion** (integer, this document is `1`). The host refuses an extension whose `contractVersion` is above what it supports,
+with a line in `/ext list`: `needs extension contract v2, this quoxon supports v1`. An extension with no `contractVersion` is a
+pre-contract (legacy) extension: it loads, and `emit` may use `n` without `id` (see F2). Declare `contractVersion: 1` to get the strict rules.
+
+## Module
+
+Default export (or the module itself):
+
+```ts
+interface Extension {
+  name: string; version?: string;
+  contractVersion?: 1;
+  commands?: Command[];
+  settings?: SettingDef[];
+  create(ctx: { emit(msg: Emit): boolean; log(text: string): void; settings: Record<string, string|number|boolean>; invalidate(): void }): Instance;
+}
+interface Instance {
+  update?(state: State): void;                 // deduped; see Freshness
+  close?(): void | Promise<void>;              // see Close
+  panel?: Panel;                               // see Panels (one panel per extension)
+  onSettings?(next: Record<string, string|number|boolean>): void;
+  onEmitResult?(r: { ok: boolean; reason?: string; msg: Emit }): void;
+}
+```
+
+`panel`, `onSettings` and `onEmitResult` live on the object `create()` returns. There is no module-level `onSettings`.
+
+## Commands
+
+```ts
+interface Command {
+  name: `/${string}`; help?: string;
+  subcommands?: { name: string; help?: string }[];   // feed /help and Tab completion
+  run(args: string[], ctx: { raw: string; say(text: string, tone?: 'ok'|'warn'|'accent'|'dim'): void; extension: string; loaded: string[] }): string | { text: string; tone?: string } | Promise<...>;
+}
+```
+
+`args` is the text after the command split on whitespace; `ctx.raw` is the same text unsplit. Commands exist only while the extension is loaded.
+A thrown error is printed as `<cmd>: <message>`, never crashes the window.
+
+## State
+
+`update(state)` is deduped (a push identical except `at` is dropped) and sent at most once per second.
+
+```ts
+interface State {
+  at: string;                 // ISO time of this push
+  stale?: true;               // present only when the host's last successful server read is over 60 s old
+  org: { id: string|null; name: string|null };
+  approvals: { count: number; items: { n: number; id: string|null; risk: 'low'|'high'; title: string; agent: string|null; options?: { key: string; label: string }[] }[] };
+  health: Record<string, 'ok'|'warn'|'down'>;
+  loops: { id: string; title: string; turn: number; max: number; status: string }[];
+  fleet: { total: number; online: number; offline: number; warn: number; hosts: { name: string; state: 'ok'|'warn'|'down' }[] };  // hosts max 16, may be empty
+  evidence: { chain: 'ok'|'broken'|'unknown'; checked_at: string|null };   // PLACEHOLDER: always 'unknown' until quoxon holds a chain status
+  sessions: { active: number };
+  event?: { seq: number; id?: string; kind: string; text: string; level: 'info'|'ok'|'warn'|'error' };
+}
+```
+
+**Freshness.** `state.at` is set on every push. While any extension is loaded the host pushes a heartbeat every 15 s, even when nothing
+changed, so `at` keeps moving. `stale: true` means the data may be old (the server was not read for over 60 s): show it as such.
+
+**Event ids.** `event.seq` is a positive integer, monotonic within one quoxon window session and never reused; a new event gets the next number,
+the seq changes only when `kind`, `text`, `level` or `id` changes: a repeat of the held event keeps its seq until `alert_ack`. `event.id` appears only when the server supplied one.
+
+`fleet` comes from a 30 s poll of the host list while an extension is loaded.
+
+## emit
+
+```ts
+type Emit =
+  | { type: 'open_approval'; id: string; n?: number }
+  | { type: 'pick'; id: string; n?: number; option: string }
+  | { type: 'alert_ack' };
+```
+
+`id` (from `approvals.items[].id`) is REQUIRED for `open_approval` and `pick`. `n` is display-only; when `id` and `n` disagree, `id` wins
+(logged). An unknown, missing or already-resolved `id` is refused through `onEmitResult({ ok:false, reason, msg })`, and is never retargeted
+to another item. `pick` only fills the composer with the answer command: the user presses Enter, high risk still needs the step-up PIN.
+`alert_ack` clears the event. emit returns `true` when accepted and is ignored once the extension is unloaded.
+(Legacy extensions without `contractVersion` may omit `id` and use `n`.)
+
+## Panels and tabs
+
+```ts
+interface Panel {
+  title: string;
+  render(a: { width: number; height: number; focused: boolean; theme: Theme }): string[];   // pure
+  onKey?(key: string): boolean;     // true = consumed, see Keys
+  onFocus?(): void; onBlur?(): void;
+}
+```
+
+```ts
+interface Theme { name: 'dark'|'light'|'mono'; color: boolean; unicode: boolean }
+```
+
+The host owns the tab strip, shown only when one or more panels exist. The panel region sits above the composer, height
+`min(12, 40% of terminal rows)`, collapsed until a panel is focused or opened. `/ext tab <name>` focuses (and opens) a panel; `/ext tab off`
+collapses; Ctrl+] cycles focus through the panels; Esc returns keys to the composer (the panel stays open). While focused, keys go to
+`onKey` first; a key it does not consume is dropped. The panel never receives `escape` or `ctrl+]`: the host consumes both.
+
+**Keys.** `onKey(key)` gets one of `up down left right enter tab backspace space home end pageup pagedown`, otherwise the single typed
+character (`a`, `?`, `/`), or `ctrl+<c>` / `alt+<c>` for the modifier combinations the terminal reports. Pasted text arrives one
+character at a time.
+
+`render` must be pure and fast. The 50 ms budget is wall-clock per render call (`performance.now`). The host clips the result to `height` lines and `width` columns. A render that throws, or takes over 50 ms,
+shows `panel error` in its place and is retried no sooner than 5 s later; it never crashes the window. The panel re-renders on every state
+push and on `invalidate()` (passed to `create`, throttled to 4 per second).
+
+## Settings
+
+```ts
+interface SettingDef { key: string; type: 'string'|'number'|'bool'|'enum'; default: string|number|boolean; help: string; choices?: string[] }
+```
+
+Values live in `~/.quox/extensions.json` on the extension's entry as `settings: { <key>: value }`. `create({ settings })` receives the resolved
+object (defaults overlaid with stored values). `/ext set <name> <key> <value>` validates by type (number: `Number()` and it must be a finite number; bool: `true|yes|on|1` or
+`false|no|off|0`, case-insensitive, anything else is rejected with a message; enum: an exact match to one of `choices`; string: any text), stores it, and calls `onSettings(next)` on the running instance.
+`/ext settings <name>` lists each key with its value, default and help. The extension must be loaded and listed.
+
+## Close
+
+`close()` may return a promise. The host awaits it for at most 500 ms, then drops the instance anyway and logs it. It must be idempotent
+(the host may call it twice) and must free every timer, interval, watcher, device and process listener, because hot reload calls it on each change.
+
+## Hot reload
+
+While an extension is loaded, quoxon watches its `package.json` (`fs.watch`, 2 s debounce, plus a 30 s stat poll because global installs
+replace directories). When the version or mtime changes it awaits `close()` on the old instance (500 ms cap), drops its commands and panel,
+re-imports the entry with a cache-busting `?v=<version>-<mtime>`, and calls `create()` again, then prints `↻ <name> updated <old> -> <new>`.
+Only the entry module is re-imported. A failed reload leaves the old instance closed, prints the error once, and shows `failed: <error>` in
+`/ext list` until the next change. Watchers and timers are cleared on `/ext off`, unload and exit.