quoxcli 0.4.0 → 0.5.0

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/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/evidence.js

@@ -53,7 +53,8 @@ export function registerEvidenceCommands(program, ctx) {
 
   evidence
     .command('status')
-    .description('Evidence stores (AEE, WARD, VOLT): size, rows, time span, growth, archive and backup, read-only')
+    .description('Evidence stores (AEE, WARD, VOLT): size, rows, time span, growth, archive and backup, read-only. Instance admin only')
+    .addHelpText('after', '\nInstance admin only: an org owner or admin who is not an instance admin gets a 403 (exit 4).')
     .action(async () => {
       auth.requireAuth();
       const ep = resolveEndpoint('evidence.status');

package/lib/commands/gripe.js

@@ -22,7 +22,7 @@
  */
 
 import { formatDetail, printInfo, printWarning } from '../core/output.js';
-import { events, line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { events, gripeFiledLine, line as glyphLine, printEvent } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { resolveOrgId } from './helpers.js';
 
@@ -50,20 +50,28 @@ export function registerGripeCommands(program, { client, auth }) {
         return;
       }
       printEvent(glyphLine('quox', 'filing gripe via GRIPE'));
-      const data = await askGripe({ client, complaint, repo: options.repo, label: options.label, yes: !!options.yes, orgId });
-
-      if (program.opts().output === 'json') {
-        formatDetail(data, { format: 'json' });
-        return;
-      }
-
-      const r = await settleGripe({ client, data, complaint, options, orgId });
+      // GRIPE-QUEUE: a timeout / network / 5xx saves the gripe locally instead of losing it (/gripes in quox lists it).
+      const { gripeQueue, fileOrQueue } = await import('../quoxon/gripeQueue.js');
+      let rawData = null;
+      const f = await fileOrQueue({
+        text: complaint, repo: options.repo || null, queue: gripeQueue(), queueable: !!options.yes,
+        run: async (key) => {
+          const o = { ...options, idempotencyKey: key, queueRetryable: true };
+          rawData = await askGripe({ client, complaint, repo: options.repo, label: options.label, yes: !!options.yes, orgId });
+          if (program.opts().output === 'json') return { json: true };
+          return settleGripe({ client, data: rawData, complaint, options: o, orgId });
+        },
+      });
+      if (!f.ok && f.queued) { printWarning(`${f.saved} (${f.message})`); process.exitCode = 1; return; }
+      if (!f.ok) throw new Error(f.message);
+      if (f.json) { formatDetail(rawData, { format: 'json' }); return; }
+      const r = f;
       console.log('');
       if (r.superseded) printInfo(SUPERSEDED_MESSAGE);
       else console.log(r.response || '(no response)');
       console.log('');
       for (const n of r.notes) {
-        if (n.kind === 'created') printEvent(events.created('quox', 'issue', n.url));
+        if (n.kind === 'created') { printEvent(gripeFiledLine(n.url, complaint)); console.log(n.url); }
         else if (n.kind === 'info') printInfo(n.text);
         else printWarning(n.text);
       }
@@ -117,7 +125,7 @@ export async function settleGripe({ client, data, complaint, options = {}, orgId
   const notes = [];
   let url = null;
   const det = async () => {
-    const r = await fileDeterministically({ client, complaint, options, orgId, quiet: true });
+    const r = await fileDeterministically({ client, complaint, options, orgId, quiet: true, throwRetryable: !!options.queueRetryable });
     notes.push(...r.notes); if (r.url) url = r.url;
     return r;
   };
@@ -181,7 +189,7 @@ async function promptConfirmPublic(repo) {
   } finally { rl.close(); }
 }
 
-export async function fileDeterministically({ client, complaint, options, orgId, quiet = false, confirmPublic = null }) {
+export async function fileDeterministically({ client, complaint, options, orgId, quiet = false, confirmPublic = null, throwRetryable = false }) {
   const notes = [];
   const say = (n) => { notes.push(n); if (quiet) return; if (n.kind === 'created') printEvent(events.created('quox', 'issue', n.url)); else if (n.kind === 'info') printInfo(n.text); else printWarning(n.text); };
   const repoArg = options.repo || 'quoxai/quox';
@@ -201,9 +209,10 @@ export async function fileDeterministically({ client, complaint, options, orgId,
         owner,
         repo,
         title,
-        body: `## Gripe\n${complaint}\n\n## Context\n- Filed deterministically by \`quox gripe --yes\` (the GRIPE agent run did not file; quox#478 guarantee path)\n- Priority: minor / off-task observation\n\n## Suggested Action\nInvestigate and fix if confirmed.`,
+        body: `${options.idempotencyKey ? `<!-- quox-gripe-key: ${options.idempotencyKey} -->\n` : ''}## Gripe\n${complaint}\n\n## Context\n- Filed deterministically by \`quox gripe --yes\` (the GRIPE agent run did not file; quox#478 guarantee path)\n- Priority: minor / off-task observation\n\n## Suggested Action\nInvestigate and fix if confirmed.`,
         labels: [options.label || 'fleet/qa'],
         ...(orgId ? { org_id: orgId } : {}),
+        ...(options.idempotencyKey ? { idempotency_key: options.idempotencyKey } : {}),
         ...(confirmed ? { confirm_public: true } : {}),
       },
     });
@@ -216,6 +225,8 @@ export async function fileDeterministically({ client, complaint, options, orgId,
     say({ kind: 'warn', text: 'Deterministic file returned no issue URL; treat as NOT filed until you can see the issue.' });
     return { filed: false, notes };
   } catch (err) {
+    // GRIPE-QUEUE: a timeout / network / 5xx is "Quox did not answer", not a refusal; the caller queues it.
+    if (throwRetryable && (err?.status == null || Number(err.status) >= 500)) throw err;
     say({ kind: 'warn', text: `Not filed: the GRIPE run did not file and the deterministic fallback failed too (${err.message}).` });
     return { filed: false, error: err.message, notes };
   }

package/lib/commands/inbox.js

@@ -9,6 +9,8 @@ import { attachWalkthrough } from './walkthrough.js';
 import { getApprovalContext, formatApprovalContext, approvalListColumns } from '../core/approvalContext.js';
 import { QuoxUserError } from '../core/errors.js';
 import { resolutionFromItem, alreadyResolvedError } from '../core/inboxResolution.js';
+import { withStepUp } from '../core/stepUpPrompt.js';
+import { announce, announceFailure } from '../core/announce.js';
 import chalk from 'chalk';
 
 export function registerInboxCommands(program, ctx) {
@@ -55,7 +57,7 @@ export function registerInboxCommands(program, ctx) {
   inbox
     .command('list')
     .description('List inbox items')
-    .option('--status <status>', 'filter: one status, a comma list (resolved,cancelled,expired), or all (includes answered approvals). Default: active only')
+    .option('--status <status>', 'filter: one status, a comma list (resolved,cancelled,expired,withdrawn), or all (includes answered approvals). Default: active only')
     .option('--decision <decision>', 'with resolved/all: approved or rejected')
     .option('--page <n>', 'page number (newest first)')
     .option('--priority <priority>', 'filter: low, normal, high, urgent')
@@ -78,7 +80,15 @@ export function registerInboxCommands(program, ctx) {
         columns: ['id', 'kind', 'priority', 'title', 'source', 'reason', 'status', 'created_at'],
         headers: ['ID', 'Kind', 'Priority', 'Title', 'Source', 'Reason', 'Status', 'Created'],
         rows: items,
-      }, { format: program.opts().output });
+      }, {
+        format: program.opts().output,
+        emptyMessage: 'Nothing waiting for you. Try `--status all` for answered items, or `--awaiting-human` for approvals waiting on a human org-wide.',
+      });
+      const limit = Number(options.limit);
+      if (program.opts().output !== 'json' && items.length > 0 && Number.isFinite(limit) && items.length >= limit) {
+        const total = typeof data.total === 'number' ? data.total : null;
+        console.log(`showing ${items.length}${total && total > items.length ? ` of ${total}` : ''} · --limit to see more`);
+      }
     });
 
   inbox
@@ -116,9 +126,13 @@ export function registerInboxCommands(program, ctx) {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
       const format = program.opts().output;
+      // DS-010 / #1335: a step-up sink answers 403 step_up_required; ask the person for their PIN (hidden, TTY only) and retry once.
       const post = (itemId) => {
         const ep = resolveEndpoint('inbox.respond', { orgId, itemId });
-        return client.post(ep.path, { service: ep.service, body: { action: options.action, comment: options.comment } });
+        return withStepUp(
+          (headers) => client.post(ep.path, { service: ep.service, headers, body: { action: options.action, comment: options.comment } }),
+          { client, orgId, io: ctx.stepUpIO, what: 'This approval' },
+        );
       };
       // Resolve an approvalId to its card (server-side on a current server, else the client scan). When
       // this profile cannot see the card, still ask the server: it knows WHY (an agent login, another
@@ -161,6 +175,26 @@ export function registerInboxCommands(program, ctx) {
     } catch { return null; }
   }
 
+  inbox
+    .command('unread')
+    .description('Mark inbox items unread again (undo a mark-as-read), for you only')
+    .argument('<itemId...>', 'one or more inbox item IDs')
+    .action(async (ids) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      let done = 0;
+      for (const id of ids) {
+        try {
+          await client.patch(`${resolveEndpoint('inbox.get', { orgId, itemId: encodeURIComponent(id) }).path}/read`, { service: resolveEndpoint('inbox.get', { orgId, itemId: id }).service, body: { is_read: false } });
+          done++;
+        } catch (err) {
+          announceFailure('inbox', `unread ${id}`, err);
+          throw err.status === 404 ? notFound(id, err) : err;
+        }
+      }
+      announce('inbox', `marked ${done} unread`, { result: ids.length === 1 ? ids[0] : `${done} items` });
+    });
+
   inbox
     .command('stats')
     .description('Show inbox statistics')

package/lib/commands/inboxq.js

@@ -0,0 +1,147 @@
+/**
+ * `quox inboxq`: InboxQ email namespace. Today: `inboxq watch`, awaited-mail
+ * alerts (collector: /api/v1/inboxq/watches, org resolved server-side).
+ *
+ * `quox inbox` is the HITL approvals inbox and `quox watch` is fleet
+ * monitoring; neither is touched here.
+ */
+
+import { formatOutput } from '../core/output.js';
+import { QuoxApiError, QuoxError } from '../core/errors.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const ZONES = ['focus', 'fyi', 'auto', 'screened'];
+const CHANNELS = ['hitl', 'lucid', 'telegram', 'discord', 'call', 'sms'];
+const NEEDS_DESTINATION = ['telegram', 'discord', 'call', 'sms'];
+
+const isJson = (program) => program.opts().output === 'json';
+const printJson = (d) => console.log(JSON.stringify(d, null, 2));
+
+async function call(fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    if (e instanceof QuoxApiError && e.status === 404) throw new QuoxError('Watch not found.', 1);
+    throw e;
+  }
+}
+
+export function describeMatch(match = {}) {
+  const parts = [];
+  if (match.from) parts.push(`from~${match.from}`);
+  if (match.subject) parts.push(`subject~${match.subject}`);
+  if (match.text) parts.push(`text~${match.text}`);
+  if (match.zone) parts.push(`zone=${match.zone}`);
+  return parts.join(' ') || '(any)';
+}
+
+export function parseNotify(csv) {
+  const list = String(csv ?? 'hitl').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+  if (list.length === 0) throw new QuoxError(`--notify needs at least one of: ${CHANNELS.join(', ')}`, 2);
+  const bad = list.filter((c) => !CHANNELS.includes(c));
+  if (bad.length) throw new QuoxError(`Unknown --notify channel: ${bad.join(', ')}. Use: ${CHANNELS.join(', ')}`, 2);
+  return [...new Set(list)];
+}
+
+export function registerInboxqCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const inboxq = program
+    .command('inboxq')
+    .description('InboxQ email: awaited-mail watches (not the HITL approvals inbox, see `quox inbox`)');
+
+  const watch = inboxq
+    .command('watch')
+    .description('Awaited-mail alerts: get told when a matching email arrives');
+
+  watch
+    .command('add')
+    .description('Create a watch. At least one of --from, --subject, --text, --zone is required')
+    .option('--account <id>', 'mail account id; omit to watch across all your mailboxes')
+    .requiredOption('--label <text>', 'short name for this watch')
+    .option('--from <addr>', 'sender contains this text')
+    .option('--subject <text>', 'subject contains this text')
+    .option('--text <keyword>', 'message text contains this keyword')
+    .option('--zone <zone>', `only mail triaged into this zone (${ZONES.join('|')})`)
+    .option('--notify <csv>', `alert channels, comma list of ${CHANNELS.join('|')}`, 'hitl')
+    .action(async (options) => {
+      auth.requireAuth();
+      const match = {};
+      if (options.from) match.from = options.from;
+      if (options.subject) match.subject = options.subject;
+      if (options.text) match.text = options.text;
+      if (options.zone) {
+        if (!ZONES.includes(options.zone)) throw new QuoxError(`--zone must be one of: ${ZONES.join(', ')}`, 2);
+        match.zone = options.zone;
+      }
+      if (Object.keys(match).length === 0) {
+        throw new QuoxError('Give at least one of --from, --subject, --text or --zone, or the watch would match nothing in particular.', 2);
+      }
+      const notify = parseNotify(options.notify);
+      const ep = resolveEndpoint('inboxq.watches.create');
+      const data = await call(() => client.post(ep.path, {
+        service: ep.service,
+        body: { accountId: options.account, label: options.label, match, notify },
+      }));
+      if (isJson(program)) return printJson(data);
+      const w = data.watch || {};
+      console.log(`Watch ${w.id} created: "${options.label}" watches ${describeMatch(match)}; alerts via ${notify.join(', ')}.`);
+      const needs = notify.filter((c) => NEEDS_DESTINATION.includes(c));
+      if (needs.length) {
+        console.log(`Note: ${needs.join(', ')} need a destination configured, otherwise they will report unconfigured. hitl and lucid work out of the box.`);
+      }
+    });
+
+  watch
+    .command('list')
+    .description('List watches')
+    .option('--account <id>', 'only watches for this mail account')
+    .option('--json', 'print JSON')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('inboxq.watches.list');
+      const data = await call(() => client.get(ep.path, { service: ep.service }));
+      let watches = data.watches || [];
+      if (options.account) watches = watches.filter((w) => w.accountId === options.account);
+      if (options.json || isJson(program)) return printJson({ ...data, watches });
+      if (watches.length === 0) return console.log('No watches.');
+      formatOutput({
+        columns: ['id', 'label', 'matches', 'notify', 'active', 'hits'],
+        headers: ['ID', 'Label', 'Matches', 'Notify', 'Active', 'Hits'],
+        rows: watches.map((w) => ({
+          id: w.id,
+          label: w.label,
+          matches: describeMatch(w.match),
+          notify: (w.notify || []).join(','),
+          active: w.active ? 'yes' : 'no',
+          hits: w.hitCount ?? 0,
+        })),
+      }, { format: program.opts().output });
+    });
+
+  for (const [name, active, past] of [['pause', false, 'paused'], ['resume', true, 'resumed']]) {
+    watch
+      .command(name)
+      .description(`${name === 'pause' ? 'Pause' : 'Resume'} a watch`)
+      .argument('<watchId>', 'watch id')
+      .action(async (watchId) => {
+        auth.requireAuth();
+        const ep = resolveEndpoint('inboxq.watches.active', { watchId });
+        const data = await call(() => client.post(ep.path, { service: ep.service, body: { active } }));
+        if (isJson(program)) return printJson(data);
+        console.log(`Watch ${watchId} ${past}.`);
+      });
+  }
+
+  watch
+    .command('rm')
+    .description('Delete a watch')
+    .argument('<watchId>', 'watch id')
+    .action(async (watchId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('inboxq.watches.delete', { watchId });
+      const data = await call(() => client.delete(ep.path, { service: ep.service }));
+      if (isJson(program)) return printJson(data);
+      console.log(`Watch ${watchId} deleted.`);
+    });
+}

