quoxcli 0.2.0 → 0.4.0

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/findingReconcile.js

@@ -0,0 +1,90 @@
+/**
+ * SITREP-FINDINGS: gather the evidence that a security finding was fixed, on the host where
+ * git and gh live, for `quox engagement reconcile`. The collector makes the decision
+ * (securityFindings.reconcileFinding); this module only finds facts and never guesses:
+ *   - issue: the stored issue_ref, the gripe_url Quox filed, a --link, or quox#N / #N in the
+ *     title (quox#N in the description). Its state comes from `gh issue view`; unreadable = left out.
+ *   - fix: commits on origin/main whose message cites the finding id or the linked issue
+ *     number, or a --link commit. landed = an ancestor of origin/main; deployed = an ancestor of
+ *     the build tree's HEAD (the tree quox-build last built from). A commit not on main is no fix.
+ */
+
+const GH_ISSUE_URL = /github\.com\/([\w.-]+)\/([\w.-]+)\/issues\/(\d+)/;
+
+export function issueRefsFor(finding, link = {}, issueRepo = 'quoxai/quox') {
+  const out = [];
+  const add = (r) => { if (r && !out.includes(r)) out.push(r); };
+  if (finding.issue_ref) add(finding.issue_ref);
+  const m = GH_ISSUE_URL.exec(finding.gripe_url || '');
+  if (m) add(`${m[1]}/${m[2]}#${m[3]}`);
+  if (link.issue) add(normIssue(link.issue, issueRepo));
+  const t = /(?:quox)?#(\d{1,6})\b/.exec(String(finding.title || ''));
+  if (t) add(`${issueRepo}#${t[1]}`);
+  const d = /\bquox#(\d{1,6})\b/.exec(String(finding.description || ''));
+  if (d) add(`${issueRepo}#${d[1]}`);
+  return out;
+}
+
+export function normIssue(ref, issueRepo = 'quoxai/quox') {
+  const s = String(ref).trim();
+  const m = GH_ISSUE_URL.exec(s);
+  if (m) return `${m[1]}/${m[2]}#${m[3]}`;
+  if (/^[\w.-]+\/[\w.-]+#\d+$/.test(s)) return s;
+  const n = /^(?:quox)?#?(\d+)$/.exec(s);
+  return n ? `${issueRepo}#${n[1]}` : null;
+}
+
+function issueState(ref, run) {
+  const [repo, n] = ref.split('#');
+  const r = run('gh', ['issue', 'view', n, '-R', repo, '--json', 'state']);
+  if (!r.ok) return null;
+  try {
+    const st = String(JSON.parse(r.out).state || '').toLowerCase();
+    return st === 'open' || st === 'closed' ? st : null;
+  } catch { return null; }
+}
+
+function commitsCiting(term, regex, { repoDir, run }) {
+  const r = run('git', ['-C', repoDir, 'log', 'origin/main', '--format=%H', ...(regex ? ['-E'] : ['--fixed-strings']), `--grep=${term}`]);
+  if (!r.ok) return [];
+  return r.out.split('\n').map((x) => x.trim()).filter((x) => /^[0-9a-f]{40}$/i.test(x));
+}
+
+export function gatherEvidence(finding, link = {}, { repoDir, buildDir, issueRepo = 'quoxai/quox', run }) {
+  const ev = {};
+  const refs = issueRefsFor(finding, link, issueRepo);
+  if (refs.length) {
+    ev.issue_ref = refs[0];
+    const st = issueState(refs[0], run);
+    if (st) ev.issue_state = st;
+  }
+
+  const shas = [];
+  const add = (s) => { if (s && !shas.includes(s)) shas.push(s); };
+  if (link.commit) {
+    const full = run('git', ['-C', repoDir, 'rev-parse', '--verify', `${link.commit}^{commit}`]);
+    add(full.ok && /^[0-9a-f]{40}$/i.test(full.out.trim()) ? full.out.trim() : link.commit);
+  }
+  if (finding.fix_commit) add(finding.fix_commit);
+  for (const s of commitsCiting(finding.id, false, { repoDir, run })) add(s);
+  if (ev.issue_ref && ev.issue_ref.startsWith(`${issueRepo}#`)) {
+    const n = ev.issue_ref.split('#')[1];
+    for (const s of commitsCiting(`#${n}([^0-9]|$)`, true, { repoDir, run })) add(s);
+  }
+  if (!shas.length) return ev;
+
+  const head = run('git', ['-C', buildDir, 'rev-parse', 'HEAD']);
+  const buildHead = head.ok ? head.out.trim() : null;
+  const isAnc = (dir, sha, tip) => run('git', ['-C', dir, 'merge-base', '--is-ancestor', sha, tip]).ok;
+  const landed = shas.filter((s) => isAnc(repoDir, s, 'origin/main'));
+  const deployed = buildHead ? landed.filter((s) => isAnc(buildDir, s, buildHead)) : [];
+  if (deployed.length) { ev.fix_commit = deployed[0]; ev.fix_state = 'deployed'; } else if (landed.length) { ev.fix_commit = landed[0]; ev.fix_state = 'landed'; }
+  return ev;
+}
+
+export function evidenceChanged(finding, ev) {
+  for (const k of ['issue_ref', 'issue_state', 'fix_commit', 'fix_state']) {
+    if (ev[k] != null && ev[k] !== (finding[k] ?? null)) return true;
+  }
+  return false;
+}

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, 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/governedSession.js

@@ -37,8 +37,6 @@ export function autoName(now = new Date()) {
 export const PROGRAMS = {
   claude: { tag: '', bin: 'claude', resumeHint: (n) => `quox claude --resume ${n}` },
   codex: { tag: 'codex-', bin: 'codex', resumeHint: (n) => `quox codex resume ${n}` },
-  // gemini resumes by index or "latest" (--resume latest | --resume N), not by name.
-  gemini: { tag: 'gemini-', bin: 'gemini', resumeHint: () => 'quox gemini --resume latest' },
   tui: { tag: 'tui-', bin: 'quox', resumeHint: (n) => `quox tui --governed --name ${n}` },
 };
 
@@ -335,7 +333,7 @@ export function runLs(over) {
     return 1;
   }
   if (!s.length) {
-    d.write('No Quox sessions running. Start one with: quox claude (or quox codex, quox gemini, quox wrap <program>)\n');
+    d.write('No Quox sessions running. Start one with: quox claude (or quox codex, quox wrap <program>)\n');
     return 0;
   }
   const pad = (v, n) => String(v).padEnd(n);