@calltelemetry/cli 0.12.2 → 0.12.5

package/dist/lib/cube-diag.js

@@ -10,7 +10,9 @@
  * keepalive; this bundle surfaces the DB state, NATS KV view, and the log lines
  * that explain why that keepalive never lands.
  */
-import { writeFile, chmod } from 'node:fs/promises';
+import { writeFile, chmod, mkdir, symlink, unlink } from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { compose, composeExec, composePs } from './compose.js';
 import { exec } from './exec.js';
 import { rpc } from './rpc.js';
@@ -31,6 +33,16 @@ const LONG_TIMEOUT = 25_000;
 // timeout alone (API-1791 gap fix).
 const PG_OPTIONS_DEFAULT = "-c statement_timeout=5000 -c lock_timeout=1000";
 const PG_OPTIONS_LONG = "-c statement_timeout=15000 -c lock_timeout=2000";
+// Bridge leg BPF (docker backend leg — plaintext XCC/CURRI after Caddy
+// terminates TLS). Parity with the bash _cd_xcc_pcap_bridge_filter / Go
+// cubeDiagBridgePcapFilter.
+const PCAP_BRIDGE_FILTER = '(tcp port 4080 or tcp port 4000)';
+// Cube-router TLS port clause for the host NIC ingress leg. Parity with the
+// bash/Go port-only fallback when no xcc_hostname/source IP resolves.
+const PCAP_PORT_CLAUSE = '(tcp port 443 or tcp port 80)';
+// Only safe-shaped hostnames/IPs are allowed into a tcpdump BPF filter string
+// (parity with bash _cd_xcc_pcap_host_valid / Go cubeDiagValidPcapHost).
+const PCAP_HOST_RE = /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/;
 /** Sleep helper for the heartbeat-trace loop. */
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
@@ -96,6 +108,115 @@ Enum.each(cubes, fn c ->
   IO.puts(out)
 end)
 :ok`;
+/**
+ * Snapshot of the ProbeFastDiag fast-path counters (API-1838). Backend module
+ * ships on 0.8.7-stable; on an older appliance the module simply doesn't
+ * exist and this RPC errors or returns garbage — the renderer below must
+ * tolerate that (see `renderProbeFastDiag`).
+ *
+ * NOTE: same `${...}`-free rule as CUBE_DIAG_RPC_SNAPSHOT above (this one has
+ * no Elixir string interpolation at all, but keep the convention documented).
+ */
+const CUBE_DIAG_RPC_PROBE_FAST = `Cdrcisco.Cubes.ProbeFastDiag.snapshot() |> Jason.encode!() |> IO.puts()`;
+/**
+ * Render the probe_fast snapshot payload into the terse KeyValue-ish text
+ * block used by the rest of cube-diag's sections.
+ *
+ * Payload contract (extend-only; every leaf may independently be the string
+ * "unavailable", and the whole payload may be `{"error":"probe_fast_unavailable"}`):
+ *   - window_seconds:            number | "unavailable"
+ *   - counts:                    { handled, fallthrough, fault_contained } | "unavailable"
+ *   - fast_path_enabled:         boolean | "unavailable"
+ *   - budget:                    { wall_budget_ms, probe_wall_budget_ms,
+ *                                   call_control_statement_timeout_ms } | "unavailable"
+ *   - cube_config_cache_entries: number | "unavailable"
+ *
+ * On an appliance older than the module's release, the RPC either throws
+ * (caught by `section()`) or returns non-JSON / unrecognized JSON — both are
+ * treated as "unavailable", never a crash.
+ */
+function renderProbeFastDiag(raw) {
+    const trimmed = raw.trim();
+    const oldApplianceHint = 'probe fast-path diagnostics unavailable (appliance < 0.8.7-rc?)';
+    if (!trimmed)
+        return oldApplianceHint;
+    let payload;
+    try {
+        payload = JSON.parse(trimmed);
+    }
+    catch {
+        return oldApplianceHint;
+    }
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        return oldApplianceHint;
+    }
+    const obj = payload;
+    if (typeof obj.error === 'string') {
+        return `probe fast-path diagnostics unavailable (${obj.error})`;
+    }
+    // A recognizable payload needs at least one of the documented top-level
+    // keys — otherwise this is "unrecognized JSON", treat like an old appliance.
+    const knownKeys = ['window_seconds', 'counts', 'fast_path_enabled', 'budget', 'cube_config_cache_entries'];
+    if (!knownKeys.some(k => k in obj)) {
+        return oldApplianceHint;
+    }
+    const fmt = (v) => (v === undefined ? 'unavailable' : typeof v === 'string' ? v : JSON.stringify(v));
+    const lines = [];
+    lines.push(`window_seconds : ${fmt(obj.window_seconds)}`);
+    const counts = obj.counts;
+    let handled = 'unavailable';
+    let fallthrough = 'unavailable';
+    let faultContained = 'unavailable';
+    if (counts && typeof counts === 'object' && !Array.isArray(counts)) {
+        const c = counts;
+        handled = c.handled ?? 'unavailable';
+        fallthrough = c.fallthrough ?? 'unavailable';
+        faultContained = c.fault_contained ?? 'unavailable';
+    }
+    else if (counts !== undefined) {
+        // counts itself may be the literal string "unavailable".
+        handled = counts;
+        fallthrough = counts;
+        faultContained = counts;
+    }
+    lines.push(`counts         : handled=${fmt(handled)} fallthrough=${fmt(fallthrough)} fault_contained=${fmt(faultContained)}`);
+    lines.push(`fast_path      : enabled=${fmt(obj.fast_path_enabled)}`);
+    const budget = obj.budget;
+    let wallBudget = 'unavailable';
+    let probeWallBudget = 'unavailable';
+    let ccStatementTimeout = 'unavailable';
+    if (budget && typeof budget === 'object' && !Array.isArray(budget)) {
+        const b = budget;
+        wallBudget = b.wall_budget_ms ?? 'unavailable';
+        probeWallBudget = b.probe_wall_budget_ms ?? 'unavailable';
+        ccStatementTimeout = b.call_control_statement_timeout_ms ?? 'unavailable';
+    }
+    else if (budget !== undefined) {
+        wallBudget = budget;
+        probeWallBudget = budget;
+        ccStatementTimeout = budget;
+    }
+    lines.push(`budget_ms      : wall=${fmt(wallBudget)} probe_wall=${fmt(probeWallBudget)} call_control_statement_timeout=${fmt(ccStatementTimeout)}`);
+    lines.push(`cache_entries  : ${fmt(obj.cube_config_cache_entries)}`);
+    // Interpretive hint: only fires when we have real (numeric, positive)
+    // fallthrough/fault_contained counts — never on "unavailable" leaves — AND
+    // the fast path is actually enabled. With the kill switch OFF
+    // (fast_path_enabled === false) every probe deliberately takes the budgeted
+    // path, so positive fallthrough is EXPECTED, not a "missing the fast path"
+    // signal — emit a kill-switch note instead. When fast_path_enabled is
+    // unknown/"unavailable", stay silent rather than guess.
+    const isPositiveNumber = (v) => typeof v === 'number' && v > 0;
+    if (isPositiveNumber(fallthrough) || isPositiveNumber(faultContained)) {
+        if (obj.fast_path_enabled === true) {
+            lines.push('hint           : fallthrough/fault_contained > 0 -> probes are missing the fast path ' +
+                '(fallthrough: budgeted-path fallback; fault_contained: fast-path internal error contained)');
+        }
+        else if (obj.fast_path_enabled === false) {
+            lines.push('hint           : fast path disabled by kill switch -> fallthrough is expected');
+        }
+    }
+    return lines.join('\n');
+}
 /**
  * Compact one-line-per-cube trace sample, called repeatedly by the
  * `--monitor <secs>` heartbeat trace to capture how the FSM state / learned
@@ -242,11 +363,17 @@ async function containerId(service) {
     return '';
 }
 /**
- * Tail container logs and keep only the lines matching the cube/xcc keepalive
- * grep. When `opts.since` is given, uses `docker logs --since <window>` instead
- * of `--tail`, mirroring the bash reference's 10-minute heartbeat window.
+ * Fetch a container's raw combined stdout/stderr log tail, with NO grep
+ * filtering and NO truncation. Used both by `logsFiltered()` (which filters
+ * this down for display) and by the rejected-keepalive summary, which needs
+ * the full unfiltered fetch — parity with the bash/Go collectors, which scan
+ * the SAME raw `docker compose logs --tail=6000` fetch for the summary that
+ * they display (grep-)filtered and truncated to 800 lines. Reusing the
+ * post-filter/post-truncate text for the summary (an earlier version of this
+ * port did) could silently undercount rejections squeezed out by the 800-line
+ * cap even though they were present in the raw 6000-line fetch.
  */
-async function logsFiltered(service, tailIn, keepTail, grep, opts) {
+async function rawLogsTail(service, tailIn, opts) {
     const id = await containerId(service);
     if (!id)
         return `(no ${service} container found)`;
@@ -257,25 +384,321 @@ async function logsFiltered(service, tailIn, keepTail, grep, opts) {
         timeout: DEFAULT_TIMEOUT,
         reject: false,
     });
-    const combined = `${(result.stdout ?? '').toString()}\n${(result.stderr ?? '').toString()}`;
+    return `${(result.stdout ?? '').toString()}\n${(result.stderr ?? '').toString()}`;
+}
+/**
+ * Tail container logs and keep only the lines matching the cube/xcc keepalive
+ * grep. When `opts.since` is given, uses `docker logs --since <window>` instead
+ * of `--tail`, mirroring the bash reference's 10-minute heartbeat window.
+ */
+async function logsFiltered(service, tailIn, keepTail, grep, opts) {
+    const combined = await rawLogsTail(service, tailIn, opts);
     let lines = combined.split('\n');
     if (grep)
         lines = lines.filter(l => grep.test(l));
     return lines.slice(-keepTail).join('\n');
 }
+// ── XCC wire capture (--pcap) ────────────────────────────────────────────
+//
+// Two legs, parity with the bash _cd_xcc_pcap_* helpers and Go
+// cubeDiagBridgeIface/cubeDiagIngressIface/cubeDiagIngressPcapFilter*:
+//   - bridge:  the compose `_ct` network's docker bridge iface (br-<id[:12]>),
+//              filtered to the plaintext web:4080/CURRI:4000 backend leg.
+//   - ingress: the host's primary route-to-internet NIC, filtered to the
+//              cube-router TLS/HTTP leg (443/80) scoped to each xcc-enabled
+//              cube's hostname (+ resolved IP) and/or last-seen source IP —
+//              falling back to a port-only filter when nothing resolves, so
+//              the leg still captures traffic with zero DB load.
+/** True when every dot-separated segment is a valid IPv4 octet (0-255, no leading garbage). */
+function isValidIPv4(h) {
+    const parts = h.split('.');
+    if (parts.length !== 4)
+        return false;
+    return parts.every(p => /^\d{1,3}$/.test(p) && Number(p) <= 255);
+}
+/** True when `host` is safe to interpolate into a tcpdump BPF `host <x>` clause. */
+function validPcapHost(host) {
+    const h = host.trim();
+    if (!h)
+        return false;
+    // IPv4 literal — validated octet-by-octet so e.g. "999.999.999.999" or
+    // "1..2.3" (grok T1 P2: the old `/^[0-9.]+$/` + 4-segment check let both
+    // through, producing a useless BPF term with no surfaced error) is rejected.
+    if (/^[0-9.]+$/.test(h))
+        return isValidIPv4(h);
+    if (h.includes(':'))
+        return /^[0-9a-fA-F:]+$/.test(h);
+    return PCAP_HOST_RE.test(h);
+}
+/** Resolve the docker bridge interface backing the compose `_ct` network. */
+async function pcapBridgeIface(net) {
+    if (!net)
+        return '';
+    try {
+        const result = await exec('docker', ['network', 'inspect', net, '-f', '{{.Id}}'], {
+            timeout: DEFAULT_TIMEOUT,
+            reject: false,
+        });
+        const id = (result.stdout ?? '').toString().trim();
+        if (id.length < 12)
+            return '';
+        const bridge = `br-${id.slice(0, 12)}`;
+        const check = await exec('ip', ['link', 'show', bridge], { timeout: DEFAULT_TIMEOUT, reject: false });
+        return check.exitCode === 0 ? bridge : '';
+    }
+    catch (err) {
+        debug(`cube-diag: pcap bridge iface resolve failed: ${err instanceof Error ? err.message : String(err)}`);
+        return '';
+    }
+}
+/** Resolve the primary host NIC used to reach the internet (cube TLS ingress). */
+async function pcapIngressIface() {
+    try {
+        const result = await exec('ip', ['-o', 'route', 'get', '1.1.1.1'], { timeout: DEFAULT_TIMEOUT, reject: false });
+        const out = (result.stdout ?? '').toString().trim();
+        const fields = out.split(/\s+/);
+        const idx = fields.indexOf('dev');
+        return idx >= 0 && idx + 1 < fields.length ? fields[idx + 1] : '';
+    }
+    catch (err) {
+        debug(`cube-diag: pcap ingress iface resolve failed: ${err instanceof Error ? err.message : String(err)}`);
+        return '';
+    }
+}
 /**
- * Collect the full cube-diag bundle and write it to a single .log file.
+ * Build the ingress BPF filter from resolved xcc_hostname values (+ DNS) and
+ * per-cube last-seen source IPs. Falls back to a port-only filter when
+ * nothing resolves, so the leg still captures every cube's traffic with zero
+ * DB load — parity with bash/Go.
+ */
+async function pcapIngressFilter() {
+    const seen = new Set();
+    const parts = [];
+    const addHost = (host) => {
+        const h = host.trim();
+        if (!validPcapHost(h) || seen.has(h))
+            return;
+        seen.add(h);
+        parts.push(`host ${h}`);
+    };
+    let hostnameRows = '';
+    try {
+        hostnameRows = await psql(`SELECT DISTINCT xcc_hostname FROM cubes WHERE xcc_enabled = true AND xcc_hostname IS NOT NULL AND xcc_hostname <> '' ORDER BY 1;`);
+    }
+    catch (err) {
+        debug(`cube-diag: pcap hostname query failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    for (const raw of hostnameRows.split('\n')) {
+        const h = raw.trim();
+        if (!h || h.includes('xcc_hostname') || h.startsWith('-') || h.startsWith('('))
+            continue;
+        addHost(h);
+        try {
+            const resolved = await exec('getent', ['hosts', h], { timeout: DEFAULT_TIMEOUT, reject: false });
+            const ip = (resolved.stdout ?? '').toString().trim().split(/\s+/)[0];
+            if (ip)
+                addHost(ip);
+        }
+        catch {
+            // DNS resolution best-effort only.
+        }
+    }
+    // Per-cube NAT/VIP source IPs: index seek (cube_id, inserted_at DESC) LIMIT 1
+    // per enabled cube (~dozens of rows), NOT a `SELECT DISTINCT ip_address ...
+    // 24h` scan over the whole hot partition (API-1791 lesson — never regress
+    // this to a table-wide scan). Routed through psqlLong (15s statement_timeout)
+    // rather than the 5s default: it's the same LATERAL-over-cube_event_logs
+    // shape as the "24h volume per cube" section, which already needs the long
+    // budget under SQL distress (grok T1 P2 — falling back to port-only on a
+    // timeout here silently loses host-scoped capture).
+    let ipRows = '';
+    try {
+        ipRows = await psqlLong(`SELECT e.ip_address FROM cubes c CROSS JOIN LATERAL (SELECT ip_address FROM cube_event_logs WHERE cube_id = c.id AND inserted_at > NOW() - INTERVAL '24 hours' AND ip_address IS NOT NULL AND ip_address <> '' ORDER BY inserted_at DESC LIMIT 1) e WHERE c.xcc_enabled = true;`);
+    }
+    catch (err) {
+        debug(`cube-diag: pcap source-ip query failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    for (const raw of ipRows.split('\n')) {
+        addHost(raw.trim());
+    }
+    if (parts.length === 0)
+        return PCAP_PORT_CLAUSE;
+    return `(${parts.join(' or ')}) and ${PCAP_PORT_CLAUSE}`;
+}
+/** Stat a pcap file for the report (size in bytes, or "not created"). */
+function pcapStatLine(label, path) {
+    try {
+        const st = statSync(path);
+        return `  ${label}: ${path} (${st.size} bytes)`;
+    }
+    catch {
+        return `  ${label}: (not created)`;
+    }
+}
+/**
+ * Run the two-leg XCC wire capture (bridge + host ingress) for `secs` seconds,
+ * writing pcap files alongside the bundle's report and symlinking a
+ * `xcc.pcap` compat name to whichever leg actually captured bytes — parity
+ * with the bash/Go collectors' `--pcap <secs>` option (a gap this TS port
+ * never had until now).
+ */
+async function collectPcap(net, secs, bundleDir) {
+    if (process.env.CT_CLI_TEST_NO_TCPDUMP === '1') {
+        return '(pcap skipped: CT_CLI_TEST_NO_TCPDUMP=1)';
+    }
+    const tcpdumpCheck = await exec('sh', ['-c', 'command -v tcpdump'], { timeout: DEFAULT_TIMEOUT, reject: false });
+    if (tcpdumpCheck.exitCode !== 0) {
+        return '(pcap skipped: tcpdump unavailable)';
+    }
+    // Private-then-publish, same invariant as the report bundle: an interrupted
+    // pcap run must never leave a world-readable directory. mkdir's `mode` only
+    // applies on CREATE (parity with writeFile's mode caveat elsewhere in this
+    // file), so also clamp with chmod in case the directory already existed
+    // with broader perms (e.g. a caller re-running against the same --output
+    // parent dir).
+    await mkdir(bundleDir, { recursive: true, mode: 0o700 });
+    await chmod(bundleDir, 0o700).catch(() => { });
+    const bridgePath = join(bundleDir, 'xcc-bridge.pcap');
+    const ingressPath = join(bundleDir, 'xcc-ingress.pcap');
+    const compatPath = join(bundleDir, 'xcc.pcap');
+    const lines = [];
+    const bridgeIface = await pcapBridgeIface(net);
+    const ingressIface = await pcapIngressIface();
+    const ingressFilter = await pcapIngressFilter();
+    // Returns a `[failed exit=N] stderr` note when tcpdump/sudo/timeout itself
+    // failed (permission denied, bad interface, bad filter), so a silent 0-byte
+    // capture isn't the only signal (grok T1 P2 — reject:false swallowed
+    // exitCode/stderr entirely before this).
+    const runTcpdump = async (iface, filter, outPath) => {
+        const hostBudget = String(secs + 5);
+        const result = await exec('timeout', [hostBudget, 'sudo', 'timeout', String(secs), 'tcpdump', '-i', iface, '-s', '0', '-w', outPath, ...filter.split(' ')], { timeout: (secs + 10) * 1000, reject: false });
+        const exitCode = result.exitCode;
+        if (exitCode !== undefined && exitCode !== 0) {
+            const stderr = (result.stderr ?? '').toString().trim();
+            return `  [tcpdump failed: exit=${exitCode}]${stderr ? ` ${stderr}` : ''}`;
+        }
+        return '';
+    };
+    if (bridgeIface) {
+        lines.push(`  bridge ${bridgeIface}: ${PCAP_BRIDGE_FILTER}`);
+        const failNote = await runTcpdump(bridgeIface, PCAP_BRIDGE_FILTER, bridgePath);
+        if (failNote)
+            lines.push(failNote);
+        lines.push(pcapStatLine('bridge', bridgePath));
+    }
+    if (ingressIface && ingressFilter) {
+        lines.push(`  ingress ${ingressIface}: ${ingressFilter}`);
+        const failNote = await runTcpdump(ingressIface, ingressFilter, ingressPath);
+        if (failNote)
+            lines.push(failNote);
+        lines.push(pcapStatLine('ingress', ingressPath));
+    }
+    if (!bridgeIface && !(ingressIface && ingressFilter)) {
+        lines.push('  (no bridge or ingress interface resolved — pcap skipped)');
+    }
+    // Compat symlink: prefer whichever leg actually captured bytes (pcap header
+    // alone is 24 bytes), bridge first — parity with bash/Go.
+    const hasBytes = (p) => {
+        try {
+            return statSync(p).size > 24;
+        }
+        catch {
+            return false;
+        }
+    };
+    try {
+        if (hasBytes(bridgePath)) {
+            await unlink(compatPath).catch(() => { });
+            await symlink('xcc-bridge.pcap', compatPath);
+        }
+        else if (hasBytes(ingressPath)) {
+            await unlink(compatPath).catch(() => { });
+            await symlink('xcc-ingress.pcap', compatPath);
+        }
+    }
+    catch (err) {
+        debug(`cube-diag: pcap compat symlink failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    lines.push(pcapStatLine('xcc.pcap (compat)', compatPath));
+    return lines.join('\n');
+}
+// ── Rejected-keepalive summary (API-1792 parity) ────────────────────────────
+//
+// Distinct api_key_prefix x distinct source_ip x count table, so a stale CUBE
+// key (many events, one key, one/few IPs) is visually distinguishable from a
+// stale CUCM ECC profile (many events, many keys, one router IP). Scoped to
+// keepalive rejections specifically — parity with the bash/Go collectors'
+// `_cd_shell "web XCC/cube logs..."` / cubeDiagRejectedKeepaliveSummary gate.
+const REJECTED_RE = /CURRI edge rejected request|CurriController: Unknown policy|CurriController:.*rejected.*suppressed/i;
+const KEEPALIVE_RE = /endpoint=keepalive|on keepalive|rejected keepalive/i;
+const API_KEY_PREFIX_VAL_RE = /api[_-]?key[_-]?prefix=([^\s,;]+)/i;
+const REMOTE_IP_VAL_RE = /remote_ip=([^\s,;]+)/;
+const SOURCE_IP_VAL_RE = /source_ip=([^\s,;]+)/;
+/**
+ * Parse rejected-keepalive / unknown-policy web log lines into a distinct
+ * api_key_prefix x distinct source_ip x count table.
+ */
+function rejectedKeepaliveSummary(webLog) {
+    // Keyed by a JSON-encoded [prefix, ip] tuple rather than a delimited string —
+    // both fields come from a `[^\s,;]+` capture so they can never themselves
+    // contain the delimiter, but encoding the pair avoids relying on that
+    // invariant to safely split the key back apart.
+    const counts = new Map();
+    const prefixes = new Set();
+    const ips = new Set();
+    let total = 0;
+    for (const line of webLog.split('\n')) {
+        if (!REJECTED_RE.test(line) || !KEEPALIVE_RE.test(line))
+            continue;
+        const prefixMatch = API_KEY_PREFIX_VAL_RE.exec(line);
+        const prefix = prefixMatch ? prefixMatch[1] : '(unknown)';
+        const ipMatch = REMOTE_IP_VAL_RE.exec(line) ?? SOURCE_IP_VAL_RE.exec(line);
+        const ip = ipMatch ? ipMatch[1] : '(unknown)';
+        const key = JSON.stringify([prefix, ip]);
+        const existing = counts.get(key);
+        if (existing) {
+            existing.count++;
+        }
+        else {
+            counts.set(key, { prefix, ip, count: 1 });
+        }
+        prefixes.add(prefix);
+        ips.add(ip);
+        total++;
+    }
+    if (total === 0)
+        return '(no rejected-keepalive / unknown-policy lines in window)';
+    const rows = Array.from(counts.values());
+    rows.sort((a, b) => (b.count - a.count) || a.prefix.localeCompare(b.prefix) || a.ip.localeCompare(b.ip));
+    const lines = [];
+    lines.push(`distinct api_key_prefix: ${prefixes.size}   distinct source_ip: ${ips.size}   total rejected: ${total}`);
+    lines.push('');
+    lines.push(`${'api_key_prefix'.padEnd(18)} ${'source_ip'.padEnd(18)} count`);
+    for (const r of rows) {
+        lines.push(`${r.prefix.padEnd(18)} ${r.ip.padEnd(18)} ${r.count}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Collect the full cube-diag bundle and write it to a single .log file (plus,
+ * when `--pcap` is requested, sibling `xcc-bridge.pcap` / `xcc-ingress.pcap` /
+ * `xcc.pcap` files in the same directory as `outputPath`).
  *
  * @param opts.outputPath  Target log path. Defaults to ./cube-diag-<ISO>.log.
  * @param opts.captureSecs Seconds to live-capture cube.> / alarms.> subjects (0 = skip).
  * @param opts.monitorSecs Seconds to RPC-poll each cube's state/interval ~every 5s (0 = skip).
+ * @param opts.pcapSecs    Seconds to tcpdump the XCC wire (bridge + host TLS ingress legs, 0 = skip).
  * @returns the path the bundle was written to.
  */
 export async function collectCubeDiag(opts) {
     const captureSecs = opts?.captureSecs ?? 0;
     const monitorSecs = opts?.monitorSecs ?? 0;
+    const pcapSecs = opts?.pcapSecs ?? 0;
     const iso = new Date().toISOString().replace(/[:.]/g, '-');
     const outputPath = opts?.outputPath ?? `./cube-diag-${iso}.log`;
+    // pcap files land beside the report — same directory as outputPath, so a
+    // custom --output still keeps the bundle together on disk.
+    const bundleDir = dirname(outputPath) || '.';
     const parts = [];
     parts.push('===== CUBE DIAGNOSTIC BUNDLE =====', `Generated: ${new Date().toISOString()}`, 'Bug class: cube stuck REGISTERED, never ONLINE (registered->online requires a healthy SolicitXccProbing keepalive).');
     // ── Database sections ──────────────────────────────────────────────────
@@ -329,6 +752,14 @@ export async function collectCubeDiag(opts) {
     // mismatch, DB-vs-KV divergence). This is where a "shows 10s, router is 15s"
     // stuck cube is caught.
     parts.push(await section('cube interval + KV health (RPC-decoded)', () => rpcBounded(CUBE_DIAG_RPC_SNAPSHOT)));
+    // ── Probe fast-path diagnostics (API-1838) ──────────────────────────────
+    // Best-effort like every other section: an old appliance (module doesn't
+    // exist yet) or a malformed/errored payload degrades to a one-line hint
+    // instead of aborting the bundle.
+    parts.push(await section('probe fast-path diagnostics (probe_fast)', async () => {
+        const raw = await rpcBounded(CUBE_DIAG_RPC_PROBE_FAST);
+        return renderProbeFastDiag(raw);
+    }));
     // ── Optional RPC heartbeat trace ────────────────────────────────────────
     // Polls the compact per-cube snapshot every ~5s for the window so engineering
     // can watch the FSM state / learned cadence / freshness window evolve.
@@ -370,15 +801,66 @@ export async function collectCubeDiag(opts) {
             }));
         }
     }
+    // ── Optional XCC wire capture (--pcap) ──────────────────────────────────
+    // Two legs, overlapping the monitor/capture windows above: bridge (docker
+    // backend leg) + host TLS ingress (cube-router leg). Parity gap fix — the
+    // bash and Go collectors have shipped this since PR #430; this port never
+    // had it until now.
+    if (pcapSecs > 0) {
+        parts.push(await section(`XCC pcap (${pcapSecs}s, bridge web:4080 + host TLS ingress)`, () => collectPcap(net, pcapSecs, bundleDir)));
+    }
     // ── Log sections ───────────────────────────────────────────────────────
     // Heartbeat timeline first: the failure_count progression, "did not refresh
     // healthy" gate hits, and registration rotations are the stuck/flap signature.
     const heartbeatGrep = /failure_count|did not refresh healthy|registrationID rotated|keepalive/i;
     parts.push(await section('probe heartbeat timeline (failure_count / refresh / rotation, last 10m)', () => logsFiltered('web', 6000, 200, heartbeatGrep, { since: '10m' })));
+    // Fetched ONCE (raw, unfiltered, untruncated) and reused by both sections
+    // below — parity with the bash/Go collectors, which scan the SAME raw
+    // `docker compose logs --tail=6000` fetch for both the filtered display and
+    // the rejected-keepalive summary. Scanning the already-grep-filtered/800-
+    // truncated text for the summary (as an earlier version of this port did)
+    // could silently undercount rejections squeezed out of the display window
+    // even though they were present in the raw 6000-line fetch (grok T1 P2).
+    // Captured outside section() so a failure here still degrades both
+    // sections independently, matching the original per-section isolation
+    // guarantee — rawLogsTail itself never throws (containerId()/exec() are
+    // already best-effort internally), but this keeps that invariant explicit
+    // rather than assumed.
+    let webLogRaw = '';
+    let webLogErr = null;
     const cubeGrep = /xcc|cube|keepalive|solicit|probing|register|authorize|reconnect|liveness|connection_state/i;
-    parts.push(await section('LOGS: web (filtered, tail 800)', () => logsFiltered('web', 6000, 800, cubeGrep)));
+    try {
+        webLogRaw = await rawLogsTail('web', 6000);
+    }
+    catch (err) {
+        webLogErr = err instanceof Error ? err.message : String(err);
+    }
+    parts.push(await section('LOGS: web (filtered, tail 800)', async () => {
+        if (webLogErr !== null)
+            throw new Error(webLogErr);
+        const lines = webLogRaw.split('\n').filter(l => cubeGrep.test(l));
+        return lines.slice(-800).join('\n');
+    }));
+    // API-1792 parity: rejected-keepalive summary — distinct api_key_prefix x
+    // distinct source_ip x count. Scans the raw (unfiltered, untruncated) web
+    // log tail fetched above rather than a second docker exec.
+    parts.push(await section('Rejected-Keepalive Summary (api_key_prefix x source_ip)', async () => {
+        if (webLogErr !== null)
+            throw new Error(webLogErr);
+        return rejectedKeepaliveSummary(webLogRaw);
+    }));
     parts.push(await section('LOGS: nats (tail 300)', () => logsFiltered('nats', 300, 300, null)));
     const bundle = redactSecrets(parts.join('\n') + '\n');
+    // Create the bundle directory private (mkdir handles the case where
+    // outputPath's directory doesn't exist yet, e.g. a custom --output nested
+    // path) BEFORE writing, mirroring the bash/Go "private then publish"
+    // pattern: an interrupted run should never leave a world-readable partial
+    // bundle. writeFile's own 0o600 mode covers report.log. When pcapSecs > 0,
+    // collectPcap() has already hardened (and re-clamped) this same directory
+    // before writing any pcap file, so this call is a no-op in that case.
+    if (bundleDir !== '.' && !existsSync(bundleDir)) {
+        await mkdir(bundleDir, { recursive: true, mode: 0o700 });
+    }
     await writeFile(outputPath, bundle, { mode: 0o600 });
     // `mode` only applies when writeFile CREATES the file. If outputPath already
     // existed with broader perms, the write truncates but leaves the old mode, so