quoxcli 0.0.0-stage → 0.2.0

package/lib/commands/gripe.js

@@ -0,0 +1,324 @@
+/**
+ * `quox gripe` — QUOXIFY PASS 2 (DEVSUITE phase 15).
+ *
+ * The bundle audit (note #2840, theme S9) found Gripe had no `quox` verb at
+ * all, despite one being in its own definition of done. The customer-facing
+ * filing path was chat-agent-only, which meant a user had to know an agent
+ * existed and open a chat surface to report that something was broken. The
+ * fastest possible complaint is a one-liner in the terminal you are already
+ * in, which is exactly what the original terminal-only gripe skill was for.
+ *
+ * This wraps the WORKING path rather than building a second one: it talks to
+ * the GRIPE agent over the same governed chat route the dashboard and the
+ * Discord/Telegram bridges use, and GRIPE files the issue through the GitHub
+ * connector. No parallel issue store, no second credential model (the audit
+ * flagged three entry paths with three credential models; this adds a fourth
+ * ENTRY but reuses the third's governed path deliberately).
+ *
+ * Honest prerequisite, per the audit's "disclose the prereq" finding: filing
+ * needs a configured GitHub connector for the org. If it is missing, the
+ * agent says so and this command surfaces that plainly instead of pretending
+ * an issue was created.
+ */
+
+import { formatDetail, printInfo, printWarning } from '../core/output.js';
+import { events, line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+export function registerGripeCommands(program, { client, auth }) {
+  program
+    .command('gripe')
+    .description('File a one-liner complaint as a GitHub issue (via the GRIPE agent)')
+    .argument('<complaint...>', 'the gripe, e.g. "sidebar tooltip clips on resize"')
+    .option('--repo <owner/name>', 'target repo (GRIPE defaults sensibly when omitted)')
+    .option('--label <label>', 'issue label, e.g. bug, idea, fleet')
+    .option('--yes', 'skip the confirmation step and let GRIPE file it directly')
+    .action(async (complaintParts, options) => {
+      auth.requireAuth();
+      const complaint = complaintParts.join(' ').trim();
+      if (!complaint) throw new Error('say what is wrong: quox gripe "the thing that is broken"');
+
+      printEvent(glyphLine('quox', 'filing gripe via GRIPE'));
+      const orgId = resolveOrgId(auth, program);
+      const data = await askGripe({ client, complaint, repo: options.repo, label: options.label, yes: !!options.yes, orgId });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+
+      const r = await settleGripe({ client, data, complaint, options, orgId });
+      console.log('');
+      if (r.superseded) printInfo(SUPERSEDED_MESSAGE);
+      else console.log(r.response || '(no response)');
+      console.log('');
+      for (const n of r.notes) {
+        if (n.kind === 'created') printEvent(events.created('quox', 'issue', n.url));
+        else if (n.kind === 'info') printInfo(n.text);
+        else printWarning(n.text);
+      }
+    });
+}
+
+const SUPERSEDED_MESSAGE = 'GRIPE agent did not file this itself; its reply is superseded by the direct filing below.';
+
+/**
+ * Ask the GRIPE agent to file `complaint` over the governed chat route. -> the raw chat response.
+ * Shared by `quox gripe` and the quox client's /gripe, so there is one filing path.
+ */
+export async function askGripe({ client, complaint, repo, label, yes = false, orgId = null }) {
+  // GRIPE's whole discipline is speed: it does not investigate, it files.
+  // So the prompt states everything up front rather than inviting a
+  // back-and-forth the terminal is a bad place for.
+  const parts = [`File this gripe: ${complaint}`];
+  if (repo) parts.push(`Repo: ${repo}.`);
+  if (label) parts.push(`Label: ${label}.`);
+  if (yes) parts.push('File it now without asking me to confirm.');
+  else parts.push('Confirm the repo, label and title with me before filing.');
+  const ep = resolveEndpoint('chat.claude');
+  const body = { prompt: parts.join(' '), selected_agent: 'gripe' };
+  // The collector tracks which tools ran PER caller-supplied session_id;
+  // sending none meant tools_used always came back [] and classification
+  // fell back to parsing prose (DEVSUITE-GRIPE phase 5). One id per run.
+  body.session_id = `GRIPE_CLI_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+  if (orgId) body.org_id = orgId;
+  return client.post(ep.path, { service: ep.service, body, timeout: 120000 });
+}
+
+/**
+ * Decide the outcome of a GRIPE run and, with yes, run the deterministic file when the agent did not.
+ * -> { response, outcome, superseded, url, notes: [{ kind: 'created', url } | { kind: 'info'|'warn', text }] }.
+ * Prints nothing: the caller renders the notes (console for `quox gripe`, history lines for /gripe).
+ */
+export async function settleGripe({ client, data, complaint, options = {}, orgId = null }) {
+  const response = data?.result || data?.response || data?.text || '';
+  const yes = !!options.yes;
+  // tools_used is the collector's own record of which tools ran. Passing it
+  // is what stops the outcome from depending on how the agent phrased its
+  // reply. Absent (older collector), classification falls back to prose.
+  const toolsUsed = Array.isArray(data?.tools_used) ? data.tools_used : null;
+  const outcome = classifyGripeResponse(response, { assumedYes: yes, toolsUsed });
+  // quox#668: with --yes, a non-filing agent run is followed by the
+  // deterministic file. Printing the agent's prose first ("no tool, cannot
+  // file") right above "issue created" contradicted the real outcome. In
+  // that case the agent's reply is superseded, so say so instead of
+  // echoing a claim the next lines disprove.
+  const superseded = yes && ['no-connector', 'awaiting-confirm', 'not-filed'].some((k) => outcome.kind === k || outcome.hint === k);
+  const notes = [];
+  let url = null;
+  const det = async () => {
+    const r = await fileDeterministically({ client, complaint, options, orgId, quiet: true });
+    notes.push(...r.notes); if (r.url) url = r.url;
+    return r;
+  };
+  if (outcome.kind === 'filed') {
+    url = outcome.url; notes.push({ kind: 'created', url });
+  } else if (outcome.kind === 'filed-unknown') {
+    notes.push({ kind: 'warn', text: 'GRIPE called github_create_issue but no issue link came back. Check the repo before re-running: '
+      + 'the issue may exist, and a re-run would file it twice.' });
+  } else if (outcome.hint === 'no-connector' || outcome.kind === 'no-connector') {
+    // quox#621: "no connector" from the AGENT is not proof the org lacks
+    // one. The agent's tool-resolution can transiently fail (the gripe
+    // filed on an immediate retry, same org) or the github_create_issue
+    // tool may not be wired to this agent (#581), while a healthy github
+    // credential sits in the vault. The deterministic path resolves that
+    // credential server-side over a DIFFERENT route (the /github/issues
+    // proxy, not the agent tool), so with --yes we try it before believing
+    // the agent: if a connector really exists this files it (turning a
+    // silent-loss-then-retry into a first-try success); only if the vault
+    // path ALSO cannot file is the connector genuinely missing, and only
+    // then do we send the user to Settings.
+    if (yes) {
+      const r = await det();
+      if (!r.filed) notes.push({ kind: 'warn', text: NO_CONNECTOR_MESSAGE });
+    } else {
+      notes.push({ kind: 'warn', text: NO_CONNECTOR_MESSAGE });
+    }
+  } else if (outcome.hint === 'auth-unavailable' || outcome.kind === 'auth-unavailable') {
+    notes.push({ kind: 'warn', text: AUTH_UNAVAILABLE_MESSAGE });
+  } else if (outcome.hint === 'awaiting-confirm' || outcome.kind === 'awaiting-confirm') {
+    if (yes) await det();
+    else notes.push({ kind: 'info', text: 'GRIPE is asking you to confirm. Re-run with --yes to file it directly.' });
+  } else if (outcome.kind === 'not-filed') {
+    if (yes) await det();
+    else notes.push({ kind: 'warn', text: 'Not filed: github_create_issue was never called on this run.' });
+  } else {
+    notes.push({ kind: 'warn', text: 'No issue URL came back, so treat this as NOT filed until you can see the issue.' });
+  }
+  return { response, outcome, superseded, url, notes };
+}
+
+// quox#478: --yes must GUARANTEE a headless file, not merely ask the model
+// nicely. When the LLM run verifiably did not file (tools_used is the
+// collector's own record), fall back to the governed GitHub proxy
+// (POST /github/issues: user-authed, entitlement-gated, credential resolved
+// from the org vault server-side) and file deterministically. Deliberately
+// NOT run after 'filed-unknown' (the issue may exist; a second file would
+// duplicate it). It IS now run after 'no-connector' with --yes (quox#621):
+// the proxy resolves the vault credential over a DIFFERENT route than the
+// agent tool, so it succeeds when the agent merely failed to resolve/​wire the
+// tool (#581) — and the caller falls back to NO_CONNECTOR_MESSAGE only if this
+// also cannot file. Still NOT auto-run after auth-unavailable (a 403/429/503
+// is a platform outage the proxy would hit too; retrying shortly is the fix).
+// Returns { filed, url?, error? } so the caller can decide the message.
+export async function fileDeterministically({ client, complaint, options, orgId, quiet = false }) {
+  const notes = [];
+  const say = (n) => { notes.push(n); if (quiet) return; if (n.kind === 'created') printEvent(events.created('quox', 'issue', n.url)); else if (n.kind === 'info') printInfo(n.text); else printWarning(n.text); };
+  const repoArg = options.repo || 'quoxai/quox';
+  const [owner, repo] = repoArg.includes('/') ? repoArg.split('/', 2) : ['quoxai', repoArg];
+  const firstLine = complaint.split('\n')[0];
+  const title = firstLine.length > 80 ? `${firstLine.slice(0, 77)}...` : firstLine;
+  const ep = resolveEndpoint('github.issue.create');
+  try {
+    const data = await client.post(ep.path, {
+      service: ep.service,
+      body: {
+        owner,
+        repo,
+        title,
+        body: `## Gripe\n${complaint}\n\n## Context\n- Filed deterministically by \`quox gripe --yes\` (the GRIPE agent run did not file; quox#478 guarantee path)\n- Priority: minor / off-task observation\n\n## Suggested Action\nInvestigate and fix if confirmed.`,
+        labels: [options.label || 'fleet/qa'],
+        ...(orgId ? { org_id: orgId } : {}),
+      },
+    });
+    const url = data?.issue?.html_url || data?.issue?.url || null;
+    if (url) {
+      say({ kind: 'created', url });
+      say({ kind: 'info', text: 'Filed via the deterministic path (the GRIPE agent run did not file; --yes now guarantees the file).' });
+      return { filed: true, url, notes };
+    }
+    say({ kind: 'warn', text: 'Deterministic file returned no issue URL; treat as NOT filed until you can see the issue.' });
+    return { filed: false, notes };
+  } catch (err) {
+    say({ kind: 'warn', text: `Not filed: the GRIPE run did not file and the deterministic fallback failed too (${err.message}).` });
+    return { filed: false, error: err.message, notes };
+  }
+}
+
+const NO_CONNECTOR_MESSAGE =
+  'No issue was filed: the org has no GitHub connector configured. Set one up in Settings > Integrations, then re-run.';
+
+const AUTH_UNAVAILABLE_MESSAGE =
+  'No issue was filed: a platform authorization step failed (membership verify or credential resolve did not answer). '
+  + 'This is NOT a missing GitHub connector. Retry shortly; if it persists, check auth service health.';
+
+/**
+ * Decide what actually happened from GRIPE's reply.
+ *
+ * Split out of the action handler so it can be tested against real agent
+ * wording. The missing-connector branch used to match
+ * /not configured|no github|credential|connector/i, which does not match what
+ * the agent actually says. Observed live on 2026-08-23:
+ *
+ *   "GitHub isn't connected for this org, no issue-filing tool is available
+ *    right now. Connect GitHub in Settings > Integrations and I'll file it
+ *    immediately after. I'm not fabricating an issue number."
+ *
+ * None of the four alternatives appear in that sentence, so the specific,
+ * actionable "connect GitHub in Settings" advice was skipped and the user got
+ * the generic "treat this as NOT filed" instead. Both are honest, which is why
+ * this never showed up as a bug: it degraded to a vaguer truth rather than a
+ * falsehood. It still costs the user the one sentence that says what to do.
+ *
+ * Matching prose with a regex is fragile by nature and this will drift again
+ * when the agent's phrasing changes. It is deliberately biased toward the
+ * generic branch: a missed connector hint is a papercut, whereas wrongly
+ * claiming a connector problem would send someone to Settings for a fault
+ * that is not there. The URL check stays first and stays authoritative, since
+ * a real issue link is the only thing that proves filing.
+ */
+export function classifyGripeResponse(response, { assumedYes = false, toolsUsed = null } = {}) {
+  const text = String(response ?? '');
+  const url = (text.match(/https:\/\/github\.com\/\S+\/issues\/\d+/) || [])[0];
+  if (url) return { kind: 'filed', url, certain: true };
+
+  // The Claude CLI's own error for a NATIVE call to a tool that is not native.
+  // In CLI-tools mode the catalogue runs only via `quox tool exec`, so this
+  // string means github_create_issue never ran (2026-10-10: every --yes gripe
+  // fell to "unknown" on it and never reached the direct filing).
+  if (/No such tool available/i.test(text)) {
+    return { kind: 'not-filed', certain: true, hint: null };
+  }
+
+  // Structured evidence beats prose. The collector returns `tools_used` on
+  // every chat response, so whether github_create_issue actually RAN is a fact,
+  // not something to infer from English. Reading the outcome out of the agent's
+  // wording is what this function got wrong twice: once when the
+  // missing-connector phrasing changed, once when the bare word "connector"
+  // matched a healthy reply. A third regex patch would be the same mistake
+  // again, so the outcome now comes from the tool list and prose is demoted to
+  // a HINT about what to advise, where being wrong costs a sentence rather than
+  // a false claim.
+  // An EMPTY list is NOT evidence. The collector tracks MCP tool calls per
+  // caller-supplied session_id, so a request that sends none gets [] back
+  // whether or not the tool ran. Reading that as "never called" would replace a
+  // hedged truth with a confident falsehood and invite a duplicate issue.
+  // Absence of evidence is not evidence of absence.
+  if (Array.isArray(toolsUsed) && toolsUsed.length > 0) {
+    const ran = toolsUsed.some((t) => String(t).endsWith('github_create_issue'));
+    if (ran) {
+      // The tool ran and returned no link. Saying "filed" would invent an
+      // issue; saying "not filed" would send the user to file a duplicate.
+      return { kind: 'filed-unknown', certain: true };
+    }
+    return { kind: 'not-filed', certain: true, hint: adviceHint(text, assumedYes) };
+  }
+
+  // No structured evidence available (an older collector, or a surface that
+  // does not return tools_used). Fall back to the prose-only classification,
+  // unchanged, rather than degrading every caller to "unknown".
+  const hint = adviceHint(text, assumedYes);
+  if (hint === 'no-connector') return { kind: 'no-connector' };
+  if (hint === 'auth-unavailable') return { kind: 'auth-unavailable' };
+  if (hint === 'awaiting-confirm') return { kind: 'awaiting-confirm' };
+  return { kind: 'unknown' };
+}
+
+/**
+ * What to ADVISE when nothing was filed. This is a hint, never an outcome:
+ * getting it wrong costs the user one unhelpful sentence, where getting the
+ * outcome wrong costs them a duplicate issue or a phantom one.
+ *
+ * @returns {'no-connector'|'awaiting-confirm'|null}
+ */
+function adviceHint(text, assumedYes) {
+  // Platform-side authorization/availability failures beat the no-connector
+  // guess. On 2026-09-21 auth's rate limiter 429'd the collector's membership
+  // verify, the tool call 403'd with "no active membership", GRIPE narrated
+  // "GitHub isn't connected", and this function turned a platform outage into
+  // "the org has no GitHub connector configured" — a confident falsehood while
+  // the vault held three healthy credentials (quox#565). These shapes come
+  // from the collector's own error strings, so match them FIRST.
+  if (
+    /membership/i.test(text) ||
+    /verification .{0,20}unavailable/i.test(text) ||
+    /auth service did not answer/i.test(text) ||
+    /\b(403|503|429)\b/.test(text)
+  ) {
+    return 'auth-unavailable';
+  }
+
+  // Every alternative here must carry its own NEGATION. The bare words
+  // `credential` and `connector` used to be alternatives on their own, and on
+  // 2026-08-23 that fired on a reply where GRIPE said "Yes, I can see it" and
+  // then echoed the user's word inside the proposed issue title. The CLI told
+  // the user to go configure a connector that was working. `connector` and
+  // `credential` are what this feature is ABOUT, so they appear in healthy
+  // replies constantly; only a negation makes them evidence of anything.
+  const noConnector =
+    /not configured/i.test(text) ||
+    /no github/i.test(text) ||
+    /github (is|isn't|is not|was not|wasn't)\s*(n't)?\s*connect/i.test(text) ||
+    /no issue[- ]filing tool/i.test(text) ||
+    /connect github/i.test(text) ||
+    /no (\w+ ){0,2}(credential|connector|integration)/i.test(text) ||
+    /(credential|connector|integration)s?\s+(is|are)\s+(not|un)(configured|available|connected|set)/i.test(text);
+  if (noConnector) return 'no-connector';
+
+  // Only meaningful when the caller did NOT pass --yes: with --yes the prompt
+  // already told GRIPE to file without asking, so a reply with no URL is an
+  // unknown outcome, not a confirmation prompt.
+  if (!assumedYes) return 'awaiting-confirm';
+  return null;
+}

package/lib/commands/hat.js

@@ -0,0 +1,205 @@
+/**
+ * QuoxHat commands (QUOXHAT #721 b): READ-ONLY views of the org's hats.
+ *
+ *   quox hat list
+ *   quox hat show <id|key> [--rev <n>]
+ *   quox hat reset <id|key> --yes      (audited reset-to-template)
+ *
+ * Shows what each hat presents (explicit tools, bundles, connector families),
+ * its authorization mode, revision, template status and the org's enforcement
+ * and selection mode. Editing hat definitions is deliberately NOT here: edits
+ * go through the dashboard (Settings, QuoxHat Modes) where they are validated
+ * and audited. The one write is `reset`, which returns an org-edited built-in
+ * to its current template through the same audited route the dashboard uses.
+ *
+ * Backend: services/auth/routes/quoxhat.js (see cli/lib/api/endpoints/quoxhat.js).
+ */
+
+import chalk from 'chalk';
+import { formatOutput, printInfo } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+/** Authorization mode a hat declares; no authz block means permissive (grant ceiling). */
+export function authzMode(def) {
+  const a = def && typeof def.authz === 'object' ? def.authz : null;
+  if (!a) return 'permissive';
+  return a.mode === 'restrictive' ? 'restrictive' : 'permissive (declared)';
+}
+
+/** "v9", "v8 (template v9 available)" or "custom". */
+export function templateLabel(hat) {
+  if (!hat.template_key) return 'custom';
+  const cur = hat.template_version;
+  const latest = hat.template_latest;
+  // The latest revision's author (only on `show`, which carries history):
+  // anything not 'template:*' means the org edited this built-in, which
+  // freezes it out of automatic template upgrades until reset-to-template.
+  const latestAuthor = Array.isArray(hat.revisions) && hat.revisions[0] ? hat.revisions[0].created_by : null;
+  const customised = typeof latestAuthor === 'string' && !latestAuthor.startsWith('template:');
+  if (latest && cur && cur < latest) return `v${cur} (template v${latest} available)`;
+  return customised ? `v${cur || '?'} (edited)` : `v${cur || '?'}`;
+}
+
+function toolCounts(def) {
+  const explicit = Array.isArray(def?.tools?.explicit) ? def.tools.explicit.length : 0;
+  const bundles = Array.isArray(def?.tools?.bundles) ? def.tools.bundles : [];
+  const bundled = bundles.reduce((n, b) => n + (Array.isArray(b?.tools) ? b.tools.length : 0), 0);
+  return { explicit, bundles: bundles.length, bundled };
+}
+
+async function fetchList(client, orgId) {
+  const ep = resolveEndpoint('hat.list', { orgId });
+  return client.get(ep.path, { service: ep.service });
+}
+
+/** Resolve a hat argument (ULID or key) to its id using the org's hat list. */
+export function findHat(hats, ref) {
+  const r = String(ref || '').trim();
+  return (hats || []).find(h => h.id === r) || (hats || []).find(h => h.key === r) || null;
+}
+
+export function registerHatCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const hat = program
+    .command('hat')
+    .description('QuoxHat: read the org hats (tools, mode, revision, enforcement); reset a built-in to its template');
+
+  // ── hat list ────────────────────────────────────────────────────────────────
+  hat
+    .command('list')
+    .description('List the org hats with revision, template status, mode and tool counts')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const data = await fetchList(client, orgId);
+      const hats = Array.isArray(data?.hats) ? data.hats : [];
+      const settings = data?.settings || {};
+      const format = program.opts().output;
+
+      if (format === 'json') {
+        console.log(JSON.stringify({ hats, settings }, null, 2));
+        return;
+      }
+
+      const rows = hats.map(h => {
+        const c = toolCounts(h.definition);
+        return {
+          key: h.key + (settings.default_hat_id === h.id ? ' *' : ''),
+          name: h.name,
+          rev: String(h.current_revision),
+          status: h.status,
+          template: templateLabel(h),
+          mode: authzMode(h.definition),
+          privileged: h.definition?.transitions?.privileged ? 'yes' : 'no',
+          tools: `${c.explicit} + ${c.bundled} in ${c.bundles} bundle(s)`,
+          id: h.id,
+        };
+      });
+      formatOutput({
+        rows,
+        columns: ['key', 'name', 'rev', 'status', 'template', 'mode', 'privileged', 'tools', 'id'],
+        headers: ['Key', 'Name', 'Rev', 'Status', 'Template', 'Mode', 'Privileged', 'Tools (explicit + bundled)', 'ID'],
+      }, { format, emptyMessage: 'No hats.' });
+      printInfo(`Enforcement: ${settings.enforcement || 'preview'} · selection: ${settings.selection_mode || 'manual'}${settings.default_hat_id ? ' · * = org default' : ' · org default: built-in Default'}`);
+    });
+
+  // ── hat show ────────────────────────────────────────────────────────────────
+  hat
+    .command('show <hat>')
+    .description('Show one hat (id or key): tools, bundles, mode, revision history, enforcement')
+    .option('--rev <n>', 'show a historical revision instead of the current one')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      let rev;
+      if (options.rev !== undefined) {
+        rev = Number(options.rev);
+        if (!Number.isInteger(rev) || rev < 1) throw new Error(`--rev must be a positive integer (got '${options.rev}')`);
+      }
+
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) {
+        const keys = (list?.hats || []).map(h => h.key).join(', ') || 'none';
+        throw new Error(`No hat '${ref}' in this org. Available: ${keys}`);
+      }
+
+      const ep = resolveEndpoint('hat.get', { orgId, hatId: found.id });
+      const data = await client.get(ep.path, {
+        service: ep.service,
+        ...(rev ? { query: { revision: rev } } : {}),
+      });
+      const h = data?.hat;
+      if (!h) throw new Error(`Hat '${ref}' not found`);
+      const enforcement = data.enforcement || list?.settings?.enforcement || 'preview';
+
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify({ hat: h, enforcement, settings: list?.settings || null }, null, 2));
+        return;
+      }
+
+      const def = h.definition || {};
+      const shown = h.revision_shown || h.current_revision;
+      const out = [];
+      out.push(chalk.bold(`${h.name} (${h.key})`) + chalk.dim(`  ${h.id}`));
+      if (h.purpose) out.push(h.purpose);
+      out.push('');
+      out.push(`Revision:     ${shown}${shown !== h.current_revision ? chalk.yellow(`  (historical; current is ${h.current_revision})`) : ' (current)'}`);
+      out.push(`Digest:       ${h.digest || '-'}`);
+      out.push(`Status:       ${h.status}`);
+      out.push(`Template:     ${templateLabel(h)}`);
+      out.push(`Mode:         ${authzMode(def)}`);
+      out.push(`Enforcement:  ${enforcement} (org)`);
+      out.push(`Transitions:  confirm=${def.transitions?.confirm || 'none'} privileged=${def.transitions?.privileged ? 'yes' : 'no'}`);
+      out.push(`Agents:       orchestrator=${def.agents?.orchestrator || '-'} specialists=${(def.agents?.specialists || []).join(', ') || 'none'}`);
+      out.push(`Budgets:      initial_tool_target=${def.budgets?.initial_tool_target ?? '-'} max_manifest=${def.budgets?.max_manifest ?? '-'}`);
+      out.push('');
+      const explicit = def.tools?.explicit || [];
+      out.push(chalk.bold(`Explicit tools (${explicit.length}):`));
+      out.push(`  ${explicit.join(', ') || 'none'}`);
+      const bundles = def.tools?.bundles || [];
+      out.push(chalk.bold(`Bundles (${bundles.length}, loaded per conversation with hat_load_bundle):`));
+      for (const b of bundles) out.push(`  ${b.key}: ${(b.tools || []).join(', ')}`);
+      if (!bundles.length) out.push('  none');
+      const fams = def.tools?.connector_families || [];
+      out.push(chalk.bold('Connector families:') + ` ${fams.join(', ') || 'none'}`);
+      if (def.authz && typeof def.authz === 'object') {
+        if (Array.isArray(def.authz.allow)) out.push(`Authz allow:  ${def.authz.allow.join(', ')}`);
+        if (Array.isArray(def.authz.deny)) out.push(`Authz deny:   ${def.authz.deny.join(', ')}`);
+      }
+      const revisions = Array.isArray(h.revisions) ? h.revisions : [];
+      if (revisions.length) {
+        out.push('');
+        out.push(chalk.bold('Revisions:'));
+        for (const r of revisions) {
+          out.push(`  ${String(r.revision).padStart(3)}  ${r.created_at || ''}  ${r.created_by || ''}  ${r.change_reason || ''}`);
+        }
+      }
+      console.log(out.join('\n'));
+    });
+
+  // ── hat reset ───────────────────────────────────────────────────────────────
+  hat
+    .command('reset <hat>')
+    .description('Reset an org-edited built-in hat to its current template (drops the org edits; audited)')
+    .option('--yes', 'confirm: the org edits on this hat are replaced by the template')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      if (!options.yes) throw new Error(`Resetting '${ref}' replaces its org edits with the template. Re-run with --yes to confirm.`);
+      const orgId = resolveOrgId(auth, program);
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) {
+        const keys = (list?.hats || []).map(h => h.key).join(', ') || 'none';
+        throw new Error(`No hat '${ref}' in this org. Available: ${keys}`);
+      }
+      const ep = resolveEndpoint('hat.reset', { orgId, hatId: found.id });
+      const data = await client.post(ep.path, { service: ep.service, body: {} });
+      const h = data?.hat;
+      if (!h) throw new Error(`Reset of '${ref}' returned no hat`);
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ hat: h }, null, 2)); return; }
+      console.log(`  Ⓠ QUOX │ hat ${h.key} reset to template │ rev ${h.current_revision} · ${templateLabel(h)} ✔`);
+    });
+}

