@agentdeck/bridge 0.2.1 → 0.2.3

package/dist/esp32-serial.js

@@ -10,33 +10,113 @@
  *
  * ESP32 side reads lines starting with '{' and passes to Protocol::parseMessage().
  */
-import { exec } from 'child_process';
-import { createWriteStream, createReadStream } from 'fs';
+import { exec, execFile } from 'child_process';
+import { openSync, close, read, write, readFileSync, writeFileSync, mkdirSync, constants as fsConstants, } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
 import { SERIAL_FORWARDED_EVENTS } from '@agentdeck/shared/protocol';
 import { formatResetTime } from '@agentdeck/shared';
 import { debug } from './logger.js';
 /** @internal Exported for testing only */
 export const ESP32_PORT_PATTERNS = [
-    /\/dev\/cu\.usbserial-\d+/, // CP210x / CH340 (cu.usbserial-XXXX)
-    /\/dev\/cu\.wchusbserial\d+/, // CH340 (cu.wchusbserialXXXX — 86 Box)
-    /\/dev\/cu\.usbmodem\d+/, // Native USB JTAG (IPS 3.5", Round AMOLED)
-    /\/dev\/ttyUSB\d+/, // Linux CH340
-    /\/dev\/ttyACM\d+/, // Linux native USB
+    /\/dev\/cu\.usbserial-\w+/, // CP210x / CH340 (cu.usbserial-XXXX)
+    /\/dev\/cu\.wchusbserial\w+/, // CH340 (cu.wchusbserialXXXX — 86 Box)
+    /\/dev\/cu\.usbmodem\w+/, // Native USB JTAG (IPS 3.5", Round AMOLED)
+    /\/dev\/ttyUSB\w+/, // Linux CH340
+    /\/dev\/ttyACM\w+/, // Linux native USB
 ];
 /** @internal Exported for testing only */
 export const EXCLUDE_PATTERNS = [
     /Bluetooth/i,
     /WLAN/i,
 ];
+/** No-traffic threshold. ESP32 firmware should answer device_info/heartbeat JSON. */
+const STALE_THRESHOLD_MS = 60000; // 60 seconds
+const INITIAL_READ_TIMEOUT_MS = 20000;
+const DEVICE_INFO_RETRY_MS = 5000;
+const DEVICE_INFO_READ_RETRY_MS = 5000;
+const DEVICE_INFO_MAX_REQUESTS = 10;
+// A serial port that opens fine but never speaks the AgentDeck protocol (e.g. a
+// TRMNL e-ink panel, or any third-party USB-serial device) would otherwise be
+// reopened every poll — and opening a port toggles DTR/RTS, which resets an
+// ESP32. After this many failed identification cycles we denylist the port for a
+// cooldown so we stop holding/resetting foreign hardware.
+const FOREIGN_MAX_PROBE_FAILURES = 3;
+const FOREIGN_DENYLIST_COOLDOWN_MS = 10 * 60_000; // 10 minutes, then re-probe once
+const FOREIGN_CDC_GRACE_MS = 90_000; // a held-open CDC port gets this long to identify
+// An *identified* CDC port (live or cache-restored board) that reads nothing for
+// this long since (re)connect is half-open: the board reset/re-enumerated and its
+// RX pipe is dead, but heartbeat writes keep succeeding so the write-death reaper
+// never fires. Larger than FOREIGN_CDC_GRACE_MS so an unidentified foreign port is
+// always caught by the foreign clause first.
+const CDC_SILENT_READ_TIMEOUT_MS = 120_000;
+const SERIAL_OPEN_PROBE_TIMEOUT_MS = 1500;
+const SERIAL_WRITE_INTERVAL_MS = 120;
+const SERIAL_MAX_QUEUE = 24;
+const SERIAL_KEEPALIVE_JSON = JSON.stringify({ type: 'serial_keepalive' });
+const SERIAL_OPEN_PROBE_SCRIPT = `
+const fs = require('fs');
+const port = process.argv[1];
+let fd = -1;
+try {
+  fd = fs.openSync(port, fs.constants.O_RDWR | (fs.constants.O_NOCTTY || 0) | (fs.constants.O_NONBLOCK || 0));
+  fs.closeSync(fd);
+  process.exit(0);
+} catch (err) {
+  if (fd >= 0) {
+    try { fs.closeSync(fd); } catch {}
+  }
+  console.error(err && err.message ? err.message : String(err));
+  process.exit(1);
+}
+`;
 let connections = [];
 let pollTimer = null;
 let heartbeatTimer = null;
+let pollInProgress = false;
+const openingPorts = new Set();
+const lastKnownDeviceInfoByPort = new Map();
+const lastErrorByPort = new Map();
+// Foreign (non-AgentDeck) serial ports: failure count + denylist-until timestamp.
+const foreignProbeFailures = new Map();
+const foreignDenylistUntil = new Map();
+let deviceInfoCacheLoaded = false;
 let stateProvider = null;
 let usageProvider = null;
+let displayStateProvider = null;
+let sessionsListProvider = null;
 let initialStateProvider = null;
 let messageHandler = null;
 // Events to forward — shared constant from @agentdeck/shared
 const FORWARDED_EVENTS = SERIAL_FORWARDED_EVENTS;
+function deviceInfoCachePath() {
+    return join(process.env.AGENTDECK_DATA_DIR || join(homedir(), '.agentdeck'), 'esp32-device-cache.json');
+}
+function loadDeviceInfoCache() {
+    if (deviceInfoCacheLoaded)
+        return;
+    deviceInfoCacheLoaded = true;
+    try {
+        const parsed = JSON.parse(readFileSync(deviceInfoCachePath(), 'utf-8'));
+        for (const [port, info] of Object.entries(parsed)) {
+            if (info?.board)
+                lastKnownDeviceInfoByPort.set(port, info);
+        }
+    }
+    catch {
+        // Missing cache is normal.
+    }
+}
+function persistDeviceInfoCache() {
+    try {
+        const path = deviceInfoCachePath();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(Object.fromEntries(lastKnownDeviceInfoByPort), null, 2), 'utf-8');
+    }
+    catch (err) {
+        debug('ESP32', `Failed to persist device cache: ${String(err)}`);
+    }
+}
 // ESP32 without WiFi/NTP can't parse ISO dates — shared formatResetTime
 // handles undefined and pre-formatted strings.
 /**
@@ -45,28 +125,208 @@ const FORWARDED_EVENTS = SERIAL_FORWARDED_EVENTS;
  * - Strip fields the ESP32 firmware doesn't parse (reduce size for small RX buffers)
  */
 /** @internal Exported for testing only */
