quoxcli 0.2.0 → 0.3.1

package/lib/quoxon/main.js

@@ -5,119 +5,22 @@ import { App } from './app.js';
 import { inkRenderOptions, inkStdout } from './term.js';
 import { createDemoApi } from './demo.js';
 import { DEMO_LABEL } from './demo.fixtures.js';
-import { PASTE_ON } from './keys.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 { parseModelArg } from './model.js';
+import { createScreenRecorder, screenFramesEnabled } from './screenFrames.js';
 import { applySettings } from './slash/settings.js';
-import { headOf, RUNNING_ROOT, execRestart, checkRestart } from './slash/restart.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';
 
-const FLAGS = new Set(['-p', '--profile', '--verbose', '--demo', '--print', '--output', '--conversation', '--turn-id', '--timeout', '--color', '--no-clear', '-n', '--name', '--service-key', '--demo-onboarding', '--provider', '--model', '--resume', '-h', '--help', '--']);
-const isFlag = (a) => FLAGS.has(a) || /^--(profile|verbose|print|output|conversation|turn-id|timeout|provider|model|resume)=/.test(a);
+export { parseArgs, USAGE, pickProfile, choosePick, chatCredentialProblem, noServerConfigured, printAuthMessage } from './headless.js';
+import { parseArgs, USAGE, noServerConfigured, mainPrint, pickProfile, chatCredentialProblem } from './headless.js';
 
-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, provider: 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 === '--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 === '--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] [--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>] [--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  --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) {
-  if (explicit) return { name: explicit, note: null };
-  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
-  return { name: undefined, note: `The default profile "${active}" is an agent login and cannot chat. Pass -p <your profile>.` };
-}
-
-/**
- * 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` : ''}`;
-}
-
-/** Keys typed before the app is ready: raw mode now, so nothing is cooked-echoed, buffered for the composer. */
-export function captureEarlyInput(stdin = process.stdin, stdout = process.stdout) {
-  if (!stdin?.isTTY) return null;
-  const chunks = [];
-  const fn = (d) => chunks.push(typeof d === 'string' ? d : d.toString('utf8'));
-  try { stdin.setRawMode?.(true); stdin.resume?.(); } catch { /* not a tty after all */ }
-  stdin.on('data', fn);
-  if (stdout?.isTTY) stdout.write(PASTE_ON);
-  return { chunks, detach: () => stdin.off('data', fn) };
-}
+export { captureEarlyInput } from './earlyInput.js';
 
 /**
  * Clear the screen before the chat client? Never right after Getting started: its finale (the one-time
@@ -129,13 +32,14 @@ export function shouldClearBeforeChat({ isTTY, noClear, fromGettingStarted }) {
 
 export async function main(argv = process.argv.slice(2)) {
   const opts = parseArgs(argv);
-  if (opts.help) { console.log(USAGE); return; }
-  if (opts.errors.length) { process.stderr.write(`quox: ${opts.errors.join('; ')}\n${USAGE}\n`); process.exitCode = 1; return; }
   // 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.2.0';
+  let version = '0.3.1';
   try { version = resolveCliVersion?.() || version; } catch { /* keep default */ }
   if (opts.print) return mainPrint(opts);
   let replay = null;
@@ -156,8 +60,10 @@ export async function main(argv = process.argv.slice(2)) {
   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
-    props = { api: createDemoApi(), profile: 'demo', org: 'demo-org', demoLabel: DEMO_LABEL, autoplay: 'Show me what you can do (demo)', onRestart: (r) => { restart = { ...r, conversationId: null }; }, restartCheck: checkRestart };
+    // 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');
@@ -168,77 +74,103 @@ export async function main(argv = process.argv.slice(2)) {
     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 auth = createAuth(config);
-    const client = createClient(config, auth);
-    const api = createApi({ client, config, auth });
+    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 && ['off', 'on', 'full'].includes(saved.verbose)) opts.verbose = saved.verbose;
-    props = { api, modelChoice: opts.provider, resume: opts.resume ?? null, onRestart: (r) => { restart = r; }, restartCheck: checkRestart, startSha: headOf(RUNNING_ROOT), rules: loadRules(), profile: pname, org: missing ? null : (config.getAuth?.()?.org_name || null), startup, blocked: problem ? problem.message : null, autoplay: replay };
+    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);
-  const app = render(React.createElement(App, { ...props, welcome, version, cwd, verbose: opts.verbose, earlyInput: early, sessionName: opts.name, resumeConversation: opts.conversation || null, invite: Boolean(process.stdout.isTTY) && !opts.name, transcript }), inkRenderOptions(process.stdout));
-  try { await app.waitUntilExit(); transcript?.end(restart ? 'restart' : 'exit'); }
-  catch (e) { transcript?.end(`crash: ${e?.message || e}`); throw e; }
-  finally { process.stdout.off('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 r = execRestart({ argv, conversationId: restart.conversationId, profile: opts.demo ? null : props.profile, name: restart.name || opts.name || null, bin: restart.bin || undefined });
+  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;
 }
-
-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 = 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;
-    }
-    api = createApi({ client: createClient(config, auth), config, auth });
-    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, promptProfile: opts.promptProfile, context: rulesContext(rules), prompt, output: opts.output, conversation: opts.conversation, turnId: opts.turnId || undefined, timeoutS: opts.timeout, color: opts.color, out, err });
-}

