quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/main.js

@@ -0,0 +1,176 @@
+import React from 'react';
+import { render } from 'ink';
+import { realpathSync } from 'node:fs';
+import { App } from './app.js';
+import { inkRenderOptions, inkStdout } from './term.js';
+import { createDemoApi } from './demo.js';
+import { DEMO_LABEL } from './demo.fixtures.js';
+import { AUTOPLAY_LABEL, autoplayOn } from './demo.autoplay.js';
+import { captureEarlyInput } from './earlyInput.js';
+import { shouldShowWelcome, markWelcomeSeen } from './welcome.js';
+import { loadRules, rulesContext } from './rules.js';
+import { createTranscript } from './transcript.js';
+import { createScreenRecorder, screenFramesEnabled } from './screenFrames.js';
+import { applySettings } from './slash/settings.js';
+import { headOf, RUNNING_ROOT, execRestart, restartPlan, checkRestart, startBuildWatch, settleMsFrom, restoreTerminal, RESTART_SLOT_ENV, RESTART_ATTACH_ENV, RESTART_NOTE_ENV, RESTART_MODE_ENV } from './slash/restart.js';
+import { readLastSeen, writeLastSeen } from './away.js';
+import { fileHistory } from './promptHistory.js';
+import { takeLauncherHandoff, writeRestartHandoff, RESTART_EXIT_CODE } from './launcher.js';
+
+export { parseArgs, USAGE, pickProfile, choosePick, chatCredentialProblem, noServerConfigured, printAuthMessage } from './headless.js';
+import { parseArgs, USAGE, noServerConfigured, mainPrint, pickProfile, chatCredentialProblem } from './headless.js';
+
+export { captureEarlyInput } from './earlyInput.js';
+
+/**
+ * Clear the screen before the chat client? Never right after Getting started: its finale (the one-time
+ * dashboard link, a password shown once) is on screen and in scrollback, and ESC[3J would erase both.
+ */
+export function shouldClearBeforeChat({ isTTY, noClear, fromGettingStarted }) {
+  return Boolean(isTTY) && !noClear && !fromGettingStarted;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  // Raw mode FIRST: the awaits below (module loads, config, health) must not leave the tty cooked.
+  // bin/quox.js already turned it on before loading anything heavy; this returns that same capture.
+  const early = !opts.print ? captureEarlyInput() : null;
+  if (opts.help) { early?.release(); console.log(USAGE); return; }
+  if (opts.errors.length) { early?.release(); process.stderr.write(`quox: ${opts.errors.join('; ')}\n${USAGE}\n`); process.exitCode = 1; return; }
+  const cwd = process.cwd().replace(process.env.HOME || '\0', '~');
+  const { resolveCliVersion } = await import('../core/version.js');
+  let version = '0.3.1';
+  try { version = resolveCliVersion?.() || version; } catch { /* keep default */ }
+  if (opts.print) return mainPrint(opts);
+  let replay = null;
+  let fromGettingStarted = false;
+  if (opts.demoOnboarding || (!opts.demo && await noServerConfigured(opts, await import('../core/config.js')))) {
+    // Getting started (FIRST_RUN_JOURNEY.md C2a): a separate view, never the chat client talking.
+    if (process.stdout.isTTY && !opts.noClear) process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+    const welcome = shouldShowWelcome({ print: false });
+    if (welcome && !opts.demoOnboarding) markWelcomeSeen();
+    const { runGettingStarted } = await import('./onboarding/index.js');
+    const r = await runGettingStarted({ version, cwd, welcome, earlyInput: early, demo: opts.demoOnboarding });
+    if (r?.action !== 'connected') return;
+    // signed in (an existing server, or the one just installed): carry on into the conversation,
+    // and a fresh install replays the original request as the first real turn
+    replay = r.replay || null;
+    fromGettingStarted = true;
+  }
+  let props;
+  let restart = null; // set by /restart: run the installed quox here once the app has let go of the terminal
+  if (opts.demo) {
+    const auto = autoplayOn(opts.autoplay) ? { exitAfterMs: opts.autoplayExit != null ? opts.autoplayExit * 1000 : (process.env.QUOX_DEMO_AUTOPLAY_EXIT ? Number(process.env.QUOX_DEMO_AUTOPLAY_EXIT) * 1000 : null) } : null;
+    // /restart works in the demo too (a fresh demo, nothing to resume): the same hand-over, testable with no server
+    // QUOX_DEMO_DECISIONS: demo-only pty test seam for the walkthrough proofs (a decisions state file; never a real server)
+    props = { api: createDemoApi({ objects: true, decisionsFile: process.env.QUOX_DEMO_DECISIONS || null }), profile: 'demo', org: 'demo-org', demoLabel: auto ? AUTOPLAY_LABEL : DEMO_LABEL, autoplay: auto ? null : 'Show me what you can do (demo)', demoAuto: auto, onRestart: (r) => { restart = { ...r, conversationId: null }; }, onDemo: () => { restart = { demo: true }; }, restartCheck: checkRestart };
+  } 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);
+    const config = missing ? probe : cfgMod.loadConfig(pick.name);
+    const { createWindowClient, carryOrg, RESTART_ORG_ENV } = await import('./windowOrg.js');
+    const win = createWindowClient({ config, auth: createAuth(config), createClient }); // #1034: /org switch is window-scoped
+    const api = createApi({ ...win, 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 });
+    // Z2H: a dead session (refresh rejected) or a cleared login on a human profile is ONE signed-out state, answered
+    // by a single card and /login, not scattered digest/approvals/chat errors. Transient failures read as alive.
+    let signedOut = null;
+    if (!missing && !opts.serviceKey) {
+      if (problem && !pick.note) signedOut = { reason: null };
+      else if (!problem) {
+        const pr = await Promise.race([api.probeSession(), new Promise(r => setTimeout(() => r({ alive: true }), 4000))]).catch(() => ({ alive: true }));
+        if (!pr.alive) signedOut = { reason: pr.reason || null };
+      }
+    }
+    // The health probe runs inside the app (background); the UI is up and typing works immediately.
+    const startup = async () => {
+      if (signedOut) return null;
+      if (problem) return problem.message;
+      if (pick.note) return pick.note;
+      const hl = await api.health(8000);
+      return hl.ok ? null : hl.absent ? `No QuoxCORE running at ${hl.url}` : `QuoxCORE at ${hl.url} is not answering (${hl.status}); messages may be slow`;
+    };
+    // /restart hand-over: re-enter the predecessor window's org in this window only (the profile is untouched).
+    const carried = !missing && !signedOut && !problem ? await carryOrg(api, process.env) : (delete process.env.QUOX_RESTART_ORG, null);
+    const startupCarry = async () => (carried?.error ? `Could not re-enter org ${carried.id} after the restart (${carried.error}). This window is in the profile's org.` : startup());
+    const saved = api.settings();
+    applySettings(saved);
+    if (!opts.verboseSet) opts.verbose = ['off', 'on', 'full'].includes(saved.verbose) ? saved.verbose : 'off'; // protocol lines are opt-in: /verbose on
+    // PROFILE-SWITCH: build a signed-in profile's api for an in-place window switch (the App only asks after a y or
+    // /profile). The window org rides along; the profile file's default is never moved (loadConfig(name) is a lens).
+    const residentNames = () => (cfgMod.loadConfig().listResidentProfiles?.() || []).map(r => r.name);
+    const switchProfile = async (name, { org: winOrg = null } = {}) => {
+      const row = (cfgMod.loadConfig().listProfiles?.() || []).find(p => p.name === name);
+      if (!row || !row.loggedIn) return { ok: false, reason: 'not_signed_in' };
+      const c2 = cfgMod.loadConfig(name);
+      const a2 = createApi({ ...createWindowClient({ config: c2, auth: createAuth(c2), createClient }), config: c2 });
+      const pr = await Promise.race([a2.probeSession(), new Promise(r => setTimeout(() => r({ alive: true }), 4000))]).catch(() => ({ alive: true }));
+      if (!pr.alive) return { ok: false, reason: 'not_signed_in' };
+      const c = winOrg ? await carryOrg(a2, { [RESTART_ORG_ENV]: winOrg }) : null;
+      const note = c?.error ? `Could not re-enter org ${winOrg} (${c.error}); this window is in ${name}'s org.` : null;
+      return { ok: true, api: a2, agentLogin: residentNames().includes(name), orgName: (c && !c.error && c.name) || c2.getAuth?.()?.org_name || null, note };
+    };
+    const loginCandidates = profiles.filter(p => !p.loggedIn && !residentNames().includes(p.name)).map(p => p.name);
+    props = { api, switchProfile, loginCandidates, away: { read: readLastSeen, write: writeLastSeen }, modelChoice: opts.provider, resume: opts.resume ?? null, onRestart: (r) => { restart = r; }, onDemo: () => { restart = { demo: true }; }, restartCheck: checkRestart, buildWatch: (o) => startBuildWatch({ ...o, settleMs: settleMsFrom() }), startSha: headOf(RUNNING_ROOT), rules: loadRules(), profile: pname, agentLogin: (probe.listResidentProfiles?.() || []).some(r => r.name === pname), humanProfiles: profiles.filter(p => p.loggedIn && !(probe.listResidentProfiles?.() || []).some(r => r.name === p.name)).map(p => p.name), org: missing ? null : ((carried && !carried.error && carried.name) || config.getAuth?.()?.org_name || null), startup: startupCarry, healthRecheck: () => api.health(8000), blocked: problem && !signedOut ? problem.message : null, signedOut, autoplay: replay };
+  }
+  // Interactive start: a clean screen under the intro (never when piped; NO_COLOR still clears),
+  // except straight after Getting started, whose finale must stay readable.
+  if (shouldClearBeforeChat({ isTTY: process.stdout.isTTY, noClear: opts.noClear, fromGettingStarted })) process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+  // Z2H-R5 C: do not advertise /slot where the licence check says no (the server's own capabilities answer, short wait).
+  let slotsAvailable = true;
+  if (!opts.demo && process.stdout.isTTY && props.api?.capabilities && !props.signedOut && !props.blocked) {
+    try {
+      const caps = await Promise.race([props.api.capabilities(), new Promise(res => setTimeout(() => res(null), 2000))]);
+      const c = caps?.ok ? caps.capabilities.find(x => x.id === 'slots') : null;
+      if (c && c.availability === 'unavailable' && /not in your plan/i.test(String(c.reason || ''))) slotsAvailable = false;
+    } catch { /* unknown: leave the invite as it was */ }
+  }
+  const welcome = shouldShowWelcome({ print: opts.print });
+  if (welcome) markWelcomeSeen();
+  const transcript = opts.demo ? null : createTranscript({ meta: { version, cols: process.stdout.columns, rows: process.stdout.rows, profile: props.profile, org: props.org, cwd } });
+  const onResize = () => transcript?.resize(process.stdout.columns, process.stdout.rows);
+  if (transcript) process.stdout.on('resize', onResize);
+  // SCREEN-FRAMES: what the screen showed, settled, into the same local transcript (QUOX_SCREEN_FRAMES=0 turns it off).
+  const screenRec = transcript && process.stdout.isTTY && screenFramesEnabled(process.env)
+    ? createScreenRecorder({ write: (rec) => transcript.screen(rec), cols: () => process.stdout.columns, rows: () => process.stdout.rows })
+    : null;
+  const restartSlot = opts.demo ? null : (process.env[RESTART_SLOT_ENV] || null); delete process.env[RESTART_SLOT_ENV]; // one hand-over only
+  const restartAttach = opts.demo ? null : (process.env[RESTART_ATTACH_ENV] || null); delete process.env[RESTART_ATTACH_ENV];
+  const restartMode = opts.demo ? null : (process.env[RESTART_MODE_ENV] === 'plan' ? 'plan' : null); delete process.env[RESTART_MODE_ENV]; // PLAN MODE: window-scoped, carried once
+  const restartNote = opts.demo ? null : (process.env[RESTART_NOTE_ENV] || null); delete process.env[RESTART_NOTE_ENV]; // e.g. a failed /update, said once in the restarted client
+  if (restartNote && !props.introNote) props.introNote = restartNote;
+  const app = render(React.createElement(App, { ...props, restartSlot, restartAttach, ...(restartMode ? { mode: restartMode } : {}), welcome, tipStartup: !fromGettingStarted && !opts.demo && Boolean(process.stdout.isTTY), whatsNewStartup: !opts.demo && Boolean(process.stdout.isTTY), version, cwd, verbose: opts.verbose, earlyInput: early, sessionName: opts.name, resumeConversation: opts.conversation || null, invite: Boolean(process.stdout.isTTY) && !opts.name, slotsAvailable, transcript, historyStore: opts.demo ? null : fileHistory() }), inkRenderOptions(process.stdout, { tap: screenRec?.tap }));
+  try { await app.waitUntilExit(); screenRec?.stop(); transcript?.end(restart ? 'restart' : 'exit'); }
+  catch (e) { screenRec?.stop(); transcript?.end(`crash: ${e?.message || e}`); throw e; }
+  finally { screenRec?.stop(); process.stdout.off('resize', onResize); }
+  if (!restart) return;
+  if (restart.update) { // /update said y: the update owns the terminal (npm prompts, sudo), then the same restart either way
+    const { runUpdate } = await import('../core/selfUpdate.js');
+    const plan = restart.update;
+    restoreTerminal();
+    process.stdout.write(`\nUpdating quox: ${plan.command.display}\n`);
+    const u = runUpdate(plan);
+    if (u.ok) process.stdout.write(`\u2714 Update finished (exit 0). Restarting into this conversation\u2026\n`);
+    else {
+      const note = `Update failed: ${plan.command.display} ${u.error ? `could not start (${u.error})` : `exited ${u.code}`}. Restarting on the build that is installed now. Run it yourself to see why: ${plan.manual}`;
+      process.stdout.write(`\u2716 ${note}\n`);
+      process.env[RESTART_NOTE_ENV] = note; // the restarted client (same build) says it again in the conversation
+    }
+  }
+  // The app preflighted the installed quox before letting go, so a failure here is rare (it changed in between).
+  const how = { argv: restart.demo ? ['--demo', '--autoplay'] : argv, conversationId: restart.demo ? null : restart.conversationId, profile: opts.demo ? null : (restart.profile || props.profile), name: restart.name || opts.name || null, slot: restart.demo ? null : (restart.slot || null), attach: restart.demo ? null : (restart.attach || null), org: restart.demo ? null : (restart.org || null), mode: restart.demo ? null : (restart.mode || null), bin: restart.bin || undefined };
+  // QUOXON-RESTART-LEAK: under the launcher this process EXITS and the launcher runs the successor, so exactly one
+  // client stays alive per terminal. Without one (QUOX_NO_LAUNCHER=1) it falls back to waiting on a nested child.
+  const launched = takeLauncherHandoff();
+  if (launched && writeRestartHandoff(launched, restartPlan(how))) { restoreTerminal(); process.exitCode = RESTART_EXIT_CODE; return; }
+  const r = execRestart(how);
+  if (r.error) { process.stderr.write(`quox: could not restart (${r.bin}: ${r.error})${restart.conversationId ? `; resume with: quox --resume ${restart.conversationId}` : ''}\n`); process.exitCode = 1; return; }
+  process.exitCode = r.code;
+}