-export function prepareForSerial(event) {
+// Firmware (handleSessionsList) only stores the first N sessions; both sides
+// must agree on the same cap. Keep in sync with esp32/src/net/protocol.cpp
+// (sessions[10] / MOSAIC_MAX / min(...,10)).
+export const SERIAL_SESSIONS_CAP = 10;
+/**
+ * Pick which sessions survive the serial session cap.
+ *
+ * A naive `slice(0, cap)` lets a single agent type (e.g. several idle Claude Code
+ * sessions) fill every slot and starve other agents — a running Codex/OpenClaw
+ * session that lands past the cap never reaches the firmware's creature renderer.
+ *
+ * Instead we round-robin across agent types so each present type claims at least
+ * one slot before any type takes a second. Within a type, live + active
+ * (non-idle) sessions are preferred so a processing session is never dropped in
+ * favour of an idle sibling. Order within a type is otherwise preserved (stable).
+ */
+export function roundRobinByAgentType(sessions, cap) {
+    if (sessions.length <= cap)
+        return sessions;
+    const groups = new Map();
+    const order = [];
+    for (const s of sessions) {
+        const key = typeof s?.agentType === 'string' ? s.agentType : '';
+        let bucket = groups.get(key);
+        if (!bucket) {
+            bucket = [];
+            groups.set(key, bucket);
+            order.push(key);
+        }
+        bucket.push(s);
+    }
+    // Within each type: alive first, then active (non-idle) first. Stable for ties.
+    const rank = (s) => {
+        const alive = s?.alive ? 1 : 0;
+        const state = typeof s?.state === 'string' ? s.state : '';
+        const active = state && state !== 'idle' ? 1 : 0;
+        return alive * 2 + active;
+    };
+    for (const key of order) {
+        groups.get(key).sort((a, b) => rank(b) - rank(a));
+    }
+    const result = [];
+    let progressed = true;
+    while (result.length < cap && progressed) {
+        progressed = false;
+        for (const key of order) {
+            const bucket = groups.get(key);
+            if (bucket.length === 0)
+                continue;
+            result.push(bucket.shift());
+            progressed = true;
+            if (result.length >= cap)
+                break;
+        }
+    }
+    return result;
+}
+export function prepareForSerial(event, _conn) {
     const e = event;
     if (event.type === 'usage_update') {
-        // Pre-format ISO dates + strip unused fields
-        const { ollamaStatus, tokenStatus, extraUsageEnabled, extraUsageMonthlyLimit, extraUsageUsedCredits, extraUsageUtilization, costSpent, costLimit, sessionPercent, resetTime, resetDate, ...keep } = e;
+        // WHITELIST of the fields the firmware actually parses (protocol.cpp
+        // handleUsageUpdate). The old blocklist approach silently leaked every
+        // NEW usage field onto the wire — modelCatalog alone (3.2KB) pushed the
+        // line past the firmware's 4096-byte line buffer, so boards discarded
+        // EVERY usage_update and their gauges froze on stale values.
+        const cx = e.codexRateLimits
+            ? {
+                primary: e.codexRateLimits.primary
+                    ? { usedPercent: e.codexRateLimits.primary.usedPercent, resetsAt: formatResetTime(e.codexRateLimits.primary.resetsAt) }
+                    : undefined,
+                secondary: e.codexRateLimits.secondary
+                    ? { usedPercent: e.codexRateLimits.secondary.usedPercent, resetsAt: formatResetTime(e.codexRateLimits.secondary.resetsAt) }
+                    : undefined,
+            }
+            : undefined;
+        // Subscriptions carry an ISO `until`; a serial device has no reliable
+        // clock, so pre-format to a short "~M/D" the panel can render as-is.
+        const subs = Array.isArray(e.subscriptions)
+            ? e.subscriptions.map((sub) => ({
+                name: limitString(sub.name, 27),
+                until: formatShortDate(sub.until),
+            })).filter((sub) => sub.name)
+            : undefined;
+        const ag = e.antigravityStatus
+            ? { planName: limitString(e.antigravityStatus.planName, 23), availableCredits: e.antigravityStatus.availableCredits }
+            : undefined;
         return {
-            ...keep,
-            fiveHourResetsAt: formatResetTime(keep.fiveHourResetsAt),
-            sevenDayResetsAt: formatResetTime(keep.sevenDayResetsAt),
+            type: 'usage_update',
+            fiveHourPercent: e.fiveHourPercent,
+            sevenDayPercent: e.sevenDayPercent,
+            fiveHourResetsAt: formatResetTime(e.fiveHourResetsAt),
+            sevenDayResetsAt: formatResetTime(e.sevenDayResetsAt),
+            inputTokens: e.inputTokens,
+            outputTokens: e.outputTokens,
+            toolCalls: e.toolCalls,
+            sessionDurationSec: e.sessionDurationSec,
+            estimatedCostUsd: e.estimatedCostUsd,
+            usageStale: e.usageStale,
+            ...(cx ? { codexRateLimits: cx } : {}),
+            ...(subs ? { subscriptions: subs } : {}),
+            ...(ag ? { antigravityStatus: ag } : {}),
         };
     }
     if (event.type === 'state_update') {
-        // Strip agentCapabilities + other fields ESP32 doesn't parse
-        const { agentCapabilities, billingType, remoteUrl, diff, context, selectedOptionIndex, ...keep } = e;
-        return keep;
+        return {
+            type: 'state_update',
+            state: e.state,
+            permissionMode: e.permissionMode,
+            agentType: limitString(e.agentType, 15),
+            currentTool: limitString(e.currentTool, 39),
+            toolInput: limitString(e.toolInput, 79),
+            projectName: limitString(e.projectName, 39),
+            modelName: limitString(e.modelName, 31),
+            effortLevel: limitString(e.effortLevel, 7),
+            promptType: limitString(e.promptType, 19),
+            question: limitString(e.question, 199),
+            options: sanitizeOptions(e.options),
+            gatewayAvailable: Boolean(e.gatewayAvailable),
+            gatewayConnected: Boolean(e.gatewayConnected),
+            gatewayHasError: Boolean(e.gatewayHasError),
+        };
+    }
+    if (event.type === 'timeline_event' || event.type === 'timeline_history') {
+        // Panels have no local timezone — attach host-local "HH:MM" so the
+        // InkDeck ticker (and future e-ink timelines) shows wall-clock time.
+        const stamp = (entry) => {
+            if (!entry || !Number.isFinite(entry.ts))
+                return entry;
+            const d = new Date(entry.ts);
+            return {
+                ...entry,
+                // Bound to the firmware's TimelineEntry buffers (raw[120]/detail[200])
+                // so a history seed with long chat bodies can't balloon the line.
+                raw: limitString(entry.raw, 119) ?? '',
+                detail: limitString(entry.detail, 199),
+                localHm: `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`,
+            };
+        };
+        if (event.type === 'timeline_event')
+            return { ...e, entry: stamp(e.entry) };
+        return { ...e, entries: Array.isArray(e.entries) ? e.entries.map(stamp) : e.entries };
+    }
+    if (event.type === 'sessions_list') {
+        const raw = Array.isArray(e.sessions) ? e.sessions : [];
+        return {
+            type: 'sessions_list',
+            sessions: roundRobinByAgentType(raw, SERIAL_SESSIONS_CAP).map((s) => ({
+                id: limitString(s.id, 31),
+                projectName: limitString(s.projectName, 39),
+                modelName: limitString(s.modelName, 31),
+                agentType: limitString(s.agentType, 15),
+                state: limitString(s.state, 19),
+                port: Number.isFinite(s.port) ? s.port : 0,
+                alive: Boolean(s.alive),
+                // Per-session detail for the IPS10 D1 mosaic (cells show tool/elapsed,
+                // and awaiting cells render the real option buttons Claude reported).
+                currentTool: limitString(s.currentTool, 39),
+                promptType: limitString(s.promptType, 19),
+                question: limitString(s.question, 159),
+                elapsedSec: Number.isFinite(s.elapsedSec) ? Math.round(s.elapsedSec) : undefined,
+                // Shared activity one-liner — the glanceable "what is it doing" line
+                // (InkDeck session cards render it; other boards ignore it).
+                activity: limitString(s.activity, 79),
+                options: sanitizeOptions(s.options),
+            })),
+        };
     }
     return event;
 }
+function limitString(value, max) {
+    if (typeof value !== 'string')
+        return undefined;
+    return value.length > max ? value.slice(0, max) : value;
+}
+/** ISO date → short "~M/D" for clock-less serial panels ('' when absent/invalid). */
+function formatShortDate(iso) {
+    if (typeof iso !== 'string' || !iso)
+        return '';
+    const d = new Date(iso);
+    if (isNaN(d.getTime()))
+        return '';
+    return `~${d.getMonth() + 1}/${d.getDate()}`;
+}
+function sanitizeOptions(options) {
+    if (!Array.isArray(options))
+        return undefined;
+    return options.slice(0, 8).map((o, index) => ({
+        label: limitString(o?.label, 79) ?? '',
+        shortcut: limitString(o?.shortcut, 39),
+        index: Number.isFinite(o?.index) ? o.index : index,
+        recommended: Boolean(o?.recommended),
+        selected: Boolean(o?.selected),
+    }));
+}
 /** Run a shell command with timeout, escalating to SIGKILL if SIGTERM fails. */
 function execWithKill(cmd, timeoutMs = 3000) {
     return new Promise((resolve, reject) => {
+        let settled = false;
         const child = exec(cmd, { encoding: 'utf-8', timeout: timeoutMs }, (err, stdout) => {
+            if (settled)
+                return;
+            settled = true;
             if (err) {
                 reject(err);
             }
@@ -74,17 +334,94 @@ function execWithKill(cmd, timeoutMs = 3000) {
                 resolve(stdout);
             }
         });
-        // When exec timeout fires, it sends SIGTERM. But stty stuck in kernel I/O
-        // ignores SIGTERM. Schedule a SIGKILL as escalation.
+        // Serial ioctl can enter uninterruptible kernel I/O on broken CDC ports.
+        // On timeout, unblock our promise immediately instead of waiting for exit.
         const killTimer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
             try {
                 child.kill('SIGKILL');
             }
             catch { /* already dead */ }
+            reject(new Error(`command timed out: ${cmd}`));
         }, timeoutMs + 1000);
         child.on('exit', () => clearTimeout(killTimer));
     });
 }
