quoxcli 0.5.0 → 0.6.1

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,7 +49,77 @@ 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' };
@@ -112,9 +185,11 @@ export function registerMailCommands(program, ctx) {
     .command('connect')
     .description('Connect a mailbox. Reuse a stored credential (--credential), or create one inline from IMAP settings (--imap-host with --password-env, or --provider gmail|icloud|outlook to pre-fill host/port). Creating a credential needs a human/admin profile, e.g. quox -p moo mail connect ...')
     .option('--credential <id>', 'reuse a stored email_account credential ID')
-    .requiredOption('--email <address>', 'mailbox address (also the IMAP username unless --username is given)')
+    .option('--email <address>', 'mailbox address (also the IMAP username unless --username is given); required except with --provider fixture')
     .option('--username <user>', 'IMAP username, if different from --email')
-    .option('--provider <name>', 'named email provider (gmail, icloud, outlook): pre-fills IMAP/SMTP host and port')
+    .option('--provider <name>', 'named email provider (gmail, icloud, outlook): pre-fills IMAP/SMTP host and port; fixture = a seeded scratch-org mailbox (needs --seed)')
+    .option('--seed <name>', 'with --provider fixture: the fixture seed to load (e.g. scratch-office-day); scratch orgs on a fixture-enabled deployment only, the server decides')
+    .option('--run <id>', 'with --provider fixture: proof run id substituted into the seed ({{run}})')
     .option('--imap-host <host>', 'IMAP host (creating a new credential; not required with --provider)')
     .option('--imap-port <n>', 'IMAP port', '993')
     .option('--smtp-host <host>', 'SMTP host (defaults to --imap-host)')
@@ -142,6 +217,23 @@ export function registerMailCommands(program, ctx) {
         );
       }
 
+      // AQ-9H LADON-P1B: a seeded fixture mailbox for scratch-org proof runs. No credential and no env
+      // pre-check here: the collector's fixture gate (deployment env + platform-admin scratch mark) decides,
+      // and its 403 names the condition that failed.
+      if (options.provider === 'fixture') {
+        if (!options.seed) throw new Error('--seed <name> is required with --provider fixture (e.g. --seed scratch-office-day).');
+        const fbody = { provider: 'fixture', seed: options.seed };
+        if (options.run) fbody.run = options.run;
+        if (options.name) fbody.displayName = options.name;
+        const fep = resolveEndpoint('inboxq.accounts.create');
+        const fdata = await client.post(fep.path, { service: fep.service, body: fbody });
+        if (isJsonOutput(program)) return printJson(fdata);
+        const facc = fdata.account || fdata;
+        printSuccess(`Connected fixture mailbox ${facc.emailAddress || ''} (${facc.id}) from seed ${options.seed} in org ${sessionOrg || '(active)'}`);
+        return;
+      }
+      if (!options.email) throw new Error("required option '--email <address>' not specified");
+
       let credentialId = options.credential;
 
       // Inline credential creation: turns the ugly `vault create --credentials-stdin`
@@ -579,20 +671,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 });

package/lib/commands/mcp.js

