quoxcli 0.5.0 → 0.6.1

package/lib/commands/admin.js

@@ -407,4 +407,90 @@ export function registerAdminCommands(program, ctx) {
       const data = await client.get(resolveEndpoint('admin.retention.stats.list').path, { service: resolveEndpoint('admin.retention.stats.list').service });
       formatDetail(data.stats || data, { format: program.opts().output, title: 'Retention Stats' });
     });
+
+  // AQ-9H LADON-P1B (plan v6.2 A9, owner decision S9): the scratch-org registry. Fixture mail and calendar
+  // providers load only for an org marked here, and only on a deployment that sets QUOX_FIXTURE_PROVIDERS=1.
+  // The collector refuses every caller but a human instance admin (requireInstanceAdminMw), so this verb is a
+  // human step: an agent or service key gets a 403.
+  const scratchOrgs = admin
+    .command('scratch-orgs')
+    .description('Scratch orgs: only a human instance admin can mark an org, which enables fixture mail and calendar providers for that org only');
+
+  scratchOrgs
+    .command('list')
+    .description('List the orgs marked scratch (human instance admin)')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('admin.scratch_orgs.list');
+      let data;
+      try {
+        data = await client.get(ep.path, { service: ep.service });
+      } catch (err) {
+        announceFailure('quox', 'admin scratch-orgs list', err);
+        throw err;
+      }
+      const orgs = data.orgs || [];
+      announce('quox', 'admin scratch-orgs list', data.corrupt
+        ? { result: 'registry unreadable', status: 'warn' }
+        : { result: `${orgs.length} scratch org(s)` });
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      if (data.corrupt) {
+        console.error(`Scratch-org registry is unreadable, so NO org is treated as scratch: ${data.error || 'unknown error'}`);
+        process.exitCode = 1;
+      }
+      formatOutput({
+        columns: ['orgId', 'markedBy', 'markedAt', 'note'],
+        headers: ['Org', 'Marked by', 'Marked at', 'Note'],
+        rows: orgs.map((o) => ({ orgId: o.orgId, markedBy: o.markedBy || '-', markedAt: o.markedAt || '-', note: o.note || '' })),
+      }, { format: program.opts().output, raw: orgs, emptyMessage: 'No org is marked scratch.' });
+      if (program.opts().output !== 'quiet' && program.opts().output !== 'csv') {
+        console.log(data.fixtureProvidersEnv
+          ? 'Fixture providers are enabled on this deployment (QUOX_FIXTURE_PROVIDERS=1).'
+          : 'Fixture providers are off on this deployment (QUOX_FIXTURE_PROVIDERS is not 1), so marking has no effect yet.');
+      }
+    });
+
+  scratchOrgs
+    .command('mark')
+    .description('Mark an org scratch so fixture providers load for that org only (human instance admin; audited)')
+    .argument('<orgId>', 'the org id to mark')
+    .option('--note <text>', 'why this org is scratch (stored with the mark, 200 characters max)')
+    .action(async (orgId, opts) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('admin.scratch_orgs.mark', { orgId });
+      let data;
+      try {
+        data = await client.put(ep.path, { service: ep.service, body: opts.note ? { note: opts.note } : {} });
+      } catch (err) {
+        announceFailure('quox', `admin scratch-orgs mark ${orgId}`, err);
+        throw err;
+      }
+      announce('quox', `admin scratch-orgs mark ${orgId}`, { result: 'marked scratch' });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      printSuccess(`Org ${orgId} is marked scratch. Fixture providers load for this org only, on a deployment with QUOX_FIXTURE_PROVIDERS=1.`);
+    });
+
+  scratchOrgs
+    .command('unmark')
+    .description('Remove the scratch mark from an org, so fixture providers no longer load for it (human instance admin; audited)')
+    .argument('<orgId>', 'the org id to unmark')
+    .action(async (orgId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('admin.scratch_orgs.unmark', { orgId });
+      let data;
+      try {
+        data = await client.delete(ep.path, { service: ep.service });
+      } catch (err) {
+        announceFailure('quox', `admin scratch-orgs unmark ${orgId}`, err);
+        throw err;
+      }
+      announce('quox', `admin scratch-orgs unmark ${orgId}`, { result: data.removed ? 'unmarked' : 'was not marked' });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      printSuccess(data.removed
+        ? `Org ${orgId} is no longer scratch. Fixture providers no longer load for it.`
+        : `Org ${orgId} was not marked scratch. Nothing changed.`);
+    });
 }

