quoxcli 0.2.0 → 0.4.0

package/lib/commands/presence.js

@@ -0,0 +1,89 @@
+/**
+ * `quox presence [who]` / `quox presence set present|away|sleeping`: PRESENCE (owner 2026-10-16).
+ * A human says they are not at their terminal (/afk, /sleep in quox do the same). Sessions and agents
+ * read it so they stop waiting on approvals, which still queue normally: nothing is ever auto-approved.
+ * Collector routes GET/PUT /api/v1/presence; the org is the caller's, only a human login sets its own.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+const STATES = ['present', 'away', 'sleeping'];
+
+function stamp(iso) {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? String(iso || '') : `${d.toISOString().slice(0, 10)} ${d.toISOString().slice(11, 16)} UTC`;
+}
+
+/** One plain line for a presence record. */
+export function presenceText(p) {
+  if (!p || !p.away) return `${p?.who || 'they'}: present`;
+  const note = p.note ? `, "${p.note}"` : '';
+  return `${p.who}: ${p.auto ? 'away (idle)' : p.state} since ${stamp(p.since)}${note} (approvals will queue)`;
+}
+
+/** The fields an approval request reports, from GET /api/v1/presence. */
+export function approvalPresenceFields(list) {
+  const away = (list && Array.isArray(list.presence) ? list.presence : []).filter((p) => p && p.away);
+  if (!away.length) return { owner_away: false };
+  const p = away.find((x) => x.who === 'owner') || away[0];
+  return { owner_away: true, owner_away_since: p.since, owner_presence: p.state, owner_away_notice: list.notice || presenceText(p) };
+}
+
+/** Read the org's presence; null on any failure (a presence read never fails the caller). */
+export async function readPresence(client, orgId) {
+  try {
+    const ep = resolveEndpoint('presence.list');
+    return await client.get(ep.path, { service: ep.service, query: orgId ? { org_id: orgId } : undefined, retries: 0, timeout: 5000 });
+  } catch { return null; }
+}
+
+export function registerPresenceCommands(program, { client, auth }) {
+  const pr = program
+    .command('presence')
+    .description('Is a person at their terminal? With no name: everyone with presence on record. When someone is away, approvals queue; work on something else')
+    .argument('[who]', 'user id, email, email name, "owner" or "me"')
+    .action(async (who) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const json = program.opts().output === 'json';
+      if (who) {
+        const ep = resolveEndpoint('presence.get', { who });
+        const d = await client.get(ep.path, { service: ep.service, query: { org_id: orgId } });
+        if (json) { console.log(JSON.stringify(d, null, 2)); return; }
+        console.log(presenceText(d.presence));
+        return;
+      }
+      const ep = resolveEndpoint('presence.list');
+      const d = await client.get(ep.path, { service: ep.service, query: { org_id: orgId } });
+      if (json) { console.log(JSON.stringify(d, null, 2)); return; }
+      const list = Array.isArray(d.presence) ? d.presence : [];
+      if (!list.some((p) => p.away)) console.log('Everyone is present: nobody has marked themselves away.');
+      for (const p of list) console.log(presenceText(p));
+    });
+
+  pr
+    .command('set')
+    .description('Say where you are: present, away or sleeping (a human login only). Same as /afk, /sleep, /back in quox')
+    .argument('<state>', 'present | away | sleeping')
+    .option('--note <text>', 'a short note sessions will see ("school run")')
+    .option('--slots <list>', 'your own window slots, comma separated (hitl and triage-q always count)')
+    .option('--auto-away <minutes>', 'read as away after this many idle minutes; "off" to disable (default off)')
+    .action(async (state, options) => {
+      if (!STATES.includes(state)) throw new Error('state must be present, away or sleeping');
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { state };
+      if (options.note !== undefined) body.note = options.note;
+      if (options.slots) body.slots = String(options.slots).split(',').map((s) => s.trim()).filter(Boolean);
+      if (options.autoAway !== undefined) {
+        const off = /^(off|0|no)$/i.test(String(options.autoAway));
+        const n = Number(options.autoAway);
+        if (!off && (!Number.isInteger(n) || n < 1 || n > 1440)) throw new Error('--auto-away is minutes (1 to 1440) or off');
+        body.auto_away_minutes = off ? 0 : n;
+      }
+      const ep = resolveEndpoint('presence.set');
+      const d = await client.put(ep.path, { service: ep.service, body, query: { org_id: orgId } });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(d, null, 2)); return; }
+      console.log(presenceText(d.presence));
+    });
+}

package/lib/commands/provider.js

