quoxcli 0.2.0 → 0.4.0

package/lib/commands/chatCompanion.js

@@ -0,0 +1,27 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** Explicit local opt-in only. A display failure must not interrupt a chat. */
+export async function loadChatCompanion(path, { output = process.stdout, warn = console.error, display = {} } = {}) {
+  if (!path || !output.isTTY) return null;
+  try {
+    const mod = await import(pathToFileURL(resolve(path)).href);
+    const c = await mod.createCompanion({ output, ...display });
+    if (!c || !['event', 'write', 'close', 'suspend'].every(k => typeof c[k] === 'function')) {
+      try { c?.close?.(); } catch {}
+      throw new Error('Expected createCompanion() with event/write/close/suspend');
+    }
+    let active = true;
+    const stop = async () => { active = false; try { await c.close(); } catch {} };
+    return {
+      event(e) { if (active) try { c.event(e); } catch { stop(); } },
+      write(text) { if (!active) output.write(text); else c.write(text); },
+      // Trace writes to stderr: relinquish the block first to prevent overlap.
+      suspend() { if (active) try { c.suspend(); } catch { stop(); } },
+      close: stop,
+    };
+  } catch (e) {
+    warn('Dragon companion unavailable; continuing normal chat: ' + e.message);
+    return null;
+  }
+}

package/lib/commands/chatState.js

@@ -0,0 +1,45 @@
+/**
+ * Last conversation per (profile, cwd), so `quox chat --continue` keeps context without the user
+ * copying a session id. Best-effort: a read/write failure never breaks a chat turn.
+ */
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, readlinkSync } from 'node:fs';
+
+const stateFile = () => process.env.QUOX_CHAT_STATE || join(homedir(), '.config', 'quox', 'chat-last.json');
+/**
+ * Who is calling: $QUOX_SESSION when set, else this terminal's tty, else nothing (a headless
+ * caller with no session id falls back to profile + cwd only). Parallel terminals/sessions must
+ * never share a "last conversation".
+ */
+export function callerScope(env = process.env) {
+  if (env.QUOX_SESSION) return `session:${String(env.QUOX_SESSION).slice(0, 64)}`;
+  for (const fd of [0, 1, 2]) {
+    try {
+      const t = readlinkSync(`/proc/self/fd/${fd}`);
+      if (/^\/dev\/(pts\/\d+|tty\w*)$/.test(t)) return `tty:${t}`;
+    } catch { /* not linux, or fd closed */ }
+  }
+  return '';
+}
+const keyOf = (profile, cwd) => `${profile || 'default'}|${cwd || process.cwd()}|${callerScope()}`;
+
+function read() {
+  try { return JSON.parse(readFileSync(stateFile(), 'utf8')) || {}; } catch { return {}; }
+}
+
+export function lastConversation(profile, cwd) {
+  const v = read()[keyOf(profile, cwd)];
+  return typeof v === 'string' && v ? v : undefined;
+}
+
+export function saveLastConversation(profile, cwd, id) {
+  if (!id) return;
+  try {
+    const all = read();
+    all[keyOf(profile, cwd)] = id;
+    const f = stateFile();
+    mkdirSync(dirname(f), { recursive: true });
+    writeFileSync(f, JSON.stringify(all, null, 2));
+  } catch { /* best-effort */ }
+}

package/lib/commands/claude.js