package/lib/commands/approvals.js

@@ -142,7 +142,11 @@ export function registerApprovalsCommands(program, ctx) {
         body.patterns = options.pattern || [];
       }
       const ep = resolveEndpoint('v1.approvals.grants.create');
-      const data = await client.post(ep.path, { service: ep.service, body });
+      // VULCAN: a standing grant pre-authorises ssh_exec for days, so the server asks for a step-up PIN (scope override).
+      const data = await withStepUp(
+        (headers) => client.post(ep.path, { service: ep.service, headers, body }),
+        { client, orgId: auth.getOrgId?.(program.opts().org) || null, scope: 'override', io: ctx.stepUpIO, what: 'Creating a standing grant' },
+      );
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       const g = data.grant || {};
       announce('approvals', `grant created ${g.tool || 'ssh_exec'}@${g.host || options.host}`, { result: g.grant_id });

package/lib/commands/calendar.js

@@ -28,6 +28,33 @@ export function registerCalendarCommands(program, ctx) {
     .command('calendar')
     .description('Calendar-Q: connected calendars, agenda, coverage, sync');
 
+  // ── connections add (AQ-9H LADON-P1B: fixture only) ─────────────────────────────
+
+  const connections = calendar
+    .command('connections')
+    .description('Calendar connections (Google connects through the OAuth flow; add here is fixture only)');
+
+  connections
+    .command('add')
+    .description('Connect a seeded fixture calendar for scratch-org proof runs (--provider fixture --seed <name>). The server decides: it refuses unless this deployment enables fixture providers and a platform admin marked the org scratch. Google calendars connect through the OAuth flow, not this command.')
+    .requiredOption('--provider <name>', 'calendar provider; only fixture is accepted here')
+    .option('--seed <name>', 'fixture seed to load (e.g. scratch-office-day)')
+    .option('--run <id>', 'proof run id substituted into the seed ({{run}})')
+    .action(async (options) => {
+      auth.requireAuth();
+      if (options.provider !== 'fixture') {
+        throw new Error(`--provider ${options.provider} is not connected here. Only --provider fixture is; Google calendars connect through the OAuth flow.`);
+      }
+      if (!options.seed) throw new Error('--seed <name> is required with --provider fixture (e.g. --seed scratch-office-day).');
+      const body = { provider: 'fixture', seed: options.seed };
+      if (options.run) body.run = options.run;
+      const ep = resolveEndpoint('calendarq.connections.create');
+      const data = await client.post(ep.path, { service: ep.service, body });
+      if (isJsonOutput(program)) return printJson(data);
+      const conn = data.connection || data;
+      printSuccess(`Connected fixture calendar ${conn.resourceLabel || ''} (${conn.id}) from seed ${options.seed}.`);
+    });
+
   // ── status ───────────────────────────────────────────────────────────
 
   calendar

package/lib/commands/chat.js

@@ -221,7 +221,7 @@ async function awaitTurn(client, turnId) {
 }
 
 /** One-shot (non-streaming) chat via POST /chat/claude, kept server side as a pollable turn. */
-async function sendOneShot(client, { message, agent, sessionId, resumeTurn }) {
+export async function sendOneShot(client, { message, agent, sessionId, resumeTurn }) {
   let data;
   if (resumeTurn) {
     data = await awaitTurn(client, resumeTurn);

package/lib/commands/contacts.js

@@ -408,6 +408,8 @@ export function registerContactsCommands(program, ctx) {
       if (isJson(program)) return printJson(d);
       console.log(`channel: ${d.channel || 'none allowed'}`);
       for (const a of d.alternatives || []) console.log(`  ${a.channel}: ${a.decision}${(a.reasons || []).length ? ` (${a.reasons.join(', ')})` : ''}`);
+      if (d.evaluated_for) console.log(`for: ${d.evaluated_for === 'agent' ? 'an agent' : 'you (a person)'}`);
+      if ((d.quiet_hours_for_agents || []).length) console.log(`quiet hours: an agent reaching them by ${d.quiet_hours_for_agents.join(', ')} now needs approval`);
       announce('contacts best-channel', d.channel || 'none allowed');
     });
 

package/lib/commands/fleet.js

@@ -10,6 +10,51 @@ import { formatOutput, formatDetail, printSuccess, printWarning, printInfo } fro
 import { events, printEvent, line as glyphLine } from '../core/quoxglyph.js';
 import { parseJSON } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { registerFleetRecipeCommands } from './fleetRecipe.js';
+
+/** HYPERION-NEXT P10: one `quox fleet hw` summary row. */
+function formatHwRow(h) {
+  const c = h.components || {};
+  return {
+    host: h.host,
+    overall: h.overall,
+    fans: c.fans || '-', psu: c.psu || '-', memory: c.memory || '-', cpu: c.cpu || '-',
+    raid: c.raid || '-', disks: c.disks || '-', temps: c.temps || '-',
+    findings: h.findings ?? 0,
+    checked: h.checked_at ? h.checked_at.replace('T', ' ').slice(0, 16) : '-',
+  };
+}
+
+/**
+ * When a finding was seen. Event findings carry the earliest and latest REAL dated event (an undated "Pre-Init"
+ * SEL entry has none); a run over several days shows both ends, and no date is said plainly, never invented.
+ */
+function hwWhen(f) {
+  const first = f.first_seen ? f.first_seen.slice(0, 10) : null;
+  const last = f.last_seen ? f.last_seen.slice(0, 10) : null;
+  if (first && last && last !== first) return `  (first ${first}, last ${last})`;
+  if (first) return `  (since ${first})`;
+  if (f.basis === 'events' && !/date not recorded/.test(f.title || '')) return '  (date not recorded by the BMC)';
+  return '';
+}
+
+/** HYPERION-NEXT P10: `quox fleet hw <host>`: every finding with what it means and what to do. */
+function printHwHost(r, baseline) {
+  console.log(`${r.host || '?'}  ${String(r.overall || 'unknown').toUpperCase()}  ${r.model || ''}  checked ${r.checked_at || '-'}`);
+  const c = r.components || {};
+  console.log(Object.keys(c).map((k) => `${k} ${c[k]}`).join('  '));
+  if (r.dimms) console.log(`memory: ${r.dimms.count} modules, ${r.dimms.total_gb} GB${baseline ? ` (baseline ${baseline.count} modules, ${baseline.total_gb} GB)` : ''}`);
+  if (r.power_restore_policy) console.log(`power restore policy: ${r.power_restore_policy}`);
+  const findings = r.findings || [];
+  if (!findings.length) console.log('\nNo findings.');
+  for (const f of findings) {
+    console.log(`\n[${f.severity}] ${f.component}: ${f.title}${hwWhen(f)}`);
+    console.log(`  What it means: ${f.meaning}`);
+    console.log(`  What to do: ${f.action}`);
+    for (const e of (f.evidence || []).slice(0, 3)) console.log(`  evidence: ${e}`);
+  }
+  for (const g of r.gaps || []) printWarning(`not checked: ${g}`);
+}
 
 /**
  * Map a raw /api/v1/gpu/nodes row to the flat shape `fleet gpu`'s table
@@ -95,6 +140,7 @@ export const DEFAULT_CODEX_MODEL = 'gpt-5.4';
 
 /** Tools whose input schema has a `host` field (collector reads input.host, not body.host_id). */
 const TOOLS_READING_INPUT_HOST = new Set(['ssh_exec']);
+const HW_HOST_RE = /^(?:[A-Za-z0-9][A-Za-z0-9_-]{0,62}|\d{1,3}(?:\.\d{1,3}){3})$/; // same shape the collector's fleet hw routes accept
 
 /** Locates the vendored (bwrap-capable) codex binary on the host. */
 export const CODEX_VENDOR_FIND_COMMAND =
@@ -635,6 +681,121 @@ export function registerFleetCommands(program, ctx) {
       }, { format: program.opts().output, emptyMessage: 'No GPU nodes enrolled yet.' });
     });
 
