quoxcli 0.4.0 → 0.5.0

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

package/lib/commands/loop.js

@@ -29,6 +29,32 @@ function toMs(ts) {
   return Number.isNaN(n) ? null : n;
 }
 
+const LIVE_STATES = new Set(['pending', 'starting', 'decomposing', 'running', 'waiting']);
+
+/**
+ * One row, one vocabulary. The list route counts turn events, which loops driven by the runner never write, so a
+ * finished loop could read 0 there. The server now sends a real 0 (started, ran nothing) and null (no record at
+ * all); a number from the server is kept, null stays unknown unless the loop is live. objective_status is the objective row's word ('cancelled' for a
+ * human halt); `state` is the loop's, so the row says one thing and the raw word is kept as objective_row_status.
+ */
+export function normLoop(l) {
+  const n = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : 0);
+  const count = n(l.turn) || n(l.iteration_count);
+  // the server's turn is authoritative: a real 0 (started, ran nothing) stays 0; only null/absent means unknown
+  const turn = count || (l.turn === 0 || LIVE_STATES.has(l.state) ? 0 : null);
+  const out = { ...l, turn };
+  if (l.objective_status !== undefined && l.state && l.objective_status !== l.state) {
+    out.objective_row_status = l.objective_status;
+    out.objective_status = l.state;
+  }
+  return out;
+}
+
+function turnLabel(l) {
+  if (l.turn === null) return '-';
+  return l.max_turns ? `${l.turn}/${l.max_turns}` : String(l.turn);
+}
+
 const SETTLE_MAX_MS = 90000;
 const SETTLE_POLL_MS = 4000;
 
@@ -149,7 +175,7 @@ function oneLineErr(err) {
 
 export function statusLines(s, { diagnostics = false } = {}) {
   const lines = [];
-  const turns = `turn ${s.turn}${s.max_turns ? `/${s.max_turns}` : ''}`;
+  const turns = `turn ${s.turn === null || s.turn === undefined ? '-' : s.turn}${s.max_turns ? `/${s.max_turns}` : ''}`;
   lines.push(loopLine(s.title || s.objective_id, `${s.state}, ${turns}`, s.state === 'running' ? 'busy' : (s.state === 'completed' ? 'ok' : (s.state === 'completed_with_errors' || s.state === 'halted' || s.state === 'interrupted' ? 'warn' : (s.finished ? 'fail' : 'busy')))));
   lines.push(`  id        ${s.objective_id}`);
   lines.push(`  host      ${s.host || '-'}   backend ${s.backend || '-'}   scope ${(s.scope || []).join(',') || '-'}`);
@@ -240,11 +266,12 @@ export function registerLoopCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('loops.list');
       const data = await client.get(ep.path, { service: ep.service, query: { limit: options.limit } });
+      const loops = (data.loops || []).map(normLoop);
       formatOutput({
         columns: ['objective_id', 'title', 'state', 'turn', 'backend', 'created_at'],
         headers: ['ID', 'Title', 'State', 'Turn', 'Backend', 'Created'],
-        rows: (data.loops || []).map((l) => ({ ...l, turn: l.max_turns ? `${l.turn}/${l.max_turns}` : String(l.turn) })),
-      }, { format: program.opts().output, emptyMessage: 'No loops in this org yet.' });
+        rows: loops.map((l) => ({ ...l, turn: turnLabel(l) })),
+      }, { format: program.opts().output, raw: loops, emptyMessage: 'No loops in this org yet.' });
     });
 
   // SECURITY containment (2026-10-26): which orgs may run loops in-server (core-local) while a security review is open.

package/lib/commands/lucid.js

