quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/inbox.js

@@ -0,0 +1,173 @@
+/**
+ * Inbox / HITL commands: list, get, respond
+ */
+
+import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { attachWalkthrough } from './walkthrough.js';
+import { getApprovalContext, formatApprovalContext, approvalListColumns } from '../core/approvalContext.js';
+import { QuoxUserError } from '../core/errors.js';
+import { resolutionFromItem, alreadyResolvedError } from '../core/inboxResolution.js';
+import chalk from 'chalk';
+
+export function registerInboxCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  // An agent hands back a tool approvalId (tool_approvals.approval_id), stored on the card as
+  // aee_correlation_id. The server now resolves it on GET and respond (CLI-ERRORS); this client-side
+  // scan stays as the fallback for an older server. A failed scan is reported, never read as "no card".
+  async function findByApprovalId(orgId, id) {
+    const list = resolveEndpoint('inbox.list', { orgId });
+    const data = await client.get(list.path, { service: list.service, query: { status: 'all', kind: 'approval', limit: 200 } });
+    const items = (data && (data.items || data)) || [];
+    const hit = Array.isArray(items) && items.find((it) => it.aee_correlation_id === id || (it.payload && it.payload.approval_id === id));
+    return hit ? hit.id : null;
+  }
+
+  function notFound(id, cause) {
+    const err = new QuoxUserError(`No inbox item or approval with id ${id} in this org, open or resolved.`, {
+      next: "if it came from another org, switch with `quox org switch <org>`; `quox inbox list --status all` lists this org's items.",
+      exitCode: 5, code: 'not_found', status: 404, body: cause?.body,
+    });
+    return err;
+  }
+
+  async function resolveItemId(orgId, id) {
+    const direct = resolveEndpoint('inbox.get', { orgId, itemId: id });
+    try {
+      const data = await client.get(direct.path, { service: direct.service });
+      // the server resolves an approvalId to its card; post to the card's own id
+      return (data && data.item && data.item.id) || id;
+    } catch (err) {
+      if (!err || err.status !== 404) throw err;
+      const hit = await findByApprovalId(orgId, id);
+      if (hit) return hit;
+      throw notFound(id, err);
+    }
+  }
+
+  const inbox = program
+    .command('inbox')
+    .description('Manage inbox and approval requests');
+  attachWalkthrough(inbox, ctx, program);
+
+  inbox
+    .command('list')
+    .description('List inbox items')
+    .option('--status <status>', 'filter: one status, a comma list (resolved,cancelled,expired), or all (includes answered approvals). Default: active only')
+    .option('--decision <decision>', 'with resolved/all: approved or rejected')
+    .option('--page <n>', 'page number (newest first)')
+    .option('--priority <priority>', 'filter: low, normal, high, urgent')
+    .option('--awaiting-human', 'org-wide: approvals waiting for a human (see-only, cannot act)')
+    .option('--limit <n>', 'max results', '50')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const query = { limit: options.limit };
+      if (options.status) query.status = options.status;
+      if (options.decision) query.decision = options.decision;
+      if (options.page) query.page = options.page;
+      if (options.priority) query.priority = options.priority;
+      if (options.awaitingHuman) query.awaiting_human = 'true';
+      const data = await client.get(resolveEndpoint('inbox.list', { orgId }).path, { service: resolveEndpoint('inbox.list', { orgId }).service, query });
+      // HITL-CONTEXT: Source + Reason columns from payload.approval_context so a
+      // stale approval still says who asked and why without opening it.
+      const items = (data.items || data || []).map((it) => ({ ...it, ...approvalListColumns(it) }));
+      formatOutput({
+        columns: ['id', 'kind', 'priority', 'title', 'source', 'reason', 'status', 'created_at'],
+        headers: ['ID', 'Kind', 'Priority', 'Title', 'Source', 'Reason', 'Status', 'Created'],
+        rows: items,
+      }, { format: program.opts().output });
+    });
+
+  inbox
+    .command('get')
+    .alias('show')
+    .description('Get inbox item details (alias: show), including the approval context: source, on behalf of, reason, method, why approval')
+    .argument('<itemId>', 'inbox item ID, or a tool approvalId from an agent')
+    .action(async (givenId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const itemId = await resolveItemId(orgId, givenId);
+      const data = await client.get(resolveEndpoint('inbox.get', { orgId, itemId }).path, { service: resolveEndpoint('inbox.get', { orgId, itemId }).service });
+      const item = data.item || data;
+      const format = program.opts().output;
+      const context = getApprovalContext(item);
+      if (context && format !== 'json') {
+        // Lead with the context block: it is what a human needs to decide.
+        console.log(formatApprovalContext(context));
+        console.log('');
+        const { payload, ...rest } = item;
+        const { approval_context: _omit, ...payloadRest } = payload || {};
+        formatDetail({ ...rest, payload: payloadRest }, { format });
+        return;
+      }
+      formatDetail(item, { format });
+    });
+
+  inbox
+    .command('respond')
+    .description('Respond to an inbox item')
+    .argument('<itemId>', 'inbox item ID, or a tool approvalId from an agent')
+    .requiredOption('--action <action>', 'action: approve, reject, defer, resolve')
+    .option('--comment <text>', 'response comment')
+    .action(async (givenId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const format = program.opts().output;
+      const post = (itemId) => {
+        const ep = resolveEndpoint('inbox.respond', { orgId, itemId });
+        return client.post(ep.path, { service: ep.service, body: { action: options.action, comment: options.comment } });
+      };
+      // Resolve an approvalId to its card (server-side on a current server, else the client scan). When
+      // this profile cannot see the card, still ask the server: it knows WHY (an agent login, another
+      // org, already decided) and says so, where "not found" would hide it.
+      let itemId = givenId;
+      try { itemId = await resolveItemId(orgId, givenId); } catch (err) { if (err?.code !== 'not_found') throw err; }
+      let result;
+      try {
+        result = await post(itemId);
+      } catch (err) {
+        if (err?.status === 404) throw notFound(givenId, err);
+        if (!result) {
+          const resolution = await alreadyResolvedFrom(err, orgId, itemId, options.action);
+          if (!resolution) throw err;
+          if (!resolution.matches) throw alreadyResolvedError(resolution, err);
+          if (format === 'json') console.log(JSON.stringify({ success: true, already_resolved: true, ...resolution }));
+          else if (format !== 'quiet') console.log(chalk.green(`✔ ${resolution.message}`));
+          return;
+        }
+      }
+      if (result?.item?.status === 'expired') {
+        throw new QuoxUserError(result.message || 'This approval had expired, so nothing ran.', {
+          next: 're-run the original command to ask for a fresh approval.', exitCode: 1, code: 'approval_expired',
+        });
+      }
+      const PAST = { approve: 'approved', reject: 'rejected', deny: 'denied', defer: 'deferred', resolve: 'resolved', answer: 'answered' };
+      printSuccess(`Item ${PAST[options.action] || `${options.action} recorded`}.`);
+    });
+
+  // A respond on a closed card: the server's structured answer, else (older server) read the card.
+  async function alreadyResolvedFrom(err, orgId, givenId, action) {
+    if (!err || err.status !== 400) return null;
+    const body = err.body || {};
+    if (body.code === 'already_resolved' && body.resolution) return { ...body.resolution, message: body.message };
+    if (!/not open for response/i.test(`${body.error || ''} ${err.message || ''}`)) return null;
+    try {
+      const ep = resolveEndpoint('inbox.get', { orgId, itemId: givenId });
+      const data = await client.get(ep.path, { service: ep.service });
+      return resolutionFromItem(data.item || data, action);
+    } catch { return null; }
+  }
+
+  inbox
+    .command('stats')
+    .description('Show inbox statistics')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const data = await client.get(resolveEndpoint('inbox.stats.list', { orgId }).path, { service: resolveEndpoint('inbox.stats.list', { orgId }).service });
+      formatDetail(data.stats || data, { format: program.opts().output, title: 'Inbox Stats' });
+    });
+}

