quoxcli 0.4.0 → 0.5.0

package/lib/commands/x.js

@@ -389,6 +389,56 @@ export function registerXCommands(program, ctx) {
       }
     });
 
+  // ── x whoami / accounts ───────────────────────────────────────────────────
+  // quox#867: a focused read of the connected social account (platform, handle,
+  // connection status), without the posting-budget half of `x status`. Backs the
+  // chat read-parity lane (an agent/CLI asking "which X account am I connected as?").
+  x
+    .command('whoami')
+    .alias('accounts')
+    .description('Show the connected X account: platform, handle and connection status')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('v1.tools.execute');
+
+      let cred = null;
+      let credError = null;
+      try {
+        const credData = await client.post(ep.path, {
+          service: ep.service,
+          body: { tool_name: 'twitter_verify_credentials', input: {}, org_id: orgId },
+        });
+        if (credData && credData.success === false) {
+          credError = credData.error || 'unknown error';
+        } else {
+          cred = credData && credData.result ? credData.result : credData;
+        }
+      } catch (err) {
+        credError = err.message;
+      }
+
+      const account = {
+        platform: 'x',
+        connected: !credError && !!cred,
+        handle: cred && cred.username ? `@${cred.username}` : null,
+        name: (cred && cred.name) || null,
+        id: (cred && cred.id) || null,
+        error: credError,
+      };
+
+      if (program.opts().output === 'json') {
+        formatDetail({ accounts: [account] }, { format: 'json' });
+        return;
+      }
+
+      if (credError) {
+        printWarning(`X: not connected (twitter_verify_credentials via POST ${ep.path}): ${credError}`);
+      } else {
+        printSuccess(`X: connected as ${account.handle}${account.name ? ` (${account.name})` : ''}`);
+      }
+    });
+
   // ── x media-root ────────────────────────────────────────────────────────
 
   x

package/lib/core/announce.js

@@ -0,0 +1,86 @@
+/**
+ * announce: the ONE renderer CLI verbs use to say "Quox did something".
+ *
+ * Owner order 2026-10-29: if anything Quox happens, it announces. A verb that
+ * writes or governs prints exactly one QuoxGlyph line:
+ *   <icon> NAME │ <verb object> │ <result>[ · <duration>] <status>
+ * built on core/quoxglyph.js (the canonical grammar), never hand-typed.
+ *
+ * Output rules:
+ *  - stderr, not stdout: scripted stdout (tables, ids, --json) is byte-for-byte unchanged;
+ *  - silent under --json / --quiet;
+ *  - brand-gradient name only when stderr is a TTY, plain when piped or redirected.
+ */
+
+import { line } from './quoxglyph.js';
+import { getOutputFormat } from './output.js';
+
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;]*m/g;
+
+function errMessage(err) {
+  if (!err) return 'failed';
+  const body = err.body && (err.body.message || err.body.error);
+  return String(body || err.message || err).replace(/\s+/g, ' ').trim();
+}
+
+/** Render without printing. opts: {result, ms, status} (status defaults to ok). */
+export function renderAnnounce(surface, verb, opts = {}) {
+  let s = line(surface, verb, { status: 'ok', ...opts });
+  if (!(process.stderr && process.stderr.isTTY)) s = s.replace(ANSI, '');
+  return tidy(s);
+}
+
+// No result: the grammar's third field is just the status glyph (avoid a double space after the separator).
+const tidy = (s) => s.replace(/│ {2}(?=\S)/, '│ ');
+
+export function announceMuted() { return muted(); }
+function muted() {
+  const f = getOutputFormat();
+  return f === 'json' || f === 'quiet';
+}
+
+/** Print one announce line to stderr. Returns the rendered line (or null when muted). */
+export function announce(surface, verb, opts = {}) {
+  if (muted()) return null;
+  const s = renderAnnounce(surface, verb, opts);
+  process.stderr.write(`${s}\n`);
+  return s;
+}
+
+/** The failure twin: one line, status fail, reason as the result. */
+export function announceFailure(surface, verb, err) {
+  if (err && typeof err === 'object') { try { Object.defineProperty(err, 'quoxAnnounced', { value: true, configurable: true }); } catch { /* frozen */ } }
+  return announce(surface, verb, { result: errMessage(err), status: 'fail' });
+}
+
+/**
+ * Command-level wrapper: a verb whose SUCCESS announces itself inline gets its FAILURE exit announced here, once, so
+ * every exit (return or throw) of the verb prints exactly one QuoxGlyph line. `verb` is a string, or a function of the
+ * action's arguments. An error already announced (by an inner announceFailure) is not announced twice.
+ */
+export function announceOnFail(surface, verb, fn) {
+  return async (...args) => {
+    try { return await fn(...args); } catch (err) {
+      if (err && typeof err === 'object' && !err.quoxAnnounced) {
+        announceFailure(surface, typeof verb === 'function' ? verb(...args) : verb, err);
+      } else if (!err || typeof err !== 'object') announceFailure(surface, typeof verb === 'function' ? verb(...args) : verb, err);
+      throw err;
+    }
+  };
+}
+
+// quox_event statuses arrive as QuoxGlyph status names (ok fail busy warn block).
+const EVENT_STATUS = new Set(['ok', 'fail', 'busy', 'warn', 'block']);
+
+/**
+ * The plain (no ANSI) QuoxGlyph line for a collector `quox_event` frame, so the TUI transcript
+ * and `--print` render a turn's Quox effects with the SAME renderer the verbs use.
+ * Returns null for a frame with nothing to say.
+ */
+export function eventLine(ev) {
+  if (!ev || typeof ev !== 'object' || !ev.verb) return null;
+  const surface = String(ev.surface || 'quox').toLowerCase().replace(/[^a-z0-9_-]/g, '') || 'quox';
+  const status = EVENT_STATUS.has(ev.status) ? ev.status : 'ok';
+  return tidy(line(surface, String(ev.verb), { status, ...(ev.result ? { result: String(ev.result) } : {}) }).replace(ANSI, ''));
+}