@@ -0,0 +1,217 @@
+/**
+ * quox provider list | connect <kind> | test [<kind>]  (quox#1281, CLI verb first)
+ *
+ * The SAME backend calls as the TUI's /connect: cli/lib/quoxon/connect.js flows (connectFlow, connectOllamaFlow,
+ * connectCompatFlow, connectionLines) over cli/lib/quoxon/api.js createApi (the auth vault create/update with
+ * confirm_private_origin, the server-side key test and Ollama / OpenAI-compatible probes, capabilities, consent).
+ * Nothing here talks to the backend on its own, so the TUI and the CLI cannot drift. The vault routes audit every
+ * write server side (integration.private_origin for a private address), org-scoped by the caller's session.
+ *
+ * Secrets: a key is never an argv flag or argument. It arrives on stdin (--key-from-stdin) or from a hidden prompt,
+ * is sent once to the server test and the vault, and is never printed (connectFlow scrubs it from any message).
+ */
+import { formatDetail, printInfo } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { createApi, isInteractiveHuman } from '../quoxon/api.js';
+import { PROVIDERS, providerFor, looksLikeKey, connectionLines, connectFlow, connectOllamaFlow, connectCompatFlow } from '../quoxon/connect.js';
+import { needsConsent, consentCovers, connectConsentNote, providerLabel } from '../quoxon/consent.js';
+import { readStdin } from '../quoxon/print.js';
+import { INSTALL_TOOLS, toolFor, planLine, offerQuestion, runInstall, isAgentCaller } from '../quoxon/installCli.js';
+import { YN_OPTIONS, waitForDecision } from '../core/askDecision.js';
+import { detectCallerSource } from '../core/callerSource.js';
+
+const KINDS = Object.keys(PROVIDERS);
+const SAFE_ROW = ['id', 'integration_type', 'label', 'is_default', 'test_status', 'last_tested_at', 'created_at'];
+const CONTAINER_NOTE = 'Quox runs in containers: 127.0.0.1 or localhost means the Quox container, not your machine. Use the host\'s LAN IP, e.g. http://192.0.2.10:11434';
+
+function defaultIO() {
+  return {
+    isTTY: () => isInteractiveHuman(),
+    isAgent: () => isAgentCaller(process.env),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    readStdin: () => readStdin(),
+    promptSecret: async (message) => {
+      const { default: inquirer } = await import('inquirer');
+      const a = await inquirer.prompt([{ type: 'password', name: 'v', message, mask: '*' }]);
+      return a.v;
+    },
+    confirm: async (message) => {
+      const { default: inquirer } = await import('inquirer');
+      const a = await inquirer.prompt([{ type: 'confirm', name: 'v', message, default: false }]);
+      return Boolean(a.v);
+    },
+  };
+}
+
+const say = (lines) => { for (const [t] of lines || []) printInfo(t); };
+
+export function registerProviderCommands(program, ctx) {
+  const { client, auth, config } = ctx;
+  const io = ctx.providerIO || defaultIO();
+  const api = () => (ctx.makeApi ? ctx.makeApi() : createApi({ client, config, auth }));
+
+  const provider = program
+    .command('provider')
+    .description('Connect the AI providers your org uses (the same as /connect in the Quox terminal)');
+
+  // ── provider list ──────────────────────────────────────────────────────────
+  provider
+    .command('list')
+    .description('Show which AI providers this org can use, and how each is connected')
+    .action(async () => {
+      auth.requireAuth();
+      const a = api();
+      const [vault, caps] = await Promise.all([a.connections(), a.capabilities ? a.capabilities() : null]);
+      if (program.opts().output === 'json') {
+        const rows = vault?.ok ? vault.rows.map((r) => Object.fromEntries(SAFE_ROW.filter((k) => r[k] !== undefined).map((k) => [k, r[k]]))) : null;
+        formatDetail({ connections: rows, ...(vault?.ok ? {} : { error: vault?.error || 'vault not readable' }), capabilities: caps?.ok ? caps.capabilities : null }, { format: 'json' });
+        return;
+      }
+      say(connectionLines(vault, caps));
+    });
+
+  // ── provider connect ───────────────────────────────────────────────────────
+  const readKey = async (p, opts) => {
+    if (opts.keyFromStdin) return String(await io.readStdin() || '').replace(/\r?\n$/, '').trim();
+    if (io.isTTY()) return String(await io.promptSecret(`${p.name} key (hidden, never shown or stored on this machine):`) || '').trim();
+    throw new Error(`No key given. Pipe it in with --key-from-stdin (for example: quox provider connect ${p.id} --key-from-stdin < keyfile), or run this in a terminal to be asked. A key is never taken as an argument.`);
+  };
+  const consentAfter = async (type) => {
+    const a = api();
+    if (!needsConsent(type) || !a.consentStatus) return;
+    let rec = null; try { rec = await a.consentStatus(); } catch { rec = null; }
+    if (consentCovers(rec, type)) return;
+    // --yes never grants consent: it is this person's own OK to send their conversations to a third party
+    if (!io.isTTY() || !a.grantConsent) { printInfo(connectConsentNote(type)); return; }
+    const yes = await io.confirm(`Allow Quox to send your conversations to ${providerLabel(type)}? Your messages and tool results go to ${providerLabel(type)}, a third party, when it answers. Nothing is sent until you say yes.`);
+    if (!yes) { printInfo(`Left off: nothing goes to ${providerLabel(type)} until you say so. ${connectConsentNote(type)}`); return; }
+    try { await a.grantConsent(type); printInfo(`✔ Your OK is recorded: ${providerLabel(type)} can now answer. Withdraw it any time: quox consent list.`); }
+    catch (e) { printInfo(`Quox could not record your OK (${e?.message || e}). Try: quox consent grant ${type}`); }
+  };
+
+  provider
+    .command('connect')
+    .description('Connect an AI provider for this org: a keyed provider (openai, anthropic, groq...) takes its key on stdin or a hidden prompt; a self-hosted one (ollama, lmstudio, vllm, custom) takes a URL')
+    .argument('<kind>', `provider: ${KINDS.join(', ')}`)
+    .argument('[url]', 'server URL for ollama / lmstudio / vllm / custom (same as --url)')
+    .option('--url <url>', `server URL for a self-hosted provider. ${CONTAINER_NOTE}`)
+    .option('--model <model>', 'default model to use on that server')
+    .option('--key-from-stdin', 'read the API key from stdin (never pass a key as an argument)')
+    .option('--yes', 'confirm connecting to an address on your private network (the server still checks it and audits the decision)')
+    .addHelpText('after', `\n${CONTAINER_NOTE}\nKeys: --key-from-stdin, or run in a terminal to be asked with a hidden prompt.`)
+    .action(async (kind, urlArg, opts) => {
+      auth.requireAuth();
+      const p = providerFor(kind);
+      if (!p) throw new Error(`No provider called "${kind}". Use one of: ${KINDS.join(', ')}`);
+      if (urlArg && (looksLikeKey(urlArg) || (p.card && !p.url))) throw new Error('never pass a key as an argument (it would sit in your shell history and process list). Use --key-from-stdin, or run in a terminal to be asked.');
+      const a = api();
+      const url = opts.url || urlArg || '';
+      let r;
+      if (p.id === 'ollama') {
+        r = await connectOllamaFlow(a, [url, opts.model].filter(Boolean).join(' '));
+        say(r.lines);
+        if (r.privateAsk) {
+          const q = `Connect to ${r.privateAsk.host}? It's on your private network. Quox saves only ${r.privateAsk.origin}, after the server checks it answers as Ollama.`;
+          let yes = Boolean(opts.yes);
+          if (!yes && io.isTTY()) yes = await io.confirm(q);
+          if (!yes && !io.isTTY()) throw new Error(`${r.privateAsk.host} is on your private network. Run again with --yes to confirm this one address. Nothing was saved.`);
+          if (!yes) throw new Error(`Left blocked: ${r.privateAsk.host} was not connected. Nothing was saved.`);
+          r = await r.privateAsk.retry();
+          say(r.lines);
+        }
+      } else if (p.url) {
+        r = await connectCompatFlow(a, p.id, [url, opts.model].filter(Boolean).join(' '));
+        say(r.lines);
+        if (r.needsKey) { r = await connectFlow(a, 'custom', await readKey(PROVIDERS.custom, opts), r.extra); printInfo(r.text); if (r.disclosure) printInfo(r.disclosure); }
+      } else {
+        r = await connectFlow(a, p.id, await readKey(p, opts));
+        printInfo(r.text);
+        if (r.ok && r.disclosure) printInfo(r.disclosure);
+      }
+      if (r?.lanOffer) printInfo('  From the CLI an instance admin allows private targets with: quox server config lan-targets on   then run this again.');
+      if (!r?.ok) throw new Error(r?.text || `${p.name} was not connected. Nothing was saved.`);
+      await consentAfter(p.type);
+    });
+
+  // ── provider install (LAZY-AI-CLI) ────────────────────────────────────────
+  // The user's own server downloads the vendor's npm package (never a binary Quox ships). A person decides: y/N on
+  // a terminal, a high-risk approval card when an agent runs it (an agent's --yes is not a person's yes).
+  provider
+    .command('install')
+    .description('Install Claude Code or Codex on this Quox server from npm (the vendor\'s own package), so Claude sign-in and Codex work. Instance admin only')
+    .argument('<tool>', `what to install: ${Object.keys(INSTALL_TOOLS).join(', ')}`)
+    .option('--yes', 'install without the y/N question (a script; an agent still gets an approval card)')
+    .action(async (toolArg, opts) => {
+      auth.requireAuth();
+      const tool = toolFor(toolArg);
+      if (!tool) throw new Error(`No installable CLI called "${toolArg}". Use one of: ${Object.keys(INSTALL_TOOLS).join(', ')}`);
+      const t = INSTALL_TOOLS[tool];
+      const a = api();
+      const st = await a.providerCliStatus();
+      const cur = st?.ok ? st.tools.find((x) => x.id === tool) : null;
+      if (cur?.installed) { printInfo(`✔ ${t.name} is already installed on this server (${cur.version || 'version unknown'}${cur.location ? `, ${cur.location}` : ''}). Nothing to do.`); return; }
+      const plan = await a.providerCliPlan(tool);
+      if (!plan?.ok) {
+        if (plan?.status === 404 || plan?.status === 405) throw new Error(`This Quox server is too old to install ${t.name} for you. Update it first: quox server update`);
+        throw new Error(plan?.status === 403 ? (plan.error || 'Only an instance admin can install software on this server.') : `Could not plan the install: ${plan?.error || 'no answer'}`);
+      }
+      printInfo(planLine(plan));
+      let approvalId = null;
+      if (io.isAgent()) {
+        const orgId = resolveOrgId(auth, program);
+        const src = (() => { try { return detectCallerSource(process.env); } catch { return {}; } })();
+        const session = process.env.QUOX_SESSION || src?.label || 'agent';
+        const ep = resolveEndpoint('inbox.decision.create', { orgId });
+        const filed = await client.post(ep.path, { service: ep.service, body: {
+          session, title: `Install ${t.name} on this server?`, why: planLine(plan), options: YN_OPTIONS, recommend: 'y', high_risk: true,
+          justification: `${session} asked to install ${t.vendor}'s ${plan.package} ${plan.version} from npm on this Quox server, so ${t.name} works. It runs as the Quox service user, never root, and every install is audited.`,
+          agent: process.env.QUOX_AGENT_ID || undefined,
+        } });
+        const id = filed?.decision?.id;
+        if (!id) throw new Error('Could not file the approval card. Nothing was installed.');
+        printInfo(`An agent is running this, so a person decides: approval card ${id} is in /approvals (needs the step-up PIN).`);
+        const r = await waitForDecision({
+          poll: (w) => { const g = resolveEndpoint('inbox.decision.get', { orgId, id }); return client.get(g.path, { service: g.service, query: { wait: w }, timeout: (w + 15) * 1000, retries: 0 }); },
+          log: (m) => process.stderr.write(`${m}\n`),
+        });
+        if (r.decision?.state !== 'answered' || r.decision?.answer?.option !== 'y') { printInfo(`Not installed: the card was not approved. Nothing was downloaded.`); process.exitCode = 2; return; }
+        approvalId = id;
+      } else if (!opts.yes) {
+        if (!io.isTTY()) throw new Error(`Run again with --yes to install ${t.name}, or run it in a terminal to be asked. Nothing was installed.`);
+        if (!(await io.confirm(offerQuestion(tool, plan)))) { printInfo('Not installed. Nothing was downloaded.'); return; }
+      }
+      printInfo(`◐ installing ${t.name} ${plan.version} on the server (this takes a minute or two)`);
+      const r = await runInstall(a, tool, { approvalId, onProgress: printInfo, sleep: io.sleep || undefined });
+      if (!r.ok) throw new Error(r.lines.join(' '));
+      for (const l of r.lines) printInfo(l);
+    });
+
+  // ── provider test ──────────────────────────────────────────────────────────
+  provider
+    .command('test')
+    .description('Test the stored connection for a provider (or every default connection) through the vault test')
+    .argument('[kind]', 'provider to test (default: every connected provider)')
+    .action(async (kind) => {
+      auth.requireAuth();
+      const p = kind ? providerFor(kind) : null;
+      if (kind && !p) throw new Error(`No provider called "${kind}". Use one of: ${KINDS.join(', ')}`);
+      const vault = await api().connections();
+      if (!vault?.ok) throw new Error(`Could not read the vault: ${vault?.error || 'no answer'}`);
+      const types = new Set(p ? [p.type] : Object.values(PROVIDERS).map((x) => x.type));
+      const rows = vault.rows.filter((r) => types.has(r.integration_type) && (r.is_default === 1 || r.is_default === true));
+      if (!rows.length) throw new Error(p ? `No ${p.id} connection is stored for this org. Connect one: quox provider connect ${p.id}` : 'No provider connection is stored for this org. Connect one: quox provider connect <kind>');
+      const orgId = resolveOrgId(auth, program);
+      let failed = 0;
+      for (const row of rows) {
+        const name = (Object.values(PROVIDERS).find((x) => x.type === row.integration_type) || {}).name || row.integration_type;
+        const ep = resolveEndpoint('vault.test', { orgId, id: row.id });
+        let res;
+        try { res = await client.post(ep.path, { service: ep.service, retries: 0 }); }
+        catch (e) { res = { success: false, message: e?.message || 'failed' }; }
+        if (res?.success === false) { failed++; printInfo(`✖ ${name}  ${row.label || row.id}  failed: ${res?.message || 'no reason given'}`); }
+        else printInfo(`✔ ${name}  ${row.label || row.id}  ok${res?.message ? `: ${res.message}` : ''}`);
+      }
+      if (failed) process.exitCode = 1;
+    });
+}

