@agentdeck/bridge 1.0.20 → 1.0.22

package/dist/cli.js

@@ -8,10 +8,13 @@ import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { request } from 'http';
 import { BRIDGE_WS_PORT } from './types.js';
-import { SESSION_WEIGHT_MIN, SESSION_WEIGHT_MAX } from '@agentdeck/shared';
+import { SESSION_WEIGHT_MIN, SESSION_WEIGHT_MAX, stopDeliveryLoss } from '@agentdeck/shared';
 import { ensureBleRuntime, getBleRuntimeStatus } from './python-ble-runtime.js';
 import { TASK_NAME, installWindowsTask, taskExists, runWindowsTask, endWindowsTask, deleteWindowsTask, } from './windows-service.js';
-import { deriveRemoteAttachOpts } from './session-registry.js';
+import { deriveRemoteAttachOpts, daemonPortWindow, isDefaultDaemonPortWindow, DEFAULT_DAEMON_PORT_WINDOW, } from './session-registry.js';
+// From modules/types.js, not modules/index.js: the latter pulls the whole
+// device stack (serial, Pixoo, BLE) into `agentdeck --help`.
+import { allModulesOff } from './modules/types.js';
 import { SERVICE_NAME, hasSystemctl, unitExists, installUnit, startUnit, disableUnit, getUnitPath, getDataDir, } from './linux-service.js';
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
@@ -41,6 +44,22 @@ async function refreshClaudeHooks() {
         log(`Claude hooks unavailable: ${String(err)}`);
     }
 }
