@agentdeck/bridge 1.0.2 → 1.0.4

package/dist/daemon-server.js

@@ -23,9 +23,17 @@ import { PassiveSessionObserver } from './passive-observer.js';
 import { SessionTimelineRelay } from './session-timeline-relay.js';
 import { SessionFocusRelay } from './session-focus-relay.js';
 import { updatePushState } from './session-aggregator.js';
-import { setAwaitingOverlay, clearAwaitingOverlay, getAwaitingOverlay, isPermissionNotification, applyAwaitingOverlayToObserved } from './awaiting-overlay.js';
+import { setAwaitingOverlay, setPermissionNotificationOverlay, setAskUserQuestionOverlay, clearAwaitingOverlay, clearAskUserQuestionOverlay, getAwaitingOverlay, isPermissionNotification, applyAwaitingOverlayToObserved, } from './awaiting-overlay.js';
 import { registerPending, resolvePending, sweepStalePending, drainAllPending, isPendingRequest } from './permission-resolver.js';
-import { shouldHoldPreToolUse, gateReleased, buildGateQuestion, consumeStop, requestStop, clearStop, STOP_DENY_REASON, queueDirective, takeDirective, clearOnUserPrompt, clearSession as clearSteeringSession, notePermissionPromptShown, noteToolEnd, steeringSnapshot, } from './observed-steering.js';
+import { shouldHoldPreToolUse, gateReleased, buildGateQuestion, consumeStop, requestStop, clearStop, STOP_DENY_REASON, queueDirective, takeDirective, clearOnUserPrompt, clearSession as clearSteeringSession, } from './observed-steering.js';
+import { notePermissionPromptShown, noteToolEnd, steeringSnapshot, } from './observed-steering.js';
+import { resolveSessionIdPrefix } from './session-id-resolve.js';
+import { injectObservedSelection, injectObservedText } from './observed-inject.js';
+import { setSerialCommandSink, setSerialVoiceSink, setSerialQuiesceCheck, sendSerialJson, serialPortConnected, serialPortCapabilities, serialPortBoard, liveSerialPortForBoard, serialBoardsAttached, } from './esp32-serial.js';
+import { parsePeripheralMappings, resolvePeripheralAction, commandForAction } from './peripheral-mapping.js';
+import { DeviceVoiceCollector } from './device-voice.js';
+import { DevicePhotoCollector } from './device-photo.js';
+import { transcribeWithHelper, synthesizeWavWithHelper } from './foundation-models-helper.js';
 import { enqueueOpenCodeCommand, pollOpenCodeCommands } from './opencode-steering.js';
 import { runSessionReview, reviewSnapshot } from './review-runner.js';
 /** Observed-session device approval gate (PreToolUse hold). Default ON — the
@@ -51,7 +59,9 @@ import { initApme, isTimelineProjectionEnabled, loadApmeConfig } from './apme/in
 import { FallbackTaskTimeline } from './fallback-task-timeline.js';
 import { handleApmeRequest } from './apme/http.js';
 import { readModelFromTranscript } from './apme/claude-transcript-reader.js';
-import { transcriptTimelineForSession, lastAssistantTextFromTranscript } from './session-transcript-timeline.js';
+import { transcriptTimelineForSession, lastAssistantTextFromTranscript, lastAssistantTextForSession, } from './session-transcript-timeline.js';
+import { DeviceVoiceReplyRouter, speakableReply, } from './device-voice-reply.js';
+import { rawSessionId } from '@agentdeck/shared';
 import { lastAgentMessageFromCodexRollout } from './codex-rollout-response.js';
 import { callFoundationModelsHelper } from './foundation-models-helper.js';
 import { initModules, stopModules, createDefaultModules, } from './modules/index.js';
@@ -62,7 +72,11 @@ import { getPixooDeviceDetails, pixooDeviceCount } from './pixoo/pixoo-bridge.js
 import { loadTimeboxDevices } from './timebox/timebox-settings.js';
 import { getLanIp, stripUnsafeText, cleanRawText, prepareMarkdownDetail, normalizeCommandPrompt, formatDurationSec } from '@agentdeck/shared';
 import { injectOpenClawSession } from './openclaw-session.js';
+import { buildCardFeed, applyOutboxDecisions, FeedPullTracker, formatFeedPull, normalizeClientIp, } from './card-feed.js';
+import { CARD_FEED_PATH, CARD_OUTBOX_PATH } from '@agentdeck/shared';
 import { readFileSync, statSync } from 'fs';
+import { readFile, rm } from 'fs/promises';
+import { tmpdir } from 'os';
 import { join } from 'path';
 import { homedir } from 'os';
 import { OPENCLAW_CAPABILITIES, State, } from './types.js';
@@ -80,6 +94,10 @@ function exitProcessNow(code = 0) {
 }
 const wifiEsp32Devices = new Map();
 const wifiEsp32Sockets = new Map();
+/** What each ESP32 socket reported about itself, independent of whether the
+ *  single-path dedup kept it in the registry above. */
+const wsSelfBoard = new Map();
+const wsSelfCaps = new Map();
 const otaWaiters = new Map();
 function listWifiEsp32Devices() {
     const now = Date.now();
@@ -98,6 +116,24 @@ function listWifiEsp32Devices() {
     }
     return out;
 }
+/** Card-feed pull log. Daemon-lifetime only: it answers "is the wake cadence
+ *  working right now", which is exactly the M6 power-ladder check that has no
+ *  other observable — a battery client with an empty outbox never identifies
+ *  itself and never opens a socket. */
+const feedPulls = new FeedPullTracker();
+/** Name a pulling client from the WiFi WS roster. A board that has been
+ *  deep-sleeping may have aged out of that roster, which is why the tracker
+ *  keeps its own IP→board memory once it has learned one. */
+function boardForClientIp(ip) {
+    const want = normalizeClientIp(ip);
+    if (!want)
+        return undefined;
+    for (const d of wifiEsp32Devices.values()) {
+        if (d.ip && normalizeClientIp(d.ip) === want)
+            return d.board;
+    }
+    return undefined;
+}
 function wifiEsp32Key(d) {
     const board = typeof d.board === 'string' && d.board ? d.board : 'unknown';
     const ip = typeof d.ip === 'string' && d.ip ? d.ip : 'no-ip';
@@ -164,6 +200,19 @@ function registerWifiEsp32(d, ws) {
         otaSlotSize: typeof d.otaSlotSize === 'number' ? d.otaSlotSize : undefined,
         otaFreeSketchSpace: typeof d.otaFreeSketchSpace === 'number' ? d.otaFreeSketchSpace : undefined,
         otaReason: typeof d.otaReason === 'string' ? d.otaReason : undefined,
+        // Peripheral telemetry/diag — without these the /devices view silently
+        // drops what capability-advertising boards report (the t_embed battery
+        // fields were invisible here for a day for exactly this reason).
+        capabilities: Array.isArray(d.capabilities) ? d.capabilities : undefined,
+        batteryPercent: typeof d.batteryPercent === 'number' ? d.batteryPercent : undefined,
+        batteryVoltageMv: typeof d.batteryVoltageMv === 'number' ? d.batteryVoltageMv : undefined,
+        batteryCharging: typeof d.batteryCharging === 'boolean' ? d.batteryCharging : undefined,
+        usbPowered: typeof d.usbPowered === 'boolean' ? d.usbPowered : undefined,
+        batteryDiag: typeof d.batteryDiag === 'number' ? d.batteryDiag : undefined,
+        touchReady: typeof d.touchReady === 'boolean' ? d.touchReady : undefined,
+        touchDownSamples: typeof d.touchDownSamples === 'number' ? d.touchDownSamples : undefined,
+        touchGestures: typeof d.touchGestures === 'number' ? d.touchGestures : undefined,
+        alsReady: typeof d.alsReady === 'boolean' ? d.alsReady : undefined,
         lastSeenMs: Date.now(),
     });
     wifiEsp32Sockets.set(key, ws);