package/lib/commands/qlarity.js

@@ -49,9 +49,12 @@ function annotate(err) {
   throw err;
 }
 
-async function call(client, id, params = {}, body) {
+// quox#907: a browser login is slower than a read; well above the client's 30s default.
+const LOGIN_TIMEOUT_MS = 120000;
+
+async function call(client, id, params = {}, body, extra = {}) {
   const ep = resolveEndpoint(id, params);
-  const opts = { service: ep.service };
+  const opts = { service: ep.service, ...extra };
   if (body) opts.body = body;
   switch (ep.method) {
     case 'POST': return client.post(ep.path, opts);
@@ -634,15 +637,28 @@ export function registerQlarityCommands(program, ctx) {
           (await call(client, 'qlarity.sessions.list')).sessions || [],
           normalizedOrigin,
         );
+        let fresh = false;
         if (!sessionId) {
           const s = await call(client, 'qlarity.session.create', {}, {});
           sessionId = s.id;
+          fresh = true;
         }
 
         const body = { origin: normalizedOrigin, credential_id: credentialId };
         if (options.loginPath) body.login_path = options.loginPath;
 
-        const r = await call(client, 'qlarity.session.login', { sessionId }, body);
+        // quox#907: a real login (page load, form fill, cookie wait) can outlast the CLI's 30s default on a loaded
+        // box, and the server kept finishing it, so every timed-out retry left a headless browser behind. Give login
+        // its own budget, and close a session THIS call created when the login call fails (as openSession does, #680).
+        let r;
+        try {
+          r = await call(client, 'qlarity.session.login', { sessionId }, body, { timeout: LOGIN_TIMEOUT_MS });
+        } catch (loginErr) {
+          if (fresh) {
+            try { await call(client, 'qlarity.session.close', { sessionId }); } catch { /* the server reaper will get it */ }
+          }
+          throw loginErr;
+        }
 
         if (r.logged_in) {
           loggedIn[normalizedOrigin] = { sessionId, logged_in_at: new Date().toISOString() };

package/lib/commands/quoxchat.js

@@ -131,11 +131,19 @@ export function registerQuoxchatCommands(program, ctx) {
     .action(async () => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const data = await client.get(resolveEndpoint('quoxchat.widgets.list', { orgId }).path, { service: resolveEndpoint('quoxchat.widgets.list', { orgId }).service });
+      // QC-BRUTALOOP-W15: the route pages at 20; listing only page 1 silently
+      // under-reported the org's widgets (20 of 34). Walk every page.
+      const ep = resolveEndpoint('quoxchat.widgets.list', { orgId });
+      const rows = [];
+      for (let page = 1; page <= 50; page++) {
+        const data = await client.get(page === 1 ? ep.path : `${ep.path}?page=${page}`, { service: ep.service });
+        rows.push(...(Array.isArray(data) ? data : (data.items || [])));
+        if (Array.isArray(data) || !data.pagination?.has_more) break;
+      }
       formatOutput({
         columns: ['id', 'name', 'assistant_name', 'status', 'operator_online', 'created_at'],
         headers: ['ID', 'Name', 'Assistant', 'Status', 'Operator online', 'Created'],
-        rows: data.items || data,
+        rows,
       }, { format: program.opts().output, emptyMessage: 'No widgets found.' });
     });
 
@@ -209,7 +217,8 @@ export function registerQuoxchatCommands(program, ctx) {
     .description('Print a conversation transcript in chronological order')
     .argument('<widgetId>', 'widget ID')
     .argument('<conversationId>', 'conversation ID')
-    .action(async (widgetId, conversationId) => {
+    .option('--full', 'do not truncate long messages in table output (JSON output is never truncated)')
+    .action(async (widgetId, conversationId, cmdOpts = {}) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
 
@@ -236,7 +245,7 @@ export function registerQuoxchatCommands(program, ctx) {
           from: m.role === 'user' ? visitorName : m.role === 'operator' ? (m.sender_name || 'Operator') : 'AI assistant',
           content: m.content || '',
         })),
-      }, { format: program.opts().output, emptyMessage: 'No messages in this conversation yet.' });
+      }, { format: program.opts().output, full: cmdOpts.full === true, emptyMessage: 'No messages in this conversation yet.' });
     });
 
   quoxchat

