quoxcli 0.2.0 → 0.3.1

package/lib/commands/chat.js

@@ -26,6 +26,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 +74,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 } = {}) {
   const queryId = generateQueryId();
   const body = buildStreamQuery({ queryId, message, agent, sessionId, context });
 
@@ -50,7 +90,19 @@ 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 iter = client.stream(resolveEndpoint('chat.stream').path, { service: resolveEndpoint('chat.stream').service, body, untilClose: Boolean(trace) })[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)) for (const l of err.body.aocl_layers) printTrace({ type: 'aocl.layer', ...l });
+      throw err;
+    }
+    if (step.done) break;
+    const event = step.value;
+    if (trace) printTrace(event);
     switch (event.type) {
       case 'connected':
         break;
@@ -120,6 +172,7 @@ 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('--trace', 'print the turn\'s protocol events (per-layer AOCL, traces, summary) to stderr as they arrive')
     .action(async (message, options) => {
       auth.requireAuth();
       const streaming = options.stream !== false;
@@ -161,6 +214,7 @@ 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;
               console.log();
@@ -190,6 +244,7 @@ export function registerChatCommands(program, ctx) {
             sessionId: options.conversation,
           }, {
             onAgentLabel: () => {}, // no label prefix in single-shot streaming; just print tokens
+            trace: Boolean(options.trace),
           });
         } catch (err) {
           console.error(chalk.red(`Error: ${err.message}`));

package/lib/commands/claude.js

@@ -3,6 +3,7 @@
  * lives in core/governedSession.js; this file holds argument parsing and the
  * commander wiring. argv arrays only; user input never reaches a shell string.
  */
+import { markForwardsRawArgs } from '../core/global-flags.js';
 import * as gs from '../core/governedSession.js';
 import { validateName, PROGRAMS } from '../core/governedSession.js';
 import { runClaudeLs } from '../core/claudeLs.js';
@@ -178,8 +179,8 @@ export function registerClaudeCommands(program, ctx, over) {
   // `quox claude <args>` behaves exactly like `claude <args>`: every arg is
   // forwarded verbatim. Only --no-tmux is quox's own. Management lives in
   // `quox sessions` so it can never collide with claude's own arguments.
-  program
-    .command('claude')
+  markForwardsRawArgs(program
+    .command('claude'), 'forwards argv after the verb verbatim')
     .description('Run Claude Code (same arguments as claude) in a tmux session that survives sleep and drops')
     .argument('[args...]', 'passed to claude exactly as given (quox adds only --no-tmux, --as, --slot)')
     .addHelpText('after', `
@@ -205,8 +206,8 @@ Claude's own --agent is untouched and passes through to claude.`)
       const parsed = parseClaudeArgs(rest);
       process.exitCode = runClaude(parsed, over);
     });
-  program
-    .command('codex')
+  markForwardsRawArgs(program
+    .command('codex'), 'forwards argv after the verb verbatim')
     .description('Run Codex (same arguments as codex) in a tmux session that survives sleep and drops')
     .argument('[args...]', 'passed to codex exactly as given (quox adds only --no-tmux)')
     .helpOption(false)
@@ -218,8 +219,8 @@ Claude's own --agent is untouched and passes through to claude.`)
       const parsed = parseCodexArgs(i >= 0 ? raw.slice(i + 1) : []);
       process.exitCode = runCodex(parsed, over);
     });
-  program
-    .command('gemini')
+  markForwardsRawArgs(program
+    .command('gemini'), 'forwards argv after the verb verbatim')
     .description('Run Gemini CLI (same arguments as gemini) in a tmux session that survives sleep and drops')
     .argument('[args...]', 'passed to gemini exactly as given (quox adds only --no-tmux)')
     .helpOption(false)
@@ -230,8 +231,8 @@ Claude's own --agent is untouched and passes through to claude.`)
       const i = raw.indexOf('gemini', 2);
       process.exitCode = runGemini(parseGeminiArgs(i >= 0 ? raw.slice(i + 1) : []), over);
     });
-  program
-    .command('wrap')
+  markForwardsRawArgs(program
+    .command('wrap'), 'forwards argv after the verb verbatim')
     .description('Run any program in a governed tmux session: quox wrap <program> [args...]')
     .argument('<program>', 'command name on PATH')
     .argument('[args...]', 'passed to the program exactly as given')
