quoxcli 0.3.1 → 0.5.0

package/lib/commands/qlarity.js

@@ -49,6 +49,25 @@ function annotate(err) {
   throw err;
 }
 
+/**
+ * Inspectors whose server-side run() calls assertSelector (qlarity/src/inspectors.js).
+ * The registry lives in another repo and `inspectors list` does not expose the
+ * flag, so this mirrors it; storage, dom_summary, layout_health and
+ * responsive_sweep default or skip the selector and are deliberately absent.
+ */
+export const SELECTOR_INSPECTORS = ['computed_style', 'pseudo_style', 'text_content', 'attribute', 'count', 'bounding_box', 'expect'];
+
+/** Keep scheme+host+port only (lowercased); anything unparseable goes through for the server to explain. */
+export function normaliseOrigin(input) {
+  try {
+    const u = new URL(String(input).trim());
+    if (!/^https?:$/.test(u.protocol)) return input;
+    return u.origin;
+  } catch {
+    return input;
+  }
+}
+
 // quox#907: a browser login is slower than a read; well above the client's 30s default.
 const LOGIN_TIMEOUT_MS = 120000;
 
@@ -308,14 +327,21 @@ export function registerQlarityCommands(program, ctx) {
   al.command('add <origin>')
     .description('Declare an origin this org may inspect, e.g. https://staging.example.com')
     .option('--note <text>', 'why it is allowed, shown alongside it later')
-    .action(async (origin, opts) => {
+    .action(async (rawOrigin, opts) => {
+      const origin = normaliseOrigin(rawOrigin);
       try {
+        if (origin !== rawOrigin) process.stdout.write(`allowlisting ${origin} (scheme+host+port of ${rawOrigin})\n`);
         const d = await call(client, 'qlarity.orgAllowlist.add', {}, { origin, note: opts.note });
         process.stdout.write(`\u{1F50D} QLARITY: added ${d.entry.origin}\n`);
         process.stdout.write(`  ${d.origins.length} origin(s) now declared for this org\n`);
       } catch (err) {
         // A refusal here is usually a wildcard or a typo, and the server sends
         // the reason. Surface it instead of a bare 400.
+        if (err?.status === 403) {
+          process.stderr.write(`Not added: adding an origin is an org-admin action by design (an agent cannot self-authorize egress).\nRetry as an org admin: quox -p <admin-profile> qlarity origins add ${origin}\n`);
+          process.exitCode = 4;
+          return;
+        }
         if (err?.status === 400 && err?.message) {
           process.stderr.write(`Not added: ${err.message}\n`);
           process.exitCode = 1;
@@ -395,6 +421,11 @@ export function registerQlarityCommands(program, ctx) {
     .option('--session <id>', 'reuse an existing session (e.g. one left open by `quox qlarity login`) instead of opening a fresh one')
     .option('--json', 'raw JSON output')
     .action(async (url, options) => {
+      if (SELECTOR_INSPECTORS.includes(options.inspector) && !options.selector) {
+        process.stderr.write(`${options.inspector} needs --selector. Try: quox qlarity read ${url} --inspector ${options.inspector} --selector 'body'\n`);
+        process.exitCode = 2;
+        return;
+      }
       let sessionId = null;
       let reused = false;
       try {

package/lib/commands/quoxseo.js

@@ -231,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/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/rows.js

@@ -38,9 +38,16 @@ export const CONTRACT = {
     trend: 'optional. up, down, flat, or a number (the change: 3 shows ▲3, -2 shows ▼2).',
     link: 'optional. An http(s) URL to look at for more; shown by quox rows test and /row test.'
   },
+  // TUI-QPE 2026-10-19: additive v1.1 fields, kept apart so the v1 field list stays exactly as published.
+  fields_v1_1: {
+    cells: 'optional. [{parts: [{text, tone, bold, keep, group}], keep}]: one row in several colours. A narrow window drops the lowest keep first (a whole part, its group, or a cell; no keep = never dropped), never half a word.',
+    grid: 'optional. A short name; rows with the same grid line their cells up in columns (quox-qpe-row uses "qpe").',
+    min_cols: 'optional. A whole number; the row hides when the drawn width (the terminal width less one) is under it.'
+  },
   example: { label: 'Approvals', value: 3, text: 'waiting for you', tone: 'warn', trend: 1, link: 'https://quox.example/approvals' },
   rules: [
     'Plain text output counts as {"text": "<the text>"}.',
+    'One source can draw several lines: {"text": "<short line for older clients>", "grid": "...", "lines": [<status row>, ...]} (up to 4 lines in all above the status bar).',
     'Terminal escapes and control characters are removed before anything is drawn.',
     'A row definition never carries a secret: use a quox or plugin row (your session is used) or a local command that reads its own secret.',
     'Command rows run on the machine that holds them only. They are never synced, shared or imported without a person saying yes to the exact command.'
@@ -347,6 +354,8 @@ export function registerRowsCommands(program, ctx) {
       if (json()) return say(JSON.stringify(CONTRACT, null, 2));
       say(tint('heading').bold('Status-row contract v1'));
       for (const [k, v] of Object.entries(CONTRACT.fields)) say(`  ${tint('id').bold(k.padEnd(6))} ${v}`);
+      say(tint('label')('v1.1 (colours and narrow windows):'));
+      for (const [k, v] of Object.entries(CONTRACT.fields_v1_1)) say(`  ${tint('id').bold(k.padEnd(8))} ${v}`);
       say(tint('label')('Example:'));
       say('  ' + JSON.stringify(CONTRACT.example));
       say(tint('label')('Draws as:'));

package/lib/commands/run.js

@@ -39,7 +39,8 @@ export function registerRunCommands(program, ctx) {
         let items = data.data || data.items || (Array.isArray(data) ? data : []);
         // an older engine that ignores the filter must still never show another workflow's runs
         if (options.workflow) items = items.filter((it) => (it.workflowId ?? it.workflow_id) === options.workflow);
-        rows = items.map((item) => ({ ...item, source: 'engine' }));
+        // quoxflow rows are camelCase (workflowName, startedAt, completedAt); the table reads snake_case columns.
+        rows = items.map((item) => ({ ...item, workflow_name: item.workflow_name ?? item.workflowName, started_at: item.started_at ?? item.startedAt, finished_at: item.finished_at ?? item.completedAt ?? item.finishedAt, source: 'engine' }));
         source = 'engine';
       } catch (err) {
         printWarning(`Engine (quoxflow) execution list failed, falling back to the auth-service store: ${err.message}`);
@@ -90,7 +91,24 @@ export function registerRunCommands(program, ctx) {
         }
       }
 
-      formatDetail({ ...data, source }, { format: program.opts().output });
+      // RUNS: surface WHICH step failed and the retry hint at the top level, so a failed
+      // run no longer reads as a bare "fetch failed" with no step.
+      const detail = { ...data, source };
+      const d = data.error && typeof data.error.details === 'object' && data.error.details ? data.error.details : null;
+      if (data.status === 'failed' && d && d.nodeId) {
+        detail.failedStep = d.nodeName && d.nodeName !== d.nodeId ? `${d.nodeName} (${d.nodeId})` : String(d.nodeId);
+      }
+      if (data.status === 'failed' && data.error && data.error.message) {
+        // formatDetail truncates long nested values; show the full code + network detail here.
+        detail.failure = `${data.error.code || 'ERROR'}: ${data.error.message}`;
+      }
+      if (data.metadata && data.metadata.retryable) {
+        detail.retry = data.metadata.retryExecutionId
+          ? `auto-retried as ${data.metadata.retryExecutionId}`
+          : `retryable: ${data.metadata.retryHint || `quox run create --workflow ${data.workflowId}`}`;
+      }
+
+      formatDetail(detail, { format: program.opts().output, full: true });
     });
 
   run

package/lib/commands/scope.js

@@ -5,7 +5,7 @@
  *
  * Scopes are read-only projections of the org/division/department/team
  * hierarchy — there is no backend write route for scopes. To create,
- * update, or delete a scope, use `quox org`, `quox division`,
+ * update, or delete a scope, use `quox org`, `quox org divisions`,
  * `quox department`, or `quox team` instead.
  */
 
@@ -18,7 +18,7 @@ export function registerScopeCommands(program, ctx) {
 
   const scope = program
     .command('scope')
-    .description('View scopes (read-only — use `quox org`/`quox division`/`quox team` to manage)');
+    .description('View scopes (read-only — use `quox org`/`quox org divisions`/`quox department`/`quox team` to manage)');
 
   scope
     .command('list')

package/lib/commands/server.js

@@ -24,6 +24,8 @@ import { planUninstall, runUninstall } from '../server/uninstall.js';
 import { serverChecks } from '../server/doctor.js';
 import { writeDiagBundle } from '../server/diag.js';
 import { latestSnapshot, listSnapshots } from '../server/snapshot.js';
+import { runInstallFlow } from '../server/installFlow.js';
+import { loadRegistry, saveServer, buildRows, planGo, hereIdentity, registryPath } from '../server/devServers.js';
 
 const icon = (s) => (s === 'pass' ? chalk.green('✔') : s === 'warn' ? chalk.yellow('⚠') : s === 'skip' ? chalk.dim('·') : chalk.red('✖'));
 
@@ -69,6 +71,42 @@ export function registerServerCommands(program, ctx = {}) {
   const server = program.command('server').description('Your self-hosted Quox install: status, update, rollback, uninstall, doctor, diag');
   const withDir = (c) => c.option('--dir <path>', 'the install directory (default: the one Getting started recorded)');
 
+  server.command('install')
+    .description('Install Quox on this machine: checks, download, start, owner account, one-time dashboard link (the same installer Getting started runs)')
+    .option('--dir <path>', 'where to install (default: ~/quox-install)')
+    .option('--dry-run', 'check this machine, print the plan, change nothing')
+    .option('-y, --yes', 'skip the confirmation (required without a terminal)')
+    .option('--json', 'one JSON object per line: stage events, then a result')
+    .option('--email <address>', 'owner account email (asked when there is a terminal)')
+    .option('--password-stdin', 'read the owner password from stdin, one line (never an argument)')
+    .option('--print-login-link', 'print the live one-time sign-in link (default: only on an interactive terminal, never in --json)')
+    .action(async (o) => {
+      const asJson = Boolean(o.json) || json();
+      const human = (e) => {
+        if (e.type === 'log') { console.log(chalk.dim(`    ${e.line}`)); return; }
+        if (e.type === 'stage') {
+          if (e.status === 'running') console.log(` ${chalk.cyan('◐')} ${e.stage}`);
+          else if (e.status === 'ok') console.log(` ${chalk.green('✔')} ${e.stage}${e.detail ? chalk.dim(`  ${e.detail}`) : ''}`);
+          else if (e.status === 'skip') console.log(` ${chalk.dim('·')} ${e.stage} skipped${e.detail ? `: ${e.detail}` : ''}${e.next ? `. ${e.next}` : ''}`);
+          else if (e.status === 'fail') { console.log(chalk.red(` ✖ ${e.stage} failed: ${e.error}`)); console.log(`   Next: ${e.next}`); }
+        } else if (e.type === 'plan') {
+          console.log(chalk.bold(`\n Plan: install Quox into ${e.dir || '~/quox-install'}`));
+          for (const c of e.checks) console.log(`   ${c.status === 'fail' ? chalk.red('✖') : c.status === 'warn' ? chalk.yellow('⚠') : chalk.green('✔')} ${c.id.padEnd(8)} ${c.body}`);
+          console.log(' It will:'); e.steps.forEach((s, i) => console.log(`   ${i + 1}. ${s}`));
+          console.log(chalk.dim('\n Dry run: nothing was changed. Run quox server install to install.\n'));
+        } else if (e.type === 'result' && e.ok && !e.dryRun) {
+          console.log(chalk.green('\n ✔ Your Quox is running.'));
+          if (e.link) console.log(` Dashboard sign-in link (single use, 10 minutes): ${e.link}`);
+          else console.log(` A one-time sign-in link was issued but not printed (stdout is not a terminal). Get one with: ${e.linkHow}`);
+          console.log(chalk.dim(' Your browser will warn about the certificate once: it is the self-signed one this install made.\n'));
+        }
+      };
+      const emit = (e) => (asJson ? console.log(JSON.stringify(e)) : human(e));
+      const r = await runInstallFlow({ dir: o.dir, dryRun: dry(o), yes: yes(o), email: o.email, passwordStdin: Boolean(o.passwordStdin), printLink: Boolean(o.printLoginLink) || (!asJson && Boolean(process.stdout.isTTY)) }, deps.installFlowDeps || {}, emit);
+      if (!r.ok && !r.dryRun) process.exitCode = r.declined ? 1 : 2;
+      if (!r.ok && r.dryRun === undefined && r.failedStage && dry(o)) process.exitCode = 2;
+    });
+
   withDir(server.command('status').description('Version, health per service, disk, ports and the last update (read-only)'))
     .action(async (o) => {
       const i = await install(o);
@@ -288,5 +326,117 @@ export function registerServerCommands(program, ctx = {}) {
       console.log(`Private-network targets: ${r.enabled ? 'on' : 'off'} ${chalk.dim('(quox server config lan-targets on|off)')}`);
     });
 
+  // DEVFLEET CX-2: `quox server roles` — the server roles registry (role -> url). A role (brain today) can be pointed
+  // off-box so the service runs on another host without an env edit; resolveServiceUrl reads the registry before env.
+  // list is readable by any instance admin; set/unset mutate instance-wide state so are instance-OWNER (superadmin) only.
+  const roles = server.command('roles').description('Point a server role (e.g. brain) at a URL, so a service can run off-box without an env change');
+  roles.command('list')
+    .description('Show each role, its URL, and whether it comes from the registry or the environment (read-only)')
+    .action(async () => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      const ep = resolveEndpoint('server.roles.list');
+      const r = await client.get(ep.path, { service: ep.service });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      if (r.corrupt) console.log(chalk.yellow(` ⚠ the roles store is unreadable (${r.error}); showing environment values only
+`));
+      for (const row of (r.roles || [])) {
+        const where = row.source === 'registry' ? chalk.green('registry') : (row.source === 'env' ? chalk.dim('environment') : chalk.dim('unset'));
+        console.log(` ${row.role.padEnd(10)} ${row.url || chalk.dim('(none)')}  ${chalk.dim(`[${where}]`)}`);
+      }
+      if (!(r.roles || []).length) console.log(chalk.dim(' no roles'));
+    });
+  roles.command('set')
+    .description('Point a role at a URL (instance owner only). Use --test to probe it for health and version first')
+    .argument('<role>', 'the role, e.g. brain')
+    .argument('<url>', 'the URL the role should resolve to, e.g. http://10.1.2.3:3106')
+    .option('--test', 'probe <url> for health and version before storing it; abort if it is unreachable')
+    .action(async (role, url, o) => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      if (o.test) {
+        const tp = resolveEndpoint('server.roles.test', { role });
+        const t = await client.post(tp.path, { service: tp.service, body: { url } });
+        if (!t.success) { const e = new Error(`--test failed: ${t.error || `status ${t.status}`}; not storing`); e.exitCode = 1; throw e; }
+        if (!json()) console.log(chalk.dim(` probe ok: status ${t.status}${t.version ? `, version ${t.version}` : ''}`));
+      }
+      const ep = resolveEndpoint('server.roles.set', { role });
+      const r = await client.put(ep.path, { service: ep.service, body: { url } });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(chalk.green(` ✔ role ${r.role} -> ${r.url}`));
+    });
+  roles.command('unset')
+    .description('Remove a role from the registry so it falls back to the environment value (instance owner only)')
+    .argument('<role>', 'the role to remove')
+    .action(async (role) => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      const ep = resolveEndpoint('server.roles.unset', { role });
+      const r = await client.delete(ep.path, { service: ep.service });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(chalk.green(r.removed ? ` ✔ role ${role} removed; falling back to the environment value` : ` role ${role} was not set`));
+    });
+
+  // DEVFLEET: the registered dev servers. Bastion supplies address + state, the org's dev-server registry supplies purpose/project/workdir.
+  const regPath = () => deps.registryPath || registryPath(env);
+  async function devRows() {
+    const { client, auth } = ctx;
+    auth?.requireAuth?.();
+    const ep = resolveEndpoint('v1.fleet.hosts.list');
+    const d = await client.get(ep.path, { service: ep.service, retries: 0, timeout: 5000 });
+    const hosts = d?.hosts || d;
+    if (!Array.isArray(hosts)) throw new Error('could not read the Bastion host registry (quox fleet hosts)');
+    { const reg = await loadRegistry({ client, path: regPath() }); return buildRows(hosts, { servers: reg.servers, defaults: reg.defaults }, deps.here || hereIdentity()); }
+  }
+  server.command('list')
+    .description('The registered dev servers: purpose, project, reachable, and which one this is (read-only)')
+    .action(async () => {
+      const rows = await devRows();
+      if (json()) { console.log(JSON.stringify(rows.map(({ ip, user, jump, ...r }) => r), null, 2)); return; }
+      if (!rows.length) { console.log(chalk.dim(` no dev servers registered. Add one: quox server mark <host> --purpose "main dev"`)); return; }
+      const showDeploy = rows.some(r => r.lastDeploy);
+      const cell = (v) => (v == null || v === '' ? '-' : String(v));
+      const w = (k) => Math.max(k.length, ...rows.map(r => cell(r[k]).length));
+      const cols = ['name', 'purpose', 'project', 'repo'];
+      const widths = Object.fromEntries(cols.map(k => [k, w(k)]));
+      console.log(chalk.bold(` ${cols.map(k => k.toUpperCase().padEnd(widths[k])).join('  ')}  REACHABLE${showDeploy ? '  LAST DEPLOY' : ''}`));
+      for (const r of rows) {
+        const line = `${cols.map(k => cell(r[k]).padEnd(widths[k])).join('  ')}  ${(r.reachable ? 'yes' : 'no').padEnd(9)}${showDeploy ? `  ${cell(r.lastDeploy)}` : ''}`;
+        console.log(` ${line}${r.current ? chalk.cyan('  <- this server') : ''}`);
+      }
+    });
+  server.command('mark')
+    .description('Record what a dev server is for (org registry on the Quox server, additive): purpose, project, repo, workdir, ci')
+    .argument('<name>', 'the Bastion host id, e.g. web01')
+    .option('--purpose <text>', 'what this server is for, e.g. "main dev"')
+    .option('--project <text>').option('--repo <text>').option('--workdir <path>', 'where go starts quox on that server')
+    .option('--ci <text>', 'CI or auto-deploy note or URL').option('--user <user>', 'ssh user (default control)').option('--jump <host>', 'ssh ProxyJump alias (default: the registry defaults.jump, else a direct ssh)')
+    .option('--last-deploy <text>', 'last deploy note (shown only if any server has one)')
+    .action(async (name, o) => {
+      ctx.auth?.requireAuth?.();
+      const e = await saveServer({ client: ctx.client, name, fields: { ...o, lastDeploy: o.lastDeploy }, path: regPath() });
+      if (json()) { console.log(JSON.stringify({ name, ...e }, null, 2)); return; }
+      console.log(chalk.green(` ✔ ${name} recorded${e.purpose ? ` as ${e.purpose}` : ''}`));
+    });
+  server.command('go')
+    .description('Open a Quox window on a registered dev server (ssh via your own config and the Bastion jump host, then quox in its workdir)')
+    .argument('<name>', 'a server from `quox server list`')
+    .option('--dry-run', 'print what would run and run nothing')
+    .action(async (name, o) => {
+      const rows = await devRows();
+      const plan = planGo(rows.find(r => r.name === name));
+      if (plan.error) {
+        const known = rows.map(r => r.name).join(', ') || 'none registered';
+        const e = new Error(plan.error === 'unknown server' ? `unknown server "${name}". Registered: ${known}` : plan.error);
+        e.exitCode = 1; throw e;
+      }
+      console.log(chalk.dim(` going to ${name}: ${plan.text}`));
+      if (dry(o)) return;
+      const spawnImpl = deps.spawnSync || (await import('node:child_process')).spawnSync;
+      const r = spawnImpl(plan.cmd, plan.args, { stdio: 'inherit', cwd: plan.cwd });
+      if (r?.error) { const e = new Error(`could not start ${plan.cmd}: ${r.error.message}`); e.exitCode = 1; throw e; }
+      if (r?.status) process.exitCode = r.status;
+    });
+
   return server;
 }