quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/feedback.js

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

package/lib/quoxon/gallery.js

@@ -0,0 +1,237 @@
+/**
+ * `quox motion`: the product version of the animation lab (~/quoxon-work/intro/lab). Plays every Q motion
+ * with a caption: Orbit & Lock, Portal, Particle collapse, the perpetual status Q in its
+ * four states, the hello, the composer ring and the reveal effects. No server, no account, nothing sent.
+ *
+ * Scenes are pure: galleryScenes() returns { id, title, caption, ms, frame(t) -> ANSI lines }. runGallery()
+ * is the only part that touches a terminal (cursor, timers, signals).
+ */
+import {
+  labSize, orbitCellsAt, portalCellsAt, particleCellsAt, cellsToAnsi, qCells,
+  INTRO_MS, PORTAL_MS, SKY, VIOLET, AMBER,
+} from './qart.js';
+import { qGlyph, glyphAnsi, GLYPH_STATES } from './qglyph.js';
+import { helloCells, helloAnsi, helloGradient, helloMs } from './qhello.js';
+import { CLIPS, MOOD_CLIPS, clipCells, clipCaption } from './qdragonScenes.js';
+import { isLight } from './theme.js';
+
+const RESET = '\x1b[0m';
+const fg = (rgb) => `\x1b[38;2;${rgb.map((v) => Math.max(0, Math.min(255, Math.round(v)))).join(';')}m`;
+const mix = (a, b, t) => a.map((v, i) => v + (b[i] - v) * t);
+const clamp = (x, a = 0, b = 1) => Math.max(a, Math.min(b, x));
+const DIM = [58, 66, 82], MUTED = [120, 132, 150], TXT = [226, 232, 240], TEAL = [6, 182, 212];
+const GREEN = [34, 197, 94], WHITE = [255, 255, 255];
+const paint = (s, rgb, mono) => (mono || !rgb ? s : fg(rgb) + s + RESET);
+
+// ---- composer ring (lab rules.mjs: the website's conic border as one light ring over the two rules) ------
+const PAL = { work: [SKY, VIOLET, TEAL], wait: [AMBER, [0xea, 0x58, 0x0c], [0xb4, 0x53, 0x09]] };
+const STOPS = [[0, 0, 0.85], [0.35, 1, 0.8], [0.6, 0, 0], [0.85, 2, 0.55], [1, 0, 0.85]];
+function ringAt(u, w) {
+  let i = 0; while (i < STOPS.length - 2 && u > STOPS[i + 1][0]) i++;
+  const [p0, c0, a0] = STOPS[i], [p1, c1, a1] = STOPS[i + 1], t = (u - p0) / (p1 - p0 || 1);
+  const col = (c) => mix(PAL.work[c], PAL.wait[c], w);
+  const A = a0 + (a1 - a0) * t;
+  const pm = mix(col(c0).map((v) => v * a0), col(c1).map((v) => v * a1), t);
+  return [A ? pm.map((v) => v / A) : col(c0), A];
+}
+const RING_SEG = [['idle', 0.8], ['work', 3.2], ['settle', 0.4], ['idle', 0.6], ['wait', 2.2], ['settle', 0.4]];
+export const RING_MS = RING_SEG.reduce((a, s) => a + s[1], 0) * 1000;
+/** Ring state at t ms, integrated at 60 Hz from 0 (deterministic). { angle, k, w, mode } */
+export function ringState(t) {
+  let angle = 0, k = 0, w = 0, mode = 'idle', settleFrom = { om: 144 }, om = 0, prev = 'idle';
+  const T = t / 1000, dt = 1 / 60;
+  for (let s = 0; s < T; s += dt) {
+    let acc = 0, si = 0;
+    while (si < RING_SEG.length - 1 && acc + RING_SEG[si][1] <= s) acc += RING_SEG[si++][1];
+    const [m, dur] = RING_SEG[si], p = clamp((s - acc) / dur);
+    if (m === 'settle' && prev !== 'settle') settleFrom = { om };
+    mode = m; prev = m;
+    let wt = 0;
+    if (m === 'work') { om = 144; k = Math.min(1, k + dt / 0.15); wt = 0; }
+    else if (m === 'wait') { om = 144 * 0.3; k = Math.min(1, k + dt / 0.15); wt = 1; }
+    else if (m === 'settle') { om = settleFrom.om * (1 - p) ** 2; k = 1 - p * p * (3 - 2 * p); wt = w; }
+    else { om = 0; k = 0; w = 0; }
+    if (m !== 'idle') w += (wt - w) * Math.min(1, dt / 0.2);
+    angle = (angle + om * dt) % 360;
+  }
+  return { angle, k, w, mode };
+}
+/** The two composer rules at ring state st, W columns wide. */
+export function ringLines(W, st, mono = false) {
+  const line = (top) => {
+    let s = '', last = '';
+    const base = top ? mix(DIM, SKY, 0.75) : DIM;
+    for (let x = 0; x < W; x++) {
+      let rgb = base;
+      if (st.k > 0) {
+        const pos = top ? (x + 0.5) / (2 * W) : (W + (W - 1 - x) + 0.5) / (2 * W);
+        const u = (((pos - st.angle / 360) % 1) + 1) % 1;
+        const [c, a] = ringAt(u, st.w);
+        rgb = mix(base, mix(DIM, c, a), st.k);
+      }
+      if (!mono) { const e = fg(rgb); if (e !== last) { s += e; last = e; } }
+      s += '─';
+    }
+    return s + (mono ? '' : RESET);
+  };
+  const label = { idle: 'idle', work: 'working', wait: 'waiting for approval', settle: 'done' }[st.mode];
+  return [line(true), paint('› ', SKY, mono) + paint('Ask Quox anything…', MUTED, mono), line(false), paint(`ring: ${label}`, MUTED, mono)];
+}
+
+// ---- reveal effects (lab fx.mjs, the reveals that ship in the client) ------------------------------------
+const decodeLine = (text, t, f, mono, perChar = 14) => helloAnsi(helloCells(text, t, { fg: f, mono, perChar }));
+/** fx at t ms: a tool row settles, an answer drops in, an approval card arms, a receipt seals, ProofFlow lights. */
+export function fxLines(t, W, mono = false) {
+  const out = [];
+  const at = (s) => t - s;
+  // tool row (0 ms): spinner while running, then a flash to ✔ and the result decodes in
+  const L = at(0), SETTLE = 900;
+  const head = L < SETTLE ? paint('◐◓◑◒'[Math.floor(t / 125) % 4], SKY, mono) : paint('✔', L < SETTLE + 120 ? WHITE : GREEN, mono);
+  out.push(head + decodeLine(' SEO │ summary │ ', L, (i, ch) => (ch === '│' ? DIM : i < 5 ? TEAL : MUTED), mono) + (L < SETTLE ? paint('…', MUTED, mono) : decodeLine('30 crawls · 2.4s', L - SETTLE, TXT, mono)));
+  out.push('');
+  // answer (1400 ms): lines drop in one by one, first chars decode, afterglow behind
+  const ans = ['Crawls finished with no blocking errors this week.', 'Impressions are up 8 percent; 3 pages moved into the top ten.'];
+  ans.forEach((ln, k) => { const s = at(1400 + k * 110); out.push(s < -140 ? '' : '  ' + decodeLine(ln.slice(0, W - 4), s, TXT, mono, 6)); });
+  out.push('');
+  // approval card (2600 ms): amber rule draws in, title decodes, 300 ms arming, then ready
+  const A = at(2600), iw = Math.min(W - 4, 50), draw = clamp(A / 250), n = Math.round(draw * (iw + 2));
+  const rule = (a, b) => (A <= 0 ? '' : paint([...(a + '─'.repeat(iw) + b)].slice(0, n).join(''), AMBER, mono));
+  out.push(rule('╭', '╮'));
+  const armed = clamp((A - 400) / 300), ready = A >= 700;
+  out.push(A > 100 ? paint('│ ', AMBER, mono) + decodeLine('Send the weekly SEO report?', A - 100, TXT, mono) : '');
+  out.push(A > 100 ? paint('│ ', AMBER, mono) + paint('[ Approve ]', ready ? AMBER : DIM, mono) + '  ' + paint('[ Deny ]', ready ? MUTED : DIM, mono) + '  ' + paint(ready ? 'ready ' : 'arming', ready ? GREEN : AMBER, mono) + ' ' + paint([...'▰▰▰▰▰▰'].map((c, i) => (ready || i < Math.floor(armed * 6) ? '▰' : '▱')).join(''), ready ? GREEN : AMBER, mono) : '');
+  out.push(rule('╰', '╯'));
+  out.push('');
+  // receipt seal (3800 ms): text resolves, the seal settles with a one-frame glint
+  const R = at(3800), seq = ['·', '○', '◌', '◎'];
+  const seal = R < 0 ? ' ' : R < 400 ? paint(seq[Math.floor(R / 70) % 4], mix(DIM, TEAL, clamp(R / 400)), mono) : paint('◉', R < 460 ? WHITE : TEAL, mono);
+  out.push(R < -140 ? '' : seal + decodeLine(' WARD │ witnessed · seq 393', R, (i, ch) => (ch === '│' ? DIM : i < 5 ? TEAL : TXT), mono));
+  // ProofFlow (4600 ms): AEE > AOCL > TOOL > WARD light up in sequence; completed ones stay still
+  const P = at(4600);
+  out.push(P < 0 ? '' : paint('proof  ', MUTED, mono) + ['AEE', 'AOCL', 'TOOL', 'WARD'].map((nm, i) => { const d = P - i * 120; return paint(nm, d < 0 ? DIM : d < 100 ? WHITE : SKY, mono); }).join(paint(' ─▸ ', mix(DIM, SKY, 0.8), mono)));
+  out.push('');
+  // closing line (5400 ms)
+  const C = at(5400);
+  out.push(C < -140 ? '' : decodeLine('Thought for 12s · 1.4k tokens · $0.02', C, (i, ch) => (ch === '·' ? DIM : MUTED), mono));
+  return out;
+}
+export const FX_MS = 6600;
+
+// ---- scenes ------------------------------------------------------------------------------------------------
+const STATE_WORD = { resting: 'Ready', working: 'Thinking…', waiting: 'Waiting for approval', failing: 'Failed' };
+const STATE_TAG = { resting: 'resting: slow breathing glow', working: 'working: the gradient flows through it', waiting: 'waiting: amber pulse', failing: 'failing: a red flash, then steady red' };
+const STATE_RGB = { resting: SKY, working: SKY, waiting: AMBER, failing: [239, 68, 68] };
+export const PERP_MS = 2600;
+
+/**
+ * The gallery's scenes for a terminal. narrow forces the 40-column layout (the compact particle Q).
+ * Each scene: { id, title, caption, ms, frame(t, { mono }) -> string[] }.
+ */
+export function galleryScenes({ cols = 100, rows = 30, narrow = false, theme = isLight() ? 'light' : 'dark' } = {}) {
+  const W = narrow ? 40 : cols;
+  // the dragon (qdragonScenes.js): eyes as quadrant blocks with a background colour, the lab's light palette on light terminals
+  const fit = (str) => (str.length > W ? str.slice(0, W - 1) + '…' : str);
+  const dragon = (name, t, o) => [...art(clipCells(name, t, { cols: W, theme, mono: o.mono })), '', paint(fit(clipCaption(name, t)), MUTED, o.mono)];
+  const MOOD_SPAN = MOOD_CLIPS.map((m) => CLIPS[m].dur + 400);
+  const size = narrow ? 'small' : labSize(W, rows);
+  const big = size === 'small' ? 'small' : size;
+  const art = (cells) => cellsToAnsi(cells);
+  const hello = "Hi, I'm Quox.";
+  return [
+    { id: 'orbit', title: 'Orbit & Lock', caption: size === 'small' ? 'the compact Q: particles circle, then collapse into the mark (the intro under 60 columns)' : 'particles swirl on a ring with trailing drag, then lock into the Q in an angular wave; horns grow out, the tail sweeps in last (the intro)', ms: INTRO_MS + 300,
+      frame: (t, o) => art(orbitCellsAt(big, t, { color: !o.mono })) },
+    { id: 'portal', title: 'Portal', caption: 'a ring spins edge-on and opens; the Q fills in from the opening, the tail sweeps in last', ms: PORTAL_MS + 600,
+      frame: (t, o) => art(portalCellsAt(big, t, { color: !o.mono })) },
+    { id: 'particle', title: 'Particle collapse', caption: 'density rises on a circle, then collapses into the compact Q', ms: 1100 + 500,
+      frame: (t, o) => art(particleCellsAt('small', t, { color: !o.mono })) },
+    { id: 'hello', title: 'Hello', caption: 'the Q locks, then says hello: the line decodes in from katakana with a short afterglow', ms: INTRO_MS + helloMs(hello) + 600,
+      frame: (t, o) => {
+        const q = art(t < INTRO_MS ? orbitCellsAt(big, t, { color: !o.mono }) : qCells(big, { color: !o.mono }));
+        const line = helloAnsi(helloCells(hello, t - INTRO_MS, { fg: helloGradient(hello), mono: o.mono }));
+        if (W < 60) return [...q, '', line];
+        const mid = Math.floor(q.length / 2);
+        return q.map((l, i) => (i === mid ? l + '  ' + line : l));
+      } },
+    { id: 'perpetual', title: 'The perpetual Q', caption: 'the status glyph carries state in colour alone, one fixed shape: resting breathes, working flows sky to violet to teal, waiting pulses amber, failing flashes red', ms: PERP_MS * 4,
+      frame: (t, o) => {
+        const i = Math.min(3, Math.floor(t / PERP_MS)), st = GLYPH_STATES[i], tt = t - i * PERP_MS;
+        return GLYPH_STATES.map((s, k) => {
+          const g = qGlyph(s, k === i ? tt : 0, { mono: o.mono, quiet: k !== i, since: 0 });
+          const word = paint(STATE_WORD[s], k === i ? STATE_RGB[s] : DIM, o.mono);
+          const tag = W >= 70 ? '   ' + paint(STATE_TAG[s], k === i ? MUTED : DIM, o.mono) : '';
+          return (k === i ? '› ' : '  ') + glyphAnsi(g) + ' ' + word + tag;
+        }).concat(['', '  ' + paint(`now: ${st}`, MUTED, o.mono)]);
+      } },
+    { id: 'ring', title: 'The composer ring', caption: 'the two composer rules become one light ring while Quox works; amber while it waits for you', ms: RING_MS,
+      frame: (t, o) => ringLines(Math.min(W - 2, 72), ringState(t), o.mono) },
+    { id: 'fx', title: 'Reveal effects', caption: 'tool row, answer drop-in, approval arming, receipt seal, ProofFlow, closing line', ms: FX_MS,
+      frame: (t, o) => fxLines(t, Math.min(W - 2, 78), o.mono) },
+    { id: 'dragon', title: CLIPS.pick.title, caption: CLIPS.pick.caption, ms: CLIPS.pick.dur, frame: (t, o) => dragon('pick', t, o) },
+    { id: 'dragon-fire', title: CLIPS.fire.title, caption: CLIPS.fire.caption, ms: CLIPS.fire.dur, frame: (t, o) => dragon('fire', t, o) },
+    { id: 'dragon-moods', title: 'Dragon moods', caption: 'at the cinematic motion level the dragon reacts: wide eyes and an amber glint while it waits for you, a wink when done, a puff of smoke on failure, and a greeting on launch',
+      ms: MOOD_SPAN.reduce((a, b) => a + b, 0),
+      frame: (t, o) => {
+        let i = 0, s0 = 0;
+        while (i < MOOD_CLIPS.length - 1 && t >= s0 + MOOD_SPAN[i]) s0 += MOOD_SPAN[i++];
+        const m = MOOD_CLIPS[i];
+        return [...art(clipCells(m, t - s0, { cols: Math.min(W, 64), theme, mono: o.mono })), '', paint(fit(`${m}: ${CLIPS[m].caption.split(':')[1].replace(/\s*\(.*\)$/, '').trim()}`), MUTED, o.mono)];
+      } },
+  ];
+}
+export const SCENE_IDS = ['orbit', 'portal', 'particle', 'hello', 'perpetual', 'ring', 'fx', 'dragon', 'dragon-fire', 'dragon-moods'];
+
+// ---- runner (the only impure part) ---------------------------------------------------------------------------
+const visible = (s) => s.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');  // eslint-disable-line no-control-regex
+const width = (s) => [...visible(s)].length;
+
+/** One full screen for a scene frame: title + caption on top, the frame centred under it. */
+export function screenFor(scene, t, { cols, mono, index, total }) {
+  const lines = scene.frame(t, { mono });
+  const head = paint(`[${index + 1}/${total}] ${scene.title}`, SKY, mono);
+  const cap = wrap(scene.caption, Math.max(20, cols - 2)).map((l) => paint(l, MUTED, mono));
+  const w = Math.max(0, ...lines.map(width));
+  const left = ' '.repeat(Math.max(0, Math.floor((cols - w) / 2)));
+  return [head, ...cap, '', ...lines.map((l) => left + l)];
+}
+function wrap(s, n) { const o = []; let l = ''; for (const w of s.split(' ')) { if ((l + ' ' + w).trim().length > n) { o.push(l); l = w; } else l = (l + ' ' + w).trim(); } if (l) o.push(l); return o; }
+
+export async function runGallery({ out = process.stdout, env = process.env, only = [], narrow = false, slow = false, mono: monoFlag = false } = {}) {
+  const cols = narrow ? 40 : Math.max(40, out.columns || 100), rows = out.rows || 30;
+  const mono = monoFlag || Boolean(env.NO_COLOR) || env.TERM === 'dumb';
+  const still = env.QUOX_REDUCED_MOTION === '1' || !out.isTTY;
+  const all = galleryScenes({ cols, rows, narrow });
+  const bad = only.filter((n) => !SCENE_IDS.includes(n));
+  if (bad.length) throw new Error(`unknown motion: ${bad.join(', ')} (one of ${SCENE_IDS.join(', ')})`);
+  const scenes = only.length ? all.filter((s) => only.includes(s.id)) : all;
+  if (still) {
+    // Reduced motion or piped: every scene's settled frame, printed once.
+    scenes.forEach((s, i) => out.write(screenFor(s, s.ms, { cols, mono, index: i, total: scenes.length }).join('\n') + '\n\n'));
+    return;
+  }
+  const SLOW = slow ? 3 : 1;
+  let restored = false;
+  const restore = () => { if (!restored) { restored = true; out.write(RESET + '\x1b[?25h\n'); } };
+  const onSig = () => { restore(); process.exit(130); };
+  process.once('SIGINT', onSig); process.once('SIGTERM', onSig);
+  out.write('\x1b[?25l');
+  try {
+    for (let i = 0; i < scenes.length; i++) {
+      const s = scenes[i];
+      out.write('\x1b[2J\x1b[H');
+      const t0 = performance.now();
+      for (let n = 0; ; n++) {
+        const t = (performance.now() - t0) / SLOW;
+        const done = t >= s.ms;
+        const lines = screenFor(s, done ? s.ms : t, { cols, mono, index: i, total: scenes.length });
+        out.write('\x1b[?2026h\x1b[H' + lines.map((l) => l + '\x1b[K').join('\n') + '\x1b[J\x1b[?2026l');
+        if (done) break;
+        const wait = t0 + (n + 1) * (1000 / 30) - performance.now();
+        if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+      }
+      await new Promise((r) => setTimeout(r, 700 * SLOW));
+    }
+  } finally {
+    process.off('SIGINT', onSig); process.off('SIGTERM', onSig);
+    restore();
+  }
+}