+  // HYPERION-NEXT P10: bare-metal hardware health (fans, power supplies, temperatures, memory, CPU, RAID, disks).
+  const hw = fleet
+    .command('hw')
+    .description('Hardware health of the bare-metal hosts (fans, PSUs, memory, CPU, RAID, disks); give a host for its findings')
+    .argument('[host]', 'one host: list its findings with what they mean and what to do')
+    .action(async (host) => {
+      auth.requireAuth();
+      const json = program.opts().output === 'json';
+      if (host) {
+        const ep = resolveEndpoint('v1.fleet.hw.get', { host });
+        const data = await client.get(ep.path, { service: ep.service });
+        if (json) { formatDetail(data, { format: 'json' }); return; }
+        printHwHost(data.report || {}, data.baseline);
+        return;
+      }
+      const ep = resolveEndpoint('v1.fleet.hw.list');
+      const data = await client.get(ep.path, { service: ep.service });
+      if (json) { formatDetail(data, { format: 'json' }); return; }
+      formatOutput({
+        columns: ['host', 'overall', 'fans', 'psu', 'memory', 'cpu', 'raid', 'disks', 'temps', 'findings', 'checked'],
+        headers: ['Host', 'Overall', 'Fans', 'PSU', 'Memory', 'CPU', 'RAID', 'Disks', 'Temps', 'Findings', 'Checked'],
+        rows: (data.hosts || []).map(formatHwRow),
+      }, { format: program.opts().output, emptyMessage: data.no_fleet_for_org ? (data.message || 'This organisation has no fleet hosts on this Quox instance.') : 'No hardware reports yet. Run: quox fleet hw refresh' });
+      const o = data.overall || {};
+      if ((data.hosts || []).length) printInfo(`${o.fault || 0} fault, ${o.warn || 0} warn, ${o.ok || 0} ok, ${o.unknown || 0} unknown. Details: quox fleet hw <host>`);
+      if (data.poller) printInfo(`Poller: ${data.poller.armed ? `on, every ${Math.round((data.poller.interval_ms || 0) / 60000)} min` : 'off (FLEET_HW_POLL=1 turns it on)'}${data.poller.state && data.poller.state.last_outcome ? `, last tick ${data.poller.state.last_outcome}` : ''}`);
+      if (data.alerts) printInfo(`Alerts: ${data.alerts.enabled ? 'on, one inbox notification per new fault' : `off (${data.alerts.env_flag || 'FLEET_HW_ALERTS'}=1 turns them on)`}`);
+    });
+
+  hw
+    .command('events')
+    .description('Hardware event log (IPMI SEL) entries across the bare-metal hosts')
+    .option('--since <window>', 'only events since this window (30m, 12h, 1d, 2w) or ISO time', '1d')
+    .option('--host <host>', 'one host only')
+    .option('--severity <level>', 'fault, warn or info')
+    .option('--limit <n>', 'most events to return (max 1000)', '200')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('v1.fleet.hw.events');
+      const query = { since: options.since, limit: options.limit };
+      if (options.host) query.host = options.host;
+      if (options.severity) query.severity = options.severity;
+      const data = await client.get(ep.path, { service: ep.service, query });
+      if (program.opts().output === 'json') { formatDetail(data, { format: 'json' }); return; }
+      formatOutput({
+        columns: ['when', 'host', 'severity', 'sensor', 'event'],
+        headers: ['When', 'Host', 'Severity', 'Sensor', 'Event'],
+        rows: (data.events || []).map((e) => ({
+          when: e.ts ? e.ts.replace('T', ' ').slice(0, 19) : (e.raw_time || '-'),
+          host: e.host,
+          severity: e.severity,
+          sensor: e.sensor || '-',
+          event: [e.event, e.direction, e.detail].filter(Boolean).join(' | '),
+        })),
+      }, { format: program.opts().output, emptyMessage: `No hardware events since ${options.since}.` });
+    });
+
+  hw
+    .command('refresh')
+    .description('Check the bare-metal hardware now (read-only IPMI, RAID and SMART reads) and store a fresh report')
+    .argument('[host]', 'one host only (default: every bare-metal host)')
+    .action(async (host) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('v1.fleet.hw.refresh');
+      const data = await client.post(ep.path, { service: ep.service, body: host ? { hosts: [host] } : {}, timeout: 600000 });
+      if (program.opts().output === 'json') { formatDetail(data, { format: 'json' }); return; }
+      formatOutput({
+        columns: ['host', 'overall', 'faults', 'warns', 'top'],
+        headers: ['Host', 'Overall', 'Faults', 'Warnings', 'Top finding'],
+        rows: (data.hosts || []).map((h) => ({ host: h.host, overall: h.overall, faults: h.faults ?? 0, warns: h.warns ?? 0, top: (h.findings && h.findings[0] && h.findings[0].title) || '-' })),
+      }, { format: program.opts().output, emptyMessage: 'No bare-metal host answered.' });
+      for (const u of data.unreachable || []) printWarning(`${u.host}: no hardware answer (${u.error})`);
+      printInfo(`${(data.hosts || []).length} host(s) checked, ${data.reads || 0} read(s), ${data.failures || 0} failure(s). Collection ${data.collection_id || '-'}`);
+    });
+
+  // HYPERION-NEXT P10 slice 2: blink the chassis identify light so a person can find the server in the rack.
+  // An ACTION on the BMC, never card-free: it goes through ssh_exec, where `ipmitool chassis identify <n>` is not an
+  // allowlisted read, so the call is held for a human approval card like any other fleet write.
+  hw
+    .command('identify')
+    .description('Blink a host\'s chassis identify light so it can be found in the rack (held for approval)')
+    .argument('<host>', 'the bare-metal host')
+    .option('--seconds <n>', 'how long the light blinks, 30 to 600 seconds', '120')
+    .option('--reason <text>', 'why; shown on the approval card')
+    .option('--org <id>', 'org ID (overrides active org; required for QUOX_SERVICE_KEY automation callers unless QUOX_ORG_ID is set)')
+    .action(async (host, options) => {
+      auth.requireAuth();
+      if (!HW_HOST_RE.test(String(host))) throw new Error(`not a safe short hostname: ${JSON.stringify(String(host).slice(0, 40))}`);
+      const raw = String(options.seconds);
+      const seconds = /^\d{1,3}$/.test(raw) ? Number(raw) : NaN;
+      if (!(seconds >= 30 && seconds <= 600)) throw new Error(`--seconds must be a whole number from 30 to 600 (got ${JSON.stringify(raw.slice(0, 20))})`);
+      const body = {
+        tool_name: 'ssh_exec',
+        input: { host, command: `ipmitool chassis identify ${seconds}` },
+        reason: options.reason ? String(options.reason) : `Blink the identify light on ${host} for ${seconds} seconds so someone can find it in the rack`,
+      };
+      const orgId = auth.getOrgId(options.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> for automation callers, or pass --org <id>.');
+      }
+      if (orgId) body.org_id = orgId;
+      const ep = resolveEndpoint('v1.tools.execute');
+      const data = await client.post(ep.path, { service: ep.service, body, timeout: 120000 });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); }
+      const heldId = data && data.pending && (data.approvalId || (data._approval && data._approval.id));
+      const failed = (data && data.success === false) || (data && data.result && data.result.success === false);
+      if (program.opts().output !== 'json') {
+        if (data && data.pending) printInfo(`Held for approval (${heldId || 'pending'}). Once approved, the identify light on ${host} blinks for ${seconds} seconds.`);
+        else if (failed) printWarning(`The identify light on ${host} could not be turned on: ${(data && (data.error || (data.result && data.result.error))) || 'the command failed'}`);
+        else console.log(`The identify light on ${host} is blinking for ${seconds} seconds.`);
+      }
+      if (heldId) console.error(`after approval run: quox approvals result ${heldId}`);
+      if (failed && !(data && data.pending)) process.exitCode = 1;
+    });
+
   fleet
     .command('tools')
     .description('List available fleet tools')
@@ -716,6 +877,9 @@ export function registerFleetCommands(program, ctx) {
       if (failed && !(data && data.pending)) process.exitCode = 1;
     });
 
+  // BASTION-JANUS P3: the governed fleet recipe library (lib/commands/fleetRecipe.js).
+  registerFleetRecipeCommands(fleet, { client, auth, program });
+
   fleet
     .command('host-update <hostId>')
     .description('Update a host in the Bastion registry (link/clear its bootstrap credential)')

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