quoxcli 0.3.1 → 0.4.0

package/lib/commands/kuma.js

@@ -0,0 +1,1050 @@
+/**
+ * Uptime Kuma commands: read-only view of the monitors behind a Kuma status page.
+ *
+ * With no slug (and no --all) status|down|uptime read the ORG's own Kuma (vault credential, GET /api/v1/kuma/status),
+ * the same live set VIGIL sees; the header line shows the source. A slug or --all asks for that public status page.
+ * quox kuma status [slug]    every monitor, grouped, with state/ping/uptime
+ * 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 incidents [--open]          Kuma alerts that became Quox incidents (NQ-KUMA-4)
+ * 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)
+ * quox kuma maintenance list|open|end    planned work does not page people (NQ-KUMA-8; open/end are approval-gated)
+ * quox kuma status-incident draft|publish|resolve   customer-safe status-page comms (NQ-KUMA-8; publish/resolve are approval-gated)
+ *
+ * Backend (existing collector routes, no collector changes):
+ *   GET  /api/v1/monitoring/config                       configured Kuma URL + status-page slugs
+ *   GET  /api/v1/monitoring/uptime-kuma/status/:slug     monitors (cached, scannedAt says how old)
+ *   POST /api/v1/monitoring/uptime-kuma/refresh          background re-scrape of all configured pages
+ *
+ * Honesty: a non-2xx or a body with success:false is an ERROR, reported with the
+ * verb, endpoint and status. It is never rendered as "0 monitors".
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { line as glyphLine } from '../core/quoxglyph.js';
+import { resolveActing } from '../core/actingAs.js';
+import { resolveOrgId } from './helpers.js';
+import { execResultFailed, execResultPending, pendingBodyOfError } from './agentAttach.js';
+import { registerKumaSla } from './kumaSla.js';
+
+const STATE = { 1: 'up', 0: 'down', 2: 'pending', 3: 'maintenance' };
+export const stateOf = (m) => (m && typeof m.state === 'string' ? m.state : m && Object.prototype.hasOwnProperty.call(STATE, m.status) ? STATE[m.status] : 'unknown');
+
+const SETUP_HINT =
+  'Uptime Kuma is not configured on this collector.\n'
+  + '  Check:  quox mon config get\n'
+  + '  Fix:    set the Kuma URL and a status page slug in the dashboard monitoring settings\n'
+  + '          (PUT /api/v1/monitoring/config/uptime-kuma with url and statusPageSlug; instance admin).\n'
+  + '          There is no `quox mon config set` verb yet.';
+
+class KumaFail extends Error {
+  constructor(message, exitCode = 1) { super(message); this.exitCode = exitCode; }
+}
+
+function failFrom(verb, ep, err) {
+  const status = err && (err.status ?? err.statusCode);
+  const msg = (err && err.message) || String(err);
+  return new KumaFail(`quox kuma ${verb}: ${ep.method} ${ep.path} failed${status ? ` with HTTP ${status}` : ''}: ${msg}`);
+}
+
+const pct = (v) => {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+const fmtPct = (v) => { const n = pct(v); return n === null ? '-' : `${n.toFixed(2)}%`; };
+const fmtPing = (v) => (v === null || v === undefined || v === '' || !Number.isFinite(Number(v)) ? '-' : `${Math.round(Number(v))}ms`);
+
+function pad(rows) {
+  const w = [];
+  for (const r of rows) r.forEach((c, i) => { w[i] = Math.max(w[i] || 0, [...String(c)].length); });
+  return rows.map((r) => r.map((c, i) => String(c) + ' '.repeat(w[i] - [...String(c)].length)).join('  ').trimEnd());
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${Number(n) === 1 ? one : many}`;
+
+/** Compact duration for relative times: 45s, 4m, 2h 35m, 3d 4h. */
+export function relDuration(ms) {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+  return `${Math.floor(s / 86400)}d ${Math.floor((s % 86400) / 3600)}h`;
+}
+
+/** Wrap text to width; continuation lines get the indent. Never breaks inside a word unless the word alone is too long. */
+export function wrapText(text, width, indent = '') {
+  const lines = [];
+  let cur = '';
+  for (const word of String(text).split(/\s+/).filter(Boolean)) {
+    if (cur && [...cur].length + 1 + [...word].length > width) { lines.push(cur); cur = indent + word; } else cur = cur ? `${cur} ${word}` : word;
+  }
+  if (cur) lines.push(cur);
+  return lines;
+}
+
+const hasTz = (s) => /(?:Z|[+-]\d\d:?\d\d)$/i.test(String(s));
+/** A Kuma time as `YYYY-MM-DD HH:MM UTC`. A zoneless string is converted when its zone is known, else labelled as Kuma server time. */
+export function fmtWhen(value, tz) {
+  if (value === null || value === undefined || value === '') return '-';
+  const str = String(value);
+  if (hasTz(str)) {
+    const d = new Date(str);
+    return Number.isNaN(d.getTime()) ? str : `${d.toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+  }
+  const m = /^(\d{4})-(\d\d)-(\d\d)[T ](\d\d):(\d\d)/.exec(str);
+  if (m && tz) {
+    try {
+      const asUtc = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5]);
+      const parts = new Intl.DateTimeFormat('en-US', { timeZone: tz, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' }).formatToParts(new Date(asUtc));
+      const g = (t) => Number(parts.find((x) => x.type === t).value);
+      const shown = Date.UTC(g('year'), g('month') - 1, g('day'), g('hour'), g('minute'));
+      return `${new Date(asUtc - (shown - asUtc)).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+    } catch { /* unknown zone: fall through to the label */ }
+  }
+  return `${str} (Kuma server time)`;
+}
+
+export function registerKumaCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const jsonOut = () => program.opts().output === 'json';
+
+  const kuma = program
+    .command('kuma')
+    .description('Uptime Kuma. Bare `quox kuma` runs status. Verbs: status, down, uptime, refresh, monitors, incidents, diagnose, coverage, sla, maintenance, status-incident, hooks')
+    .addHelpText('after', '\nExample:  quox kuma\nExit codes: 0 ok, 1 error or Kuma not configured, 3 `quox kuma down` found monitors not up.');
+  const exampled = new Set([kuma]);
+  const example = (cmd, line) => { exampled.add(cmd); return cmd.addHelpText('after', `\nExample:  ${line}`); };
+
+  /** Returns { slugs: [...] } or throws KumaFail (unconfigured / HTTP error). */
+  async function configuredSlugs(verb) {
+    const ep = resolveEndpoint('mon.config.get');
+    let data;
+    try {
+      data = await client.get(ep.path, { service: ep.service });
+    } catch (err) { throw failFrom(verb, ep, err); }
+    if (!data || data.success === false) {
+      throw new KumaFail(`quox kuma ${verb}: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'no body'}`);
+    }
+    const k = data.services && data.services['uptime-kuma'];
+    const pages = (k && Array.isArray(k.statusPages) ? k.statusPages : []).map((p) => p.slug).filter(Boolean);
+    if (!pages.length && k && k.statusPageSlug) pages.push(k.statusPageSlug);
+    if (!k || !k.configured || !pages.length) {
+      throw new KumaFail(`${SETUP_HINT}${k && k.configured && !pages.length ? '\n  (a URL is set but no status page slug is configured)' : ''}`);
+    }
+    return pages;
+  }
+
+  async function fetchPage(verb, slug) {
+    const ep = resolveEndpoint('mon.kuma.status.get', { slug });
+    let data;
+    try {
+      data = await client.get(ep.path, { service: ep.service });
+    } catch (err) { throw failFrom(verb, ep, err); }
+    if (!data || data.success === false || !Array.isArray(data.monitors)) {
+      const why = data && data.error ? data.error : 'response had no monitors array';
+      if (/not configured/i.test(why)) throw new KumaFail(SETUP_HINT);
+      throw new KumaFail(`quox kuma ${verb}: ${ep.method} ${ep.path} returned an error body: ${why}`);
+    }
+    return { slug, ...data };
+  }
+
+  /** NQ-KUMA-3: the org's live Kuma. Returns a page-shaped object, or null to use the legacy status page. */
+  async function fetchLive(verb) {
+    const ep = resolveEndpoint('mon.kuma.live.get');
+    let data;
+    try {
+      data = await client.get(ep.path, { service: ep.service });
+    } catch (err) {
+      if ((err && (err.status ?? err.statusCode)) === 404) return null; // older collector: no live route
+      throw failFrom(verb, ep, err);
+    }
+    if (data && data.success === false) {
+      throw new KumaFail(`quox kuma ${verb}: ${ep.method} ${ep.path} returned an error body: ${data.error || 'no body'}`);
+    }
+    if (!data || !Array.isArray(data.monitors)) return null;
+    const slug = data.source === 'vault' ? 'vault' : `status_page${data.slug ? ` ${data.slug}` : ''}`;
+    return { ...data, slug };
+  }
+
+  /** Resolve slug(s) then fetch each page. */
+  async function loadPages(verb, slugArg, all) {
+    auth.requireAuth();
+    if (!slugArg && !all) {
+      const live = await fetchLive(verb);
+      if (live) return [live];
+    }
+    let slugs;
+    if (slugArg) slugs = [slugArg];
+    else {
+      const configured = await configuredSlugs(verb);
+      slugs = all ? configured : [configured[0]];
+    }
+    const pages = [];
+    for (const s of slugs) pages.push(await fetchPage(verb, s));
+    return pages;
+  }
+
+  function guard(verb, fn) {
+    return async (...args) => {
+      try { await fn(...args); } catch (err) {
+        if (!(err instanceof KumaFail)) throw err;
+        console.error(err.message);
+        process.exitCode = err.exitCode || 1;
+      }
+    };
+  }
+
+  const summaryOf = (ms) => {
+    const c = { up: 0, down: 0, pending: 0, maintenance: 0, unknown: 0 };
+    for (const m of ms) c[stateOf(m)]++;
+    return c;
+  };
+  const summaryText = (ms) => {
+    const c = summaryOf(ms);
+    const parts = [`${c.up}/${ms.length} up`];
+    for (const k of ['down', 'pending', 'maintenance', 'unknown']) if (c[k]) parts.push(`${c[k]} ${k}`);
+    return parts.join(' · ');
+  };
+  const nameOf = (m) => m.name || `monitor ${m.id}`;
+  // A snapshot older than STALE_AFTER_MS is not current state: say how old, and how to get a fresh one.
+  const STALE_AFTER_MS = 10 * 60 * 1000;
+  const ageText = (ms) => (ms >= 86400000 ? `${Math.floor(ms / 86400000)}d` : ms >= 3600000 ? `${Math.floor(ms / 3600000)}h` : `${Math.floor(ms / 60000)}m`);
+  const age = (p) => {
+    if (!p.scannedAt) return '';
+    const ms = Date.now() - Date.parse(p.scannedAt);
+    const old = Number.isFinite(ms) && ms > STALE_AFTER_MS;
+    const why = p.stale ? `, ${p.source ? 'status page snapshot is old' : `last refresh failed: ${p.error}`}` : '';
+    return `${p.source ? `source ${p.source}${p.fallbackReason ? ' (org has no Kuma credential in the vault)' : ''}, ` : ''}${p.cached ? 'cached' : 'fresh'} ${p.scannedAt}${old || p.stale ? ` ⚠ STALE: ${old ? `${ageText(ms)} old` : 'refresh failed'}${why}; this is not current state, run \`quox kuma refresh\`` : ''}`;
+  };
+
+  function printMonitors(page, monitors) {
+    const anyGroup = monitors.some((m) => m.group);
+    const has30d = monitors.some((m) => pct(m.uptime30d) !== null);
+    const byGroup = new Map();
+    for (const m of monitors) {
+      const g = m.group || 'ungrouped';
+      if (!byGroup.has(g)) byGroup.set(g, []);
+      byGroup.get(g).push(m);
+    }
+    for (const [g, ms] of byGroup) {
+      if (anyGroup) console.log(`\n${g}`); else console.log('');
+      const ind = anyGroup ? '  ' : '';
+      const rows = [[`${ind}STATE`, 'MONITOR', 'PING', '24H', ...(has30d ? ['30D'] : [])]];
+      for (const m of ms) rows.push([`${ind}${stateOf(m)}`, nameOf(m), fmtPing(m.ping), fmtPct(m.uptime24h), ...(has30d ? [fmtPct(m.uptime30d)] : [])]);
+      console.log(pad(rows).join('\n'));
+    }
+  }
+
+  const statusAction = guard('status', async (slugArg, options) => {
+      const pages = await loadPages('status', slugArg, options.all);
+      if (jsonOut()) { console.log(JSON.stringify(options.all || pages.length > 1 ? pages : pages[0], null, 2)); return; }
+      for (const p of pages) {
+        const st = summaryOf(p.monitors).down ? 'fail' : 'ok';
+        console.log(glyphLine('kuma', `status ${p.slug}`, { result: `${summaryText(p.monitors)}${p.kumaVersion ? ` · Kuma ${p.kumaVersion}` : ''}`, status: st }));
+        if (age(p)) console.log(age(p));
+        if (!p.monitors.length) console.log('Status page has no monitors.');
+        else printMonitors(p, p.monitors);
+      }
+    });
+  example(kuma
+    .command('status')
+    .description('Every monitor, grouped, with state, ping and 24h/30d uptime')
+    .argument('[slug]', 'status page slug (default: first configured)')
+    .option('--all', 'show every configured status page')
+    .action(statusAction), 'quox kuma status');
+  // Bare `quox kuma` is the fast path: the same as `quox kuma status`.
+  kuma.action(async () => { await statusAction(undefined, {}); });
+
+  example(kuma
+    .command('down')
+    .description('Only monitors that are not up. Exit code 0 when all up, 3 when any is not up')
+    .argument('[slug]', 'status page slug (default: first configured)')
+    .option('--all', 'check every configured status page')
+    .action(guard('down', async (slugArg, options) => {
+      const pages = await loadPages('down', slugArg, options.all);
+      const notUp = pages.flatMap((p) => p.monitors.filter((m) => stateOf(m) !== 'up').map((m) => ({ ...m, page: p.slug })));
+      if (jsonOut()) console.log(JSON.stringify({ down: notUp, checked: pages.map((p) => p.slug) }, null, 2));
+      else {
+        const total = pages.reduce((n, p) => n + p.monitors.length, 0);
+        console.log(glyphLine('kuma', `down ${pages.map((p) => p.slug).join(',')}`, {
+          result: notUp.length ? `${notUp.length} of ${total} not up` : `all ${total} up`, status: notUp.length ? 'fail' : 'ok',
+        }));
+        if (notUp.length) {
+          const anyGroup = notUp.some((m) => m.group);
+          const rows = [['STATE', 'MONITOR', ...(anyGroup ? ['GROUP'] : []), 'MESSAGE']];
+          for (const m of notUp) rows.push([stateOf(m), nameOf(m), ...(anyGroup ? [m.group || '-'] : []), String(m.message || '-').replace(/\s+/g, ' ').slice(0, 80)]);
+          console.log(pad(rows).join('\n'));
+        }
+      }
+      if (notUp.length) process.exitCode = 3;
+    })), 'quox kuma down');
+
+  example(kuma
+    .command('uptime')
+    .description('Per-monitor 24h/30d uptime, worst first')
+    .argument('[slug]', 'status page slug (default: first configured)')
+    .option('--all', 'include every configured status page')
+    .option('--below <pct>', 'only monitors whose 24h or 30d uptime is below this percentage')
+    .action(guard('uptime', async (slugArg, options) => {
+      let below = null;
+      if (options.below !== undefined) {
+        below = Number(options.below);
+        if (!Number.isFinite(below)) throw new KumaFail(`quox kuma uptime: --below needs a number, got "${options.below}"`);
+      }
+      const pages = await loadPages('uptime', slugArg, options.all);
+      let list = pages.flatMap((p) => p.monitors.map((m) => ({ ...m, page: p.slug })));
+      const worst = (m) => Math.min(pct(m.uptime24h) ?? 101, pct(m.uptime30d) ?? 101);
+      if (below !== null) list = list.filter((m) => worst(m) < below);
+      list.sort((a, b) => worst(a) - worst(b) || nameOf(a).localeCompare(nameOf(b)));
+      if (jsonOut()) { console.log(JSON.stringify(list, null, 2)); return; }
+      console.log(glyphLine('kuma', `uptime ${pages.map((p) => p.slug).join(',')}`, {
+        result: below !== null ? `${list.length} below ${below}%` : plural(list.length, 'monitor'),
+        status: list.length && below !== null ? 'warn' : 'ok',
+      }));
+      if (!list.length) { console.log(below !== null ? `No monitors below ${below}%.` : 'Status page has no monitors.'); return; }
+      const has30d = list.some((m) => pct(m.uptime30d) !== null);
+      const rows = [['24H', ...(has30d ? ['30D'] : []), 'STATE', 'MONITOR']];
+      for (const m of list) rows.push([fmtPct(m.uptime24h), ...(has30d ? [fmtPct(m.uptime30d)] : []), stateOf(m), nameOf(m)]);
+      console.log(pad(rows).join('\n'));
+    })), 'quox kuma uptime --below 99.9');
+
+  example(kuma
+    .command('refresh')
+    .description('Bust the live-state cache and show fresh monitor state (also re-scrapes any configured public status pages)')
+    .argument('[slug]', 'accepted for symmetry; the collector refreshes every configured public status page')
+    , 'quox kuma refresh')
+    .action(async () => {
+      // Not wrapped in guard(): the leaf-methods scanner reads this handler's own
+      // source, and the client.post below must stay visible so refresh is classed a write.
+      try {
+        auth.requireAuth();
+        // 1. the org's live state, bypassing the per-org 30s cache (the same set `quox kuma status` reads)
+        const liveEp = resolveEndpoint('mon.kuma.live.get', { fresh: true });
+        let live = null;
+        try {
+          const d = await client.get(liveEp.path, { service: liveEp.service });
+          if (d && d.success === false) throw new KumaFail(`quox kuma refresh: ${liveEp.method} ${liveEp.path} returned an error body: ${d.error || 'no body'}`);
+          if (d && Array.isArray(d.monitors)) live = { ...d, slug: d.source === 'vault' ? 'vault' : `status_page${d.slug ? ` ${d.slug}` : ''}` };
+        } catch (err) {
+          if (err instanceof KumaFail) throw err;
+          if ((err && (err.status ?? err.statusCode)) !== 404) throw failFrom('refresh', liveEp, err); // 404: older collector, no live route
+        }
+        // 2. legacy public status pages: only mentioned when any are configured
+        const ep = resolveEndpoint('mon.kuma.refresh.create');
+        let data;
+        try {
+          data = await client.post(ep.path, { service: ep.service, body: {} });
+        } catch (err) { throw failFrom('refresh', ep, err); }
+        if (!data || data.success === false) {
+          throw new KumaFail(`quox kuma refresh: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'no body'}`);
+        }
+        const pages = Array.isArray(data.refreshing) ? data.refreshing : [];
+        if (jsonOut()) { console.log(JSON.stringify(live ? { live, ...data } : data, null, 2)); return; }
+        if (live) {
+          console.log(glyphLine('kuma', 'refresh', { result: `${summaryText(live.monitors)} · fresh ${live.scannedAt || ''}`.trim(), status: summaryOf(live.monitors).down ? 'fail' : 'ok' }));
+          if (pages.length) console.log(`Also queued a re-scrape of public status pages: ${pages.join(', ')} (background).`);
+          return;
+        }
+        if (!pages.length) throw new KumaFail(SETUP_HINT);
+        console.log(glyphLine('kuma', 'refresh', { result: `${pages.length} page(s) queued: ${pages.join(', ')}`, status: 'busy' }));
+        console.log('Runs in the background; re-run `quox kuma status` in a few seconds.');
+      } catch (err) {
+        if (!(err instanceof KumaFail)) throw err;
+        console.error(err.message);
+        process.exitCode = err.exitCode || 1;
+      }
+    });
+
+  // ---- monitors: manage the monitors themselves (collector /api/v1/kuma/monitors) ----
+  const monitors = kuma
+    .command('monitors')
+    .description('List, inspect and (org admin, human approved) change Uptime Kuma monitors')
+    .addHelpText('after', '\nWrites are held for human approval (HTTP 202); approve in the inbox, then `quox approvals result <approval_id>`.\nAgents use VIGIL\'s kuma_* tools instead of these verbs.');
+
+  const targetOf = (m) => (m.target || (m.url && !/^https?:\/\/?$/i.test(m.url) ? m.url : null) || (m.hostname ? `${m.hostname}${m.port ? `:${m.port}` : ''}` : '-'));
+  const MON_TYPES = ['http', 'keyword', 'port', 'ping', 'dns'];
+
+  /** Turn a thrown API error into a KumaFail with the verb, endpoint, status and a useful hint. */
+  function monFail(verb, ep, err, id) {
+    const status = err && (err.status ?? err.statusCode);
+    const body = (err && err.body) || {};
+    const code = body.error_code || body.code || (err && err.code);
+    const msg = (err && err.message) || String(err);
+    const head = `quox kuma monitors ${verb}: ${ep.method} ${ep.path} failed${status ? ` with HTTP ${status}` : ''}`;
+    if (status === 403 && (code === 'admin_required' || /admin role required/i.test(msg))) {
+      return new KumaFail(`${head}: writes need an org admin or owner. Ask one to run this, or have an agent use VIGIL's kuma_* tools.`);
+    }
+    if (status === 403 && (code === 'org_required' || /organisation required/i.test(msg))) {
+      return new KumaFail(`${head}: no organisation on this login. Run \`quox login\` against an org account.`);
+    }
+    if (status === 422 || code === 'not_configured') {
+      return new KumaFail(`${head}: Uptime Kuma admin access is not configured for this org (${msg}).\n  Set the Kuma admin credentials in the dashboard monitoring settings (vault), then retry.`);
+    }
+    if (status === 404) return new KumaFail(`${head}: ${/not found/i.test(msg) ? msg : `monitor ${id || ''} not found`.replace('  ', ' ')}. List them with \`quox kuma monitors\`.`);
+    return new KumaFail(`${head}: ${msg}${id ? ` (monitor ${id})` : ''}`);
+  }
+
+  /** Print the result of a write. 202 = held for approval, never "done". */
+  function reportWrite(verb, ep, data, okLine) {
+    if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+    if (data && data.status === 'awaiting_approval') {
+      const id = data.approval_id || 'unknown';
+      console.log(`◐ awaiting approval ${id}: approve in the inbox${data.inbox_item_id ? ` (item ${data.inbox_item_id})` : ''}, then check with \`quox approvals result ${id}\``);
+      return;
+    }
+    if (!data || data.success === false || data.error) {
+      throw new KumaFail(`quox kuma monitors ${verb}: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'no body'}`);
+    }
+    console.log(glyphLine('kuma', `monitors ${verb}`, { result: okLine(data), status: 'ok' }));
+  }
+
+  /** Map CLI flags to allowlisted Kuma monitor fields (adminClient FIELD_RULES). Only given flags appear. */
+  function fieldsFrom(verb, o) {
+    const f = {};
+    const num = (flag, v) => {
+      if (!/^\d+$/.test(String(v))) throw new KumaFail(`quox kuma monitors ${verb}: --${flag} needs a whole number, got "${v}"`);
+      return Number(v);
+    };
+    if (o.name !== undefined) f.name = o.name;
+    if (o.type !== undefined) {
+      if (!MON_TYPES.includes(o.type)) throw new KumaFail(`quox kuma monitors ${verb}: --type must be one of ${MON_TYPES.join(', ')}, got "${o.type}"`);
+      f.type = o.type;
+    }
+    if (o.url !== undefined) f.url = o.url;
+    if (o.hostname !== undefined) f.hostname = o.hostname;
+    if (o.port !== undefined) f.port = num('port', o.port);
+    if (o.interval !== undefined) f.interval = num('interval', o.interval);
+    if (o.keyword !== undefined) f.keyword = o.keyword;
+    return f;
+  }
+  const withFlags = (cmd) => cmd
+    .option('--type <type>', `monitor type: ${MON_TYPES.join('|')}`)
+    .option('--url <url>', 'http(s) URL (http, keyword)')
+    .option('--hostname <host>', 'host name or IP (port, ping, dns)')
+    .option('--port <n>', 'TCP port (port, dns)')
+    .option('--interval <seconds>', 'check interval, 20..86400')
+    .option('--keyword <text>', 'text that must appear (keyword)');
+
+  monitors
+    .command('list')
+    .description('Every monitor: id, active, type, name, target, interval')
+    .action(guard('monitors list', async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.kuma.monitors.list');
+      let data;
+      try { data = await client.get(ep.path, { service: ep.service }); } catch (err) { throw monFail('list', ep, err); }
+      if (!data || data.success === false || data.error || !Array.isArray(data.monitors)) {
+        throw new KumaFail(`quox kuma monitors list: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no monitors array'}`);
+      }
+      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']];
+      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` : '-']);
+      }
+      console.log(pad(rows).join('\n'));
+    }));
+
+  monitors
+    .command('get')
+    .description('One monitor in full')
+    .argument('<id>', 'monitor id')
+    .action(guard('monitors get', async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.kuma.monitors.get', { id });
+      let data;
+      try { data = await client.get(ep.path, { service: ep.service }); } catch (err) { throw monFail('get', ep, err, id); }
+      if (!data || data.success === false || data.error || !data.monitor) {
+        throw new KumaFail(`quox kuma monitors get: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no monitor'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const m = data.monitor;
+      console.log(glyphLine('kuma', `monitors get ${id}`, { result: m.name || `monitor ${id}`, status: 'ok' }));
+      const rows = [['ID', m.id], ['NAME', m.name], ['TYPE', m.type], ['ACTIVE', m.active === null || m.active === undefined ? '-' : (m.active ? 'yes' : 'no')], ['TARGET', targetOf(m)], ['INTERVAL', m.interval ? `${m.interval}s` : '-']];
+      if (Array.isArray(m.tags) && m.tags.length) rows.push(['TAGS', m.tags.map((t) => (t.value ? `${t.name}:${t.value}` : t.name)).join(', ')]);
+      console.log(pad(rows.map(([k, v]) => [k, v ?? '-'])).join('\n'));
+    }));
+
+  // The add/edit/pause/resume/remove actions are NOT wrapped in guard(): the leaf-methods scanner
+  // reads each handler's own source, so every mutating client call must stay visible in its action.
+  const fail = (err) => {
+    if (!(err instanceof KumaFail)) throw err;
+    console.error(err.message);
+    process.exitCode = err.exitCode || 1;
+  };
+
+  // ---- attached-agent writes ----
+  // A session attached as an agent (quox agent attach) acts as that agent for plain verbs. The /api/v1/kuma write
+  // routes are human-admin only (they 403 an agent), so an attached session files the same governed kuma_* tool
+  // call `quox agent exec <agent> --tool kuma_...` makes: it comes back pending with an approval id.
+  async function actingAgent() {
+    const who = ctx.resolveActing ? await ctx.resolveActing() : await resolveActing({ explicitProfile: Boolean(ctx.config && ctx.config._explicitProfile) });
+    return (who && who.name) || null;
+  }
+  const wholeId = (verb, v) => {
+    if (!/^\d+$/.test(String(v))) throw new KumaFail(`quox kuma ${verb}: the id must be a whole number, got "${v}"`);
+    return Number(v);
+  };
+  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) {
+    const ep = resolveEndpoint('v1.tools.execute');
+    let data;
+    try {
+      data = await client.post(ep.path, { service: ep.service, body: { tool_name: tool, input, org_id: resolveOrgId(auth, program) } });
+    } catch (err) {
+      // The policy layer answers a held write with HTTP 403 + {pending:true, approvalId}: the approval is filed.
+      data = pendingBodyOfError(err);
+      if (!data) {
+        const status = err && (err.status ?? err.statusCode);
+        throw new KumaFail(`quox kuma ${verb}: ${ep.method} ${ep.path} (${tool} as ${agentName}) failed${status ? ` with HTTP ${status}` : ''}: ${(err && err.message) || err}`);
+      }
+    }
+    const pendingId = execResultPending(data);
+    if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); if (!pendingId && execResultFailed(data)) process.exitCode = 1; return data; }
+    if (pendingId) { console.log(awaitingLine(pendingId)); return data; }
+    if (execResultFailed(data) || !data || data.error) {
+      throw new KumaFail(`quox kuma ${verb}: ${tool} as ${agentName} failed: ${(data && (data.error || data.message || data.error_code)) || 'tool reported failure'}`);
+    }
+    if (okLine) console.log(glyphLine('kuma', verb, { result: okLine(data), status: 'ok' }));
+    return data;
+  }
+
+  withFlags(monitors.command('add').description('Add a monitor (org admin; held for human approval)')
+    .option('--name <name>', 'monitor name (required)'))
+    .action(async (options) => {
+      try {
+        auth.requireAuth();
+        if (!options.name) throw new KumaFail('quox kuma monitors add: --name is required');
+        if (!options.type) throw new KumaFail(`quox kuma monitors add: --type is required (${MON_TYPES.join('|')})`);
+        const monitor = fieldsFrom('add', options);
+        const agentName = await actingAgent();
+        if (agentName) { await agentTool(agentName, 'monitors add', 'kuma_monitor_add', { monitor: { name: options.name, ...monitor } }, (d) => `added ${(d.monitor && d.monitor.name) || monitor.name}`); return; }
+        const ep = resolveEndpoint('mon.kuma.monitors.create');
+        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})` : ''}`);
+      } catch (err) { fail(err); }
+    });
+
+  withFlags(monitors.command('edit').description('Change a monitor; only the flags you give are changed (org admin; held for approval)')
+    .argument('<id>', 'monitor id')
+    .option('--name <name>', 'new monitor name'))
+    .action(async (id, options) => {
+      try {
+        auth.requireAuth();
+        const changes = fieldsFrom('edit', options);
+        if (!Object.keys(changes).length) throw new KumaFail('quox kuma monitors edit: give at least one of --name --type --url --hostname --port --interval --keyword');
+        const agentName = await actingAgent();
+        if (agentName) { await agentTool(agentName, 'monitors edit', 'kuma_monitor_edit', { id: wholeId('monitors edit', id), changes }, () => `edited monitor ${id}`); return; }
+        const ep = resolveEndpoint('mon.kuma.monitors.update', { id });
+        let data;
+        try { data = await client.patch(ep.path, { service: ep.service, body: { changes } }); } catch (err) { throw monFail('edit', ep, err, id); }
+        reportWrite('edit', ep, data, (d) => `edited ${d.name || `monitor ${id}`} (id ${d.id ?? id})`);
+      } catch (err) { fail(err); }
+    });
+
+  monitors
+    .command('pause')
+    .description('Pause a monitor (org admin; held for human approval)')
+    .argument('<id>', 'monitor id')
+    .action(async (id) => {
+      try {
+        auth.requireAuth();
+        const agentName = await actingAgent();
+        if (agentName) { await agentTool(agentName, 'monitors pause', 'kuma_monitor_pause', { id: wholeId('monitors pause', id) }, () => `paused monitor ${id}`); return; }
+        const ep = resolveEndpoint('mon.kuma.monitors.pause', { id });
+        let data;
+        try { data = await client.post(ep.path, { service: ep.service, body: {} }); } catch (err) { throw monFail('pause', ep, err, id); }
+        reportWrite('pause', ep, data, (d) => `paused ${d.name || `monitor ${id}`}`);
+      } catch (err) { fail(err); }
+    });
+
+  monitors
+    .command('resume')
+    .description('Resume a paused monitor (org admin; held for human approval)')
+    .argument('<id>', 'monitor id')
+    .action(async (id) => {
+      try {
+        auth.requireAuth();
+        const agentName = await actingAgent();
+        if (agentName) { await agentTool(agentName, 'monitors resume', 'kuma_monitor_resume', { id: wholeId('monitors resume', id) }, () => `resumed monitor ${id}`); return; }
+        const ep = resolveEndpoint('mon.kuma.monitors.resume', { id });
+        let data;
+        try { data = await client.post(ep.path, { service: ep.service, body: {} }); } catch (err) { throw monFail('resume', ep, err, id); }
+        reportWrite('resume', ep, data, (d) => `resumed ${d.name || `monitor ${id}`}`);
+      } catch (err) { fail(err); }
+    });
+
+  monitors
+    .command('remove')
+    .description('Delete a monitor (org admin; held for human approval)')
+    .argument('<id>', 'monitor id')
+    .action(async (id) => {
+      try {
+        auth.requireAuth();
+        const agentName = await actingAgent();
+        if (agentName) { await agentTool(agentName, 'monitors remove', 'kuma_monitor_delete', { id: wholeId('monitors remove', id) }, () => `removed monitor ${id}`); return; }
+        const ep = resolveEndpoint('mon.kuma.monitors.delete', { id });
+        let data;
+        try { data = await client.delete(ep.path, { service: ep.service }); } catch (err) { throw monFail('remove', ep, err, id); }
+        reportWrite('remove', ep, data, (d) => `removed ${d.name || `monitor ${id}`}`);
+      } catch (err) { fail(err); }
+    });
+
+  // ---- incidents + alert hooks (NQ-KUMA-4) ----
+  const ageOf = (s) => {
+    if (s === null || s === undefined) return '-';
+    if (s < 60) return `${s}s`;
+    if (s < 3600) return `${Math.floor(s / 60)}m`;
+    return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+  };
+  const hookFail = (verb, ep, err, id) => {
+    const status = err && (err.status ?? err.statusCode);
+    const code = err && err.body && err.body.error_code;
+    const msg = (err && err.message) || String(err);
+    const head = `quox kuma ${verb}: ${ep.method} ${ep.path} failed${status ? ` with HTTP ${status}` : ''}`;
+    if (status === 403 && (code === 'admin_required' || /admin role required/i.test(msg))) return new KumaFail(`${head}: managing alert hooks needs an org admin or owner.`);
+    if (status === 404) return new KumaFail(`${head}: no such hook${id ? ` (${id})` : ''} in this org. List them with \`quox kuma hooks list\`.`);
+    return new KumaFail(`${head}: ${msg}`);
+  };
+
+  kuma
+    .command('incidents')
+    .description('Kuma alerts that became Quox incidents: when down, when back, how long')
+    .option('--open', 'only outages still going')
+    .option('--limit <n>', 'max rows (default 50, max 200)')
+    .action(guard('incidents', async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.kuma.incidents.list', { open: !!options.open, limit: options.limit });
+      let data;
+      try { data = await client.get(ep.path, { service: ep.service }); } catch (err) { throw hookFail('incidents', ep, err); }
+      if (!data || data.success === false || data.error || !Array.isArray(data.incidents)) {
+        throw new KumaFail(`quox kuma incidents: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no incidents array'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const openN = data.incidents.filter((i) => i.open).length;
+      console.log(glyphLine('kuma', 'incidents', { result: `${data.incidents.length} shown · ${openN} open`, status: openN ? 'warn' : 'ok' }));
+      if (!data.incidents.length) return;
+      // Relative times (the ISO stays in --json). The OPENED cell is one token (2h35m) so the table columns stay scannable.
+      const now = Date.now();
+      const sinceOpen = (i) => { const t = Date.parse(i.opened_at); return Number.isFinite(t) ? relDuration(now - t) : null; };
+      const rows = [['STATE', 'MONITOR', 'TARGET', 'OPENED AGO', 'DURATION', 'EVENTS', 'LAST MESSAGE']];
+      for (const i of data.incidents) {
+        const ago = sinceOpen(i);
+        const downFor = i.close_reason === 'monitor_deleted' ? 'closed: monitor deleted' : i.open ? (ago ? `ongoing, down for ${ago}` : 'ongoing') : ageOf(i.duration_s);
+        rows.push([i.open ? 'DOWN' : (i.close_reason === 'monitor_deleted' ? 'closed' : 'resolved'), i.monitor_name || i.monitor_id, i.target || '-', ago ? `${ago.replace(/ /g, '')}` : (i.opened_at || '-'), downFor, i.events ?? '-', i.last_msg || '-']);
+      }
+      console.log(pad(rows).join('\n'));
+      // NQ-KUMA-5: the why, under the table, for every incident VIGIL has looked at.
+      const diagnosed = data.incidents.filter((i) => i.diagnosis && i.diagnosis.summary);
+      if (diagnosed.length) {
+        console.log('');
+        const width = Math.max(40, process.stdout.columns || 100);
+        for (const i of diagnosed) {
+          const head = `why  ${i.id}  `;
+          const tag = `  [${i.diagnosis.verdict}]`;
+          const full = `${head}${i.diagnosis.summary}${tag}`;
+          if ([...full].length <= width) { console.log(full); continue; }
+          const lines = wrapText(`${i.diagnosis.summary}${tag}`, width - head.length);
+          lines.forEach((l, n) => console.log(n === 0 ? `${head}${l}` : `${' '.repeat(head.length)}${l}`));
+        }
+      }
+    }));
+
+  const printDiagnosis = (d, verb) => {
+    console.log(glyphLine('kuma', verb, { result: d.verdict, status: d.verdict === 'not_reproducible' ? 'warn' : 'fail' }));
+    console.log(d.summary);
+    const insideNote = {
+      ran: `inside checks ran on ${d.inside && d.inside.host}`,
+      no_host: 'outside-in only (the target is not a managed fleet host)',
+      needs_approval: 'outside-in only (host checks need a human approval)',
+      refused: 'outside-in only (the fleet boundary refused the host checks)',
+      unavailable: 'outside-in only (the fleet boundary was not available)',
+    }[d.inside && d.inside.status] || '';
+    if (insideNote) console.log(insideNote);
+    const rows = [['CHECK', 'OK', 'MS', 'DETAIL']];
+    for (const c of d.checks || []) rows.push([c.name, c.ok ? 'yes' : 'NO', c.ms, c.detail]);
+    if (rows.length > 1) { console.log(''); console.log(pad(rows).join('\n')); }
+  };
+
+  kuma
+    .command('diagnose')
+    .description('Why is it down: outside-in checks (DNS, TCP, HTTP, TLS, keyword) plus read-only host checks when the target is a managed fleet host')
+    .argument('[incidentId]', 'incident id from `quox kuma incidents`')
+    .option('--monitor <id>', 'diagnose the newest open incident of this monitor')
+    .action(guard('diagnose', async (incidentId, options) => {
+      auth.requireAuth();
+      if (!incidentId && !options.monitor) throw new KumaFail('quox kuma diagnose: give an incident id (quox kuma incidents) or --monitor <id>.');
+      const ep = resolveEndpoint('mon.kuma.diagnose.create');
+      const body = incidentId ? { incident_id: incidentId } : { monitor_id: String(options.monitor) };
+      let data;
+      try { data = await client.post(ep.path, { service: ep.service, body }); } catch (err) {
+        const status = err && (err.status ?? err.statusCode);
+        if (status === 404) throw new KumaFail(`quox kuma diagnose: ${ep.method} ${ep.path} failed with HTTP 404: no such incident${incidentId ? ` (${incidentId})` : ` for monitor ${options.monitor}`} in this org. List them with \`quox kuma incidents\`.`);
+        throw hookFail('diagnose', ep, err);
+      }
+      if (!data || data.success === false || data.error || !data.diagnosis) {
+        throw new KumaFail(`quox kuma diagnose: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no diagnosis'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      printDiagnosis(data.diagnosis, 'diagnose');
+    }));
+
+  // ---- coverage audit (NQ-KUMA-6) ----
+  const coverage = kuma
+    .command('coverage')
+    .description('What is not watched: fleet hosts, verified domains and the Quox URL against your Kuma monitors ("9 of 14 watched")');
+
+  const UNWATCHED_CAP = 20;
+  coverage.option('--all', 'list every unwatched item (default: the first 20)');
+  example(coverage
+    .command('show', { isDefault: true })
+    .description('The coverage audit: watched, unwatched, orphan monitors')
+    .option('--all', 'list every unwatched item (default: the first 20)')
+    .action(guard('coverage', async (options, cmd) => {
+      const showAll = Boolean((options && options.all) || coverage.opts().all);
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.kuma.coverage.get');
+      let data;
+      try { data = await client.get(ep.path, { service: ep.service }); } catch (err) { throw hookFail('coverage', ep, err); }
+      if (!data || data.success === false || data.error || !Array.isArray(data.unwatched)) {
+        throw new KumaFail(`quox kuma coverage: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no coverage'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(glyphLine('kuma', 'coverage', { result: data.headline, status: data.unwatched.length || data.partial ? 'warn' : 'ok' }));
+      for (const e of data.sourceErrors || []) console.log(`could not read ${e.source}: ${e.error}`);
+      if (data.unwatched.length) {
+        console.log('');
+        console.log('NOT WATCHED');
+        const shown = showAll ? data.unwatched : data.unwatched.slice(0, UNWATCHED_CAP);
+        console.log(pad([['KIND', 'NAME', 'ADDRESS', 'SUGGESTED'], ...shown.map((i) => [i.kind, i.name, i.address, `${i.suggested.type} ${i.suggested.url || i.suggested.hostname}`])]).join('\n'));
+        if (shown.length < data.unwatched.length) console.log(`and ${data.unwatched.length - shown.length} more (quox kuma coverage --all)`);
+        console.log('Cover them: quox kuma coverage propose <name...>   (each one waits for a human approval)');
+      }
+      if (Array.isArray(data.invalid) && data.invalid.length) {
+        console.log('');
+        console.log('BAD INVENTORY ADDRESS (cannot be monitored; fix the host record, nothing is suggested)');
+        console.log(pad([['KIND', 'NAME', 'ADDRESS', 'WHY'], ...data.invalid.map((i) => [i.kind, i.name, i.address || '-', i.reason])]).join('\n'));
+      }
+      if (data.watched.length) {
+        console.log('');
+        console.log('WATCHED');
+        console.log(pad([['KIND', 'NAME', 'MONITORS'], ...data.watched.map((i) => [i.kind, i.name, i.monitors.map((m) => m.name).join(', ')])]).join('\n'));
+      }
+      if (data.orphans.length) {
+        console.log('');
+        console.log('MONITORS MATCHING NOTHING IN THE INVENTORY (informational)');
+        console.log(pad([['ID', 'NAME', 'TYPE', 'TARGET'], ...data.orphans.map((m) => [m.id, m.name, m.type, m.target || '-'])]).join('\n'));
+      }
+    })), 'quox kuma coverage --all');
+
+  example(coverage
+    .command('propose')
+    .description('File an approval-gated add request for each named unwatched item (org admin; nothing is added until approved)')
+    .argument('<name...>', 'item names from `quox kuma coverage`')
+    .option('--dry-run', 'only list what would be proposed')
+    .action(async (names, options) => {
+      try {
+        auth.requireAuth();
+        const agentName = await actingAgent();
+        const ep = resolveEndpoint('mon.kuma.coverage.propose');
+        let data;
+        if (agentName) {
+          // kuma_coverage_propose files one approval per item itself; its result has the route's shape.
+          const t = await client.post(resolveEndpoint('v1.tools.execute').path, { service: 'collector', body: { tool_name: 'kuma_coverage_propose', input: { items: names, ...(options.dryRun ? { dry_run: true } : {}) }, org_id: resolveOrgId(auth, program) } });
+          if (execResultFailed(t) || !t || t.error) throw new KumaFail(`quox kuma coverage propose: kuma_coverage_propose as ${agentName} failed: ${(t && (t.error || t.message || t.error_code)) || 'tool reported failure'}`);
+          data = t;
+        } else {
+          try { data = await client.post(ep.path, { service: ep.service, body: { items: names, ...(options.dryRun ? { dry_run: true } : {}) } }); } catch (err) { throw hookFail('coverage propose', ep, err); }
+        }
+        if (!data || data.success === false || data.error) throw new KumaFail(`quox kuma coverage propose: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'no body'}`);
+        if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+        if (data.dryRun) {
+          console.log(glyphLine('kuma', 'coverage propose', { result: `dry run: ${(data.would_propose || []).length} would be proposed`, status: 'ok' }));
+          for (const i of data.would_propose || []) console.log(`${i.kind}  ${i.name}  ->  ${i.suggested.type} ${i.suggested.url || i.suggested.hostname}`);
+        } else {
+          const n = (data.proposals || []).filter((p) => p.status === 'awaiting_approval').length;
+          console.log(glyphLine('kuma', 'coverage propose', { result: `${n} awaiting approval`, status: n ? 'ok' : 'warn' }));
+          for (const p of data.proposals || []) console.log(`${p.name}  ${p.status}${p.approval_id ? `  (${p.approval_id})` : ''}${p.error ? `  ${p.error}` : ''}`);
+          if (n) console.log('Approve them in the inbox; nothing is monitored until you do.');
+        }
+        if (data.truncated) console.log(`Capped at ${data.cap} per call; run it again for the rest.`);
+        for (const r of data.refusedBadAddress || []) console.log(`Refused ${r.name}: ${r.reason} (${r.address || 'no address'}). Fix the inventory record first.`);
+        if ((data.notUnwatched || []).length) console.log(`Not on the unwatched list (already watched or unknown): ${data.notUnwatched.join(', ')}`);
+      } catch (err) { fail(err); }
+    }), 'quox kuma coverage propose cache01 --dry-run');
+  // NQ-KUMA-7: quox kuma sla [list|verify]
+  registerKumaSla(kuma, { client, auth, jsonOut, guard, KumaFail, pad });
+
+  // ---- maintenance windows + customer-safe status-page incidents (NQ-KUMA-8) ----
+  // Like the monitor writes, these actions are not wrapped in guard(): the leaf-methods scanner reads each
+  // handler's own source, so every mutating client call stays visible in its action.
+  function p8Fail(verb, ep, err) {
+    const status = err && (err.status ?? err.statusCode);
+    const body = (err && err.body) || {};
+    const code = body.error_code || body.code || (err && err.code);
+    const msg = body.error || (err && err.message) || String(err);
+    const head = `quox kuma ${verb}: ${ep.method} ${ep.path} failed${status ? ` with HTTP ${status}` : ''}`;
+    if (status === 403 && (code === 'admin_required' || /admin role required/i.test(msg))) return new KumaFail(`${head}: this needs an org admin or owner.`);
+    if (status === 404) return new KumaFail(`${head}: ${msg}`);
+    if (status === 422 || code === 'not_configured') return new KumaFail(`${head}: Uptime Kuma admin access is not configured for this org (${msg}).`);
+    return new KumaFail(`${head}: ${msg}`);
+  }
+  function p8Report(verb, ep, data, okLine) {
+    if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+    if (data && data.status === 'awaiting_approval') {
+      const id = data.approval_id || 'unknown';
+      console.log(`◐ awaiting approval ${id}: approve in the inbox${data.inbox_item_id ? ` (item ${data.inbox_item_id})` : ''}, then check with \`quox approvals result ${id}\``);
+      return;
+    }
+    if (!data || data.success === false || data.error) throw new KumaFail(`quox kuma ${verb}: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'no body'}`);
+    console.log(glyphLine('kuma', verb, { result: okLine(data), status: 'ok' }));
+  }
+
+  const maintenance = kuma
+    .command('maintenance')
+    .description('Maintenance windows: planned work does not page people (open and end are org admin, human approved)')
+    .addHelpText('after', '\nDeploy hook (one line, before the deploy; the window still waits for a human approval):\n'
+      + '  quox kuma maintenance open --for 15 --monitors all --title "Deploy"\n'
+      + 'Monitors: all, a comma list of monitor ids (3,7), or tag:<name>. A window is at most 1440 minutes.\n'
+      + 'End early: quox kuma maintenance end <id>   (ids from `quox kuma maintenance list`)');
+
+  maintenance
+    .command('list', { isDefault: true })
+    .description('The maintenance windows: id, status, start, end')
+    .action(guard('maintenance list', async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.kuma.maintenance.list');
+      let data;
+      try { data = await client.get(ep.path, { service: ep.service }); } catch (err) { throw p8Fail('maintenance list', ep, err); }
+      if (!data || data.success === false || data.error || !Array.isArray(data.windows)) {
+        throw new KumaFail(`quox kuma maintenance list: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no windows array'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(glyphLine('kuma', 'maintenance list', { result: `${data.windows.length} windows`, status: 'ok' }));
+      if (!data.windows.length) return;
+      // Times in UTC. Kuma returns server-local strings: converted when the zone is known, labelled "Kuma server time" when not.
+      const tzOf = (w) => w.timezone || data.timezone || null;
+      console.log(pad([['ID', 'STATE', 'TITLE', 'START', 'END'], ...data.windows.map((w) => [w.id ?? '-', w.state || w.status || (w.active === false ? 'inactive' : '-'), w.title || '-', fmtWhen(w.start, tzOf(w)), fmtWhen(w.end, tzOf(w))])]).join('\n'));
+    }));
+
+  maintenance
+    .command('open')
+    .description('Open a one-off window over monitors for N minutes (org admin; held for human approval)')
+    .requiredOption('--title <text>', 'window title')
+    .requiredOption('--for <minutes>', 'how long, in minutes from now (1..1440)')
+    .requiredOption('--monitors <list>', 'all | comma list of monitor ids | tag:<name>')
+    .option('--start <iso>', 'start at this ISO time instead of now')
+    .action(async (options) => {
+      try {
+        auth.requireAuth();
+        if (!/^\d+$/.test(String(options.for))) throw new KumaFail(`quox kuma maintenance open: --for needs a whole number of minutes, got "${options.for}"`);
+        const sel = String(options.monitors).trim();
+        let monitors;
+        if (sel === 'all') monitors = 'all';
+        else if (/^tag:./.test(sel)) monitors = { tag: sel.slice(4) };
+        else if (/^\d+(,\d+)*$/.test(sel)) monitors = sel.split(',').map(Number);
+        else throw new KumaFail(`quox kuma maintenance open: --monitors must be all, a comma list of ids (3,7) or tag:<name>, got "${sel}"`);
+        const body = { title: options.title, minutes: Number(options.for), monitors, ...(options.start ? { start: options.start } : {}) };
+        const agentName = await actingAgent();
+        if (agentName) { await agentTool(agentName, 'maintenance open', 'kuma_maintenance_open', body, () => `window open for ${options.for} minutes`); return; }
+        const ep = resolveEndpoint('mon.kuma.maintenance.open');
+        let data;
+        try { data = await client.post(ep.path, { service: ep.service, body }); } catch (err) { throw p8Fail('maintenance open', ep, err); }
+        p8Report('maintenance open', ep, data, (d) => `window ${d.maintenance && d.maintenance.id != null ? d.maintenance.id : ''} open for ${options.for} minutes over ${d.maintenance && d.maintenance.monitor_ids ? plural(d.maintenance.monitor_ids.length, 'monitor') : '? monitors'}`);
+      } catch (err) { fail(err); }
+    });
+
+  maintenance
+    .command('end')
+    .description('End a maintenance window early (org admin; held for human approval)')
+    .argument('<id>', 'window id from `quox kuma maintenance list`')
+    .action(async (id) => {
+      try {
+        auth.requireAuth();
+        const agentName = await actingAgent();
+        if (agentName) { await agentTool(agentName, 'maintenance end', 'kuma_maintenance_end', { id: wholeId('maintenance end', id) }, () => `window ${id} ended`); return; }
+        const ep = resolveEndpoint('mon.kuma.maintenance.end', { id });
+        let data;
+        try { data = await client.post(ep.path, { service: ep.service, body: {} }); } catch (err) { throw p8Fail('maintenance end', ep, err); }
+        p8Report('maintenance end', ep, data, () => `window ${id} ended`);
+      } catch (err) { fail(err); }
+    });
+
+  const statusIncident = kuma
+    .command('status-incident')
+    .description('Customer-safe status-page comms for an outage: draft, publish, resolve (publish and resolve are org admin, human approved)');
+
+  /** --slug, else the first configured status page. */
+  async function slugOrDefault(verb, slug) {
+    if (slug) return slug;
+    return (await configuredSlugs(verb))[0];
+  }
+
+  statusIncident
+    .command('draft')
+    .description('The plain-words notice for an incident (no hostnames, IPs or internal detail); nothing is posted')
+    .argument('<incidentId>', 'incident id from `quox kuma incidents`')
+    .action(guard('status-incident draft', async (incidentId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.kuma.statusIncident.draft', { id: incidentId });
+      let data;
+      try { data = await client.get(ep.path, { service: ep.service }); } catch (err) { throw p8Fail('status-incident draft', ep, err); }
+      if (!data || data.success === false || data.error || !data.draft) {
+        throw new KumaFail(`quox kuma status-incident draft: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no draft'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(glyphLine('kuma', 'status-incident draft', { result: `${data.draft.style} · ${data.draft.open ? 'outage' : 'recovered'}`, status: 'ok' }));
+      console.log(`${data.draft.title}\n\n${data.draft.content}\n\nPost it: quox kuma status-incident publish ${incidentId}   (held for a human approval)`);
+    }));
+
+  statusIncident
+    .command('publish')
+    .description('Post the drafted notice to a PUBLIC status page (org admin; held for human approval, HIGH risk)')
+    .argument('<incidentId>', 'incident id from `quox kuma incidents`')
+    .option('--slug <slug>', 'status page slug (default: the first configured page)')
+    .action(async (incidentId, options) => {
+      try {
+        auth.requireAuth();
+        const slug = await slugOrDefault('status-incident publish', options.slug);
+        const agentName = await actingAgent();
+        if (agentName) { await agentTool(agentName, 'status-incident publish', 'kuma_status_incident_publish', { incident_id: incidentId, slug }, () => `posted to ${slug}`); return; }
+        const ep = resolveEndpoint('mon.kuma.statusIncident.publish', { id: incidentId });
+        let data;
+        try { data = await client.post(ep.path, { service: ep.service, body: { slug } }); } catch (err) { throw p8Fail('status-incident publish', ep, err); }
+        p8Report('status-incident publish', ep, data, (d) => `posted to ${slug}${d.status_incident && d.status_incident.title ? `: ${d.status_incident.title}` : ''}`);
+      } catch (err) { fail(err); }
+    });
+
+  statusIncident
+    .command('resolve')
+    .description('Take the pinned notice down from a PUBLIC status page (org admin; held for human approval, HIGH risk)')
+    .option('--slug <slug>', 'status page slug (default: the first configured page)')
+    .action(async (options) => {
+      try {
+        auth.requireAuth();
+        const slug = await slugOrDefault('status-incident resolve', options.slug);
+        const agentName = await actingAgent();
+        if (agentName) { await agentTool(agentName, 'status-incident resolve', 'kuma_status_incident_resolve', { slug }, () => `notice on ${slug} taken down`); return; }
+        const ep = resolveEndpoint('mon.kuma.statusIncident.resolve');
+        let data;
+        try { data = await client.post(ep.path, { service: ep.service, body: { slug } }); } catch (err) { throw p8Fail('status-incident resolve', ep, err); }
+        p8Report('status-incident resolve', ep, data, () => `notice on ${slug} taken down`);
+      } catch (err) { fail(err); }
+    });
+
+  const hooks = kuma
+    .command('hooks')
+    .description('The per-org signed hook Uptime Kuma posts alerts to (list, create, delete; org admin)');
+
+  hooks
+    .command('list')
+    .description('This org\'s alert hooks (never shows secrets)')
+    .action(guard('hooks list', async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.kuma.hooks.list');
+      let data;
+      try { data = await client.get(ep.path, { service: ep.service }); } catch (err) { throw hookFail('hooks list', ep, err); }
+      if (!data || data.success === false || data.error || !Array.isArray(data.hooks)) {
+        throw new KumaFail(`quox kuma hooks list: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no hooks array'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(glyphLine('kuma', 'hooks list', { result: plural(data.hooks.length, 'hook'), status: 'ok' }));
+      if (!data.hooks.length) { console.log('No hooks yet. Create one: quox kuma hooks create'); return; }
+      const rows = [['HOOK', 'LABEL', 'CREATED', 'LAST USED', 'PATH']];
+      for (const h of data.hooks) rows.push([h.hookId, h.label || '-', h.created_at || '-', h.last_used_at || 'never', h.path || '-']);
+      console.log(pad(rows).join('\n'));
+    }));
+
+  hooks
+    .command('create')
+    .description('Create an alert hook; the secret is shown ONCE (org admin)')
+    .option('--label <text>', 'a name for this hook')
+    .action(async (options) => {
+      try {
+        auth.requireAuth();
+        const ep = resolveEndpoint('mon.kuma.hooks.create');
+        let data;
+        try { data = await client.post(ep.path, { service: ep.service, body: options.label ? { label: options.label } : {} }); } catch (err) { throw hookFail('hooks create', ep, err); }
+        if (!data || data.success === false || data.error || !data.hookId || !data.secret) {
+          throw new KumaFail(`quox kuma hooks create: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no hook'}`);
+        }
+        if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+        console.log(glyphLine('kuma', 'hooks create', { result: data.hookId, status: 'ok' }));
+        console.log([
+          `URL path : ${data.path}   (append to your Quox collector base URL)`,
+          `Secret   : ${data.secret}`,
+          '',
+          'The secret is shown ONCE and is stored only as a hash. Copy it now.',
+          '',
+          'Set it up in Uptime Kuma:',
+          '  1. Settings > Notifications > Setup Notification',
+          '  2. Notification Type: Webhook',
+          '  3. Post URL: <collector base URL>' + data.path,
+          '  4. Request Body: Preset - application/json (POST JSON)',
+          '  5. Additional Headers: {"X-Quox-Kuma-Secret": "' + data.secret + '"}',
+          '  6. Save, press Test (answers 200), then enable it on your monitors (or Default enabled).',
+        ].join('\n'));
+      } catch (err) { fail(err); }
+    });
+
+  hooks
+    .command('delete')
+    .description('Delete an alert hook; Kuma posts to it are refused from then on (org admin)')
+    .argument('<hookId>', 'hook id from `quox kuma hooks list`')
+    .action(async (hookId) => {
+      try {
+        auth.requireAuth();
+        const ep = resolveEndpoint('mon.kuma.hooks.delete', { id: hookId });
+        let data;
+        try { data = await client.delete(ep.path, { service: ep.service }); } catch (err) { throw hookFail('hooks delete', ep, err, hookId); }
+        if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+        if (!data || data.success === false || data.error) throw new KumaFail(`quox kuma hooks delete: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'no body'}`);
+        console.log(glyphLine('kuma', 'hooks delete', { result: `deleted ${hookId}`, status: 'ok' }));
+      } catch (err) { fail(err); }
+    });
+
+  // Every verb's --help carries one example line (the ones above were added inline).
+  const EXAMPLES = {
+    monitors: 'quox kuma monitors list',
+    'monitors list': 'quox kuma monitors list',
+    'monitors get': 'quox kuma monitors get 4',
+    'monitors add': 'quox kuma monitors add --name api --type http --url https://api.example.test',
+    'monitors edit': 'quox kuma monitors edit 4 --interval 60',
+    'monitors pause': 'quox kuma monitors pause 4',
+    'monitors resume': 'quox kuma monitors resume 4',
+    'monitors remove': 'quox kuma monitors remove 4',
+    incidents: 'quox kuma incidents --open',
+    diagnose: 'quox kuma diagnose --monitor 7',
+    coverage: 'quox kuma coverage',
+    sla: 'quox kuma sla --month 2026-09',
+    'sla list': 'quox kuma sla list',
+    'sla verify': 'quox kuma sla verify <report-id>',
+    maintenance: 'quox kuma maintenance list',
+    'maintenance list': 'quox kuma maintenance list',
+    'maintenance open': 'quox kuma maintenance open --for 15 --monitors all --title "Deploy"',
+    'maintenance end': 'quox kuma maintenance end 5',
+    'status-incident': 'quox kuma status-incident draft <incident-id>',
+    'status-incident draft': 'quox kuma status-incident draft <incident-id>',
+    'status-incident publish': 'quox kuma status-incident publish <incident-id>',
+    'status-incident resolve': 'quox kuma status-incident resolve',
+    hooks: 'quox kuma hooks list',
+    'hooks list': 'quox kuma hooks list',
+    'hooks create': 'quox kuma hooks create --label alerts',
+    'hooks delete': 'quox kuma hooks delete <hook-id>',
+  };
+  (function addExamples(cmd, path) {
+    for (const c of cmd.commands) {
+      const key = [...path, c.name()].join(' ');
+      if (!exampled.has(c) && EXAMPLES[key]) example(c, EXAMPLES[key]);
+      addExamples(c, [...path, c.name()]);
+    }
+  }(kuma, []));
+
+}