@@ -270,6 +271,31 @@ Claude's own --agent is untouched and passes through to claude.`)
       const json = !!o.json || program.opts().output === 'json';
       process.exitCode = await runSessionsOverview({ json, watch: !!o.watch, all: !!o.all }, { ...so, fetchIndex });
     });
+  // `quox active [sessions|slots|agents]`: one short summary of who is doing what (QUOXON-1208).
+  program.command('active [filter]')
+    .description('Who is doing what: one line per active worker, grouped working / waiting on you / idle; filter: sessions, slots, agents')
+    .option('--json', 'print the summary as JSON')
+    .option('--all', 'show every worker (default: top 10 per group)')
+    .option('--lines', 'the older one-line-per-worker layout with state and age columns')
+    .action(async (filter, o) => {
+      const so = (over && over.sessionsOverview) || {};
+      const fetchIndex = so.fetchIndex || (async () => {
+        const { client, auth } = ctx;
+        auth.requireAuth();
+        const ep = resolveEndpoint('v1.sessions.index');
+        const org = orgOrNull(auth);
+        return client.get(ep.path, { service: ep.service, retries: 0, ...(org ? { query: { org_id: org } } : {}) });
+      });
+      const json = !!o.json || program.opts().output === 'json';
+      const { runActive } = await import('../core/activeSummary.js');
+      const fetchSlots = so.fetchSlots || (async () => {
+        const { client, auth } = ctx;
+        const ep = resolveEndpoint('v1.slots.list');
+        const r = await client.get(ep.path, { service: ep.service, retries: 0 });
+        return Array.isArray(r) ? r : (r?.slots || r?.data || []);
+      });
+      process.exitCode = await runActive({ filter: filter || null, json, all: !!o.all, lines: !!o.lines }, { ...so, fetchIndex, fetchSlots });
+    });
   sessions.command('heartbeat <tmuxSession>', { hidden: true })
     .description('Heartbeat one wrapped tmux session to the org session index (started by quox claude)')
     .option('--loop', 'keep beating until the tmux session ends')

package/lib/commands/contacts.js

@@ -107,6 +107,7 @@ export function registerContactsCommands(program, ctx) {
     const q = textQuery ?? options.q;
     if (q) query.q = q;
     if (options.status) query.status = options.status;
+    if (options.relationship) query.relationship = options.relationship;
     if (options.limit !== undefined) query.limit = Number(options.limit);
     const ep = resolveEndpoint('contactsq.contacts.list');
     const data = await call(() => client.get(ep.path, { service: ep.service, query }));
@@ -186,6 +187,7 @@ export function registerContactsCommands(program, ctx) {
     .description('List contacts')
     .option('--q <text>', 'name filter')
     .option('--status <s>', 'active | candidate | archived')
+    .option('--relationship <r>', 'primary relationship, e.g. customer | supplier | partner')
     .option('--limit <n>', 'max contacts')
     .action((options) => list(options));
 
@@ -373,6 +375,53 @@ export function registerContactsCommands(program, ctx) {
       announce('contacts brief', `${d.candidates_to_review} candidates, ${d.duplicates} duplicates`);
     });
 
+  contacts
+    .command('timeline <id>')
+    .description('Interaction history of a contact, newest first: surface, direction, outcome and time (refs only, no message bodies)')
+    .option('--limit <n>', 'max entries', '20')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('contactsq.timeline', { id });
+      const d = await call(() => client.get(ep.path, { service: ep.service, query: { limit: options.limit } }));
+      if (isJson(program)) return printJson(d);
+      const rows = d.timeline || [];
+      if (!rows.length) console.log('No interactions recorded.');
+      for (const t of rows) console.log(`${t.occurred_at || ''}  ${t.surface || ''} ${t.direction || ''} ${t.outcome || ''}${t.agent_id ? ` (agent ${t.agent_id})` : ''}`);
+      announce('contacts timeline', `${rows.length} entries`);
+    });
+
+  contacts
+    .command('best-channel <id>')
+    .description('Which channel (voice, email or sms) may be used to reach a contact for a purpose, with every alternative and its reason codes. Read-only; never shows a number or address')
+    .option('--purpose <purpose>', 'service, transactional, marketing or research', 'service')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('contactsq.best_channel', { id });
+      const d = await call(() => client.get(ep.path, { service: ep.service, query: { purpose: options.purpose } }));
+      if (isJson(program)) return printJson(d);
+      console.log(`channel: ${d.channel || 'none allowed'}`);
+      for (const a of d.alternatives || []) console.log(`  ${a.channel}: ${a.decision}${(a.reasons || []).length ? ` (${a.reasons.join(', ')})` : ''}`);
+      announce('contacts best-channel', d.channel || 'none allowed');
+    });
+
+  contacts
+    .command('count')
+    .description('How many contacts: the total (people and organisations, not archived or erased) with counts by kind, status and relationship. --kind narrows to person or organisation')
+    .option('--kind <kind>', 'person or organisation')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('contactsq.count');
+      const query = options.kind ? { kind: options.kind } : undefined;
+      const d = await call(() => client.get(ep.path, { service: ep.service, query }));
+      if (isJson(program)) return printJson(d);
+      const fmt = (o) => Object.entries(o || {}).map(([k, n]) => `${k} ${n}`).join(', ') || 'none';
+      formatDetail({
+        total: d.total, ...(d.kind ? { kind: d.kind } : {}), by_kind: fmt(d.by_kind), by_status: fmt(d.by_status),
+        by_relationship: fmt(d.by_relationship), candidates_to_review: d.candidates_to_review, generated_at: d.generated_at,
+      });
+      announce('contacts count', `${d.total} contacts${d.kind ? ` (${d.kind})` : ''}`);
+    });
+
   contacts
     .command('selftest')
     .description('Drive the read path (search, find, resolve, best channel, timeline, touchpoint, brief) against a demo contact. Never dials or sends. --agent runs it through the attached agent tool scope')

