@agentdeck/bridge 1.0.20 → 1.0.22

package/dist/daemon-server.js

@@ -28,7 +28,7 @@ import { createPushChannelHandler } from './session-push-channel.js';
 import { setAwaitingOverlay, setPermissionNotificationOverlay, setAskUserQuestionOverlay, advanceAskUserQuestionOverlay, getAskUserQuestionAnswers, clearAwaitingOverlay, clearAskUserQuestionOverlay, getAwaitingOverlay, isPermissionNotification, applyAwaitingOverlayToObserved, } from './awaiting-overlay.js';
 import { askEchoMatches, askGateDecision, askPressVerdict } from './ask-gate.js';
 import { registerPending, resolvePending, resolvePendingWithReason, sweepStalePending, drainAllPending, isPendingRequest, } from './permission-resolver.js';
-import { shouldHoldPreToolUse, beginAskGate, gateReleased, buildGateQuestion, buildAskAnswerReason, consumeStop, requestStop, clearStop, STOP_DENY_REASON, queueDirective, takeDirective, clearOnUserPrompt, clearSession as clearSteeringSession, } from './observed-steering.js';
+import { shouldHoldPreToolUse, beginAskGate, gateReleased, buildGateQuestion, buildAskAnswerReason, consumeStop, requestStop, clearStop, STOP_DENY_REASON, queueDirective, takeDirectiveForStop, 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';
@@ -72,8 +72,11 @@ 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, DAEMON_DEFAULT_PORT, probeDaemonHealth, requestDaemonShutdown, scanDaemonPortWindow, shouldConcedePortToOccupant, waitForDaemonExit, waitForPortBindable, writeDaemonInfo, ensureDaemonInfo, removeDaemonInfo, readDaemonInfo, removeDaemonSession, getCandidateDataDirs, getOwnTimelineFile, } from './session-registry.js';
-import { fetchUsageFromApi, hasOAuthToken, resetConsecutiveFailures } from './usage-api.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 { isForeignDaemon } from './daemon-takeover.js';
+import { loadDaemonSettings } from './daemon-settings.js';
+import { resolveDaemonPort, describeDaemonPortSource, PREFERRED_PORT_RECLAIM_MS, } from './daemon-port.js';
+import { fetchUsageFromApi, resetConsecutiveFailures } from './usage-api.js';
 import { getOrCreateToken, isLocalConnection, validateToken } from './auth.js';
 import { buildPublicHealth, gateHttpRequest, isAuthorizedHttpRequest } from './http-auth-gate.js';
 import { closePairingWindow, getPairingWindowStatus, openPairingWindow, pairingWindowOpen, redeemPairingCode, } from './pairing-window.js';
@@ -85,16 +88,20 @@ import { rgbToBmp, pixooLiveHtml } from './hook-server.js';
 import { enableDebugLog, debug, debugThrottled } from './logger.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';
 import { initApme, isTimelineProjectionEnabled, loadApmeConfig } from './apme/index.js';
 import { FallbackTaskTimeline } from './fallback-task-timeline.js';
 import { handleApmeRequest } from './apme/http.js';
 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 { DeviceVoiceReplyRouter, speakableReply, spokenDigest, pcmFromWav, } from './device-voice-reply.js';
 import { rawSessionId } from '@agentdeck/shared';
 import { codexTurnOutcomeFromRollout, lastAgentMessageFromCodexRollout } from './codex-rollout-response.js';
 import { callFoundationModelsHelper } from './foundation-models-helper.js';
 import { initModules, stopModules, createDefaultModules, } from './modules/index.js';
+import { bindHostFor, daemonModuleConfigs, describeDaemonPosture, resolveDaemonPosture, } from './network-posture.js';
 import { esp32ConnectionCount, getESP32DeviceInfo, onESP32Message, sendAuthProvisionToAll, sendWifiProvision, sendWifiProvisionToAll, handleESP32Wake, getESP32Ports, getSerialConnectionStatus, getSerialLastError, getSerialReachableBoards } from './esp32-serial.js';
 import { loadWifiConfig } from './wifi-config.js';
 import { getConnectedAdbDevices, hasAdb, getAdbDeviceCount } from './adb-reverse.js';
