quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/slash/paletteController.js

@@ -0,0 +1,169 @@
+/**
+ * The palette's key handling, kept out of app.js. The palette is not modal: it shows while the draft is
+ * a bare `/word`, and only Up, Down, Tab, Enter and Esc go to it. Everything else is ordinary typing,
+ * which narrows the list because the draft IS the filter.
+ */
+import { findEntry } from '../commands.js';
+import { signedOutNotice } from '../sessionDead.js';
+import { paletteQuery, paletteItems, filterPalette, completion, paletteView, PALETTE_MAX } from './palette.js';
+import { argContext, levelFor, staticItems, rankArgs, applyArg } from './args.js';
+import { mentionContext, rankMentions, applyMention } from '../mentions.js';
+
+const ARG_TTL = 30000;      // a fetched list is reused this long
+const ARG_FAIL_TTL = 8000;  // a failed fetch is quiet (no rows) and retried after this
+
+const startsLike = (q, it) => {
+  const w = String(q || '').toLowerCase().replace(/^\//, '');
+  return [it.name, ...(it.aliases || [])].some(n => String(n).toLowerCase().replace(/^\//, '').startsWith(w));
+};
+
+export function createPalette({
+  getDraft, setDraft, run, say, ctx = () => ({}), source = null, refresh = () => {}, now = Date.now,
+  mentions = null // MENTIONS: { cache (mentions.js createMentionCache), local: () => receipt items }
+}) {
+  const st = { sel: 0, q: null, dismissed: null, picked: false, aq: null, mq: null };
+  const cache = new Map(); // 'src:param' -> { at, ttl, items, pending }
+  /** Cached items for an async source; fetches when missing or stale. Never throws or blocks. */
+  const fetchItems = (src, param) => {
+    if (!source) return [];
+    const key = `${src}:${param ?? ''}`;
+    const hit = cache.get(key);
+    if (hit && (hit.pending || now() - hit.at < hit.ttl)) return hit.items;
+    const ent = { at: now(), ttl: ARG_TTL, items: hit?.items ?? [], pending: true };
+    cache.set(key, ent);
+    Promise.resolve().then(() => source(src, param)).then(
+      (items) => {
+        ent.items = Array.isArray(items) ? items : [];
+        ent.at = now(); ent.pending = false;
+      },
+      () => { ent.items = []; ent.ttl = ARG_FAIL_TTL; ent.at = now(); ent.pending = false; }
+    ).then(() => refresh());
+    return ent.items;
+  };
+  /** The argument suggestions for the current draft, or null when it is not at an argument. */
+  const argState = () => {
+    const d = getDraft();
+    const cx = argContext(d);
+    if (!cx) return null;
+    const lv = levelFor(cx.entry, cx.words);
+    if (!lv) return null;
+    const param = lv.of === 'partial' ? cx.partial.slice(0, cx.partial.lastIndexOf('/') + 1) : lv.of != null ? cx.words[lv.of] : undefined; // 'partial': the directory typed so far (QUOXON-MESH /send paths)
+    const items = [...staticItems(lv), ...(lv.src ? fetchItems(lv.src, param) : [])];
+    const rows = rankArgs(items, cx.partial);
+    const key = d.slice(0, cx.start) + '\u0000' + cx.partial;
+    if (key !== st.aq) { st.aq = key; st.sel = 0; st.picked = false; }
+    return { cx, rows };
+  };
+  const argOpen = () => {
+    const d = getDraft();
+    if (st.dismissed !== null && st.dismissed !== d) st.dismissed = null;
+    if (st.dismissed === d) return null;
+    const a = argState();
+    return a && a.rows.length ? a : null;
+  };
+  /** MENTIONS: the @word at the end of the draft and its ranked rows from the session cache, or null. */
+  const mentionOpen = () => {
+    if (!mentions) return null;
+    const d = getDraft();
+    const cx = mentionContext(d);
+    if (!cx) return null;
+    if (st.dismissed !== null && st.dismissed !== d) st.dismissed = null;
+    if (st.dismissed === d) return null;
+    const rows = rankMentions([...mentions.cache.items(), ...(mentions.local?.() || [])], cx.partial);
+    const key = d.slice(0, cx.start) + '\u0000' + cx.partial;
+    if (key !== st.mq) { st.mq = key; st.sel = 0; st.picked = false; }
+    return rows.length ? { cx, rows } : null;
+  };
+  const rows = () => {
+    const q = paletteQuery(getDraft());
+    if (q !== st.q) { st.q = q; st.sel = 0; st.picked = false; }
+    return q === null ? [] : filterPalette(paletteItems(ctx()), q);
+  };
+  const isOpen = () => {
+    const d = getDraft();
+    if (st.dismissed !== null && st.dismissed !== d) st.dismissed = null;
+    if (paletteQuery(d) === null) return argOpen() !== null || mentionOpen() !== null;
+    return st.dismissed !== d;
+  };
+  /** MENTIONS keys: Up/Down choose, Tab or Enter accept, Esc closes. */
+  function onMentionKey(name, m) {
+    const n = m.rows.length;
+    switch (name) {
+      case 'up': st.sel = (st.sel - 1 + n) % n; st.picked = true; return true;
+      case 'down': st.sel = (st.sel + 1) % n; st.picked = true; return true;
+      case 'escape': st.dismissed = getDraft(); return true;
+      case 'tab': case 'enter': setDraft(applyMention(getDraft(), m.cx, m.rows[Math.min(st.sel, n - 1)].value)); return true;
+      default: return false;
+    }
+  }
+  /** -> true when the key was the palette's. */
+  function onArgKey(name, a) {
+    const n = a.rows.length;
+    switch (name) {
+      case 'up': st.sel = (st.sel - 1 + n) % n; st.picked = true; return true;
+      case 'down': st.sel = (st.sel + 1) % n; st.picked = true; return true;
+      case 'escape': st.dismissed = getDraft(); return true;
+      case 'tab': case 'enter': {
+        if (name === 'enter' && !st.picked) return false; // Enter sends what was typed
+        const it = a.rows[Math.min(st.sel, n - 1)];
+        setDraft(applyArg(getDraft(), a.cx, it.value));
+        return true;
+      }
+      default: return false;
+    }
+  }
+  function onKey(name) {
+    if (!isOpen()) return false;
+    if (paletteQuery(getDraft()) === null) { const a = argOpen(); return a ? onArgKey(name, a) : onMentionKey(name, mentionOpen()); }
+    const list = rows();
+    switch (name) {
+      case 'up': if (!list.length) return false; st.sel = (st.sel - 1 + list.length) % list.length; st.picked = true; return true;
+      case 'down': if (!list.length) return false; st.sel = (st.sel + 1) % list.length; st.picked = true; return true;
+      case 'escape': st.dismissed = getDraft(); return true;
+      case 'tab': {
+        const it = list[st.sel];
+        if (!it) return true;
+        setDraft(completion(it));
+        return true;
+      }
+      case 'enter': {
+        const typed = findEntry(getDraft());
+        if (typed && typed.kind === 'command') return false; // an exact command runs as typed (planned ones say so)
+        const it = list[st.sel];
+        if (!it) return false; // nothing matches: the normal path says "Unknown command"
+        // A loose (subsequence) match only runs when the user chose it with the arrows. Typing an unknown
+        // word and pressing Enter must not run some other command (z2h: "/hat" ran /approvals).
+        if (!st.picked && !startsLike(st.q, it)) return false;
+        if (it.disabled) { say(signedOutNotice(it.name, it.disabled), 'warn'); return true; }
+        setDraft('');
+        run(it.name);
+        return true;
+      }
+      default: return false;
+    }
+  }
+  function view() {
+    if (paletteQuery(getDraft()) === null) {
+      const a = argOpen();
+      if (!a) {
+        const mo = mentionOpen();
+        if (!mo) return { rows: [], sel: 0, more: 0, empty: null, hint: null };
+        const mv = paletteView(mo.rows, st.sel, PALETTE_MAX);
+        return { rows: mv.rows.map(it => ({ key: `@${it.value}`, text: `${it.kind}${it.label ? ` · ${it.label}` : ''}` })), sel: mv.sel, more: mv.more, empty: null, hint: '↑↓ select · Tab or Enter accept · Esc close' };
+      }
+      const v = paletteView(a.rows, st.sel, PALETTE_MAX);
+      const rows = v.rows.map(it => ({ key: it.value, text: it.desc || '' }));
+      const hint = '↑↓ select · Tab complete · Esc close';
+      return { rows, sel: v.sel, more: v.more, empty: null, hint };
+    }
+    const list = rows();
+    const v = paletteView(list, st.sel, PALETTE_MAX);
+    return {
+      rows: v.rows.map(it => ({ key: it.name, text: (it.aliases.length ? `(also ${it.aliases.join(', ')}) ` : '') + it.desc, dim: Boolean(it.disabled), note: it.disabled || null })),
+      sel: v.sel, more: v.more,
+      empty: 'No command matches. Enter sends it anyway; /help lists everything.',
+      hint: '↑↓ select · Tab complete · Enter run · Esc close'
+    };
+  }
+  return { isOpen, onKey, view, state: st };
+}

package/lib/quoxon/slash/panels.js

@@ -0,0 +1,116 @@
+/**
+ * Pure panel models for /status, /context and /doctor, rendered with the /help view (head + key/value rows).
+ * Every value comes from the caller's real data; anything not known is said plainly, never filled in.
+ */
+import { capabilityMap } from './palette.js';
+import { CHOICES } from '../model.js';
+import { providerState, capabilityName } from '../providers.js';
+
+const n = (v) => Number(v || 0).toLocaleString('en-US');
+const row = (key, text) => ({ kind: 'row', key, text: String(text) });
+
+export function healthText(hl) {
+  if (!hl) return '? not checked';
+  if (hl.ok) return `✔ answering (HTTP ${hl.status})`;
+  if (hl.absent) return `✖ nothing running there (${hl.status})`;
+  return `✖ not healthy (${hl.status})`;
+}
+
+/** What actually ran (turn.started), else what was asked for, said as such. */
+export function modelText(ctx = {}, choice = null) {
+  if (ctx.provider || ctx.model) return `${[ctx.provider, ctx.model].filter(Boolean).join(' ')} (as the server last reported)`;
+  const ask = choice ? [choice.provider, choice.model].filter(Boolean).join(' ') : 'auto (server policy)';
+  return `no turn yet; asking for ${ask}`;
+}
+
+export function statusModel(d = {}) {
+  return [
+    { kind: 'head', text: 'Status' },
+    row('Profile', d.profile || '?'),
+    row('Org', d.org || '? not in this login'),
+    row('Server', `${d.serverUrl || '?'} · ${healthText(d.health)}`),
+    row('Model', modelText(d.ctx, d.choice)),
+    row('Agent', d.agent || 'CommanderQ (quox)'),
+    row('Slot', d.slot || 'none (/slot <name>)'),
+    row('Session', d.sessionName || 'unnamed (/rename <name>)'),
+    row('Conversation', d.conversationId || 'new (starts with your next message)'),
+    row('Version', d.version || '?'),
+    ...(d.local ? [{ kind: 'dim', text: 'Server health not re-checked for this tip; /status checks it live.' }] : [])
+  ];
+}
+
+export function contextModel(d = {}) {
+  const rules = d.rules;
+  const ruleFiles = rules?.files || [];
+  const out = [
+    { kind: 'head', text: 'Context' },
+    row('Model', modelText(d.ctx, d.choice)),
+    row('Conversation', !d.conversationId ? 'new, nothing sent yet' : d.server ? `${d.server.tokensText}${d.server.turnsText ? ` · ${d.server.turnsText}` : ''}` : `${n(d.tokens)} tokens reported so far in this session${d.serverError ? ` (server context: ${d.serverError})` : ''}`),
+    ...(d.conversationId && d.server ? [row('Summary', d.server.summaryText)] : []),
+    row('Rules', d.rulesOn === false ? 'off for this session (/rules on)' : ruleFiles.length ? `${ruleFiles.length} QUOX.md file${ruleFiles.length === 1 ? '' : 's'}, ${n(rules.totalChars)} chars${rules.truncated ? ' (truncated to fit)' : ''}` : 'none loaded')
+  ];
+  if (d.rulesOn !== false) for (const f of ruleFiles) out.push({ kind: 'dim', key: '', text: `  ${f.label || f.path}  ${n(f.chars)} chars` });
+  const sk = d.skills;
+  out.push(row('Skills', !sk ? '? not checked (/context checks it live)' : sk.ok ? `${sk.count} available in your org (/skills)` : `? ${sk.error}`));
+  const mem = d.memory;
+  out.push(row('Memory', !mem ? '? not checked (/context checks it live)' : mem.ok ? 'connected (persistent memory answers)' : `not reachable: ${mem.error}`));
+  out.push(row('Agent', d.agent || 'CommanderQ (quox)'));
+  if (d.screen) {
+    const l = d.screen.last;
+    out.push(row('Terminal', !d.screen.on ? 'off for this session (/context on)' : l ? `${l.bytes} bytes sent last turn: ${l.sections.join(', ') || 'nothing new'}${l.unchanged?.length ? ` (unchanged: ${l.unchanged.join(', ')})` : ''} · /context off stops it` : 'on, sent with your next message · /context off stops it'));
+    if (d.screen.on && l?.text) for (const t of l.text.split('\n')) out.push({ kind: 'dim', key: '', text: '  ' + t });
+  }
+  return out;
+}
+
+const icon = (s) => (s === 'pass' ? '✔' : s === 'warn' ? '⚠' : s === 'skip' ? '·' : '✖');
+
+/** checks: [{ name, status:'pass'|'warn'|'fail'|'error'|'skip', detail?, latency_ms? }] */
+export function doctorModel(platform, chat, platformError = null) {
+  const rowOf = (c) => ({ kind: c.status === 'skip' ? 'dim' : 'row', key: `${icon(c.status)} ${c.name}`, text: [c.detail, c.latency_ms != null ? `${c.latency_ms}ms` : null].filter(Boolean).join(' · ') || (c.status === 'pass' ? 'ok' : c.status) });
+  const out = [{ kind: 'head', text: 'Doctor' }];
+  if (platformError) out.push(row('✖ quox doctor', platformError));
+  for (const c of platform || []) out.push(rowOf(c));
+  out.push({ kind: 'gap' }, { kind: 'head', text: 'Chat' });
+  for (const c of chat || []) out.push(rowOf(c));
+  const all = [...(platform || []), ...(chat || [])];
+  const count = (s) => all.filter(c => c.status === s || (s === 'fail' && c.status === 'error')).length;
+  out.push({ kind: 'gap' }, { kind: 'dim', text: `${count('pass')} passed · ${count('warn')} warning${count('warn') === 1 ? '' : 's'} · ${count('fail')} failed` });
+  return out;
+}
+
+/** Chat checks, each on its own: the chat routes answer, a provider is connected, the capability contract. */
+export async function chatChecks(api, providerTypes = ['openai', 'anthropic', 'ollama']) {
+  const one = async (name, fn) => { try { return { name, ...(await fn()) }; } catch (e) { return { name, status: 'fail', detail: e?.status ? `HTTP ${e.status} ${e.message || ''}`.trim() : (e?.message || 'failed') }; } };
+  return Promise.all([
+    one('Chat server', async () => {
+      if (!api.conversations) return { status: 'skip', detail: 'not available in this mode' };
+      const t0 = Date.now(); await api.conversations(1);
+      return { status: 'pass', detail: 'conversation routes answer for this login', latency_ms: Date.now() - t0 };
+    }),
+    one('AI provider', async () => {
+      if (!api.connections) return { status: 'skip', detail: 'not available in this mode' };
+      // The same provider status as /model and /connect (providers.js): the server's capabilities first.
+      const [r, caps] = await Promise.all([api.connections(), api.capabilities ? api.capabilities() : null]);
+      const ready = CHOICES.filter(c => providerState({ cap: c.cap || c.id, vault: c.vault }, caps, r).state === 'connected').map(c => c.name);
+      if (ready.length) return { status: 'pass', detail: `ready: ${ready.join(', ')}` };
+      if (!r.ok && !caps?.ok) return { status: 'fail', detail: `could not read the vault: ${r.error}` };
+      return { status: 'warn', detail: 'no AI provider is ready; /connect openai' };
+    }),
+    one('Capabilities', async () => {
+      if (!api.capabilities) return { status: 'skip', detail: 'not available in this mode' };
+      const res = await api.capabilities();
+      if (res && res.ok === false) return res.missing ? { status: 'warn', detail: 'this server has no capability contract yet (GET /api/v1/capabilities)' } : { status: 'fail', detail: res.error || 'failed' };
+      const m = capabilityMap(res);
+      if (!m) return { status: 'warn', detail: 'unexpected capability response' };
+      const names = (a) => res.capabilities.filter(c => c?.availability === a).map(capabilityName);
+      const off = names('unavailable'), setup = names('requires_setup');
+      const more = (l) => `${l.slice(0, 4).join(', ')}${l.length > 4 ? ` +${l.length - 4} more` : ''}`;
+      const parts = [`${Object.keys(m).length} known`];
+      if (off.length) parts.push(`unavailable here: ${more(off)}`);
+      if (setup.length) parts.push(`needs setup: ${more(setup)}`);
+      if (!off.length && !setup.length) parts.push('all available');
+      return { status: off.length ? 'warn' : 'pass', detail: parts.join(', ') };
+    })
+  ]);
+}

package/lib/quoxon/slash/picker.js

@@ -0,0 +1,56 @@
+/**
+ * A modal list under the composer (the /resume picker, the /config card). While open it takes every key,
+ * like the /connect card: Up/Down select, Enter picks, Esc closes, Left/Right/Space go to onAdjust.
+ * Typing (any text but a Space the card uses) closes it and goes to the composer, so a slash command typed
+ * while it is open runs instead of being read as navigation (R3 D2). onEvent returns false for those keys.
+ */
+export function createPicker({ refresh = () => {} } = {}) {
+  let cur = null; // { title, rows, sel, hint, onPick, onAdjust, onClose, rowsFn }
+  const close = () => { const c = cur; cur = null; c?.onClose?.(); refresh(); };
+  return {
+    isOpen: () => Boolean(cur),
+    open(spec) { cur = { sel: 0, ...spec }; refresh(); },
+    close,
+    rows: () => (cur ? (cur.rowsFn ? cur.rowsFn() : cur.rows) : []),
+    onEvent(e) {
+      if (!cur) return false;
+      const rows = cur.rowsFn ? cur.rowsFn() : cur.rows;
+      // onChar(char, sel): a card key such as f or d. true, or a new selection index = handled.
+      if (e.type === 'text' && cur.onChar) {
+        const r = cur.onChar(e.text, cur.sel);
+        if (r === true || typeof r === 'number') {
+          if (typeof r === 'number') {
+            const n = (cur.rowsFn ? cur.rowsFn() : cur.rows).length;
+            cur.sel = Math.max(0, Math.min(r, Math.max(0, n - 1)));
+          }
+          refresh();
+          return true;
+        }
+      }
+      if (e.type === 'paste' || (e.type === 'text' && !(e.text === ' ' && cur.onAdjust))) { close(); return false; } // typing goes to the composer
+      if (e.type !== 'key' && !(e.type === 'text' && e.text === ' ')) return true;
+      const name = e.type === 'text' ? 'space' : e.name;
+      if (name === 'escape' || name === 'ctrl-c') { close(); return true; }
+      if (name === 'up' && rows.length) cur.sel = (cur.sel - 1 + rows.length) % rows.length;
+      else if (name === 'down' && rows.length) cur.sel = (cur.sel + 1) % rows.length;
+      else if ((name === 'left' || name === 'right' || name === 'space') && cur.onAdjust) cur.onAdjust(cur.sel, name === 'left' ? -1 : 1);
+      else if (name === 'enter') {
+        const c = cur; const pick = rows[c.sel];
+        if (c.keepOpen?.(c.sel)) c.onPick?.(pick, c.sel);
+        else { cur = null; c.onPick?.(pick, c.sel); }
+      }
+      refresh();
+      return true;
+    },
+    view() {
+      if (!cur) return null;
+      const rows = cur.rowsFn ? cur.rowsFn() : cur.rows;
+      const max = 10;
+      const start = Math.max(0, Math.min(cur.sel - max + 1, rows.length - max));
+      const title = cur.titleFn ? cur.titleFn() : cur.title;
+      const more = Math.max(0, rows.length - max);
+      const view = rows.slice(start, start + max);
+      return { title, rows: view, sel: cur.sel - start, more, hint: cur.hint, empty: cur.empty };
+    }
+  };
+}

package/lib/quoxon/slash/restart.js

@@ -0,0 +1,202 @@
+/**
+ * /restart and the "newer build installed" notice.
+ *
+ * The installed quox is whatever `quox` on PATH runs: a symlink to cli/bin/quox.js, or a small wrapper
+ * script that execs one (the dev box's ~/bin/quox). Its build is the git HEAD of that CLI tree, read
+ * locally (no fetch, no network). The running build is that HEAD captured when this client started, so a
+ * refresh of the tree under a running client shows up as "newer installed".
+ */
+import { execFile, execFileSync, spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+
+/** The CLI tree this code runs from (…/cli). */
+export const RUNNING_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+export const NEWER_NOTICE = 'A newer quox is installed. /restart to use it.';
+export const DIFFERENT_NOTICE = 'A different quox build is installed. /restart to use it.';
+
+export function findOnPath(name = 'quox', env = process.env) {
+  for (const dir of String(env.PATH || '').split(delimiter)) {
+    if (!dir) continue;
+    const p = join(dir, name);
+    try { accessSync(p, constants.X_OK); if (statSync(p).isFile()) return p; } catch { /* next */ }
+  }
+  return null;
+}
+
+const isCliRoot = (d) => existsSync(join(d, 'lib', 'core', 'version.js')) && existsSync(join(d, 'bin', 'quox.js'));
+
+/** The CLI root a `quox` executable runs, or null. */
+export function cliRootOf(bin) {
+  if (!bin) return null;
+  let real;
+  try { real = realpathSync(bin); } catch { return null; }
+  if (/[/\\]bin[/\\]quox(\.js)?$/.test(real)) { const d = resolve(dirname(real), '..'); if (isCliRoot(d)) return d; }
+  try {
+    if (statSync(real).size > 65536) return null;
+    const m = /(\/[^\s"'$]+)\/bin\/quox\.js/.exec(readFileSync(real, 'utf8'));
+    if (m && isCliRoot(m[1])) return m[1];
+  } catch { /* unreadable */ }
+  return null;
+}
+
+const git = (root, args) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).trim();
+export function headOf(root) { try { return root ? git(root, ['rev-parse', '--short', 'HEAD']) || null : null; } catch { return null; } }
+/** true / false, or null when it cannot be told. */
+export function isAncestor(root, a, b) {
+  try { execFileSync('git', ['-C', root, 'merge-base', '--is-ancestor', a, b], { stdio: 'ignore', timeout: 2000 }); return true; }
+  catch (e) { return e?.status === 1 ? false : null; }
+}
+
+/**
+ * Compare the running build with the installed one. -> notice text or null. `deps` lets tests stand in for
+ * git and PATH.
+ */
+export function newerBuild({ startSha, runningRoot = RUNNING_ROOT, env = process.env, deps = {} } = {}) {
+  const d = { findOnPath, cliRootOf, headOf, isAncestor, ...deps };
+  if (!startSha) return null;
+  const root = d.cliRootOf(d.findOnPath('quox', env)) || runningRoot;
+  const head = d.headOf(root);
+  if (!head || head === startSha || head.startsWith(startSha) || startSha.startsWith(head)) return null;
+  if (d.isAncestor(root, startSha, head) === true) return NEWER_NOTICE;
+  if (d.isAncestor(root, head, startSha) === true) return null; // the installed build is older than this one: nothing to gain
+  return DIFFERENT_NOTICE; // unrelated or unknown history: say so, never claim "newer
+}
+
+/** The installed build's id (its CLI tree's git HEAD), read locally. null when it cannot be told. */
+export function installedBuildId({ runningRoot = RUNNING_ROOT, env = process.env } = {}) {
+  return headOf(cliRootOf(findOnPath('quox', env)) || runningRoot);
+}
+
+/**
+ * Poll at most every `everyMs`; calls onNotice(text, buildId) once. -> stop().
+ * With `repeat`, keeps watching and calls onNotice again for each LATER installed build (a new id).
+ */
+// settleMs defaults to 0 here (announce at once); the TUI (main.js) passes settleMsFrom() so real sessions settle.
+export const RESTART_SETTLE_MS = 120000; // a newer build must stay the installed one this long before it is announced
+export const RESTART_BOOT_WINDOW_MS = 5 * 60 * 1000; // after a start, the settle window runs from the start
+
+export function settleMsFrom(env = process.env) {
+  const n = Number(env.QUOX_RESTART_SETTLE_MS);
+  return env.QUOX_RESTART_SETTLE_MS != null && env.QUOX_RESTART_SETTLE_MS !== '' && Number.isFinite(n) && n >= 0 ? n : RESTART_SETTLE_MS;
+}
+
+export function startBuildWatch({ onNotice, everyMs = 60000, check = newerBuild, repeat = false, buildId = installedBuildId, settleMs = 0, now = Date.now, ...opts } = {}) {
+  let last; // repeat mode: the last build announced
+  let seen; let seenAt = 0; let seenNotice = null; // repeat mode: the build waiting to settle, and when it last changed
+  const bootAt = now();
+  const id = setInterval(() => {
+    let t = null;
+    try { t = check(opts); } catch { t = null; }
+    if (!t) return;
+    let b = null;
+    try { b = buildId(opts); } catch { b = null; }
+    if (!repeat) { clearInterval(id); onNotice(t, b); return; }
+    if (b === last && last !== undefined) return;
+    if (b !== seen || seen === undefined) { seen = b; seenAt = now(); } // a new build resets the settle timer
+    seenNotice = t;
+    const t0 = now() - bootAt < RESTART_BOOT_WINDOW_MS ? Math.max(seenAt, bootAt) : seenAt;
+    if (now() - t0 < settleMs) return;
+    last = b;
+    onNotice(seenNotice, b);
+  }, everyMs);
+  id.unref?.();
+  return () => clearInterval(id);
+}
+
+/**
+ * Same arguments, minus any earlier resume target, plus --resume <id> for this conversation. The profile and
+ * session name this client is using are carried over when the original command line did not name them.
+ */
+export function restartArgs(argv = [], conversationId = null, { profile = null, name = null } = {}) {
+  const out = [];
+  const pin = Boolean(profile) && !argv.includes('--demo'); // the profile the session RESOLVED wins over whatever argv said
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (pin && (a === '-p' || a === '--profile')) { const n = argv[i + 1]; if (n !== undefined && !n.startsWith('-')) i++; continue; }
+    if (pin && a.startsWith('--profile=')) continue;
+    if (a === '--conversation') { i++; continue; }
+    if (a === '--resume') { const n = argv[i + 1]; if (n !== undefined && !n.startsWith('-')) i++; continue; }
+    if (/^--(resume|conversation)=/.test(a)) continue;
+    out.push(a);
+  }
+  const has = (...f) => out.some(a => f.includes(a) || f.some(x => a.startsWith(`${x}=`)));
+  if (pin) out.push('-p', profile);
+  if (name && !has('-n', '--name')) out.push('-n', name);
+  return conversationId ? [...out, '--resume', conversationId] : out;
+}
+
+/** The quox a restart would run: the one on PATH, else this client's own tree. -> [command, leading args]. */
+export function restartTarget(env = process.env, bin = findOnPath('quox', env)) {
+  return bin ? [bin, []] : [process.execPath, [join(RUNNING_ROOT, 'bin', 'quox.js')]];
+}
+
+/**
+ * Before the client lets go of the terminal: can the installed quox start at all? Runs `quox --version`
+ * (no network, no login). -> Promise<{ ok, bin (what runs), onPath (the PATH quox or null), version?, error? }>. A failure keeps the user in this client.
+ */
+export function checkRestart({ env = process.env, bin = findOnPath('quox', env), run = execFile, timeoutMs = 15000 } = {}) {
+  const [cmd, lead] = restartTarget(env, bin);
+  return new Promise((done) => {
+    run(cmd, [...lead, '--version'], { env, timeout: timeoutMs, encoding: 'utf8' }, (err, stdout, stderr) => {
+      if (err) {
+        const why = err.code === 'ENOENT' || err.code === 'EACCES' ? `${err.code}: it cannot be run`
+          : err.killed ? `no answer in ${Math.round(timeoutMs / 1000)} s`
+            : String(stderr || err.message || 'failed').trim().split('\n')[0].slice(0, 160);
+        return done({ ok: false, bin: cmd, onPath: bin || null, error: why });
+      }
+      done({ ok: true, bin: cmd, onPath: bin || null, version: String(stdout || '').trim().split('\n')[0] || null });
+    });
+  });
+}
+
+/** Env var carrying the held slot name from the old client to its restarted successor. */
+export const RESTART_SLOT_ENV = 'QUOX_RESTART_SLOT';
+/** Env var carrying the /attach target (`agent:<id>` or `slot:<name>`) to the restarted successor. */
+export const RESTART_ATTACH_ENV = 'QUOX_RESTART_ATTACH';
+/** Env var carrying one line for the restarted client to say first (a failed /update says why there). */
+export const RESTART_NOTE_ENV = 'QUOX_RESTART_NOTE';
+/** Env var carrying the window's own org (#1034: /org switch is window-scoped) to the restarted successor. */
+export const RESTART_ORG_ENV = 'QUOX_RESTART_ORG';
+/** Env var carrying the window's /mode (PLAN MODE: only 'plan' is carried; ask is the default) to the restarted successor. */
+export const RESTART_MODE_ENV = 'QUOX_RESTART_MODE';
+
+/** Terminal modes the client turns on (bracketed paste, focus reporting, hidden cursor): all off before the hand-over. */
+export const TERMINAL_RESTORE = '\x1b[?2004l\x1b[?1004l\x1b[?25h\x1b[?1006l\x1b[?1002l\x1b[?1000l'; // bracketed paste, focus, cursor; mouse tracking off (QUOXON-MOUSE)
+
+/** Give the terminal back in a plain state: cooked mode, stdin paused, modes off. */
+export function restoreTerminal({ stdin = process.stdin, stdout = process.stdout } = {}) {
+  try { if (stdin?.isTTY) stdin.setRawMode?.(false); stdin?.pause?.(); } catch { /* not a tty */ }
+  try { if (stdout?.isTTY) stdout.write(TERMINAL_RESTORE); } catch { /* closed */ }
+}
+
+/**
+ * What a restart runs: { cmd, args, env }. The installed quox (or this tree), the same arguments with --resume
+ * for this conversation, and the one-shot hand-over env (held slot, attach, org, plan mode) for the successor.
+ */
+export function restartPlan({ argv, conversationId, profile = null, name = null, slot = null, attach = null, org = null, mode = null, env = process.env, bin = findOnPath('quox', env) }) {
+  const args = restartArgs(argv, conversationId, { profile, name });
+  let childEnv = profile && !argv.includes('--demo') ? { ...env, QUOX_PROFILE: profile } : env; // belt and braces: same profile even if -p were lost
+  if (slot) childEnv = { ...childEnv, [RESTART_SLOT_ENV]: slot }; // the held slot rides along; the new client takes it over before this one is gone
+  if (attach) childEnv = { ...childEnv, [RESTART_ATTACH_ENV]: attach }; // so does the attached agent or slot
+  if (org) childEnv = { ...childEnv, [RESTART_ORG_ENV]: org }; // and the window's org (never the profile's file)
+  if (mode === 'plan') childEnv = { ...childEnv, [RESTART_MODE_ENV]: 'plan' }; // and the window's /mode (never the profile)
+  const [cmd, lead] = restartTarget(env, bin);
+  return { cmd, args: [...lead, ...args], env: childEnv };
+}
+
+/**
+ * Run the installed quox in this terminal, wait for it, and hand back { code } (its exit code), or
+ * { error } when it could not be started (the caller stays in the current client and says so).
+ * Only used when there is no launcher (QUOX_NO_LAUNCHER=1, or no handoff dir): it NESTS the successor under
+ * this process, which stays resident until the successor exits. The launcher path (launcher.js) does not.
+ */
+export function execRestart({ argv, conversationId, profile = null, name = null, slot = null, attach = null, org = null, mode = null, env = process.env, spawn = spawnSync, bin = findOnPath('quox', env), restore = restoreTerminal }) {
+  const plan = restartPlan({ argv, conversationId, profile, name, slot, attach, org, mode, env, bin });
+  restore(); // the child owns the terminal now
+  const r = spawn(plan.cmd, plan.args, { stdio: 'inherit', env: plan.env });
+  if (r.error) return { error: `${r.error.code || 'failed'}: ${r.error.message}`, bin: plan.cmd };
+  return { code: r.status ?? (r.signal ? 128 + (os.constants.signals[r.signal] || 0) : 1), bin: plan.cmd };
+}

package/lib/quoxon/slash/resume.js

@@ -0,0 +1,59 @@
+/**
+ * /resume and `quox --resume`: pick a recent conversation, show its last turns as ordinary history, and
+ * continue it. Conversations come from GET /api/v1/conversations (title, updated_at, turn_count); the agent
+ * comes from the session index (GET /api/v1/sessions) when that answers, and names set with /rename from
+ * the local name store.
+ */
+export const RESUME_TURNS = 20;
+
+export function age(iso, now = Date.now()) {
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return '?';
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.round(s / 60)}m ago`;
+  if (s < 86400) return `${Math.round(s / 3600)}h ago`;
+  return `${Math.round(s / 86400)}d ago`;
+}
+
+/** -> [{ id, title, agent, updated_at, turns }] newest first. */
+export function resumeRows(conversations = [], index = null, names = {}) {
+  const agentOf = new Map();
+  for (const r of index?.rows || []) if (r.kind === 'conversation' && r.id) agentOf.set(r.id, r.agent || null);
+  return conversations.map(c => ({
+    id: c.id,
+    title: names[c.id]?.name || c.title || '(untitled)',
+    agent: agentOf.get(c.id) ?? null,
+    updated_at: c.updated_at || null,
+    turns: c.turn_count ?? null
+  })).sort((a, b) => String(b.updated_at || '').localeCompare(String(a.updated_at || '')));
+}
+
+export const pickerRow = (r, now = Date.now()) => ({ key: r.id.slice(0, 12), text: `${r.title} · ${r.agent || 'agent not recorded'} · ${age(r.updated_at, now)}${r.turns != null ? ` · ${r.turns} turn${r.turns === 1 ? '' : 's'}` : ''}` });
+
+/** An id, an id prefix (4+), or a session name/title -> { row } | { ambiguous:[ids] } | { none:true }. */
+export function matchConversation(rows, q) {
+  const s = String(q || '').trim();
+  if (!s) return { none: true };
+  const exact = rows.find(r => r.id === s);
+  if (exact) return { row: exact };
+  const lower = s.toLowerCase();
+  const byName = rows.filter(r => r.title.toLowerCase() === lower);
+  if (byName.length === 1) return { row: byName[0] };
+  const pre = s.length >= 4 ? rows.filter(r => r.id.startsWith(s)) : [];
+  if (pre.length === 1) return { row: pre[0] };
+  const hits = byName.length ? byName : pre;
+  return hits.length > 1 ? { ambiguous: hits.map(r => r.id) } : { none: true };
+}
+
+/** Stored turns -> history items (user prompts and answers, rendered as normal history). */
+export function turnsToHistory(turns = [], max = RESUME_TURNS) {
+  const list = turns.filter(t => (t.role === 'user' || t.role === 'assistant') && String(t.content || '').trim());
+  const shown = list.slice(-max);
+  return {
+    items: shown.map(t => (t.role === 'user' ? { kind: 'user', text: String(t.content) } : { kind: 'text', text: String(t.content) })),
+    answers: shown.filter(t => t.role === 'assistant').map((t, i) => ({ id: `resumed_${i}`, text: String(t.content) })),
+    shown: shown.length,
+    total: list.length
+  };
+}