quoxcli 0.3.1 → 0.4.0

package/lib/commands/engagement.js

@@ -4,6 +4,7 @@
  * quox engagement create <name> --environment-tier <tier> [--risk-ceiling <tier>]
  * quox engagement list
  * quox engagement show <id>
+ * quox engagement verify <id>
  * quox engagement add-target <id> <type> <value> [--verification-method <method>]
  * quox engagement verify-target <id> <targetId>
  *
@@ -20,6 +21,7 @@ import { writeFileSync } from 'node:fs';
 import { formatOutput, formatDetail, printSuccess, printInfo } from '../core/output.js';
 import { events, printEvent, line as glyphLine } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { gatherEvidence, evidenceChanged } from '../core/findingReconcile.js';
 
 export function registerEngagementCommands(program, ctx) {
   const { client, auth } = ctx;
@@ -80,6 +82,31 @@ export function registerEngagementCommands(program, ctx) {
       }, { format: program.opts().output, emptyMessage: 'No targets added yet.' });
     });
 
+  engagement
+    .command('verify <id>')
+    .description('Verify the WARD witness for an engagement (recompute receipt + Ed25519 tip signature)')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('engagement.verify', { id });
+      const data = await client.get(ep.path, { service: ep.service });
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      const ok = data.pass === true;
+      console.log(ok ? '✓ WITNESS VERIFIED' : '✗ NOT VERIFIED');
+      console.log(`  engagement   ${data.engagement_id || id}`);
+      console.log(`  witnessed    ${data.witnessed ? 'yes' : 'no'}`);
+      console.log(`  chain        ${data.chainId || '-'}`);
+      if (data.seq != null) console.log(`  entry        #${data.seq}`);
+      if (data.chainHash) console.log(`  chain hash   ${String(data.chainHash).slice(0, 40)}`);
+      console.log(`  chain recompute  ${data.chainHashRecomputed ? 'ok' : 'FAILED'}`);
+      const sig = data.signature || {};
+      console.log(`  tip signature    ${sig.status}${sig.keyId ? ` (key ${String(sig.keyId).slice(0, 16)})` : ''}`);
+      if (data.signedTip && data.signedTip.tipId) console.log(`  signed tip   ${data.signedTip.tipId} (seq ${data.signedTip.tipSeq})`);
+      if (!ok && data.reason) console.log(`  reason       ${data.reason}`);
+    });
+
   engagement
     .command('set-gripe-target <id>')
     .description('Set which repo a finding filed from this engagement goes to, and which org GitHub connector token files it. Lets a customer-site engagement file into the customer repo with the customer org token. Pass --clear (or --repo "") to fall back to the platform default (quoxai/quox) and the engagement own org.')
@@ -575,6 +602,69 @@ export function registerEngagementCommands(program, ctx) {
       printSuccess(`Schedule "${scheduleId}" deleted.`);
     });
 