package/lib/commands/quoxseo.js

@@ -100,6 +100,44 @@ export function registerQuoxseoCommands(program, ctx) {
       } catch (err) { annotate(err); }
     });
 
+  s.command('remove-site <site>')
+    .description('Remove a registered site and its warehouse data for this org (governed, witnessed). <site> is an origin or property id')
+    .option('-y, --yes', 'skip the confirmation prompt')
+    .action(async (site, opts) => {
+      try {
+        const list = await get(client, 'quoxseo.sites');
+        const props = list.properties || [];
+        const norm = (v) => String(v).trim().replace(/\/+$/, '').toLowerCase();
+        const target = props.find((p) => String(p.id) === String(site).trim() || norm(p.origin) === norm(site));
+        if (!target) {
+          throw new Error(`Site not found: ${site} is not registered for this org. List them with: quox seo sites`);
+        }
+        const warn = `This permanently removes ${target.origin} (#${target.id}) from this org and deletes its crawl, GSC and GA4 warehouse data. This cannot be undone.`;
+        if (!opts.yes && program.opts().yes !== true) {
+          if (!process.stdin.isTTY) {
+            throw new Error(`${warn} Confirmation needed; re-run with --yes in a non-interactive shell: quox seo remove-site ${target.origin} --yes`);
+          }
+          console.log(warn);
+          const { confirmDestructive } = await import('../core/confirm.js');
+          const ok = await confirmDestructive(program, {}, `Remove ${target.origin}?`);
+          if (!ok) { console.log('Aborted. Nothing was removed.'); return; }
+        }
+        const ep = resolveEndpoint('quoxseo.sites.remove', { id: target.id });
+        let data;
+        try {
+          data = await client.delete(ep.path, { service: ep.service });
+        } catch (err) {
+          const code = err?.status ?? err?.statusCode ?? err?.response?.status;
+          if (code === 404 || code === 405 || /\b(404|405)\b|not found|read.only/i.test(err?.message || '')) {
+            err.message = `${err.message}\nThis install's QuoxSEO service does not support site removal (no DELETE route), or the site no longer exists. Nothing was removed.`;
+          }
+          throw err;
+        }
+        if (jsonOut(data)) return;
+        console.log(`removed #${target.id}  ${target.origin}`);
+      } catch (err) { annotate(err); }
+    });
+
   s.command('urls')
     .description('Warehouse rows for the latest crawl')
     .option('--filter <f>', 'orphans | noindex | errors | no-gsc | discovered')
