quoxcli 0.3.1 → 0.5.0

package/lib/quoxon/deckLazy.js

@@ -0,0 +1,58 @@
+/**
+ * LAZY PATH (QUOXON, 2026-10-29; plan first-run-onboarding-plan.md section 4): /deck on a machine that lacks the
+ * quoxdeck extension, or the ALSA headers its native midi dependency builds against, OFFERS one y/N instead of a raw
+ * build error. Pure planning plus an injected runner: nothing here touches the machine until the user says y, and
+ * sudo is the user's own (the exact command is shown first; no password is ever read, stored or passed).
+ */
+import { spawnSync } from 'node:child_process';
+
+export const DECK_PKG = 'quoxdeck';
+export const ALSA_PKG = 'libasound2-dev';
+const SYSTEM = { apt: { cmd: `sudo apt-get install -y ${ALSA_PKG}`, pkg: ALSA_PKG }, dnf: { cmd: 'sudo dnf install -y alsa-lib-devel', pkg: 'alsa-lib-devel' } };
+const NPM_CMD = `npm i -g ${DECK_PKG}`;
+const ADD_CMD = `quox ext add ${DECK_PKG}`;
+
+const quick = (file, args) => { try { return spawnSync(file, args, { stdio: 'ignore', timeout: 3000 }); } catch { return { status: 1 }; } };
+/** Cheap ALSA header check: pkg-config, else the header path. */
+export async function defaultHasAlsa() {
+  if (quick('pkg-config', ['--exists', 'alsa']).status === 0) return true;
+  return ['/usr/include/alsa/asoundlib.h'].some((p) => quick('test', ['-f', p]).status === 0);
+}
+/** apt or dnf only; anything else is null (we never guess further). */
+export async function defaultPackageManager() {
+  for (const pm of ['apt-get', 'dnf']) if (quick('sh', ['-c', `command -v ${pm}`]).status === 0) return pm === 'dnf' ? 'dnf' : 'apt';
+  return null;
+}
+
+/**
+ * -> null (nothing to offer) | { text } (no automatic path: say it, show manual commands)
+ *    | { question, steps:[{label, cmd, interactive?}], manual:[cmd] }
+ */
+export async function deckOffer({ platform = process.platform, isInstalled, hasAlsa = defaultHasAlsa, packageManager = defaultPackageManager } = {}) {
+  const installed = Boolean(await isInstalled());
+  const alsaMissing = platform === 'linux' && !(await hasAlsa());
+  if (installed && !alsaMissing) return null;
+  const pm = alsaMissing ? await packageManager() : null;
+  if (alsaMissing && !pm) {
+    return { steps: null, text: `quoxdeck needs the ALSA development headers (${ALSA_PKG} on Debian, alsa-lib-devel on Fedora). This machine has neither apt or dnf, so install them with your own package manager, then run: ${NPM_CMD} && ${ADD_CMD}` };
+  }
+  const steps = [];
+  if (alsaMissing) steps.push({ label: `system package ${SYSTEM[pm].pkg}`, cmd: SYSTEM[pm].cmd, interactive: true });
+  steps.push({ label: installed ? 'rebuild the quoxdeck extension' : 'install the quoxdeck extension', cmd: NPM_CMD });
+  steps.push({ label: 'list it in quoxon', cmd: ADD_CMD });
+  const need = [...(alsaMissing ? [`system package ${SYSTEM[pm].pkg}`] : []), 'the quoxdeck extension'];
+  return { steps, manual: steps.map((s) => s.cmd), question: `quoxdeck needs: ${need.join(', then ')}. Install now?` };
+}
+
+export const declineText = (o) => `Nothing to turn off. When you want it: ${o.manual.join(' && ')}`;
+
+/** Runs the steps in order via the injected run(step); stops at the first failure; re-runs /deck only on full success. */
+export async function runDeckOffer(o, { run, say = () => {}, rerun = async () => {} }) {
+  for (const s of o.steps) {
+    say(`Running: ${s.cmd}`);
+    let r; try { r = await run(s); } catch (e) { r = { code: 1, error: e?.message }; }
+    if (r?.code !== 0) { say(`Stopped at: ${s.cmd} (${r?.error || `exit ${r?.code ?? 'unknown'}`}). Nothing after it ran. To finish by hand: ${o.manual.slice(o.steps.indexOf(s)).join(' && ')}`, 'warn'); return { ok: false, failed: s.cmd }; }
+  }
+  await rerun();
+  return { ok: true };
+}

package/lib/quoxon/demo.autoplay.js

