quoxcli 0.4.0 → 0.6.0

package/lib/commands/mail.js

@@ -11,6 +11,9 @@ import { readFileSync, statSync } from 'fs';
 import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
 import { parseJSON, resolveOrgId } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { announce, announceOnFail } from '../core/announce.js';
+import { confirmInteractive } from '../core/confirm.js';
+import { QuoxUserError } from '../core/errors.js';
 
 // --- minimal CSV parsing (quoted fields + escaped quotes, no deps) ----------
 function splitCsvLine(line) {
@@ -46,8 +49,80 @@ function parseCsvFile(path) {
 }
 
 const VALID_ZONES = ['focus', 'fyi', 'auto', 'screened'];
-const VALID_KINDS = ['file', 'block', 'draft'];
+// The server accepts file|block|draft|rezone|folder_create|rule (api.js PROPOSAL_KINDS).
+// 'rule' is left out on purpose: it has no executor, so approving one only records the
+// decision and nothing happens to the mailbox (api.js hResolveProposal). Offering it
+// would let a user file an approval that can never do what it says.
+const VALID_KINDS = ['file', 'block', 'draft', 'rezone', 'folder_create'];
+const PROPOSE_PAYLOADS = `Payload per --kind (a JSON object):
+  block          {"scope":"sender"|"domain","target":"<address or domain>"}
+                 scope sender: target is the sender address (fromAddr is accepted too);
+                 scope domain: target is the domain, e.g. "spam.test" (domain is accepted too).
+                 Approving it runs the same block as \`quox mail block\`: stored mail is
+                 screened and moved to Junk. \`quox mail block <addr|@domain> --propose\`
+                 builds this payload for you.
+  file           {"messageIds":["<id>",...],"folder":"<folder name, id or IMAP path>"}
+  rezone         {"messageIds":["<id>",...],"toZone":"focus"|"fyi"|"auto"|"screened"}
+  folder_create  {"name":"<folder name>"}
+  draft          {"messageId":"<id to reply to>","body":"<text>"} (or "to" instead of messageId)
+Kind "rule" is not offered: the server has no executor for it yet, so approving one would change nothing.`;
+
+/**
+ * Parse a block/unblock target: "@domain" is a domain, "a@b" a sender address.
+ * --scope domain on an address blocks the address's domain.
+ * -> { scope, target, fromAddr?, domain? } (all lower-cased).
+ */
+function parseBlockTarget(raw, scopeOpt) {
+  const t = String(raw || '').trim().toLowerCase();
+  if (scopeOpt && !['sender', 'domain'].includes(scopeOpt)) {
+    throw new QuoxUserError(`invalid --scope "${scopeOpt}" (expected sender or domain)`, { exitCode: 2 });
+  }
+  if (t.startsWith('@')) {
+    const domain = t.slice(1);
+    if (!domain || domain.includes('@')) throw new QuoxUserError(`"${raw}" is not a domain. Use @example.com.`, { exitCode: 2 });
+    if (scopeOpt === 'sender') throw new QuoxUserError(`--scope sender needs a sender address, not ${raw}. Drop --scope (an @domain is a domain block) or give the address.`, { exitCode: 2 });
+    return { scope: 'domain', target: domain, domain };
+  }
+  const at = t.indexOf('@');
+  if (at > 0 && at < t.length - 1 && t.indexOf('@', at + 1) === -1) {
+    if (scopeOpt === 'domain') {
+      const domain = t.slice(at + 1);
+      return { scope: 'domain', target: domain, fromAddr: t, domain };
+    }
+    return { scope: 'sender', target: t, fromAddr: t };
+  }
+  throw new QuoxUserError(`"${raw}" is not a sender address or @domain. Give an address (tanya@example.com) or a domain (@example.com). To find an address by name: quox mail list --account <id>`, { exitCode: 2 });
+}
+
+/** The block proposal payload the server executor reads (api.js executeBlockProposal). */
+function blockProposalPayload(t) {
+  return t.scope === 'domain'
+    ? { scope: 'domain', target: t.target, domain: t.domain }
+    : { scope: 'sender', target: t.target, fromAddr: t.fromAddr };
+}
+
+/** Validate a block payload before it reaches the server (the server also checks). */
+function checkBlockPayload(payload) {
+  const p = payload && typeof payload === 'object' ? payload : {};
+  if (!['sender', 'domain'].includes(p.scope)) {
+    throw new QuoxUserError('block payload needs "scope": "sender" or "domain". Example: {"scope":"sender","target":"tanya@example.com"}', { exitCode: 2 });
+  }
+  const target = p.target || (p.scope === 'domain' ? (p.domain || (p.fromAddr ? String(p.fromAddr).split('@')[1] : '')) : p.fromAddr);
+  if (!target || !String(target).trim()) {
+    throw new QuoxUserError(`block payload needs "target" (the ${p.scope === 'domain' ? 'domain' : 'sender address'}). Example: {"scope":"${p.scope}","target":"${p.scope === 'domain' ? 'example.com' : 'tanya@example.com'}"}`, { exitCode: 2 });
+  }
+}
+
+const JUNK_NAME = /\b(spam|junk|bulk)\b/i;
+
+/** --yes (local or root -y) or an interactive y/N. Throws with no terminal. */
+async function confirmWrite(program, options, message) {
+  if (options.yes || (program.opts && program.opts().yes)) return true;
+  return confirmInteractive(message, { flag: '--yes', purpose: 'confirm' });
+}
 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 +142,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 +175,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 +378,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 +590,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
@@ -438,20 +652,208 @@ export function registerMailCommands(program, ctx) {
       printSuccess(`Watch ${watchId} is now ${active ? 'active' : 'inactive'}.`);
     });
 
