quoxcli 0.3.1 → 0.5.0

package/lib/commands/compliance.js

@@ -0,0 +1,109 @@
+/**
+ * Compliance commands: scheduled compliance report jobs.
+ *
+ * `compliance jobs list` calls GET /compliance/jobs (services/collector/server.js),
+ * the same route the compliance_list_jobs agent tool uses. Jobs can carry an
+ * optional name (set via the compliance_schedule_job tool / POST body `name`).
+ *
+ * `compliance reports list|show` read GET /compliance/reports and /compliance/reports/:id, the
+ * routes compliance_get_reports reads (org-scoped by the caller's session). The ORG column is
+ * always shown: a row with no org (org_id null) is printed as `none`, never hidden.
+ */
+
+import { formatOutput, formatDetail } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerComplianceCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const compliance = program
+    .command('compliance')
+    .description('Compliance: generated reports and scheduled report jobs');
+
+  const jobs = compliance
+    .command('jobs')
+    .description('Scheduled compliance report jobs');
+
+  jobs
+    .command('list')
+    .description('List scheduled compliance report jobs (with NAME)')
+    .option('--status <status>', 'filter by status (active|paused|error)')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('compliance.jobs.list');
+      const data = await client.get(ep.path, { service: ep.service, query: { org_id: orgId } });
+      let rows = data.jobs || [];
+      if (options.status) rows = rows.filter((j) => j.status === options.status);
+      formatOutput({
+        columns: ['id', 'name', 'format', 'schedule_interval', 'status', 'next_run'],
+        headers: ['ID', 'NAME', 'Format', 'Interval', 'Status', 'Next run'],
+        rows: rows.map((j) => ({ ...j, name: j.name || '-' })),
+      }, { format: program.opts().output, emptyMessage: 'No compliance jobs found.', raw: rows });
+    });
+
+  const reports = compliance
+    .command('reports')
+    .description('Generated compliance reports (read only)');
+
+  const scoreOf = (r) => (r.summary && typeof r.summary === 'object' && r.summary.overallScore != null ? r.summary.overallScore : '-');
+
+  reports
+    .command('list')
+    .description('List generated compliance reports: framework, period, score, sampled evidence, ORG')
+    .option('--format <format>', 'only this framework (soc2, hipaa, gdpr, iso27001, euAiAct, iso42001, nistAiRmf)')
+    .option('--limit <n>', 'max rows', '20')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('compliance.reports.list');
+      const query = { org_id: orgId, limit: String(options.limit || 20) };
+      if (options.format) query.format = options.format;
+      const data = await client.get(ep.path, { service: ep.service, query });
+      let rows = data.reports || [];
+      // the route does not filter by format, so the flag is applied here too
+      if (options.format) rows = rows.filter((r) => r.format === options.format);
+      formatOutput({
+        columns: ['id', 'format', 'generated_at', 'period_days', 'score', 'status', 'sample', 'org'],
+        headers: ['ID', 'Format', 'Generated', 'Days', 'Score', 'Status', 'Evidence sample', 'ORG'],
+        rows: rows.map((r) => ({
+          ...r,
+          period_days: r.period_days ?? '-',
+          score: scoreOf(r),
+          status: (r.summary && r.summary.overallStatus) || '-',
+          sample: (r.summary && Array.isArray(r.summary.evidenceSample) && r.summary.evidenceSample.length) ? r.summary.evidenceSample.join(' ') : '-',
+          org: r.org_id || 'none',
+        })),
+      }, { format: program.opts().output, emptyMessage: 'No compliance reports found.', raw: rows });
+    });
+
+  reports
+    .command('show <id>')
+    .description('Show one generated report: framework, period, score, per-control status, sampled evidence')
+    .action(async (id) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('compliance.reports.get', { id });
+      const data = await client.get(ep.path, { service: ep.service, query: { org_id: orgId } });
+      const r = data.report || data;
+      const fmt = program.opts().output;
+      if (fmt && fmt !== 'table') { formatDetail(r, { format: fmt }); return; }
+      const s = (r.summary && typeof r.summary === 'object') ? r.summary : {};
+      const body = (r.report_data && typeof r.report_data === 'object') ? r.report_data : {};
+      const lines = [
+        `Report     ${r.id}`,
+        `Framework  ${s.framework || body.framework || r.format}`,
+        `Org        ${r.org_id || 'none'}`,
+        `Period     ${r.period_start || '-'} .. ${r.period_end || '-'} (${r.period_days ?? '-'} days)`,
+        `Score      ${s.overallScore ?? body.overallScore ?? '-'}  status ${s.overallStatus || body.overallStatus || '-'}`,
+        `Evidence   ${Array.isArray(s.evidenceSample) && s.evidenceSample.length ? s.evidenceSample.join(' ') : '-'}`,
+      ];
+      const sections = body.sections && typeof body.sections === 'object' ? body.sections : {};
+      for (const [key, sec] of Object.entries(sections)) {
+        lines.push('', `${key}  ${sec && sec.name ? sec.name : ''}`.trimEnd());
+        for (const c of (sec && Array.isArray(sec.controls) ? sec.controls : [])) lines.push(`  ${String(c.id || '-').padEnd(10)} ${String(c.status || '-').padEnd(16)} ${c.name || ''}`);
+      }
+      for (const l of lines) console.log(l);
+    });
+}

