ccdeck 3.25.0 → 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/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);