quoxcli 0.3.1 → 0.4.0

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/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 };
+}

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() };

package/lib/quoxon/dragonMoments.js

@@ -0,0 +1,82 @@
+/**
+ * ONE moment engine for both dragon systems. A "moment" is a stream fact worth a dragon: an approval is waiting, a turn or the
+ * stream failed, a long turn finished, a turn finished. The classification (and its dedupe) lives here once; the table says what
+ * each moment calls: `mood` is the Q dragon's cinematic clip (qmotion playDragon), `companion` is whether an attached companion
+ * dragon shows itself. The controller (dragonCompanion.js) runs the engine on every stream fact and owns the routing: while a
+ * companion owns the moments the Q dragon stays quiet, so a moment is never two dragons.
+ */
+export const MOMENTS = Object.freeze({
+  approval: Object.freeze({ mood: 'waiting', companion: true }),
+  failure: Object.freeze({ mood: 'failure', companion: true }),
+  long: Object.freeze({ mood: 'success', companion: true }),
+  success: Object.freeze({ mood: 'success', companion: false }),
+});
+/** A turn at least this long counts as a "long task" when it finishes. */
+export const LONG_TASK_MS = 30000;
+
+export function createMomentEngine({ now = Date.now } = {}) {
+  const seen = new Set();
+  let turnStart = null;
+  const moment = (kind) => ({ kind, ...MOMENTS[kind] });
+  return {
+    turnStarted() { turnStart = now(); },
+    reset() { seen.clear(); turnStart = null; },
+    /** A reducer event (the companion's vocabulary) -> { kind, mood, companion } | null. */
+    observe(ev) {
+      if (!ev) return null;
+      if (ev.type === 'approval.requested') {
+        // The same approval arrives twice (the stream event, then the inbox poll) under different ids: one moment for it.
+        const keys = [ev.call_id, ev.inbox_item_id, ev.approval_id].filter(Boolean).map(String);
+        if (keys.some(k => seen.has(k))) return null;
+        keys.forEach(k => seen.add(k));
+        return moment('approval');
+      }
+      if (ev.type === 'error') return moment('failure');
+      if (ev.type === 'turn.finished') {
+        const started = turnStart; turnStart = null;
+        if (ev.status === 'failed' || ev.status === 'unconfirmed') return moment('failure');
+        if (ev.status !== 'completed') return null;
+        return moment(started != null && now() - started >= LONG_TASK_MS ? 'long' : 'success');
+      }
+      return null;
+    },
+  };
+}
+
+// ---- domain moments: a fact from the estate summons the matching dragon (companion mode `on` only) ------------------------
+/** A dragon summoned by a domain moment cannot be summoned again for this long. */
+export const SUMMON_COOLDOWN_MS = 60000;
+
+/**
+ * An objective or loop roster row -> { dragon, caption } when it has finished or failed, else null. The caption states only
+ * what the row says. The roster row carries no agent, so the dragon is Seer (the plan dragon); an agent field would pick its own.
+ */
+export function objectiveMoment(row) {
+  if (!row || (row.kind !== 'objective' && row.kind !== 'loop') || (row.state !== 'done' && row.state !== 'failed')) return null;
+  const noun = row.kind === 'loop' ? 'Loop' : 'Objective', name = row.name || row.id;
+  const caption = row.state === 'done' ? `${noun} finished: ${name}.` : `${noun} failed: ${name}${row.activity ? ` (${row.activity})` : ''}.`;
+  return { dragon: 'seer', caption };
+}
+
+/**
+ * Watches roster rows and reports each objective/loop that was seen unfinished and is now done or failed, once. The first
+ * observation is a baseline (rows already finished at startup never fire); a reported key is retired for good.
+ */
+export function createRosterWatch() {
+  const active = new Set(), retired = new Set();
+  let primed = false;
+  return {
+    observe(rows = []) {
+      const out = [];
+      for (const r of rows) {
+        if (!r || (r.kind !== 'objective' && r.kind !== 'loop') || retired.has(r.key)) continue;
+        if (r.state === 'done' || r.state === 'failed') {
+          if (active.delete(r.key) && primed) { const m = objectiveMoment(r); if (m) out.push(m); }
+          retired.add(r.key);
+        } else active.add(r.key);
+      }
+      primed = true;
+      return out;
+    },
+  };
+}

package/lib/quoxon/dragonReads.js