+  // SITREP-FINDINGS: reconcile open findings against their issue and fix. Evidence is gathered
+  // here (git + gh on this host); the collector decides and keeps the audit trail. Resolves only
+  // on a closed issue AND a fix in the running build; a critical is never auto-resolved.
+  engagement
+    .command('reconcile [findingId]')
+    .description('Reconcile open findings against their linked issue and fix commit (landed on main, deployed in the running build). Resolves only when the issue is closed AND the fix is deployed; a critical never auto-resolves. Every change is audited')
+    .option('--link <ref...>', 'link evidence: <findingId>=<owner/repo#N | #N | commit-sha> (repeatable)')
+    .option('--repo-dir <dir>', 'git checkout to read origin/main from (default: ~/quox-dashboard)')
+    .option('--build-dir <dir>', 'the tree the running build was built from (default: ~/.quox-build/quox-dashboard)')
+    .option('--issue-repo <owner/repo>', 'repo a bare #N refers to', 'quoxai/quox')
+    .option('--no-fetch', 'do not fetch origin/main first')
+    .option('--dry-run', 'show the evidence without recording anything')
+    .action(async (findingId, options) => {
+      auth.requireAuth();
+      const { spawnSync } = await import('node:child_process');
+      const run = (cmd, args) => {
+        const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: 30000 });
+        return { ok: r.status === 0, out: String(r.stdout || '') };
+      };
+      const home = (await import('node:os')).homedir();
+      options.repoDir = options.repoDir || `${home}/quox-dashboard`;
+      options.buildDir = options.buildDir || `${home}/.quox-build/quox-dashboard`;
+      const links = {};
+      for (const l of options.link || []) {
+        const m = /^(FND_[0-9A-Z]+)=(.+)$/.exec(String(l));
+        if (!m) throw new Error(`--link must look like FND_...=<issue or sha>, got "${l}"`);
+        const v = m[2].trim();
+        links[m[1]] = { ...(links[m[1]] || {}), ...(/^[0-9a-f]{7,40}$/i.test(v) ? { commit: v } : { issue: v }) };
+      }
+      if (options.fetch !== false) run('git', ['-C', options.repoDir, 'fetch', '--quiet', 'origin', 'main']);
+      const ep = resolveEndpoint('engagement.findings.open', {});
+      const all = (await client.get(ep.path, { service: ep.service })).findings || [];
+      const findings = findingId ? all.filter((f) => f.id === findingId) : all;
+      if (findingId && !findings.length) throw new Error(`Finding "${findingId}" is not open in this org`);
+      const rows = [];
+      for (const f of findings) {
+        const ev = gatherEvidence(f, links[f.id] || {}, { repoDir: options.repoDir, buildDir: options.buildDir, issueRepo: options.issueRepo, run });
+        const row = { id: f.id, severity: f.severity, status: f.status, issue: ev.issue_ref ? `${ev.issue_ref}${ev.issue_state ? ` (${ev.issue_state})` : ''}` : '',
+          fix: ev.fix_commit ? `${ev.fix_commit.slice(0, 9)} ${ev.fix_state}` : '', outcome: '' };
+        if (!Object.keys(ev).length) { row.outcome = 'no evidence'; rows.push(row); continue; }
+        if (!evidenceChanged(f, ev)) { row.outcome = 'unchanged'; rows.push(row); continue; }
+        if (options.dryRun) { row.outcome = 'would record'; rows.push(row); continue; }
+        const rep = resolveEndpoint('engagement.findings.reconcile', { findingId: f.id });
+        const data = await client.post(rep.path, { service: rep.service, body: ev });
+        row.outcome = `${data.outcome}: ${data.reason}`;
+        row.status = data.finding?.status || row.status;
+        rows.push(row);
+      }
+      formatOutput({ columns: ['id', 'severity', 'status', 'issue', 'fix', 'outcome'], headers: ['Finding', 'Severity', 'Status', 'Issue', 'Fix', 'Outcome'], rows },
+        { format: program.opts().output, emptyMessage: 'No open findings.' });
+    });
+
+  engagement
+    .command('reconciliations <findingId>')
+    .description('Show the reconciliation audit trail of one finding (what evidence was recorded, when, by whom, and the outcome)')
+    .action(async (findingId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('engagement.findings.reconciliations', { findingId });
+      const data = await client.get(ep.path, { service: ep.service });
+      formatOutput({ columns: ['created_at', 'outcome', 'reason', 'actor', 'evidence'], headers: ['When', 'Outcome', 'Reason', 'Actor', 'Evidence'], rows: data.reconciliations || [] },
+        { format: program.opts().output, emptyMessage: 'No reconciliations recorded.' });
+    });
+
   engagement
     .command('sync-issues <id>')
     .description('Reconcile this engagement\'s filed findings against their GitHub issue state. A closed issue auto-resolves its finding. Honest no-op if GitHub is not configured')

package/lib/commands/evidence.js