package/lib/core/auth.js

@@ -7,6 +7,7 @@
 
 import { readFileSync, statSync, openSync, closeSync, unlinkSync } from 'node:fs';
 import { QuoxAuthError, QuoxApiError, QuoxTransientAuthError } from './errors.js';
+import { rateLimitHint, retryAfterMsFrom } from './loginGuard.js';
 import { loadResidentProfile, residentLogin, resolveResidentBaseUrl } from './residentAuth.js';
 
 // A resident agent has no refresh token: its expired-access-token seam is
@@ -159,6 +160,17 @@ async function acquireRefreshLock(file, { staleMs = 20000, waitMs = 20000 } = {}
   }
 }
 
+// H4: tag a failed bare fetch with the server and profile so the central error mapping can name the exact
+// `quox connect` command when the cause is a certificate this machine does not trust.
+async function fetchTagged(config, baseUrl, url, opts) {
+  try { return await fetch(url, opts); } catch (e) {
+    if (e && typeof e === 'object') {
+      try { e.quoxUrl = baseUrl; e.quoxProfile = config?.getActiveProfileName?.(); } catch { /* tagging is best effort */ }
+    }
+    throw e;
+  }
+}
+
 export function createAuth(config) {
   return {
     async login(baseUrl, email, password, orgId) {
@@ -170,7 +182,7 @@ export function createAuth(config) {
       const body = { email, password, client: 'cli' };
       if (orgId) body.org_id = orgId;
 
-      const res = await fetch(url, {
+      const res = await fetchTagged(config, baseUrl, url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(body),
@@ -179,6 +191,12 @@ export function createAuth(config) {
       const data = await res.json();
 
       if (!res.ok) {
+        if (res.status === 429) {
+          const retryAfterMs = retryAfterMsFrom(res, data);
+          const err = new QuoxApiError(429, data.error, rateLimitHint({ retryAfterMs }));
+          err.retryAfterMs = retryAfterMs;
+          throw err;
+        }
         throw new QuoxApiError(res.status, data.error, data.message || 'Login failed');
       }
 
@@ -204,7 +222,7 @@ export function createAuth(config) {
 
     async verifyMfa(baseUrl, token, code) {
       const url = `${baseUrl}/api/mfa/verify`;
-      const res = await fetch(url, {
+      const res = await fetchTagged(config, baseUrl, url, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',

package/lib/core/callMe.js

@@ -0,0 +1,118 @@
+/**
+ * callMe: the shared core behind `quox approvals call-me` and the TUI
+ * /callmeforapprovals. It reads and flips the ApprovalsQ call-me policy (the
+ * switch for the watcher that phones a human when a high-risk approval sits
+ * unanswered). The server route is human-org-admin only; agent identities and
+ * service keys are refused there, and every write is audited (AEE).
+ *
+ * It NEVER approves or denies anything. on/off flip `enabled` only (plus the
+ * optional --after / --quiet knobs); every other stored field is preserved.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxUserError } from './errors.js';
+
+const HHMM = /^(\d{1,2}):(\d{2})$/;
+const ok = (s) => { const m = HHMM.exec(s); return Boolean(m && Number(m[1]) <= 23 && Number(m[2]) <= 59); };
+
+/** "22:00-08:00" -> { start, end }, or throws a QuoxUserError naming the fix. */
+export function parseQuiet(text) {
+  const m = /^(\d{1,2}:\d{2})\s*-\s*(\d{1,2}:\d{2})$/.exec(String(text || '').trim());
+  if (!m || !ok(m[1]) || !ok(m[2])) {
+    throw new QuoxUserError(`--quiet must look like 22:00-08:00 (got "${text}")`, { code: 'bad_quiet_hours' });
+  }
+  return { start: m[1], end: m[2] };
+}
+
+/** --after <minutes>: integer 1-1440, or throws. */
+export function parseAfter(text) {
+  const n = Number(text);
+  if (!Number.isInteger(n) || n < 1 || n > 1440) {
+    throw new QuoxUserError(`--after must be whole minutes between 1 and 1440 (got "${text}")`, { code: 'bad_after' });
+  }
+  return n;
+}
+
+/** Build the PUT body for an action (on|off) plus options { after, quiet }. */
+export function buildChange(action, { after, quiet } = {}) {
+  if (action !== 'on' && action !== 'off') {
+    throw new QuoxUserError(`Unknown action "${action}". Use status, on or off.`, { code: 'bad_action' });
+  }
+  const body = { enabled: action === 'on' };
+  if (after !== undefined && after !== null && after !== '') body.age_threshold_minutes = parseAfter(after);
+  if (quiet) body.quiet_hours = parseQuiet(quiet);
+  return body;
+}
+
+/** One honest line about the watcher. Unknown is said as unknown, never guessed as alive. */
+export function watcherLine(w) {
+  if (!w || typeof w !== 'object') return 'watcher: unknown (the server did not report it)';
+  if (w.running === false) {
+    return w.reason === 'env_flag_off'
+      ? 'watcher: NOT RUNNING (QUOX_APPROVALSQ_WATCHER is off on the collector, so no call will be placed)'
+      : 'watcher: NOT RUNNING (it did not start, so no call will be placed)';
+  }
+  if (w.running === true) {
+    if (!w.last_tick_at) return 'watcher: started, no check completed yet';
+    const tail = w.stale ? ' STALE, it has stopped checking' : (w.last_tick_ok === false ? ' (last check had errors)' : '');
+    return `watcher: alive, last check ${w.last_tick_at}${tail}`;
+  }
+  return 'watcher: unknown (the server did not report it)';
+}
+
+/** Human-readable status lines from a { policy, watcher } response. */
+export function statusLines(data) {
+  const p = (data && data.policy) || {};
+  const q = p.quiet_hours || {};
+  const lines = [
+    `call me for approvals: ${p.enabled ? 'ON' : 'OFF'}`,
+    `rings after: ${p.age_threshold_minutes} min unanswered`,
+    `quiet hours: ${q.start}-${q.end} ${q.timezone || ''}`.trimEnd(),
+    `min tier: ${p.min_tier}`,
+    watcherLine(data && data.watcher),
+  ];
+  if (p.enabled && p.destination_configured === false) lines.push('calls go to: the owner mobile (QuoxVoice default; no destination number set on this policy)');
+  return lines;
+}
+
+/** Plain-words refusal for a 401/403 from the server. */
+function refusal(e) {
+  if (e && e.status === 402) {
+    return new QuoxUserError('QuoxVoice is not licensed for this org, so call-me for approvals is unavailable.', { code: 'license_required', status: 402 });
+  }
+  if (e && (e.status === 403 || e.status === 401)) {
+    return new QuoxUserError('Only a signed-in human org admin can change or read the call-me policy. Agent identities and service keys are refused.', { code: 'admin_only', status: e.status });
+  }
+  return e;
+}
+
+export async function getCallMe(client) {
+  const ep = resolveEndpoint('v1.approvals.call-me.get');
+  try { return await client.get(ep.path, { service: ep.service, retries: 0 }); } catch (e) { throw refusal(e); }
+}
+
+export async function setCallMe(client, change) {
+  const ep = resolveEndpoint('v1.approvals.call-me.put');
+  try { return await client.put(ep.path, { service: ep.service, body: change, retries: 0 }); } catch (e) { throw refusal(e); }
+}
+
+/** Parse TUI args: "[on|off|status] [--after N] [--quiet HH:MM-HH:MM]" -> { action, after, quiet }. */
+export function parseSlashArgs(text) {
+  const toks = String(text || '').trim().split(/\s+/).filter(Boolean);
+  const out = { action: 'status' };
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    if (t === 'on' || t === 'off' || t === 'status') out.action = t;
+    else if (t === '--after') out.after = toks[++i];
+    else if (t === '--quiet') out.quiet = toks[++i];
+    else throw new QuoxUserError(`Unknown argument "${t}". Usage: /callmeforapprovals [on|off|status] [--after <minutes>] [--quiet HH:MM-HH:MM]`, { code: 'bad_args' });
+  }
+  return out;
+}
+
+/** Run an action end to end -> { data, changed }. status reads; on/off write. */
+export async function runCallMe(client, { action = 'status', after, quiet } = {}) {
+  if (action === 'status') return { data: await getCallMe(client), changed: false };
+  const body = buildChange(action, { after, quiet });
+  return { data: await setCallMe(client, body), changed: true };
+}

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) {
@@ -209,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.
@@ -538,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;
     }

package/lib/core/commandRegistrars.js

@@ -11,6 +11,7 @@ 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'],
@@ -45,6 +46,11 @@ export const COMMAND_REGISTRARS = [
   ['../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'],
@@ -65,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'],
@@ -90,6 +97,7 @@ export const COMMAND_REGISTRARS = [
   ['../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'],

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;
@@ -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);
+}