package/lib/commands/instagram.js

@@ -0,0 +1,264 @@
+/**
+ * `quox instagram` — Instagram plugin verbs, IG-3 (facebook CLI parity).
+ *
+ * quox instagram publish "<caption>" --account <ig_user_id> (--image <https url> | --video <https url>) [--reel]
+ * quox instagram accounts [--page <page_id>]
+ * quox instagram media --account <ig_user_id> [--limit <n>]
+ * quox instagram insights (--media <media_id> | --account <ig_user_id>) [--metrics <a,b,c>] [--period <period>]
+ * quox instagram comments --media <media_id> [--limit <n>]
+ * quox instagram reply <comment_id> "<message>"
+ * quox instagram quota --account <ig_user_id>
+ *
+ * The write verbs (publish, reply) execute the instagram connector tool
+ * through the governed collector endpoint (POST /api/v1/tools/execute ->
+ * connector bridge). The bridge gates them on requiresApproval: it files an
+ * owner approval card and returns immediately with
+ * { pending:true, status:'awaiting_approval', approvalId, inbox_item_id }.
+ * The actual Meta Graph API write (create-container -> poll -> publish, or
+ * the comment reply) only happens once the owner approves via the dashboard
+ * inbox or `quox inbox respond <id> --action approve`.
+ * Reads (accounts, media, insights, comments, quota) execute directly.
+ *
+ * Instagram is its own plugin on the SAME shared 'meta' vault credential as
+ * facebook_pages; there is no separate Instagram credential to configure.
+ */
+
+import { formatDetail, printSuccess, printInfo } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+/**
+ * Execute one instagram connector tool via the governed collector endpoint.
+ * A pending-approval response is a SUCCESS shape here (the card was filed);
+ * only a non-pending success:false is an error.
+ */
+async function executeInstagramTool({ client, auth, program }, toolName, input) {
+  auth.requireAuth();
+  const orgId = resolveOrgId(auth, program);
+  const ep = resolveEndpoint('v1.tools.execute');
+  const body = { tool_name: toolName, input, org_id: orgId };
+  const data = await client.post(ep.path, { service: ep.service, body });
+  if (data && data.success === false && !data.pending) {
+    throw new Error(`${toolName} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}`);
+  }
+  return data;
+}
+
+function printAwaitingApproval(action, data) {
+  const itemRef = data.inbox_item_id || data.approvalId || 'unknown';
+  printSuccess(`${action} filed for owner approval - inbox item ${itemRef} (awaiting approval). Nothing publishes until an approver says yes.`);
+  if (data.inbox_item_id) {
+    printInfo(`Review and approve: quox inbox get ${data.inbox_item_id}  (or: quox inbox respond ${data.inbox_item_id} --action approve)`);
+  }
+}
+
+export function registerInstagramCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const instagram = program
+    .command('instagram')
+    .description('Instagram publishing and monitoring (organic): governed, HITL-approved via HITL Inbox, on the shared Meta credential');
+
+  // ── instagram publish ────────────────────────────────────────────────────
+
+  instagram
+    .command('publish')
+    .description('Publish a single image, video, or reel to an Instagram account. Files an owner approval card and returns immediately; never publishes directly.')
+    .argument('[caption]', 'post caption (optional)')
+    .requiredOption('--account <ig_user_id>', 'Instagram professional account ID (from `quox instagram accounts`)')
+    .option('--image <url>', 'https URL of an image to publish (exactly one of --image/--video is required)')
+    .option('--video <url>', 'https URL of a video to publish (exactly one of --image/--video is required)')
+    .option('--reel', 'publish the video as a reel (only valid with --video)')
+    .action(async (caption, options) => {
+      if (!options.image && !options.video) {
+        throw new Error('instagram publish requires exactly one of --image or --video');
+      }
+      if (options.image && options.video) {
+        throw new Error('instagram publish accepts exactly one of --image or --video, not both');
+      }
+      if (options.reel && !options.video) {
+        throw new Error('--reel is only valid with --video');
+      }
+
+      const input = { ig_user_id: options.account };
+      if (caption) input.caption = caption;
+      if (options.image) {
+        input.image_url = options.image;
+        input.media_type = 'IMAGE';
+      } else {
+        input.video_url = options.video;
+        input.media_type = options.reel ? 'REELS' : 'VIDEO';
+      }
+
+      const data = await executeInstagramTool({ client, auth, program }, 'instagram_publish_media', input);
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      printAwaitingApproval('Publish', data);
+    });
+
+  // ── instagram accounts (discover, read) ──────────────────────────────────
+
+  instagram
+    .command('accounts')
+    .description('Discover the Instagram professional account linked to a Facebook Page (read-only, no approval needed).')
+    .option('--page <page_id>', 'Facebook Page ID to resolve (optional; checks every Page this token can manage when omitted)')
+    .action(async (options) => {
+      const input = {};
+      if (options.page) input.page_id = options.page;
+      const data = await executeInstagramTool({ client, auth, program }, 'instagram_discover_account', input);
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const result = data.result || {};
+      if (!result.ig_user_id) {
+        printInfo('No Instagram account resolved.');
+        return;
+      }
+      console.log(`${result.ig_user_id}  @${result.username || 'unknown'}  linked page: ${result.linked_page?.name || result.linked_page?.id || 'unknown'}`);
+    });
+
+  // ── instagram media (read) ───────────────────────────────────────────────
+
+  instagram
+    .command('media')
+    .description('List recent media on an Instagram account (read-only, no approval needed).')
+    .requiredOption('--account <ig_user_id>', 'Instagram professional account ID')
+    .option('--limit <n>', 'max media items to return (max 50)', '10')
+    .action(async (options) => {
+      const limit = Math.min(parseInt(options.limit, 10) || 10, 50);
+      const data = await executeInstagramTool({ client, auth, program }, 'instagram_list_media', {
+        ig_user_id: options.account,
+        limit,
+      });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const media = data.result || [];
+      if (media.length === 0) {
+        printInfo('No media returned.');
+        return;
+      }
+      for (const m of media) {
+        console.log(`${m.id}  ${m.media_type || ''}  ${m.timestamp || ''}`);
+        console.log(`  ${String(m.caption || '').replace(/\n/g, '\n  ')}`);
+      }
+    });
+
+  // ── instagram insights (read) ────────────────────────────────────────────
+
+  instagram
+    .command('insights')
+    .description('Show media or account insights (reach, saved, likes, comments, shares, views, follower_count).')
+    .option('--media <media_id>', 'Instagram media ID (media-level insights)')
+    .option('--account <ig_user_id>', 'Instagram professional account ID (account-level insights)')
+    .option('--metrics <metrics>', 'comma-separated metric names')
+    .option('--period <period>', 'day|week|days_28|lifetime (account-level only)')
+    .action(async (options) => {
+      if (!options.media && !options.account) {
+        throw new Error('instagram insights requires exactly one of --media or --account');
+      }
+      if (options.media && options.account) {
+        throw new Error('instagram insights accepts exactly one of --media or --account, not both');
+      }
+
+      let data;
+      if (options.media) {
+        const input = { media_id: options.media };
+        if (options.metrics) input.metrics = options.metrics;
+        data = await executeInstagramTool({ client, auth, program }, 'instagram_get_media_insights', input);
+      } else {
+        const input = { ig_user_id: options.account };
+        if (options.metrics) input.metrics = options.metrics;
+        if (options.period) input.period = options.period;
+        data = await executeInstagramTool({ client, auth, program }, 'instagram_get_account_insights', input);
+      }
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const series = data.result || [];
+      if (series.length === 0) {
+        printInfo('No insights returned.');
+        return;
+      }
+      for (const m of series) {
+        const latest = (m.values || [])[m.values.length - 1];
+        console.log(`${m.title || m.name}: ${latest ? JSON.stringify(latest.value) : 'unknown'}`);
+      }
+    });
+
+  // ── instagram comments (read) ────────────────────────────────────────────
+
+  instagram
+    .command('comments')
+    .description('List comments on an Instagram media item.')
+    .requiredOption('--media <media_id>', 'Instagram media ID')
+    .option('--limit <n>', 'max comments to return (max 100)', '25')
+    .action(async (options) => {
+      const limit = Math.min(parseInt(options.limit, 10) || 25, 100);
+      const data = await executeInstagramTool({ client, auth, program }, 'instagram_get_comments', {
+        media_id: options.media,
+        limit,
+      });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const comments = data.result || [];
+      if (comments.length === 0) {
+        printInfo('No comments returned.');
+        return;
+      }
+      for (const c of comments) {
+        console.log(`${c.id}  ${c.username || 'unknown'}  ${c.timestamp || ''}`);
+        console.log(`  ${String(c.text || '').replace(/\n/g, '\n  ')}`);
+      }
+    });
+
+  // ── instagram reply ──────────────────────────────────────────────────────
+
+  instagram
+    .command('reply')
+    .description('Reply to a comment on an Instagram media item. Files an owner approval card and returns immediately; never replies directly.')
+    .argument('<comment_id>', 'Instagram comment ID to reply to')
+    .argument('<message>', 'reply text')
+    .action(async (commentId, message) => {
+      const data = await executeInstagramTool({ client, auth, program }, 'instagram_reply_comment', { comment_id: commentId, message });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      printAwaitingApproval('Reply', data);
+    });
+
+  // ── instagram quota (read) ───────────────────────────────────────────────
+
+  instagram
+    .command('quota')
+    .description('Show the rolling 24-hour publishing quota for an Instagram account (hard cap: 100 API-published posts).')
+    .requiredOption('--account <ig_user_id>', 'Instagram professional account ID')
+    .action(async (options) => {
+      const data = await executeInstagramTool({ client, auth, program }, 'instagram_get_publishing_limit', { ig_user_id: options.account });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const result = data.result || {};
+      if (result.quota_usage == null) {
+        printInfo('No quota data returned.');
+        return;
+      }
+      console.log(`${result.quota_usage} / ${result.quota_total ?? 'unknown'} posts used (rolling ${result.quota_duration ? `${Math.round(result.quota_duration / 3600)}h` : '24h'} window)`);
+    });
+}

