quoxcli 0.2.0 → 0.4.0

package/lib/commands/discord.js

@@ -25,14 +25,10 @@ const QDP = process.env.QDP_CLI_PATH
 
 /**
  * Per-verb usage, mirrored from qdp.mjs's own header doc block (bin/qdp.mjs
- * in the quox-discord-pro repo). qdp itself has no --help handling of its
- * own, and this command hand-rolls arg dispatch (allowUnknownOption +
- * helpOption(false), see below) rather than commander subcommands, so
- * `--help`/`-h` was previously just another unrecognised arg forwarded
- * straight through to qdp — which silently ran the verb instead of showing
- * help. Worst case for a mutating verb (bind/unbind/provision): "--help"
- * would have actually bound/unbound/provisioned a channel. This map is
- * checked BEFORE qdp is ever spawned so that can't happen (quox#603).
+ * in the quox-discord-pro repo), shown in each subcommand's --help. qdp has no
+ * --help handling of its own; before quox#1077 this command hand-rolled arg
+ * dispatch and had to intercept --help itself (quox#603). Commander
+ * subcommands now answer --help before any action runs.
  */
 const VERB_USAGE = {
   status: 'qdp status                 daemon liveness, instances, binding count',
@@ -56,41 +52,81 @@ const VERB_USAGE = {
     + '    --dry-run                   print exactly what it WOULD do, change nothing',
 };
 
-const GENERAL_USAGE = 'Usage: quox discord <verb> [args...]\n\n'
-  + Object.values(VERB_USAGE).map((u) => `  ${u}`).join('\n')
+/**
+ * qdp verbs that only READ (quox#1077). Each was checked against bin/qdp.mjs:
+ * status/instances/bindings print config.json, the pid file and the systemd
+ * state; gaps GETs the open support-gap inbox items; health reads the pid and
+ * systemd state; doctor GETs the control API /health and Discord's channel,
+ * webhook and @me endpoints. None issues PUT/POST/PATCH/DELETE or writes a
+ * file. bind, unbind and provision PUT/DELETE bindings and create channels.
+ */
+export const DISCORD_READ_VERBS = ['status', 'instances', 'bindings', 'gaps', 'health', 'doctor'];
+export const DISCORD_WRITE_VERBS = ['bind', 'unbind', 'provision'];
+
+// No "Usage:" line here: the matrix's --help walker (scripts/matrix/cli-tree.mjs) reads one as the command's usage.
+const GENERAL_USAGE = Object.values(VERB_USAGE).map((u) => `  ${u}`).join('\n')
   + '\n\nRun `quox discord <verb> --help` for a single verb\'s usage.';
 
-function printVerbHelp(verb) {
-  if (verb && VERB_USAGE[verb]) {
-    process.stdout.write(`Usage:\n  ${VERB_USAGE[verb]}\n`);
-  } else {
-    process.stdout.write(`${GENERAL_USAGE}\n`);
+function runQdp(verb, args = []) {
+  if (!fs.existsSync(QDP)) {
+    process.stderr.write(
+      `Discord Pro control CLI (qdp) not found at ${QDP}\n` +
+      'Set QDP_CLI_PATH if it lives elsewhere, or install the quox-discord-pro daemon on this host.\n',
+    );
+    process.exit(2);
   }
+  const r = spawnSync(process.execPath, [QDP, verb, ...args], { stdio: 'inherit' });
+  if (r.error) {
+    process.stderr.write(`qdp failed to run: ${r.error.message}\n`);
+    process.exit(2);
+  }
+  process.exit(r.status ?? 2);
 }
 
+const VERB_DESC = { unbind: 'remove a channel binding', doctor: 'per-binding view/webhook/liveness check (exits non-zero if any binding is broken)' };
+const firstLine = (verb) => VERB_DESC[verb] || VERB_USAGE[verb].split('\n')[0].replace(/^qdp \S+(?: [<[][^\]>]*[>\]])*\s+/, '').trim();
+
+/**
+ * One commander subcommand per qdp verb (quox#1077). It used to be a single
+ * `discord [args...]` leaf, so the CLI leaf policy could only class the whole
+ * group, and it classed it write: a read like `quox discord bindings` was held
+ * for approval. Per-verb leaves let reads be read and keep bind/unbind/provision
+ * write. Commander's own --help runs before any action, so `--help` can never
+ * reach qdp and run a mutating verb (quox#603).
+ */
 export function registerDiscordCommands(program) {
-  program
-    .command('discord [args...]')
-    .description('Quox Discord Pro daemon: status | instances | bindings | bind | unbind | gaps | health')
-    .allowUnknownOption(true)
-    .helpOption(false)
-    .action((args = []) => {
-      if (args.includes('--help') || args.includes('-h')) {
-        printVerbHelp(args[0]);
-        process.exit(0);
-      }
-      if (!fs.existsSync(QDP)) {
-        process.stderr.write(
-          `Discord Pro control CLI (qdp) not found at ${QDP}\n` +
-          'Set QDP_CLI_PATH if it lives elsewhere, or install the quox-discord-pro daemon on this host.\n',
-        );
-        process.exit(2);
-      }
-      const r = spawnSync(process.execPath, [QDP, ...args], { stdio: 'inherit' });
-      if (r.error) {
-        process.stderr.write(`qdp failed to run: ${r.error.message}\n`);
-        process.exit(2);
-      }
-      process.exit(r.status ?? 2);
-    });
+  const discord = program
+    .command('discord')
+    .description('Quox Discord Pro daemon: status | instances | bindings | gaps | health | doctor | bind | unbind | provision')
+    .addHelpText('after', `\nPer-verb usage (each verb shells straight through to qdp):\n${GENERAL_USAGE}`);
+
+  for (const verb of DISCORD_READ_VERBS) {
+    discord
+      .command(verb)
+      .description(firstLine(verb) || verb)
+      .addHelpText('after', `\nqdp usage:\n  ${VERB_USAGE[verb]}`)
+      .action(() => runQdp(verb));
+  }
+
+  const writeArgs = { bind: '<channelId> <mode> [pairs...]', unbind: '<channelId>', provision: '<agentId> [args...]' };
+  for (const verb of DISCORD_WRITE_VERBS) {
+    const leaf = discord
+      .command(`${verb} ${writeArgs[verb]}`);
+    // Only provision has a dry run in qdp. Declaring it here keeps it in --help and lets the
+    // root guard refuse `discord bind|unbind --dry-run` instead of binding for real.
+    if (verb === 'provision') leaf.option('--dry-run', 'print exactly what it WOULD do, change nothing');
+    leaf
+      .description(firstLine(verb) || verb)
+      .addHelpText('after', `\nqdp usage:\n  ${VERB_USAGE[verb]}`)
+      // qdp parses its own options (provision --mode/--host/...), so they pass through unchanged.
+      .allowUnknownOption(true)
+      .action((...a) => {
+        const cmd = a[a.length - 1];
+        const args = [...cmd.args];
+        // --dry-run is also a root quox flag, so commander hands it to the root and it never reaches
+        // cmd.args: a requested dry run of provision used to provision for real. Forward it explicitly.
+        if (cmd.optsWithGlobals().dryRun && !args.includes('--dry-run')) args.push('--dry-run');
+        runQdp(verb, args);
+      });
+  }
 }

package/lib/commands/done.js

@@ -55,6 +55,7 @@ import path from 'node:path';
 import {
   resolveFetchDestination,
   fetchEngine,
+  inspectInstall,
   OPT_GAUGE_DIR,
   userLocalGaugeDir,
   legacyGaugeDir,
@@ -88,19 +89,21 @@ export function resolveEnginePath({ env = process.env, existsSync = fs.existsSyn
 
 const ENGINE = resolveEnginePath();
 
-function runEngine(args) {
-  if (!fs.existsSync(ENGINE)) {
-    process.stderr.write(
-      `DoneEngine not found at ${ENGINE}\n` +
-      'Self-heal: `quox done fetch` pulls the engine bundle straight from ' +
-      'the collector, no human in the loop. Otherwise `quox dev enable` ' +
-      'delivers it to /opt/quoxgauge as part of full dev-server ' +
-      'provisioning. Or set QUOX_DONEENGINE_PATH to a checkout.\n',
-    );
+function engineMissingMessage(engine) {
+  return `DoneEngine not found at ${engine}\n`
+    + 'Self-heal: `quox done fetch` pulls the engine bundle straight from '
+    + 'the collector, no human in the loop. Otherwise `quox dev enable` '
+    + 'delivers it to /opt/quoxgauge as part of full dev-server '
+    + 'provisioning. Or set QUOX_DONEENGINE_PATH to a checkout.\n';
+}
+
+function runEngine(args, engine = ENGINE) {
+  if (!fs.existsSync(engine)) {
+    process.stderr.write(engineMissingMessage(engine));
     // 2, not 1: a missing engine is "cannot tell", not "refused".
     return 2;
   }
-  const r = spawnSync(process.execPath, [ENGINE, ...args], { stdio: 'inherit' });
+  const r = spawnSync(process.execPath, [engine, ...args], { stdio: 'inherit' });
   if (r.error) {
     process.stderr.write(`DoneEngine failed to run: ${r.error.message}\n`);
     return 2;
@@ -108,6 +111,23 @@ function runEngine(args) {
   return r.status ?? 2;
 }
 
+/**
+ * VISIBILITY GATE (#988 follow-on). Public installs do not ship DoneEngine
+ * (its bundle is built from the private quox-gauge repo and delivered to dev
+ * servers by `quox dev enable`), so listing `quox done` in their help
+ * advertises a command that can only fail. It is listed only when an engine
+ * is installed locally, decided from the filesystem alone with the same
+ * resolution the runner uses: building help never makes a network call.
+ * QUOX_HELP_INCLUDE_GATED=1 lists it regardless; the generators that scrape
+ * `--help` into the command trees set it so those trees do not depend on
+ * which host ran them.
+ */
+export function isDoneEngineInstalled({ env = process.env, home = os.homedir(), fsOps } = {}) {
+  const ops = fsOps || { existsSync: fs.existsSync, readdirSync: fs.readdirSync };
+  const engine = resolveEnginePath({ env, existsSync: ops.existsSync, home });
+  return inspectInstall(path.dirname(engine), ops).healthy;
+}
+
 function defaultExecFn(cmd, args) {
   return spawnSync(cmd, args, { encoding: 'utf8' });
 }
@@ -140,8 +160,56 @@ function defaultFsOps() {
 }
 
 export function registerDoneCommands(program, ctx = {}) {
+  const env = ctx.env || process.env;
+  const home = ctx.home || os.homedir();
+  // Tests inject fsOps/env/home; the real CLI keeps the import-time ENGINE.
+  const injected = !!(ctx.fsOps || ctx.env || ctx.home);
+  const currentEngine = () => (injected
+    ? resolveEnginePath({ env, existsSync: (ctx.fsOps || fs).existsSync, home })
+    : ENGINE);
+  const visible = env.QUOX_HELP_INCLUDE_GATED === '1'
+    || isDoneEngineInstalled({ env, home, fsOps: ctx.fsOps });
+
+  const fetchDeps = () => ({
+    execFn: ctx.execFn || defaultExecFn,
+    isWritable: ctx.isWritable || defaultIsWritable,
+    fsOps: ctx.fsOps || defaultFsOps(),
+  });
+
+  /**
+   * Resolve a runnable engine for a subcommand. Present: use it, no network.
+   * Absent: try the existing fetch path once. A collector 404
+   * (DONEENGINE_NOT_SHIPPED) means this is a public install: refuse with that
+   * message and exit 2, having changed nothing. A bundle that IS available
+   * (a dev collector) installs and the freshly fetched engine runs.
+   */
+  async function ensureEngine() {
+    const engine = currentEngine();
+    const exists = (ctx.fsOps || fs).existsSync(engine);
+    if (exists || !ctx.client || env.QUOX_DONEENGINE_PATH) return { engine };
+    const { execFn, isWritable, fsOps } = fetchDeps();
+    const { dest, needsSudo } = resolveFetchDestination({ env, isWritable, execFn });
+    try {
+      await fetchEngine({ dest, needsSudo, force: false, client: ctx.client, execFn, fsOps });
+      return { engine: path.join(dest, 'gauge.mjs') };
+    } catch (err) {
+      if (err.code === 'DONEENGINE_NOT_SHIPPED') {
+        process.stderr.write(`quox done: ${err.message}\n`);
+        return { code: 2 };
+      }
+      process.stderr.write(`quox done: engine fetch failed: ${err.message}\n`);
+      return { engine };
+    }
+  }
+
+  async function runGuarded(args) {
+    const r = await ensureEngine();
+    if (r.code !== undefined) return r.code;
+    return runEngine(args, r.engine);
+  }
+
   const done = program
-    .command('done')
+    .command('done', { hidden: !visible })
     .description('Quox DoneEngine: is this actually done, and what is the evidence?');
 
   done
@@ -150,7 +218,7 @@ export function registerDoneCommands(program, ctx = {}) {
     .option('--pack <id>', 'rule pack to judge against', 'launch-spine')
     .option('--json', 'structured verdict for agents')
     .option('--root <path>', 'judge <subject> in this repo, reading its own STATUS map with the selected pack (e.g. a plugin with --pack plugin)')
-    .action((subject, options) => {
+    .action(async (subject, options) => {
       const args = ['--can-ship', subject || 'all', '--pack', options.pack];
       if (options.root) {
         if (!subject) {
@@ -161,17 +229,17 @@ export function registerDoneCommands(program, ctx = {}) {
         args.push('--subject', subject, '--root', path.resolve(options.root));
       }
       if (options.json) args.push('--json');
-      process.exitCode = runEngine(args);
+      process.exitCode = await runGuarded(args);
     });
 
   done
     .command('checklist [pack]')
     .description('The builder checklist GENERATED from a pack (every gate the engine judges); --check verifies a doc that embeds it')
     .option('--check <file>', 'exit 1 if the checklist block in this file has drifted from the pack')
-    .action((pack, options) => {
+    .action(async (pack, options) => {
       const args = ['--checklist', pack || 'plugin'];
       if (options.check) args.push('--check', path.resolve(options.check));
-      process.exitCode = runEngine(args);
+      process.exitCode = await runGuarded(args);
     });
 
   done
@@ -180,12 +248,12 @@ export function registerDoneCommands(program, ctx = {}) {
     .option('--json', 'machine-readable, includes raw deploy state')
     .option('--dod', 'per-surface gates, split by evidence class')
     .option('--no-deploy', 'skip docker/git; Deployed Ready becomes unknown, which is not a pass')
-    .action((options) => {
+    .action(async (options) => {
       const args = [];
       if (options.json) args.push('--json');
       if (options.dod) args.push('--dod');
       if (options.deploy === false) args.push('--no-deploy');
-      process.exitCode = runEngine(args);
+      process.exitCode = await runGuarded(args);
     });
 
   done
@@ -193,25 +261,27 @@ export function registerDoneCommands(program, ctx = {}) {
     .description('One rule pack against its subjects: BOTH finish lines, build and deployed')
     .option('--snapshot', 'append this reading to the snapshot history')
     .option('--org <id>', 'measure FOR this org: plan evidence reads as it, the snapshot is stamped with it (default: the pack\'s own org field)')
-    .action((pack, options) => {
+    .action(async (pack, options) => {
       const args = pack ? ['--pack', pack] : ['--launch'];
       if (options.snapshot) args.push('--snapshot');
       if (options.org) args.push('--org', options.org);
-      process.exitCode = runEngine(args);
+      process.exitCode = await runGuarded(args);
     });
 
   done
     .command('history [pack]')
     .description('Movement between snapshots, regressions listed first')
-    .action((pack) => {
-      process.exitCode = runEngine(pack ? ['--history', '--pack', pack] : ['--history']);
+    .action(async (pack) => {
+      process.exitCode = await runGuarded(pack ? ['--history', '--pack', pack] : ['--history']);
     });
 
   done
     .command('packs')
     .description('List available rule packs')
-    .action(() => {
-      const dir = path.join(path.dirname(ENGINE), 'packs');
+    .action(async () => {
+      const r = await ensureEngine();
+      if (r.code !== undefined) { process.exitCode = r.code; return; }
+      const dir = path.join(path.dirname(r.engine), 'packs');
       if (!fs.existsSync(dir)) {
         process.stderr.write(
           `No packs directory at ${dir}\n` +
@@ -246,13 +316,11 @@ export function registerDoneCommands(program, ctx = {}) {
         process.exitCode = 2;
         return;
       }
-      const execFn = ctx.execFn || defaultExecFn;
-      const isWritable = ctx.isWritable || defaultIsWritable;
-      const fsOps = ctx.fsOps || defaultFsOps();
+      const { execFn, isWritable, fsOps } = fetchDeps();
 
       const { dest, reason, needsSudo } = resolveFetchDestination({
         destOption: options.dest,
-        env: process.env,
+        env,
         isWritable,
         execFn,
       });
@@ -267,7 +335,9 @@ export function registerDoneCommands(program, ctx = {}) {
         }
       } catch (err) {
         process.stderr.write(`quox done fetch failed: ${err.message}\n`);
-        process.exitCode = 1;
+        // A public install's 404 is "this install has no DoneEngine", not a
+        // transient failure: exit 2 like every other "cannot tell" here.
+        process.exitCode = err.code === 'DONEENGINE_NOT_SHIPPED' ? 2 : 1;
       }
     });
 

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.')
@@ -121,10 +148,13 @@ export function registerEngagementCommands(program, ctx) {
       const data = await client.post(ep.path, { service: ep.service, body });
       printSuccess(`Target "${value}" added to engagement ${id}.`);
       if (data.target.verification_token) {
+        // #1007: a url target is challenged on its hostname (dns_txt) or at its own origin (well_known_file)
+        const stored = data.target.value || value;
+        const url = data.target.type === 'url' ? (() => { try { return new URL(stored); } catch { return null; } })() : null;
         if (data.target.verification_method === 'dns_txt') {
-          console.log(`  Add a DNS TXT record on ${value}: quox-verify=${data.target.verification_token}`);
+          console.log(`  Add a DNS TXT record on ${url ? url.hostname : stored}: quox-verify=${data.target.verification_token}`);
         } else if (data.target.verification_method === 'well_known_file') {
-          console.log(`  Serve this content at https://${value}/.well-known/quox-verification: ${data.target.verification_token}`);
+          console.log(`  Serve this content at ${url ? url.origin : `https://${stored}`}/.well-known/quox-verification: ${data.target.verification_token}`);
         }
         console.log(`  Then run: quox engagement verify-target ${id} ${data.target.id}`);
       }
@@ -172,6 +202,7 @@ export function registerEngagementCommands(program, ctx) {
         console.log(JSON.stringify(data.output, null, 2));
       } else {
         console.log(`  Failed (allowed: ${data.allowed}): ${data.error}`);
+        process.exitCode = 1; // #1007: a refusal is not success, for scripts as much as people
       }
     });
 
@@ -185,6 +216,7 @@ export function registerEngagementCommands(program, ctx) {
       const data = await client.post(ep.path, { service: ep.service, body: { target: hostTarget, add: options.add === true } });
       if (!data.success) {
         console.log(`  Failed (allowed: ${data.allowed}): ${data.error}`);
+        process.exitCode = 1; // #1007: a refusal is not success, for scripts as much as people
         return;
       }
       const discovered = data.discovered || [];
@@ -234,6 +266,7 @@ export function registerEngagementCommands(program, ctx) {
         console.log(`  Poll: quox engagement job ${data.job_id}`);
       } else {
         console.log(`  Failed (allowed: ${data.allowed}): ${data.error}`);
+        process.exitCode = 1; // #1007: a refusal is not success, for scripts as much as people
       }
     });
 
@@ -372,11 +405,16 @@ export function registerEngagementCommands(program, ctx) {
       }
       const buf = Buffer.from(await res.arrayBuffer());
       const rootOutput = program.opts().output;
-      const outFile = options.output
-        || (rootOutput && !KNOWN_OUTPUT_FORMATS.has(rootOutput) ? rootOutput : null)
-        || `quox-security-${id}.pdf`;
+      // quox#919: the global --json reaches options.output as 'json' via
+      // mergeShadowedGlobals; an output-format name is never a file path.
+      const asPath = (v) => (v && !KNOWN_OUTPUT_FORMATS.has(v) ? v : null);
+      const outFile = asPath(options.output) || asPath(rootOutput) || `quox-security-${id}.pdf`;
       writeFileSync(outFile, buf);
-      printSuccess(`Report saved to ${outFile} (${buf.length} bytes).`);
+      if (rootOutput === 'json') {
+        console.log(JSON.stringify({ success: true, file: outFile, bytes: buf.length }));
+      } else {
+        printSuccess(`Report saved to ${outFile} (${buf.length} bytes).`);
+      }
     });
 
   async function raiseIssue(findingId) {
@@ -564,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')