@agentdeck/bridge 1.0.24 → 1.1.0

package/dist/daemon-server.js

@@ -19,6 +19,7 @@ import { SERIAL_FORWARDED_EVENTS } from '@agentdeck/shared/protocol';
 import { prepareForSerial } from './esp32-serial.js';
 import { OpenClawAdapter } from './adapters/openclaw.js';
 import { BridgeLogStream } from './log-stream.js';
+import { distBuildId } from './daemon-build-identity.js';
 import { PassiveSessionObserver } from './passive-observer.js';
 import { SessionTimelineRelay } from './session-timeline-relay.js';
 import { SessionFocusRelay } from './session-focus-relay.js';
@@ -72,7 +73,7 @@ const ASK_GATE_HOLD_MS = Math.min(50_000, Math.max(5_000, Number(process.env.AGE
 const APME_ABANDONED_RUN_STALE_SEC = Math.max(600, Number(process.env.AGENTDECK_APME_ABANDON_SEC) || 7200);
 import { VoiceManager } from './voice.js';
 import { VoiceAssistantManager } from './voice-assistant.js';
-import { listActive as listActiveSessions, findAvailablePort, findExistingDaemon, probeDaemonHealth, requestDaemonShutdown, scanDaemonPortWindow, shouldConcedePortToOccupant, waitForDaemonExit, waitForPortBindable, writeDaemonInfo, ensureDaemonInfo, removeDaemonInfo, readDaemonInfo, removeDaemonSession, getCandidateDataDirs, getOwnTimelineFile, } from './session-registry.js';
+import { listActive as listActiveSessions, findAvailablePort, findExistingDaemon, probeDaemonHealth, requestDaemonShutdown, scanDaemonPortWindow, shouldConcedePortToOccupant, waitForDaemonExit, waitForPortBindable, writeDaemonInfo, ensureDaemonInfo, removeDaemonInfo, readDaemonInfo, removeDaemonSession, getCandidateDataDirs, getDataDir, getOwnTimelineFile, } from './session-registry.js';
 import { isForeignDaemon } from './daemon-takeover.js';
 import { loadDaemonSettings } from './daemon-settings.js';
 import { resolveDaemonPort, describeDaemonPortSource, PREFERRED_PORT_RECLAIM_MS, } from './daemon-port.js';
@@ -86,6 +87,7 @@ import { handlePixooWake } from './pixoo/pixoo-client.js';
 import { triggerMdnsRecovery } from './mdns.js';
 import { rgbToBmp, pixooLiveHtml } from './hook-server.js';
 import { enableDebugLog, debug, debugThrottled } from './logger.js';
+import { LegacyRearmLedger } from './legacy-rearm-ledger.js';
 import { CodexOtelTracker, CODEX_OTEL_TRACES_PATH, spanNameSummary } from './codex-otel.js';
 import { HookCodexSessions } from './hook-codex-sessions.js';
 import { ObservedTurnWatchdogs } from './observed-turn-watchdogs.js';
@@ -96,6 +98,7 @@ import { readModelFromTranscript } from './apme/claude-transcript-reader.js';
 import { transcriptTimelineForSession, lastAssistantTextFromTranscript, lastAssistantTextForSession, } from './session-transcript-timeline.js';
 import { kiroTimelineForSession } from './kiro-transcript-timeline.js';
 import { KiroTimelineFeed } from './kiro-timeline-feed.js';
+import { OpenClawTimelineFeed, OPENCLAW_FEED_INTERVAL_MS } from './openclaw-timeline-feed.js';
 import { DeviceVoiceReplyRouter, speakableReply, spokenDigest, pcmFromWav, } from './device-voice-reply.js';
 import { rawSessionId } from '@agentdeck/shared';
 import { codexTurnOutcomeFromRollout, lastAgentMessageFromCodexRollout } from './codex-rollout-response.js';
@@ -110,17 +113,18 @@ 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, OPENCLAW_SESSION_ID } from './openclaw-session.js';
-import { buildCardFeed, buildGlance, applyOutboxDecisions, FeedPullTracker, formatFeedPull, normalizeClientIp, parsePullTelemetry, } from './card-feed.js';
+import { buildCardFeed, buildGlance, projectPortableReaderGlance, applyOutboxDecisions, FeedPullTracker, formatFeedPull, applyPullOtaBootstrap, OutboxIdempotencyLedger, normalizeClientIp, parsePullTelemetry, } from './card-feed.js';
 import { threadModule } from './card-modules.js';
 import { AutonomousPocketEngine, createAutonomousPocketModules, parsePocketAutonomyConfig, } from './pocket-autonomy.js';
 import { WeatherProvider, parseWeatherSettings } from './weather.js';
 import { CalendarProvider, parseCalendarSettings } from './calendar.js';
 import { renderGlanceFrame, GLANCE_FRAME_BOARDS } from './glance-frame.js';
-import { mergeRelayedSessionUsage } from './usage-event.js';
+import { isPortableReaderProfile, negotiateSurface, parseHttpSurfaceIdentity, pullOtaResponseStatus, surfaceErrorBody, surfaceAllowsEvent, SurfaceProtocolError, validateSurfaceOtaIdentity, validateSurfaceQueryTuple, usesPortableReaderProjection, } from './surface-protocol.js';
+import { resolveRelayedUsageEvent } from './relayed-usage.js';
 import { CARD_FEED_PATH, CARD_OUTBOX_PATH, GLANCE_FRAME_PATH } from '@agentdeck/shared';
 import { readFileSync, statSync, writeFileSync, appendFileSync } from 'fs';
 import { readFile, rm } from 'fs/promises';
-import { tmpdir } from 'os';
+import { tmpdir, networkInterfaces } from 'os';
 import { join } from 'path';
 import { homedir } from 'os';
 import { OPENCLAW_CAPABILITIES, State, } from './types.js';
@@ -142,6 +146,7 @@ const wifiEsp32Sockets = new Map();
  *  single-path dedup kept it in the registry above. */
 const wsSelfBoard = new Map();
 const wsSelfCaps = new Map();
+const surfaceNegotiations = new Map();
 const otaWaiters = new Map();
 function listWifiEsp32Devices() {
     const now = Date.now();
@@ -165,6 +170,7 @@ function listWifiEsp32Devices() {
  *  other observable — a battery client with an empty outbox never identifies
  *  itself and never opens a socket. */
 const feedPulls = new FeedPullTracker();
+const outboxIdempotency = new OutboxIdempotencyLedger();
 /** Daemon-owned personal feed. It persists aggregate bandit state only — no
  *  card copy, session names, calendar titles or weather locations. */
 const pocketAutonomy = new AutonomousPocketEngine({ onError: (message) => log(`[agentdeck] ${message}`) });
@@ -176,18 +182,123 @@ const pocketReaderModules = pocketCardModules.filter((module) => module.id !== '
 /** Glance weather for the card-feed sleep dashboard. Config is read from
  *  settings.json per pull (cheap; honors edits without a restart); the
  *  provider caches the upstream fetch itself. */
-const glanceWeather = new WeatherProvider();
+const glanceWeather = new WeatherProvider(fetch, (message) => log(`[agentdeck] ${message}`), join(getDataDir(), 'weather-cache-v1.json'));
 /** Glance schedule (today's ICS events) — same config/caching contract as
  *  weather: settings.json `calendar: {ics}`, 30 min cache, never throws. */
 const glanceCalendar = new CalendarProvider();
-const stagedFwByBoard = new Map();
-const stagedFwStatePath = () => join(homedir(), '.agentdeck', 'staged-fw.json');
+// Legacy firmware does only six GETs per awake pass, so its previous 128 KiB
+// response cap made at most 768 KiB progress before sleeping. 256 KiB was
+// measured to complete in 1–2 seconds on X3 and halves those reconnects. New
+// cooperative clients explicitly ask for a smaller `limit` when they need a
+// tighter UI-yield budget.
+const PULL_OTA_SEGMENT_BYTES = 256 * 1024;
+const PULL_OTA_MIN_SEGMENT_BYTES = 32 * 1024;
+const PULL_OTA_MAX_SEGMENT_BYTES = 512 * 1024;
+function pullOtaSegment(firmware, requestedFrom, requestedLimit) {
+    const from = Number.isFinite(requestedFrom) && requestedFrom > 0
+        ? Math.min(Math.floor(requestedFrom), firmware.length) : 0;
+    const limit = Number.isFinite(requestedLimit) && requestedLimit > 0
+        ? Math.max(PULL_OTA_MIN_SEGMENT_BYTES, Math.min(Math.floor(requestedLimit), PULL_OTA_MAX_SEGMENT_BYTES))
+        : PULL_OTA_SEGMENT_BYTES;
+    return { from, body: firmware.subarray(from, Math.min(from + limit, firmware.length)) };
+}
+/** The route above keeps dual-homed hosts on the device-side Wi-Fi interface.
+ * Once there, hand the bounded remainder to Node directly: timer-paced 1 KiB
+ * writes stretched a 1.6 MB transfer past the device's 60-second read timeout.
+ * TCP backpressure still governs the socket; res.end does not retain another
+ * firmware copy because `body` is a view over the already-loaded image. */
+function sendPullOtaBody(res, body) {
+    res.socket?.setNoDelay(true);
+    res.end(body);
+}
+function ipv4Number(address) {
+    const parts = address.split('.').map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+        return undefined;
+    return (((parts[0] << 24) >>> 0) + (parts[1] << 16) + (parts[2] << 8) + parts[3]) >>> 0;
+}
+/** Pick the host's Wi-Fi address only when it shares the device subnet. This
+ * avoids the measured Ethernet→AP return-path loss on dual-homed Macs without
+ * changing global routes or affecting non-OTA traffic. */
+function preferredPullOtaIp(remoteAddress, localAddress, interfaces = networkInterfaces()) {
+    const remote = ipv4Number(normalizeClientIp(remoteAddress));
+    const local = normalizeClientIp(localAddress);
+    if (remote === undefined)
+        return undefined;
+    const candidates = [];
+    for (const [name, entries] of Object.entries(interfaces)) {
+        for (const entry of entries ?? []) {
+            if (entry.internal || entry.family !== 'IPv4')
+                continue;
+            const address = ipv4Number(entry.address);
+            const mask = ipv4Number(entry.netmask);
+            if (address === undefined || mask === undefined || (address & mask) !== (remote & mask))
+                continue;
+            candidates.push({ name, address: entry.address });
+        }
+    }
+    if (candidates.length < 2)
+        return undefined;
+    candidates.sort((a, b) => {
+        const wireless = (name) => /^(en1|wlan)|wi-?fi/i.test(name) ? 0 : 1;
+        return wireless(a.name) - wireless(b.name) || a.name.localeCompare(b.name);
+    });
+    const preferred = candidates[0]?.address;
+    return preferred && preferred !== local ? preferred : undefined;
+}
+const legacyStagedFwByBoard = new Map();
+const stagedFwByIdentity = new Map();
+const stagedFwStatePath = () => join(getDataDir(), 'staged-fw.json');
+function otaIdentityKey(identity) {
+    return JSON.stringify([identity.productId, identity.board, identity.updateChannel]);
+}
+/** Read the NUL-terminated build identity already present in Pocket images.
+ * This avoids inventing another manifest field and also repairs older persisted
+ * stages that predate firmwareVersion. */
+function embeddedFirmwareVersion(firmware) {
+    const marker = Buffer.from('CrossPoint version: ', 'ascii');
+    const start = firmware.indexOf(marker);
+    if (start < 0)
+        return undefined;
+    const valueStart = start + marker.length;
+    let end = valueStart;
+    while (end < firmware.length && end - valueStart < 96) {
+        const byte = firmware[end];
+        if (byte === 0 || byte === 0x0a || byte === 0x0d)
+            break;
+        if (byte < 0x20 || byte > 0x7e)
+            return undefined;
+        end++;
+    }
+    if (end === valueStart || end - valueStart >= 96)
+        return undefined;
+    return firmware.subarray(valueStart, end).toString('ascii');
+}
 function loadStagedFw() {
     try {
         const raw = JSON.parse(readFileSync(stagedFwStatePath(), 'utf8'));
+        if ('version' in raw && raw.version === 2 && Array.isArray(raw.identities)) {
+            for (const candidate of raw.identities) {
+                try {
+                    const identity = validateSurfaceOtaIdentity(candidate);
+                    if (typeof candidate.firmwarePath === 'string' && typeof candidate.md5 === 'string' && typeof candidate.size === 'number') {
+                        stagedFwByIdentity.set(otaIdentityKey(identity), { ...candidate, ...identity });
+                    }
+                }
+                catch { /* invalid/stale registration: do not widen its namespace */ }
+            }
+            for (const [board, s] of Object.entries(raw.legacy ?? {})) {
+                if (s && typeof s.firmwarePath === 'string' && typeof s.md5 === 'string' && typeof s.size === 'number') {
+                    legacyStagedFwByBoard.set(board, s);
+                }
+            }
+            return;
+        }
+        // Version 1 was a board-keyed object. Preserve it only in the legacy
+        // namespace; product-aware requests must never inherit those images.
         for (const [board, s] of Object.entries(raw)) {
             if (s && typeof s.firmwarePath === 'string' && typeof s.md5 === 'string' && typeof s.size === 'number') {
-                stagedFwByBoard.set(board, s);
+                legacyStagedFwByBoard.set(board, s);
             }
         }
     }
@@ -196,7 +307,12 @@ function loadStagedFw() {
 loadStagedFw();
 function saveStagedFw() {
     try {
-        writeFileSync(stagedFwStatePath(), JSON.stringify(Object.fromEntries(stagedFwByBoard), null, 2));
+        const state = {
+            version: 2,
+            identities: [...stagedFwByIdentity.values()],
+            legacy: Object.fromEntries(legacyStagedFwByBoard),
+        };
+        writeFileSync(stagedFwStatePath(), JSON.stringify(state, null, 2));
     }
     catch (err) {
         log(`[agentdeck] staged-fw persist failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -227,9 +343,9 @@ function resolveStagedFwBoard(target) {
     const puller = feedPulls.clients().find((c) => c.client === target || c.board === target);
     return puller?.board ?? target;
 }
-/** Stage a build for a board. Reads the file once to fingerprint it; the file
- *  itself is re-read at device download time (a rebuild at the same path is
- *  re-fingerprinted by re-staging).
+/** Stage a build for a board. Reads the file once to fingerprint it. The Feed
+ *  advert path re-fingerprints a rebuild at the same path before advertising,
+ *  and the download path re-reads the bytes that are actually served.
  *
  *  `pullSeen` reports whether this daemon has actually observed a feed pull
  *  from the board, because "staged" proves neither transfer nor install and a
@@ -237,33 +353,68 @@ function resolveStagedFwBoard(target) {
  *  image; a board that holds a live WS never asks, so its stage sits forever
  *  while the CLI says it is handled. It is daemon-lifetime state, so `false`
  *  means "not seen since this daemon started" — not "cannot pull". */
-function stageEsp32Fw(target, firmwarePath) {
+function stageEsp32Fw(target, firmwarePath, offeredIdentity) {
     const board = resolveStagedFwBoard(target);
+    const identity = offeredIdentity ? validateSurfaceOtaIdentity(offeredIdentity) : undefined;
+    if (identity && identity.board !== board) {
+        throw new SurfaceProtocolError(409, 'surface_stage_target_mismatch', 'Stage target does not match OTA identity board');
+    }
     const firmware = readFileSync(firmwarePath);
     const md5 = createHash('md5').update(firmware).digest('hex');
-    stagedFwByBoard.set(board, { firmwarePath, md5, size: firmware.length, stagedAt: Date.now() });
+    const staged = {
+        firmwarePath,
+        md5,
+        size: firmware.length,
+        stagedAt: Date.now(),
+        firmwareVersion: embeddedFirmwareVersion(firmware),
+    };
+    if (identity)
+        stagedFwByIdentity.set(otaIdentityKey(identity), { ...staged, ...identity });
+    else
+        legacyStagedFwByBoard.set(board, staged);
     saveStagedFw();
-    const pullSeen = feedPulls.clients().some((c) => c.board === board);
-    log(`[agentdeck] staged firmware for ${board}: ${firmware.length} bytes md5=${md5} — ${pullSeen ? 'installs on its next feed pull' : 'NO feed pull seen from this board since daemon start'}`);
-    return { board, bytes: firmware.length, md5, pullSeen };
+    const pullSeen = feedPulls.clients().some((c) => c.board === board
+        && (!identity || c.productId === identity.productId));
+    const namespace = identity ? `${identity.productId}/${board}/${identity.updateChannel}` : `legacy/${board}`;
+    log(`[agentdeck] staged firmware for ${namespace}: ${firmware.length} bytes md5=${md5} — ${pullSeen ? 'installs on its next feed pull' : 'NO feed pull seen from this board since daemon start'}`);
+    return { board, bytes: firmware.length, md5, pullSeen,
+        ...(identity ? { productId: identity.productId, updateChannel: identity.updateChannel } : {}) };
 }
 /** The staged advert for a feed response, re-validated against the file on
  *  disk so a rebuilt-in-place binary never adverts a stale md5. */
-function stagedFwAdvert(board) {
+function stagedFwAdvert(board, identity, clientVersion) {
     if (!board)
         return undefined;
-    const staged = stagedFwByBoard.get(board);
+    const validatedIdentity = identity ? validateSurfaceOtaIdentity(identity) : undefined;
+    const staged = validatedIdentity
+        ? stagedFwByIdentity.get(otaIdentityKey(validatedIdentity))
+        : legacyStagedFwByBoard.get(board);
     if (!staged)
         return undefined;
     try {
         const firmware = readFileSync(staged.firmwarePath);
         const md5 = createHash('md5').update(firmware).digest('hex');
-        if (md5 !== staged.md5 || firmware.length !== staged.size) {
-            stagedFwByBoard.set(board, { ...staged, md5, size: firmware.length });
+        const firmwareVersion = embeddedFirmwareVersion(firmware);
+        if (md5 !== staged.md5 || firmware.length !== staged.size || firmwareVersion !== staged.firmwareVersion) {
+            if (validatedIdentity)
+                stagedFwByIdentity.set(otaIdentityKey(validatedIdentity), {
+                    ...staged, ...validatedIdentity, md5, size: firmware.length, firmwareVersion,
+                });
+            else
+                legacyStagedFwByBoard.set(board, { ...staged, md5, size: firmware.length, firmwareVersion });
             saveStagedFw();
-            return { size: firmware.length, md5 };
+            return { size: firmware.length, md5, ...(validatedIdentity ?? {}) };
         }
-        return { size: staged.size, md5: staged.md5 };
+        if (clientVersion && firmwareVersion && clientVersion === firmwareVersion) {
+            if (validatedIdentity)
+                stagedFwByIdentity.delete(otaIdentityKey(validatedIdentity));
+            else
+                legacyStagedFwByBoard.delete(board);
+            saveStagedFw();
+            log(`[agentdeck] staged firmware acknowledged by ${validatedIdentity?.productId ?? 'legacy'}/${board}: v${clientVersion}`);
+            return undefined;
+        }
+        return { size: staged.size, md5: staged.md5, ...(validatedIdentity ?? {}) };
     }
     catch {
         return undefined; // file gone — advert nothing rather than a dead download
@@ -335,6 +486,11 @@ function registerWifiEsp32(d, ws) {
     const resetReasonCode = typeof d.resetReasonCode === 'number' ? d.resetReasonCode : undefined;
     wifiEsp32Devices.set(key, {
         board: typeof d.board === 'string' ? d.board : 'unknown',
+        productId: typeof d.productId === 'string' ? d.productId : undefined,
+        productName: typeof d.productName === 'string' ? d.productName : undefined,
+        surfaceProfile: typeof d.surfaceProfile === 'string' ? d.surfaceProfile : undefined,
+        surfaceProtocol: typeof d.surfaceProtocol === 'number' ? d.surfaceProtocol : undefined,
+        updateChannel: typeof d.updateChannel === 'string' ? d.updateChannel : undefined,
         version: typeof d.version === 'string' ? d.version : undefined,
         buildHash: typeof d.buildHash === 'string' ? d.buildHash : undefined,
         buildEpoch: typeof d.buildEpoch === 'number' ? d.buildEpoch : undefined,
@@ -528,8 +684,12 @@ export const __wifiOtaTestApi = {
     resolveStagedFwBoard,
     stageEsp32Fw,
     stagedFwAdvert,
+    embeddedFirmwareVersion,
+    pullOtaSegment,
+    preferredPullOtaIp,
     feedPulls,
-    clearStagedFwForTest: () => { stagedFwByBoard.clear(); },
+    getStagedFw: (identity) => stagedFwByIdentity.get(otaIdentityKey(identity)),
+    clearStagedFwForTest: () => { legacyStagedFwByBoard.clear(); stagedFwByIdentity.clear(); },
 };
 async function performWifiEsp32Ota(core, target, firmwarePath) {
     const { key, device } = findWifiOtaTarget(target);
@@ -887,6 +1047,7 @@ function buildNodeModuleHealth(startedModules) {
             port: status.port,
             connected: status.connected,
             transportOpen: status.transportOpen,
+            deviceInfoFresh: status.deviceInfoFresh,
             deviceInfo: status.board ? {
                 board: status.board,
                 version: status.version,
@@ -905,6 +1066,7 @@ function buildNodeModuleHealth(startedModules) {
                 sessionCount: status.sessionCount,
                 usageFiveH: status.usageFiveH,
                 processingCount: status.processingCount,
+                deviceInfoFresh: status.deviceInfoFresh,
             } : null,
             lastReadAt: status.lastReadAt,
             lastWriteAt: status.lastWriteAt,
@@ -922,7 +1084,15 @@ function buildNodeModuleHealth(startedModules) {
     return modules;
 }
 // ===== startDaemon =====
+/**
+ * The build this daemon process started with — the answer `/health` gives for
+ * as long as it runs. Captured once in `startDaemon`, never refreshed: a
+ * daemon that recomputed it would start reporting the newest build on disk the
+ * moment someone rebuilt, which is precisely the state a caller asks about.
+ */
+let startupBuildId = null;
 export async function startDaemon(opts) {
+    startupBuildId = distBuildId();
     if (opts.debug) {
         enableDebugLog();
         log('[agentdeck] Debug logging enabled');
@@ -1135,6 +1305,7 @@ export async function startDaemon(opts) {
     /** Produces live timeline rows for observed Kiro sessions — see the class
      *  doc for why Kiro needs a producer when hook agents do not. */
     const kiroTimelineFeed = new KiroTimelineFeed();
+    const openclawTimelineFeed = new OpenClawTimelineFeed();
     /** Kiro has no CLI hooks, so transcript rows also feed APME. These maps are
      *  bounded by the observer's current live set and discarded on disappearance. */
     const kiroApmeSessions = new Set();
@@ -1358,6 +1529,12 @@ export async function startDaemon(opts) {
                 status: 'ok', mode: 'daemon', state: snap.state,
                 gateway: gatewayAdapter?.isAlive() ? 'connected' : 'disconnected',
                 uptime: process.uptime(), port, pid: process.pid,
+                // Which build is SERVING this port. Captured when this process started
+                // (see daemon-build-identity.ts) and never recomputed, so a rebuild
+                // underneath a running daemon reads as a mismatch instead of being
+                // absorbed — `dist/cli.js` is overwritten in place, and nothing else
+                // here distinguishes the code on disk from the code in memory.
+                build: startupBuildId,
                 pairingToken: core.authToken,
                 // Capability: this daemon drives remote sessions down their own push
                 // socket (session_focus_down / session_command_down / session_event_up).
@@ -1717,17 +1894,32 @@ export async function startDaemon(opts) {
                     throw new Error('target and firmwarePath are required');
                 }
                 // Pull-OTA staging: remember the build; the board installs it on its
-                // next feed pull (no live WS needed). See stagedFwByBoard.
+                // next feed pull (no live WS needed). Product-aware stages live in an
+                // exact productId + board + updateChannel namespace.
                 if (body.stage === true) {
-                    return { ok: true, staged: true, ...stageEsp32Fw(target, firmwarePath) };
+                    const tupleValues = [body.productId, body.board, body.updateChannel];
+                    const tuplePresent = tupleValues.filter((value) => typeof value === 'string' && value.length > 0).length;
+                    if (tuplePresent !== 0 && tuplePresent !== 3) {
+                        throw new SurfaceProtocolError(400, 'surface_stage_identity_incomplete', 'productId, board, and updateChannel are required together');
+                    }
+                    if (tuplePresent === 0 && (target === 'xteink_x3' || target === 'xteink_x4')) {
+                        throw new SurfaceProtocolError(400, 'surface_stage_identity_required', 'XTeink pull OTA requires productId, board, and updateChannel');
+                    }
+                    const identity = tuplePresent === 3 ? {
+                        productId: String(body.productId), board: String(body.board), updateChannel: String(body.updateChannel),
+                    } : undefined;
+                    return { ok: true, staged: true, ...stageEsp32Fw(target, firmwarePath, identity) };
                 }
                 return performWifiEsp32Ota(core, target, firmwarePath);
             })().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) }));
+                const status = err instanceof SurfaceProtocolError ? err.status : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(err instanceof SurfaceProtocolError
+                    ? { ok: false, ...surfaceErrorBody(err) }
+                    : { ok: false, error: err instanceof Error ? err.message : String(err) }));
             });
             return;
         }
@@ -1744,11 +1936,52 @@ export async function startDaemon(opts) {
                     return;
                 }
             }
-            const board = parsedUrl.searchParams.get('board') ?? '';
-            const staged = stagedFwByBoard.get(board);
+            let surfaceIdentity;
+            try {
+                surfaceIdentity = parseHttpSurfaceIdentity(req.headers, 'ota.feed');
+                if (surfaceIdentity)
+                    validateSurfaceQueryTuple(surfaceIdentity, parsedUrl.searchParams);
+            }
+            catch (err) {
+                if (err instanceof SurfaceProtocolError) {
+                    res.writeHead(err.status, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(surfaceErrorBody(err)));
+                    return;
+                }
+                throw err;
+            }
+            const preferredIp = preferredPullOtaIp(ip, req.socket.localAddress ?? '');
+            if (preferredIp) {
+                const port = req.socket.localPort ?? 9120;
+                const redirectBoard = surfaceIdentity?.board ?? parsedUrl.searchParams.get('board') ?? 'unknown';
+                log(`[agentdeck] pull-OTA path redirect: ${redirectBoard} (${ip}) via ${preferredIp}`);
+                res.writeHead(307, {
+                    Location: `http://${preferredIp}:${port}${parsedUrl.pathname}${parsedUrl.search}`,
+                    'Cache-Control': 'no-store',
+                });
+                res.end();
+                return;
+            }
+            const board = surfaceIdentity?.board ?? parsedUrl.searchParams.get('board') ?? '';
+            const hasProductQuery = parsedUrl.searchParams.has('productId') || parsedUrl.searchParams.has('updateChannel');
+            if (!surfaceIdentity && hasProductQuery) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'surface_identity_required', message: 'Product-aware OTA requires all Surface identity headers' }));
+                return;
+            }
+            const otaIdentity = surfaceIdentity ? {
+                productId: surfaceIdentity.productId,
+                board: surfaceIdentity.board,
+                updateChannel: surfaceIdentity.updateChannel,
+            } : undefined;
+            const staged = otaIdentity
+                ? stagedFwByIdentity.get(otaIdentityKey(otaIdentity))
+                : legacyStagedFwByBoard.get(board);
             if (!staged) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: `nothing staged for board "${board}"` }));
