quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/loopCards.js

@@ -0,0 +1,180 @@
+/**
+ * QLOOP-LIVE: the loop cards in the chat stream. One card per loop, updated in place; observer points and the finish line
+ * append as ordinary chat lines beneath it, so the history reads as the loop's story.
+ *
+ * Glue only (the logic is in loopCard.js and loopStream.js): it owns the watchers, the redraw throttle (<= 8 per second),
+ * the keys of a focused card and the finish moment. The host (app.js) supplies say / addItem / bump / dragon, which keeps this
+ * testable without Ink.
+ */
+import { loopPinned, initLoop, applySnapshot, applyProgress, reduceLoop, setConn, observerLine, finishLines, startLine, createThrottle, REDRAW_MIN_MS, REDRAW_UNFOCUSED_MS, TERMINAL } from './loopCard.js';
+import { watchLoop } from './loopStream.js';
+import { objectiveMoment } from './dragonMoments.js';
+
+const TICK_MS = 250; // a focused card's spinner and clock
+const TICK_UNFOCUSED_EVERY = 4; // nobody on the card: every 4th tick (1 s), so idle cards cost little
+const REFRESH_MIN_MS = 2000; // the runner's own turn is read from the snapshot at most this often per card
+const REFRESH_CAP_MS = 1500; // and the finish never waits longer than this for the last read
+
+/**
+ * The roster sees a loop finish (its row turns done) up to a minute BEFORE the stream's loop.finished reaches the card (the server
+ * drains receipts first), and its dragon then lands on a card that is still running and overflows the screen. A loop with a live card
+ * summons its dragon from the card, once, at its finish: the roster's watch skips those rows.
+ */
+export const rowsWithoutLoopCards = (rows, has) => (rows || []).filter((r) => !(r?.kind === 'loop' && has(r.id)));
+
+export function createLoopCards({ api, say, addItem, bump, dragon = null, now = Date.now, setTick = (f, ms) => { const t = setInterval(f, ms); t.unref?.(); return () => clearInterval(t); }, throttleTimer, watch = watchLoop, sleep } = {}) {
+  const cards = new Map(); // id -> ctrl
+  let focusId = null, cancelTick = null;
+  const throttle = createThrottle(() => bump(), { minMs: () => (focusId ? REDRAW_MIN_MS : REDRAW_UNFOCUSED_MS), now, ...(throttleTimer ? { timer: throttleTimer } : {}) });
+
+  const running = () => [...cards.values()].some((c) => !c.state.done);
+  /**
+   * A runner loop's stream `turn` counts model messages; its own turn is the snapshot's `iteration`. Read it again when a turn moves
+   * (at most every REFRESH_MIN_MS; a request inside the window is made by the next tick). -> a promise that settles when the read is over.
+   */
+  function refresh(c, force = false) {
+    if (!api.loopSnapshot || c.refreshing) return c.refreshing || Promise.resolve();
+    if (!force && now() - (c.lastSnapAt ?? -Infinity) < REFRESH_MIN_MS) { c.refreshDue = true; return Promise.resolve(); }
+    c.lastSnapAt = now(); c.refreshDue = false;
+    c.refreshing = Promise.resolve().then(() => api.loopSnapshot(c.id)).then((snap) => { c.state = applyProgress(c.state, snap); throttle.poke(); }, () => {}).finally(() => { c.refreshing = null; });
+    return c.refreshing;
+  }
+  let tickN = 0;
+  function tick() { // elapsed time and the spinner move once per tick, never faster than the throttle allows
+    if (!running()) { cancelTick?.(); cancelTick = null; return; }
+    if (!focusId && ++tickN % TICK_UNFOCUSED_EVERY) return;
+    for (const c of cards.values()) if (!c.state.done) { c.frame = (c.frame + 1) % 4; if (c.refreshDue) refresh(c); }
+    throttle.poke();
+  }
+  const ensureTick = () => { if (!cancelTick && running()) cancelTick = setTick(tick, TICK_MS); };
+
+  function finish(c, ev) {
+    if (!c.finishedSaid) { c.finishedSaid = true; for (const l of finishLines(c.state)) say(l.text, l.tone); }
+    c.confirm = false; // a focused card keeps its focus: Enter then expands the final output and Esc lets the frozen card go to scrollback
+    // The moment engine fires the dragon. Same call and same gates as a finished roster row (mode on, not typing, cooldown).
+    const st = c.state;
+    const m = !c.quiet && dragon?.summon && ['completed', 'completed_with_errors', 'failed'].includes(st.state)
+      ? objectiveMoment({ kind: 'loop', state: st.state === 'failed' ? 'failed' : 'done', name: st.title || st.id, activity: st.reason || '' }) : null;
+    if (m) Promise.resolve(dragon.summon(st.agent && typeof st.agent === 'string' ? st.agent : m.dragon, m.caption)).then((shown) => { if (shown) bump(); }, () => {});
+    return ev;
+  }
+
+  function onEvent(c, ev) {
+    const before = c.state;
+    c.state = reduceLoop(before, ev);
+    if (c.state === before) return;
+    const line = c.quiet ? null : observerLine(ev, c.state); // replaying a loop that was already over: the card tells it, the chat does not re-read it
+    if (line) { c.state.observed = [...c.state.observed, line.text].slice(-50); say(line.text, line.tone); }
+    if (ev.type === 'loop.turn.started' || ev.type === 'loop.turn.completed' || ev.type === 'loop.observe') refresh(c);
+    if (ev.type === 'loop.finished') { // the last read of the runner's turn first: "completed, N turns" must be the loop's count
+      c.finishing = true;
+      let t; const cap = new Promise((res) => { t = setTimeout(res, REFRESH_CAP_MS); t.unref?.(); });
+      Promise.race([refresh(c, true), cap]).then(() => { clearTimeout(t); finish(c, ev); throttle.poke(); });
+    }
+    throttle.poke();
+  }
+
+  async function run(c) {
+    const ctl = c.abort = new AbortController();
+    try {
+      const out = await watch({
+        api, id: c.id, signal: ctl.signal, sleep,
+        onSnapshot: (snap) => { c.state = applySnapshot(c.state, snap); if (c.state.done) c.quiet = true; throttle.poke(); }, // the finish line waits for the replay: it needs the receipts
+        onEvent: (ev) => onEvent(c, ev),
+        onConn: ({ conn, attempt, note }) => { if (!c.state.done) { c.state = setConn(c.state, conn, { attempt, note }); throttle.poke(); } },
+      });
+      if (out?.lost && !c.state.done) { c.state = setConn(c.state, 'lost', { attempt: 0, note: out.reason }); }
+      if (c.state.done && !c.finishedSaid && !c.finishing) { c.finishedSaid = true; for (const l of finishLines(c.state)) say(l.text, l.tone); } // finished before we looked (or the replay ended without a finish event)
+    } catch (e) {
+      c.state = setConn(c.state, 'lost', { note: e?.message || 'failed' });
+    } finally { throttle.poke(); }
+  }
+
+  return {
+    /** Put a live card in the chat stream for this loop and start following it. -> the card, or the existing one. */
+    watch(id, { title = '', agent = null, announce = true } = {}) {
+      if (!id) return null;
+      if (cards.has(id)) return cards.get(id);
+      const c = { id, state: initLoop({ id, title, agent }), expanded: false, focused: false, confirm: false, frame: 0, abort: null, finishedSaid: false };
+      cards.set(id, c);
+      if (announce) { const l = startLine(c.state); say(l.text, l.tone); } // the start line first, then the card, then the story beneath
+      addItem({ id: `loopcard-${id}`, kind: 'loopcard', card: c });
+      ensureTick();
+      run(c).then(() => bump());
+      return c;
+    },
+    /**
+     * A loop the chat just made (its `objective` tool answered `Loop "<title>" created ...`): the tool result carries no id, so look
+     * the loop up in the org's list (newest first) and put a card in this conversation for the live, unwatched one that matches
+     * the title. One retry, because the list can lag the tool's answer. -> ids watched.
+     */
+    async discover({ title = '' } = {}) {
+      if (!api.loopList) return [];
+      const want = String(title || '').replace(/…$/, '').trim().toLowerCase();
+      for (let attempt = 0; attempt < 2; attempt++) {
+        let rows = [];
+        try { const d = await api.loopList(); rows = Array.isArray(d) ? d : (d?.loops || []); } catch { rows = []; }
+        const hit = rows.filter((r) => {
+          const id = r.objective_id || r.id; if (!id || cards.has(id) || TERMINAL.has(r.state)) return false;
+          const age = now() - (Date.parse(String(r.created_at || '').replace(' ', 'T') + (/[zZ]|[+-]\d\d:?\d\d$/.test(String(r.created_at || '')) ? '' : 'Z')) || 0);
+          return age < 20 * 60 * 1000 && (!want || String(r.title || '').toLowerCase().startsWith(want));
+        });
+        if (hit.length) { const r = hit[0]; const id = r.objective_id || r.id; this.watch(id, { title: r.title || title }); return [id]; }
+        if (attempt === 0) await (sleep || ((ms) => new Promise((res) => setTimeout(res, ms))))(1500);
+      }
+      return [];
+    },
+    /** Read the runner's turn now (tests, and a card that was just focused). */
+    refresh: (id) => (cards.has(id) ? refresh(cards.get(id), true) : Promise.resolve()),
+    has: (id) => cards.has(id),
+    get: (id) => cards.get(id) || null,
+    all: () => [...cards.values()],
+    /** True while this history item must stay in the live region (commitLimit): its loop has not finished. */
+    held: (item) => Boolean(item?.kind === 'loopcard' && item.card && (!item.card.state.done || item.card.focused)), // a focused card stays live even when finished, so Enter / Esc work on it
+    anyRunning: running,
+    /** The cards drawn above the composer: running ones, and a finished one you are still on. */
+    pinned: () => [...cards.values()].filter(loopPinned),
+    /** The card the keys act on, or null. */
+    focused: () => (focusId && cards.get(focusId)) || null,
+    /** Focus the newest card that is still running (or the named one). -> the card or null. */
+    focus(id = null) {
+      const pick = id ? cards.get(id) : [...cards.values()].reverse().find((c) => !c.state.done) || [...cards.values()].pop();
+      if (!pick) return null;
+      const old = this.focused(); if (old) { old.focused = false; old.confirm = false; }
+      pick.focused = true; focusId = pick.id; throttle.poke(); bump(); return pick;
+    },
+    blur() { const c = this.focused(); if (c) { c.focused = false; c.confirm = false; } focusId = null; bump(); },
+    /**
+     * Keys while a card is focused. Enter toggles the expanded spool, s asks to halt (y confirms, anything else cancels),
+     * Esc collapses and then leaves. -> true when the key was consumed.
+     */
+    key(name, text) {
+      const c = this.focused(); if (!c) return false;
+      if (c.confirm) {
+        c.confirm = false;
+        if (text === 'y') this.halt(c.id).then(() => bump(), () => bump()); else say('Halt cancelled.');
+        bump(); return true;
+      }
+      if (name === 'enter') { c.expanded = !c.expanded; bump(); return true; }
+      if (name === 'escape') { if (c.expanded) c.expanded = false; else this.blur(); bump(); return true; }
+      if (text === 's' && !c.state.done) { c.confirm = true; bump(); return true; }
+      if (name === 'up' || name === 'down' || name === 'tab') { // cycle between cards when there are several
+        const ids = [...cards.keys()]; if (ids.length > 1) { const i = ids.indexOf(c.id); this.focus(ids[(i + (name === 'up' ? ids.length - 1 : 1)) % ids.length]); }
+        return true;
+      }
+      if (text) { this.blur(); return false; } // ordinary typing goes to the draft
+      return true;
+    },
+    /** The halt goes through the same governed route as the roster's s: after an explicit y from the human, never silently. */
+    async halt(id) {
+      const c = cards.get(id); if (!c) return { ok: false, message: `no loop card for ${id}` };
+      if (!api.stopRow) { say('Halt is not available on this server.', 'warn'); return { ok: false }; }
+      const r = await api.stopRow({ source: 'objectives', kind: 'loop', id, name: c.state.title || id });
+      say(r.message || (r.ok ? 'Halt sent.' : 'Halt refused.'), r.ok ? undefined : 'warn');
+      return r;
+    },
+    dispose() { for (const c of cards.values()) c.abort?.abort(); cards.clear(); cancelTick?.(); cancelTick = null; throttle.dispose(); },
+  };
+}
+
+export { TERMINAL };

