ccdeck 3.24.1 → 3.26.0

package/src/server/lan-socket.mjs

@@ -23,6 +23,7 @@
 // address.
 import dgram from "node:dgram";
 import { networkInterfaces } from "node:os";
+import { looksLikeTunnel } from "./route-via.mjs";
 
 /** An IPv4 dotted quad as four numbers, or null for anything that is not one. */
 /**
@@ -75,18 +76,43 @@ export function directedBroadcast(address, netmask) {
  * IPv6 broadcast address.
  */
 export function broadcastTargets(ifaces) {
-  const out = ["255.255.255.255"];
-  for (const list of Object.values(ifaces ?? {})) {
+  return broadcastPlan(ifaces).map(p => p.to);
+}
+
+/**
+ * The same targets, each with the interface whose subnet it is — null for the
+ * limited broadcast, which is nobody's. What lets a beacon be held back when
+ * the machine would send it out by some OTHER interface: see leavesByTunnel.
+ */
+export function broadcastPlan(ifaces) {
+  const out = [{ to: "255.255.255.255", iface: null }];
+  for (const [name, list] of Object.entries(ifaces ?? {})) {
     for (const ni of list ?? []) {
       if (!ni || ni.internal) continue;
       // Node 18 reports `family` as the string "IPv4"; older shapes used 4.
       if (ni.family !== "IPv4" && ni.family !== 4) continue;
       const to = directedBroadcast(ni.address, ni.netmask);
-      if (to && !out.includes(to)) out.push(to);
+      if (to && !out.some(p => p.to === to)) out.push({ to, iface: name });
     }
   }
   return out;
 }
+
+/**
+ * Would this broadcast leave the local network?
+ *
+ * A directed broadcast belongs to the interface whose subnet it is, so the
+ * machine sending it out by any other one means something rerouted the local
+ * network — a VPN, or a Tailscale exit node without local network access —
+ * and the beacon would come out on the far end of the tunnel. The limited
+ * broadcast belongs to none, so it is held back only when it would go into
+ * something that is plainly a tunnel. Unknown answers nothing: send.
+ */
+export function leavesByTunnel(target, via, isTunnel) {
+  if (!via) return false;
+  if (target.iface) return via !== target.iface;
+  return isTunnel(via);
+}
 import net from "node:net";
 import { randomBytes } from "node:crypto";
 import {
@@ -201,6 +227,30 @@ export function createBeacon({
   // restarting the deck, and a list captured at start would announce to the
   // addresses it had at breakfast.
   ifaces = () => networkInterfaces(),
+  /**
+   * Addresses to send the beacon to one by one, beside the broadcast — the
+   * owner's machines on Tailscale, whose tunnel carries no broadcast at all.
+   * Read per announce like `ifaces`, because the tailnet list is re-read while
+   * the deck runs and a machine that just came online belongs in the next one.
+   */
+  unicast = () => [],
+  /**
+   * Which way a packet from this address came: "lan", "tailscale", or null for
+   * one to ignore entirely. Null is what a tailnet packet gets while this
+   * deck's Tailscale switch is off — the sockets hear it either way, because
+   * they bind every interface, and off has to mean the deck does not act on it.
+   */
+  routeFor = () => "lan",
+  /** How long to wait before trying the discovery port again while another
+   *  program holds it, and who to tell when hearing stops or comes back. */
+  rebindMs = 30_000,
+  onHearing,
+  /**
+   * Where the machine would send each broadcast — see createRouteCheck in
+   * route-via.mjs. Absent, every broadcast goes, as before; the suite's
+   * beacons have none.
+   */
+  routes = null,
 } = {}) {
   // Randomised per process. Two beacons from one fingerprint with different
   // instance ids mean the deck restarted between them, which is the signal to
@@ -213,7 +263,34 @@ export function createBeacon({
   const host = hostId();
   const peers = new Map();
   let sock = null;
+  /**
+   * The socket beacons LEAVE by, on a port of its own. See start.
+   *
+   * Null until it is bound, and whenever it could not be — the listening
+   * socket then sends as it always did, because a beacon from the wrong port is
+   * still a beacon and none at all is a deck nobody finds.
+   */
+  let out = null;
   let timer = null;
+  /**
+   * Whether this deck can HEAR — whether it holds the discovery port.
+   *
+   * SEPARATE FROM RUNNING, because a deck that cannot bind 45317 is still most
+   * of a deck. It announces from its own socket, so every other deck still
+   * finds it, asks it and dials it; what it has lost is hearing them announce.
+   * Stopping the whole feature over that — which is what this did — took a
+   * working sync away from somebody whose Tailscale exit node happened to be
+   * holding the port. It keeps trying for the port instead, and takes it back
+   * the moment it is free.
+   */
+  let hearing = false;
+  let deafError = null;
+  /** Whether the last announce held back every broadcast because the local
+   *  network goes through a tunnel here — see leavesByTunnel. */
+  let tunneled = false;
+  let told = null;
+  let rebind = null;
+  let stopped = true;
   /** When this deck last answered a deck it had not heard, so answering cannot
    *  become a storm, and which decks it has already answered — without the
    *  second, a deck that is never accepted is answered again on every packet
@@ -223,8 +300,8 @@ export function createBeacon({
 
     const payload = () => Buffer.from(JSON.stringify(beaconPayload({ name, fp, port, instance, host })));
 
-  const announce = () => {
-    if (!sock) return;
+  const announce = (also = []) => {
+    if (!sock && !out) return;
     // EVERY BROADCAST ADDRESS THIS MACHINE HAS, not one.
     //
     // This used to send only to 255.255.255.255, on the argument that the
@@ -246,11 +323,18 @@ export function createBeacon({
     // broadcast is filtered, and it is what Syncthing sends — and every
     // interface's own directed broadcast goes out beside it. A duplicate packet
     // costs one datagram; a missing one costs the whole feature.
-    const targets = broadcastTargets(ifaces());
+    const plan = broadcastPlan(ifaces());
+    // Asked behind the send, and read from what was last answered: the first
+    // beacon after a start goes as it always did, and the ones after it know.
+    void routes?.want?.(plan.map(p => p.to));
+    const kept = routes ? plan.filter(p => !leavesByTunnel(p, routes.via(p.to), looksLikeTunnel)) : plan;
+    tunneled = kept.length === 0;
+    const targets = kept.map(p => p.to);
+    const from = out ?? sock;
     let left = targets.length;
     const failed = [];
     for (const to of targets) {
-      sock.send(payload(), DISCOVERY_PORT, to, err => {
+      from.send(payload(), DISCOVERY_PORT, to, err => {
         if (err) failed.push(`${to} (${err.code ?? err.message})`);
         // REPORTED ONLY WHEN EVERY ONE FAILED. One address being unreachable is
         // the ordinary state of a machine with a VPN up, and a panel that said
@@ -262,82 +346,181 @@ export function createBeacon({
         }
       });
     }
+    // AND ONE PACKET PER TAILNET MACHINE. Not part of the verdict above: a node
+    // that has gone to sleep since the list was read is the ordinary state of a
+    // laptop, and it says nothing about whether this deck can be discovered.
+    let direct = [];
+    try { direct = [...(unicast() ?? []), ...also]; } catch { direct = [...also]; }
+    for (const to of new Set(direct)) {
+      if (typeof to !== "string" || !to || targets.includes(to)) continue;
+      from.send(payload(), DISCOVERY_PORT, to, () => {});
+    }
   };
 
-  const start = () => new Promise(resolve => {
-    sock = createSocket({ type: "udp4", reuseAddr: true });
-    sock.on("error", err => { onError?.("socket", err); });
-    sock.on("message", (msg, rinfo) => {
-      // Everything about whether to care lives in lan-sync.mjs. This hands it
-      // the bytes and the address and does what it is told.
-      if (msg.length > MAX_BEACON_BYTES) return;
-      const beacon = readBeacon(msg);
-      const verdict = beaconVerdict(beacon, { selfFp: fp, selfInstance: instance, selfHost: host, trusted: trusted() });
-      // ANSWER A DECK WE HAVE NEVER HEARD, once, WHOEVER IT IS — and that last
-      // part is the change. It used to answer only a deck already in the group,
-      // which was fine when a group existed. Now the first thing a new deck has
-      // to become is a row on somebody's screen, and it cannot become one if
-      // this deck never tells it that it exists.
-      //
-      // Measured on two real decks before any of this: deck 1 saw deck 2 the
-      // instant it started and deck 2 saw nobody, because deck 1's own
-      // immediate announce went out before deck 2 was listening. Thirty seconds
-      // of an empty list is how a working feature reads as broken.
-      //
-      // At most once every few seconds, because the obvious version is a shout
-      // storm: two decks answering each other's answers forever. A new pair
-      // converges in two extra packets.
-      const newToUs = beacon && verdict !== "self" && verdict !== "id-clash" && verdict !== "unreadable"
-        && !peers.has(beacon.fp) && !answered.has(beacon.fp);
-      if (newToUs && now() - repliedAt > REPLY_COOLDOWN_MS) {
-        repliedAt = now();
-        answered.add(beacon.fp);
-        announce();
-      }
-      if (verdict !== "peer") {
-        // Another deck is using this one's key — see beaconVerdict. Reported
-        // rather than fixed here: this file carries packets, and choosing a new
-        // identity for the deck belongs to whoever stores it.
-        if (verdict === "id-clash") onIdClash?.();
-        // A DECK NOBODY HAS ACCEPTED. It is not refused and not silently
-        // dropped: it is a name and an address on the same network, which is a
-        // row somebody can accept. Nothing is asked of it and nothing is
-        // offered to it until they do.
-        if (verdict === "stranger") {
-          onStranger?.({
-            fp: beacon.fp, name: beacon.name, addr: rinfo.address, port: beacon.port,
-            // Carried through so the list can show one row per machine rather
-            // than one per key that machine has ever held.
-            host: beacon.host, at: now(),
-          });
-        }
-        return;
+  const onMessage = (msg, rinfo) => {
+    // Everything about whether to care lives in lan-sync.mjs. This hands it
+    // the bytes and the address and does what it is told.
+    if (msg.length > MAX_BEACON_BYTES) return;
+    let via = "lan";
+    try { via = routeFor(rinfo.address); } catch { via = "lan"; }
+    if (!via) return;
+    const beacon = readBeacon(msg);
+    const verdict = beaconVerdict(beacon, { selfFp: fp, selfInstance: instance, selfHost: host, trusted: trusted() });
+    // ANSWER A DECK WE HAVE NEVER HEARD, once, WHOEVER IT IS — and that last
+    // part is the change. It used to answer only a deck already in the group,
+    // which was fine when a group existed. Now the first thing a new deck has
+    // to become is a row on somebody's screen, and it cannot become one if
+    // this deck never tells it that it exists.
+    //
+    // Measured on two real decks before any of this: deck 1 saw deck 2 the
+    // instant it started and deck 2 saw nobody, because deck 1's own
+    // immediate announce went out before deck 2 was listening. Thirty seconds
+    // of an empty list is how a working feature reads as broken.
+    //
+    // At most once every few seconds, because the obvious version is a shout
+    // storm: two decks answering each other's answers forever. A new pair
+    // converges in two extra packets.
+    const newToUs = beacon && verdict !== "self" && verdict !== "id-clash" && verdict !== "unreadable"
+      && !peers.has(beacon.fp) && !answered.has(beacon.fp);
+    if (newToUs && now() - repliedAt > REPLY_COOLDOWN_MS) {
+      repliedAt = now();
+      answered.add(beacon.fp);
+      // A deck that reached this one over the tailnet is answered there too:
+      // a broadcast never gets back down its tunnel.
+      announce(via === "tailscale" ? [rinfo.address] : []);
+    }
+    if (verdict !== "peer") {
+      // Another deck is using this one's key — see beaconVerdict. Reported
+      // rather than fixed here: this file carries packets, and choosing a new
+      // identity for the deck belongs to whoever stores it.
+      if (verdict === "id-clash") onIdClash?.();
+      // A DECK NOBODY HAS ACCEPTED. It is not refused and not silently
+      // dropped: it is a name and an address on the same network, which is a
+      // row somebody can accept. Nothing is asked of it and nothing is
+      // offered to it until they do.
+      if (verdict === "stranger") {
+        onStranger?.({
+          fp: beacon.fp, name: beacon.name, addr: rinfo.address, port: beacon.port,
+          // Carried through so the list can show one row per machine rather
+          // than one per key that machine has ever held.
+          host: beacon.host, at: now(), via,
+        });
       }
-      const noted = notePeer(peers, beacon, rinfo.address, now());
-      if (noted.changed || noted.restarted) onPeer?.(noted);
+      return;
+    }
+    const noted = notePeer(peers, beacon, rinfo.address, now(), via);
+    if (noted.changed || noted.restarted) onPeer?.(noted);
+  };
+
+  /** Tell whoever asked, once per change rather than once per try. */
+  const tell = now => {
+    if (told === now) return;
+    told = now;
+    onHearing?.(now);
+  };
+
+  /** One try at the discovery port: the listening socket, or the error that
+   *  kept it. A bind that fails never calls back; it arrives as an error. */
+  const listen = () => new Promise(resolve => {
+    let s;
+    try { s = createSocket({ type: "udp4", reuseAddr: true }); } catch (err) { resolve({ err }); return; }
+    let bound = false;
+    s.on("error", err => {
+      if (bound) { onError?.("socket", err); return; }
+      try { s.close(); } catch { /* never opened */ }
+      resolve({ err });
     });
-    sock.bind(DISCOVERY_PORT, "0.0.0.0", () => {
-      try { sock.setBroadcast(true); } catch (err) { onError?.("broadcast", err); }
-      // Immediately, not on the next tick. Syncthing's rule: a deck that just
-      // came up should appear now rather than up to thirty seconds later, which
-      // is the difference between "it works" and "it seems broken" for anybody
-      // who starts two decks and watches.
-      announce();
-      timer = setInterval(announce, ANNOUNCE_MS);
-      timer.unref?.();
-      resolve();
+    s.on("message", onMessage);
+    s.bind(DISCOVERY_PORT, "0.0.0.0", () => {
+      bound = true;
+      try { s.setBroadcast(true); } catch (err) { onError?.("broadcast", err); }
+      resolve({ sock: s });
     });
   });
 
+  const tryListen = async () => {
+    const got = await listen();
+    if (stopped) { try { got.sock?.close(); } catch { /* gone */ } return; }
+    if (got.sock) {
+      sock = got.sock;
+      hearing = true;
+      deafError = null;
+      tell(true);
+      return;
+    }
+    hearing = false;
+    deafError = got.err;
+    tell(false);
+    rebind = setTimeout(() => { rebind = null; void tryListen(); }, rebindMs);
+    rebind.unref?.();
+  };
+
+  /**
+   * The socket beacons leave by, bound to whatever port the OS gives it.
+   *
+   * SENT FROM A PORT OF ITS OWN, NOT FROM 45317. Nothing that hears a beacon
+   * reads the port it came from — the reply goes to 45317 whatever the source
+   * — and sending from the discovery port gave that port away. Measured on a
+   * Mac that is a Tailscale exit node: a deck elsewhere on the tailnet routed a
+   * beacon through it, and Tailscale's forwarder binds its end of every UDP
+   * flow to the CLIENT's source port (netstack.go, forwardUDP), idling it out
+   * after two minutes. A beacon every thirty seconds never idles, so the Mac's
+   * own deck could never bind 45317 again. From an ephemeral port, the
+   * forwarder takes an ephemeral port.
+   */
+  const openOut = () => new Promise(resolve => {
+    let o;
+    try { o = createSocket({ type: "udp4" }); } catch { resolve(null); return; }
+    let opened = false;
+    o.on("error", err => {
+      if (opened) { onError?.("socket", err); return; }
+      opened = true;
+      try { o.close(); } catch { /* never opened */ }
+      resolve(null);
+    });
+    o.bind(0, "0.0.0.0", () => {
+      if (opened) return;
+      opened = true;
+      try { o.setBroadcast(true); } catch (err) { onError?.("broadcast", err); }
+      resolve(o);
+    });
+  });
+
+  const start = async () => {
+    stopped = false;
+    told = null;
+    await tryListen();
+    out = await openOut();
+    if (stopped) return;
+    // Immediately, not on the next tick. Syncthing's rule: a deck that just
+    // came up should appear now rather than up to thirty seconds later, which
+    // is the difference between "it works" and "it seems broken" for anybody
+    // who starts two decks and watches.
+    announce();
+    timer = setInterval(announce, ANNOUNCE_MS);
+    timer.unref?.();
+  };
+
   return {
     start,
     announce,
     peers,
+    /** Whether this deck holds the discovery port, and why not when it does
+     *  not. */
+    hearing: () => hearing,
+    deafError: () => deafError,
+    tunneled: () => tunneled,
     stop() {
+      stopped = true;
       if (timer) clearInterval(timer);
       timer = null;
+      if (rebind) clearTimeout(rebind);
+      rebind = null;
+      hearing = false;
       try { sock?.close(); } catch { /* already closed */ }
       sock = null;
+      try { out?.close(); } catch { /* already closed */ }
+      out = null;
     },
   };
 }

package/src/server/lan-sync.mjs

@@ -894,13 +894,26 @@ export function pairable(strangers, now, { presentMs = PRESENT_MS, limit = 8, mi
  * `changed` is returned rather than inferred by the caller so a beacon that
  * says nothing new — which is most of them, one every thirty seconds per peer
  * forever — costs no render and no write.
+ *
+ * `via` is the route the packet came by: "lan", or "tailscale" for one sent to
+ * this machine's tailnet address — see routeOf in tailscale.mjs.
  */
-export function notePeer(peers, beacon, addr, now) {
+export function notePeer(peers, beacon, addr, now, via = "lan") {
   const prev = peers.get(beacon.fp);
+  // ONE MACHINE, TWO ROUTES, AND THE LOCAL ONE WINS WHILE IT ANSWERS. A laptop
+  // in the office is heard on the Wi-Fi and over Tailscale in the same half
+  // minute, and taking whichever packet came last flipped its address every
+  // beacon — each flip a `changed`, and a round dialling a different route each
+  // minute. The tailnet address is used only once the local one has gone quiet
+  // for as long as presence lasts, which is the laptop having left the building.
+  const lanAt = via === "lan" ? now : prev && prev.via !== "tailscale" ? prev.lanAt ?? prev.lastSeen : prev?.lanAt;
+  const keepLan = via === "tailscale" && prev && prev.via !== "tailscale" && lanAt != null && now - lanAt < PRESENT_MS;
   const next = {
     fp: beacon.fp,
     name: beacon.name,
-    addr,
+    addr: keepLan ? prev.addr : addr,
+    via: keepLan ? prev.via ?? "lan" : via,
+    lanAt: lanAt ?? null,
     port: beacon.port,
     instance: beacon.instance,
     host: beacon.host,

package/src/server/login-service.mjs

@@ -31,6 +31,7 @@
 // (crashPolicy, in supervisor.mjs), it is identical on every platform, and it is
 // tested. Two policies over one process is how `ccdeck --stop` becomes a
 // suggestion the machine overrules a second later.
+import { inApp } from "./app-host.mjs";
 import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -264,6 +265,9 @@ export function taskXmlFor({ execPath, script, args = [], product = "ccdeck" } =
  */
 export function shouldOfferService({ record = null, npx = false, checkout = false, env = process.env } = {}) {
   if (env.AGENTS_DECK_NO_INSTALL === "1") return false;
+  // The desktop app owns start-at-login; a second login item from the deck it
+  // started would launch that deck with no app around it (app-host.mjs).
+  if (inApp(env)) return false;
   if (npx || checkout) return false;
   return record === null;
 }

package/src/server/network-metrics.mjs

@@ -0,0 +1,190 @@
+// The network section's readings, as pure functions of what the platform prints.
+//
+// Everything here is text in, numbers out, so a Linux answer can be checked from
+// a Mac and a Windows one from either — the same reason every parser in
+// system-metrics.mjs is exported and pure. The sampler that runs the commands,
+// times the connection and keeps the history lives there; this file only reads.
+//
+// THREE READINGS, AND WHY THESE THREE (#network). The first build of this idea
+// was a speed test, and a speed test is the wrong instrument twice over: it
+// fills the line for as long as it runs — which is exactly the stall a person
+// opens this section to explain — and the maximum a line can carry is not what
+// was wrong the day this was designed. That day the Wi-Fi measured 270 Mbit/s
+// and Claude FM still went silent for twenty seconds at a time, because every
+// packet was leaving through a Tailscale exit node on another continent's relay.
+// So the section reports what is MOVING (throughput), how FAR Claude is
+// (latency), and which WAY the traffic goes (the route) — the three things a
+// person needs to tell "the network is slow" from "the network is fine and
+// something else is".
+
+/**
+ * Bytes received and sent across the interfaces that are wires, out of
+ * `/proc/net/dev`.
+ *
+ * `include` decides which interfaces count, and the sampler passes the set of
+ * physical ones (those with a `device` under /sys/class/net). Counting every
+ * interface would count a VPN's traffic twice — once inside the tunnel and once
+ * again, encrypted, on the Wi-Fi that carries it — and loopback's traffic,
+ * which never leaves the machine, would read as the deck downloading.
+ *
+ * Returns null when nothing matched, which is not the same as zero: a machine
+ * whose counters read zero moved nothing, and one this could not read did not
+ * say.
+ */
+export function parseProcNetDev(text, include = name => name !== "lo") {
+  if (typeof text !== "string") return null;
+  let rx = 0;
+  let tx = 0;
+  const ifaces = [];
+  for (const line of text.split("\n")) {
+    const colon = line.indexOf(":");
+    if (colon < 0) continue;
+    const name = line.slice(0, colon).trim();
+    if (!name || name.includes("|") || !include(name)) continue;
+    const f = line.slice(colon + 1).trim().split(/\s+/).map(Number);
+    // Receive is the first eight columns and transmit the next eight; bytes
+    // lead each group.
+    if (f.length < 9 || !Number.isFinite(f[0]) || !Number.isFinite(f[8])) continue;
+    rx += f[0];
+    tx += f[8];
+    ifaces.push(name);
+  }
+  return ifaces.length ? { rx, tx, ifaces } : null;
+}
+
+/**
+ * The same two totals out of macOS's `netstat -ibn`.
+ *
+ * Only the `enN` rows, which are the Mac's Ethernet and Wi-Fi ports, and only
+ * their `<Link#N>` row — netstat prints one row per address family per
+ * interface, and summing all of them would count every byte two or three times.
+ * `utun` (every VPN, Tailscale included), `lo`, `awdl`, `llw`, `bridge` and the
+ * rest are left out for the reason the Linux reader leaves virtual interfaces
+ * out. Read from the END of the row, because the Address column is empty on
+ * some interfaces and a count from the front would shift by one.
+ */
+export function parseNetstatIbn(text) {
+  if (typeof text !== "string") return null;
+  let rx = 0;
+  let tx = 0;
+  let seen = 0;
+  for (const line of text.split("\n")) {
+    const f = line.trim().split(/\s+/);
+    if (f.length < 8 || !/^en\d+$/.test(f[0]) || !f.some(c => c.startsWith("<Link#"))) continue;
+    // … Ipkts Ierrs Ibytes Opkts Oerrs Obytes Coll
+    const ibytes = Number(f[f.length - 5]);
+    const obytes = Number(f[f.length - 2]);
+    if (!Number.isFinite(ibytes) || !Number.isFinite(obytes)) continue;
+    rx += ibytes;
+    tx += obytes;
+    seen++;
+  }
+  return seen ? { rx, tx } : null;
+}
+
+/**
+ * The two totals out of Windows' `netstat -e`.
+ *
+ * Found by shape rather than by label: the first row that is a word followed by
+ * exactly two integers is the Bytes row, in every language Windows ships —
+ * "Bytes" is "Octets" on a French machine, and a parser that matched the word
+ * would read nothing there. The totals cover every adapter; Windows offers no
+ * cheaper per-adapter figure than a PowerShell start, which costs more than
+ * this whole section is worth every five seconds.
+ */
+export function parseNetstatE(text) {
+  if (typeof text !== "string") return null;
+  for (const line of text.split(/\r?\n/)) {
+    const m = /^\s*\S[^\d]*?\s+(\d+)\s+(\d+)\s*$/.exec(line);
+    if (m) return { rx: Number(m[1]), tx: Number(m[2]) };
+  }
+  return null;
+}
+
+/**
+ * Bytes per second between two readings, or null when the pair cannot say.
+ *
+ * A counter that went BACKWARDS is an adapter that was reset — unplugged,
+ * resumed from sleep, a driver reloaded — and the difference across a reset is
+ * not a rate, it is a large negative number. Too short a gap is refused for the
+ * opposite reason: two reads a few milliseconds apart turn one packet into a
+ * wild figure.
+ */
+export function rateBetween(prev, next) {
+  if (!prev || !next) return null;
+  const seconds = (next.at - prev.at) / 1000;
+  if (!(seconds >= 0.5)) return null;
+  const drx = next.rx - prev.rx;
+  const dtx = next.tx - prev.tx;
+  if (drx < 0 || dtx < 0) return null;
+  return { down: Math.round(drx / seconds), up: Math.round(dtx / seconds) };
+}
+
+/** The interface Linux would send a packet for this address out of, from
+ *  `ip -o route get <address>`. Asking sends nothing; it reads the routing
+ *  table, including the policy tables a Tailscale exit node installs, which
+ *  `/proc/net/route` does not show. */
+export function routeIfaceLinux(text) {
+  if (typeof text !== "string") return null;
+  return /\bdev\s+(\S+)/.exec(text)?.[1] ?? null;
+}
+
+/** The same question on macOS, from `route -n get <address>`. */
+export function routeIfaceDarwin(text) {
+  if (typeof text !== "string") return null;
+  return /^\s*interface:\s*(\S+)/m.exec(text)?.[1] ?? null;
+}
+
+/**
+ * What kind of path an interface name is.
+ *
+ * Direct is the ordinary case and draws nothing at all in the panel: only a
+ * route that is not the machine's own connection is worth a line. Names, not
+ * probes, because the kernel already named them — `tailscale0`, `wg0`,
+ * `nordlynx`, `utun4`, `tun0`, `ppp0`, `zt…` — and asking each VPN client
+ * whether it is running would cost a process per client per sample.
+ */
+export function classifyRoute(iface) {
+  if (typeof iface !== "string" || !iface) return null;
+  if (/^tailscale\d*$/.test(iface)) return { kind: "tailscale", iface };
+  if (/^(wg\d|nordlynx|mullvad|proton|wgpia)/.test(iface)) return { kind: "vpn", iface, name: "WireGuard" };
+  if (/^zt/.test(iface)) return { kind: "vpn", iface, name: "ZeroTier" };
+  if (/^(utun|tun|tap|ppp|ipsec|gpd|cscotun|vpn)/.test(iface)) return { kind: "vpn", iface, name: null };
+  return { kind: "direct", iface };
+}
+
+/**
+ * The exit node carrying this machine's traffic, and whether it is reached
+ * directly or through one of Tailscale's relays, from `tailscale status --json`.
+ *
+ * The relay is the half that matters. A direct path to an exit node costs a
+ * hop; a relayed one sends every byte through a DERP server — `nue` is
+ * Nuremberg — and adds the round trip to wherever that is, twice. That is what
+ * made a live stream buffer every few minutes on the day this was written, on a
+ * line that was otherwise fine.
+ */
+export function tailscaleExitFromStatus(json) {
+  let status = json;
+  if (typeof json === "string") {
+    try { status = JSON.parse(json); } catch { return null; }
+  }
+  if (!status || typeof status !== "object" || !status.ExitNodeStatus) return null;
+  const peer = Object.values(status.Peer ?? {}).find(p => p && p.ExitNode);
+  const node = peer?.HostName || peer?.DNSName?.split(".")[0] || null;
+  // CurAddr is set when the path is direct; an empty one with a Relay named is
+  // every packet going through that relay.
+  const relay = peer && !peer.CurAddr && peer.Relay ? String(peer.Relay) : null;
+  return { node, relay };
+}
+
+/** One line for a route, the same words the panel and the history use, so the
+ *  two can never describe one path differently. */
+export function routeLabel(route) {
+  if (!route) return null;
+  if (route.kind === "direct") return "direct";
+  if (route.kind === "tailscale-exit") {
+    return `through Tailscale exit node${route.node ? ` ${route.node}` : ""}${route.relay ? `, relayed via ${route.relay}` : ""}`;
+  }
+  if (route.kind === "tailscale") return "through Tailscale";
+  return `through ${route.name ? `${route.name} ` : "a "}VPN${route.iface ? ` (${route.iface})` : ""}`;
+}