quoxcli 0.3.1 → 0.5.0

package/lib/commands/evidence.js

@@ -0,0 +1,155 @@
+/**
+ * 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. Instance admin only')
+    .addHelpText('after', '\nInstance admin only: an org owner or admin who is not an instance admin gets a 403 (exit 4).')
+    .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/gripe.js

@@ -22,7 +22,7 @@
  */
 
 import { formatDetail, printInfo, printWarning } from '../core/output.js';
-import { events, line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { events, gripeFiledLine, line as glyphLine, printEvent } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { resolveOrgId } from './helpers.js';
 
@@ -50,20 +50,28 @@ export function registerGripeCommands(program, { client, auth }) {
         return;
       }
       printEvent(glyphLine('quox', 'filing gripe via GRIPE'));
-      const data = await askGripe({ client, complaint, repo: options.repo, label: options.label, yes: !!options.yes, orgId });
-
-      if (program.opts().output === 'json') {
-        formatDetail(data, { format: 'json' });
-        return;
-      }
-
-      const r = await settleGripe({ client, data, complaint, options, orgId });
+      // GRIPE-QUEUE: a timeout / network / 5xx saves the gripe locally instead of losing it (/gripes in quox lists it).
+      const { gripeQueue, fileOrQueue } = await import('../quoxon/gripeQueue.js');
+      let rawData = null;
+      const f = await fileOrQueue({
+        text: complaint, repo: options.repo || null, queue: gripeQueue(), queueable: !!options.yes,
+        run: async (key) => {
+          const o = { ...options, idempotencyKey: key, queueRetryable: true };
+          rawData = await askGripe({ client, complaint, repo: options.repo, label: options.label, yes: !!options.yes, orgId });
+          if (program.opts().output === 'json') return { json: true };
+          return settleGripe({ client, data: rawData, complaint, options: o, orgId });
+        },
+      });
+      if (!f.ok && f.queued) { printWarning(`${f.saved} (${f.message})`); process.exitCode = 1; return; }
+      if (!f.ok) throw new Error(f.message);
+      if (f.json) { formatDetail(rawData, { format: 'json' }); return; }
+      const r = f;
       console.log('');
       if (r.superseded) printInfo(SUPERSEDED_MESSAGE);
       else console.log(r.response || '(no response)');
       console.log('');
       for (const n of r.notes) {
-        if (n.kind === 'created') printEvent(events.created('quox', 'issue', n.url));
+        if (n.kind === 'created') { printEvent(gripeFiledLine(n.url, complaint)); console.log(n.url); }
         else if (n.kind === 'info') printInfo(n.text);
         else printWarning(n.text);
       }
@@ -117,7 +125,7 @@ export async function settleGripe({ client, data, complaint, options = {}, orgId
   const notes = [];
   let url = null;
   const det = async () => {
-    const r = await fileDeterministically({ client, complaint, options, orgId, quiet: true });
+    const r = await fileDeterministically({ client, complaint, options, orgId, quiet: true, throwRetryable: !!options.queueRetryable });
     notes.push(...r.notes); if (r.url) url = r.url;
     return r;
   };
@@ -181,7 +189,7 @@ async function promptConfirmPublic(repo) {
   } finally { rl.close(); }
 }
 
-export async function fileDeterministically({ client, complaint, options, orgId, quiet = false, confirmPublic = null }) {
+export async function fileDeterministically({ client, complaint, options, orgId, quiet = false, confirmPublic = null, throwRetryable = false }) {
   const notes = [];
   const say = (n) => { notes.push(n); if (quiet) return; if (n.kind === 'created') printEvent(events.created('quox', 'issue', n.url)); else if (n.kind === 'info') printInfo(n.text); else printWarning(n.text); };
   const repoArg = options.repo || 'quoxai/quox';
@@ -201,9 +209,10 @@ export async function fileDeterministically({ client, complaint, options, orgId,
         owner,
         repo,
         title,
-        body: `## Gripe\n${complaint}\n\n## Context\n- Filed deterministically by \`quox gripe --yes\` (the GRIPE agent run did not file; quox#478 guarantee path)\n- Priority: minor / off-task observation\n\n## Suggested Action\nInvestigate and fix if confirmed.`,
+        body: `${options.idempotencyKey ? `<!-- quox-gripe-key: ${options.idempotencyKey} -->\n` : ''}## Gripe\n${complaint}\n\n## Context\n- Filed deterministically by \`quox gripe --yes\` (the GRIPE agent run did not file; quox#478 guarantee path)\n- Priority: minor / off-task observation\n\n## Suggested Action\nInvestigate and fix if confirmed.`,
         labels: [options.label || 'fleet/qa'],
         ...(orgId ? { org_id: orgId } : {}),
+        ...(options.idempotencyKey ? { idempotency_key: options.idempotencyKey } : {}),
         ...(confirmed ? { confirm_public: true } : {}),
       },
     });
@@ -216,6 +225,8 @@ export async function fileDeterministically({ client, complaint, options, orgId,
     say({ kind: 'warn', text: 'Deterministic file returned no issue URL; treat as NOT filed until you can see the issue.' });
     return { filed: false, notes };
   } catch (err) {
+    // GRIPE-QUEUE: a timeout / network / 5xx is "Quox did not answer", not a refusal; the caller queues it.
+    if (throwRetryable && (err?.status == null || Number(err.status) >= 500)) throw err;
     say({ kind: 'warn', text: `Not filed: the GRIPE run did not file and the deterministic fallback failed too (${err.message}).` });
     return { filed: false, error: err.message, notes };
   }

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;
+  });
+}

package/lib/commands/inbox.js

@@ -9,6 +9,8 @@ import { attachWalkthrough } from './walkthrough.js';
 import { getApprovalContext, formatApprovalContext, approvalListColumns } from '../core/approvalContext.js';
 import { QuoxUserError } from '../core/errors.js';
 import { resolutionFromItem, alreadyResolvedError } from '../core/inboxResolution.js';
+import { withStepUp } from '../core/stepUpPrompt.js';
+import { announce, announceFailure } from '../core/announce.js';
 import chalk from 'chalk';
 
 export function registerInboxCommands(program, ctx) {
@@ -55,7 +57,7 @@ export function registerInboxCommands(program, ctx) {
   inbox
     .command('list')
     .description('List inbox items')
-    .option('--status <status>', 'filter: one status, a comma list (resolved,cancelled,expired), or all (includes answered approvals). Default: active only')
+    .option('--status <status>', 'filter: one status, a comma list (resolved,cancelled,expired,withdrawn), or all (includes answered approvals). Default: active only')
     .option('--decision <decision>', 'with resolved/all: approved or rejected')
     .option('--page <n>', 'page number (newest first)')
     .option('--priority <priority>', 'filter: low, normal, high, urgent')
@@ -78,7 +80,15 @@ export function registerInboxCommands(program, ctx) {
         columns: ['id', 'kind', 'priority', 'title', 'source', 'reason', 'status', 'created_at'],
         headers: ['ID', 'Kind', 'Priority', 'Title', 'Source', 'Reason', 'Status', 'Created'],
         rows: items,
-      }, { format: program.opts().output });
+      }, {
+        format: program.opts().output,
+        emptyMessage: 'Nothing waiting for you. Try `--status all` for answered items, or `--awaiting-human` for approvals waiting on a human org-wide.',
+      });
+      const limit = Number(options.limit);
+      if (program.opts().output !== 'json' && items.length > 0 && Number.isFinite(limit) && items.length >= limit) {
+        const total = typeof data.total === 'number' ? data.total : null;
+        console.log(`showing ${items.length}${total && total > items.length ? ` of ${total}` : ''} · --limit to see more`);
+      }
     });
 
   inbox
