quoxcli 0.3.1 → 0.5.0

package/lib/core/client.js

@@ -12,6 +12,7 @@
 import { resolveActing, resolveActingToken } from './actingAs.js';
 import { detectCallerSource } from './callerSource.js';
 import { QuoxApiError, QuoxNetworkError, QuoxAuthError, QuoxTransientAuthError } from './errors.js';
+import { tlsFailureSentence } from './profileTrust.js';
 import { joinServiceUrl, isLocalServiceTarget } from './config.js';
 
 const RETRY_STATUSES = new Set([429, 502, 503]);
@@ -30,14 +31,21 @@ const TLS_TRUST_CODES = new Set([
   'ERR_TLS_CERT_ALTNAME_INVALID',
 ]);
 
+function tlsConnectUrl(u) {
+  try { return new URL(u).origin; } catch { return '<url>'; }
+}
+
 export function describeNetworkError(service, baseUrl, err) {
   const code = err?.cause?.code || err?.code;
   let msg = `Could not connect to ${service} service at ${baseUrl}: ${err.message}`;
   if (code && TLS_TRUST_CODES.has(code)) {
     msg += `\n  TLS: certificate not trusted (${code}). A new QuoxCORE uses its own self-signed certificate; trust that file`
+      + `\n  Trust this server for one profile with: quox connect ${tlsConnectUrl(baseUrl)} --profile <name>`
+      + `\n  (it shows the certificate SHA256 and asks y/N; with no terminal add --fingerprint <sha256>). Or trust the file for the whole shell`
       + `\n  (on the server, by default ~/quox-install/quox/ssl/quox.crt; copy it here if the server is another machine):`
       + `\n    export NODE_EXTRA_CA_CERTS=<path to quox.crt>`
-      + `\n  Never disable TLS verification (NODE_TLS_REJECT_UNAUTHORIZED=0) instead.`;
+      + `\n  Never disable TLS verification (NODE_TLS_REJECT_UNAUTHORIZED=0) instead.`
+      + `\n  ${tlsFailureSentence(code, baseUrl)}`;
   } else if (code === 'ERR_SSL_WRONG_VERSION_NUMBER' || code === 'EPROTO') {
     // quox#532 defect 1: the profile says https:// but the service answered
     // PLAINTEXT (classic: url stamped https://localhost:3000 against plain
@@ -68,6 +76,20 @@ function generateCorrelationId() {
   return `cli-${t}-${r}`;
 }
 
+/**
+ * PROFILE-NO-FALLBACK (2026-10-29): an explicitly chosen profile (-p / --profile / QUOX_PROFILE) with no
+ * session must never borrow this box's ambient service key: a memory create ran as the SERVICE, not objeng.
+ * The implicit fallback stays for the no-profile-chosen case. Throws before any request is sent.
+ */
+function assertNoExplicitProfileFallback(config) {
+  const explicit = Boolean(config?._explicitProfile) || Boolean(String(process.env.QUOX_PROFILE || '').trim());
+  if (!explicit) return;
+  let name = null;
+  try { name = typeof config.getActiveProfileName === 'function' ? config.getActiveProfileName() : null; } catch { name = null; }
+  name = name || config._effectiveProfile || process.env.QUOX_PROFILE;
+  throw new QuoxAuthError(`Profile ${name} is signed out. Sign in: quox -p ${name} login`);
+}
+
 /**
  * HITL-CONTEXT (owner 2026-10-07): name the calling session and profile so an
  * approval this call triggers says "VULCAN (CLI) · profile moo" instead of a
@@ -84,6 +106,8 @@ export function callerContextHeaders(config, env = process.env, detectDeps = {})
     try { session = detectCallerSource(env, detectDeps).label; } catch { session = null; }
   }
   if (session) headers['X-Quox-Session'] = clean(session, 48);
+  // The proof engine marks its turns: the server then files no approval for them (a read case must never page the owner).
+  if (env.QUOX_PROOF_TURN === '1') headers['X-Quox-Proof-Turn'] = '1';
   let profile = null;
   try { profile = typeof config?.getActiveProfileName === 'function' ? config.getActiveProfileName() : null; } catch { profile = null; }
   if (profile) {
@@ -115,6 +139,14 @@ export function createClient(config, auth) {
   // never tried again for the rest of its life). A cooldown keeps the
   // don't-hammer-auth property without the death sentence.
   const REFRESH_RETRY_COOLDOWN_MS = 60 * 1000;
+  // quox#1375: a profile with nothing to refresh with (the collector's quox_cli hop writes only the caller's access
+  // token) must surface the route's own 401, not "Session expired... No refresh token", which hid the real cause.
+  // A token-file principal re-mints its own file and a resident re-auths by signed challenge, so both still refresh.
+  const canRefresh = () => {
+    if (process.env.QUOX_TOKEN_FILE) return true;
+    const a = typeof config.getAuth === 'function' ? config.getAuth() : null;
+    return !!(a && (a.refresh_token || a.kind === 'resident'));
+  };
   let refreshFailedAt = 0;
   const correlationId = generateCorrelationId();
 
@@ -201,6 +233,7 @@ export function createClient(config, auth) {
       } else if (tokens?.access_token) {
         fetchHeaders['Authorization'] = `Bearer ${tokens.access_token}`;
       } else if (serviceKey && isLocalServiceTarget(url.href)) {
+        assertNoExplicitProfileFallback(config);
         // QUOXON-Z2H lane R: the implicit fallback is THIS box's key; never
         // offer it to another host (a remote profile with no login). A caller
         // that owns a remote key says so with QUOX_FORCE_SERVICE_KEY.
@@ -291,7 +324,7 @@ export function createClient(config, auth) {
         }
 
         const refreshCoolingDown = refreshFailedAt && (Date.now() - refreshFailedAt < REFRESH_RETRY_COOLDOWN_MS);
-        if (res.status === 401 && !noAuth && !actingAs && !refreshedThisRequest && !refreshCoolingDown && looksExpired) {
+        if (res.status === 401 && !noAuth && !actingAs && !refreshedThisRequest && !refreshCoolingDown && looksExpired && canRefresh()) {
           refreshedThisRequest = true;
           try {
             if (!refreshing) {
@@ -530,6 +563,7 @@ export function createClient(config, auth) {
     } else if (streamTokens?.access_token) {
       fetchHeaders['Authorization'] = `Bearer ${streamTokens.access_token}`;
     } else if (process.env.QUOX_SERVICE_KEY && isLocalServiceTarget(url.href)) {
+      assertNoExplicitProfileFallback(config);
       streamServiceKey = process.env.QUOX_SERVICE_KEY;
       fetchHeaders['X-Service-Key'] = streamServiceKey;
     }
@@ -575,7 +609,7 @@ export function createClient(config, auth) {
         try { looksExpired = (await res.clone().json())?.error === 'invalid_token'; } catch { /* non-JSON body */ }
       }
       const refreshCoolingDown = refreshFailedAt && (Date.now() - refreshFailedAt < REFRESH_RETRY_COOLDOWN_MS);