@@ -105,6 +105,7 @@ export function registerLucidCommands(program, ctx) {
     if (o.markdown) { const { renderSitrepMarkdown } = await import('../lucid/markdown.js'); console.log(renderSitrepMarkdown(data)); return; }
     const { renderSitrep } = await import('../lucid/sitrep.js');
     const tty = Boolean(process.stdout.isTTY);
+    if (tty) process.stderr.write('Tip: for a shorter form use --spoken (sentences), --agent (compact) or --markdown (one chat message).\n');
     process.stdout.write(renderSitrep(data, {
       width: process.stdout.columns || 100,
       color: tty && !process.env.NO_COLOR && process.env.QUOX_COLOR !== '0',

package/lib/commands/mail.js

@@ -48,6 +48,8 @@ function parseCsvFile(path) {
 const VALID_ZONES = ['focus', 'fyi', 'auto', 'screened'];
 const VALID_KINDS = ['file', 'block', 'draft'];
 const VALID_DECISIONS = ['approve', 'deny'];
+// quox#1518: past tense comes from a map, never verb + 'd' ("denyd").
+const DECISION_PAST_TENSE = { approve: 'approved', deny: 'denied', reject: 'rejected' };
 
 // Small CLI-local copy of src/config/emailProviders.js's EMAIL_PROVIDERS.
 // The cli/ package can't import from src/, so the host/port defaults for
@@ -67,6 +69,21 @@ function printJson(data) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// quox#1504: a failure is printed as a failure (stderr, non-zero exit), never
+// dressed up as an empty success.
+function printFailure(message) {
+  console.error(message);
+  process.exitCode = 1;
+}
+
+function pinHint(accountId, error) {
+  return /^TLS: /.test(error || '')
+    ? `If this server's certificate is one you trust, an org admin can pin it: quox mail account pin ${accountId} --sha256 <fingerprint>`
+    : null;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
 export function registerMailCommands(program, ctx) {
   const { client, auth } = ctx;
 
@@ -85,9 +102,9 @@ export function registerMailCommands(program, ctx) {
       const data = await client.get(ep.path, { service: ep.service });
       if (isJsonOutput(program)) return printJson(data);
       formatOutput({
-        columns: ['id', 'emailAddress', 'displayName', 'pollEnabled', 'createdAt'],
-        headers: ['ID', 'Email', 'Name', 'Polling', 'Connected'],
-        rows: data.accounts || [],
+        columns: ['id', 'emailAddress', 'displayName', 'pollEnabled', 'tlsPin', 'lastError'],
+        headers: ['ID', 'Email', 'Name', 'Polling', 'TLS pin', 'Last error'],
+        rows: (data.accounts || []).map((a) => ({ ...a, tlsPin: a.tlsPinSha256 ? 'sha256 pinned' : '', lastError: a.lastError || '' })),
       }, { format: program.opts().output });
     });
 
@@ -288,31 +305,123 @@ export function registerMailCommands(program, ctx) {
 
   mail
     .command('sync')
-    .description('Sync a mail account now (fetch new messages, run triage)')
+    .description('Sync a mail account now (fetch new messages, run triage). Waits for the result and shows the real cause if the mailbox cannot be reached (TLS, login, network).')
     .argument('<accountId>', 'account ID')
-    .action(async (accountId) => {
+    .option('--wait <seconds>', 'how long to wait for a background sync to finish (0 = do not wait)', '120')
+    .action(async (accountId, options) => {
       auth.requireAuth();
       const ep = resolveEndpoint('inboxq.sync');
-      // A first full-mailbox pull runs the whole IMAP fetch + classify in one
-      // synchronous request and routinely exceeds the default 30s client timeout
-      // (the sync still completes server-side, but the CLI showed a false
-      // "timed out"). Give sync a generous 4-minute ceiling (nginx allows 300s).
+      // A first full-mailbox pull can be slow; the collector usually runs it
+      // detached and returns {started:true} at once. Keep a generous ceiling
+      // for the inline shape (nginx allows 300s).
       const data = await client.post(ep.path, { service: ep.service, body: { accountId }, timeout: 240000 });
+
+      // Detached run: poll sync-status until it finishes, then report the
+      // OUTCOME. quox#1504: this used to print "No folders reported" while the
+      // background run failed TLS and nobody saw why.
+      if (data && (data.started || data.status === 'already_syncing')) {
+        const sep = resolveEndpoint('inboxq.syncStatus');
+        const deadline = Date.now() + Math.max(0, Number(options.wait) || 0) * 1000;
+        let st = await client.get(sep.path, { service: sep.service, query: { accountId } });
+        while (st && st.syncing && Date.now() < deadline) {
+          await sleep(2000);
+          st = await client.get(sep.path, { service: sep.service, query: { accountId } });
+        }
+        if (isJsonOutput(program)) return printJson({ ...data, status: st });
+        if (st && st.lastError) {
+          printFailure(`Sync of ${accountId} failed: ${st.lastError}`);
+          for (const f of st.folderErrors || []) printFailure(`  ${f.folder}: ${f.error} (failures in a row: ${f.consecutiveFailures}${f.retired ? ', retired' : ''})`);
+          const hint = pinHint(accountId, st.lastError);
+          if (hint) console.error(hint);
+          return;
+        }
+        if (st && st.syncing) {
+          printSuccess(`Sync of ${accountId} is still running (${st.stored ?? 0} messages stored so far). Check: quox mail sync-status ${accountId}`);
+          return;
+        }
+        printSuccess(`Synced ${accountId}. ${st?.stored ?? 0} messages stored.`);
+        return;
+      }
+
       if (isJsonOutput(program)) return printJson(data);
       const summary = data.summary || {};
       const folders = summary.folders || [];
+      const failed = folders.filter((f) => f.failed);
       if (folders.length === 0) {
-        printSuccess(`Synced ${accountId}. No folders reported.`);
+        if (data.lastError) { printFailure(`Sync of ${accountId} failed: ${data.lastError}`); return; }
+        printSuccess(`Synced ${accountId}. No folders were eligible this pass (all in backoff or retired); see quox mail sync-status ${accountId}.`);
         return;
       }
       formatOutput({
-        columns: ['folder', 'new', 'failed'],
-        headers: ['Folder', 'New', 'Failed'],
-        rows: folders,
+        columns: ['folder', 'new', 'error'],
+        headers: ['Folder', 'New', 'Error'],
+        rows: folders.map((f) => ({ ...f, new: f.new ?? '', error: f.error || f.skipped || '' })),
       }, { format: program.opts().output });
+      if (failed.length) {
+        printFailure(`Sync of ${accountId}: ${failed.length} of ${folders.length} folder(s) failed: ${failed[0].error}`);
+        const hint = pinHint(accountId, failed[0].error);
+        if (hint) console.error(hint);
+        return;
+      }
       printSuccess(`Synced ${accountId}. LLM calls: ${summary.llmCalls ?? 0}`);
     });
 
+  mail
+    .command('sync-status')
+    .description('Show whether an account is syncing, how many messages are stored, and the last connect/TLS/login error if any')
+    .argument('<accountId>', 'account ID')
+    .action(async (accountId) => {
+      auth.requireAuth();
+      const sep = resolveEndpoint('inboxq.syncStatus');
+      const st = await client.get(sep.path, { service: sep.service, query: { accountId } });
+      if (isJsonOutput(program)) return printJson(st);
+      formatDetail({
+        syncing: Boolean(st.syncing),
+        stored: st.stored ?? 0,
+        folders: st.folders ? `${st.folders.backfilled}/${st.folders.total} fully imported` : '',
+        tlsPin: st.tlsPinSha256 || 'none (default certificate verification)',
+        lastError: st.lastError || 'none',
+        lastErrorAt: st.lastErrorAt || '',
+      }, { format: program.opts().output });
+      if ((st.folderErrors || []).length) {
+        formatOutput({
+          columns: ['folder', 'error', 'consecutiveFailures', 'retired', 'nextAttemptAt'],
+          headers: ['Folder', 'Error', 'Failures', 'Retired', 'Next attempt'],
+          rows: st.folderErrors,
+        }, { format: program.opts().output });
+      }
+      const hint = pinHint(accountId, st.lastError);
+      if (hint) console.error(hint);
+    });
+
+  // ── account (per-account settings) ───────────────────────────────────
+
+  const account = mail
+    .command('account')
+    .description('Per-account settings for a connected mailbox');
+
+  account
+    .command('pin')
+    .description('Pin the TLS certificate (SHA-256 fingerprint) an account trusts, for a mail server with a self-signed or private-CA certificate. Only that exact certificate is accepted; anything else still fails. Org admin only. Get the fingerprint with: openssl s_client -connect <host>:<port> </dev/null | openssl x509 -noout -fingerprint -sha256')
+    .argument('<accountId>', 'account ID')
+    .option('--sha256 <fingerprint>', 'SHA-256 certificate fingerprint (64 hex characters, colons optional; the openssl output line is accepted)')
+    .option('--clear', 'remove the pin (back to default certificate verification)')
+    .action(async (accountId, options) => {
+      auth.requireAuth();
+      if (Boolean(options.sha256) === Boolean(options.clear)) {
+        printFailure('Give exactly one of --sha256 <fingerprint> or --clear.');
+        return;
+      }
+      const ep = resolveEndpoint('inboxq.accounts.tlsPin', { accountId });
+      const body = options.clear ? { clear: true } : { sha256: options.sha256 };
+      const data = await client.put(ep.path, { service: ep.service, body });
+      if (isJsonOutput(program)) return printJson(data);
+      const pin = data?.account?.tlsPinSha256;
+      printSuccess(pin
+        ? `Pinned ${accountId} to TLS certificate sha256 ${pin}. Run quox mail sync ${accountId} to retry now.`
+        : `Removed the TLS pin from ${accountId}; it uses default certificate verification again.`);
+    });
+
   // ── messages ─────────────────────────────────────────────────────────
 
   mail
@@ -408,20 +517,52 @@ export function registerMailCommands(program, ctx) {
 
   watch
     .command('add')
-    .description('Add a watch')
+    .description('Add a watch (awaited-mail alert). Give --match, or at least one of --from/--subject/--text/--zone.')
     .requiredOption('--label <label>', 'watch label')
-    .requiredOption('--match <json>', 'match rule as a JSON object')
-    .option('--account <id>', 'restrict the watch to one account')
+    .option('--match <json>', 'match rule as a JSON object (advanced; alternative to the --from/--subject/--text/--zone flags)')
+    .option('--from <addr>', 'match: sender address/name contains this')
+    .option('--subject <text>', 'match: subject contains this')
+    .option('--text <keyword>', 'match: message text contains this')
+    .option('--zone <zone>', 'match: only mail triaged into this zone (focus|fyi|auto|screened)')
+    .option('--notify <csv>', 'alert channels, comma list of hitl,lucid,telegram,discord,call,sms', 'hitl')
+    .option('--account <id>', 'restrict the watch to one account (omit to watch all your mailboxes)')
     .action(async (options) => {
       auth.requireAuth();
-      const match = parseJSON(options.match, '--match');
-      const body = { label: options.label, match };
+      let match;
+      if (options.match) {
+        match = parseJSON(options.match, '--match');
+      } else {
+        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) match.zone = options.zone;
+      }
+      if (!match || typeof match !== 'object' || Object.keys(match).length === 0) {
+        throw new Error('Give --match, or at least one of --from, --subject, --text, --zone, or the watch would match nothing in particular.');
+      }
+      const notify = String(options.notify).split(',').map((s) => s.trim()).filter(Boolean);
+      const body = { label: options.label, match, notify };
       if (options.account) body.accountId = options.account;
       const ep = resolveEndpoint('inboxq.watches.create');
       const data = await client.post(ep.path, { service: ep.service, body });
       if (isJsonOutput(program)) return printJson(data);
       const created = data.watch || data;
-      printSuccess(`Added watch "${options.label}" (${created.id})`);
+      printSuccess(`Added watch "${options.label}" (${created.id}); alerts via ${notify.join(', ')}.`);
+      const ext = notify.filter((c) => ['telegram', 'discord', 'call', 'sms'].includes(c));
+      if (ext.length) console.log(`Note: ${ext.join(', ')} need a destination configured, or they report unconfigured; hitl and lucid work out of the box.`);
+    });
+
+  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 client.delete(ep.path, { service: ep.service });
+      if (isJsonOutput(program)) return printJson(data);
+      printSuccess(`Watch ${watchId} deleted.`);
     });
 
   watch
@@ -493,7 +634,7 @@ export function registerMailCommands(program, ctx) {
       const ep = resolveEndpoint('inboxq.proposals.resolve', { proposalId });
       const data = await client.post(ep.path, { service: ep.service, body: { decision: options.decision } });
       if (isJsonOutput(program)) return printJson(data);
-      printSuccess(`Proposal ${proposalId} ${options.decision}d.`);
+      printSuccess(`Proposal ${proposalId} ${DECISION_PAST_TENSE[options.decision] || options.decision}.`);
     });
 
   // ── moves (AQ-9E U2: reversible moves) ─────────────────────────────────