package/lib/commands/integration.js

@@ -0,0 +1,100 @@
+/**
+ * Integration commands — DEPRECATED alias of `quox vault`.
+ *
+ * VAULT-INTEG P6: this used to be a second, parallel implementation of
+ * credential CRUD that could not actually supply secret field values (its
+ * `create`/`update` sent a `config` body key the real route
+ * (POST/PUT /orgs/:orgId/integrations) never reads — it expects
+ * `credentials`). `quox vault` is the one working implementation; every
+ * subcommand here just prints a one-line deprecation note to stderr and
+ * forwards into the exact same action factories `quox vault` itself wires
+ * up (see lib/commands/vault.js `make*Action` exports), so a script that
+ * already calls `quox integration ...` keeps working (same HTTP calls, same
+ * exit codes) without a second copy of the request/response handling to
+ * drift out of sync.
+ */
+
+import {
+  makeVaultListAction,
+  makeVaultGetAction,
+  makeVaultCreateAction,
+  makeVaultUpdateAction,
+  makeVaultDeleteAction,
+  makeVaultTestAction,
+} from './vault.js';
+
+function warnDeprecated(subcommand, replacement) {
+  console.error(`quox integration ${subcommand} is deprecated; use \`quox vault ${replacement}\` instead.`);
+}
+
+export function registerIntegrationCommands(program, ctx) {
+  const integration = program
+    .command('integration')
+    .description('DEPRECATED: alias of `quox vault` — kept for existing scripts');
+
+  integration
+    .command('list')
+    .description('DEPRECATED — alias of `quox vault list`')
+    .option('--type <type>', 'filter by integration type')
+    .option('--status <status>', 'filter by test status (success|failed|untested)')
+    .action(async (options) => {
+      warnDeprecated('list', 'list');
+      return makeVaultListAction(ctx, program)(options);
+    });
+
+  integration
+    .command('get')
+    .description('DEPRECATED — alias of `quox vault get`')
+    .argument('<integrationId>', 'integration ID')
+    .action(async (integrationId) => {
+      warnDeprecated('get', 'get');
+      return makeVaultGetAction(ctx, program)(integrationId);
+    });
+
+  integration
+    .command('create')
+    .description('DEPRECATED — alias of `quox vault create`')
+    .option('--type <type>', 'integration type (skip prompt)')
+    .option('--label <label>', 'display label (skip prompt)')
+    .option('--set-default', 'set as default for this type')
+    .option('--no-test', 'skip connection test after creation')
+    .option('--credentials-file <path>', 'JSON object of {field: value} for the credential fields (use 0600; supports "env:VAR_NAME" values)')
+    .option('--credentials-stdin', 'read that same JSON object from stdin (never touches argv or disk)')
+    .option('--metadata <json>', 'JSON object of non-secret metadata tags')
+    .option('--repos <patterns>', 'repositories this credential covers: comma-separated owner/name, owner/*, or *')
+    .option('--no-input', 'never prompt; fail with a clear error if a required field is missing')
+    .action(async (options) => {
+      warnDeprecated('create', 'create');
+      return makeVaultCreateAction(ctx, program)(options);
+    });
+
+  integration
+    .command('update')
+    .description('DEPRECATED — alias of `quox vault update`')
+    .argument('<integrationId>', 'integration ID')
+    .option('--label <label>', 'new label')
+    .option('--description <desc>', 'new description')
+    .action(async (integrationId, options) => {
+      warnDeprecated('update', 'update');
+      return makeVaultUpdateAction(ctx, program)(integrationId, options);
+    });
+
+  integration
+    .command('delete')
+    .description('DEPRECATED — alias of `quox vault delete`')
+    .argument('<integrationId>', 'integration ID')
+    .option('--force', 'skip confirmation')
+    .action(async (integrationId, options) => {
+      warnDeprecated('delete', 'delete');
+      return makeVaultDeleteAction(ctx, program)(integrationId, options);
+    });
+
+  integration
+    .command('test')
+    .description('DEPRECATED — alias of `quox vault test`')
+    .argument('<integrationId>', 'integration ID')
+    .action(async (integrationId) => {
+      warnDeprecated('test', 'test');
+      return makeVaultTestAction(ctx, program)(integrationId);
+    });
+}