@@ -193,6 +231,37 @@ export function registerQuoxseoCommands(program, ctx) {
       } catch (err) { annotate(err); }
     });
 
+  s.command('queries')
+    .description('Ranked Search Console query rows: query, page, impressions, clicks, CTR, position')
+    .option('--sort <s>', 'impressions | clicks | position-opportunity (high impressions at position 5-20)', 'impressions')
+    .option('--limit <n>', 'max rows (default 25, max 100)', '25')
+    .option('--filter <text>', 'only queries containing this text, e.g. "conversation"')
+    .option('--gaps', 'topic-gap view: queries with impressions that no crawled page targets')
+    .action(async (opts) => {
+      try {
+        const qs = new URLSearchParams();
+        qs.set('sort', opts.sort);
+        qs.set('limit', opts.limit);
+        if (opts.filter) qs.set('filter', opts.filter);
+        if (opts.gaps) qs.set('gaps', '1');
+        const data = await get(client, 'quoxseo.queries.rows', { query: `?${qs}` });
+        if (jsonOut(data)) return;
+        if (!data.crawl_id) { console.log('No Search Console query data yet; the ingest with Search Console access has not run.'); return; }
+        const p = data.period;
+        const when = p && p.start ? `${p.start}..${p.end}` : 'period unknown';
+        const rows = data.rows || [];
+        if (data.view === 'topic-gaps') {
+          console.log(`topic gaps (impressions, no page targets the query) · ${when} · ${rows.length} of ${data.total_gaps}`);
+        } else {
+          console.log(`queries by ${data.sort}${opts.filter ? ` matching "${opts.filter}"` : ''} · ${when} · ${rows.length} of ${data.matched}`);
+        }
+        if (!rows.length) { console.log('No rows.'); return; }
+        for (const r of rows) {
+          console.log(`${r.query}  | ${r.page}  impr ${r.impressions}  clk ${r.clicks}  ctr ${(r.ctr * 100).toFixed(1)}%  pos ${r.position ?? '-'}`);
+        }
+      } catch (err) { annotate(err); }
+    });
+
   s.command('coverage')
     .description("Google index coverage: what's indexed, and where Google disagrees with the page")
     .option('--filter <f>', 'indexed | not-indexed')

