quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/headless.js

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

package/lib/quoxon/hostUrls.js

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

package/lib/quoxon/inboxView.js

@@ -0,0 +1,79 @@
+/**
+ * HITL-INBOX-BAR (owner 2026-10-26): the owner's Quox inbox in the chat. Pure helpers: the status-area bar text,
+ * the arrival line, the /inbox table and the one-item view. No I/O here; app.js owns the calls.
+ */
+const clip = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, Math.max(0, n - 1))}…` : t; };
+const pad = (s, n) => { const t = clip(s, n); return t + ' '.repeat(Math.max(0, n - [...t].length)); };
+const ms = (v) => { const t = Date.parse(String(v ?? '').includes('T') || !v ? v : `${String(v).replace(' ', 'T')}Z`); return Number.isFinite(t) ? t : 0; };
+const CLOSED = new Set(['resolved', 'cancelled', 'expired', 'deleted', 'archived']);
+
+/** Newest first. */
+export const newestFirst = (items) => [...(Array.isArray(items) ? items : [])].filter((i) => i && i.id).sort((a, b) => ms(b.created_at ?? b.createdAt) - ms(a.created_at ?? a.createdAt));
+/** Unread = the server's per-user is_read flag is not set, and the item is not closed or archived. */
+export const isUnread = (it) => !it.is_read && !it.archived_at && !CLOSED.has(String(it.status || '').toLowerCase());
+export const unreadItems = (items) => newestFirst(items).filter(isUnread);
+
+/** The status-area line, or '' when nothing is unread: `📨 2 new · <newest title>`. */
+export function inboxBarText(items, cols = 80) {
+  const un = unreadItems(items);
+  if (!un.length) return '';
+  const head = `📨 ${un.length} new · `;
+  return head + clip(un[0].title || un[0].kind || 'untitled', Math.max(8, cols - 4 - [...head].length));
+}
+
+/** Unread items not seen on an earlier poll. `seen` is a Set of ids; the first poll seeds it and announces nothing. */
+export function arrivals(items, seen) {
+  const un = unreadItems(items);
+  const fresh = seen ? un.filter((i) => !seen.has(i.id)) : [];
+  return { fresh, ids: new Set((Array.isArray(items) ? items : []).map((i) => i?.id).filter(Boolean)) };
+}
+export const arrivalLine = (it) => `📨 ${clip(it.title || it.kind || 'untitled', 70)} · /inbox 1`;
+
+export const fromOf = (it) => String(it.created_by_name || it.payload?.source || it.payload?.approval_context?.source_label || it.source || it.inbox_type || it.kind || 'system');
+export function ageOf(v, now = Date.now()) {
+  const t = ms(v); if (!t) return '?';
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 90) return 'now';
+  if (s < 5400) return `${Math.round(s / 60)}m`;
+  if (s < 129600) return `${Math.round(s / 3600)}h`;
+  return `${Math.round(s / 86400)}d`;
+}
+
+/** The latest 10 as a compact table; unread rows carry a dot. -> [{ text, tone }] */
+export function inboxTable(items, now = Date.now(), cols = 100, max = 10) {
+  const rows = newestFirst(items).slice(0, max);
+  if (!rows.length) return [{ text: 'Your inbox is empty.', tone: 'dim' }];
+  const tw = Math.max(16, Math.min(60, cols - 40));
+  const out = [{ text: `  ${pad('#', 3)}${pad('when', 6)}${pad('from', 14)}${pad('title', tw)} state`, tone: 'dim' }];
+  rows.forEach((it, i) => {
+    const un = isUnread(it);
+    out.push({ text: `${un ? '●' : ' '} ${pad(i + 1, 3)}${pad(ageOf(it.created_at ?? it.createdAt, now), 6)}${pad(fromOf(it), 14)}${pad(it.title || it.kind || 'untitled', tw)} ${un ? 'unread' : (it.status || 'read')}`, tone: un ? 'accent' : 'dim' });
+  });
+  const un = unreadItems(items).length;
+  out.push({ text: `${un} unread · /inbox N open one · /inbox read N|all · /inbox open N (approvals)`, tone: 'dim' });
+  return out;
+}
+
+/** Arg grammar: '' | N | read N|all | open N. -> { kind, n?|all? } | { kind:'usage' } */
+export function parseInbox(arg) {
+  const a = String(arg || '').trim().toLowerCase();
+  if (!a || a === 'list' || a === 'latest') return { kind: 'list' };
+  let m = /^(?:show\s+)?#?(\d+)$/.exec(a); if (m) return { kind: 'show', n: Number(m[1]) };
+  m = /^open\s+#?(\d+)$/.exec(a); if (m) return { kind: 'open', n: Number(m[1]) };
+  m = /^read\s+(all|#?\d+)$/.exec(a); if (m) return m[1] === 'all' ? { kind: 'read', all: true } : { kind: 'read', n: Number(m[1].replace('#', '')) };
+  return { kind: 'usage' };
+}
+export const INBOX_USAGE = 'Usage: /inbox | /inbox N | /inbox read N|all | /inbox open N';
+
+/** One item in full. -> [{ text, tone }] */
+export function inboxDetail(it, now = Date.now()) {
+  const p = it.payload || {};
+  const body = it.body || it.message || p.message || p.body || p.summary || p.text || '';
+  const out = [{ text: `${it.title || it.kind || 'untitled'}`, tone: 'accent' },
+    { text: `from ${fromOf(it)} · ${ageOf(it.created_at ?? it.createdAt, now)} ago · ${it.kind || 'item'} · ${it.priority || 'normal'} · ${it.status || '?'}`, tone: 'dim' }];
+  if (body) for (const l of String(body).split('\n')) out.push({ text: l, tone: 'text' });
+  if (it.dashboard_url) out.push({ text: it.dashboard_url, tone: 'dim' });
+  return out;
+}
+/** Approval-type items route to /approvals (the existing view). */
+export const isApprovalItem = (it) => String(it.kind || '').toLowerCase() === 'approval' || Boolean(it.payload?.approval_context) || it.payload?.type === 'decision';

package/lib/quoxon/indicator.js

@@ -64,8 +64,10 @@ export function normUsage(u, doneCost) {
   const tokens = Number.isFinite(Number(out)) && out != null ? Number(out)
     : Number.isFinite(Number(total)) && total != null ? Number(total)
     : Number.isFinite(Number(inp)) && inp != null ? Number(inp) : null;
+  // cost_source 'claude-cli': the claude CLI's own API-equivalent estimate on the subscription path, not a price.
+  const costSource = typeof o.cost_source === 'string' ? o.cost_source : null;
   const cost = Number(o.cost_usd ?? doneCost);
-  return { tokens, cost: Number.isFinite(cost) && cost > 0 ? cost : null, real: tokens != null };
+  return { tokens, cost: !costSource && Number.isFinite(cost) && cost > 0 ? cost : null, real: tokens != null, costSource };
 }
 
 /** Live token figure: the real number once the server reported it, else an estimate from received text (~chars/4). */
@@ -82,7 +84,9 @@ export function turnTokens(turn) {
  * Sans Mono fallback (ｪｴ like I/E, ｭｮﾕﾖ boxes, ﾆ "=", ﾉ "/", ﾌ "7", ﾍ "^", ﾘ "U", ﾚ "L", ﾛ a box, ｰ a dash)
  * and the voiced marks ﾞ ﾟ.
  */
-export const SCRAMBLE_GLYPHS = 'ｦｧｨｩｫｬｯｱｲｳｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾇﾈﾊﾋﾎﾏﾐﾑﾒﾓﾔﾗﾙﾜﾝ';
+/** Decode glyphs: every half-width katakana (U+FF66-FF9D, one cell each, minus the long-vowel bar ｰ) plus the
+ * code-rain digits. Owner 2026-10-15: the reveal felt like "just a few characters" with 44 look-alike kana. */
+export const SCRAMBLE_GLYPHS = 'ｦｧｨｩｪｫｬｭｮｯｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝ0123456789';
 
 /** Deterministic hash in [0,1). */
 const hsh = (a, b, c = 0) => { let x = (a * 374761393 + b * 668265263 + c * 2147483647) | 0; x = Math.imul(x ^ (x >>> 13), 1274126177); return ((x ^ (x >>> 16)) >>> 0) / 4294967296; };

package/lib/quoxon/installCli.js

@@ -0,0 +1,79 @@
+/**
+ * LAZY-AI-CLI (owner 2026-10-19): "Quox can depend heavily on your choice or blend of Claude and OpenAI models.
+ * We advise installing both Claude Code and Codex." Draw people in step by step: when something needs a vendor CLI
+ * that is missing, offer to install it THEN, as a y/N.
+ *
+ * ONE flow behind `quox provider install` and the TUI offer cards (first-run suggestion + just-in-time), so they
+ * cannot drift. The server downloads the vendor's own npm package (never a binary Quox ships), as the Quox service
+ * user, into a volume that survives updates, audited start and finish (services/collector/routes/providerCli.js).
+ */
+import { detectCallerSource } from '../core/callerSource.js';
+
+export const INSTALL_TOOLS = {
+  'claude-code': { id: 'claude-code', name: 'Claude Code', vendor: 'Anthropic', bin: 'claude', after: 'Claude sign-in is available now: sign in from the dashboard Terminal, then pick Claude in /model.' },
+  codex: { id: 'codex', name: 'Codex', vendor: 'OpenAI', bin: 'codex', after: 'Codex is ready: sign in to ChatGPT from the dashboard Terminal (Codex), then pick it in /model.' },
+};
+
+export const SUGGEST_LINE = 'Quox works best with both Claude and OpenAI models. We suggest installing Claude Code and Codex.';
+
+const ALIASES = { claude: 'claude-code', 'claude-code': 'claude-code', claudecode: 'claude-code', codex: 'codex', 'openai-codex': 'codex' };
+export const toolFor = (s) => ALIASES[String(s || '').trim().toLowerCase()] || null;
+
+const sizeText = (p) => (p?.downloadMb ? `about ${p.downloadMb} MB` : null);
+
+export function planLine(p) {
+  const t = INSTALL_TOOLS[p?.id] || { name: p?.name || p?.id };
+  const size = sizeText(p);
+  return `${t.name} ${p?.version || ''} (${t.vendor ? `${t.vendor}'s ` : ''}${p?.package || ''}) from ${p?.source || 'registry.npmjs.org'}${size ? `, ${size} download` : ''}${p?.installedMb ? `, ${p.installedMb} MB on disk` : ''}. It installs on this server as the Quox service user and stays across updates.`.replace(/\s+/g, ' ');
+}
+
+export function offerQuestion(tool, plan) {
+  const t = INSTALL_TOOLS[tool];
+  const size = sizeText(plan);
+  return `${t.name} isn't installed on this server. Install it now? (${size ? `${size} from npm` : 'from npm'})`;
+}
+
+/** The CLIs the server says are missing, in a stable order. */
+export function missingTools(status) {
+  if (!status?.ok || !Array.isArray(status.tools)) return [];
+  return Object.keys(INSTALL_TOOLS).filter((id) => status.tools.some((t) => t.id === id && t.installed === false));
+}
+
+/** An agent (a session, an attached agent, a Claude process) never self-approves an install: it files a card. */
+export function isAgentCaller(env = process.env, detect = detectCallerSource) {
+  if (env.QUOX_AGENT_ID || env.QUOX_SESSION_ID || env.QUOX_SESSION) return true;
+  let src = null;
+  try { src = detect(env); } catch { src = null; }
+  if (!src) return false;
+  if (['attached_agent', 'held_slot', 'QUOX_STREAM'].includes(src.via)) return true;
+  return src.via === 'process' && /^claude\b/i.test(String(src.label || ''));
+}
+
+const POLL_MS = 3000;
+
+/**
+ * Start the server install and wait for it. Never throws.
+ * @returns {Promise<{ok:boolean, version?:string|null, lines:string[]}>}
+ */
+export async function runInstall(api, tool, { approvalId = null, onProgress = () => {}, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, timeoutMs = 15 * 60 * 1000 } = {}) {
+  const t = INSTALL_TOOLS[tool];
+  if (!t) return { ok: false, lines: [`No installable CLI called "${tool}". Use one of: ${Object.keys(INSTALL_TOOLS).join(', ')}`] };
+  const start = await api.providerCliInstall(tool, { approvalId });
+  if (!start?.ok || !start.job_id) {
+    if (start?.status === 404 || start?.status === 405) return { ok: false, lines: [`This Quox server is too old to install ${t.name} for you. Update it first: quox server update`] };
+    if (start?.status === 403) return { ok: false, lines: [`✖ ${start.error || 'Only an instance admin can install software on this server.'} Nothing was installed.`] };
+    return { ok: false, lines: [`✖ ${t.name} was not installed: ${start?.error || 'the server did not start the install'}`] };
+  }
+  const began = now();
+  let last = began;
+  for (;;) {
+    await sleep(POLL_MS);
+    const j = await api.providerCliJob(start.job_id);
+    if (j?.state === 'done' && j.ok) {
+      return { ok: true, version: j.version || null, lines: [`✔ ${t.name} ${j.version || ''} is installed on this server.`.replace(/\s+/g, ' ').replace(' .', '.'), t.after] };
+    }
+    if (j?.state === 'failed') return { ok: false, lines: [`✖ ${t.name} was not installed: ${j.error || 'the install failed'}`] };
+    if (now() - began >= timeoutMs) return { ok: false, lines: [`◐ ${t.name} is still running its install on the server. Check again shortly: quox provider list`] };
+    if (now() - last >= 15000) { last = now(); onProgress(`◐ installing ${t.name} (${Math.round((now() - began) / 1000)}s)`); }
+  }
+}

