quoxcli 0.4.0 → 0.6.0

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',

package/lib/commands/licenceLinkView.js

@@ -0,0 +1,311 @@
+/**
+ * QUOXON (owner 2026-11-05): the render layer for `quox setup license link`.
+ *
+ * The owner linked the wrong licence twice in one day (one granting 0
+ * plugins) because neither the web page nor the CLI said what was being
+ * picked. This view frames the code and link, counts the code down live,
+ * and on approval names WHAT was linked: licence id, plan, plugins, seats.
+ *
+ * Everything here is pure (strings in, strings out) so it is testable without
+ * a terminal. Colour comes from the house QuoxGlyph module (lib/core/
+ * quoxglyph.js: line grammar, brand gradient, status colours) and the spinner
+ * frames from the TUI's house spinner; nothing here invents a parallel style.
+ * With colour off every function returns plain lines with no escape codes.
+ */
+
+import { line, setColor, GRAD, STATUS, celebrate } from '../core/quoxglyph.js';
+import { SPIN_FRAMES } from '../quoxon/slashSpinner.js';
+import { motionAllowed } from '../quoxon/motion/clock.js';
+
+const R = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const UNDERLINE = '\x1b[4m';
+const fg = ([r, g, b]) => `\x1b[38;2;${r};${g};${b}m`;
+const AMBER = STATUS.warn.rgb;
+const GREEN = STATUS.ok.rgb;
+
+// eslint-disable-next-line no-control-regex
+const ESC = /\x1b\]8;;[^\x07]*\x07|\x1b\[[0-9;]*[A-Za-z]/g;
+/** Visible width: escape codes stripped, one column per code point. */
+const vis = (s) => [...String(s).replace(ESC, '')].length;
+const padTo = (s, w) => s + ' '.repeat(Math.max(0, w - vis(s)));
+
+/** Run a QuoxGlyph render with colour forced on or off, then hand control back to auto. */
+function withColor(color, fn) {
+  setColor(color);
+  try { return fn(); } finally { setColor(null); }
+}
+
+/** Should this terminal get colour? Same rule as quoxglyph, decided for an injected stream. */
+export function colorFor(term, env = process.env) {
+  if (env.QUOX_COLOR === '0') return false;
+  if (env.QUOX_COLOR === '1' || env.QUOX_COLOR === '2') return true;
+  return Boolean(term && term.isTTY) && !env.NO_COLOR;
+}
+
+/** Should the waiting line animate? TTY only, and never under reduced motion. */
+export const animateFor = (term, env = process.env) => motionAllowed(Boolean(term && term.isTTY), env);
+
+/** m:ss, floored at 0:00. */
+export function fmtCountdown(ms) {
+  const total = Math.max(0, Math.floor(Number(ms) / 1000) || 0);
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
+}
+
+/** WQXP-7T4K -> "W Q X P - 7 T 4 K". */
+export const spacedCode = (code) => [...String(code || '')].join(' ');
+
+/** Paint text in the brand gradient (per visible character), bold. */
+function gradient(text) {
+  const chars = [...text];
+  const last = Math.max(1, chars.length - 1);
+  return BOLD + chars.map((ch, i) => (ch === ' ' ? ch
+    : fg(GRAD[0].map((v, k) => Math.round(v + (GRAD[1][k] - v) * (i / last)))) + ch)).join('') + R;
+}
+
+/** ▰▰▰▱▱ in the brand gradient, for a 0..1 ratio. */
+function bar(ratio, width = 10) {
+  const filled = Math.max(0, Math.min(width, Math.round(ratio * width)));
+  const last = Math.max(1, width - 1);
+  let out = '';
+  for (let i = 0; i < filled; i++) out += fg(GRAD[0].map((v, k) => Math.round(v + (GRAD[1][k] - v) * (i / last)))) + '▰';
+  return out + (filled ? R : '') + DIM + '▱'.repeat(width - filled) + R;
+}
+
+/** OSC 8 hyperlink whose visible text is the full URL, so it is clickable either way. */
+const hyperlink = (url) => `\x1b]8;;${url}\x07${UNDERLINE}${fg(GRAD[0])}${url}${R}\x1b]8;;\x07`;
+
+/**
+ * A rounded frame around rows (already styled). The title sits in the top
+ * border. The frame grows to fit its widest row (a URL is never clipped).
+ */
+function frame(rows, { title = '', cols = 80, tint = null } = {}) {
+  const b = (s) => (tint ? fg(tint) + s + R : DIM + s + R);
+  const titleText = title ? ` ${title} ` : '';
+  const inner = Math.max(44, Math.min(Math.max(44, cols - 6), 76), ...rows.map((r) => vis(r) + 4), vis(titleText) + 4);
+  const top = b('╭─') + titleText + b('─'.repeat(Math.max(0, inner - 1 - vis(titleText))) + '╮');
+  const body = rows.map((r) => b('│') + padTo(`  ${r}`, inner) + b('│'));
+  const bottom = b('╰' + '─'.repeat(inner) + '╯');
+  return [top, ...body, bottom].map((l) => `  ${l}`).join('\n');
+}
+
+/** Greedy wrap of items into lines no wider than `width`, joined by `sep`. */
+function wrapList(items, width, sep = ' · ') {
+  const lines = [];
+  let cur = '';
+  for (const item of items) {
+    const next = cur ? cur + sep + item : item;
+    if (cur && vis(next) > width) { lines.push(cur); cur = item; } else cur = next;
+  }
+  if (cur) lines.push(cur);
+  return lines;
+}
+
+const minutes = (ms) => Math.max(1, Math.round(ms / 60000));
+
+/**
+ * The card shown while the code waits for approval.
+ * @param {{userCode:string,url:string,remainingMs:number,color:boolean,cols?:number}} o
+ */
+export function renderLinkCard({ userCode, url, remainingMs, color, cols = 80 }) {
+  const header = withColor(color, () => line('quox', 'licence link', { result: 'approve on quox.ai', status: 'busy' }));
+  if (!color) {
+    return [
+      header,
+      `Open ${url} and enter this code:`,
+      '',
+      `    ${userCode}`,
+      '',
+      `The code is good for ${minutes(remainingMs)} minutes.`,
+      'Pick the licence you want on quox.ai: this instance gets exactly what you approve.',
+      'Waiting for approval...',
+    ].join('\n');
+  }
+  const label = (s) => `${DIM}${s.padEnd(11)}${R}`;
+  const rows = [
+    '',
+    `${label('Your code')}${gradient(spacedCode(userCode))}`,
+    '',
+    `${label('Open')}${hyperlink(url)}`,
+    `${label('Expires in')}${bar(1)} ${BOLD}${fmtCountdown(remainingMs)}${R}`,
+    '',
+    `${fg(AMBER)}Pick the licence you want on quox.ai.${R}`,
+    `${DIM}This instance gets exactly what you approve.${R}`,
+  ];
+  return [header, frame(rows, { title: `${BOLD}Link this instance${R}`, cols })].join('\n');
+}
+
+/**
+ * One frame of the live waiting line (TTY only): spinner, label, countdown.
+ * @param {{frame:number,remainingMs:number,totalMs?:number,color:boolean,note?:string}} o
+ */
+export function renderWaitingLine({ frame: i, remainingMs, totalMs = 600000, color, note = '' }) {
+  const spin = SPIN_FRAMES[i % SPIN_FRAMES.length];
+  const left = `${fmtCountdown(remainingMs)} left`;
+  const extra = note ? ` · ${note}` : '';
+  if (!color) return `${spin} Waiting for approval on quox.ai · ${left}${extra}`;
+  const ratio = totalMs > 0 ? remainingMs / totalMs : 0;
+  const tone = ratio < 0.2 ? fg(AMBER) : '';
+  return `  ${fg(GRAD[0])}${spin}${R} Waiting for approval on quox.ai ${DIM}│${R} ${bar(ratio)} ${tone}${BOLD}${left}${R}${note ? `${DIM}${extra}${R}` : ''}`;
+}
+
+const bareId = (raw) => String(raw).split('@')[0];
+const orgAllowance = (raw) => {
+  const m = /@orgs=(\d+)/.exec(String(raw));
+  return m ? Number(m[1]) : null;
+};
+
+/**
+ * What was linked, from the approved lease plus the read-back of
+ * GET /api/setup/licensing/entitlements (the route `quox licence status`
+ * reads). The read-back wins where it has the licence; the lease is the
+ * fallback, so a failed read never hides what was activated.
+ *
+ * @returns {{license_id, plans:string[], entitlements:string[], seats:Array<{plugin,used,total}>, warnings:string[], servers?:{used,total}}}
+ */
+export function linkedDetails(lease = {}, status = null, poll = {}) {
+  const id = lease.license_id || null;
+  const row = (status && Array.isArray(status.licenses))
+    ? status.licenses.find((l) => l && l.license_id === id) : null;
+
+  let rawEntitlements;
+  let plans;
+  if (row) {
+    rawEntitlements = row.entitlements || [];
+    plans = row.plans || [];
+  } else {
+    const raw = lease.entitlements || [];
+    plans = raw.filter((e) => String(e).toLowerCase().startsWith('plan.')).map((e) => bareId(e).slice(5).toLowerCase()).filter(Boolean);
+    rawEntitlements = raw.filter((e) => !String(e).toLowerCase().startsWith('plan.'));
+  }
+
+  const bands = (status && status.org_bands && typeof status.org_bands === 'object') ? status.org_bands : {};
+  const entitlements = [...new Set(rawEntitlements.map(bareId))];
+  const seats = [];
+  for (const raw of rawEntitlements) {
+    const plugin = bareId(raw);
+    const band = bands[plugin];
+    if (band) seats.push({ plugin, used: Number(band.assigned_count ?? 0), total: Number(band.allowance ?? 0) });
+    else if (orgAllowance(raw) != null) seats.push({ plugin, used: null, total: orgAllowance(raw) });
+  }
+
+  const out = { license_id: id, plans, entitlements, seats, warnings: entitlements.length === 0 ? ['zero_entitlements'] : [] };
+  // Server seats travel only when the poll response carries them (the
+  // control plane sends max_servers and bound; additive, never guessed).
+  if (poll && poll.max_servers != null) {
+    out.servers = { used: Array.isArray(poll.bound) ? poll.bound.length : null, total: Number(poll.max_servers) };
+  }
+  return out;
+}
+
+const seatText = (s) => (s.used == null ? `${s.plugin} up to ${s.total} orgs` : `${s.plugin} ${s.used} of ${s.total} orgs`);
+const leaseText = (iso) => {
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? new Date(t).toISOString().slice(0, 16).replace('T', ' ') + ' UTC' : null;
+};
+
+/** The exact command that unlinks this licence and starts a fresh link. */
+export function relinkCommand(licenseId, profile) {
+  const q = profile ? `quox -p ${profile}` : 'quox';
+  return `${q} setup license deactivate --license-id ${licenseId} --yes && ${q} setup license link`;
+}
+
+/**
+ * The result after approval: compact, celebratory when the licence grants
+ * something, amber with the one fix command when it grants nothing.
+ * @param {ReturnType<typeof linkedDetails>} d
+ * @param {{color:boolean, cols?:number, leaseExpiresAt?:string, profile?:string, readBackError?:string}} o
+ */
+export function renderLinkedCard(d, { color, cols = 80, leaseExpiresAt = null, profile = null, readBackError = null } = {}) {
+  const zero = d.warnings.includes('zero_entitlements');
+  const header = withColor(color, () => (zero
+    ? line('quox', 'licence linked', { result: 'grants 0 plugins', status: 'warn' })
+    : line('quox', 'licence linked', { result: color ? celebrate('instance activated') : 'instance activated', status: 'ok', max: 400 })));
+  const plan = d.plans.length ? d.plans.join(', ') : '(none on this licence)';
+  const renews = leaseText(leaseExpiresAt);
+  const fix = relinkCommand(d.license_id, profile);
+  const warnText = 'This licence grants 0 plugins, so nothing unlocks. You may have picked the wrong licence on quox.ai.';
+  const readBack = readBackError
+    ? `Could not read the licence details back (${readBackError}). Showing what the lease carried; run \`quox licence status\` to check.`
+    : null;
+
+  if (!color) {
+    const out = [header];
+    if (readBack) out.push(readBack);
+    out.push(`Licence: ${d.license_id}`);
+    out.push(`Plan: ${plan}`);
+    out.push(`Plugins (${d.entitlements.length}): ${d.entitlements.join(', ') || 'none'}`);
+    if (d.seats.length) out.push(`Seats: ${d.seats.map(seatText).join(', ')}`);
+    if (d.servers) out.push(`Servers: ${d.servers.used ?? '?'} of ${d.servers.total} in use`);
+    if (renews) out.push(`Lease renews by: ${renews}`);
+    if (zero) {
+      out.push(`⚠ ${warnText}`);
+      out.push('Unlink it and link the right one:');
+      out.push(`    ${fix}`);
+    } else {
+      out.push('This instance is activated. No key was ever pasted into it.');
+    }
+    return out.join('\n');
+  }
+
+  const label = (s) => `${DIM}${s.padEnd(10)}${R}`;
+  const width = Math.min(Math.max(44, cols - 6), 76) - 14;
+  const rows = [
+    `${label('Licence')}${BOLD}${d.license_id}${R}`,
+    `${label('Plan')}${d.plans.length ? gradient(plan) : `${DIM}${plan}${R}`}`,
+  ];
+  if (zero) {
+    rows.push(`${label('Plugins')}${fg(AMBER)}${BOLD}0${R}${fg(AMBER)} entitled${R}`);
+  } else {
+    const list = wrapList(d.entitlements, width);
+    rows.push(`${label('Plugins')}${BOLD}${d.entitlements.length}${R} ${DIM}entitled${R}`);
+    for (const l of list) rows.push(`${' '.repeat(10)}${fg(GREEN)}${l}${R}`);
+  }
+  for (const [n, s] of d.seats.entries()) {
+    const ratio = s.used == null || !s.total ? 0 : s.used / s.total;
+    const text = s.used == null ? `up to ${s.total} orgs` : `${s.used} of ${s.total} orgs`;
+    rows.push(`${label(n === 0 ? 'Seats' : '')}${s.plugin} ${bar(ratio, 6)} ${text}`);
+  }
+  if (d.servers) rows.push(`${label('Servers')}${d.servers.used ?? '?'} of ${d.servers.total} in use`);
+  if (renews) rows.push(`${label('Lease')}${DIM}renews by ${renews}${R}`);
+
+  const title = zero
+    ? `${fg(AMBER)}${BOLD}${STATUS.warn.glyph} Linked, but it grants 0 plugins${R}`
+    : `${fg(GREEN)}${BOLD}${STATUS.ok.glyph} Licence linked${R}`;
+  const out = [header];
+  if (readBack) out.push(`  ${fg(AMBER)}${readBack}${R}`);
+  out.push(frame(rows, { title, cols, tint: zero ? AMBER : GREEN }));
+  if (zero) {
+    out.push(`  ${fg(AMBER)}${BOLD}${STATUS.warn.glyph}${R} ${fg(AMBER)}${warnText}${R}`);
+    out.push(`    ${DIM}Unlink it and link the right one:${R}`);
+    out.push(`    ${BOLD}${fix}${R}`);
+  } else {
+    out.push(`  ${DIM}No key was ever pasted into this instance.${R}`);
+  }
+  return out.join('\n');
+}
+
+/**
+ * The live waiting indicator. On an animating TTY it redraws one line in
+ * place every 80 ms (house spinner pace) with the countdown; with motion off
+ * it draws once. `note()` prints a line above it without tearing the spinner.
+ * `stop()` clears the line. Never used when the stream is not a TTY.
+ */
+export function startWaiting({ term, deadline, totalMs, color, animate, now = () => Date.now(), frameMs = 80 }) {
+  let i = 0;
+  let note = '';
+  const draw = () => {
+    term.write('\r\x1b[2K' + renderWaitingLine({ frame: i++, remainingMs: deadline - now(), totalMs, color, note }));
+  };
+  draw();
+  const timer = animate ? setInterval(draw, frameMs) : null;
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  return {
+    note(text) { note = text; draw(); },
+    stop() {
+      if (timer) clearInterval(timer);
+      term.write('\r\x1b[2K');
+    },
+  };
+}

package/lib/commands/linkedin.js

@@ -4,6 +4,7 @@
  * quox linkedin post "<text>" --as <author_urn> [--visibility PUBLIC|CONNECTIONS] [--link <url>] [--image-url <https url>]
  * quox linkedin comment <post_urn> "<text>" --as <actor_urn>
  * quox linkedin posts <author_urn> [--count <n>]
+ * quox linkedin whoami
  * quox linkedin org <org_id>
  *
  * Both write verbs execute the linkedin connector tools through the governed
@@ -154,6 +155,24 @@ export function registerLinkedInCommands(program, ctx) {
       }
     });
 
+  // ── linkedin me (read) ───────────────────────────────────────────────────
+
+  linkedin
+    .command('whoami')
+    .description('Show the connected member identity and the member URN to use with --as on posts (read-only). Needs the openid and profile scopes on the token.')
+    .action(async () => {
+      const data = await executeLinkedInTool({ client, auth, program }, 'linkedin_get_me', {});
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const me = data.result || {};
+      printSuccess(`${me.name || 'Unknown'} (${me.member_urn || 'no member URN returned'})`);
+      if (me.email) printInfo(`Email: ${me.email}`);
+      if (me.member_urn) printInfo(`Use as author: --as ${me.member_urn}`);
+    });
+
   // ── linkedin org (read) ──────────────────────────────────────────────────
 
   linkedin