@@ -815,6 +864,15 @@ export async function startDaemon(opts) {
     let gatewayAdapter = null;
     let gatewayConnecting = false;
     let moduleHealthProvider = () => ({});
+    // Gateway-local activity state for the virtual `openclaw-gateway` session row.
+    // Driven ONLY by the OpenClaw adapter's own parser events — NOT the global
+    // `core.stateMachine`, which every observed Claude session hook also feeds
+    // (daemon-server.ts:1181-1188). Borrowing `snap.state` there painted OpenClaw
+    // as "processing" whenever any unrelated Claude/opencode turn was in flight,
+    // even though the Gateway itself was idle. Mirror of Swift DaemonServer's
+    // `gatewaySessionState` / `gatewayModelName` dedicated fields.
+    let gatewaySessionState = 'idle';
+    let gatewayModelName;
     // Wi-Fi WebSocket e-ink panels (XTeink X3/X4 CrossPoint fork) self-register
     // their device roster via `client_register{clientType:"eink-device"}` — the
     // same volunteer model as the Stream Deck plugin. This handler lived ONLY in
@@ -868,6 +926,17 @@ export async function startDaemon(opts) {
         }
         return out;
     };
+    /**
+     * Debug hook behind `POST /voice/speak` — synthesize arbitrary text straight
+     * to a board's amplifier, bypassing the arming that the real voice loop needs.
+     * Without it the only way to hear the speaker is to hold a board's mic button
+     * and wait for an agent turn, which is useless for verifying a flash.
+     *
+     * Assigned late, once the reply router and its sinks exist: those live far
+     * below the HTTP server, which is already listening by then, so the route must
+     * read this binding at request time rather than close over one in its TDZ.
+     */
+    let speakToBoard = null;
     // ===== HTTP server =====
     const httpServer = createServer((req, res) => {
         // APME routes: auth-gated (task prompts, project paths, hook payloads are sensitive).
@@ -942,6 +1011,10 @@ export async function startDaemon(opts) {
                     { type: 'tui', devices: core.wsServer.getTuiClients() },
                     { type: 'esp32', count: esp32ConnectionCount(), ports: getESP32Ports(), devices: getESP32DeviceInfo() },
                     { type: 'esp32-wifi', devices: listWifiEsp32Devices() },
+                    // Pull-sync clients (M6). Separate from esp32-wifi on purpose: a
+                    // battery board that wakes, syncs over HTTP and sleeps is never in
+                    // the WS roster while it matters.
+                    { type: 'card-feed', clients: feedPulls.clients(), recent: feedPulls.recent(8) },
                     { type: 'pixoo', details: getPixooDeviceDetails() },
                     { type: 'timebox', devices: loadTimeboxDevices() },
                     { type: 'idotmatrix', devices: loadIDotMatrixDevices() },
@@ -956,6 +1029,55 @@ export async function startDaemon(opts) {
             }));
             return;
         }