package/lib/commands/conversation.js

@@ -16,11 +16,29 @@ export function registerConversationCommands(program, ctx) {
 
   conv
     .command('list')
-    .description('List conversations')
+    .description('List your chat conversations (newest first); --archive lists the imported conversation archive')
     .option('--limit <n>', 'Max results', '20')
-    .option('--offset <n>', 'Skip results', '0')
+    .option('--offset <n>', 'Skip results (archive only)', '0')
+    .option('--archive', 'list the imported conversation archive instead of chat conversations')
     .action(async (opts) => {
       auth.requireAuth();
+      if (!opts.archive) {
+        const ep = resolveEndpoint('conversations.chat.list');
+        const data = await client.get(ep.path, { service: ep.service, query: { limit: opts.limit } });
+        const rows = data.conversations || [];
+        formatOutput({
+          columns: ['id', 'title', 'turns', 'agent', 'updated_at'],
+          headers: ['ID', 'Title', 'Turns', 'Agent', 'Updated'],
+          rows: rows.map((c) => ({
+            id: c.id,
+            title: (c.title || 'Untitled').slice(0, 50),
+            turns: c.turn_count ?? 0,
+            agent: c.agent || '-',
+            updated_at: c.updated_at ? new Date(c.updated_at).toLocaleString() : '-',
+          })),
+        }, { format: program.opts().output });
+        return;
+      }
       const query = { limit: opts.limit, offset: opts.offset };
       const data = await client.get(resolveEndpoint('conversations.list').path, { service: resolveEndpoint('conversations.list').service, query });
       const conversations = data.conversations || data || [];
@@ -39,9 +57,22 @@ export function registerConversationCommands(program, ctx) {
   conv
     .command('get')
     .argument('<id>', 'conversation ID')
-    .description('Get conversation details')
-    .action(async (id) => {
+    .description('Show a chat conversation\'s turns; --archive reads the imported conversation archive')
+    .option('--limit <n>', 'Max turns (chat only)', '50')
+    .option('--archive', 'read the imported conversation archive instead of chat conversations')
+    .action(async (id, opts) => {
       auth.requireAuth();
+      if (!opts.archive) {
+        const ep = resolveEndpoint('conversations.chat.turns', { id });
+        const data = await client.get(ep.path, { service: ep.service, query: { limit: opts.limit } });
+        const turns = data.turns || [];
+        formatOutput({
+          columns: ['ts', 'role', 'content'],
+          headers: ['Time', 'Role', 'Content'],
+          rows: turns.map((t) => ({ ts: t.ts ? new Date(t.ts).toLocaleString() : '-', role: t.role, content: t.content })),
+        }, { format: program.opts().output });
+        return;
+      }
       const data = await client.get(resolveEndpoint('conversations.get', { id }).path, { service: resolveEndpoint('conversations.get', { id }).service });
       formatDetail(data.conversation || data, { format: program.opts().output, title: 'Conversation' });
     });

package/lib/commands/dashboard.js

@@ -0,0 +1,43 @@
+/**
+ * `quox dashboard [page]`: open the web dashboard already signed in, via a one-time link
+ * (10 minutes, single use). Same engine as /dashboard in the Quox client (lib/quoxon/slash/dashboard.js).
+ * Over SSH it prints the link and does not open a browser. The link is a credential: it is printed
+ * to the terminal only, never logged.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+import { runDashboard, dashboardLines, PAGES } from '../quoxon/slash/dashboard.js';
+import { supportsHyperlinks } from '../quoxon/markdown.js';
+import { resolveDashboardBase, detectLanIp } from '../quoxon/hostUrls.js';
+import { loadJourney } from '../quoxon/onboarding/journey.js';
+
+/**
+ * Z2H-R4: the address to print, resolved exactly like /dashboard in the Quox client (api.js
+ * dashboardBase): server app URL, else a non-loopback profile URL, else the install finale's URL,
+ * else this machine's LAN IP. Over SSH a localhost link only works on the Quox box itself.
+ */
+export async function commandDashboardBase({ client, config, journey = loadJourney, lanIp = detectLanIp() } = {}) {
+  const profileUrl = config.getActiveProfile?.()?.url || config.getBaseUrl();
+  let serverApp = null;
+  try { const ep = resolveEndpoint('admin.instance.basics.get'); const r = await client.get(ep.path, { service: ep.service, retries: 0 }); serverApp = r?.effective?.appBaseUrl || null; } catch { serverApp = null; }
+  let journeyUrl = null; try { journeyUrl = journey()?.dashboardUrl || null; } catch { journeyUrl = null; }
+  return resolveDashboardBase({ serverApp, profileUrl, journeyUrl, lanIp }).url;
+}
+
+export function registerDashboardCommands(program, ctx) {
+  const { client, auth, config, lanIp = detectLanIp, journey = loadJourney } = ctx;
+  program
+    .command('dashboard')
+    .description(`Open the web dashboard signed in (one-time link, 10 minutes). Pages: ${Object.keys(PAGES).join(', ')}`)
+    .argument('[page]', 'dashboard page to land on')
+    .action(async (page) => {
+      auth.requireAuth();
+      const baseUrl = await commandDashboardBase({ client, config, journey, lanIp: lanIp() });
+      const r = await runDashboard({ page, baseUrl, mint: () => { const ep = resolveEndpoint('auth.login-link'); return client.post(ep.path, { service: ep.service, body: {}, retries: 0 }); } });
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify({ kind: r.kind, url: r.url ?? null, opened: Boolean(r.opened), remote: Boolean(r.remote), error: r.error ?? null }, null, 2));
+      } else {
+        for (const l of dashboardLines(r, { hyperlinks: supportsHyperlinks() })) console.log(l.text);
+      }
+      if (r.kind === 'error') process.exitCode = 1;
+    });
+}

package/lib/commands/department.js

@@ -15,17 +15,38 @@ export function registerDepartmentCommands(program, ctx) {
 
   dept
     .command('list')
-    .description('List departments')
-    .requiredOption('--division <divId>', 'division ID')
+    .description('List departments (all divisions unless --division; division ids: quox org divisions list)')
+    .option('--division <divId>', 'only this division')
     .action(async (options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const data = await client.get(resolveEndpoint('divisions.departments.list', { orgId, division: options.division }).path, { service: resolveEndpoint('divisions.departments.list', { orgId, division: options.division }).service });
+      const listFor = async (division) => {
+        const ep = resolveEndpoint('divisions.departments.list', { orgId, division });
+        const data = await client.get(ep.path, { service: ep.service });
+        return data.departments || data || [];
+      };
+      if (options.division) {
+        formatOutput({
+          columns: ['id', 'name', 'description', 'created_at'],
+          headers: ['ID', 'Name', 'Description', 'Created'],
+          rows: await listFor(options.division),
+        }, { format: program.opts().output });
+        return;
+      }
+      // quox#922: no --division lists every division's departments, so the read
+      // needs no id the department group cannot show.
+      const divEp = resolveEndpoint('divisions.list', { orgId });
+      const divData = await client.get(divEp.path, { service: divEp.service });
+      const divisions = divData.divisions || divData || [];
+      const rows = [];
+      for (const d of divisions) {
+        for (const dept of await listFor(d.id)) rows.push({ ...dept, division: d.name || d.id });
+      }
       formatOutput({
-        columns: ['id', 'name', 'description', 'created_at'],
-        headers: ['ID', 'Name', 'Description', 'Created'],
-        rows: data.departments || data,
-      }, { format: program.opts().output });
+        columns: ['id', 'name', 'division', 'description', 'created_at'],
+        headers: ['ID', 'Name', 'Division', 'Description', 'Created'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No departments.' });
     });
 
   dept

package/lib/commands/devResident.js

@@ -164,10 +164,13 @@ export function registerDevResidentCommands(dev, ctx) {
     const slotName = resolveSlotName(options, hostId);
     const sessionName = options.sessionName || defaultSessionName(slotName);
 
+    let released = true;
+    let killed = true;
     try {
       const releaseEp = resolveEndpoint('v1.slots.release', { name: slotName });
       await client.post(releaseEp.path, { service: releaseEp.service, body: { org_id: orgId, force: true } });
     } catch (err) {
+      released = false;
       printWarning(`Releasing ${slotName} failed (continuing): ${err.message}`);
     }
 
@@ -175,10 +178,11 @@ export function registerDevResidentCommands(dev, ctx) {
       const killEp = resolveEndpoint('v1.dev.sessions.kill', { hostId, sessionId: sessionName, byName: true });
       await client.delete(killEp.path, { service: killEp.service });
     } catch (err) {
+      killed = false;
       printWarning(`Killing tmux session ${sessionName} on ${hostId} failed (continuing): ${err.message}`);
     }
 
-    return { host_id: hostId, slot_name: slotName, session_name: sessionName };
+    return { host_id: hostId, slot_name: slotName, session_name: sessionName, released, killed };
   }
 
   resident
@@ -290,8 +294,16 @@ export function registerDevResidentCommands(dev, ctx) {
     .action(async (options) => {
       auth.requireAuth();
       const report = await releaseAndKill(options);
-      formatDetail(report, { format: program.opts().output, title: `Resident retired on ${report.host_id}` });
-      printSuccess(`Resident retired on ${report.host_id}: slot ${report.slot_name} released, session ${report.session_name} killed.`);
+      // #1018: only claim what happened, in the card title too; a retire that left the slot held or the session running failed.
+      const outcome = report.released && report.killed ? 'Resident retired'
+        : report.released || report.killed ? 'Resident retire incomplete' : 'Resident retire failed';
+      formatDetail(report, { format: program.opts().output, title: `${outcome} on ${report.host_id}` });
+      if (report.released && report.killed) {
+        printSuccess(`Resident retired on ${report.host_id}: slot ${report.slot_name} released, session ${report.session_name} killed.`);
+      } else {
+        printWarning(`Resident NOT fully retired on ${report.host_id}: slot ${report.slot_name} ${report.released ? 'released' : 'NOT released'}, session ${report.session_name} ${report.killed ? 'killed' : 'NOT killed'}.`);
+        process.exitCode = 1;
+      }
     });
 
   resident

package/lib/commands/devSupervisor.js

@@ -29,7 +29,7 @@ import { resolveEndpoint } from '../api/endpoints.js';
 import { resolveOrgId } from './helpers.js';
 import { loadResidentProfile, expandHome, deriveSupervisorEnv } from '../core/residentAuth.js';
 import { createInitialPumpState, runPumpOnce } from '../core/residentPump.js';
-import { createInitialAlarmState, runWardenPass } from '../core/residentAlarm.js';
+import { createInitialAlarmState, runWardenPass, sendAlarm } from '../core/residentAlarm.js';
 import {
   DEFAULT_SETTINGS,
   DEFAULT_IDLE_RECHECK_SECONDS,
@@ -344,7 +344,17 @@ export function registerDevSupervisorCommands(dev, ctx) {
         await client.post(ep.path, { service: ep.service, body: { ...fields, slot_name: slotName, org_id: orgId } });
       };
 
+      // GRIPE-797: one owner alert per auth-expiry episode, same transport
+      // order as the warden alarm (tg-send.sh first, slot say fallback).
+      const alertOwner = async (text) => {
+        const script = ctx.tgSendScriptPath || join(homedir(), '.claude', 'skills', 'telegram-owner', 'tg-send.sh');
+        await sendAlarm({
+          tgSend: async (session, t) => { await (ctx.execFileAsync || promisify(execFile))('bash', [script, session, t]); },
+          postSlotNotice: postReply, text, sessionName: `SUPERVISOR-${hostId}`, log,
+        });
+      };
       const commonPollArgs = {
+        alertOwner,
         hostId,
         slot: slotName,
         selfIdentity,
@@ -633,6 +643,8 @@ export function registerDevSupervisorCommands(dev, ctx) {
           }
         } catch (err) {
           log('error', `poll failed: ${err.message}`);
+          // #1018: a single pass that failed is a failed run, not a quiet success.
+          if (options.once) process.exitCode = 1;
           if (continuous && waitMode) {
             waitFailures += 1;
             if (waitFailures >= DEFAULT_WAIT_FAILURE_THRESHOLD) {

package/lib/commands/discord.js

@@ -25,14 +25,10 @@ const QDP = process.env.QDP_CLI_PATH
 
 /**
  * Per-verb usage, mirrored from qdp.mjs's own header doc block (bin/qdp.mjs
- * in the quox-discord-pro repo). qdp itself has no --help handling of its
- * own, and this command hand-rolls arg dispatch (allowUnknownOption +
- * helpOption(false), see below) rather than commander subcommands, so
- * `--help`/`-h` was previously just another unrecognised arg forwarded
- * straight through to qdp — which silently ran the verb instead of showing
- * help. Worst case for a mutating verb (bind/unbind/provision): "--help"
- * would have actually bound/unbound/provisioned a channel. This map is
- * checked BEFORE qdp is ever spawned so that can't happen (quox#603).
+ * in the quox-discord-pro repo), shown in each subcommand's --help. qdp has no
+ * --help handling of its own; before quox#1077 this command hand-rolled arg
+ * dispatch and had to intercept --help itself (quox#603). Commander
+ * subcommands now answer --help before any action runs.
  */
 const VERB_USAGE = {
   status: 'qdp status                 daemon liveness, instances, binding count',
@@ -56,41 +52,81 @@ const VERB_USAGE = {
     + '    --dry-run                   print exactly what it WOULD do, change nothing',
 };
 
-const GENERAL_USAGE = 'Usage: quox discord <verb> [args...]\n\n'
-  + Object.values(VERB_USAGE).map((u) => `  ${u}`).join('\n')
+/**
+ * qdp verbs that only READ (quox#1077). Each was checked against bin/qdp.mjs:
+ * status/instances/bindings print config.json, the pid file and the systemd
+ * state; gaps GETs the open support-gap inbox items; health reads the pid and
+ * systemd state; doctor GETs the control API /health and Discord's channel,
+ * webhook and @me endpoints. None issues PUT/POST/PATCH/DELETE or writes a
+ * file. bind, unbind and provision PUT/DELETE bindings and create channels.
+ */
+export const DISCORD_READ_VERBS = ['status', 'instances', 'bindings', 'gaps', 'health', 'doctor'];
+export const DISCORD_WRITE_VERBS = ['bind', 'unbind', 'provision'];
+
+// No "Usage:" line here: the matrix's --help walker (scripts/matrix/cli-tree.mjs) reads one as the command's usage.
+const GENERAL_USAGE = Object.values(VERB_USAGE).map((u) => `  ${u}`).join('\n')
   + '\n\nRun `quox discord <verb> --help` for a single verb\'s usage.';
 
-function printVerbHelp(verb) {
-  if (verb && VERB_USAGE[verb]) {
-    process.stdout.write(`Usage:\n  ${VERB_USAGE[verb]}\n`);
-  } else {
-    process.stdout.write(`${GENERAL_USAGE}\n`);
+function runQdp(verb, args = []) {
+  if (!fs.existsSync(QDP)) {
+    process.stderr.write(
+      `Discord Pro control CLI (qdp) not found at ${QDP}\n` +
+      'Set QDP_CLI_PATH if it lives elsewhere, or install the quox-discord-pro daemon on this host.\n',
+    );
+    process.exit(2);
   }
+  const r = spawnSync(process.execPath, [QDP, verb, ...args], { stdio: 'inherit' });
+  if (r.error) {
+    process.stderr.write(`qdp failed to run: ${r.error.message}\n`);
+    process.exit(2);
+  }
+  process.exit(r.status ?? 2);
 }
 
+const VERB_DESC = { unbind: 'remove a channel binding', doctor: 'per-binding view/webhook/liveness check (exits non-zero if any binding is broken)' };
+const firstLine = (verb) => VERB_DESC[verb] || VERB_USAGE[verb].split('\n')[0].replace(/^qdp \S+(?: [<[][^\]>]*[>\]])*\s+/, '').trim();
+
+/**
+ * One commander subcommand per qdp verb (quox#1077). It used to be a single
+ * `discord [args...]` leaf, so the CLI leaf policy could only class the whole
+ * group, and it classed it write: a read like `quox discord bindings` was held
+ * for approval. Per-verb leaves let reads be read and keep bind/unbind/provision
+ * write. Commander's own --help runs before any action, so `--help` can never
+ * reach qdp and run a mutating verb (quox#603).
+ */
 export function registerDiscordCommands(program) {
-  program
-    .command('discord [args...]')
-    .description('Quox Discord Pro daemon: status | instances | bindings | bind | unbind | gaps | health')
-    .allowUnknownOption(true)
-    .helpOption(false)
-    .action((args = []) => {
-      if (args.includes('--help') || args.includes('-h')) {
-        printVerbHelp(args[0]);
-        process.exit(0);
-      }
-      if (!fs.existsSync(QDP)) {
-        process.stderr.write(
-          `Discord Pro control CLI (qdp) not found at ${QDP}\n` +
-          'Set QDP_CLI_PATH if it lives elsewhere, or install the quox-discord-pro daemon on this host.\n',
-        );
-        process.exit(2);
-      }
-      const r = spawnSync(process.execPath, [QDP, ...args], { stdio: 'inherit' });
-      if (r.error) {
-        process.stderr.write(`qdp failed to run: ${r.error.message}\n`);
-        process.exit(2);
-      }
-      process.exit(r.status ?? 2);
-    });
+  const discord = program
+    .command('discord')
+    .description('Quox Discord Pro daemon: status | instances | bindings | gaps | health | doctor | bind | unbind | provision')
+    .addHelpText('after', `\nPer-verb usage (each verb shells straight through to qdp):\n${GENERAL_USAGE}`);
+
+  for (const verb of DISCORD_READ_VERBS) {
+    discord
+      .command(verb)
+      .description(firstLine(verb) || verb)
+      .addHelpText('after', `\nqdp usage:\n  ${VERB_USAGE[verb]}`)
+      .action(() => runQdp(verb));
+  }
+
+  const writeArgs = { bind: '<channelId> <mode> [pairs...]', unbind: '<channelId>', provision: '<agentId> [args...]' };
+  for (const verb of DISCORD_WRITE_VERBS) {
+    const leaf = discord
+      .command(`${verb} ${writeArgs[verb]}`);
+    // Only provision has a dry run in qdp. Declaring it here keeps it in --help and lets the
+    // root guard refuse `discord bind|unbind --dry-run` instead of binding for real.
+    if (verb === 'provision') leaf.option('--dry-run', 'print exactly what it WOULD do, change nothing');
+    leaf
+      .description(firstLine(verb) || verb)
+      .addHelpText('after', `\nqdp usage:\n  ${VERB_USAGE[verb]}`)
+      // qdp parses its own options (provision --mode/--host/...), so they pass through unchanged.
+      .allowUnknownOption(true)
+      .action((...a) => {
+        const cmd = a[a.length - 1];
+        const args = [...cmd.args];
+        // --dry-run is also a root quox flag, so commander hands it to the root and it never reaches
+        // cmd.args: a requested dry run of provision used to provision for real. Forward it explicitly.
+        if (cmd.optsWithGlobals().dryRun && !args.includes('--dry-run')) args.push('--dry-run');
+        runQdp(verb, args);
+      });
+  }
 }