+                res.end(JSON.stringify({ error: 'firmware_not_staged', message: otaIdentity
+                        ? `Nothing staged for ${otaIdentity.productId}/${board}/${otaIdentity.updateChannel}`
+                        : `Nothing staged for legacy board "${board}"` }));
                 return;
             }
             try {
@@ -1760,20 +1993,30 @@ export async function startDaemon(opts) {
                 // never converge there). The device appends whatever arrives and
                 // re-asks from where it stopped, so partial transfers accumulate.
                 const fromRaw = Number(parsedUrl.searchParams.get('from') ?? 0);
-                const from = Number.isFinite(fromRaw) && fromRaw > 0 ? Math.min(Math.floor(fromRaw), firmware.length) : 0;
-                const body = from > 0 ? firmware.subarray(from) : firmware;
+                const limitRaw = parsedUrl.searchParams.has('limit')
+                    ? Number(parsedUrl.searchParams.get('limit')) : undefined;
+                const { from, body } = pullOtaSegment(firmware, fromRaw, limitRaw);
                 log(`[agentdeck] pull-OTA download: ${board} (${ip}) ← ${body.length} bytes`
                     + (from > 0 ? ` (resume from ${from}/${firmware.length})` : ''));
-                res.writeHead(from > 0 ? 206 : 200, {
+                // Early Pocket Daily builds persisted partial bodies but treated 206
+                // as an error. Keep their private `?from=` resume convergent with a
+                // 200 response; clients that explicitly negotiate ota.resume-206 get
+                // the standards-shaped partial response. This is capability-gated,
+                // not version-sniffed, so independent reader implementations have an
+                // unambiguous migration path.
+                const partialStatus = pullOtaResponseStatus(from, surfaceIdentity);
+                res.writeHead(partialStatus, {
                     'Content-Type': 'application/octet-stream',
                     'Content-Length': String(body.length),
                     ...(from > 0
-                        ? { 'Content-Range': `bytes ${from}-${Math.max(from, firmware.length - 1)}/${firmware.length}` }
+                        ? { 'Content-Range': body.length > 0
+                                ? `bytes ${from}-${from + body.length - 1}/${firmware.length}`
+                                : `bytes */${firmware.length}` }
                         : {}),
                     'X-FW-MD5': staged.md5,
                     'Cache-Control': 'no-store',
                 });
-                res.end(body);
+                sendPullOtaBody(res, body);
             }
             catch (err) {
                 res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -1799,8 +2042,36 @@ export async function startDaemon(opts) {
                     return;
                 }
             }
+            let surfaceIdentity;
+            try {
+                surfaceIdentity = parseHttpSurfaceIdentity(req.headers, 'glance.read');
+                if (surfaceIdentity)
+                    validateSurfaceQueryTuple(surfaceIdentity, parsedUrl.searchParams);
+            }
+            catch (err) {
+                if (err instanceof SurfaceProtocolError) {
+                    res.writeHead(err.status, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(surfaceErrorBody(err)));
+                    return;
+                }
+                throw err;
+            }
+            if (surfaceIdentity) {
+                const preferredIp = preferredPullOtaIp(ip, req.socket.localAddress ?? '');
+                if (preferredIp) {
+                    const port = req.socket.localPort ?? 9120;
+                    log(`[agentdeck] Surface path redirect: glance-frame ${surfaceIdentity.board} (${ip}) via ${preferredIp}`);
+                    res.writeHead(307, {
+                        Location: `http://${preferredIp}:${port}${parsedUrl.pathname}${parsedUrl.search}`,
+                        'Cache-Control': 'no-store',
+                        'Connection': 'close',
+                    });
+                    res.end();
+                    return;
+                }
+            }
             (async () => {
-                const board = parsedUrl.searchParams.get('board') ?? 'xteink_x3';
+                const board = surfaceIdentity?.board ?? parsedUrl.searchParams.get('board') ?? 'xteink_x3';
                 const preset = GLANCE_FRAME_BOARDS[board];
                 const w = Number(parsedUrl.searchParams.get('w'));
                 const h = Number(parsedUrl.searchParams.get('h'));
@@ -1854,6 +2125,39 @@ export async function startDaemon(opts) {
                     return;
                 }
             }
+            let surfaceIdentity;
+            try {
+                surfaceIdentity = parseHttpSurfaceIdentity(req.headers, req.method === 'GET' ? 'feed.pull' : 'outbox.push');
+                if (surfaceIdentity)
+                    validateSurfaceQueryTuple(surfaceIdentity, parsedUrl.searchParams);
+            }
+            catch (err) {
+                if (err instanceof SurfaceProtocolError) {
+                    res.writeHead(err.status, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(surfaceErrorBody(err)));
+                    return;
+                }
+                throw err;
+            }
+            // Redirect bodyless Feed GETs only. Pocket builds predating the explicit
+            // POST replay support cannot follow a 307 Outbox response and stall the
+            // whole Sync before Feed/OTA. Outbox is tiny and idempotency-keyed, so
+            // serving it on the accepted local interface is both compatible and
+            // safe; current clients still learn/promote the Wi-Fi origin from Feed.
+            if (surfaceIdentity && req.method === 'GET') {
+                const preferredIp = preferredPullOtaIp(ip, req.socket.localAddress ?? '');
+                if (preferredIp) {
+                    const port = req.socket.localPort ?? 9120;
+                    log(`[agentdeck] Surface path redirect: ${pathname.slice(1)} ${surfaceIdentity.board} (${ip}) via ${preferredIp}`);
+                    res.writeHead(307, {
+                        Location: `http://${preferredIp}:${port}${parsedUrl.pathname}${parsedUrl.search}`,
+                        'Cache-Control': 'no-store',
+                        'Connection': 'close',
+                    });
+                    res.end();
+                    return;
+                }
+            }
             (async () => {
                 if (req.method === 'GET') {
                     const sessions = await core.buildSessionsSnapshot();
@@ -1869,45 +2173,68 @@ export async function startDaemon(opts) {
                         events: await glanceCalendar.get(parseCalendarSettings(settings)),
                     });
                     const now = Date.now();
-                    const pocketReader = parsedUrl.searchParams.get('surface') === 'pocket-reader';
+                    const pocketReader = usesPortableReaderProjection(surfaceIdentity, parsedUrl.searchParams);
+                    const includeWeatherOutlook = surfaceIdentity?.capabilities.includes('weather.snapshot.read') === true;
+                    const feedGlance = pocketReader ? projectPortableReaderGlance(glance, includeWeatherOutlook) : glance;
                     const feed = buildCardFeed(sessions, now, pocketReader ? pocketReaderModules : pocketCardModules, {
-                        glance,
+                        glance: feedGlance,
                         echoSig: parsedUrl.searchParams.get('sig') ?? undefined,
                         includeSessions: !pocketReader,
                     });
                     // Pull-OTA advert: rides full AND `unchanged` responses, so a
                     // sleeping board learns about a staged build on any pull. Board
                     // identity from the query (newer firmware) or the IP memory.
-                    const pullBoard = parsedUrl.searchParams.get('board') ?? boardForClientIp(ip);
-                    if (!feed.unchanged)
-                        pocketAutonomy.observeDelivery(feed.cards, now, pullBoard ?? undefined);
-                    const fwAdvert = stagedFwAdvert(pullBoard ?? undefined);
+                    const pullBoard = surfaceIdentity?.board ?? parsedUrl.searchParams.get('board') ?? boardForClientIp(ip);
+                    const otaIdentity = surfaceIdentity ? {
+                        productId: surfaceIdentity.productId,
+                        board: surfaceIdentity.board,
+                        updateChannel: surfaceIdentity.updateChannel,
+                    } : undefined;
+                    const fwAdvert = stagedFwAdvert(pullBoard ?? undefined, otaIdentity, surfaceIdentity?.clientVersion);
                     if (fwAdvert)
                         feed.fw = fwAdvert;
+                    const telemetry = parsePullTelemetry(parsedUrl.searchParams);
+                    if (applyPullOtaBootstrap(feed, fwAdvert !== undefined)) {
+                        // Do not make a weak-link X3 receive and parse a full content deck
+                        // before it can discover the resumable image. `unchanged` tells it
+                        // to retain the durable cards already on SD; after the update its
+                        // next ordinary pull receives the complete current deck.
+                        log(`[agentdeck] OTA-first Feed bootstrap: ${pullBoard ?? 'unknown'} (${ip})${telemetry.rssiDbm !== undefined ? ` rssi ${telemetry.rssiDbm}dBm` : ''}`);
+                    }
+                    if (!feed.unchanged)
+                        pocketAutonomy.observeDelivery(feed.cards, now, pullBoard ?? undefined);
                     // 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));
+                    feedPulls.noteBoard(ip, pullBoard);
+                    if (surfaceIdentity)
+                        feedPulls.noteIdentity(ip, surfaceIdentity);
                     log(`[agentdeck] ${formatFeedPull(feedPulls.record(ip, {
                         cards: feed.cards.length,
                         nextPullSec: feed.nextPullSec,
                         unchanged: feed.unchanged === true,
-                        telemetry: parsePullTelemetry(parsedUrl.searchParams),
+                        telemetry,
                     }))}`);
                     return feed;
                 }
                 const body = await readJsonBody(req);
                 const board = typeof body.board === 'string' ? body.board : 'unknown';
+                if (surfaceIdentity && board !== surfaceIdentity.board) {
+                    throw new SurfaceProtocolError(409, 'surface_outbox_board_mismatch', 'Outbox board does not match Surface identity');
+                }
                 // 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);
+                if (surfaceIdentity)
+                    feedPulls.noteIdentity(ip, surfaceIdentity);
                 const sessions = await core.buildSessionsSnapshot();
                 const result = applyOutboxDecisions(body, {
                     sessions: sessions,
                     isPendingRequest,
                     dispatch: (cmd) => handleDeviceCommand(cmd),
                     modules: pocketCardModules,
+                    idempotency: outboxIdempotency,
                 });
                 const applied = result.results.filter((r) => r.status === 'applied').length;
                 if (result.results.length > 0) {
@@ -1915,11 +2242,26 @@ export async function startDaemon(opts) {
                 }
                 return result;
             })().then((payload) => {
-                res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
-                res.end(JSON.stringify(payload));
+                const body = JSON.stringify(payload);
+                // A fixed length lets esp_http_client prove completion without relying
+                // on a keep-alive chunk terminator. This is especially important when
+                // the daemon host has Ethernet and Wi-Fi on the same LAN: the request
+                // may arrive while a later return segment is lost on the competing
+                // route. Portable-reader projection above normally keeps this body in
+                // one TCP payload; Content-Length makes any short read fail explicitly.
+                res.writeHead(200, {
+                    'Content-Type': 'application/json',
+                    'Content-Length': String(Buffer.byteLength(body)),
+                    'Cache-Control': 'no-store',
+                    'Connection': 'close',
+                });
+                res.end(body);
             }).catch((err) => {
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+                const status = err instanceof SurfaceProtocolError ? err.status : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(err instanceof SurfaceProtocolError
+                    ? surfaceErrorBody(err)
+                    : { error: err instanceof Error ? err.message : String(err) }));
             });
             return;
         }
@@ -3026,6 +3368,15 @@ export async function startDaemon(opts) {
         'device_info_request',
     ]);
     core.wsServer.setEventTransformer((event, client) => {
+        const surface = surfaceNegotiations.get(client);
+        if (surface && isPortableReaderProfile(surface.profile)) {
+            // portable-reader/v1 is pull-first. A negotiated socket gets only its
+            // acknowledgement and bounded liveness/device probes; it never inherits
+            // the daemon's private dashboard state burst or command plane.
+            if (!surfaceAllowsEvent(surface.profile, event.type))
+                return null;
+            return event;
+        }
         if (!core.wsServer.isEsp32Client(client))
             return event;
         if (!esp32WifiEvents.has(event.type))
@@ -3240,7 +3591,6 @@ export async function startDaemon(opts) {
         else if (evt.type === 'usage_update') {
             // Sync daemon cache with relay's already-adjusted values (prevents oscillation)
             const u = evt;
-            const hasClaudeData = u.fiveHourPercent != null || u.sevenDayPercent != null;
             if (core.cachedApiUsage && u.fiveHourPercent != null) {
                 core.cachedApiUsage.fiveHourPercent = u.fiveHourPercent;
                 core.cachedApiUsage.fiveHourResetsAt = u.fiveHourResetsAt ?? null;
@@ -3253,43 +3603,15 @@ export async function startDaemon(opts) {
                 core.cachedApiUsage.scopedLimits = Array.isArray(u.scopedLimits) ? u.scopedLimits : [];
                 core.apiUsagePreAdjusted = true;
             }
-            // A session bridge broadcasts usage on EVERY state change. In daemon-first
-            // mode its snapshot usually has no model context, so the Claude quota model
-            // gate (isClaudeSubscriptionModel) yields no percents and the event carries
-            // usageStale=true. Forwarding that bare event verbatim clobbered the daemon's
-            // own authoritative aggregate on the dashboard: the Claude gauge blanked to
-            // "No usage data" on every state tick (the Codex gauge, which ignores global
-            // staleness, stayed put — hence the Claude-only flicker).
-            //
-            // Suppressing the relay instead is NOT an option: usage_update is the ONLY
-            // carrier of per-session tokens / cost / duration (state_update has none of
-            // those fields), and the daemon's own buildUsage() reads a UsageTracker that
-            // no PTY ever feeds, so its session half is zeros. Dropping the event would
-            // blank the session numbers for every focus that legitimately carries no
-            // Claude quota — Codex, OpenCode, API billing.
-            //
-            // So split the event by half instead of by event: the ACCOUNT half (quota,
-            // scoped caps, extra usage, subscriptions, Codex/Ollama, usageStale) comes
-            // from the daemon's authoritative aggregate, the SESSION half from the relay.
-            //
-            // That split applies on the `else` branch ONLY. When the relay carries
-            // Claude percentages its event goes out verbatim, so the account half —
-            // `codexRateLimits` included — is the BRIDGE's. Usually identical: both
-            // sides run the same plan-aware rollout read. They can differ only when no
-            // plan-matching rollout exists at all, since the daemon additionally holds
-            // a `codex app-server` reading that a session bridge structurally cannot
-            // (no host processes there) — then successive events alternate between a
-            // real Codex window and a voided one. Left as is deliberately: the only
-            // targeted fix is to overwrite the block from `core.buildUsage()` here, and
-            // that is the call which arms the throttled spawn, on the one path whose
-            // whole history is about not clobbering the dashboard. Tracked as issue
-            // #253, not just as this comment.
-            if (hasClaudeData) {
-                core.wsServer.broadcast(evt);
-            }
-            else {
-                core.wsServer.broadcast(mergeRelayedSessionUsage(core.buildUsage(), u));
-            }
+            // WHICH half of the relayed event survives, and why, lives in
+            // `resolveRelayedUsageEvent`. It was inlined here until issue #253: this is
+            // the daemon's most flicker-sensitive path, its whole history is about not
+            // clobbering the dashboard, and an inline branch had no test seam.
+            core.wsServer.broadcast(resolveRelayedUsageEvent({
+                relayed: u,
+                ownCodexRateLimits: core.lastBuiltCodexRateLimits,
+                buildOwnUsage: () => core.buildUsage(),
+            }));
         }
         else {
             // prompt_options — relay as-is
@@ -3443,6 +3765,9 @@ export async function startDaemon(opts) {
         // fires once per board per token, only after the silence, and only when the
         // user has auto-provisioning on (it carries their WiFi credentials).
         const legacyRearmTimers = new Map();
+        // Bounds the fallback to once per board per token. The rule and the
+        // measurement that forced it live in the module.
+        const legacyRearm = new LegacyRearmLedger();
         const cancelLegacyRearm = (portPath) => {
             const timer = legacyRearmTimers.get(portPath);
             if (!timer)
@@ -3468,11 +3793,20 @@ export async function startDaemon(opts) {
                 if (armed.length > 0)
                     log(`[agentdeck] Pairing token armed on ${armed.length} ESP32 device(s) after ${portPath}`);
                 if (wifiConfig?.autoProvision) {
+                    const currentToken = getOrCreateToken();
                     for (const armedPort of armed) {
                         if (legacyRearmTimers.has(armedPort))
                             continue;
+                        if (!legacyRearm.needsRearm(armedPort, currentToken))
+                            continue;
                         const timer = setTimeout(() => {
                             legacyRearmTimers.delete(armedPort);
+                            // Record BEFORE the send: a write that fails is still an attempt
+                            // this token made, and retrying it on the next device_info is the
+                            // loop this map exists to end. A board that stays unreachable is
+                            // re-armed again when the token next changes, or when the daemon
+                            // restarts — both of which are real events, unlike a 30s poll.
+                            legacyRearm.markRearmed(armedPort, currentToken);
                             const sent = sendWifiProvision(armedPort, {
                                 type: 'wifi_provision',
                                 ssid: wifiConfig.ssid,
@@ -3491,7 +3825,11 @@ export async function startDaemon(opts) {
                 }
             }
             else if (msg.type === 'auth_provision_ack') {
+                // The board understood `auth_provision`, so the legacy WiFi re-provision
+                // is not needed for it at all. Mark the current token as handled so a
+                // later device_info cannot schedule one behind the cancelled timer.
                 cancelLegacyRearm(portPath);
+                legacyRearm.markUnderstood(portPath, getOrCreateToken());
                 if (msg.changed)
                     log(`[agentdeck] ESP32 pairing token re-armed on ${portPath}`);
             }
@@ -3618,6 +3956,8 @@ export async function startDaemon(opts) {
         catch (err) {
             debug('daemon', `kiro timeline feed failed: ${String(err)}`);
         }
+        // NOTE: the OpenClaw transcript feed used to pump from here and must not —
+        // see `openclawFeedTimer` below for why this callback cannot drive it.
         core.maybeBroadcastSessionsList();
     };
     // OTel turn boundaries arrive in milliseconds where the observer only re-reads
@@ -3720,6 +4060,44 @@ export async function startDaemon(opts) {
     // `connectGatewayAdapter` open + `disconnectGatewayAdapter` close paths
     // can reference the same id.
     let openclawApmeSessionId = null;
+    /** Gateway session key → APME session id. One APME run per OpenClaw session
+     *  key, opened on that key's first event and closed when the link drops.
+     *
+     *  Before this map the run was scoped to the Gateway CONNECTION, so a user
+     *  chat, every cron job and every model-eval run (a suite opens a fresh key
+     *  per run) shared one run, one `model_id` and one idle-gap boundary. */
+    const openclawRunsBySessionKey = new Map();
+    /** Open (or return) the APME run for one Gateway session key.
+     *
+     *  `projectName` is the key itself rather than the bare literal "openclaw":
+     *  that literal is what made an approval raised by a model-eval harness look
+     *  like it came from a conversation the user could not find. */
+    function openclawRunForSessionKey(sessionKey) {
+        const existing = openclawRunsBySessionKey.get(sessionKey);
+        if (existing)
+            return existing;
+        if (!apme)
+            return null;
+        const sessionId = `openclaw:${sessionKey}`;
+        try {
+            apme.collector.openRun({
+                sessionId,
+                agentType: 'openclaw',
+                projectName: sessionKey,
+                // Seed with whatever the catalog last reported. Runs open lazily on a
+                // key's first event, so a run opened AFTER `model_info` fired would
+                // otherwise persist `model_id=NULL` — the defect that per-run
+                // `updateModel` was added to fix, reintroduced by the lazy open.
+                ...(gatewayModelName ? { modelId: gatewayModelName } : {}),
+            });
+        }
+        catch (err) {
+            debug('APME', `openRun for OpenClaw ${sessionKey} failed: ${String(err)}`);
+            return null;
+        }
+        openclawRunsBySessionKey.set(sessionKey, sessionId);
+        return sessionId;
+    }
     function connectGatewayAdapter() {
         if (gatewayAdapter || gatewayConnecting)
             return;
@@ -3739,6 +4117,7 @@ export async function startDaemon(opts) {
                     projectName: 'openclaw',
                 });
                 adapter.setApmeSession(openclawApmeSessionId, process.cwd());
+                adapter.setApmeRunResolver(openclawRunForSessionKey);
             }
             catch (err) {
                 debug('APME', `openRun for OpenClaw failed: ${String(err)}`);
@@ -3787,8 +4166,19 @@ export async function startDaemon(opts) {
                         const model = evt.data?.model;
                         if (model) {
                             gatewayModelName = model;
-                            if (apme && openclawApmeSessionId)
-                                apme.collector.updateModel(openclawApmeSessionId, model);
+                            // `model_info` rides the connection, not a session key — the
+                            // Gateway's `chat` frame reports no model, so this is the
+                            // catalog default rather than the model that answered any one
+                            // turn. Apply it to every open run as a FLOOR; a per-turn
+                            // `session_meta` span (which does name the model that answered)
+                            // overwrites it wherever one arrives.
+                            if (apme) {
+                                if (openclawApmeSessionId)
+                                    apme.collector.updateModel(openclawApmeSessionId, model);
+                                for (const sessionId of openclawRunsBySessionKey.values()) {
+                                    apme.collector.updateModel(sessionId, model);
+                                }
+                            }
                         }
                     }
                     break;
@@ -3841,7 +4231,14 @@ export async function startDaemon(opts) {
                         // still read as outstanding in the timeline. `updateEntryStatus`
                         // existed for exactly this and had no production caller.
                         if (enriched.type === 'tool_resolved' && enriched.approvalId) {
-                            core.bridgeTimeline.updateEntryStatus(enriched.approvalId, enriched.status === 'approved' ? 'approved' : 'denied');
+                            // Carry the resolution's own status onto the request row rather
+                            // than collapsing everything-not-approved into `denied`: an
+                            // abandoned approval (run cancelled / turn ended / expired) is a
+                            // non-decision, and flattening it here would undo the split at
+                            // the one place the two rows are reconciled.
+                            core.bridgeTimeline.updateEntryStatus(enriched.approvalId, enriched.status === 'approved' ? 'approved'
+                                : enriched.status === 'abandoned' ? 'abandoned'
+                                    : 'denied');
                         }
                     }
                     break;
@@ -3909,15 +4306,30 @@ export async function startDaemon(opts) {
         // APME: close the OpenClaw run so the collector fires its
         // session_end boundary and the run becomes eligible for the layer-2
         // judge queue.
-        if (apme && openclawApmeSessionId) {
-            try {
-                apme.collector.closeRun(openclawApmeSessionId);
+        if (apme) {
+            // Every per-session-key run, not just the connection-scoped one. A run
+            // left open is never finalized, and a task that never closes is never
+            // evaluated — the failure the abandoned-run reaper exists to clean up
+            // after, hours later and with `boundary_signal='orphaned'`.
+            for (const sessionId of openclawRunsBySessionKey.values()) {
+                try {
+                    apme.collector.closeRun(sessionId);
+                }
+                catch (err) {
+                    debug('APME', `closeRun for OpenClaw ${sessionId} failed: ${String(err)}`);
+                }
             }
-            catch (err) {
-                debug('APME', `closeRun for OpenClaw failed: ${String(err)}`);
+            openclawRunsBySessionKey.clear();
+            if (openclawApmeSessionId) {
+                try {
+                    apme.collector.closeRun(openclawApmeSessionId);
+                }
+                catch (err) {
+                    debug('APME', `closeRun for OpenClaw failed: ${String(err)}`);
+                }
             }
-            openclawApmeSessionId = null;
         }
+        openclawApmeSessionId = null;
         core.cachedGatewayConnected = false;
         core.cachedGatewayAuthStatus = 'gateway_not_found';
         core.cachedModelCatalog = null;
@@ -4009,6 +4421,28 @@ export async function startDaemon(opts) {
     // ===== Commands from WS clients =====
     // ===== Internal WS: session push channel =====
     core.wsServer.onRawMessage((msg, sender) => {
+        if (msg.type === 'client_register' && msg.surface !== undefined) {
+            try {
+                const negotiation = negotiateSurface(msg.surface);
+                surfaceNegotiations.set(sender, negotiation);
+                core.wsServer.sendTo(sender, negotiation.welcome);
+                debug('daemon', `Surface negotiated ${negotiation.profile} client=${negotiation.clientId} product=${negotiation.productId}`);
+            }
+            catch (err) {
+                if (err instanceof SurfaceProtocolError) {
+                    try {
+                        sender.send(JSON.stringify({ type: 'surface_error', ...surfaceErrorBody(err) }));
+                    }
+                    catch { /* gone */ }
+                    try {
+                        sender.close(1008, err.code.slice(0, 120));
+                    }
+                    catch { /* gone */ }
+                    return true;
+                }
+                throw err;
+            }
+        }
         // WiFi ESP32 boards announce device_info over WS on connect. Capture the
         // sender here so OTA can address the exact socket instead of broadcasting.
         if (msg.type === 'device_info') {
@@ -5414,19 +5848,33 @@ export async function startDaemon(opts) {
     setSerialCommandSink((c) => handleDeviceCommand(c));
     // ===== Client connect =====
     core.wsServer.onClientConnect((ws) => {
-        const gwAlive = gatewayAdapter?.isAlive() ?? false;
-        core.sendInitialState(ws, {
-            agentType: gwAlive ? 'openclaw' : 'daemon',
-            agentCapabilities: gwAlive ? OPENCLAW_CAPABILITIES : undefined,
-            isAlive: true, // WS client IS connected to daemon — gateway status conveyed via state_update
-        });
-        // Fetch usage on connect if stale
-        const cacheAge = Date.now() - core.lastApiFetchTime;
-        if (!core.cachedApiUsage || (core.lastApiFetchTime > 0 && cacheAge > 5 * 60 * 1000)) {
-            fetchUsageRelayed(port).then((result) => core.applyUsageResult(result));
-        }
+        // The WS class invokes this before installing its message listener. Give a
+        // Surface client one short turn to send client_register; legacy clients
+        // still receive the exact same initial payload, only 75 ms later.
+        const initialTimer = setTimeout(() => {
+            if (ws.readyState !== WebSocket.OPEN)
+                return;
+            const surface = surfaceNegotiations.get(ws);
+            const gwAlive = gatewayAdapter?.isAlive() ?? false;
+            if (surface && isPortableReaderProfile(surface.profile)) {
+                core.wsServer.sendTo(ws, { type: 'connection', status: 'connected' });
+                return;
+            }
+            core.sendInitialState(ws, {
+                agentType: gwAlive ? 'openclaw' : 'daemon',
+                agentCapabilities: gwAlive ? OPENCLAW_CAPABILITIES : undefined,
+                isAlive: true,
+            });
+            // Fetch usage on connect if stale
+            const cacheAge = Date.now() - core.lastApiFetchTime;
+            if (!core.cachedApiUsage || (core.lastApiFetchTime > 0 && cacheAge > 5 * 60 * 1000)) {
+                fetchUsageRelayed(port).then((result) => core.applyUsageResult(result));
+            }
+        }, 75);
+        initialTimer.unref?.();
     });
     core.wsServer.onClientDisconnect((ws) => {
+        surfaceNegotiations.delete(ws);
         unregisterWifiEsp32Socket(ws);
     });
     // ===== Probes & polling =====
@@ -5647,10 +6095,64 @@ export async function startDaemon(opts) {
     // socket can't leak and Claude's own prompt isn't lost forever.
     const permissionSweepTimer = setInterval(() => { sweepStalePending(60_000); }, 30_000);
     permissionSweepTimer.unref?.();
+    // OpenClaw is Gateway-observed, and that stream carries the prompt, the final
+    // response and the approvals it has to block on — never the tool calls. The
+    // only tools that ever reached the strip were the ones that happened to need
+    // approval, which is a biased sample rather than a log. This reads the
+    // transcript OpenClaw writes anyway and emits the rest.
+    //
+    // **This needs a timer of its own, and that is the whole point.** The pump
+    // originally hung off `passiveSessionObserver.onRefreshed`, which fires only
+    // when the observed PROCESS set changes (`scan()` compares `next` against the
+    // cache and calls back only on a difference). Every other transcript feed can
+    // ride that edge because its subject is in that set — a Kiro turn moves its
+    // own row's `state`/`lastActivityAt`, so Kiro activity wakes the Kiro feed.
+    // OpenClaw is reached over the Gateway WebSocket and has NO process row at
+    // all, so an OpenClaw turn moves nothing the observer can see: the feed woke
+    // only when some unrelated agent happened to start or stop, and on the first
+    // scan after boot (empty cache → populated, which always counts as a change).
+    // Measured 2026-08-23 on a live daemon: three consecutive OpenClaw turns each
+    // wrote a tool call to the store, the reader returned it, and the pump ran
+    // exactly twice — both at startup — so the timeline showed zero `tool_exec`
+    // rows. A producer must be driven by a signal its own subject can move.
+    //
+    // Gated on the SSOT presence predicate, not on the store: the rows are
+    // attributed to the virtual `openclaw-gateway` session, and that row exists
+    // only while the Gateway is authenticated. Emitting them otherwise would put
+    // activity under a session no surface is showing.
+    //
+    // Cadence matches the passive observer's own `SCAN_INTERVAL_MS`, which is the
+    // "seconds late, never instant" contract every transcript-observed agent
+    // already carries. The pump is synchronous fs work; measured against a real
+    // store it costs ~7 ms typically and ~28 ms in its worst case (the index
+    // parse plus the eight largest transcripts), so the duty cycle stays well
+    // under 1% of the interval it shares with the observer.
+    const openclawFeedTimer = setInterval(() => {
+        try {
+            if (!core.cachedGatewayConnected)
+                return;
+            const rows = openclawTimelineFeed.pump();
+            // Logged because the silent path and the broken path look identical from
+            // outside: a tick that emits nothing writes nothing, so "no rows on the
+            // strip" cannot be told from "the pump never ran" without this line. That
+            // ambiguity is exactly what hid the `onRefreshed` coupling.
+            if (rows.length > 0) {
+                debug('daemon', `openclaw-feed emitting ${rows.length} row(s)`);
+            }
+            for (const entry of rows) {
+                core.bridgeTimeline.addEntry(entry);
+            }
+        }
+        catch (err) {
+            debug('daemon', `openclaw timeline feed failed: ${String(err)}`);
+        }
+    }, OPENCLAW_FEED_INTERVAL_MS);
+    openclawFeedTimer.unref?.();
     // ===== Shutdown =====
     core.onShutdown(async () => {
         clearInterval(permissionSweepTimer);
         clearInterval(daemonInfoHealTimer);
+        clearInterval(openclawFeedTimer);
         drainAllPending();
         removeDaemonInfo();
         focusRelay.stop();
@@ -5677,6 +6179,9 @@ export async function startDaemon(opts) {
     // Trigger initial state broadcast so display hardware modules (D200H, Pixoo, Serial) get populated
     broadcastFocusedState();
     core.broadcastUsage();
-    log(`[agentdeck] Daemon running. Gateway probe active.`);
+    // Name the build in the log, once. A daemon log that does not say which build
+    // wrote it cannot answer "was this fixed before or after that restart?" —
+    // and on a dev checkout the answer changes several times a day.
+    log(`[agentdeck] Daemon running (build ${startupBuildId ?? 'unknown'}). Gateway probe active.`);
 }
 //# sourceMappingURL=daemon-server.js.map