package/lib/commands/connect.js

@@ -0,0 +1,69 @@
+/**
+ * quox connect <url>: point a profile at a QuoxCORE server on another machine and sign in (ONBOARD-P1).
+ *
+ * Probes <url>/health, and when the server answers with its own certificate shows its SHA256 fingerprint and,
+ * after a yes (--trust-cert, or the y/N), stores that certificate for THAT PROFILE ONLY. It is never the global
+ * NODE_EXTRA_CA_CERTS and TLS checks are never turned off. Then hands to `quox -p <profile> login`.
+ * One implementation with the TUI's /connect server (lib/quoxon/onboarding/connectServer.js).
+ */
+import { announce, announceOnFail } from '../core/announce.js';
+import { QuoxUserError } from '../core/errors.js';
+import { confirmInteractive } from '../core/confirm.js';
+import { profileNameForUrl } from '../core/profileTrust.js';
+import { loadConfig } from '../core/config.js';
+
+/** H1: no terminal and no pin: the safer non-interactive choice is the fingerprint pin, --trust-cert the alternative. */
+export const noTerminalTrustMessage = () => 'No terminal to answer y/N here. Read the certificate fingerprint above, then re-run with --fingerprint <sha256> to trust only that exact certificate (safer), or --trust-cert to trust whatever this server presents.';
+
+export function registerConnectCommand(program, ctx) {
+  program
+    .command('connect')
+    .description('Connect to a Quox server on another machine: probe it, trust its certificate for one profile, sign in')
+    .argument('<url>', 'the server address, for example https://192.0.2.10:3000')
+    .option('--profile <name>', 'profile to create or update (default: named from the address; -p also works)')
+    .option('--trust-cert', "trust the server's own certificate for this profile without asking (its fingerprint is still printed)")
+    .option('--fingerprint <sha256>', "trust the server's own certificate only if its SHA256 fingerprint is exactly this (colons optional); implies --trust-cert for that one certificate")
+    .option('--email <email>', 'sign in with this email without a prompt (use with --password-stdin to run with no terminal)')
+    .option('--password-stdin', 'read the password from stdin, one line (never an argument)')
+    .addHelpText('after', '\nA new QuoxCORE serves its own self-signed certificate. Compare the SHA256 printed here with the one `quox server status` shows on the server before you trust it. The certificate is stored for the one profile; TLS checks are never turned off.')
+    .action(announceOnFail('quox', (url) => `connect ${url}`, async (url, options, cmd) => {
+      const { connectServer } = await import('../quoxon/onboarding/connectServer.js');
+      const root = cmd.parent?.opts?.() || {};
+      const profile = options.profile || root.profile || profileNameForUrl(url);
+      // H1: the password comes from stdin only, never argv.
+      let password = null;
+      if (options.passwordStdin) {
+        const chunks = [];
+        for await (const chunk of process.stdin) chunks.push(chunk);
+        password = Buffer.concat(chunks).toString('utf8').split('\n')[0].replace(/\r$/, '');
+        if (!password) throw new QuoxUserError('--password-stdin given but stdin was empty. Pipe the password in, for example: printf %s "$PW" | quox connect <url> --email <email> --password-stdin', { exitCode: 2, code: 'empty_password' });
+      }
+      const email = options.email ? String(options.email).trim() : null;
+      const pin = options.fingerprint ? String(options.fingerprint).replace(/[:\s]/g, '').toUpperCase() : null;
+      const trust = async (card, peer) => {
+        if (pin) {
+          const got = String(peer?.chain?.[0]?.fingerprint256 || '').replace(/:/g, '').toUpperCase();
+          if (got === pin) return true;
+          throw new QuoxUserError(`The certificate ${url} presents has SHA256 ${peer?.chain?.[0]?.fingerprint256 || '(unreadable)'}, not the --fingerprint you gave. Nothing was saved.`, { exitCode: 2, code: 'fingerprint_mismatch' });
+        }
+        if (options.trustCert) return true;
+        if (!process.stdin.isTTY) throw new QuoxUserError(noTerminalTrustMessage(), { exitCode: 2, code: 'no_terminal' });
+        return confirmInteractive(`Trust this server's certificate for profile "${profile}" only?`, { flag: '--trust-cert', purpose: 'trust it' });
+      };
+      // loadConfig, not ctx.config: fresh each time, because the sign-in runs in a child process and writes the file.
+      // ctx.connectOverrides is for tests only.
+      const r = await connectServer(url, { profile, trust, email, password, loadConfigImpl: loadConfig, ...(ctx.connectOverrides || {}) });
+      if (r.action === 'connected') {
+        announce('quox', `connected ${url}`, { result: `profile ${profile}` });
+        console.log(`Connected as profile "${profile}". Use it with: quox -p ${profile} <command>. Make it your default with: quox config profile use ${profile}`);
+        return;
+      }
+      // H1: no terminal and no way to sign in: say which flags are missing, exit 2 (not 130, which means "cancelled").
+      const missing = [!email && '--email <email>', !password && '--password-stdin'].filter(Boolean);
+      if (!process.stdin.isTTY && missing.length && r.action !== 'connected') {
+        throw new QuoxUserError(`No terminal to sign in with. Re-run with ${missing.join(' and ')}; nothing was left saved.`, { exitCode: 2, code: 'no_terminal' });
+      }
+      if (r.action === 'connect-cancelled') { announce('quox', `connect ${url}`, { result: 'cancelled', status: 'warn' }); process.exitCode = 130; return; }
+      throw new QuoxUserError(`Could not connect to ${url}. See the message above; nothing was left saved.`, { exitCode: 1, code: 'connect_failed' });
+    }));
+}

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);
@@ -109,12 +112,15 @@ export function registerContactsCommands(program, ctx) {
     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
@@ -186,9 +192,10 @@ export function registerContactsCommands(program, ctx) {
     .command('list')
     .description('List contacts')
     .option('--q <text>', 'name filter')
-    .option('--status <s>', 'active | candidate | archived')
+    .option('--status <s>', 'active | candidate | archived | all (default: everyone except archived)')
     .option('--relationship <r>', 'primary relationship, e.g. customer | supplier | partner')
-    .option('--limit <n>', 'max contacts')
+    .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
@@ -480,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 };
@@ -495,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/dev.js

@@ -325,14 +325,12 @@ export function registerDevCommands(program, ctx) {
       printInfo(`Terms hash: ${offer.termsSha256} (presentation ${offer.presentationVersion})`);
 
       if (!options.iAccept) {
-        const { default: inquirer } = await import('inquirer');
-        const ans = await inquirer.prompt([{
-          type: 'confirm',
-          name: 'confirm',
-          message: `Do you accept these terms, on behalf of your organisation, for exactly this pack content?`,
-          default: false,
-        }]);
-        if (!ans.confirm) {
+        const { confirmInteractive } = await import('../core/confirm.js');
+        const accepted = await confirmInteractive(
+          `Do you accept these terms, on behalf of your organisation, for exactly this pack content?`,
+          { flag: '--i-accept', purpose: 'accept them as yourself' },
+        );
+        if (!accepted) {
           printInfo('Not accepted. Nothing was recorded.');
           return;
         }

package/lib/commands/doctor.js

@@ -8,6 +8,9 @@
  */
 
 import chalk from 'chalk';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { SERVICE_PORTS } from '../core/config.js';
 import { emitCliEvent } from '../core/aee.js';
 import { resolveCliVersion, checkCliDrift } from '../core/version.js';
@@ -20,7 +23,7 @@ const CHECKS = [
   { name: 'QuoxFlow', service: 'quoxflow', port: 3200, path: '/health' },
   { name: 'Files service', service: 'files', port: 3102, path: '/health' },
   // External services
-  { name: 'QuoxAgent daemon', port: 9847, path: '/health', url: 'http://localhost:9847' },
+  { name: 'QuoxAgent daemon', port: 9847, path: '/health', url: 'http://localhost:9847', optionalUnlessEnrolled: true },
   { name: 'Qdrant vectors', port: 6333, path: '/', url: 'http://localhost:6333' },
 ];
 
@@ -40,11 +43,20 @@ async function checkEndpoint(url, path, timeoutMs = 3000) {
   }
 }
 
+/**
+ * F2 (ONBOARD-P1): is a QuoxAgent installed/enrolled on THIS machine? Its config is the evidence: the system
+ * install writes /etc/quoxagent/quoxagent.yaml, a user install ~/.quoxagent/. Absent both, nothing is enrolled
+ * and a daemon that is not running is the normal state of a single-box install, not a critical.
+ */
+export function defaultAgentEnrolled({ exists = existsSync, home = homedir() } = {}) {
+  return ['/etc/quoxagent/quoxagent.yaml', join(home, '.quoxagent', 'quoxagent.yaml'), join(home, '.quoxagent', 'config.yaml')].some((p) => exists(p));
+}
+
 /**
  * Every doctor check, in this process: services, auth token, CLI version. Shared by `quox doctor` and the
  * conversation's /doctor so the two can never disagree. -> [{ name, status, detail?, latency_ms?, ... }].
  */
-export async function runDoctorChecks({ config }) {
+export async function runDoctorChecks({ config, agentEnrolled = defaultAgentEnrolled } = {}) {
   // Check all services in parallel — per-item try/catch so one failure doesn't lose all results
   const checks = await Promise.all(
     CHECKS.map(async (check) => {
@@ -71,6 +83,9 @@ export async function runDoctorChecks({ config }) {
             }
           }
         }
+        if (result.status === 'fail' && check.optionalUnlessEnrolled && !agentEnrolled()) {
+          result = { status: 'skip', latency_ms: null, detail: 'optional: not running, and no QuoxAgent is enrolled on this machine (install one with the fleet enrol steps if you want a fleet)' };
+        }
         return {
           name: check.name,
           port: check.port,
@@ -130,6 +145,7 @@ export function registerDoctorCommand(program, ctx) {
   program
     .command('doctor')
     .description('Run platform health diagnostics')
+    .addHelpText('after', '\nAdd --json for machine output: { checks: [...], summary: { passed, warnings, failed } }.')
     .action(async (opts, cmd) => {
       const outputFormat = cmd.parent?.opts()?.output || 'table';
       const isJson = outputFormat === 'json' || cmd.parent?.opts()?.json;
@@ -140,9 +156,10 @@ export function registerDoctorCommand(program, ctx) {
       const passed = checks.filter(c => c.status === 'pass').length;
       const warnings = checks.filter(c => c.status === 'warn').length;
       const failed = checks.filter(c => c.status === 'fail').length;
+      const skipped = checks.filter(c => c.status === 'skip').length;
 
       if (isJson) {
-        console.log(JSON.stringify({ checks, summary: { passed, warnings, failed } }, null, 2));
+        console.log(JSON.stringify({ checks, summary: { passed, warnings, failed, skipped } }, null, 2));
         return;
       }
 
@@ -151,6 +168,7 @@ export function registerDoctorCommand(program, ctx) {
       for (const c of checks) {
         const icon = c.status === 'pass' ? chalk.green(' ✓')
           : c.status === 'warn' ? chalk.yellow(' ⚠')
+          : c.status === 'skip' ? chalk.dim(' ·')
           : chalk.red(' ✗');
 
         const latency = c.latency_ms != null ? chalk.dim(` (${c.latency_ms}ms)`) : '';
@@ -165,6 +183,7 @@ export function registerDoctorCommand(program, ctx) {
       if (passed) parts.push(chalk.green(`${passed} passed`));
       if (warnings) parts.push(chalk.yellow(`${warnings} warning${warnings > 1 ? 's' : ''}`));
       if (failed) parts.push(chalk.red(`${failed} critical`));
+      if (skipped) parts.push(chalk.dim(`${skipped} optional, not set up`));
       console.log(` ${parts.join('  ')}`);
       console.log('');
 

package/lib/commands/engagement.js

@@ -4,6 +4,7 @@
  * quox engagement create <name> --environment-tier <tier> [--risk-ceiling <tier>]
  * quox engagement list
  * quox engagement show <id>
+ * quox engagement verify <id>
  * quox engagement add-target <id> <type> <value> [--verification-method <method>]
  * quox engagement verify-target <id> <targetId>
  *
@@ -20,6 +21,7 @@ import { writeFileSync } from 'node:fs';
 import { formatOutput, formatDetail, printSuccess, printInfo } from '../core/output.js';
 import { events, printEvent, line as glyphLine } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { gatherEvidence, evidenceChanged } from '../core/findingReconcile.js';
 
 export function registerEngagementCommands(program, ctx) {
   const { client, auth } = ctx;
@@ -80,6 +82,31 @@ export function registerEngagementCommands(program, ctx) {
       }, { format: program.opts().output, emptyMessage: 'No targets added yet.' });
     });
 
+  engagement
+    .command('verify <id>')
+    .description('Verify the WARD witness for an engagement (recompute receipt + Ed25519 tip signature)')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('engagement.verify', { id });
+      const data = await client.get(ep.path, { service: ep.service });
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      const ok = data.pass === true;
+      console.log(ok ? '✓ WITNESS VERIFIED' : '✗ NOT VERIFIED');
+      console.log(`  engagement   ${data.engagement_id || id}`);
+      console.log(`  witnessed    ${data.witnessed ? 'yes' : 'no'}`);
+      console.log(`  chain        ${data.chainId || '-'}`);
+      if (data.seq != null) console.log(`  entry        #${data.seq}`);
+      if (data.chainHash) console.log(`  chain hash   ${String(data.chainHash).slice(0, 40)}`);
+      console.log(`  chain recompute  ${data.chainHashRecomputed ? 'ok' : 'FAILED'}`);
+      const sig = data.signature || {};
+      console.log(`  tip signature    ${sig.status}${sig.keyId ? ` (key ${String(sig.keyId).slice(0, 16)})` : ''}`);
+      if (data.signedTip && data.signedTip.tipId) console.log(`  signed tip   ${data.signedTip.tipId} (seq ${data.signedTip.tipSeq})`);
+      if (!ok && data.reason) console.log(`  reason       ${data.reason}`);
+    });
+
   engagement
     .command('set-gripe-target <id>')
     .description('Set which repo a finding filed from this engagement goes to, and which org GitHub connector token files it. Lets a customer-site engagement file into the customer repo with the customer org token. Pass --clear (or --repo "") to fall back to the platform default (quoxai/quox) and the engagement own org.')
@@ -575,6 +602,69 @@ export function registerEngagementCommands(program, ctx) {
       printSuccess(`Schedule "${scheduleId}" deleted.`);
     });
 
+  // SITREP-FINDINGS: reconcile open findings against their issue and fix. Evidence is gathered
+  // here (git + gh on this host); the collector decides and keeps the audit trail. Resolves only
+  // on a closed issue AND a fix in the running build; a critical is never auto-resolved.
+  engagement
+    .command('reconcile [findingId]')
+    .description('Reconcile open findings against their linked issue and fix commit (landed on main, deployed in the running build). Resolves only when the issue is closed AND the fix is deployed; a critical never auto-resolves. Every change is audited')
+    .option('--link <ref...>', 'link evidence: <findingId>=<owner/repo#N | #N | commit-sha> (repeatable)')
+    .option('--repo-dir <dir>', 'git checkout to read origin/main from (default: ~/quox-dashboard)')
+    .option('--build-dir <dir>', 'the tree the running build was built from (default: ~/.quox-build/quox-dashboard)')
+    .option('--issue-repo <owner/repo>', 'repo a bare #N refers to', 'quoxai/quox')
+    .option('--no-fetch', 'do not fetch origin/main first')
+    .option('--dry-run', 'show the evidence without recording anything')
+    .action(async (findingId, options) => {
+      auth.requireAuth();
+      const { spawnSync } = await import('node:child_process');
+      const run = (cmd, args) => {
+        const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: 30000 });
+        return { ok: r.status === 0, out: String(r.stdout || '') };
+      };
+      const home = (await import('node:os')).homedir();
+      options.repoDir = options.repoDir || `${home}/quox-dashboard`;
+      options.buildDir = options.buildDir || `${home}/.quox-build/quox-dashboard`;
+      const links = {};
+      for (const l of options.link || []) {
+        const m = /^(FND_[0-9A-Z]+)=(.+)$/.exec(String(l));
+        if (!m) throw new Error(`--link must look like FND_...=<issue or sha>, got "${l}"`);
+        const v = m[2].trim();
+        links[m[1]] = { ...(links[m[1]] || {}), ...(/^[0-9a-f]{7,40}$/i.test(v) ? { commit: v } : { issue: v }) };
+      }
+      if (options.fetch !== false) run('git', ['-C', options.repoDir, 'fetch', '--quiet', 'origin', 'main']);
+      const ep = resolveEndpoint('engagement.findings.open', {});
+      const all = (await client.get(ep.path, { service: ep.service })).findings || [];
+      const findings = findingId ? all.filter((f) => f.id === findingId) : all;
+      if (findingId && !findings.length) throw new Error(`Finding "${findingId}" is not open in this org`);
+      const rows = [];
+      for (const f of findings) {
+        const ev = gatherEvidence(f, links[f.id] || {}, { repoDir: options.repoDir, buildDir: options.buildDir, issueRepo: options.issueRepo, run });
+        const row = { id: f.id, severity: f.severity, status: f.status, issue: ev.issue_ref ? `${ev.issue_ref}${ev.issue_state ? ` (${ev.issue_state})` : ''}` : '',
+          fix: ev.fix_commit ? `${ev.fix_commit.slice(0, 9)} ${ev.fix_state}` : '', outcome: '' };
+        if (!Object.keys(ev).length) { row.outcome = 'no evidence'; rows.push(row); continue; }
+        if (!evidenceChanged(f, ev)) { row.outcome = 'unchanged'; rows.push(row); continue; }
+        if (options.dryRun) { row.outcome = 'would record'; rows.push(row); continue; }
+        const rep = resolveEndpoint('engagement.findings.reconcile', { findingId: f.id });
+        const data = await client.post(rep.path, { service: rep.service, body: ev });
+        row.outcome = `${data.outcome}: ${data.reason}`;
+        row.status = data.finding?.status || row.status;
+        rows.push(row);
+      }
+      formatOutput({ columns: ['id', 'severity', 'status', 'issue', 'fix', 'outcome'], headers: ['Finding', 'Severity', 'Status', 'Issue', 'Fix', 'Outcome'], rows },
+        { format: program.opts().output, emptyMessage: 'No open findings.' });
+    });
+
+  engagement
+    .command('reconciliations <findingId>')
+    .description('Show the reconciliation audit trail of one finding (what evidence was recorded, when, by whom, and the outcome)')
+    .action(async (findingId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('engagement.findings.reconciliations', { findingId });
+      const data = await client.get(ep.path, { service: ep.service });
+      formatOutput({ columns: ['created_at', 'outcome', 'reason', 'actor', 'evidence'], headers: ['When', 'Outcome', 'Reason', 'Actor', 'Evidence'], rows: data.reconciliations || [] },
+        { format: program.opts().output, emptyMessage: 'No reconciliations recorded.' });
+    });
+
   engagement
     .command('sync-issues <id>')
     .description('Reconcile this engagement\'s filed findings against their GitHub issue state. A closed issue auto-resolves its finding. Honest no-op if GitHub is not configured')