package/lib/commands/helpers.js

@@ -0,0 +1,79 @@
+/**
+ * Shared helpers for command modules
+ */
+
+import { QuoxValidationError } from '../core/errors.js';
+
+/**
+ * Resolve the active org ID from --org flag or stored auth.
+ * Throws if no org context is available.
+ */
+export function resolveOrgId(auth, program) {
+  const orgId = auth.getOrgId(program.opts().org);
+  if (!orgId) {
+    // Ask about AUTH before blaming the org, because a logged-out user has no
+    // org for the obvious reason, and telling them to switch org sends them
+    // down a path that cannot work.
+    //
+    // 2026-08-18: a new-user setup audit ran `quox slot create audit-demo` on
+    // a shell with no token. It answered "No active org. Use --org <id> or
+    // `quox org switch <id>` first." Following that instruction gave a
+    // DIFFERENT error, "No authentication token provided ... Run `quox login`".
+    // Two errors, two dead ends, and the real first step named only in the
+    // second one. The owner's standing complaint about this bundle is that it
+    // is not "easy as pie" to set up; this was the very first command in that
+    // path, and it misdirected.
+    //
+    // Every command that needs an org goes through here, so the fix lands once
+    // for all of them.
+    auth.requireAuth();
+
+    // requireAuth() passing does NOT mean a USER is logged in. isLoggedIn()
+    // also accepts an ambient QUOX_SERVICE_KEY as the automation fallback, and
+    // a service key carries no organisation — so on any box that exports one
+    // globally (every dev box here does) a logged-out user sails past the auth
+    // check and lands on "No active org", which sends them to `quox org
+    // switch` when the real first step is `quox login`.
+    //
+    // 2026-08-19: reproduced exactly that with `quox slot list --profile local`
+    // on a shell with QUOX_SERVICE_KEY exported. This is the SAME misdirection
+    // the 2026-08-18 note above set out to kill, arriving through the one door
+    // that check cannot see: the fix asked "are you authenticated?" when the
+    // question that matters is "authenticated AS WHOM?".
+    const hasUserToken = Boolean(auth.getTokens?.()?.access_token);
+    if (!hasUserToken) {
+      throw new Error(
+        'Authenticated with a service key, which has no organisation. '
+        + 'Run `quox login` to act as a user, or pass --org <id> to name the org explicitly.'
+      );
+    }
+
+    throw new Error('No active org. Use --org <id>, or pick one with `quox org list` then `quox org switch <id>`.');
+  }
+  return orgId;
+}
+
+/**
+ * Safely parse a JSON string from CLI input.
+ * Throws QuoxValidationError with a clear message on invalid JSON.
+ */
+export function parseJSON(value, label = 'JSON') {
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new QuoxValidationError(`Invalid ${label}: not valid JSON. Check your input and try again.`);
+  }
+}
+
+/**
+ * Build a query object from common list options.
+ */
+export function buildListQuery(options) {
+  const query = {};
+  if (options.limit) query.limit = options.limit;
+  if (options.offset) query.offset = options.offset;
+  if (options.search) query.search = options.search;
+  if (options.status) query.status = options.status;
+  if (options.sort) query.sort = options.sort;
+  return query;
+}