+        // Device photo upload — a whole JPEG as one request body. The chunked
+        // WS/serial path is loss-prone on this hardware (HWCDC drops 64-byte
+        // blocks; the board's WS TX jammed after the first binary frame), and a
+        // partial JPEG is worthless, so a board with WiFi posts the image over
+        // plain TCP and lets the kernel handle ordering and retransmit.
+        if (req.method === 'POST' && pathname === '/esp32/photo') {
+            const ip = req.socket.remoteAddress ?? '';
+            if (!isLocalConnection(ip)) {
+                const token = parsedUrl.searchParams.get('token') ?? '';
+                if (!validateToken(token)) {
+                    res.writeHead(401, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Unauthorized' }));
+                    return;
+                }
+            }
+            (async () => {
+                const chunks = [];
+                let total = 0;
+                for await (const chunk of req) {
+                    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                    total += buf.length;
+                    if (total > 8 * 1024 * 1024)
+                        throw new Error('photo_too_large');
+                    chunks.push(buf);
+                }
+                if (total === 0)
+                    throw new Error('empty_body');
+                const jpeg = Buffer.concat(chunks);
+                const board = parsedUrl.searchParams.get('board') ?? 'esp32';
+                const saved = devicePhoto.saveDirect(jpeg, {
+                    board,
+                    sessionId: parsedUrl.searchParams.get('sessionId') ?? '',
+                    width: Number(parsedUrl.searchParams.get('w') ?? 0) || 0,
+                    height: Number(parsedUrl.searchParams.get('h') ?? 0) || 0,
+                });
+                // Reply on the board's own transport (serial when it is cabled), the
+                // same way the chunked path did — the HTTP response only confirms
+                // receipt of the bytes.
+                await finishPhotoCapture(saved, photoResultSinkFor(board));
+                return { ok: true, bytes: saved.bytes, path: saved.path };
+            })().then((result) => {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(result));
+            }).catch((err) => {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }));
+            });
+            return;
+        }
         if (req.method === 'POST' && pathname === '/esp32/ota') {
             (async () => {
                 const body = await readJsonBody(req);
@@ -974,6 +1096,61 @@ export async function startDaemon(opts) {
             });
             return;
         }
+        // ===== Card Feed pull sync (M6) — wake-sync-sleep battery clients =====
+        // Auth mirrors /apme: local connections are free; anything else needs the
+        // pairing token (?token=). Devices hold it from provisioning; /health
+        // exposes it for LAN pairing.
+        if ((req.method === 'GET' && pathname === CARD_FEED_PATH)
+            || (req.method === 'POST' && pathname === CARD_OUTBOX_PATH)) {
+            const ip = req.socket.remoteAddress ?? '';
+            if (!isLocalConnection(ip)) {
+                const token = parsedUrl.searchParams.get('token') ?? '';
+                if (!validateToken(token)) {
+                    res.writeHead(401, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Unauthorized — token required for card feed routes' }));
+                    return;
+                }
+            }
+            (async () => {
+                if (req.method === 'GET') {
+                    const sessions = await core.buildSessionsSnapshot();
+                    const feed = buildCardFeed(sessions);
+                    // A sleeping client's whole visit is this one request: no body, no
+                    // board id, nothing pushed. Record it, because the gap between two
+                    // pulls is the only evidence that the timer wake fired at all.
+                    feedPulls.noteBoard(ip, boardForClientIp(ip));
+                    log(`[agentdeck] ${formatFeedPull(feedPulls.record(ip, {
+                        cards: feed.cards.length,
+                        nextPullSec: feed.nextPullSec,
+                    }))}`);
+                    return feed;
+                }
+                const body = await readJsonBody(req);
+                const board = typeof body.board === 'string' ? body.board : 'unknown';
+                // An outbox push is the one request that names the board — bind it to
+                // the IP so the (anonymous) feed pulls that follow are attributable.
+                if (board !== 'unknown')
+                    feedPulls.noteBoard(ip, board);
+                const sessions = await core.buildSessionsSnapshot();
+                const result = applyOutboxDecisions(body, {
+                    sessions: sessions,
+                    isPendingRequest,
+                    dispatch: (cmd) => handleDeviceCommand(cmd),
+                });
+                const applied = result.results.filter((r) => r.status === 'applied').length;
+                if (result.results.length > 0) {
+                    log(`[agentdeck] outbox push from ${board}: ${applied}/${result.results.length} applied`);
+                }
+                return result;
+            })().then((payload) => {
+                res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                res.end(JSON.stringify(payload));
+            }).catch((err) => {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+            });
+            return;
+        }
         if (req.method === 'GET' && pathname === '/display-state') {
             res.writeHead(200, {
                 'Content-Type': 'application/json',
@@ -1083,6 +1260,7 @@ export async function startDaemon(opts) {
                 const eventMap = {
                     SessionStart: 'session_start', SessionEnd: 'session_end',
                     PreToolUse: 'tool_start', PostToolUse: 'tool_end',
+                    PostToolUseFailure: 'tool_failure',
                     Stop: 'stop', UserPromptSubmit: 'user_prompt_submit',
                     Notification: 'notification',
                 };
@@ -1109,17 +1287,22 @@ export async function startDaemon(opts) {
                 else if (mapped === 'tool_end') {
                     core.stateMachine.handleHookEvent('PostToolUse', json);
                 }
-                // Per-session awaiting overlay (observed/direct-`claude` sessions),
-                // display-only. Claude emits Notification with `notification_type:
-                // "permission_prompt"` only when a permission prompt is actually shown
-                // to the user (auto-approved tools fire PreToolUse but never this), so
-                // it is a genuine "waiting for explicit response" signal — unlike the
-                // removed PreToolUse gate. No requestId is ever set: surfaces render
-                // awaiting + question with the respond-in-terminal fallback, never a
-                // fabricated Allow/Deny. Keyed by Claude's own session_id and merged
-                // into the observed-session list at enrich time (awaiting-overlay.ts).
+                // Per-session awaiting overlay for observed/direct-`claude` sessions.
+                // Permission prompts stay Notification-driven and display-only unless
+                // the precision PreToolUse gate below owns a real requestId.
+                // AskUserQuestion is different: its PreToolUse payload already carries
+                // question/options/tool_use_id, so preserve that structured lifecycle
+                // as awaiting_option until the matching PostToolUse/Failure. This avoids
+                // both the generic "Claude needs your permission" downgrade and the
+                // transcript-mtime false resolution that affected a live 17-minute
+                // choice wait. No requestId is fabricated: observed surfaces remain
+                // respond-in-terminal only.
                 const claudeSid = typeof json.session_id === 'string' ? json.session_id : undefined;
                 if (claudeSid) {
+                    const toolName = typeof json.tool_name === 'string' ? json.tool_name : '';
+                    const toolUseId = typeof json.tool_use_id === 'string' ? json.tool_use_id : undefined;
+                    const toolInput = (json.tool_input && typeof json.tool_input === 'object')
+                        ? json.tool_input : undefined;
                     if (mapped === 'notification') {
                         const message = typeof json.message === 'string' ? json.message : '';
                         const notificationType = typeof json.notification_type === 'string' ? json.notification_type : undefined;
@@ -1128,13 +1311,23 @@ export async function startDaemon(opts) {
                             // releases were real prompts, so nothing gets learned as
                             // auto-approved (observed-steering learner).
                             notePermissionPromptShown(claudeSid);
-                            setAwaitingOverlay(claudeSid, message);
-                            // Broadcast immediately rather than waiting for the 2s debounce
-                            // or the 5s observer tick, so the prompt surfaces within one frame.
+                            // AskUserQuestion emits this generic permission notification
+                            // several seconds after its structured PreToolUse. Never replace
+                            // the real question/options with the generic message.
+                            if (setPermissionNotificationOverlay(claudeSid, message)) {
+                                // Broadcast immediately rather than waiting for the 2s debounce
+                                // or the 5s observer tick, so the prompt surfaces within one frame.
+                                core.broadcastSessionsList().catch(() => { });
+                            }
+                        }
+                    }
+                    else if (mapped === 'tool_start' && toolName === 'AskUserQuestion') {
+                        if (setAskUserQuestionOverlay(claudeSid, toolUseId, toolInput)) {
+                            debug('daemon', `AskUserQuestion awaiting_option set: sid=${claudeSid} tool=${toolUseId ?? 'unknown'}`);
                             core.broadcastSessionsList().catch(() => { });
                         }
                     }
-                    else if (mapped === 'tool_start' || mapped === 'tool_end' ||
+                    else if (mapped === 'tool_start' || mapped === 'tool_end' || mapped === 'tool_failure' ||
                         mapped === 'user_prompt_submit' || mapped === 'stop' ||
                         mapped === 'session_start' || mapped === 'session_end') {
                         // Steering lifecycle: a PostToolUse right after an undecided gate
@@ -1143,7 +1336,7 @@ export async function startDaemon(opts) {
                         // never held again this session. User prompt / session end clear
                         // pending STOP + queued directives (the user took over).
                         if (mapped === 'tool_end') {
-                            noteToolEnd(claudeSid, typeof json.tool_name === 'string' ? json.tool_name : undefined);
+                            noteToolEnd(claudeSid, toolName || undefined);
                         }
                         else if (mapped === 'user_prompt_submit') {
                             if (clearOnUserPrompt(claudeSid))
@@ -1152,16 +1345,29 @@ export async function startDaemon(opts) {
                         else if (mapped === 'session_end') {
                             clearSteeringSession(claudeSid);
                         }
-                        // Any subsequent hook means the prompt was answered — drop the
-                        // overlay. Only rebroadcast if there was actually one to clear
-                        // (direct-`claude` sessions fire tool hooks constantly).
-                        // EXCEPT while a held gate is still pending: parallel tool calls
-                        // fire their own PreToolUse/PostToolUse hooks, and clearing here
-                        // would strip the Allow/Deny UI out from under the open request
-                        // (its own onResolved clears the overlay when it settles).
-                        const heldOverlay = getAwaitingOverlay(claudeSid);
-                        const gateStillPending = Boolean(heldOverlay?.requestId && isPendingRequest(heldOverlay.requestId));
-                        if (!gateStillPending && clearAwaitingOverlay(claudeSid)) {
+                        const currentOverlay = getAwaitingOverlay(claudeSid);
+                        let cleared = false;
+                        if ((mapped === 'tool_end' || mapped === 'tool_failure') &&
+                            toolName === 'AskUserQuestion') {
+                            cleared = clearAskUserQuestionOverlay(claudeSid, toolUseId);
+                            if (cleared) {
+                                debug('daemon', `AskUserQuestion awaiting_option cleared by ${eventName}: sid=${claudeSid} tool=${toolUseId ?? 'unknown'}`);
+                            }
+                        }
+                        else if (mapped === 'user_prompt_submit' || mapped === 'stop' ||
+                            mapped === 'session_start' || mapped === 'session_end') {
+                            // Authoritative turn/session boundary supersedes every overlay.
+                            cleared = clearAwaitingOverlay(claudeSid);
+                        }
+                        else if (currentOverlay?.kind !== 'option') {
+                            // Permission overlay: any subsequent tool hook means the prompt
+                            // was answered. Held gates are owned by their resolver and must
+                            // survive unrelated parallel tool hooks.
+                            const gateStillPending = Boolean(currentOverlay?.requestId && isPendingRequest(currentOverlay.requestId));
+                            if (!gateStillPending)
+                                cleared = clearAwaitingOverlay(claudeSid);
+                        }
+                        if (cleared) {
                             core.broadcastSessionsList().catch(() => { });
                         }
                     }
@@ -1600,6 +1806,53 @@ export async function startDaemon(opts) {
             });
             return;
         }
+        // Speak arbitrary text on a board's amplifier — the bench test for the
+        // playback half of the voice loop, which otherwise only fires when a
+        // dictation happens to arm a board and its session finishes a turn. Body:
+        //   { board: string, text: string, force?: boolean, locale?: string }
+        // `board` is the name `agentdeck devices` prints (e.g. "t_embed"); serial is
+        // preferred over WiFi, matching the reply router's routing policy.
+        if (req.method === 'POST' && pathname === '/voice/speak') {
+            let body = '';
+            req.on('data', (chunk) => { body += chunk; if (body.length > 8192)
+                req.destroy(); });
+            req.on('end', () => {
+                let board = '', text = '', force = false, locale;
+                try {
+                    const parsed = body ? JSON.parse(body) : {};
+                    board = typeof parsed.board === 'string' ? parsed.board : '';
+                    text = typeof parsed.text === 'string' ? parsed.text : '';
+                    force = parsed.force === true;
+                    locale = typeof parsed.locale === 'string' && parsed.locale ? parsed.locale : undefined;
+                }
+                catch (err) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `bad body: ${String(err)}` }));
+                    return;
+                }
+                if (!board || !text) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'board and text required' }));
+                    return;
+                }
+                if (!speakToBoard) {
+                    // Only reachable in the window between listen() and the voice wiring.
+                    res.writeHead(503, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'voice not initialized yet' }));
+                    return;
+                }
+                speakToBoard(board, text, { force, locale })
+                    .then(({ ok, detail }) => {
+                    res.writeHead(ok ? 200 : 409, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ spoke: ok, board, detail }));
+                })
+                    .catch((err) => {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `speak failed: ${String(err)}` }));
+                });
+            });
+            return;
+        }
         // On-device Apple Intelligence (FoundationModels) text generation via the
         // daemon-managed *persistent* helper. Keeping it warm in the daemon avoids
         // the ~7s per-process cold start callers would otherwise pay each time
