quoxcli 0.3.1 → 0.5.0

package/lib/commands/loop.js

@@ -0,0 +1,318 @@
+/**
+ * Loop commands (QLOOP-LIVE): observe a QLoop loop as it runs.
+ *
+ *   quox loop watch <id> [--spool|--quiet] [--since n]   live, one QuoxGlyph line per event
+ *   quox loop status <id>                                snapshot
+ *   quox loop list                                       running + recent loops (org)
+ *
+ * `watch` reconnects with ?since=<last event_seq> when the stream drops, and exits with the loop's
+ * outcome: 0 completed, 1 failed, 2 halted, 3 interrupted, 4 connection lost for good.
+ * Events come from GET /api/v1/loops/:id/events (design: ~/quoxon-work/qloop-live-design.md).
+ */
+
+import { formatOutput, getOutputFormat } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { loopLine, renderEvent, exitCodeFor, elapsedLabel } from '../core/loopGlyph.js';
+import { QuoxApiError, QuoxAuthError, QuoxUserError } from '../core/errors.js';
+
+const MAX_SILENT_RETRIES = 10;
+const BACKOFF_BASE_MS = 1000;
+const BACKOFF_CAP_MS = 10000;
+
+const sleepReal = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** SQLite "YYYY-MM-DD HH:MM:SS" (UTC, no zone) or ISO to epoch ms; null if unreadable. */
+function toMs(ts) {
+  if (!ts) return null;
+  const iso = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(ts) ? `${ts.replace(' ', 'T')}Z` : ts;
+  const n = Date.parse(iso);
+  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;
+
+/**
+ * After loop.finished: wait (bounded) for the loop's receipts to be WITNESSED by WARD, asking the snapshot
+ * (which re-checks WARD and records what it finds), printing each receipt as it flips. Returns the finished
+ * event with the final witnessed count. A snapshot that cannot be read ends the wait and says so; it never
+ * reads as "0 witnessed".
+ */
+async function settleReceipts({ client, id, finished, write, sleep, ctx, maxMs, signal, seen = new Set() }) {
+  const ep = resolveEndpoint('loops.get', { id: encodeURIComponent(id) });
+  let witnessed = finished.witnessed;
+  write(loopLine('receipts', `${witnessed}/${finished.receipts} witnessed, waiting for WARD to sign the covering tip`, 'busy'));
+  let waited = 0;
+  while (witnessed < finished.receipts && waited < maxMs && !(signal && signal.aborted)) {
+    await sleep(SETTLE_POLL_MS);
+    waited += SETTLE_POLL_MS;
+    let snap;
+    try { snap = await client.get(ep.path, { service: ep.service }); } catch (err) {
+      write(loopLine('receipts', `could not re-check WARD (${oneLineErr(err)}); \`quox loop status ${id}\` will`, 'warn'));
+      break;
+    }
+    const items = (snap && snap.receipts && snap.receipts.items) || [];
+    for (const r of items) {
+      if (r.status === 'WITNESSED' && !seen.has(r.envelope_id)) {
+        seen.add(r.envelope_id);
+        write(loopLine('receipt', `${String(r.envelope_id)} WITNESSED`, 'ok'));
+      }
+    }
+    witnessed = snap && snap.receipts ? snap.receipts.witnessed : witnessed;
+  }
+  if (witnessed < finished.receipts) write(loopLine('receipts', `${finished.receipts - witnessed} still pending after ${Math.round(waited / 1000)}s; they are witnessed when the next tip signs (quox loop status ${id})`, 'warn'));
+  return { ...finished, witnessed };
+}
+
+/**
+ * Follow one loop to its end. Returns the process exit code. Exported for tests.
+ * @param {object} p
+ * @param {object} p.client   cli client (stream)
+ * @param {string} p.id
+ * @param {object} p.snapshot  loops.get result (title, max_turns, started_at)
+ * @param {{spool?: boolean, quiet?: boolean, since?: number, json?: boolean, noSettle?: boolean, settleMs?: number}} p.opts
+ * @param {(line: string) => void} p.write
+ * @param {(ms: number) => Promise<void>} [p.sleep]
+ * @param {AbortSignal} [p.signal]
+ */
+export async function watchLoop({ client, id, snapshot, opts = {}, write, sleep = sleepReal, signal }) {
+  const ep = resolveEndpoint('loops.events', { id: encodeURIComponent(id) });
+  let lastSeq = Number(opts.since) || 0;
+  let startedMs = toMs(snapshot && snapshot.started_at);
+  const ctx = { title: snapshot && snapshot.title, maxTurns: snapshot && snapshot.max_turns, startedMs, spool: !!opts.spool };
+  const showQuiet = new Set(['loop.started', 'loop.observe', 'loop.approval', 'loop.finished']);
+  let failures = 0;
+  let backoff = BACKOFF_BASE_MS;
+  const witnessedShown = new Set(); // receipts already printed from loop.ward events, so the settle phase does not repeat them
+
+  while (!signal || !signal.aborted) {
+    let gotEvent = false;
+    let ended = null;
+    try {
+      for await (const ev of client.stream(ep.path, { service: ep.service, query: { since: lastSeq }, signal })) {
+        // `event: end` frame (an old loop that never logged a finish): no type, a reason
+        if (ev && !ev.type && ev.reason) { ended = ev; break; }
+        if (!ev || typeof ev.type !== 'string' || !ev.type.startsWith('loop.')) continue;
+        gotEvent = true;
+        if (typeof ev.event_seq === 'number') {
+          if (ev.event_seq <= lastSeq) continue; // replay overlap after a reconnect
+          lastSeq = ev.event_seq;
+        }
+        if (ev.type === 'loop.ward' && ev.status === 'WITNESSED') witnessedShown.add(ev.envelope_id);
+        if (!ctx.startedMs && ev.type === 'loop.started') ctx.startedMs = Date.parse(ev.at);
+        if (opts.json) write(JSON.stringify(ev));
+        else if (ev.type !== 'loop.finished' && !(opts.quiet && !showQuiet.has(ev.type))) for (const l of renderEvent(ev, ctx)) write(l);
+        if (ev.type === 'loop.finished') {
+          // the loop is over; its receipts are WITNESSED when WARD's next signed tip covers them (about a minute),
+          // so say so and follow them in rather than printing a final count that is about to be stale
+          const last = (!opts.json && !opts.noSettle && ev.receipts > ev.witnessed)
+            ? await settleReceipts({ client, id, finished: ev, write, sleep, ctx, maxMs: opts.settleMs ?? SETTLE_MAX_MS, signal, seen: witnessedShown })
+            : ev;
+          if (!opts.json) for (const l of renderEvent(last, ctx).slice(-1)) write(l);
+          if (!opts.json && !opts.quiet) write(`  quox loop status ${id}   # receipts and proof`);
+          return exitCodeFor(ev.state);
+        }
+      }
+    } catch (err) {
+      // a refusal is not a dropped connection: 401/403/404 and friends end the watch now with the server's words
+      if (err instanceof QuoxAuthError || (err instanceof QuoxApiError && err.status >= 400 && err.status < 500 && err.status !== 429)) throw err;
+      if (signal && signal.aborted) return 130;
+      failures += 1;
+      if (failures > MAX_SILENT_RETRIES) {
+        write(loopLine('connection lost', `could not reach the loop stream after ${MAX_SILENT_RETRIES} tries; resume with: quox loop watch ${id} --since ${lastSeq}`, 'fail'));
+        return 4;
+      }
+      if (!opts.quiet && !opts.json) write(loopLine('reconnecting', `stream dropped (${oneLineErr(err)}); resuming after event ${lastSeq}`, 'warn'));
+      await sleep(backoff);
+      backoff = Math.min(BACKOFF_CAP_MS, backoff * 2);
+      continue;
+    }
+    if (ended) {
+      write(loopLine(ctx.title || 'loop', `ended without a recorded finish (${ended.status || 'unknown'}): ${ended.reason}`, 'warn'));
+      return ended.status === 'completed' ? 0 : 1;
+    }
+    // stream closed by the server (restart, proxy idle limit) before loop.finished: resume, quietly counting
+    if (gotEvent) { failures = 0; backoff = BACKOFF_BASE_MS; } else failures += 1;
+    if (failures > MAX_SILENT_RETRIES) {
+      write(loopLine('connection lost', `the loop stream keeps closing with nothing new; resume with: quox loop watch ${id} --since ${lastSeq}`, 'fail'));
+      return 4;
+    }
+    await sleep(gotEvent ? 250 : backoff);
+    if (!gotEvent) backoff = Math.min(BACKOFF_CAP_MS, backoff * 2);
+  }
+  return 130;
+}
+
+function oneLineErr(err) {
+  return String((err && err.message) || err).replace(/\s+/g, ' ').slice(0, 80);
+}
+
+export function statusLines(s, { diagnostics = false } = {}) {
+  const lines = [];
+  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(',') || '-'}`);
+  if (s.until) lines.push(`  until     ${s.until}${s.every_seconds ? `   (a turn every ${s.every_seconds}s)` : ''}`);
+  else if (s.every_seconds) lines.push(`  every     ${s.every_seconds}s`);
+  if (s.workspace) lines.push(`  workspace ${s.workspace}`);
+  const r = s.receipts || { total: 0, witnessed: 0 };
+  lines.push(`  receipts  ${r.witnessed}/${r.total} witnessed${s.ward_check_error ? `   (WARD could not be asked just now: ${s.ward_check_error})` : ''}`);
+  if (s.observe) lines.push(`  observe   ${JSON.stringify(s.observe)}`);
+  if (s.reason && s.finished) lines.push(`  reason    ${s.reason}`);
+  if (diagnostics && s.diagnostics) lines.push(`  diagnostics ${s.diagnostics}`);
+  if ((s.last_turns || []).length) {
+    lines.push('  last turns');
+    for (const t of s.last_turns) {
+      const tools = (t.tools || []).map((x) => `${x.tool}${x.denied ? ' denied' : (x.ok ? '' : ' FAILED')}`).join(', ');
+      lines.push(`    ${t.turn}  ${t.summary}${tools ? `  [${tools}]` : ''}  ${t.envelope_id ? `${String(t.envelope_id)} ${t.ward}` : ''}`.trimEnd());
+    }
+  }
+  if (s.started_at) {
+    const st = toMs(s.started_at);
+    const en = toMs(s.completed_at) || Date.now();
+    if (st) lines.push(`  elapsed   ${elapsedLabel(en - st)}`);
+  }
+  return lines;
+}
+
+export function registerLoopCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const loop = program
+    .command('loop')
+    .description('Observe QLoop loops as they run (watch, status, list)');
+
+  loop
+    .command('watch')
+    .description('Follow a loop live: one QuoxGlyph line per event, reconnecting on drop. Exits 0 completed, 1 failed, 2 halted, 3 interrupted, 4 connection lost')
+    .argument('<id>', 'loop (objective) ID')
+    .option('--spool', 'also stream the loop\'s output text under each turn line')
+    .option('--quiet', 'only the headline lines: started, observe points (milestones, errors, approvals, stalls), the final line')
+    .option('--since <n>', 'resume after this event_seq (printed by a previous watch; default: from the start)')
+    .option('--no-wait-receipts', 'print the final line as soon as the loop ends instead of waiting (up to 90s) for its receipts to be witnessed')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      if (options.spool && options.quiet) throw new QuoxUserError('--spool and --quiet cancel each other out; pick one.');
+      const since = options.since !== undefined ? Number(options.since) : 0;
+      if (!Number.isInteger(since) || since < 0) throw new QuoxUserError('--since needs a whole number event_seq (0 or more).');
+      const snap = resolveEndpoint('loops.get', { id: encodeURIComponent(id) });
+      const snapshot = await client.get(snap.path, { service: snap.service });
+      const ac = new AbortController();
+      const onSigint = () => ac.abort();
+      process.once('SIGINT', onSigint);
+      let code;
+      try {
+        code = await watchLoop({
+          client, id, snapshot,
+          opts: { spool: options.spool, quiet: options.quiet, since, json: getOutputFormat() === 'json', noSettle: options.waitReceipts === false },
+          write: (l) => console.log(l),
+          signal: ac.signal,
+        });
+      } finally {
+        process.removeListener('SIGINT', onSigint);
+      }
+      if (code === 130) console.log(`  stopped watching; the loop keeps running. Resume: quox loop watch ${id}`);
+      if (code) process.exitCode = code;
+    });
+
+  loop
+    .command('status')
+    .description('Snapshot of a loop: state, turn n/max, host, backend, scope, last turns, receipts')
+    .argument('<id>', 'loop (objective) ID')
+    .option('--diagnostics', 'also show the raw diagnostics behind the finish reason (hidden by default)')
+    .action(async (id, options = {}) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('loops.get', { id: encodeURIComponent(id) });
+      const data = await client.get(ep.path, { service: ep.service });
+      if (getOutputFormat() === 'json') {
+        const out = options.diagnostics || !data || typeof data !== 'object' ? data : { ...data, diagnostics: undefined };
+        console.log(JSON.stringify(out, null, 2)); return;
+      }
+      for (const l of statusLines(data, { diagnostics: !!options.diagnostics })) console.log(l);
+    });
+
+  loop
+    .command('list')
+    .description('Running and recent loops in this org')
+    .option('--limit <n>', 'max results', '20')
+    .action(async (options) => {
+      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: 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.
+  // Instance-admin only (the server enforces it; a non-admin gets a 403). Stored server-side in instance_config.
+  const coreLocal = loop
+    .command('core-local')
+    .description('Instance admin: which workspaces may run loops inside the server (limited while a security review is open)');
+
+  coreLocal
+    .command('list')
+    .description('Show the workspaces allowed to run loops inside the server')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('admin.instance.core_local_orgs.list');
+      const r = await client.get(ep.path, { service: ep.service });
+      if (getOutputFormat() === 'json') { console.log(JSON.stringify(r, null, 2)); return; }
+      if (!(r.orgs || []).length) { console.log('No workspace may run loops inside the server (loops need a dev server).'); return; }
+      for (const o of r.orgs) console.log(o);
+    });
+
+  coreLocal
+    .command('add')
+    .description('Allow a workspace to run loops inside the server (instance admin)')
+    .argument('<orgId>', 'workspace (org) id')
+    .action(async (orgId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('admin.instance.core_local_orgs.add');
+      const r = await client.post(ep.path, { service: ep.service, body: { org_id: orgId } });
+      if (getOutputFormat() === 'json') { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(`Added ${orgId}. ${(r.orgs || []).length} workspace(s) may now run loops inside the server.`);
+    });
+
+  coreLocal
+    .command('remove')
+    .description('Stop a workspace running loops inside the server (instance admin)')
+    .argument('<orgId>', 'workspace (org) id')
+    .action(async (orgId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('admin.instance.core_local_orgs.remove', { orgId: encodeURIComponent(orgId) });
+      const r = await client.delete(ep.path, { service: ep.service });
+      if (getOutputFormat() === 'json') { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(`Removed ${orgId}. ${(r.orgs || []).length} workspace(s) may still run loops inside the server.`);
+    });
+}

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) ─────────────────────────────────