@@ -4,7 +4,7 @@
  */
 export const AUTOPLAY_LABEL = 'DEMO: demo data, nothing real runs.';
 export const AUTOPLAY_REQUEST = 'Show me what you can do (demo)';
-export const AUTOPLAY_PROOF = '/proof';
+export const AUTOPLAY_PROOF = '/proof 1'; // bare /proof lists envelope ids (d73f04ab4); 1 is the newest chain, which the journey shows
 export const AUTOPLAY = Object.freeze({ seed: 20261013, startMs: 900, typeMinMs: 38, typeMaxMs: 78, afterTypeMs: 450, approvalHoldMs: 2500, afterKeyMs: 400, afterTurnMs: 900, finalHoldMs: 600 });
 
 /** Small seeded PRNG (mulberry32): deterministic across runs and platforms. */

package/lib/quoxon/demo.js

@@ -19,13 +19,15 @@ function decisionStore(file) {
   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)
-    async open() { const d = load(); await wait(d.approvalsDelayMs); return d.items.filter(x => x.status === 'open' || (d.staleMs && x.answeredAt && Date.now() - x.answeredAt < d.staleMs)); },
+    // 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 };
     }

package/lib/quoxon/destructive.js

@@ -0,0 +1,35 @@
+// A DESTRUCTIVE approval (owner 2026-10-27 16:15 UTC, after two delete_workflow cards were approved by one 'y' each)
+// needs a stronger confirm: the human types the object's name. One place decides what is destructive.
+import { describeInboxItem } from './events.js';
+
+/** Tools named delete_*, remove_*, purge_*, destroy_*, drop_* or wipe_* (the prefix only; "undelete_x" is not one). */
+export const DESTRUCTIVE_TOOL = /^(delete|remove|purge|destroy|drop|wipe)_/i;
+export const isDestructiveTool = (tool) => DESTRUCTIVE_TOOL.test(String(tool ?? '').trim());
+
+const flagged = (o) => Boolean(o && (o.destructive === true || o.irreversible === true));
+
+/** True when the server marks the item destructive or irreversible, else when its tool name follows the rule. */
+export function isDestructive(it) {
+  if (!it) return false;
+  const p = it.payload || {}; const c = p.approval_context || {};
+  if (flagged(it) || flagged(p) || flagged(c) || flagged(c.method) || flagged(p.what)) return true;
+  return isDestructiveTool(describeInboxItem(it).tool);
+}
+
+const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : typeof v === 'number' ? String(v) : null);
+const argsOf = (it) => {
+  const p = it?.payload || {}; const c = p.approval_context || {}; const m = c.method || {};
+  const a = m.args ?? m.input ?? c.args ?? c.input ?? p.args ?? p.input ?? p.action_params ?? null;
+  if (a && typeof a === 'object' && !Array.isArray(a)) return a;
+  if (typeof a === 'string') { try { const j = JSON.parse(a); if (j && typeof j === 'object' && !Array.isArray(j)) return j; } catch { /* not JSON */ } }
+  return {};
+};
+
+/** What gets deleted: { label, name }. The human name when the input has one (name, workflow_name, host_name...), else the id from the input, else the short item id. name is what the human must type. */
+export function destructiveObject(it) {
+  const a = argsOf(it);
+  const nameKey = Object.keys(a).find(k => /(^|_)name$/i.test(k) && str(a[k]));
+  const idKey = Object.keys(a).find(k => /(^|_)id$/i.test(k) && str(a[k]));
+  const v = (nameKey && str(a[nameKey])) || (idKey && str(a[idKey])) || String(it?.id ?? 'item').slice(0, 8);
+  return { label: v, name: v };
+}

package/lib/quoxon/dividerAocl.js

