quoxcli 0.2.0 → 0.4.0

package/lib/commands/brain.js

@@ -51,6 +51,18 @@ export function titleOverlap(a, b) {
   for (const w of x) if (y.has(w)) hit++;
   return hit / Math.min(x.size, y.size);
 }
+const NEGATIVE_WORDS = new Set(['disable', 'disabled', 'disabling', 'off', 'deny', 'denied', 'block', 'blocked', 'stop', 'stopped', 'remove', 'removed', 'drop', 'dropped', 'abandon', 'abandoned', 'reject', 'rejected', 'exclude', 'excluded', 'not', 'never', 'no', 'dont', 'cannot', 'cant', 'wont', 'without', 'revoke', 'revoked']);
+/** Odd count of negating words = negative polarity ("not", "stop", "disable", "reject", ...). */
+function negativeParity(t) {
+  const toks = String(t || '').toLowerCase().replace(/['\u2019]/g, '').split(/[^a-z0-9]+/).filter(Boolean);
+  let n = 0;
+  for (const w of toks) if (NEGATIVE_WORDS.has(w)) n++;
+  return n % 2;
+}
+/** True when two decision titles read as opposites (enable/disable, on/off, stop X, no longer X...). */
+export function oppositePolarity(a, b) {
+  return negativeParity(a) !== negativeParity(b);
+}
 export const DECIDE_DUPE_THRESHOLD = 0.6;
 export const DISTILL_CAP = 50;
 
@@ -136,6 +148,24 @@ export function scoreRetrievalEval(judgements, searches, k = 8) {
 export function registerBrainCommands(program, ctx) {
   const { client, auth } = ctx;
 
+  // quox#934: read/history/related go through the NotesQ API, which only knows
+  // editable NotesQ notes. A feed note (git_commit, email, ...) that `brain note`
+  // resolves came back as a bare 404. On a NotesQ 404, ask the brain itself;
+  // rethrow the original error when the brain does not know the note either.
+  const brainNoteOn404 = async (noteId, err) => {
+    if (!(err instanceof QuoxApiError) || err.status !== 404) throw err;
+    let note;
+    try {
+      const ep = resolveEndpoint('brain.note.get', { id: noteId });
+      note = await client.get(ep.path, { service: ep.service });
+    } catch {
+      throw err;
+    }
+    if (!note || !note.id) throw err;
+    return note;
+  };
+  const feedReason = (n, what) => `${n.id} is a ${n.kind || 'feed'} note${n.source_type ? ` from the ${n.source_type} source` : ''}, not an editable NotesQ note, so it has no ${what}.`;
+
   const brain = program
     .command('brain')
     .description('Query Quox Qortex (vaults, notes, semantic search)')
@@ -164,10 +194,16 @@ export function registerBrainCommands(program, ctx) {
         console.log(JSON.stringify(data, null, 2));
         return;
       }
+      // quox#853: a keyword-only fallback fooled both the product and a
+      // verifier ("0 hits" read as "does not exist"). Say it in words.
+      const degradedNote = data.retrieval === 'fts' && data.degraded
+        ? '⚠ Semantic search was unavailable for this query, so this is keyword-only: a missing or zero result does not prove the note is absent. Retry shortly.'
+        : '';
       if (insufficient) {
         const legLabel = data.retrieval ? ` · ${data.retrieval}` : '';
         console.log(glyphLine('brain2', `search "${query.slice(0, 40)}"`, { result: `0 relevant hits${legLabel}`, ms: data.tookMs ?? '?' }));
         console.log('⚠ Qortex judged the matches for this query insufficient (no relevant notes). The weak hits are withheld; use -o json to see them with the relevance details.');
+        if (degradedNote) console.log(degradedNote);
         return;
       }
       // BRAIN2-AUDIT: sessions must SEE what Qortex recalled, not just a hit
@@ -176,12 +212,14 @@ export function registerBrainCommands(program, ctx) {
         const results = data.results || [];
         const legLabel = data.retrieval ? ` · ${data.retrieval}` : '';
         console.log(glyphLine('brain2', `search "${query.slice(0, 40)}"`, { result: `${results.length} hits${legLabel}`, ms: data.tookMs ?? '?' }));
+        if (degradedNote) console.log(degradedNote);
         if (results.length === 0) {
           console.log(glyphLine('brain2', 'recall', { result: 'nothing on record for this query' }));
           return;
         }
         for (const r of results) {
-          console.log(`${brandName('🌌 QORTEX')} recall │ "${recallSnippet(r)}" · ${recallSource(r)} · ${r.title || 'untitled'} · note ${r.noteId || '?'}`);
+          const miss = Array.isArray(r.missingEntities) && r.missingEntities.length ? ` · does not mention ${r.missingEntities.join(', ')}` : '';
+          console.log(`${brandName('🌌 QORTEX')} recall │ "${recallSnippet(r)}" · ${recallSource(r)} · ${r.title || 'untitled'} · note ${r.noteId || '?'}${miss}`);
         }
         return;
       }
@@ -191,6 +229,7 @@ export function registerBrainCommands(program, ctx) {
       if (program.opts().output !== 'json') {
         const legLabel = data.retrieval ? ` · ${data.retrieval}` : '';
         console.log(glyphLine('brain2', `search "${query.slice(0, 40)}"`, { result: `${(data.results || []).length} hits${legLabel}`, ms: data.tookMs ?? '?' }));
+        if (degradedNote) console.log(degradedNote);
       }
       formatOutput({
         columns: ['title', 'kind', 'snippet', 'score'],
@@ -300,7 +339,7 @@ export function registerBrainCommands(program, ctx) {
       if (!['private', 'org'].includes(options.scope)) throw new QuoxError('--scope must be private or org.', 2);
       const prov = decisionProvenance();
       const title = `Decision: ${what}`.slice(0, 200);
-      const markdown = decisionMarkdown({ what, why: options.why, rejected: options.rejected, prov });
+      let markdown = decisionMarkdown({ what, why: options.why, rejected: options.rejected, prov });
       const tags = ['decision', ...String(options.tags || '').split(',').map((t) => t.trim()).filter(Boolean)];
       const json = program.opts().output === 'json';
       if (options.dryRun) {
@@ -311,7 +350,15 @@ export function registerBrainCommands(program, ctx) {
       const sp = resolveEndpoint('brain.search.list');
       const found = await client.post(sp.path, { service: sp.service, body: { query: what, limit: 5 } });
       const insufficient = found.insufficient === true || found.relevance?.insufficient === true;
-      const dupe = insufficient ? null : (found.results || []).find((r) => titleOverlap(what, String(r.title || '').replace(/^Decision:\s*/i, '')) >= DECIDE_DUPE_THRESHOLD);
+      const bare = (r) => String(r.title || '').replace(/^Decision:\s*/i, '');
+      const matches = insufficient ? [] : (found.results || []).filter((r) => titleOverlap(what, bare(r)) >= DECIDE_DUPE_THRESHOLD);
+      // An opposite-polarity match is a reversal of the earlier decision, never a duplicate of it.
+      const dupe = matches.find((r) => !oppositePolarity(what, bare(r)));
+      const reversed = dupe ? null : matches[0];
+      if (reversed) {
+        const ref = reversed.noteId || reversed.title;
+        if (ref) markdown = decisionMarkdown({ what, why: options.why, rejected: options.rejected, prov: { ...prov, supersedes: ref } });
+      }
       if (dupe && !options.force) {
         if (json) console.log(JSON.stringify({ saved: false, reason: 'existing_match', match: { noteId: dupe.noteId, title: dupe.title, kind: dupe.kind } }, null, 2));
         else {
@@ -324,9 +371,10 @@ export function registerBrainCommands(program, ctx) {
       }
       const ep = resolveEndpoint('brain.capture.create');
       const data = await client.post(ep.path, { service: ep.service, body: { title, text: markdown.replace(/^# .*\n\n/, ''), tags, scope: options.scope === 'org' ? 'org' : 'user' } });
-      if (json) { console.log(JSON.stringify(data, null, 2)); return; }
+      if (json) { console.log(JSON.stringify(reversed ? { ...data, reverses: { noteId: reversed.noteId, title: reversed.title } } : data, null, 2)); return; }
       const verb = data.status === 'created' ? 'saved' : data.status === 'unchanged' ? 'already saved' : 'updated';
       console.log(glyphLine('brain2', 'decide', { result: `${verb} · note ${String(data.noteId || '?').slice(0, 8)}` }));
+      if (reversed) console.log(`  reverses ${reversed.title || 'untitled'}  (note ${reversed.noteId || '?'})`);
     });
 
   brain
@@ -443,14 +491,14 @@ export function registerBrainCommands(program, ctx) {
         formatDetail(data, { format });
         return;
       }
-      const verdict = (r) => (r.contradicted ? 'contradicted' : r.supported === true ? 'supported' : r.supported === false ? 'unsupported' : 'not measured');
+      const verdict = (r) => (r.fabricated || r.support_method === 'fabricated' ? 'fabricated' : r.support_method === 'unchecked' ? 'unchecked' : r.contradicted ? 'contradicted' : r.supported === true ? 'supported' : r.support_method === 'overlap' ? 'overlap' : r.supported === false ? 'unsupported' : 'not measured');
       formatOutput({
         columns: ['session', 'handle', 'note', 'span', 'rev', 'verdict', 'at'],
         headers: ['Session', 'Handle', 'Note', 'Span', 'Rev', 'Verdict', 'At'],
         rows: (data.records || []).map((r) => ({
           session: r.session || '-',
           handle: r.handle || '-',
-          note: r.note_id,
+          note: r.note_id || '-',
           span: r.char_start != null && r.char_end != null ? `${r.char_start}-${r.char_end}` : '-',
           rev: r.note_hash ? String(r.note_hash).slice(0, 8) : '-',
           verdict: verdict(r),
@@ -509,7 +557,8 @@ export function registerBrainCommands(program, ctx) {
               { metric: 'answers after brain search', week: cw.answers ?? 0, total: ct.answers ?? 0 },
               { metric: 'answers citing a note', week: `${cw.grounded ?? 0} (${pct(cw.grounded ?? 0, cw.answers ?? 0)})`, total: `${ct.grounded ?? 0} (${pct(ct.grounded ?? 0, ct.answers ?? 0)})` },
               ...((cw.supportMeasured ?? 0) + (ct.supportMeasured ?? 0) > 0
-                ? [{ metric: 'answers with supported citations (lexical)', week: `${cw.supportedAnswers ?? 0} (${pct(cw.supportedAnswers ?? 0, cw.supportMeasured ?? 0)})`, total: `${ct.supportedAnswers ?? 0} (${pct(ct.supportedAnswers ?? 0, ct.supportMeasured ?? 0)})` }]
+                ? [{ metric: 'answers with supported citations (entailment)', week: `${cw.supportedAnswers ?? 0} (${pct(cw.supportedAnswers ?? 0, cw.supportMeasured ?? 0)})`, total: `${ct.supportedAnswers ?? 0} (${pct(ct.supportedAnswers ?? 0, ct.supportMeasured ?? 0)})` },
+                   { metric: 'answers with overlap only (not checked for meaning)', week: `${cw.overlapAnswers ?? 0}`, total: `${ct.overlapAnswers ?? 0}` }]
                 : []),
               { metric: 'notes cited / retrieved', week: `${cw.citedNotes ?? 0}/${cw.retrievedNotes ?? 0}`, total: `${ct.citedNotes ?? 0}/${ct.retrievedNotes ?? 0}` },
             ],
@@ -559,7 +608,13 @@ export function registerBrainCommands(program, ctx) {
     .action(async (noteId, options) => {
       auth.requireAuth();
       const ep = resolveEndpoint('notesq.notes.get', { id: noteId });
-      const data = await client.get(ep.path, { service: ep.service });
+      let data;
+      try {
+        data = await client.get(ep.path, { service: ep.service });
+      } catch (e) {
+        const bn = await brainNoteOn404(noteId, e);
+        data = { note: bn, source: 'brain', editable: false };
+      }
       const n = data.note || data;
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       if (options.raw) { console.log(n.body ?? n.markdown ?? ''); return; }
@@ -602,11 +657,22 @@ export function registerBrainCommands(program, ctx) {
     .description('Delete a note (recorded as a revision, restorable in NotesQ). Requires --yes.')
     .argument('<noteId>', 'note id')
     .option('--yes', 'confirm deletion')
+    .option('--expected-hash <hash>', "the note's content_hash you read (see `quox brain read`); a stale value is a conflict (409) and nothing is deleted")
     .action(async (noteId, options) => {
       auth.requireAuth();
       if (!options.yes) throw new QuoxError(`Refusing to delete ${noteId} without --yes.`, 2);
+      if (!options.expectedHash) throw new QuoxError(`Refusing to delete ${noteId} without --expected-hash (the content_hash from \`quox brain read ${noteId}\`), so a concurrent edit is never deleted.`, 2);
       const ep = resolveEndpoint('notesq.notes.delete', { id: noteId });
-      const data = await client.delete(ep.path, { service: ep.service });
+      let data;
+      try {
+        data = await client.delete(ep.path, { service: ep.service, query: { expected_hash: options.expectedHash } });
+      } catch (e) {
+        if (e instanceof QuoxApiError && e.status === 409) {
+          const h = e.body && (e.body.currentHash || e.body.current_hash);
+          throw new QuoxError(`Conflict (409): note ${noteId} changed since hash ${options.expectedHash} (current_hash ${h || 'unknown'}). Nothing was deleted. Re-run \`quox brain read ${noteId}\` and retry.`, 1);
+        }
+        throw e;
+      }
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       printSuccess(`Deleted note ${noteId}.`);
     });
@@ -621,7 +687,14 @@ export function registerBrainCommands(program, ctx) {
     .action(async (noteId, options) => {
       auth.requireAuth();
       const ep = resolveEndpoint('notesq.notes.related', { id: noteId });
-      const data = await client.get(ep.path, { service: ep.service, query: { limit: Math.min(Math.max(parseInt(options.limit, 10) || 8, 1), 20) } });
+      let data;
+      try {
+        data = await client.get(ep.path, { service: ep.service, query: { limit: Math.min(Math.max(parseInt(options.limit, 10) || 8, 1), 20) } });
+      } catch (e) {
+        const bn = await brainNoteOn404(noteId, e);
+        data = { related: [], editable: false, reason: `${feedReason(bn, 'similarity links')} Use \`quox brain neighbours ${noteId}\` for its graph links.` };
+        if (program.opts().output !== 'json') console.log(data.reason);
+      }
       const related = data.related || [];
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       console.log(glyphLine('brain2', `related ${noteId.slice(0, 8)}`, { result: `${related.length} notes` }));
@@ -657,11 +730,13 @@ export function registerBrainCommands(program, ctx) {
     .description('Token-budgeted pack of the most relevant cited passages on a topic (what the Cortex brain_context tool returns)')
     .argument('<query>', 'topic or task')
     .option('--budget <n>', 'approximate token budget (200-4000)', '1200')
+    .option('--since <date>', 'only notes dated on or after this ISO date/datetime (e.g. 2026-10-05)')
+    .option('--until <date>', 'only notes dated on or before this ISO date/datetime (a date alone means the whole day)')
     .action(async (query, options) => {
       auth.requireAuth();
       const tokenBudget = Math.min(Math.max(parseInt(options.budget, 10) || 1200, 200), 4000);
       const ep = resolveEndpoint('brain.context.pack');
-      const data = await client.post(ep.path, { service: ep.service, body: { query, tokenBudget } });
+      const data = await client.post(ep.path, { service: ep.service, body: { query, tokenBudget, ...(options.since ? { since: options.since } : {}), ...(options.until ? { until: options.until } : {}) } });
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       const passages = data.passages || [];
       const insufficient = data.insufficient === true || data.relevance?.insufficient === true || passages.length === 0;
@@ -693,7 +768,7 @@ export function registerBrainCommands(program, ctx) {
       if (!data || data.success === false) {
         throw new QuoxError(`brain_check failed: ${(data && (data.error || data.output)) || 'unknown error'}`, 1);
       }
-      const mark = { supported: '✔', contradicted: '✖', unknown: '◐' }[data.verdict] || '';
+      const mark = { supported: '✔', contradicted: '✖', overlap: '◐', unknown: '◐' }[data.verdict] || '';
       console.log(glyphLine('brain2', `check "${claim.slice(0, 40)}"`, { result: `${data.verdict} ${mark}`.trim() }));
       const ev = data.evidence || [];
       for (const e of ev) {
@@ -749,7 +824,14 @@ export function registerBrainCommands(program, ctx) {
         return;
       }
       const ep = resolveEndpoint('notesq.notes.revisions', { id: noteId });
-      const data = await client.get(ep.path, { service: ep.service });
+      let data;
+      try {
+        data = await client.get(ep.path, { service: ep.service });
+      } catch (e) {
+        const bn = await brainNoteOn404(noteId, e);
+        data = { revisions: [], editable: false, reason: feedReason(bn, 'revision history') };
+        if (program.opts().output !== 'json') { console.log(data.reason); return; }
+      }
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       formatOutput({ columns: ['rev', 'action', 'author_kind', 'created_at', 'content_hash'], headers: ['Rev', 'Action', 'Author', 'When', 'Hash'], rows: data.revisions || [] }, { format: program.opts().output });
     });
@@ -770,7 +852,16 @@ export function registerBrainCommands(program, ctx) {
         throw new QuoxError(`Conflict: note ${noteId} changed since hash ${options.expectedHash} (current_hash ${current || 'unknown'}). Nothing was restored. Re-run \`quox brain read ${noteId}\` and try again.`, 1);
       }
       const ep = resolveEndpoint('notesq.notes.restore', { id: noteId });
-      const data = await client.post(ep.path, { service: ep.service, body: { rev } });
+      let data;
+      try {
+        data = await client.post(ep.path, { service: ep.service, body: { rev, expected_hash: options.expectedHash } });
+      } catch (e) {
+        if (e instanceof QuoxApiError && e.status === 409) {
+          const h = e.body && (e.body.currentHash || e.body.current_hash);
+          throw new QuoxError(`Conflict (409): note ${noteId} changed since hash ${options.expectedHash} (current_hash ${h || 'unknown'}). Nothing was restored. Re-run \`quox brain read ${noteId}\` and try again.`, 1);
+        }
+        throw e;
+      }
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       printSuccess(data.unchanged ? `Note ${noteId} already matches revision ${rev}.` : `Restored note ${noteId} to revision ${rev} (new rev ${data.revision?.rev ?? '?'}).`);
     });

package/lib/commands/build.js

@@ -33,10 +33,26 @@ export function registerBuildCommands(program, ctx) {
   // own parsed opts.
   const groupOpt = (options, key) => options[key] ?? build.opts()[key];
 
+  // An org with exactly one dev server needs no --host: use it and say so. With several, name them;
+  // with none, say so (proof cases code/reach-build-status / -targets exited 1 on a one-server org).
+  async function resolveHost(options) {
+    const given = groupOpt(options, 'host');
+    if (given) return given;
+    const listEp = resolveEndpoint('v1.dev.servers.list');
+    const list = await client.get(listEp.path, { service: listEp.service });
+    const ids = (Array.isArray(list?.servers) ? list.servers : []).map((s) => s.host_id).filter(Boolean);
+    if (ids.length === 1) {
+      printWarning(`No --host given; using the only dev server: ${ids[0]}`);
+      return ids[0];
+    }
+    if (ids.length === 0) throw new Error('No dev server is registered for this org (register one with `quox dev enable <hostId>`).');
+    throw new Error(`--host <hostId> is required: this org has ${ids.length} dev servers (${ids.join(', ')}).`);
+  }
+
   async function dispatch(target, options) {
     auth.requireAuth();
     options = {
-      host: groupOpt(options, 'host'),
+      host: await resolveHost(options),
       stream: groupOpt(options, 'stream'),
       phase: groupOpt(options, 'phase'),
       msg: groupOpt(options, 'msg'),
@@ -76,8 +92,7 @@ export function registerBuildCommands(program, ctx) {
     .option('--host <hostId>', 'dev server host_id')
     .action(async (options) => {
       auth.requireAuth();
-      const host = groupOpt(options, 'host');
-      if (!host) throw new Error('--host <hostId> is required');
+      const host = await resolveHost(options);
       const endpoint = resolveEndpoint('v1.dev.build.status', { hostId: host });
       const data = await client.get(endpoint.path, { service: endpoint.service });
       formatDetail(data, { format: program.opts().output, title: `Build status: ${host}` });
@@ -89,8 +104,7 @@ export function registerBuildCommands(program, ctx) {
     .option('--host <hostId>', 'dev server host_id')
     .action(async (options) => {
       auth.requireAuth();
-      const host = groupOpt(options, 'host');
-      if (!host) throw new Error('--host <hostId> is required');
+      const host = await resolveHost(options);
       const endpoint = resolveEndpoint('v1.dev.build.targets', { hostId: host });
       const data = await client.get(endpoint.path, { service: endpoint.service });
       formatOutput(data.targets || [], {

package/lib/commands/chat.js

@@ -5,6 +5,10 @@
 import chalk from 'chalk';
 import { formatDetail } from '../core/output.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { existsSync } from 'node:fs';
+import { lastConversation, saveLastConversation } from './chatState.js';
+import { loadChatCompanion } from './chatCompanion.js';
+import { companionPlan, motionPolicy, VENDORED_DRAGONLAB } from '../dragon/select.js';
 
 /**
  * Build the POST body for /chat/stream (quox#782). The prompt and context
@@ -26,6 +30,46 @@ export function buildStreamQuery({ queryId, message, agent, sessionId, context }
   return body;
 }
 
+/**
+ * TUI-DIVIDER: `quox chat --trace` prints the turn's protocol events as they arrive, so the
+ * per-layer AOCL record (`aocl.layer`: id, name, result, ms) is visible in the CLI before any
+ * UI animates it. Returns { text, tone } or null for an event --trace does not show.
+ * tone: ok | warn | fail | accent (no grey: every tone is a real colour).
+ */
+const RESULT_TONE = { pass: 'ok', gated: 'warn', blocked: 'fail', bypass: 'accent' };
+const fmtTraceMs = (ms) => {
+  const n = Number(ms);
+  if (!Number.isFinite(n)) return '';
+  return n < 10 ? `${Math.round(n * 10) / 10} ms` : `${Math.round(n)} ms`;
+};
+export function formatTraceEvent(ev) {
+  if (!ev || typeof ev !== 'object') return null;
+  switch (ev.type) {
+    case 'turn.started':
+      return { text: `▸ turn.started  ${[ev.provider, ev.model].filter(Boolean).join(' ')}`, tone: 'accent' };
+    case 'aocl.layer': {
+      const result = String(ev.result || 'pass');
+      const line = `▤ aocl.layer  ${String(ev.id || '?').padEnd(4)}${String(ev.name || '').padEnd(10)}${result.padEnd(8)}${fmtTraceMs(ev.ms).padStart(8)}  ${ev.phase || ''}${ev.reason ? `  ${ev.reason}` : ''}`;
+      return { text: line, tone: RESULT_TONE[result] || 'accent' };
+    }
+    case 'aocl.summary':
+      return { text: `▤ aocl.summary ${ev.accounted ?? '?'}/${ev.total ?? '?'} accounted · ${ev.passed ?? 0} passed · ${ev.bypassed ?? 0} bypassed · ${ev.rejected ?? 0} rejected${ev.ms != null ? ` · ${fmtTraceMs(ev.ms)}` : ''}`, tone: ev.rejected ? 'fail' : 'ok' };
+    case 'aocl.verdict':
+      return { text: `▤ aocl.verdict ${ev.layer || 'L8'} ${ev.verdict}${ev.reason ? `: ${ev.reason}` : ''}`, tone: ev.verdict === 'blocked' ? 'fail' : 'warn' };
+    case 'trace':
+      return { text: `· trace ${ev.protocol || ''} ${ev.label || ''}${ev.detail ? `  ${ev.detail}` : ''}`, tone: 'accent' };
+    case 'turn.finished':
+      return { text: `▸ turn.finished ${ev.status || ''}${ev.usage?.elapsed_ms != null ? ` · ${ev.usage.elapsed_ms} ms` : ''}`, tone: ev.status === 'completed' ? 'ok' : 'fail' };
+    default:
+      return null;
+  }
+}
+const TONE_PAINT = { ok: chalk.green, warn: chalk.yellow, fail: chalk.red, accent: chalk.cyan };
+function printTrace(ev) {
+  const f = formatTraceEvent(ev);
+  if (f) process.stderr.write((TONE_PAINT[f.tone] || chalk.cyan)(f.text) + '\n');
+}
+
 function generateQueryId() {
   return `CLI_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -34,7 +78,7 @@ function generateQueryId() {
  * Consume a chat SSE stream, printing chunks as they arrive.
  * Returns { text, sessionId, agentUsed } once the stream completes.
  */
-export async function consumeStream(client, { message, agent, sessionId, context }, { onAgentLabel } = {}) {
+export async function consumeStream(client, { message, agent, sessionId, context }, { onAgentLabel, trace = false, companionPath, companionDisplay } = {}) {
   const queryId = generateQueryId();
   const body = buildStreamQuery({ queryId, message, agent, sessionId, context });
 
@@ -50,7 +94,25 @@ export async function consumeStream(client, { message, agent, sessionId, context
     onAgentLabel?.(agentUsed);
   };
 
-  for await (const event of client.stream(resolveEndpoint('chat.stream').path, { service: resolveEndpoint('chat.stream').service, body })) {
+  const companion = await loadChatCompanion(companionPath, { display: companionDisplay });
+  const write = text => companion ? companion.write(text) : process.stdout.write(text);
+  // Native terminal status follows legacy `done`; observe it when opted in.
+  let iter;
+  try {
+  iter = client.stream(resolveEndpoint('chat.stream').path, { service: resolveEndpoint('chat.stream').service, body, untilClose: Boolean(trace || companion) })[Symbol.asyncIterator]();
+  while (true) {
+    let step;
+    try {
+      step = await iter.next();
+    } catch (err) {
+      // A refusal before the stream opened carries the layers it really evaluated.
+      if (trace && Array.isArray(err?.body?.aocl_layers)) { companion?.suspend(); for (const l of err.body.aocl_layers) printTrace({ type: 'aocl.layer', ...l }); }
+      throw err;
+    }
+    if (step.done) break;
+    const event = step.value;
+    companion?.event(event);
+    if (trace) { companion?.suspend(); printTrace(event); }
     switch (event.type) {
       case 'connected':
         break;
@@ -58,9 +120,9 @@ export async function consumeStream(client, { message, agent, sessionId, context
       case 'thinking': {
         const stage = event.stage || '';
         if (stage === 'tool_call' || stage.includes('tool')) {
-          console.log(chalk.dim(`  ⚙ using tool: ${event.message}`));
+          write(chalk.dim(`  ⚙ using tool: ${event.message}`) + '\n');
         } else if (process.argv.includes('--verbose') || process.argv.includes('-v')) {
-          console.log(chalk.dim(`  … ${event.message}`));
+          write(chalk.dim(`  … ${event.message}`) + '\n');
         }
         break;
       }
@@ -68,19 +130,19 @@ export async function consumeStream(client, { message, agent, sessionId, context
       case 'chunk':
         printLabel();
         sawChunk = true;
-        process.stdout.write(event.content || '');
+        write(event.content || '');
         text += event.content || '';
         break;
 
       case 'done':
         if (!sawChunk && event.full_response) {
           printLabel();
-          process.stdout.write(event.full_response);
+          write(event.full_response);
           text = event.full_response;
         }
         if (event.session_id) resultSessionId = event.session_id;
         if (event.agent_used) agentUsed = event.agent_used;
-        console.log();
+        write('\n');
         break;
 
       case 'error':
@@ -90,28 +152,99 @@ export async function consumeStream(client, { message, agent, sessionId, context
         break;
     }
   }
+  } catch (err) {
+    companion?.event({ type: 'error' });
+    throw err;
+  } finally {
+    await companion?.close();
+    try { await iter?.return?.(); } catch { /* cleanup must not mask a stream error */ }
+  }
 
   return { text, sessionId: resultSessionId, agentUsed };
 }
 
-/** One-shot (non-streaming) chat via POST /chat/claude. */
-async function sendOneShot(client, { message, agent, sessionId }) {
-  const body = { prompt: message };
-  if (agent) body.selected_agent = agent;
-  if (sessionId) body.session_id = sessionId;
+/** The words for a failed turn: the server's plain message first, the bare error code only as a fallback. */
+export function turnFailureText(result, httpStatus) {
+  return result?.message || result?.error || `chat turn failed (HTTP ${httpStatus})`;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Poll a server-side chat turn until it is done. The turn keeps running on the server whatever this
+ * client does, so giving up early would hide a result (and any objects it created) from the user.
+ */
+async function awaitTurn(client, turnId) {
+  const capMs = Number(process.env.QUOX_CHAT_TURN_TIMEOUT_MS) || 20 * 60 * 1000;
+  const fixed = Number(process.env.QUOX_CHAT_POLL_MS) || 0;
+  const started = Date.now();
+  let wait = fixed || 1500;
+  let failures = 0;
+  const ep = resolveEndpoint('chat.turn.get', { id: turnId });
+  while (true) {
+    let t;
+    try {
+      t = await client.get(ep.path, { service: ep.service });
+      failures = 0;
+    } catch (err) {
+      if (err?.status === 404 || /not.found/i.test(err?.message || '')) {
+        throw new Error(`The server no longer has chat turn ${turnId} (expired, or the collector restarted). Check \`quox conversation list\` to see whether it finished.`);
+      }
+      if (++failures >= 5) throw err;
+      t = { status: 'running' };
+    }
+    if (t.status === 'done') {
+      if (t.http_status >= 400) throw new Error(turnFailureText(t.result, t.http_status));
+      return t.result || {};
+    }
+    if (t.status === 'error') throw new Error(`chat turn ${turnId} failed on the server: ${t.error || 'unknown error'}`);
+    if (Date.now() - started > capMs) {
+      throw new Error(`Chat turn ${turnId} is still running after ${Math.round(capMs / 1000)}s. It has not been lost: fetch it with \`quox chat --resume ${turnId}\`.`);
+    }
+    await sleep(wait);
+    if (!fixed) wait = Math.min(wait + 500, 5000);
+  }
+}
+
+/** One-shot (non-streaming) chat via POST /chat/claude, kept server side as a pollable turn. */
+async function sendOneShot(client, { message, agent, sessionId, resumeTurn }) {
+  let data;
+  if (resumeTurn) {
+    data = await awaitTurn(client, resumeTurn);
+  } else {
+    const body = { prompt: message };
+    if (agent) body.selected_agent = agent;
+    if (sessionId) body.session_id = sessionId;
 
-  const data = await client.post(resolveEndpoint('chat.claude').path, {
-    service: resolveEndpoint('chat.claude').service,
-    body,
-    timeout: 120000,
-  });
+    // Prefer: respond-async returns 202 {turn_id} at once, so no client timeout can orphan a
+    // multi-tool turn. An older collector ignores it and answers synchronously (handled below).
+    data = await client.post(resolveEndpoint('chat.claude').path, {
+      service: resolveEndpoint('chat.claude').service,
+      body,
+      headers: { Prefer: 'respond-async' },
+      timeout: 30000,
+    });
+    if (data && data.turn_id && data.status === 'running') data = await awaitTurn(client, data.turn_id);
+  }
 
   const response = data.result || data.response || data.text || JSON.stringify(data);
   return { data, response, sessionId: data.session_id || sessionId };
 }
 
+/** Explicit --dragon-module wins; otherwise pick the dragon for the attached agent (null path = ordinary chat). */
+export function chooseCompanion({ options, config, env = process.env, isTTY = Boolean(process.stdout.isTTY), exists = existsSync }) {
+  const policy = motionPolicy(env);
+  if (options.dragonModule) return { companionPath: options.dragonModule, companionDisplay: { still: policy.still, mono: policy.mono } };
+  let settings = {};
+  try { settings = config?.getActiveProfile?.()?.quoxon || {}; } catch { /* no profile settings */ }
+  const e = options.dragon ? { ...env, QUOX_DRAGON_COMPANION: options.dragon } : env;
+  const plan = companionPlan({ agent: options.agent, settings, env: e, isTTY, exists, bundled: VENDORED_DRAGONLAB });
+  if (!plan.enabled) return { companionPath: undefined, companionDisplay: undefined };
+  return { companionPath: plan.file, companionDisplay: { still: plan.still, mono: plan.mono, persist: plan.persist } };
+}
+
 export function registerChatCommands(program, ctx) {
-  const { client, auth } = ctx;
+  const { client, auth, config } = ctx;
 
   const chat = program
     .command('chat')
@@ -120,12 +253,25 @@ export function registerChatCommands(program, ctx) {
     .option('--agent <name>', 'route to a specific agent (e.g. sentinel, cipher, nova)')
     .option('--no-stream', 'disable streaming output (one-shot request/response)')
     .option('--conversation <id>', 'continue a conversation (session id)')
+    .option('--continue', 'continue the last conversation for this profile and directory')
+    .option('--resume <turn>', 'fetch a chat turn that was still running (its id is printed if a turn outlives the wait)')
+    .option('--trace', 'print the turn\'s protocol events (per-layer AOCL, traces, summary) to stderr as they arrive')
+    .option('--dragon <mode>', 'dragon companion for dragon-backed agents: on, greeting or off (default from /dragon companion; art is bundled; QUOX_DRAGONLAB overrides it)')
+    .option('--dragon-module <path>', 'opt in to a trusted local dragon companion module (streaming, single-message mode)')
     .action(async (message, options) => {
       auth.requireAuth();
       const streaming = options.stream !== false;
+      const profileName = (() => { try { return config?.getActiveProfileName?.(); } catch { return undefined; } })();
+      const noteConversation = (id) => {
+        if (!id) return;
+        saveLastConversation(profileName, process.cwd(), id);
+        if (program.opts().output !== 'json') process.stderr.write(`conversation: ${id}\n`);
+      };
+      if (!options.conversation && options.continue) options.conversation = lastConversation(profileName, process.cwd());
+      if (options.dragonModule && (!message || !streaming)) throw new Error('--dragon-module requires a single message with streaming enabled.');
 
-      // Interactive mode if no message
-      if (!message) {
+      // Interactive mode if no message (a --resume fetch is not interactive)
+      if (!message && !options.resume) {
         const { default: inquirer } = await import('inquirer');
         let currentAgent = options.agent || 'quox';
         let sessionId = options.conversation;
@@ -161,8 +307,9 @@ export function registerChatCommands(program, ctx) {
                 sessionId,
               }, {
                 onAgentLabel: (agentUsed) => process.stdout.write(chalk.green(`${(agentUsed || currentAgent).toUpperCase()}: `)),
+                trace: Boolean(options.trace),
               });
-              if (result.sessionId) sessionId = result.sessionId;
+              if (result.sessionId) { sessionId = result.sessionId; saveLastConversation(profileName, process.cwd(), sessionId); }
               console.log();
             } else {
               const { response, sessionId: newSessionId } = await sendOneShot(client, {
@@ -170,7 +317,7 @@ export function registerChatCommands(program, ctx) {
                 agent: currentAgent,
                 sessionId,
               });
-              if (newSessionId) sessionId = newSessionId;
+              if (newSessionId) { sessionId = newSessionId; saveLastConversation(profileName, process.cwd(), sessionId); }
               console.log(chalk.green(`${currentAgent.toUpperCase()}:`), response);
               console.log();
             }
@@ -182,15 +329,19 @@ export function registerChatCommands(program, ctx) {
       }
 
       // Single message mode
-      if (streaming) {
+      if (streaming && !options.resume) {
+        const companion = chooseCompanion({ options, config });
         try {
-          await consumeStream(client, {
+          const result = await consumeStream(client, {
             message,
             agent: options.agent,
             sessionId: options.conversation,
           }, {
             onAgentLabel: () => {}, // no label prefix in single-shot streaming; just print tokens
+            trace: Boolean(options.trace),
+            ...companion,
           });
+          noteConversation(result?.sessionId);
         } catch (err) {
           console.error(chalk.red(`Error: ${err.message}`));
           process.exitCode = 1;
@@ -202,15 +353,17 @@ export function registerChatCommands(program, ctx) {
       const spinner = ora('Thinking...').start();
 
       try {
-        const { data, response } = await sendOneShot(client, {
+        const { data, response, sessionId: convId } = await sendOneShot(client, {
           message,
           agent: options.agent,
           sessionId: options.conversation,
+          resumeTurn: options.resume,
         });
         spinner.stop();
+        noteConversation(convId);
 
         if (program.opts().output === 'json') {
-          console.log(JSON.stringify(data, null, 2));
+          console.log(JSON.stringify({ ...data, conversation_id: convId || null }, null, 2));
         } else {
           console.log(response);
 
@@ -238,3 +391,4 @@ export function registerChatCommands(program, ctx) {
       });
     });
 }
+