quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/app.js

@@ -0,0 +1,1262 @@
+/**
+ * QUOXON app: composer + live turn. State lives in refs updated synchronously
+ * (so a stdin chunk carrying several keys applies in order) and mirrored into
+ * React state for rendering.
+ */
+import React from 'react';
+import { Box, Static, Text, measureElement, useApp, useStdin, useStdout } from 'ink';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import { tmpdir, hostname as osHostname } from 'node:os';
+import { join } from 'node:path';
+import { bufferReducer, initialBuffer, sanitizeForSend } from './textBuffer.js';
+import { parseChunk, initialKeyState, flushDangling, hasDangling, PASTE_ON, PASTE_OFF, PASTE_DANGLING_MS } from './keys.js';
+import { reduce, initialState, approvalKeyAllowed } from './events.js';
+import { turnTokens } from './indicator.js';
+import {
+  Composer, RingComposer, Pending, ApprovalCard, StatusLine, NotifyBar, Working, HistoryItem, liveRows, Intro, Roster, INTRO_FRAMES, introAnimates, describeActivity, clampCols, clip, COLORS, revealTimingFor
+} from './render.js';
+import { c, mono } from './theme.js';
+import { findEntry, helpModel } from './commands.js';
+import { osc52, pickCopy } from './copy.js';
+import { detectSlotAgent } from './context.js';
+import { rulesContext, rulesLabel, rulesLines } from './rules.js';
+import { findSkill, skillRows, skillDetail, skillPrompt } from './skills.js';
+import { rosterView, peekLines, selectRows, backgroundAlerts, isExpired } from './roster.js';
+import { runObjectCommand } from './objects/index.js';
+const OBJECT_CMDS = new Set(['/skills', '/agents', '/workflow', '/crystal', '/memory', '/rules', '/proof', '/reconcile']);
+import { intentHint } from './intent.js';
+import { observerLines } from './observers.js';
+import { packageVersion } from './welcome.js';
+import { INVITE, cleanName, loadNames, saveName, matchAgent } from './session.js';
+import { termRows } from './term.js';
+import { createConnectController, connectionLines, connectOfferFor, looksLikeKey, keyWarning, providerFor, parseOllamaArg, connectOllamaFlow, ollamaModelRows, connectCompatFlow, compatModelRows } from './connect.js';
+import { ConnectCard } from './connectCard.js';
+import { CHOICES, modelLines, selectModel, selectOllamaModel, selectCompatModel, modelLabel, fallbackNote, streamFields, normChoice } from './model.js';
+import { overviewLines } from '../core/sessionsOverview.js';
+import { capabilityLines, offerFor, findCapability } from './capabilities.js';
+import { EyeLive, playEye, eyeActive } from './qmotion.js';
+import { createSound } from './sound/index.js';
+import { createPalette } from './slash/paletteController.js';
+import { capabilityMap } from './slash/palette.js';
+import { ListView } from './slash/listView.js';
+import { createLedger, costModel } from './slash/ledger.js';
+import { statusModel, contextModel, doctorModel, chatChecks } from './slash/panels.js';
+import { createPicker } from './slash/picker.js';
+import { resumeRows, pickerRow, matchConversation, turnsToHistory } from './slash/resume.js';
+import { settingsList, applySettings, configRows, cycle } from './slash/settings.js';
+import { startBuildWatch } from './slash/restart.js';
+import { compactResult, compactError, contextFacts, compactShowLines } from './slash/compact.js';
+import { intentPanel } from './intent.js';
+import { launchEgg } from './egg.js';
+import { INTRO_MS, EYE_MS } from './qart.js';
+import { Clock, FRAME_MS, SECOND_MS, motionAllowed, createFrames } from './motion/clock.js';
+import { FrameContext, useFrame } from './motion/frame.js';
+import { ringMode, ringAnimating } from './motion/ring.js';
+import { TIMING, revealSpan } from './motion/reveal.js';
+
+const h = React.createElement;
+const PASTE_GUARD_MS = 40;
+const MAX_ROSTER = 4;
+const ESC_ESC_MS = 500;
+const INTERRUPT_FALLBACK_MS = 8000;
+const INTRO_FRAME_MS = 50; // intro frame period on the shared clock (the plan's length is INTRO_MS, + the eye when the egg fires)
+const HELD_WINDOW_MS = 1000; // a key seen this close before a card appears is treated as still held
+const APPROVE_WORD = 'approve';
+const CARD_GONE_MS = 400;
+const CARD_EDIT_KEYS = ['backspace', 'delete', 'delete-word', 'kill-line', 'left', 'right', 'home', 'end', 'word-left', 'word-right', 'undo', 'redo'];
+
+
+const STEER_OFF_NOTE = "This model can't take steering mid-turn; queued for next turn.";
+const newTurnId = () => `QXN_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+function openEditor(text) {
+  const dir = mkdtempSync(join(tmpdir(), 'quoxon-'));
+  const file = join(dir, 'prompt.md');
+  writeFileSync(file, text, 'utf8');
+  const editor = process.env.VISUAL || process.env.EDITOR || 'vi';
+  const r = spawnSync(editor, [file], { stdio: 'inherit' });
+  let out = null;
+  if (!r.error) out = readFileSync(file, 'utf8').replace(/\n+$/, '');
+  try { unlinkSync(file); } catch { /* best-effort */ }
+  return out;
+}
+
+export const friendlyError = (e, profile) =>
+  (e?.status === 401 || /valid jwt|service key|unauthor/i.test(e?.message || ''))
+    ? `Not signed in for chat on profile ${profile}. Run: quox login -p ${profile}` : (e?.message || String(e));
+
+const byId = (id) => CHOICES.find(x => x.id === id) || null;
+
+export function App({ slotAgent, notifyMs = 4000, resultPollMs = 3000, resultTimeoutMs = 120000, rosterMs = 15000, api, profile = 'default', org = null, version = '0.1.0', cwd = '', columns, demoLabel = null, verbose = 'on', mode = 'ask', editor = openEditor, introNote = null, animateIntro, earlyInput = null, startup = null, blocked = null, autoplay = null, rules = null, welcome = false, sessionName = null, invite = false, namesPath, transcript = null, modelChoice = null, resumeConversation = null, resume = null, onRestart = null, restartCheck = null, startSha = null, buildWatch = startBuildWatch, env = process.env, motion, motionStats = null }) {
+  const { exit } = useApp();
+  const { stdin, setRawMode, isRawModeSupported } = useStdin();
+  const { stdout } = useStdout();
+  const [cols, setCols] = React.useState(clampCols(columns ?? ((stdout?.columns || 80) - 1)));
+  const [, bump] = React.useState(0);
+  const [epoch, setEpoch] = React.useState(0);
+
+  const introItem = { id: 'intro', kind: 'intro', text: `${version} · ${profile} · ${cwd}`, cols: clampCols(columns ?? ((process.stdout.columns || 80) - 1)) };
+  const introHistory = () => [introItem,
+    ...(welcome ? [{ id: 'welcome', kind: 'welcome', version: packageVersion() }] : []),
+    ...(demoLabel ? [{ id: 'demo', kind: 'note', text: demoLabel, tone: 'warn' }] : []),
+    ...(introNote ? [{ id: 'introNote', kind: 'note', text: introNote, tone: 'warn' }] : []),
+    ...(invite ? [{ id: 'invite', kind: 'note', text: INVITE }] : [])];
+  // The animated intro lives in the live region (no flicker, nothing printed twice) and moves into
+  // <Static> history once settled. Any keypress skips it; the composer is usable throughout.
+  const introAnimating = animateIntro ?? introAnimates(stdout?.isTTY);
+  // Motion (decorative animation) is decided once: a real terminal and no QUOX_REDUCED_MOTION / LITE. Colour
+  // is a separate setting (NO_COLOR); one never implies the other.
+  const motionOn = motion ?? motionAllowed(stdout?.isTTY);
+  const introStart = React.useRef(Date.now());
+  // Launch egg: rarely the Dragon's Eye after Orbit & Lock (egg.js decides once per launch; never reduced motion).
+  const eye = React.useMemo(() => (introAnimating && animateIntro === undefined ? launchEgg({ tty: Boolean(stdout?.isTTY) }) : false), []);
+  const introMs = INTRO_MS + (eye ? EYE_MS + 400 : 0);
+  const introDone = React.useRef(!introAnimating);
+  const finishIntro = () => {
+    if (introDone.current) return;
+    introDone.current = true;
+    const intro = introHistory();
+    S.current = { ...S.current, history: [...intro, ...S.current.history] };
+    committedRef.current = intro.length; // the intro itself is already on screen; later items may still reveal
+    bump(n => n + 1);
+  };
+  const finishIntroRef = React.useRef(finishIntro);
+  finishIntroRef.current = finishIntro;
+
+  const S = React.useRef(initialState({
+    verbose,
+    history: introAnimating ? [] : introHistory()
+  }));
+  const B = React.useRef(initialBuffer());
+  // Drop-in reveals: history items enter <Static> only once their reveal has ended (at most ~1 s); until then
+  // they render in the live region. committedRef = how many history items <Static> has been given.
+  const committedRef = React.useRef(introAnimating ? 0 : S.current.history.length);
+  const fxRef = React.useRef(new Map()); // item id -> { at, timing, running, settleAt }
+  const rosterSeen = React.useRef(new Map()); // roster row key -> first seen (ms)
+  const K = React.useRef({ keys: initialKeyState(), lastKeyAt: null, lastKeyCh: null, lastDataAt: 0, lastPasteAt: 0, lastEscAt: 0, ctrlC: 0, guard: null, cardFocus: false, cardGoneAt: 0, typed: '', danglingTimer: null });
+  const chromeRef = React.useRef(null);
+  const chromeH = React.useRef(null);
+  const R = React.useRef({ abort: null, histIdx: -1, history: [], stash: [], reviewing: false, fallbackTimer: null, ctrlCTimer: null, banner: null, closed: false, pollTimers: new Set(), caps: { steer: true, interrupt: true }, confirmMulti: null, roster: { rows: [], all: false, allRows: [], alerts: [], sources: null, on: true, focus: false, sel: 0, peek: false, confirm: null, stopping: false } });
+
+  const SND = React.useRef(null); SND.current ??= createSound({ api, stdout }); // QuoxSound: one subscription point (dispatch)
+  const dispatch = (a) => {
+    transcript?.action(a); // dev transcript capture (off by default; see transcript.js)
+    const prevS = S.current; S.current = reduce(prevS, { now: Date.now(), ...a }); SND.current.observe(prevS, S.current, a);
+    // Per shown card: remember the key that was already down when it appeared, and restart the typed word.
+    const c0 = S.current.approvals[0];
+    if (!c0 && K.current.guard) K.current.cardGoneAt = Date.now();
+    const gid = c0 ? `${c0.callId}:${c0.displayedAt}` : null;
+    if (gid !== K.current.guard?.id) {
+      const k = K.current;
+      const held = c0 && k.lastKeyAt != null && Date.now() - k.lastKeyAt < HELD_WINDOW_MS ? k.lastKeyCh : null;
+      k.guard = gid ? { id: gid, heldKey: held } : null;
+      k.typed = '';
+      k.cardFocus = false;
+    }
+    if (!R.current.closed) bump(n => n + 1);
+  };
+  const edit = (a) => { B.current = bufferReducer(B.current, a); if (!B.current.text) R.current.multiWarned = false; bump(n => n + 1); };
+  const say = (text, tone) => dispatch({ type: 'note', text, tone });
+  // /model: the --provider flag wins for this run ('auto' = ignore the saved choice), else the profile's saved choice.
+  const MC = React.useRef(modelChoice === 'auto' ? null : normChoice(modelChoice) || (api.modelChoice?.() ?? null));
+  // /connect card: owns its own secret box; the key never enters dispatch, the buffer or history.
+  const CN = React.useRef(null);
+  CN.current ??= createConnectController({ api, note: (t, tone) => say(t, tone), emit: (a) => dispatch(a), refresh: () => bump(n => n + 1) });
+  // L0 palette: opens under the composer while the draft is a bare /word (slash/paletteController.js).
+  const PL = React.useRef(null);
+  PL.current ??= createPalette({ getDraft: () => B.current.text, setDraft: (t) => edit({ type: 'set', text: t }), run: (t) => { R.current.history.push(t); command(t); }, say: (t, tone) => say(t, tone), ctx: () => ({ api, caps: R.current.contract, blocked }) });
+  const LG = React.useRef(null); LG.current ??= createLedger(); // /cost, /context: real usage only
+  const PK = React.useRef(null); PK.current ??= createPicker({ refresh: () => bump(n => n + 1) }); // /resume, /config
+  React.useEffect(() => (startSha ? buildWatch({ startSha, onNotice: (t) => say(t, 'dim') }) : undefined), []);
+  React.useEffect(() => { if (resume && !blocked) resumeCmd(resume === true ? '' : String(resume)); }, []);
+  React.useEffect(() => { if (!blocked && api.capabilities) api.capabilities().then((res) => { R.current.contract = capabilityMap(res); }, () => {}); }, []);
+
+  React.useEffect(() => {
+    if (columns != null) { setCols(clampCols(columns)); return undefined; }
+    // Rows the old width wrapped cannot be erased by Ink's line-count log-update (ghost composers). Wipe the
+    // visible screen, then remount <Static> so history reprints once at the new width.
+    const onResize = () => {
+      if (stdout?.isTTY !== false) stdout.write('\x1b[2J\x1b[H');
+      setEpoch(e => e + 1);
+      setCols(clampCols((stdout.columns || 80) - 1));
+    };
+    stdout?.on?.('resize', onResize);
+    return () => stdout?.off?.('resize', onResize);
+  }, [stdout, columns]);
+
+  R.current.startedAt ??= Date.now();
+  const where = React.useRef(slotAgent || detectSlotAgent());
+  // Session name (top rule) and the attached agent. The name is saved locally once a conversation id exists.
+  const SN = React.useRef({ name: cleanName(sessionName), saved: null, agent: null, baseAgent: where.current.agent ?? null });
+  React.useEffect(() => {
+    const id = S.current.ctx.conversationId; const key = `${id}|${SN.current.name}`;
+    if (SN.current.name && id && SN.current.saved !== key) { SN.current.saved = key; saveName(id, SN.current.name, namesPath); }
+  });
+
+  // Live approvals count: refreshed from the inbox every 30 s. A failed refresh keeps the last
+  // known count and records the error; it never reads as "0 waiting".
+  const refreshNotify = async () => {
+    if (blocked) return;
+    try {
+      const items = await api.approvals();
+      dispatch({ type: 'notify', patch: { approvals: items.length, error: null } });
+      dispatch({ type: 'inbox.sync', ids: items.map(i => i.id) });
+      // Provider paths that emit no approval.requested still surface here, as the same card.
+      for (const item of items) dispatch({ type: 'approval.found', item, since: R.current.startedAt, userId: api.userId?.() || null });
+    } catch (e) { dispatch({ type: 'notify', patch: { error: e?.message || 'failed' } }); }
+  };
+  React.useEffect(() => {
+    refreshNotify();
+    const id = setInterval(refreshNotify, notifyMs);
+    return () => clearInterval(id);
+  }, []);
+
+  // Roster: refreshed from real list endpoints. A failing source adds no rows and is named in /roster.
+  const refreshRoster = async () => {
+    if (blocked || !api.roster) return;
+    try {
+      let r = await api.roster(Date.now());
+      const R0 = R.current.roster;
+      const prevKey = R0.rows[R0.sel]?.key;
+      R0.allRows = r.rows; R0.alerts = backgroundAlerts(r.rows); R0.sources = r.sources;
+      r = { ...r, rows: selectRows(r.rows, { all: R0.all }) };
+      R0.rows = r.rows;
+      const at = r.rows.findIndex(x => x.key === prevKey);
+      R0.sel = at >= 0 ? at : Math.min(R0.sel, Math.max(0, r.rows.length - 1));
+      if (!r.rows.length) { R0.focus = false; R0.peek = false; R0.confirm = null; }
+      if (!R.current.closed) bump(n => n + 1);
+    } catch { /* api.roster handles per-source failures; nothing to show */ }
+  };
+  React.useEffect(() => {
+    refreshRoster();
+    const id = setInterval(refreshRoster, rosterMs);
+    return () => clearInterval(id);
+  }, []);
+
+  // Roster clock: finished rows fade out and drop locally at their expiry (runs on the motion clock's ticks).
+  const expireRoster = () => {
+    const ro = R.current.roster;
+    if (!ro.rows.length) return false;
+    const now = Date.now();
+    if (ro.rows.some(r => isExpired(r, now))) {
+      const selKey = ro.rows[ro.sel]?.key;
+      ro.rows = ro.rows.filter(r => !isExpired(r, now)); ro.allRows = ro.allRows.filter(r => !isExpired(r, now));
+      const at = ro.rows.findIndex(r => r.key === selKey);
+      ro.sel = at >= 0 ? at : Math.min(ro.sel, Math.max(0, ro.rows.length - 1));
+      if (!ro.rows.length) { ro.focus = false; ro.peek = false; ro.confirm = null; }
+      return true;
+    }
+    return false;
+  };
+
+  // ---- motion: ONE clock for every animation and visible tick (motion/clock.js). Each render declares what it
+  // still needs (frames, a second tick, a one-shot wake); with nothing declared there is no timer at all.
+  const clockRef = React.useRef(null);
+  const framesRef = React.useRef(null);
+  if (!framesRef.current) framesRef.current = createFrames();
+  const lastAppRender = React.useRef(0);
+  const ringRef = React.useRef(null);
+  const onClockTick = React.useRef(null);
+  onClockTick.current = () => {
+    if (R.current.closed) return;
+    R.current.tickPerf = performance.now();
+    const now = Date.now();
+    if (!introDone.current && now - introStart.current >= introMs) { finishIntro(); return; }
+    framesRef.current.emit(now); // animated leaves re-render themselves
+    if (expireRoster() || appDue(now)) bump(n => n + 1); // structural change: the whole view
+    else clockRef.current.schedule(demands(), now);
+  };
+  // The newest protocol stage stays live (its icon pulses) while it is the last thing that happened in the turn.
+  const isActiveStage = (st, i) => i === st.history.length - 1 && Boolean(st.turn) && !st.blocks.length && st.history[i].kind === 'trace';
+  // The app itself re-renders on a tick only when something it lays out is due (not for every frame).
+  function appDue(now) {
+    const s0 = S.current;
+    if (!introDone.current) return true;
+    const sec = (t) => Math.floor(t / 1000);
+    if (R.current.roster.rows.length && sec(now) !== sec(lastAppRender.current)) return true; // roster ages
+    if (motionOn) {
+      if (s0.history.length > committedRef.current && !fxActive(s0.history[committedRef.current], now) && !isActiveStage(s0, committedRef.current)) return true; // commit to Static
+      for (const r of R.current.roster.rows) if (rosterFx(r.key, now) != null || !rosterSeen.current.has(r.key)) return true;
+    }
+    const card0 = s0.approvals[0];
+    if (card0) {
+      const age = now - (card0.displayedAt ?? card0.shownAt);
+      if (motionOn && age < 1000) return true; // arrival animation
+      if (!R.current.armedShown && age >= 300) return true; // the card arms
+    }
+    return false;
+  }
+  if (!clockRef.current) clockRef.current = new Clock(() => onClockTick.current());
+  if (motionStats) motionStats.clock = clockRef.current;
+  React.useEffect(() => () => clockRef.current.stop(), []);
+  const demands = () => {
+    const s0 = S.current, now = Date.now(), d = [];
+    if (!introDone.current) d.push({ every: INTRO_FRAME_MS });
+    if (s0.turn) d.push(motionOn ? { every: FRAME_MS } : { every: SECOND_MS, since: s0.turn.startedAt });
+    const card0 = s0.approvals[0];
+    if (card0) { const at = (card0.displayedAt ?? card0.shownAt) + 320; if (now < at) d.push(motionOn ? { every: FRAME_MS } : { at }); }
+    if (R.current.roster.rows.length) d.push({ every: SECOND_MS });
+    if (ringAnimating(ringRef.current)) d.push({ every: FRAME_MS }); // the ring settling after the turn
+    if (eyeActive(now, !motionOn)) d.push({ every: motionOn ? 50 : 500 }); // /eye (qmotion EyeLive) plays on the shared clock
+    if (motionOn && fxBusy(now)) d.push({ every: FRAME_MS }); // reveals in flight
+    return d;
+  };
+  React.useEffect(() => { if (!R.current.closed) clockRef.current.schedule(demands()); });
+
+  const fxEnd = (e) => Math.max(e.at + revealSpan(e.timing) * 1000, e.settleAt != null ? e.settleAt + revealSpan(TIMING.settle) * 1000 : 0);
+  const fxActive = (item, now) => { const e = fxRef.current.get(item.id); return Boolean(e) && now < fxEnd(e); };
+  const fxFor = (item, now) => {
+    const e = fxRef.current.get(item.id);
+    if (!e || now >= fxEnd(e)) return null;
+    return { e: (now - e.at) / 1000, timing: e.timing, settle: e.settleAt != null ? (now - e.settleAt) / 1000 : null };
+  };
+  const registerFx = (item, now) => {
+    const t = revealTimingFor(item);
+    if (!t) return;
+    const e = fxRef.current.get(item.id);
+    if (!e) fxRef.current.set(item.id, { at: now, timing: t, running: item.kind === 'tool' && item.status === 'running', settleAt: null });
+    else if (e.running && item.status !== 'running' && e.settleAt == null) e.settleAt = now;
+  };
+  const rosterFx = (key, now) => { const at = rosterSeen.current.get(key); const e = at == null ? null : (now - at) / 1000; return e != null && e < revealSpan(TIMING.roster) ? e : null; };
+  function fxBusy(now) {
+    const s0 = S.current;
+    if (s0.history.length > committedRef.current) return true;
+    if (s0.blocks.some(b => fxActive(b, now))) return true;
+    const card0 = s0.approvals[0];
+    if (card0 && now - (card0.displayedAt ?? card0.shownAt) < 1000) return true;
+    for (const r of R.current.roster.rows) if (rosterFx(r.key, now) != null) return true;
+    return false;
+  }
+
+  // After approving from the terminal the tool runs asynchronously: poll its stored result.
+  const pollResult = async (run) => {
+    if (!run.approvalId || !api.approvalResult) return dispatch({ type: 'approval.result', callId: run.callId, outcome: 'timeout' });
+    const t0 = Date.now();
+    while (Date.now() - t0 < resultTimeoutMs) {
+      await new Promise(r => { const t = setTimeout(() => { R.current.pollTimers.delete(t); r(); }, resultPollMs); R.current.pollTimers.add(t); R.current.pollWake = r; });
+      if (R.current.closed) return undefined;
+      if (!S.current.running.some(x => x.callId === run.callId)) return undefined; // resolved elsewhere
+      try {
+        const r = await api.approvalResult(run.approvalId);
+        if (r?.status === 'denied') return dispatch({ type: 'approval.result', callId: run.callId, outcome: 'denied' });
+        if (r && (r.status === 'approved' || r.status === 'error') && r.executed_at) {
+          const text = r.result == null ? null : clip(typeof r.result === 'string' ? r.result : JSON.stringify(r.result), cols - 20);
+          return dispatch({ type: 'approval.result', callId: run.callId, outcome: r.status === 'error' ? 'failed' : 'done', text });
+        }
+      } catch { /* keep polling until the deadline */ }
+    }
+    return dispatch({ type: 'approval.result', callId: run.callId, outcome: 'timeout' });
+  };
+  const answer = async (card, action) => {
+    if (R.current.answering?.has(card.callId)) return;
+    (R.current.answering ||= new Set()).add(card.callId);
+    try {
+      await api.respond(card.inboxItemId, action);
+      dispatch({ type: 'approval.sent', callId: card.callId, action, tool: card.tool, target: card.target, approvalId: card.approvalId });
+      if (action === 'approve') pollResult({ callId: card.callId, approvalId: card.approvalId });
+    } catch (e) { dispatch({ type: 'error', text: `approval: ${e.message}` }); }
+    finally { R.current.answering.delete(card.callId); }
+  };
+
+  // ---- turn runner ---------------------------------------------------------------------------
+  async function runTurn(text) {
+    if (blocked) { say(blocked, 'warn'); return; }
+    const turnId = newTurnId();
+    return consumeTurn(turnId, (signal) => api.stream({ turnId, message: text, agent: SN.current.agent || 'quox', conversationId: S.current.ctx.conversationId, context: R.current.rulesOn === false ? undefined : rulesContext(rules), ...streamFields(MC.current) }, signal));
+  }
+
+  // QUOXON C5: render a turn that is already running on the server (after /resume, --conversation or a
+  // restart). Replays it from the start, then follows it live; exactly once by seq.
+  async function followTurn(conversationId, turnId) {
+    if (S.current.turn || !api.reattach) return;
+    say('A turn is still running in this conversation; reattaching to it.', 'dim');
+    return consumeTurn(turnId, (signal) => api.reattach({ conversationId, turnId, after: 0 }, signal));
+  }
+  async function reattachIfRunning(conversationId) {
+    if (!conversationId || !api.runningTurn || S.current.turn) return;
+    const r = await api.runningTurn(conversationId);
+    if (r?.running && r.turnId && !S.current.turn && S.current.ctx.conversationId === conversationId) followTurn(conversationId, r.turnId);
+  }
+
+  async function consumeTurn(turnId, open) {
+    R.current.caps.steer = true; R.current.steerNoted = false; // steer support is learned per turn (provider paths differ)
+    R.current.durable = false; // learned from the server: v1.1 events carry a seq
+    dispatch({ type: 'turn.begin', turnId });
+    const ctrl = new AbortController();
+    R.current.abort = ctrl;
+    let offered = false;
+    try {
+      for await (const ev of open(ctrl.signal)) {
+        if (ctrl.signal.aborted) break;
+        if (typeof ev?.seq === 'number') R.current.durable = true;
+        LG.current.observe(ev);
+        dispatch({ type: 'event', ev });
+        const fb = fallbackNote(MC.current, ev);
+        if (fb) say(fb, 'warn');
+        const offer = connectOfferFor(ev);
+        if (offer && !offered) { offered = true; say(offer); }
+      }
+      if (S.current.turn?.id === turnId) {
+        // stream closed without a terminal event
+        // never claim completion the server did not confirm
+        dispatch({ type: 'event', ev: { type: 'turn.finished', status: ctrl.signal.aborted ? 'interrupted' : 'unconfirmed' } });
+      }
+    } catch (e) {
+      if (!ctrl.signal.aborted) {
+        dispatch({ type: 'event', ev: { type: 'error', error: friendlyError(e, profile) } });
+        // A lost reattach is not a failed turn: the server may still be finishing it (C5).
+        if (S.current.turn?.id === turnId) dispatch({ type: 'event', ev: { type: 'turn.finished', status: e?.code === 'reattach_failed' ? 'unconfirmed' : 'failed' } });
+      }
+    } finally {
+      clearTimeout(R.current.fallbackTimer);
+      LG.current.end();
+      R.current.abort = null;
+      if (S.current.turn?.id === turnId) dispatch({ type: 'stopped.local' });
+    }
+  }
+
+  React.useEffect(() => {
+    const s = S.current;
+    if (!s.turn && s.autoDrain && s.pending.length) {
+      const next = s.pending[0];
+      dispatch({ type: 'queue.shift' });
+      dispatch({ type: 'user', text: next.text, queued: true });
+      runTurn(next.text);
+    }
+  });
+
+  function submit(text) {
+    dispatch({ type: 'user', text });
+    const tip = intentHint(text); // a hint only: the turn still goes to the model
+    if (tip) say(tip);
+    const panel = intentPanel(text); // the same panel as the command, from local facts, above the answer
+    if (panel) showPanel(panel, { local: true });
+    R.current.history.push(text);
+    R.current.histIdx = -1;
+    runTurn(text);
+  }
+
+  async function steer(text) {
+    const id = `steer_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+    const s = S.current;
+    dispatch({ type: 'steer.add', id, text });
+    const r = await api.steer(s.ctx.conversationId, s.turn.id, text, id);
+    if (r.ok) return;
+    // Put the text back in the draft (in front of anything typed since) instead of losing or replaying it.
+    const restore = () => { const cur = B.current.text; edit({ type: 'set', text: cur ? `${text}\n${cur}` : text }); };
+    if (r.reason === 'ambiguous') {
+      dispatch({ type: 'steer.failed', id, reason: 'Steer may not have been applied; resend? Your text is back in the draft.' });
+      restore();
+    } else if (r.reason === 'denied') {
+      dispatch({ type: 'steer.failed', id, reason: `Steering was denied by policy (${r.message || 'steer_denied_by_policy'}). Your text is back in the draft; it was not run.` });
+      restore();
+    } else {
+      if (r.reason === 'unsupported') { R.current.caps.steer = false; R.current.steerNoted = true; bump(n => n + 1); }
+      dispatch({ type: 'steer.converted', id, reason: r.reason === 'turn_finished'
+        ? 'That turn already finished; queued your message as the next turn.'
+        : STEER_OFF_NOTE });
+    }
+  }
+
+  async function interrupt() {
+    const s = S.current;
+    if (!s.turn || s.turn.status === 'interrupting') return;
+    dispatch({ type: 'interrupt.requested' });
+    const r = await api.interrupt(s.ctx.conversationId, s.turn.id);
+    const turnId = s.turn.id;
+    const local = () => { if (S.current.turn?.id === turnId) { R.current.abort?.abort(); dispatch({ type: 'stopped.local' }); } };
+    if (!r.ok) { R.current.caps.interrupt = false; return local(); }
+    R.current.fallbackTimer = setTimeout(local, INTERRUPT_FALLBACK_MS);
+  }
+
+  // ---- L1 slash commands (models in slash/*.js) ------------------------------------------------
+  const help = (model) => dispatch({ type: 'help', model });
+  const leaveArmed = (kind) => { // a running turn would be disconnected: ask once, a second ask within 5 s goes ahead
+    if (!S.current.turn) return true;
+    // C5: a durable turn (the server sends seq) keeps running when we leave; /resume reattaches.
+    if (R.current.durable) { say('Quox keeps working; it will be here when you come back. /resume reattaches to the turn.', 'ok'); return true; }
+    const t = R.current.leaveAsk;
+    if (t && t.kind === kind && Date.now() - t.at < 5000) return true;
+    R.current.leaveAsk = { kind, at: Date.now() };
+    say(`A turn is running. ${kind === 'restart' ? 'Restarting' : 'Leaving'} disconnects it, and the server stops it before its next step (a tool already running finishes and is recorded). /${kind === 'restart' ? 'restart' : 'quit'} again within 5 s to go ahead, or wait for the turn.`, 'warn');
+    return false;
+  };
+  async function showPanel(cmd, { local = false } = {}) {
+    const base = { ctx: S.current.ctx, choice: MC.current, agent: SN.current.agent || where.current.agent, conversationId: S.current.ctx.conversationId };
+    if (cmd === '/cost') return help(costModel(LG.current));
+    if (cmd === '/status') {
+      let hl = R.current.lastHealth || null;
+      if (!local && api.health) { hl = await api.health(8000); R.current.lastHealth = hl; }
+      return help(statusModel({ ...base, profile, org: org || null, serverUrl: api.serverUrl?.() || hl?.url || null, health: hl, slot: where.current.slot, sessionName: SN.current.name, version, local: local && !hl }));
+    }
+    if (cmd === '/context') {
+      let skills = R.current.skillsInfo || null; let memory = R.current.memoryInfo || null;
+      if (!local) {
+        [skills, memory] = await Promise.all([
+          api.skills ? api.skills().then(l => ({ ok: true, count: l.length }), e => ({ ok: false, error: e?.status ? `HTTP ${e.status}` : (e?.message || 'failed') })) : { ok: false, error: 'not available in this mode' },
+          api.memoryStatus ? api.memoryStatus() : { ok: false, error: 'not available in this mode' }
+        ]);
+        R.current.skillsInfo = skills; R.current.memoryInfo = memory;
+      }
+      let server = null; let serverError = null;
+      if (!local && base.conversationId && api.conversationContext) {
+        try { server = contextFacts(await api.conversationContext(base.conversationId)); }
+        catch (e) { serverError = e?.status === 404 ? 'no stored turns yet' : e?.status ? `HTTP ${e.status}` : (e?.message || 'failed'); }
+      }
+      return help(contextModel({ ...base, server, serverError, tokens: LG.current.conversationTokens(S.current.ctx.conversationId), rules, rulesOn: R.current.rulesOn !== false, skills, memory }));
+    }
+    return undefined;
+  }
+  async function resumeTo(row) {
+    if (S.current.turn) return say('Wait for the current turn or press Esc first.', 'warn');
+    let turns;
+    try { turns = await api.conversationTurns(row.id); } catch (e) { return dispatch({ type: 'error', text: `resume: ${e?.status ? `HTTP ${e.status}: ` : ''}${e?.message || 'failed'}` }); }
+    const t = turnsToHistory(turns);
+    dispatch({ type: 'ctx', ctx: { conversationId: row.id } });
+    SN.current.name = loadNames(namesPath)[row.id]?.name || null; SN.current.saved = null;
+    say(`Resumed "${clip(row.title, cols - 20)}"${row.agent ? ` with ${row.agent}` : ''}.`, 'ok');
+    dispatch({ type: 'history.add', items: t.items, answers: t.answers });
+    say(t.total ? `Showing the last ${t.shown} of ${t.total} stored messages. Your next message continues this conversation.` : 'The server has no stored messages for it (it keeps them 7 days). Your next message continues it anyway.', 'dim');
+    return reattachIfRunning(row.id);
+  }
+  async function resumeCmd(q) {
+    if (!api.conversations || !api.conversationTurns) return say('Resume is not available in this mode.', 'warn');
+    let rows;
+    try {
+      const [list, index] = await Promise.all([api.conversations(30), api.sessionsIndex ? api.sessionsIndex().catch(() => null) : null]);
+      rows = resumeRows(list, index, loadNames(namesPath));
+    } catch (e) { return dispatch({ type: 'error', text: `resume: ${e?.status ? `HTTP ${e.status}: ` : ''}${e?.message || 'failed'}` }); }
+    if (q) {
+      const m = matchConversation(rows, q);
+      if (m.row) return resumeTo(m.row);
+      return say(m.ambiguous ? `"${q}" matches ${m.ambiguous.length} conversations: ${m.ambiguous.map(x => x.slice(0, 12)).join(', ')}. Use more of the id.` : `No recent conversation matches "${q}". /resume lists them.`, 'warn');
+    }
+    if (!rows.length) return say('No recent conversations to resume.');
+    const now = Date.now();
+    PK.current.open({ title: 'Resume a conversation', rows: rows.map(r => pickerRow(r, now)), hint: '↑↓ select · Enter resume · Esc cancel', onPick: (_, i) => resumeTo(rows[i]) });
+    return undefined;
+  }
+  function openConfig() {
+    const list = settingsList();
+    const saved = api.settings ? api.settings() : (R.current.sessionSettings ||= {});
+    const vals = { verbose: S.current.verbose, ...saved, sound: SND.current.settings?.().profile };
+    const set = (it, v) => {
+      vals[it.id] = v;
+      if (it.id === 'sound') { SND.current.command(v, say); return; } // the sound controller saves its own profile
+      const ok = api.saveSetting ? api.saveSetting(it.id, v) : ((R.current.sessionSettings ||= {})[it.id] = v, false);
+      if (it.id === 'verbose') dispatch({ type: 'verbose', mode: v });
+      if (it.id === 'theme' || it.id === 'motion') {
+        applySettings(vals, env);
+        if (it.id === 'theme' && stdout?.isTTY !== false) { stdout.write('\x1b[2J\x1b[H'); setEpoch(e => e + 1); } // repaint history in the new look
+      }
+      R.current.configSaved = ok;
+    };
+    PK.current.open({
+      title: api.saveSetting ? `Settings · saved to profile ${profile}` : 'Settings · this session only (no profile in this mode)',
+      rowsFn: () => configRows(list, vals, { model: modelLabel(S.current.ctx, MC.current) || 'auto' }),
+      hint: '↑↓ select · ←→ or Space change · Enter on Model opens /model · Esc close',
+      onAdjust: (i, dir) => { const it = list[i]; if (!it.action) set(it, cycle(it, vals[it.id], dir)); },
+      keepOpen: (i) => !list[i].action,
+      onPick: (_, i) => { const it = list[i]; if (it.action === 'model') command('/model'); else set(it, cycle(it, vals[it.id], 1)); }
+    });
+  }
+
+  async function command(line) {
+    if (/^\/\/(\s|$)/.test(line.trim())) line = line.trim().replace(/^\/\//, '/note');
+    const [cmd, arg] = line.trim().split(/\s+/);
+    if (cmd !== '/note') transcript?.command(line);
+    const restArg = line.trim().replace(/^\S+\s*/, '');
+    if (OBJECT_CMDS.has(cmd) && !(cmd === '/rules' && arg)) { // inline object views (objects/): a card into history, or an honest note
+      const r = await runObjectCommand(cmd, restArg, { objects: api.objects, rules, rulesOn: R.current.rulesOn, items: [...S.current.history, ...S.current.blocks] });
+      if (r) return r.object ? dispatch({ type: 'object', obj: r.object }) : say(clip(r.note, cols - 4), r.tone);
+    }
+    switch (cmd) {
+      case '/copy': {
+        const r = pickCopy(S.current.answers, arg || '');
+        if (r.error) return say(r.error, 'warn');
+        if (stdout?.isTTY) stdout.write(osc52(r.text));
+        return say(`copied ${r.text.length.toLocaleString('en-US')} chars to the clipboard (needs a terminal that allows OSC 52)`, 'dim');
+      }
+      case '/note': {
+        if (!restArg) return say('Usage: /note <text>  (or // text). Nothing to note.', 'warn');
+        if (!transcript?.note) return say('notes need dev transcripts on (touch ~/.config/quox/dev-transcripts)', 'warn');
+        transcript.note(restArg.slice(0, 2000));
+        return say('noted for the observer', 'dim');
+      }
+      case '/rename': {
+        if (!restArg) return say(SN.current.name ? `Session name: ${SN.current.name}` : 'This session has no name. Use /rename <name>.');
+        const n = cleanName(restArg);
+        SN.current.name = n; SN.current.saved = null; bump(x => x + 1);
+        return say(`Session named "${n}".`, 'ok');
+      }
+      case '/slot': {
+        if (!restArg) return say(where.current.slot ? `Slot: ${where.current.slot}` : 'No slot. Use /slot <name> to give this session an address.');
+        if (!api.checkoutSlot) return say('Slots are not available in this mode.', 'warn');
+        const nm = restArg.split(/\s+/)[0];
+        const r = await api.checkoutSlot(nm, SN.current.name || S.current.ctx.conversationId || 'quox');
+        if (!r.ok) return say(`slot ${nm}: ${r.message}`, 'warn');
+        where.current = { ...where.current, slot: nm }; bump(x => x + 1);
+        return say(`Slot ${nm} checked out. Discord replies are not relayed into this window yet.`, 'ok');
+      }
+      case '/attach': {
+        if (!restArg) return say(SN.current.agent ? `Attached to ${SN.current.agent}. /detach returns to CommanderQ.` : 'Talking to CommanderQ. Use /attach <agent> to pick one.');
+        if (S.current.turn) return say('Wait for the current turn or press Esc first.', 'warn');
+        if (!api.agents) return say('Agents are not available in this mode.', 'warn');
+        let list;
+        try { list = await api.agents(); } catch (e) { return say(`could not list agents: ${e.message}`, 'warn'); }
+        const m = matchAgent(restArg, list);
+        if (!m.agent) return say(`No agent called "${restArg}".${m.matches.length ? ` Closest: ${m.matches.join(', ')}.` : ' Try quox agent list.'}`, 'warn');
+        SN.current.agent = m.agent.id; where.current = { ...where.current, agent: m.agent.id }; bump(x => x + 1);
+        return say(`Attached to ${m.agent.id}. Your next turns go to it. /detach returns to CommanderQ.`, 'ok');
+      }
+      case '/connect': {
+        if (!restArg) {
+          if (!api.connections) return say('Connections are not available in this mode.', 'warn');
+          for (const [t, tone] of connectionLines(await api.connections())) say(clip(t, cols - 4), tone);
+          return undefined;
+        }
+        if (S.current.turn) return say('Wait for the current turn or press Esc first.', 'warn');
+        const pv = providerFor(arg);
+        if (pv?.url && pv.id !== 'ollama') { // B5: LM Studio / vLLM / custom: probed server side, then saved (custom may need a key)
+          const rest = restArg.replace(/^\S+\s*/, '');
+          say(`Checking the URL from the server…`);
+          const r = await connectCompatFlow(api, pv.id, rest);
+          for (const [t, tone] of r.lines) say(clip(t, cols - 4), tone);
+          if (r.needsKey) CN.current.openCustom(r.extra);
+          return undefined;
+        }
+        if (pv?.url) { // B3: Ollama takes a URL, probed and saved server side
+          say(`Checking ${parseOllamaArg(restArg.replace(/^\S+\s*/, '')).url || 'the URL'} from the server…`);
+          const r = await connectOllamaFlow(api, restArg.replace(/^\S+\s*/, ''));
+          for (const [t, tone] of r.lines) say(clip(t, cols - 4), tone);
+          return undefined;
+        }
+        CN.current.open(arg);
+        return undefined;
+      }
+      case '/model': {
+        if (!api.connections) return say('Model choice is not available in this mode.', 'warn');
+        const res = await api.connections();
+        if (!restArg) { for (const [t, tone] of modelLines(res, MC.current)) say(clip(t, cols - 4), tone); return undefined; }
+        let r = selectModel(res, restArg);
+        let installed = null;
+        if (r.ok && r.choice?.provider === 'ollama' && api.ollamaModels) { // B3: check against what that Ollama has installed
+          r = selectOllamaModel(await api.ollamaModels(), r.choice.model || null);
+          if (r.models) installed = ollamaModelRows(r.models, r.current || r.choice?.model);
+        }
+        if (r.ok && byId(r.choice?.provider)?.compat && api.compatModels) { // B5: check against the provider's own /models
+          r = selectCompatModel(await api.compatModels(r.choice.provider), r.choice.provider, r.choice.model || null);
+          if (r.models) installed = compatModelRows(r.models, r.current || r.choice?.model);
+        }
+        if (r.ok) {
+          MC.current = r.choice; api.setModelChoice?.(r.choice);
+          dispatch({ type: 'ctx', ctx: { provider: null, model: null, endpoint: null } }); // the status line shows the new ask until the server answers
+        }
+        say(r.text, r.tone);
+        if (installed) for (const [t, tone] of installed) say(clip(t, cols - 4), tone);
+        return undefined;
+      }
+      case '/capabilities': {
+        if (!api.capabilities) return say('Capabilities are not available in this mode.', 'warn');
+        const res = await api.capabilities();
+        if (restArg && res.ok) {
+          const c = findCapability(restArg, res);
+          if (!c) return say(`Nothing called "${restArg}". /capabilities lists them.`, 'warn');
+          say(clip(`${c.name}: ${c.intent}`, cols - 4));
+          say(clip(`Proof: ${c.evidence || 'not stated'}`, cols - 4));
+          return say(clip(offerFor(c.id, res) || `✔ ${c.name} is ready here.`, cols - 4), c.availability === 'installed' ? 'ok' : 'warn');
+        }
+        for (const [t, tone] of capabilityLines(res)) say(clip(t, cols - 4), tone);
+        return undefined;
+      }
+      case '/workflow': case '/crystal': case '/memory': case '/proof': case '/reconcile': return undefined; // answered above (runObjectCommand)
+      case '/agents': return say('Usage: /agents <name> shows an agent card.'); // the bare list belongs to the slash-commands work
+      case '/detach':
+        SN.current.agent = null; where.current = { ...where.current, agent: SN.current.baseAgent }; bump(x => x + 1);
+        return say('Back to CommanderQ.');
+      case '/sessions': {
+        if (arg === 'all') {
+          if (!api.sessionsIndex) return say('The session index is not available in this mode.', 'warn');
+          try {
+            for (const l of overviewLines(await api.sessionsIndex(), { localHost: osHostname(), names: loadNames(namesPath) })) say(clip(l.text, cols - 4), l.tone);
+          } catch (e) { dispatch({ type: 'error', text: `sessions all: ${e.status ? `HTTP ${e.status}: ` : ''}${e.message}` }); }
+          return undefined;
+        }
+        if (!api.conversations) return say('Sessions are not available in this mode.', 'warn');
+        try {
+          const rows = await api.conversations(); const names = loadNames(namesPath);
+          if (!rows.length) return say('No recent conversations.');
+          for (const r of rows) say(`${r.id.slice(0, 12)}  ${clip(names[r.id]?.name || r.title || '(untitled)', Math.max(10, cols - 30))}  ${r.updated_at ? String(r.updated_at).slice(0, 16).replace('T', ' ') : ''}`);
+        } catch (e) { dispatch({ type: 'error', text: `sessions: ${e.message}` }); }
+        return undefined;
+      }
+      case '/quit': case '/exit': {
+        const midTurn = Boolean(S.current.turn);
+        if (!leaveArmed('quit')) return undefined;
+        R.current.leaveAsk = null;
+        return midTurn ? setTimeout(() => exit(), 30) : exit(); // mid-turn: let the "keeps working" line paint first
+      }
+      case '/restart': {
+        if (!onRestart) return say('Restart is not available in this mode.', 'warn');
+        if (!leaveArmed('restart')) return undefined;
+        R.current.leaveAsk = null;
+        if (R.current.restarting) return say('Already restarting…', 'dim');
+        R.current.restarting = true;
+        let target;
+        if (restartCheck) { // never let go of the terminal for a quox that cannot start: say so and stay
+          say('Checking the installed quox…', 'dim');
+          const c = await restartCheck();
+          if (!c.ok) { R.current.restarting = false; return say(`Could not restart: ${c.bin} did not start (${c.error}). Still in this client.`, 'warn'); }
+          target = c.onPath || undefined;
+        }
+        say(`Restarting${S.current.ctx.conversationId ? ' into this conversation' : ''}…`, 'dim');
+        onRestart({ conversationId: S.current.ctx.conversationId || null, name: SN.current.name || null, bin: target });
+        return setTimeout(() => exit(), 30);
+      }
+      case '/gripe': case '/gripe!': {
+        if (!api.gripe) return say('/gripe is not available in this mode.', 'warn');
+        const pending = R.current.pendingGripe && Date.now() - R.current.pendingGripe.at < 120000 ? R.current.pendingGripe.text : null;
+        const text = restArg || (cmd === '/gripe!' ? pending : null);
+        if (!text) return say(cmd === '/gripe!' ? 'Nothing to file. /gripe <text> first, or /gripe! <text>.' : 'Usage: /gripe <what is wrong>  (/gripe! <text> files without asking)', 'warn');
+        if (cmd === '/gripe') { // ask first: filing makes a public-ish issue
+          R.current.pendingGripe = { text, at: Date.now() };
+          say(`File this as a GitHub issue via GRIPE? "${clip(text, Math.max(20, cols - 50))}"`);
+          return say('/gripe! files it · /gripe <new text> replaces it · anything else leaves it unfiled', 'dim');
+        }
+        R.current.pendingGripe = null;
+        say('Filing via GRIPE…', 'dim');
+        const g = await api.gripe(text.slice(0, 4000), { yes: true });
+        if (!g.ok) return say(`Gripe not filed: ${g.message}`, 'warn');
+        if (!g.superseded && g.response && !g.url) for (const l of String(g.response).split('\n').filter(Boolean).slice(0, 6)) say(clip(l, cols - 4), 'dim');
+        for (const n of g.notes || []) {
+          if (n.kind === 'created') say(`✔ GRIPE │ issue filed │ ${n.url}`, 'ok');
+          else say(clip(n.text, cols * 3), n.kind === 'warn' ? 'warn' : 'dim');
+        }
+        return undefined;
+      }
+      case '/status': case '/context': case '/cost': case '/usage':
+        return showPanel(cmd === '/usage' ? '/cost' : cmd);
+      case '/doctor': {
+        if (!api.doctorChecks) return say('/doctor is not available in this mode.', 'warn');
+        say('Running the quox doctor checks…', 'dim');
+        const [plat, chat] = await Promise.all([api.doctorChecks().then(c => ({ c }), e => ({ e })), chatChecks(api)]);
+        return help(doctorModel(plat.c || [], chat, plat.e ? (plat.e.message || 'failed') : null));
+      }
+      case '/config': case '/settings':
+        if (S.current.turn) return say('Wait for the current turn or press Esc first.', 'warn');
+        return openConfig();
+      case '/compact': {
+        if (arg === 'show') {
+          const last = R.current.lastCompact;
+          if (!last) return say('Nothing compacted in this session yet. /compact runs it.', 'warn');
+          return help(compactShowLines(last));
+        }
+        if (!api.compactConversation) return say('/compact is not available in this mode.', 'warn');
+        const id = S.current.ctx.conversationId;
+        if (!id) return say('Nothing to compact yet: this conversation starts with your next message.', 'warn');
+        if (S.current.turn) return say('A turn is still running in this conversation. Compact after it finishes.', 'warn');
+        say('Compacting on the server (one model call)…', 'dim');
+        let r;
+        try { r = await api.compactConversation(id); } catch (e) { return say(compactError(e), 'warn'); }
+        const v = compactResult(r);
+        R.current.lastCompact = v;
+        return help([
+          { kind: 'plain', text: v.head },
+          ...v.summaryLines.map(t => ({ kind: 'dim', text: `│ ${t}` })),
+          ...(v.more ? [{ kind: 'dim', text: `│ … ${v.more} more line${v.more === 1 ? '' : 's'}. /compact show for all` }] : []),
+          ...v.notes.map(t => ({ kind: 'dim', text: t }))
+        ]);
+      }
+      case '/resume':
+        if (S.current.turn) return say('Wait for the current turn or press Esc first.', 'warn');
+        return resumeCmd(restArg);
+      case '/eye': playEye(); bump(n => n + 1); return true; // the Dragon's Eye, on demand (qmotion.js EyeLive); the bump lets the app's clock frame it
+      case '/sound': return SND.current.command(arg, say);
+      case '/about': return dispatch({ type: 'welcome', version: packageVersion() });
+      case '/help': return dispatch({ type: 'help', model: helpModel(arg, R.current.caps) });
+      case '/clear': case '/new': case '/reset': {
+        if (S.current.turn) return say('Wait for the current turn or press Esc first.', 'warn');
+        const prev = S.current.ctx.conversationId;
+        dispatch({ type: 'ctx', ctx: { conversationId: null } });
+        SN.current.name = null; SN.current.saved = null;
+        dispatch({ type: 'history.reset' });
+        if (stdout?.isTTY) stdout.write('\x1b[2J\x1b[3J\x1b[H');
+        setEpoch(e => e + 1);
+        return say(prev ? 'Previous conversation saved. /resume to go back.' : 'New conversation.');
+      }
+      case '/verbose':
+        if (!['off', 'on', 'full'].includes(arg)) return say(`verbose is ${S.current.verbose}. Use /verbose off|on|full`);
+        dispatch({ type: 'verbose', mode: arg });
+        return say(`verbose ${arg}`);
+      case '/rules': {
+        if (arg === 'off' || arg === 'on') {
+          R.current.rulesOn = arg === 'on';
+          bump(n => n + 1);
+          return say(arg === 'on' ? (rules?.files?.length ? 'Rules on.' : 'No QUOX.md loaded, nothing to turn on.') : 'Rules off for this session (nothing from QUOX.md is sent).');
+        }
+        const lines = rulesLines(rules, { enabled: R.current.rulesOn !== false, cols });
+        const per = 20, pages = Math.max(1, Math.ceil(lines.length / per));
+        const pg = Math.min(pages, Math.max(1, Number(arg) || 1));
+        lines.slice((pg - 1) * per, pg * per).forEach(l => say(clip(l, cols - 4)));
+        if (pages > 1) say(`page ${pg}/${pages}${pg < pages ? ` · /rules ${pg + 1} for more` : ''}`);
+        return undefined;
+      }
+      case '/skills': {
+        if (!api.skills) return say('This server has no skills list.', 'warn');
+        try {
+          const all = await api.skills();
+          if (arg) {
+            const sk = findSkill(all, arg);
+            if (!sk) return say(`No skill named "${arg}". /skills lists them.`, 'warn');
+            const full = (api.skill && sk.id ? await api.skill(sk.id) : null) || sk;
+            skillDetail(full).forEach(l => say(clip(l, cols - 4)));
+            return undefined;
+          }
+          if (!all.length) return say('No skills in this org yet.');
+          say(`${all.length} skill${all.length === 1 ? '' : 's'}. /skills <name> for detail, /skill <name> [args] to run:`);
+          skillRows(all.slice(0, 25), cols - 4).forEach(l => say(l));
+          if (all.length > 25) say(`... and ${all.length - 25} more. /skills <name> shows any one.`);
+        } catch (e) { dispatch({ type: 'error', text: `skills: ${e.message}` }); }
+        return undefined;
+      }
+      case '/skill': {
+        const argRest = line.trim().split(/\s+/).slice(2).join(' ');
+        if (!arg) return say('Usage: /skill <name> [args]. /skills lists them.', 'warn');
+        if (S.current.turn) return say('Wait for the current turn or press Esc first.', 'warn');
+        if (blocked) return say(blocked, 'warn');
+        if (api.skills) {
+          try {
+            const sk = findSkill(await api.skills(), arg);
+            if (!sk) return say(`No skill named "${arg}". /skills lists them.`, 'warn');
+            return submit(skillPrompt(sk.name || arg, argRest));
+          } catch (e) { return dispatch({ type: 'error', text: `skills: ${e.message}` }); }
+        }
+        return submit(skillPrompt(arg, argRest));
+      }
+      case '/roster': {
+        const ro = R.current.roster;
+        if (arg === 'all') {
+          ro.all = !ro.all; ro.on = true;
+          ro.rows = selectRows(ro.allRows, { all: ro.all }); ro.sel = 0;
+          return say(ro.all ? 'Roster shows everything, background work included. /roster all again to hide it.' : 'Roster shows only what needs you. Background work is hidden.');
+        }
+        ro.on = !ro.on; if (!ro.on) { ro.focus = false; ro.peek = false; ro.confirm = null; }
+        say(`Roster ${ro.on ? 'on' : 'off'}.${ro.sources ? '' : ' Not loaded yet.'}`);
+        for (const src of ro.sources || []) {
+          say(`${src.state === 'connected' ? '✔' : src.state === 'error' ? '✖' : '·'} ${src.label}: ${src.state === 'connected' ? `${src.count} shown` : `${src.state}${src.note ? ` (${src.note})` : ''}`}`, src.state === 'error' ? 'warn' : undefined);
+        }
+        if (ro.sources) say('Down on an empty composer focuses the roster. Enter peeks, s stops (y confirms), Esc returns.');
+        return undefined;
+      }
+      case '/observers': {
+        if (!api.observers) return say('Observers are not available in this mode.', 'warn');
+        try { for (const [text, tone] of observerLines(await api.observers(), cols)) say(text, tone); }
+        catch (e) { dispatch({ type: 'error', text: `observers: ${e.message}` }); }
+        return undefined;
+      }
+      case '/approvals': {
+        try {
+          const items = await api.approvals();
+          dispatch({ type: 'inbox', items });
+          dispatch({ type: 'notify', patch: { approvals: items.length, error: null } });
+          if (!items.length) return say('Nothing is waiting for your approval.');
+          say(`${items.length} waiting. /approve N or /deny N:`, 'warn');
+          items.slice(0, 9).forEach((it, i) => say(`[${i + 1}] ${clip(it.title || it.summary || it.id, cols - 12)}`));
+        } catch (e) { dispatch({ type: 'error', text: `approvals: ${e.message}` }); }
+        return undefined;
+      }
+      case '/approve': case '/deny': {
+        const it = S.current.inbox[Number(arg) - 1];
+        if (!it) return say('Run /approvals first, then /approve N.', 'warn');
+        try {
+          await answer({ callId: it.id, inboxItemId: it.id, approvalId: it.approval_id || it.approvalId || null, tool: clip(it.title || it.id, cols - 40), target: null }, cmd === '/approve' ? 'approve' : 'reject');
+        } catch (e) { dispatch({ type: 'error', text: `approval: ${e.message}` }); }
+        return undefined;
+      }
+      default: {
+        const e = findEntry(cmd);
+        if (e && e.status === 'planned') return say(`${e.usage} is planned, not built yet. /help shows what works today.`, 'warn');
+        return say(`Unknown command ${cmd}. Try /help`, 'warn');
+      }
+    }
+  }
+
+  function onEnter(now) {
+    if (now - K.current.lastPasteAt < PASTE_GUARD_MS) return; // post-paste guard
+    if (now - K.current.cardGoneAt < CARD_GONE_MS) return; // keys meant for the card must not send a turn
+    const buf = B.current;
+    if (buf.text.endsWith('\\')) { edit({ type: 'set', text: buf.text.slice(0, -1) + '\n', keepPastes: true }); return; }
+    if (!buf.text.trim()) {
+      const s = S.current;
+      if (!s.turn && s.pending.length) { dispatch({ type: 'queue.shift' }); const n = s.pending[0]; dispatch({ type: 'user', text: n.text, queued: true }); runTurn(n.text); }
+      return;
+    }
+    const chk = sanitizeForSend(buf);
+    if (!chk.ok) { B.current = { ...chk.buffer, undo: buf.undo, redo: buf.redo }; say(chk.note, 'warn'); bump(n => n + 1); return; }
+    const text = chk.text.trim();
+    const keyHit = looksLikeKey(text);
+    if (keyHit) { B.current = initialBuffer(); R.current.confirmMulti = null; say(keyWarning(keyHit), 'warn'); return; } // never sent, never in history
+    const s = S.current;
+    const isCommand = text.startsWith('/') && !text.includes('\n');
+    if (blocked && !isCommand) { say(blocked, 'warn'); return; }
+    if (text.startsWith('/') && text.includes('\n') && R.current.confirmMulti !== text) {
+      // commands are one line: never ship a multi-line "/..." draft to the model without an explicit second Enter
+      R.current.confirmMulti = text;
+      if (!R.current.multiWarned) {
+        R.current.multiWarned = true;
+        say('That draft starts with / but has several lines, so it is not a command. Press Enter again to send it to Quox as chat, or edit it (Esc Esc clears it).', 'warn');
+      }
+      return;
+    }
+    R.current.confirmMulti = null; R.current.multiWarned = false;
+    B.current = initialBuffer();
+    if (text.startsWith('/') && !text.includes('\n')) { command(text); return; }
+    if (s.turn && !R.current.caps.steer) { // steering already refused for this turn: queue, say so once
+      dispatch({ type: 'queue.add', text });
+      if (!R.current.steerNoted) { R.current.steerNoted = true; say(STEER_OFF_NOTE, 'warn'); }
+      return;
+    }
+    if (s.turn) { steer(text); return; }
+    submit(text);
+  }
+
+  /** Returns true when the text was consumed as an approval key, false when it is ordinary typing. */
+  function approvalKey(name, text, now) {
+    const card = S.current.approvals[0];
+    if (!card) return false;
+    const ch = text || '';
+    const g = K.current.guard;
+    const armedAt = card.displayedAt ?? card.shownAt;
+    // With a draft in progress, a/d/o are ordinary text unless the card has focus (Tab).
+    if (B.current.text && !K.current.cardFocus) return false;
+    if (card.undescribable) {
+      // no one-key approve for an action Quox cannot describe: the word must be typed, fresh
+      if (ch === 'd' && approvalKeyAllowed({ now, shownAt: armedAt, lastKeyAt: K.current.lastKeyAt, heldKey: g?.heldKey, ch })) { answer(card, 'reject'); return true; }
+      if (now - armedAt < 300) return true;
+      K.current.typed = (K.current.typed + ch.toLowerCase()).slice(-APPROVE_WORD.length);
+      if (K.current.typed === APPROVE_WORD) { K.current.typed = ''; answer(card, 'approve'); }
+      return true;
+    }
+    if (!['a', 'd', 'o'].includes(ch)) return false; // ordinary typing: the draft keeps it
+    if (!approvalKeyAllowed({ now, shownAt: armedAt, lastKeyAt: K.current.lastKeyAt, heldKey: g?.heldKey, ch })) return true;
+    if (ch === 'o') { say(`open: ${card.url || '(no link)'}`); return true; }
+    const action = ch === 'a' ? 'approve' : 'reject';
+    answer(card, action);
+    return true;
+  }
+
+  const rosterOn = () => { const ro = R.current.roster; return ro.on && ro.rows.length > 0 && rosterView({ rows: ro.rows, cols, termRows: termRows(stdout) ?? 40 }).mode === 'full'; };
+  function focusRoster() { const ro = R.current.roster; ro.focus = true; ro.sel = Math.min(ro.sel, Math.min(ro.rows.length, MAX_ROSTER) - 1); ro.peek = false; ro.confirm = null; bump(n => n + 1); }
+  function leaveRoster() { const ro = R.current.roster; ro.focus = false; ro.peek = false; ro.confirm = null; bump(n => n + 1); }
+  /** Keys while the roster has focus. Returns true when consumed. */
+  function rosterKey(name, text) {
+    const ro = R.current.roster;
+    const visible = Math.min(ro.rows.length, MAX_ROSTER);
+    if (!visible) { leaveRoster(); return false; }
+    if (ro.confirm) { // any key answers; only y stops
+      const row = ro.confirm; ro.confirm = null;
+      if (text === 'y') stopRow(row); else { say('Stop cancelled.'); bump(n => n + 1); }
+      return true;
+    }
+    if (name === 'up') { ro.sel = Math.max(0, ro.sel - 1); ro.peek = false; bump(n => n + 1); return true; }
+    if (name === 'down') { ro.sel = Math.min(visible - 1, ro.sel + 1); ro.peek = false; bump(n => n + 1); return true; }
+    if (name === 'enter') { ro.peek = !ro.peek; bump(n => n + 1); if (ro.peek && ro.rows[ro.sel]?.kind === 'workflow') command(`/workflow ${ro.rows[ro.sel].id}`); return true; }
+    if (name === 'escape') { if (ro.peek) { ro.peek = false; bump(n => n + 1); } else leaveRoster(); return true; }
+    if (text === 's') { ro.confirm = ro.rows[ro.sel]; ro.peek = false; bump(n => n + 1); return true; }
+    if (text) { leaveRoster(); return false; } // ordinary typing goes to the draft
+    return true; // other keys are swallowed while focused
+  }
+  async function stopRow(row) {
+    const ro = R.current.roster;
+    if (!api.stopRow) return say('Stop not available on this server.', 'warn');
+    const r = await api.stopRow(row);
+    if (r.unavailable) return say(`Stop not available for ${row.kind} "${clip(row.name, 40)}": no governed stop route exists.`, 'warn');
+    say(r.message, r.ok ? undefined : 'warn');
+    if (r.ok) { refreshRoster(); }
+    return ro;
+  }
+
+  function onKey(e, now) {
+    const s = S.current;
+    const busy = Boolean(s.turn);
+    const name = e.name;
+    if (name === 'ctrl-c') {
+      if (B.current.text) { edit({ type: 'clear' }); return; }
+      if (busy) { interrupt(); return; }
+      if (K.current.ctrlC) return exit();
+      K.current.ctrlC = 1; say('Press Ctrl+C again to quit.');
+      clearTimeout(R.current.ctrlCTimer);
+      R.current.ctrlCTimer = setTimeout(() => { K.current.ctrlC = 0; }, 1500);
+      return;
+    }
+    if (name === 'ctrl-d') { if (!B.current.text) exit(); return; }
+    if (R.current.roster.focus && !s.approvals.length && rosterKey(name)) return;
+    if (!s.approvals.length && PL.current.onKey(name)) { bump(n => n + 1); return; }
+    if (name === 'escape') {
+      if (busy) { interrupt(); return; }
+      if (now - K.current.lastEscAt < ESC_ESC_MS && B.current.text) {
+        if (looksLikeKey(B.current.text)) { edit({ type: 'clear' }); say('Draft cleared. It looked like a key, so it was not kept.'); }
+        else { R.current.history.push(B.current.text); edit({ type: 'clear' }); say('Draft cleared (Up recalls it).'); }
+      }
+      K.current.lastEscAt = now; return;
+    }
+    // with a card up only draft-editing keys work (so the draft can be cleared); nothing submits or recalls
+    if (s.approvals.length && !CARD_EDIT_KEYS.includes(name)) return;
+    switch (name) {
+      case 'enter': return onEnter(now);
+      case 'shift-enter': case 'newline': return edit({ type: 'newline' });
+      case 'tab':
+        if (busy && B.current.text.trim()) { const t = sanitizeForSend(B.current); if (!t.ok || looksLikeKey(t.text)) return onEnter(now); dispatch({ type: 'queue.add', text: t.text.trim() }); B.current = initialBuffer(); bump(n => n + 1); }
+        return;
+      case 'backspace': return edit({ type: 'backspace' });
+      case 'delete': return edit({ type: 'delete' });
+      case 'delete-word': return edit({ type: 'deleteWordBack' });
+      case 'kill-line': return edit({ type: 'killLineBack' });
+      case 'left': case 'right': case 'home': case 'end': return edit({ type: name });
+      case 'word-left': case 'word-right': return edit({ type: name === 'word-left' ? 'left' : 'right' });
+      case 'undo': return edit({ type: 'undo' });
+      case 'redo': return edit({ type: 'redo' });
+      case 'up': {
+        if (B.current.text === '' && s.pending.length) { const last = s.pending[s.pending.length - 1]; dispatch({ type: 'queue.pop' }); edit({ type: 'set', text: last.text }); return; }
+        if (!B.current.text.slice(0, B.current.cursor).includes('\n')) {
+          const hist = R.current.history;
+          if (B.current.text === '' || R.current.histIdx >= 0) {
+            const i = R.current.histIdx < 0 ? hist.length - 1 : Math.max(0, R.current.histIdx - 1);
+            if (hist[i] !== undefined) { R.current.histIdx = i; edit({ type: 'set', text: hist[i] }); }
+          }
+          return;
+        }
+        return edit({ type: 'up' });
+      }
+      case 'down': {
+        if (B.current.text === '' && R.current.histIdx < 0 && rosterOn()) { focusRoster(); return; }
+        if (!B.current.text.slice(B.current.cursor).includes('\n') && R.current.histIdx >= 0) {
+          const i = R.current.histIdx + 1;
+          if (i >= R.current.history.length) { R.current.histIdx = -1; edit({ type: 'clear' }); } else { R.current.histIdx = i; edit({ type: 'set', text: R.current.history[i] }); }
+          return;
+        }
+        return edit({ type: 'down' });
+      }
+      case 'ctrl-g': {
+        const full = sanitizeForSend({ ...B.current }).text ?? B.current.text;
+        if (isRawModeSupported) setRawMode(false);
+        const out = editor(full);
+        if (isRawModeSupported) setRawMode(true);
+        if (out !== null && out !== undefined) edit({ type: 'set', text: out });
+        return;
+      }
+      case 'ctrl-s': {
+        if (B.current.text) { R.current.stash.push(B.current.text); edit({ type: 'clear' }); say('Draft stashed. Ctrl+S on an empty composer restores it.'); }
+        else if (R.current.stash.length) edit({ type: 'set', text: R.current.stash.pop() });
+        return;
+      }
+      default:
+    }
+  }
+
+  const onData = React.useRef(null);
+  const handleEvents = (events, now, burst) => {
+    for (const e of events) {
+      if (e.type === 'focus') { SND.current.focus(e.focused); continue; } // CSI I / CSI O, never a key
+      if (CN.current.isOpen()) { CN.current.onEvent(e); K.current.lastKeyAt = now; K.current.lastKeyCh = null; continue; } // the secure card takes every key
+      if (PK.current.isOpen() && !S.current.approvals.length) { PK.current.onEvent(e); K.current.lastKeyAt = now; K.current.lastKeyCh = null; continue; } // /resume, /config
+      const card = S.current.approvals[0];
+      const g = K.current.guard;
+      // any different key ends the "this key was already down" suppression
+      if (g?.heldKey && !(e.type === 'text' && e.text === g.heldKey)) g.heldKey = null;
+      if (card && e.type === 'key' && e.name === 'tab') { if (B.current.text) { K.current.cardFocus = true; bump(n => n + 1); } K.current.lastKeyAt = now; K.current.lastKeyCh = null; continue; }
+      if (card && e.type === 'key' && e.name === 'escape' && K.current.cardFocus) { K.current.cardFocus = false; bump(n => n + 1); K.current.lastKeyAt = now; K.current.lastKeyCh = null; continue; }
+      if (e.type === 'paste') {
+        K.current.lastPasteAt = now;
+        edit({ type: 'paste', text: e.text }); // a card never discards a paste
+      } else if (e.type === 'text') {
+        if (card && approvalKey('text', e.text, now)) { /* consumed by the approval dialog */ }
+        else if (!card && R.current.roster.focus && rosterKey(null, e.text)) { /* consumed by the roster */ }
+        else edit({ type: 'insert', text: e.text });
+      } else if (e.type === 'key') {
+        if (card && !['escape', 'ctrl-c', ...CARD_EDIT_KEYS].includes(e.name)) { /* swallowed while approving */ }
+        else if (e.name === 'enter' && burst) edit({ type: 'newline' }); // startup keys only: never submitted
+        else onKey(e, now);
+      }
+      K.current.lastKeyAt = now;
+      K.current.lastKeyCh = e.type === 'text' ? e.text : null;
+    }
+  };
+  onData.current = (chunk) => {
+    const now = Date.now();
+    finishIntroRef.current();
+    // Enter is a newline only inside a real paste (bracketed, or several lines in one chunk: keys.js).
+    // Its timing relative to the previous chunk says nothing: tmux, expect and SSH batch segments.
+    const burst = false;
+    K.current.lastDataAt = now;
+    const parsed = parseChunk(typeof chunk === 'string' ? chunk : chunk.toString('utf8'), K.current.keys);
+    K.current.keys = parsed.state;
+    clearTimeout(K.current.danglingTimer);
+    if (hasDangling(parsed.state)) {
+      K.current.danglingTimer = setTimeout(() => {
+        const f = flushDangling(K.current.keys);
+        K.current.keys = f.state;
+        handleEvents(f.events, Date.now(), false); // as paste text: inserted, never submitted
+        bump(n => n + 1);
+      }, PASTE_DANGLING_MS);
+    }
+    handleEvents(parsed.events, now, burst);
+  };
+
+  // QUOXON J2: `quox --conversation <id>` opens that conversation interactively.
+  React.useEffect(() => {
+    if (!resumeConversation || !api.conversationTurns) return undefined;
+    let live = true;
+    api.conversationTurns(resumeConversation).then((turns) => {
+      if (!live) return;
+      if (!turns.length) {
+        // C5: the conversation's first turn may still be running (nothing is stored until it ends).
+        return api.runningTurn?.(resumeConversation).then((r) => {
+          if (!live) return;
+          if (r?.running) { dispatch({ type: 'ctx', ctx: { conversationId: resumeConversation } }); followTurn(resumeConversation, r.turnId); return; }
+          say(`No saved turns for conversation ${resumeConversation} (not yours, expired after 7 days, or a typo). Starting a new conversation.`, 'warn');
+        }) ?? say(`No saved turns for conversation ${resumeConversation} (not yours, expired after 7 days, or a typo). Starting a new conversation.`, 'warn');
+      }
+      dispatch({ type: 'resume', conversationId: resumeConversation, turns });
+      return reattachIfRunning(resumeConversation);
+    }, (e) => { if (live) dispatch({ type: 'error', text: `could not load conversation ${resumeConversation}: ${e?.status ? `HTTP ${e.status}: ` : ''}${e?.message || 'failed'}` }); });
+    return () => { live = false; };
+  }, []);
+  React.useEffect(() => {
+    if (!startup) return undefined;
+    let live = true;
+    Promise.resolve().then(startup).then((note) => { if (live && note) say(note, 'warn'); }, () => {});
+    return () => { live = false; };
+  }, []);
+  React.useEffect(() => { // --demo plays by itself
+    if (!autoplay) return undefined;
+    const t = setTimeout(() => { if (!S.current.turn && !R.current.closed) { dispatch({ type: 'user', text: autoplay }); runTurn(autoplay); } }, 600);
+    return () => clearTimeout(t);
+  }, []);
+  React.useEffect(() => {
+    if (!stdin) return undefined;
+    if (isRawModeSupported) setRawMode(true);
+    if (stdout?.isTTY) stdout.write(PASTE_ON);
+    const fn = (d) => onData.current(d);
+    if (earlyInput) { // keys typed during startup: into the draft as typed, never submitted, never a paste-submit
+      earlyInput.detach();
+      for (const chunk of earlyInput.chunks.splice(0)) {
+        const parsed = parseChunk(chunk, K.current.keys);
+        K.current.keys = parsed.state;
+        handleEvents(parsed.events, Date.now(), true);
+      }
+    }
+    stdin.on('data', fn);
+    return () => {
+      R.current.closed = true;
+      R.current.abort?.abort(); // closing quoxon cancels the active stream (and its HTTP body)
+      for (const k of ['fallbackTimer', 'ctrlCTimer']) clearTimeout(R.current[k]);
+      clearTimeout(K.current.danglingTimer);
+      for (const t of R.current.pollTimers) clearTimeout(t);
+      R.current.pollTimers.clear();
+      R.current.pollWake?.();
+      stdin.off('data', fn);
+      if (stdout?.isTTY) stdout.write(PASTE_OFF);
+      SND.current?.dispose?.(); // focus reporting off: it must not outlive the client (or leak into a /restart child)
+      if (isRawModeSupported) setRawMode(false);
+    };
+  }, [stdin]);
+
+  // ---- view ----------------------------------------------------------------------------------
+  // Height of everything below the live blocks, measured after each layout; sizes the live region next frame.
+  React.useLayoutEffect(() => { if (chromeRef.current) chromeH.current = measureElement(chromeRef.current).height; });
+  // Frame cost (tick -> React commit), for measurement only (motionStats prop; tests and the bench).
+  React.useLayoutEffect(() => {
+    if (!motionStats || R.current.tickPerf == null) return;
+    (motionStats.costs ||= []).push(performance.now() - R.current.tickPerf);
+    R.current.tickPerf = null;
+  });
+  const s = S.current;
+  const busy = Boolean(s.turn);
+  // Reveals: register what just landed, then give <Static> every leading item whose reveal has ended.
+  const nowR = Date.now();
+  let pendingHist = [];
+  if (introDone.current) {
+    if (!motionOn) committedRef.current = s.history.length;
+    else {
+      for (let i = committedRef.current; i < s.history.length; i++) registerFx(s.history[i], nowR);
+      for (const b of s.blocks) registerFx(b, nowR);
+      // The newest protocol stage stays live (its icon pulses) while it is the last thing that happened in the turn.
+      const activeStage = (i) => isActiveStage(s, i);
+      while (committedRef.current < s.history.length && !fxActive(s.history[committedRef.current], nowR) && !activeStage(committedRef.current)) fxRef.current.delete(s.history[committedRef.current++].id);
+      pendingHist = s.history.slice(committedRef.current);
+      for (const r of R.current.roster.rows) if (!rosterSeen.current.has(r.key)) rosterSeen.current.set(r.key, nowR);
+    }
+  }
+  lastAppRender.current = nowR;
+  // Composer ring: motion and colour both on. Thinking/tools cyan-purple, writing green, approval amber.
+  const ring = motionOn && !mono() ? { ref: ringRef, active: busy, mode: ringMode({ approvals: s.approvals.length, act: s.turn?.act }) } : null;
+  const card = s.approvals[0];
+  const armed = card ? Date.now() - (card.displayedAt ?? card.shownAt) >= 300 : false;
+  R.current.armedShown = armed;
+  const ctxParts = [profile, org, modelLabel(s.ctx, MC.current), demoLabel ? 'demo' : mode, R.current.rulesOn === false ? (rulesLabel(rules) ? 'rules: off' : null) : rulesLabel(rules)];
+  const caps = R.current.caps;
+  const hint = busy ? `${caps.steer ? 'Enter steer' : 'Enter queue'} · Tab queue · ${caps.interrupt ? 'Esc stop' : 'Esc disconnects'}` : 'Enter send · /help';
+  const placeholder = busy ? (caps.steer ? 'Type to steer (Enter) or queue (Tab)' : 'Type to queue (Enter or Tab)') : 'Ask Quox anything…';
+
+  // The live region (unsettled blocks + chrome) must stay SHORTER than the screen: log-update can only
+  // erase rows that are still on screen, and Ink's own tall-frame path loses a line of history (term.js).
+  // A tall live tail shows its latest lines; the whole block prints to <Static> in full once it settles.
+  function liveRegion(kids) {
+    const rows = termRows(stdout);
+    if (!rows || !kids.length) return kids;
+    const max = Math.max(2, rows - (chromeH.current ?? 8) - 2);
+    if (liveRows([...pendingHist, ...s.blocks], cols) <= max) return kids;
+    return [
+      h(Box, { key: 'live-cap', paddingLeft: 2 }, h(Text, { color: c('dim'), wrap: 'truncate-end' }, clip('⋮ latest lines; the full reply prints when this part ends', cols - 2))),
+      h(Box, { key: 'live-clip', height: max - 1, overflow: 'hidden', flexDirection: 'column', justifyContent: 'flex-end' },
+        h(Box, { flexDirection: 'column', flexShrink: 0 }, ...kids))
+    ];
+  }
+
+  function rosterNode() {
+    const ro = R.current.roster;
+    const view = rosterView({ rows: ro.rows, cols, termRows: termRows(stdout) ?? 40, max: MAX_ROSTER, on: ro.on, sel: ro.sel, focus: ro.focus, now: Date.now() });
+    const row = ro.rows[ro.sel];
+    return h(Roster, {
+      view, cols,
+      peek: ro.focus && ro.peek ? peekLines(row, Date.now()) : [],
+      fx: motionOn ? (key) => rosterFx(key, Date.now()) : null,
+      confirm: ro.focus && ro.confirm ? `Stop ${ro.confirm.kind} "${clip(ro.confirm.name, 30)}"? y to stop, any other key cancels` : null,
+      hint: ro.focus && !ro.confirm ? '↑↓ select · Enter peek · s stop · Esc back' : null
+    });
+  }
+
+  return h(FrameContext.Provider, { value: framesRef.current }, h(Box, { flexDirection: 'column' },
+    // Nothing enters <Static> before the intro settles: Static is index-based, so prepending the intro to
+    // already-printed items would drop it (and reprint the rest).
+    h(Static, { key: `static-${epoch}`, items: introDone.current ? s.history.slice(0, committedRef.current) : [] }, (it) => h(Box, { key: it.id, flexDirection: 'column' }, h(HistoryItem, { item: it, cols }))),
+    introDone.current ? null : h(Box, { key: 'intro-live', flexDirection: 'column' }, h(Intro, { item: introItem, cols, eye, progress: Math.min(1, (Date.now() - introStart.current) / introMs) })),
+    liveRegion([
+      ...pendingHist.map((it, i) => h(Box, { key: it.id, flexDirection: 'column' }, h(FxItem, { item: it, cols, fxFor, active: busy && it.kind === 'trace' && i === pendingHist.length - 1 && !s.blocks.length }))),
+      ...s.blocks.map(b => h(Box, { key: b.id, flexDirection: 'column' }, motionOn && revealTimingFor(b) ? h(FxItem, { item: b, cols, live: true, fxFor }) : h(HistoryItem, { item: b, cols, live: true })))]),
+    h(EyeLive, { key: 'eye', cols }),
+    h(Box, { key: 'chrome', ref: chromeRef, flexDirection: 'column' },
+    busy ? h(Working, { key: 'working', motion: motionOn, tokens: turnTokens(s.turn), act: s.turn.act, activity: describeActivity(s), since: s.turn.startedAt, interrupting: s.turn.status === 'interrupting', escLabel: caps.interrupt ? null : 'Esc disconnects' }) : null,
+    card ? h(ApprovalCard, { card, org: org || api.orgId?.() || null, cols, armed, motionE: motionOn && nowR - (card.displayedAt ?? card.shownAt) < 1000 ? (nowR - (card.displayedAt ?? card.shownAt)) / 1000 : null, draftHint: B.current.text ? (K.current.cardFocus ? 'focus' : 'draft') : null }) : null,
+    // TODO(contract v2): background agents. `background.status` is NOT in events v1, so nothing sets s.background today.
+    s.background > 0 ? h(Box, { paddingLeft: 2 }, h(Text, { color: c('dim') }, `Waiting for ${s.background} background agent${s.background === 1 ? '' : 's'} to finish`)) : null,
+    h(Pending, { pending: s.pending, steering: s.steering, cols }),
+    h(Box, { marginTop: 1 }),
+    CN.current.isOpen() ? h(ConnectCard, { ...CN.current.view(), cols })
+      : ring ? h(RingComposer, { buf: B.current, cols, mode: demoLabel ? 'demo' : mode, busy, placeholder, name: SN.current.name, ring })
+        : h(Composer, { buf: B.current, cols, mode: demoLabel ? 'demo' : mode, busy, placeholder, name: SN.current.name }),
+    !CN.current.isOpen() && PK.current.isOpen() && !card ? h(ListView, { ...PK.current.view(), cols }) : !CN.current.isOpen() && PL.current.isOpen() && !card ? h(ListView, { ...PL.current.view(), cols }) : null,
+    h(StatusLine, { cols, slot: where.current.slot, agent: where.current.agent, parts: ctxParts, right: hint }),
+    h(NotifyBar, { approvals: s.notify.approvals, error: s.notify.error, cols, signedOut: Boolean(blocked), alerts: R.current.roster.all ? [] : R.current.roster.alerts }),
+    rosterNode())));
+}
+
+/** A live item that may be revealing: re-renders on every clock frame by itself (not the app). */
+function FxItem({ item, cols, live = false, fxFor, active = false }) {
+  const now = useFrame();
+  const pulse = (item.kind === 'tool' && item.status === 'running') || active ? now : null;
+  return h(HistoryItem, { item, cols, live, fx: fxFor(item, now), pulse });
+}
+export { COLORS };