@@ -153,13 +153,14 @@ export function chainCells(d, now, { still = false } = {}) {
  * 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, d, now, mono = false, reduced = false, still = false, seed = 0 }) {
+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 left = cols - lw - 1 - cw;
+  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] || ''} ` : '';
@@ -184,7 +185,7 @@ export function dividerFrame({ cols, label, d, now, mono = false, reduced = fals
       }
     } else labelCells = [{ t: lab, label: true }];
   }
-  return { cells: [...leftCells, ...chain.cells, ...labelCells, { t: '─' }] };
+  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). */

package/lib/quoxon/dividerRule.js

@@ -38,7 +38,7 @@ export function paintFrame(f, { ruleColor, labelColor }) {
   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.label ? labelColor : ruleColor) || null, bold: Boolean(c.bold) };
+    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;
@@ -48,10 +48,10 @@ export function paintFrame(f, { ruleColor, labelColor }) {
 }
 
 /** 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, divider, now, ruleColor, labelColor, mono = false, reduced = false, slow = null }) {
+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, d: divider, now, mono, reduced, still: isSlow }); // slow: keep the lit pips, drop the motion
+  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/dnd.js

@@ -0,0 +1,71 @@
+/**
+ * DO-NOT-DISTURB (owner 2026-10-28: "sleep means sleep"). Pure helpers for /donotdisturb (/dnd) and /morningreport.
+ * While DND is on the window collects instead of announcing; the app holds the collected arrivals and these functions
+ * turn them into the morning digest. No I/O here.
+ */
+export const DND_NOTE = 'do not disturb';
+export const DND_USAGE = 'Usage: /donotdisturb [on|off] [until HH:MM]  (alias /dnd; bare turns it on)';
+
+/** `/dnd [on|off] [until HH:MM]` -> { ok, op: 'on'|'off'|'toggle', until: {h,m}|null } | { ok:false, error }. */
+export function parseDndArgs(arg) {
+  const a = String(arg || '').trim().toLowerCase();
+  if (!a) return { ok: true, op: 'toggle', until: null };
+  const m = /^(?:(on|off)\s*)?(?:until\s+(\d{1,2}):(\d{2}))?$/.exec(a);
+  if (!m || (!m[1] && m[2] === undefined)) return { ok: false, error: DND_USAGE };
+  let until = null;
+  if (m[2] !== undefined) {
+    const h = Number(m[2]), mi = Number(m[3]);
+    if (h > 23 || mi > 59) return { ok: false, error: DND_USAGE };
+    if (m[1] === 'off') return { ok: false, error: DND_USAGE };
+    until = { h, m: mi };
+  }
+  return { ok: true, op: m[1] || 'on', until };
+}
+
+/** The next local HH:MM after `now` as epoch ms. */
+export function untilEpoch({ h, m }, now = Date.now()) {
+  const d = new Date(now); d.setHours(h, m, 0, 0);
+  if (d.getTime() <= now) d.setDate(d.getDate() + 1);
+  return d.getTime();
+}
+
+/** Text that says the owner is heading off: going to sleep / off to bed / signing off for the night / night all. */
+const SLEEP_RE = /\b(?:i['’]?m|i am|im|we['’]?re|owner(?: is)?|adam(?: is)?)?\s*(?:going to (?:sleep|bed)|off to (?:bed|sleep)|heading to (?:bed|sleep)|going offline|signing off(?: for (?:the )?(?:night|today|now))?|logging off for the night|turning in(?: for the night)?)\b|\bnight[,!. ]+(?:all|everyone|team|folks)\b|\bgood ?night (?:all|everyone|team|folks)\b/i;
+export const sleepIntent = (text) => SLEEP_RE.test(String(text || ''));
+
+/** `/afk <text>` whose text says sleep/bed/night: the owner means /sleep. */
+export const afkMeansSleep = (text) => /\b(?:sleep|sleeping|asleep|bed|bedtime|night|goodnight)\b/i.test(String(text || '')) || /\bgood night\b/i.test(String(text || ''));
+
+export const newCollected = () => ({ inbox: [], slots: [], since: Date.now() });
+
+const titleOf = (it) => String(it.title || it.kind || 'untitled');
+const INCIDENT_RE = /incident|outage|critical|sev[ -]?[01]|down\b|breach|alert|failed/i;
+export const isIncident = (it) => INCIDENT_RE.test(`${it.kind || ''} ${it.severity || ''} ${it.priority || ''} ${titleOf(it)}`);
+
+/** Collapse by title with a count: [{ title, n }] in first-seen order. */
+export function collapseByTitle(items) {
+  const m = new Map();
+  for (const it of items) { const k = titleOf(it); m.set(k, (m.get(k) || 0) + 1); }
+  return [...m].map(([title, n]) => ({ title, n }));
+}
+
+/** How many things wait for the owner: approvals + collected inbox arrivals + collected slot messages. */
+export const waitingCount = (c, approvals = 0) => approvals + (c?.inbox?.length || 0) + (c?.slots?.length || 0);
+
+/** The digest as [text, tone] lines. Incidents first, then approvals, inbox (xN), slot messages, sessions that need you. */
+export function morningLines(c, { approvals = 0, sessions = [] } = {}) {
+  const lines = [];
+  const inc = c.inbox.filter(isIncident), rest = c.inbox.filter((i) => !isIncident(i));
+  const group = (head, items, tone) => { if (items.length) { lines.push([head, tone]); for (const g of collapseByTitle(items)) lines.push([`  ${g.title}${g.n > 1 ? ` (×${g.n})` : ''}`, 'plain']); } };
+  group(`Incidents (${inc.length})`, inc, 'warn');
+  if (approvals) lines.push([`Approvals waiting (${approvals}): /approvals`, 'warn']);
+  group(`Inbox (${rest.length})`, rest, 'plain');
+  if (c.slots.length) {
+    lines.push([`Slot messages (${c.slots.length})`, 'plain']);
+    for (const s of c.slots.slice(0, 10)) lines.push([`  ${s.from}: ${String(s.text).replace(/\s+/g, ' ').slice(0, 90)}`, 'plain']);
+    if (c.slots.length > 10) lines.push([`  ... ${c.slots.length - 10} more`, 'dim']);
+  }
+  if (sessions.length) { lines.push([`Sessions that need you (${sessions.length})`, 'warn']); for (const s of sessions.slice(0, 8)) lines.push([`  ${s}`, 'plain']); }
+  if (!lines.length) lines.push(['Nothing collected while you were away.', 'ok']);
+  return lines;
+}

package/lib/quoxon/dragonCompanion.js

@@ -0,0 +1,285 @@
+/**
+ * Dragon companion for Quoxon (Lucid, Hyperion, Seer, Sentinel, Drago, Cipher, Vulcan, Quoxperticus). 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, createSenderWatch, 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, narrowNoticed = 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(); const senderWatch = createSenderWatch({ now }); // 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.
+     */
+    canSummon(dragon) {
+      if (companionMode(settings(), env) !== 'on' || typing() || live()) return false;
+      const last = lastSummon.get(dragon);
+      return !(last != null && now() - last < SUMMON_COOLDOWN_MS);
+    },
+    async summon(dragon, caption) {
+      if (!this.canSummon(dragon)) 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);
+    },
+    /**
+     * A slot message landed in the owner's stream: a fresh line from a session whose agent has a dragon summons that dragon for one
+     * dwell (dragonMoments.js slotMessageMoment; deduped, per-sender cooldown). `opts` = { broadcast, run }. -> true when it showed.
+     */
+    async slotMessage(m, opts = {}) {
+      const mo = senderWatch.observe(m, opts);
+      if (!mo || !this.canSummon(mo.dragon)) return false;
+      senderWatch.shown(mo.sender);
+      return this.summon(mo.dragon, mo.caption);
+    },
+    /** Another session's approval card newly waiting (state prev -> next), asked by a dragon agent: that dragon appears. */
+    async waitingCards(prev, next) {
+      const mo = senderWatch.card(prev, next);
+      if (!mo || !this.canSummon(mo.dragon)) return false;
+      senderWatch.shown(mo.sender);
+      return this.summon(mo.dragon, mo.caption);
+    },
+    /** 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,
+    /**
+     * Once per session: a dragon is attached and would show, but this window is too small for the art, so all that appears is a
+     * one-line label. Say why in plain words rather than hiding it silently. Otherwise null.
+     */
+    narrowNotice({ cols, rows }) {
+      if (narrowNoticed || !agent || !dragonForAgent(agent) || !plan.enabled || !view) return null;
+      if (cols >= ART_MIN_COLS && rows >= ART_MIN_ROWS) return null;
+      narrowNoticed = true;
+      return `The dragon needs ${ART_MIN_COLS} columns and ${ART_MIN_ROWS} rows to be drawn; this window is ${cols} by ${rows}, so you only get its caption line. Widen the window to see it.`;
+    },
+    /** -> 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, Cipher, Vulcan and Quoxperticus 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 };
+}

package/lib/quoxon/dragonModes.js

@@ -54,6 +54,7 @@ export function parseDragonArg(restArg) {
     case 'hero': return rest.length ? null : { mode: 'hero' };
     // `/dragon explain <thing>` is a question about that thing (owner 2026-10-15: it used to print usage).
     case 'explain': return rest.length ? { mode: 'ask', question: rest.join(' ').trim() } : { mode: 'explain' };
+    case 'companion': return { mode: 'companion', arg: rest.join(' ') };
     case 'sleep': return rest.length ? null : { mode: 'sleep' };
     case 'fly': return rest.length ? null : { mode: 'fly' };
     case 'ask': return { mode: 'ask', question: rest.join(' ').trim() };