package/lib/commands/kuma.js

@@ -7,8 +7,9 @@
  * quox kuma down [slug]      only monitors that are not up (exit 3 when any)
  * quox kuma uptime [slug]    24h/30d uptime table, worst first
  * quox kuma refresh [slug]   ask the collector to re-scrape the status page(s)
- * quox kuma monitors list|get|add|edit|pause|resume|remove   manage monitors (writes need org admin + human approval)
+ * quox kuma monitors list|get|add|edit|pause|resume|wire-alerts|remove   manage monitors (writes need org admin + human approval)
  * quox kuma incidents [--open]          Kuma alerts that became Quox incidents (NQ-KUMA-4)
+ * quox kuma incidents show <id>         one incident, its diagnosis and the Wazuh picture for its host (WAZ P7)
  * quox kuma hooks list|create|delete    per-org signed alert hook Kuma posts to (org admin)
  * quox kuma diagnose <incidentId>|--monitor <id>   why is it down: outside-in + governed host checks (NQ-KUMA-5)
  * quox kuma sla [--month|--from --to] | list | verify <id|file>   signed, verifiable uptime reports (NQ-KUMA-7)
@@ -443,11 +444,17 @@ export function registerKumaCommands(program, ctx) {
       if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
       console.log(glyphLine('kuma', 'monitors list', { result: `${data.monitors.length} monitors${data.kumaVersion ? ` · Kuma ${data.kumaVersion}` : ''}`, status: 'ok' }));
       if (!data.monitors.length) return;
-      const rows = [['ID', 'ACTIVE', 'TYPE', 'NAME', 'TARGET', 'INTERVAL']];
+      const rows = [['ID', 'ACTIVE', 'TYPE', 'NAME', 'TARGET', 'INTERVAL', 'ALERTS']];
+      let noAlert = 0;
       for (const m of data.monitors) {
-        rows.push([m.id ?? '-', m.active === null || m.active === undefined ? '-' : (m.active ? 'yes' : 'no'), m.type || '-', m.name || '-', targetOf(m), m.interval ? `${m.interval}s` : '-']);
+        let alerts;
+        if (!Array.isArray(m.alerts)) alerts = '?';
+        else if (!m.alerts.length) { alerts = '⚠ NONE'; noAlert += 1; }
+        else alerts = m.alerts.map((a) => (a && a.name) || a).join(',');
+        rows.push([m.id ?? '-', m.active === null || m.active === undefined ? '-' : (m.active ? 'yes' : 'no'), m.type || '-', m.name || '-', targetOf(m), m.interval ? `${m.interval}s` : '-', alerts]);
       }
       console.log(pad(rows).join('\n'));
+      if (noAlert) console.log(`${noAlert} monitor(s) have no Quox alert, so outages on them are not seen. Fix: quox kuma monitors wire-alerts <id...>   (each waits for a human approval)`);
     }));
 
   monitors