@@ -0,0 +1,154 @@
+/**
+ * Evidence commands (DEVFLEET EV-1): `quox evidence status` shows size, rows, time span, growth, archive and
+ * backup for the AEE, WARD and VOLT stores. Read-only; the collector route is instance admin only.
+ */
+
+import chalk from 'chalk';
+import { formatOutput } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import fs from 'node:fs';
+import { exportConversationBundle, newestConversationId } from '../evidence/bundleExport.js';
+import { verifyEvidenceBundle } from '../evidence/bundleVerify.js';
+
+const NA = 'n/a';
+
+// verify_state from auth, said once: 'verified', 'never verified', 'verify failed', 'verify n/a'.
+function verifyLabel(v) {
+  if (v === null || v === undefined || v === '') return 'verify n/a';
+  if (v === 'verified') return 'verified';
+  if (v === 'failed') return 'verify failed';
+  if (v === 'never_verified') return 'never verified';
+  return `verify ${String(v).replace(/_/g, ' ')}`;
+}
+
+function bytes(n) {
+  if (n === null || n === undefined) return NA;
+  if (n < 1024) return `${n} B`;
+  const units = ['KB', 'MB', 'GB', 'TB'];
+  let v = n; let i = -1;
+  do { v /= 1024; i++; } while (v >= 1024 && i < units.length - 1);
+  return `${v.toFixed(1)} ${units[i]}`;
+}
+
+const val = (v) => (v === null || v === undefined ? NA : String(v));
+const day = (iso) => (iso ? String(iso).slice(0, 10) : NA);
+
+function archiveCell(a) {
+  if (a === null || a === undefined) return NA;
+  if (typeof a === 'string') return a;
+  return `${a.anchors} anchors${a.newest_archived_at ? `, newest ${day(a.newest_archived_at)}` : ''}`;
+}
+
+function diskCell(d) {
+  if (!d) return NA;
+  return `${bytes(d.free_bytes)} free of ${bytes(d.total_bytes)} (${d.mount})`;
+}
+
+export function registerEvidenceCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const evidence = program
+    .command('evidence')
+    .description('Evidence stores: AEE, WARD, VOLT');
+
+  evidence
+    .command('status')
+    .description('Evidence stores (AEE, WARD, VOLT): size, rows, time span, growth, archive and backup, read-only')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('evidence.status');
+      const data = await client.get(ep.path, { service: ep.service });
+      if (!data || !Array.isArray(data.stores)) {
+        throw new Error(`Unexpected evidence status response${data && data.error ? `: ${data.error}` : ''}`);
+      }
+      const format = program.opts().output;
+      if (format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+
+      const rows = data.stores.map((s) => ({
+        store: s.name,
+        size: bytes(s.bytes),
+        wal: bytes(s.wal_bytes),
+        rows: val(s.rows),
+        oldest: day(s.oldest),
+        newest: day(s.newest),
+        last7d: s.per_day && s.per_day.last_7d ? `${s.per_day.last_7d.per_day}/day` : NA,
+        archive: archiveCell(s.archive),
+        disk: diskCell(s.disk),
+      }));
+      formatOutput({
+        columns: ['store', 'size', 'wal', 'rows', 'oldest', 'newest', 'last7d', 'archive', 'disk'],
+        headers: ['Store', 'Size', 'WAL', 'Rows', 'Oldest', 'Newest', 'Last 7d', 'Archive', 'Disk'],
+        rows,
+      }, { format, full: true });
+
+      const b = data.backup || {};
+      if (b.last) {
+        const l = b.last;
+        const when = l.ts ? `${String(l.ts).slice(0, 10)} ${String(l.ts).slice(11, 16)} UTC` : NA;
+        const parts = [
+          b.age_hours === null || b.age_hours === undefined ? 'age n/a' : `${b.age_hours} h ago`,
+          l.count === null || l.count === undefined ? 'count n/a' : `${l.count} backups`,
+          (b.scope && b.scope.ts) || 'all orgs',
+        ];
+        const line = `Last backup ${when} (${parts.join(', ')})${b.stale ? ' STALE' : ''}`;
+        console.log(b.stale ? chalk.yellow(line) : line);
+        // The newest backup can belong to any org; health and verify state are the caller's org only.
+        console.log(`Backup health (${(b.scope && b.scope.health) || 'your org'}): ${val(l.status)}, ${verifyLabel(l.verified)}`);
+        if (l.last_failed) console.log(`  last failure: ${val(l.last_failed.error)} (${l.last_failed.at ? String(l.last_failed.at).slice(0, 16).replace('T', ' ') + ' UTC' : NA})`);
+        if (b.verify_error) console.log(`  ${b.verify_error}`);
+      } else {
+        console.log(`Backup: ${NA}`);
+      }
+
+      const errors = [];
+      for (const s of data.stores) for (const e of s.errors || []) errors.push(`${s.name}: ${e}`);
+      if (b.error) errors.push(`backup: ${b.error}`);
+      if (errors.length) {
+        console.log(chalk.yellow('Errors'));
+        for (const e of errors) console.log(`  ${e}`);
+      }
+    });
+  evidence
+    .command('bundle')
+    .description('Export a signed, offline-verifiable evidence bundle (zip) of every AEE envelope, WARD receipt and VOLT run for one conversation')
+    .argument('[conversation]', 'conversation id (the corr); default: your newest chat conversation')
+    .option('--out <file.zip>', 'where to write it (default ~/quox-evidence/<conversation>-<timestamp>.zip)')
+    .option('--json', 'print the result as JSON')
+    .action(async (conversation, options) => {
+      auth.requireAuth();
+      const corr = conversation || await newestConversationId(client);
+      if (!corr) throw new Error('No conversation to export: pass a conversation id (`quox conversation list`).');
+      const r = await exportConversationBundle({ client, corr, out: options.out });
+      const failed = r.verify.checks.filter((c) => !c.ok);
+      if (options.json || program.opts().output === 'json') {
+        console.log(JSON.stringify({ path: r.path, conversation: r.corr, bytes: r.bytes, envelopes: r.envelopes, receipts: r.receipts, verified: r.verify.ok, failed_checks: failed }, null, 2));
+      } else {
+        console.log(`${r.verify.ok ? chalk.green('Evidence bundle written') : chalk.red('Evidence bundle written but FAILED verification')}: ${r.path}`);
+        console.log(`  conversation ${r.corr} | ${r.envelopes} envelopes | ${r.receipts} WARD receipts | ${r.bytes} bytes`);
+        console.log(`  verify offline: quox evidence verify ${r.path}`);
+        for (const c of failed) console.log(chalk.red(`  FAILED ${c.name}: ${c.detail || ''}`));
+      }
+      if (!r.verify.ok) process.exitCode = 1;
+    });
+
+  evidence
+    .command('verify')
+    .description('Verify an evidence bundle zip offline: file hashes, envelope list hash, counts and the Ed25519 signature (no network)')
+    .argument('<file.zip>', 'a bundle from `quox evidence bundle`')
+    .option('--json', 'print the result as JSON')
+    .action(async (file, options) => {
+      let bytes;
+      try { bytes = fs.readFileSync(file); } catch (e) { throw new Error(`Cannot read ${file}: ${e.message}`); }
+      const v = await verifyEvidenceBundle(bytes);
+      if (options.json || program.opts().output === 'json') {
+        console.log(JSON.stringify({ file, verified: v.ok, checks: v.checks, counts: v.manifest?.counts || null, conversation: v.manifest?.corr || null, key_id: v.signature?.key_id || null }, null, 2));
+      } else {
+        for (const c of v.checks) console.log(`  ${c.ok ? chalk.green('PASS') : chalk.red('FAIL')} ${c.name}${c.detail ? ` (${c.detail})` : ''}`);
+        const m = v.manifest;
+        console.log(v.ok
+          ? chalk.green(`VERIFIED: ${m.counts.envelopes} envelopes, ${m.counts.ward_receipts} WARD receipts, conversation ${m.corr}, signed by ${v.signature.key_id}`)
+          : chalk.red('NOT VERIFIED: this bundle was altered or is not a Quox evidence bundle.'));
+      }
+      if (!v.ok) process.exitCode = 1;
+    });
+}

