quoxcli 0.0.0-stage → 0.3.1

package/lib/core/residentPump.js

@@ -0,0 +1,229 @@
+/**
+ * Resident pump — QUOXPERTICUS-REVISIT P4 "steer pump".
+ *
+ * When a resident's slot is held by a FULL INTERACTIVE claude session (the
+ * resident itself, deployed via `quox dev resident deploy`), the warden
+ * process never answers (see the HOLD-IS-THE-VOICE gate in
+ * supervisorEngine.js): the resident already holds the voice. What the
+ * warden does instead, while that hold lasts, is PUMP: relay new owner
+ * messages from the slot channel into the resident's live tmux pane via the
+ * dev-sessions `keys` route (services/collector/lib/devSessionsProxy.js), so
+ * the interactive session hears its owner without anyone opening the pane
+ * by hand.
+ *
+ * Live-spike findings this reads (2026-09-04, real injection into a real
+ * claude TUI on .131 via tmux send-keys):
+ *   - Text injected mid-turn queues cleanly in the composer and submits when
+ *     the turn ends. Injection mid-turn is SAFE.
+ *   - A permission dialog ("Do you want to proceed? ... Esc to cancel")
+ *     BLOCKS the pipeline indefinitely. Queued input survives but does not
+ *     process. This pump NEVER injects bare Enter or any control key to
+ *     resolve one; a stuck dialog is a residentAlarm.js condition, not
+ *     something this module resolves. See paneHasDialog below.
+ *   - `keys` is one line, max 4096 chars (the collector's MAX_KEYS_LENGTH),
+ *     and the collector appends Enter itself.
+ *
+ * Every I/O dependency (fetch, pane read, key injection, heartbeat, the
+ * clock, sleep) is injected, matching supervisorEngine.js's contract, so
+ * this runs under vitest with no real network, no real tmux pane.
+ */
+
+import { pickNewMessages, boundSeenIds, pruneOldTurns, shouldPostErrorNotice, ERROR_NOTICE_WINDOW_MS, DEFAULT_SETTINGS } from './supervisorEngine.js';
+
+// The exact literal markers a Claude Code permission dialog shows
+// ("Do you want to proceed? 1. Yes 2. No ... Esc to cancel"). Either marker
+// alone is enough to hold injection: better to over-detect (delay a message
+// one pass) than under-detect and blind-inject into a live approval prompt.
+export const DIALOG_MARKERS = ['Do you want to proceed?', 'Esc to cancel'];
+
+export function paneHasDialog(paneText) {
+  const text = String(paneText || '');
+  return DIALOG_MARKERS.some((marker) => text.includes(marker));
+}
+
+function sanitizeOneLine(text) {
+  return String(text || '').replace(/\r?\n+/g, ' ').replace(/[ \t]{2,}/g, ' ').trim();
+}
+
+/**
+ * Build the `keys` line(s) for one owner message: `[slot:<name> owner]
+ * <text>`, newlines collapsed to spaces (a literal newline mid-line would
+ * submit a half-typed line early — same reasoning as residentSeed.js's
+ * oneLine()). A message that overflows maxLen is CHUNKED, never truncated
+ * (silent data loss is worse than several turns): each chunk carries its
+ * own prefix and a `(i/n)` suffix so the resident can read each line
+ * standalone.
+ */
+export function buildPumpLines({ slotName, text, maxLen = 4000 }) {
+  const prefix = `[slot:${slotName} owner] `;
+  const sanitized = sanitizeOneLine(text);
+  if (prefix.length + sanitized.length <= maxLen) {
+    return [`${prefix}${sanitized}`];
+  }
+  // Reserve headroom for the ` (NN/NN)` suffix appended to every chunk.
+  const suffixReserve = 10;
+  const available = Math.max(1, maxLen - prefix.length - suffixReserve);
+  const parts = [];
+  for (let i = 0; i < sanitized.length; i += available) {
+    parts.push(sanitized.slice(i, i + available));
+  }
+  return parts.map((part, i) => `${prefix}${part} (${i + 1}/${parts.length})`);
+}
+
+export function createInitialPumpState() {
+  return {
+    bootstrapped: false,
+    seen_ids: [],
+    // Owner messages picked up from the channel but not yet delivered to
+    // the pane: held back by a stuck dialog, or by the per-hour cap. A
+    // message only ever leaves `pending` by being injected, never dropped.
+    pending: [],
+    injection_timestamps: [],
+    overflow_notices: [],
+    // Set the moment a permission dialog is first observed; cleared the
+    // moment it is no longer observed. residentAlarm.js reads the age of
+    // this field to decide whether the stuck-dialog condition should alarm.
+    stuck_dialog_since: null,
+  };
+}
+
+/**
+ * Heartbeat the resident's slot hold with retry/backoff. The pump must not
+ * rely on the wait long-poll alone to keep the hold warm: a failed poll
+ * pass must never stop heartbeats while the collector is genuinely
+ * reachable, so this is a small standalone retry loop, called every pump
+ * pass regardless of what else happens this pass.
+ */
+export async function heartbeatWithBackoff({
+  heartbeatHold,
+  log = () => {},
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  maxAttempts = 3,
+  baseDelayMs = 2000,
+}) {
+  let lastErr = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await heartbeatHold();
+      return { ok: true, attempts: attempt };
+    } catch (err) {
+      lastErr = err;
+      log('warn', `pump: heartbeat attempt ${attempt}/${maxAttempts} failed: ${err.message}`);
+      if (attempt < maxAttempts) {
+        await sleep(baseDelayMs * attempt);
+      }
+    }
+  }
+  log('warn', `pump: heartbeat failed after ${maxAttempts} attempt(s), giving up this pass (hold may lapse): ${lastErr ? lastErr.message : 'unknown error'}`);
+  return { ok: false, attempts: maxAttempts, error: lastErr };
+}
+
+/**
+ * Run one pump pass: heartbeat the resident's hold, read the pane for a
+ * stuck permission dialog, pick up new owner messages, and inject whatever
+ * is safe to inject this pass (never while a dialog is visible, never past
+ * the per-hour cap).
+ *
+ * Injected dependencies:
+ *   fetchMessages()      -> array of slot messages (same shape the engine
+ *                           uses; a `wait`-mode caller can pass the same
+ *                           closure it already built for the headless path)
+ *   readPane()            -> current pane text (string)
+ *   injectKeys(line)      -> POST one `keys` line to the resident's pane
+ *   heartbeatHold()       -> heartbeat the slot AS the resident's own
+ *                           holder_session (not this warden's identity)
+ *   postReply(text)       -> slot `say`, used only for the once-per-hour
+ *                           overflow notice
+ */
+export async function runPumpOnce({
+  hostId,
+  slot,
+  selfIdentity,
+  fromFilters = [],
+  fetchMessages,
+  readPane,
+  injectKeys,
+  heartbeatHold,
+  postReply,
+  state,
+  log = () => {},
+  now = () => Date.now(),
+  maxSeenIds = 500,
+  maxTurnsPerHour = DEFAULT_SETTINGS.max_turns_per_hour,
+  maxLineLen = 4000,
+  heartbeatMaxAttempts = 3,
+  heartbeatBaseDelayMs = 2000,
+  sleep,
+}) {
+  const heartbeat = await heartbeatWithBackoff({
+    heartbeatHold, log, sleep, maxAttempts: heartbeatMaxAttempts, baseDelayMs: heartbeatBaseDelayMs,
+  });
+
+  const paneText = await readPane();
+  const dialogPresent = paneHasDialog(paneText);
+
+  let nextState = { ...state, pending: [...(state.pending || [])] };
+
+  if (dialogPresent) {
+    if (nextState.stuck_dialog_since == null) {
+      nextState.stuck_dialog_since = now();
+      log('warn', `slot ${slot}: permission dialog detected in the resident's pane on ${hostId}; holding owner messages until it clears (never injecting Enter to resolve it).`);
+    }
+  } else if (nextState.stuck_dialog_since != null) {
+    log('info', `slot ${slot}: permission dialog cleared after ${Math.round((now() - nextState.stuck_dialog_since) / 1000)}s; resuming injection.`);
+    nextState.stuck_dialog_since = null;
+  }
+
+  const messages = await fetchMessages();
+  const firstRun = nextState.bootstrapped !== true;
+  const picked = pickNewMessages({ messages, seenIds: nextState.seen_ids, selfIdentity, fromFilters, firstRun });
+  nextState.seen_ids = boundSeenIds(picked.seenIds, maxSeenIds);
+  if (firstRun) {
+    nextState.bootstrapped = true;
+    log('info', `pump first run on ${slot}: seeded seen-set with ${picked.allSeen.length} existing message id(s), queuing none for injection.`);
+  }
+
+  const newPending = picked.toAnswer.filter((m) => !nextState.pending.some((p) => p.id === m.id));
+  nextState.pending = [...nextState.pending, ...newPending];
+  if (newPending.length > 0) {
+    log('info', `pump: queued ${newPending.length} new owner message(s) for ${slot}'s resident.`);
+  }
+
+  let injected = 0;
+  let capHit = false;
+
+  if (!dialogPresent) {
+    let timestamps = pruneOldTurns(nextState.injection_timestamps, now(), ERROR_NOTICE_WINDOW_MS);
+    const stillPending = [];
+    for (const message of nextState.pending) {
+      if (timestamps.length >= maxTurnsPerHour) {
+        capHit = true;
+        stillPending.push(message);
+        continue;
+      }
+      const lines = buildPumpLines({ slotName: slot, text: message.text, maxLen: maxLineLen });
+      for (const line of lines) {
+        await injectKeys(line);
+      }
+      timestamps = [...timestamps, now()];
+      injected += 1;
+      log('info', `pump: injected message ${message.id} from ${message.from} into ${slot}'s resident pane (${lines.length} line(s)).`);
+    }
+    nextState.pending = stillPending;
+    nextState.injection_timestamps = timestamps;
+  } else if (nextState.pending.length > 0) {
+    log('warn', `pump: ${nextState.pending.length} owner message(s) on ${slot} held, waiting for the permission dialog to clear.`);
+  }
+
+  if (capHit && nextState.pending.length > 0) {
+    const notice = shouldPostErrorNotice(nextState.overflow_notices, 'pump_rate_cap', now(), ERROR_NOTICE_WINDOW_MS);
+    nextState.overflow_notices = notice.notices;
+    if (notice.shouldPost) {
+      const text = `Pump injection cap reached (${maxTurnsPerHour}/hour) on slot ${slot}: ${nextState.pending.length} owner message(s) still queued, will resume as the hour rolls over.`;
+      await postReply(text);
+      log('warn', `pump: posted once-per-hour overflow notice on ${slot} (${nextState.pending.length} still queued).`);
+    }
+  }
+
+  return { state: nextState, injected, dialogPresent, pendingCount: nextState.pending.length, heartbeat };
+}

