quoxcli 0.2.0 → 0.3.1

package/lib/core/errors.js

@@ -25,6 +25,15 @@ export class QuoxApiError extends QuoxError {
    *   handlers read this to render something actionable; --json emits it raw.
    */
   constructor(status, code, message, detail, body) {
+    // #1005: some services (quoxflow) answer { error: { code, message, details } }.
+    // Passed through as `code`, it printed as "Status: 400 [object Object]" and the
+    // real message and field errors were lost. Lift them out.
+    const structured = code && typeof code === 'object' ? code : null;
+    if (structured) {
+      if (structured.message && (!message || /^(Stream request|Request) failed with status/.test(message))) message = structured.message;
+      if (detail == null && structured.details != null) detail = structured.details;
+      code = typeof structured.code === 'string' ? structured.code : 'api_error';
+    }
     super(message, statusToExitCode(status));
     this.name = 'QuoxApiError';
     this.status = status;
@@ -73,6 +82,25 @@ export class QuoxValidationError extends QuoxError {
   }
 }
 
+/**
+ * CLI-ERRORS (owner 2026-10-17): the shared error contract. A command that knows what went wrong throws
+ * this: `headline` says what happened and why in plain words, `next` is the ONE best next step. The
+ * renderer prints exactly those two lines; technical detail (status, code, raw server text) only with
+ * --verbose. Exit code is the caller's choice (6 for "already decided differently", 5 for not found...).
+ */
+export class QuoxUserError extends QuoxError {
+  constructor(headline, { next = null, exitCode = 1, code = 'user_error', status, detail, body } = {}) {
+    super(headline, exitCode);
+    this.name = 'QuoxUserError';
+    this.headline = headline;
+    this.next = next;
+    this.code = code;
+    if (status) this.status = status;
+    if (detail != null) this.detail = detail;
+    if (body && typeof body === 'object') this.body = body;
+  }
+}
+
 function statusToExitCode(status) {
   if (status === 401) return 3;
   if (status === 403) return 4;
@@ -85,7 +113,8 @@ function statusToExitCode(status) {
 const STATUS_HINTS = {
   401: 'Run `quox login` to authenticate.',
   403: 'You may not have permission. Try `quox org switch` to change context.',
-  404: 'Resource not found. Use the `list` subcommand to see what exists.',
+  // #995: never name a verb that may not exist; handleError names the real one when it knows the group
+  404: 'Resource not found. Check the id; `quox <command> --help` shows how to list what exists.',
   409: 'Resource conflict. The item may already exist.',
   429: 'Rate limited. Wait a moment and try again.',
   500: 'Server error. Use --debug for details.',
@@ -93,40 +122,320 @@ const STATUS_HINTS = {
   503: 'Service temporarily unavailable. Check `quox service health`.',
 };
 
-export function handleError(err, outputFormat = 'table') {
+// quox#803: a 403 signature_invalid is not a permissions problem; the org
+// enforces trusted plugin keys. Only real verbs are named: `quox plugin
+// trusted-keys add` (CLI) and `quox-plugin sign` (@quoxai/quox-plugin-vite).
+function signatureInvalidHint(reason) {
+  const why = reason ? ` (reason: ${reason})` : '';
+  return `This org enforces trusted plugin signing keys${why}. Sign the bundle with \`npx quox-plugin sign\` (from @quoxai/quox-plugin-vite) and pass \`--signature <file>\`, `
+    + 'or have an org admin register your public key with `quox plugin trusted-keys add`.';
+}
+
+// Z2H-3c: a 402 LICENSE_REQUIRED printed only "Request failed with status 402" (seen on `quox fleet hosts`
+// on a fresh install). Name what is locked and the real verbs that unlock or inspect it.
+function licenseRequiredHint(body) {
+  const plugin = body?.plugin || body?.requiredPlugin;
+  return `${plugin ? `This needs a licence that includes \`${plugin}\`` : 'This needs a licence entitlement'}, and this install does not have it. `
+    + 'Activate one with `quox setup license activate --key-file <path>`; see what you have with `quox setup license status`.';
+}
+
+// An object `detail` (e.g. {holder_session}) printed as "[object Object]". Show message/code when present,
+// else compact JSON.
+export function renderDetail(detail) {
+  if (detail == null || detail === '') return '';
+  if (typeof detail === 'string') return detail;
+  // #1005: validation details as [{ path, message }] read as "field: problem".
+  if (Array.isArray(detail) && detail.length && detail.every((d) => d && typeof d === 'object' && typeof d.message === 'string')) {
+    return detail.map((d) => {
+      const path = Array.isArray(d.path) ? d.path.join('.') : d.path;
+      return path ? `${path}: ${d.message}` : d.message;
+    }).join('; ');
+  }
+  if (typeof detail === 'object') {
+    const parts = [detail.message, detail.code].filter((x) => typeof x === 'string' && x);
+    if (parts.length) return parts.join(' ');
+    try { return JSON.stringify(detail); } catch { return String(detail); }
+  }
+  return String(detail);
+}
+
+// A human-only route refused this login (an agent or resident identity). Switching org cannot help; a
+// human profile can.
+function humanOnlyHint() {
+  return 'This needs a human login, and the active profile is not one (it is an agent or service login). '
+    + 'Run it from a human profile: `quox -p <profile> ...`; `quox config profile list` shows them.';
+}
+
+function notSlotHolderHint() {
+  return 'You don\'t hold this slot. To post as a member: `quox slot join <slot> --session <S>`, then `quox slot say <slot> --room --session <S> <text>`.';
+}
+
+// #995: the 404 hint names `quox <group> list` only when that group really has a list verb, else its --help.
+function notFoundHint(ctx) {
+  if (!ctx || !ctx.group) return null;
+  return (ctx.subcommands || []).includes('list')
+    ? `Resource not found. \`quox ${ctx.group} list\` shows what exists.`
+    : `Resource not found. \`quox ${ctx.group} --help\` shows how to list what exists.`;
+}
+
+const RAW_HEADLINE = /^(Stream request|Request) failed with status \d+$/;
+
+function sentence(text) {
+  const t = String(text || '').trim();
+  if (!t) return t;
+  return /[.!?]$/.test(t) ? t : `${t}.`;
+}
+
+function lowerFirst(text) {
+  return text ? text[0].toLowerCase() + text.slice(1) : text;
+}
+
+/** The server's own words for this error: its message, else its prose `error`, else null. */
+function serverReason(err) {
+  const m = String(err.message || '').split('\n')[0];
+  if (m && !RAW_HEADLINE.test(m)) return m;
+  const code = typeof err.code === 'string' ? err.code : (typeof err.body?.error === 'string' ? err.body.error : '');
+  return /\s/.test(code) ? code : null;
+}
+
+/**
+ * CLI-ERRORS: map an error to the contract { headline, next }, or null to keep the legacy rendering
+ * (an error whose message already says it well; existing tests pin that output, see the audit).
+ */
+export function explainError(err, ctx = null) {
+  if (!err) return null;
+  if (err instanceof QuoxUserError) return { headline: err.headline, next: err.next };
+  if (!(err instanceof QuoxApiError)) return null;
+  const status = err.status;
+  const body = err.body && typeof err.body === 'object' ? err.body : {};
+  const code = typeof err.code === 'string' ? err.code : '';
+  const all = `${code} ${typeof body.error === 'string' ? body.error : ''} ${err.message || ''}`;
+  // reasonFromError: the client lifted a prose `error` into the message because the body had no `message`
+  const raw = RAW_HEADLINE.test(String(err.message || '').split('\n')[0]) || err.reasonFromError === true;
+  const reason = serverReason(err);
+
+  // #8 service-key fallback: the real problem is "no stored session", say it once.
+  if (err.serviceKeyFallback && (status === 401 || status === 403)) {
+    return {
+      headline: 'This needs a signed-in user, and this profile has no stored session, so the request went out with the service key, which carries no user.',
+      next: 'run `quox login` (or `quox -p <profile> login`), then retry.',
+    };
+  }
+  // #3 non-JSON error page from a proxy in front of a service
+  if ((code === 'non_json_response' || code === 'unknown') && status >= 500) {
+    return {
+      headline: 'The server answered with an error page instead of Quox data, so the service behind it is down or restarting.',
+      next: 'check `quox service health`, then retry.',
+    };
+  }
+  // #9 / #10 sign-in
+  if (status === 401 && code === 'invalid_credentials') {
+    return {
+      headline: 'Sign-in failed: the email or password is wrong for this server.',
+      next: 'check the profile and server with `quox config profile list`, or reset the password from the dashboard sign-in page.',
+    };
+  }
+  if (status === 401 && code === 'account_locked') {
+    return { headline: sentence(reason || 'This account is locked after too many failed sign-ins'), next: 'wait for the lock to expire, then run `quox login` again; nothing else is needed.' };
+  }
+  // #6 an agent login tried to decide a HITL item
+  if (status === 403 && /agents cannot resolve hitl/i.test(all)) {
+    return {
+      headline: 'Only a person can approve or reject inbox items, and this profile is an agent login.',
+      next: 'run it from a human profile: `quox -p <profile> ...`; `quox config profile list` shows them.',
+    };
+  }
+  // #13 / LICENSE_REQUIRED
+  if ((status === 402 || status === 403) && (code === 'LICENSE_REQUIRED' || body.error === 'LICENSE_REQUIRED')) {
+    if (body.reason === 'no_org_context') {
+      return { headline: 'This command needs an org, and none is selected for this profile.', next: 'pick one with `quox org switch <org>`; `quox org list` shows them.' };
+    }
+    const plugin = body.plugin || body.requiredPlugin;
+    return {
+      headline: `${plugin ? `This needs a licence that includes \`${plugin}\`` : 'This needs a licence entitlement'}, and this install does not have it.`,
+      next: 'activate one with `quox setup license activate --key-file <path>`; see what you have with `quox setup license status`.',
+    };
+  }
+  // #11 / #12 prose "not licensed" (only when the headline would otherwise be raw)
+  if ((status === 402 || status === 403) && /not licen[cs]ed/i.test(all) && (raw || status === 402)) {
+    const text = (reason || 'This feature is not licensed for this org').replace(/^(\S+) not licen/i, '$1 is not licen');
+    return { headline: sentence(text), next: '`quox setup license status` shows what this install has.' };
+  }
+  // #14 / #15 approvals
+  if (/^approval (request )?has expired$/i.test(reason || '')) {
+    return { headline: 'That approval expired before anyone decided it, so nothing ran.', next: 're-run the original command to ask for a fresh approval.' };
+  }
+  if (status === 404 && /^approval not found$/i.test(reason || '')) {
+    return { headline: 'No approval with that id in this org; it may belong to another org or be past retention.', next: notFoundNext(ctx) || '`quox approvals --help` shows how to list what exists.' };
+  }
+  // #5 a role refusal is not an org-context problem
+  if (status === 403 && /insufficient permissions?|lacks?[ _]capability|requires? (an? |the )?(admin|owner) role|not an? (org )?(admin|owner)/i.test(all)) {
+    return { headline: sentence(reason || 'Your role does not allow this'), next: 'your role in this org does not allow this; ask an org owner or admin to do it or to raise your role.' };
+  }
+  // #18 a 409 that already says "already exists" needs no echo
+  if (status === 409 && /already exists/i.test(reason || '')) {
+    return { headline: sentence(reason), next: 'pick a different id, or update the existing one.' };
+  }
+  // #1 / #4 the headline would be "Request failed with status N": lead with the server's reason
+  if (raw && reason) {
+    const next = (typeof body.hint === 'string' && body.hint)
+      || (status === 404 && notFoundNext(ctx))
+      || CONTRACT_NEXT[status]
+      || (STATUS_HINTS[status] ? lowerFirst(STATUS_HINTS[status]) : null);
+    return { headline: sentence(reason), next };
+  }
+  return null;
+}
+
+// The contract's own next steps: an action, never a restatement of the headline.
+const CONTRACT_NEXT = {
+  401: 'run `quox login`, then retry.',
+  403: 'if this belongs to another org, switch with `quox org switch <org>`; otherwise ask an org owner or admin.',
+  404: 'check the id; `quox <command> --help` shows how to list what exists.',
+  409: 'it may already exist or be in use; check its current state before retrying.',
+};
+
+function notFoundNext(ctx) {
+  const h = notFoundHint(ctx);
+  return h ? h.replace(/^Resource not found\. /, '') : null;
+}
+
+function isVerbose(ctx) {
+  if (ctx && ctx.verbose) return true;
+  const a = process.argv || [];
+  return a.includes('--verbose') || a.includes('-v') || a.includes('--debug') || Boolean(process.env.DEBUG);
+}
+
+/**
+ * CLI-ERRORS: the contract rendering for an API error with no specific mapping. Headline = the server's
+ * own first line; next = the most specific hint we have (the cases the legacy renderer knew), once.
+ */
+function fallbackExplain(err, ctx) {
+  const body = err.body && typeof err.body === 'object' ? err.body : {};
+  const tags = `${typeof err.code === 'string' ? err.code : ''} ${typeof body.error === 'string' ? body.error : ''}`;
+  const status = err.status;
+  let next;
+  if (status === 403 && /not (the current )?slot holder/i.test(tags)) next = notSlotHolderHint();
+  else if (status === 403 && /\b(only a human|requires a human)\b/i.test(`${tags} ${err.message || ''}`)) next = humanOnlyHint();
+  else if (status === 403 && (err.code === 'signature_invalid' || body.error === 'signature_invalid')) next = signatureInvalidHint(body.reason);
+  else if (status === 403 && /not licen[cs]ed/i.test(tags)) next = '`quox setup license status` shows what this install has.';
+  else if (err.code === 'PLUGIN_SERVICE_UNAVAILABLE') next = null;
+  else {
+    next = (typeof body.hint === 'string' && body.hint) || (status === 404 && notFoundNext(ctx)) || CONTRACT_NEXT[status]
+      || (STATUS_HINTS[status] ? lowerFirst(STATUS_HINTS[status]) : null);
+  }
+  const plain = { 400: 'The server could not accept that request', 401: 'You are not signed in, or the session has expired', 402: 'This needs a licence this install does not have',
+    403: 'This profile is not allowed to do that', 404: 'That was not found', 409: 'That conflicts with its current state', 429: 'Too many requests right now' };
+  const msg = String(err.message || '').split('\n')[0];
+  const first = serverReason(err) || (RAW_HEADLINE.test(msg) || !msg ? (plain[status] || (status >= 500 ? 'The server hit an error' : 'The request was refused')) : msg);
+  return { headline: sentence(first), next: next || null };
+}
+
+// CLI-ERRORS: an instruction sentence (the step the user takes) vs the rest (what happened).
+const INSTRUCTION = /^(run|check|use|retry|try|pass|fix|set|pick|switch|ask|log ?in|re-?run|please)\b/i;
+
+function splitInstruction(text) {
+  const first = String(text || '').split('\n')[0].trim();
+  const rest = String(text || '').split('\n').slice(1).map((l) => l.trim()).filter(Boolean);
+  const parts = first.split(/(?<=[.!?;])\s+/);
+  let idx = parts.findIndex((p, i) => i > 0 && INSTRUCTION.test(p));
+  let head = idx === -1 ? parts.join(' ') : parts.slice(0, idx).join(' ');
+  let next = idx === -1 ? null : parts[idx];
+  const more = [...(idx === -1 ? [] : parts.slice(idx + 1)), ...rest];
+  head = head.replace(/;$/, '');
+  if (next && /^please log ?in again\.?$/i.test(next)) next = 'run `quox login`, then retry.';
+  return { headline: sentence(head), next: next ? lowerFirst(next) : null, more };
+}
+
+/**
+ * CLI-ERRORS: errors the CLI raises itself (auth, network, validation, anything else) in the same
+ * contract as API errors: one headline, at most one Next, the rest (`more`) only with --verbose.
+ */
+export function explainLocal(err) {
+  if (!err || err instanceof QuoxApiError || err instanceof QuoxUserError) return null;
+  const message = String(err.message || '');
+  if (err instanceof QuoxNetworkError) {
+    const code = err.cause?.cause?.code || err.cause?.code || null;
+    const m = /^Could not connect to (\S+) service at (\S+?): /.exec(message);
+    const svc = m ? m[1] : null;
+    const url = m ? m[2] : null;
+    const more = message.split('\n').slice(1).map((l) => l.trim()).filter(Boolean);
+    if (m && code && /CERT|SELF_SIGNED|UNABLE_TO_VERIFY/.test(code)) {
+      return { headline: `Could not reach the ${svc} service at ${url}: its certificate is not trusted (${code}).`,
+        next: 'trust it with export NODE_EXTRA_CA_CERTS=<path to quox.crt> (on the server: ~/quox-install/quox/ssl/quox.crt); never disable TLS verification.', more };
+    }
+    if (m && (code === 'ERR_SSL_WRONG_VERSION_NUMBER' || code === 'EPROTO')) {
+      return { headline: `The ${svc} service at ${url} speaks plain http, but this profile's URL says https://.`,
+        next: `quox config set url ${url.replace(/^https:/, 'http:')}`, more };
+    }
+    if (m && code === 'ECONNREFUSED') {
+      return { headline: `Nothing is listening at ${url} for the ${svc} service: it is down, or this profile's URL is stale.`,
+        next: `run \`quox doctor\`; to point this shell elsewhere: export QUOX_${svc.toUpperCase()}_URL=<url>`, more };
+    }
+    const t = /^Request timed out after (\d+)ms$/.exec(message);
+    if (t) {
+      const secs = Math.round(Number(t[1]) / 1000);
+      return { headline: `The server did not answer within ${secs} second${secs === 1 ? '' : 's'}.`, next: 'check `quox service health`, then retry.', more };
+    }
+    return { headline: sentence(message.split('\n')[0]), next: 'check `quox service health`, then retry.', more };
+  }
+  if (err instanceof QuoxAuthError) {
+    const sp = splitInstruction(message);
+    if (!sp.next) {
+      sp.next = /QUOX_TOKEN_FILE/.test(message)
+        ? 'this principal runs only on its issued token; ask the owner to re-issue the token file.'
+        : err.transient ? 'wait a moment and retry; your stored session is kept.' : 'run `quox login`, then retry.';
+    }
+    return sp;
+  }
+  if (err instanceof QuoxValidationError) return splitInstruction(message);
+  const first = message.split('\n')[0];
+  return { headline: sentence(first || 'Something went wrong'), next: null, more: message.split('\n').slice(1), stack: true };
+}
+
+function renderContract(err, ex, ctx) {
+  console.error(chalk.red(`✖ ${ex.headline}`));
+  if (ex.next) console.error(chalk.yellow(`  Next: ${ex.next}`));
+  // #1000: a server that names the allowed values is telling the user the fix; keep it
+  if (err.body && typeof err.body === 'object') {
+    for (const [k, v] of Object.entries(err.body)) {
+      if (k.startsWith('valid_') && Array.isArray(v) && v.length) console.error(chalk.dim(`  Valid ${k.slice(6).replace(/_/g, ' ')}: ${v.join(', ')}`));
+    }
+  }
+  if (err.detail) console.error(chalk.dim(`  Detail: ${renderDetail(err.detail)}`));
+  if (isVerbose(ctx)) {
+    if (err.status) console.error(chalk.dim(`  Status: ${err.status} ${typeof err.code === 'object' && err.code ? renderDetail(err.code) : (err.code || '')}`));
+    if (err instanceof QuoxApiError && err.message && err.message !== ex.headline) console.error(chalk.dim(`  Server said: ${err.message}`));
+    for (const line of ex.more || []) if (line) console.error(chalk.dim(`  More: ${line}`));
+    if (ex.stack && err.stack) console.error(chalk.dim((err.stack || '').replace(/eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[JWT_REDACTED]')));
+  }
+}
+
+export function handleError(err, outputFormat = 'table', ctx = null) {
   if (outputFormat === 'json') {
     const obj = {
       error: true,
       code: err.code || err.name,
-      message: err.message,
+      message: err.headline || err.message,
     };
     if (err.status) obj.status = err.status;
     if (err.detail) obj.detail = err.detail;
     // LL-3d: scripts parsing --json get the server's own body verbatim, not
     // our prose rendering of it.
     if (err.body && typeof err.body === 'object') obj.body = err.body;
+    const ex = explainError(err, ctx) || (err instanceof QuoxApiError ? fallbackExplain(err, ctx) : explainLocal(err));
+    if (ex) { obj.headline = ex.headline; if (ex.next) obj.next = ex.next; }
     process.stderr.write(JSON.stringify(obj) + '\n');
     return;
   }
 
+  const ex = explainError(err, ctx);
+  if (ex) { renderContract(err, ex, ctx); return; }
+
   if (err instanceof QuoxApiError) {
-    console.error(chalk.red(`Error: ${err.message}`));
-    if (err.detail) console.error(chalk.dim(`  Detail: ${err.detail}`));
-    console.error(chalk.dim(`  Status: ${err.status} ${err.code || ''}`));
-    const hint = STATUS_HINTS[err.status];
-    if (hint) console.error(chalk.yellow(`  Hint: ${hint}`));
-  } else if (err instanceof QuoxAuthError) {
-    console.error(chalk.red(`Auth: ${err.message}`));
-  } else if (err instanceof QuoxNetworkError) {
-    console.error(chalk.red(`Network: ${err.message}`));
-    console.error(chalk.yellow('  Hint: Check that services are running with `quox service health`.'));
-  } else if (err instanceof QuoxValidationError) {
-    console.error(chalk.red(`Validation: ${err.message}`));
+    // CLI-ERRORS (PIN 01K55JRA11YHH73TN67X9ZDEGM): every API error renders in the contract now.
+    renderContract(err, fallbackExplain(err, ctx), ctx);
   } else {
-    console.error(chalk.red(`Error: ${err.message}`));
-    if (process.env.DEBUG || process.argv.includes('--debug')) {
-      const sanitized = (err.stack || '').replace(/eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[JWT_REDACTED]');
-      console.error(chalk.dim(sanitized));
-    }
+    renderContract(err, explainLocal(err), ctx);
   }
 }

package/lib/core/global-flags.js

@@ -39,15 +39,41 @@
 export function mergeShadowedGlobals(rootCommand, actionCommand) {
   if (!rootCommand || !actionCommand || actionCommand === rootCommand) return [];
 
-  const rootOpts = rootCommand.opts();
+  // Nearest ancestor first, root last. quox#1077 follow-up: a PARENT group
+  // that declares the same option shadows its leaf exactly like the root does
+  // (`quox lucid since-last --no-advance` set the flag on `lucid`, and the
+  // leaf kept its default and advanced the cursor). Only the root used to be
+  // consulted.
+  const ancestors = [];
+  for (let c = actionCommand.parent; c; c = c.parent) {
+    ancestors.push(c);
+    if (c === rootCommand) break;
+  }
+  const typed = (src) => src === 'cli' || src === 'env';
   const merged = [];
 
   for (const option of actionCommand.options) {
     const name = option.attributeName();
-    // A shadowed option can never carry a user value (commander gave it to
-    // the root), so an undefined here is unambiguous: nothing local to lose.
-    // A subcommand default is a real value and is left alone.
-    if (actionCommand.getOptionValue(name) === undefined && rootOpts[name] !== undefined) {
+    const localValue = actionCommand.getOptionValue(name);
+    const localSource = actionCommand.getOptionValueSource(name);
+    if (typed(localSource)) continue; // the user typed it on the leaf itself
+
+    // 1. A value the user TYPED on an ancestor wins over the leaf's default.
+    //    A shadowed option can never carry a user value (commander gave it to
+    //    the ancestor), so the leaf's value here is at most a default. This is
+    //    what makes --no-* options work: their default is true, never undefined.
+    const typedOn = ancestors.find((a) => a.options.some((o) => o.attributeName() === name)
+      && typed(a.getOptionValueSource(name)));
+    if (typedOn) {
+      actionCommand.setOptionValue(name, typedOn.getOptionValue(name));
+      merged.push(name);
+      continue;
+    }
+
+    // 2. Otherwise fill an empty leaf from the root (its default included),
+    //    as before. A subcommand default is a real value and is left alone.
+    const rootOpts = rootCommand.opts();
+    if (localValue === undefined && rootOpts[name] !== undefined) {
       actionCommand.setOptionValue(name, rootOpts[name]);
       merged.push(name);
     }
@@ -56,6 +82,80 @@ export function mergeShadowedGlobals(rootCommand, actionCommand) {
   return merged;
 }
 
+const HONOURS_GLOBAL_DRY_RUN = Symbol.for('quox.forwardsRawArgs');
+
+/**
+ * Mark a leaf that honours a --dry-run WITHOUT declaring its own option,
+ * because it forwards every raw argv token after its verb word to a wrapped
+ * tool (claude, codex, gemini, wrap). Such a leaf honours the flag only when
+ * it is typed AFTER the verb (it then reaches the wrapped tool); typed before
+ * the verb it reaches nothing, so it is refused like any other.
+ */
+export function markForwardsRawArgs(command, reason) {
+  command[HONOURS_GLOBAL_DRY_RUN] = reason || true;
+  return command;
+}
+
+/** 'declared' | 'forwards' | false */
+export function dryRunSupport(command) {
+  if (!command) return false;
+  if (command.options.some((o) => o.attributeName() === 'dryRun')) return 'declared';
+  if (command[HONOURS_GLOBAL_DRY_RUN]) return 'forwards';
+  return false;
+}
+
+/** The raw argv tokens before the leaf's own verb word (commander's root rawArgs). */
+function tokensBeforeVerb(rootCommand, actionCommand) {
+  const raw = Array.isArray(rootCommand.rawArgs) ? rootCommand.rawArgs : [];
+  const words = [];
+  for (let c = actionCommand; c && c !== rootCommand; c = c.parent) words.unshift(c.name());
+  let at = 0;
+  for (const w of words) {
+    const i = raw.indexOf(w, at);
+    if (i < 0) return raw; // cannot locate: treat everything as "before" (refuse)
+    at = i + 1;
+  }
+  return raw.slice(0, at - 1);
+}
+
+export function honoursGlobalDryRun(command, rootCommand) {
+  const support = dryRunSupport(command);
+  if (support === 'declared') return true;
+  if (support === 'forwards') return !rootCommand || !tokensBeforeVerb(rootCommand, command).includes('--dry-run');
+  return false;
+}
+
+/**
+ * Refuse a --dry-run the running leaf cannot honour (quox#1077 follow-up).
+ *
+ * `--dry-run` is a ROOT option, so commander accepts it after ANY verb. A leaf
+ * that never declared it then ignores it and runs for real: `quox offload npm
+ * publish --dry-run` published (the flag never reached npm), `quox discord bind
+ * ... --dry-run` bound (qdp bind has no dry run). A requested dry run must
+ * either be honoured or refused; it is never silently dropped.
+ *
+ * @throws {Error} exitCode 2, before the action runs
+ */
+export function assertDryRunHonoured(rootCommand, actionCommand) {
+  if (!rootCommand || !actionCommand || actionCommand === rootCommand) return;
+  const typed = (c) => ['cli', 'env'].includes(c.getOptionValueSource('dryRun')) && c.getOptionValue('dryRun') === true;
+  let requested = false;
+  for (let c = actionCommand; c; c = c.parent) {
+    if (typed(c)) { requested = true; break; }
+    if (c === rootCommand) break;
+  }
+  if (!requested || honoursGlobalDryRun(actionCommand, rootCommand)) return;
+  const path = [];
+  for (let c = actionCommand; c && c !== rootCommand; c = c.parent) path.unshift(c.name());
+  const err = new Error(
+    `\`quox ${path.join(' ')}\` has no dry run, so --dry-run cannot be honoured. Nothing was run. `
+    + 'If --dry-run belongs to a command you are passing through, put that command after -- .',
+  );
+  err.code = 'quox.dryRunNotHonoured';
+  err.exitCode = 2;
+  throw err;
+}
+
 /**
  * Walk a command tree and report every subcommand option that collides with a
  * root option. Used by the regression test to keep the blast radius visible:

package/lib/core/hyperion.js

@@ -0,0 +1,102 @@
+/**
+ * HYPERION activity: the shared reader and plain-text renderers behind `quox hyperion`,
+ * `quox hyperion deck` and the QUOXON /hyperion command. Pure functions over the
+ * GET /api/v1/proxmox/activity payload; no colour (callers paint), no grey, labels not bare values.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function fetchActivity(client) {
+  const ep = resolveEndpoint('v1.proxmox.activity');
+  return client.get(ep.path, { service: ep.service });
+}
+
+const ms = (v) => {
+  if (v == null || v === '') return null;
+  const n = typeof v === 'number' ? v : Date.parse(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+function span(delta) {
+  const s = Math.max(0, Math.floor(delta / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+/** Expiry wins ("expires in 3h" / "expired 1h ago"), else how long it has been held, else "-". */
+export function whenText(held, now = Date.now()) {
+  const exp = ms(held && held.expires);
+  if (exp != null) return exp >= now ? `expires in ${span(exp - now)}` : `expired ${span(now - exp)} ago`;
+  const since = ms(held && held.since);
+  if (since != null) return `held ${span(now - since)}`;
+  return '-';
+}
+
+export function holderText(held) {
+  const h = held || {};
+  if (h.source === 'pool') return h.lessee ? `${h.lessee} (pool)` : 'free (pool)';
+  if (h.source === 'lane') return `${h.lessee || 'unknown'} (lane)`;
+  return 'nobody recorded';
+}
+
+const isHeld = (v) => Boolean(v.held_by && v.held_by.lessee);
+const pct = (x) => (typeof x === 'number' ? `${Math.round(x * 100)}%` : '?');
+const gb = (b) => (typeof b === 'number' ? (b / 1e9).toFixed(1) : '?');
+const clipTo = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+/** Full one-shot view: VM table, node load, pool counts, last 5 ops. */
+export function statusLines(data, { now = Date.now() } = {}) {
+  const d = data || {};
+  const out = [];
+  const vms = d.vms || [];
+  if (!vms.length) out.push('No VMs are held or pooled right now.');
+  else {
+    const rows = vms.map((v) => [String(v.vmid), v.name || '', v.node || '', v.status || '', holderText(v.held_by), (v.held_by && v.held_by.purpose) || '-', whenText(v.held_by, now)]);
+    const head = ['VMID', 'NAME', 'NODE', 'STATUS', 'HELD BY', 'PURPOSE', 'AGE / EXPIRY'];
+    const w = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const fmt = (r) => r.map((c, i) => c.padEnd(w[i])).join('  ').trimEnd();
+    out.push(fmt(head), ...rows.map(fmt));
+  }
+  if (d.vms_truncated) out.push(`⚠ ${d.vms_truncated} more tagged VMs not shown`);
+  if (d.vm_config_errors) out.push(`⚠ ${d.vm_config_errors} VM description(s) could not be read, holder taken from tags`);
+  out.push('');
+  out.push('Node load');
+  if (d.nodes_error) out.push(`  Node load unavailable: ${d.nodes_error}`);
+  else if (!(d.nodes || []).length) out.push('  no nodes reported');
+  else for (const n of d.nodes) out.push(`  ${String(n.node).padEnd(10)} ${String(n.status).padEnd(8)} cpu ${pct(n.cpu)}   mem ${gb(n.mem_used)}/${gb(n.mem_total)} GB`);
+  out.push('');
+  if (d.pool) {
+    const counts = Object.entries(d.pool.counts || {}).map(([k, v]) => `${k} ${v}`).join(', ') || 'no VMs';
+    out.push(`Pool: ${d.pool.enabled ? 'enabled' : 'disabled'}, ${counts}${d.pool.paused ? ' (paused, waiting for approval)' : ''}`);
+  } else out.push(`Pool unavailable: ${d.pool_error || 'unknown'}`);
+  out.push('');
+  if (d.ops_error) out.push(`Recent ops unavailable: ${d.ops_error}`);
+  else {
+    const ops = (d.recent_ops || []).slice(0, 5);
+    out.push(`Recent ops (${ops.length})`);
+    if (!ops.length) out.push('  none recorded');
+    for (const o of ops) out.push(`  ${o.ts}  ${o.intent}  vmid ${o.vmid ?? '-'}  by ${o.actor || '?'}  outcome ${o.outcome ?? '-'}`);
+  }
+  return out;
+}
+
+/** Compact list for the TUI: a header, then one line per held VM. */
+export function heldLines(data, { now = Date.now(), width = 100 } = {}) {
+  const held = ((data && data.vms) || []).filter(isHeld);
+  if (!held.length) return ['No VMs are held right now.'];
+  const lines = [`${held.length} held`];
+  for (const v of held) {
+    const purpose = v.held_by.purpose ? `, ${v.held_by.purpose}` : '';
+    lines.push(clipTo(`${v.vmid} ${v.name || ''} on ${v.node || '?'} ${v.status || ''}: held by ${holderText(v.held_by)}${purpose}, ${whenText(v.held_by, now)}`, width));
+  }
+  return lines;
+}
+
+/** Result text for the QuoxGlyph header line. */
+export function summaryText(data) {
+  const vms = (data && data.vms) || [];
+  return `${vms.length} VMs · ${vms.filter(isHeld).length} held`;
+}