package/lib/commands/ext.js

@@ -0,0 +1,23 @@
+/**
+ * quox ext add|remove|list <pkg>
+ *
+ * The listing behind quoxon's extension host (cli/lib/quoxon/extensions.js, contract EXTENSIONS.md). It edits
+ * ~/.quox/extensions.json only; it does not install npm packages (npm i -g <pkg> does that). Nothing loads unless
+ * it is both installed and listed.
+ */
+import { readExtList, extAdd, extRemove, extListPath } from '../quoxon/extensions.js';
+
+export function registerExtCommands(program) {
+  const ext = program.command('ext').description('Optional quoxon extensions: list, add or remove one (npm i -g <pkg> installs it)');
+  const out = (r) => { console.log(r.text); if (!r.ok) process.exitCode = 1; };
+  ext.command('list').description('Extensions listed in ~/.quox/extensions.json')
+    .option('--json', 'print as JSON')
+    .action((opts) => {
+      const list = readExtList();
+      if (opts.json || program.opts().output === 'json') { console.log(JSON.stringify({ file: extListPath(), extensions: list }, null, 2)); return; }
+      if (!list.length) { console.log('No extensions listed. quox ext add <pkg>'); return; }
+      for (const x of list) console.log(`${x.name}  ${x.enabled ? 'on' : 'off'}`);
+    });
+  ext.command('add').description('List an extension so quoxon loads it once installed').argument('<pkg>').action((pkg) => out(extAdd(pkg)));
+  ext.command('remove').description('Stop listing an extension').argument('<pkg>').action((pkg) => out(extRemove(pkg)));
+}