@@ -194,16 +201,50 @@ function saveStagedFw() {
         log(`[agentdeck] staged-fw persist failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/** Resolve a stage target (canonical board, registry key, or IP) to the board
+ *  string the advert is keyed on.
+ *
+ *  This map is read back by `stagedFwAdvert(device_info.board)`, so anything
+ *  else stored as the key is an advert that can never fire. Staging with an IP
+ *  is not a misuse to reject — it is the documented way to name one unit when
+ *  two share a `board` string (see esp32-ota's ambiguity error) — so normalize
+ *  it here instead. Consequence worth stating: the feed pull carries only a
+ *  board, so a stage aimed at one unit adverts to every unit of that board.
+ *  They run the same image, so that is correct rather than merely tolerable.
+ *
+ *  Unlike `findWifiOtaTarget` this must NOT require an open socket: a
+ *  wake-sync-sleep board holds none by design, which is the entire reason
+ *  staging exists. An unrecognized target is kept verbatim — staging for a
+ *  board this daemon has not met yet is legitimate. */
+function resolveStagedFwBoard(target) {
+    for (const [key, device] of wifiEsp32Devices) {
+        if (key === target || device.board === target || device.ip === target)
+            return device.board;
+    }
+    // A pull-sync client ages out of the WS roster between wakes; the feed
+    // tracker keeps its IP→board memory precisely for that gap.
+    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). */
-function stageEsp32Fw(board, firmwarePath) {
+ *  re-fingerprinted by re-staging).
+ *
+ *  `pullSeen` reports whether this daemon has actually observed a feed pull
+ *  from the board, because "staged" proves neither transfer nor install and a
+ *  bare success reads as if it did. Only pull-sync firmware fetches a staged
+ *  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) {
+    const board = resolveStagedFwBoard(target);
     const firmware = readFileSync(firmwarePath);
     const md5 = createHash('md5').update(firmware).digest('hex');
     stagedFwByBoard.set(board, { firmwarePath, md5, size: firmware.length, stagedAt: Date.now() });
     saveStagedFw();
-    log(`[agentdeck] staged firmware for ${board}: ${firmware.length} bytes md5=${md5} — installs on its next feed pull`);
-    return { board, bytes: firmware.length, md5 };
+    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 };
 }
 /** 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. */
@@ -483,6 +524,11 @@ export const __wifiOtaTestApi = {
     unregisterWifiEsp32Socket,
     handleEsp32OtaReply,
     performWifiEsp32Ota,
+    resolveStagedFwBoard,
+    stageEsp32Fw,
+    stagedFwAdvert,
+    feedPulls,
+    clearStagedFwForTest: () => { stagedFwByBoard.clear(); },
 };
 async function performWifiEsp32Ota(core, target, firmwarePath) {
     const { key, device } = findWifiOtaTarget(target);
@@ -580,30 +626,6 @@ async function performWifiEsp32Ota(core, target, firmwarePath) {
         throw err;
     }
 }
-function loadDaemonSettings() {
-    // Newest settings.json across candidate data dirs — mirrors the
-    // daemon.json/sessions.json cross-dir discovery (and honors the
-    // AGENTDECK_DATA_DIR test override, which the old hardcoded
-    // ~/.agentdeck path ignored). The App Store sandbox container is
-    // intentionally NOT a candidate (TCC hang risk — see
-    // getCandidateDataDirs), so settings written by the sandboxed Swift
-    // app stay invisible here; that coexistence limit is documented in
-    // docs/appstore-feature-matrix.md.
-    let best = null;
-    for (const dir of getCandidateDataDirs()) {
-        try {
-            const path = join(dir, 'settings.json');
-            const mtime = statSync(path).mtimeMs;
-            if (best && best.mtime >= mtime)
-                continue;
-            best = { mtime, parsed: JSON.parse(readFileSync(path, 'utf-8')) };
-        }
-        catch {
-            // Missing or unreadable — skip this candidate.
-        }
-    }
-    return best?.parsed ?? {};
-}
 function latestTimelinePath() {
     let best = null;
     for (const dir of getCandidateDataDirs()) {
@@ -696,13 +718,15 @@ async function fetchUsageViaWs(siblings) {
 export async function fetchUsageRelayed(selfPort) {
     const sessions = listActiveSessions();
     const siblings = sessions.filter(s => s.port !== selfPort && s.agentType !== 'daemon');
+    // A sibling's reading is a real successful one, not a failure fallback, so it
+    // is `fresh` — its age contract is the 5-minute gate inside fetchUsageViaHttp.
     if (siblings.length > 0) {
         const httpResult = await fetchUsageViaHttp(siblings);
         if (httpResult)
-            return httpResult.usage;
+            return { data: httpResult.usage, fresh: true };
         const wsResult = await fetchUsageViaWs(siblings);
         if (wsResult)
-            return wsResult;
+            return { data: wsResult, fresh: true };
         // Relay is only an optimization to avoid multiple API pollers. A PTY session
         // bridge only refreshes usage when it has *direct* inbound WS clients, but
         // dashboards/Stream Deck connect to the daemon (sole entry point) — so a
@@ -767,15 +791,19 @@ export function classifyObservedHookEvent(eventName, mapped) {
     if (eventName === 'codex_subagent_start' || eventName === 'codex_subagent_stop') {
         return { boundary: eventName, agentType: 'codex-cli' };
     }
-    const prefixed = /^(codex|opencode|antigravity)_(session_start|session_end|user_prompt_submit|tool_start|tool_end|stop|turn_complete|notification|permission_asked|permission_replied)$/
+    const prefixed = /^(codex|opencode|antigravity|kiro|kiro_ide)_(agent_spawn|session_start|session_end|user_prompt_submit|tool_start|tool_end|stop|turn_complete|notification|permission_asked|permission_replied)$/
         .exec(eventName);
     if (!prefixed)
         return { boundary: mapped, agentType: 'claude-code' };
     return {
-        boundary: prefixed[2] === 'turn_complete' ? 'stop' : prefixed[2],
+        boundary: prefixed[2] === 'turn_complete' ? 'stop'
+            : prefixed[2] === 'agent_spawn' ? 'session_start'
+                : prefixed[2],
         agentType: prefixed[1] === 'codex' ? 'codex-cli'
             : prefixed[1] === 'opencode' ? 'opencode'
-                : 'antigravity',
+                : prefixed[1] === 'antigravity' ? 'antigravity'
+                    : prefixed[1] === 'kiro_ide' ? 'kiro-ide'
+                        : 'kiro-cli',
     };
 }
 function buildNodeModuleHealth(startedModules) {
@@ -901,6 +929,10 @@ export async function startDaemon(opts) {
     // CLI --wake-word flag OR settings.json wakeWord: true
     const settings = loadDaemonSettings();
     const wakeWordEnabled = opts.wakeWord || settings.wakeWord === true;
+    // Network posture (bind address + which device modules may run). Resolved once
+    // here so the bind, the module set, and the startup log cannot disagree about
+    // what this daemon is allowed to do.
+    const posture = resolveDaemonPosture({ local: opts.local, loopback: opts.loopback });
     // ===== Singleton guard + port allocation =====
     // 1. Check daemon.json and sessions.json for existing daemon
     const existingInfo = readDaemonInfo();
@@ -948,32 +980,46 @@ export async function startDaemon(opts) {
             removeDaemonSession(existingSession);
         }
     }
-    // 2. Determine port — try default first, fallback if occupied by non-daemon
-    const requestedPort = opts.port ?? DAEMON_DEFAULT_PORT;
+    // 2. Determine the preferred port — the one this daemon intends to serve.
+    // `opts.port` is already resolved by the CLI (flag › AGENTDECK_DAEMON_PORT ›
+    // settings.json `daemonPort` › 9120); resolving again here covers the
+    // library entry point, and both paths read the same sources.
+    const preferred = opts.port !== undefined
+        ? { port: opts.port, source: opts.portSource ?? 'flag' }
+        : resolveDaemonPort();
+    const requestedPort = preferred.port;
     let port = requestedPort;
-    // If using default port, check if it's available
-    if (requestedPort === DAEMON_DEFAULT_PORT) {
-        const health = await probeDaemonHealth(requestedPort);
-        if (health) {
-            if (health.mode === 'daemon') {
-                if (health.isSwift) {
-                    log(`[agentdeck] Swift daemon detected on port ${requestedPort} via /health. Requesting shutdown to take over...`);
-                    await requestDaemonShutdown(requestedPort);
-                    await waitForDaemonExit(requestedPort);
-                    await waitForPortBindable(requestedPort);
-                }
-                else {
-                    // Daemon alive but not in our registry — race condition or stale state
-                    log(`[agentdeck] Daemon already running on port ${requestedPort} (detected via /health).`);
-                    process.exit(0);
-                }
+    // Probe the preferred port before binding it. This used to run only for the
+    // built-in 9120, which made every other preferred port skip the Swift-daemon
+    // eviction and the occupied-port check — a persisted `daemonPort: 9200` would
+    // have been a second-class port on the same machine. The port a daemon
+    // intends to serve gets the same treatment wherever the intent came from.
+    const preferredOccupant = await probeDaemonHealth(requestedPort);
+    if (preferredOccupant) {
+        if (preferredOccupant.mode === 'daemon' && isForeignDaemon(preferredOccupant)) {
+            // Another OS user's daemon. Neither evict it nor concede to it — this
+            // user still gets a daemon, on a port of their own.
+            log(`[agentdeck] Port ${requestedPort} is held by another user's daemon — leaving it alone and taking a free port.`);
+            port = await findAvailablePort();
+        }
+        else if (preferredOccupant.mode === 'daemon') {
+            if (preferredOccupant.isSwift) {
+                log(`[agentdeck] Swift daemon detected on port ${requestedPort} via /health. Requesting shutdown to take over...`);
+                await requestDaemonShutdown(requestedPort);
+                await waitForDaemonExit(requestedPort);
+                await waitForPortBindable(requestedPort);
             }
             else {
-                // Port occupied by non-daemon (e.g. session bridge) — find alternative
-                log(`[agentdeck] Port ${requestedPort} occupied (${health.mode ?? 'unknown'}), finding alternative...`);
-                port = await findAvailablePort();
+                // Daemon alive but not in our registry — race condition or stale state
+                log(`[agentdeck] Daemon already running on port ${requestedPort} (detected via /health).`);
+                process.exit(0);
             }
         }
+        else {
+            // Port occupied by non-daemon (e.g. session bridge) — find alternative
+            log(`[agentdeck] Port ${requestedPort} occupied (${preferredOccupant.mode ?? 'unknown'}), finding alternative...`);
+            port = await findAvailablePort();
+        }
     }
     // 3. Cross-implementation sweep of the daemon port window. File discovery
     // has two blind spots that the checks above never cover: the App Store
