quoxcli 0.2.0 → 0.4.0

package/lib/commands/loop.js

@@ -0,0 +1,291 @@
+/**
+ * Loop commands (QLOOP-LIVE): observe a QLoop loop as it runs.
+ *
+ *   quox loop watch <id> [--spool|--quiet] [--since n]   live, one QuoxGlyph line per event
+ *   quox loop status <id>                                snapshot
+ *   quox loop list                                       running + recent loops (org)
+ *
+ * `watch` reconnects with ?since=<last event_seq> when the stream drops, and exits with the loop's
+ * outcome: 0 completed, 1 failed, 2 halted, 3 interrupted, 4 connection lost for good.
+ * Events come from GET /api/v1/loops/:id/events (design: ~/quoxon-work/qloop-live-design.md).
+ */
+
+import { formatOutput, getOutputFormat } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { loopLine, renderEvent, exitCodeFor, elapsedLabel } from '../core/loopGlyph.js';
+import { QuoxApiError, QuoxAuthError, QuoxUserError } from '../core/errors.js';
+
+const MAX_SILENT_RETRIES = 10;
+const BACKOFF_BASE_MS = 1000;
+const BACKOFF_CAP_MS = 10000;
+
+const sleepReal = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** SQLite "YYYY-MM-DD HH:MM:SS" (UTC, no zone) or ISO to epoch ms; null if unreadable. */
+function toMs(ts) {
+  if (!ts) return null;
+  const iso = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(ts) ? `${ts.replace(' ', 'T')}Z` : ts;
+  const n = Date.parse(iso);
+  return Number.isNaN(n) ? null : n;
+}
+
+const SETTLE_MAX_MS = 90000;
+const SETTLE_POLL_MS = 4000;
+
+/**
+ * After loop.finished: wait (bounded) for the loop's receipts to be WITNESSED by WARD, asking the snapshot
+ * (which re-checks WARD and records what it finds), printing each receipt as it flips. Returns the finished
+ * event with the final witnessed count. A snapshot that cannot be read ends the wait and says so; it never
+ * reads as "0 witnessed".
+ */
+async function settleReceipts({ client, id, finished, write, sleep, ctx, maxMs, signal, seen = new Set() }) {
+  const ep = resolveEndpoint('loops.get', { id: encodeURIComponent(id) });
+  let witnessed = finished.witnessed;
+  write(loopLine('receipts', `${witnessed}/${finished.receipts} witnessed, waiting for WARD to sign the covering tip`, 'busy'));
+  let waited = 0;
+  while (witnessed < finished.receipts && waited < maxMs && !(signal && signal.aborted)) {
+    await sleep(SETTLE_POLL_MS);
+    waited += SETTLE_POLL_MS;
+    let snap;
+    try { snap = await client.get(ep.path, { service: ep.service }); } catch (err) {
+      write(loopLine('receipts', `could not re-check WARD (${oneLineErr(err)}); \`quox loop status ${id}\` will`, 'warn'));
+      break;
+    }
+    const items = (snap && snap.receipts && snap.receipts.items) || [];
+    for (const r of items) {
+      if (r.status === 'WITNESSED' && !seen.has(r.envelope_id)) {
+        seen.add(r.envelope_id);
+        write(loopLine('receipt', `${String(r.envelope_id)} WITNESSED`, 'ok'));
+      }
+    }
+    witnessed = snap && snap.receipts ? snap.receipts.witnessed : witnessed;
+  }
+  if (witnessed < finished.receipts) write(loopLine('receipts', `${finished.receipts - witnessed} still pending after ${Math.round(waited / 1000)}s; they are witnessed when the next tip signs (quox loop status ${id})`, 'warn'));
+  return { ...finished, witnessed };
+}
+
+/**
+ * Follow one loop to its end. Returns the process exit code. Exported for tests.
+ * @param {object} p
+ * @param {object} p.client   cli client (stream)
+ * @param {string} p.id
+ * @param {object} p.snapshot  loops.get result (title, max_turns, started_at)
+ * @param {{spool?: boolean, quiet?: boolean, since?: number, json?: boolean, noSettle?: boolean, settleMs?: number}} p.opts
+ * @param {(line: string) => void} p.write
+ * @param {(ms: number) => Promise<void>} [p.sleep]
+ * @param {AbortSignal} [p.signal]
+ */
+export async function watchLoop({ client, id, snapshot, opts = {}, write, sleep = sleepReal, signal }) {
+  const ep = resolveEndpoint('loops.events', { id: encodeURIComponent(id) });
+  let lastSeq = Number(opts.since) || 0;
+  let startedMs = toMs(snapshot && snapshot.started_at);
+  const ctx = { title: snapshot && snapshot.title, maxTurns: snapshot && snapshot.max_turns, startedMs, spool: !!opts.spool };
+  const showQuiet = new Set(['loop.started', 'loop.observe', 'loop.approval', 'loop.finished']);
+  let failures = 0;
+  let backoff = BACKOFF_BASE_MS;
+  const witnessedShown = new Set(); // receipts already printed from loop.ward events, so the settle phase does not repeat them
+
+  while (!signal || !signal.aborted) {
+    let gotEvent = false;
+    let ended = null;
+    try {
+      for await (const ev of client.stream(ep.path, { service: ep.service, query: { since: lastSeq }, signal })) {
+        // `event: end` frame (an old loop that never logged a finish): no type, a reason
+        if (ev && !ev.type && ev.reason) { ended = ev; break; }
+        if (!ev || typeof ev.type !== 'string' || !ev.type.startsWith('loop.')) continue;
+        gotEvent = true;
+        if (typeof ev.event_seq === 'number') {
+          if (ev.event_seq <= lastSeq) continue; // replay overlap after a reconnect
+          lastSeq = ev.event_seq;
+        }
+        if (ev.type === 'loop.ward' && ev.status === 'WITNESSED') witnessedShown.add(ev.envelope_id);
+        if (!ctx.startedMs && ev.type === 'loop.started') ctx.startedMs = Date.parse(ev.at);
+        if (opts.json) write(JSON.stringify(ev));
+        else if (ev.type !== 'loop.finished' && !(opts.quiet && !showQuiet.has(ev.type))) for (const l of renderEvent(ev, ctx)) write(l);
+        if (ev.type === 'loop.finished') {
+          // the loop is over; its receipts are WITNESSED when WARD's next signed tip covers them (about a minute),
+          // so say so and follow them in rather than printing a final count that is about to be stale
+          const last = (!opts.json && !opts.noSettle && ev.receipts > ev.witnessed)
+            ? await settleReceipts({ client, id, finished: ev, write, sleep, ctx, maxMs: opts.settleMs ?? SETTLE_MAX_MS, signal, seen: witnessedShown })
+            : ev;
+          if (!opts.json) for (const l of renderEvent(last, ctx).slice(-1)) write(l);
+          if (!opts.json && !opts.quiet) write(`  quox loop status ${id}   # receipts and proof`);
+          return exitCodeFor(ev.state);
+        }
+      }
+    } catch (err) {
+      // a refusal is not a dropped connection: 401/403/404 and friends end the watch now with the server's words
+      if (err instanceof QuoxAuthError || (err instanceof QuoxApiError && err.status >= 400 && err.status < 500 && err.status !== 429)) throw err;
+      if (signal && signal.aborted) return 130;
+      failures += 1;
+      if (failures > MAX_SILENT_RETRIES) {
+        write(loopLine('connection lost', `could not reach the loop stream after ${MAX_SILENT_RETRIES} tries; resume with: quox loop watch ${id} --since ${lastSeq}`, 'fail'));
+        return 4;
+      }
+      if (!opts.quiet && !opts.json) write(loopLine('reconnecting', `stream dropped (${oneLineErr(err)}); resuming after event ${lastSeq}`, 'warn'));
+      await sleep(backoff);
+      backoff = Math.min(BACKOFF_CAP_MS, backoff * 2);
+      continue;
+    }
+    if (ended) {
+      write(loopLine(ctx.title || 'loop', `ended without a recorded finish (${ended.status || 'unknown'}): ${ended.reason}`, 'warn'));
+      return ended.status === 'completed' ? 0 : 1;
+    }
+    // stream closed by the server (restart, proxy idle limit) before loop.finished: resume, quietly counting
+    if (gotEvent) { failures = 0; backoff = BACKOFF_BASE_MS; } else failures += 1;
+    if (failures > MAX_SILENT_RETRIES) {
+      write(loopLine('connection lost', `the loop stream keeps closing with nothing new; resume with: quox loop watch ${id} --since ${lastSeq}`, 'fail'));
+      return 4;
+    }
+    await sleep(gotEvent ? 250 : backoff);
+    if (!gotEvent) backoff = Math.min(BACKOFF_CAP_MS, backoff * 2);
+  }
+  return 130;
+}
+
+function oneLineErr(err) {
+  return String((err && err.message) || err).replace(/\s+/g, ' ').slice(0, 80);
+}
+
+export function statusLines(s, { diagnostics = false } = {}) {
+  const lines = [];
+  const turns = `turn ${s.turn}${s.max_turns ? `/${s.max_turns}` : ''}`;
+  lines.push(loopLine(s.title || s.objective_id, `${s.state}, ${turns}`, s.state === 'running' ? 'busy' : (s.state === 'completed' ? 'ok' : (s.state === 'completed_with_errors' || s.state === 'halted' || s.state === 'interrupted' ? 'warn' : (s.finished ? 'fail' : 'busy')))));
+  lines.push(`  id        ${s.objective_id}`);
+  lines.push(`  host      ${s.host || '-'}   backend ${s.backend || '-'}   scope ${(s.scope || []).join(',') || '-'}`);
+  if (s.until) lines.push(`  until     ${s.until}${s.every_seconds ? `   (a turn every ${s.every_seconds}s)` : ''}`);
+  else if (s.every_seconds) lines.push(`  every     ${s.every_seconds}s`);
+  if (s.workspace) lines.push(`  workspace ${s.workspace}`);
+  const r = s.receipts || { total: 0, witnessed: 0 };
+  lines.push(`  receipts  ${r.witnessed}/${r.total} witnessed${s.ward_check_error ? `   (WARD could not be asked just now: ${s.ward_check_error})` : ''}`);
+  if (s.observe) lines.push(`  observe   ${JSON.stringify(s.observe)}`);
+  if (s.reason && s.finished) lines.push(`  reason    ${s.reason}`);
+  if (diagnostics && s.diagnostics) lines.push(`  diagnostics ${s.diagnostics}`);
+  if ((s.last_turns || []).length) {
+    lines.push('  last turns');
+    for (const t of s.last_turns) {
+      const tools = (t.tools || []).map((x) => `${x.tool}${x.denied ? ' denied' : (x.ok ? '' : ' FAILED')}`).join(', ');
+      lines.push(`    ${t.turn}  ${t.summary}${tools ? `  [${tools}]` : ''}  ${t.envelope_id ? `${String(t.envelope_id)} ${t.ward}` : ''}`.trimEnd());
+    }
+  }
+  if (s.started_at) {
+    const st = toMs(s.started_at);
+    const en = toMs(s.completed_at) || Date.now();
+    if (st) lines.push(`  elapsed   ${elapsedLabel(en - st)}`);
+  }
+  return lines;
+}
+
+export function registerLoopCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const loop = program
+    .command('loop')
+    .description('Observe QLoop loops as they run (watch, status, list)');
+
+  loop
+    .command('watch')
+    .description('Follow a loop live: one QuoxGlyph line per event, reconnecting on drop. Exits 0 completed, 1 failed, 2 halted, 3 interrupted, 4 connection lost')
+    .argument('<id>', 'loop (objective) ID')
+    .option('--spool', 'also stream the loop\'s output text under each turn line')
+    .option('--quiet', 'only the headline lines: started, observe points (milestones, errors, approvals, stalls), the final line')
+    .option('--since <n>', 'resume after this event_seq (printed by a previous watch; default: from the start)')
+    .option('--no-wait-receipts', 'print the final line as soon as the loop ends instead of waiting (up to 90s) for its receipts to be witnessed')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      if (options.spool && options.quiet) throw new QuoxUserError('--spool and --quiet cancel each other out; pick one.');
+      const since = options.since !== undefined ? Number(options.since) : 0;
+      if (!Number.isInteger(since) || since < 0) throw new QuoxUserError('--since needs a whole number event_seq (0 or more).');
+      const snap = resolveEndpoint('loops.get', { id: encodeURIComponent(id) });
+      const snapshot = await client.get(snap.path, { service: snap.service });
+      const ac = new AbortController();
+      const onSigint = () => ac.abort();
+      process.once('SIGINT', onSigint);
+      let code;
+      try {
+        code = await watchLoop({
+          client, id, snapshot,
+          opts: { spool: options.spool, quiet: options.quiet, since, json: getOutputFormat() === 'json', noSettle: options.waitReceipts === false },
+          write: (l) => console.log(l),
+          signal: ac.signal,
+        });
+      } finally {
+        process.removeListener('SIGINT', onSigint);
+      }
+      if (code === 130) console.log(`  stopped watching; the loop keeps running. Resume: quox loop watch ${id}`);
+      if (code) process.exitCode = code;
+    });
+
+  loop
+    .command('status')
+    .description('Snapshot of a loop: state, turn n/max, host, backend, scope, last turns, receipts')
+    .argument('<id>', 'loop (objective) ID')
+    .option('--diagnostics', 'also show the raw diagnostics behind the finish reason (hidden by default)')
+    .action(async (id, options = {}) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('loops.get', { id: encodeURIComponent(id) });
+      const data = await client.get(ep.path, { service: ep.service });
+      if (getOutputFormat() === 'json') {
+        const out = options.diagnostics || !data || typeof data !== 'object' ? data : { ...data, diagnostics: undefined };
+        console.log(JSON.stringify(out, null, 2)); return;
+      }
+      for (const l of statusLines(data, { diagnostics: !!options.diagnostics })) console.log(l);
+    });
+
+  loop
+    .command('list')
+    .description('Running and recent loops in this org')
+    .option('--limit <n>', 'max results', '20')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('loops.list');
+      const data = await client.get(ep.path, { service: ep.service, query: { limit: options.limit } });
+      formatOutput({
+        columns: ['objective_id', 'title', 'state', 'turn', 'backend', 'created_at'],
+        headers: ['ID', 'Title', 'State', 'Turn', 'Backend', 'Created'],
+        rows: (data.loops || []).map((l) => ({ ...l, turn: l.max_turns ? `${l.turn}/${l.max_turns}` : String(l.turn) })),
+      }, { format: program.opts().output, emptyMessage: 'No loops in this org yet.' });
+    });
+
+  // SECURITY containment (2026-10-26): which orgs may run loops in-server (core-local) while a security review is open.
+  // Instance-admin only (the server enforces it; a non-admin gets a 403). Stored server-side in instance_config.
+  const coreLocal = loop
+    .command('core-local')
+    .description('Instance admin: which workspaces may run loops inside the server (limited while a security review is open)');
+
+  coreLocal
+    .command('list')
+    .description('Show the workspaces allowed to run loops inside the server')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('admin.instance.core_local_orgs.list');
+      const r = await client.get(ep.path, { service: ep.service });
+      if (getOutputFormat() === 'json') { console.log(JSON.stringify(r, null, 2)); return; }
+      if (!(r.orgs || []).length) { console.log('No workspace may run loops inside the server (loops need a dev server).'); return; }
+      for (const o of r.orgs) console.log(o);
+    });
+
+  coreLocal
+    .command('add')
+    .description('Allow a workspace to run loops inside the server (instance admin)')
+    .argument('<orgId>', 'workspace (org) id')
+    .action(async (orgId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('admin.instance.core_local_orgs.add');
+      const r = await client.post(ep.path, { service: ep.service, body: { org_id: orgId } });
+      if (getOutputFormat() === 'json') { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(`Added ${orgId}. ${(r.orgs || []).length} workspace(s) may now run loops inside the server.`);
+    });
+
+  coreLocal
+    .command('remove')
+    .description('Stop a workspace running loops inside the server (instance admin)')
+    .argument('<orgId>', 'workspace (org) id')
+    .action(async (orgId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('admin.instance.core_local_orgs.remove', { orgId: encodeURIComponent(orgId) });
+      const r = await client.delete(ep.path, { service: ep.service });
+      if (getOutputFormat() === 'json') { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(`Removed ${orgId}. ${(r.orgs || []).length} workspace(s) may still run loops inside the server.`);
+    });
+}

package/lib/commands/lucid.js

@@ -102,6 +102,7 @@ export function registerLucidCommands(program, ctx) {
     if (o.json) { console.log(JSON.stringify(data, null, 2)); return; }
     if (o.agent) { console.log(data.text_agent ?? data.text ?? ''); return; }
     if (o.spoken) { console.log(data.spoken ?? data.text ?? ''); return; }
+    if (o.markdown) { const { renderSitrepMarkdown } = await import('../lucid/markdown.js'); console.log(renderSitrepMarkdown(data)); return; }
     const { renderSitrep } = await import('../lucid/sitrep.js');
     const tty = Boolean(process.stdout.isTTY);
     process.stdout.write(renderSitrep(data, {
@@ -118,14 +119,15 @@ export function registerLucidCommands(program, ctx) {
   const sitrepOpts = (c) => c
     .option('--agent', 'compact, id-rich form for agents')
     .option('--json', 'the full structured situation')
-    .option('--spoken', 'sentences only, as read on the phone');
+    .option('--spoken', 'sentences only, as read on the phone')
+    .option('--markdown', 'chat-ready Markdown for Discord, Matrix and slots (fits one message)');
 
   sitrepOpts(lu
     .command('sitrep')
     .description('One-shot formatted snapshot (areas, what needs you, what changed, what I cannot see)'))
     .action(async (o) => showSitrep(o));
 
-  // Top-level shortcut so any human or agent can ask for a sitrep: `quox sitrep [--agent|--json|--spoken]`.
+  // Top-level shortcut so any human or agent can ask for a sitrep: `quox sitrep [--agent|--json|--spoken|--markdown]`.
   sitrepOpts(program
     .command('sitrep')
     .description('LUCID situation report: what needs you, every area, what changed, what LUCID cannot see'))
@@ -393,9 +395,13 @@ export function registerLucidCommands(program, ctx) {
       if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
       if (data.status === 'filed') {
         printSuccess(`Filed${data.approval_id ? ` (approval ${data.approval_id})` : ''}. Approve it in Approvals.`);
-      } else if (data.status === 'manual') {
+      } else if (data.status === 'manual' && data.command) {
         console.log('This one is manual. Run this yourself:');
-        console.log(`  ${data.command ?? ''}`);
+        console.log(`  ${data.command}`);
+      } else if (data.status === 'manual') {
+        // #992: a 'say' measure has no command; print what it says and how to ask, never a blank instruction.
+        console.log(data.say || (m && m.label) || 'There is nothing to run for this one.');
+        console.log(`  quox lucid ask "${((m && m.label) || 'Look into it').replace(/"/g, "'")} (${ref})"`);
       } else if (data.status === 'opened') {
         console.log(`Opened: ${data.url ?? ''}`);
       } else {

package/lib/commands/memory.js

@@ -26,6 +26,7 @@ import { resolveEndpoint } from '../api/endpoints.js';
 import { QuoxError } from '../core/errors.js';
 import { resolveOrgId } from './helpers.js';
 import { resolveMyAttach } from './agentAttach.js';
+import { hasExplicitProfile } from '../core/actingAs.js';
 
 // QUOXIDENTITY P9: which agent this session acts as is resolved session-scoped
 // (QUOX_T subtree / QUOX_ATTACH_AGENT override / single-attach fallback), so
@@ -46,7 +47,12 @@ async function callMemoryTool({ client, auth, program }, toolName, input) {
   const body = { tool_name: toolName, input };
   const requestOptions = { service: ep.service, body };
 
-  const lease = detectSoleAttachLease();
+  // An explicit -p/--profile (or QUOX_PROFILE) is the caller saying "as me":
+  // it wins over the session's attach lease, same precedence as
+  // core/actingAs. Before this, `quox -p moo memory search` inside an attached
+  // session went out on the lease token and 401'd (proof engine 2026-10-14).
+  const argv = (program.rawArgs || process.argv).slice(2);
+  const lease = hasExplicitProfile(argv) ? null : detectSoleAttachLease();
   if (lease) {
     requestOptions.noAuth = true;
     requestOptions.headers = { Authorization: `Bearer ${lease.token}` };
@@ -260,16 +266,87 @@ export function registerMemoryCommands(program, ctx) {
       }, { format: program.opts().output });
     });
 
+  // QUOXMIND #1111: the old view counted only rows under YOUR user id, so an
+  // org holding hundreds of agent-written memories looked nearly empty. Default
+  // is now the org view (per agent, per writer), falling back honestly.
   memory
     .command('stats')
-    .description('Show memory statistics')
-    .action(async () => {
+    .description('Show memory statistics: the whole org by agent and writer (org admins), else your own')
+    .option('--mine', 'only memories written under your own login')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('memory.stats.list');
+      let data;
+      let note = '';
+      if (options.mine) {
+        data = await client.get(ep.path, { service: ep.service, query: {} });
+      } else {
+        try {
+          data = await client.get(ep.path, { service: ep.service, query: { scope: 'org' } });
+        } catch (err) {
+          if (err?.status !== 403) throw err;
+          data = await client.get(ep.path, { service: ep.service, query: {} });
+          note = 'Org-wide counts need an org admin or owner. Showing only memories written under your own login; agents write under their own identities, so the org holds more.';
+        }
+      }
+      const format = program.opts().output;
+      if (format === 'json') { console.log(JSON.stringify(note ? { ...data, note } : data, null, 2)); return; }
+      if (data?.scope !== 'org') {
+        formatDetail(data.stats || data, { format, title: 'Memory Stats (your login only)' });
+        console.log(note || 'Counts only memories written under your own login. `quox memory stats` without --mine shows the whole org (org admins).');
+        return;
+      }
+      const m = data.memories || {};
+      console.log(`Memory Stats (org): ${m.total ?? 0} valid memories, ${m.not_valid ?? 0} superseded or deleted (kept for history), ${data.pinned ?? 0} pinned, last write ${data.last_write_at || 'never'}`);
+      if (m.by_type) console.log(`By type: ${Object.entries(m.by_type).map(([k, v]) => `${k} ${v}`).join(', ')}`);
+      formatOutput({
+        columns: ['agent', 'count'], headers: ['Agent', 'Memories'],
+        rows: Object.entries(data.by_agent || {}).map(([agent, count]) => ({ agent, count })),
+      }, { format });
+      formatOutput({
+        columns: ['user_id', 'kind', 'count', 'agents'], headers: ['Writer', 'Kind', 'Memories', 'Agents'],
+        rows: (data.by_user || []).map((u) => ({ ...u, agents: (u.agents || []).join(',') })),
+      }, { format });
+      console.log('Valid = not deleted and not superseded. A writer is the login a memory was saved under: your own, an agent identity, service/system (internal agents), or org-shared beliefs.');
+    });
+
+  memory
+    .command('core')
+    .description('Show the core set: memories loaded into every chat turn (pinned, plus auto-promoted decisions and facts rated high or critical)')
+    .option('--limit <n>', 'max memories', '20')
+    .action(async (options) => {
       auth.requireAuth();
-      const data = await client.get(resolveEndpoint('memory.stats.list').path, { service: resolveEndpoint('memory.stats.list').service });
-      formatDetail(data.stats || data, {
-        format: program.opts().output,
-        title: 'Memory Stats',
-      });
+      const ep = resolveEndpoint('memory.core-set');
+      const data = await client.get(ep.path, { service: ep.service, query: { limit: options.limit } });
+      formatOutput({
+        columns: ['id', 'core_reason', 'agent_id', 'memory_type', 'content'],
+        headers: ['ID', 'Why', 'Agent', 'Type', 'Content'],
+        rows: (data.memories || []).map((m) => ({ ...m, content: (m.content || '').slice(0, 80) })),
+      }, { format: program.opts().output, raw: data });
+    });
+
+  memory
+    .command('pin')
+    .description('Pin a memory into the core set so every chat turn carries it')
+    .argument('<id>', 'memory ID')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('memory.pin', { id });
+      const data = await client.post(ep.path, { service: ep.service, body: {} });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      printSuccess(`Pinned ${id} into the core set.`);
+    });
+
+  memory
+    .command('unpin')
+    .description('Take a memory out of the core set (also stops it being auto-promoted)')
+    .argument('<id>', 'memory ID')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('memory.unpin', { id });
+      const data = await client.delete(ep.path, { service: ep.service });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      printSuccess(`Unpinned ${id}: it stays a memory, but is no longer in the core set.`);
     });
 
   memory

package/lib/commands/mind.js

@@ -0,0 +1,71 @@
+/**
+ * `quox mind implants|implant <id>|health`: QuoxMind cognitive implants (read-only).
+ * Collector routes under /api/v1/mind (org-scoped). Implants with no recorded
+ * activity say so; nothing is invented.
+ */
+import { formatOutput } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+export function registerMindCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const get = async (name, params) => {
+    auth.requireAuth();
+    const ep = resolveEndpoint(name, params);
+    return client.get(ep.path, { service: ep.service, query: { org_id: resolveOrgId(auth, program) } });
+  };
+  const isJson = () => program.opts().output === 'json';
+
+  const mind = program.command('mind').description('QuoxMind: the cognitive implants (read-only)');
+
+  mind
+    .command('implants')
+    .description('List the cognitive implants: purpose, status, last activity')
+    .action(async () => {
+      const data = await get('mind.implants');
+      const rows = data.implants || [];
+      formatOutput(rows.map((i) => ({
+        ID: i.short,
+        NAME: i.name,
+        PURPOSE: i.purpose,
+        STATUS: i.status,
+        'LAST ACTIVITY': i.last_activity || 'no activity recorded',
+        // QUOXMIND-PROOF: firing evidence from the implant's own table (null = not tracked).
+        'LAST FIRED': i.activity_error ? 'unknown' : (typeof i.fired_7d === 'number' ? (i.last_fired || 'never') : 'not tracked'),
+        '7D': typeof i.fired_7d === 'number' && !i.activity_error ? i.fired_7d : '-',
+      })), {
+        format: program.opts().output,
+        columns: ['ID', 'NAME', 'STATUS', 'LAST FIRED', '7D', 'PURPOSE'],
+        emptyMessage: 'No implants registered.',
+        raw: rows,
+      });
+    });
+
+  mind
+    .command('implant <id>')
+    .description('One implant in detail (e.g. predict, reflect, repobrain, qortex)')
+    .action(async (id) => {
+      const d = await get('mind.implant', { id });
+      if (isJson()) { console.log(JSON.stringify(d, null, 2)); return; }
+      console.log(`${d.name} (${d.short}) · ${d.status}${d.tier ? ` · ${d.tier}` : ''}`);
+      console.log(d.description || d.purpose);
+      if (d.inspired_by) console.log(`Inspired by: ${d.inspired_by}`);
+      if (d.summary) console.log(`Now: ${d.summary}`);
+      console.log(d.activity);
+      if (typeof d.fired_7d === 'number' && !d.activity_error) console.log(`Fired: ${d.last_fired || 'never'} · ${d.fired_7d} in the last 7 days${d.activity_source ? ` (from ${d.activity_source})` : ''}`);
+      else if (d.activity_error) console.log(`Fired: unknown (${d.activity_error})`);
+      for (const [k, v] of Object.entries(d.metrics || {})) if (v !== null && typeof v !== 'object') console.log(`  ${k}: ${v}`);
+    });
+
+  mind
+    .command('health')
+    .description('Summary of QuoxMind health across all implants')
+    .action(async () => {
+      const d = await get('mind.health');
+      if (isJson()) { console.log(JSON.stringify(d, null, 2)); return; }
+      console.log(`${d.total} implants: ${Object.entries(d.by_status).map(([k, v]) => `${v} ${k}`).join(', ')}`);
+      console.log(`${d.with_activity} with recorded activity, ${d.no_activity} with no activity recorded`);
+      if (typeof d.fired_7d_total === 'number') console.log(`Last 7 days: ${d.fired_7d_implants} implants fired (${d.fired_7d_total} firings), ${d.silent_7d} silent, ${d.activity_unknown} not tracked`);
+      console.log(d.average_health === null ? 'Average health: not enough data' : `Average health: ${d.average_health} (over ${d.scored} scored)`);
+    });
+}

package/lib/commands/mon.js

@@ -2,7 +2,7 @@
  * Monitoring commands: Docker fleet, Wazuh security monitoring, AGH-chain
  * agent honesty leaderboard, Prometheus metrics, and monitoring config.
  *
- * quox mon docker fleet|containers|container|logs|stats|stacks|df|action
+ * quox mon docker fleet|containers|container|inspect|logs|stats|stacks|df|action
  * quox mon wazuh status|agents|alerts|vulns|deploy-history|deploy-agent|deploy-bulk|active-response
  * quox mon agh-chain leaderboard|agent|events
  * quox mon metrics
@@ -36,6 +36,47 @@ async function confirmOrSkip(program, options, message) {
   return ans.confirm;
 }
 
+
+/** One readable line per fact from the inspect health block (null when the container has no healthcheck). */
+function healthRows(h) {
+  if (!h) return null;
+  const rows = [];
+  const streak = h.failing_streak ? ` (failing ${h.failing_streak} times)` : '';
+  rows.push(`health: ${h.status || 'unknown'}${streak}`);
+  if (h.test) {
+    const parts = [h.interval && `every ${h.interval}`, h.timeout && `timeout ${h.timeout}`, h.retries != null && `retries ${h.retries}`].filter(Boolean);
+    rows.push(`probe: ${h.test}${parts.length ? ' ' + parts.join(', ') : ''}`);
+  }
+  for (const p of h.last_probes || []) {
+    const o = String(p.output || '').replace(/\s+/g, ' ').trim();
+    rows.push(`last: exit ${p.exit_code}${o ? ` '${o}'` : ''}${p.end ? ` at ${p.end}` : ''}`);
+  }
+  return rows;
+}
+
+/**
+ * DEVFLEET-DOCKER: an error body is not data. If the collector reports a refused/failed Docker
+ * read, say so (stderr) and set a non-zero exit instead of printing an empty list. Partial fleets
+ * print the failed hosts as warnings. Returns true when the whole read failed (caller stops).
+ */
+function reportDockerReadFailures(data) {
+  if (!data) return false;
+  const failedHosts = Array.isArray(data.hosts_failed) ? data.hosts_failed
+    : (data.success === false && Array.isArray(data.hosts) ? data.hosts.filter((h) => h && h.ok === false) : []);
+  if (data.success === false) {
+    const tag = data.refused ? ' (refused, error_code ' + (data.error_code || 'approval_required') + ')' : '';
+    console.error('Docker read failed' + tag + ': ' + (data.error || 'unknown error'));
+    for (const h of failedHosts) console.error('  ' + h.host + ': ' + (h.error || 'failed'));
+    process.exitCode = 1;
+    return true;
+  }
+  if (data.partial) {
+    console.error('Partial result: ' + failedHosts.length + ' host(s) could not be read; the list below is incomplete.');
+    for (const h of failedHosts) console.error('  ' + h.host + ': ' + (h.error || 'failed'));
+  }
+  return false;
+}
+
 export function registerMonCommands(program, ctx) {
   const { client, auth } = ctx;
 
@@ -59,6 +100,7 @@ export function registerMonCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('mon.docker.fleet.list');
       const data = await client.get(ep.path, { service: ep.service, query: options.refresh ? { refresh: 'true' } : undefined });
+      if (reportDockerReadFailures(data)) return;
       const hosts = data.hosts || [];
       formatOutput({
         // fleet #392: docker fleet rows are id/containers_total/docker_version; ip and status don't exist.
@@ -82,6 +124,7 @@ export function registerMonCommands(program, ctx) {
       if (options.all === false) query.all = 'false';
       if (options.refresh) query.refresh = 'true';
       const data = await client.get(ep.path, { service: ep.service, query });
+      if (reportDockerReadFailures(data)) return;
       formatOutput({
         columns: ['host_id', 'id', 'name', 'image', 'state', 'status'],
         headers: ['Host', 'ID', 'Name', 'Image', 'State', 'Status'],
@@ -98,6 +141,9 @@ export function registerMonCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('mon.docker.containers.get', { id });
       const data = await client.get(ep.path, { service: ep.service, query: { host: options.host } });
+      // quox#1001: a 200 with success:false (e.g. "Bastion not configured") is a failure, not an
+      // empty container. Surface the error on stderr + exit non-zero instead of rendering a blank card.
+      if (reportDockerReadFailures(data)) return;
       formatDetail(data, {
         format: program.opts().output,
         title: `Container: ${id} (${options.host})`,
@@ -106,6 +152,24 @@ export function registerMonCommands(program, ctx) {
       });
     });
 
+  docker
+    .command('inspect')
+    .description('Show container state and health (failing probe command and last results)')
+    .argument('<id>', 'container ID')
+    .requiredOption('--host <hostId>', 'host the container lives on')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.docker.containers.inspect', { id });
+      const data = await client.get(ep.path, { service: ep.service, query: { host: options.host } });
+      if (reportDockerReadFailures(data)) return;
+      if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      const d = data.details || {};
+      console.log(`Container: ${id} (${options.host})`);
+      console.log(`state: ${d.status || 'unknown'} · image: ${d.image || 'unknown'}`);
+      const rows = healthRows(d.health);
+      console.log(rows ? rows.join('\n') : 'health: no healthcheck configured');
+    });
+
   docker
     .command('logs')
     .description('Show container logs')
@@ -143,6 +207,7 @@ export function registerMonCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('mon.docker.stacks.list');
       const data = await client.get(ep.path, { service: ep.service, query: options.host ? { host: options.host } : undefined });
+      if (reportDockerReadFailures(data)) return;
       formatOutput({
         columns: ['host_id', 'name', 'status', 'services'],
         headers: ['Host', 'Stack', 'Status', 'Services'],
@@ -181,7 +246,9 @@ export function registerMonCommands(program, ctx) {
       const ep = resolveEndpoint('mon.docker.containers.action', { id, action });
       const data = await client.post(ep.path, { service: ep.service, body: { host: options.host } });
       if (data.success === false) {
-        printWarning(`Action failed: ${data.error || 'unknown error'}`);
+        // quox#1001: surface the real server error and exit non-zero (was exit 0 = success on failure).
+        printWarning(`Action failed: ${data.error || data.message || 'unknown error'}`);
+        process.exitCode = 1;
         return;
       }
       printSuccess(`Container ${id}: ${action} succeeded.`);

package/lib/commands/monitoring.js

@@ -35,7 +35,7 @@ export function registerMonitoringCommands(program, ctx) {
       // nothing is stored); logged-in now actually sends the token.
       const data = await client.get(resolveEndpoint('v1.health.aggregate.list').path, {
         service: resolveEndpoint('v1.health.aggregate.list').service,
-        timeout: 5000,
+        timeout: 15000, // #930: aggregate fan-out, 5s too tight under load
       });
       formatDetail(data, { format: program.opts().output, title: 'Platform Health' });
     });