quoxcli 0.3.1 → 0.4.0

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

@@ -12,7 +12,7 @@ import { loadRules, rulesContext } from './rules.js';
 import { createTranscript } from './transcript.js';
 import { createScreenRecorder, screenFramesEnabled } from './screenFrames.js';
 import { applySettings } from './slash/settings.js';
-import { headOf, RUNNING_ROOT, execRestart, restartPlan, checkRestart, startBuildWatch, settleMsFrom, restoreTerminal, RESTART_SLOT_ENV, RESTART_ATTACH_ENV, RESTART_NOTE_ENV, RESTART_MODE_ENV } from './slash/restart.js';
+import { 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';
@@ -39,7 +39,7 @@ export async function main(argv = process.argv.slice(2)) {
   if (opts.errors.length) { early?.release(); process.stderr.write(`quox: ${opts.errors.join('; ')}\n${USAGE}\n`); process.exitCode = 1; return; }
   const cwd = process.cwd().replace(process.env.HOME || '\0', '~');
   const { resolveCliVersion } = await import('../core/version.js');
-  let version = '0.3.1';
+  let version = '0.4.0';
   try { version = resolveCliVersion?.() || version; } catch { /* keep default */ }
   if (opts.print) return mainPrint(opts);
   let replay = null;
@@ -56,6 +56,15 @@ 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
@@ -118,7 +127,7 @@ export async function main(argv = process.argv.slice(2)) {
       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 };
+    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.

package/lib/quoxon/mouse.js

@@ -17,6 +17,17 @@
  */
 import { graphemes, composerFrom } from './textBuffer.js';
 
+/** The logical line (between newlines) holding buffer index `idx` -> { from, to }; a triple-click selects it. */
+export function lineAt(text, idx) {
+  const t = String(text);
+  const i = Math.max(0, Math.min(idx, t.length));
+  const from = t.lastIndexOf('\n', i - 1) + 1;
+  const nl = t.indexOf('\n', i);
+  return { from, to: nl < 0 ? t.length : nl };
+}
+
+export const MOUSE_HINT = 'Click your draft to place the cursor, drag to select (copies), double-click a word, triple-click a line. Shift+drag uses your terminal\'s own selection in most terminals. /mouse off gives native selection back.';
+
 export const MOUSE_ON = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
 export const MOUSE_OFF = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
 export const DSR = '\x1b[6n';
@@ -26,7 +37,7 @@ export const DOUBLE_MS = 400;
 export const DSR_TIMEOUT_MS = 400;
 
 export function mouseOnNote() {
-  return 'Mouse on. Click a ◆ sender to reply, click a card\'s y / n / c to answer, click or drag in your draft to place the cursor or select (Backspace deletes, typing replaces, double-click selects a word). While it is on your terminal sends clicks and the wheel to Quox: hold Shift to select or copy text (Option on macOS Terminal and iTerm2), and use Shift+wheel or the scrollbar to scroll back. /mouse off returns all of it.';
+  return 'Mouse on. Click a ◆ sender to reply, click a card\'s y / n / c to answer, click or drag in your draft to place the cursor or select (Backspace deletes, typing replaces, double-click selects a word, triple-click a line). While it is on your terminal sends clicks and the wheel to Quox: hold Shift to select or copy text (Option on macOS Terminal and iTerm2), and use Shift+wheel or the scrollbar to scroll back. /mouse off returns all of it.';
 }
 
 // ---- cell widths --------------------------------------------------------------------------------

package/lib/quoxon/objectiveOffer.js

@@ -0,0 +1,82 @@
+/**
+ * QUOXON objective offer (owner, live 2026-10-25 19:47). Attached to SEER (advisory, no image/X/site tools) the owner asked
+ * for a blog article, an image, a publish and a tweet draft, and got "I couldn't". Offer, don't give up: the server sends
+ * turn.objective_suggested (from the turn's tool selection and the shape of the ask, never the answer text) and the TUI
+ * asks once. It REPLACES the single-turn handoff card (one ask, not two):
+ *
+ *   ⚠ SEER asks: Make this an objective that runs until done?
+ *     do     create objective "<the user's words>"; you approve the plan, then each publish/post step
+ *     why    SEER can't run x post.
+ *   ▶ Make this an objective that runs until done? y yes · n no
+ *
+ * y = `quox objective create <goal>` + start (the plan decomposes and lands as an approval card). n does nothing.
+ */
+import { askText } from './ask.js';
+
+const clipQ = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t; };
+
+/** The suggestion from a turn event, when it applies to THIS window (attached to the agent it names). Else null. */
+export function objectiveFromEvent(ev, attachedAgent) {
+  if (!ev || ev.type !== 'turn.objective_suggested') return null;
+  const o = ev.objective_suggested;
+  const at = String(attachedAgent || '').toLowerCase();
+  if (!o || typeof o !== 'object' || !o.from || !o.goal || !at) return null;
+  if (String(o.from).toLowerCase() !== at) return null; // a suggestion about some other agent
+  const loop = o.mode === 'loop' && o.loop && Array.isArray(o.loop.capability_scope) && o.loop.capability_scope.length ? { goal_condition: String(o.loop.goal_condition || o.goal), capability_scope: o.loop.capability_scope.map(String), ...(o.loop.plain ? { plain: true } : {}), ...(Number.isInteger(o.loop.max_iterations) ? { max_iterations: o.loop.max_iterations } : {}), ...(o.loop.summary ? { summary: String(o.loop.summary) } : {}), ...(o.loop.until ? { until: String(o.loop.until) } : {}), ...(Number.isInteger(o.loop.every_seconds) ? { every_seconds: o.loop.every_seconds } : {}), ...(Number.isInteger(o.loop.max_duration_seconds) ? { max_duration_seconds: o.loop.max_duration_seconds } : {}), ...(Array.isArray(o.loop.done_check) && o.loop.done_check.length ? { done_check: o.loop.done_check } : {}) } : null; // QLOOP: a ready, engine-valid loop spec
+  return { from: at, fromName: String(o.from_name || at.toUpperCase()), goal: String(o.goal), reason: String(o.reason || '').trim(), tools: Array.isArray(o.tools) ? o.tools : [], ...(loop ? { loop } : {}) };
+}
+
+/** The ask line (drawn as the approval-style card). The goal is clipped for the card only, never in what yes creates. */
+export function objectiveAskText(o, cols = 100) {
+  if (o.loop && o.loop.plain) { // the user never said "loop": say what it does, in plain words, whole (it wraps; never clipped)
+    const mins = o.loop.max_duration_seconds ? Math.max(1, Math.round(o.loop.max_duration_seconds / 60)) : null;
+    const q = o.loop.summary ? `${o.loop.summary}?` : `This needs repeated checks: keep going until ${String(o.loop.goal_condition || o.goal).replace(/\s+/g, ' ').trim()}${mins ? `, up to ${mins} minute${mins === 1 ? '' : 's'}` : ''}?`;
+    return askText(q, { keys: 'y yes · n just once', who: o.fromName, reason: '', action: `keep going${o.loop.every_seconds ? `, checking about every ${o.loop.every_seconds} seconds,` : ''} using only ${o.loop.capability_scope.join(', ')}; you approve it before it starts` });
+  }
+  if (o.loop) return askText('Run this as a loop until it is done?', { keys: 'y/N', who: o.fromName, reason: o.reason, action: `create a loop "${clipQ(o.goal, Math.max(20, cols - 70))}" that may use only ${o.loop.capability_scope.join(', ')}; you approve it before it starts` });
+  const action = `create objective "${clipQ(o.goal, Math.max(20, cols - 60))}"; you approve the plan, then each publish/post step`;
+  return askText('Make this an objective that runs until done?', { keys: 'y/N', who: o.fromName, reason: o.reason, action });
+}
+
+export const objectiveStartedNote = (id) => `▶ Objective ${id} started. The plan will land as an approval card.`;
+export const objectiveWatchLine = (id) => `Watch it: quox objective get ${id}`;
+export const objectiveFailedNote = (goal, err) => `Objective not created: ${String(err?.message || err || 'unknown error')}. Retry: quox objective create ${JSON.stringify(goal)} --checkpoint`;
+
+// ---- report back into the conversation (owner 2026-10-26) ----
+const TERMINAL = new Set(['completed', 'completed_with_errors', 'failed', 'cancelled', 'aborted']);
+// A finished step's result is the node output JSON; its text is completion.value.
+const textOf = (r) => { const s = String(r ?? ''); if (!s.trimStart().startsWith('{')) return s; try { const o = JSON.parse(s); return typeof o?.completion?.value === 'string' ? o.completion.value : s; } catch { return s; } };
+const reportOf = (tasks) => {
+  const done = (tasks || []).filter(t => t.status === 'completed' && textOf(t.result).trim()).sort((a, b) => (a.sequence_num || 0) - (b.sequence_num || 0));
+  const pick = [...done].reverse().find(t => /report/i.test(String(t.title || ''))) || done[done.length - 1];
+  const text = pick ? textOf(pick.result).trim() : '';
+  return text.length > 1500 ? `${text.slice(0, 1499)}…` : text;
+};
+
+/** The lines the chat prints when an objective ends: the glyph line, then its report (or what did not complete). */
+export function objectiveFinishedLines(o) {
+  const tasks = Array.isArray(o.tasks) ? o.tasks : [];
+  const done = tasks.filter(t => t.status === 'completed').length;
+  const title = String(o.title || o.id || '').replace(/\s+/g, ' ').slice(0, 80);
+  const lines = [`◎ OBJECTIVE │ ${title} │ ${o.status}, ${done}/${tasks.length} steps`];
+  const report = reportOf(tasks);
+  if (report) lines.push(...report.split('\n').map(l => l.trimEnd()).filter(Boolean));
+  if (o.status !== 'completed' && o.error_message) lines.push(String(o.error_message).slice(0, 400));
+  return lines;
+}
+
+/**
+ * Poll an objective while this window is open and say how it ended. get() -> the objective with its tasks; a failed read is
+ * retried, never fatal. Resolves { finished, status }. Gives up quietly at maxMs or when stopped() (the inbox item covers a closed window).
+ */
+export async function watchObjective({ get, say, intervalMs = 8000, maxMs = 6 * 3600 * 1000, stopped = () => false } = {}) {
+  const t0 = Date.now();
+  while (Date.now() - t0 < maxMs && !stopped()) {
+    try {
+      const o = await get();
+      if (o && TERMINAL.has(o.status)) { for (const l of objectiveFinishedLines(o)) say(l); return { finished: true, status: o.status }; }
+    } catch { /* a transient read: try again */ }
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  return { finished: false };
+}

package/lib/quoxon/objects/index.js

@@ -11,6 +11,7 @@ import { agentCard } from './agent.js';
 import { memoryFacts } from './memory.js';
 import { rulesLadder } from './ladder.js';
 import { proofChain, reconcileView } from './proof.js';
+import { wrapHang } from './model.js';
 import { awayCard } from './away.js';
 import { sitrepCard } from './sitrep.js';
 import { fleetView } from './fleet.js';
@@ -91,10 +92,27 @@ export async function runObjectCommand(cmd, arg, ctx) {
       });
     }
     case '/proof': {
-      const calls = toolCalls(ctx.items).filter(b => b.envelopeId);
-      const t = a ? calls.find(b => b.envelopeId === a || b.callId === a) : calls[calls.length - 1];
-      if (!t) return { note: a ? `No tool call "${a}" with an envelope in this session.` : 'No tool call with an envelope id in this session yet.', tone: 'warn' };
-      return wrap('proof', () => o.proof({ tool: t.tool, status: t.status, envelopeId: t.envelopeId, callId: t.callId }));
+      const all = toolCalls(ctx.items);
+      const calls = all.filter(b => b.envelopeId);
+      const newest = [...calls].reverse(); // 1 = newest
+      const num = /^\d{1,3}$/.test(a) ? Number(a) : 0;
+      const pick = (b) => wrap('proof', () => o.proof({ tool: b.tool, status: b.status, envelopeId: b.envelopeId, callId: b.callId }));
+      if (num >= 1 && newest[num - 1]) return pick(newest[num - 1]);
+      const t = a && !num ? calls.find(b => b.envelopeId === a || b.callId === a) : (calls.length === 1 ? calls[0] : null);
+      if (t) return pick(t);
+      if (a) return { note: `No tool call "${a}" with an envelope in this session. /proof lists them; /evidence exports the whole conversation.`, tone: 'warn' };
+      if (!calls.length) {
+        const ran = all.length ? ` ${all.length} tool call${all.length === 1 ? '' : 's'} ran, but the server reported no envelope id for ${all.length === 1 ? 'it' : 'them'}.` : '';
+        return { note: `No tool call with an envelope id in this session yet.${ran} /evidence exports what the server filed for this conversation.`, tone: 'warn' };
+      }
+      // Several calls: list the envelope ids, newest first (ten), then how many more.
+      const shown = newest.slice(0, 10);
+      const W = Math.max(20, (ctx.cols || 1e9) - 4);
+      const lines = [...wrapHang(`${calls.length} tool call${calls.length === 1 ? '' : 's'} with an envelope in this conversation (newest first):`, W, 2),
+        ...shown.flatMap((b, i) => wrapHang(`  ${i + 1}. ${b.envelopeId}  ${b.tool || 'tool'} ${b.status || ''}`.trimEnd(), W, 5))];
+      if (newest.length > shown.length) lines.push(`  ${newest.length - shown.length} more (older)`);
+      lines.push(...wrapHang('/proof <number or id> shows one chain. /evidence exports the signed bundle of all of them.', W, 2));
+      return { note: lines.join('\n'), lines, tone: 'dim' };
     }
     case '/reconcile': {
       const unk = toolCalls(ctx.items).filter(b => b.status === 'effect_unknown');

package/lib/quoxon/objects/model.js

@@ -21,6 +21,39 @@ export const fit = (s, n) => {
   return g.length > n ? g.slice(0, Math.max(0, n - 1)).join('') + '…' : g.join('');
 };
 
+/**
+ * Wrap a string to `width` display chars, never clipping: breaks at spaces, indents each continuation by `hang`
+ * spaces beyond the line's own leading indent, and hard-splits a token longer than the line (an id stays whole
+ * across rows, no ellipsis). -> string[]
+ */
+export function wrapHang(text, width, hang = 4) {
+  const src = String(text ?? '');
+  const lead = (src.match(/^ */) || [''])[0];
+  const words = src.trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return [src];
+  const w = Math.max(8, width);
+  const lines = [];
+  let cur = lead;
+  let curHas = false;
+  const pad = () => lead + ' '.repeat(hang);
+  const push = () => { lines.push(cur); cur = pad(); curHas = false; };
+  for (let word of words) {
+    while (len(cur) + (curHas ? 1 : 0) + len(word) > w) {
+      if (curHas) { push(); continue; }
+      const room = Math.max(1, w - len(cur));
+      const g = [...word];
+      if (g.length <= room) break;
+      cur += g.slice(0, room).join('');
+      word = g.slice(room).join('');
+      push();
+    }
+    cur += (curHas ? ' ' : '') + word;
+    curHas = true;
+  }
+  if (curHas) lines.push(cur);
+  return lines;
+}
+
 /** Clip a row of segments to n chars total; later segments shrink first, the last one gets the ellipsis. */
 export function fitRow(row, n) {
   const out = [];

package/lib/quoxon/objects/proof.js

@@ -10,7 +10,7 @@
  * D3: a tool that ended effect_unknown is reconciled against the server's own record of the call
  * (the ops.tool envelope's payload.success). No envelope id means it cannot be reconciled from here.
  */
-import { seg, fit, short, plural } from './model.js';
+import { seg, fit, plural, wrapHang } from './model.js';
 
 const LINKS = ['AEE', 'AOCL', 'TOOL', 'WARD'];
 
@@ -19,7 +19,7 @@ export function chainLinks(d) {
   const t = d.tool || {};
   const env = d.envelope?.ok ? d.envelope.env : null;
   const out = [];
-  out.push(env ? { name: 'AEE', ok: true, sub: `envelope ${short(env.id || t.envelopeId, 14)}` }
+  out.push(env ? { name: 'AEE', ok: true, sub: 'envelope read, id above' }
     : { name: 'AEE', ok: d.envelope?.status === 404 ? false : null, sub: d.envelope?.status === 404 ? 'envelope not found' : `envelope not read${d.envelope?.error ? ` (${fit(d.envelope.error, 24)})` : ''}` });
   const aocl = d.aocl?.ok ? d.aocl.list || [] : null;
   if (aocl && aocl.length) {
@@ -52,7 +52,13 @@ const markOf = (ok) => (ok === true ? ['✔', 'ok'] : ok === false ? ['✖', 'er
 export function proofChain(d, cols) {
   const links = chainLinks(d);
   const rows = [];
-  rows.push([seg('proof ', 'muted'), seg(fit(`${d.tool?.tool || 'tool call'}${d.tool?.envelopeId ? ` · ${short(d.tool.envelopeId, 18)}` : ''}`, cols - 10), 'value', true)]);
+  const envId = d.tool?.envelopeId || (d.envelope?.ok ? d.envelope.env?.id : null);
+  rows.push([seg('proof ', 'muted'), seg(fit(d.tool?.tool || 'tool call', cols - 10), 'value', true)]);
+  // The full id on its own row, never clipped, so it can be selected and copied whole.
+  if (envId) {
+    wrapHang(envId, cols - 7, 0).forEach((l, i) => rows.push([seg(i ? '   ' : 'id ', 'muted'), seg(l, 'value', true)]));
+    for (const t of [`read it back: quox aee get ${envId}`, 'check a bundle: quox evidence verify <file>']) for (const l of wrapHang(t, cols - 4, 2)) rows.push([seg(l, 'muted')]);
+  }
   if (cols >= 90) {
     const head = [], sub = [], cw = Math.max(23, Math.floor((cols - 4) / 4));
     links.forEach((l, i) => {
@@ -69,7 +75,9 @@ export function proofChain(d, cols) {
     links.forEach((l, i) => {
       const role = `proto:${l.name.toLowerCase() === 'tool' ? 'volt' : l.name.toLowerCase()}`;
       const [m, mr] = markOf(l.ok);
-      rows.push([seg(m, mr), seg(' '), seg(l.name.padEnd(5), l.name === 'TOOL' ? 'value' : role, true), seg(fit(l.sub, cols - 12), l.ok === false ? 'error' : 'muted')]);
+      const subs = wrapHang(l.sub, cols - 11, 0);
+      rows.push([seg(m, mr), seg(' '), seg(l.name.padEnd(5), l.name === 'TOOL' ? 'value' : role, true), seg(subs[0], l.ok === false ? 'error' : 'muted')]);
+      for (const more of subs.slice(1)) rows.push([seg(' '.repeat(7)), seg(more, l.ok === false ? 'error' : 'muted')]);
       if (i < 3) rows.push([seg(l.ok === true && links[i + 1].ok === true ? '┃' : '╎', l.ok === true && links[i + 1].ok === true ? 'indigo' : 'faint')]);
     });
   }

package/lib/quoxon/onboarding/shortcutOffer.js

@@ -0,0 +1,28 @@
+/**
+ * QUOXON-Q: after first-run onboarding succeeds, ONE offer (y/N, default No, asked once) to make `q` run quox.
+ * The answer is remembered in the CLI config (shortcutOffer = 'yes' | 'no'). A yes runs the same code as
+ * `quox shortcut add`. Nothing is offered when q already resolves to something (ours or not): never shadow.
+ */
+import { askText } from '../ask.js';
+import { addShortcut, whichOnPath, DEFAULT_NAME } from '../../core/shortcut.js';
+
+export const SHORTCUT_QUESTION = 'Want a shorter command? Type `q` instead of `quox`.';
+export const shortcutOfferLine = () => askText(SHORTCUT_QUESTION, { keys: 'y/N', who: 'Quox', action: `make \`${DEFAULT_NAME}\` a link to quox in a folder you own (no sudo, no shell edits); undo with: quox shortcut remove` });
+
+/** -> true when the offer should be shown now. */
+export function shouldOfferShortcut({ config, env = process.env, which = whichOnPath } = {}) {
+  if (config?.get?.('shortcutOffer')) return false; // asked once
+  return !which(DEFAULT_NAME, env);
+}
+
+/** Runs the offer. ask(line) -> string answer. -> { offered, accepted, result? } */
+export async function offerShortcut({ config, ask, out = (s) => process.stdout.write(s), env = process.env, add = addShortcut, which = whichOnPath } = {}) {
+  if (!shouldOfferShortcut({ config, env, which })) return { offered: false };
+  const answer = String(await ask(shortcutOfferLine()) ?? '').trim();
+  const accepted = /^y(es)?$/i.test(answer);
+  config.set('shortcutOffer', accepted ? 'yes' : 'no');
+  if (!accepted) return { offered: true, accepted: false };
+  const result = add({ name: DEFAULT_NAME, env });
+  out(`${result.ok ? '✔' : '✖'} ${result.message}\n`);
+  return { offered: true, accepted: true, result };
+}

package/lib/quoxon/onboarding/view.js

@@ -101,7 +101,7 @@ const Hint = ({ text, cols }) => h(Box, { paddingLeft: 2 }, h(Text, { color: c('
 
 // ---- the view ---------------------------------------------------------------------------------
 export function GettingStarted({
-  columns, version = '0.3.1', cwd = '', welcome = false, animateIntro, earlyInput = null,
+  columns, version = '0.4.0', cwd = '', welcome = false, animateIntro, earlyInput = null,
   journeyPath, dryRun = false, runner = null, preflightDeps, runChecks = runPreflight, findOllama = detectOllama,
   requestCredential, broker = null, finisher = null, onExit = () => {}, now = () => Date.now()
 }) {

package/lib/quoxon/orgSwitch.js

@@ -5,7 +5,7 @@ export const orgRows = (list) => (Array.isArray(list) ? list : []).map((o) => ({
 
 /**
  * Resolve a typed name or id against the user's orgs. Exact id, exact slug/name, then every word of the
- * query found in the name or slug (so "hot tubs hampshire" finds "Hot Tubs Hampshire Ltd"). Never guesses between ties.
+ * query found in the name or slug (so "acme widgets" finds "Acme Widgets Ltd"). Never guesses between ties.
  * -> { org } | { ambiguous: [orgs] } | { none: true }
  */
 export function matchOrg(query, list) {
@@ -31,3 +31,29 @@ export function orgLines(list, currentId) {
   const w = Math.min(36, Math.max(4, ...rows.map((o) => [...o.name].length)));
   return rows.map((o) => `${o.id === currentId ? '* ' : '  '}${o.name.padEnd(w)}  ${o.slug || o.id}${o.role ? `  (${o.role})` : ''}`);
 }
+
+/** `quox org switch` with no argument: the same list, numbered from 1, current org marked. */
+export function numberedOrgLines(list, currentId) {
+  const rows = orgRows(list);
+  const w = Math.min(36, Math.max(4, ...rows.map((o) => [...o.name].length)));
+  return rows.map((o, i) => `${o.id === currentId ? '*' : ' '} ${String(i + 1).padStart(String(rows.length).length)}) ${o.name.padEnd(w)}  ${o.slug || o.id}${o.role ? `  (${o.role})` : ''}`);
+}
+
+/** A typed answer to the numbered list: an exact slug/name/id first (so a numeric slug is never shadowed), then a 1-based number. */
+export function pickOrgByInput(input, list) {
+  const rows = orgRows(list);
+  const t = String(input ?? '').trim();
+  if (!t) return { none: true };
+  const m = matchOrg(t, rows);
+  const exactly = m.org && (m.org.slug === t || String(m.org.id).toLowerCase() === t.toLowerCase() || norm(m.org.name) === norm(t));
+  if (exactly) return m;
+  if (/^\d+$/.test(t)) { const n = Number(t); return n >= 1 && n <= rows.length ? { org: rows[n - 1] } : { none: true }; }
+  return m;
+}
+
+/** After a profile-wide `quox org switch`: how the other windows on that profile pick the change up. */
+export function sharedSwitchHint({ name, pids }) {
+  const n = pids.length;
+  return `${n} other quox session${n === 1 ? '' : 's'} ${n === 1 ? 'uses' : 'use'} profile "${name}" (pid ${pids.join(', ')}). `
+    + 'They pick this org up on their next token refresh; run /restart in a window to pick it up now. /org <name> moves one window only.';
+}

package/lib/quoxon/planSteps.js

@@ -0,0 +1,51 @@
+// QUOXON plan approval card (owner 2026-10-26 18:05: "i would deny based on the fact it's not even presenting a plan"):
+// an objective's "approve plan" item must list the plan's steps, and show the org the item really lives in.
+// Pure helpers plus one async enrich step; the card renders what this returns and nothing else.
+
+export const PLAN_STEPS_MAX = 8;
+/** Verbs that change things. Anything else reads as read-only (inspect, list, audit, report). */
+const CHANGES = /\b(upgrad\w*|updat\w*|restart\w*|redeploy\w*|deploy\w*|writ\w*|delet\w*|remov\w*|install\w*|migrat\w*|patch\w*|rollback|roll back|reboot\w*|creat\w*|apply|applies|rotat\w*|scal\w*|provision\w*|stop|start|kill|drop|reset|modify|modifies|change\w*|configur\w*)\b/i;
+export const changesThings = (title) => CHANGES.test(String(title || ''));
+
+/** Does this inbox item ask for approval of an objective's plan? */
+export const isPlanApproval = (it) => it?.payload?.source === 'objective_checkpoint'
+  && it?.payload?.checkpoint_type === 'plan_approval' && typeof it?.payload?.objective_id === 'string';
+
+/** Steps from an objective read: [{ n, title, agent, writes }]. Agent display name from `names` (id -> name), else the id. */
+export function stepsOf(objective, names = new Map()) {
+  const tasks = Array.isArray(objective?.tasks) ? objective.tasks : [];
+  return tasks.filter(t => t && t.title).map((t, i) => ({
+    n: i + 1, title: String(t.title), agent: t.agent_id ? String(names.get(t.agent_id) || t.agent_id) : null, writes: changesThings(t.title)
+  }));
+}
+
+/** Rows for the card: numbered lines plus "+N more" past the cap. Each row is a plain string. */
+export function planLines(steps, max = PLAN_STEPS_MAX) {
+  const list = Array.isArray(steps) ? steps : [];
+  const lines = list.slice(0, max).map(s => `${s.n}. ${s.writes ? '[changes]' : '[read-only]'} ${s.title}${s.agent ? ` · ${s.agent}` : ''}`);
+  if (list.length > max) lines.push(`+${list.length - max} more`);
+  return lines;
+}
+
+/**
+ * Attach { steps, orgId, orgName } as item._plan for a plan-approval item. Reads the objective once (cached by objective id
+ * in `cache`). Never throws: when the read fails the item is returned as it came and the card says the plan could not be loaded.
+ */
+export async function enrichPlanItem(item, { objectiveGet, agents = null, orgs = null, cache = new Map() } = {}) {
+  if (!isPlanApproval(item) || typeof objectiveGet !== 'function') return item;
+  const id = item.payload.objective_id;
+  if (!cache.has(id)) {
+    cache.set(id, (async () => {
+      try {
+        const o = await objectiveGet(id);
+        let names = new Map();
+        try { for (const a of (agents ? await agents() : []) || []) if (a?.agent_id && a.name) names.set(a.agent_id, a.name); } catch { /* ids stand in */ }
+        const orgId = item.org_id || o?.org_id || null;
+        let orgName = null;
+        try { orgName = orgId && orgs ? ((await orgs()) || []).find(x => x?.id === orgId)?.name || null : null; } catch { /* the short id stands in */ }
+        return { steps: stepsOf(o, names), orgId, orgName, loaded: true };
+      } catch (e) { cache.delete(id); return { steps: [], orgId: item.org_id || null, orgName: null, loaded: false, error: e?.message || 'failed' }; }
+    })());
+  }
+  return { ...item, _plan: await cache.get(id) };
+}

package/lib/quoxon/print.js

@@ -46,7 +46,7 @@ export async function runPrint({ api, prompt, agent = 'quox', output = 'text', c
   const sum = { tools: 0, approvals: 0, receipts: [] };
   let convo = conversation, doneSession = null, status = null, text = '', sawApproval = false, errorMsg = null, authFail = false;
   const seen = new Set();
-  let offer = null, handoff = null;
+  let offer = null, handoff = null, objective = null;
   let gate = null;
   try {
     for await (const ev of api.stream({ turnId, message: prompt, agent: agent || 'quox', conversationId: conversation, context, ...streamFields(choice), ...(promptProfile ? { promptProfile } : {}), ...(timeoutS > 0 ? { turnBudgetMs: timeoutS * 1000 } : {}) }, ctrl.signal)) {
@@ -62,6 +62,7 @@ export async function runPrint({ api, prompt, agent = 'quox', output = 'text', c
       else if (ev.type === 'tool.finished') { if (!seen.has(ev.call_id)) { seen.add(ev.call_id); sum.tools++; } if (ev.receipt?.ward_seq != null) sum.receipts.push(ev.receipt.ward_seq); }
       else if (ev.type === 'approval.requested') { sawApproval = true; sum.approvals++; }
       else if (ev.type === 'approval.resolved') sawApproval = false;
+      else if (ev.type === 'turn.objective_suggested' && ev.objective_suggested?.goal) objective = ev.objective_suggested; // QUOXON objective offer
       else if (ev.type === 'turn.handoff_suggested' && ev.handoff_suggested?.agent) handoff = ev.handoff_suggested; // QUOXON handoff offer
       else if (ev.type === 'turn.finished') status = ev.status || 'completed';
       else if (ev.type === 'error') errorMsg = isConsentError(ev) ? consentPrintMessage(ev, profile) : (ev.error || 'stream error');
@@ -85,7 +86,7 @@ export async function runPrint({ api, prompt, agent = 'quox', output = 'text', c
   if (!status) status = authFail ? 'auth' : 'failed';
 
   if (output === 'json') {
-    out(JSON.stringify({ type: 'summary', status, turn_id: turnId, conversation_id: convo, duration_ms: Date.now() - t0, server_stopped: serverStopped, ...sum, ...(handoff ? { handoff_suggested: handoff } : {}) }) + '\n');
+    out(JSON.stringify({ type: 'summary', status, turn_id: turnId, conversation_id: convo, duration_ms: Date.now() - t0, server_stopped: serverStopped, ...sum, ...(handoff ? { handoff_suggested: handoff } : {}), ...(objective ? { objective_suggested: objective } : {}) }) + '\n');
   } else if (text) out(text.endsWith('\n') ? text : text + '\n');
   if (authFail) err(`Not signed in for chat. Run: quox login -p <profile>\n`);
   else if (code === EXIT.approval) err('Held for approval: approve it in the dashboard or with `quox` /approvals.\n');
@@ -93,6 +94,8 @@ export async function runPrint({ api, prompt, agent = 'quox', output = 'text', c
   else if (errorMsg) err(`quox: ${errorMsg}\n`);
   if (offer && code !== EXIT.ok) err(`${offer}\n`);
   // QUOXON handoff offer: no y/N here, so name the exact one-turn command (same question, same conversation).
-  if (handoff && output !== 'json' && code === EXIT.ok) err(`quox: ${handoff.reason ? `${String(handoff.reason).replace(/\s+$/, '')} ` : ''}${handoff.name || handoff.agent} can answer it: quox --print --agent ${handoff.agent}${convo ? ` --conversation ${convo}` : ''} ${JSON.stringify(prompt)}\n`);
+  // QUOXON objective offer: no y/N here, so name the exact command that makes it an objective.
+  if (objective && output !== 'json' && code === EXIT.ok) err(`quox: ${objective.reason ? `${String(objective.reason).replace(/\s+$/, '')} ` : ''}Run it until done: quox objective create ${JSON.stringify(objective.goal)} --checkpoint\n`);
+  else if (handoff && output !== 'json' && code === EXIT.ok) err(`quox: ${handoff.reason ? `${String(handoff.reason).replace(/\s+$/, '')} ` : ''}${handoff.name || handoff.agent} can answer it: quox --print --agent ${handoff.agent}${convo ? ` --conversation ${convo}` : ''} ${JSON.stringify(prompt)}\n`);
   return code;
 }

package/lib/quoxon/qdragonFly.js

@@ -37,17 +37,18 @@ export function flyPose(ms) {
 /** The frame at `ms` since the pass began. still: the one fixed frame (mid-sky, wings raised). mono: shapes only. */
 /** The sky's size for a terminal `termRows` tall: the mid Q, or the small Q (headroom scaled to match) when the mid sky would
  *  not leave 10 rows for the transcript and composer. Never taller than max(12, termRows - 10). */
-export function flySky(termRows) {
-  const room = Math.max(12, (termRows || 40) - 10);
+export function flySky(termRows, chromeH = null) {
+  const room = chromeH == null ? Math.max(12, (termRows || 40) - 10) : (termRows || 40) - chromeH - 2; // measured chrome (app.js): the sky + margin + chrome must stay under the terminal height or Ink wipes the screen
   const fits = (size, top) => dragonLayout(120, { size, lm: 0, ty: top }).rows <= room;
-  if (fits(SIZE, TOP)) return { size: SIZE, top: TOP, bob: BOB };
+  if (fits(SIZE, TOP)) return { size: SIZE, top: TOP, bob: BOB, fits: true };
   const k = DSIZES.small / DSIZES[SIZE];
-  return { size: 'small', top: Math.round(TOP * k), bob: Math.max(1, Math.round(BOB * k)) };
+  const top = Math.round(TOP * k);
+  return { size: 'small', top, bob: Math.max(1, Math.round(BOB * k)), fits: chromeH == null || dragonLayout(120, { size: 'small', lm: 0, ty: top }).rows <= room };
 }
 
-export function flyFrame(ms, cols, { still = false, mono = false, theme = 'dark', termRows } = {}) {
+export function flyFrame(ms, cols, { still = false, mono = false, theme = 'dark', termRows, chromeH = null } = {}) {
   const t = still ? 0 : Math.max(0, Math.min(ms, FLY_PASS_MS));
-  const { size: SIZE, top: TOP, bob: BOB } = flySky(termRows);
+  const { size: SIZE, top: TOP, bob: BOB } = flySky(termRows, chromeH);
   const probe = dragonLayout(cols, { size: SIZE, lm: 0, ty: TOP });
   const rows = probe.rows;
   const xc = still ? cols / 2 : -SPAN + (cols + 2 * SPAN) * kf(t, [[0, 0], [FLY_PASS_MS, 1]]);

package/lib/quoxon/qmotion.js

@@ -11,6 +11,7 @@ import { helloCells, helloGradient, helloMs } from './qhello.js';
 import { mono, c, clip, isLight } from './theme.js';
 import { CLIPS, clipCells, clipCaption, eggCells, EGG_MS } from './qdragonScenes.js';
 import { reducedMotion } from './motion/clock.js';
+import { flySky } from './qdragonFly.js';
 import { FrameContext, useFrame } from './motion/frame.js';
 const isQuiet = () => reducedMotion(); // motion only (NO_COLOR is colour only; QGlyph falls back to the circled Q itself)
 import { termRows } from './term.js';
@@ -130,3 +131,19 @@ export function DragonLive({ cols, rows }) {
     ...cells.map((row, k) => h(Text, { key: k, wrap: 'truncate' }, ...cellNodes(row, `d${k}-`))),
     h(Text, { color: c('dim') }, clip(caption, Math.max(10, cols - 2))));
 }
+
+/** Rows the 15-row dragon clips need besides the chrome: the clip, its caption and the margin above it. */
+export const CLIP_ROWS = 17;
+/** Does an explicit /dragon <clip> fit? { ok } or { ok:false, note } (one line, never silent). Unknown size (null rows) is ok. */
+export function clipRoom(clipName, rows, chromeH = 10) {
+  if (!rows) return { ok: true };
+  const need = CLIP_ROWS + chromeH + 2;
+  return rows >= need ? { ok: true } : { ok: false, note: `${clipName} needs ${need} rows, you have ${rows}. Make the window taller.` };
+}
+/** Does /dragon-fly fit? Same shape as clipRoom; the smallest sky is 12 rows. */
+export function flyRoom(rows, chromeH = 10) {
+  if (!rows) return { ok: true };
+  if (flySky(rows, chromeH).fits) return { ok: true };
+  const need = 12 + 1 + chromeH + 2;
+  return { ok: false, note: `fly needs ${need} rows, you have ${rows}. Make the window taller.` };
+}