+function execFileWithKill(file, args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let killTimer = null;
+        const child = execFile(file, args, { encoding: 'utf-8', maxBuffer: 64 * 1024 }, (err, stdout, stderr) => {
+            if (settled)
+                return;
+            settled = true;
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (err) {
+                const message = String(stderr || '').trim() || err.message;
+                reject(new Error(message));
+            }
+            else {
+                resolve({ stdout: String(stdout || ''), stderr: String(stderr || '') });
+            }
+        });
+        killTimer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already dead */ }
+            reject(new Error(`timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        child.on('exit', () => {
+            if (killTimer)
+                clearTimeout(killTimer);
+        });
+    });
+}
+async function probePortOpenable(port) {
+    try {
+        await execFileWithKill(process.execPath, ['-e', SERIAL_OPEN_PROBE_SCRIPT, port], SERIAL_OPEN_PROBE_TIMEOUT_MS);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`open probe failed: ${message}`);
+    }
+}
+async function openFdWithProbe(port) {
+    // Isolate potentially wedged macOS CDC/serial open calls in a short-lived
+    // process. Promise.race around fs.open() in this daemon can leave late file
+    // descriptors owned by the daemon after timeout, permanently blocking polls.
+    await probePortOpenable(port);
+    return openSync(port, fsConstants.O_RDWR | fsConstants.O_NOCTTY | fsConstants.O_NONBLOCK);
+}
+function readFromFd(fd, buf) {
+    return new Promise((resolve, reject) => {
+        read(fd, buf, 0, buf.length, null, (err, bytesRead) => {
+            if (err)
+                reject(err);
+            else
+                resolve({ bytesRead });
+        });
+    });
+}
+function writeToFd(fd, data) {
+    return new Promise((resolve, reject) => {
+        write(fd, data, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}
+function closeFd(fd) {
+    close(fd, () => { });
+}
 async function detectESP32Ports() {
     try {
         const platform = process.platform;
@@ -104,12 +441,57 @@ async function detectESP32Ports() {
             if (EXCLUDE_PATTERNS.some(p => p.test(port)))
                 return false;
             return ESP32_PORT_PATTERNS.some(p => p.test(port));
-        });
+        }).sort(compareSerialPorts);
     }
-    catch {
+    catch (err) {
+        lastErrorByPort.set('detect', `port detection failed: ${err instanceof Error ? err.message : String(err)}`);
         return [];
     }
 }
+function compareSerialPorts(a, b) {
+    const aNative = /usbmodem|ttyACM/.test(a);
+    const bNative = /usbmodem|ttyACM/.test(b);
+    if (aNative !== bNative)
+        return aNative ? 1 : -1;
+    return a.localeCompare(b);
+}
+function serialError(port, message) {
+    lastErrorByPort.set(port, message);
+    debug('ESP32', message);
+}
+function isResponsive(conn, now = Date.now()) {
+    if (!conn.connected)
+        return false;
+    const hasRead = conn.lastReadAt > 0;
+    if (hasRead && (now - conn.lastReadAt) <= STALE_THRESHOLD_MS) {
+        return true;
+    }
+    // Fallback for native USB CDC ports: if we have written to it successfully recently,
+    // and it is open, consider it responsive. This prevents native CDC displays (which may
+    // not send read data due to DTR/RTS line states in raw fs mode) from being marked disconnected.
+    const isCDC = /usbmodem|ttyACM/.test(conn.port);
+    if (isCDC && conn.lastWriteAt > 0 && (now - conn.lastWriteAt) <= STALE_THRESHOLD_MS) {
+        return true;
+    }
+    // If no read has occurred yet, allow an initial grace period
+    if (conn.lastReadAt <= 0) {
+        return (now - conn.connectedAt) <= INITIAL_READ_TIMEOUT_MS;
+    }
+    return false;
+}
+/** @internal Exported for testing only */
+export function isRetryableSerialIoError(err) {
+    const code = err?.code;
+    return code === 'EAGAIN' || code === 'EWOULDBLOCK';
+}
+function hasLiveDeviceInfo(conn) {
+    const isCDC = /usbmodem|ttyACM/.test(conn.port);
+    if (isCDC) {
+        // CDC ports may have no read traffic but can still run dashboard/sessions if cached board type exists
+        return Boolean(conn.deviceInfo?.board);
+    }
+    return Boolean(conn.deviceInfo?.board) && conn.lastReadAt > 0;
+}
 /** @internal Exported for testing only */
 export function handleSerialLine(conn, line) {
     if (!line.startsWith('{'))
@@ -117,15 +499,46 @@ export function handleSerialLine(conn, line) {
     try {
         const msg = JSON.parse(line);
         if (msg.type) {
+            conn.lastReadAt = Date.now(); // Update last read timestamp
             debug('ESP32', `← ${conn.port}: ${msg.type}`);
-            conn.deviceInfo = conn.deviceInfo || {};
             if (msg.type === 'device_info') {
                 conn.deviceInfo = {
                     board: msg.board,
                     version: msg.version,
+                    buildHash: msg.buildHash,
+                    buildEpoch: msg.buildEpoch,
                     wifiConfigured: msg.wifiConfigured,
                     wifiConnected: msg.wifiConnected,
+                    wifiRadioParked: msg.wifiRadioParked,
+                    ip: msg.ip,
+                    uptimeSec: msg.uptimeSec,
+                    resetReason: msg.resetReason,
+                    resetReasonCode: msg.resetReasonCode,
+                    otaSupported: msg.otaSupported,
+                    otaSlotCount: msg.otaSlotCount,
+                    otaSlotSize: msg.otaSlotSize,
+                    otaFreeSketchSpace: msg.otaFreeSketchSpace,
+                    otaReason: msg.otaReason,
+                    // Board-side reality counters (debug aid — surfaced on /devices so
+                    // "device shows nothing" can be diagnosed without stealing the port)
+                    timelineCount: msg.timelineCount,
+                    sessionCount: msg.sessionCount,
+                    usageFiveH: msg.usageFiveH,
+                    processingCount: msg.processingCount,
                 };
+                conn.deviceInfoFresh = true;
+                if (conn.deviceInfo.board) {
+                    lastKnownDeviceInfoByPort.set(conn.port, conn.deviceInfo);
+                    persistDeviceInfoCache();
+                }
+            }
+            else if (!conn.deviceInfoFresh &&
+                conn.deviceInfoRequestsSent < DEVICE_INFO_MAX_REQUESTS &&
+                Date.now() - conn.lastDeviceInfoRequestAt >= DEVICE_INFO_READ_RETRY_MS) {
+                // Retry until a device_info arrives on THIS connection — the cache
+                // seed keeps /devices populated meanwhile but must not silence the
+                // re-identify (a lost reply or reflashed board would stay stale).
+                sendDeviceInfoRequest(conn);
             }
             if (messageHandler) {
                 messageHandler(conn.port, msg);
@@ -136,35 +549,16 @@ export function handleSerialLine(conn, line) {
         // Not valid JSON — ignore (ESP32 debug output)
     }
 }
-async function openPort(port) {
-    try {
-        // Open streams first, THEN configure baud rate.
-        // On macOS, opening a serial device can reset stty settings to defaults (9600).
-        // So stty must run AFTER the file descriptors are open.
-        const stream = createWriteStream(port, { flags: 'w' });
-        const conn = {
-            port, stream, reader: null, readBuf: '',
-            connected: true, deviceInfo: null, provisionSent: false,
-        };
-        stream.on('error', (err) => {
-            debug('ESP32', `Serial write error on ${port}: ${err.message}`);
-            conn.connected = false;
-            try {
-                conn.reader?.destroy();
-            }
-            catch { /* ignore */ }
-        });
-        stream.on('close', () => {
-            debug('ESP32', `Serial write closed: ${port}`);
-            conn.connected = false;
-        });
-        // Open read stream for incoming ESP32 messages
+async function startReadLoop(conn) {
+    const buf = Buffer.alloc(1024);
+    while (conn.connected && conn.fd != null) {
         try {
-            const reader = createReadStream(port, { flags: 'r', encoding: 'utf-8' });
-            reader.pause(); // Don't process data until baud rate is configured
-            conn.reader = reader;
-            reader.on('data', (chunk) => {
-                const str = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+            const fd = conn.fd;
+            if (fd == null)
+                break;
+            const { bytesRead } = await readFromFd(fd, buf);
+            if (bytesRead > 0) {
+                const str = buf.toString('utf-8', 0, bytesRead);
                 conn.readBuf += str;
                 let newlineIdx;
                 while ((newlineIdx = conn.readBuf.indexOf('\n')) !== -1) {
@@ -174,55 +568,67 @@ async function openPort(port) {
                         handleSerialLine(conn, line);
                     }
                 }
-                // Prevent buffer bloat from non-newline data
                 if (conn.readBuf.length > 8192) {
                     conn.readBuf = '';
                 }
-            });
-            reader.on('error', (err) => {
-                debug('ESP32', `Serial read error on ${port}: ${err.message}`);
-                conn.connected = false;
-                try {
-                    reader.destroy();
-                }
-                catch { /* ignore */ }
-                try {
-                    conn.stream.end();
-                }
-                catch { /* ignore */ }
-            });
-            reader.on('close', () => {
-                conn.reader = null;
-                conn.connected = false;
-            });
+            }
+            else {
+                // EOF
+                await new Promise(r => setTimeout(r, 20));
+            }
         }
         catch (err) {
-            debug('ESP32', `Failed to open reader on ${port}: ${err.message}`);
-            // Write-only still works for broadcast
-        }
-        // Configure baud rate AFTER file descriptors are open.
-        // On macOS, open() on serial devices can reset stty to defaults (9600).
-        // Skip stty for native USB CDC ports (cu.usbmodem / ttyACM) — they use
-        // USB bus speed, not UART baud rate. stty can interfere with open fds.
-        const isCDC = /usbmodem|ttyACM/.test(port);
-        if (!isCDC) {
-            const platform = process.platform;
-            if (platform === 'darwin') {
-                await execWithKill(`stty -f ${port} 115200 cs8 -cstopb -parenb -hupcl`);
+            if (err.code === 'EAGAIN' || err.code === 'EWOULDBLOCK') {
+                // No data right now, wait 20ms and try again
+                await new Promise(r => setTimeout(r, 20));
             }
-            else if (platform === 'linux') {
-                await execWithKill(`stty -F ${port} 115200 cs8 -cstopb -parenb -hupcl`);
+            else {
+                debug('ESP32', `Serial read error on ${conn.port}: ${err.message}`);
+                closeConnection(conn);
+                break;
             }
         }
-        // Resume reader now that baud rate is configured (flush any garbled data from open→stty window)
-        if (conn.reader) {
-            conn.readBuf = '';
-            conn.reader.resume();
+    }
+}
+async function openPort(port) {
+    let fd = null;
+    try {
+        // Use one read/write fd. Opening /dev/cu.* separately for read and write
+        // can make macOS serial look writable while ESP32 never receives host JSON.
+        fd = await openFdWithProbe(port);
+        const platform = process.platform;
+        const isCDC = /usbmodem|ttyACM/.test(port);
+        if (!isCDC && platform === 'darwin') {
+            await execWithKill(`stty -f ${port} 115200 cs8 -cstopb -parenb -hupcl raw -echo`);
+        }
+        else if (!isCDC && platform === 'linux') {
+            await execWithKill(`stty -F ${port} 115200 cs8 -cstopb -parenb -hupcl raw -echo`);
         }
+        const stream = {
+            destroyed: false,
+            writable: true,
+            write: () => true,
+            destroy: () => { },
+            on: () => { },
+        };
+        const conn = {
+            port, fd, stream, reader: null, readBuf: '',
+            connected: true, deviceInfo: lastKnownDeviceInfoByPort.get(port) ?? null,
+            deviceInfoFresh: false, provisionSent: false,
+            connectedAt: Date.now(),
+            lastReadAt: 0,
+            lastWriteAt: Date.now(),
+            lastDeviceInfoRequestAt: 0,
+            deviceInfoRequestsSent: 0,
+            writeQueue: [],
+            writeTimer: null,
+        };
         const portType = isCDC ? 'CDC' : 'UART';
         debug('ESP32', `Opened serial port (r/w): ${port} [${portType}]`);
+        // Start async read loop
+        void startReadLoop(conn);
         // Request device info on connect
-        sendToConnection(conn, JSON.stringify({ type: 'device_info_request' }));
+        sendDeviceInfoRequest(conn);
         // Send full initial state (state + usage + sessions) so ESP32 doesn't
         // have to wait for next state change or heartbeat cycle
         if (initialStateProvider) {
@@ -233,34 +639,96 @@ async function openPort(port) {
                 // Skip usage_update without API data — would reset ESP32 to "no data"
                 if (event.type === 'usage_update' && event.fiveHourPercent == null)
                     continue;
-                sendToConnection(conn, JSON.stringify(prepareForSerial(event)));
+                if ((event.type === 'usage_update' || event.type === 'sessions_list') && !hasLiveDeviceInfo(conn))
+                    continue;
+                sendToConnection(conn, JSON.stringify(prepareForSerial(event, conn)));
             }
         }
         else if (stateProvider) {
             const event = stateProvider();
             if (event)
-                sendToConnection(conn, JSON.stringify(event));
+                sendToConnection(conn, JSON.stringify(prepareForSerial(event, conn)));
         }
         return conn;
     }
     catch (err) {
-        debug('ESP32', `Failed to open ${port}: ${err.message}`);
+        if (fd != null) {
+            closeFd(fd);
+        }
+        serialError(port, `Failed to open ${port}: ${err.message}`);
         return null;
     }
 }
-function sendToConnection(conn, json) {
+function closeConnection(conn) {
+    conn.connected = false;
+    if (conn.writeTimer) {
+        clearTimeout(conn.writeTimer);
+        conn.writeTimer = null;
+    }
+    conn.writeQueue = [];
+    if (conn.fd != null)
+        closeFd(conn.fd);
+    conn.fd = null;
+}
+function sendToConnection(conn, json, priority = false) {
     if (!conn.connected)
         return;
-    if (conn.stream.destroyed || !conn.stream.writable) {
-        conn.connected = false;
-        return;
+    if (priority) {
+        conn.writeQueue.unshift(json);
     }
-    try {
-        conn.stream.write(json + '\n');
+    else {
+        conn.writeQueue.push(json);
     }
-    catch {
-        conn.connected = false;
+    while (conn.writeQueue.length > SERIAL_MAX_QUEUE) {
+        const dropIdx = conn.writeQueue.findIndex((queued) => queued.startsWith('{"type":"state_update"') || queued.startsWith('{"type":"sessions_list"'));
+        conn.writeQueue.splice(dropIdx >= 0 ? dropIdx : 0, 1);
     }
+    scheduleWriteFlush(conn, 0);
+}
+function scheduleWriteFlush(conn, delayMs) {
+    if (conn.writeTimer || !conn.connected)
+        return;
+    conn.writeTimer = setTimeout(() => flushNextWrite(conn), delayMs);
+}
+function flushNextWrite(conn) {
+    conn.writeTimer = null;
+    if (!conn.connected)
+        return;
+    const json = conn.writeQueue.shift();
+    if (!json)
+        return;
+    if (conn.fd == null) {
+        closeConnection(conn);
+        return;
+    }
+    writeToFd(conn.fd, json + '\n')
+        .then(() => {
+        conn.lastWriteAt = Date.now();
+        if (conn.writeQueue.length > 0) {
+            scheduleWriteFlush(conn, SERIAL_WRITE_INTERVAL_MS);
+        }
+    })
+        .catch((err) => {
+        if (isRetryableSerialIoError(err)) {
+            conn.writeQueue.unshift(json);
+            scheduleWriteFlush(conn, SERIAL_WRITE_INTERVAL_MS);
+            return;
+        }
+        debug('ESP32', `Serial write error on ${conn.port}: ${err.message}`);
+        closeConnection(conn);
+    });
+}
+function sendDeviceInfoRequest(conn) {
+    conn.lastDeviceInfoRequestAt = Date.now();
+    conn.deviceInfoRequestsSent++;
+    sendToConnection(conn, JSON.stringify({ type: 'device_info_request' }), true);
+}
+function sendSerialKeepalive(conn) {
+    // ESP32 marks USB as connected only after successfully parsing recent JSON.
+    // Keep this independent from larger state/session payloads so display
+    // reconnect overlays do not flap when a board is slow to parse UI updates.
+    conn.writeQueue = conn.writeQueue.filter((queued) => queued !== SERIAL_KEEPALIVE_JSON);
+    sendToConnection(conn, SERIAL_KEEPALIVE_JSON, true);
 }
 /**
  * Register a callback that returns the current state_update event.
@@ -277,6 +745,25 @@ export function setESP32StateProvider(provider) {
 export function setESP32UsageProvider(provider) {
     usageProvider = provider;
 }
+/**
+ * Register a callback that returns the current display_state event.
+ * display_state is otherwise edge-triggered (on change + on connect); a board
+ * that misses the wake edge (half-open serial, daemon handoff) would stay
+ * dark until power-cycled. The heartbeat re-sync makes it self-heal.
+ */
+export function setESP32DisplayStateProvider(provider) {
+    displayStateProvider = provider;
+}
+/**
+ * Register a callback that returns the current sessions_list event.
+ * Like display_state it is otherwise edge-triggered (on change + on connect);
+ * a board that (re)connects during a quiet window — daemon handoff, half-open
+ * serial — would sit on an empty roster ("no active sessions") until the next
+ * unrelated session change. The heartbeat re-sync makes it self-heal.
+ */
+export function setESP32SessionsListProvider(provider) {
+    sessionsListProvider = provider;
+}
 /**
  * Register a provider that returns all initial state events (state + usage + sessions).
  * Called when a new ESP32 device connects to send full state immediately.
@@ -296,28 +783,222 @@ function sendHeartbeat() {
     if (connections.length === 0)
         return;
     heartbeatCount++;
+    for (const conn of connections) {
+        if (conn.connected)
+            sendSerialKeepalive(conn);
+        // Refresh the identity snapshot about once a minute even after a fresh
+        // device_info landed — its debug counters (sessionCount/timelineCount)
+        // are point-in-time, and a connect-moment snapshot reading "0" on
+        // /devices masquerades as "board parses nothing".
+        if (conn.deviceInfoFresh && Date.now() - conn.lastDeviceInfoRequestAt > 60_000) {
+            sendDeviceInfoRequest(conn);
+        }
+    }
     // Send state_update (stripped for serial — smaller payload)
     if (stateProvider) {
         const event = stateProvider();
         if (event) {
-            const json = JSON.stringify(prepareForSerial(event));
             for (const conn of connections) {
-                sendToConnection(conn, json);
+                sendToConnection(conn, JSON.stringify(prepareForSerial(event, conn)));
+            }
+        }
+    }
+    // Re-sync display_state every cycle. It is edge-triggered elsewhere, and a
+    // board that misses a wake edge would otherwise stay blacked out until the
+    // next reconnect or a power cycle (payload is ~70 bytes; the firmware
+    // handler is idempotent).
+    if (displayStateProvider) {
+        const event = displayStateProvider();
+        if (event) {
+            for (const conn of connections) {
+                sendToConnection(conn, JSON.stringify(prepareForSerial(event, conn)));
+            }
+        }
+    }
+    // Re-sync sessions_list every cycle for the same reason: it is edge-triggered
+    // elsewhere, so a board that reconnects during a quiet window shows "no active
+    // sessions" until the next session change. Only send once a device has
+    // identified (matches the sessions_list gating in the broadcast path).
+    if (sessionsListProvider) {
+        const event = sessionsListProvider();
+        if (event) {
+            for (const conn of connections) {
+                if (!hasLiveDeviceInfo(conn))
+                    continue;
+                sendToConnection(conn, JSON.stringify(prepareForSerial(event, conn)));
             }
         }
     }
     // Send usage_update (so ESP32 always has fresh usage/reset times)
-    // Only send if API usage data is present (fiveHourPercent defined),
-    // otherwise the ESP32 would reset its cached values to "no data" sentinel.
+    // Only send once SOME usage signal is present — Claude 5h/7d, Codex limits,
+    // or Antigravity credits — otherwise the ESP32 would reset its cached values
+    // to the "no data" sentinel before any provider has populated them.
     if (usageProvider) {
         const event = usageProvider();
-        if (event && event.fiveHourPercent != null) {
-            const json = JSON.stringify(prepareForSerial(event));
+        const u = event;
+        const hasUsage = u && (u.fiveHourPercent != null || u.codexRateLimits != null || u.antigravityStatus != null);
+        if (hasUsage && event) {
             for (const conn of connections) {
-                sendToConnection(conn, json);
+                if (!hasLiveDeviceInfo(conn))
+                    continue;
+                sendToConnection(conn, JSON.stringify(prepareForSerial(event, conn)));
             }
         }
     }
+    // Retry device identification. Some boards answer heartbeats/provisioning
+    // but miss the first request after USB reset; without a retry they stay
+    // anonymous and surfaces render them as reconnecting.
+    //
+    // Gate on deviceInfoFresh, NOT conn.deviceInfo: a cache-seeded connection has
+    // a non-null (stale) deviceInfo but deviceInfoFresh=false. Keying off
+    // conn.deviceInfo froze such a connection at the cache seed forever — a board
+    // reflashed/OTA-updated on the same port (e.g. inkdeck round8→round9) would
+    // keep reporting its old buildHash/no-OTA because no path ever re-requested.
+    // deviceInfoFresh only flips true once a LIVE device_info lands on THIS
+    // connection, so a fresh board stops the retries (capped at MAX) as before.
+    const now = Date.now();
+    for (const conn of connections) {
+        if (!shouldRetryDeviceInfoIdentify(conn, now))
+            continue;
+        const seeded = conn.deviceInfo ? ' (cache-seeded — refreshing identity)' : '';
+        debug('ESP32', `${conn.port}: no live device_info yet${seeded} — retrying request`);
+        sendDeviceInfoRequest(conn);
+    }
+    // Check for stale connections and trigger recovery
+    checkStaleConnections();
+}
+/**
+ * A connection that opened cleanly but has never spoken the AgentDeck protocol:
+ * no device_info, no cached board for this port, and not a single valid JSON
+ * line read. Strong evidence it's a foreign device (e.g. a TRMNL panel) we
+ * should stop holding/resetting rather than an AgentDeck board that's just slow.
+ */
+/** @internal Exported for testing only */
+export function isUnidentifiedForeign(conn) {
+    return !conn.deviceInfo?.board && !lastKnownDeviceInfoByPort.has(conn.port) && conn.lastReadAt === 0;
+}
+/**
+ * A CDC port that IS an AgentDeck board (live device_info, or a cached board for
+ * this port) yet has produced no read since this (re)connection. A healthy board
+ * answers device_info/keepalive within seconds, so lastReadAt===0 well past a
+ * generous grace means a half-open USB-CDC pipe (board reset / re-enumerated)
+ * that heartbeat writes will never revive — the FD must be recycled so re-poll
+ * re-probes. Mutually exclusive with isUnidentifiedForeign (this REQUIRES an
+ * identified board; that one requires none).
+ */
+/** @internal Exported for testing only */
+export function isHalfOpenIdentifiedCdc(conn, now = Date.now()) {
+    const isCDC = /usbmodem|ttyACM/.test(conn.port);
+    if (!isCDC)
+        return false;
+    const isIdentified = Boolean(conn.deviceInfo?.board) || lastKnownDeviceInfoByPort.has(conn.port);
+    return isIdentified && conn.lastReadAt === 0 && (now - conn.connectedAt) > CDC_SILENT_READ_TIMEOUT_MS;
+}
+/**
+ * Whether the periodic heartbeat should (re)send a device_info_request to
+ * re-identify this connection. Keys off deviceInfoFresh (a LIVE reply on THIS
+ * connection), NOT conn.deviceInfo — a cache-seeded connection carries a stale
+ * deviceInfo but deviceInfoFresh=false and must keep re-requesting until the
+ * board answers, so a reflashed/OTA-updated board on the same port refreshes
+ * its buildHash/OTA fields instead of freezing at the cache seed. Capped by
+ * DEVICE_INFO_MAX_REQUESTS and paced by DEVICE_INFO_RETRY_MS.
+ */
+/** @internal Exported for testing only */
+export function shouldRetryDeviceInfoIdentify(conn, now = Date.now()) {
+    if (!conn.connected || conn.deviceInfoFresh)
+        return false;
+    if (conn.deviceInfoRequestsSent >= DEVICE_INFO_MAX_REQUESTS)
+        return false;
+    if (now - conn.lastDeviceInfoRequestAt < DEVICE_INFO_RETRY_MS)
+        return false;
+    return true;
+}
+function denylistForeignPort(port, reason) {
+    foreignDenylistUntil.set(port, Date.now() + FOREIGN_DENYLIST_COOLDOWN_MS);
+    foreignProbeFailures.delete(port);
+    debug('ESP32', `Denylisting non-AgentDeck port ${port} for ${Math.round(FOREIGN_DENYLIST_COOLDOWN_MS / 60000)}min (${reason})`);
+}
+/** @internal Exported for testing only. True if the port is in active cooldown. */
+export function isForeignPortDenylisted(port, now = Date.now()) {
+    const until = foreignDenylistUntil.get(port);
+    return until != null && until > now;
+}
+/** @internal Exported for testing only. Clear all foreign-port tracking state. */
+export function __resetForeignPortState() {
+    foreignProbeFailures.clear();
+    foreignDenylistUntil.clear();
+}
+/** @internal Exported for testing only.
+ *  Count a failed identification cycle; denylist once it crosses the threshold. */
+export function recordForeignProbeFailure(port) {
+    const next = (foreignProbeFailures.get(port) ?? 0) + 1;
+    foreignProbeFailures.set(port, next);
+    if (next >= FOREIGN_MAX_PROBE_FAILURES) {
+        denylistForeignPort(port, `${next} failed probes`);
+    }
+}
+/**
+ * Check for stale connections (no read for >60s) and close them.
+ * This allows re-poll to automatically reconnect devices that stopped responding.
+ */
+function checkStaleConnections() {
+    const now = Date.now();
+    let staleCount = 0;
+    for (const conn of connections) {
+        if (!conn.connected)
+            continue;
+        const isCDC = /usbmodem|ttyACM/.test(conn.port);
+        const hasRead = conn.lastReadAt > 0;
+        const readAge = hasRead ? now - conn.lastReadAt : now - conn.connectedAt;
+        const writeAge = now - conn.lastWriteAt;
+        // For CDC ports, do not close due to lack of read traffic if write is active and healthy.
+        if (isCDC) {
+            // A held-open CDC port that never identifies is a foreign device; denylist
+            // it so we stop occupying it (CDC ports aren't otherwise reaped on silence).
+            if (isUnidentifiedForeign(conn) && (now - conn.connectedAt) > FOREIGN_CDC_GRACE_MS) {
+                denylistForeignPort(conn.port, 'CDC never identified');
+                closeConnection(conn);
+                staleCount++;
+                continue;
+            }
+            // A CDC port whose board is identified but has read nothing since connect is
+            // half-open (board reset, RX pipe dead). Recycle the FD so re-poll re-probes;
+            // the reopen's DTR/RTS toggle may itself revive the board. Feed the foreign
+            // probe-failure counter so a permanently-dead board denylists after a few
+            // strikes instead of getting DTR/RTS-reset every grace window.
+            if (isHalfOpenIdentifiedCdc(conn, now)) {
+                debug('ESP32', `Half-open CDC (identified, no read since connect): ${conn.port} — recycling`);
+                recordForeignProbeFailure(conn.port);
+                closeConnection(conn);
+                staleCount++;
+                continue;
+            }
+            if (writeAge > STALE_THRESHOLD_MS) {
+                debug('ESP32', `Stale CDC connection (no write for >60s): ${conn.port}`);
+                closeConnection(conn);
+                staleCount++;
+            }
+            continue;
+        }
+        if ((!hasRead && readAge > INITIAL_READ_TIMEOUT_MS) ||
+            (hasRead && readAge > STALE_THRESHOLD_MS && writeAge > STALE_THRESHOLD_MS)) {
+            debug('ESP32', `Stale connection detected: ${conn.port} (${Math.floor(readAge / 1000)}s ${hasRead ? 'since last read' : 'without initial read'}, ${Math.floor(writeAge / 1000)}s since write)`);
+            // A UART port closed before ever identifying counts as a foreign probe
+            // failure; enough failures denylist it so we stop reopening (and resetting) it.
+            if (isUnidentifiedForeign(conn))
+                recordForeignProbeFailure(conn.port);
+            closeConnection(conn);
+            staleCount++;
+        }
+    }
+    if (staleCount > 0) {
+        // Remove stale connections immediately, then trigger re-poll
+        connections = connections.filter(c => c.connected);
+        debug('ESP32', `Closed ${staleCount} stale connection(s), re-polling...`);
+        pollForDevices().catch(err => {
+            debug('ESP32', `Re-poll after stale cleanup failed: ${err.message}`);
+        });
+    }
 }
 /**
  * Start ESP32 serial bridge.
@@ -328,6 +1009,7 @@ function sendHeartbeat() {
  * USB port (stty stuck in kernel I/O) cannot block bridge startup.
  */
 export function startESP32Serial() {
+    loadDeviceInfoCache();
     // Fire-and-forget initial detection (non-blocking)
     pollForDevices().catch(err => {
         debug('ESP32', `Initial poll failed: ${err.message}`);
@@ -343,31 +1025,69 @@ export function startESP32Serial() {
     debug('ESP32', 'Serial bridge started');
 }
 async function pollForDevices() {
-    const ports = await detectESP32Ports();
-    // Remove disconnected
-    connections = connections.filter(c => {
-        if (!c.connected) {
-            try {
-                c.stream.end();
+    if (pollInProgress)
+        return;
+    pollInProgress = true;
+    try {
+        const ports = [...new Set(await detectESP32Ports())];
+        const portSet = new Set(ports);
+        // Forget foreign-port state for ports that are gone (a replug re-probes
+        // fresh) or whose cooldown has elapsed. Then skip ports still in cooldown so
+        // we don't reopen — and reset — a non-AgentDeck device every poll.
+        const nowTs = Date.now();
+        for (const [p, until] of [...foreignDenylistUntil]) {
+            if (until <= nowTs || !portSet.has(p))
+                foreignDenylistUntil.delete(p);
+        }
+        for (const p of [...foreignProbeFailures.keys()]) {
+            if (!portSet.has(p))
+                foreignProbeFailures.delete(p);
+        }
+        const allowedPorts = ports.filter((p) => {
+            const until = foreignDenylistUntil.get(p);
+            if (until && until > nowTs) {
+                debug('ESP32', `Skipping denylisted non-AgentDeck port ${p} (${Math.ceil((until - nowTs) / 1000)}s left)`);
+                return false;
+            }
+            return true;
+        });
+        // Remove disconnected or unplugged ports. Read silence alone is handled
+        // separately so half-duplex-but-rendering boards are not reset every minute.
+        connections = connections.filter(c => {
+            if (!c.connected) {
+                closeConnection(c);
+                return false;
             }
-            catch { /* ignore */ }
+            if (!portSet.has(c.port)) {
+                debug('ESP32', `Serial port disappeared: ${c.port}`);
+                closeConnection(c);
+                return false;
+            }
+            return true;
+        });
+        // Add new ports (denylisted foreign ports are excluded via allowedPorts)
+        for (const port of allowedPorts) {
+            if (connections.some(c => c.port === port) || openingPorts.has(port))
+                continue;
+            openingPorts.add(port);
             try {
-                c.reader?.destroy();
+                const conn = await openPort(port);
+                if (conn && !connections.some(c => c.port === port)) {
+                    connections.push(conn);
+                }
+                else if (conn) {
+                    conn.connected = false;
+                    closeConnection(conn);
+                }
             }
-            catch { /* ignore */ }
-            return false;
-        }
-        return true;
-    });
-    // Add new ports
-    for (const port of ports) {
-        if (!connections.some(c => c.port === port)) {
-            const conn = await openPort(port);
-            if (conn) {
-                connections.push(conn);
+            finally {
+                openingPorts.delete(port);
             }
         }
     }
+    finally {
+        pollInProgress = false;
+    }
 }
 /**
  * Broadcast a BridgeEvent to all connected ESP32 devices via serial.
@@ -377,7 +1097,6 @@ export function broadcastESP32(event) {
         return;
     if (!FORWARDED_EVENTS.has(event.type))
         return;
-    const prepared = prepareForSerial(event);
     // Debug: log sessions_list and state_update details for ESP32 troubleshooting
     if (event.type === 'sessions_list') {
         const e = event;
@@ -388,9 +1107,11 @@ export function broadcastESP32(event) {
         const e = event;
         debug('ESP32', `→ state_update: agent=${e.agentType} state=${e.state}`);
     }
-    const json = JSON.stringify(prepared);
     for (const conn of connections) {
-        sendToConnection(conn, json);
+        if (event.type === 'sessions_list' && !hasLiveDeviceInfo(conn))
+            continue;
+        const prepared = prepareForSerial(event, conn);
+        sendToConnection(conn, JSON.stringify(prepared));
     }
 }
 /**
@@ -400,7 +1121,7 @@ export function sendWifiProvision(port, msg) {
     const conn = connections.find(c => c.port === port && c.connected);
     if (!conn)
         return false;
-    sendToConnection(conn, JSON.stringify(msg));
+    sendToConnection(conn, JSON.stringify(msg), true);
     conn.provisionSent = true;
     debug('ESP32', `→ ${port}: wifi_provision (SSID: ${msg.ssid})`);
     return true;
@@ -411,31 +1132,76 @@ export function sendWifiProvision(port, msg) {
 export function sendWifiProvisionToAll(msg) {
     let count = 0;
     for (const conn of connections) {
-        if (!conn.connected)
-            continue;
-        // Skip if already provisioned or WiFi already configured
-        if (conn.provisionSent)
+        if (!shouldSendWifiProvision(conn))
             continue;
-        if (conn.deviceInfo?.wifiConnected)
-            continue;
-        sendToConnection(conn, JSON.stringify(msg));
+        sendToConnection(conn, JSON.stringify(msg), true);
         conn.provisionSent = true;
         count++;
         debug('ESP32', `→ ${conn.port}: wifi_provision (SSID: ${msg.ssid})`);
     }
     return count;
 }
+/** @internal Exported for testing only */
+export function shouldSendWifiProvision(conn) {
+    if (!conn.connected)
+        return false;
+    if (!conn.deviceInfo?.board)
+        return false;
+    if (conn.provisionSent)
+        return false;
+    // IPS10 carries a daemon endpoint in NVS in addition to WiFi credentials.
+    // Refresh it once while USB serial is active and the radio is online, even
+    // if the board is already configured/connected; otherwise a stale endpoint
+    // can survive and WiFi-only operation keeps dialing the old daemon host.
+    if (conn.deviceInfo.board === 'ips_10' && conn.deviceInfo.wifiConnected && !conn.deviceInfo.wifiRadioParked) {
+        return true;
+    }
+    if (conn.deviceInfo.wifiConnected)
+        return false;
+    // Auto-provision is for first setup. A configured board may intentionally have
+    // WiFi off (IPS10 USB-primary radio parking) or may be temporarily away from
+    // its AP; repeatedly injecting credentials would fight firmware policy.
+    if (conn.deviceInfo.wifiConfigured)
+        return false;
+    return true;
+}
 /**
  * Get device info for all connected ESP32 devices.
  */
 export function getESP32DeviceInfo() {
+    const now = Date.now();
     return connections
-        .filter(c => c.connected)
+        .filter(c => isResponsive(c, now))
         .map(c => ({
         port: c.port,
         ...c.deviceInfo,
     }));
 }
+/**
+ * Board identities currently reachable over a LIVE, responsive USB serial
+ * connection (has announced device_info and is actively read/written). The
+ * daemon uses this to enforce single-path communication: when a physical board
+ * is driven over serial, its WiFi WebSocket copy is redundant and is suppressed
+ * (see daemon-server transport dedup). A power-only USB (no enumerated port) or
+ * a silent/booting port is NOT responsive, so it never appears here and the
+ * board keeps using WiFi — exactly the desired fallback.
+ *
+ * `ip` is the board's own WiFi IP (when connected), used to confirm the serial
+ * connection and the WiFi socket are the same physical unit before deduping.
+ */
+export function getSerialReachableBoards() {
+    const now = Date.now();
+    const out = [];
+    for (const c of connections) {
+        if (!isResponsive(c, now))
+            continue;
+        const board = c.deviceInfo?.board;
+        if (!board)
+            continue;
+        out.push({ board, ip: c.deviceInfo?.wifiConnected ? c.deviceInfo?.ip : undefined });
+    }
+    return out;
+}
 /**
  * Wake recovery — close stale file descriptors, force immediate re-poll.
  */
@@ -443,14 +1209,7 @@ export function handleESP32Wake() {
     debug('ESP32', `Wake recovery — closing ${connections.length} stale connection(s)`);
     for (const conn of connections) {
         conn.connected = false;
-        try {
-            conn.stream.end();
-        }
-        catch { /* ignore */ }
-        try {
-            conn.reader?.destroy();
-        }
-        catch { /* ignore */ }
+        closeConnection(conn);
     }
     connections = [];
     // Delay re-poll 2s to let USB bus stabilize after wake
@@ -474,14 +1233,7 @@ export function stopESP32Serial() {
     }
     for (const conn of connections) {
         conn.connected = false;
-        try {
-            conn.stream.end();
-        }
-        catch { /* ignore */ }
-        try {
-            conn.reader?.destroy();
-        }
-        catch { /* ignore */ }
+        closeConnection(conn);
     }
     connections = [];
     messageHandler = null;
@@ -491,12 +1243,57 @@ export function stopESP32Serial() {
  * Get number of connected ESP32 devices.
  */
 export function esp32ConnectionCount() {
-    return connections.filter(c => c.connected).length;
+    const now = Date.now();
+    return connections.filter(c => isResponsive(c, now)).length;
 }
 /**
  * Get list of connected ESP32 serial port paths.
  */
 export function getESP32Ports() {
-    return connections.filter(c => c.connected).map(c => c.port);
+    const now = Date.now();
+    return connections.filter(c => isResponsive(c, now)).map(c => c.port);
+}
+/**
+ * Get detailed connection status for all ESP32 devices.
+ * Used by /api/status endpoint to show connection health.
+ */
+export function getSerialConnectionStatus() {
+    const now = Date.now();
+    return connections.map(c => ({
+        port: c.port,
+        connected: isResponsive(c, now),
+        transportOpen: c.connected,
+        board: c.deviceInfo?.board,
+        version: c.deviceInfo?.version,
+        buildHash: c.deviceInfo?.buildHash,
+        buildEpoch: c.deviceInfo?.buildEpoch,
+        wifiConfigured: c.deviceInfo?.wifiConfigured,
+        wifiConnected: c.deviceInfo?.wifiConnected,
+        wifiRadioParked: c.deviceInfo?.wifiRadioParked,
+        uptimeSec: c.deviceInfo?.uptimeSec,
+        resetReason: c.deviceInfo?.resetReason,
+        resetReasonCode: c.deviceInfo?.resetReasonCode,
+        otaSupported: c.deviceInfo?.otaSupported,
+        otaSlotCount: c.deviceInfo?.otaSlotCount,
+        otaSlotSize: c.deviceInfo?.otaSlotSize,
+        otaFreeSketchSpace: c.deviceInfo?.otaFreeSketchSpace,
+        otaReason: c.deviceInfo?.otaReason,
+        timelineCount: c.deviceInfo?.timelineCount,
+        sessionCount: c.deviceInfo?.sessionCount,
+        usageFiveH: c.deviceInfo?.usageFiveH,
+        processingCount: c.deviceInfo?.processingCount,
+        lastReadAt: c.lastReadAt,
+        lastWriteAt: c.lastWriteAt,
+        lastReadSecondsAgo: c.lastReadAt > 0 ? Math.floor((now - c.lastReadAt) / 1000) : null,
+        lastWriteSecondsAgo: Math.floor((now - c.lastWriteAt) / 1000),
+        stale: c.connected && !isResponsive(c, now),
+    }));
+}
+export function getSerialLastError() {
+    if (lastErrorByPort.size === 0)
+        return null;
+    return Array.from(lastErrorByPort.entries())
+        .map(([port, error]) => `${port}: ${error}`)
+        .join('; ');
 }
 //# sourceMappingURL=esp32-serial.js.map