quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/demo.js

@@ -1,3 +1,4 @@
+import { readFileSync, writeFileSync } from 'node:fs';
 import { DEMO_STEPS } from './demo.fixtures.js';
 
 const sleep = (ms, signal) => new Promise((res) => {
@@ -7,7 +8,34 @@ const sleep = (ms, signal) => new Promise((res) => {
 });
 
 /** A fake api with the same surface as createApi(), driven by DEMO_STEPS. */
-export function createDemoApi({ speed = 1 } = {}) {
+/**
+ * WALK-FIXES pty seam (demo only, never a real server): decisionsFile is a JSON state file
+ * { items: [decision inbox items], log: [], answerDelayMs?, approvalsDelayMs? }. approvals() lists the open ones,
+ * answerDecision() marks one answered and appends { id, key, note, at } to log, so a test in another process reads
+ * exactly what was submitted, and when.
+ */
+function decisionStore(file) {
+  const load = () => JSON.parse(readFileSync(file, 'utf8'));
+  const wait = (ms) => new Promise(r => setTimeout(r, ms || 0));
+  return {
+    // staleMs: an answered item is still listed for this long (a server that lags behind its own answers)
+    // failAfterAnswers: the server is down once anything was answered (the walkthrough's closing re-check)
+    async open() { const d = load(); await wait(d.approvalsDelayMs); if (d.failAfterAnswers && d.log.length) { const e = new Error('connect ECONNREFUSED'); e.status = 503; throw e; } return d.items.filter(x => x.status === 'open' || (d.staleMs && x.answeredAt && Date.now() - x.answeredAt < d.staleMs)); },
+    async answer(id, key, note) {
+      const d0 = load(); await wait(d0.answerDelayMs);
+      const d = load(); const it = d.items.find(x => x.id === id);
+      if (!it || it.status !== 'open') { const e = new Error('already handled'); e.status = 404; throw e; }
+      it.status = 'answered'; it.answeredAt = Date.now(); it.answer = { key, note: note || null };
+      d.log.push({ id, key, note: note || null, at: Date.now() });
+      if (d.arriveOnAnswer && !d.arrived) { d.items.push(...d.arriveOnAnswer); d.arrived = true; } // arriveOnAnswer: new items land while the owner is answering
+      writeFileSync(file, JSON.stringify(d));
+      return { ok: true };
+    }
+  };
+}
+
+export function createDemoApi({ speed = 1, objects = false, decisionsFile = null } = {}) {
+  const decs = decisionsFile ? decisionStore(decisionsFile) : null;
   let gate = null;
   let decision = 'approve';
   return {
@@ -26,10 +54,25 @@ export function createDemoApi({ speed = 1 } = {}) {
     async steer() { return { ok: false, reason: 'unsupported' }; },
     async interrupt() { return { ok: false }; },
     async health() { return { ok: true, url: 'demo' }; },
-    async approvals() { return []; },
+    // the open approval is in the inbox while the demo holds at the gate, so a poll never prunes its card
+    async approvals() { return [...(gate ? [{ id: 'demo-item', title: 'host_restart on web on edge-02', approval_id: 'demo-appr', created_at: new Date().toISOString() }] : []), ...(decs ? await decs.open() : [])]; },
+    ...(decs ? { async answerDecision(id, key, { note } = {}) { return decs.answer(id, key, note); }, async approvalStats() { return { awaiting: (await decs.open()).length + (gate ? 1 : 0) }; } } : {}),
     async skills() { return [{ id: 'sk1', name: 'daily-fleet-check', description: 'Check fleet health and summarise.', edition: 'stable' }]; },
     async skill(id) { return { id, name: 'daily-fleet-check', description: 'Check fleet health and summarise.', edition: 'stable' }; },
     async conversationExists() { return { exists: true }; },
-    async respond(_id, action) { decision = action === 'reject' ? 'reject' : 'approve'; const g = gate; gate = null; g?.(); return { ok: true }; }
+    // /proof works in the demo journey (main.js asks for it); the other object views stay unavailable offline
+    ...(objects ? { objects: {
+      async proof(tool) {
+        const env = { id: tool.envelopeId, corr: 'demo-corr', payload: { success: true, tool_name: tool.tool } };
+        return { data: { tool, envelope: { ok: true, env },
+          aocl: { ok: true, list: [{ intent: 'aocl.identity.verified' }, { intent: 'aocl.policy.evaluated', payload: { allPassed: true } }] },
+          receipt: { ok: true, result: { status: 'WITNESSED', entry: { seq: 4069513 } } } } };
+      },
+      ...Object.fromEntries(['skill', 'agent', 'workflowRun', 'crystal', 'memory', 'rules', 'reconcile'].map((k) => [k, async () => ({ error: 'Object views are not available in the demo.' })]))
+    } } : {}),
+    async respond(_id, action) {
+      if (decs && _id !== 'demo-item') return decs.answer(_id, action === 'reject' ? 'n' : 'y', null); // a yes/no decision answered as an approval (the bulk card)
+      decision = action === 'reject' ? 'reject' : 'approve'; const g = gate; gate = null; g?.(); return { ok: true };
+    }
   };
 }

package/lib/quoxon/devObserver.js

@@ -0,0 +1,20 @@
+/**
+ * Is a dev observer wired to this install? /observe and /note exist only for the developer whose
+ * window a QUOXON observer session watches; a customer has no observer, so for them these commands
+ * are hidden (help, palette, autocomplete) and refuse with a plain line.
+ *
+ * The switch is config driven, in the same style as the dev-transcripts flag: QUOX_DEV_OBSERVER=1
+ * turns it on for one shell, QUOX_DEV_OBSERVER=0 forces it off, otherwise the flag file
+ * ~/.config/quox/dev-observer decides (touch it on a dev box; it survives new shells).
+ */
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const DEV_OBSERVER_REFUSAL = 'No dev observer is set up on this install, so there is nothing to send this to.';
+
+export function devObserverOn(env = process.env, { home = homedir(), exists = existsSync } = {}) {
+  if (env.QUOX_DEV_OBSERVER === '0') return false;
+  if (env.QUOX_DEV_OBSERVER === '1') return true;
+  try { return exists(join(home, '.config', 'quox', 'dev-observer')); } catch { return false; }
+}

package/lib/quoxon/dividerAocl.js

@@ -0,0 +1,192 @@
+/**
+ * TUI-DIVIDER: the composer's bottom rule (`──────── anthropic claude-sonnet-5-5 ─`) as a live AOCL strip.
+ *
+ * Owner design (2026-10-17 22:09, after the first cut): a PIPELINE, like the dashboard command screen's
+ * LayerStackMini. One compact chain of 11 dots, one per AOCL layer, each in its own layer colour, sits just left of
+ * the model label: `────────•─•─●─●─◆─•─•─•─•─•─• anthropic claude-sonnet-5-5 ─`. On Enter the dots light left to
+ * right as the real layer events arrive; when they reach the model, only the label animates (katakana shimmer).
+ * Motion lives in one place at a time (the newest dot, or the label), never across the row. The finished state is
+ * the label green (red on an error or a block, with the blocking dot marked) for ~1.6 s, then the normal rule.
+ *
+ * HONESTY: only REAL state moves this. A pip lights only when that layer's `aocl.layer` event arrives (or a
+ * pre-stream refusal's `aocl_layers` record), in the colour of its real result. A bypassed layer (not evaluated
+ * on this path) stays unlit, and so does every layer of a server that sends no `aocl.layer`. The "model is
+ * working" phase starts on a real signal: the last pre-model layer (L4) reported, or the first model output.
+ * Dots light one step apart for readability (STEP_MS), but never before their own event.
+ *
+ * Pure: `dividerStep` folds actions into state, `dividerFrame` draws one frame (or null = draw the normal rule).
+ * Nothing here runs a timer; the app asks the clock for frames only while `dividerLive` says so.
+ */
+import stringWidth from 'string-width';
+import { wordFrame, wordColor } from './indicator.js';
+import { LAYER_NAMES } from './aocl.js';
+
+export const ORDER = ['L0', 'L1', 'L2', 'L3', 'L4', 'L5', 'L6', 'L7', 'L8', 'L9', 'L10'];
+const PRE_LAST = 'L4';
+export const GREEN_MS = 1600;   // the label holds green this long after a completed reply (under the app's 2 s idle guarantee, motion-app.test)
+export const RED_MS = 1600;     // and red this long after an error or a block (the error itself stays in the transcript)
+export const MIN_COLS = 70;     // narrower than this: the plain rule, no animation
+export const STEP_MS = 120;     // dots light at most one per step, left to right (never before their event)
+export const CURRENT_MS = 700;  // the newest dot blinks this long after it lights; then it is just lit
+export const TAG_MS = 1200;     // the newest layer's name shows beside the chain this long
+export const LIT_RESULTS = new Set(['pass', 'gated', 'blocked']);
+
+// Real model work only. `thinking` frames are mostly server staging (routing, processing, provider notes) sent
+// before turn.started; only the model's own reasoning counts.
+const MODEL_SIGNALS = new Set(['chunk', 'text.delta', 'tool.started']);
+const isModelSignal = (ev) => MODEL_SIGNALS.has(ev.type) || (ev.type === 'thinking' && ev.stage === 'model_reasoning');
+
+/** A fresh strip for a turn the user just sent. */
+export const dividerStart = (turnId, now) => ({ turnId, startedAt: now, pips: {}, seen: {}, order: [], modelAt: null, phase: 'gates', endedAt: null, blockedAt: null });
+
+function light(d, l, now) {
+  const id = String(l?.id || '');
+  if (!ORDER.includes(id) || d.pips[id]) return d; // unknown layer or already lit: nothing changes
+  const result = String(l.result || '');
+  if (!LIT_RESULTS.has(result)) { // bypass: a real event, but not evaluated: the pipeline steps over it, unlit
+    return result === 'bypass' && !(d.seen || {})[id] ? { ...d, seen: { ...(d.seen || {}), [id]: { result, at: now } } } : d;
+  }
+  let n = { ...d, pips: { ...d.pips, [id]: { result, at: now } }, seen: { ...(d.seen || {}), [id]: { result, at: now } }, order: [...d.order, id] };
+  if (result === 'blocked') n = { ...n, phase: 'error', blockedAt: id, endedAt: n.endedAt ?? now };
+  return n;
+}
+
+/**
+ * Fold one reducer action into the strip. `a` is the quoxon reducer action ({type:'turn.begin'} or
+ * {type:'event', ev}); unknown actions return `d` unchanged (same object).
+ */
+export function dividerStep(d, a, now) {
+  if (!a) return d;
+  if (a.type === 'turn.begin') return dividerStart(a.turnId, now);
+  if (a.type !== 'event' || !d || d.endedAt != null && a.ev?.type !== 'aocl.layer') return d;
+  const ev = a.ev || {};
+  if (ev.type === 'aocl.layer') {
+    if (d.endedAt != null && d.phase !== 'error') return d; // a finished green strip never changes
+    let n = light(d, ev, now);
+    const pre = ev.phase === 'pre' || ORDER.indexOf(String(ev.id)) <= ORDER.indexOf(PRE_LAST);
+    if (n.phase === 'gates' && (String(ev.id) === PRE_LAST || !pre)) n = { ...n, phase: 'model', modelAt: n.modelAt ?? now };
+    return n;
+  }
+  if (isModelSignal(ev)) return d.phase === 'gates' ? { ...d, phase: 'model', modelAt: now } : d;
+  if (ev.type === 'aocl.verdict' && ev.verdict === 'blocked') {
+    const id = ORDER.includes(ev.layer) ? ev.layer : 'L8';
+    return { ...d, phase: 'error', blockedAt: d.blockedAt || id, endedAt: d.endedAt ?? now };
+  }
+  if (ev.type === 'error') return { ...d, phase: 'error', endedAt: now };
+  if (ev.type === 'turn.finished') {
+    const ok = (ev.status || 'completed') === 'completed';
+    return ok && d.phase !== 'error' ? { ...d, phase: 'done', endedAt: now } : { ...d, phase: 'error', endedAt: d.endedAt ?? now };
+  }
+  return d;
+}
+
+/** True while the strip needs frames: a turn in flight, or the green/red hold after it. */
+export function dividerLive(d, now) {
+  if (!d) return false;
+  if (d.endedAt == null) return true;
+  return now - d.endedAt < (d.phase === 'done' ? GREEN_MS : RED_MS);
+}
+
+// Each layer's own colour, from the dashboard (src/lib/aee/envelope.js AOCL_LAYERS, which LayerStackMini uses).
+// L0 and L10 are grey there (#6b7280); the TUI has no grey text, so they take sky and violet.
+export const LAYER_HEX = {
+  L0: '#38bdf8', L1: '#3b82f6', L2: '#3b82f6', L3: '#f59e0b', L4: '#8b5cf6', L5: '#8b5cf6',
+  L6: '#6366f1', L7: '#f97316', L8: '#14b8a6', L9: '#22c55e', L10: '#a855f7',
+};
+const hexRgb = (h) => [1, 3, 5].map(i => parseInt(h.slice(i, i + 2), 16));
+const mixRgb = (a, b, t) => a.map((v, i) => Math.round(v + (b[i] - v) * t));
+const DARK = [30, 36, 48];
+export const layerRgb = (id) => hexRgb(LAYER_HEX[id]);
+export const dimRgb = (id) => mixRgb(layerRgb(id), DARK, 0.6); // pending / bypassed: the layer's own hue, dimmed (not grey)
+
+export const RGB = { done: [34, 197, 94], blocked: [239, 68, 68], model: [56, 189, 248] };
+const LIT = { pass: '●', gated: '◆', blocked: '✖' };
+const PENDING = '•';
+
+/**
+ * When each layer the server reported was reached in the pipeline: in layer order, one STEP_MS apart, never
+ * before its own event. Bypassed layers are reached (the chain passes them) but stay unlit.
+ */
+export function layerReachTimes(d) {
+  const out = {};
+  if (!d) return out;
+  let t = d.startedAt - STEP_MS;
+  for (const id of ORDER) {
+    const s = (d.seen || {})[id] || d.pips[id];
+    if (!s) continue;
+    t = Math.max(t + STEP_MS, s.at);
+    out[id] = t;
+  }
+  return out;
+}
+
+/** When the pipeline hands over to the model (the label starts to shimmer): every pre-model layer seen was reached. */
+export function modelReachedAt(d) {
+  if (!d || d.modelAt == null) return null;
+  const r = layerReachTimes(d);
+  const pre = ORDER.slice(0, ORDER.indexOf(PRE_LAST) + 1).map(id => r[id]).filter(x => x != null);
+  return Math.max(d.modelAt, ...pre, d.startedAt) + (pre.length ? STEP_MS : 0);
+}
+
+/** The chain of 11 dots joined by rule: cells [{ t, rgb, bold }]. Motion only on the newest dot. */
+export function chainCells(d, now, { still = false } = {}) {
+  const reach = layerReachTimes(d);
+  const reached = ORDER.filter(id => reach[id] != null && reach[id] <= now);
+  const newest = reached.filter(id => d.pips[id]).sort((a, b) => reach[b] - reach[a])[0] || null;
+  const cells = [];
+  ORDER.forEach((id, i) => {
+    if (i) cells.push({ t: '─' });
+    const p = d.pips[id];
+    if (p && reach[id] <= now) {
+      // only the newest dot blinks, only while the turn runs, and a blocked dot never dims (it stays red)
+      const blinkOff = !still && d.endedAt == null && p.result !== 'blocked' && id === newest && now - reach[id] < CURRENT_MS && Math.floor((now - reach[id]) / 175) % 2 === 1;
+      const rgb = p.result === 'blocked' ? RGB.blocked : layerRgb(id);
+      cells.push({ t: LIT[p.result], rgb: blinkOff ? dimRgb(id) : rgb, bold: !blinkOff });
+    } else cells.push({ t: PENDING, rgb: dimRgb(id) });
+  });
+  return { cells, newest, newestAt: newest ? reach[newest] : null };
+}
+
+/**
+ * One frame of the rule: `{ cells: [{ t, rgb?, bold?, label? }] }` whose widths sum to exactly `cols`, or null
+ * when the normal rule should draw (no strip, the hold is over, NO_COLOR, reduced motion, too narrow, no label).
+ * Cells without `rgb` take the rule's own colour; `label: true` takes the label's own colour.
+ * `still` (a slow redraw): no blink and no katakana, but every lit dot and the end colours stay.
+ */
+export function dividerFrame({ cols, label, extra = null, d, now, mono = false, reduced = false, still = false, seed = 0 }) {
+  if (mono || reduced || !d || cols < MIN_COLS || !label || !dividerLive(d, now)) return null;
+  const lab = ` ${label} `;
+  const lw = stringWidth(lab);
+  const chain = chainCells(d, now, { still });
+  const cw = chain.cells.length;
+  const ew = extra ? stringWidth(` ${extra.text} `) : 0;
+  const left = cols - lw - 1 - cw - ew;
+  if (left < 4) return null;
+  // the newest lit layer names itself to the left of the chain, in its colour, while it is new
+  const tag = chain.newest && now - chain.newestAt < TAG_MS ? ` ${chain.newest} ${LAYER_NAMES[chain.newest] || ''} ` : '';
+  const fill = Math.max(1, left - (tag && tag.length + 1 <= left - 1 ? tag.length : 0));
+  const leftCells = Array.from({ length: fill }, () => ({ t: '─' }));
+  if (fill < left) {
+    const rgb = d.pips[chain.newest].result === 'blocked' ? RGB.blocked : layerRgb(chain.newest);
+    leftCells.splice(fill - 1, 0, ...[...tag].map(ch => ({ t: ch, rgb, bold: true })));
+  }
+  while (leftCells.length < left) leftCells.push({ t: '─' });
+  let labelCells;
+  if (d.phase === 'done') labelCells = [{ t: lab, rgb: RGB.done, bold: true }];
+  else if (d.phase === 'error') labelCells = [{ t: lab, rgb: RGB.blocked, bold: true }];
+  else {
+    const at = modelReachedAt(d);
+    if (at != null && now >= at) {
+      if (still) labelCells = [{ t: lab, rgb: RGB.model, bold: true }];
+      else {
+        const fr = wordFrame(label, now, { since: at, seed });
+        const n = fr.length;
+        labelCells = [{ t: ' ' }, ...fr.map((c, i) => ({ t: c.ch, rgb: wordColor('working', i, n, now, c.flash ? 'flash' : c.glyph ? 'glyph' : 'letter') })), { t: ' ' }];
+      }
+    } else labelCells = [{ t: lab, label: true }];
+  }
+  return { cells: [...leftCells, ...chain.cells, ...labelCells, ...(extra ? [{ t: ` ${extra.text} `, hex: extra.hex, bold: true }] : []), { t: '─' }] };
+}
+
+/** Plain text of a frame (tests and pty proofs). */
+export const frameText = (f) => (f ? f.cells.map(c => c.t).join('') : null);

package/lib/quoxon/dividerRule.js

@@ -0,0 +1,57 @@
+/**
+ * TUI-DIVIDER: the composer's bottom rule drawn from a dividerAocl frame (pips, bullet, katakana label, green/red).
+ * Draws ONE pre-coloured string per colour run (as the ring does), so a frame is a single row of exactly `cols`
+ * cells and Ink tokenises a handful of escapes, not one per cell.
+ */
+import React from 'react';
+import chalk from 'chalk';
+import { Text } from 'ink';
+import { dividerFrame } from './dividerAocl.js';
+
+const h = React.createElement;
+const RUN_Q = 8; // quantise shimmer colours so neighbouring cells share a run
+
+/**
+ * Per turn, a frame gap this long while the strip is live marks the redraw as slow: the strip then drops its motion
+ * (no bullet, no katakana) for the rest of that turn but keeps every lit pip. `slow` is a ref object owned by the caller.
+ */
+export const SLOW_GAP_MS = 400;
+export function noteFrameGap(slow, d, now) {
+  if (!slow || !d) return false;
+  if (slow.turnId !== d.turnId) { slow.turnId = d.turnId; slow.last = now; slow.slow = false; return false; }
+  if (slow.last != null && now - slow.last > SLOW_GAP_MS && d.endedAt == null) slow.slow = true;
+  slow.last = now;
+  return slow.slow;
+}
+
+/** The frame as one string of chalk runs; `ruleColor`/`labelColor` are hex or undefined (theme roles resolved). */
+export function paintFrame(f, { ruleColor, labelColor }) {
+  let out = '', run = '', key = null, style = null;
+  const paint = (s) => {
+    if (!s) return '';
+    let p = chalk;
+    if (style.rgb) p = p.rgb(...style.rgb);
+    else if (style.hex) p = p.hex(style.hex);
+    if (style.bold) p = p.bold;
+    return p(s);
+  };
+  const flush = () => { if (run) out += paint(run); run = ''; };
+  for (const c of f.cells) {
+    const rgb = c.rgb ? c.rgb.map(v => Math.max(0, Math.min(255, Math.round(v / RUN_Q) * RUN_Q))) : null;
+    const st = { rgb, hex: rgb ? null : (c.hex || (c.label ? labelColor : ruleColor)) || null, bold: Boolean(c.bold) };
+    const k = `${rgb ? rgb.join(',') : st.hex}|${st.bold}`;
+    if (k !== key) { flush(); key = k; style = st; }
+    run += c.t;
+  }
+  flush();
+  return out;
+}
+
+/** The bottom rule as a strip element, or null when the caller should draw its normal Rule (a plain call, not a component). */
+export function dividerRuleEl({ cols, label, extra = null, divider, now, ruleColor, labelColor, mono = false, reduced = false, slow = null }) {
+  if (!divider) return null;
+  const isSlow = noteFrameGap(slow, divider, now);
+  const f = dividerFrame({ cols, label, extra, d: divider, now, mono, reduced, still: isSlow }); // slow: keep the lit pips, drop the motion
+  if (!f) return null;
+  return h(Text, { wrap: 'truncate-end' }, paintFrame(f, { ruleColor, labelColor }));
+}

package/lib/quoxon/dragonCompanion.js

@@ -0,0 +1,255 @@
+/**
+ * Dragon companion for Quoxon (Lucid, Hyperion, Seer, Sentinel, Drago, Cipher). The controller owns attach state and feeds REAL stream
+ * events to dragonlab's pure view (integration/companions-v1/view.mjs: the same reducer and renderer the CLI
+ * uses). No art, state logic or timers are duplicated here; this file only decides, translates and lays out.
+ * Decisions: docs/dragons/COMPANION-UX.md. The reducer never overwrites pending approvals or failures, but the host only SHOWS the dragon during a dwell (attach, key moment, invoke).
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { existsSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { cellNodes, dragonActive, clipRoom } from './qmotion.js';
+import { useFrame } from './motion/frame.js';
+import { loadCompanionView } from '../dragon/companionView.js';
+import { ART_MIN_COLS as SLOT_MIN_COLS, ART_MIN_ROWS as SLOT_MIN_ROWS } from '../dragon/frames.js';
+import { companionPlan, motionPolicy, normaliseMode, COMPANION_MODES, VENDORED_DRAGONLAB, dragonForAgent, companionMode } from '../dragon/select.js';
+import { createMomentEngine, createRosterWatch, LONG_TASK_MS, SUMMON_COOLDOWN_MS } from './dragonMoments.js';
+import { moodForEvent } from './motion/level.js';
+
+const h = React.createElement;
+const AGES_OUT = 10 * 60 * 1000; // an attach that is not a greeting starts with its entrance already over
+/** How long the dragon stays after any appearance (attach, key moment, invoke). The one dwell constant. */
+export const DRAGON_DWELL_MS = 10000;
+/** A keypress inside the first part of a dwell does not send it away: invoking with Enter and then typing must not kill it. */
+export const KEY_GRACE_MS = 2000;
+/** A turn at least this long counts as a "long task" when it finishes (defined with the moment engine). */
+export { LONG_TASK_MS };
+/** Art that is still being drawn when its dwell would end is waited for this long (from the appearance) before giving up. */
+export const FIRST_FRAME_GRACE_MS = 20000;
+
+/** Art needs room; below this the companion is one plain text line. */
+export const ART_MIN_COLS = SLOT_MIN_COLS, ART_MIN_ROWS = SLOT_MIN_ROWS;
+
+/**
+ * Whether this /attach greets. Every explicit, typed /attach does (even a repeat of the same agent in one session); only an
+ * automatic re-attach (after a restart, or resuming a conversation) is quiet. The quiet flag is read AND cleared in one step
+ * at the start of the command, so an attach that bails early (a slot, a busy turn) can never leave it armed for the next typed one.
+ */
+export function takeGreeting(flags) { const quiet = Boolean(flags.noGreeting); flags.noGreeting = false; return !quiet; }
+
+/** Quoxon stream/poll facts -> the reducer's event vocabulary. Unknown shapes pass through (the reducer ignores them). */
+export function toCompanionEvent(action) {
+  if (!action) return null;
+  if (action.type === 'turn.begin') return { type: 'turn.started', turn_id: action.turnId };
+  if (action.type === 'approval.found') {
+    const key = action.item?.id || action.item?.approval_id || action.item?.approvalId;
+    return key ? { type: 'approval.requested', call_id: String(key) } : null;
+  }
+  if (action.type === 'event') return action.ev || null;
+  return null;
+}
+
+export function createCompanionController({ settings = () => ({}), env = process.env, isTTY = true, exists = existsSync, now = Date.now, importer = null, makeView = loadCompanionView, jobs = null, typing = () => false } = {}) {
+  let noticed = false, showUntil = 0, shownAt = 0, unpainted = false, waitingFrame = false, trigger = 'attach', forced = false, timer = null, job = null;
+  let summoned = null, summonCaption = null; const lastSummon = new Map(); const rosterWatch = createRosterWatch(); // a domain moment's dragon (not the attached one) and its truthful caption
+  const moments = createMomentEngine({ now });
+  let agent = null, plan = { enabled: false, why: 'no agent attached' }, view = null, state = null, token = 0, greet = true;
+  const listeners = new Set();
+  const notify = () => listeners.forEach(f => f());
+  const replan = (as = null) => companionPlan({ agent: as ?? agent, settings: settings(), env: forced ? { ...env, QUOX_DRAGON_COMPANION: 'greeting' } : env, isTTY, exists, bundled: VENDORED_DRAGONLAB });
+
+  /** (Re)start the dwell from shownAt; a timer wakes the renderer at expiry. */
+  function arm() {
+    showUntil = shownAt + DRAGON_DWELL_MS;
+    clearTimeout(timer);
+    timer = setTimeout(() => { if (summoned && now() >= showUntil) restore(); else notify(); }, Math.max(0, showUntil - now()) + 50); timer.unref?.();
+  }
+  /** Show for one dwell, then leave on its own. The dwell and the keypress grace start when the first frame is actually drawn (see snapshot). */
+  function appear(why = 'attach') {
+    if (!view) return;
+    trigger = why; shownAt = now(); unpainted = true; waitingFrame = false;
+    arm();
+    readJob();
+    notify();
+  }
+  /** The dragon's one job: a real read (cached 30 s inside `jobs`), asked only when the dragon is about to be shown. Its caption replaces the generic one when it lands. */
+  function readJob() {
+    const mine = token, id = plan.id;
+    if (!jobs || !id) return;
+    const first = jobs.peek?.(id);
+    if (first) job = first;
+    Promise.resolve().then(() => jobs.run(id)).then((r) => { if (mine === token && r) { job = r; notify(); } }, () => { /* a failed job read leaves the generic caption: never a made-up one */ });
+  }
+  /** Still on screen: inside the dwell, or waiting for art that has not been drawn yet (the dwell then counts from the first picture). */
+  const live = () => now() < showUntil || (waitingFrame && unpainted && now() < shownAt + FIRST_FRAME_GRACE_MS);
+  /** Key moments only in mode `on`; `greeting` and `off` never show for approvals or failures. */
+  const keyMoment = () => { if (view && companionMode(settings(), env) === 'on') appear('moment'); };
+
+  /** A summoned dragon's dwell is over (or it was dismissed): drop it and put the attached agent's dragon back, quietly. */
+  function restore() {
+    summoned = null; summonCaption = null;
+    if (agent) load({ quiet: true }); else { token++; view?.dispose?.(); view = null; state = null; showUntil = 0; plan = replan(); notify(); }
+  }
+
+  async function load({ show = false, persist = null, why = 'attach', as = null, caption = null, quiet = false } = {}) {
+    const mine = ++token;
+    view?.dispose?.(); view = null; state = null; showUntil = 0; job = null;
+    summoned = as; summonCaption = caption;
+    plan = replan(as);
+    if (!plan.enabled) return notify();
+    try {
+      const opts = { still: plan.still, mono: plan.mono, persist: persist ?? plan.persist };
+      let v;
+      if (importer) v = await (await importer(pathToFileURL(plan.viewFile).href)).loadDragonView(plan.id, opts);
+      else {
+        // The playback path: frames come from a worker through a cache (dragon/frames.js). If the worker cannot start, the
+        // art still shows through dragonlab's own view (slower, inline), as before.
+        try { v = await makeView(plan.root, plan.id, { ...opts, persist: true, onFrame: notify }); } // persist: this host's dwell (showUntil) decides how long it stays, not the entrance length (Lucid's is 3 s)
+        catch { v = await (await import(pathToFileURL(plan.viewFile).href)).loadDragonView(plan.id, opts); }
+      }
+      if (mine !== token) { v.dispose?.(); return; }
+      view = v; state = v.initial(now() - (greet && !quiet ? 0 : AGES_OUT));
+      if (!quiet && (show || greet)) appear(why);
+    } catch (e) {
+      if (mine !== token) return;
+      plan = { ...plan, enabled: false, why: `could not load dragon art: ${e.message}` };
+    }
+    notify();
+  }
+
+  return {
+    subscribe(f) { listeners.add(f); return () => listeners.delete(f); },
+    /** Attach: entrance when `greet` (explicit attach), none when re-attaching after a restart. */
+    attach(a, { greet: g = true } = {}) { agent = a || null; greet = g; forced = false; moments.reset(); return load(); },
+    detach() { agent = null; token++; view?.dispose?.(); view = null; state = null; showUntil = 0; job = null; forced = false; clearTimeout(timer); plan = replan(); notify(); },
+    /** Re-read the saved mode (after /dragon companion on|off|greeting). An enable greets. */
+    refresh() { greet = true; forced = false; return load(); },
+    /** Explicit /dragon: show the attached agent's dragon for one dwell, in any mode (even off). false = no dragon agent attached. */
+    async invoke() {
+      if (!agent || !dragonForAgent(agent)) return false;
+      // The view hides itself once its arrival is over unless it persists, and `greeting`/`off` (or a resumed attach) do not persist:
+      // an explicit call reloads it persistent so the whole dwell shows, whatever mode and however long ago it attached.
+      if (!view || !plan.persist) { forced = true; await load({ show: true, persist: true, why: 'invoke' }); return Boolean(view); }
+      appear('invoke'); return true;
+    },
+    /** Send it away now. */
+    dismiss() { if (showUntil) { showUntil = 0; if (summoned) restore(); else notify(); } },
+    /** A keypress: sends it away, but not during the first KEY_GRACE_MS of a dwell (the Enter that invoked it is followed by typing). */
+    keypress() { if (showUntil && now() - shownAt >= KEY_GRACE_MS) this.dismiss(); },
+    /**
+     * A domain moment calls a dragon: companion mode `on` only, never while the user is typing, never while another dragon is on
+     * screen, and not the same dragon again inside SUMMON_COOLDOWN_MS. Works with nothing attached. The caption is the moment's own
+     * truthful line. -> true when it showed.
+     */
+    async summon(dragon, caption) {
+      if (companionMode(settings(), env) !== 'on' || typing() || live()) return false;
+      const last = lastSummon.get(dragon);
+      if (last != null && now() - last < SUMMON_COOLDOWN_MS) return false;
+      lastSummon.set(dragon, now());
+      if (agent && dragonForAgent(agent) === dragon && view && plan.persist) { summonCaption = caption; appear('summon'); return true; }
+      await load({ show: true, as: dragon, caption, persist: true, why: 'summon' });
+      return Boolean(view);
+    },
+    /** Roster rows (every refresh) -> the first objective/loop that just finished or failed summons its dragon. */
+    watchRoster(rows) { const m = rosterWatch.observe(rows)[0]; return m ? this.summon(m.dragon, m.caption) : Promise.resolve(false); },
+    /** True while the dragon is on screen and moving: the host asks the shared clock for frames only then. */
+    animating() { return Boolean(view && state && !plan.still && live()); },
+    /** Feed a reducer action (turn.begin / event / approval.found). Cheap no-op when no companion is active. */
+    tap(action) {
+      if (!view) return;
+      const ev = toCompanionEvent(action);
+      if (ev) { state = view.reduce(state, ev, now()); jobs?.observe?.(ev); }
+      if (action?.type === 'turn.begin') moments.turnStarted();
+      const m = moments.observe(ev);
+      if (m?.companion) keyMoment();
+    },
+    /** True while an attached companion shows key moments (mode on): it owns them, so the Q dragon stays quiet. */
+    ownsMoments() { return Boolean(view && companionMode(settings(), env) === 'on'); },
+    /** The Q dragon's mood for a state change, or null when the companion owns the moment (one dragon per moment). */
+    moodFor(prev, action, next) { return this.ownsMoments() ? null : moodForEvent(prev, action, next); },
+    plan: () => plan,
+    /** Why the art cannot show (mode on/greeting but art missing or unloadable), or null. Independent of the attached agent. */
+    artProblem() {
+      if (companionMode(settings(), env) === 'off') return null;
+      if (/dragon art/.test(plan.why || '')) return plan.why;
+      const p = companionPlan({ agent: 'lucid', settings: settings(), env, isTTY: true, exists, bundled: VENDORED_DRAGONLAB });
+      return !p.enabled && /dragon art/.test(p.why || '') ? p.why : null;
+    },
+    /** One line, once per session, when a dragon agent attaches but the art cannot show. Otherwise null. */
+    takeArtNotice() {
+      if (noticed || !agent || !dragonForAgent(agent) || plan.enabled || !/dragon art/.test(plan.why || '')) return null;
+      noticed = true;
+      return `Dragon companion is ${plan.mode} but its art could not be loaded, so no dragon will show (${plan.why}). /dragon companion status`;
+    },
+    mode: () => plan.mode,
+    /** -> null | { kind:'art', frame, caption, name } | { kind:'label', text } */
+    snapshot(t, { cols, rows }) {
+      const out = this.snapshotNow(t, { cols, rows });
+      if (out && unpainted) { unpainted = false; shownAt = now(); arm(); } // first picture on screen: the dwell and the keypress grace count from here, not from when the art finished loading
+      return out;
+    },
+    snapshotNow(t, { cols, rows }) {
+      if (summoned && view && !live()) { restore(); return null; } // a summoned dragon's dwell ended: back to the attached one (never while its art is still loading: a frame drawn then cancelled the summon)
+      if (!view || !state || !live()) return null;
+      const big = cols >= ART_MIN_COLS && rows >= ART_MIN_ROWS;
+      let v;
+      const mood = job?.mood === 'concerned' && !state.approvals.length ? 'concerned' : null;
+      try { v = view.view(state, t, { cols, rows: big ? rows : 1, mood }); } catch { return null; }
+      if (v.hidden) return null;
+      // One caption per trigger: "Attached." only on an attach; an invoke says who is here; an approval always says so.
+      let caption = v.caption;
+      const summonedCaption = summonCaption;
+      if (state.approvals.length) caption = 'Waiting for your approval.';
+      else if (job?.caption && !state.issue) caption = job.caption; // the dragon's job: a real read (jobs.js); an approval or a recorded failure still comes first
+      else if (state.phase === 'connecting') caption = trigger === 'attach' ? 'Attached.' : trigger === 'invoke' ? `${view.name} is here.` : v.caption;
+      if (summonedCaption && now() < showUntil) caption = summonedCaption; // a domain moment states its own fact
+      if (!big) return { kind: 'label', text: `${view.name}: ${caption}` };
+      if (!v.frame) { waitingFrame = true; return null; } // the first frame is still being drawn off the main thread: draw nothing rather than a gap
+      return { kind: 'art', frame: v.frame, caption, name: view.name };
+    },
+  };
+}
+
+/** "/dragon companion <arg>" -> { text, tone, save?, refresh? }. Pure. */
+export function companionCommand(arg, { settings = {}, plan = null, artProblem = null } = {}) {
+  // `invoke: true` = the host also plays the attached agent's dragon for a dwell (a status check is a call for the dragon too).
+  const w = String(arg || '').trim().toLowerCase();
+  const cur = normaliseMode(settings.dragonCompanion);
+  if (!w || w === 'status') {
+    const mode = cur || plan?.mode || 'on';
+    const now = plan?.enabled ? `showing ${plan.id}` : `not showing (${plan?.why || 'no agent attached'})`;
+    if (artProblem && mode !== 'off') return { text: `Dragon companion: ${mode}, but the art can't be loaded so no dragon will show (${artProblem}). /dragon companion on|greeting|off.`, tone: 'warn' };
+    return { text: `Dragon companion: ${mode}, ${now}. /dragon companion on|greeting|off. Only Lucid, Hyperion, Seer, Sentinel, Drago and Cipher have dragons.`, invoke: true };
+  }
+  const m = normaliseMode(w);
+  if (!m) return { text: `Usage: /dragon companion ${COMPANION_MODES.join('|')}|status`, tone: 'warn' };
+  const what = { on: 'appears on attach and at key moments such as a new approval, a failure or a long task finishing, then leaves after a few seconds', greeting: 'appears on attach only, then leaves', off: 'never appears on its own' }[m];
+  if (artProblem && m !== 'off') return { text: `Dragon companion: ${m} saved, but the art can't be loaded so no dragon will show (${artProblem}).`, tone: 'warn', save: m, refresh: true };
+  return { text: `Dragon companion: ${m} (${what}). /dragon always calls it. Saved to this profile.`, tone: 'ok', save: m, refresh: true };
+}
+
+/** The live block. Re-renders on the shared clock; draws nothing when there is no companion. */
+export function DragonCompanionLive({ ctl, cols, rows }) {
+  const t = useFrame();
+  const [, bump] = React.useState(0);
+  React.useEffect(() => ctl.subscribe(() => bump(x => x + 1)), [ctl]);
+  const snap = ctl.snapshot(t, { cols, rows });
+  if (!snap) return null;
+  if (dragonActive()) return null; // an explicit /dragon <clip> owns the canvas: the companion steps aside (both stacked overflow a 34-row terminal and Ink wipes the screen, 2026-10-25)
+  if (snap.kind === 'label') return h(Box, { paddingLeft: 2 }, h(Text, { wrap: 'truncate' }, snap.text));
+  return h(Box, { flexDirection: 'row', marginTop: 1 },
+    h(Box, { flexDirection: 'column', flexShrink: 0 }, ...snap.frame.map((r, k) => h(Text, { key: k, wrap: 'truncate' }, ...cellNodes(r, `dc${k}-`)))),
+    h(Box, { flexDirection: 'column', paddingLeft: 2 },
+      h(Text, { bold: true }, snap.name.toUpperCase()),
+      h(Text, { wrap: 'wrap' }, snap.caption)));
+}
+
+/**
+ * /detach back to Q: with dragons on (mode on or greeting) the Q dragon gets one greeting, the way an attach shows the agent's.
+ * -> null | { clip:'pick' } | { note } (the window is too small: say so in one line). Pure.
+ */
+export function detachGreeting({ settings = {}, env = process.env, rows = null, chromeH = 10, hadAgent = true } = {}) {
+  if (!hadAgent || companionMode(settings, env) === 'off' || motionPolicy(env).off) return null;
+  const room = clipRoom('dragon', rows, chromeH);
+  return room.ok ? { clip: 'pick' } : { note: room.note };
+}