ccdeck 3.24.1 → 3.26.0

package/src/server/port-holder.mjs

@@ -0,0 +1,66 @@
+// Which program holds a UDP port, in the words the LAN panel prints.
+//
+// A deck that cannot bind the discovery port says so, and "another program"
+// is a sentence nobody can act on. On the Mac where this was measured the
+// program was Tailscale, and finding that out took netstat and an hour. The
+// operating system will usually say, without elevation, and when it will not
+// the sentence stays the one it was.
+//
+// Pure readers per platform, and one runner that picks the command; nothing
+// here is ever a reason for the deck to fail.
+import { run as runCommand } from "./exec.mjs";
+
+/**
+ * macOS: `netstat -anv -p udp` lists every UDP socket with its owner as
+ * `name:pid` in the process column — readable by a plain user for sockets of
+ * any user, which is the reason this is the Mac's answer.
+ */
+export function holderFromNetstat(text, port) {
+  const at = new RegExp(`[.:]${port}\\s`);
+  for (const line of String(text ?? "").split("\n")) {
+    if (!/^udp/.test(line) || !at.test(line.split(/\s+/).slice(0, 5).join(" ") + " ")) continue;
+    const owner = line.split(/\s+/).find(f => /^[A-Za-z][\w.-]*:\d+$/.test(f));
+    if (owner) return owner.replace(/:\d+$/, "");
+  }
+  return null;
+}
+
+/** Linux: `ss -H -uanp 'sport = :PORT'` — `users:(("name",pid=…))`, shown
+ *  only for this user's own processes; somebody else's is an unnamed row. */
+export function holderFromSs(text) {
+  const m = /users:\(\("([^"]+)"/.exec(String(text ?? ""));
+  return m ? m[1] : null;
+}
+
+/** Windows: the owning process's name, one line, from the PowerShell below. */
+export function holderFromPowershell(text) {
+  const name = String(text ?? "").split(/\r?\n/).map(l => l.trim()).find(Boolean);
+  return name && /^[\w .()-]{1,64}$/.test(name) ? name : null;
+}
+
+/** The name a person knows the program by. Tailscale is the one measured,
+ *  and it goes by a different process name on each platform. */
+export function friendlyHolder(name) {
+  if (!name) return null;
+  if (/tailscale/i.test(name)) return "Tailscale";
+  return name;
+}
+
+/** Who holds UDP `port` here, or null when the machine will not say. */
+export async function portHolder(port, { platform = process.platform, run = runCommand } = {}) {
+  try {
+    if (platform === "darwin") {
+      const r = await run("netstat", ["-anv", "-p", "udp"], { timeout: 5_000 });
+      return friendlyHolder(r?.ok ? holderFromNetstat(r.stdout, port) : null);
+    }
+    if (platform === "win32") {
+      const ps = `Get-NetUDPEndpoint -LocalPort ${Number(port)} -ErrorAction SilentlyContinue | Select-Object -First 1 | ForEach-Object { (Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue).ProcessName }`;
+      const r = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", ps], { timeout: 15_000 });
+      return friendlyHolder(r?.ok ? holderFromPowershell(r.stdout) : null);
+    }
+    const r = await run("ss", ["-H", "-uanp", `sport = :${Number(port)}`], { timeout: 5_000 });
+    return friendlyHolder(r?.ok ? holderFromSs(r.stdout) : null);
+  } catch {
+    return null;
+  }
+}

package/src/server/route-via.mjs