@@ -985,6 +1031,14 @@ export async function startDaemon(opts) {
     // a live Node daemon wins and we exit.
     const strayDaemons = await scanDaemonPortWindow(new Set([requestedPort]));
     for (const stray of strayDaemons) {
+        if (isForeignDaemon(stray.health)) {
+            // Not a stray — someone else's daemon, doing its job for its own user.
+            // This sweep runs on every start, so without this check one user
+            // starting a CLI daemon shuts down every colleague's macOS app on the
+            // box (docs/ENTERPRISE-ROADMAP.md §1.3).
+            log(`[agentdeck] Port ${stray.port} is held by another user's daemon — not touching it.`);
+            continue;
+        }
         if (stray.health.isSwift) {
             log(`[agentdeck] Swift daemon detected on fallback port ${stray.port}. Requesting shutdown to take over...`);
             await requestDaemonShutdown(stray.port);
@@ -1017,6 +1071,53 @@ export async function startDaemon(opts) {
      * anything arrived SINCE this turn opened.
      */
     const hookSessionLastSeenAt = new Map();
+    /**
+     * Missed-Stop recovery for observed Claude sessions (plain `claude` in the
+     * user's own terminal — no PTY, hooks only).
+     *
+     * The Stop hook is the sole authority that closes a Claude turn, and its
+     * curl is fire-and-forget with a tight budget, so it drops. `agentdeck
+     * claude` has recovered from that since 1.0.20; observed sessions had
+     * nothing, which is the majority of real usage. Recovery re-enters this
+     * daemon's own `/hooks/Stop` over loopback rather than reimplementing that
+     * branch — see the class doc for why the same path matters.
+     *
+     * Declared before the HTTP server (hooks arrive the moment the port binds)
+     * and, like every other route, trusted purely because it is loopback: the
+     * auth gate treats same-machine as fully authorized, so no token is
+     * involved and none is minted.
+     */
+    const observedStopWatchdogs = new ObservedTurnWatchdogs({
+        onMissedStop: ({ sessionId, transcriptPath, reason, cwd, projectName }) => {
+            const url = `http://127.0.0.1:${port}/hooks/Stop`;
+            const controller = new AbortController();
+            // Bounded like every other peer await, loopback or not: a daemon
+            // mid-shutdown accepts the socket and never answers, and an unbounded
+            // wait there would pin the recovery forever.
+            const timer = setTimeout(() => controller.abort(), 2_000);
+            void fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                signal: controller.signal,
+                body: JSON.stringify({
+                    session_id: sessionId,
+                    transcript_path: transcriptPath,
+                    // Tags the APME turn `end_source='synthetic_stop'`, which is the
+                    // standing measurement of how often the real hook drops — unless
+                    // the user cancelled, in which case no Stop was ever due and the
+                    // turn must not be charged to that rate.
+                    synthetic_stop: true,
+                    ...(reason === 'interrupted' ? { interrupted: true } : {}),
+                    // Same for a client abort (usage limit, auth, API error): Claude
+                    // Code fires no Stop for it, so nothing was lost to recover.
+                    ...(reason === 'aborted' ? { aborted: true } : {}),
+                    ...(cwd ? { cwd } : {}),
+                    ...(projectName ? { project_name: projectName } : {}),
+                }),
+            }).catch(() => { })
+                .finally(() => clearTimeout(timer));
+        },
+    });
     // Codex OTel span state. Declared before the HTTP server because the
     // `/otel/v1/traces` handler closes over it — Codex's exporter can POST before
     // the rest of daemon startup finishes.
@@ -1030,6 +1131,9 @@ export async function startDaemon(opts) {
     // the rest of startup finishes. A later `const` would leave that window
     // throwing on the temporal dead zone.
     const passiveSessionObserver = new PassiveSessionObserver();
+    /** 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();
     /** Observed Claude sessions whose AskUserQuestion PreToolUse is held open for
      *  a device answer, keyed by the bare Claude session UUID. Its presence is
      *  what makes the session's options pressable (`liveAnswerable`) and what
@@ -1255,6 +1359,11 @@ export async function startDaemon(opts) {
                 // Workers require this flag before remote-attaching; the Swift daemon
                 // does not advertise it and is therefore never selected as a remote hub.
                 sameSocketControl: true,
+                // Network posture, so `agentdeck daemon restart` can carry the running
+                // daemon's posture across the restart instead of silently downgrading
+                // an enterprise install back to "advertise everything". Local-only
+                // payload; it is diagnostic, not a credential.
+                posture,
                 modules: moduleHealthProvider(),
                 apme: apme
                     ? {
@@ -1887,13 +1996,22 @@ export async function startDaemon(opts) {
                 const earlyHookProject = (typeof json.project_name === 'string' && json.project_name)
                     ? json.project_name
                     : (earlyHookCwd ? earlyHookCwd.split('/').filter(Boolean).pop() : undefined);
-                const childHook = subagentTimeline?.handle({
+                const childResult = subagentTimeline?.handle({
                     eventName,
                     payload: json,
                     sessionId: earlyHookSid,
                     agentType: hookAgentType,
                     projectName: earlyHookProject,
-                }).childOnly === true;
+                });
+                // A child starting or stopping is the ONLY thing that moves a parent's
+                // `subagents` block, and it moves nothing else — the parent's own state
+                // is untouched by design. Without this rebroadcast the census would sit
+                // stale until some unrelated event happened to refresh the list, which
+                // for an idle parent waiting on eight children is never.
+                if (childResult?.censusChangedFor) {
+                    core.broadcastSessionsList().catch(() => { });
+                }
+                const childHook = childResult?.childOnly === true;
                 if (childHook) {
                     // Child activity is observation-only. Never let child PreToolUse
                     // reach the parent's approval, STOP, state, or APME paths.
@@ -2044,6 +2162,15 @@ export async function startDaemon(opts) {
                 // (even one persisted before the restart) must not be force-closed.
                 hookSessionsSeen.add(hookSid);
                 hookSessionLastSeenAt.set(hookSid, Date.now());
+                // Missed-Stop recovery for observed Claude sessions. Fed the raw
+                // PascalCase event name — the watchdog's vocabulary is Claude's, and
+                // its transcript probe reads Claude's JSONL, so only Claude sessions
+                // are admitted (Codex/OpenCode carry their own turn-end signals).
+                // A synthetic Stop re-enters here as a normal hook and disarms the
+                // watchdog exactly like the real one would.
+                if (hookAgentType === 'claude-code') {
+                    observedStopWatchdogs.noteHookEvent(hookSid, eventName, json);
+                }
                 // Claude hooks carry `cwd` (the worktree dir), not project_name/path —
                 // capture it so APME runs are attributable to a specific worktree.
                 const hookCwd = (typeof json.cwd === 'string' ? json.cwd
@@ -2205,7 +2332,13 @@ export async function startDaemon(opts) {
                     }
                     const turnOpen = Boolean(lastStart && lastStart.ts > lastCompletionTs);
                     const tp = typeof json.transcript_path === 'string' ? json.transcript_path : '';
-                    const inlineResponse = [json.last_assistant_message, json.response, json.output, json.result]
+                    const inlineResponse = [
+                        json.last_assistant_message,
+                        json.assistant_response,
+                        json.response,
+                        json.output,
+                        json.result,
+                    ]
                         .find((v) => typeof v === 'string' && v.trim().length > 0) ?? '';
                     // Codex's stop payload rarely carries the text inline; its rollout
                     // JSONL (agent_message / task_complete records) is the
@@ -2242,6 +2375,18 @@ export async function startDaemon(opts) {
                             // response, so a duplicate stop is a no-op instead of a clobber.
                             apme.collector.setLastClosedTurnResponse(hookSid, responseText);
                         }
+                        // Close the APME turn on the Stop that ended it, tagged with which
+                        // Stop that was. Runs AFTER the response capture above (the
+                        // trajectory event wants the still-active turn) and is a no-op when
+                        // no turn is open, so a duplicate/late stop cannot re-attribute an
+                        // already-closed turn. `turnOpen` above is a TIMELINE predicate —
+                        // it says nothing about the collector's turn, which is why this is
+                        // unconditional rather than nested under it.
+                        apme.collector.noteTurnStop(hookSid, {
+                            synthetic: json.synthetic_stop === true,
+                            interrupted: json.interrupted === true,
+                            aborted: json.aborted === true,
+                        });
                     }
                     if (turnOpen && lastStart) {
                         const now = Date.now();
@@ -2442,7 +2587,13 @@ export async function startDaemon(opts) {
                     // by blocking the stop with the directive as the continuation
                     // reason. Empty queue (the overwhelmingly common case) → empty body,
                     // Claude ends the turn normally — no stop_hook_active loop possible.
-                    const directive = claudeSid ? takeDirective(claudeSid) : undefined;
+                    //
+                    // `takeDirectiveForStop` refuses a synthetic Stop (missed-Stop
+                    // watchdog): nothing is listening on that response, so draining the
+                    // queue there would silently eat the user's queued follow-up.
+                    // `clearStop` still runs either way — the transcript proved the turn
+                    // ended, so a pending soft-stop is moot however we learned it.
+                    const directive = claudeSid ? takeDirectiveForStop(claudeSid, json) : undefined;
                     if (claudeSid)
                         clearStop(claudeSid); // turn ended — a pending soft-stop is moot
                     res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -2680,8 +2831,9 @@ export async function startDaemon(opts) {
     // pull-sync e-ink clients live on the LAN — and the security boundary is the
     // pairing token (http-auth-gate.ts default-denies unauthenticated LAN
     // requests; the WS server has always token-gated non-local peers). Users
-    // with no LAN devices can opt into a loopback-only bind (issue #145).
-    const bindHost = process.env.AGENTDECK_LOOPBACK_ONLY === '1' ? '127.0.0.1' : '0.0.0.0';
+    // with no LAN devices can opt into a loopback-only posture (issue #145),
+    // which also silences everything the daemon emits (see network-posture.ts).
+    const bindHost = bindHostFor(posture);
     await new Promise((resolve, reject) => {
         httpServer.on('error', (err) => {
             if (err.code === 'EADDRINUSE') {
@@ -2716,8 +2868,48 @@ export async function startDaemon(opts) {
             if (occupant?.mode === 'daemon') {
                 log(`[agentdeck] Port ${requestedPort} reports a daemon but PID ${occupant.pid} is not a live distinct process; treating as stale and falling back.`);
             }
+            // Nobody answered on the preferred port, yet it refuses to bind. That is
+            // not a peer to yield to — it is the kernel still holding a port whose
+            // owner has already gone: macOS keeps a NECP reservation for ~14s after
+            // an `NWListener.cancel()` (measured 2026-08-06: bindable at ~17s, with
+            // `lsof` showing zero sockets throughout), and a half-closed socket in
+            // TIME_WAIT/LAST_ACK looks the same from here.
+            //
+            // Without this wait the daemon conceded instantly and moved to 9121 —
+            // permanently, because nothing ever moved it back. Seconds after that
+            // decision the canonical port was free and owned by nobody. Waiting is
+            // the whole recovery: `waitForPortBindable` polls, so a kernel-held port
+            // costs the ~14s it is actually held, and only a genuinely occupied port
+            // pays the full budget before falling back.
+            if (!occupant) {
+                log(`[agentdeck] Port ${requestedPort} is held but nothing answers /health — usually the kernel still `
+                    + `releasing it after the previous owner exited. Waiting up to ${Math.round(PREFERRED_PORT_RECLAIM_MS / 1000)}s…`);
+                if (await waitForPortBindable(requestedPort, PREFERRED_PORT_RECLAIM_MS)) {
+                    const bound = await new Promise((resolve) => {
+                        const onError = () => resolve(false);
+                        httpServer.once('error', onError);
+                        httpServer.listen(requestedPort, bindHost, () => {
+                            httpServer.removeListener('error', onError);
+                            resolve(true);
+                        });
+                    });
+                    if (bound) {
+                        log(`[agentdeck] Port ${requestedPort} came free — bound it instead of falling back.`);
+                        return;
+                    }
+                    // Lost it again between the probe bind and ours. Rare, and the
+                    // fallback below is exactly the right answer for it.
+                    log(`[agentdeck] Port ${requestedPort} was taken again before this daemon could bind it.`);
+                }
+                else {
+                    log(`[agentdeck] Port ${requestedPort} is still held after ${Math.round(PREFERRED_PORT_RECLAIM_MS / 1000)}s — `
+                        + `something outside AgentDeck is listening on it, or a sleeping device is holding a half-closed socket.`);
+                }
+            }
             port = await findAvailablePort();
             log(`[agentdeck] Port ${requestedPort} grabbed by ${occupant?.mode ?? 'a non-daemon'}, retrying on ${port}...`);
+            log(`[agentdeck] This daemon prefers port ${requestedPort} (${describeDaemonPortSource(preferred.source)}). `
+                + `Clients resolve the actual port from daemon.json; 'agentdeck daemon restart' aims at the preferred port again.`);
             await new Promise((resolve, reject) => {
                 httpServer.on('error', (e) => reject(e));
                 httpServer.listen(port, bindHost, () => resolve());
@@ -2727,11 +2919,11 @@ export async function startDaemon(opts) {
             throw err;
         }
     });
-    if (bindHost === '127.0.0.1') {
-        log(`[agentdeck] AGENTDECK_LOOPBACK_ONLY=1 — daemon bound to 127.0.0.1:${port}; LAN devices (companion apps, ESP32/WiFi boards) cannot connect.`);
-    }
-    else {
-        log(`[agentdeck] Daemon listening on all interfaces (:${port}) — LAN requests require the pairing token (~/.agentdeck/auth-token). Set AGENTDECK_LOOPBACK_ONLY=1 for a loopback-only bind.`);
+    log(describeDaemonPosture(posture, port));
+    if (preferred.source === 'settings' || preferred.source === 'env') {
+        // A persisted or environmental port is invisible in the command line that
+        // started this daemon, so the log is the only place it can be discovered.
+        log(`[agentdeck] Preferred port ${requestedPort} comes from ${describeDaemonPortSource(preferred.source)}.`);
     }
     // Write daemon.json for client discovery (must be after successful bind).
     // Keep the original startedAt stable when the self-heal timer rewrites it.
@@ -2744,8 +2936,14 @@ export async function startDaemon(opts) {
         httpServer,
         isDaemon: true,
     });
-    subagentTimeline = new SubagentTimelineTracker((entry) => {
-        core.bridgeTimeline.addEntry(entry, { bypassSuppression: true });
+    subagentTimeline = new SubagentTimelineTracker((entry, upsert) => {
+        // A dispatch row is upserted as its burst grows (one row per fan-out, the
+        // `task_start` folding pattern) — emitting a fresh row per child would
+        // spend a 200-entry buffer shared by every session on one workflow.
+        if (upsert)
+            core.bridgeTimeline.upsertEntry(entry, { bypassSuppression: true });
+        else
+            core.bridgeTimeline.addEntry(entry, { bypassSuppression: true });
     });
     // Hooks resolve a fallback daemon port through daemon.json. Another process
     // can delete that file while this daemon remains healthy, which makes every
@@ -2828,6 +3026,11 @@ export async function startDaemon(opts) {
         const TURN_WATCHDOG_SILENCE_MS = 3 * 60_000;
         const turnWatchdog = setInterval(() => {
             const now = Date.now();
+            // Drop per-session missed-Stop watchdogs whose session has gone cold.
+            // Rides this existing tick rather than owning a timer: an observed
+            // session that dies mid-turn never sends SessionEnd, so its watchdog
+            // would otherwise poll for the life of the daemon.
+            observedStopWatchdogs.sweep();
             const active = new Set();
             for (const [sid, at] of hookSessionLastSeenAt) {
                 if (now - at <= TURN_WATCHDOG_SILENCE_MS)
@@ -2912,15 +3115,7 @@ export async function startDaemon(opts) {
         // Reset backoff from pre-sleep failures and fetch fresh usage after network stabilizes
         resetConsecutiveFailures();
         setTimeout(() => {
-            fetchUsageRelayed(port).then((usage) => {
-                if (usage)
-                    core.updateApiUsage(usage);
-                else {
-                    core.oauthConnected = hasOAuthToken();
-                    if (core.cachedApiUsage)
-                        core.apiUsageStale = true;
-                }
-            });
+            fetchUsageRelayed(port).then((result) => core.applyUsageResult(result));
         }, 4000);
     });
     // Subscribe to sibling session bridges' timelines + modelCatalog relay
@@ -3015,6 +3210,19 @@ export async function startDaemon(opts) {
             // 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);
             }
@@ -3039,7 +3247,12 @@ export async function startDaemon(opts) {
     // driven exclusively by the Ulanzi Studio plugin (`ulanzi-plugin`) over WebSocket;
     // the daemon never opens it over HID. Its health is reported via the Ulanzi client
     // count in moduleHealthProvider below.
-    const startedModules = await initModules(deviceModules, { mdns: true, broadcast: true, adb: 'auto', serial: serialMode, pixoo: 'auto', timebox: 'auto', idotmatrix: 'auto' }, { port, authToken: core.authToken, projectName: 'AgentDeck', wsServer: core.wsServer });
+    const startedModules = await initModules(deviceModules, daemonModuleConfigs(posture, serialMode), {
+        port, authToken: core.authToken, projectName: 'AgentDeck', wsServer: core.wsServer,
+        // AdbModule restricts `adb reverse` to USB transports under loopback —
+        // a TCP/mDNS adb device would carry the tunnel over the LAN.
+        loopbackOnly: posture.loopbackOnly,
+    });
     moduleHealthProvider = () => {
         const modules = buildNodeModuleHealth(startedModules);
         const einkDevices = collectEinkDevices();
@@ -3293,7 +3506,24 @@ export async function startDaemon(opts) {
     // The observer scans in the background now (collect() returns the cache
     // immediately). When a scan lands fresh observations, push them out via
     // the debounced broadcast so clients don't wait for the next 10 s poll.
-    passiveSessionObserver.onRefreshed = () => core.maybeBroadcastSessionsList();
+    passiveSessionObserver.onRefreshed = () => {
+        // Kiro pushes nothing: no `kiro_*` hook has ever reached this daemon, so
+        // without a producer here its session shows in the HUD while the timeline
+        // beside it stays empty. #218 taught the per-session QUERY to read Kiro's
+        // own transcript; the main timeline is a STREAM, and this is what feeds it.
+        try {
+            const kiroIds = passiveSessionObserver.collect([])
+                .filter((s) => typeof s.agentType === 'string' && s.agentType.startsWith('kiro'))
+                .map((s) => s.id);
+            for (const entry of kiroTimelineFeed.pump(kiroIds)) {
+                core.bridgeTimeline.addEntry(entry);
+            }
+        }
+        catch (err) {
+            debug('daemon', `kiro timeline feed failed: ${String(err)}`);
+        }
+        core.maybeBroadcastSessionsList();
+    };
     // OTel turn boundaries arrive in milliseconds where the observer only re-reads
     // the rollout tail every scan interval, so a span that changed thread state is
     // worth a broadcast of its own.
@@ -3344,15 +3574,24 @@ export async function startDaemon(opts) {
         // Derive per-session elapsed seconds from startedAt so NTP-less devices
         // (ESP32 IPS10 mosaic) render an elapsed value per cell without a wall clock.
         const now = Date.now();
+        // Live child-agent census. Hooks key children by the BARE session uuid
+        // while these rows are `observed:<agent>:<uuid>`, so normalize before the
+        // lookup — the two id forms are the standing trap here.
+        const subagentCensus = subagentTimeline?.summaries() ?? new Map();
         const enrichedSessions = [...sessions, ...observed, ...remote].map((s) => {
             // On-demand review badge (REVIEW tile verdict / REVIEWING state) —
             // applies to every session type, managed included.
             const review = reviewSnapshot(s.id);
             const withReview = Object.keys(review).length > 0 ? { ...s, ...review } : s;
-            if (withReview.elapsedSec != null || !withReview.startedAt)
-                return withReview;
-            const sec = Math.round((now - Date.parse(withReview.startedAt)) / 1000);
-            return Number.isFinite(sec) && sec >= 0 ? { ...withReview, elapsedSec: sec } : withReview;
+            // Emitted whenever this session has EVER had a child, zeros included: a
+            // field that disappears when the last child exits latches "8 running" on
+            // every client that merges retain-on-absent.
+            const census = subagentCensus.get(rawSessionId(withReview.id));
+            const withCensus = census ? { ...withReview, subagents: census } : withReview;
+            if (withCensus.elapsedSec != null || !withCensus.startedAt)
+                return withCensus;
+            const sec = Math.round((now - Date.parse(withCensus.startedAt)) / 1000);
+            return Number.isFinite(sec) && sec >= 0 ? { ...withCensus, elapsedSec: sec } : withCensus;
         });
         // SSOT: inject iff Gateway is authenticated (gatewayConnected). Reachability
         // / adapter-liveness alone must not materialize a session — that kept a
@@ -3371,6 +3610,11 @@ export async function startDaemon(opts) {
             projectName: 'OpenClaw',
             modelName: gatewayModelName,
             controlMode: 'managed',
+            // Read live from the adapter rather than cached alongside
+            // `gatewaySessionState`: the two would drift, and a row that says
+            // "awaiting_permission" while carrying no options is exactly the
+            // dead end this fixes.
+            approval: gatewayAdapter?.getPendingApproval() ?? null,
         });
     });
     // OpenClaw-specific APME session id. Distinct from `core.sessionId`
@@ -3432,6 +3676,14 @@ export async function startDaemon(opts) {
                         gatewaySessionState = 'idle';
                     else if (evt.event === 'permission_prompt')
                         gatewaySessionState = 'awaiting_permission';
+                    // The virtual Gateway row carries the approval's question/options, so
+                    // a prompt appearing or clearing changes `sessions_list` — not just
+                    // the state event. Devices read their option cells from that list; a
+                    // state-only broadcast left them showing the previous prompt (or
+                    // none) until some unrelated event forced a refresh.
+                    if (evt.event === 'spinner_start' || evt.event === 'idle' || evt.event === 'permission_prompt') {
+                        core.broadcastSessionsList().catch(() => { });
+                    }
                     // 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.
@@ -3487,6 +3739,14 @@ export async function startDaemon(opts) {
                             core.bridgeTimeline.addEntry(enriched);
                         if (enriched.type === 'tool_request')
                             bridgeLogStream.trackToolRequest(enriched.raw);
+                        // Flip the matching `tool_request` row off `pending`. The resolution
+                        // has always been emitted as its own row, so the request row kept
+                        // `status: 'pending'` forever — an approval answered minutes ago
+                        // 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');
+                        }
                     }
                     break;
                 case 'connection': {
@@ -3800,6 +4060,17 @@ export async function startDaemon(opts) {
                     }
                     catch { /* read-only best effort */ }
                 }
+                // Kiro keeps its transcript in its OWN store, so the Claude reader
+                // above can never find one — and no `kiro_*` hook has ever reached
+                // this daemon (v2 has no global hook surface at all), so the timeline
+                // store is empty for it too. Without this branch an observed Kiro
+                // session's Detail view is empty whatever it does.
+                if (entries.length === 0 && sessionId.startsWith('observed:kiro')) {
+                    try {
+                        entries = kiroTimelineForSession(sessionId, { since: sinceMs });
+                    }
+                    catch { /* read-only best effort */ }
+                }
                 const historyEvent = buildCappedTimelineHistory(entries, undefined, { sessionId });
                 if (historyEvent) {
                     try {
@@ -4233,12 +4504,7 @@ export async function startDaemon(opts) {
             return;
         }
         if (cmd.type === 'query_usage') {
-            fetchUsageRelayed(port).then((usage) => {
-                if (usage)
-                    core.updateApiUsage(usage);
-                else if (core.cachedApiUsage)
-                    core.apiUsageStale = true;
-            });
+            fetchUsageRelayed(port).then((result) => core.applyUsageResult(result));
         }
     };
     // ── Device-sourced voice ──────────────────────────────────────────────
@@ -5061,15 +5327,7 @@ export async function startDaemon(opts) {
         // 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((usage) => {
-                if (usage)
-                    core.updateApiUsage(usage);
-                else {
-                    core.oauthConnected = hasOAuthToken();
-                    if (core.cachedApiUsage)
-                        core.apiUsageStale = true;
-                }
-            });
+            fetchUsageRelayed(port).then((result) => core.applyUsageResult(result));
         }
     });
     core.wsServer.onClientDisconnect((ws) => {
@@ -5286,15 +5544,7 @@ export async function startDaemon(opts) {
     }
     // Initial usage fetch (delayed 10s)
     core.addTimeout(setTimeout(() => {
-        fetchUsageRelayed(port).then((usage) => {
-            if (usage)
-                core.updateApiUsage(usage);
-            else {
-                core.oauthConnected = hasOAuthToken();
-                if (core.cachedApiUsage)
-                    core.apiUsageStale = true;
-            }
-        });
+        fetchUsageRelayed(port).then((result) => core.applyUsageResult(result));
     }, 10_000));
     // Backstop sweep for held PreToolUse approval responses whose per-entry timer
     // somehow didn't fire — resolves anything older than 60s to "ask" so a held
@@ -5309,6 +5559,9 @@ export async function startDaemon(opts) {
         removeDaemonInfo();
         focusRelay.stop();
         timelineRelay.stop();
+        // Clears every per-session poll timer. A watchdog that survived teardown
+        // would keep firing self-POSTs at a port this daemon no longer owns.
+        observedStopWatchdogs.stop();
         voiceAssistant?.stop();
         bridgeLogStream.stop();
         // Flush synchronously — the process exits a few lines below and a pending