package/lib/quoxon/handoffOffer.js

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

package/lib/quoxon/hatSwitch.js

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

package/lib/quoxon/headless.js

@@ -0,0 +1,161 @@
+/**
+ * QUOXON-LATENCY: the headless half of the conversation client (`quox --print`), with no
+ * React / Ink / App import. bin/quox.js routes --print here directly, so a headless turn
+ * no longer pays ~2 s of renderer load before its request is sent. main.js re-exports
+ * every name below, so the interactive client and its importers are unchanged.
+ */
+import { parseModelArg } from './model.js';
+import { loadRules, rulesContext } from './rules.js';
+
+const FLAGS = new Set(['-p', '--profile', '--verbose', '--demo', '--print', '--output', '--conversation', '--turn-id', '--timeout', '--color', '--no-clear', '-n', '--name', '--service-key', '--demo-onboarding', '--autoplay', '--autoplay-exit', '--provider', '--model', '--agent', '--prompt-profile', '--resume', '-h', '--help', '--']);
+const isFlag = (a) => FLAGS.has(a) || /^--(profile|verbose|print|output|conversation|turn-id|timeout|provider|model|agent|prompt-profile|resume)=/.test(a);
+
+export function parseArgs(argv) {
+  const o = { profile: null, verbose: 'on', demo: false, help: false, print: false, prompt: null, output: 'text', conversation: null, turnId: null, timeout: 0, color: false, noClear: false, name: null, serviceKey: false, demoOnboarding: false, autoplay: false, autoplayExit: null, provider: null, agent: null, resume: null, verboseSet: false, errors: [] };
+  let rawProvider = null, rawModel = null;
+  const value = (flag, i) => { const v = argv[i + 1]; if (v === undefined || (v.startsWith('-') && isFlag(v))) { o.errors.push(`${flag} needs a value`); return undefined; } return v; };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { const rest = argv.slice(i + 1).join(' '); if (rest) o.prompt = rest; break; }
+    if (a === '-p' || a === '--profile') { const v = value(a, i); if (v !== undefined) { o.profile = v; i++; } }
+    else if (a.startsWith('--profile=')) o.profile = a.slice(10);
+    else if (a === '--verbose') { o.verboseSet = true; const v = argv[i + 1]; if (['off', 'on', 'full'].includes(v)) { o.verbose = v; i++; } else o.verbose = 'on'; } // no value means on
+    else if (a.startsWith('--verbose=')) { o.verboseSet = true; o.verbose = a.slice(10); }
+    else if (a === '--resume') { const v = argv[i + 1]; if (v !== undefined && !v.startsWith('-')) { o.resume = v; i++; } else o.resume = true; } // alone: the picker
+    else if (a.startsWith('--resume=')) o.resume = a.slice(9) || true;
+    else if (a === '-n' || a === '--name') { const v = value(a, i); if (v !== undefined) { o.name = v; i++; } }
+    else if (a.startsWith('--name=')) o.name = a.slice(7);
+    else if (a === '--demo') o.demo = true;
+    else if (a === '--autoplay') o.autoplay = true;
+    else if (a === '--autoplay-exit') { o.autoplay = true; const v = argv[i + 1]; if (v !== undefined && /^\d+(\.\d+)?$/.test(v)) { o.autoplayExit = Number(v); i++; } else o.autoplayExit = 5; } // seconds to hold the final frame
+    else if (a === '--demo-onboarding') o.demoOnboarding = true;
+    else if (a === '--print') { o.print = true; const n = argv[i + 1]; if (n !== undefined && !isFlag(n)) { o.prompt = n; i++; } }
+    else if (a.startsWith('--print=')) { o.print = true; o.prompt = a.slice(8); }
+    else if (a === '--output') { const v = value(a, i); if (v !== undefined) { o.output = v; i++; } }
+    else if (a.startsWith('--output=')) o.output = a.slice(9);
+    else if (a === '--conversation') { const v = value(a, i); if (v !== undefined) { o.conversation = v; i++; } }
+    else if (a === '--agent') { const v = value(a, i); if (v !== undefined) { o.agent = v; i++; } }
+    else if (a.startsWith('--agent=')) o.agent = a.slice(8) || null;
+    else if (a === '--turn-id') { const v = value(a, i); if (v !== undefined) { o.turnId = v; i++; } }
+    else if (a === '--timeout') { const v = value(a, i); if (v !== undefined) { o.timeout = Number(v) || 0; i++; } }
+    else if (a === '--color') o.color = true;
+    else if (a === '--no-clear') o.noClear = true;
+    else if (a === '--service-key') o.serviceKey = true;
+    else if (a === '--provider' || a === '--model') { const v = value(a, i); if (v !== undefined) { if (a === '--provider') rawProvider = v; else rawModel = v; i++; } }
+    else if (a.startsWith('--provider=')) rawProvider = a.slice(11);
+    else if (a.startsWith('--model=')) rawModel = a.slice(8);
+    else if (a === '--prompt-profile') { const v = value(a, i); if (v !== undefined) { o.promptProfile = v; i++; } }
+    else if (a.startsWith('--prompt-profile=')) o.promptProfile = a.slice(17);
+    else if (a === '-h' || a === '--help') o.help = true;
+    else if (!a.startsWith('-') && o.prompt === null && argv.includes('--print')) o.prompt = a; // `--print` given earlier or later; this is its prompt
+    else o.errors.push(a.startsWith('-') ? `unknown option ${a}` : `unexpected argument ${a}`);
+  }
+  if (rawModel && !rawProvider) o.errors.push('--model needs --provider (e.g. --provider openai --model gpt-5.4)');
+  else if (rawProvider) {
+    const m = parseModelArg(rawModel ? `${rawProvider} ${rawModel}` : rawProvider);
+    if (!m.ok) o.errors.push(m.error); else o.provider = m.choice || 'auto'; // 'auto' = this run ignores the saved /model choice
+  }
+  if (o.promptProfile !== undefined && !['compact', 'full'].includes(o.promptProfile)) { o.errors.push(`invalid --prompt-profile "${o.promptProfile}" (use compact or full)`); delete o.promptProfile; }
+  if (!['off', 'on', 'full'].includes(o.verbose)) o.verbose = 'on';
+  if (!['text', 'json'].includes(o.output)) { o.errors.push(`invalid --output "${o.output}" (use text or json)`); o.output = 'text'; }
+  return o;
+}
+
+export const USAGE = 'quox [-p|--profile <name>] [-n|--name <session name>] [--conversation <id>] [--resume [id|name]] [--verbose off|on|full] [--demo [--autoplay [--autoplay-exit [s]]]] [--no-clear] [--service-key] [--provider openai|anthropic|ollama|openrouter|huggingface|groq|together|lmstudio|vllm|custom|auto [--model <id>]]   (quoxon is an alias; the old menu is `quox tui`)\n  quox --conversation <id>   resume that conversation interactively (its saved turns load into the window)\n  quox --resume [id|name]   pick up a recent conversation; alone it opens a picker\n  quox --print "<prompt>" [--output text|json] [--conversation <id>] [--turn-id <id>] [--timeout <s>] [--agent <id>] [--provider <p> [--model <id>]] [--prompt-profile compact|full]   (prompt from stdin if absent or -; use -- before a prompt that starts with -)\n  exit: 0 completed, 1 other, 2 held for approval, 3 interrupted or abandoned, 4 not signed in, 5 ended without server confirmation\n  --provider asks the server for that provider this run (default: your /model choice for this profile, else auto); turn.started from the server says what ran\n  --service-key lets chat use an ambient QUOX_SERVICE_KEY when the profile has no login (never used silently)\n  --demo plays a simulated journey on its own (no server, nothing real runs)\n  --autoplay (with --demo, or QUOX_DEMO_AUTOPLAY=1) plays the whole journey with no input on a fixed script; --autoplay-exit [s] quits s seconds (default 5) after the last frame\n  --demo-onboarding walks Getting started with a dry-run install (nothing is downloaded, built or started)';
+
+/** Default profile: a resident (agent) login cannot chat, so use the single logged-in human profile. */
+export function pickProfile(explicit, cfgMod, env = process.env) {
+  if (explicit) return { name: explicit, note: null };
+  if (env.QUOX_PROFILE) return { name: env.QUOX_PROFILE, note: null }; // an explicit one-shot choice (same as -p), never "the default profile"
+
+  const probe = cfgMod.loadConfig();
+  const active = probe.getActiveProfileName?.();
+  const residents = new Set((probe.listResidentProfiles?.() || []).map(r => r.name));
+  return choosePick(active, residents, probe.listProfiles?.() || []);
+}
+export function choosePick(active, residents, profiles) {
+  if (!residents.has(active)) return { name: undefined, note: null };
+  const humans = profiles.filter(p => !residents.has(p.name) && p.loggedIn);
+  if (humans.length === 1) return { name: humans[0].name, note: null }; // the status line shows the profile; no transcript noise
+  const names = profiles.filter(p => !residents.has(p.name) && p.loggedIn).map(p => p.name);
+  const hint = names.length ? ` Pass -p <your profile>. Human profiles found: ${names.join(', ')} (start with: quox -p ${names[0]}).` : ' Pass -p <your profile>.';
+  return { name: undefined, note: `The default profile "${active}" is an agent login, so this chat runs as the agent, not as a person.${hint}` };
+}
+
+/**
+ * Chat identity gate. A named profile that does not exist is an error (never created on the fly), and an
+ * ambient QUOX_SERVICE_KEY is only a credential when the user asked for it (--service-key or FORCE).
+ * -> null when chat may proceed, else { message }.
+ */
+export function chatCredentialProblem({ profileArg, profiles, hasStoredLogin, profileName, env = process.env, serviceKeyFlag = false }) {
+  if (profileArg && !profiles.some(p => p.name === profileArg)) return { message: `profile ${profileArg} does not exist; create it with: quox login -p ${profileArg}` };
+  if (hasStoredLogin) return null;
+  if ((serviceKeyFlag || env.QUOX_FORCE_SERVICE_KEY) && env.QUOX_SERVICE_KEY) return null;
+  return { message: `Not signed in for chat on profile ${profileName}. Run: quox login -p ${profileName}${env.QUOX_SERVICE_KEY ? ' (an ambient QUOX_SERVICE_KEY is ignored unless you pass --service-key)' : ''}` };
+}
+
+/**
+ * Is this a machine with no Quox server configured at all? Then bare `quox` is Getting started, and --print
+ * says how to get there. Reads profiles only (no network).
+ */
+export async function noServerConfigured(opts, cfgMod, env = process.env) {
+  const { needsGettingStarted } = await import('./onboarding/detect.js');
+  const { loadJourney } = await import('./onboarding/journey.js');
+  const probe = cfgMod.loadConfig();
+  return needsGettingStarted({ profiles: probe.listProfiles?.() || [], residents: probe.listResidentProfiles?.() || [], profileArg: opts.profile, env, serviceKeyFlag: opts.serviceKey, journey: loadJourney() });
+}
+
+/** --print without a usable login: today's message, plus the way in when no server exists yet. */
+export function printAuthMessage(problem, gettingStarted, hint) {
+  return `quox: ${problem.message}\n${gettingStarted ? `quox: ${hint}\n` : ''}`;
+}
+
+export async function mainPrint(opts) {
+  const { runPrint, resolvePrompt, EXIT } = await import('./print.js');
+  const out = (s) => process.stdout.write(s);
+  const err = (s) => process.stderr.write(s);
+  const prompt = await resolvePrompt(opts.prompt, process.stdin);
+  let api;
+  if (opts.demo) api = (await import('./demo.js')).createDemoApi({ speed: 20 });
+  else {
+    const cfgMod = await import('../core/config.js');
+    const { createAuth } = await import('../core/auth.js');
+    const { createClient } = await import('../core/client.js');
+    const { createApi } = await import('./api.js');
+    const probe = cfgMod.loadConfig();
+    const profiles = probe.listProfiles?.() || [];
+    const missing = opts.profile && !profiles.some(p => p.name === opts.profile);
+    const pick = pickProfile(opts.profile, cfgMod);
+    if (pick.note) err(pick.note + '\n');
+    const config = missing ? probe : cfgMod.loadConfig(pick.name);
+    const auth = createAuth(config);
+    const pname = missing ? opts.profile : (config.getActiveProfileName?.() || 'default');
+    const problem = chatCredentialProblem({ profileArg: opts.profile, profiles, hasStoredLogin: missing ? false : Boolean(config.getAuth?.()?.access_token), profileName: pname, serviceKeyFlag: opts.serviceKey });
+    if (problem) {
+      const { NO_SERVER_PRINT } = await import('./onboarding/copy.js');
+      err(printAuthMessage(problem, await noServerConfigured(opts, cfgMod), NO_SERVER_PRINT));
+      process.exitCode = EXIT.auth; return;
+    }
+    const { createWindowClient } = await import('./windowOrg.js');
+    api = createApi({ ...createWindowClient({ config, auth, createClient }), config }); // #1034: /org stays in this process
+    if (opts.conversation && api.conversationExists) {
+      const c = await api.conversationExists(opts.conversation);
+      if (c.exists === false) { err(`quox: conversation not found: ${opts.conversation}\n`); process.exitCode = EXIT.error; return; }
+      if (c.exists === null) err(`quox: could not verify conversation ${opts.conversation} (${c.reason}); continuing\n`);
+    }
+  }
+  const rules = opts.demo ? null : loadRules();
+  for (const s of rules?.skipped || []) err(`quox: ignoring ${s.path}: ${s.reason}\n`);
+  const choice = opts.provider === 'auto' ? null : opts.provider || api.modelChoice?.() || null;
+  process.exitCode = await runPrint({ api, choice, agent: opts.agent || undefined, promptProfile: opts.promptProfile, context: rulesContext(rules), prompt, output: opts.output, conversation: opts.conversation, turnId: opts.turnId || undefined, timeoutS: opts.timeout, color: opts.color, profile: opts.profile || null, out, err });
+}
+
+/** bin/quox.js entry for --print: the same arg checks main() makes, then the headless turn. */
+export async function runHeadless(argv) {
+  const opts = parseArgs(argv);
+  if (!opts.print) return false; // not a headless run after all (e.g. `-- --print` is a prompt): main() owns it
+  if (opts.help) { console.log(USAGE); return true; }
+  if (opts.errors.length) { process.stderr.write(`quox: ${opts.errors.join('; ')}\n${USAGE}\n`); process.exitCode = 1; return true; }
+  await mainPrint(opts);
+  return true;
+}