@@ -1,8 +1,9 @@
 /**
- * quox claude / codex / gemini / run / sessions: governed tmux sessions. The runner
+ * quox claude / codex / run / sessions: governed tmux sessions. The runner
  * 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';
@@ -101,22 +102,6 @@ export const runClaude = ({ as, slot, ...opts } = {}, over) => gs.runGoverned({
   program: 'claude',
   ...(as || slot ? { preattach: { agent: as, slot, session: opts.name } } : {}),
 }, over);
-/**
- * quox gemini <args>: verbatim to `gemini`. Gemini resumes by index or
- * "latest" (`--resume latest`, `-r 5`), not by name, so the tmux session is
- * auto-named; reattach with `quox sessions attach NAME`.
- */
-export function parseGeminiArgs(raw) {
-  let noTmux = false;
-  const args = [];
-  for (const a of raw) {
-    if (a === '--no-tmux') noTmux = true;
-    else args.push(a);
-  }
-  const resume = args.some((a) => a === '--resume' || a === '-r' || a.startsWith('--resume='));
-  return { args, name: undefined, resume, noTmux };
-}
-
 /**
  * quox wrap <program> [args...]: wrap ANY command. Known programs use their
  * registry entry (so `quox wrap codex` == `quox codex`); unknown ones get the
@@ -134,12 +119,11 @@ export function parseRunArgs(raw) {
 }
 
 export function runRun({ bin, args = [], noTmux = false } = {}, over) {
-  const known = ['claude', 'codex', 'gemini'].find((k) => PROGRAMS[k].bin === bin);
+  const known = ['claude', 'codex'].find((k) => PROGRAMS[k].bin === bin);
   if (known) return gs.runGoverned({ program: known, args, noTmux }, over);
   return gs.runGoverned({ program: 'run', bin, args, noTmux }, over);
 }
 
-export const runGemini = (opts, over) => gs.runGoverned({ ...opts, program: 'gemini' }, over);
 export const runCodex = (opts, over) => gs.runGoverned({ ...opts, program: 'codex' }, over);
 export const runTui = (opts, over) => gs.runGoverned({ ...opts, program: 'tui' }, over);
 export const runHelp = gs.runHelp;
@@ -178,8 +162,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 +189,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,20 +202,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')
-    .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)
-    .allowUnknownOption()
-    .allowExcessArguments()
-    .action((_a, _o, cmd) => {
-      const raw = (cmd.parent && cmd.parent.rawArgs) || process.argv;
-      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,10 +242,35 @@ 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')
-    .option('--backend <program>', 'claude, codex, gemini, ...')
+    .option('--backend <program>', 'claude, codex, ...')
     .option('--agent <agent>', 'agent the session started attached to (--as)')
     .option('--slot <slot>', 'slot the session started holding (--slot)')
     .action(async (name, o) => {

package/lib/commands/contacts.js

@@ -14,6 +14,7 @@ import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { runSelftest } from './contactsSelftest.js';
 import { resolveOrgId } from './helpers.js';
+import { atToSendAt } from './contactsSendAt.js';
 
 const KINDS = ['person', 'organisation'];
 const REASONS = ['dnc', 'do_not_market', 'bounced'];
@@ -38,6 +39,8 @@ async function call(fn, { forbidden } = {}) {
     return await fn();
   } catch (e) {
     if (e instanceof QuoxApiError) {
+      // A refusal that says why (scheduled/immediate send) is shown as said, never swapped for a generic line.
+      if ((e.status === 403 || e.status === 409) && e.body && typeof e.body.reason === 'string' && e.body.reason) throw new QuoxError(e.body.reason, 1);
       if (e.status === 403 && forbidden) throw new QuoxError(forbidden, 1);
       if (e.status === 404 && e.body && e.body.error === 'tombstone_not_found') {
         throw new QuoxError('No erasure tombstone exists for that identifier in this org.', 1);
@@ -107,13 +110,17 @@ 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);
+    if (options.offset !== undefined) query.offset = Number(options.offset);
     const ep = resolveEndpoint('contactsq.contacts.list');
     const data = await call(() => client.get(ep.path, { service: ep.service, query }));
     if (isJson(program)) return printJson(data);
     const rows = (data.contacts || []).map(cardRow);
     formatOutput({ columns: CARD_COLS, headers: CARD_HEADS, rows }, { format: program.opts().output });
-    announce('contacts list', `${rows.length} contacts`);
+    const total = Number.isInteger(data.total) ? data.total : rows.length;
+    const next = (data.offset || 0) + rows.length;
+    announce('contacts list', next < total ? `${rows.length} of ${total} contacts, next: --offset ${next}` : `${rows.length} of ${total} contacts`);
   };
 
   addNameOptions(contacts
@@ -185,8 +192,10 @@ export function registerContactsCommands(program, ctx) {
     .command('list')
     .description('List contacts')
     .option('--q <text>', 'name filter')
-    .option('--status <s>', 'active | candidate | archived')
-    .option('--limit <n>', 'max contacts')
+    .option('--status <s>', 'active | candidate | archived | all (default: everyone except archived)')
+    .option('--relationship <r>', 'primary relationship, e.g. customer | supplier | partner')
+    .option('--limit <n>', 'page size (default 25, max 100)')
+    .option('--offset <n>', 'skip this many (paging: the footer prints the next --offset)')
     .action((options) => list(options));
 
   contacts
@@ -373,6 +382,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')
@@ -431,7 +487,7 @@ export function registerContactsCommands(program, ctx) {
     .description('Dial a contact by id through the phone bridge; you never see or type the number')
     .argument('<id>', 'contact id (find it with `quox contacts search`)')
     .option('--reason <text>', 'what the call is about (the agent opens with it)')
-    .option('--purpose <p>', 'service | transactional | marketing | research', 'service')
+    .option('--purpose <p>', 'service | transactional | marketing | research | personal', 'service')
     .action(async (id, options) => {
       auth.requireAuth();
       const body = { contact_id: id, projection: 'dial', channel: 'voice', purpose: options.purpose };
@@ -446,6 +502,80 @@ export function registerContactsCommands(program, ctx) {
       announce('contacts call', `${l.id || '?'} queued for the phone bridge`);
     });
 
+  // ---- send: SMS or email now or at a time (the server delivers; you approve by running it) ----
+  const DEFAULT_TZ = 'Europe/London';
+  async function resolveContactArg(arg) {
+    if (/^ct_[a-z0-9_]+$/i.test(arg)) return arg;
+    const ep = resolveEndpoint('contactsq.search');
+    const data = await call(() => client.get(ep.path, { service: ep.service, query: { q: arg } }));
+    const c = data.candidates || [];
+    if (!c.length) throw new QuoxError(`No contact matches "${arg}". Try \`quox contacts search\`.`, 1);
+    if (data.ambiguous || c.length > 1) {
+      throw new QuoxError(`"${arg}" matches more than one contact (${c.slice(0, 5).map((x) => `${x.display_name} ${x.id}`).join('; ')}). Pass the contact id.`, 1);
+    }
+    return c[0].id;
+  }
+
+  contacts
+    .command('send')
+    .description('Send an SMS or email to a contact now, or at a time with --at (the server delivers it; the answer says exactly when)')
+    .argument('<contact>', 'contact id (ct_...) or an unambiguous name')
+    .argument('<text>', 'the message')
+    .option('--channel <c>', 'sms | email', 'sms')
+    .option('--at <time>', 'send later: ISO time with offset, or a clock time like 10am / 14:30 (next occurrence, in --tz)')
+    .option('--tz <zone>', 'IANA zone for --at', DEFAULT_TZ)
+    .option('--title <t>', 'subject (email)')
+    .option('--purpose <p>', 'service | transactional | marketing | research | personal', 'service')
+    .option('--reason <text>', 'why (recorded as a hash only)')
+    .action(async (contactArg, text, options) => {
+      auth.requireAuth();
+      checkEnum(options.channel, ['sms', 'email'], '--channel');
+      checkEnum(options.purpose, ['service', 'transactional', 'marketing', 'research', 'personal'], '--purpose');
+      const contactId = await resolveContactArg(contactArg);
+      const body = { contact_id: contactId, channel: options.channel, message: text, purpose: options.purpose };
+      if (options.title) body.title = options.title;
+      if (options.reason) body.reason = options.reason;
+      if (options.at) { body.send_at = atToSendAt(options.at, options.tz); body.timezone = options.tz; }
+      const ep = resolveEndpoint('contactsq.sends.create');
+      const data = await call(() => client.post(ep.path, { service: ep.service, body, retries: 0 }), {
+        forbidden: 'Blocked by contact policy, or you are not a human user. Run `quox contacts best-channel <id>` to see why.',
+      });
+      if (isJson(program)) return printJson(data);
+      if (data.job) {
+        formatDetail({ job: data.job.id, status: data.job.status, channel: data.job.channel, when: data.job.when, send_at: data.job.send_at });
+        return announce('contacts send', `scheduled ${data.job.id}: ${data.job.when}`);
+      }
+      if (data.status === 'sent') { formatDetail({ lease: data.lease_id, status: 'sent' }); return announce('contacts send', `${options.channel} sent`); }
+      formatDetail({ lease: data.lease_id, status: data.status, error: data.error, reason: data.reason });
+      announce('contacts send', `FAILED: ${data.reason || data.error}`);
+      process.exitCode = 1;
+    });
+
+  const scheduled = contacts.command('scheduled').description('Scheduled sends: what is queued, and cancel one before it goes out');
+  scheduled
+    .command('list')
+    .option('--status <s>', 'comma list of pending,sending,sent,failed,cancelled (default pending,sending)')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('contactsq.sends.scheduled');
+      const data = await call(() => client.get(ep.path, { service: ep.service, query: options.status ? { status: options.status } : {} }), { forbidden: 'Scheduled sends are for human users.' });
+      if (isJson(program)) return printJson(data);
+      const rows = (data.jobs || []).map((j) => ({ id: j.id, contact: j.contact_id, channel: j.channel, status: j.status, when: j.when || j.finished_at || '', outcome: j.outcome_reason || j.outcome_code || '' }));
+      formatOutput({ columns: ['id', 'contact', 'channel', 'status', 'when', 'outcome'], rows }, { format: program.opts().output });
+      announce('contacts scheduled list', `${rows.length} jobs`);
+    });
+  scheduled
+    .command('cancel')
+    .argument('<id>', 'scheduled send id (ss_...)')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('contactsq.sends.cancel', { id });
+      const data = await call(() => client.post(ep.path, { service: ep.service, body: {} }), { forbidden: 'Cancelling a scheduled send is for human users.' });
+      if (isJson(program)) return printJson(data);
+      formatDetail({ job: data.job.id, status: data.job.status });
+      announce('contacts scheduled cancel', data.job.id);
+    });
+
   contacts
     .command('leases')
     .description('Lease + use ledger for a contact (who was given access, when, why; never the values)')

package/lib/commands/contactsSendAt.js

@@ -0,0 +1,21 @@
+import { QuoxError } from '../core/errors.js';
+
+/** "10am", "10:30", "22:15" -> the next such wall-clock time in tz as a bare local ISO the server reads in that zone. ISO input passes through. */
+export function atToSendAt(at, tz, nowMs = Date.now()) {
+  const raw = String(at).trim();
+  if (/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(raw) || /(?:Z|[+-]\d{2}:?\d{2})$/i.test(raw)) return raw;
+  const m = /^(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/i.exec(raw);
+  if (!m) throw new QuoxError(`--at must be an ISO time (2026-10-25T10:00:00+00:00) or a clock time such as 10am or 14:30, got "${raw}"`, 2);
+  let h = Number(m[1]);
+  const mi = Number(m[2] || 0);
+  if (m[3]) { if (h < 1 || h > 12) throw new QuoxError('--at hour must be 1 to 12 with am/pm', 2); h = (h % 12) + (m[3].toLowerCase() === 'pm' ? 12 : 0); }
+  if (h > 23 || mi > 59) throw new QuoxError('--at is not a valid clock time', 2);
+  const parts = (ms) => Object.fromEntries(new Intl.DateTimeFormat('en-GB', { timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' }).formatToParts(new Date(ms)).map((p) => [p.type, p.value]));
+  const n = parts(nowMs);
+  const pad = (v) => String(v).padStart(2, '0');
+  let day = Date.UTC(Number(n.year), Number(n.month) - 1, Number(n.day));
+  if (h * 60 + mi <= Number(n.hour) * 60 + Number(n.minute)) day += 86400000; // already passed today: tomorrow
+  const d = new Date(day);
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}T${pad(h)}:${pad(mi)}`;
+}
+

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) {