quoxcli 0.2.0 → 0.3.1

package/lib/commands/hat.js

@@ -1,18 +1,22 @@
 /**
- * QuoxHat commands (QUOXHAT #721 b): READ-ONLY views of the org's hats.
+ * QuoxHat commands (QUOXHAT #721 b; CUSTOM-HATS 2026-10-17).
  *
  *   quox hat list
  *   quox hat show <id|key> [--rev <n>]
- *   quox hat reset <id|key> --yes      (audited reset-to-template)
+ *   quox hat reset <id|key> --yes      (audited reset-to-template, built-ins)
+ *   quox hat create <key> --name "<Name>" [--from <hat>] [--agents a,b] [--tools x,y] [--mode m] [--offer o]
+ *   quox hat edit <hat> [--name N] [--add-agents|--remove-agents|--agents] [--add-tools|--remove-tools|--tools] [--mode m]
+ *   quox hat delete <hat> --yes        (custom hats only)
+ *   quox hat use <hat> --conversation <id> [--yes]
  *
- * 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.
+ * Custom hats (owner 2026-10-17): users who build their own agents organise them under their own
+ * hats, so a turn under "security" carries only the security agents, not every agent in the org.
+ * create/edit/delete act on CUSTOM hats only; a built-in is reset to its template, or copied with --from.
+ * Everything is server-side, org-scoped, revisioned and audited (services/auth/routes/quoxhat.js);
+ * who may create or change an org hat is the existing hat-edit permission (org manage-settings),
+ * a private hat (--private) only its owner. This file never decides permission itself.
  *
- * Backend: services/auth/routes/quoxhat.js (see cli/lib/api/endpoints/quoxhat.js).
+ * Backend: services/auth/routes/quoxhat.js (see cli/lib/api/endpoints/hat.js).
  */
 
 import chalk from 'chalk';
@@ -59,6 +63,32 @@ export function findHat(hats, ref) {
   return (hats || []).find(h => h.id === r) || (hats || []).find(h => h.key === r) || null;
 }
 