package/lib/quoxon/hostUrls.js

@@ -0,0 +1,41 @@
+/**
+ * Z2H-R3: which address to PRINT for the dashboard and for the host installer. Over SSH to a fresh
+ * install the profile is https://localhost:3000, which only works on the Quox box, so a printed
+ * localhost is wrong for anyone reading it elsewhere. Order: the server's app URL (app_base_url),
+ * else the address this CLI reached the server on, else the address the install finale showed,
+ * else this machine's detected LAN address. Loopback is the last resort, never the first answer.
+ */
+import { networkInterfaces } from 'node:os';
+
+export const isLoopbackUrl = (u) => {
+  try { return /^(localhost|127\.\d+\.\d+\.\d+|\[::1\]|::1|0\.0\.0\.0)$/i.test(new URL(u).hostname); } catch { return true; }
+};
+const ok = (u) => typeof u === 'string' && /^https?:\/\/[^\s/]+/.test(u) && !isLoopbackUrl(u);
+const origin = (u) => new URL(u).origin;
+
+/** First non-internal IPv4 address (private ranges preferred), or null. */
+export function detectLanIp(ifaces = networkInterfaces()) {
+  const all = Object.entries(ifaces || {}).filter(([n]) => !/^(docker|br-|veth|virbr|cni|flannel|cali|tun|tap)/i.test(n)).flatMap(([, v]) => v || [])
+    .filter(a => a && a.family === 'IPv4' && !a.internal && a.address);
+  const priv = all.find(a => /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(a.address));
+  return (priv || all[0])?.address || null;
+}
+
+/** Dashboard base: { url, source } . source: server | profile | install | lan | local. */
+export function resolveDashboardBase({ serverApp, profileUrl, journeyUrl, lanIp } = {}) {
+  if (ok(serverApp)) return { url: origin(serverApp), source: 'server' };
+  if (ok(profileUrl)) return { url: origin(profileUrl), source: 'profile' };
+  if (ok(journeyUrl)) return { url: origin(journeyUrl), source: 'install' };
+  if (lanIp) return { url: `https://${lanIp}:3000`, source: 'lan' };
+  return { url: profileUrl || 'https://localhost:3000', source: 'local' };
+}
+
+/** Base that serves GET /install (the collector, :9848): { url, source }. */
+export function resolveCollectorBase({ collectorUrl, serverApp, journeyUrl, lanIp } = {}) {
+  if (ok(collectorUrl)) return { url: origin(collectorUrl), source: 'profile' };
+  for (const [u, source] of [[serverApp, 'server'], [journeyUrl, 'install']]) {
+    if (ok(u)) return { url: `http://${new URL(u).hostname}:9848`, source };
+  }
+  if (lanIp) return { url: `http://${lanIp}:9848`, source: 'lan' };
+  return { url: collectorUrl || null, source: 'local' };
+}