package/lib/quoxon/markdown.js

@@ -0,0 +1,341 @@
+/**
+ * Terminal markdown for QUOXON. `marked` supplies the LEXER only; every token is
+ * rendered by our own Ink components in the Quox style (no marked-terminal).
+ *
+ * Streaming contract:
+ *   splitSettled(text) -> { settled, rest }   settled = complete top-level blocks
+ *                                             (safe to move to <Static>), rest = the
+ *                                             unfinished tail (re-rendered live).
+ *   healInline(text)                          hides half-typed syntax in the live tail
+ *                                             (`**bo`, `` `co ``, `[txt](ht`).
+ *   An unclosed ``` fence is a single code token to the end of text, so it renders
+ *   as code while streaming and never as raw backticks.
+ */
+import React from 'react';
+import { Box, Text, Transform } from 'ink';
+import { graphemes } from './textBuffer.js';
+import { c, mono, gradient, bulletRole } from './theme.js';
+
+const h = React.createElement;
+
+import { lex, splitSettled } from './markdownSettle.js';
+
+export { lex, splitSettled }; // QUOXON-LATENCY: defined in markdownSettle.js so --print never loads Ink
+
+export function healInline(text) {
+  let t = text;
+  const fence = (t.match(/^ {0,3}(```|~~~)/gm) || []).length;
+  if (fence % 2 === 1) return t; // inside an open fence: leave verbatim, it renders as code
+  const cut = (i) => { t = t.slice(0, i); };
+  const ticks = (t.match(/`/g) || []).length;
+  if (ticks % 2 === 1) cut(t.lastIndexOf('`'));
+  const bold = t.split('**').length - 1;
+  if (bold % 2 === 1) cut(t.lastIndexOf('**'));
+  const tilde = t.split('~~').length - 1;
+  if (tilde % 2 === 1) cut(t.lastIndexOf('~~'));
+  const lb = t.lastIndexOf('[');
+  if (lb >= 0 && !/\]\([^)]*\)/.test(t.slice(lb)) && /^\[[^\]]*(\]\(?[^)\s]*)?$/.test(t.slice(lb))) cut(lb);
+  return t;
+}
+
+// ---- wrapped text ------------------------------------------------------------------------------
+/**
+ * Ink wraps with wrap-ansi `trim: false`: when a row fills the width exactly, the space before the next
+ * word starts the continuation row (" AI agents."). Drop that one space on wrapped rows (index > 0),
+ * after any leading colour codes. Width is unchanged, so layout and row counts are unaffected.
+ */
+export const dropLeadSpace = (line, i) => (i > 0 ? line.replace(/^((?:\x1b\[[0-9;]*m)*) /, '$1') : line);
+/** <Text> whose wrapped continuation rows never start with a stray space. */
+export const WText = (props) => h(Transform, { transform: dropLeadSpace }, h(Text, props));
+
+// ---- hyperlinks (OSC 8) --------------------------------------------------------------------------
+export function supportsHyperlinks(env = process.env, isTTY = Boolean(process.stdout?.isTTY)) {
+  if (!isTTY || env.NO_COLOR || env.QUOX_HYPERLINKS === '0') return false;
+  if (env.QUOX_HYPERLINKS === '1') return true;
+  if (env.KITTY_WINDOW_ID || env.WT_SESSION) return true;
+  if (['iTerm.app', 'WezTerm', 'vscode', 'ghostty'].includes(env.TERM_PROGRAM)) return true;
+  return Number(env.VTE_VERSION) >= 5000;
+}
+const osc8 = (url, text) => `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+
+// ---- inline ----------------------------------------------------------------------------------
+export function inlineText(tokens = []) {
+  return tokens.map(t => {
+    if (t.tokens) return inlineText(t.tokens);
+    if (t.type === 'br') return ' ';
+    return t.text ?? t.raw ?? '';
+  }).join('').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+}
+
+/** A heading word painted sky -> indigo -> violet, bold (plain bold under NO_COLOR). */
+export const Heading = ({ text, underline = false }) => h(Text, { bold: true, underline },
+  ...(mono() ? [String(text)] : gradient(text).map((g, i) => h(Text, { key: i, color: g.color }, g.ch))));
+
+/** Prose with numbers and quantities picked out in the number role. Characters unchanged. */
+const NUM = /(?<![\w.#/-])\d+(?:[.,:-]\d+)*(?:%|ms|s|k|m|h|d|x|KB|MB|GB)?(?!\w)/g;
+export function numberRuns(text, key = 'n') {
+  const s = String(text);
+  if (mono()) return [s];
+  const out = [];
+  let i = 0;
+  for (const m of s.matchAll(NUM)) {
+    if (m.index > i) out.push(s.slice(i, m.index));
+    out.push(h(Text, { key: `${key}#${m.index}`, color: c('number') }, m[0]));
+    i = m.index + m[0].length;
+  }
+  if (i < s.length) out.push(s.slice(i));
+  return out;
+}
+
+const unesc = (s) => String(s).replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+
+function inline(tokens = [], style = {}, key = 'i') {
+  return tokens.map((t, i) => {
+    const k = `${key}.${i}`;
+    switch (t.type) {
+      case 'strong': return h(Text, { key: k, bold: true, color: c('value') }, ...inline(t.tokens, style, k));
+      case 'em': return h(Text, { key: k, italic: true }, ...inline(t.tokens, style, k));
+      case 'del': return h(Text, { key: k, strikethrough: true }, ...inline(t.tokens, style, k));
+      case 'codespan': return mono()
+        ? h(Text, { key: k }, '`' + unesc(t.text) + '`')
+        : h(Text, { key: k, color: c('code'), backgroundColor: c('codeBg') }, ' ' + unesc(t.text) + ' ');
+      case 'br': return h(Text, { key: k }, '\n');
+      case 'link': {
+        const label = inlineText(t.tokens) || t.href;
+        const shown = supportsHyperlinks() ? osc8(t.href, label) : label;
+        return h(Text, { key: k }, h(Text, { color: c('sky'), underline: true }, shown),
+          label !== t.href ? h(Text, { color: c('muted') }, ` (${t.href})`) : null);
+      }
+      case 'image': return h(Text, { key: k, color: c('dim') }, `[image: ${t.text || t.href}]`);
+      case 'escape': return h(Text, { key: k }, t.text);
+      case 'html': return h(Text, { key: k, color: c('dim') }, t.text);
+      case 'text': return t.tokens ? h(Text, { key: k }, ...inline(t.tokens, style, k)) : h(Text, { key: k }, ...numberRuns(unesc(t.text), k));
+      default: return h(Text, { key: k }, unesc(t.text ?? t.raw ?? ''));
+    }
+  });
+}
+
+// ---- tables ----------------------------------------------------------------------------------
+const w = (s) => graphemes(s).length;
+const padTo = (s, n) => s + ' '.repeat(Math.max(0, n - w(s)));
+
+/** Hard-wrap plain text to `width` columns at word boundaries (long words split). Never drops text. Always >= 1 line. */
+export function wrapCell(text, width) {
+  const width_ = Math.max(1, width);
+  const out = [];
+  for (const para of String(text ?? '').split('\n')) {
+    let cur = '';
+    for (const word of para.split(/\s+/).filter(Boolean)) {
+      let g = graphemes(word).map(x => x.text);
+      if (cur && w(cur) + 1 + g.length <= width_) { cur += ' ' + word; continue; }
+      if (cur) { out.push(cur); cur = ''; }
+      while (g.length > width_) { out.push(g.slice(0, width_).join('')); g = g.slice(width_); }
+      cur = g.join('');
+    }
+    out.push(cur);
+  }
+  return out;
+}
+
+/**
+ * Plain-text table layout: { mode: 'grid'|'vertical', lines: [{ text, head?, rule? }] }. Pure, for tests.
+ * Grid when it fits, else vertical key/value blocks whose values wrap under a hanging indent. No cell is ever truncated
+ * (TUI-UX #3: the grounding warning named an id that sat in a clipped cell).
+ */
+export function layoutTable(header, rows, cols) {
+  const n = header.length;
+  const widths = header.map((hd, i) => Math.max(w(hd), ...rows.map(r => w(r[i] ?? '')), 1));
+  const total = widths.reduce((a, b) => a + b, 0) + 3 * (n - 1);
+  const gridLines = (ws) => {
+    const cellLines = (r) => {
+      const cells = r.map((cell, i) => wrapCell(cell ?? '', ws[i]));
+      const h_ = Math.max(...cells.map(x => x.length));
+      return Array.from({ length: h_ }, (_, k) => cells.map((x, i) => padTo(x[k] ?? '', ws[i])).join(' │ ').replace(/\s+$/, ''));
+    };
+    const rule = ws.map(x => '─'.repeat(x)).join('─┼─');
+    return [...cellLines(header).map(text => ({ text, head: true })), { text: rule, rule: true }, ...rows.flatMap(r => cellLines(r).map(text => ({ text })))];
+  };
+  if (total <= cols) return { mode: 'grid', lines: gridLines(widths) };
+  // vertical key: value, one block per row; values wrap under a hanging indent
+  const lines = [];
+  const keyW = Math.min(Math.max(...header.map(w)), Math.floor(cols / 3));
+  const valW = Math.max(8, cols - keyW - 2);
+  rows.forEach((r, ri) => {
+    if (ri) lines.push({ text: '' });
+    header.forEach((hd, i) => {
+      const keyLines = wrapCell(hd, keyW);
+      const val = wrapCell(r[i] ?? '', valW);
+      const count = Math.max(keyLines.length, val.length);
+      for (let k = 0; k < count; k++) lines.push({ text: `${padTo(keyLines[k] ?? '', keyW)}  ${val[k] ?? ''}`.replace(/\s+$/, ''), key: k === 0 ? keyW : undefined });
+    });
+  });
+  return { mode: 'vertical', lines };
+}
+
+function Table({ t, cols }) {
+  const header = t.header.map(x => inlineText(x.tokens));
+  const rows = t.rows.map(r => r.map(x => inlineText(x.tokens)));
+  const lay = layoutTable(header, rows, cols);
+  return h(Box, { flexDirection: 'column' }, ...lay.lines.map((l, i) => h(Text, {
+    key: i, bold: l.head, color: l.rule ? c('muted') : (l.head ? c('label') : undefined), wrap: 'wrap'
+  }, l.text || ' ')));
+}
+
+// ---- blocks ----------------------------------------------------------------------------------
+const rule = (cols, label) => {
+  if (!label) return '─'.repeat(cols);
+  const lead = `── ${label} `;
+  return lead + '─'.repeat(Math.max(0, cols - w(lead)));
+};
+
+/** Fenced code top rule: dim teal line, the language label in the icon role. Same characters as rule(). */
+function codeRule(cols, label) {
+  const line = rule(cols, label);
+  if (!label) return h(Text, { color: c('codeRule') }, line);
+  return h(Text, null, h(Text, { color: c('codeRule') }, '── '), h(Text, { color: c('icon') }, label), h(Text, { color: c('codeRule') }, line.slice(3 + label.length)));
+}
+
+function List({ t, cols, depth }) {
+  const start = typeof t.start === 'number' ? t.start : 1;
+  return h(Box, { flexDirection: 'column' }, ...t.items.map((it, i) => {
+    const marker = t.ordered ? `${start + i}.` : (depth % 2 ? '◦' : '•');
+    const mw = w(marker) + 1;
+    return h(Box, { key: i },
+      h(Box, { width: mw, flexShrink: 0 }, h(Text, { color: c(bulletRole(depth)) }, marker)),
+      h(Box, { flexDirection: 'column', flexGrow: 1, flexShrink: 1 }, ...blocks(it.tokens, cols - mw, depth + 1, `li${i}`)));
+  }));
+}
+
+function blocks(tokens = [], cols, depth = 0, key = 'b') {
+  const out = [];
+  tokens.forEach((t, i) => {
+    const k = `${key}.${i}`;
+    switch (t.type) {
+      case 'space': return;
+      case 'heading': {
+        out.push(h(Box, { key: k, marginTop: depth ? 0 : 1 }, h(Transform, { transform: dropLeadSpace }, h(Heading, { text: inlineStr(t.tokens), underline: t.depth === 1 && mono() }))));
+        return;
+      }
+      case 'paragraph': case 'text':
+        out.push(h(Box, { key: k }, h(WText, null, ...inline(t.tokens || [{ type: 'text', text: t.text }], {}, k))));
+        return;
+      case 'code': {
+        const lines = String(t.text).split('\n');
+        out.push(h(Box, { key: k, flexDirection: 'column', width: cols },
+          codeRule(cols, t.lang ? String(t.lang).split(/\s+/)[0] : ''),
+          ...lines.map((ln, j) => h(Text, { key: j, color: c('text') }, ln || ' ')),
+          h(Text, { color: c('codeRule') }, rule(cols))));
+        return;
+      }
+      case 'list': out.push(h(List, { key: k, t, cols, depth })); return;
+      case 'blockquote':
+        out.push(h(Box, { key: k },
+          h(Box, { width: 2, flexShrink: 0 }, h(Text, { color: c('label') }, '▎ ')),
+          h(Box, { flexDirection: 'column', flexGrow: 1, flexShrink: 1 }, ...blocks(t.tokens, cols - 2, depth + 1, k))));
+        return;
+      case 'hr': out.push(h(Text, { key: k, color: c('dim') }, '─'.repeat(cols))); return;
+      case 'table': out.push(h(Table, { key: k, t, cols })); return;
+      case 'html': out.push(h(Text, { key: k, color: c('dim') }, t.text.trim())); return;
+      case 'def': return;
+      default: out.push(h(Text, { key: k }, unesc(t.raw || '')));
+    }
+  });
+  return out;
+}
+
+/** Render markdown text. live = unfinished tail of a streaming answer. */
+export function Markdown({ text, cols, live = false }) {
+  const src = live ? healInline(text) : text;
+  if (!src.trim()) return null;
+  const kids = blocks(lex(src), cols).map((el, i) => h(Box, { key: el.key ?? i, marginTop: i ? 1 : 0, flexDirection: 'column' }, el));
+  return h(Box, { flexDirection: 'column', width: cols }, ...kids);
+}
+
+// ---- height (sizes the live region; must match what Ink lays out) ---------------------------------
+/** Rows one line takes in Ink's Text wrap (wrap-ansi 9, trim: false, hard: true), plain text only. */
+function wrapLineRows(line, cols) {
+  if (cols <= 0) return 1;
+  const words = line.split(' ');
+  const rows = [0];
+  words.forEach((word, i) => {
+    let len = rows[rows.length - 1];
+    const wl = w(word);
+    if (i !== 0) {
+      if (len >= cols) { rows.push(0); len = 0; }
+      rows[rows.length - 1] = ++len;
+    }
+    if (wl > cols) { // hard-break a word longer than the line
+      const remaining = cols - len;
+      const startHere = 1 + Math.floor((wl - remaining - 1) / cols);
+      const startNext = Math.floor((wl - 1) / cols);
+      if (startNext < startHere) rows.push(0);
+      let vis = rows[rows.length - 1];
+      const chars = graphemes(word);
+      chars.forEach((_, k) => {
+        if (vis + 1 <= cols) rows[rows.length - 1] = ++vis;
+        else { rows.push(1); vis = 1; }
+        if (vis === cols && k < chars.length - 1) { rows.push(0); vis = 0; }
+      });
+      if (!vis && rows.length > 1 && rows[rows.length - 1] === 0) rows.pop();
+      return;
+    }
+    if (len + wl > cols && len > 0 && wl > 0) { rows.push(0); len = 0; }
+    rows[rows.length - 1] = len + wl;
+  });
+  return rows.length;
+}
+
+/** Rows a plain string takes when Ink wraps it at `cols`. */
+export function wrapRows(text, cols) {
+  return String(text).replace(/\r\n/g, '\n').split('\n').reduce((n, l) => n + wrapLineRows(l, cols), 0);
+}
+
+function inlineStr(tokens = []) {
+  return tokens.map(t => {
+    switch (t.type) {
+      case 'strong': case 'em': case 'del': return inlineStr(t.tokens);
+      case 'codespan': return mono() ? '`' + unesc(t.text) + '`' : ' ' + unesc(t.text) + ' ';
+      case 'br': return '\n';
+      case 'link': { const label = inlineText(t.tokens) || t.href; return label + (label !== t.href ? ` (${t.href})` : ''); }
+      case 'image': return `[image: ${t.text || t.href}]`;
+      case 'escape': case 'html': return t.text;
+      case 'text': return t.tokens ? inlineStr(t.tokens) : unesc(t.text);
+      default: return unesc(t.text ?? t.raw ?? '');
+    }
+  }).join('');
+}
+
+/** Heights of the elements blocks() would produce, in order (space/def produce none). */
+function blockRows(tokens = [], cols, depth = 0) {
+  const out = [];
+  for (const t of tokens) {
+    switch (t.type) {
+      case 'space': case 'def': break;
+      case 'heading': out.push(wrapRows(inlineStr(t.tokens), cols) + (depth ? 0 : 1)); break;
+      case 'paragraph': case 'text': out.push(wrapRows(inlineStr(t.tokens || [{ type: 'text', text: t.text }]), cols)); break;
+      case 'code': out.push(2 + String(t.text).split('\n').reduce((n, ln) => n + wrapRows(ln || ' ', cols), 0)); break;
+      case 'list': {
+        out.push(t.items.reduce((n, it, i) => {
+          const marker = t.ordered ? `${(typeof t.start === 'number' ? t.start : 1) + i}.` : '•';
+          const inner = blockRows(it.tokens, cols - (w(marker) + 1), depth + 1).reduce((a, b) => a + b, 0);
+          return n + Math.max(1, inner);
+        }, 0));
+        break;
+      }
+      case 'blockquote': out.push(Math.max(1, blockRows(t.tokens, cols - 2, depth + 1).reduce((a, b) => a + b, 0))); break;
+      case 'hr': out.push(1); break;
+      case 'table': out.push(layoutTable(t.header.map(x => inlineText(x.tokens)), t.rows.map(r => r.map(x => inlineText(x.tokens))), cols).lines.length); break;
+      case 'html': out.push(wrapRows(t.text.trim(), cols)); break;
+      default: out.push(wrapRows(unesc(t.raw || ''), cols));
+    }
+  }
+  return out;
+}
+
+/** Rows <Markdown text cols live/> occupies. Pure; mirrors Markdown() above. */
+export function markdownRows(text, cols, live = false) {
+  const src = live ? healInline(text) : text;
+  if (!src.trim()) return 0;
+  const rows = blockRows(lex(src), cols);
+  return rows.reduce((a, b) => a + b, 0) + Math.max(0, rows.length - 1);
+}

