agent-dag 3.19.0 → 3.20.0

package/src/server/index.mjs

@@ -10,7 +10,17 @@ import { extname, join, resolve, sep, dirname as pdirname } from "node:path";
 import { homedir, networkInterfaces } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname } from "node:path";
-import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+// Moved out to a leaf so that a one-shot `ccdeck --stop`, the boot-path module
+// that finds a running deck, and the tests that pin the handshake against
+// hook/hook.js can all ask these questions without importing this file and
+// arming everything in it. Re-exported below under the names they have always
+// had — see src/server/deck-probe.mjs.
+import { challengeDeck, challengeProof, isProcessAlive } from "./deck-probe.mjs";
+// The three this file's own callers and tests already name. `sameProof` and the
+// challenge deadline stay private to the leaf: they were private here too, and
+// re-exporting them would be inventing API on the way out of a move.
+export { challengeDeck, challengeProof, isProcessAlive };
 import { promisify } from "node:util";
 import { claudeConfigDir } from "./claude-dir.mjs";
 import { CODEX_HOME, CODEX_SESSIONS_DIR, STOP, walkRolloutDays } from "./codex-dir.mjs";
@@ -2036,10 +2046,6 @@ let codexWorkspace = "";
 // believing a stale "yes" is at most a few unwritten lines, against a directory
 // listing plus an HTTP round trip on every tick of every deck forever.
 const DECK_PROOF_TTL_MS = 5000;
-// The same deadline hook.js gives a challenge, and for the same reason: a
-// bodyless GET to a loopback port is sub-millisecond when a deck is there and an
-// instant ECONNREFUSED when nothing is.
-const DECK_CHALLENGE_TIMEOUT_MS = 400;
 // `${pid}:${port}:${token}` -> { at, ok }. Keyed on the record's own identity so
 // a rewritten record — a deck that restarted onto the same port with a fresh
 // token — is a new question rather than an inherited answer.
@@ -2105,57 +2111,6 @@ async function provesDeck(d) {
   return ok;
 }
 
