quoxcli 0.6.0 → 0.6.1

package/lib/commands/fleetRecipe.js

@@ -0,0 +1,174 @@
+/**
+ * `quox fleet recipe ...` (BASTION-JANUS P3): the org's governed fleet recipe library.
+ *
+ * A recipe is a saved list of exact shell lines plus a risk tier, stored server-side per org.
+ * `run` never runs anything itself: the collector renders the recipe and hands it to the same
+ * ssh_exec gate as `quox fleet exec`, so a change raises one approval card (up to 25 hosts) and
+ * an allowlisted read runs without one. Output of a held run: `quox approvals result <id>`.
+ */
+import { readFileSync } from 'node:fs';
+import yaml from 'js-yaml';
+import { formatOutput, formatDetail, printInfo } from '../core/output.js';
+import { printEvent, line as glyphLine } from '../core/quoxglyph.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+/** Parse a recipe file (YAML or JSON) into a plain object. */
+export function parseRecipeFile(text, filename = '') {
+  let doc;
+  if (/\.json$/i.test(filename)) doc = JSON.parse(text);
+  else doc = yaml.load(text, { schema: yaml.JSON_SCHEMA });
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw new Error(`${filename || 'recipe file'} must hold one recipe object (name, risk, commands, ...)`);
+  }
+  return doc;
+}
+
+/** `--param k=v` (repeatable) into { k: v }. */
+export function parseParamFlags(list = []) {
+  const out = {};
+  for (const p of list) {
+    const i = String(p).indexOf('=');
+    if (i < 1) throw new Error(`--param ${JSON.stringify(p)} must be k=v`);
+    const k = p.slice(0, i);
+    if (Object.prototype.hasOwnProperty.call(out, k)) throw new Error(`--param ${k} given twice`);
+    out[k] = p.slice(i + 1);
+  }
+  return out;
+}
+
+/** `--host a,b --host c` into ['a', 'b', 'c']. */
+export function parseHostList(list = []) {
+  const hosts = [].concat(list || []).flatMap((h) => String(h).split(',')).map((h) => h.trim()).filter(Boolean);
+  if (!hosts.length) throw new Error('Give at least one --host <h>[,h...] (up to 25)');
+  return hosts;
+}
+
+const collect = (v, prev) => (prev || []).concat([v]);
+
+/** Org for automation callers, same precedence as `fleet exec`: --org > QUOX_ORG_ID > the profile's org. */
+function orgFor(auth, program) {
+  const orgId = auth.getOrgId(program.opts().org || process.env.QUOX_ORG_ID);
+  if (!orgId && process.env.QUOX_SERVICE_KEY) {
+    throw new Error('QUOX_SERVICE_KEY is set but no org could be resolved. Set QUOX_ORG_ID=<org> or pass --org <id>.');
+  }
+  return orgId || null;
+}
+
+export function registerFleetRecipeCommands(fleet, { client, auth, program }) {
+  const isJson = () => (program.opts().output === 'json');
+  const recipe = fleet
+    .command('recipe')
+    .description('Governed fleet recipe library: saved command sets, run through the ssh_exec approval gate');
+
+  recipe
+    .command('list')
+    .description('List the built-in and org fleet recipes')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('v1.fleet.recipes.list');
+      const org = orgFor(auth, program);
+      const data = await client.get(ep.path, { service: ep.service, ...(org ? { query: { org_id: org } } : {}) });
+      if (isJson()) { console.log(JSON.stringify(data, null, 2)); return; }
+      formatOutput({
+        columns: ['name', 'risk', 'source', 'detached', 'commands', 'title'],
+        headers: ['Name', 'Risk', 'Source', 'Detached', 'Lines', 'Title'],
+        rows: (data.recipes || []).map((r) => ({
+          name: r.name, risk: r.risk, source: r.builtin ? 'built-in' : 'org',
+          detached: r.detached ? 'yes' : 'no', commands: r.command_count, title: r.title,
+        })),
+      }, { format: program.opts().output, emptyMessage: 'No fleet recipes.' });
+    });
+
+  recipe
+    .command('show <name>')
+    .description('Show one fleet recipe, every command line included')
+    .action(async (name) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('v1.fleet.recipes.get', { name });
+      const org = orgFor(auth, program);
+      const data = await client.get(ep.path, { service: ep.service, ...(org ? { query: { org_id: org } } : {}) });
+      if (isJson()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const r = data.recipe || {};
+      formatDetail({
+        name: r.name, title: r.title, risk: r.risk, source: r.builtin ? 'built-in (read-only)' : 'org',
+        detached: r.detached ? 'yes (systemd-run unit, log in the journal)' : 'no',
+        params: (r.params || []).map((p) => `${p.name} (${p.kind})`).join(', ') || 'none',
+        description: r.description || '',
+      }, { format: program.opts().output });
+      console.log('\nCommands:');
+      for (const c of r.commands || []) console.log(`  ${c}`);
+    });
+
+  recipe
+    .command('add')
+    .description('Add an org fleet recipe from a YAML or JSON file (human org admin or operator)')
+    .requiredOption('--file <path>', 'recipe file: name, title, description, risk (read|change|destructive), commands[], detached, params[]')
+    .action(async (options) => {
+      auth.requireAuth();
+      const body = parseRecipeFile(readFileSync(options.file, 'utf8'), options.file);
+      const ep = resolveEndpoint('v1.fleet.recipes.create');
+      const data = await client.post(ep.path, { service: ep.service, body });
+      if (isJson()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const r = data.recipe || body;
+      printEvent(glyphLine('bastion', 'recipe added', { result: `${r.name} (${r.risk})`, status: 'ok' }));
+    });
+
+  recipe
+    .command('remove <name>')
+    .description('Remove an org fleet recipe (human org admin or operator; built-ins cannot be removed)')
+    .action(async (name) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('v1.fleet.recipes.delete', { name });
+      const data = await client.delete(ep.path, { service: ep.service });
+      if (isJson()) { console.log(JSON.stringify(data, null, 2)); return; }
+      printEvent(glyphLine('bastion', 'recipe removed', { result: data.removed || name, status: 'ok' }));
+    });
+
+  recipe
+    .command('run <name>')
+    .description('Run a fleet recipe on 1-25 hosts through the governed ssh_exec gate (a change waits on one approval card)')
+    .requiredOption('--host <h[,h...]>', 'target host(s); repeat or comma-separate, up to 25', collect)
+    .option('--param <k=v>', 'recipe parameter (repeatable)', collect)
+    .option('--reason <text>', 'why you are running this; shown on the approval card')
+    .option('--session-label <name>', 'name this session on approval cards (default: $QUOX_SESSION)')
+    .action(async (name, options) => {
+      auth.requireAuth();
+      const body = { recipe: name, hosts: parseHostList(options.host), params: parseParamFlags(options.param || []) };
+      if (options.reason) body.reason = String(options.reason);
+      if (options.sessionLabel) body.session_label = String(options.sessionLabel);
+      const org = orgFor(auth, program);
+      if (org) body.org_id = org;
+      const ep = resolveEndpoint('v1.fleet.recipes.run');
+      const data = await client.post(ep.path, { service: ep.service, body, timeout: 180000 });
+      const run = (data && data.recipe_run) || {};
+      const heldId = data && data.pending && (data.approvalId || (data._approval && data._approval.id));
+      const failed = data && data.success === false && !data.pending;
+      if (isJson()) {
+        console.log(JSON.stringify(data, null, 2));
+      } else {
+        printEvent(glyphLine('bastion', `recipe ${name}`, {
+          result: heldId ? `held ${heldId}` : (failed ? (data.error || 'failed') : `${run.mode || 'ran'} on ${body.hosts.length} host(s)`),
+          status: heldId ? 'busy' : (failed ? 'fail' : 'ok'),
+        }));
+        if (Array.isArray(data.steps)) {
+          for (const s of data.steps) {
+            console.log(`$ ${s.command}`);
+            const r = s.result !== undefined ? s.result : s;
+            console.log(typeof r === 'string' ? r : JSON.stringify(r, null, 2));
+          }
+        } else if (data.result !== undefined) {
+          console.log(typeof data.result === 'string' ? data.result : JSON.stringify(data.result, null, 2));
+        } else if (failed) {
+          console.error(data.error || JSON.stringify(data));
+        }
+        if (heldId) printInfo(`waiting on approval ${heldId}; after approval run: quox approvals result ${heldId}`);
+        if (run.detached && run.detached.follow_up) {
+          printInfo(`detached as unit ${run.detached.unit}; read its log (allowlisted, no card): `
+            + `quox fleet exec --tool ssh_exec --host <h> --input '${JSON.stringify({ command: run.detached.follow_up })}'`);
+        }
+      }
+      if (failed) process.exitCode = 1;
+    });
+
+  return recipe;
+}