@@ -0,0 +1,190 @@
+/**
+ * QuoxMCP setup from the CLI (VULCAN): the CLI rung under Settings > MCP credentials.
+ *
+ *   quox mcp token create --label <text> [--days <1-90>]   mint a personal MCP token (raw token shown ONCE)
+ *   quox mcp token list                                    your MCP tokens (never the token or its hash)
+ *   quox mcp token revoke <id>                             revoke one of your tokens
+ *   quox mcp bundle [--out <file>]                         personalised Claude Desktop .mcpb (EMBEDS a fresh token)
+ *
+ * Tokens: auth /api/auth/tokens/mcp (services/auth/routes/mcp-tokens.js). Bundle: collector /api/v1/mcp/bundle
+ * (services/collector/routes/mcp-bundle.js), which takes the raw token in the body and bakes it into the
+ * bundle manifest as QUOX_SERVICE_KEY, so the bundle file is a credential: written 0600, never printed.
+ */
+
+import { existsSync, writeFileSync, chmodSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { formatOutput, printSuccess, printInfo, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxError } from '../core/errors.js';
+
+const MAX_DAYS = 90;
+const OUTPUT_FORMATS = ['table', 'json', 'csv', 'quiet'];
+const DEFAULT_BUNDLE = 'quoxmcp.mcpb';
+
+function parseDays(raw) {
+  if (raw === undefined) return undefined;
+  const s = String(raw).trim();
+  const n = Number(s);
+  if (!/^\d+$/.test(s) || n < 1 || n > MAX_DAYS) {
+    throw new QuoxError(`--days must be a whole number from 1 to ${MAX_DAYS} (got "${raw}")`, 1);
+  }
+  return n;
+}
+
+function parseLabel(raw) {
+  const label = String(raw ?? '').trim();
+  if (!label) throw new QuoxError('--label must not be empty', 1);
+  if (label.length > 128) throw new QuoxError('--label must be 128 characters or fewer', 1);
+  return label;
+}
+
+const isJson = (program) => program.opts().output === 'json';
+
+export function registerMcpCommands(program, ctx) {
+  const { client, auth, config } = ctx;
+
+  async function mint(label, days) {
+    const ep = resolveEndpoint('mcp.tokens.create');
+    return client.post(ep.path, {
+      service: ep.service,
+      sensitive: true,
+      body: { label, ...(days !== undefined ? { expires_in_days: days } : {}) },
+    });
+  }
+
+  const mcp = program
+    .command('mcp')
+    .description('QuoxMCP setup: personal MCP tokens and the Claude Desktop bundle');
+
+  const token = mcp
+    .command('token')
+    .description('Personal MCP tokens (qmcp_...) for connecting an MCP client to Quox');
+
+  token
+    .command('create')
+    .description(`Mint a personal MCP token for your active org; the raw token is shown ONCE (expires in ${MAX_DAYS} days unless --days is lower)`)
+    .requiredOption('--label <text>', 'what this token is for, e.g. "work laptop" (max 128 chars)')
+    .option('--days <n>', `days until it expires, 1 to ${MAX_DAYS} (default ${MAX_DAYS})`)
+    .action(async (opts) => {
+      auth.requireAuth();
+      const label = parseLabel(opts.label);
+      const days = parseDays(opts.days);
+      const data = await mint(label, days);
+      if (isJson(program)) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      printSuccess(`MCP token ${data.id} created (label "${data.label ?? label}").`);
+      console.log('Token (shown once, store it now; it cannot be shown again):');
+      console.log(data.token);
+      console.log(`Expires: ${data.expires_at || 'no expiry'}`);
+      printInfo(`Revoke it any time with: quox mcp token revoke ${data.id}`);
+    });
+
+  token
+    .command('list')
+    .description('List your MCP tokens (id, label, created, last used, expiry, revoked); never shows a token value')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mcp.tokens.list');
+      const data = await client.get(ep.path, { service: ep.service });
+      const tokens = Array.isArray(data?.tokens) ? data.tokens : [];
+      formatOutput({
+        columns: ['id', 'label', 'created_at', 'last_used_at', 'expires_at', 'revoked_at'],
+        headers: ['ID', 'Label', 'Created', 'Last used', 'Expires', 'Revoked'],
+        rows: tokens.map((t) => ({
+          id: t.id,
+          label: t.label,
+          created_at: t.created_at || '',
+          last_used_at: t.last_used_at || 'never',
+          expires_at: t.expires_at || 'no expiry',
+          revoked_at: t.revoked_at || 'no',
+        })),
+      }, { format: program.opts().output, raw: tokens, emptyMessage: 'No MCP tokens. Create one with: quox mcp token create --label <text>' });
+    });
+
+  token
+    .command('revoke')
+    .description('Revoke one of your MCP tokens (takes effect at the collector straight away)')
+    .argument('<id>', 'token id from `quox mcp token list`')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mcp.tokens.revoke', { id });
+      try {
+        await client.delete(ep.path, { service: ep.service });
+      } catch (err) {
+        if (err?.status === 404) throw new QuoxError(`MCP token ${id} not found or already revoked.`, 1);
+        throw err;
+      }
+      printSuccess(`MCP token ${id} revoked.`);
+    });
+
+  mcp
+    .command('bundle')
+    .description('Download a personalised QuoxMCP bundle (.mcpb) for Claude Desktop. It mints a NEW MCP token and embeds a live MCP token in the file: treat the file as a secret (written 0600, never printed)')
+    .option('--out <path>', `where to save it (-o <path> also works); default ./${DEFAULT_BUNDLE}`)
+    .option('--label <text>', 'label for the token minted into the bundle', 'Claude Desktop')
+    .option('--days <n>', `days until the embedded token expires, 1 to ${MAX_DAYS} (default ${MAX_DAYS})`)
+    .option('--collector-url <url>', 'collector URL the bundle will call (default: this profile\'s collector URL)')
+    .option('--force', 'overwrite an existing file')
+    .addHelpText('after', '\nThe bundle embeds a live MCP token. Anyone holding the file can act as you over MCP until the token\nexpires or you revoke it (quox mcp token revoke <id>). Do not commit or share it.\n')
+    .action(async (opts) => {
+      auth.requireAuth();
+      const label = parseLabel(opts.label);
+      const days = parseDays(opts.days);
+      const collectorUrl = opts.collectorUrl || config?.getServiceUrl?.('collector');
+      try {
+        if (!collectorUrl) throw new Error('missing');
+        new URL(collectorUrl);
+      } catch {
+        throw new QuoxError(`--collector-url must be a valid URL (got "${collectorUrl ?? ''}")`, 1);
+      }
+      const g = program.opts().output;
+      const outArg = opts.out || (g && !OUTPUT_FORMATS.includes(g) ? g : undefined) || DEFAULT_BUNDLE;
+      const target = resolve(ctx.cwd || process.cwd(), outArg);
+      if (existsSync(target) && !opts.force) throw new QuoxError(`${target} already exists. Use --force to overwrite.`, 1);
+
+      const minted = await mint(label, days);
+      const revokeMinted = async () => {
+        try {
+          const rep = resolveEndpoint('mcp.tokens.revoke', { id: minted.id });
+          await client.delete(rep.path, { service: rep.service });
+          printWarning(`Revoked the token minted for this bundle (${minted.id}).`);
+        } catch {
+          printWarning(`Could not revoke the token minted for this bundle; revoke it with: quox mcp token revoke ${minted.id}`);
+        }
+      };
+
+      const bep = resolveEndpoint('mcp.bundle');
+      let buf;
+      try {
+        const res = await client.post(bep.path, {
+          service: bep.service,
+          raw: true,
+          sensitive: true,
+          timeout: 120000,
+          body: { token: minted.token, collector_url: collectorUrl, agent_id: 'quox' },
+        });
+        if (!res.ok) {
+          let detail = '';
+          try { const b = await res.json(); detail = b?.message || b?.error || ''; } catch { /* non-JSON body */ }
+          throw new QuoxError(`Bundle generation failed: HTTP ${res.status}${detail ? ` (${detail})` : ''}.`, 1);
+        }
+        buf = Buffer.from(await res.arrayBuffer());
+      } catch (err) {
+        await revokeMinted();
+        throw err;
+      }
+
+      writeFileSync(target, buf, { mode: 0o600 });
+      chmodSync(target, 0o600); // mode only applies on create; --force over an existing file must tighten it too
+      if (isJson(program)) {
+        console.log(JSON.stringify({ path: target, bytes: buf.length, token_id: minted.id, expires_at: minted.expires_at ?? null, collector_url: collectorUrl }, null, 2));
+        return;
+      }
+      printSuccess(`Saved ${target} (${buf.length} bytes, mode 0600).`);
+      console.log(`It embeds MCP token ${minted.id} (expires ${minted.expires_at || 'never'}) and calls ${collectorUrl}.`);
+      console.log('Open the file with Claude Desktop to install QuoxMCP. Treat it as a secret.');
+      printInfo(`Revoke it any time with: quox mcp token revoke ${minted.id}`);
+    });
+}