package/lib/commands/reach.js

@@ -103,7 +103,8 @@ export function registerReachCommands(program, ctx) {
       const orgId = resolveOrgId(auth, program);
       const days = parseInt(options.days, 10) || 30;
       const ep = resolveEndpoint('reach.agent.leastPrivilege', { orgId, agentId, days });
-      const result = await client.get(ep.path, { service: ep.service });
+      // #923: the report scans the usage window and outlived the 30 s default under load
+      const result = await client.get(ep.path, { service: ep.service, timeout: 120000 });
 
       if (isJsonOutput(program)) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/lib/commands/research.js

@@ -0,0 +1,79 @@
+/**
+ * quox research domains list|add <domain>|remove <domain>
+ *
+ * The curated trusted research list: hosts the research agent may web_read after a web_search has run.
+ * Stored as the org setting RESEARCH_TRUSTED_DOMAINS through the SAME governed settings path as
+ * `quox settings set` (PATCH /api/v1/platform/settings/flags/:key, human org admin, witnessed there).
+ * Unset or empty means the built-in default list, which add/remove seed from so a first edit never drops it.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const KEY = 'RESEARCH_TRUSTED_DOMAINS';
+
+// Mirror of services/collector/lib/researchTrustedDefaults.js DEFAULT_TRUSTED_SETTING (a test keeps them identical).
+export const DEFAULT_DOMAINS = (`nist.gov,cisa.gov,cve.org,=cve.mitre.org,=cveawg.mitre.org,=www.kernel.org,=developers.cloudflare.com,=attack.mitre.org,=www.python.org,=docs.python.org,=peps.python.org,=go.dev,=tip.golang.org,` +
+  `=nginx.org/en/,=nginx.org/license,=www.postgresql.org/docs/,=www.postgresql.org/support/security/,=www.postgresql.org/about/news/,` +
+  `openssl-library.org,openssl.org,openssh.com,=kubernetes.io,msrc.microsoft.com,=www.rfc-editor.org,=datatracker.ietf.org/doc/,` +
+  `security-tracker.debian.org,ubuntu.com/security,github.com/advisories/ghsa-`).split(',');
+
+const tokens = (v) => String(v || '').split(/[\s,]+/).map((t) => t.trim().toLowerCase()).filter(Boolean);
+
+function cleanDomain(raw) {
+  const eq = String(raw || '').trim().startsWith('=') ? '=' : '';
+  const t = String(raw || '').trim().replace(/^=/, '').toLowerCase().replace(/^https?:\/\//, '').replace(/\/+$/, '');
+  const host = t.split('/')[0].replace(/\.+$/, '');
+  if (!/^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/.test(host)) return null; // IP literals and junk refused
+  return eq + (t.includes('/') ? host + t.slice(t.indexOf('/')) : host);
+}
+
+async function effective(client) {
+  const ep = resolveEndpoint('v1.settings.list');
+  const data = await client.get(ep.path, { service: ep.service });
+  const f = (data.flags || []).find((x) => x.key === KEY);
+  const list = tokens(f && f.value);
+  const isOrg = !!(f && f.source === 'setting' && list.length);
+  return { list: isOrg ? list : DEFAULT_DOMAINS.slice(), source: isOrg ? 'org setting' : 'built-in default' };
+}
+
+async function write(client, list) {
+  const ep = resolveEndpoint('v1.settings.set', { key: KEY });
+  return client.patch(ep.path, { service: ep.service, body: { value: list.join(',') } });
+}
+
+export function registerResearchCommands(program, ctx) {
+  const { client } = ctx;
+  const r = program.command('research').description('Governed web research settings');
+  const d = r.command('domains').description('Trusted research domains: hosts agents may read after a web search (org setting)');
+
+  d.command('list', { isDefault: true })
+    .description('Show the effective trusted research list and where it comes from')
+    .action(async () => {
+      const { list, source } = await effective(client);
+      process.stdout.write(`source: ${source}\n`);
+      for (const e of list) process.stdout.write(`  ${e}\n`);
+    });
+
+  d.command('add <domain>')
+    .description('Add a domain (or host/path-prefix; a leading = means exact host only) to the org list (human org admin)')
+    .action(async (domain) => {
+      const dom = cleanDomain(domain);
+      if (!dom) { process.stderr.write(`Not added: "${domain}" is not a domain name (IP literals are never trusted)\n`); process.exitCode = 1; return; }
+      const { list } = await effective(client);
+      if (list.includes(dom)) { process.stdout.write(`${dom} is already on the list\n`); return; }
+      await write(client, [...list, dom]);
+      process.stdout.write(`added ${dom} (${list.length + 1} entries, org setting)\n`);
+    });
+
+  d.command('remove <domain>')
+    .description('Remove a domain from the org list (human org admin)')
+    .action(async (domain) => {
+      const dom = cleanDomain(domain);
+      const { list } = await effective(client);
+      if (!dom || !list.includes(dom)) { process.stderr.write(`Not removed: ${domain} is not on the list\n`); process.exitCode = 1; return; }
+      const next = list.filter((e) => e !== dom);
+      if (!next.length) { process.stderr.write('Not removed: that would empty the list, which means the built-in default. Add another entry first.\n'); process.exitCode = 1; return; }
+      await write(client, next);
+      process.stdout.write(`removed ${dom} (${next.length} entries, org setting)\n`);
+    });
+}

package/lib/commands/router.js

@@ -0,0 +1,77 @@
+/**
+ * `quox router` : read-only MikroTik RouterOS views via the NETWATCH tools (ROUTEROS-WIRE).
+ *
+ *   quox router health                    CPU, memory, temperature, uptime
+ *   quox router leases                    DHCP leases
+ *   quox router pools                     DHCP pool usage
+ *   quox router conflicts                 IP address conflicts (ARP vs DHCP leases)
+ *   quox router free-ip [--count n] [--pool name]   spare addresses for static use (reserves nothing)
+ *   quox router vpn                       VPN tunnel health (WireGuard + IPsec)
+ *   quox router wireguard                 WireGuard peers and whether they are connected
+ *   quox router inventory                 routers and the devices connected to them
+ *   quox router trust --show              the router's current TLS fingerprint (sends NO credentials; pins nothing)
+ *
+ * Every verb is one tool call through POST /api/v1/tools/execute. No verb writes to the router.
+ * Engine: lib/core/router.js.
+ */
+import { resolveOrgId } from './helpers.js';
+import { ROUTER_TOOLS, ROUTER_FORMATTERS, makeRouterExec, formatTrust } from '../core/router.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const DESCRIPTIONS = {
+  health: 'Router CPU, memory, temperature and uptime (read only)',
+  leases: 'DHCP leases: which devices hold an address (read only)',
+  pools: 'DHCP pool usage: size, used, free (read only)',
+  conflicts: 'IP address conflicts seen by the router, ARP vs DHCP leases (read only)',
+  'free-ip': 'Spare pool addresses for static assignment; reserves nothing (read only)',
+  vpn: 'VPN tunnel health, WireGuard and IPsec (read only)',
+  wireguard: 'WireGuard peers and whether each is connected (read only)',
+  inventory: 'MikroTik routers and the devices connected to them (read only)',
+};
+
+export function registerRouterCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const json = () => program.opts().output === 'json';
+
+  const router = program
+    .command('router')
+    .description('MikroTik RouterOS read-only views via NETWATCH (health, DHCP, VPN, inventory)');
+
+  for (const verb of Object.keys(ROUTER_TOOLS)) {
+    const cmd = router.command(verb).description(DESCRIPTIONS[verb]);
+    if (verb === 'free-ip') {
+      cmd.option('--count <n>', 'how many addresses (1-20)', '3').option('--pool <name>', 'only this DHCP pool');
+    }
+    cmd.action(async (opts = {}) => {
+      auth.requireAuth();
+      const exec = makeRouterExec({ client, orgId: resolveOrgId(auth, program) });
+      const input = {};
+      if (verb === 'free-ip') {
+        const n = Number.parseInt(opts.count, 10);
+        if (!Number.isInteger(n) || n < 1 || n > 20) throw new Error('--count must be a whole number from 1 to 20');
+        input.count = n;
+        if (opts.pool) input.pool = String(opts.pool);
+      }
+      const p = await exec(ROUTER_TOOLS[verb], input);
+      if (json()) console.log(JSON.stringify(p, null, 2));
+      else console.log(ROUTER_FORMATTERS[verb](p).join('\n'));
+    });
+  }
+
+  // quoxai/quox#1236: the operator reads the endpoint's fingerprint here (no credentials sent),
+  // compares it out of band, then sets MIKROTIK_TLS_PIN themselves. This verb never pins.
+  router
+    .command('trust')
+    .description("Show the router's current TLS fingerprint, sending no credentials (never pins; you set MIKROTIK_TLS_PIN yourself)")
+    .option('--show', "print the fingerprint the router's HTTPS endpoint presents now")
+    .action(async (opts = {}) => {
+      auth.requireAuth();
+      if (!opts.show) {
+        throw new Error('quox router trust only has --show. It never pins anything: compare the fingerprint out of band, then set MIKROTIK_TLS_PIN yourself.');
+      }
+      const ep = resolveEndpoint('router.tlsFingerprint');
+      const data = await client.get(ep.path, { service: ep.service, query: { org_id: resolveOrgId(auth, program) } });
+      if (json()) { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(formatTrust(data).join('\n'));
+    });
+}