@@ -490,6 +497,12 @@ export function registerKumaCommands(program, ctx) {
     if (!/^\d+$/.test(String(v))) throw new KumaFail(`quox kuma ${verb}: the id must be a whole number, got "${v}"`);
     return Number(v);
   };
+  /** A monitor added with alerts [] is invisible to Quox incident capture: say so. */
+  const warnNoAlert = (d) => {
+    if (d && d.status !== 'awaiting_approval' && Array.isArray(d.alerts) && d.alerts.length === 0) {
+      console.log(`⚠ ${d.name || 'The new monitor'}${d.id ? ` (id ${d.id})` : ''} has no Quox alert, so outages on it are not seen. Fix: quox kuma monitors wire-alerts ${d.id ?? '<id>'}`);
+    }
+  };
   const awaitingLine = (id) => `◐ awaiting approval ${id}: a person approves it in the inbox; check with quox approvals result ${id}`;
   /** Run a governed kuma_* tool as the attached agent and report it like a human write. Returns the tool result. */
   async function agentTool(agentName, verb, tool, input, okLine) {
@@ -529,6 +542,7 @@ export function registerKumaCommands(program, ctx) {
         let data;
         try { data = await client.post(ep.path, { service: ep.service, body: { monitor } }); } catch (err) { throw monFail('add', ep, err); }
         reportWrite('add', ep, data, (d) => `added ${d.name || monitor.name}${d.id ? ` (id ${d.id})` : ''}`);
+        if (!jsonOut()) warnNoAlert(data);
       } catch (err) { fail(err); }
     });
 