package/lib/commands/fleet.js

@@ -595,6 +595,31 @@ export function registerFleetCommands(program, ctx) {
       }, { format: program.opts().output, emptyMessage: data && data.bastion === false ? 'No agents enrolled yet.' : 'No hosts in the Bastion registry.' });
     });
 
+  fleet
+    .command('ping [host]')
+    .description('Refresh Bastion host state by pinging every host (or one); org admin, writes a quox.fleet.ping evidence envelope')
+    .action(async (host) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('v1.fleet.ping');
+      const data = await client.post(ep.path, { service: ep.service, body: host ? { host } : {}, timeout: 60000 });
+      const results = data.results || [];
+      const summary = data.summary || { requested: results.length, reachable: results.filter(r => r.reachable).length, unreachable: results.filter(r => !r.reachable).length };
+      if (program.opts().output === 'json') {
+        formatDetail({ success: data.success !== false, results, summary }, { format: 'json' });
+        return;
+      }
+      formatOutput({
+        columns: ['host_id', 'reachable', 'latency'],
+        headers: ['Host', 'Reachable', 'Latency'],
+        rows: results.map(r => ({
+          host_id: r.host_id,
+          reachable: r.reachable ? 'yes' : (r.error ? `no (${r.error})` : 'no'),
+          latency: typeof r.latency_ms === 'number' ? `${r.latency_ms}ms` : '-',
+        })),
+      }, { format: program.opts().output, emptyMessage: 'No hosts answered the ping.' });
+      printInfo(`${summary.reachable} of ${summary.requested} reachable, ${summary.unreachable} unreachable`);
+    });
+
   fleet
     .command('gpu')
     .description('List the durable GPU fleet')

package/lib/commands/hat.js

@@ -4,6 +4,7 @@
  *   quox hat list
  *   quox hat show <id|key> [--rev <n>]
  *   quox hat reset <id|key> --yes      (audited reset-to-template, built-ins)
+ *   quox hat upgrade <id|key> [--dry-run|--yes]  (3-way merge of an org-edited built-in onto the current template)
  *   quox hat create <key> --name "<Name>" [--from <hat>] [--agents a,b] [--tools x,y] [--mode m] [--offer o]
  *   quox hat edit <hat> [--name N] [--add-agents|--remove-agents|--agents] [--add-tools|--remove-tools|--tools] [--mode m]
  *   quox hat delete <hat> --yes        (custom hats only)
@@ -42,6 +43,12 @@ export function templateLabel(hat) {
   const latestAuthor = Array.isArray(hat.revisions) && hat.revisions[0] ? hat.revisions[0].created_by : null;
   const customised = typeof latestAuthor === 'string' && !latestAuthor.startsWith('template:');
   if (latest && cur && cur < latest) return `v${cur} (template v${latest} available)`;
+  // Merge-upgrade: the last applied 3-way merge (org edits carried onto the new template).
+  const u = hat.last_upgrade;
+  if (u && u.to_template_version === cur) {
+    const k = Number(u.org_changes_kept) || 0;
+    return `v${cur}, upgraded from v${u.from_template_version}, ${k} org change${k === 1 ? '' : 's'} kept`;
+  }
   return customised ? `v${cur || '?'} (edited)` : `v${cur || '?'}`;
 }
 