-      if (looksExpired && !refreshCoolingDown) {
+      if (looksExpired && !refreshCoolingDown && canRefresh()) {
         try {
           if (!refreshing) {
             refreshing = auth.refresh(config.getServiceUrl('auth')).finally(() => { refreshing = null; });

package/lib/core/commandRegistrars.js

@@ -11,7 +11,9 @@ export const COMMAND_REGISTRARS = [
   ['../commands/status.js', 'registerStatusCommand'],
   ['../commands/doctor.js', 'registerDoctorCommand'],
   ['../commands/server.js', 'registerServerCommands'],
+  ['../commands/connect.js', 'registerConnectCommand'],
   ['../commands/update.js', 'registerUpdateCommand'],
+  ['../commands/shortcut.js', 'registerShortcutCommand'],
   ['../commands/open.js', 'registerOpenCommand'],
   ['../commands/peek.js', 'registerPeekCommand'],
   ['../commands/aside.js', 'registerAsideCommand'],
@@ -26,6 +28,7 @@ export const COMMAND_REGISTRARS = [
   ['../commands/tool.js', 'registerToolCommands'],
   ['../commands/workflow.js', 'registerWorkflowCommands'],
   ['../commands/objective.js', 'registerObjectiveCommands'],
+  ['../commands/loop.js', 'registerLoopCommands'],
   ['../commands/assistant.js', 'registerAssistantCommands'],
   ['../commands/fleet.js', 'registerFleetCommands'],
   ['../commands/chat.js', 'registerChatCommands'],
@@ -41,10 +44,17 @@ export const COMMAND_REGISTRARS = [
   ['../commands/mail.js', 'registerMailCommands'],
   ['../commands/calendar.js', 'registerCalendarCommands'],
   ['../commands/notes.js', 'registerNotesCommands'],
+  ['../commands/blog.js', 'registerBlogCommands'],
   ['../commands/contacts.js', 'registerContactsCommands'],
+  // `quox inboxq watch` was consolidated into `quox mail watch` (the canonical
+  // InboxQ namespace: accounts/zones/sync/watches/proposals). The command file
+  // and its test are kept but unregistered; full deletion is a follow-up that
+  // needs a test-removal approval. Do not re-register without re-consolidating.
+  // ['../commands/inboxq.js', 'registerInboxqCommands'],
   ['../commands/licence.js', 'registerLicenceCommands'],
   ['../commands/run.js', 'registerRunCommands'],
   ['../commands/file.js', 'registerFileCommands'],
+  ['../commands/evidence.js', 'registerEvidenceCommands'],
   ['../commands/admin.js', 'registerAdminCommands'],
   ['../commands/aee.js', 'registerAeeCommands'],
   ['../commands/integration.js', 'registerIntegrationCommands'],
@@ -61,6 +71,7 @@ export const COMMAND_REGISTRARS = [
   ['../commands/vault.js', 'registerVaultCommands'],
   ['../commands/volt.js', 'registerVoltCommands'],
   ['../commands/governance.js', 'registerGovernanceCommands'],
+  ['../commands/compliance.js', 'registerComplianceCommands'],
   ['../commands/skills.js', 'registerSkillsCommands'],
   ['../commands/claude.js', 'registerClaudeCommands'],
   ['../commands/monitoring.js', 'registerMonitoringCommands'],
@@ -80,10 +91,13 @@ export const COMMAND_REGISTRARS = [
   ['../commands/capabilities.js', 'registerCapabilitiesCommands'],
   ['../commands/provider.js', 'registerProviderCommands'],
   ['../commands/tips.js', 'registerTipsCommands'],
+  ['../commands/ext.js', 'registerExtCommands'],
   ['../commands/quoxchat.js', 'registerQuoxchatCommands'],
   ['../commands/budget.js', 'registerBudgetCommands'],
   ['../commands/trace.js', 'registerTraceCommands'],
   ['../commands/mon.js', 'registerMonCommands'],
+  ['../commands/kuma.js', 'registerKumaCommands'],
+  ['../commands/wazuh.js', 'registerWazuhCommands'],
   ['../commands/quoxbox.js', 'registerQuoxboxCommands'],
   ['../commands/plan.js', 'registerPlanCommands'],
   ['../commands/engagement.js', 'registerEngagementCommands'],
@@ -91,6 +105,7 @@ export const COMMAND_REGISTRARS = [
   ['../commands/discord.js', 'registerDiscordCommands'],
   ['../commands/qlarity.js', 'registerQlarityCommands'],
   ['../commands/fetchAllowlist.js', 'registerFetchAllowlistCommands'],
+  ['../commands/research.js', 'registerResearchCommands'],
   ['../commands/reach.js', 'registerReachCommands'],
   ['../commands/inventory.js', 'registerInventoryCommands'],
   ['../commands/policy.js', 'registerPolicyCommands'],
@@ -115,6 +130,8 @@ export const COMMAND_REGISTRARS = [
   ['../commands/facebook.js', 'registerFacebookCommands'],
   ['../commands/instagram.js', 'registerInstagramCommands'],
   ['../commands/tiktok.js', 'registerTikTokCommands'],
+  ['../commands/youtube.js', 'registerYouTubeCommands'],
+  ['../commands/image.js', 'registerImageCommands'],
   ['../commands/offload.js', 'registerOffloadCommands'],
 ];
 

package/lib/core/config.js

@@ -9,8 +9,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, renameSy
 import { join } from 'node:path';
 import { homedir, networkInterfaces, hostname as osHostname } from 'node:os';
 
-function getConfigDir() { return join(homedir(), '.config', 'quox'); }
-function getConfigFile() { return join(getConfigDir(), 'config.json'); }
+export function getConfigDir() { return join(homedir(), '.config', 'quox'); }
+export function getConfigFile() { return join(getConfigDir(), 'config.json'); }
 
 // quox#713: cross-process lock around read-merge-write of config.json.
 const LOCK_STALE_MS = 10000;
@@ -220,7 +220,7 @@ export function deriveServiceUrl(baseUrl, port, service, opts = {}) {
 // only correct source for the flag at ctx-build time.
 // Commands whose remaining argv belongs to another program (`quox claude -p
 // "prompt"` is claude's --print, not quox's --profile).
-const WRAPPED_PROGRAM_COMMANDS = new Set(['claude', 'codex', 'gemini', 'wrap']);
+const WRAPPED_PROGRAM_COMMANDS = new Set(['claude', 'codex', 'wrap']);
 
 export function resolveProfileFlagFromArgv(argv) {
   for (let i = 0; i < argv.length; i++) {
@@ -346,6 +346,32 @@ export function loadConfig(profileOverride) {
       this.save();
     },
 
+    // ONBOARD-P1 (quox connect): a named profile that is not the active one, created or updated in place.
+    // Never moves the persisted default.
+    getProfile(name) { return this._data.profiles[name] || null; },
+    upsertProfile(name, patch = {}) {
+      let prof = this._data.profiles[name];
+      if (!prof) {
+        prof = this._data.profiles[name] = { url: patch.url || DEFAULT_CONFIG.profiles.local.url, auth: null };
+        this._removedProfiles?.delete(name);
+      }
+      Object.assign(prof, patch);
+      this.save();
+      return prof;
+    },
+    // Put a profile back exactly as it was before upsertProfile (snapshot from getProfile, null = did not exist).
+    restoreProfile(name, snapshot) {
+      if (snapshot == null) {
+        delete this._data.profiles[name];
+        this._removedProfiles.add(name);
+      } else {
+        const cur = this._data.profiles[name] || (this._data.profiles[name] = {});
+        for (const k of Object.keys(cur)) if (!(k in snapshot)) delete cur[k];
+        Object.assign(cur, JSON.parse(JSON.stringify(snapshot)));
+      }
+      this.save();
+    },
+
     removeProfile(name) {
       if (name === this._effectiveProfile) {
         throw new Error('Cannot remove the active profile. Switch first.');

package/lib/core/confirm.js

@@ -17,6 +17,51 @@
  * @param {string} message - confirmation prompt text
  * @returns {Promise<boolean>}
  */
+import { QuoxUserError } from './errors.js';
+
+/**
+ * Ask y/N, but treat a closed stdin (EOF) as "no answer" (resolves false)
+ * instead of leaving the prompt pending, which Node reports as a leaked
+ * "Detected unsettled top-level await" warning.
+ */
+async function askConfirm(message) {
+  const { default: inquirer } = await import('inquirer');
+  let onEnd;
+  const eof = new Promise((resolve) => {
+    onEnd = () => resolve(false);
+    process.stdin.once('end', onEnd);
+    process.stdin.once('close', onEnd);
+  });
+  try {
+    const ans = await Promise.race([
+      inquirer.prompt([{ type: 'confirm', name: 'confirm', message, default: false }]),
+      eof,
+    ]);
+    return ans === false ? false : ans.confirm;
+  } finally {
+    process.stdin.off('end', onEnd);
+    process.stdin.off('close', onEnd);
+  }
+}
+
+/**
+ * y/N for verbs that have their own non-interactive flag (e.g. `--i-accept`).
+ * With no terminal it does not open a prompt: it throws a one-line
+ * QuoxUserError naming the flag, exit code 2.
+ * @param {string} message
+ * @param {{ flag?: string, purpose?: string }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function confirmInteractive(message, { flag = '--yes', purpose = 'confirm' } = {}) {
+  if (!process.stdin.isTTY) {
+    throw new QuoxUserError(
+      `No terminal to answer y/N here. Read the output above, then re-run with ${flag} to ${purpose}.`,
+      { exitCode: 2, code: 'no_terminal' },
+    );
+  }
+  return askConfirm(message);
+}
+
 export async function confirmDestructive(program, options, message) {
   if (options.force === true || program.opts().yes === true) {
     return true;
@@ -26,12 +71,28 @@ export async function confirmDestructive(program, options, message) {
     throw new Error(`${message} — this needs confirmation; re-run with --force (or -y) in a non-interactive shell`);
   }
 
+  return askConfirm(message);
+}
+
+/**
+ * Ask for a typed line (e.g. the name of the object about to be deleted). EOF settles as null.
+ * Callers check the terminal first; this never opens a prompt without one.
+ * @param {string} message
+ * @returns {Promise<string|null>}
+ */
+export async function askTyped(message) {
   const { default: inquirer } = await import('inquirer');
-  const ans = await inquirer.prompt([{
-    type: 'confirm',
-    name: 'confirm',
-    message,
-    default: false,
-  }]);
-  return ans.confirm;
+  let onEnd;
+  const eof = new Promise((resolve) => {
+    onEnd = () => resolve(null);
+    process.stdin.once('end', onEnd);
+    process.stdin.once('close', onEnd);
+  });
+  try {
+    const ans = await Promise.race([inquirer.prompt([{ type: 'input', name: 'typed', message }]), eof]);
+    return ans === null ? null : String(ans.typed ?? '');
+  } finally {
+    process.stdin.off('end', onEnd);
+    process.stdin.off('close', onEnd);
+  }
 }

package/lib/core/crossOrgApprovals.js

@@ -0,0 +1,69 @@
+/**
+ * crossOrgApprovals: "N more waiting in <org>" for the orgs the user belongs to OTHER than the active one.
+ *
+ * Read-only and counts only. orgs.list is scoped to the caller, and each count is the user's own
+ * GET /api/orgs/:orgId/inbox/stats (server: active membership of THAT org, owner/admin see the whole org,
+ * members only their own items), read with the caller's OWN token: the server checks membership of the URL org
+ * in the database, not the token's org claim, so no per-org token is minted (a mint is an auth.org_switch audit
+ * event and ~2s each). No card content crosses orgs and nothing here can decide anything; deciding in another org
+ * is an explicit `--org <id>` on the verb. Counts (never tokens) are cached 60s in-process.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const listOf = (d) => (Array.isArray(d) ? d : (d?.organizations || d?.orgs || d?.data || []));
+
+const CACHE_MS = 60 * 1000;
+const cache = new Map(); // `${userScope}|${currentOrgId}` -> { at, res }
+export const _clearCrossOrgCache = () => cache.clear();
+
+/**
+ * @param {object} a
+ * @param {object} a.client                     the caller's client (lists memberships, reads each org's counts)
+ * @param {string|null} a.currentOrgId
+ * @param {()=>number} [a.now]
+ * @returns {Promise<{ waiting: {id:string,name:string,count:number}[], failed: number, checked: boolean }>}
+ *   failed counts orgs that could not be read: an unreadable org is NOT "nothing waiting".
+ */
+export async function otherOrgsWaiting({ client, currentOrgId, now = Date.now }) {
+  if (!client) return { waiting: [], failed: 0, checked: false };
+  const key = `${currentOrgId}`;
+  const hit = cache.get(key);
+  if (hit && now() - hit.at < CACHE_MS) return hit.res;
+  let orgs;
+  try { const ep = resolveEndpoint('orgs.list'); orgs = listOf(await client.get(ep.path, { service: ep.service })); }
+  catch { return { waiting: [], failed: 1, checked: true }; }
+  const others = orgs.filter((o) => o?.id && o.id !== currentOrgId);
+  const waiting = []; let failed = 0;
+  await Promise.all(others.map(async (o) => {
+    try {
+      const ep = resolveEndpoint('inbox.stats.list', { orgId: o.id });
+      const d = await client.get(ep.path, { service: ep.service, retries: 0 });
+      const count = Number(d?.awaiting_human ?? d?.pending_approvals ?? 0);
+      if (count > 0) waiting.push({ id: o.id, name: o.name || o.slug || o.id, count });
+    } catch { failed += 1; }
+  }));
+  waiting.sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+  const res = { waiting, failed, checked: true };
+  if (!failed) cache.set(key, { at: now(), res }); // a partial answer is never cached
+  return res;
+}
+
+/** One line per org (plain terminal): the exact command to run. */
+export function crossOrgLines(res, verb = 'list') {
+  const out = (res?.waiting || []).map((w) => `${w.count} more waiting in ${w.name}: quox approvals ${verb} --org ${w.id}`);
+  if (res?.failed) out.push(`Could not check ${res.failed} other org${res.failed === 1 ? '' : 's'} for waiting approvals; that does not mean nothing is waiting there.`);
+  return out;
+}
+
+/** TUI wording: switching is the TUI's own move. */
+export function crossOrgTuiLines(res) {
+  const out = (res?.waiting || []).map((w) => `${w.count} more waiting in ${w.name}: /org switch ${w.name}`);
+  if (res?.failed) out.push(`Could not check ${res.failed} other org${res.failed === 1 ? '' : 's'} for waiting approvals; that does not mean nothing is waiting there.`);
+  return out;
+}
+
+/** The client for a verb: the profile client for the session org, a minted same-user token client for another. */
+export async function clientForTarget({ client, clientForOrg, sessionOrgId, orgId }) {
+  if (!orgId || orgId === sessionOrgId || typeof clientForOrg !== 'function') return client;
+  return clientForOrg(orgId);
+}

package/lib/core/errors.js

@@ -214,6 +214,14 @@ export function explainError(err, ctx = null) {
   const raw = RAW_HEADLINE.test(String(err.message || '').split('\n')[0]) || err.reasonFromError === true;
   const reason = serverReason(err);
 
+  // SKILLRIGHTS #478: require-acceptance refusal is not a generic 409 conflict.
+  if (status === 409 && (code === 'acceptance_required' || body.error === 'acceptance_required')) {
+    const pack = typeof body.packId === 'string' && body.packId ? body.packId : 'quox-core-dev-pack';
+    return {
+      headline: sentence(reason || `This org's distribution policy is require-acceptance, and nobody has accepted the current terms for pack '${pack}'`),
+      next: `accept the terms as yourself: quox dev skills accept ${pack} (add --i-accept with no terminal), then re-run the sync.`,
+    };
+  }
   // #8 service-key fallback: the real problem is "no stored session", say it once.
   if (err.serviceKeyFallback && (status === 401 || status === 403)) {
     return {
@@ -268,6 +276,28 @@ export function explainError(err, ctx = null) {
   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.' };
   }
+  // DS-010 / #1335: a step-up refusal is about WHO is at the keyboard, not about org or role. The old fall-through
+  // sent people to "switch org / ask an admin", which cannot help: only the approver's own PIN does.
+  if (status === 403 && /step_up_required/.test(all)) {
+    if (body.reason === 'non_human') {
+      return { headline: 'This approval needs a person, and this login is an agent or service identity.', next: 'approve it from a person\'s own login (the dashboard, or `quox` in their terminal).' };
+    }
+    return {
+      headline: 'This approval needs your step-up PIN.',
+      next: body.pin_set === false
+        ? 'set a PIN in the dashboard (Settings > Account > Approval PIN), then run this again in a terminal.'
+        : 'run this command in an interactive terminal; it will ask for the PIN with hidden input. The PIN cannot be passed as a flag or environment variable.',
+    };
+  }
+  // the auth service's requireInstanceAdmin refusal (code instance_admin_required): instance admin is instance-wide,
+  // so neither switching org nor asking an org admin can help
+  if (status === 403 && /instance_admin_required|instance administrator access required/i.test(all)) {
+    return { headline: sentence(reason || 'Instance administrator access required'), next: 'this needs an instance administrator account. Run it with a profile that is one (quox -p <profile> ...), or ask your instance admin.' };
+  }
+  // an instance-admin gate: switching org cannot help, only an instance admin can
+  if (status === 403 && /instance admin required/i.test(all)) {
+    return { headline: 'This needs an instance admin, and this login is not one.', next: 'ask an instance admin of this Quox server to run it, or to make your login an instance admin.' };
+  }
   // #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.' };
@@ -332,6 +362,7 @@ function fallbackExplain(err, ctx) {
 }
 
 // CLI-ERRORS: an instruction sentence (the step the user takes) vs the rest (what happened).
+const TLS_HINT_CODES = ['DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'ERR_TLS_CERT_ALTNAME_INVALID', 'CERT_HAS_EXPIRED'];
 const INSTRUCTION = /^(run|check|use|retry|try|pass|fix|set|pick|switch|ask|log ?in|re-?run|please)\b/i;
 
 function splitInstruction(text) {
@@ -351,6 +382,10 @@ function splitInstruction(text) {
  * 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.
  */
+function connectUrl(u) {
+  try { return new URL(u).origin; } catch { return '<url>'; }
+}
+
 export function explainLocal(err) {
   if (!err || err instanceof QuoxApiError || err instanceof QuoxUserError) return null;
   const message = String(err.message || '');
@@ -362,7 +397,7 @@ export function explainLocal(err) {
     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 };
+        next: `trust this server for one profile with quox connect ${connectUrl(url)} --profile <name> (it shows the certificate SHA256 and asks y/N; with no terminal add --fingerprint <sha256>); 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://.`,
@@ -389,6 +424,20 @@ export function explainLocal(err) {
     return sp;
   }
   if (err instanceof QuoxValidationError) return splitInstruction(message);
+  // H4: a bare fetch (login, MFA, refresh) that died on a certificate this machine does not trust. undici reports it
+  // as "fetch failed"; name the problem and the exact next command. Never auto-trust, never TLS-off.
+  const tlsCode = TLS_HINT_CODES.find((c) => c === (err.cause?.cause?.code || err.cause?.code || err.code));
+  if (tlsCode && err.quoxUrl) {
+    const profile = err.quoxProfile ? ` --profile ${err.quoxProfile}` : '';
+    const expired = tlsCode === 'CERT_HAS_EXPIRED' || tlsCode === 'ERR_TLS_CERT_ALTNAME_INVALID';
+    return { headline: expired
+        ? `The server at ${err.quoxUrl} presents a certificate that ${tlsCode === 'CERT_HAS_EXPIRED' ? 'has expired' : 'does not name the address you used'} (${tlsCode}).`
+        : `The server at ${err.quoxUrl} uses a certificate this machine does not trust yet.`,
+      next: expired
+        ? 'the server needs a certificate that is current and names this address; trusting it would not help. Never disable TLS verification.'
+        : `run quox connect ${err.quoxUrl}${profile} (it shows the SHA256 fingerprint and asks y/N); with no terminal use quox connect ${err.quoxUrl}${profile} --trust-cert, or --fingerprint <sha256> to pin it. Never disable TLS verification.`,
+      more: [`TLS error: ${tlsCode}`] };
+  }
   const first = message.split('\n')[0];
   return { headline: sentence(first || 'Something went wrong'), next: null, more: message.split('\n').slice(1), stack: true };
 }
@@ -404,6 +453,7 @@ function renderContract(err, ex, ctx) {
   }
   if (err.detail) console.error(chalk.dim(`  Detail: ${renderDetail(err.detail)}`));
   if (isVerbose(ctx)) {
+    if (err.debug) console.error(chalk.dim(`  Debug: ${renderDetail(err.debug)}`));
     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}`));
@@ -420,6 +470,7 @@ export function handleError(err, outputFormat = 'table', ctx = null) {
     };
     if (err.status) obj.status = err.status;
     if (err.detail) obj.detail = err.detail;
+    if (err.debug) obj.debug = err.debug; // plumbing kept out of the headline, still there for scripts
     // 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;

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

@@ -87,7 +87,7 @@ 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
+ * 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.
  */