@@ -0,0 +1,68 @@
+/**
+ * The reads behind the dragon jobs (lib/dragon/jobs.js). Each is the same call a `quox` verb already makes, read-only,
+ * bounded, retries off. The CLI client throws on a non-2xx, so a throw is the failure and a returned body is checked for the
+ * error shapes some routes use with a 200 (success:false). Nothing here turns an error into a count.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+import { healthOf } from './objects/fleet.js';
+
+const TIMEOUT = 5000;
+const STATE = { 1: 'up', 0: 'down', 2: 'pending', 3: 'maintenance' };
+const kumaState = (m) => (m && typeof m.state === 'string' ? m.state : m && Object.hasOwn(STATE, m.status) ? STATE[m.status] : 'unknown'); // same mapping as `quox kuma`
+const whyOf = (e) => (e?.status ? `HTTP ${e.status}` : /timed out/i.test(e?.message || '') ? 'timed out' : e?.message || 'failed');
+
+export function createDragonReads({ client }) {
+  const get = (name, params, query) => { const ep = resolveEndpoint(name, params); return client.get(ep.path, { service: ep.service, query, retries: 0, timeout: TIMEOUT }); };
+  return {
+    /** WARD inclusion receipt of one envelope (POST /ward/verify-receipt, the route /proof uses). -> { ok, result } | { ok:false, error } */
+    async verifyReceipt(envelopeId) {
+      try {
+        const d = await client.post('/ward/verify-receipt', { service: 'collector', body: { source_id: envelopeId, source_kind: 'AEE' }, retries: 0, timeout: TIMEOUT });
+        return { ok: true, result: d?.result || d };
+      } catch (e) { return { ok: false, error: whyOf(e) }; }
+    },
+    /** `quox kuma` live read -> { up, down, total, avgPing, downNames, ageSeconds } */
+    async routes() {
+      const d = await get('mon.kuma.live.get');
+      if (d?.success === false) throw new Error(`kuma returned an error body: ${d.error || 'no detail'}`);
+      if (!Array.isArray(d?.monitors)) throw new Error('kuma answered with no monitors list');
+      const ms = d.monitors;
+      const up = ms.filter(m => kumaState(m) === 'up'), down = ms.filter(m => kumaState(m) === 'down');
+      const pings = up.filter(m => m.ping != null).map(m => Number(m.ping)).filter(Number.isFinite); // a null ping is no measurement, not 0 ms
+      return { up: up.length, down: down.length, total: ms.length, avgPing: pings.length ? pings.reduce((a, b) => a + b, 0) / pings.length : null, downNames: down.map(m => m.name || `monitor ${m.id}`), ageSeconds: Number.isFinite(d.ageSeconds) ? d.ageSeconds : null };
+    },
+    /** `quox plan focus` -> { id, done, total } of the first focus stream; null when nothing is in focus or there is no roadmap. */
+    async plan() {
+      const rms = (await get('quoxplan.roadmaps.list'))?.roadmaps;
+      if (!Array.isArray(rms)) throw new Error('quoxplan answered with no roadmaps list');
+      if (!rms.length) return null;
+      const streams = (await get('quoxplan.roadmap.streams.list', { roadmapId: rms[0].id }, { lens: 'focus' }))?.streams;
+      if (!Array.isArray(streams)) throw new Error('quoxplan answered with no streams list');
+      if (!streams.length) return null;
+      // The first few focus streams, in the server's order: the first one that has phases gives "x of y". A stream with none (a meta
+      // stream) or whose phases could not be read is only named, never given a made-up count.
+      const top = streams.slice(0, 3);
+      const details = await Promise.allSettled(top.map(t => get('quoxplan.stream.get', { id: t.id })));
+      const rows = top.map((t, i) => {
+        const phases = details[i].status === 'fulfilled' && Array.isArray(details[i].value?.phases) ? details[i].value.phases : null;
+        return phases ? { id: t.id, done: phases.filter(p => p.done_at || /^(done|complete)/i.test(String(p.status || ''))).length, total: phases.length } : { id: t.id, done: null, total: null };
+      });
+      return rows.find(r => r.total > 0) || rows[0];
+    },
+    /** `quox fleet hosts` rows bucketed by health. */
+    async fleet() {
+      const d = await get('v1.fleet.hosts.list');
+      const hosts = Array.isArray(d) ? d : d?.hosts;
+      if (!Array.isArray(hosts)) throw new Error('unexpected fleet response');
+      const c = { total: hosts.length, healthy: 0, degraded: 0, unhealthy: 0, offline: 0, unknown: 0 };
+      for (const h of hosts) c[healthOf(h)]++;
+      return c;
+    },
+    /** The org's open security findings (engagement store). */
+    async findings() {
+      const d = await get('engagement.findings.open', {});
+      if (!Array.isArray(d?.findings)) throw new Error('unexpected findings response');
+      return { open: d.findings.length, severe: d.findings.filter(f => /^(critical|high)$/i.test(String(f.severity || ''))).length };
+    },
+  };
+}