@@ -89,6 +96,30 @@ export async function findUnknownAgents(client, orgId, ids) {
 
 function isBuiltin(h) { return !!h?.template_key; }
 
+const fmtItem = (e) => (e.item !== undefined ? `${e.path}: ${e.item}` : e.path);
+
+/** Human preview of a merge upgrade (exported for reuse by other surfaces). */
+export function renderUpgradePreview(key, p) {
+  const out = [];
+  out.push(chalk.bold(`Hat ${key}: template v${p.from_template_version} -> v${p.to_template_version}`) + chalk.dim(`  (from rev ${p.from_revision})`));
+  out.push(`Tools added:    ${(p.tools_added || []).join(', ') || 'none'}`);
+  out.push(`Tools removed:  ${(p.tools_removed || []).join(', ') || 'none'}`);
+  const changed = (p.template_changed || []).map(c => c.path);
+  if (changed.length) out.push(`Template changed: ${changed.join(', ')}`);
+  out.push(chalk.bold(`Org changes kept (${(p.org_changes || []).length}):`));
+  for (const c of p.org_changes || []) out.push(`  ${c.change.padEnd(7)} ${fmtItem(c)}`);
+  if (!(p.org_changes || []).length) out.push('  none');
+  out.push(chalk.bold(`Conflicts, org choice kept (${(p.conflicts || []).length}):`));
+  for (const c of p.conflicts || []) out.push(`  ${c.path}${c.reason ? ` (${c.reason})` : ''}`);
+  if (!(p.conflicts || []).length) out.push('  none');
+  out.push(chalk.bold(`Held, would widen authorization (${(p.held || []).length}):`));
+  for (const c of p.held || []) out.push(`  ${c.path} ${(c.fields || []).join(', ')}`);
+  if (!(p.held || []).length) out.push('  none');
+  out.push(`Valid:          ${p.valid ? 'yes' : `NO: ${(p.errors || []).join('; ')}`}`);
+  out.push(`Digest:         ${p.from_digest || '-'} -> ${p.digest}`);
+  return out;
+}
+
 export function registerHatCommands(program, ctx) {
   const { client, auth } = ctx;
 
@@ -234,6 +265,51 @@ export function registerHatCommands(program, ctx) {
       if (program.opts().output === 'json') { console.log(JSON.stringify({ hat: h }, null, 2)); return; }
       console.log(`  Ⓠ QUOX │ hat ${h.key} reset to template │ rev ${h.current_revision} · ${templateLabel(h)} ✔`);
     });
+  // ── hat upgrade ─────────────────────────────────────────────────────────────
+  hat
+    .command('upgrade <hat>')
+    .description('Carry an org-edited built-in hat onto the current template (3-way merge: org changes kept, conflicts keep the org choice, widening authz changes held); previews unless --yes')
+    .option('--dry-run', 'preview the merge only (writes nothing); the default without --yes')
+    .option('--yes', 'apply the previewed merge as a new system-authored revision (audited)')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      if (options.dryRun && options.yes) throw new Error('Pass either --dry-run (preview) or --yes (apply), not both.');
+      const orgId = resolveOrgId(auth, program);
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) {
+        const keys = (list?.hats || []).map(h => h.key).join(', ') || 'none';
+        throw new Error(`No hat '${ref}' in this org. Available: ${keys}`);
+      }
+      const pep = resolveEndpoint('hat.upgrade.preview', { orgId, hatId: found.id });
+      let data;
+      try {
+        data = await client.get(pep.path, { service: pep.service });
+      } catch (err) {
+        const code = err?.response?.data?.error || err?.data?.error || err?.body?.error;
+        if (code === 'up_to_date') { console.log(`  Ⓠ QUOX │ hat ${found.key} upgrade │ already on template v${found.template_version} ✔`); return; }
+        throw err;
+      }
+      const p = data?.preview;
+      if (!p) throw new Error(`Upgrade preview for '${ref}' returned nothing`);
+      const json = program.opts().output === 'json';
+
+      if (!options.yes) {
+        if (json) { console.log(JSON.stringify({ preview: p, applied: false }, null, 2)); return; }
+        console.log(renderUpgradePreview(found.key, p).join('\n'));
+        console.log('');
+        console.log(`  dry run: nothing written. Apply with: quox hat upgrade ${found.key} --yes`);
+        return;
+      }
+      if (!p.valid) throw new Error(`The merged hat does not validate: ${(p.errors || []).join('; ')}`);
+      const aep = resolveEndpoint('hat.upgrade', { orgId, hatId: found.id });
+      const res = await client.post(aep.path, { service: aep.service, body: { expected_revision: p.from_revision } });
+      const h = res?.hat;
+      if (!h) throw new Error(`Upgrade of '${ref}' returned no hat`);
+      if (json) { console.log(JSON.stringify({ hat: h, preview: res.preview || p, applied: true }, null, 2)); return; }
+      console.log(`  Ⓠ QUOX │ hat ${h.key} upgraded │ rev ${h.current_revision} · ${templateLabel(h)} ✔`);
+    });
+
   // ── hat create (custom) ───────────────────────────────────────────────────────
   hat
     .command('create <key>')