package/lib/quoxon/markdownSettle.js

@@ -0,0 +1,19 @@
+/**
+ * The streaming split, without the renderer. events.js (and so `quox --print`) needs only
+ * splitSettled; importing it from markdown.js loaded React + Ink (~2 s cold) on every
+ * headless turn before the request was even sent (QUOXON-LATENCY). markdown.js re-exports
+ * both names, so the interactive client is unchanged.
+ */
+import { Lexer } from 'marked';
+
+export const lex = (src) => new Lexer({ gfm: true, breaks: false }).lex(src);
+
+export function splitSettled(text) {
+  const tokens = lex(text);
+  let last = -1;
+  for (let i = tokens.length - 1; i >= 0; i--) if (tokens[i].type !== 'space') { last = i; break; }
+  if (last <= 0) return { settled: '', rest: text };
+  let off = 0;
+  for (let i = 0; i < last; i++) off += tokens[i].raw.length;
+  return { settled: text.slice(0, off), rest: text.slice(off) };
+}

package/lib/quoxon/matrixDomains.json

@@ -0,0 +1,46 @@
+{
+  "_comment": "Vendored from ~/cli.quox.ai/matrix/domains.json (the proof matrix, 40 domain ids). Source: https://github.com/quoxai/cli.quox.ai matrix/domains.json. Tips name a domain from this list so the matrix can ingest them. When the matrix becomes canonical this file is replaced by the matrix export.",
+  "domains": [
+    "chat",
+    "providers",
+    "approvals",
+    "receipts",
+    "safety",
+    "hats",
+    "fleet",
+    "proxmox",
+    "monitoring",
+    "lucid",
+    "memory",
+    "qortex",
+    "vault",
+    "agents",
+    "workflows",
+    "skills",
+    "objectives",
+    "mail",
+    "calendar",
+    "contacts",
+    "notes",
+    "actions",
+    "voice",
+    "quoxchat",
+    "seo",
+    "plan",
+    "signal",
+    "browser",
+    "lens",
+    "social",
+    "comms",
+    "sessions",
+    "code",
+    "security",
+    "spend",
+    "files",
+    "plugins",
+    "identity",
+    "install",
+    "compliance",
+    "mind"
+  ]
+}