-/**
- * One challenge round trip, resolving true only on a correct proof.
- *
- * The compare is constant-time for the reason hook.js's sameProof is: whatever
- * is on that port may not be a deck, and it must not be able to walk the
- * expected proof out of us one byte at a time by timing how long we take to hang
- * up. The nonce is fresh per call, so an answer overheard earlier is worth
- * nothing, and the token itself never leaves this process.
- */
-function challengeDeck(port, token) {
-  return new Promise(resolve => {
-    let settled = false;
-    const finish = ok => { if (settled) return; settled = true; resolve(ok); };
-    const nonce = randomBytes(16).toString("hex");
-    const want = challengeProof(token, nonce);
-    const req = httpRequest({
-      hostname: "127.0.0.1",
-      port,
-      path: `/api/hook-challenge?nonce=${nonce}`,
-      method: "GET",
-      timeout: DECK_CHALLENGE_TIMEOUT_MS,
-    }, res => {
-      if (res.statusCode !== 200) { res.resume(); return res.on("end", () => finish(false)); }
-      let answer = "";
-      res.setEncoding("utf8");
-      res.on("data", c => {
-        answer += c;
-        // A deck answers in ~100 bytes. Anything pouring data at us is not one,
-        // and must not be allowed to grow this buffer without bound.
-        if (answer.length > 4096) { req.destroy(); finish(false); }
-      });
-      res.on("end", () => {
-        if (settled) return;
-        let proof;
-        try { proof = JSON.parse(answer).proof; } catch { return finish(false); }
-        finish(sameProof(proof, want));
-      });
-    });
-    req.on("error", () => finish(false));
-    req.on("timeout", () => req.destroy());
-    req.end();
-  });
-}
-
-/** hook.js's sameProof, for the same reason it is constant-time there. */
-function sameProof(got, want) {
-  if (typeof got !== "string") return false;
-  const a = Buffer.from(got, "utf8");
-  const b = Buffer.from(want, "utf8");
-  return a.length === b.length && timingSafeEqual(a, b);
-}
 
 /**
  * Every deck registered right now, as its own discovery record spells it — and
@@ -3246,15 +3201,67 @@ const lanEngine = createEngine({
     const out = await shareAccounts([String(num)]);
     return out?.ok ? out.blob : null;
   },
-  importAccount: async blob => {
-    const { importAccount } = await import("./cswap-admin.mjs");
+  importAccount: async (blob, step) => {
+    const { importAccount, landed } = await import("./cswap-admin.mjs");
     // NO `force`, ever, and this is the line where that promise is kept. A
     // plain import adds an account that is missing and replaces exactly one
     // claude-swap has quarantined; it SKIPS one that is present and healthy.
     // So a peer cannot overwrite a working credential of this deck's even by
     // lying about its own, because the flag that would allow it is not passed.
     const out = await importAccount(blob);
-    return !!out?.ok;
+    if (!out?.ok) return { ok: false, why: out?.reason ?? "import refused" };
+    // A SKIP IS NOT A HEAL, and reading `ok` alone said it was. `cswap import`
+    // exits ZERO when it declines an account it already holds — importAccount's
+    // own comment says so and reports it as `added: false` — so a round that
+    // changed nothing was counted as a successful repair and the panel said the
+    // account had been fixed. Whoever read that then waited for numbers that
+    // were never going to move.
+    //
+    // The decline is narrow and documented on claude-swap's side: a plain
+    // import replaces a slot only when its usage row is quarantined as
+    // refresh-token-dead, and is "never triggered by the live store's
+    // `no credentials` state". So an account whose login expired heals over the
+    // network, and one that has NO stored login does not — which is a true
+    // sentence the panel can now print instead of a false one.
+    if (out.added === true) return { ok: true };
+
+    // THE DECLINE, AND WHY IT MATTERS WHICH ONE IT IS.
+    //
+    // `cswap import` without --force declines for two opposite reasons and says
+    // the same thing about both: the slot is present and HEALTHY, which is the
+    // promise above working exactly as intended — or the slot is EMPTY, which
+    // is the one case pairing exists for and the one a plain import will never
+    // touch. claude-swap is explicit about the second: a plain import replaces
+    // a slot "iff its usage row is quarantined as refresh-token-dead", and is
+    // "never triggered by the live store's `no credentials` state".
+    //
+    // So `login expired` healed over the network and `no stored login` did not,
+    // and the account somebody most needed repaired was the one the feature
+    // could not repair.
+    //
+    // ASKED NOW, NOT READ FROM THE CACHE. The cached verdicts are up to ten
+    // minutes old, which is right for a label and wrong for a decision that
+    // writes a credential: somebody who signed in two minutes ago still reads
+    // as `no_credentials` there, and acting on that would replace the login
+    // they had just created.
+    const { verdictNow } = await import("./claude-accounts.mjs");
+    const [email, org] = String(step?.key ?? "").split("@@");
+    const now = await verdictNow(email, org ?? "");
+    if (now !== "no_credentials") return { ok: false, why: "claude-swap kept the slot it already has" };
+
+    // FILLING AN EMPTY SLOT, WHICH IS NOT OVERWRITING A WORKING ONE — and the
+    // promise above survives word for word. A peer cannot reach this: the
+    // verdict comes from THIS machine's claude-swap, about THIS machine's
+    // store, and nothing a peer sends can make a slot report that it holds
+    // nothing. Narrowed to the one account with `only`, so a bundle carrying
+    // several cannot ride in behind it.
+    const forced = await importAccount(blob, { force: true, only: { email, org: org ?? "" } });
+    if (!forced?.ok) return { ok: false, why: forced?.reason ?? "import refused" };
+    // `added` counts `imported` alone, and a forced replace is `healed` — see
+    // landed, which is the difference between a repair and a repair reported as
+    // a failure.
+    if (!landed(forced.results)) return { ok: false, why: "claude-swap kept the slot it already has" };
+    return { ok: true, filled: true };
   },
   // The deck's own long-term key, kept so a restart is the same deck rather
   // than a stranger to everybody who has paired with it. Written once, on the
@@ -3315,6 +3322,8 @@ async function applyLanPrefs() {
       shared: Array.isArray(lan.shared) ? lan.shared : [],
       trusted: Array.isArray(lan.trusted) ? lan.trusted : [],
       port: lan.port || 0,
+      autoAsk: lan.autoAsk !== false,
+      autoAccept: lan.autoAccept !== false,
     });
     // Wholesale, so removing an address in the panel really stops it being
     // dialled rather than only taking the row away.
@@ -4429,6 +4438,50 @@ export function markDeckReady() {
   _deckReady = true;
 }
 
+/**
+ * POST /api/shutdown — end this deck, from `ccdeck --stop`.
+ *
+ * THE TOKEN AND NOTHING ELSE. Every other mutating route accepts either the
+ * token or the deck's own page (isAuthorizedMutation), and this one must not:
+ * there is no button for it, so a page asking to end the deck is a page doing
+ * something no part of this product asks it to do. Refusing the browser half
+ * costs nothing and removes the whole class.
+ *
+ * WHY A ROUTE AND NOT A SIGNAL. Windows has none. `process.kill(pid, "SIGTERM")`
+ * there is TerminateProcess: the deck stops mid-instruction, its discovery file
+ * is left for the next boot to sweep, and its LAN beacon never says goodbye — so
+ * every paired colleague watches it time out instead of seeing it leave. One
+ * loopback POST behaves identically on all three platforms and ends in the
+ * deck's own shutdown(), which closes the listener, unlinks the registration and
+ * stops the beacon. The pid ladder still exists in `--stop`, as the fallback for
+ * a deck too wedged to answer this.
+ *
+ * ANSWERED BEFORE ANYTHING IS TORN DOWN. shutdown() calls
+ * server.closeAllConnections(), which would cut this very socket — so the
+ * teardown is hung off the response having left rather than run beside it, and
+ * the caller gets a 200 instead of a dropped connection it has to interpret.
+ */
+async function handleStop(req, res) {
+  if (!presentsDeckToken(req?.headers ?? {})) return send(res, 401, { ok: false, reason: "unauthenticated" });
+  if (!_onStop) return send(res, 501, { ok: false, reason: "no_launcher" });
+  if (_stopping) return send(res, 200, { ok: true, pid: process.pid, already: true });
+  _stopping = true;
+  let left = false;
+  const leave = () => {
+    if (left) return;
+    left = true;
+    // A throw here must still end the process: the caller has already been told
+    // this deck is going, and a deck that answered "ok" and stayed up is worse
+    // than one that never answered.
+    try { _onStop(); } catch { process.exit(0); }
+  };
+  // 'finish' is the response handed to the OS; 'close' covers the caller that
+  // hung up before it got there. Either one means nothing is left to flush.
+  res.once("finish", leave);
+  res.once("close", leave);
+  send(res, 200, { ok: true, pid: process.pid });
+}
+
 async function handleQuota(req, res) {
   const { fetchClaudeQuota } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/quota.mjs")).href
@@ -5035,17 +5088,6 @@ const HOOK_TOKEN = randomBytes(32).toString("hex");
 /** The token this deck expects to be challenged on. Written by writeDiscovery. */
 export function hookToken() { return HOOK_TOKEN; }
 
-/**
- * The proof of knowing `token`, for a nonce the challenger chose.
- *
- * hook/hook.js spells this out a second time — it is installed outside the
- * package and cannot import from here — and a test pins the two against each
- * other. Changing one without the other silently blinds the deck.
- */
-export function challengeProof(token, nonce) {
-  return createHash("sha256").update(`${token}:${nonce}`).digest("hex");
-}
-
 // GET /api/hook-challenge?nonce=… — answer a hook's challenge.
 //
 // The nonce is the caller's, so the answer proves knowledge of the token
@@ -5070,21 +5112,6 @@ function handleHookChallenge(_req, res, url) {
   send(res, 200, { proof: challengeProof(HOOK_TOKEN, nonce) });
 }
 
-// Signal 0 delivers nothing; it asks whether the pid could be signalled.
-//
-// BOTH ERRNOS, and the second one is the Windows spelling. POSIX `kill(2)`
-// answers EPERM for a process this account may not signal. On Windows
-// `uv_kill` calls `OpenProcess`, a denial is ERROR_ACCESS_DENIED, and libuv
-// maps that to EACCES — so a deck started from an elevated terminal, or under
-// another account, read as DEAD to every probe in this repo. What followed was
-// silent: the live deck's discovery file was unlinked on the next hook fire,
-// rewritten five seconds later by keepDiscovery, and its banner went on
-// claiming it was receiving events it had stopped receiving.
-function isProcessAlive(pid) {
-  try { process.kill(pid, 0); return true; }
-  catch (e) { return !!e && (e.code === "EPERM" || e.code === "EACCES"); }
-}
-
 async function sweepStaleDiscovery() {
   // Same directory the installer writes and the hooks read — see claude-dir.mjs.
   const dir = join(claudeConfigDir(), "agent-dag");
@@ -5590,6 +5617,15 @@ export function listenFailure(err, { host = "", port = 0, platform = process.pla
 // launcher), /api/restart answers 501 and the UI hides the control rather than
 // offering a button that does nothing.
 let _onRestart = null;
+// How this process ends itself, handed down by bin/deck.js for the same reason
+// _onRestart is: the server does not own the process lifecycle and must be told
+// how to leave. Absent when nothing handed one down — running the module
+// directly, or an embedder — and /api/shutdown then answers 501 rather than
+// pretending.
+let _onStop = null;
+// A stop is in flight. Two sockets asking at once must not both start one, and
+// the response's 'finish' and 'close' can both fire for the same request.
+let _stopping = false;
 // A restart is in flight. Several browser tabs watching the same deck will each
 // ask; the second ask must not re-enter the shutdown.
 let _restarting = false;
@@ -5599,8 +5635,10 @@ let _restarting = false;
 // is reachable in and cannot answer for on its own.
 let _deckReady = false;
 
-export async function startServer({ port = 4317, host = "127.0.0.1", persist = null, portRange = [4318, 4400], workspace = "", codex = true, claude = true, onRestart = null } = {}) {
+export async function startServer({ port = 4317, host = "127.0.0.1", persist = null, portRange = [4318, 4400], workspace = "", codex = true, claude = true, onRestart = null, onStop = null } = {}) {
   _onRestart = typeof onRestart === "function" ? onRestart : null;
+  _onStop = typeof onStop === "function" ? onStop : null;
+  _stopping = false;
   _canRestart = _onRestart != null && persist != null;
   // A new listener is a new boot, whatever a previous one had got as far as
   // reporting. Nothing but bin/deck.js ever sets this, and it does so once, at
@@ -5687,6 +5725,7 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "GET"  && url.pathname === "/api/version")     return guard(handleVersion(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/upgrade")     return guard(handleUpgrade(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/restart")     return guard(handleRestart(req, res), res);
+    if (req.method === "POST" && url.pathname === "/api/shutdown")    return guard(handleStop(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/quota")       return guard(handleQuota(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/codex-usage")  return guard(handleCodexUsage(req, res), res);
     // Machine state, not session state: sampled on the server's own timer and

package/src/server/installer.mjs

@@ -709,7 +709,7 @@ async function ensureDiscoveryDir() {
  * the target already had — a first registration, or one left by an earlier run
  * under a recycled pid, would otherwise keep whatever the umask handed it.
  */
-export async function writeDiscovery({ port, workspace, token, persist = null, codex = true }) {
+export async function writeDiscovery({ port, workspace, token, persist = null, codex = true, claude = true, version = "", parent = null }) {
   await ensureDiscoveryDir();
   const file = discoveryPath();
   const data = {
@@ -744,6 +744,27 @@ export async function writeDiscovery({ port, workspace, token, persist = null, c
     // doing the work must be left out of the election rather than win it. An
     // older deck has no such field, so it is excluded by construction.
     watch: true,
+    // Is the Claude side of this deck switched on? Same shape as `codex` above
+    // and there for a second reader: a bare `ccdeck` that finds this deck
+    // running attaches to it instead of starting a rival, and it may only do
+    // that when the deck on the port is the deck it would itself have built. A
+    // `--no-claude` deck has no hooks, no accounts panel and no switcher, and
+    // until this field existed it was indistinguishable from one that has all
+    // three. An older deck has no such field, so it is excluded by
+    // construction — see runningDeck.
+    claude: claude !== false,
+    // What this deck IS, so a launcher that attaches can say whether the deck
+    // it found is the version the user just asked for. Never a decision: a
+    // rival deck on a random port is worse than an older deck said out loud.
+    version: typeof version === "string" ? version : "",
+    // The supervisor above this worker, or null when nothing is supervising.
+    //
+    // Only `ccdeck --stop` reads it, and only on the path where the polite
+    // request failed. A worker killed on its own leaves its supervisor alive,
+    // and a supervisor that puts crashed workers back would answer that kill by
+    // starting the deck again — so the ladder has to end the parent first and
+    // the child second, which it cannot do without being told who the parent is.
+    parent: Number.isInteger(parent) ? parent : null,
     startedAt: new Date().toISOString(),
   };
   await writeFileAtomic(file, JSON.stringify(data, null, 2) + "\n");
@@ -771,13 +792,14 @@ export function discoveryPath() {
  * is cheap (one small read), so the deck checks rather than assumes.
  *
  * A file this process wrote is left alone, mode included. Anything else — no
- * file, unreadable, another pid, a stale port, token, events log or Codex
- * setting — is replaced. Every field another deck decides by is compared, the
+ * file, unreadable, another pid, a stale port, token, events log, Codex or
+ * Claude setting, or a version left by the deck this process replaced — is
+ * replaced. Every field another deck decides by is compared, the
  * log path included: leave one out and a record missing it would pass as ours
  * forever, which for the log path means no deck can tell which of them share a
  * file and they all write their own copy of every event again.
  */
-export async function ensureDiscovery({ port, workspace, token, persist = null, codex = true }) {
+export async function ensureDiscovery({ port, workspace, token, persist = null, codex = true, claude = true, version = "", parent = null }) {
   const file = discoveryPath();
   try {
     const d = JSON.parse(stripBom(await readFile(file, "utf8")));
@@ -787,11 +809,14 @@ export async function ensureDiscovery({ port, workspace, token, persist = null,
       && (d.workspace ?? "") === (workspace ?? "")
       && (d.token ?? "") === (token ?? "")
       && (d.persist ?? null) === persistField(persist)
-      && d.codex === (codex !== false)) {
+      && d.codex === (codex !== false)
+      && d.claude === (claude !== false)
+      && (d.version ?? "") === (typeof version === "string" ? version : "")
+      && (d.parent ?? null) === (Number.isInteger(parent) ? parent : null)) {
       return { file, rewritten: false };
     }
   } catch { /* missing, unreadable or corrupt — rewritten below */ }
-  await writeDiscovery({ port, workspace, token, persist, codex });
+  await writeDiscovery({ port, workspace, token, persist, codex, claude, version, parent });
   return { file, rewritten: true };
 }
 
@@ -822,7 +847,7 @@ export async function ensureDiscovery({ port, workspace, token, persist = null,
  * `run()` never rejects (every failure is a state), so awaiting this cannot
  * throw and cannot outlast one bounded check.
  */
-export function keepDiscovery({ port, workspace, token, persist = null, codex = true, intervalMs = 5000, onState = null } = {}) {
+export function keepDiscovery({ port, workspace, token, persist = null, codex = true, claude = true, version = "", parent = null, intervalMs = 5000, onState = null } = {}) {
   // null until the first outcome, which therefore always differs and is always
   // reported — the caller learns where it stands before anything else happens.
   let healthy = null;
@@ -830,7 +855,7 @@ export function keepDiscovery({ port, workspace, token, persist = null, codex =
   const run = async () => {
     let state;
     try {
-      const { rewritten } = await ensureDiscovery({ port, workspace, token, persist, codex });
+      const { rewritten } = await ensureDiscovery({ port, workspace, token, persist, codex, claude, version, parent });
       state = { ok: true, rewritten, file: discoveryPath(), error: null };
     } catch (err) {
       state = { ok: false, rewritten: false, file: discoveryPath(), error: err };

package/src/server/lan-engine.mjs

@@ -119,7 +119,10 @@ export function createEngine({
    */
   createSocket,
 } = {}) {
-  let cfg = { enabled: false, name: defaultName(), secret: "", shared: [], trusted: [], port: 0 };
+  let cfg = {
+    enabled: false, name: defaultName(), secret: "", shared: [], trusted: [], port: 0,
+    autoAsk: true, autoAccept: true,
+  };
   let identity = null;
   let beacon = null;
   let server = null;
@@ -341,8 +344,16 @@ export function createEngine({
         if (reply?.t !== "have" || !reply.sealed) { done.push({ ...step, ok: false, why: reply?.why ?? "refused" }); continue; }
         const blob = open(conn.key, reply.sealed, `${conn.peerFp}->${identity.fp}|${step.key}`);
         if (!blob) { done.push({ ...step, ok: false, why: "could not open" }); continue; }
-        const ok = await importAccount(blob);
-        done.push({ ...step, ok: !!ok, why: ok ? null : "import failed" });
+        // A verdict rather than a boolean, because "refused" and "kept the
+        // slot it already has" are different things to tell somebody and the
+        // second one used to be reported as success. A bare `true` is still
+        // accepted: the suite drives this with one.
+        // The step goes down with the blob: the wiring has to know WHICH account
+        // it is placing before it may treat a decline as an empty slot rather
+        // than as a healthy one.
+        const got = await importAccount(blob, step);
+        const ok = got === true || got?.ok === true;
+        done.push({ ...step, ok, why: ok ? null : (got?.why ?? "import failed") });
       }
       lastRound.set(peer.fp, { at: now(), name: peer.name, offered: theirs.accounts.length, done });
       if (done.length) onChange?.();
@@ -396,8 +407,23 @@ export function createEngine({
 
   return {
     async apply(next) {
+      /** The engine itself, for the callbacks handed to the socket below: they
+       *  outlive this call and `this` is not theirs to keep. */
+      const self = this;
       const was = cfg;
       cfg = { ...cfg, ...next };
+      // TURNING IT ON ANSWERS WHAT IS ALREADY WAITING. A person who switches
+      // this on with two rows sitting in the panel means those two as much as
+      // the next one, and leaving them queued behind a setting called
+      // "automatic" is the switch not doing what it says.
+      if (!was.autoAccept && cfg.autoAccept) {
+        for (const fp of [...pending.keys()]) this.accept(fp);
+      }
+      // The same for the other direction: switching `ask` on with four machines
+      // already listed asks those four.
+      if (!was.autoAsk && cfg.autoAsk) {
+        for (const [fp, p] of [...strangers]) if (!declined.has(fp) && !p.pub) this.accept(fp);
+      }
       const restart = !was.enabled !== !cfg.enabled
         || was.secret !== cfg.secret
         || was.name !== cfg.name;
@@ -451,6 +477,16 @@ export function createEngine({
         onPending: entry => {
           const had = pending.get(entry.fp);
           pending.set(entry.fp, { ...entry, at: had?.at ?? now(), lastAt: now() });
+          // SAY YES FOR SOMEBODY WHO SAID TO. It is the accept button and
+          // nothing else: the same pin, from the same key this handshake just
+          // proved, so the deck is trusted on its next attempt a few seconds
+          // later exactly as it would be if a person had pressed it. Nothing
+          // about the wire changes — this connection is still refused, because
+          // trust is read fresh per connection.
+          //
+          // A deck already told no does NOT come back this way: lan-socket
+          // refuses it before this is ever called.
+          if (cfg.autoAccept) { self.accept(entry.fp); return; }
           if (!had) onChange?.();
         },
       });
@@ -477,6 +513,16 @@ export function createEngine({
           // one of them drew a row offering to pair with the same machine.
           if (entry.host) for (const [fp, p] of strangers) if (p.host === entry.host && fp !== entry.fp) strangers.delete(fp);
           strangers.set(entry.fp, entry);
+          // ASK IT, which is what the `ask` verb on its row does and nothing
+          // more: the address goes on the dial list and the next round sends a
+          // request that somebody over there still has to answer. A beacon
+          // carries a fingerprint and no key, so nothing is pinned here — see
+          // accept, which is deliberate about the difference.
+          //
+          // Only a deck that is NEW is asked, or a beacon every thirty seconds
+          // would be thirty seconds of asking; and never one this deck's owner
+          // already turned away.
+          if (cfg.autoAsk && !had && !declined.has(entry.fp)) { self.accept(entry.fp); return; }
           // Only a deck that is new to us is news. A beacon every thirty
           // seconds from one already on the list is not a reason to redraw.
           if (!had) onChange?.();
@@ -712,6 +758,10 @@ export function createEngine({
         // which on a deck that has just started is the honest answer.
         checkedAt: roundAt,
         name: cfg.name,
+        // Whether this deck asks on its own, and whether a request that
+        // arrives is answered here or answered for you.
+        autoAsk: !!cfg.autoAsk,
+        autoAccept: !!cfg.autoAccept,
         fp: identity?.fp ?? null,
         // The address and port a person on another subnet types into the other
         // deck's field. Null when this machine has no ordinary one, which the

package/src/server/lan-socket.mjs

@@ -22,6 +22,57 @@
 // all — and it is why self-recognition is by fingerprint rather than by
 // address.
 import dgram from "node:dgram";
+import { networkInterfaces } from "node:os";
+
+/** An IPv4 dotted quad as four numbers, or null for anything that is not one. */
+function quad(text) {
+  const parts = String(text ?? "").split(".");
+  if (parts.length !== 4) return null;
+  const out = parts.map(p => Number(p));
+  return out.every(n => Number.isInteger(n) && n >= 0 && n <= 255) ? out : null;
+}
+
+/**
+ * The address that reaches every host on one interface's own subnet.
+ *
+ * `address | ~netmask`, which is the definition. Null for a /32, because a
+ * point-to-point link — a VPN tunnel, `utun` on macOS — has a directed
+ * broadcast equal to its own address, and sending a beacon to ourselves down a
+ * tunnel is a packet nobody wanted.
+ */
+export function directedBroadcast(address, netmask) {
+  const a = quad(address);
+  const m = quad(netmask);
+  if (!a || !m) return null;
+  if (m.every(o => o === 255)) return null;
+  return a.map((o, i) => o | (~m[i] & 255)).join(".");
+}
+
+/**
+ * Where a beacon has to go to be heard on this machine's networks.
+ *
+ * The limited broadcast first, because it is the one that works where a router
+ * or an access point filters the directed form, and because it is what every
+ * deck before this version sent — a machine that was fine stays fine. Then one
+ * per interface, which is what a multi-homed host actually needs: see announce.
+ *
+ * Loopback and IPv6 are skipped. A deck on `lo0` can only hear itself, and this
+ * protocol is IPv4 broadcast by construction — there is no such thing as an
+ * IPv6 broadcast address.
+ */
+export function broadcastTargets(ifaces) {
+  const out = ["255.255.255.255"];
+  for (const list of Object.values(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);
+    }
+  }
+  return out;
+}
 import net from "node:net";
 import { randomBytes } from "node:crypto";
 import {
@@ -84,6 +135,11 @@ export function createBeacon({
   // without saying so. The REAL socket is exercised by hand, two decks on one
   // machine, which works because a broadcast comes back to its own host.
   createSocket = opts => dgram.createSocket(opts),
+  // Injected for the same reason, and read PER ANNOUNCE rather than once: a
+  // laptop that joins a network, or brings a VPN up, grows an interface without
+  // restarting the deck, and a list captured at start would announce to the
+  // addresses it had at breakfast.
+  ifaces = () => networkInterfaces(),
 } = {}) {
   // Randomised per process. Two beacons from one fingerprint with different
   // instance ids mean the deck restarted between them, which is the signal to
@@ -104,20 +160,47 @@ export function createBeacon({
   let repliedAt = 0;
   const answered = new Set();
 
-  const payload = () => Buffer.from(JSON.stringify(beaconPayload({ name, fp, port, instance, host })));
+    const payload = () => Buffer.from(JSON.stringify(beaconPayload({ name, fp, port, instance, host })));
 
   const announce = () => {
     if (!sock) return;
-    // 255.255.255.255 rather than a multicast group, and rather than the
-    // subnet's own broadcast address. The subnet-directed form needs the
-    // netmask of whichever interface the packet leaves by, which changes when a
-    // VPN comes up; the limited broadcast needs nothing and is what Syncthing
-    // sends for the same reason.
-    sock.send(payload(), DISCOVERY_PORT, "255.255.255.255", err => {
-      // ENETUNREACH and EACCES are what a machine with no network, or a
-      // firewall, says. Both are states the panel reports rather than crashes.
-      if (err) onError?.("announce", err);
-    });
+    // EVERY BROADCAST ADDRESS THIS MACHINE HAS, not one.
+    //
+    // This used to send only to 255.255.255.255, on the argument that the
+    // limited broadcast "needs nothing" while a subnet-directed one needs the
+    // netmask of whichever interface the packet leaves by. The argument is
+    // sound and the machine disagreed with it. Measured on a Mac with Wi-Fi and
+    // a VPN tunnel up, from a bare node process with no deck involved:
+    //
+    //   send to 255.255.255.255  ->  EHOSTUNREACH
+    //   send to 192.168.1.255    ->  sent ok
+    //
+    // On a multi-homed host the limited broadcast has no single interface to
+    // leave by, and macOS refuses it rather than choosing. The deck went on
+    // announcing into nothing for as long as that machine was up: it could still
+    // HEAR colleagues, because receiving is per-port and not per-address, so the
+    // symptom was one-sided and looked like everybody else's problem.
+    //
+    // So the limited form stays — it is the one that works where a directed
+    // 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());
+    let left = targets.length;
+    const failed = [];
+    for (const to of targets) {
+      sock.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
+        // so every thirty seconds would be crying wolf about a working deck.
+        // No address working at all is a deck nobody can discover, which is
+        // exactly what the panel is for.
+        if (--left === 0 && failed.length === targets.length) {
+          onError?.("announce", new Error(`no broadcast address worked — ${failed.join(", ")}`));
+        }
+      });
+    }
   };
 
   const start = () => new Promise(resolve => {