package/lib/quoxon/loopStream.js

@@ -0,0 +1,87 @@
+/**
+ * QLOOP-LIVE: the client for a running loop. Reads GET /api/v1/loops/:id (snapshot) and
+ * GET /api/v1/loops/:id/events (SSE; ?since=<event_seq> resumes; a heartbeat comment every 15 s; ends after loop.finished).
+ * Contract: ~/quoxon-work/qloop-live-design.md section 1. Every event carries a monotonic event_seq.
+ *
+ * Reconnect is the part that must not lie. A drop is counted, backed off (500 ms doubling to 10 s, reset by any event) and
+ * reported to the card as 'reconnecting'; after MAX_FAILS drops in a row with no event between, or at once on 401/403/404,
+ * the watcher stops and says 'lost' with the reason. It never reports a lost stream as a finished loop.
+ */
+export const BACKOFF_START_MS = 500;
+export const BACKOFF_CAP_MS = 10000;
+export const MAX_FAILS = 8;
+const FATAL = new Set([401, 403, 404]);
+const TERMINAL_STATES = new Set(['completed', 'completed_with_errors', 'failed', 'interrupted', 'halted', 'cancelled', 'aborted', 'stopped']);
+const isTerminal = (snap) => Boolean(snap && (snap.finished === true || TERMINAL_STATES.has(snap.state)));
+
+const sleepFor = (ms, signal) => new Promise((resolve) => {
+  if (signal?.aborted) return resolve();
+  const t = setTimeout(done, ms); t.unref?.();
+  function done() { signal?.removeEventListener?.('abort', done); clearTimeout(t); resolve(); }
+  signal?.addEventListener?.('abort', done, { once: true });
+});
+
+/**
+ * Follow one loop until loop.finished, abort, or a fatal failure.
+ *
+ * api: { loopSnapshot(id) -> object, loopEvents(id, { since }, signal) -> async iterable of events }
+ * handlers: { onSnapshot(snap), onEvent(ev), onConn({ conn: 'live'|'reconnecting'|'lost', attempt, note }) }
+ * -> { finished: boolean, lost: boolean, lastSeq, reason? }
+ */
+export async function watchLoop({ api, id, signal, since = 0, onSnapshot = () => {}, onEvent = () => {}, onConn = () => {}, sleep = sleepFor, backoffStart = BACKOFF_START_MS, backoffCap = BACKOFF_CAP_MS, maxFails = MAX_FAILS }) {
+  let lastSeq = Number(since) || 0, fails = 0, delay = backoffStart, finished = false;
+  try { onSnapshot(await api.loopSnapshot(id)); }
+  catch (e) { // the snapshot is a head start, not a gate: the replayed events carry the same facts. A fatal status still stops.
+    if (FATAL.has(e?.status)) { onConn({ conn: 'lost', attempt: 0, note: describe(e) }); return { finished: false, lost: true, lastSeq, reason: describe(e) }; }
+  }
+  while (!signal?.aborted && !finished) {
+    let sawEvent = false;
+    try {
+      for await (const ev of api.loopEvents(id, { since: lastSeq || undefined }, signal)) {
+        if (signal?.aborted) break;
+        if (!ev || typeof ev.type !== 'string') continue;
+        const seq = Number(ev.event_seq);
+        if (Number.isFinite(seq) && seq <= lastSeq) continue; // the boundary event of a resume
+        if (Number.isFinite(seq)) lastSeq = seq;
+        if (!sawEvent) { sawEvent = true; fails = 0; delay = backoffStart; onConn({ conn: 'live', attempt: 0, note: null }); }
+        onEvent(ev);
+        if (ev.type === 'loop.finished') { finished = true; break; }
+      }
+      if (!finished && !signal?.aborted && !sawEvent) {
+        // A clean close with no events is not a failure: a loop's silent final turn, or a loop that already finished, ends this way.
+        // Ask the snapshot. Terminal: finish quietly with the final state. Still running: reconnect with ?since, failures reset.
+        // Only a snapshot read that itself fails counts (a real error).
+        let snap = null;
+        try { snap = await api.loopSnapshot(id); }
+        catch (e) {
+          if (FATAL.has(e?.status)) { onConn({ conn: 'lost', attempt: fails, note: describe(e) }); return { finished: false, lost: true, lastSeq, reason: describe(e) }; }
+          fails += 1;
+          if (fails >= maxFails) { onConn({ conn: 'lost', attempt: fails, note: describe(e) }); return { finished: false, lost: true, lastSeq, reason: describe(e) }; }
+          onConn({ conn: 'reconnecting', attempt: fails, note: describe(e) });
+          await sleep(delay, signal); delay = Math.min(delay * 2, backoffCap);
+          continue;
+        }
+        if (isTerminal(snap)) { onSnapshot(snap); return { finished: true, lost: false, lastSeq, final: snap }; }
+        fails = 0; // still running: quiet, not a failure
+        await sleep(backoffStart, signal);
+        continue;
+      }
+      else if (!finished && sawEvent) fails = 0;
+    } catch (e) {
+      if (signal?.aborted) break;
+      if (FATAL.has(e?.status)) { onConn({ conn: 'lost', attempt: fails, note: describe(e) }); return { finished: false, lost: true, lastSeq, reason: describe(e) }; }
+      fails += 1;
+      if (fails >= maxFails) { onConn({ conn: 'lost', attempt: fails, note: describe(e) }); return { finished: false, lost: true, lastSeq, reason: describe(e) }; }
+      onConn({ conn: 'reconnecting', attempt: fails, note: describe(e) });
+      await sleep(delay, signal); delay = Math.min(delay * 2, backoffCap);
+      continue;
+    }
+    if (finished || signal?.aborted) break;
+    if (fails >= maxFails) { onConn({ conn: 'lost', attempt: fails, note: 'the stream keeps closing' }); return { finished: false, lost: true, lastSeq, reason: 'the stream keeps closing' }; }
+    onConn({ conn: 'reconnecting', attempt: Math.max(1, fails), note: null });
+    await sleep(delay, signal); delay = Math.min(delay * 2, backoffCap);
+  }
+  return { finished, lost: false, lastSeq };
+}
+
+const describe = (e) => `${e?.status ? `HTTP ${e.status} ` : ''}${e?.message || 'failed'}`.trim();

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, minGapMsFrom, 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.4.0';
   try { version = resolveCliVersion?.() || version; } catch { /* keep default */ }
   if (opts.print) return mainPrint(opts);
   let replay = null;
@@ -152,12 +56,23 @@ export async function main(argv = process.argv.slice(2)) {
     // and a fresh install replays the original request as the first real turn
     replay = r.replay || null;
     fromGettingStarted = true;
+    // QUOXON-Q: ONE offer for a short `q` command, asked once (answer kept in the CLI config)
+    if (process.stdin.isTTY && process.stdout.isTTY && !opts.demoOnboarding) {
+      try {
+        const { offerShortcut } = await import('./onboarding/shortcutOffer.js');
+        const { createInterface } = await import('node:readline/promises');
+        const config = (await import('../core/config.js')).loadConfig();
+        await offerShortcut({ config, ask: async (line) => { const rl = createInterface({ input: process.stdin, output: process.stdout }); try { return await rl.question(`\n${line} `); } finally { rl.close(); } } });
+      } catch { /* an offer must never block the first conversation */ }
+    }
   }
   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 +83,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(), minGapMs: minGapMsFrom() }), 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 });
-}