@@ -581,6 +595,24 @@ export function registerKumaCommands(program, ctx) {
       } catch (err) { fail(err); }
     });
 
+  monitors
+    .command('wire-alerts')
+    .description('Attach the default Quox alert to monitors that have none, so their outages are seen (org admin; one human approval per monitor)')
+    .argument('<id...>', 'monitor id(s)')
+    .action(async (ids) => {
+      try {
+        auth.requireAuth();
+        const agentName = await actingAgent();
+        for (const id of ids) {
+          if (agentName) { await agentTool(agentName, 'monitors wire-alerts', 'kuma_monitor_wire_alerts', { id: wholeId('monitors wire-alerts', id) }, () => `wired Quox alerts on monitor ${id}`); continue; }
+          const ep = resolveEndpoint('mon.kuma.monitors.wire-alerts', { id });
+          let data;
+          try { data = await client.post(ep.path, { service: ep.service, body: {} }); } catch (err) { throw monFail('wire-alerts', ep, err, id); }
+          reportWrite('wire-alerts', ep, data, (d) => `wired Quox alerts on ${d.name || `monitor ${id}`}`);
+        }
+      } catch (err) { fail(err); }
+    });
+
   monitors
     .command('remove')
     .description('Delete a monitor (org admin; held for human approval)')