@@ -2096,12 +2349,16 @@ export async function startDaemon(opts) {
             // Steering feedback for observed Claude sessions: devices render
             // "stopping at next tool" / queued-directive badges from these.
             if (!s.id.startsWith('observed:claude:'))
-                return s;
+                return { ...s, liveAnswerable: false };
+            // Can this daemon type into the session's live prompt? Only observed
+            // Claude routes select_option to the injector, and only with a host to
+            // aim at. Sent in both polarities — decks read it to decide whether an
+            // AskUserQuestion option is a button or an inert mirror of the terminal.
+            const liveAnswerable = Boolean(s.tty || s.appName);
             const snap = steeringSnapshot(s.id.slice('observed:claude:'.length));
-            if (!snap.stopRequested && snap.queuedDirectives === 0)
-                return s;
             return {
                 ...s,
+                liveAnswerable,
                 ...(snap.stopRequested ? { stopRequested: true } : {}),
                 ...(snap.queuedDirectives > 0 ? { queuedDirectives: snap.queuedDirectives } : {}),
             };
@@ -2123,12 +2380,18 @@ export async function startDaemon(opts) {
         // / adapter-liveness alone must not materialize a session — that kept a
         // phantom OpenClaw alive on devices after it was effectively off. Shared
         // injector with bridge/src/index.ts; mirror of Swift buildSessionsListEvent.
-        const snap = core.stateMachine.getSnapshot();
+        //
+        // State/project/model come from Gateway-LOCAL trackers, never the global
+        // `core.stateMachine` snapshot: the daemon hub feeds that same snapshot from
+        // every observed Claude/opencode hook, so borrowing it here reported OpenClaw
+        // as active whenever any unrelated session was mid-turn. `projectName` is
+        // pinned to 'OpenClaw' (Swift parity) rather than the global machine's
+        // last-seen project for the same reason.
         return injectOpenClawSession(enrichedSessions, {
             gatewayConnected: core.cachedGatewayConnected,
-            state: snap.state,
-            projectName: snap.projectName ?? 'OpenClaw',
-            modelName: snap.modelName ?? undefined,
+            state: gatewaySessionState,
+            projectName: 'OpenClaw',
+            modelName: gatewayModelName,
             controlMode: 'managed',
         });
     });