@@ -0,0 +1,109 @@
+// Which interface the machine would send a packet to an address by.
+//
+// A BEACON FOR THE LOCAL NETWORK MUST STAY ON IT. A laptop using a Tailscale
+// exit node, or any VPN that takes the local network too, routes even a
+// broadcast for its own Wi-Fi into the tunnel — and on the far end it comes out
+// on somebody else's network: an office Mac that is the exit node for a home
+// laptop put the laptop's beacons on the office LAN, where a colleague whose
+// network uses the same addresses could see the name of a machine that is
+// nothing to do with them. So before a beacon goes, the machine is asked where
+// it would go, and a beacon that would leave through a tunnel does not leave.
+//
+// Asked of the operating system rather than reasoned from interface names,
+// because only the routing table knows what a VPN did to it: `route get` on
+// macOS, `ip route get` on Linux, Find-NetRoute on Windows. The answers are
+// cached, since routes change when networks do and not every thirty seconds,
+// and a lookup that fails or cannot be made answers nothing — the beacon then
+// goes as it always did.
+import { run as runCommand } from "./exec.mjs";
+
+/** How long one answer is kept. Long enough that a Windows machine starts one
+ *  PowerShell every couple of minutes rather than every beacon; short enough
+ *  that turning an exit node on stops the beacons into it soon after. */
+export const ROUTE_TTL_MS = 120_000;
+
+/** `route -n get <ip>` on macOS: the `interface:` line. */
+export function viaFromRouteGet(text) {
+  const m = /^\s*interface:\s*(\S+)/m.exec(String(text ?? ""));
+  return m ? m[1] : null;
+}
+
+/** `ip -o route get <ip>` on Linux: the device after `dev`. */
+export function viaFromIpRoute(text) {
+  const m = /\bdev\s+(\S+)/.exec(String(text ?? ""));
+  return m ? m[1] : null;
+}
+
+/** The PowerShell below prints `address|alias` per line on Windows. */
+export function viaFromFindNetRoute(text) {
+  const out = new Map();
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    const at = line.indexOf("|");
+    if (at <= 0) continue;
+    const alias = line.slice(at + 1).trim();
+    if (alias) out.set(line.slice(0, at).trim(), alias);
+  }
+  return out;
+}
+
+/**
+ * Whether an interface is a tunnel rather than a network a person is on.
+ *
+ * Used only for the limited broadcast, which belongs to no one interface: a
+ * directed broadcast is judged by whether it leaves by the interface whose
+ * subnet it is, which needs no names at all. These are the names tunnels go
+ * by on the three platforms — macOS numbers every VPN `utun`, and a Windows
+ * adapter is called whatever its VPN named it.
+ */
+export function looksLikeTunnel(name) {
+  if (typeof name !== "string" || !name) return false;
+  return /^(utun|tun|tap|wg|ppp|ipsec|gpd|zt)\d*$/i.test(name)
+    || /tailscale|wireguard|nordlynx|openvpn|vpn/i.test(name);
+}
+
+const QUAD = /^\d{1,3}(\.\d{1,3}){3}$/;
+
+/** Ask the machine, for every address in `targets`, which interface it would
+ *  use. A Map of address to interface name; missing where it would not say. */
+export async function lookupRoutes(targets, { platform = process.platform, run = runCommand } = {}) {
+  const list = targets.filter(t => typeof t === "string" && QUAD.test(t));
+  const out = new Map();
+  if (!list.length) return out;
+  if (platform === "win32") {
+    const quoted = list.map(t => `'${t}'`).join(",");
+    const ps = `foreach($t in @(${quoted})){ $r = Find-NetRoute -RemoteIPAddress $t -ErrorAction SilentlyContinue | Where-Object { $_.InterfaceAlias } | Select-Object -First 1; $t + '|' + $r.InterfaceAlias }`;
+    const r = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", ps], { timeout: 15_000 });
+    return r?.ok ? viaFromFindNetRoute(r.stdout) : out;
+  }
+  for (const t of list) {
+    const r = platform === "darwin"
+      ? await run("route", ["-n", "get", t], { timeout: 3_000 })
+      : await run("ip", ["-o", "route", "get", t], { timeout: 3_000 });
+    const via = r?.ok ? (platform === "darwin" ? viaFromRouteGet(r.stdout) : viaFromIpRoute(r.stdout)) : null;
+    if (via) out.set(t, via);
+  }
+  return out;
+}
+
+/**
+ * The cache the beacon reads synchronously: `via(address)` is the last answer
+ * or undefined, and `want(addresses)` starts one lookup for whichever of them
+ * are missing or stale. Never more than one lookup at a time.
+ */
+export function createRouteCheck({ platform = process.platform, run = runCommand, now = Date.now, ttlMs = ROUTE_TTL_MS } = {}) {
+  const cache = new Map();
+  let busy = null;
+  return {
+    via: to => cache.get(to)?.via,
+    want(targets) {
+      if (busy) return busy;
+      const stale = (targets ?? []).filter(t => { const c = cache.get(t); return !c || now() - c.at > ttlMs; });
+      if (!stale.length) return Promise.resolve();
+      busy = lookupRoutes(stale, { platform, run })
+        .then(found => { for (const t of stale) cache.set(t, { via: found.get(t) ?? null, at: now() }); })
+        .catch(() => { /* nothing learned; the beacon goes as it always did */ })
+        .finally(() => { busy = null; });
+      return busy;
+    },
+  };
+}