@@ -614,12 +646,20 @@ export function registerKumaCommands(program, ctx) {
     return new KumaFail(`${head}: ${msg}`);
   };
 
+  // WAZ P7: `quox kuma incidents show <id>` is positional words on this ONE leaf (not a subcommand), so the list verb
+  // keeps its leaf-policy row for chat and the matrix; `show <id>` prints one incident with the Wazuh picture.
   kuma
     .command('incidents')
-    .description('Kuma alerts that became Quox incidents: when down, when back, how long')
+    .description('Kuma alerts that became Quox incidents: when down, when back, how long. `incidents show <id>`: one incident with its diagnosis and the Wazuh agent + open Wazuh incidents for the same host')
+    .argument('[words...]', 'show <incidentId> for one incident')
     .option('--open', 'only outages still going')
     .option('--limit <n>', 'max rows (default 50, max 200)')
-    .action(guard('incidents', async (options) => {
+    .action(guard('incidents', async (words, options) => {
+      const w = Array.isArray(words) ? words : [];
+      if (w.length) {
+        if (w[0] !== 'show' || w.length !== 2) throw new KumaFail(`quox kuma incidents: unexpected "${w.join(' ')}". Use \`quox kuma incidents [--open]\` or \`quox kuma incidents show <incidentId>\`.`);
+        return showIncident(w[1]);
+      }
       auth.requireAuth();
       const ep = resolveEndpoint('mon.kuma.incidents.list', { open: !!options.open, limit: options.limit });
       let data;
@@ -657,6 +697,38 @@ export function registerKumaCommands(program, ctx) {
       }
     }));
 
+  // WAZ P7: one incident with its diagnosis and the Wazuh picture for the host (attached when the outage opened).
+  async function showIncident(incidentId) {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.kuma.incidents.get', { id: incidentId });
+      let data;
+      try { data = await client.get(ep.path, { service: ep.service }); } catch (err) {
+        const status = err && (err.status ?? err.statusCode);
+        if (status === 404) throw new KumaFail(`quox kuma incidents show: ${ep.method} ${ep.path} failed with HTTP 404: no such incident (${incidentId}) in this org. List them with \`quox kuma incidents\`.`);
+        throw new KumaFail(`quox kuma incidents show: ${ep.method} ${ep.path} failed${status ? ` with HTTP ${status}` : ''}: ${(err && err.message) || err}`);
+      }
+      if (!data || data.success === false || data.error || !data.incident) {
+        throw new KumaFail(`quox kuma incidents show: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no incident'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const i = data.incident;
+      console.log(glyphLine('kuma', 'incidents show', { result: `${i.id} · ${i.open ? 'DOWN' : 'resolved'}`, status: i.open ? 'warn' : 'ok' }));
+      const d = i.diagnosis;
+      const w = i.wazuh;
+      const rows = [
+        ['Monitor', `${i.monitor_name || '-'} (monitor ${i.monitor_id ?? '-'})`],
+        ['Target', i.target || '-'],
+        ['State', i.open ? 'down' : (i.close_reason === 'monitor_deleted' ? 'closed: monitor deleted' : 'resolved')],
+        ['Opened', i.opened_at || '-'],
+        ['Closed', i.closed_at || '-'],
+        ['Events', i.events ?? '-'],
+        ['Last message', i.last_msg || '-'],
+        ['Why', d && d.summary ? `${d.summary} [${d.verdict}]` : 'not diagnosed yet (quox kuma diagnose ' + i.id + ')'],
+        ['Wazuh', w && w.summary ? w.summary : 'not checked (Quox attaches the Wazuh picture when an outage opens and Wazuh is configured)'],
+      ];
+      console.log(pad(rows).join('\n'));
+  }
+
   const printDiagnosis = (d, verb) => {
     console.log(glyphLine('kuma', verb, { result: d.verdict, status: d.verdict === 'not_reproducible' ? 'warn' : 'fail' }));
     console.log(d.summary);
@@ -1019,6 +1091,7 @@ export function registerKumaCommands(program, ctx) {
     'monitors edit': 'quox kuma monitors edit 4 --interval 60',
     'monitors pause': 'quox kuma monitors pause 4',
     'monitors resume': 'quox kuma monitors resume 4',
+    'monitors wire-alerts': 'quox kuma monitors wire-alerts 4 7',
     'monitors remove': 'quox kuma monitors remove 4',
     incidents: 'quox kuma incidents --open',
     diagnose: 'quox kuma diagnose --monitor 7',