package/lib/commands/lens.js

@@ -0,0 +1,268 @@
+/**
+ * `quox lens`: QuoxLens, apply a declared-stance Lens to a target text.
+ * Collector routes under /api/v1/lens (services/collector/routes/quoxlens.js), behind
+ * requireServiceOrUserAuth + requirePluginEntitlement('quoxlens').
+ *
+ *   quox lens list                                   every Lens, its stance, measured lift, unproven flag
+ *   quox lens show <id>                              one Lens in full (blind spots, finding classes, body)
+ *   quox lens apply <lensId> --file <path|->         apply one Lens to text from a file or stdin (-)
+ *                       [--target-label <s>]         a human label for the target (artifact title)
+ *   quox lens panel --file <path|->                  the Critic panel: several Lenses, repeated runs, run consensus
+ *                       [--lenses a,b] [--runs N] [--min-agreement K] [--depth quick|standard|thorough]
+ *                       [--target-label <s>] [--allow-unproven]
+ *
+ * All honour --json / -o json. An error body is not data: a non-2xx (400 unknown lens,
+ * 402 LICENSE_REQUIRED, 404, 409, 422) is reported with its status and exits 1.
+ */
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const isJson = (program) => program.opts().output === 'json';
+const printJson = (d) => console.log(JSON.stringify(d, null, 2));
+
+async function readTarget(file, ctx) {
+  if (file === '-') {
+    const input = ctx.stdin || process.stdin;
+    let buf = '';
+    for await (const chunk of input) buf += chunk;
+    return buf;
+  }
+  return readFileSync(file, 'utf-8');
+}
+
+// Stable per text, so finding fingerprints (lens + artifact.id + class + location) stay
+// stable when the same target is re-checked.
+function artifactIdFor(text) {
+  return `cli-${createHash('sha256').update(text).digest('hex').slice(0, 16)}`;
+}
+
+function describeError(err) {
+  const body = err.body || {};
+  const parts = [`HTTP ${err.status || err.statusCode}`];
+  if (body.error && !String(err.message || '').includes(body.error)) parts.push(body.error);
+  if (err.message) parts.push(err.message);
+  const detail = body.detail || err.details;
+  if (detail && typeof detail === 'string' && !String(err.message || '').includes(detail)) parts.push(`(${detail})`);
+  if (body.plugin) parts.push(`[plugin: ${body.plugin}]`);
+  return parts.join(' ');
+}
+
+const PANEL_DEPTHS = ['quick', 'standard', 'thorough'];
+// One lens call can take up to 5 minutes server-side and a panel runs lenses x runs calls in sequence.
+const PANEL_CALL_WAIT_MS = 5.5 * 60 * 1000;
+const PANEL_WAIT_CAP_MS = 30 * 60 * 1000;
+
+function parseWholeNumber(value, flag, min, max) {
+  if (value === undefined) return { value: undefined };
+  const n = Number(value);
+  if (!/^\d+$/.test(String(value).trim()) || !Number.isInteger(n) || n < min || n > max) {
+    return { error: `${flag} must be a whole number from ${min} to ${max}, got "${value}"` };
+  }
+  return { value: n };
+}
+
+function formatUsage(verdict) {
+  const u = verdict && verdict.usage;
+  if (!u) return `not available (${(verdict && verdict.usage_reason) || 'no reason given'})`;
+  const parts = [`input ${u.input_tokens}`, `output ${u.output_tokens}`];
+  if (u.cache_creation_input_tokens) parts.push(`cache write ${u.cache_creation_input_tokens}`);
+  if (u.cache_read_input_tokens) parts.push(`cache read ${u.cache_read_input_tokens}`);
+  const calls = `${u.calls} model call${u.calls === 1 ? '' : 's'}`;
+  const price = typeof u.list_price_usd === 'number' ? `, list price $${u.list_price_usd.toFixed(4)}` : '';
+  return `${parts.join(', ')} tokens over ${calls}${price}`;
+}
+
+export function registerLensCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  // An error body is not data: a non-2xx is reported with its status and exits 1 (returns null).
+  async function guarded(request) {
+    if (auth && typeof auth.requireAuth === 'function') auth.requireAuth();
+    try {
+      return await request();
+    } catch (err) {
+      if (err && (err.status || err.statusCode)) {
+        console.error(`QuoxLens request failed: ${describeError(err)}`);
+        process.exitCode = 1;
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  const lens = program
+    .command('lens')
+    .description('QuoxLens: apply a declared-stance Lens to a target and get evidence-quoted findings');
+
+  lens
+    .command('list')
+    .description('List every Lens with its stance, measured lift and unproven flag')
+    .action(async () => {
+      const ep = resolveEndpoint('lens.list');
+      const data = await guarded(() => client.get(ep.path, { service: ep.service }));
+      if (data === null) return;
+      const lenses = Array.isArray(data.lenses) ? data.lenses : [];
+      if (isJson(program)) { printJson(lenses); return; }
+      if (!lenses.length) { console.log('No lenses installed.'); return; }
+      for (const l of lenses) {
+        if (l.error) { console.log(`${l.id}  [${l.category || '-'}]  ERROR: ${l.error}`); continue; }
+        const proof = l.unproven ? 'unproven' : 'measured';
+        const ver = l.version ? ` v${l.version}` : '';
+        console.log(`${l.id}${ver}  [${l.category || '-'}]  ${proof}  ${l.name || ''}`);
+        if (l.description) console.log(`    ${l.description}`);
+      }
+      console.log(`\n${lenses.length} lens${lenses.length === 1 ? '' : 'es'}`);
+    });
+
+  lens
+    .command('show <id>')
+    .description('Show one Lens in full: blind spots, finding classes, prohibited, eval results, body')
+    .action(async (id) => {
+      const ep = resolveEndpoint('lens.get', { id });
+      const data = await guarded(() => client.get(ep.path, { service: ep.service }));
+      if (data === null) return;
+      if (isJson(program)) { printJson(data); return; }
+      const list = (a) => (Array.isArray(a) && a.length ? a.join(', ') : '-');
+      console.log(`${data.name || data.id} (${data.id})`);
+      if (data.description) console.log(data.description);
+      console.log(`version:         ${data.version || '-'}`);
+      console.log(`kind:            ${data.kind || '-'}`);
+      if (data.edition) console.log(`edition:         ${data.edition}`);
+      if (data.author) console.log(`author:          ${data.author}`);
+      console.log(`unproven:        ${data.unproven ? 'yes (no measured lift)' : 'no'}`);
+      console.log(`tags:            ${list(data.tags)}`);
+      console.log(`finding classes: ${list(data.finding_classes)}`);
+      console.log(`blind spots:     ${list(data.blind_spots)}`);
+      console.log(`prohibited:      ${list(data.prohibited)}`);
+      console.log(`eval results:    ${Array.isArray(data.results) ? data.results.length : 0}`);
+      if (data.body) console.log(`\n${data.body}`);
+    });
+
+  lens
+    .command('apply <lensId>')
+    .description('Apply one Lens to target text from a file, or stdin with --file -')
+    .requiredOption('--file <path>', 'read the target text from this file, or - for stdin')
+    .option('--target-label <label>', 'a human label for the target (sent as the artifact title)')
+    .action(async (lensId, options) => {
+      let text;
+      try {
+        text = await readTarget(options.file, ctx);
+      } catch (err) {
+        console.error(`Could not read target ${options.file === '-' ? 'from stdin' : `file ${options.file}`}: ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (!text || !text.trim()) {
+        console.error('Not applied: the target text is empty. Nothing was sent.');
+        process.exitCode = 1;
+        return;
+      }
+      const artifact = { kind: 'text', id: artifactIdFor(text), content: text };
+      if (options.targetLabel) artifact.title = options.targetLabel;
+      const ep = resolveEndpoint('lens.apply');
+      const body = { lens_id: lensId, mode: 'single', artifact };
+      // A lens apply is one model call (up to 5 min on the server); the client default (30s) gave up on real runs.
+      const data = await guarded(() => client.post(ep.path, { service: ep.service, body, timeout: PANEL_CALL_WAIT_MS, retries: 0 }));
+      if (data === null) return;
+      if (isJson(program)) { printJson(data); return; }
+
+      const v = data.verdict || {};
+      const a = data.applied || {};
+      console.log(`lens:        ${a.lens_id || lensId}${a.version ? ` v${a.version}` : ''}${a.unproven ? '  (unproven: no measured lift)' : ''}`);
+      if (artifact.title) console.log(`target:      ${artifact.title}`);
+      console.log(`disposition: ${v.disposition || '-'}`);
+      console.log(`confidence:  ${v.confidence ?? '-'}`);
+      if (a.model) console.log(`model:       ${a.model}`);
+      if (v.summary) console.log(`\n${v.summary}`);
+      const findings = Array.isArray(data.findings) ? data.findings : [];
+      console.log(`\nfindings: ${findings.length}`);
+      for (const f of findings) {
+        console.log(`  [${f.severity || '-'}] ${f.class || '-'}: ${f.claim || ''}`);
+        for (const e of Array.isArray(f.evidence) ? f.evidence : []) {
+          if (e && e.quote) console.log(`      "${e.quote}"${e.at ? ` (${e.at})` : ''}`);
+        }
+      }
+      if (Array.isArray(a.blind_spots) && a.blind_spots.length) console.log(`\nblind spots: ${a.blind_spots.join(', ')}`);
+      if (data.evidence && data.evidence.corr) console.log(`evidence:    ${data.evidence.corr}`);
+    });
+
+  lens
+    .command('panel')
+    .description('The Critic panel: several Lenses over one target, repeated runs; keeps findings that recur across runs')
+    .requiredOption('--file <path>', 'read the target text from this file, or - for stdin')
+    .option('--lenses <ids>', 'comma-separated lens ids, 2 to 5 (server default: honesty-and-claims,enterprise-compliance-auditor)')
+    .option('--runs <n>', 'how many times to run the panel, 1 to 5 (server default 1)')
+    .option('--min-agreement <k>', 'runs a finding must appear in to be kept (server default: a majority of runs)')
+    .option('--depth <depth>', `depth profile: ${PANEL_DEPTHS.join(', ')} (server default standard)`)
+    .option('--target-label <label>', 'a human label for the target (sent as the artifact title)')
+    .option('--allow-unproven', 'run lenses with no measured lift anyway (the result says so)')
+    .action(async (options) => {
+      const runs = parseWholeNumber(options.runs, '--runs', 1, 5);
+      const minAgreement = parseWholeNumber(options.minAgreement, '--min-agreement', 1, 5);
+      const bad = runs.error || minAgreement.error
+        || (options.depth !== undefined && !PANEL_DEPTHS.includes(options.depth) ? `--depth must be one of ${PANEL_DEPTHS.join(', ')}, got "${options.depth}"` : null);
+      if (bad) {
+        console.error(`Not run: ${bad}. Nothing was sent.`);
+        process.exitCode = 1;
+        return;
+      }
+      let text;
+      try {
+        text = await readTarget(options.file, ctx);
+      } catch (err) {
+        console.error(`Could not read target ${options.file === '-' ? 'from stdin' : `file ${options.file}`}: ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (!text || !text.trim()) {
+        console.error('Not run: the target text is empty. Nothing was sent.');
+        process.exitCode = 1;
+        return;
+      }
+      const artifact = { kind: 'text', id: artifactIdFor(text), content: text };
+      if (options.targetLabel) artifact.title = options.targetLabel;
+      const body = { artifact };
+      const lensIds = options.lenses ? options.lenses.split(',').map((s) => s.trim()).filter(Boolean) : null;
+      if (lensIds) body.lens_ids = lensIds;
+      if (runs.value !== undefined) body.runs = runs.value;
+      if (minAgreement.value !== undefined) body.min_agreement = minAgreement.value;
+      if (options.depth) body.depth = options.depth;
+      if (options.allowUnproven) body.allow_unproven = true;
+
+      const calls = (lensIds ? lensIds.length : 2) * (runs.value || 1);
+      const timeout = Math.min(calls * PANEL_CALL_WAIT_MS, PANEL_WAIT_CAP_MS);
+      const ep = resolveEndpoint('lens.panel');
+      // retries: 0, a panel is a paid model run; a retried POST would run it twice.
+      const data = await guarded(() => client.post(ep.path, { service: ep.service, body, timeout, retries: 0 }));
+      if (data === null) return;
+      if (isJson(program)) { printJson(data); return; }
+
+      const v = data.verdict || {};
+      const lensList = (Array.isArray(data.lenses) ? data.lenses : []).map((l) => `${l.id}${l.version ? ` v${l.version}` : ''}${l.unproven ? ' (unproven)' : ''}`);
+      console.log(`lenses:      ${lensList.join(', ') || '-'}`);
+      if (artifact.title) console.log(`target:      ${artifact.title}`);
+      console.log(`disposition: ${v.disposition || '-'}`);
+      console.log(`runs:        ${data.runs_completed ?? '-'} of ${data.runs_requested ?? '-'} completed, a finding needs ${data.min_agreement ?? '-'} to be kept${data.depth ? `, depth ${data.depth}` : ''}`);
+      if (data.partial) console.log(`PARTIAL:     stopped early (${data.stop_reason || 'unknown'}${data.stop_detail ? `: ${data.stop_detail}` : ''})`);
+      if (Array.isArray(data.unproven_lenses) && data.unproven_lenses.length) console.log(`unproven:    ${data.unproven_lenses.join(', ')} (no measured lift; run because --allow-unproven was given)`);
+      if (v.summary) console.log(`\n${v.summary}`);
+      const findings = Array.isArray(data.findings) ? data.findings : [];
+      console.log(`\nfindings: ${findings.length}`);
+      for (const f of findings) {
+        const agreement = f.agreement ? `${f.agreement.label || `${f.agreement.runs}/${f.agreement.of}`} runs` : '-';
+        const by = Array.isArray(f.lens_ids) && f.lens_ids.length ? `  [${f.lens_ids.join(', ')}]` : '';
+        console.log(`  [${f.severity || '-'}] ${f.class || '-'}: ${f.claim || ''}  (${agreement})${by}`);
+        for (const e of Array.isArray(f.evidence) ? f.evidence : []) {
+          if (e && e.quote) console.log(`      "${e.quote}"${e.at ? ` (${e.at})` : ''}`);
+        }
+      }
+      const below = Array.isArray(data.below_agreement) ? data.below_agreement : [];
+      if (below.length) {
+        console.log(`\nbelow agreement (not kept): ${below.length}`);
+        for (const f of below) console.log(`  ${f.class || '-'}: ${f.claim || ''}  (${f.agreement ? f.agreement.label : '-'} runs)`);
+      }
+      console.log(`\nusage:       ${formatUsage(v)}`);
+      if (data.evidence && data.evidence.corr) console.log(`evidence:    ${data.evidence.corr}`);
+    });
+}

package/lib/commands/lucidGoals.js

@@ -272,10 +272,11 @@ export function registerLucidInsightsCommands(lu, program, ctx) {
     const o = cmd.optsWithGlobals ? cmd.optsWithGlobals() : cmd.opts();
     return Boolean(o.json) || program.opts().output === 'json';
   };
-  async function get(key, { params, query } = {}) {
+  async function get(key, { params, query, body } = {}) {
     const ep = resolveEndpoint(key, params);
+    const method = ep.method === 'POST' ? 'post' : 'get';
     try {
-      return await client.get(ep.path, { service: ep.service, query: { org_id: resolveOrgId(auth, program), ...query } });
+      return await client[method](ep.path, { service: ep.service, query: { org_id: resolveOrgId(auth, program), ...query }, ...(body !== undefined ? { body } : {}) });
     } catch (err) {
       const status = err && (err.status || err.statusCode);
       if (status) {
@@ -334,8 +335,32 @@ export function registerLucidInsightsCommands(lu, program, ctx) {
       for (const l of (i.interpretation && i.interpretation.limitations) || []) console.log(`  Limit: ${l}`);
       if (i.priority) console.log(`  Why it ranks ${i.priority.band}: ${i.priority.why}`);
       console.log(`  ${insightStanding(i)}${i.retracted_at ? `, resolved ${i.retracted_at}` : ''}`);
+      const rz = data.reasoner;
+      if (rz && rz.plain) console.log(`  In plain words: ${rz.plain}`);
+      for (const p of (rz && rz.proposals) || []) {
+        console.log(`  Suggested link to goal ${p.goal_id}: ${p.why} (a model's guess; quox lucid insights accept ${i.id} ${p.goal_id}, or reject)`);
+      }
     });
 
+  for (const verb of ['accept', 'reject']) {
+    ins
+      .command(`${verb} <id> <goalId>`)
+      .description(verb === 'accept'
+        ? 'Accept a link the model suggested: records that this depends on the goal, as your own statement'
+        : 'Reject a link the model suggested; it stays rejected if suggested again')
+      .option('--json', 'print the full JSON response')
+      .action(async (id, goalId, _o, cmd) => {
+        auth.requireAuth();
+        const data = await get('lucid.insights.decide', { params: { id, goalId }, body: { decision: verb } });
+        if (data === null) return;
+        if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+        const l = data.link || {};
+        printSuccess(l.status === 'accepted'
+          ? `Linked: ${id} now counts against goal ${l.goal_id} (dependency ${l.entity_id}). LUCID uses it from its next pass.`
+          : `Rejected: LUCID will not suggest goal ${l.goal_id} for ${id} again.`);
+      });
+  }
+
   ins
     .command('status')
     .description("The shadow worker's health for your org: runs, skips, failures, last error")
@@ -349,6 +374,15 @@ export function registerLucidInsightsCommands(lu, program, ctx) {
       console.log(`Runs ${w.runs}, skipped (nothing new) ${w.skipped}, failures ${w.failures}${w.consecutive_failures ? ` (${w.consecutive_failures} in a row)` : ''}.`);
       console.log(`Last run ${w.last_run_at || 'never'}: found ${w.last_found}, rejected for bad evidence ${w.last_rejected}.`);
       if (w.last_error) console.log(`Last error: ${w.last_error}${w.next_run_at ? ` (next try ${w.next_run_at})` : ''}`);
+      const rz = data.reasoner;
+      if (rz) {
+        if (!rz.enabled) console.log('Model wording: off (quox lucid herald set reasoner=true).');
+        else if (!rz.cloud_processing) console.log('Model wording: switched on, but nothing is sent until cloud processing is on (quox lucid herald set synth=true).');
+        else {
+          console.log(`Model wording: on, ${rz.calls_today} of ${rz.daily_cap} calls today. Worded ${rz.worded}, rejected by the brief check ${rz.lint_rejected}, empty ${rz.empty}, failures ${rz.failures}${rz.consecutive_failures ? ` (${rz.consecutive_failures} in a row)` : ''}, retired ${rz.retired}, links proposed ${rz.proposals}.`);
+          if (rz.last_error) console.log(`Model wording last error: ${rz.last_error}${rz.next_run_at ? ` (next try ${rz.next_run_at})` : ''}`);
+        }
+      }
     });
 }
 

package/lib/commands/mail.js

@@ -185,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)')
@@ -215,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`

package/lib/commands/monitoring.js

@@ -117,7 +117,11 @@ export function registerMonitoringCommands(program, ctx) {
     .action(async (id) => {
       auth.requireAuth();
       const data = await client.get(resolveEndpoint('governance.incidents.get', { id }).path, { service: resolveEndpoint('governance.incidents.get', { id }).service });
-      formatDetail(data.incident || data, { format: program.opts().output, title: `Incident: ${id}` });
+      const inc = data.incident || data;
+      // WAZ-11 (audit batch 5, N3): on a Wazuh incident the governance `escalated` flag means escalated as UNOWNED
+      // (inbox item + LUCID ask), not sent to QuoxSecurity; the human label says so. The field (and --json) is unchanged.
+      const labels = inc && inc.incident_type === 'wazuh_alert' ? { escalated: 'unowned-escalated' } : undefined;
+      formatDetail(inc, { format: program.opts().output, title: `Incident: ${id}`, ...(labels ? { labels } : {}) });
     });
 
   incidents

package/lib/commands/plan.js

@@ -669,8 +669,15 @@ function coerceUpdateValue(field, value) {
 
 // ── registration ─────────────────────────────────────────────────────────
 
+async function readProcessStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks.map((c) => (typeof c === 'string' ? Buffer.from(c) : c))).toString('utf8');
+}
+
 export function registerPlanCommands(program, ctx) {
   const { client, auth } = ctx;
+  const readStdin = ctx.readStdin || readProcessStdin;
 
   const plan = program
     .command('plan')
@@ -1188,12 +1195,17 @@ export function registerPlanCommands(program, ctx) {
 
   plan
     .command('plan <id>')
-    .description('Print raw plan markdown; --edit opens $EDITOR (PUT on save if changed); --history lists versions')
+    .description('Print raw plan markdown; --file writes a new version from a file or stdin; --edit opens $EDITOR (PUT on save if changed); --history lists versions')
+    .option('--file <path>', "write the plan body from a file ('-' reads stdin); a new version only if it changed")
     .option('--edit', 'open $EDITOR on the plan body, PUT on save if changed')
     .option('--history', 'list plan versions instead of printing the body')
     .action(async (id, options) => {
       auth.requireAuth();
 
+      if (options.file !== undefined && (options.edit || options.history)) {
+        throw new Error('--file cannot be combined with --edit or --history');
+      }
+
       if (options.history) {
         const ep = resolveEndpoint('quoxplan.stream.plan.versions.list', { id });
         const data = await client.get(ep.path, { service: ep.service });
@@ -1213,6 +1225,29 @@ export function registerPlanCommands(program, ctx) {
       const detail = await client.get(detailEp.path, { service: detailEp.service });
       const currentBody = (detail.plan && detail.plan.body) || '';
 
+      if (options.file !== undefined) {
+        let newBody;
+        if (options.file === '-') {
+          newBody = await readStdin();
+        } else {
+          try {
+            newBody = readFileSync(options.file, 'utf8');
+          } catch (err) {
+            throw new Error(`cannot read plan file ${options.file}: ${err.code || err.message}`);
+          }
+        }
+        if (!String(newBody).trim()) throw new Error('plan body is empty; refusing to write an empty plan');
+        if (newBody === currentBody) {
+          console.log(chalk.dim('  No changes.'));
+          return;
+        }
+        const putEp = resolveEndpoint('quoxplan.stream.plan.put', { id });
+        const data = await client.put(putEp.path, { service: putEp.service, body: { body: newBody, actor: 'quox-cli' } });
+        if (isJsonOutput(program)) return printJson(data);
+        printSuccess(`${id}: plan updated to v${data.version}`);
+        return;
+      }
+
       if (options.edit) {
         const dir = mkdtempSync(join(tmpdir(), 'quox-plan-'));
         const file = join(dir, `${id}.md`);