package/lib/commands/image.js

@@ -0,0 +1,68 @@
+/**
+ * quox image generate "<prompt>" [--out file] [--provider gemini|openai] [--aspect-ratio 16:9] [--count n]
+ *
+ * CLI verb first for image generation. It runs the SAME governed tool the chat uses (gemini_image_generate via
+ * POST /api/v1/tools/execute), so the provider fallback, the receipt/witnessing and the plain all-fail message are
+ * the collector's, not re-implemented here. Providers tried: Gemini, then OpenAI, using only what the org already
+ * connected (`quox provider list`). Nothing here adds a provider or a key.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { printSuccess } from '../core/output.js';
+import { executeGovernedTool } from './tool.js';
+
+const EXT = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' };
+
+export function registerImageCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const image = program.command('image').description('Generate images with the providers your org has connected');
+
+  image
+    .command('generate')
+    .description('Generate an image from a prompt (tries Gemini, then OpenAI; says which made it)')
+    .argument('<prompt>', 'what to draw')
+    .option('--out <file>', 'where to save the image (default ./quox-image-<time>.png)')
+    .option('--provider <name>', 'use only this provider: gemini or openai (no fall-through)')
+    .option('--aspect-ratio <ratio>', 'e.g. 16:9 for a hero, 1:1 for social, 9:16 for stories')
+    .option('--count <n>', 'how many images (1-4)', '1')
+    .action(async (prompt, options) => {
+      const input = { prompt };
+      if (options.provider) input.provider = options.provider;
+      if (options.aspectRatio) input.aspect_ratio = options.aspectRatio;
+      const n = Number(options.count);
+      if (n > 1) input.number_of_images = Math.min(n, 4);
+
+      const data = await executeGovernedTool({ client, auth, program }, 'gemini_image_generate', input, { reason: 'quox image generate' });
+      const r = (data && data.result && typeof data.result === 'object') ? data.result : (data || {});
+      const failed = (data && data.success === false) || r.success === false;
+
+      if (program.opts().output === 'json') {
+        // Never dump base64 into a terminal or a pipe: report where the files went.
+        const out = failed ? r : { ...r, images: undefined };
+        if (!failed) out.files = saveImages(r.images, options.out);
+        console.log(JSON.stringify({ ...out, ...(failed && !r.error && data.error ? { error: data.error } : {}) }, null, 2));
+        if (failed) process.exitCode = 1;
+        return;
+      }
+      if (failed) {
+        console.error(r.error || data.error || 'Image generation failed.');
+        process.exitCode = 1;
+        return;
+      }
+      const files = saveImages(r.images, options.out);
+      printSuccess(`Made by ${r.provider_used || 'gemini'}${r.model_used ? ` (${r.model_used})` : ''}: ${files.join(', ')}`);
+      if (r.note) console.log(r.note);
+    });
+}
+
+function saveImages(images, out) {
+  const list = Array.isArray(images) ? images : [];
+  const stamp = Date.now();
+  return list.map((img, i) => {
+    const ext = EXT[img.mime_type] || 'png';
+    let file = out || `quox-image-${stamp}.${ext}`;
+    if (list.length > 1) { const p = path.parse(file); file = path.join(p.dir, `${p.name}-${i + 1}${p.ext || `.${ext}`}`); }
+    fs.writeFileSync(file, Buffer.from(img.base64, 'base64'));
+    return file;
+  });
+}