@agentdeck/bridge 1.0.8 → 1.0.10

package/dist/broadcast.js

@@ -14,10 +14,12 @@ import { getLanIp } from '@agentdeck/shared';
  * (and 255.255.255.255 as a fallback) on UDP port 9121 every 2 seconds.
  * Subnet broadcast is unicast-friendly IGMP-wise and is forwarded by every
  * WiFi AP we have seen, so the device's UDP listener picks it up even when
- * mDNS is blocked. The beacon reuses the same fields the device needs from
- * the mDNS TXT records (ip / port / project / agent / token) so the existing
- * selection logic in mdns_discovery.cpp and udp_discovery.cpp share the same
- * BridgeInfo contract.
+ * mDNS is blocked. The beacon contains discovery metadata only (ip / port /
+ * project / agent) plus `authRequired`, matching the unauthenticated /health
+ * semantics: discovery says "a daemon is here and pairing is required" and
+ * nothing more. It must never contain the pairing token: UDP broadcast is
+ * visible to every peer on the segment, just like multicast mDNS. A client
+ * must already hold a token obtained through explicit pairing/provisioning.
  */
 const UDP_DISCOVERY_PORT = 9121;
 const UDP_BROADCAST_INTERVAL_MS = 2_000;
@@ -34,7 +36,7 @@ function computeSubnetBroadcast(ip) {
     }
     return `${parts[0]}.${parts[1]}.${parts[2]}.255`;
 }