+
+export { DELEGATION_TOOLS, HAT_MODES, HAT_OFFERS, parseList, memberTools, applyMode, buildCustomDefinition, applyHatEdits } from '../core/customHats.js';
+import { parseList, memberTools, buildCustomDefinition, applyHatEdits } from '../core/customHats.js';
+
+/** Which of `ids` no registered or org agent matches. checked=false when neither list could be read. */
+export async function findUnknownAgents(client, orgId, ids) {
+  if (!ids.length) return { unknown: [], checked: true };
+  const known = new Set();
+  let read = 0;
+  try {
+    const ep = resolveEndpoint('v1.agents.registry');
+    const d = await client.get(ep.path, { service: ep.service });
+    if (Array.isArray(d?.agents)) { read++; for (const a of d.agents) if (a?.agent_id) known.add(String(a.agent_id).toLowerCase()); }
+  } catch { /* named below */ }
+  try {
+    const ep = resolveEndpoint('agents.list', { orgId });
+    const d = await client.get(ep.path, { service: ep.service });
+    const rows = Array.isArray(d?.agents) ? d.agents : (Array.isArray(d) ? d : null);
+    if (rows) { read++; for (const a of rows) { const id = a?.agent_id || a?.agentId; if (id) known.add(String(id).toLowerCase()); } }
+  } catch { /* named below */ }
+  if (!read) return { unknown: [], checked: false };
+  return { unknown: ids.filter(id => !known.has(id)), checked: true };
+}
+
+function isBuiltin(h) { return !!h?.template_key; }
+
 export function registerHatCommands(program, ctx) {
   const { client, auth } = ctx;
 
@@ -154,6 +184,8 @@ export function registerHatCommands(program, ctx) {
       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(`Offer:        ${def.tools?.offer === 'members' ? 'members (an orchestrator turn is offered only this hat\'s tools)' : 'authorized (hat tools first, then the rest of the grant)'}`);
+      out.push(`Kind:         ${h.template_key ? 'built-in' : 'custom'}${h.visibility === 'private' ? ' (private)' : ''}`);
       out.push(`Budgets:      initial_tool_target=${def.budgets?.initial_tool_target ?? '-'} max_manifest=${def.budgets?.max_manifest ?? '-'}`);
       out.push('');
       const explicit = def.tools?.explicit || [];
@@ -202,4 +234,141 @@ export function registerHatCommands(program, ctx) {
       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)} ✔`);
     });
+  // ── hat create (custom) ───────────────────────────────────────────────────────
+  hat
+    .command('create <key>')
+    .description('Create a custom hat: the agents and tools it lists are the only ones a turn under it carries')
+    .requiredOption('--name <name>', 'display name, e.g. "Security"')
+    .option('--from <hat>', 'start from a copy of this hat (key or id)')
+    .option('--agents <ids>', 'comma-separated agent ids this hat puts in scope (registered or your own agents)')
+    .option('--tools <names>', 'comma-separated tool names the orchestrator is offered under this hat')
+    .option('--mode <mode>', 'permissive (default: each agent keeps its own grant) or restrictive (only the listed tools are authorized, for every agent under the hat)')
+    .option('--offer <offer>', 'members (default: offer only this hat\'s tools) or authorized')
+    .option('--purpose <text>', 'one line: what this hat is for')
+    .option('--private', 'a private hat only you can see and wear (needs no org settings permission)')
+    .option('--reason <text>', 'why (kept in the revision history)')
+    .action(async (key, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const k = String(key || '').trim().toLowerCase();
+      if (!/^[a-z0-9][a-z0-9-]{1,40}$/.test(k)) throw new Error(`Hat key '${key}' must be a lowercase slug (a-z, 0-9, hyphen), 2-41 characters.`);
+      const list = await fetchList(client, orgId);
+      const hats = list?.hats || [];
+      if (findHat(hats, k)) throw new Error(`A hat with key '${k}' already exists in this org. Use quox hat edit ${k}.`);
+      let base = null;
+      if (options.from) {
+        const from = findHat(hats, options.from);
+        if (!from) throw new Error(`No hat '${options.from}' to copy. Available: ${hats.map(h => h.key).join(', ') || 'none'}`);
+        base = from.definition;
+      }
+      const agents = options.agents !== undefined ? parseList(options.agents) : undefined;
+      const tools = options.tools !== undefined ? parseList(options.tools) : undefined;
+      const { definition, autoAdded } = buildCustomDefinition({ base, name: options.name, purpose: options.purpose, agents, tools, mode: options.mode, offer: options.offer });
+      const named = definition.agents.specialists;
+      const check = await findUnknownAgents(client, orgId, named);
+      if (check.unknown.length) throw new Error(`Unknown agent(s): ${check.unknown.join(', ')}. See quox agent list.`);
+      const ep = resolveEndpoint('hat.create', { orgId });
+      const data = await client.post(ep.path, { service: ep.service, body: { key: k, name: String(options.name).trim(), definition, visibility: options.private ? 'private' : 'org' } });
+      const h = data?.hat;
+      if (!h) throw new Error(`Create of '${k}' returned no hat`);
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ hat: h, warnings: data.warnings || [], auto_added_tools: autoAdded }, null, 2)); return; }
+      const d = h.definition || definition;
+      console.log(`  Ⓠ QUOX │ hat ${h.key} created │ rev ${h.current_revision} · agents ${(d.agents?.specialists || []).join(', ') || 'none'} · ${memberTools(d).length} tool(s) · offer ${d.tools?.offer || 'authorized'} · ${authzMode(d)} ✔`);
+      if (autoAdded.length) printInfo(`Added ${autoAdded.join(', ')} so the orchestrator can reach the hat's agents.`);
+      if (!check.checked) printInfo('Agent ids were not checked: the agent lists could not be read.');
+      if (d.authz?.mode === 'restrictive') printInfo('Restrictive: every agent working under this hat, its own agents included when delegated to, may only run the tools listed here.');
+      for (const w of data.warnings || []) printInfo(`warning: ${w}`);
+      printInfo(`Wear it: /hat ${h.key} in quox, or quox hat use ${h.key} --conversation <id>.`);
+    });
+
+  // ── hat edit (custom) ─────────────────────────────────────────────────────────
+  hat
+    .command('edit <hat>')
+    .description('Change a custom hat: add or remove agents and tools, rename, mode (appends an audited revision)')
+    .option('--name <name>', 'rename the hat')
+    .option('--purpose <text>', 'new one-line purpose')
+    .option('--agents <ids>', 'replace the agent list')
+    .option('--add-agents <ids>', 'comma-separated agents to add')
+    .option('--remove-agents <ids>', 'comma-separated agents to remove')
+    .option('--tools <names>', 'replace the explicit tool list')
+    .option('--add-tools <names>', 'comma-separated tools to add')
+    .option('--remove-tools <names>', 'comma-separated tools to remove')
+    .option('--mode <mode>', 'permissive or restrictive')
+    .option('--offer <offer>', 'members or authorized')
+    .option('--reason <text>', 'why (kept in the revision history)')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) throw new Error(`No hat '${ref}' in this org. Available: ${(list?.hats || []).map(h => h.key).join(', ') || 'none'}`);
+      if (isBuiltin(found)) throw new Error(`'${found.key}' is a built-in hat: quox hat edit changes custom hats only. Reset it with quox hat reset ${found.key} --yes, or make your own from it: quox hat create <key> --name "<Name>" --from ${found.key}.`);
+      const opts = {
+        agents: options.agents !== undefined ? parseList(options.agents) : undefined,
+        addAgents: parseList(options.addAgents),
+        removeAgents: parseList(options.removeAgents),
+        tools: options.tools !== undefined ? parseList(options.tools) : undefined,
+        addTools: parseList(options.addTools),
+        removeTools: parseList(options.removeTools),
+        mode: options.mode,
+        offer: options.offer,
+        purpose: options.purpose,
+      };
+      const { definition, changes } = applyHatEdits(found.definition, opts);
+      const rename = options.name !== undefined && String(options.name).trim() !== found.name ? String(options.name).trim() : undefined;
+      if (rename !== undefined) changes.unshift(`name "${found.name}" -> "${rename}"`);
+      if (!changes.length) throw new Error(`Nothing to change on '${found.key}'.`);
+      const newAgents = [...(opts.agents || []), ...opts.addAgents];
+      const check = await findUnknownAgents(client, orgId, newAgents);
+      if (check.unknown.length) throw new Error(`Unknown agent(s): ${check.unknown.join(', ')}. See quox agent list.`);
+      const ep = resolveEndpoint('hat.update', { orgId, hatId: found.id });
+      const data = await client.put(ep.path, { service: ep.service, body: { definition, ...(rename !== undefined ? { name: rename } : {}), change_reason: options.reason || changes.join('; ') } });
+      const h = data?.hat;
+      if (!h) throw new Error(`Edit of '${found.key}' returned no hat`);
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ hat: h, changes, warnings: data.warnings || [] }, null, 2)); return; }
+      console.log(`  Ⓠ QUOX │ hat ${h.key} edited │ rev ${h.current_revision} · ${changes.join(' · ')} ✔`);
+      for (const w of data.warnings || []) printInfo(`warning: ${w}`);
+    });
+
+  // ── hat delete (custom) ───────────────────────────────────────────────────────
+  hat
+    .command('delete <hat>')
+    .description('Delete a custom hat (built-ins cannot be deleted; reset them instead). Audited.')
+    .option('--yes', 'confirm: conversations wearing it fall back to the default hat')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) throw new Error(`No hat '${ref}' in this org. Available: ${(list?.hats || []).map(h => h.key).join(', ') || 'none'}`);
+      if (isBuiltin(found)) throw new Error(`'${found.key}' is a built-in hat and cannot be deleted. quox hat reset ${found.key} --yes returns it to its template.`);
+      if (!options.yes) throw new Error(`Deleting '${found.key}' moves every conversation wearing it back to the default hat. Re-run with --yes to confirm.`);
+      const ep = resolveEndpoint('hat.delete', { orgId, hatId: found.id });
+      const data = await client.delete(ep.path, { service: ep.service });
+      const d = data?.deleted;
+      if (!d) throw new Error(`Delete of '${found.key}' returned no confirmation`);
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ deleted: d }, null, 2)); return; }
+      console.log(`  Ⓠ QUOX │ hat ${d.key} deleted │ was rev ${d.revision} · ${d.bindings_cleared} conversation(s) moved to the default · ${d.user_prefs_cleared} preference(s) cleared ✔`);
+    });
+
+  // ── hat use ───────────────────────────────────────────────────────────────────
+  hat
+    .command('use <hat>')
+    .description('Wear a hat in one conversation (the same audited switch as /hat <name> in quox)')
+    .requiredOption('--conversation <id>', 'the conversation to switch')
+    .option('--yes', 'confirm a privileged hat')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) throw new Error(`No hat '${ref}' in this org. Available: ${(list?.hats || []).map(h => h.key).join(', ') || 'none'}`);
+      if (found.definition?.transitions?.privileged && !options.yes) throw new Error(`'${found.key}' is a privileged hat. Re-run with --yes to wear it.`);
+      const ep = resolveEndpoint('hat.bind', { orgId, conversationId: options.conversation });
+      const data = await client.put(ep.path, { service: ep.service, body: { hat_id: found.id } });
+      const b = data?.binding;
+      if (!b) throw new Error(`Switch to '${found.key}' returned no binding`);
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ binding: b, hat: { id: found.id, key: found.key } }, null, 2)); return; }
+      console.log(`  Ⓠ QUOX │ conversation ${options.conversation} now wears ${found.key} │ rev ${b.revision} · seq ${b.seq} ✔`);
+    });
 }