+/** Kiro v3 global hooks preserve native `kiro-cli --v3` launch behavior. */
+async function refreshKiroHooks() {
+    try {
+        const { installKiroHooksIfNeeded } = await import('@agentdeck/hooks');
+        const result = installKiroHooksIfNeeded();
+        if (result.installed) {
+            log(`Kiro v3 lifecycle hooks installed/refreshed in ${result.path}`);
+        }
+        else if (result.reason) {
+            log(`Kiro hooks skipped: ${result.reason}`);
+        }
+    }
+    catch (err) {
+        log(`Kiro hooks unavailable: ${String(err)}`);
+    }
+}
 /**
  * Parse a `--weight <n>` value into an integer sort override. Rejects
  * non-integers so a typo (`--weight foo`) fails loudly instead of silently
@@ -65,6 +84,19 @@ function formatBytes(value) {
         return `${Math.round(bytes / 1024)}KB`;
     return `${bytes}B`;
 }
+/** Parse a `--since`-style lookback (`90m`, `6h`, `3d`, `2w`) into milliseconds.
+ *  Returns null for anything unrecognized so the caller can reject it loudly —
+ *  silently defaulting a typo'd window would report a rate over the wrong span. */
+function parseLookbackWindow(value) {
+    const m = /^(\d+(?:\.\d+)?)\s*(m|h|d|w)$/i.exec(String(value ?? '').trim());
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    const unit = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 }[m[2].toLowerCase()];
+    return n * unit;
+}
 function postJsonWithTimeout(urlString, body, timeoutMs) {
     return new Promise((resolve, reject) => {
         const payload = JSON.stringify(body);
@@ -113,9 +145,54 @@ function getAgentdeckBin() {
         return join(distDir, 'cli.js');
     }
 }
-function buildPlist() {
+/**
+ * Extra `daemon start` argv the autostart unit must carry.
+ *
+ * A posture that only applies when typed by hand is not a posture: an
+ * enterprise install IS an autostart install, so the flags have to live in the
+ * LaunchAgent / Scheduled Task / systemd unit. Baking them into argv (rather
+ * than an environment variable) is the one mechanism all three writers already
+ * have — Task Scheduler has no environment element at all.
+ */
+/**
+ * Warn before handing out a LAN credential that cannot be used.
+ *
+ * `agentdeck qr` and `agentdeck pair` both hand a phone or a board a
+ * `ws://<lan-ip>:<port>` endpoint. Against a loopback-only daemon that endpoint
+ * refuses every connection, and nothing on either side says why — the user sees
+ * a QR that "doesn't work". Ask the daemon what posture it is in (that is what
+ * `posture` on `/health` is for) and say so, rather than printing a dead URL.
+ * Silent on any probe failure: this is an explanation, never a gate.
+ */
+async function warnIfLoopbackPosture(port) {
+    try {
+        const { probeDaemonHealth } = await import('./session-registry.js');
+        const health = await probeDaemonHealth(port);
+        if (health?.posture?.loopbackOnly !== true)
+            return;
+        log('Note: this daemon is running loopback-only — it is bound to 127.0.0.1 and refuses LAN connections.');
+        log('      A phone, tablet or WiFi board cannot reach the address below, whatever credential it holds.');
+        log('      Restart without --loopback (and unset AGENTDECK_LOOPBACK_ONLY) to pair a LAN device.');
+    }
+    catch {
+        /* daemon not answering — nothing to say about its posture */
+    }
+}
+export function daemonPostureArgs(opts) {
+    const args = [];
+    // --enterprise is the admin-facing spelling of the loopback posture: bind
+    // 127.0.0.1 and put nothing on the wire. It deliberately does NOT imply
+    // --local — some sites want hardware on a lab subnet with discovery off.
+    if (opts.local)
+        args.push('--local');
+    if (opts.loopback || opts.enterprise)
+        args.push('--loopback');
+    return args;
+}
+export function buildPlist(extraArgs = []) {
     const bin = getAgentdeckBin();
     const logDir = join(homedir(), '.agentdeck');
+    const extra = extraArgs.map((a) => `\n    <string>${a}</string>`).join('');
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -127,7 +204,7 @@ function buildPlist() {
     <string>${bin}</string>
     <string>daemon</string>
     <string>start</string>
-    <string>--foreground</string>
+    <string>--foreground</string>${extra}
   </array>
   <key>RunAtLoad</key>
   <true/>
@@ -150,9 +227,18 @@ function buildPlist() {
 }
 // ===== Helpers =====
 async function stopDaemon(port) {
-    const { readDaemonInfo, findDaemonPort } = await import('./session-registry.js');
+    const { readDaemonInfo, findDaemonPort, probeDaemonHealth } = await import('./session-registry.js');
+    const { isForeignDaemon } = await import('./daemon-takeover.js');
     const info = readDaemonInfo();
     const targetPort = info?.httpPort ?? info?.port ?? findDaemonPort() ?? port;
+    // The registry resolves to this user's own daemon, but the `-p` fallback
+    // resolves to whatever is on that port — which on a shared host is somebody
+    // else's daemon, and `/shutdown` is trusted purely for being local.
+    if (isForeignDaemon(await probeDaemonHealth(targetPort))) {
+        log(`Port ${targetPort} is held by another user's daemon — refusing to stop it.`);
+        log(`You have no daemon of your own running.`);
+        return;
+    }
     try {
         await fetch(`http://127.0.0.1:${targetPort}/shutdown`, {
             method: 'POST',
@@ -396,12 +482,15 @@ program
         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
+        modules: opts.local ? allModulesOff() : {
+            // Off by default, ADB back on: a session bridge is an internal hook/PTY
+            // process. Only the daemon hub advertises itself or drives devices —
+            // and spelling that as "all off, then add back" is what stops the next
+            // module from arriving as an implicit 'auto' here (idotmatrix did, and
+            // every session spawned a second Python BLE client alongside the
+            // daemon's).
+            ...allModulesOff(),
             adb: opts.adb !== false ? 'auto' : false,
-            serial: false, // daemon-only — session bridges never talk to ESP32
-            pixoo: false, // daemon-only — session bridges never talk to Pixoo
-            timebox: false, // daemon-only — session bridges never talk to Timebox
         },
     });
 });
@@ -458,12 +547,11 @@ program
         daemonToken: opts.daemonToken,
         weight: opts.weight,
         codexHooksExpected: opts.codexHooks !== false,
-        modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
-            mdns: false, // daemon-only
+        modules: opts.local ? allModulesOff() : {
+            // See the claude action: all off, ADB back on. Session bridges are
+            // internal hook/PTY processes; only the daemon hub drives devices.
+            ...allModulesOff(),
             adb: opts.adb !== false ? 'auto' : false,
-            serial: false, // daemon-only
-            pixoo: false, // daemon-only
-            timebox: false, // daemon-only
         },
     });
 });
@@ -518,12 +606,10 @@ program
         daemonHost: opts.daemonHost,
         daemonToken: opts.daemonToken,
         weight: opts.weight,
-        modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
-            mdns: false,
+        modules: opts.local ? allModulesOff() : {
+            // See the claude action: all off, ADB back on.
+            ...allModulesOff(),
             adb: opts.adb !== false ? 'auto' : false,
-            serial: false,
-            pixoo: false,
-            timebox: false,
         },
     });
 });
@@ -553,7 +639,7 @@ program
         daemonHost: opts.daemonHost,
         daemonToken: opts.daemonToken,
         weight: opts.weight,
-        modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : undefined,
+        modules: opts.local ? allModulesOff() : undefined,
     });
 });
 // The worktree-compare feature ("cockpit") was extracted into its own