package/lib/quoxon/intent.js

@@ -13,14 +13,25 @@ const PANELS = [
 function PANEL_RULES() { return PANELS.map(([re, cmd]) => [re, () => cmd]); }
 
 const RULES = [
-  [new RegExp(`^attach(?: me)?(?: to)? ${WORD}$`, 'i'), (m) => `/attach ${m[1]}`],
+  // owner 2026-10-15: "attach to TRIAGE-Q agent" / "reattach to ..." took four turns; the tip must catch them
+  [new RegExp(`^(?:please )?(?:re)?attach(?: me)?(?: to)?(?: the)? ${WORD}(?: agent)?(?: please)?$`, 'i'), (m) => `/attach ${m[1].toLowerCase()}`],
   [/^rename (?:this|the|my) (?:session|conversation|chat) (?:to|as) ([\w.-]+(?: [\w.-]+){0,2})$/i, (m) => m[1].split(' ').some(w => /^(and|then|but|so|please)$/i.test(w)) ? null : `/rename ${m[1]}`],
   [/^(?:what(?:'s| is) running|what is running now)$/i, () => '/roster'],
   [/^(?:show|list|open) (?:my |the )?(?:pending )?approvals$/i, () => '/approvals'],
   [/^(?:what(?:'s| is)|show me what(?:'s| is)) (?:waiting|pending) (?:for )?(?:my )?approval$/i, () => '/approvals'],
+  [/^(?:so )?(?:what (?:did i miss|have i missed)(?: (?:while|when) i was (?:away|out|gone|offline))?|what (?:happened|changed) (?:while|when) i was (?:away|out|gone|offline)|(?:did )?anything happen(?:ed)? while i was (?:away|out|gone|offline)|catch me up)$/i, () => '/away'],
+  [/^(?:(?:give me |show me |can i get )?(?:a |the )?sit ?rep(?: please)?|what(?:'s| is) the situation(?: now)?|situation report(?: please)?)$/i, () => '/sitrep'],
+  [/^(?:how(?:'s| is) (?:the |my |our )?fleet(?: doing)?|(?:show|list) (?:me )?(?:the |my |our )?fleet|fleet (?:status|health)|what(?:'s| is) (?:the )?(?:state|health) of (?:the |my |our )?(?:fleet|computers|servers))$/i, () => '/fleet'],
+  [/^(?:open|show|take me to|go to) (?:me )?(?:to )?(?:the |my )?(?:quox )?(?:web )?dashboard$/i, () => '/dashboard'],
   [/^detach(?: from (?:the )?agent)?$/i, () => '/detach'],
+  [/^(?:clear|cls|clear (?:the )?screen)$/i, () => '/clear'], // owner typed bare "clear" (2026-10-15)
   [/^(?:start )?(?:a )?new conversation$/i, () => '/new'],
   [/^(?:please )?(?:compact|summari[sz]e and compact|compress) (?:this|the|our|my) (?:conversation|chat|session|context)(?: please)?$/i, () => '/compact'],
+  [/^(?:please )?(?:update|upgrade) (?:the |my |this )?(?:quox )?(?:server|install|instance|quox)(?: (?:to (?:the )?latest|please))?$/i, () => 'quox server update --dry-run (in a terminal; shows the plan first)'],
+  [/^(?:please )?roll ?back (?:the |my |this )?(?:quox )?(?:server|install|instance|update)$/i, () => 'quox server rollback --dry-run (in a terminal)'],
+  [/^(?:please )?uninstall (?:the |my |this )?(?:quox )?(?:server|install|instance|quox)$/i, () => 'quox server uninstall --dry-run (in a terminal; lists what goes first)'],
+  [/^(?:what version is (?:the |my )?(?:quox )?server(?: on| running)?|is (?:the |my )?(?:quox )?server (?:up to date|healthy)|server status)$/i, () => '/server'],
+  [/^(?:make|create|write) (?:a )?(?:support|diag(?:nostic)?s?) bundle$/i, () => 'quox server diag (in a terminal; written locally, never uploaded)'],
   ...PANEL_RULES()
 ];
 

package/lib/quoxon/keys.js

@@ -5,8 +5,21 @@
  *
  * parseChunk(chunk, state) -> { events, state }
  * Events: { type: 'text', text } | { type: 'paste', text } | { type: 'key', name, ctrl?, alt? } | { type: 'focus', focused }
+ *   | { type: 'mouse', action: 'press'|'release'|'drag'|'move'|'wheel', button, x, y, shift, alt, ctrl } (SGR 1006, QUOXON-MOUSE)
+ *   | { type: 'cursor', row, col } (a cursor position report, the answer to DSR ESC[6n)
  */
 
+const BUTTONS = ['left', 'middle', 'right', 'none'];
+const WHEEL = ['up', 'down', 'left', 'right'];
+/** One SGR mouse report (ESC [ < b ; x ; y M|m) as an event. */
+function mouseEvent(b, x, y, final) {
+  const low = b & 3;
+  const mods = { shift: Boolean(b & 4), alt: Boolean(b & 8), ctrl: Boolean(b & 16) };
+  if (b & 64) return { type: 'mouse', action: 'wheel', button: WHEEL[low], x, y, ...mods };
+  if (b & 32) return { type: 'mouse', action: low === 3 ? 'move' : 'drag', button: BUTTONS[low], x, y, ...mods };
+  return { type: 'mouse', action: final === 'm' ? 'release' : 'press', button: BUTTONS[low], x, y, ...mods };
+}
+
 export const PASTE_ON = '\x1b[?2004h';
 export const PASTE_OFF = '\x1b[?2004l';
 const PASTE_START = '\x1b[200~';
@@ -42,18 +55,27 @@ const CSI_KEYS = {
   '\x1b[1~': 'home', '\x1b[4~': 'end', '\x1b[7~': 'home', '\x1b[8~': 'end',
   '\x1b[3~': 'delete', '\x1b[Z': 'shift-tab',
   '\x1b[13;2u': 'shift-enter', '\x1b[27;2;13~': 'shift-enter', '\x1b\r': 'shift-enter', '\x1b\n': 'shift-enter',
-  '\x1b[1;5D': 'word-left', '\x1b[1;5C': 'word-right', '\x1b[1;3D': 'word-left', '\x1b[1;3C': 'word-right'
+  '\x1b[1;5D': 'word-left', '\x1b[1;5C': 'word-right', '\x1b[1;3D': 'word-left', '\x1b[1;3C': 'word-right',
+  // COMPOSER-EDIT (owner 2026-10-17: edit like Claude Code's prompt box). Alt+B/F (macOS Option+Left/Right), iTerm2 Alt+arrows,
+  // Alt+Backspace, Alt+D, Ctrl/Alt+Delete, and Shift (+Ctrl/Alt) arrows, Home and End for selection.
+  '\x1bb': 'word-left', '\x1bf': 'word-right', '\x1b\x1b[D': 'word-left', '\x1b\x1b[C': 'word-right',
+  '\x1b\x7f': 'delete-word', '\x1b\x08': 'delete-word', '\x1bd': 'delete-word-forward',
+  '\x1b[3;5~': 'delete-word-forward', '\x1b[3;3~': 'delete-word-forward',
+  '\x1b[1;2D': 'select-left', '\x1b[1;2C': 'select-right', '\x1b[1;2A': 'select-up', '\x1b[1;2B': 'select-down',
+  '\x1b[1;2H': 'select-home', '\x1b[1;2F': 'select-end',
+  '\x1b[1;6D': 'select-word-left', '\x1b[1;6C': 'select-word-right', '\x1b[1;4D': 'select-word-left', '\x1b[1;4C': 'select-word-right'
 };
 const CSI_LIST = Object.keys(CSI_KEYS).sort((a, b) => b.length - a.length);
 
 const CTRL = {
-  '\x01': 'home', '\x05': 'end', '\x03': 'ctrl-c', '\x04': 'ctrl-d', '\x07': 'ctrl-g',
-  '\x0f': 'ctrl-o', '\x13': 'ctrl-s', '\x15': 'kill-line', '\x17': 'delete-word',
+  '\x01': 'home', '\x05': 'end', '\x03': 'ctrl-c', '\x04': 'ctrl-d', '\x07': 'ctrl-g', '\x12': 'ctrl-r',
+  '\x0b': 'kill-line-forward', '\x0f': 'ctrl-o', '\x13': 'ctrl-s', '\x15': 'kill-line', '\x17': 'delete-word',
   '\x1f': 'undo', '\x19': 'redo', '\x0a': 'newline', '\x7f': 'backspace', '\x08': 'backspace',
   '\r': 'enter', '\t': 'tab', '\x02': 'left', '\x06': 'right'
 };
 
-export function parseChunk(chunk, state = initialKeyState()) {
+/** `draft` = the composer text before this chunk (a burst split mid-line continues the line already typed). */
+export function parseChunk(chunk, state = initialKeyState(), draft = '') {
   const events = [];
   let s = String(chunk);
   let st = { partial: '', ...state };
@@ -77,6 +99,12 @@ export function parseChunk(chunk, state = initialKeyState()) {
     if (s[0] === '\x1b') {
       // Focus reporting (CSI ?1004h, enabled by sound/index.js): CSI I = focus in, CSI O = focus out.
       if (s.startsWith('\x1b[I') || s.startsWith('\x1b[O')) { events.push({ type: 'focus', focused: s[2] === 'I' }); s = s.slice(3); continue; }
+      // QUOXON-MOUSE: SGR mouse reports; a report split across chunks is held, never typed into the composer.
+      const mm = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/.exec(s);
+      if (mm) { events.push(mouseEvent(Number(mm[1]), Number(mm[2]), Number(mm[3]), mm[4])); s = s.slice(mm[0].length); continue; }
+      if (/^\x1b\[<[\d;]*$/.test(s)) { st.partial = s; s = ''; break; }
+      const cr = /^\x1b\[(\d+);(\d+)R/.exec(s);
+      if (cr) { events.push({ type: 'cursor', row: Number(cr[1]), col: Number(cr[2]) }); s = s.slice(cr[0].length); continue; }
       const hit = CSI_LIST.find(k => s.startsWith(k));
       if (hit) { events.push({ type: 'key', name: CSI_KEYS[hit] }); s = s.slice(hit.length); continue; }
       // Unknown escape sequence: swallow ESC [ ... final byte, or a bare ESC+char (alt-x).
@@ -90,22 +118,37 @@ export function parseChunk(chunk, state = initialKeyState()) {
     const run = /^[^\x00-\x1f\x7f]+/.exec(s);
     if (run) { events.push({ type: 'text', text: run[0] }); s = s.slice(run[0].length); continue; }
     const c = s[0];
-    if (CTRL[c]) { events.push({ type: 'key', name: CTRL[c] }); }
+    if (CTRL[c]) { events.push(c === '\x01' ? { type: 'key', name: CTRL[c], via: 'ctrl-a' } : { type: 'key', name: CTRL[c] }); } // via: a double Ctrl+A selects all (app.js)
     s = s.slice(1);
   }
-  return { events: coalesceBurst(events), state: st };
+  return { events: coalesceBurst(events, draft), state: st };
 }
 
 /**
  * If a chunk produced text and then an Enter/newline FOLLOWED by more text, it is
  * a non-bracketed paste: fold it into one paste event. A trailing single Enter
  * (text then Enter at the end) stays as text + enter so fast typing still submits.
+ *
+ * Except a burst whose every line is a slash command (R3 D3): that is typed input batched by tmux,
+ * SSH/mosh or a script ("/help" Enter "/model x" Enter), never a paste, so each Enter runs its line.
+ * Folding it made a multi-line "/" draft that trapped every later Enter.
  */
-function coalesceBurst(events) {
+const isEnter = (e) => e.type === 'key' && (e.name === 'enter' || e.name === 'newline');
+function commandLines(events, draft = '') {
+  let line = draft.includes('\n') ? '\n' : draft; // a multi-line draft is never a command line
+  for (const e of events) {
+    if (e.type === 'text') line += e.text;
+    else if (e.name === 'enter') { if (!line.startsWith('/')) return false; line = ''; }
+    else return false; // newline (Ctrl+J), tab or any other key: not plain typed commands
+  }
+  return line === '' || line.startsWith('/');
+}
+function coalesceBurst(events, draft = '') {
   const hasInner = events.some((e, i) =>
-    e.type === 'key' && (e.name === 'enter' || e.name === 'newline') && i > 0 && i < events.length - 1 &&
+    isEnter(e) && i > 0 && i < events.length - 1 &&
     events.slice(i + 1).some(x => x.type === 'text'));
   if (!hasInner) return events;
+  if (commandLines(events, draft)) return events;
   let text = '';
   const rest = [];
   for (let i = 0; i < events.length; i++) {