+  // ── senders: block / unblock / blocked / junk / trust ──────────────────
+  // EMAIL-Q CLI audit (2026-11-09): the SAME routes the dashboard calls
+  // (src/components/inboxq/lib/api.js). Blocking is the human-authoritative
+  // instant path (POST /senders/block), exactly as the "Block sender" button;
+  // --propose files a governed block proposal instead.
+
+  mail
+    .command('block')
+    .description('Block a sender address or @domain on one account (stored mail screened and moved to Junk). --dry-run counts matches first; --propose files an approval instead')
+    .addHelpText('after', `
+Same action as the dashboard "Block sender" button (POST /senders/block). Future mail from it is
+screened while Quox syncs the account; no rule is set on the mail server itself.
+Examples:
+  quox mail block tanya@example.com --account <id> --dry-run
+  quox mail block tanya@example.com --account <id> --yes
+  quox mail block @example.com --account <id> --propose
+Proposal payload (--propose): {"scope":"sender"|"domain","target":"<address or domain>"}
+`)
+    .argument('<target>', 'sender address (tanya@example.com) or @domain (@example.com)')
+    .requiredOption('--account <id>', 'account ID (quox mail accounts)')
+    .option('--scope <scope>', 'sender or domain (default: sender for an address, domain for @domain)')
+    .option('--dry-run', 'count the stored messages that match and what would move; change nothing')
+    .option('--propose', 'file a block proposal for approval instead of blocking now (payload {scope, target, fromAddr|domain})')
+    .option('--yes', 'confirm the block (refused without it when there is no terminal)')
+    .action(announceOnFail('mail', (target) => `block ${target}`, async (rawTarget, options) => {
+      auth.requireAuth();
+      if (options.dryRun && options.propose) {
+        throw new QuoxUserError('Use --dry-run or --propose, not both. Run the dry run first, then --propose.', { exitCode: 2 });
+      }
+      const t = parseBlockTarget(rawTarget, options.scope);
+      const accountId = options.account;
+
+      if (options.dryRun) {
+        const ep = resolveEndpoint('inboxq.messages.search');
+        const query = { accountId, limit: 200 };
+        if (t.scope === 'domain') query.fromDomain = t.domain; else query.from = t.fromAddr;
+        const data = await client.get(ep.path, { service: ep.service, query });
+        const msgs = Array.isArray(data?.messages) ? data.messages : [];
+        // The block executor matches the sender EXACTLY (domain: address ends with @domain);
+        // the search is a substring match, so count only what the block would really touch.
+        const hit = (m) => {
+          const f = String(m.fromAddr || '').trim().toLowerCase();
+          return t.scope === 'domain' ? f.endsWith(`@${t.domain}`) : f === t.fromAddr;
+        };
+        const matched = msgs.filter(hit);
+        const alreadyInJunk = matched.filter((m) => JUNK_NAME.test(String(m.folder || ''))).length;
+        const capped = Number(data?.total || 0) > msgs.length;
+        const result = { dryRun: true, accountId, scope: t.scope, target: t.target, matched: matched.length, alreadyInJunk, wouldMove: matched.length - alreadyInJunk, capped };
+        if (isJsonOutput(program)) return printJson(result);
+        const atLeast = capped ? 'at least ' : '';
+        console.log(`Dry run: blocking ${t.target} (${t.scope}) on ${accountId} would screen ${atLeast}${matched.length} stored message(s) and move ${atLeast}${result.wouldMove} to Junk (${alreadyInJunk} already there).`);
+        if (capped) console.log('The search returns at most 200 messages, so the real count can be higher.');
+        console.log('Nothing changed. Run it without --dry-run to block, or with --propose to file an approval.');
+        announce('mail', `block ${t.target} dry run`, { result: `${atLeast}${matched.length} match, nothing changed`, status: 'ok' });
+        return;
+      }
+
+      if (options.propose) {
+        const ep = resolveEndpoint('inboxq.proposals.create');
+        const body = { accountId, kind: 'block', payload: blockProposalPayload(t), createdVia: 'cli' };
+        const data = await client.post(ep.path, { service: ep.service, body });
+        if (isJsonOutput(program)) return printJson(data);
+        const proposal = data.proposal || data;
+        printSuccess(`Proposed blocking ${t.target} (${t.scope}) on ${accountId}: proposal ${proposal.id}. Nothing changes until it is approved.`);
+        console.log(`Approve: quox mail resolve ${proposal.id} --decision approve`);
+        announce('mail', `propose block ${t.target}`, { result: `proposal ${proposal.id}`, status: 'ok' });
+        return;
+      }
+
+      const go = await confirmWrite(program, options, `Block ${t.target} (${t.scope}) on ${accountId}? Its stored mail is screened and moved to Junk.`);
+      if (!go) {
+        console.log('Not blocked. Nothing changed.');
+        announce('mail', `block ${t.target}`, { result: 'cancelled, nothing changed', status: 'warn' });
+        return;
+      }
+      const ep = resolveEndpoint('inboxq.senders.block');
+      const body = t.scope === 'domain'
+        ? { ...(t.fromAddr ? { fromAddr: t.fromAddr } : {}), accountId, scope: 'domain', domain: t.domain }
+        : { fromAddr: t.fromAddr, accountId, scope: 'sender' };
+      const data = await client.post(ep.path, { service: ep.service, body });
+      if (isJsonOutput(program)) return printJson(data);
+      const screened = data?.screened ?? 0;
+      const moved = data?.junkMoved ?? 0;
+      printSuccess(`Blocked ${data?.target || t.target} (${data?.scope || t.scope}) on ${accountId}: ${screened} stored message(s) screened, ${moved} moved to ${data?.junkFolder || 'Junk'}.`);
+      if (data?.junkFailed) {
+        console.error(`The move to Junk failed for ${Math.max(0, (data.junkMatched ?? 0) - moved)} message(s); they are screened in Quox but still in their folder on the mail server. Retry: quox mail sync ${accountId}, then block again.`);
+      }
+      if (!data?.providerRule || data.providerRule === 'none') {
+        console.log('Future mail from it is screened while Quox syncs this account; no rule was set on the mail server itself.');
+      }
+      announce('mail', `block ${t.target}`, { result: `${screened} screened, ${moved} to Junk`, status: data?.junkFailed ? 'warn' : 'ok' });
+    }));
+
+  mail
+    .command('unblock')
+    .description('Lift a sender or domain block on one account (future mail is no longer screened for it). Mail already in Junk stays there; use quox mail trust <address> to move a sender\'s mail back. Example: quox mail unblock @example.com --account <id> --yes')
+    .argument('<target>', 'sender address or @domain')
+    .requiredOption('--account <id>', 'account ID')
+    .option('--scope <scope>', 'sender or domain (default: sender for an address, domain for @domain)')
+    .option('--yes', 'confirm (refused without it when there is no terminal)')
+    .action(announceOnFail('mail', (target) => `unblock ${target}`, async (rawTarget, options) => {
+      auth.requireAuth();
+      const t = parseBlockTarget(rawTarget, options.scope);
+      const go = await confirmWrite(program, options, `Unblock ${t.target} (${t.scope}) on ${options.account}?`);
+      if (!go) {
+        console.log('Not unblocked. Nothing changed.');
+        announce('mail', `unblock ${t.target}`, { result: 'cancelled, nothing changed', status: 'warn' });
+        return;
+      }
+      const ep = resolveEndpoint('inboxq.senders.unblock');
+      const data = await client.post(ep.path, { service: ep.service, body: { target: t.target, type: t.scope, accountId: options.account } });
+      if (isJsonOutput(program)) return printJson(data);
+      printSuccess(`Unblocked ${t.target} (${t.scope}) on ${options.account}.`);
+      announce('mail', `unblock ${t.target}`, { result: t.scope, status: 'ok' });
+    }));
+
+  mail
+    .command('blocked')
+    .description('List the blocked senders and domains on one account')
+    .requiredOption('--account <id>', 'account ID')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('inboxq.senders.blocked');
+      const data = await client.get(ep.path, { service: ep.service, query: { accountId: options.account } });
+      if (isJsonOutput(program)) return printJson(data);
+      const rows = data?.blocked || [];
+      if (!rows.length) { console.log(`Nothing is blocked on ${options.account}.`); return; }
+      formatOutput({
+        columns: ['target', 'type', 'blockedAt'],
+        headers: ['Blocked', 'Type', 'Since'],
+        rows,
+      }, { format: program.opts().output });
+    });
+
+  mail
+    .command('junk')
+    .description('Confirm messages are junk: each sender is blocked and the messages move to the account\'s Junk folder on the mail server. Example: quox mail junk <messageId> <messageId> --account <id> --yes')
+    .argument('<messageIds...>', 'message IDs (quox mail list)')
+    .requiredOption('--account <id>', 'account ID')
+    .option('--yes', 'confirm (refused without it when there is no terminal)')
+    .action(announceOnFail('mail', (ids) => `junk ${ids.length} message(s)`, async (messageIds, options) => {
+      auth.requireAuth();
+      const go = await confirmWrite(program, options, `Mark ${messageIds.length} message(s) as junk on ${options.account}? Their senders are blocked and the messages move to Junk.`);
+      if (!go) {
+        console.log('Nothing marked as junk.');
+        announce('mail', `junk ${messageIds.length} message(s)`, { result: 'cancelled, nothing changed', status: 'warn' });
+        return;
+      }
+      const ep = resolveEndpoint('inboxq.messages.confirmJunk');
+      const data = await client.post(ep.path, { service: ep.service, body: { messageIds, accountId: options.account } });
+      if (isJsonOutput(program)) {
+        if ((data?.failed || []).length) process.exitCode = 1;
+        return printJson(data);
+      }
+      const failed = data?.failed || [];
+      printSuccess(`Moved ${data?.moved ?? 0} message(s) to Junk and blocked ${data?.blocked ?? 0} sender(s) on ${options.account}.`);
+      if (failed.length) printFailure(`${failed.length} message(s) were not moved: ${failed.join(', ')} (not found on this account, or the mail server refused the move).`);
+      announce('mail', `junk ${messageIds.length} message(s)`, { result: `${data?.moved ?? 0} to Junk${failed.length ? `, ${failed.length} failed` : ''}`, status: failed.length ? 'fail' : 'ok' });
+    }));
+
+  mail
+    .command('trust')
+    .description('Trust a sender (not junk): lifts their block, restores their stored mail to its zone, and moves it out of Junk back to INBOX. Example: quox mail trust tanya@example.com --account <id> --yes')
+    .argument('<address>', 'sender address')
+    .requiredOption('--account <id>', 'account ID')
+    .option('--yes', 'confirm (refused without it when there is no terminal)')
+    .action(announceOnFail('mail', (a) => `trust ${a}`, async (rawAddress, options) => {
+      auth.requireAuth();
+      const t = parseBlockTarget(rawAddress);
+      if (t.scope !== 'sender') throw new QuoxUserError('trust takes one sender address, not a domain.', { exitCode: 2 });
+      const go = await confirmWrite(program, options, `Trust ${t.fromAddr} on ${options.account}? Their mail moves out of Junk back to INBOX.`);
+      if (!go) {
+        console.log('Not trusted. Nothing changed.');
+        announce('mail', `trust ${t.fromAddr}`, { result: 'cancelled, nothing changed', status: 'warn' });
+        return;
+      }
+      const ep = resolveEndpoint('inboxq.senders.trust');
+      const data = await client.post(ep.path, { service: ep.service, body: { fromAddr: t.fromAddr, accountId: options.account } });
+      if (isJsonOutput(program)) return printJson(data);
+      const back = data?.movedBack;
+      printSuccess(`Trusted ${t.fromAddr} on ${options.account}: ${data?.restored ?? 0} stored message(s) restored${back !== undefined ? `, ${back} moved back to INBOX` : ''}.`);
+      if (data?.movedBackFailed) console.error('Some of their mail could not be moved out of Junk on the mail server; it is restored in Quox only.');
+      announce('mail', `trust ${t.fromAddr}`, { result: `${data?.restored ?? 0} restored`, status: data?.movedBackFailed ? 'warn' : 'ok' });
+    }));
+
   // ── proposals ────────────────────────────────────────────────────────
 
   mail
     .command('propose')