package/lib/quoxon/dragonView.js

@@ -32,10 +32,10 @@ export function DragonTalk({ cols, label, talking, since, still = false }) {
 }
 
 /** /dragon-fly: one pass of the dragon in flight across the live region (qdragonFly.js). `still`: a single frame, no motion. */
-export function FlyLive({ cols, rows, startedAt, still = false }) {
+export function FlyLive({ cols, rows, startedAt, still = false, chromeH = null }) {
   useFrame();
   const c = flyCols(cols);
-  const cells = flyFrame(Date.now() - startedAt, c, { still, mono: mono(), theme: isLight() ? 'light' : 'dark', termRows: rows });
+  const cells = flyFrame(Date.now() - startedAt, c, { still, mono: mono(), theme: isLight() ? 'light' : 'dark', termRows: rows, chromeH });
   return h(Box, { flexDirection: 'column', marginTop: 1 },
     ...cells.map((row, k) => h(Text, { key: k, wrap: 'truncate' }, ...cellNodes(row, `f${k}-`))));
 }

package/lib/quoxon/events.js

@@ -11,8 +11,10 @@
  *   turn     : null | { id, status: running|interrupting, startedAt, stage, activity }
  */
 
+import { approvalSentence } from './approvalSentence.js';
 import { dividerStep } from './dividerAocl.js';
 import { approvalFacts } from './approvalFacts.js';
+import { planLines } from './planSteps.js';
 import { isConsentError, consentErrorText } from './consent.js';
 import { splitSettled } from './markdownSettle.js'; // not markdown.js: that loads React + Ink (QUOXON-LATENCY)
 import { nextActivity, actionActivity } from './activity.js';
@@ -125,7 +127,8 @@ export function cardFromInboxItem(it, { since = 0, userId = null, conversationId
   return {
     callId: `inbox:${it.id}`, inboxItemId: it.id, approvalId,
     tool, target: d.target, what: d.title, askedBy: d.by, askedAt: d.at, scope: null, risk: c.risk || null,
-    url: it.dashboard_url || null, shownAt: now, undescribable: !d.tool && !d.target,
+    url: it.dashboard_url || null, shownAt: now, undescribable: !d.tool && !d.target && !it._plan,
+    plan: it._plan ? { lines: planLines(it._plan.steps), loaded: it._plan.loaded !== false, orgId: it._plan.orgId || null, orgName: it._plan.orgName || null } : null, // the plan's steps + the item's own org
     facts: approvalFacts(it), // APPROVAL-WWWH: the exact command, hosts, chain, reason, time and read-only class
     // only an item that names THIS conversation is ours; anything else came from another session and must not take the keyboard
     foreign: !here,
@@ -161,6 +164,18 @@ export function groupApprovals(items, { conversationId = null, cardIds = [] } =
   return Object.entries(g).filter(([, v]) => v.length).map(([group, v]) => ({ group, items: v }));
 }
 
+/**
+ * QLOOP-LIVE: which approval card the keyboard goes to first. Cards about a loop THIS window is watching lead, then the rest of
+ * this conversation, then other sessions' items (stable inside each rank). The loop id appears in the card's target / description.
+ */
+export function orderApprovals(cards, mineIds = []) {
+  const ids = (mineIds || []).filter(Boolean).map(String);
+  const rank = (c) => (ids.length && ids.some((id) => [c.target, c.what, c.facts?.where].some((t) => t != null && String(t).includes(id))) ? 0 : c.foreign ? 2 : 1);
+  return cards.map((c, i) => ({ c, i, r: rank(c) })).sort((a, b) => a.r - b.r || a.i - b.i).map((x) => x.c);
+}
+/** Cards raised by other sessions (the "other sessions: N" tail). */
+export const otherSessionsCount = (cards) => (cards || []).filter((c) => c.foreign).length;
+
 /** Privileged/elevated grants (hat switches and anything the server marks privileged or elevated) need an explicit confirm. */
 export function isPrivileged({ tool = '', risk = null, flag = false, title = '' } = {}) {
   if (flag === true) return true;
@@ -345,6 +360,8 @@ function reduceInner(s, a) {
       return { ...s, history: [...s.history, { id: nid(), kind: 'bang', text: a.text }] };
     case 'slotmsg': // QUOXON-MESH: a slot chat line (slotChat.js slotLine), incoming or sent
       return { ...s, history: [...s.history, { id: nid(), kind: 'slotmsg', line: a.line }] };
+    case 'loopcard': // QLOOP-LIVE: a live loop card; the card object is mutated in place by loopCards.js
+      return { ...s, history: [...s.history, { id: nid(), kind: 'loopcard', card: a.card }] };
     case 'tip': // a "did you know" tip (tips.js); text + the command to try
       return { ...s, history: [...s.history, { id: nid(), kind: 'tip', text: a.text, cmd: a.cmd }] };
     case 'bcard': // QUOXON-BROADCAST: the sender's framed delivery card (slash/broadcast.js broadcastCard), pure data
@@ -443,8 +460,8 @@ function reduceInner(s, a) {
       const rest = { ...s, inbox: (s.inbox || []).filter(x => x.id !== a.inboxItemId), seenInbox: a.inboxItemId ? { ...s.seenInbox, [a.inboxItemId]: true } : s.seenInbox, approvals: s.approvals.filter(x => x.callId !== a.callId && !(a.inboxItemId && x.inboxItemId === a.inboxItemId)), waiting: s.waiting.filter(x => x.callId !== a.callId && x.inboxItemId !== a.callId) };
       if (a.batch) return rest; // /approve N prints its own one-line summary
       if (a.quiet && a.action === 'approve') return rest;
-      if (a.action !== 'approve') return note(rest, `denied: ${a.tool || 'approval'}${a.target ? ` on ${a.target}` : ''}`, 'warn');
-      if (a.foreign) return note(rest, `✔ Approved ${a.tool || 'approval'}${a.target ? ` on ${a.target}` : ''}; the plugin or agent will act on it (its outcome is not tracked here)`, 'ok');
+      if (a.action !== 'approve') return note(rest, approvalSentence(a, false), 'warn');
+      if (a.foreign) return note(rest, approvalSentence(a, true), 'ok');
       if (a.tool === 'hat.switch') { // applied server-side by the inbox approve; nothing to wait for
         const to = String(a.target || '').split('\u2192').pop().replace(/\(privileged\)/, '').trim() || 'the new hat';
         return note(rest, `Hat switched to ${to}. Ask again and I'll carry on.`, 'ok');
@@ -485,6 +502,9 @@ export function reduce(s, a) {
     const dv = dividerStep(s.divider ?? null, a, a.now || 0);
     if (dv !== (n.divider ?? null)) n = { ...n, divider: dv };
   }
+  // A turn that ends WITHOUT a turn.finished event (stopped.local, turn.deferred, a /clear cancel) must not leave the
+  // strip open: endedAt stayed null, dividerLive stayed true, and the dot train + scrambled label looped on a dead turn.
+  if (n.divider && n.divider.endedAt == null && !n.turn) n = { ...n, divider: null };
   // The honest activity word: only real events move it (see activity.js).
   if (n.turn) {
     const act = a.type === 'event' ? nextActivity(s.turn?.act, a.ev, a.now || 0, { hasText: Boolean(n.turn.chars) })
@@ -558,6 +578,7 @@ function reduceEvent(s, ev, now) {
       let withTool = upsertTool(s, ev, {
         status, resultSummary: toolResultText(ev.result_summary, s.verbose), rawSummary: ev.result_summary, durationMs: ev.duration_ms,
         envelopeId: ev.envelope_id, receipt: ev.receipt || null,
+        ...(ev.card && typeof ev.card === 'object' && Array.isArray(ev.card.rows) ? { card: ev.card } : {}), // HITL-INBOX-BAR: a list answer's rows (toolCards.js)
         ...(Number.isFinite(ev.tools_used) ? { toolsUsed: ev.tools_used } : {})
       });
       if (first && withTool.turn) withTool = { ...withTool, turn: { ...withTool.turn, finishedTools: withTool.turn.finishedTools + 1 } };