package/lib/commands/mon.js

@@ -78,6 +78,17 @@ function reportDockerReadFailures(data) {
   return false;
 }
 
+/**
+ * AGH-chain reads answer 202 { status: 'computing' } while the collector builds them in the
+ * background; an empty body then is not data. Says so and returns true (caller stops).
+ */
+function reportComputing(program, data, message) {
+  if (!data || data.status !== 'computing') return false;
+  if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return true; }
+  printWarning(message);
+  return true;
+}
+
 export function registerMonCommands(program, ctx) {
   const { client, auth } = ctx;
 
@@ -372,6 +383,7 @@ export function registerMonCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('mon.agh-chain.leaderboard.list');
       const data = await client.get(ep.path, { service: ep.service, query: { window: options.window } });
+      if (reportComputing(program, data, 'The leaderboard is computing, try again shortly.')) return;
       formatOutput({
         columns: ['agent_id', 'claims_made', 'claims_verified', 'claims_stripped', 'unfulfilled_promises', 'honesty_rate'],
         headers: ['Agent', 'Claims Made', 'Verified', 'Stripped', 'Unfulfilled', 'Honesty Rate'],
@@ -388,6 +400,7 @@ export function registerMonCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('mon.agh-chain.leaderboard.get', { agentId });
       const data = await client.get(ep.path, { service: ep.service, query: { window: options.window } });
+      if (reportComputing(program, data, 'These honesty metrics are computing, try again shortly.')) return;
       formatDetail(data, { format: program.opts().output, title: `Honesty metrics: ${agentId}` });
     });
 
@@ -401,6 +414,7 @@ export function registerMonCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('mon.agh-chain.leaderboard.events.list', { agentId });
       const data = await client.get(ep.path, { service: ep.service, query: { window: options.window, guard: options.guard } });
+      if (reportComputing(program, data, 'These drill-through events are computing, try again shortly.')) return;
       formatOutput({
         columns: ['event_id', 'run_id', 'ts', 'payload_preview'],
         headers: ['Event', 'Run', 'Time', 'Preview'],