-export function advertiseUdpBroadcast(port, projectName, agentType, token) {
+export function advertiseUdpBroadcast(port, projectName, agentType) {
     let stopped = false;
     let socket = null;
     let timer = null;
@@ -74,9 +76,10 @@ export function advertiseUdpBroadcast(port, projectName, agentType, token) {
             port,
             project: projectName,
             agent: agentType,
+            // Same signal the unauthenticated /health carries: tells a client to
+            // open its pairing flow instead of expecting a self-serve credential.
+            authRequired: true,
         };
-        if (token)
-            payload.token = token;
         const buf = Buffer.from(JSON.stringify(payload));
         // Limited broadcast — accepted by every AP, never routed across subnets.
         // This is the primary path when IGMP Snooping drops multicast.

package/dist/broadcast.js.map

@@ -1 +1 @@
-{"version":3,"file":"broadcast.js","sourceRoot":"","sources":["../src/broadcast.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"broadcast.js","sourceRoot":"","sources":["../src/broadcast.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AAyP1D,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAM,CAAC;AAOtF;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AA+BD,gFAAgF;AAChF,QAAA,MAAM,cAAc,EAAE,MAAM,CAAC,aAAa,GAAG,WAAW,GAAG,UAAU,EAAE,MAAM,CAI5E,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAsBjE;AAKD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAyBV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,OAAO,cAAc,EACtC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAIR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,OAAO,cAAc,EACtC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,OAAO,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAER;AAID,QAAA,MAAM,OAAO,SAAgB,CAAC;AAgqE9B,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzE;AAED,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AAyP1D,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAM,CAAC;AAOtF;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AA+BD,gFAAgF;AAChF,QAAA,MAAM,cAAc,EAAE,MAAM,CAAC,aAAa,GAAG,WAAW,GAAG,UAAU,EAAE,MAAM,CAI5E,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAsBjE;AAKD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAyBV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,OAAO,cAAc,EACtC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAIR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,OAAO,cAAc,EACtC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,OAAO,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAER;AAID,QAAA,MAAM,OAAO,SAAgB,CAAC;AAquE9B,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzE;AAED,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -365,6 +365,7 @@ program
     .option('--wake-word', 'Enable wake word voice assistant ("오픈클로")')
     .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
     .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--daemon-token <token>', 'Pairing token of the remote hub (~/.agentdeck/auth-token there); or set AGENTDECK_DAEMON_TOKEN')
     .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
     .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
@@ -380,6 +381,7 @@ program
         wakeWord: !!opts.wakeWord,
         remoteDaemon: !!opts.remoteDaemon,
         daemonHost: opts.daemonHost,
+        daemonToken: opts.daemonToken,
         weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
             mdns: false, // daemon-only — session bridges never advertise mDNS
@@ -402,6 +404,7 @@ program
     .option('--no-codex-hooks', 'Skip ~/.codex/config.toml hook install')
     .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
     .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--daemon-token <token>', 'Pairing token of the remote hub (~/.agentdeck/auth-token there); or set AGENTDECK_DAEMON_TOKEN')
     .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
     .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
@@ -439,6 +442,7 @@ program
         postit: opts.postit !== false,
         remoteDaemon: !!opts.remoteDaemon,
         daemonHost: opts.daemonHost,
+        daemonToken: opts.daemonToken,
         weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
             mdns: false, // daemon-only
@@ -461,6 +465,7 @@ program
     .option('--no-opencode-hooks', 'Skip OpenCode observer plugin install')
     .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
     .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--daemon-token <token>', 'Pairing token of the remote hub (~/.agentdeck/auth-token there); or set AGENTDECK_DAEMON_TOKEN')
     .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
     .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
@@ -497,6 +502,7 @@ program
         postit: opts.postit !== false,
         remoteDaemon: !!opts.remoteDaemon,
         daemonHost: opts.daemonHost,
+        daemonToken: opts.daemonToken,
         weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
             mdns: false,
@@ -515,6 +521,7 @@ program
     .option('--local', 'Disable all device modules')
     .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
     .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--daemon-token <token>', 'Pairing token of the remote hub (~/.agentdeck/auth-token there); or set AGENTDECK_DAEMON_TOKEN')
     // Commander-layer half only: monitor spawns no agent command to weave into.
     .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS for this invocation')
     .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
@@ -530,6 +537,7 @@ program
         debug: opts.debug,
         remoteDaemon: !!opts.remoteDaemon,
         daemonHost: opts.daemonHost,
+        daemonToken: opts.daemonToken,
         weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : undefined,
     });
@@ -550,7 +558,7 @@ daemon
     .option('-f, --foreground', 'Run in foreground (default: background fork)')
     .option('--wake-word', 'Enable wake word voice assistant ("오픈클로")')
     .action(async (opts) => {
-    const { findExistingDaemon, probeDaemonHealth, readDaemonInfo, removeDaemonInfo, removeDaemonSession, requestDaemonStandDown, requestDaemonShutdown, waitForDaemonExit } = await import('./session-registry.js');
+    const { findExistingDaemon, probeDaemonHealth, readDaemonInfo, removeDaemonInfo, removeDaemonSession, requestDaemonStandDown, requestDaemonShutdown, waitForDaemonExit, waitForPortBindable } = await import('./session-registry.js');
     // Reverse two-tier upgrade path: the macOS app may already own the canonical
     // port with its in-process Swift daemon (Tier 1 — limited: no ADB devices,
     // no subscription usage, …). A plain "already running → exit" would strand
@@ -571,13 +579,52 @@ daemon
                 await requestDaemonShutdown(targetPort);
                 acked = true; // shutdown is best-effort (no ack body); rely on the exit wait
             }
-            if (acked && await waitForDaemonExit(targetPort, 12000)) {
+            // Two conditions, not one. `waitForDaemonExit` proves the app stopped
+            // answering; `waitForPortBindable` proves the socket is actually gone.
+            // The app releases the port with NWListener.cancel(), which returns
+            // before the teardown completes — binding on the first signal alone is
+            // what silently demoted this daemon to the 9121 fallback and left the
+            // canonical port ownerless.
+            if (acked
+                && await waitForDaemonExit(targetPort, 12000)
+                // 30s, and that is not padding. Cancelling the app's NWListener does
+                // not free the port: macOS keeps a NECP reservation on it for ~14s
+                // afterwards, during which `lsof` shows no sockets at all and bind()
+                // still returns EADDRINUSE (measured 2026-08-06 — bindable at ~17s).
+                // Anything shorter gives up while the kernel, not the app, is holding
+                // the port. The app's takeover-yield window is longer still (45s), so
+                // it stays off the port until well after this wait has claimed it.
+                && await waitForPortBindable(targetPort, 30000)) {
                 log(`App daemon yielded port ${targetPort}. Starting CLI daemon…`);
                 // fall through — port is clear, proceed to bind below
             }
             else {
-                log(`The AgentDeck app did not yield port ${targetPort} in time. Quit the app and retry 'agentdeck daemon start', or start on a different port with -p.`);
-                process.exit(1);
+                // The app yielded but the PORT did not come back, and that is often
+                // not the app's doing: a WiFi device that has gone to sleep with bytes
+                // still queued to it leaves its socket in LAST_ACK on this port, and
+                // TCP holds that until it exhausts retransmits — minutes, sometimes.
+                // Network.framework exposes no SO_LINGER, so the app cannot RST out of
+                // it (measured 2026-08-06: two sleeping ESP32 boards, 11901 and 4
+                // bytes queued, were the only things left on 9120).
+                //
+                // Carry on rather than exiting. The daemon binds a fallback port and
+                // writes it to daemon.json, which is what every client resolves
+                // through and what the app itself re-reads when its yield window ends
+                // — so the deck keeps working. What must NOT happen is this being
+                // silent, which is how the canonical port ended up owned by nobody
+                // with the CLI reporting success.
+                log(`The AgentDeck app yielded port ${targetPort} but the port has not been released `
+                    + `(usually a sleeping WiFi device holding a half-closed socket on it).`);
+                if (opts.port) {
+                    // The port was ASKED for, not defaulted to. Quietly binding a
+                    // different one would answer a question the user did not ask;
+                    // an explicit choice fails loudly instead.
+                    log(`Quit the AgentDeck app and retry, or choose another port.`);
+                    process.exit(1);
+                }
+                log(`Starting on a fallback port instead — clients resolve it from daemon.json. `
+                    + `For the canonical port, quit the AgentDeck app and retry, or pass -p.`);
+                // fall through to normal port selection
             }
         }
         else {
@@ -1287,6 +1334,29 @@ program
         // qrcode not available
     }
 });
+program
+    .command('token')
+    .description('Show or rotate the pairing token (~/.agentdeck/auth-token)')
+    .argument('[action]', "'show' (default) prints the token; 'rotate' replaces it", 'show')
+    .action(async (action) => {
+    const { getOrCreateToken, rotateToken } = await import('./auth.js');
+    if (action === 'rotate') {
+        const token = rotateToken();
+        log(`New pairing token: ${token}`);
+        log('All paired clients must re-pair: rescan the QR on companion apps (agentdeck qr),');
+        log('re-provision WiFi ESP32 boards (they re-provision automatically over USB serial),');
+        log('and update AGENTDECK_DAEMON_TOKEN on any remote workers.');
+        log('Restart the daemon (agentdeck daemon restart) so it picks up the new token.');
+    }
+    else if (action === 'show') {
+        log(getOrCreateToken());
+        log('(Anyone with this token can control your sessions over the LAN — treat it like a password.)');
+    }
+    else {
+        console.error(`Unknown action '${action}' — use 'show' or 'rotate'.`);
+        process.exitCode = 1;
+    }
+});
 program
     .command('inject-test')
     .description('Test observed-answer injection into a terminal or app (tuning aid)')