package/lib/quoxon/markdown.js

@@ -13,23 +13,14 @@
  */
 import React from 'react';
 import { Box, Text, Transform } from 'ink';
-import { Lexer } from 'marked';
 import { graphemes } from './textBuffer.js';
-import { c, mono, clip, gradient, bulletRole } from './theme.js';
+import { c, mono, gradient, bulletRole } from './theme.js';
 
 const h = React.createElement;
 
-export const lex = (src) => new Lexer({ gfm: true, breaks: false }).lex(src);
+import { lex, splitSettled } from './markdownSettle.js';
 
-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) };
-}
+export { lex, splitSettled }; // QUOXON-LATENCY: defined in markdownSettle.js so --print never loads Ink
 
 export function healInline(text) {
   let t = text;
@@ -128,22 +119,55 @@ function inline(tokens = [], style = {}, key = 'i') {
 const w = (s) => graphemes(s).length;
 const padTo = (s, n) => s + ' '.repeat(Math.max(0, n - w(s)));
 
-/** Plain-text table layout: returns { mode: 'grid'|'vertical', lines: [{ text, head? }] }. Pure, for tests. */
+/** 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);
-  if (total <= cols) {
-    const line = (r) => r.map((cell, i) => padTo(cell ?? '', widths[i])).join(' │ ').replace(/\s+$/, '');
-    const rule = widths.map(x => '─'.repeat(x)).join('─┼─');
-    return { mode: 'grid', lines: [{ text: line(header), head: true }, { text: rule, rule: true }, ...rows.map(r => ({ text: line(r) }))] };
-  }
-  // too wide: vertical key: value, one block per row
+  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) => lines.push({ text: `${padTo(clip(hd, keyW), keyW)}  ${r[i] ?? ''}`, key: keyW }));
+    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 };
 }
@@ -153,7 +177,7 @@ function Table({ t, cols }) {
   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: 'truncate-end'
+    key: i, bold: l.head, color: l.rule ? c('muted') : (l.head ? c('label') : undefined), wrap: 'wrap'
   }, l.text || ' ')));
 }
 

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"
+  ]
+}

package/lib/quoxon/mentions.js

@@ -0,0 +1,90 @@
+/**
+ * @mention completion in the composer (MENTIONS). Typing `@` at the start of a word suggests agents, fleet hosts,
+ * tasks (objectives) and receipts (this session's own tool-call envelopes). The remote lists are fetched ONCE per
+ * session on the first `@`, then every keystroke filters the cache: no request per key. A failed fetch is quiet
+ * (that kind just has no rows) and is retried at most every RETRY_MS. Tab or Enter accepts, Esc closes.
+ */
+export const RETRY_MS = 30000;
+export const KIND_ORDER = ['agent', 'host', 'task', 'receipt'];
+
+/** The @word being typed at the end of the draft -> { start (index after '@'), partial } or null. */
+export function mentionContext(draft) {
+  const t = String(draft ?? '');
+  const m = t.match(/(^|\s)@([^\s@]*)$/);
+  if (!m) return null;
+  return { start: t.length - m[2].length, partial: m[2] };
+}
+
+const clean = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
+
+/** api -> [{ value, kind, label }] from the session's remote sources, never throwing; failures named per kind. */
+export async function loadMentions(api) {
+  const kinds = {
+    agent: async () => (await api.agents()).map(a => ({ value: String(a.agent_id), kind: 'agent', label: a.name && a.name !== a.agent_id ? clean(a.name) : '' })),
+    host: async () => {
+      const none = { status: 'absent', value: [] };
+      const [inv, beat] = await Promise.all([api.mentionHosts, api.objects?.fleetNames].map((fn, i) => (fn ? Promise.allSettled([i ? api.objects.fleetNames() : api.mentionHosts()]).then(r => r[0]) : none)));
+      const tried = [inv, beat].filter(r => r.status !== 'absent');
+      if (tried.length && tried.every(r => r.status === 'rejected')) throw tried[0].reason;
+      const out = (inv.status === 'fulfilled' ? inv.value : []).map(h => ({ value: String(h.id), kind: 'host', label: clean([h.group, h.health].filter(Boolean).join(' · ')) }));
+      for (const h of beat.status === 'fulfilled' ? beat.value || [] : []) if (!out.some(o => o.value === String(h.value))) out.push({ value: String(h.value), kind: 'host', label: clean(h.desc) });
+      return out;
+    },
+    task: async () => ((await api.mentionTasks?.()) || []).map(o => ({ value: String(o.id), kind: 'task', label: clean(`${o.title || ''}${o.status ? ` (${o.status})` : ''}`) })),
+  };
+  const out = []; const failed = [];
+  await Promise.all(Object.entries(kinds).map(async ([k, fn]) => {
+    try { out.push(...(await fn()).filter(x => x.value && /^[\w.:-]+$/.test(x.value))); } catch { failed.push(k); }
+  }));
+  return { items: out, failed };
+}
+
+/** This session's tool calls that carry an envelope id: their receipts, newest first. Local, no request. */
+export function receiptMentions(items) {
+  const seen = new Set(); const out = [];
+  for (const b of [...(items || [])].reverse()) {
+    if (!b || b.kind !== 'tool' || !b.envelopeId || seen.has(b.envelopeId)) continue;
+    seen.add(b.envelopeId);
+    out.push({ value: String(b.envelopeId), kind: 'receipt', label: clean(`${b.tool || 'tool call'}${b.status ? ` ${b.status}` : ''}`) });
+  }
+  return out;
+}
+
+/** Prefix on the value first, then a substring of the value or its label; agents, hosts, tasks, receipts in that order. */
+export function rankMentions(items, partial, max = 50) {
+  const q = String(partial || '').toLowerCase();
+  const seen = new Set();
+  const uniq = (items || []).filter(i => i?.value && !seen.has(`${i.kind}:${i.value}`) && seen.add(`${i.kind}:${i.value}`));
+  const order = (a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind);
+  if (!q) return uniq.sort(order).slice(0, max);
+  const pre = uniq.filter(i => i.value.toLowerCase().startsWith(q)).sort(order);
+  const sub = uniq.filter(i => !i.value.toLowerCase().startsWith(q) && (i.value.toLowerCase().includes(q) || i.label.toLowerCase().includes(q))).sort(order);
+  const out = [...pre, ...sub];
+  return out.length === 1 && out[0].value.toLowerCase() === q ? [] : out.slice(0, max);
+}
+
+/** Accepting a mention: replace the partial word, add one space. */
+export const applyMention = (draft, cx, value) => String(draft).slice(0, cx.start) + value + ' ';
+
+/**
+ * One cache for the session. items() returns what is loaded (never blocks) and starts the single load the first
+ * time it is asked; a failed kind is retried no sooner than RETRY_MS. loads() counts fetches (tests, /status).
+ */
+export function createMentionCache({ load, refresh = () => {}, now = Date.now, retryMs = RETRY_MS }) {
+  let items = []; let state = 'idle'; let failedAt = 0; let loads = 0;
+  const start = () => {
+    state = 'loading'; loads++;
+    Promise.resolve().then(load).then(
+      (r) => { items = r?.items || []; state = r?.failed?.length ? 'partial' : 'ready'; if (state === 'partial') failedAt = now(); },
+      () => { state = 'failed'; failedAt = now(); }
+    ).then(() => refresh());
+  };
+  return {
+    items() {
+      if (state === 'idle' || ((state === 'failed' || state === 'partial') && now() - failedAt >= retryMs)) start();
+      return items;
+    },
+    state: () => state,
+    loads: () => loads,
+  };
+}