package/src/server/self-update.mjs

@@ -22,6 +22,7 @@
 // it by name and only where it can actually work: a global install, on a
 // directory we can write, outside a git checkout and outside an npx cache.
 // Everywhere else this stays what it has always been — a printed command.
+import { inApp } from "./app-host.mjs";
 import { accessSync, constants as FS, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
@@ -1085,7 +1086,9 @@ export function upgradeBlock(pkgRoot) {
     // npm -g rewrites the package directory and its parent (the global
     // node_modules), so both have to be ours to write.
     writable: dirWritable(target) && dirWritable(resolve(target, "..")),
-    optedOut: process.env.AGENTS_DECK_NO_INSTALL === "1",
+    // Inside the desktop app the app updates itself; an `npm i -g` here would
+    // install a copy it never runs (app-host.mjs).
+    optedOut: process.env.AGENTS_DECK_NO_INSTALL === "1" || inApp(),
     // Whether the package that write would fetch is still a deck. Kept out of
     // the pure rule above, like every other input here, so the policy stays one
     // readable expression and this file owns the filesystem half of it.
@@ -1461,7 +1464,8 @@ export async function versionReport({ running, pkgRoot, name = PUBLISHED_NAME, n
   // isOlder decides that, not this.
   const skipRegistry =
     process.env.AGENTS_DECK_NO_UPDATE_CHECK === "1" ||
-    process.env.AGENTS_DECK_NO_INSTALL === "1";
+    process.env.AGENTS_DECK_NO_INSTALL === "1" ||
+    inApp();
   const latest = skipRegistry ? null : await latestOnNpm(asked, now, force);
   const marker = skipRegistry ? null : readMarker(asked);
   const blocked = upgradeBlock(pkgRoot);

package/src/server/system-metrics.mjs

@@ -18,8 +18,15 @@
 // readout the loudest producer in the application. So this is a plain poll
 // endpoint, exactly like /api/quota and /api/codex-usage already are.
 import { spawn } from "node:child_process";
-import { readdir, readFile } from "node:fs/promises";
+import { lookup } from "node:dns/promises";
+import { access, readdir, readFile } from "node:fs/promises";
+import net from "node:net";
 import os from "node:os";
+import { hasClaudeInstalled } from "./claude-dir.mjs";
+import {
+  classifyRoute, parseNetstatE, parseNetstatIbn, parseProcNetDev, rateBetween,
+  routeIfaceDarwin, routeIfaceLinux, routeLabel, tailscaleExitFromStatus,
+} from "./network-metrics.mjs";
 
 /** CPU is the metric with spikes, so it is sampled often enough to catch one. */
 const CPU_INTERVAL_MS = 3_000;
@@ -1690,9 +1697,44 @@ function seriesFor(group) {
     }];
   }
 
+  if (group === "network") {
+    // Download and upload are two charts, not two lines on one: upload is
+    // usually a hundredth of download, and on a shared scale it is a line along
+    // the floor. Each gets a top fitted to its own peak. No bands: there is no
+    // throughput that is too much, only more than usual, and a threshold here
+    // would be a number this module made up.
+    const down = at("net:down");
+    const up = at("net:up");
+    const api = at("net:api");
+    const series = [
+      // Floors of 100 KB/s and 100 ms, so a quiet line is drawn as quiet.
+      { key: "net:down", label: "Download", unit: "B/s", top: niceTop(down, 100_000), warnAt: null, critAt: null, restsAtZero: false, points: down },
+      { key: "net:up", label: "Upload", unit: "B/s", top: niceTop(up, 100_000), warnAt: null, critAt: null, restsAtZero: false, points: up },
+      { key: "net:api", label: "Claude API latency", unit: "ms", top: niceTop(api, 100), warnAt: null, critAt: null, restsAtZero: false, points: api },
+    ].filter(s => s.points.length);
+    // The path the traffic took, as marks on the last chart — the question the
+    // section exists for is "was it the VPN", and a line that jumps where a
+    // mark sits answers it without a legend.
+    const since = history.length ? history[0].m * BUCKET_MS : 0;
+    const changes = routeLog.filter(c => c.t >= since).map(c => ({ t: c.t, label: c.label, from: c.from }));
+    if (series.length && changes.length) series[series.length - 1].changes = changes;
+    return series;
+  }
+
   return [];
 }
 
+/** A scale top a person would choose — 1, 2 or 5 times a power of ten — just
+ *  above the peak, and never below `floor`, so an idle line is not drawn as a
+ *  dramatic climb. */
+function niceTop(points, floor) {
+  const peak = points.reduce((a, p) => Math.max(a, p.v), 0);
+  const want = Math.max(floor, peak * 1.15);
+  const pow = 10 ** Math.floor(Math.log10(want));
+  for (const m of [1, 2, 5, 10]) if (m * pow >= want) return m * pow;
+  return want;
+}
+
 /**
  * Whether this machine has been held back AT ALL since the deck started, and
  * when it last was.
@@ -1854,23 +1896,219 @@ function sampleCpu() {
   if (process.platform !== "win32") record("load:1m", Math.round(load[0] * 100) / 100);
 }
 
+// ── the network ────────────────────────────────────────────────────────────
+//
+// Three readings, taken at two very different costs (network-metrics.mjs says
+// why these three). THROUGHPUT is two counters the kernel already keeps, so it
+// rides its own five-second timer for the life of the process like CPU does,
+// and its history is as complete as every other section's. LATENCY and ROUTE
+// leave the machine or spawn a process, so they are taken only while somebody
+// is looking: the panel is the only thing that polls /api/system, and a probe
+// runs only within NET_ASKED_MS of that poll. A deck left open in a background
+// tab all day makes no connection it was not asked for — the rule Claude FM's
+// probe already follows ("makes no request until a page asks for one").
+
+/** Counters on Linux are a file read; on macOS and Windows one short command.
+ *  Five seconds is often enough to catch a burst and rare enough that the
+ *  command costs nothing anybody could measure. */
+const NET_INTERVAL_MS = 5_000;
+/** How often the far end is asked, while the panel is open. */
+const NET_PROBE_MS = 30_000;
+/** How recently a poll must have come for the probe to run at all. */
+const NET_ASKED_MS = 20_000;
+/** A probe older than this is from before the panel was last closed, and is
+ *  not reported as the present. */
+const NET_STALE_MS = NET_PROBE_MS * 2 + 5_000;
+/** What "how far is Claude" is measured against: the host every request Claude
+ *  Code makes goes to, and the one quota.mjs already reads from. */
+const API_HOST = "api.anthropic.com";
+const API_PORT = 443;
+const CONNECT_TIMEOUT_MS = 4_000;
+/** Where the route is asked for when there is no API address to ask about. A
+ *  routing-table lookup sends no packet, so this contacts nobody. */
+const ROUTE_FALLBACK = "1.1.1.1";
+/** Route changes kept for the history's markers. A path changes a handful of
+ *  times a day; forty is several days of it. */
+const ROUTE_LOG = 40;
+
+let netTimer = null;
+let netInFlight = false;
+let prevNet = null;
+let netRate = null;
+let physical = null;
+let physicalAt = 0;
+let probeTimer = null;
+/** Whether this process may reach out at all. Off unless the server says so:
+ *  the suite starts this module in dozens of cases, and none of them should
+ *  open a connection to Anthropic or spawn `ip` and `tailscale` to do it. */
+let probeEnabled = false;
+let probeInFlight = false;
+let probeAt = 0;
+let askedAt = 0;
+/** Undefined until measured, null when the host could not be reached. */
+let apiMs;
+let route = null;
+const routeLog = [];
+
+/** Interfaces that are hardware, by the one test the kernel offers: a
+ *  `device` link under /sys/class/net. Rechecked each minute, because a dock or
+ *  a phone tethered over USB is a new wire. */
+async function physicalInterfaces(root = "/sys/class/net") {
+  try {
+    const names = await readdir(root);
+    const real = await Promise.all(names.map(n => access(`${root}/${n}/device`).then(() => n, () => null)));
+    return new Set(real.filter(Boolean));
+  } catch { return null; }
+}
+
+async function readNetCounters(platform = process.platform) {
+  if (platform === "linux") {
+    if (!physical || Date.now() - physicalAt > 60_000) {
+      physical = await physicalInterfaces();
+      physicalAt = Date.now();
+    }
+    try {
+      const include = physical?.size ? name => physical.has(name) : name => name !== "lo";
+      return parseProcNetDev(await readFile("/proc/net/dev", "utf8"), include);
+    } catch { return null; }
+  }
+  if (platform === "darwin") return parseNetstatIbn(await run("netstat", ["-ibn"]));
+  if (platform === "win32") return parseNetstatE(await run("netstat", ["-e"]));
+  return null;
+}
+
+async function sampleNetwork() {
+  if (netInFlight) return;
+  netInFlight = true;
+  try {
+    const counters = await readNetCounters();
+    if (!counters) return;
+    const next = { rx: counters.rx, tx: counters.tx, at: Date.now() };
+    const rate = rateBetween(prevNet, next);
+    prevNet = next;
+    if (!rate) return;
+    netRate = rate;
+    record("net:down", rate.down);
+    record("net:up", rate.up);
+  } finally { netInFlight = false; }
+}
+
+/** Milliseconds for a TCP handshake with `address`, or null. The connection
+ *  is closed the moment it opens: nothing is sent, so this is a round trip and
+ *  nothing else — no TLS, no request, nothing the far end has to answer. */
+function connectMs(address, port = API_PORT, timeoutMs = CONNECT_TIMEOUT_MS) {
+  return new Promise(resolve => {
+    const t0 = performance.now();
+    let done = false;
+    const socket = net.connect({ host: address, port });
+    const finish = ms => {
+      if (done) return;
+      done = true;
+      socket.destroy();
+      resolve(ms);
+    };
+    socket.setTimeout(timeoutMs, () => finish(null));
+    socket.once("connect", () => finish(Math.round(performance.now() - t0)));
+    socket.once("error", () => finish(null));
+  });
+}
+
+/** Which way traffic to `address` leaves, and — for a Tailscale exit node —
+ *  through which machine and whether through a relay. */
+async function readRoute(address, platform, runner) {
+  let iface = null;
+  if (platform === "linux") iface = routeIfaceLinux(await runner("ip", ["-o", "route", "get", address]));
+  else if (platform === "darwin") iface = routeIfaceDarwin(await runner("route", ["-n", "get", address]));
+  const kind = classifyRoute(iface);
+  if (!kind || kind.kind === "direct") return kind;
+  // Tailscale on a Mac is a utun like every other VPN there, so the question is
+  // asked of any tunnel rather than only of one named tailscale0. A machine
+  // without the CLI answers null and keeps the generic label.
+  const exit = tailscaleExitFromStatus(await runner("tailscale", ["status", "--json"], 3_000));
+  if (exit) return { kind: "tailscale-exit", iface, ...exit };
+  return kind;
+}
+
+/**
+ * One probe: how far the API is and which way the traffic to it goes.
+ *
+ * Guarded twice, because a GET can start it (see systemSnapshot) and a read's
+ * cost must have a ceiling (#544): never two at once, and never more often than
+ * half the probe interval however many tabs poll. `deps` is the seam the tests
+ * use — nothing else here can be made to answer "unreachable" on demand.
+ */
+export async function probeNetwork(deps = {}) {
+  const now = deps.now ?? Date.now;
+  if (!probeEnabled && !deps.force) return;
+  if (probeInFlight || now() - probeAt < NET_PROBE_MS / 2) return;
+  if (!deps.force && now() - askedAt > NET_ASKED_MS) return;
+  probeInFlight = true;
+  probeAt = now();
+  try {
+    const platform = deps.platform ?? process.platform;
+    const runner = deps.run ?? run;
+    const measureApi = (deps.hasClaude ?? hasClaudeInstalled)();
+    let address = null;
+    if (measureApi) {
+      try { address = (await (deps.lookup ?? lookup)(API_HOST)).address; } catch { address = null; }
+      apiMs = address ? await (deps.connect ?? connectMs)(address) : null;
+      if (apiMs != null) record("net:api", apiMs);
+    }
+    const next = await readRoute(address ?? ROUTE_FALLBACK, platform, runner);
+    if (next) {
+      const label = routeLabel(next);
+      const prev = routeLog[routeLog.length - 1]?.label ?? null;
+      if (prev !== label) {
+        // `from` null is the first route this process saw — the state when it
+        // started looking, not a change, and the chart draws no mark for it.
+        routeLog.push({ t: now(), label, from: prev });
+        while (routeLog.length > ROUTE_LOG) routeLog.shift();
+      }
+    }
+    route = next;
+  } finally { probeInFlight = false; }
+}
+
+/** What the panel shows for the network, or null before anything is known. */
+function networkSnapshot(nowMs = Date.now()) {
+  const fresh = nowMs - probeAt <= NET_STALE_MS;
+  const api = fresh && apiMs !== undefined ? { host: API_HOST, ms: apiMs } : null;
+  // `to` says what the route was asked about: the API itself when Claude Code
+  // is here, the open internet otherwise — a split tunnel can send one and not
+  // the other, and the panel should not claim more than was measured.
+  const via = fresh && route && route.kind !== "direct"
+    ? { ...route, label: routeLabel(route), to: apiMs !== undefined ? "claude" : "internet" }
+    : null;
+  if (!netRate && !api && !via) return null;
+  return { down: netRate?.down ?? null, up: netRate?.up ?? null, api, route: via };
+}
+
 /**
- * Begin sampling. Idempotent, and both timers are unref'd so this can never be
+ * Begin sampling. Idempotent, and every timer is unref'd so this can never be
  * the reason the process stays alive.
+ *
+ * `probe` is the network section's permission to leave the machine — latency to
+ * the API and the route there. The server passes it; nothing else should.
  */
-export function startSystemMetrics() {
+export function startSystemMetrics({ probe = false } = {}) {
   if (cpuTimer) return;
+  probeEnabled = probe;
   prevTicks = readTicks();          // baseline, so the first tick has a delta
   prevCoreTicks = readCoreTicks();
   sampleMemory();
   historySince = Date.now();
   sampleThermal();
+  sampleNetwork();
   cpuTimer = setInterval(sampleCpu, CPU_INTERVAL_MS);
   memTimer = setInterval(sampleMemory, MEM_INTERVAL_MS);
   thermalTimer = setInterval(sampleThermal, THERMAL_INTERVAL_MS);
+  netTimer = setInterval(sampleNetwork, NET_INTERVAL_MS);
+  if (probeEnabled) probeTimer = setInterval(() => { probeNetwork(); }, NET_PROBE_MS);
   cpuTimer.unref?.();
   memTimer.unref?.();
   thermalTimer.unref?.();
+  netTimer.unref?.();
+  probeTimer?.unref?.();
 }
 
 /**
@@ -1894,7 +2132,19 @@ export function stopSystemMetrics() {
   if (cpuTimer) clearInterval(cpuTimer);
   if (memTimer) clearInterval(memTimer);
   if (thermalTimer) clearInterval(thermalTimer);
-  cpuTimer = memTimer = thermalTimer = null;
+  if (netTimer) clearInterval(netTimer);
+  if (probeTimer) clearInterval(probeTimer);
+  cpuTimer = memTimer = thermalTimer = netTimer = probeTimer = null;
+  probeEnabled = false;
+  prevNet = null;
+  netRate = null;
+  physical = null;
+  physicalAt = 0;
+  probeAt = 0;
+  askedAt = 0;
+  apiMs = undefined;
+  route = null;
+  routeLog.length = 0;
   thermal = null;
   thermalMisses = 0;
   thermalEverAnswered = false;
@@ -1924,6 +2174,13 @@ export function stopSystemMetrics() {
  */
 export function systemSnapshot() {
   const cpu = cpuHistory.length ? cpuHistory[cpuHistory.length - 1] : null;
+  // The panel is the only poller, so a poll is the signal somebody is looking.
+  // The first one after the panel was closed asks at once rather than waiting
+  // out the probe timer, so the latency is on screen by the second poll; the
+  // guards inside probeNetwork are what keep a busy poller from paying twice.
+  const idle = Date.now() - askedAt > NET_ASKED_MS;
+  askedAt = Date.now();
+  if (idle && probeEnabled) void probeNetwork();
   const load = os.loadavg();
   // Platform alone, for the reason spelled out beside the `load:1m` record in
   // sampleCpu: Node's own contract makes the platform test sufficient, and the
@@ -1945,6 +2202,7 @@ export function systemSnapshot() {
     uptimeSec: Math.round(os.uptime()),
     platform: process.platform,
     loadavg: hasLoad ? load.map(n => Math.round(n * 100) / 100) : null,
+    network: networkSnapshot(),
     intervalMs: CPU_INTERVAL_MS,
     sampledAt: Date.now(),
   };