package/lib/commands/helpers.js

@@ -2,7 +2,7 @@
  * Shared helpers for command modules
  */
 
-import { QuoxValidationError } from '../core/errors.js';
+import { QuoxValidationError, QuoxNetworkError } from '../core/errors.js';
 
 /**
  * Resolve the active org ID from --org flag or stored auth.
@@ -77,3 +77,20 @@ export function buildListQuery(options) {
   if (options.sort) query.sort = options.sort;
   return query;
 }
+
+/**
+ * Run a request; if it times out, rethrow with what timed out and how to narrow
+ * it (still a QuoxNetworkError, so the exit code stays 7). A bare
+ * "Request timed out after 30000ms" does not tell the operator which call hung
+ * or what to try (quox#806, quox#807).
+ */
+export async function withTimeoutHint(what, hint, fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (err instanceof QuoxNetworkError && /timed out/i.test(err.message || '')) {
+      throw new QuoxNetworkError(`${what} timed out (${err.message}). ${hint}`, err);
+    }
+    throw err;
+  }
+}

package/lib/commands/hyperion.js

@@ -0,0 +1,58 @@
+/**
+ * `quox hyperion`: everything HYPERION (the governed Proxmox operator, agent id atlas) is doing in one place.
+ * Collector route GET /api/v1/proxmox/activity (org-scoped, read only).
+ *
+ *   quox hyperion [status] [--json]   VMs and who holds them, node load, pool counts, last 5 ops
+ *   quox hyperion deck                live full-screen view, refreshes every 10s (q quits, r refreshes)
+ */
+import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { fetchActivity, statusLines, summaryText } from '../core/hyperion.js';
+
+export function registerHyperionCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const hy = program
+    .command('hyperion')
+    .description('HYPERION activity: which VMs exist, who holds each and why, node load and recent operations')
+    .option('--json', 'print the full JSON response');
+
+  const wantJson = (cmd) => {
+    const o = cmd.optsWithGlobals ? cmd.optsWithGlobals() : cmd.opts();
+    return Boolean(o.json) || program.opts().output === 'json';
+  };
+
+  // An error body is not data: report the status and stop.
+  async function show(cmd) {
+    auth.requireAuth();
+    let data;
+    try {
+      data = await fetchActivity(client);
+    } catch (err) {
+      const status = err && (err.status || err.statusCode);
+      if (!status) throw err;
+      console.error(`HYPERION request failed: HTTP ${status}${err.message ? ` ${err.message}` : ''}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+    printEvent(glyphLine('hyperion', 'activity', { result: summaryText(data) }));
+    console.log(statusLines(data).join('\n'));
+  }
+
+  hy.action(async (_o, cmd) => show(cmd));
+
+  hy
+    .command('status')
+    .description('Same as bare `quox hyperion`')
+    .option('--json', 'print the full JSON response')
+    .action(async (_o, cmd) => show(cmd));
+
+  hy
+    .command('deck')
+    .description('Live full-screen HYPERION deck (refreshes every 10s; r refreshes, q quits)')
+    .action(async () => {
+      auth.requireAuth();
+      const { launchHyperionDeck } = await import('../hyperion/deck.js');
+      await launchHyperionDeck({ activity: () => fetchActivity(client) });
+    });
+}

package/lib/commands/inbox.js

@@ -5,39 +5,52 @@
 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), which is
-  // stored on the inbox card as aee_correlation_id, not its item id. No server
-  // lookup-by-correlation route exists, so on a 404 we scan the org's approval
-  // cards (all statuses) client-side. Falls back to the id as given.
+  // 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 {
-      await client.get(direct.path, { service: direct.service });
-      return id;
+      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 list = resolveEndpoint('inbox.list', { orgId });
-      let data;
-      try {
-        data = await client.get(list.path, { service: list.service, query: { status: 'all', kind: 'approval', limit: 200 } });
-      } catch { data = null; }
-      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));
-      if (hit) return hit.id;
-      err.message += `\nHint: ${id} is not an inbox item id, and no approval card in your recent approvals carries it as an approvalId. `
-        + 'Try `quox inbox list --status all` to find the card.';
-      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')
@@ -102,14 +115,52 @@ export function registerInboxCommands(program, ctx) {
     .action(async (givenId, options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const itemId = await resolveItemId(orgId, givenId);
-      await client.post(resolveEndpoint('inbox.respond', { orgId, itemId }).path, {
-        service: resolveEndpoint('inbox.respond', { orgId, itemId }).service,
-        body: { action: options.action, comment: options.comment },
-      });
-      printSuccess(`Item ${options.action}ed.`);
+      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')

package/lib/commands/licence.js

@@ -5,53 +5,26 @@
  * Phase 1 (instance-local): status reads the lease (never the key), refresh
  * runs the renewal, seats lists/cleans band holders (dry run default).
  *
- * Phase 2 (owner-only, talks to the quox.ai WEBSITE admin API with a separate
- * website session, see core/websiteSession.js): reissue re-bands/extends a
- * licence record, catalogue-sign re-signs the product catalogue. Both are DRY
- * RUN unless --apply. The signing key never leaves the website VM; the CLI
- * never sees, prints or sends key material or licence keys.
+ * Phase 2 (owner-only vendor tooling for the quox.ai website) lives in
+ * lib/vendor/licenceOwner.js and is registered only when that file is present.
+ * lib/vendor/ is excluded from the npm package (quox#1134): the public build
+ * never carries it.
  */
 
-import { writeFileSync } from 'node:fs';
 import { formatOutput, formatDetail, printSuccess, printInfo, printWarning } from '../core/output.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { QuoxValidationError } from '../core/errors.js';
-import {
-  DEFAULT_WEBSITE_URL, DEFAULT_WEBSITE_PROFILE, normaliseWebsiteUrl, websiteLogin, websitePost,
-  saveWebsiteSession, clearWebsiteSession, getWebsiteSession,
-} from '../core/websiteSession.js';
 
-const OWNER_HELP = `
-Owner-only (website admin session, dry run unless --apply):
-  website-login       log in to the quox.ai admin API once (password is not stored)
-  reissue <licenseId> band bare paid ids / add ids, re-signed on the website VM
-  catalogue-sign      re-sign the product catalogue with the live key
-See the quox-licensing skill (~/.claude/skills/quox-licensing/SKILL.md).
-`;
-
-const ID_LIST_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-
-export function parseIdList(value, flag) {
-  if (value === undefined) return undefined;
-  const ids = String(value).split(',').map((s) => s.trim()).filter(Boolean);
-  for (const id of ids) {
-    if (!ID_LIST_RE.test(id)) throw new QuoxValidationError(`${flag}: invalid plugin id "${id}"`);
-  }
-  return ids;
-}
-
-export function parseOrgs(value) {
-  if (value === undefined) return undefined;
-  const n = Number(value);
-  if (!Number.isInteger(n) || n < 1 || n > 1000) throw new QuoxValidationError('--orgs must be an integer between 1 and 1000');
-  return n;
+// quox#1134: the owner-only website verbs are vendor tooling, kept out of the published package (package.json
+// "files" excludes lib/vendor/). Present in the dev tree, absent for every npm user.
+let VENDOR_OWNER = null;
+try {
+  VENDOR_OWNER = await import('../vendor/licenceOwner.js');
+} catch (e) {
+  if (!(e?.code === 'ERR_MODULE_NOT_FOUND' && String(e?.message || '').includes('licenceOwner'))) throw e;
 }
 
-function list(arr) {
-  return arr && arr.length ? arr.join(', ') : '(none)';
-}
-
-export function registerLicenceCommands(program, ctx) {
+export function registerLicenceCommands(program, ctx, { owner = VENDOR_OWNER } = {}) {
   const { client, auth } = ctx;
   const fetchImpl = ctx.websiteFetch || globalThis.fetch;
   const json = () => program.opts().output === 'json';
@@ -60,8 +33,8 @@ export function registerLicenceCommands(program, ctx) {
     .command('licence')
     .alias('license')
     .description('Instance licence status, lease refresh and seat bands')
-    .addHelpText('after', OWNER_HELP)
     .action(() => { licence.help(); });
+  if (owner) licence.addHelpText('after', owner.OWNER_HELP);
 
   licence
     .command('status')
@@ -162,119 +135,5 @@ export function registerLicenceCommands(program, ctx) {
       }
     });
 
-  // ---------------- Phase 2: owner-only, website admin API ----------------
-
-  licence
-    .command('website-login')
-    .description('Log in to the quox.ai website admin API for reissue/catalogue-sign (stores the session cookie only, 0600)')
-    .option('--website-profile <name>', 'website session profile', DEFAULT_WEBSITE_PROFILE)
-    .option('--url <url>', 'website base URL', DEFAULT_WEBSITE_URL)
-    .option('--username <name>', 'website admin username')
-    .option('--password-stdin', 'read the password from stdin (one line) instead of prompting')
-    .action(async (opts) => {
-      normaliseWebsiteUrl(opts.url); // refuse a bad or plain-http URL before asking for a password
-      let { username } = opts;
-      let password;
-      if (opts.passwordStdin) {
-        const chunks = [];
-        for await (const c of process.stdin) chunks.push(Buffer.from(c));
-        password = Buffer.concat(chunks).toString('utf8').split('\n')[0].trim();
-      }
-      if (!username || !password) {
-        const { default: inquirer } = await import('inquirer');
-        if (!username) username = (await inquirer.prompt([{ type: 'input', name: 'u', message: 'Website admin username:' }])).u;
-        if (!password) password = (await inquirer.prompt([{ type: 'password', name: 'p', message: 'Password:', mask: '*' }])).p;
-      }
-      if (!username || !password) throw new QuoxValidationError('username and password are required');
-      const session = await websiteLogin({ url: opts.url, username, password, fetchImpl });
-      password = null;
-      saveWebsiteSession(opts.websiteProfile, session);
-      if (json()) { console.log(JSON.stringify({ profile: opts.websiteProfile, url: session.url, username: session.username, must_change_password: session.must_change_password }, null, 2)); return; }
-      printSuccess(`Website session saved for ${session.username} at ${session.url} (profile ${opts.websiteProfile}, valid ~24h). Password not stored.`);
-      if (session.must_change_password) printWarning('This admin must change their password on the website before licence operations will be allowed (HTTP 403 until then).');
-    });
-
-  licence
-    .command('website-logout')
-    .description('End the website admin session and delete the stored cookie')
-    .option('--website-profile <name>', 'website session profile', DEFAULT_WEBSITE_PROFILE)
-    .action(async (opts) => {
-      if (getWebsiteSession(opts.websiteProfile)) {
-        try { await websitePost(opts.websiteProfile, '/api/admin/logout', {}, { fetchImpl }); } catch { /* session may already be dead */ }
-      }
-      const had = clearWebsiteSession(opts.websiteProfile);
-      printSuccess(had ? `Website session ${opts.websiteProfile} removed.` : `No website session ${opts.websiteProfile} was stored.`);
-    });
-
-  licence
-    .command('reissue')
-    .description('Owner-only: band bare paid ids and add ids on a licence record, re-signed on the website (dry run unless --apply)')
-    .argument('<licenseId>', 'licence id, e.g. lic_abc123')
-    .option('--orgs <n>', 'org band for every banded/added id (default 10)')
-    .option('--add <ids>', 'comma-separated ids to ADD as <id>@orgs=N')
-    .option('--band <ids>', 'comma-separated ids already present to FORCE-band')
-    .option('--apply', 'actually reissue (otherwise dry run, nothing changes)')
-    .option('--website-profile <name>', 'website session profile', DEFAULT_WEBSITE_PROFILE)
-    .action(async (licenseId, opts) => {
-      const body = { dryRun: !opts.apply };
-      const orgs = parseOrgs(opts.orgs);
-      if (orgs !== undefined) body.orgs = orgs;
-      const add = parseIdList(opts.add, '--add');
-      if (add) body.add = add;
-      const band = parseIdList(opts.band, '--band');
-      if (band) body.band = band;
-
-      const d = await websitePost(opts.websiteProfile, `/api/admin/licenses/${encodeURIComponent(licenseId)}/reissue`, body, { fetchImpl });
-      if (json()) { console.log(JSON.stringify(d, null, 2)); return; }
-
-      printInfo(`Licence ${d.license_id}${d.customer_email ? ` (${d.customer_email})` : ''}: max_servers ${d.max_servers ?? '?'}, expires ${d.expires_at || 'never'}`);
-      const removed = new Set(d.diff?.removed || []);
-      const added = new Set(d.diff?.added || []);
-      for (const e of d.current || []) console.log(`  ${removed.has(e) ? '-' : ' '} ${e}`);
-      for (const e of d.next || []) if (added.has(e)) console.log(`  + ${e}`);
-      if (d.unknown_ids?.length) printWarning(`Not issuable (unknown to the signed catalogue), apply will be refused: ${d.unknown_ids.join(', ')}`);
-
-      if (!d.changed) { printSuccess('No change needed: the licence already has these entitlements.'); return; }
-      if (d.dry_run) { printInfo('DRY RUN: nothing changed. Re-run with --apply to reissue.'); return; }
-      printSuccess(`Reissued ${d.license_id}. Audit/backup id: ${d.backup_id}`);
-      printInfo('Instances pick this up on their next lease renewal (~6h). To pull it now, on the instance: quox licence refresh');
-    });
-
-  licence
-    .command('catalogue-sign')
-    .alias('catalog-sign')
-    .description('Owner-only: re-sign the product catalogue with the live key on the website (dry run unless --apply)')
-    .option('--apply', 'actually sign and publish to the website API (otherwise dry run)')
-    .option('--out <path>', 'after --apply, save the signed catalogue (public artifact) here for committing')
-    .option('--website-profile <name>', 'website session profile', DEFAULT_WEBSITE_PROFILE)
-    .action(async (opts) => {
-      if (opts.out && !opts.apply) throw new QuoxValidationError('--out is only meaningful with --apply');
-      const d = await websitePost(opts.websiteProfile, '/api/admin/catalog/sign', { dryRun: !opts.apply }, { fetchImpl });
-      if (opts.out && d.artifact) writeFileSync(opts.out, JSON.stringify(d.artifact, null, 2) + '\n', 'utf8');
-      if (json()) {
-        const { artifact, ...rest } = d;
-        console.log(JSON.stringify({ ...rest, artifact_saved_to: opts.out && artifact ? opts.out : null }, null, 2));
-        return;
-      }
-      const p = d.published || {};
-      formatDetail({
-        published: p.exists ? `${p.verified ? 'verified' : 'NOT VERIFIED'}, sha256 ${p.sha256 ? p.sha256.slice(0, 16) : '?'}..., ${p.generated_at || '?'}` : '(none)',
-        products: `${p.product_count ?? 0} -> ${d.candidate?.product_count ?? '?'}`,
-        governed: `${p.governed_count ?? 0} -> ${d.candidate?.governed_count ?? '?'}`,
-        products_added: list(d.diff?.products_added),
-        products_removed: list(d.diff?.products_removed),
-        products_changed: list(d.diff?.products_changed),
-        governed_added: list(d.diff?.governed_added),
-        governed_removed: list(d.diff?.governed_removed),
-        signing_key: d.signing ? (d.signing.trusted ? `trusted (${d.signing.trusted_key_prefix}...)` : (d.signing.configured ? 'NOT the trusted key: apply will be refused' : 'not configured: apply will be refused')) : '?',
-      }, { title: d.dry_run ? 'Catalogue sign (DRY RUN)' : 'Catalogue sign' });
-      if (d.diff?.governed_added?.length) {
-        printWarning(`Newly governed: ${d.diff.governed_added.join(', ')}. Reissue the owner licence with these ids (quox licence reissue <id> --add ...) and refresh its lease BEFORE instances install this catalogue, or they lock out.`);
-      }
-      if (!d.changed) { printSuccess('No change: the published catalogue already matches.'); return; }
-      if (d.dry_run) { printInfo('DRY RUN: nothing signed. Re-run with --apply to sign.'); return; }
-      printSuccess(`Catalogue signed. sha256 ${d.sha256}, governed ${d.governed_count}, audit id ${d.audit_id}`);
-      if (opts.out) printInfo(`Signed catalogue saved to ${opts.out}.`);
-      printInfo('The website container copy does not survive a rebuild: commit the artifact to quox-website api/data/signed-catalog.json and quox-dashboard services/auth/data/signed-catalog.json (use --out to save it).');
-    });
+  if (owner) owner.registerLicenceOwnerCommands(licence, { json, fetchImpl });
 }