@@ -598,10 +684,19 @@ async function openDaemonLogs(logDir) {
 daemon
     .command('start')
     .description('Start monitoring daemon (WS + mDNS + Gateway proxy)')
-    .option('-p, --port <port>', 'Server port', String(BRIDGE_WS_PORT))
+    // No default value on purpose: an absent `-p` must be distinguishable from a
+    // typed one. The port then resolves through AGENTDECK_DAEMON_PORT and the
+    // persisted `daemonPort` (see `agentdeck daemon port`), and the "was this
+    // port asked for?" test below has something real to test. With commander's
+    // old default of "9120" that test was always true, so the branch meant to
+    // start on a fallback port could never be reached.
+    .option('-p, --port <port>', `Server port (default: the persisted daemonPort, else ${BRIDGE_WS_PORT})`)
     .option('-d, --debug', 'Enable debug logging')
     .option('-f, --foreground', 'Run in foreground (default: background fork)')
     .option('--wake-word', 'Enable wake word voice assistant ("오픈클로")')
+    .option('--local', 'Disable all device modules (no mDNS, UDP beacon, LAN sweep, BLE, ADB or serial); still binds all interfaces for paired companion apps')
+    .option('--loopback', 'Bind 127.0.0.1 only and emit nothing onto the LAN (no mDNS, UDP beacon, LAN sweep or BLE; USB serial and ADB reverse stay on). Same as AGENTDECK_LOOPBACK_ONLY=1')
+    .option('--port-window <range>', 'Work in a non-default daemon port window, e.g. 9200-9209. Only for running a throwaway daemon beside the real one: the singleton guard sweeps this range, and a daemon outside the documented 9120-9139 window is invisible to clients that scan it. Same as AGENTDECK_PORT_WINDOW')
     .action(async (opts) => {
     const { findExistingDaemon, probeDaemonHealth, readDaemonInfo, removeDaemonInfo, removeDaemonSession, requestDaemonStandDown, requestDaemonShutdown, waitForDaemonExit, waitForPortBindable } = await import('./session-registry.js');
     const { adoptPeerToken } = await import('./auth.js');
@@ -613,79 +708,53 @@ daemon
     // CLI daemon can take over with the full feature set, then wait for the port
     // to clear before binding. A real Node daemon on the port still means
     // "already running".
-    const targetPort = opts.port ? parseInt(String(opts.port), 10) : BRIDGE_WS_PORT;
+    // Set before anything reads the window: the singleton sweep, the port
+    // allocator and the daemon itself all resolve it per call, and this action
+    // is the first place the flag is known.
+    if (opts.portWindow)
+        process.env.AGENTDECK_PORT_WINDOW = String(opts.portWindow);
+    const portWindow = daemonPortWindow();
+    if (!isDefaultDaemonPortWindow(portWindow)) {
+        const [lo, hi] = portWindow;
+        const [dlo, dhi] = DEFAULT_DAEMON_PORT_WINDOW;
+        log(`Port window ${lo}-${hi} (default ${dlo}-${dhi}).`);
+        log(`Note: clients discover daemons by scanning ${dlo}-${dhi}, so a daemon outside that range `
+            + `is reachable only by explicit host/port. Use this for a throwaway daemon, not the real one.`);
+        if (opts.portWindow && String(opts.portWindow).trim() && lo === dlo && hi === dhi) {
+            log(`(--port-window ${opts.portWindow} was not parseable — falling back to the default window.)`);
+        }
+    }
+    else if (opts.portWindow) {
+        log(`--port-window ${opts.portWindow} was not parseable — using the default window.`);
+    }
+    // The preferred port — what this daemon intends to serve. Everything below
+    // (the stand-down negotiation, the singleton guard, the bind) aims at it.
+    const { resolveDaemonPort, describeDaemonPortSource, DAEMON_PORT_MIN, DAEMON_PORT_MAX } = await import('./daemon-port.js');
+    const preferredPort = resolveDaemonPort({ flag: opts.port });
+    if (opts.port && preferredPort.source !== 'flag') {
+        log(`--port ${opts.port} is not a valid port (${DAEMON_PORT_MIN}-${DAEMON_PORT_MAX}) — using ${preferredPort.port} instead.`);
+    }
+    if (preferredPort.source === 'settings' || preferredPort.source === 'env') {
+        log(`Preferred port ${preferredPort.port} (${describeDaemonPortSource(preferredPort.source)}).`);
+    }
+    const targetPort = preferredPort.port;
+    // Adopting a credential from the incumbent and asking it to stand down are
+    // both same-user-only operations, and the whole decision — including who
+    // owns that process — lives in `negotiateIncumbentDaemon` so it can be
+    // driven in tests against a foreign-owned incumbent.
+    const { negotiateIncumbentDaemon } = await import('./daemon-takeover.js');
     const incumbent = await probeDaemonHealth(targetPort);
-    if (incumbent?.mode === 'daemon') {
-        // Take over the fleet's credential along with the port. The app's daemon
-        // keeps its token inside its sandbox container, unreadable from here, so
-        // this loopback answer is the only place we can learn what every paired
-        // board is currently holding. Adopting it BEFORE the stand-down means the
-        // handover costs no device its pairing.
-        if (adoptPeerToken(incumbent.pairingToken)) {
-            log(`Adopted the incumbent daemon's pairing token so paired devices survive the handover.`);
-        }
-        if (incumbent.isSwift) {
-            log(`AgentDeck app's in-process daemon holds port ${targetPort} — requesting stand-down to take over with the full CLI feature set…`);
-            // Prefer /stand-down (clean demote: the app stays running as a client).
-            // Fall back to /shutdown for older app builds that predate the endpoint.
-            let acked = await requestDaemonStandDown(targetPort);
-            if (!acked) {
-                await requestDaemonShutdown(targetPort);
-                acked = true; // shutdown is best-effort (no ack body); rely on the exit wait
-            }
-            // 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 {
-                // 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 {
-            log(`Daemon already running on port ${targetPort}. Use 'agentdeck daemon stop' first.`);
-            process.exit(0);
-        }
-    }
+    const outcome = await negotiateIncumbentDaemon({ port: targetPort, incumbent, portWasExplicit: !!opts.port }, {
+        adoptToken: adoptPeerToken,
+        standDown: requestDaemonStandDown,
+        shutdown: requestDaemonShutdown,
+        waitForExit: waitForDaemonExit,
+        waitForBindable: waitForPortBindable,
+    });
+    if (outcome === 'already-running')
+        process.exit(0);
+    if (outcome === 'refuse')
+        process.exit(1);
     const daemonInfo = readDaemonInfo();
     if (daemonInfo) {
         const probePort = daemonInfo.httpPort ?? daemonInfo.port;
@@ -712,12 +781,26 @@ daemon
         const logDir = join(homedir(), '.agentdeck');
         const scriptPath = fileURLToPath(import.meta.url);
         const args = [scriptPath, 'daemon', 'start', '--foreground'];
-        if (opts.port !== String(BRIDGE_WS_PORT))
-            args.push('-p', opts.port);
+        // Forward `-p` only when the user typed it. For every other source the
+        // child re-resolves from the same inherited environment and the same
+        // settings.json, so it lands on the same port — and it keeps its own
+        // provenance, which a forwarded `-p` would flatten into "asked for".
+        if (preferredPort.source === 'flag')
+            args.push('-p', String(preferredPort.port));
         if (opts.debug)
             args.push('-d');
         if (opts.wakeWord)
             args.push('--wake-word');
+        // The posture flags must survive the fork — the forked process IS the
+        // daemon, and a posture that only applies to the parent is no posture.
+        if (opts.local)
+            args.push('--local');
+        if (opts.loopback)
+            args.push('--loopback');
+        // Same reason as the posture flags: the forked process IS the daemon, and
+        // a window that only applies to the parent moves nothing.
+        if (opts.portWindow)
+            args.push('--port-window', String(opts.portWindow));
         const [out, err] = await openDaemonLogs(logDir);
         const child = spawn(process.execPath, args, {
             detached: true,
@@ -730,9 +813,12 @@ daemon
     }
     const { startDaemon } = await import('./daemon-server.js');
     await startDaemon({
-        port: parseInt(opts.port, 10),
+        port: preferredPort.port,
+        portSource: preferredPort.source,
         debug: opts.debug,
         wakeWord: !!opts.wakeWord,
+        local: !!opts.local,
+        loopback: !!opts.loopback,
     });
 });
 daemon
@@ -745,18 +831,57 @@ daemon
 daemon
     .command('restart')
     .description('Stop and restart the daemon')
-    .option('-p, --port <port>', 'Server port', String(BRIDGE_WS_PORT))
+    .option('-p, --port <port>', 'Server port to restart on (default: the persisted daemonPort)')
     .option('-d, --debug', 'Enable debug logging')
+    .option('--local', 'Disable all device modules on the restarted daemon')
+    .option('--loopback', 'Restart with a loopback-only posture (see `daemon start --loopback`)')
     .action(async (opts) => {
-    await stopDaemon(parseInt(opts.port, 10));
+    // Two different ports, and conflating them is what made this command lose
+    // the posture. The daemon must be PROBED and STOPPED where it actually is
+    // (daemon.json — which is 9121+ whenever it once fell back), but RESTARTED
+    // on the port it prefers. Probing 9120 blindly found nothing whenever the
+    // daemon had fallen back, and "no posture found" reads exactly like "open
+    // posture" — a silent enterprise downgrade, which is the one thing this
+    // inheritance exists to prevent.
+    const { probeDaemonHealth: probeHealth, readDaemonInfo, findDaemonPort } = await import('./session-registry.js');
+    const { resolveDaemonPort } = await import('./daemon-port.js');
+    const preferredPort = resolveDaemonPort({ flag: opts.port });
+    const info = readDaemonInfo();
+    const runningPort = info?.httpPort ?? info?.port ?? findDaemonPort() ?? preferredPort.port;
+    // Read the running daemon's posture BEFORE stopping it. A restart that
+    // defaults to "advertise everything" would silently undo an enterprise
+    // install — the LaunchAgent / Scheduled Task / systemd unit carries the
+    // posture in its argv, and this command does not read those three files.
+    // Explicit flags still win; inheritance only fills in what wasn't asked for.
+    const running = await probeHealth(runningPort);
+    const inheritedLocal = running?.posture?.noDeviceModules === true;
+    const inheritedLoopback = running?.posture?.loopbackOnly === true;
+    const useLocal = !!opts.local || inheritedLocal;
+    const useLoopback = !!opts.loopback || inheritedLoopback;
+    if (running && runningPort !== preferredPort.port) {
+        log(`Daemon is on port ${runningPort} but prefers ${preferredPort.port} — restarting there.`);
+    }
+    await stopDaemon(runningPort);
     // Wait for port release + session cleanup
     await new Promise(resolve => setTimeout(resolve, 1500));
     const scriptPath = fileURLToPath(import.meta.url);
     const args = [scriptPath, 'daemon', 'start', '--foreground'];
-    if (opts.port !== String(BRIDGE_WS_PORT))
-        args.push('-p', opts.port);
+    // Same rule as `daemon start`: forward `-p` only when it was typed, so the
+    // child keeps the real provenance of its port.
+    if (preferredPort.source === 'flag')
+        args.push('-p', String(preferredPort.port));
     if (opts.debug)
         args.push('-d');
+    if (useLocal)
+        args.push('--local');
+    if (useLoopback)
+        args.push('--loopback');
+    if ((inheritedLocal && !opts.local) || (inheritedLoopback && !opts.loopback)) {
+        log(`Carrying over the running daemon's posture (${[
+            inheritedLoopback ? 'loopback-only' : null,
+            inheritedLocal ? 'no device modules' : null,
+        ].filter(Boolean).join(', ')}).`);
+    }
     const [rOut, rErr] = await openDaemonLogs(join(homedir(), '.agentdeck'));
     const child = spawn(process.execPath, args, {
         detached: true,
@@ -777,11 +902,28 @@ daemon
     const info = readDaemonInfo();
     const sessions = listActive();
     const d = sessions.find(s => s.agentType === 'daemon');
-    const targetPort = info?.httpPort ?? info?.port ?? d?.port ?? port;
+    // Two ways to arrive at a port, and only one of them identifies OUR daemon.
+    // `registryPort` comes from this install's own daemon.json / sessions.json;
+    // the `?? port` tail is a blind probe of the default, which on a machine
+    // running a second AgentDeck answers with *its* daemon. Anything that
+    // claims something about "this daemon" may only use the registry-resolved
+    // port — a note attached to a stranger's daemon is worse than no note.
+    const registryPort = info?.httpPort ?? info?.port ?? d?.port ?? null;
+    const targetPort = registryPort ?? port;
     try {
         const res = await fetch(`http://127.0.0.1:${targetPort}/health`);
         const data = await res.json();
         log(`Daemon status (port ${targetPort}): ${JSON.stringify(data, null, 2)}`);
+        // A daemon on a fallback port keeps working — clients resolve it from
+        // daemon.json — so nothing else ever says it happened. Without this line
+        // the only symptom is that the canonical port is owned by nobody.
+        const { resolveDaemonPort, describeDaemonPortSource } = await import('./daemon-port.js');
+        const preferred = resolveDaemonPort();
+        if (registryPort !== null && preferred.port !== registryPort) {
+            log(`Note: this daemon prefers port ${preferred.port} (${describeDaemonPortSource(preferred.source)}) `
+                + `but is serving ${registryPort} — it fell back at startup. `
+                + `Run 'agentdeck daemon restart' to aim at ${preferred.port} again.`);
+        }
     }
     catch {
         if (info)
@@ -792,13 +934,70 @@ daemon
         process.exit(1);
     }
 });
+daemon
+    .command('port')
+    .argument('[port]', 'Port to persist as this machine\'s preferred daemon port')
+    .description('Show or set the persisted daemon port (settings.json daemonPort)')
+    .option('--clear', 'Forget the persisted port and go back to the built-in default')
+    .action(async (portArg, opts) => {
+    const { resolveDaemonPort, describeDaemonPortSource, parseDaemonPort, preferredDaemonPortFrom, DAEMON_PORT_SETTING_KEY, DAEMON_PORT_MIN, DAEMON_PORT_MAX, } = await import('./daemon-port.js');
+    const { loadDaemonSettings, updateDaemonSetting, ownSettingsPath } = await import('./daemon-settings.js');
+    const { readDaemonInfo } = await import('./session-registry.js');
+    if (opts.clear) {
+        updateDaemonSetting(DAEMON_PORT_SETTING_KEY, undefined);
+        log(`Cleared the persisted daemon port in ${ownSettingsPath()}.`);
+    }
+    else if (portArg !== undefined) {
+        const parsed = parseDaemonPort(portArg);
+        if (parsed === null) {
+            // Strict here, lenient in the reader: a typo must fail where the user
+            // can see it, not silently revert to 9120 six weeks later.
+            log(`"${portArg}" is not a valid port. Give an integer between ${DAEMON_PORT_MIN} and ${DAEMON_PORT_MAX}.`);
+            process.exit(1);
+        }
+        updateDaemonSetting(DAEMON_PORT_SETTING_KEY, parsed);
+        log(`Persisted daemon port ${parsed} in ${ownSettingsPath()}.`);
+        log(`It takes effect on the next 'agentdeck daemon restart'.`);
+        // A preferred port outside the sweep window is a quiet split-brain: the
+        // singleton guard scans the window, so a second daemon started later
+        // never sees this one and both run. Same warning `--port-window` prints,
+        // for the same reason — the window is a discovery contract, not a range
+        // of convenience.
+        const [lo, hi] = daemonPortWindow();
+        if (parsed < lo || parsed > hi) {
+            log(`Warning: ${parsed} is outside the daemon port window ${lo}-${hi}. Clients that discover `
+                + `by scanning that window will not find this daemon, and the singleton guard will not see `
+                + `it either — a second daemon could start alongside it. Move the window too `
+                + `(AGENTDECK_PORT_WINDOW), or pick a port inside it.`);
+        }
+    }
+    const resolved = resolveDaemonPort();
+    const stored = preferredDaemonPortFrom(loadDaemonSettings());
+    log(`Preferred port: ${resolved.port} (${describeDaemonPortSource(resolved.source)})`);
+    log(`Persisted value: ${stored ?? '(none)'}`);
+    const info = readDaemonInfo();
+    if (info) {
+        log(`Running daemon: port ${info.port} (PID ${info.pid})`
+            + (info.port === resolved.port ? '' : ' — on a fallback port, not its preferred one'));
+    }
+    else {
+        log('Running daemon: none found');
+    }
+});
 daemon
     .command('install')
     .description('Install daemon auto-start (LaunchAgent on macOS, Scheduled Task on Windows, systemd --user unit on Linux)')
-    .action(async () => {
+    .option('--enterprise', 'Install with a loopback-only posture: bind 127.0.0.1, no mDNS, no UDP beacon, no LAN sweep, no BLE, no ADB')
+    .option('--local', 'Install with all device modules disabled')
+    .option('--loopback', 'Alias for --enterprise')
+    .action(async (opts) => {
+    const postureArgs = daemonPostureArgs(opts);
+    if (postureArgs.length > 0) {
+        log(`Autostart posture: ${postureArgs.join(' ')} (baked into the autostart unit's arguments).`);
+    }
     if (process.platform === 'win32') {
         try {
-            installWindowsTask();
+            installWindowsTask(postureArgs);
             log(`Scheduled task '${TASK_NAME}' registered. Daemon will auto-start on logon.`);
         }
         catch (e) {
@@ -820,6 +1019,7 @@ daemon
             log('Task registered; immediate start failed — it will start on next logon.');
         }
         await refreshClaudeHooks();
+        await refreshKiroHooks();
         // Install Codex lifecycle hooks for parity with the macOS install path.
         try {
             const { installCodexHooksIfNeeded } = await import('@agentdeck/hooks');
@@ -857,7 +1057,7 @@ daemon
         }
         else {
             try {
-                installUnit();
+                installUnit(postureArgs);
                 startUnit();
                 log(`systemd user unit '${SERVICE_NAME}' installed and started.`);
                 log(`Unit file: ${getUnitPath()}`);
@@ -879,6 +1079,7 @@ daemon
             }
         }
         await refreshClaudeHooks();
+        await refreshKiroHooks();
         // Install Codex + OpenCode hooks for parity with the macOS/Windows paths.
         try {
             const { installCodexHooksIfNeeded } = await import('@agentdeck/hooks');
@@ -910,7 +1111,7 @@ daemon
         log('LaunchAgent is macOS-only');
         process.exit(1);
     }
-    const plist = buildPlist();
+    const plist = buildPlist(postureArgs);
     writeFileSync(PLIST_PATH, plist, 'utf-8');
     log(`Wrote ${PLIST_PATH}`);
     try {
@@ -920,6 +1121,7 @@ daemon
     execSync(`launchctl load "${PLIST_PATH}"`);
     log('LaunchAgent loaded. Daemon will auto-start on login.');
     await refreshClaudeHooks();
+    await refreshKiroHooks();
     // Install Codex lifecycle hooks parallel to the LaunchAgent install
     // so the daemon hub gets codex_* events as soon as Codex CLI runs.
     try {
@@ -1321,6 +1523,19 @@ program
             throw new Error(String(body.error ?? `HTTP ${statusCode}`));
         }
         log(`Staged for ${body.board}: ${formatBytes(body.bytes)} md5=${body.md5}`);
+        if (body.pullSeen === false) {
+            // "Staged" is a promise the board has to keep, and only a board that
+            // pulls the feed can keep it. Boards in this repo's esp32/ tree hold a
+            // live WebSocket and never pull, so a stage for one is a reservation
+            // nothing will ever collect — reported as success, which is how a board
+            // sat a full release behind while its OTA looked handled.
+            log(`WARNING: this daemon has seen no feed pull from ${body.board} since it started.`);
+            log('  Only pull-sync boards (XTeink X3/X4/M6) fetch staged firmware. A board that');
+            log('  holds a live WS never asks for it, so this stage may never install.');
+            log('  Check `agentdeck devices` (card-feed clients); otherwise flash over USB serial.');
+            log('  Verify with the board\'s reported buildHash, never with this message.');
+            return;
+        }
         log('The board installs it on its next feed pull (battery cadence: typically within 15-60 min).');
         return;
     }
@@ -1364,6 +1579,7 @@ program
         }
     }
     getOrCreateToken();
+    await warnIfLoopbackPosture(port);
     const url = getWsUrl(port);
     log(`\nPairing URL:\n  ${url}\n`);
     try {
@@ -1395,6 +1611,9 @@ program
         ? opts.adopt
         : (typeof opts.adopt === 'string' ? [opts.adopt] : []);
     const daemon = `http://127.0.0.1:${port}`;
+    // A pairing window against a loopback-only daemon can never be redeemed:
+    // the peer it is meant for cannot open a socket to this host at all.
+    await warnIfLoopbackPosture(port);
     let opened;
     try {
         const res = await fetch(`${daemon}/pair/open`, {
@@ -1521,12 +1740,29 @@ program
     }
 });
 program
-    .command('diag')
-    .description('Generate diagnostic dump')
+    .command('diag [target]')
+    .description('Generate a diagnostic dump, or a privacy-safe agent diagnostic')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-a, --analyze', 'Run AI analysis on the dump')
     .option('-t, --tail <lines>', 'Number of journal entries', '200')
-    .action(async (opts) => {
+    .option('--json', 'Print target diagnostics as machine-readable JSON')
+    .action(async (target, opts) => {
+    if (target) {
+        if (target !== 'kiro') {
+            log(`Unknown diagnostic target: ${target}. Supported target: kiro`);
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.analyze) {
+            log('`--analyze` is only available for the general daemon diagnostic dump.');
+            process.exitCode = 1;
+            return;
+        }
+        const { collectKiroDiagnosticReport, formatKiroDiagnosticReport } = await import('./kiro-diagnostics.js');
+        const report = await collectKiroDiagnosticReport();
+        process.stdout.write(`${opts.json ? JSON.stringify(report, null, 2) : formatKiroDiagnosticReport(report)}\n`);
+        return;
+    }
     const { readDaemonInfo, findDaemonPort } = await import('./session-registry.js');
     const info = readDaemonInfo();
     const port = info?.httpPort ?? info?.port ?? findDaemonPort() ?? parseInt(opts.port, 10);
@@ -2008,12 +2244,24 @@ timebox
 const pixoo = program.command('pixoo').description('Manage Pixoo64 LED matrix devices');
 pixoo
     .command('scan')
-    .description('Discover Pixoo devices on LAN')
-    .action(async () => {
-    const { discoverDevices, getDeviceConfig } = await import('./pixoo/pixoo-client.js');
+    .description('Discover Pixoo devices on LAN (Divoom cloud lookup, then a local /24 sweep)')
+    .option('--no-cloud', 'Skip the Divoom cloud lookup (app.divoom-gz.com) and sweep the local subnet only')
+    .action(async (opts) => {
+    const { getDeviceConfig } = await import('./pixoo/pixoo-client.js');
+    const { discoverPixoo } = await import('./pixoo/pixoo-discover.js');
     const { loadPixooDevices, savePixooDevices } = await import('./pixoo/pixoo-settings.js');
-    log('Scanning for Pixoo devices...');
-    const found = await discoverDevices();
+    // Say what this actually does before it does it. Auto-discovery is off by
+    // default precisely because these two steps are not free on a shared
+    // network; running them from an explicit command is fine, running them
+    // unannounced is not.
+    if (opts.cloud === false) {
+        log('Scanning the local subnet for Pixoo devices (cloud lookup skipped)...');
+    }
+    else {
+        log('Scanning for Pixoo devices — querying the Divoom cloud (app.divoom-gz.com), then sweeping the local /24 if needed.');
+        log('Use --no-cloud to keep the scan on your own network.');
+    }
+    const found = await discoverPixoo({ cloud: opts.cloud !== false });
     if (found.length === 0) {
         log('No devices found.');
         return;
@@ -2082,7 +2330,12 @@ pixoo
     const { loadPixooDevices } = await import('./pixoo/pixoo-settings.js');
     const devices = loadPixooDevices();
     if (devices.length === 0) {
-        log('No Pixoo devices configured. Run `agentdeck pixoo scan`.');
+        // Says why nothing appeared on its own. The daemon no longer sweeps the
+        // LAN unprompted, so "I plugged it in and nothing happened" needs an
+        // answer here — this is where a user looks when the panel is missing.
+        log('No Pixoo devices configured. Run `agentdeck pixoo scan` (add --no-cloud to keep the lookup on your own network).');
+        log('Auto-discovery is off by default: the daemon does not sweep the LAN or call the Divoom cloud on its own.');
+        log('Set "pixooAutoDiscover": true in ~/.agentdeck/settings.json to opt back in.');
         return;
     }
     log(`${devices.length} device(s):`);
@@ -2473,6 +2726,49 @@ apme
         log(`  ${c.modelId.slice(0, 26).padEnd(26)} ${c.agentType.padEnd(14)} ${String(c.runs).padEnd(6)} ${score.padEnd(8)} ${tests.padEnd(8)} ${cost.padEnd(10)} ${cpq}`);
     }
 });
+apme
+    .command('stop-health')
+    .description('Stop-hook delivery rate — how turns actually got closed')
+    .option('--since <window>', 'Lookback window, e.g. 6h / 3d / 2w (default 7d)', '7d')
+    .option('--agent <type>', 'Restrict to one agent type (claude-code, codex-cli, …)')
+    .action(async (opts) => {
+    const { initApme } = await import('./apme/index.js');
+    const apme = await initApme();
+    if (!apme) {
+        log('APME not available');
+        process.exit(1);
+    }
+    const windowMs = parseLookbackWindow(opts.since);
+    if (windowMs == null) {
+        log(`Unrecognized --since value: ${opts.since}`);
+        process.exit(1);
+    }
+    const sinceMs = Date.now() - windowMs;
+    const rows = apme.store.stopDelivery({ sinceMs, agentType: opts.agent });
+    if (rows.length === 0) {
+        log(`No turns started in the last ${opts.since}.`);
+        return;
+    }
+    log(`\n  Turns started in the last ${opts.since} — how each one's end was learned`);
+    log(`  ${'Agent'.padEnd(14)} ${'Turns'.padEnd(7)} ${'Stop'.padEnd(7)} ${'Synth'.padEnd(7)} ${'NoStop'.padEnd(7)} ${'Esc'.padEnd(6)} ${'Abort'.padEnd(6)} ${'Folded'.padEnd(7)} ${'SessEnd'.padEnd(8)} ${'Open'.padEnd(6)} ${'?'.padEnd(6)} Stop loss`);
+    log(`  ${'─'.repeat(14)} ${'─'.repeat(7)} ${'─'.repeat(7)} ${'─'.repeat(7)} ${'─'.repeat(7)} ${'─'.repeat(6)} ${'─'.repeat(6)} ${'─'.repeat(7)} ${'─'.repeat(8)} ${'─'.repeat(6)} ${'─'.repeat(6)} ${'─'.repeat(9)}`);
+    for (const r of rows) {
+        // Which buckets the ratio may read is defined once, in shared — see
+        // `stopDeliveryLoss`. Restating it here is how the instrument would come
+        // to measure something other than what its legend claims.
+        const { adjudicated, ratio } = stopDeliveryLoss(r);
+        const rate = ratio != null ? `${(ratio * 100).toFixed(0)}% of ${adjudicated}` : '—';
+        log(`  ${r.agentType.slice(0, 14).padEnd(14)} ${String(r.total).padEnd(7)} ${String(r.stop).padEnd(7)} ${String(r.syntheticStop).padEnd(7)} ${String(r.nextPrompt).padEnd(7)} ${String(r.interrupted).padEnd(6)} ${String(r.aborted).padEnd(6)} ${String(r.superseded).padEnd(7)} ${String(r.sessionEnd).padEnd(8)} ${String(r.open).padEnd(6)} ${String(r.preInstrument).padEnd(6)} ${rate}`);
+    }
+    log('');
+    log('  Synth  = Stop hook dropped, watchdog recovered it from the transcript');
+    log('  NoStop = Stop hook dropped and nothing recovered it (closed by the next prompt)');
+    log('  Esc    = user cancelled the turn — Claude Code owes no Stop, so not a loss');
+    log('  Abort  = usage limit / auth / API error ended the turn — no Stop is fired for those');
+    log('  Folded = a second prompt arrived before this one ran; one turn served both');
+    log('  ?      = closed before end_source existed — signal unknown, never guessed');
+    log('');
+});
 apme
     .command('judge')
     .description('Run evaluation on unevaluated runs')