package/lib/core/residentSeed.js

@@ -0,0 +1,106 @@
+/**
+ * Resident seed prompt — QUOXPERTICUS-REVISIT P3 "Resident lifecycle v1".
+ *
+ * The seed is the one line of text typed into a freshly-deployed interactive
+ * `claude` tmux pane (via the dev-sessions `keys` route) that turns a bare
+ * shell into the host's resident: read the revival kit before acting, claim
+ * the slot, then say a short hello. This encodes the proven 2026-09-04
+ * revival recipe (read MEMORY.md + indexed memories + NOTES_TO_SELF.md
+ * before acting, then claim, then greet) as a template, parameterized by
+ * host and slot.
+ *
+ * `keys` is a single line per call (the collector appends Enter — see
+ * services/collector/lib/devSessionsProxy.js MAX_KEYS_LENGTH=4096), so the
+ * rendered seed collapses to ONE line: no literal newlines, which would
+ * otherwise submit a half-typed prompt early.
+ *
+ * LATER PHASE SEAM: a collector-stored per-org/per-host seed override is a
+ * follow-up (dashboard-editable, versioned). Until that lands,
+ * `loadSeedOverride()` is the only override point, reading a local file on
+ * the CONTROL side (the box running `quox dev resident deploy`) verbatim.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function defaultSeedOverridePath() {
+  return join(homedir(), '.quox', 'resident', 'seed.md');
+}
+
+/**
+ * Read a local seed override file, if present. Returns null when the file
+ * is missing, unreadable, or empty — never throws, since a missing override
+ * simply means "use the built-in template", not an error.
+ *
+ * SEAM: a later phase replaces/augments this with a collector-stored
+ * config record (org/host-scoped, dashboard-editable). This function is the
+ * one place that phase needs to change.
+ */
+export function loadSeedOverride(path = defaultSeedOverridePath()) {
+  try {
+    if (!existsSync(path)) return null;
+    const content = readFileSync(path, 'utf-8');
+    return content && content.trim() ? content : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Collapse arbitrary text to one line safe for a single `keys` send. */
+function oneLine(text) {
+  return String(text || '').replace(/\s*\r?\n+\s*/g, ' ').replace(/[ \t]{2,}/g, ' ').trim();
+}
+
+function builtInTemplate({ hostId, slotName }) {
+  // #1021: Claude names a project dir by its path with separators turned into '-'.
+  const projectDirName = (process.env.QUOX_HOST_HOME || homedir()).replace(/[\\/]/g, '-');
+  const claimCmd = `quox slot checkout ${slotName} --session resident-${slotName} --kind interactive --host ${hostId} --create`;
+  return (
+    `You are the resident Claude session for host ${hostId} (slot ${slotName}). ` +
+    `Before doing anything else: read ~/.claude/projects/${projectDirName}/memory/MEMORY.md and every ` +
+    `memory file it indexes, then read ~/NOTES_TO_SELF.md if it exists, then read any identity or ` +
+    `onboarding docs in your home directory for this host. Read all of it before you act on anything. ` +
+    `Once you have read everything, claim your slot with: ${claimCmd}. ` +
+    `Then post one short hello (1-2 lines, no em dashes, lead with outcome) into the slot channel ` +
+    `confirming you are up and what you found.`
+  );
+}
+
+/**
+ * Render the seed prompt for a host/slot pair, as one line.
+ * @param {object} params
+ * @param {string} params.hostId
+ * @param {string} params.slotName
+ * @param {string} [params.overrideText] - test seam; when omitted, falls
+ *   back to loadSeedOverride().
+ */
+export function renderSeedPrompt({ hostId, slotName, overrideText } = {}) {
+  if (!hostId) throw new Error('renderSeedPrompt: hostId is required');
+  if (!slotName) throw new Error('renderSeedPrompt: slotName is required');
+
+  const override = overrideText !== undefined ? overrideText : loadSeedOverride();
+  if (override) {
+    return oneLine(
+      override.replace(/\{\{?\s*hostId\s*\}?\}/g, hostId).replace(/\{\{?\s*slotName\s*\}?\}/g, slotName)
+    );
+  }
+  return oneLine(builtInTemplate({ hostId, slotName }));
+}
+
+/**
+ * Split a one-line seed into <= maxLen chunks, each sent as its own `keys`
+ * call (each call appends its own Enter). Under maxLen this is a single
+ * chunk — the preferred, normal path. Splitting a seed that overflows
+ * maxLen means the resident receives it as multiple separate turns rather
+ * than one line, which is a documented degrade, not silent truncation.
+ */
+export function chunkSeedText(text, maxLen = 4000) {
+  const s = String(text || '');
+  if (s.length <= maxLen) return [s];
+  const chunks = [];
+  for (let i = 0; i < s.length; i += maxLen) {
+    chunks.push(s.slice(i, i + maxLen));
+  }
+  return chunks;
+}

package/lib/core/rootOptions.js

@@ -0,0 +1,39 @@
+/**
+ * The root `quox` program's global options, in one place so the binary
+ * (bin/quox.js) and the safety-flag test (test/safetyFlagsReachLeaf.test.js)
+ * build the SAME root. A test that re-typed this list would pass against a
+ * root the binary does not have.
+ */
+import { mergeShadowedGlobals, assertDryRunHonoured } from './global-flags.js';
+
+export function applyRootOptions(program) {
+  return program
+    .option('-o, --output <format>', 'output format: table, json, csv, quiet', 'table')
+    .option('--json', 'shorthand for --output json')
+    .option('-q, --quiet', 'suppress output, show IDs only')
+    .option('--org <slug|id>', 'override active organization (slug, name or ID; must match your session org)')
+    .option('-p, --profile <name>', 'use a specific config profile')
+    .option('--no-color', 'disable colored output')
+    .option('-v, --verbose', 'show detailed output')
+    .option('--debug', 'show HTTP request/response details')
+    .option('--dry-run', 'show what would happen without executing')
+    .option('-y, --yes', 'skip confirmation prompts')
+    .option('--insecure', 'allow self-signed SSL certificates');
+}
+
+/**
+ * The flag-delivery hooks every invocation needs, in order:
+ *  1. a value typed on the root or on a parent group reaches the leaf that
+ *     declared the same option (commander binds it to the first command that
+ *     knows it, so the leaf would otherwise read undefined or its default);
+ *  2. a --dry-run the leaf cannot honour is refused before anything runs.
+ */
+export function installFlagDeliveryHooks(program) {
+  program.hook('preAction', (thisCommand, actionCommand) => {
+    mergeShadowedGlobals(thisCommand, actionCommand);
+  });
+  program.hook('preAction', (thisCommand, actionCommand) => {
+    assertDryRunHonoured(thisCommand, actionCommand);
+  });
+  return program;
+}

package/lib/core/router.js

@@ -0,0 +1,168 @@
+/**
+ * ROUTEROS-WIRE: engine for `quox router`, the read-only MikroTik RouterOS views.
+ *
+ * Every verb is one NETWATCH tool run through the governed tool route
+ * (POST /api/v1/tools/execute, agent_id netwatch). The collector's mikrotikExecutor
+ * reaches the org's configured router through the allowlisted RouterOS proxy; nothing
+ * here talks to a router directly and no verb writes. Formatters are pure so the human
+ * output is tested without a router.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+
+/** verb -> the tool it runs. All read-only (aoclClassification layer 1, autonomy FULL). */
+export const ROUTER_TOOLS = Object.freeze({
+  health: 'mikrotik_monitoring_health',
+  leases: 'mikrotik_dhcp_leases',
+  pools: 'mikrotik_dhcp_pool_status',
+  conflicts: 'mikrotik_dhcp_conflict_check',
+  'free-ip': 'mikrotik_dhcp_find_free_ip',
+  vpn: 'mikrotik_vpn_health',
+  wireguard: 'mikrotik_vpn_wireguard_peers',
+  inventory: 'mikrotik_discovery_inventory',
+});
+
+export function makeRouterExec({ client, orgId }) {
+  return async function exec(tool, input = {}) {
+    const ep = resolveEndpoint('v1.tools.execute');
+    const body = { tool_name: tool, input, agent_id: 'netwatch' };
+    if (orgId) body.org_id = orgId;
+    const data = await client.post(ep.path, { service: ep.service, body });
+    if (data && data.success === false) {
+      const detail = data.detail ? ` (${data.detail})` : '';
+      const err = new Error(`${tool} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}${detail}`);
+      err.toolError = data.error || 'unknown error';
+      err.tool = tool;
+      throw err;
+    }
+    return routerPayload(data);
+  };
+}
+
+/** Unwrap the tool route envelope to the executor's own result object. */
+export function routerPayload(data) {
+  let p = data;
+  for (let i = 0; i < 3 && p && typeof p === 'object' && !Array.isArray(p); i++) {
+    const inner = ['result', 'output', 'data'].map((k) => p[k]).find((v) => v !== undefined && v !== null);
+    if (inner === undefined) break;
+    p = inner;
+  }
+  if (typeof p === 'string') { try { p = JSON.parse(p); } catch { /* keep text */ } }
+  if (p && typeof p === 'object' && p.success === false) {
+    const err = new Error(`router read failed: ${p.error || 'unknown error'}${p.detail ? ` (${p.detail})` : ''}`);
+    err.toolError = p.error;
+    throw err;
+  }
+  return p;
+}
+
+const dash = (v) => (v === null || v === undefined || v === '' ? '-' : String(v));
+const mib = (b) => (b === null || b === undefined ? '-' : `${Math.round(Number(b) / 1048576)} MiB`);
+const pad = (rows) => {
+  const w = [];
+  for (const r of rows) r.forEach((c, i) => { w[i] = Math.max(w[i] || 0, String(c).length); });
+  return rows.map((r) => r.map((c, i) => (i === r.length - 1 ? String(c) : String(c).padEnd(w[i]))).join('  ').trimEnd());
+};
+
+export function healthLines(p) {
+  const s = p.summary || {};
+  return [
+    `Router health score: ${dash(p.score)}/100`,
+    `CPU load:     ${s.cpu_load_pct === null || s.cpu_load_pct === undefined ? '-' : `${s.cpu_load_pct}%`}${s.cpu_count ? ` (${s.cpu_count} cpu)` : ''}`,
+    `Memory:       ${s.memory_used_pct === null || s.memory_used_pct === undefined ? '-' : `${s.memory_used_pct}% used`} (${mib(s.memory_free_bytes)} free of ${mib(s.memory_total_bytes)})`,
+    `Temperature:  ${s.temperature_c === null || s.temperature_c === undefined ? 'unknown (no sensor reported)' : `${s.temperature_c} C`}`,
+    `Uptime:       ${dash(s.uptime)}`,
+    `RouterOS:     ${dash(s.version)}  board ${dash(s.board_name)}  ${dash(s.architecture)}`,
+    ...(p.issues || []).map((i) => `! ${i}`),
+  ];
+}
+
+export function leaseLines(p) {
+  const rows = (p.leases || []).map((l) => [dash(l.address), dash(l['mac-address']), dash(l['host-name']), dash(l.status), l.dynamic === 'true' || l.dynamic === true ? 'dynamic' : 'static']);
+  return [`${p.total ?? rows.length} DHCP lease(s), ${p.bound ?? 0} bound`, ...(rows.length ? pad([['ADDRESS', 'MAC', 'HOST', 'STATUS', 'TYPE'], ...rows]) : [])];
+}
+
+export function poolLines(p) {
+  const rows = (p.pools || []).map((x) => [dash(x.name), dash(x.ranges), x.size, x.used, x.free, x.used_pct === null || x.used_pct === undefined ? '-' : `${x.used_pct}%`]);
+  return [
+    `${p.pool_count ?? rows.length} DHCP pool(s): ${p.total_used ?? 0} of ${p.total_size ?? 0} addresses used, ${p.total_avail ?? 0} free`,
+    ...(rows.length ? pad([['POOL', 'RANGES', 'SIZE', 'USED', 'FREE', 'USED%'], ...rows]) : []),
+  ];
+}
+
+export function conflictLines(p) {
+  const out = [p.plain_english || (p.healthy ? 'No IP address conflicts found.' : 'IP address conflicts found.')];
+  for (const c of p.conflicts || []) {
+    out.push(`  ${c.address}: ${(c.claims || []).map((k) => `${k.mac} (${(k.seen_in || []).join(', ')})`).join(' vs ') || (c.macs || []).join(' vs ')}`);
+  }
+  if (p.limits) out.push(`Limit: ${p.limits}`);
+  for (const i of p.issues || []) out.push(`! ${i}`);
+  return out;
+}
+
+export function freeIpLines(p) {
+  const ips = p.free_ips || [];
+  return [
+    `${ips.length} free address(es) in pool ${dash(p.pool_searched)} (checked against DHCP leases${p.arp_checked ? ' and ARP' : ', ARP unavailable'}). Nothing was reserved.`,
+    ...ips.map((f) => `  ${f.address}  (${dash(f.pool)})`),
+    ...(p.note ? [`! ${p.note}`] : []),
+  ];
+}
+
+function peerRow(x) {
+  return [dash(x.name || x.public_key), dash(x.interface), dash(x.endpoint), dash(x.allowed_address), dash(x.last_handshake), x.disabled ? 'disabled' : x.connected ? 'connected' : 'not connected'];
+}
+
+export function wireguardLines(p) {
+  const rows = (p.peers || []).map(peerRow);
+  return [
+    `${p.total ?? rows.length} WireGuard peer(s), ${p.connected ?? 0} connected`,
+    ...(rows.length ? pad([['PEER', 'IFACE', 'ENDPOINT', 'ALLOWED', 'HANDSHAKE', 'STATE'], ...rows]) : []),
+    ...(p.connected_rule ? [`Rule: ${p.connected_rule}`] : []),
+  ];
+}
+
+export function vpnLines(p) {
+  const h = p.health || {};
+  const out = [p.plain_english || `${p.tunnels_up ?? 0} of ${p.tunnels_total ?? 0} VPN tunnel(s) up.`, `Score: ${p.score === null || p.score === undefined ? '- (no tunnels)' : `${p.score}/100`}`];
+  for (const x of h.wireguard || []) out.push(`  wg peer ${peerRow(x)[0]}: ${peerRow(x)[5]} (handshake ${dash(x.last_handshake)})`);
+  for (const x of h.ipsec || []) out.push(`  ipsec ${dash(x.remote_address)}: ${dash(x.state)}, up ${dash(x.uptime)}`);
+  for (const i of p.issues || []) out.push(`! ${i}`);
+  return out;
+}
+
+export function inventoryLines(p) {
+  const routers = (p.routers || []).map((r) => [dash(r.identity || [r.platform, r.board_name].filter(Boolean).join(' ')), dash(r.role), dash(r.address), dash(r.version), dash(r.board_name)]);
+  const devices = (p.devices || []).map((d) => [dash(d.address), dash(d.mac), dash(d.host_name), dash(d.interface), d.seen_in_arp ? 'arp' : 'lease only']);
+  return [
+    `${p.router_count ?? routers.length} MikroTik router(s)`,
+    ...pad([['ROUTER', 'ROLE', 'ADDRESS', 'VERSION', 'BOARD'], ...routers]),
+    `${p.total ?? devices.length} connected device(s)`,
+    ...(devices.length ? pad([['ADDRESS', 'MAC', 'HOST', 'IFACE', 'SEEN'], ...devices]) : []),
+  ];
+}
+
+export const ROUTER_FORMATTERS = Object.freeze({
+  health: healthLines, leases: leaseLines, pools: poolLines, conflicts: conflictLines,
+  'free-ip': freeIpLines, vpn: vpnLines, wireguard: wireguardLines, inventory: inventoryLines,
+});
+
+/** `quox router trust --show`: the fingerprint to compare out of band. Pure. */
+export function formatTrust(d) {
+  if (!d || d.success === false) {
+    return [`Could not read the router certificate: ${(d && (d.error || d.detail)) || 'unknown error'}`, 'No credentials were sent.'];
+  }
+  const lines = [
+    `Router endpoint: ${d.host}:${d.port}`,
+    `Certificate SHA-256: ${d.cert_sha256_formatted}`,
+    `Public key SHA-256:  ${d.spki_sha256_formatted}`,
+    `Subject: ${d.subject ? String(d.subject).replace(/\n/g, ', ') : '-'}`,
+    `Issuer:  ${d.issuer ? String(d.issuer).replace(/\n/g, ', ') : '-'}${d.self_signed ? ' (self-signed)' : ''}`,
+    `Valid until: ${d.valid_to || '-'}`,
+    d.pin_configured
+      ? (d.matches_configured_pin ? 'MIKROTIK_TLS_PIN is set and MATCHES this endpoint.' : 'MIKROTIK_TLS_PIN is set and does NOT match this endpoint. Do not trust it until you know why.')
+      : 'MIKROTIK_TLS_PIN is not set, so the collector sends nothing to this router yet.',
+    'No credentials were sent. Nothing was pinned.',
+    'Compare the fingerprint with the one on the router itself (System > Certificates) over a channel you trust, then set MIKROTIK_TLS_PIN to the SHA-256 value.',
+  ];
+  return lines;
+}