@agentdeck/bridge 1.0.24 → 1.2.0

package/dist/cli.js

@@ -3,7 +3,7 @@ import { Command, InvalidArgumentError } from 'commander';
 import { writeFileSync, unlinkSync, existsSync, realpathSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { dirname, join } from 'path';
-import { execFileSync, execSync, spawn } from 'child_process';
+import { execFileSync, execSync, spawn, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { request } from 'http';
@@ -28,6 +28,25 @@ function warnIfDaemonHostIgnored(opts) {
         console.error('[agentdeck] --daemon-host / AGENTDECK_DAEMON_HOST is set but ignored: remote attach requires --remote-daemon (or AGENTDECK_REMOTE_DAEMON=1). Session stays local-only.');
     }
 }
+/**
+ * User-visible compatibility notice for the legacy per-session bridge. Keep
+ * this pure so CLI tests can pin the public migration contract without starting
+ * a PTY or importing its native dependencies.
+ */
+export function managedPtyCompatibilityNotice(command) {
+    const directLaunch = command === 'monitor'
+        ? 'run `claude`, `codex`, or `opencode` normally'
+        : `run \`${command}\` directly`;
+    return [
+        `[agentdeck] LEGACY COMPATIBILITY MODE: \`agentdeck ${command}\` uses the managed per-session bridge; daemon-first launch is the recommended default.`,
+        `[agentdeck] For ordinary local sessions, run \`agentdeck daemon install\`, then ${directLaunch}.`,
+        '[agentdeck] --remote-daemon, --weight, AGENTDECK_<AGENT>_ARGS, and terminal-only controls do not yet have daemon-first equivalents. No removal date is set. Design: https://github.com/puritysb/AgentDeck/discussions/278 Tracking: https://github.com/puritysb/AgentDeck/issues/273',
+    ];
+}
+function warnManagedPtyCompatibility(command) {
+    for (const line of managedPtyCompatibilityNotice(command))
+        console.error(line);
+}
 function log(msg) {
     process.stderr.write(msg + '\n');
 }
@@ -323,6 +342,38 @@ for (const b of ESP32_OTA_BOARDS) {
 export function resolveEsp32OtaDaemonTarget(target) {
     return ESP32_OTA_BY_TARGET[target]?.board ?? target;
 }
+export function inlineOtaPayload(target, firmwareB64, opts = {}) {
+    return {
+        target,
+        firmwareB64,
+        ...(opts.stage ? { stage: true } : {}),
+        ...(opts.identity ?? {}),
+    };
+}
+/** Resolve one exact OTA namespace from an integration manifest. Ambiguity is
+ * an error: a release command must never guess which product or channel owns
+ * an image. */
+export function resolveOtaIdentityFromManifest(manifestPath, board, productId, updateChannel) {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const matches = [];
+    for (const product of manifest.products ?? []) {
+        if (typeof product.productId !== 'string' || (productId && product.productId !== productId))
+            continue;
+        for (const ota of product.otaIdentities ?? []) {
+            if (ota.board !== board || typeof ota.updateChannel !== 'string')
+                continue;
+            if (updateChannel && ota.updateChannel !== updateChannel)
+                continue;
+            matches.push({ productId: product.productId, board, updateChannel: ota.updateChannel });
+        }
+    }
+    if (matches.length !== 1) {
+        throw new Error(matches.length === 0
+            ? `Manifest has no OTA identity for board=${board}${productId ? ` productId=${productId}` : ''}${updateChannel ? ` updateChannel=${updateChannel}` : ''}`
+            : `Manifest OTA identity is ambiguous for board=${board}; add --product-id and/or --update-channel`);
+    }
+    return matches[0];
+}
 function resolveEsp32FirmwarePath(target, envOpt, firmwareOpt) {
     if (firmwareOpt)
         return realpathSync(firmwareOpt);
@@ -457,10 +508,78 @@ program
     .name('agentdeck')
     .description('AgentDeck — Physical Controller for AI Coding Agents')
     .version(packageJson.version);
+// ===== Weather context =====
+const weatherCommand = program
+    .command('weather')
+    .description('Configure weather for Dashboard and offline Surface readers');
+weatherCommand
+    .command('set')
+    .description('Set a coarse forecast location (no account, API key, or IP lookup)')
+    .requiredOption('--lat <latitude>', 'Latitude, -90 to 90')
+    .requiredOption('--lon <longitude>', 'Longitude, -180 to 180')
+    .option('--place <label>', 'Short display label, for example Seoul')
+    .option('--timezone <iana>', 'IANA time zone; defaults to this host, for example Asia/Seoul')
+    .action(async (opts) => {
+    const { loadDaemonSettings, updateDaemonSetting, ownSettingsPath } = await import('./daemon-settings.js');
+    const { buildWeatherSetting, WeatherConfigError } = await import('./weather-config.js');
+    const settings = loadDaemonSettings();
+    const existing = settings.weather && typeof settings.weather === 'object' ? settings.weather : {};
+    try {
+        const weather = buildWeatherSetting({
+            latitude: opts.lat,
+            longitude: opts.lon,
+            place: opts.place,
+            timeZone: opts.timezone,
+        }, existing);
+        updateDaemonSetting('weather', weather);
+        log(`Weather location saved in ${ownSettingsPath()}.`);
+        log(`Coarse location: ${weather.lat.toFixed(2)}, ${weather.lon.toFixed(2)}${weather.place ? ` (${weather.place})` : ''}`);
+        log(`Time zone: ${weather.timeZone}; portable provider: MET Norway unless an explicit custom provider is retained.`);
+        log('The running daemon reads this setting on the next feed pull; no restart is required.');
+    }
+    catch (error) {
+        if (error instanceof WeatherConfigError) {
+            log(`Weather location was not changed: ${error.message}.`);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});
+weatherCommand
+    .command('show')
+    .description('Show the configured forecast location and portable provider')
+    .action(async () => {
+    const { loadDaemonSettings, ownSettingsPath } = await import('./daemon-settings.js');
+    const { describeWeatherSetting } = await import('./weather-config.js');
+    for (const line of describeWeatherSetting(loadDaemonSettings().weather))
+        log(line);
+    log(`Settings: ${ownSettingsPath()}`);
+});
+weatherCommand
+    .command('clear')
+    .description('Remove the saved forecast location and persisted forecast cache')
+    .action(async () => {
+    const { updateDaemonSetting, ownSettingsPath } = await import('./daemon-settings.js');
+    updateDaemonSetting('weather', undefined);
+    const cachePath = join(getDataDir(), 'weather-cache-v1.json');
+    try {
+        if (existsSync(cachePath))
+            unlinkSync(cachePath);
+    }
+    catch (error) {
+        log(`Weather location was cleared, but the old cache could not be removed: ${String(error)}`);
+        process.exitCode = 1;
+        return;
+    }
+    log(`Weather location cleared from ${ownSettingsPath()}.`);
+    log(`Persisted forecast cache removed from ${cachePath}.`);
+    log('The running daemon stops adding weather on the next feed pull; no restart is required.');
+});
 // ===== Agent session commands =====
 program
     .command('claude')
-    .description('Start Claude Code session (PTY + bridge)')
+    .description('[legacy compatibility] Start Claude Code in the managed PTY session bridge')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-c, --command <cmd>', 'Command to spawn', 'claude')
     .option('-d, --debug', 'Enable debug logging')
@@ -476,6 +595,7 @@ program
     .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) => {
+    warnManagedPtyCompatibility('claude');
     warnIfDaemonHostIgnored(opts);
     const { startSession } = await import('./index.js');
     await startSession({
@@ -504,7 +624,7 @@ program
 });
 program
     .command('codex')
-    .description('Start Codex CLI session (PTY + bridge)')
+    .description('[legacy compatibility] Start Codex in the managed PTY session bridge')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-c, --command <cmd>', 'Command to spawn', 'codex')
     .option('-d, --debug', 'Enable debug logging')
@@ -518,6 +638,7 @@ program
     .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) => {
+    warnManagedPtyCompatibility('codex');
     warnIfDaemonHostIgnored(opts);
     // Install Codex lifecycle hooks before starting the session so the
     // first prompt's UserPromptSubmit / Stop events reach the daemon.
@@ -565,7 +686,7 @@ program
 });
 program
     .command('opencode')
-    .description('Start OpenCode session (PTY + SSE bridge)')
+    .description('[legacy compatibility] Start OpenCode in the managed PTY/SSE session bridge')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-c, --command <cmd>', 'Command to spawn', 'opencode')
     .option('-d, --debug', 'Enable debug logging')
@@ -579,6 +700,7 @@ program
     .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) => {
+    warnManagedPtyCompatibility('opencode');
     warnIfDaemonHostIgnored(opts);
     // Install the OpenCode observer plugin so standalone `opencode` runs
     // (outside this managed session) also reach the daemon timeline. The
@@ -623,7 +745,7 @@ program
 });
 program
     .command('monitor')
-    .description('Start hook-only bridge (no PTY — run claude separately)')
+    .description('[legacy compatibility] Start the managed hook-only per-session bridge')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-d, --debug', 'Enable debug logging')
     .option('--local', 'Disable all device modules')
@@ -634,6 +756,7 @@ program
     .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)
     .action(async (opts) => {
+    warnManagedPtyCompatibility('monitor');
     warnIfDaemonHostIgnored(opts);
     const { startSession } = await import('./index.js');
     const port = parseInt(opts.port, 10);
@@ -689,6 +812,88 @@ async function openDaemonLogs(logDir) {
     };
     return [open('daemon-stdout.log'), open('daemon-stderr.log')];
 }
+/** Read `--build` / `--no-build` as three states, not two. */
+function buildModeFrom(cmd, opts) {
+    const source = cmd.getOptionValueSource?.('build');
+    if (source !== 'cli')
+        return 'auto';
+    return opts.build === false ? 'never' : 'force';
+}
+/**
+ * Make this process the newest build on disk before it starts (or restarts) a
+ * daemon.
+ *
+ * On a dev checkout `agentdeck` is a shim onto `bridge/dist/cli.js`, so
+ * "latest version" means "whatever tsc last wrote" — and an edit that has not
+ * been built is invisible: the daemon comes up, reports success, and serves the
+ * previous build with nothing anywhere naming the gap.
+ *
+ * When a rebuild happens this function does NOT return: it re-executes the
+ * command from the top with `--no-build`. Continuing in place would leave a
+ * process that had already loaded the OLD `cli.js` dynamically importing the
+ * NEW `daemon-server.js` a moment later — a mixture of two builds that nobody
+ * chose and no version string describes.
+ *
+ * An installed (non-checkout) copy has no sources to compare and returns
+ * immediately.
+ */
+async function ensureLatestBuild(mode) {
+    const { findSourceCheckout, findStaleSources, buildPackages, computeDistBuildIdentity, } = await import('./daemon-build-identity.js');
+    const root = findSourceCheckout();
+    if (!root)
+        return;
+    const stale = findStaleSources(root);
+    if (stale.length === 0)
+        return;
+    const names = stale.map((s) => s.pkg).join(', ');
+    const newest = stale.reduce((a, b) => (a.sourceMtimeMs > b.sourceMtimeMs ? a : b));
+    const rel = newest.newestSource.startsWith(root) ? newest.newestSource.slice(root.length + 1) : newest.newestSource;
+    log(`Source is newer than the build in ${names} (newest: ${rel}).`);
+    if (mode === 'never') {
+        log(`Not rebuilding (--no-build) — running the build already on disk.`);
+        return;
+    }
+    if (mode === 'auto' && !process.stdout.isTTY) {
+        // Non-interactive: almost always the autostart unit, whose stdio is a log
+        // file. Say what was found; do not spend a compiler run on it. Building
+        // here would block the daemon behind `tsc` at login and, on a tree that
+        // does not compile, turn a failed build into a KeepAlive respawn loop.
+        log(`Not rebuilding (no terminal attached — this is the autostart path). `
+            + `Run 'pnpm build' and 'agentdeck daemon restart' to pick it up.`);
+        return;
+    }
+    log(`Rebuilding ${names} first (pass --no-build to skip)…`);
+    const before = computeDistBuildIdentity().id;
+    const result = buildPackages(root, stale.map((s) => s.pkg));
+    if (!result.ok) {
+        log(result.reason
+            ? `Could not run the build: ${result.reason}.`
+            : `Build FAILED — the compiler's errors are above.`);
+        // Refusing is the point. Starting here would run the previous build, which
+        // is exactly the silent substitution this check exists to prevent — and it
+        // would do it right after telling the user a build was needed.
+        log(`Not starting. Fix the build, or pass --no-build to start the previous build deliberately.`);
+        process.exit(1);
+    }
+    // Did the build actually produce different code? Very often it did not: an
+    // mtime moves for a rebase, a worktree switch or a plain `touch`, and a
+    // composite project then compiles nothing at all. Re-executing on that would
+    // charge a second process — and a second round of this same message — for a
+    // build that changed no byte, so the delta decides, not the fact that tsc ran.
+    const after = computeDistBuildIdentity().id;
+    if (after === before) {
+        log(`Build was already current (${after ?? 'unknown'}) — the timestamps had moved, the code had not.`);
+        return;
+    }
+    // From here the process itself is stale: it loaded the OLD `cli.js` and would
+    // dynamically import the NEW `daemon-server.js` a moment later. Start over.
+    const scriptPath = fileURLToPath(import.meta.url);
+    log(`Rebuilt (${before ?? 'unknown'} → ${after ?? 'unknown'}). Re-running with the new build…`);
+    const rerun = spawnSync(process.execPath, [scriptPath, ...process.argv.slice(2), '--no-build'], {
+        stdio: 'inherit',
+    });
+    process.exit(rerun.status ?? 1);
+}
 daemon
     .command('start')
     .description('Start monitoring daemon (WS + mDNS + Gateway proxy)')
@@ -705,9 +910,19 @@ daemon
     .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) => {
+    .option('--build', 'Rebuild stale workspace packages first even with no terminal attached (dev checkout only)')
+    .option('--no-build', 'Never rebuild — start whatever build is already on disk')
+    .option('--no-upgrade', 'Leave a running daemon of yours alone even when it is serving an older build')
+    .action(async (opts, cmd) => {
+    // Before anything else: be the newest build on disk. Everything below —
+    // the incumbent comparison especially — is a claim about which code is
+    // serving the port, and it is worthless if this process is itself stale.
+    // Re-executes and never returns when it rebuilds.
+    await ensureLatestBuild(buildModeFrom(cmd, opts));
     const { findExistingDaemon, probeDaemonHealth, readDaemonInfo, removeDaemonInfo, removeDaemonSession, requestDaemonStandDown, requestDaemonShutdown, waitForDaemonExit, waitForPortBindable } = await import('./session-registry.js');
     const { adoptPeerToken } = await import('./auth.js');
+    const { distBuildId } = await import('./daemon-build-identity.js');
+    const localBuild = distBuildId();
     // 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
@@ -753,7 +968,13 @@ daemon
     const { negotiateIncumbentDaemon } = await import('./daemon-takeover.js');
     const { capturePeerActivity } = await import('./apme/activity-history.js');
     const incumbent = await probeDaemonHealth(targetPort);
-    const outcome = await negotiateIncumbentDaemon({ port: targetPort, incumbent, portWasExplicit: !!opts.port }, {
+    const outcome = await negotiateIncumbentDaemon({
+        port: targetPort,
+        incumbent,
+        portWasExplicit: !!opts.port,
+        localBuild,
+        replaceStaleBuild: opts.upgrade !== false,
+    }, {
         adoptToken: adoptPeerToken,
         standDown: requestDaemonStandDown,
         shutdown: requestDaemonShutdown,
@@ -765,26 +986,42 @@ daemon
         process.exit(0);
     if (outcome === 'refuse')
         process.exit(1);
-    const daemonInfo = readDaemonInfo();
-    if (daemonInfo) {
-        const probePort = daemonInfo.httpPort ?? daemonInfo.port;
+    // The same decision again, for a daemon that is NOT on the port we aimed at
+    // — one that fell back to 9121+ once and has been there since. It answers
+    // `daemon start` the same way (exit 0, "already running"), so without this
+    // it is the one daemon on the machine that could serve an old build
+    // forever. Routed through the same negotiation rather than a second copy of
+    // the rule: the ownership gate, the token adoption and the build comparison
+    // must not differ by which file found the daemon.
+    const settleIncumbentOn = async (probePort, reportedPort, pid, forget, what) => {
         const health = await probeDaemonHealth(probePort);
         if (health?.mode === 'daemon') {
-            log(`Daemon already running on port ${daemonInfo.port} (PID ${daemonInfo.pid}). Use 'agentdeck daemon stop' first.`);
-            process.exit(0);
+            const decision = await negotiateIncumbentDaemon({ port: probePort, incumbent: health, portWasExplicit: false, localBuild, replaceStaleBuild: opts.upgrade !== false }, {
+                adoptToken: adoptPeerToken,
+                standDown: requestDaemonStandDown,
+                shutdown: requestDaemonShutdown,
+                waitForExit: waitForDaemonExit,
+                waitForBindable: waitForPortBindable,
+                captureActivity: capturePeerActivity,
+            });
+            if (decision === 'already-running')
+                process.exit(0);
+            if (decision === 'refuse')
+                process.exit(1);
+            // 'proceed' — it stood down or was replaced; its registry row is dead.
+            forget();
+            return;
         }
-        log(`Ignoring stale daemon entry on port ${daemonInfo.port} (PID ${daemonInfo.pid}; /health did not respond).`);
-        removeDaemonInfo();
+        log(`Ignoring stale ${what} on port ${reportedPort} (PID ${pid}; /health did not respond).`);
+        forget();
+    };
+    const daemonInfo = readDaemonInfo();
+    if (daemonInfo) {
+        await settleIncumbentOn(daemonInfo.httpPort ?? daemonInfo.port, daemonInfo.port, daemonInfo.pid, removeDaemonInfo, 'daemon entry');
     }
     const existing = findExistingDaemon();
     if (existing) {
-        const health = await probeDaemonHealth(existing.port);
-        if (health?.mode === 'daemon') {
-            log(`Daemon already running on port ${existing.port} (PID ${existing.pid}). Use 'agentdeck daemon stop' first.`);
-            process.exit(0);
-        }
-        log(`Ignoring stale daemon session on port ${existing.port} (PID ${existing.pid}; /health did not respond).`);
-        removeDaemonSession(existing);
+        await settleIncumbentOn(existing.port, existing.port, existing.pid, () => removeDaemonSession(existing), 'daemon session');
     }
     // Background fork unless --foreground
     if (!opts.foreground) {
@@ -811,6 +1048,11 @@ daemon
         // a window that only applies to the parent moves nothing.
         if (opts.portWindow)
             args.push('--port-window', String(opts.portWindow));
+        // Freshness was settled by this process, above. The child inherits log
+        // files rather than a terminal, so it would decline to build anyway —
+        // saying so explicitly keeps the child's log free of a warning about a
+        // staleness the parent has already resolved.
+        args.push('--no-build');
         const [out, err] = await openDaemonLogs(logDir);
         const child = spawn(process.execPath, args, {
             detached: true,
@@ -818,7 +1060,7 @@ daemon
             windowsHide: true,
         });
         child.unref();
-        log(`Daemon started (PID ${child.pid})`);
+        log(`Daemon started (PID ${child.pid}, build ${localBuild ?? 'unknown'})`);
         process.exit(0);
     }
     const { startDaemon } = await import('./daemon-server.js');
@@ -845,7 +1087,14 @@ daemon
     .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) => {
+    .option('--build', 'Rebuild stale workspace packages first even with no terminal attached (dev checkout only)')
+    .option('--no-build', 'Never rebuild — restart onto whatever build is already on disk')
+    .action(async (opts, cmd) => {
+    // `daemon restart` is the command a developer runs to put an edit live, so
+    // it answers to the same freshness rule as `start`. Re-executes and never
+    // returns when it rebuilds — before anything has been stopped, so a failed
+    // build costs the machine nothing.
+    await ensureLatestBuild(buildModeFrom(cmd, opts));
     // 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
@@ -853,8 +1102,8 @@ daemon
     // 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 { probeDaemonHealth: probeHealth, readDaemonInfo, findDaemonPort, waitForDaemonExit, waitForPortBindable, } = await import('./session-registry.js');
+    const { resolveDaemonPort, PREFERRED_PORT_RECLAIM_MS } = await import('./daemon-port.js');
     const preferredPort = resolveDaemonPort({ flag: opts.port });
     const info = readDaemonInfo();
     const runningPort = info?.httpPort ?? info?.port ?? findDaemonPort() ?? preferredPort.port;
@@ -872,8 +1121,21 @@ daemon
         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));
+    // Wait for the old daemon to stop ANSWERING — a real condition, not the
+    // 1500ms guess that used to sit here and merely outlasted the common case.
+    //
+    // The parent deliberately does NOT also wait for the port to become
+    // bindable. Its probe opens a listener and closes it again, so it proves
+    // nothing the child does not re-prove seconds later — and the child does it
+    // better, because it KEEPS the port on success. Waiting here serialized two
+    // port-reclaim waits back to back (macOS holds a NECP reservation for ~14s
+    // after a listener is cancelled) and made a contended restart twice as slow
+    // for no extra information. Whether the child got the port is answered
+    // below, by asking the daemon that came up who it is.
+    const exited = await waitForDaemonExit(runningPort, 8000);
+    if (!exited) {
+        log(`Warning: the daemon on port ${runningPort} was still answering when the stop budget ran out.`);
+    }
     const scriptPath = fileURLToPath(import.meta.url);
     const args = [scriptPath, 'daemon', 'start', '--foreground'];
     // Same rule as `daemon start`: forward `-p` only when it was typed, so the
@@ -886,6 +1148,9 @@ daemon
         args.push('--local');
     if (useLoopback)
         args.push('--loopback');
+    // Same as the `start` fork: freshness is this process's job, and the child
+    // has log files rather than a terminal.
+    args.push('--no-build');
     if ((inheritedLocal && !opts.local) || (inheritedLoopback && !opts.loopback)) {
         log(`Carrying over the running daemon's posture (${[
             inheritedLoopback ? 'loopback-only' : null,
@@ -898,10 +1163,100 @@ daemon
         stdio: ['ignore', rOut, rErr],
         windowsHide: true,
     });
+    // Liveness is what the wait below actually keys on. `detached` + `unref`
+    // still delivers 'exit' to this process for as long as it is running.
+    let childAlive = true;
+    child.once('exit', () => { childAlive = false; });
     child.unref();
-    log(`Daemon restarted (PID ${child.pid})`);
+    // `spawn` resolving a pid means the OS forked a process — it is not
+    // evidence that a daemon is running. A child that dies on EADDRINUSE (the
+    // old port still held) exits within a second, and this command used to
+    // announce `Daemon restarted (PID …)` regardless, so a failed restart was
+    // indistinguishable from a good one and the real reason sat unread in the
+    // daemon log. Verify by asking the daemon who it is.
+    const spawnedPid = child.pid;
+    const started = spawnedPid !== undefined
+        ? await waitForDaemonPid(spawnedPid, preferredPort.port, probeHealth, readDaemonInfo, findDaemonPort, PREFERRED_PORT_RECLAIM_MS, () => childAlive, undefined, (p) => log(`Still starting — child PID ${p} is alive; waiting for it to bind.`))
+        : null;
+    if (!started) {
+        log(`Daemon restart FAILED — no daemon with PID ${spawnedPid ?? '?'} is answering.`);
+        // Both streams, not just stderr: the likeliest failure is the child
+        // hitting `daemon start`'s incumbent guard, which reports through `log()`
+        // — i.e. stdout. Naming only stderr pointed at the empty file.
+        log(`The reason is in ${join(homedir(), '.agentdeck', 'daemon-stdout.log')}`
+            + ` or ${join(homedir(), '.agentdeck', 'daemon-stderr.log')}.`);
+        process.exit(1);
+    }
+    if (started.port !== preferredPort.port) {
+        log(`Daemon restarted (PID ${started.pid}) on port ${started.port} — it could not take ${preferredPort.port}.`);
+    }
+    else {
+        log(`Daemon restarted (PID ${started.pid}) on port ${started.port}`);
+    }
     process.exit(0);
 });
+/**
+ * Poll until a daemon reporting `pid` answers `/health`, or give up.
+ *
+ * The pid comparison is the load-bearing part: probing the port alone can be
+ * satisfied by the daemon we were trying to REPLACE (a stop that silently
+ * failed), which would report a restart that never happened. The fallback-port
+ * sweep exists because the daemon is allowed to land elsewhere when it cannot
+ * win its preferred port — that is a different outcome from "did not start",
+ * and the caller says so rather than calling it a failure.
+ */
+export async function waitForDaemonPid(pid, preferredPort, probeHealth, readDaemonInfo, findDaemonPort, timeoutMs = 20_000, 
+/**
+ * Is the spawned child still running?
+ *
+ * A derived timeout is still a guess, and this one was wrong twice: the
+ * budget has to cover not just the child's port-reclaim wait but its
+ * incumbent negotiation first — a Swift daemon standing down costs up to
+ * `EXIT_WAIT_MS + BINDABLE_WAIT_MS` before `startDaemon` is even reached, so
+ * the whole worst case runs past a minute. Giving up early prints
+ * "restart FAILED" while the daemon is coming up, and the user's natural
+ * retry then kills it.
+ *
+ * "The child is still running" is a real condition rather than a derived one,
+ * so `timeoutMs` becomes a floor: while the child is alive we keep waiting,
+ * and only a child that EXITED without a matching pid is a failure. The
+ * ceiling still bounds a child that hangs forever.
+ */
+isChildAlive, ceilingMs = 180_000, onStillWaiting) {
+    let announcedWait = false;
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
+    for (;;) {
+        const candidates = new Set([preferredPort]);
+        const info = readDaemonInfo();
+        if (info?.httpPort)
+            candidates.add(info.httpPort);
+        if (info?.port)
+            candidates.add(info.port);
+        const found = findDaemonPort();
+        if (found)
+            candidates.add(found);
+        for (const port of candidates) {
+            const health = await probeHealth(port);
+            if (health?.pid === pid)
+                return { pid, port };
+        }
+        const now = Date.now();
+        if (now >= startedAt + ceilingMs)
+            return null;
+        if (now >= deadline && !(isChildAlive?.() ?? false))
+            return null;
+        // Past the floor with the child still alive, this can legitimately run for
+        // another couple of minutes (a Swift incumbent standing down, then a port
+        // reclaim). Say so once, or a correct wait is indistinguishable from a hung
+        // terminal.
+        if (now >= deadline && !announcedWait) {
+            announcedWait = true;
+            onStillWaiting?.(pid);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 300));
+    }
+}
 daemon
     .command('status')
     .description('Show daemon status')
@@ -934,6 +1289,23 @@ daemon
                 + `but is serving ${registryPort} — it fell back at startup. `
                 + `Run 'agentdeck daemon restart' to aim at ${preferred.port} again.`);
         }
+        // Is the daemon that answered running the code on this disk? `build` in
+        // the payload above is what it STARTED with; `dist/cli.js` is overwritten
+        // in place, so nothing else here would show a divergence.
+        const { distBuildId, findSourceCheckout, findStaleSources } = await import('./daemon-build-identity.js');
+        const onDisk = distBuildId();
+        const running = typeof data.build === 'string' ? data.build : null;
+        if (onDisk && running && onDisk !== running) {
+            log(`Note: it is serving build ${running}; the build on disk is ${onDisk}. `
+                + `Run 'agentdeck daemon restart' to serve the current build.`);
+        }
+        const checkout = findSourceCheckout();
+        const stale = checkout ? findStaleSources(checkout) : [];
+        if (stale.length > 0) {
+            log(`Note: ${stale.map((x) => x.pkg).join(', ')} ${stale.length === 1 ? 'has' : 'have'} `
+                + `source files newer than the build. Run 'pnpm build' if you expect that edit to be live `
+                + `(a bare timestamp move — rebase, worktree switch — compiles to nothing).`);
+        }
     }
     catch {
         if (info)
@@ -1363,6 +1735,7 @@ program
                         const ver = dev.version ? ` v${dev.version}` : '';
                         const hash = dev.buildHash ? ` (${dev.buildHash})` : '';
                         const board = dev.board ?? 'esp32';
+                        const product = dev.productId ? ` ${dev.productId}/${dev.updateChannel ?? '?'}` : '';
                         const ota = dev.otaSupported === true
                             ? ` OTA ${formatBytes(dev.otaSlotSize)}`
                             : dev.otaReason ? ` OTA no:${dev.otaReason}` : '';
@@ -1370,7 +1743,7 @@ program
                         // Single-path: a board also live on USB serial is driven over
                         // serial; its WiFi link is a hot standby (no duplicate traffic).
                         const transport = dev.serialActive ? ' [serial-active · wifi standby]' : '';
-                        lines.push(`                 ${board}${ver}${hash}${ota}${stale}${transport} @ ${dev.ip ?? 'wifi'}`);
+                        lines.push(`                 ${board}${ver}${hash}${product}${ota}${stale}${transport} @ ${dev.ip ?? 'wifi'}`);
                     }
                     total += devices.length;
                 }
@@ -1384,6 +1757,9 @@ program
                     lines.push(`  Card feed    ${clients.length} pull client${clients.length !== 1 ? 's' : ''}`);
                     for (const c of clients) {
                         const who = c.board ? `${c.board} @ ${c.client}` : c.client;
+                        const product = c.productId
+                            ? ` ${c.productId}${c.clientVersion ? ` v${c.clientVersion}` : ''}`
+                            : '';
                         const ago = `${Math.round((Date.now() - c.lastPullAt) / 1000)}s ago`;
                         const cadence = c.lastIntervalSec !== undefined
                             ? `, last gap ${c.lastIntervalSec}s vs ${c.lastNextPullSec}s asked`
@@ -1391,7 +1767,7 @@ program
                         const honoured = c.pulls > 1
                             ? ` [${c.cadenceHonouredCount}/${c.pulls - 1} on cadence]`
                             : '';
-                        lines.push(`                 ${who} — ${c.pulls} pull${c.pulls !== 1 ? 's' : ''}, last ${ago}${cadence}${honoured}`);
+                        lines.push(`                 ${who}${product} — ${c.pulls} pull${c.pulls !== 1 ? 's' : ''}, last ${ago}${cadence}${honoured}`);
                     }
                 }
             }
@@ -1504,6 +1880,9 @@ program
     .option('-f, --firmware <path>', 'Firmware .bin path')
     .option('--build', 'Build the PlatformIO environment before upload')
     .option('--stage', 'Stage for pull OTA: the board installs it on its next feed pull (no live WS needed)')
+    .option('--manifest <path>', 'Integration manifest used to resolve the exact pull-OTA identity')
+    .option('--product-id <id>', 'Surface productId for pull-OTA isolation')
+    .option('--update-channel <channel>', 'Surface update channel for pull-OTA isolation')
     .action(async (target, opts) => {
     const { readDaemonInfo, findDaemonPort } = await import('./session-registry.js');
     const info = readDaemonInfo();
@@ -1525,10 +1904,33 @@ program
     const daemonTarget = resolveEsp32OtaDaemonTarget(target);
     const firmwarePath = resolveEsp32FirmwarePath(target, opts.env, opts.firmware);
     if (opts.stage) {
+        let otaIdentity;
+        if (opts.manifest) {
+            otaIdentity = resolveOtaIdentityFromManifest(realpathSync(opts.manifest), daemonTarget, opts.productId, opts.updateChannel);
+        }
+        else if (opts.productId || opts.updateChannel) {
+            if (!opts.productId || !opts.updateChannel) {
+                throw new Error('--product-id and --update-channel are required together (or use --manifest)');
+            }
+            otaIdentity = { productId: opts.productId, board: daemonTarget, updateChannel: opts.updateChannel };
+        }
+        if (!otaIdentity && (daemonTarget === 'xteink_x3' || daemonTarget === 'xteink_x4')) {
+            throw new Error('XTeink pull OTA requires --manifest, or both --product-id and --update-channel');
+        }
         // Pull-OTA staging: for wake-sync-sleep boards (XTeink X3/X4) that never
         // hold a live WS. The daemon adverts the build on the board's feed pulls;
         // the board downloads + flashes itself on its next wake.
-        const { statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwarePath, stage: true }, 30_000);
+        let { statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwarePath, stage: true, ...(otaIdentity ?? {}) }, 30_000);
+        if (body.ok === false && String(body.error ?? '').startsWith('firmware_unreadable')) {
+            // The App Store daemon cannot reopen an arbitrary CLI path. Preserve
+            // the stage bit and exact product namespace when retrying inline — the
+            // live-OTA retry below is a different operation and must not consume a
+            // pull-stage request by accident.
+            log('Daemon cannot read the firmware path (sandbox) — resending stage inline...');
+            const { readFileSync } = await import('fs');
+            const firmwareB64 = readFileSync(firmwarePath).toString('base64');
+            ({ statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, inlineOtaPayload(daemonTarget, firmwareB64, { stage: true, identity: otaIdentity }), 30_000));
+        }
         if (statusCode < 200 || statusCode >= 300 || body.ok === false) {
             throw new Error(String(body.error ?? `HTTP ${statusCode}`));
         }
@@ -1558,7 +1960,7 @@ program
         log('Daemon cannot read the firmware path (sandbox) — resending inline...');
         const { readFileSync } = await import('fs');
         const firmwareB64 = readFileSync(firmwarePath).toString('base64');
-        ({ statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwareB64 }, 15 * 60_000));
+        ({ statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, inlineOtaPayload(daemonTarget, firmwareB64), 15 * 60_000));
     }
     if (statusCode < 200 || statusCode >= 300 || body.ok === false) {
         throw new Error(String(body.error ?? `HTTP ${statusCode}`));
@@ -1983,8 +2385,8 @@ program
     .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`);
+        if (target !== 'kiro' && target !== 'agents') {
+            log(`Unknown diagnostic target: ${target}. Supported targets: agents, kiro`);
             process.exitCode = 1;
             return;
         }
@@ -1993,6 +2395,12 @@ program
             process.exitCode = 1;
             return;
         }
+        if (target === 'agents') {
+            const { collectAgentCliDiagnosticReport, formatAgentCliDiagnosticReport } = await import('./agent-cli-diagnostics.js');
+            const report = collectAgentCliDiagnosticReport();
+            process.stdout.write(`${opts.json ? JSON.stringify(report, null, 2) : formatAgentCliDiagnosticReport(report)}\n`);
+            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`);