@@ -116,9 +126,13 @@ export function registerInboxCommands(program, ctx) {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
       const format = program.opts().output;
+      // DS-010 / #1335: a step-up sink answers 403 step_up_required; ask the person for their PIN (hidden, TTY only) and retry once.
       const post = (itemId) => {
         const ep = resolveEndpoint('inbox.respond', { orgId, itemId });
-        return client.post(ep.path, { service: ep.service, body: { action: options.action, comment: options.comment } });
+        return withStepUp(
+          (headers) => client.post(ep.path, { service: ep.service, headers, body: { action: options.action, comment: options.comment } }),
+          { client, orgId, io: ctx.stepUpIO, what: 'This approval' },
+        );
       };
       // Resolve an approvalId to its card (server-side on a current server, else the client scan). When
       // this profile cannot see the card, still ask the server: it knows WHY (an agent login, another
@@ -161,6 +175,26 @@ export function registerInboxCommands(program, ctx) {
     } catch { return null; }
   }
 
+  inbox
+    .command('unread')
+    .description('Mark inbox items unread again (undo a mark-as-read), for you only')
+    .argument('<itemId...>', 'one or more inbox item IDs')
+    .action(async (ids) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      let done = 0;
+      for (const id of ids) {
+        try {
+          await client.patch(`${resolveEndpoint('inbox.get', { orgId, itemId: encodeURIComponent(id) }).path}/read`, { service: resolveEndpoint('inbox.get', { orgId, itemId: id }).service, body: { is_read: false } });
+          done++;
+        } catch (err) {
+          announceFailure('inbox', `unread ${id}`, err);
+          throw err.status === 404 ? notFound(id, err) : err;
+        }
+      }
+      announce('inbox', `marked ${done} unread`, { result: ids.length === 1 ? ids[0] : `${done} items` });
+    });
+
   inbox
     .command('stats')
     .description('Show inbox statistics')