-    .description('Create a proposal (file, block or draft) for an account')
+    .description('Propose a change for approval (file, block, draft, rezone, folder_create). Block payload: {"scope":"sender"|"domain","target":"<address or domain>"}')
     .requiredOption('--account <id>', 'account ID')
-    .requiredOption('--kind <kind>', 'proposal kind: file, block, draft')
-    .requiredOption('--payload <json>', 'proposal payload as a JSON object')
+    .requiredOption('--kind <kind>', `proposal kind: ${VALID_KINDS.join(', ')} (not rule: no executor yet)`)
+    .requiredOption('--payload <json>', 'proposal payload as a JSON object (shape per kind below)')
+    .addHelpText('after', `\nNothing changes until a human approves it: quox mail resolve <id> --decision approve\n\n${PROPOSE_PAYLOADS}\n`)
     .action(async (options) => {
       auth.requireAuth();
       if (!VALID_KINDS.includes(options.kind)) {
-        throw new Error(`invalid --kind "${options.kind}" (expected one of ${VALID_KINDS.join(', ')})`);
+        const why = options.kind === 'rule' ? ' Kind "rule" has no executor on the server yet, so approving it would change nothing.' : '';
+        throw new Error(`invalid --kind "${options.kind}" (expected one of ${VALID_KINDS.join(', ')}).${why}`);
       }
       const payload = parseJSON(options.payload, '--payload');
+      if (options.kind === 'block') checkBlockPayload(payload);
       const body = { accountId: options.account, kind: options.kind, payload };
       const ep = resolveEndpoint('inboxq.proposals.create');
       const data = await client.post(ep.path, { service: ep.service, body });
@@ -493,7 +895,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) ─────────────────────────────────