package/lib/commands/inventory.js

@@ -0,0 +1,115 @@
+/**
+ * `quox inventory` — the org's agent CMDB from the terminal (OPGOV quox#573).
+ *
+ * Org-wide rollup of the SAME grant graph `quox reach` evaluates per agent:
+ * which agents exist (core roster + org-created), their declared model
+ * routing, and per agent the granted tools / credentials / hosts / egress /
+ * delegation counts plus the least-privilege unused-grant signal. The
+ * collector computes it (GET /orgs/:orgId/inventory, witnessed as
+ * quox.reach.inventory); this command only renders.
+ *
+ * Honesty: 'unknown' cells are real values, not absences — a registry or
+ * layer that failed to enumerate says so, and `totals.complete` is only true
+ * when NOTHING was unknown anywhere. A '?' in the table is a '?'.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+function isJsonOutput(program) {
+  const o = program.opts();
+  return o.json === true || o.output === 'json';
+}
+
+function cell(v, width) {
+  const s = v === 'unknown' ? '?' : String(v ?? '-');
+  return s.padStart(width);
+}
+
+export function registerInventoryCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  program
+    .command('inventory')
+    .description("Org agent inventory (the agent CMDB): agents, models, tool/credential grants, delegation, unused-grant drift")
+    .option('--days <n>', 'observed-usage window for the unused-grant column (default 30)')
+    .option('--unused', 'ALSO compute the org-wide unused-grant pass (SLOW: minutes at org scale; for one agent use quox reach unused <agentId>)')
+    .option('--drift', 'diff against the last stored snapshot and store this rollup as the new baseline (witnessed as quox.reach.inventory_drift)')
+    .action(async (options) => {
+      const orgId = resolveOrgId(auth, program);
+      if (options.drift === true) {
+        const dep = resolveEndpoint('reach.org.inventory.drift', { orgId });
+        const result = await client.get(dep.path, { service: dep.service, timeout: 330000 });
+        if (!result || result.schema !== 'inventory-drift.v1') {
+          throw new Error(`unexpected response (schema ${result?.schema ?? 'missing'}, expected inventory-drift.v1): refusing to render. Check the collector URL points at a real collector.`);
+        }
+        if (isJsonOutput(program)) {
+          process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+          return;
+        }
+        if (result.baseline) {
+          process.stdout.write(`\u{1F4A5} REACH │ inventory drift │ baseline stored (snapshot #${result.snapshot_id}) · nothing to diff yet · re-run after the next change\n`);
+          return;
+        }
+        const d = result.drift || {};
+        const summary = d.changed
+          ? `+${(d.agents_added || []).length} agents · −${(d.agents_removed || []).length} · ${(d.model_changes || []).length} model · ${(d.reach_changes || []).length} reach · ${(d.visibility_changes || []).length} visibility`
+          : 'no change';
+        const trust = d.prev_complete && d.curr_complete ? '' : ' · CAUTION: one side of the diff was INCOMPLETE';
+        process.stdout.write(`\u{1F4A5} REACH │ inventory drift │ ${summary} · since ${result.prev_taken_at}${trust}\n`);
+        for (const a of d.agents_added || []) process.stdout.write(`  + ${a.id} (${a.source}${a.model ? `, ${a.model}` : ''})\n`);
+        for (const a of d.agents_removed || []) process.stdout.write(`  - ${a.id} (${a.source}${a.model ? `, ${a.model}` : ''})\n`);
+        for (const m of d.model_changes || []) process.stdout.write(`  ~ ${m.id} model ${m.from ?? 'default'} → ${m.to ?? 'default'}\n`);
+        for (const r of d.reach_changes || []) {
+          const zones = ['tools', 'credentials', 'delegates'].filter((z) => r[z]).map((z) => `${z} ${r[z].from}→${r[z].to}`).join(', ');
+          process.stdout.write(`  ~ ${r.id} ${zones}\n`);
+        }
+        for (const v of d.visibility_changes || []) process.stdout.write(`  ! ${v.id} ${v.from} → ${v.to}\n`);
+        return;
+      }
+      const ep = resolveEndpoint('reach.org.inventory', {
+        orgId,
+        days: options.days,
+        unused: options.unused === true,
+      });
+      // The first cold rollup resolves reach for every agent in the org and
+      // can take minutes; the collector caches per-agent reach for 10 min so
+      // re-runs are fast. 330s ceiling, not the default 30s.
+      const result = await client.get(ep.path, { service: ep.service, timeout: 330000 });
+      // A 200 with the wrong shape once rendered a confident empty table
+      // ("? agents", "undefined unknown") from a non-collector endpoint. A
+      // response that is not inventory.v1 is an error, never a rollup.
+      if (!result || result.schema !== 'inventory.v1') {
+        throw new Error(`unexpected response (schema ${result?.schema ?? 'missing'}, expected inventory.v1): refusing to render. Check the collector URL points at a real collector.`);
+      }
+
+      if (isJsonOutput(program)) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+      }
+
+      const t = result.totals || {};
+      const completeness = t.complete ? 'complete' : `INCOMPLETE (${t.agents_reach_unknown} agent(s) unknown, ${(result.unknowns || []).length} registry gap(s))`;
+      process.stdout.write(
+        `\u{1F4A5} REACH │ inventory │ ${t.agents ?? '?'} agents · ${t.tool_grants ?? '?'} tool grants · ${t.credential_grants ?? '?'} cred grants · ${completeness} · ${result.duration_ms ?? '?'}ms\n\n`
+      );
+
+      const header = `${'agent'.padEnd(22)}${'src'.padEnd(6)}${'model'.padEnd(18)}${cell('tools', 6)}${cell('creds', 6)}${cell('hosts', 6)}${cell('deleg', 6)}${cell('unused', 7)}  badge`;
+      process.stdout.write(`${header}\n${'─'.repeat(header.length)}\n`);
+      for (const a of result.agents || []) {
+        const r = a.reach;
+        const row = r === 'unknown'
+          ? `${a.id.padEnd(22)}${(a.source || '?').padEnd(6)}${(a.model || 'default').padEnd(18)}${cell('unknown', 6)}${cell('?', 6)}${cell('?', 6)}${cell('?', 6)}${cell('?', 7)}  reach failed: ${a.reach_error || '?'}`
+          : `${a.id.padEnd(22)}${(a.source || '?').padEnd(6)}${(a.model || 'default').padEnd(18)}${cell(r.tools, 6)}${cell(r.credentials, 6)}${cell(r.hosts, 6)}${cell(r.delegates, 6)}${cell(a.unused_grants ?? '-', 7)}  ${r.badge?.level || '-'}${(r.unknown_zones || []).length ? ` (?: ${r.unknown_zones.join(',')})` : ''}`;
+        process.stdout.write(`${row}\n`);
+      }
+
+      if ((result.unknowns || []).length) {
+        process.stdout.write('\nregistry gaps (first-class UNKNOWN, not zero):\n');
+        for (const u of result.unknowns) process.stdout.write(`  · [${u.source}] ${u.statement}\n`);
+      }
+      process.stdout.write(`\nunused-grant window: ${result.unused_window_days ?? 'skipped'} days · '?' = source did not enumerate · witnessed as quox.reach.inventory\n`);
+    });
+}
+
+export default registerInventoryCommands;