@@ -2174,13 +2437,26 @@ export async function startDaemon(opts) {
                     break;
                 case 'parser':
                     core.stateMachine.handleParserEvent(evt.event, evt.data);
+                    // Gateway-local activity state for the virtual session row (mirror of
+                    // Swift `gatewaySessionState`). Kept separate from the global
+                    // `core.stateMachine` above so the OpenClaw row reflects only the
+                    // Gateway's own turn lifecycle, not unrelated observed sessions.
+                    if (evt.event === 'spinner_start')
+                        gatewaySessionState = 'processing';
+                    else if (evt.event === 'idle')
+                        gatewaySessionState = 'idle';
+                    else if (evt.event === 'permission_prompt')
+                        gatewaySessionState = 'awaiting_permission';
                     // The OpenClaw adapter emits the real model via a model_info parser
                     // event, but it only ever updated the display StateMachine — the APME
                     // run was never told, so every openclaw run persisted model_id=NULL.
-                    if (evt.event === 'model_info' && apme && openclawApmeSessionId) {
+                    if (evt.event === 'model_info') {
                         const model = evt.data?.model;
-                        if (model)
-                            apme.collector.updateModel(openclawApmeSessionId, model);
+                        if (model) {
+                            gatewayModelName = model;
+                            if (apme && openclawApmeSessionId)
+                                apme.collector.updateModel(openclawApmeSessionId, model);
+                        }
                     }
                     break;
                 case 'metadata':
@@ -2237,6 +2513,7 @@ export async function startDaemon(opts) {
                         core.cachedGatewayAvailable = true;
                         core.cachedGatewayConnected = true;
                         core.cachedGatewayAuthStatus = 'connected';
+                        gatewaySessionState = 'idle';
                         bridgeLogStream.start();
                         log('[agentdeck] OpenClaw Gateway connected');
                         if (core.stateMachine.getSnapshot().state === 'disconnected') {
@@ -2257,6 +2534,9 @@ export async function startDaemon(opts) {
                     else {
                         core.cachedGatewayConnected = false;
                         core.cachedGatewayAuthStatus = 'gateway_not_found';
+                        // Reset activity to idle; gatewayModelName is preserved across brief
+                        // disconnects (Swift parity) so a flap doesn't blank the model chip.
+                        gatewaySessionState = 'idle';
                         bridgeLogStream.stop();
                         log('[agentdeck] OpenClaw Gateway disconnected');
                         core.stateMachine.emit('state_changed', core.stateMachine.getSnapshot());
@@ -2300,6 +2580,7 @@ export async function startDaemon(opts) {
         core.cachedGatewayConnected = false;
         core.cachedGatewayAuthStatus = 'gateway_not_found';
         core.cachedModelCatalog = null;
+        gatewaySessionState = 'idle';
         if (wasAlive)
             core.stateMachine.handleHookEvent('SessionEnd', {});
         else
@@ -2391,6 +2672,18 @@ export async function startDaemon(opts) {
         // sender here so OTA can address the exact socket instead of broadcasting.
         if (msg.type === 'device_info') {
             core.wsServer.markEsp32Client(sender);
+            // Remember what this socket said about itself BEFORE registration, which
+            // is deliberately skipped when the same board is also live on USB serial
+            // (single-path dedup). Anything keyed off the WiFi registry would then see
+            // a board with no board string and no capabilities — that is what made a
+            // dictation from a USB-attached board fail to arm its spoken reply.
+            const selfBoard = typeof msg.board === 'string' ? msg.board : '';
+            if (selfBoard)
+                wsSelfBoard.set(sender, selfBoard);
+            if (Array.isArray(msg.capabilities)) {
+                wsSelfCaps.set(sender, msg
+                    .capabilities.filter((c) => typeof c === 'string'));
+            }
             registerWifiEsp32(msg, sender);
             return true;
         }
@@ -2454,9 +2747,9 @@ export async function startDaemon(opts) {
             return true; // consumed
         }
         if (msg.type === 'session_push_state') {
-            const { sessionId, state, modelName, effortLevel } = msg;
+            const { sessionId, state, modelName, effortLevel, permissionMode } = msg;
             if (sessionId && state) {
-                updatePushState(sessionId, state, modelName, effortLevel);
+                updatePushState(sessionId, state, modelName, effortLevel, permissionMode);
                 // Trigger sessions list broadcast so clients get fresh state
                 core.maybeBroadcastSessionsList();
             }
@@ -2471,12 +2764,41 @@ export async function startDaemon(opts) {
             core.broadcastSessionsList().catch(() => { });
             return true; // consumed
         }
+        if (msg.type === 'voice_begin') {
+            deviceVoice.begin(sender, msg);
+            return true; // consumed
+        }
+        if (msg.type === 'voice_end') {
+            const captured = deviceVoice.end(sender, msg);
+            if (captured)
+                void finishVoiceCapture(captured, stableSink(sender));
+            return true; // consumed
+        }
+        if (msg.type === 'photo_begin') {
+            devicePhoto.begin(sender, msg);
+            return true; // consumed
+        }
+        if (msg.type === 'photo_end') {
+            const captured = devicePhoto.end(sender, msg);
+            if (captured) {
+                void finishPhotoCapture(captured, stableSink(sender));
+            }
+            else if (msg.cancel !== true) {
+                // Unlike PCM, a JPEG that lost frames is undecodable — tell the board
+                // instead of silently eating the shutter press.
+                try {
+                    sender.send(JSON.stringify({ type: 'photo_result', delivered: false, error: 'empty_or_corrupt_capture' }));
+                }
+                catch { /* client disconnecting */ }
+            }
+            return true; // consumed
+        }
         if (msg.type === 'query_session_timeline') {
             // Reply to THIS requester only with the session's recent timeline so a
             // device that connected mid-session can fill its Detail view on demand
             // (the live timeline_event stream is forward-only). Useful for any
             // reconnecting surface, not just the XTeink X3.
-            const sessionId = msg.sessionId;
+            const sessionId = resolveDeviceSessionId(msg.sessionId);
             const since = msg.since;
             if (typeof sessionId === 'string' && sessionId) {
                 const sinceMs = typeof since === 'number' ? since : undefined;
@@ -2503,6 +2825,26 @@ export async function startDaemon(opts) {
         }
         return false; // not consumed — pass to command handler
     });
+    // Device clients with narrow id buffers (ESP32 SessionInfo.id[32]) echo back
+    // session ids truncated by prepareForSerial's 31-char cap. Observed ids
+    // (`observed:claude:<uuid>`, 52 chars) always exceed that, so an exact-match
+    // lookup silently dropped their commands — worse, the observed-steering
+    // branch queued state under a truncated uuid no hook ever reads. Restore the
+    // full id by unique-prefix match against the known roster before routing.
+    function resolveDeviceSessionId(raw) {
+        if (typeof raw !== 'string' || !raw)
+            return '';
+        const known = ['openclaw-gateway'];
+        for (const s of listActiveSessions())
+            known.push(s.id);
+        const last = core.getLastSessionsListEvent();
+        if (Array.isArray(last?.sessions)) {
+            for (const s of last.sessions)
+                if (typeof s?.id === 'string')
+                    known.push(s.id);
+        }
+        return resolveSessionIdPrefix(raw, known);
+    }
     // Steering commands for observed (hook-only, no PTY) Claude sessions —
     // shared by the session_command route and the bare-command fallback below.
     // Semantics differ from managed PTY on purpose:
@@ -2528,14 +2870,39 @@ export async function startDaemon(opts) {
                     ? command.index === 0
                     : command.value === 'y' || command.value === 'yes';
                 resolvePending(ov.requestId, allow ? 'allow' : 'deny');
+                return;
+            }
+            // No held gate — a live TUI prompt (AskUserQuestion / selector) is on
+            // the user's screen. Type the selection into the terminal itself
+            // (tmux/iTerm2 by tty) — no hold, no timeout, no auto-proceed: if the
+            // terminal isn't reachable the prompt simply stays for the user.
+            if (type === 'select_option' && typeof command.index === 'number') {
+                const idx = command.index;
+                const obs = passiveSessionObserver.collect([])
+                    .find((s) => s.id === `observed:claude:${uuid}`);
+                // The option's visible label lets app-hosted prompts press the matching
+                // native button instead of guessing cursor movement.
+                const label = ov?.options?.[idx]?.label;
+                injectObservedSelection({ tty: obs?.tty, appName: obs?.appName, label }, idx).then((r) => {
+                    debug('daemon', r.ok
+                        ? `observed selection injected via ${r.via} (idx ${idx}, ${uuid.slice(0, 8)})`
+                        : `observed selection NOT injected: ${r.reason} (${uuid.slice(0, 8)})`);
+                }).catch(() => { });
             }
             return;
         }
         debug('daemon', `observed steering: unsupported command ${type} for ${uuid}`);
     }
-    core.wsServer.onCommand((cmd) => {
+    const handleDeviceCommand = (cmd) => {
         debug('daemon', `cmd: ${cmd.type}`);
-        if (gatewayAdapter?.isAlive() && gatewayAdapter.handleCommand(cmd)) {
+        // Session-scoped commands are NEVER OpenClaw's to consume: a device
+        // answering a named session (select_option{sessionId}) must reach the
+        // session routing below — the gateway swallowing it as an exec-approval
+        // ate the Focus Strip's tap-to-approve.
+        const sessionScopedCmd = typeof cmd.sessionId === 'string'
+            && cmd.sessionId
+            && cmd.sessionId !== 'openclaw-gateway';
+        if (!sessionScopedCmd && gatewayAdapter?.isAlive() && gatewayAdapter.handleCommand(cmd)) {
             switch (cmd.type) {
                 case 'respond':
                     core.stateMachine.handleUserAction('respond');
@@ -2583,7 +2950,7 @@ export async function startDaemon(opts) {
             return;
         }
         if (cmd.type === 'focus_session') {
-            const sessionId = cmd.sessionId;
+            const sessionId = resolveDeviceSessionId(cmd.sessionId);
             if (!sessionId)
                 return;
             userFocusedSessionId = sessionId;
@@ -2606,7 +2973,7 @@ export async function startDaemon(opts) {
         // type — no agent control involved. Result: WS events + badge fields +
         // HTML report opened in the browser (this daemon's "popup" tier).
         if (cmd.type === 'review_run') {
-            const sessionId = cmd.sessionId;
+            const sessionId = resolveDeviceSessionId(cmd.sessionId);
             if (!sessionId)
                 return;
             const managed = listActiveSessions().find(s => s.id === sessionId);
@@ -2678,9 +3045,10 @@ export async function startDaemon(opts) {
         }
         // Session-scoped command: forward inner command to a specific session's bridge
         if (cmd.type === 'session_command') {
-            const { sessionId, command } = cmd;
-            if (!sessionId || !command)
+            const { sessionId: rawSessionId, command } = cmd;
+            if (!rawSessionId || !command)
                 return;
+            const sessionId = resolveDeviceSessionId(rawSessionId);
             // Observed Claude sessions have no bridge/PTY — route to the hook-based
             // steering primitives instead (soft STOP, turn-end directive queue,
             // gate approval). This replaces the old silent drop.
@@ -2719,7 +3087,15 @@ export async function startDaemon(opts) {
         // any awaiting cell can be answered, not just the focused one. Focus the
         // named session, then route a plain select_option to its bridge.
         if (cmd.type === 'select_option' && typeof cmd.sessionId === 'string') {
-            const sessionId = cmd.sessionId;
+            const sessionId = resolveDeviceSessionId(cmd.sessionId);
+            // Session-scoped answering of an OBSERVED session's gate — the same
+            // steering primitive the session_command route uses. Without this, a
+            // device answering an observed awaiting cell fell through to the
+            // focused-session relay and was dropped.
+            if (sessionId.startsWith('observed:claude:')) {
+                handleObservedClaudeCommand(sessionId.slice('observed:claude:'.length), cmd);
+                return;
+            }
             const target = listActiveSessions().find(s => s.id === sessionId);
             if (target) {
                 userFocusedSessionId = sessionId;
@@ -2742,6 +3118,45 @@ export async function startDaemon(opts) {
             handleObservedClaudeCommand(userFocusedSessionId.slice('observed:claude:'.length), cmd);
             return;
         }
+        // Peripheral primitive from a sensor-bearing board (t_embed NFC etc.):
+        // log + relay to dashboard clients. Boards never receive it back
+        // (peripheral_event is not serial-forwardable), and command mapping
+        // (tag → focus/approve) comes later as daemon-side config.
+        if (cmd.type === 'peripheral_event') {
+            const p = cmd;
+            const label = p.uid ?? p.code ?? '';
+            debug('daemon', `peripheral_event: ${p.kind} ${label} (${p.board ?? 'esp32'})`);
+            core.wsServer.broadcast(cmd);
+            // Meaning is user configuration, never firmware policy: a mapped tag /
+            // code becomes one of the steering commands the daemon already speaks.
+            try {
+                const mappings = parsePeripheralMappings(loadDaemonSettings());
+                if (mappings.length > 0) {
+                    const roster = core.getLastSessionsListEvent()?.sessions ?? [];
+                    const view = roster.map((r) => ({
+                        id: String(r.id ?? ''),
+                        projectName: typeof r.projectName === 'string' ? r.projectName : undefined,
+                        state: typeof r.state === 'string' ? r.state : undefined,
+                        requestId: typeof r.requestId === 'string' ? r.requestId : undefined,
+                    })).filter((r) => r.id);
+                    const resolved = resolvePeripheralAction({ kind: String(p.kind ?? ''), uid: p.uid, code: p.code }, mappings, view);
+                    if (!resolved) {
+                        debug('daemon', `peripheral_event: no mapping for ${label} (add one in settings.json peripheralMappings)`);
+                    }
+                    else {
+                        const mapped = commandForAction(resolved);
+                        if (mapped) {
+                            debug('daemon', `peripheral_event ${label} → ${resolved.action} on ${resolved.session.id.slice(0, 20)}`);
+                            handleDeviceCommand(mapped);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                debug('daemon', `peripheral mapping failed: ${String(err).slice(0, 120)}`);
+            }
+            return;
+        }
         if (cmd.type === 'query_usage') {
             fetchUsageRelayed(port).then((usage) => {
                 if (usage)
@@ -2750,7 +3165,553 @@ export async function startDaemon(opts) {
                     core.apiUsageStale = true;
             });
         }
+    };
+    // ── Device-sourced voice ──────────────────────────────────────────────
+    // A board streams PCM16 while its push-to-talk key is held; the daemon
+    // transcribes with Apple's on-device recognizer (bundled Swift helper) and
+    // turns the text into a prompt for the session the board was pointing at.
+    const deviceVoice = new DeviceVoiceCollector();
+    // A board sends a one-shot JPEG after its shutter press; the daemon saves it
+    // and routes a prompt referencing the file path to the target session.
+    const devicePhoto = new DevicePhotoCollector();
+    /**
+     * Reply router. The resolver lets a queued reply reach a board over whatever
+     * transport is live *now*: a board plugged in over USB parks its radio and
+     * drops the WebSocket it dictated over, and the answer must still arrive.
+     * Serial first, mirroring the single-path dedup policy used elsewhere.
+     */
+    const voiceReply = new DeviceVoiceReplyRouter(() => Date.now(), (ms) => new Promise((r) => setTimeout(r, ms)), (deviceKey) => {
+        const serialPort = liveSerialPortForBoard(deviceKey);
+        if (serialPort) {
+            log(`[agentdeck] voice: routing reply for ${deviceKey} over serial ${serialPort}`);
+            return serialSinkFor(serialPort);
+        }
+        for (const [key, sock] of wifiEsp32Sockets) {
+            if (sock.readyState !== WebSocket.OPEN)
+                continue;
+            const board = wifiEsp32Devices.get(key)?.board;
+            if (board === deviceKey || key === deviceKey) {
+                log(`[agentdeck] voice: routing reply for ${deviceKey} over ws ${key}`);
+                return stableSink(sock);
+            }
+        }
+        log(`[agentdeck] voice: no live transport for ${deviceKey}`
+            + ` (serial boards: ${serialBoardsAttached().join(',') || 'none'})`);
+        return null;
+    });
+    /**
+     * Wrap a board's socket as a reply sink. Capabilities come from the device
+     * registry rather than being assumed: only a board that advertised
+     * `audio_out` gets audio, so the same voice path degrades to text-only on
+     * boards without an amplifier instead of streaming into nothing.
+     */
+    const replySinkFor = (ws) => ({
+        send: (data) => { try {
+            ws.send(data);
+        }
+        catch { /* closing */ } },
+        sendBinary: (data) => { try {
+            ws.send(data, { binary: true });
+        }
+        catch { /* closing */ } },
+        isOpen: () => ws.readyState === WebSocket.OPEN,
+        describe: () => 'ws',
+        deviceKey: () => {
+            const self = wsSelfBoard.get(ws);
+            if (self)
+                return self;
+            for (const [key, registered] of wifiEsp32Sockets) {
+                if (registered !== ws)
+                    continue;
+                return wifiEsp32Devices.get(key)?.board ?? key;
+            }
+            return 'ws';
+        },
+        capabilities: () => {
+            const self = wsSelfCaps.get(ws);
+            if (self)
+                return self;
+            for (const [key, registered] of wifiEsp32Sockets) {
+                if (registered !== ws)
+                    continue;
+                return wifiEsp32Devices.get(key)?.capabilities ?? [];
+            }
+            return [];
+        },
+    });
+    /**
+     * The other half of the voice round trip. A dictated prompt arms the board
+     * that sent it; when that session's turn completes, the reply is synthesized
+     * on the host and streamed to the board's amplifier. `chat_response` is the
+     * one chokepoint every agent's completion reaches — managed sessions relay it
+     * from their bridge, hook-observed ones get it from the Stop handler above —
+     * so one listener covers all of them.
+     */
+    /** Speak `text` to every board waiting on `sessionId`, or tell them there was
+     *  nothing to read. Shared by both completion shapes below. */
+    const speakReplyTo = (sessionId, text) => {
+        const targets = voiceReply.targetsFor(sessionId);
+        if (targets.length === 0)
+            return;
+        log(`[agentdeck] voice: reply ready for ${sessionId.slice(0, 32)}`
+            + ` -> ${targets.length} board(s)`);
+        const voiceCfg = loadDaemonSettings().voice;
+        if (voiceCfg?.speakReplies === false)
+            return; // opt-out, default on
+        const spoken = speakableReply(text);
+        if (!spoken) {
+            // A code-only answer has nothing worth reading aloud; say that instead of
+            // spelling out punctuation, so the user still knows the turn finished.
+            log('[agentdeck] voice: reply held nothing speakable — skipped');
+            for (const sink of targets) {
+                try {
+                    sink.send(JSON.stringify({ type: 'voice_reply_skipped' }));
+                }
+                catch { /* closing */ }
+                // Consume the arming either way: the dictation was answered, and
+                // leaving it armed would read out the session's *next* turn instead.
+                voiceReply.disarm(sink);
+            }
+            return;
+        }
+        const locale = typeof voiceCfg?.locale === 'string' && voiceCfg.locale
+            ? voiceCfg.locale : undefined;
+        void (async () => {
+            const out = join(tmpdir(), `agentdeck-reply-${process.pid}-${Date.now()}.wav`);
+            try {
+                await synthesizeWavWithHelper(spoken, out, locale ? { locale } : {});
+                const wav = await readFile(out);
+                for (const sink of targets) {
+                    const ok = await voiceReply.stream(sink, wav, spoken);
+                    log(`[agentdeck] voice: ${ok ? 'spoke' : 'FAILED to speak'} reply`
+                        + ` (${wav.length}B, ${spoken.length} chars)`);
+                }
+            }
+            catch (err) {
+                log(`[agentdeck] voice: reply synthesis failed: ${String(err).slice(0, 140)}`);
+            }
+            finally {
+                await rm(out, { force: true }).catch(() => { });
+            }
+        })();
+    };
+    /**
+     * Turn completion for an armed session. Two shapes reach here:
+     *
+     * `chat_response` carries the text and speaks immediately. `chat_end` means
+     * the turn closed with nothing extractable — which routinely happens because
+     * the agent's own record hadn't flushed when the Stop hook fired, not because
+     * the turn was silent. (Measured: a Codex turn closed as "Completed · 5s" and
+     * its rollout held the full answer seconds later.) So a chat_end retries from
+     * that record before giving up, and only then tells the board there was
+     * nothing to read.
+     */
+    const REPLY_RECOVER_DELAY_MS = 2500;
+    core.bridgeTimeline.onEntry((entry, upsert) => {
+        // Upserts re-fire for rows that already spoke; only a new row is a new turn.
+        if (upsert || !entry.sessionId)
+            return;
+        if (entry.type !== 'chat_response' && entry.type !== 'chat_end')
+            return;
+        const sessionId = String(entry.sessionId);
+        if (voiceReply.targetsFor(sessionId).length === 0) {
+            // Only noisy while something is actually waiting — and this is exactly the
+            // case that used to fail silently: a completion row arrived, nothing
+            // matched it, and there was no way to tell a lost arming from a listener
+            // that never ran.
+            if (voiceReply.armedCount() > 0) {
+                log(`[agentdeck] voice: ${entry.type} for ${sessionId.slice(0, 32)} matched no`
+                    + ` arming (armed: ${voiceReply.describeArmed()})`);
+            }
+            return;
+        }
+        if (entry.type === 'chat_response') {
+            const detail = typeof entry.detail === 'string' ? entry.detail : '';
+            speakReplyTo(sessionId, detail || String(entry.raw ?? ''));
+            return;
+        }
+        const agentType = String(entry.agentType ?? '');
+        setTimeout(() => {
+            if (voiceReply.targetsFor(sessionId).length === 0)
+                return;
+            const recovered = agentType.startsWith('codex')
+                ? lastAgentMessageFromCodexRollout(rawSessionId(sessionId))
+                : lastAssistantTextForSession(sessionId);
+            log(`[agentdeck] voice: chat_end recovery for ${sessionId.slice(0, 32)}`
+                + ` (${agentType || 'unknown'}): ${recovered ? `${recovered.length} chars` : 'nothing'}`);
+            speakReplyTo(sessionId, recovered || '');
+        }, REPLY_RECOVER_DELAY_MS).unref?.();
+    });
+    const sinkByWs = new Map();
+    const stableSink = (ws) => {
+        // The router keys arming by sink identity, so the same socket must map to
+        // the same object every time — a fresh wrapper per call would arm one
+        // object and look up another.
+        let sink = sinkByWs.get(ws);
+        if (!sink) {
+            sink = replySinkFor(ws);
+            sinkByWs.set(ws, sink);
+        }
+        return sink;
+    };
+    // Serial-attached boards get the same sink shape. Audio rides base64 inside
+    // JSON lines because this transport is line-delimited and raw PCM would tear
+    // the framing; the encoding cost is invisible on native-USB CDC.
+    const serialSinks = new Map();
+    const serialSinkFor = (port) => {
+        let sink = serialSinks.get(port);
+        if (sink)
+            return sink;
+        sink = {
+            send: (data) => { sendSerialJson(port, data); },
+            sendBinary: (data) => {
+                sendSerialJson(port, { type: 'audio_play_chunk', d: data.toString('base64') });
+            },
+            isOpen: () => serialPortConnected(port),
+            describe: () => `serial:${port.replace('/dev/cu.', '')}`,
+            deviceKey: () => serialPortBoard(port) ?? port,
+            capabilities: () => serialPortCapabilities(port),
+        };
+        serialSinks.set(port, sink);
+        return sink;
+    };
+    /**
+     * Back the `POST /voice/speak` bench test now that both sink flavours exist.
+     * Same transport policy as the reply router — serial first, WiFi second — so
+     * what this proves is what the real reply path will do.
+     */
+    speakToBoard = async (board, text, opts) => {
+        const spoken = speakableReply(text);
+        if (!spoken)
+            return { ok: false, detail: 'nothing speakable in text' };
+        const serialPort = liveSerialPortForBoard(board);
+        let sink = serialPort ? serialSinkFor(serialPort) : null;
+        if (!sink) {
+            for (const [key, sock] of wifiEsp32Sockets) {
+                if (sock.readyState !== WebSocket.OPEN)
+                    continue;
+                if (wifiEsp32Devices.get(key)?.board === board || key === board) {
+                    sink = stableSink(sock);
+                    break;
+                }
+            }
+        }
+        if (!sink) {
+            const wifi = [...wifiEsp32Devices.values()].map((d) => d.board).filter(Boolean);
+            return {
+                ok: false,
+                detail: `no live transport for "${board}"`
+                    + ` (serial: ${serialBoardsAttached().join(',') || 'none'};`
+                    + ` wifi: ${wifi.join(',') || 'none'})`,
+            };
+        }
+        // A board that never initialized its amplifier drops the frames on the
+        // floor, which is indistinguishable from a wiring fault at the listening
+        // end. Say so instead, and let --force stream anyway when the question is
+        // whether the advertisement itself is wrong.
+        const caps = sink.capabilities();
+        if (!caps.includes('audio_out') && !opts.force) {
+            return {
+                ok: false,
+                detail: `${sink.describe()} does not advertise audio_out`
+                    + ` (capabilities: ${caps.join(',') || 'none'}) — pass force to stream anyway`,
+            };
+        }
+        const voiceCfg = loadDaemonSettings().voice;
+        const locale = opts.locale
+            ?? (typeof voiceCfg?.locale === 'string' && voiceCfg.locale ? voiceCfg.locale : undefined);
+        const out = join(tmpdir(), `agentdeck-speak-${process.pid}-${Date.now()}.wav`);
+        try {
+            await synthesizeWavWithHelper(spoken, out, locale ? { locale } : {});
+            const wav = await readFile(out);
+            // Note: stream() consumes any arming held by this sink, so a bench test
+            // run while a board is genuinely waiting on a reply eats that reply.
+            const ok = await voiceReply.stream(sink, wav, spoken);
+            log(`[agentdeck] voice: bench ${ok ? 'spoke' : 'FAILED to speak'} on ${sink.describe()}`
+                + ` (${wav.length}B, ${spoken.length} chars)`);
+            return {
+                ok,
+                detail: ok
+                    ? `${sink.describe()} · ${wav.length}B · ${spoken.length} chars`
+                    : `stream rejected by ${sink.describe()} (transport closed or already speaking)`,
+            };
+        }
+        finally {
+            await rm(out, { force: true }).catch(() => { });
+        }
+    };
+    // Voice from a USB-attached board. Without this the mic worked only while the
+    // board was on WiFi — and attaching USB parks WiFi, so plugging in to charge
+    // silently removed the feature.
+    // Half-duplex guard: hold daemon→board serial writes while that port has an
+    // open photo capture (see flushNextWrite — full-duplex CDC drops blocks).
+    setSerialQuiesceCheck((port) => devicePhoto.isOpen(port));
+    /**
+     * Where a photo_result goes for an HTTP-uploaded photo: the request carries
+     * no socket to answer on, so resolve the board's live transport the same
+     * way a queued voice reply does (serial first, then its WiFi socket).
+     */
+    const photoResultSinkFor = (board) => {
+        const port = liveSerialPortForBoard(board);
+        if (port)
+            return serialSinkFor(port);
+        for (const [key, sock] of wifiEsp32Sockets) {
+            if (sock.readyState !== WebSocket.OPEN)
+                continue;
+            if (wifiEsp32Devices.get(key)?.board === board || key === board) {
+                return stableSink(sock);
+            }
+        }
+        return {
+            send: () => { },
+            sendBinary: () => { },
+            isOpen: () => false,
+            capabilities: () => [],
+            describe: () => `http:${board}(no live transport)`,
+            deviceKey: () => board,
+        };
+    };
+    setSerialVoiceSink((port, msg) => {
+        if (msg.type === 'voice_begin') {
+            deviceVoice.begin(port, msg);
+        }
+        else if (msg.type === 'audio_chunk') {
+            const b64 = typeof msg.d === 'string' ? msg.d : '';
+            if (b64)
+                deviceVoice.append(port, Buffer.from(b64, 'base64'));
+        }
+        else if (msg.type === 'voice_end') {
+            const captured = deviceVoice.end(port, msg);
+            if (captured)
+                void finishVoiceCapture(captured, serialSinkFor(port));
+        }
+        else if (msg.type === 'photo_begin') {
+            // Photo over USB: the strip is a desk fixture and usually powered from
+            // the host, which parks its radio — the camera must not go dead just
+            // because the board is on the cable it lives on.
+            devicePhoto.begin(port, msg);
+        }
+        else if (msg.type === 'photo_chunk') {
+            const b64 = typeof msg.d === 'string' ? msg.d : '';
+            if (b64 && !devicePhoto.append(port, Buffer.from(b64, 'base64'))) {
+                // A chunk with no open capture means photo_begin was lost (torn
+                // serial line, board reset) — say so, or the drop is undiagnosable.
+                debug('photo', `orphan serial photo_chunk from ${port} (no open capture)`);
+            }
+        }
+        else if (msg.type === 'photo_end') {
+            const captured = devicePhoto.end(port, msg);
+            if (captured) {
+                void finishPhotoCapture(captured, serialSinkFor(port));
+            }
+            else if (msg.cancel !== true) {
+                try {
+                    serialSinkFor(port).send(JSON.stringify({ type: 'photo_result', delivered: false, error: 'empty_or_corrupt_capture' }));
+                }
+                catch { /* port closing */ }
+            }
+        }
+    });
+    /**
+     * Finish one captured utterance: transcribe, route the text to the session,
+     * tell the board what happened, and arm it for the spoken reply. Shared by
+     * the WS and serial paths — a board attached over USB must behave exactly
+     * like the same board on WiFi, which is only true if there is one
+     * implementation.
+     */
+    const finishVoiceCapture = async (captured, sink) => {
+        try {
+            // Locale matters: the recognizer falls back to the system locale,
+            // which mangles speech in another language. settings.json
+            // `voice.locale` (BCP-47, e.g. "en-US") overrides it.
+            const voiceCfg = loadDaemonSettings().voice;
+            const locale = typeof voiceCfg?.locale === 'string' && voiceCfg.locale
+                ? voiceCfg.locale : undefined;
+            const text = await transcribeWithHelper(captured.wavPath, locale);
+            const sessionId = resolveDeviceSessionId(captured.sessionId);
+            debug('voice', `transcript "${text.slice(0, 60)}" → ${sessionId.slice(0, 20) || '(no session)'}`);
+            // Always tell the board what was heard, even when it is empty or
+            // unroutable — a device that shows nothing is indistinguishable
+            // from a broken mic.
+            let delivered = false;
+            let via;
+            let deliverReason;
+            if (text && sessionId) {
+                if (sessionId.startsWith('observed:')) {
+                    // Any observed agent (claude, codex, …): type the dictated line
+                    // into the terminal that owns the session. session_command only
+                    // knew how to route observed *Claude*, so a Codex target was
+                    // silently dropped — the board said "sent" and nothing arrived.
+                    const obs = passiveSessionObserver.collect([])
+                        .find((s) => s.id === sessionId);
+                    const r = await injectObservedText({ tty: obs?.tty, appName: obs?.appName }, text);
+                    delivered = r.ok;
+                    via = r.via;
+                    deliverReason = r.reason;
+                }
+                else {
+                    handleDeviceCommand({
+                        type: 'session_command',
+                        sessionId,
+                        command: { type: 'send_prompt', text },
+                    });
+                    delivered = true;
+                    via = 'session-bridge';
+                }
+                // Only a delivered prompt earns a spoken reply: arming on a
+                // dropped one would read out whatever that session happened to
+                // answer someone else.
+                const armed = delivered ? voiceReply.arm(sink, sessionId) : false;
+                // Logged at info level rather than debug: these are rare,
+                // user-initiated events, and the silence made "the board said sent
+                // but nothing happened" undiagnosable without a rebuild.
+                log(`[agentdeck] voice: "${text.slice(0, 40)}" -> ${sessionId.slice(0, 32)}`
+                    + ` delivered=${delivered}${via ? ` via ${via}` : ''}`
+                    + `${deliverReason ? ` (${deliverReason})` : ''}`
+                    + ` spokenReply=${armed ? `armed(${sink.describe()})` : 'no'}`
+                    + ` [${sink.describe()} key=${sink.deviceKey()}`
+                    + ` caps=${sink.capabilities().join('|') || 'none'}]`);
+            }
+            try {
+                sink.send(JSON.stringify({
+                    type: 'voice_result', text, sessionId, delivered,
+                    ...(via ? { via } : {}),
+                    ...(deliverReason ? { deliverReason } : {}),
+                }));
+            }
+            catch { /* client disconnecting */ }
+        }
+        catch (err) {
+            const reason = String(err).slice(0, 160);
+            debug('voice', `transcription failed: ${reason}`);
+            try {
+                sink.send(JSON.stringify({ type: 'voice_result', text: '', error: reason }));
+            }
+            catch { /* client disconnecting */ }
+        }
+        finally {
+            captured.cleanup();
+        }
+    };
+    /**
+     * Finish one captured photo: build the prompt that points the target session
+     * at the saved file, deliver it through the same ladder as dictated text
+     * (observed → terminal injection, managed → send_prompt), and tell the board
+     * what happened. Shared by the WS and serial paths for the same reason as
+     * finishVoiceCapture: one implementation or the transports drift.
+     */
+    const finishPhotoCapture = async (captured, sink) => {
+        try {
+            // The strip aims at its own focus pick; when it sends none, fall back to
+            // the daemon's explicitly focused session rather than dropping the shot.
+            let sessionId = resolveDeviceSessionId(captured.sessionId);
+            if (!sessionId && userFocusedSessionId)
+                sessionId = userFocusedSessionId;
+            const photoCfg = loadDaemonSettings().photo;
+            const template = typeof photoCfg?.promptTemplate === 'string'
+                && photoCfg.promptTemplate.includes('{path}')
+                ? photoCfg.promptTemplate
+                : 'Look at the photo I just captured for you on the AgentDeck device and respond: {path}';
+            const text = template.replace('{path}', captured.path);
+            let delivered = false;
+            let via;
+            let deliverReason;
+            if (sessionId) {
+                if (sessionId.startsWith('observed:')) {
+                    // Any observed agent: type the prompt into the terminal that owns the
+                    // session — the same ladder dictated text uses.
+                    const obs = passiveSessionObserver.collect([])
+                        .find((s) => s.id === sessionId);
+                    const r = await injectObservedText({ tty: obs?.tty, appName: obs?.appName }, text);
+                    delivered = r.ok;
+                    via = r.via;
+                    deliverReason = r.reason;
+                }
+                else {
+                    handleDeviceCommand({
+                        type: 'session_command',
+                        sessionId,
+                        command: { type: 'send_prompt', text },
+                    });
+                    delivered = true;
+                    via = 'session-bridge';
+                }
+            }
+            else {
+                deliverReason = 'no_target_session';
+            }
+            // Info level, like voice: rare user-initiated events whose silence made
+            // "the board said sent but nothing happened" undiagnosable.
+            log(`[agentdeck] photo: ${captured.bytes}B -> ${sessionId.slice(0, 32) || '(no session)'}`
+                + ` delivered=${delivered}${via ? ` via ${via}` : ''}`
+                + `${deliverReason ? ` (${deliverReason})` : ''} [${captured.path}]`);
+            try {
+                sink.send(JSON.stringify({
+                    type: 'photo_result', delivered, sessionId, bytes: captured.bytes,
+                    ...(via ? { via } : {}),
+                    ...(deliverReason ? { deliverReason } : {}),
+                }));
+            }
+            catch { /* client disconnecting */ }
+        }
+        catch (err) {
+            const reason = String(err).slice(0, 160);
+            debug('photo', `delivery failed: ${reason}`);
+            try {
+                sink.send(JSON.stringify({ type: 'photo_result', delivered: false, error: reason }));
+            }
+            catch { /* client disconnecting */ }
+        }
+    };
+    core.wsServer.onBinary((data, sender) => {
+        // A connection holds an open voice utterance OR an open photo, never both
+        // (protocol contract) — offer the unenveloped frame to each in turn.
+        if (deviceVoice.append(sender, data))
+            return;
+        if (devicePhoto.append(sender, data))
+            return;
+        debug('voice', `binary frame with no open utterance/capture (${data.length} bytes) — ignored`);
     });
+    setInterval(() => {
+        deviceVoice.sweep();
+        for (const conn of devicePhoto.sweep()) {
+            // Tell the board its capture died (lost photo_end): the strip otherwise
+            // has no way to distinguish "delivered" from "evaporated in transit".
+            try {
+                const sink = typeof conn === 'string' ? serialSinkFor(conn) : stableSink(conn);
+                sink.send(JSON.stringify({ type: 'photo_result', delivered: false, error: 'capture_timeout' }));
+            }
+            catch { /* transport gone too */ }
+        }
+        // Keep armings alive while their session is still working: a dictated
+        // question that starts a long task must still get its answer read out when
+        // the task finally finishes, and the TTL alone would have expired first.
+        void core.buildSessionsSnapshot().then((sessions) => {
+            voiceReply.refresh(sessions
+                .filter((s) => s.state === 'processing' || s.state === 'awaiting_input')
+                .map((s) => String(s.id)));
+        }).catch(() => { });
+        voiceReply.sweep();
+        for (const ws of sinkByWs.keys()) {
+            if (ws.readyState !== WebSocket.OPEN)
+                sinkByWs.delete(ws);
+        }
+        for (const ws of wsSelfBoard.keys()) {
+            if (ws.readyState === WebSocket.CLOSED) {
+                wsSelfBoard.delete(ws);
+                wsSelfCaps.delete(ws);
+            }
+        }
+    }, 30_000).unref?.();
+    core.wsServer.onCommand(handleDeviceCommand);
+    // Idle display-only boards send no messages — their protocol pongs are the
+    // only liveness signal. Without this, every healthy quiet XTeink read as
+    // "stale" in /devices and the roster aged it toward eviction.
+    core.wsServer.onPong((ws) => touchWifiEsp32Socket(ws));
+    // Serial-attached boards get the SAME command pipeline: their steering taps
+    // arrive over USB when WiFi is parked (serial-primary), and used to be
+    // silently dropped by the device_info-only serial parser.
+    setSerialCommandSink((c) => handleDeviceCommand(c));
     // ===== Client connect =====
     core.wsServer.onClientConnect((ws) => {
         const gwAlive = gatewayAdapter?.isAlive() ?? false;