@tapflowio/relay 0.16.0 → 0.18.0

package/dist/RelayServer.js

@@ -41,6 +41,11 @@ export function isExternalAddress(addr) {
 const IDR_REQUEST_THROTTLE_MS = 500;
 // Ping every socket each interval; a missed pong window (~2× this) terminates the dead socket.
 const HEARTBEAT_MS = 30_000;
+// How long a session outlives its agent's socket, waiting for that agent to come back (#426).
+// An agent registers ~1s after its process starts, so this covers an automatic respawn several
+// times over and about half of a hand-typed restart. What bounds it is the other direction: the
+// device stays claimed by a session nobody can use until the window closes.
+const DEFAULT_AGENT_GRACE_MS = 15_000;
 import { handleVerifyReset, handleDoReset, handleSendMemberReset } from './api/passwordReset.js';
 import { handleListBuilds, handleGetBuild, handleUpdateBuild, handleUploadBuild, handleScheduleBuildDeletion, handleCancelBuildDeletion, purgeExpiredBuilds } from './api/builds.js';
 import { handleListApps, handleCreateApp, handleUpdateApp, handleDeleteApp } from './api/apps.js';
@@ -70,6 +75,10 @@ const _parsedThreshold = parseInt(process.env['TAPFLOW_RESOURCE_THRESHOLD_PERCEN
 const RESOURCE_THRESHOLD = Number.isFinite(_parsedThreshold) ? _parsedThreshold : 80;
 // Messages that only agents are allowed to send. Authenticated browser sockets
 // that send any of these are disconnected immediately.
+// Terminal input messages the MCP client awaits an ack for — if the agent is offline
+// the relay replies input:error so the client fails truthfully (non-terminal moves/starts
+// expect no ack and are dropped silently).
+const TERMINAL_INPUT_TYPES = new Set(['input:touch:end', 'input:pinch:end', 'input:key', 'input:button']);
 const AGENT_MSG_TYPES = new Set([
     'agent:register', 'agent:resources', 'screenshot:done', 'screenshot:error',
     'ui:tree:response', 'ui:tree:error',
@@ -78,7 +87,10 @@ const AGENT_MSG_TYPES = new Set([
     'session:chrome', 'session:deviceInfo',
     'app:install-done', 'app:install-error', 'app:launch-done', 'app:launch-error',
     'open-url:done', 'open-url:error', 'keyboard:toggled',
-    'input:type-done', 'input:type-error',
+    'input:type-done', 'input:type-error', 'input:done', 'input:error',
+    // clipboard:data carries the simulator's clipboard — agent-authenticated, so a
+    // browser socket can never inject it into another viewer.
+    'clipboard:data', 'clipboard:write-done', 'clipboard:error',
     // stream:register binds a session's stream socket — agent-only, or a browser
     // (view PAT / cookie) could hijack an existing session's video feed.
     'stream:register',
@@ -109,11 +121,22 @@ export class RelayServer {
     // Per-session throttled "request an IDR from the agent" callbacks (drop recovery).
     idrRequesters = new Map();
     wsRoles = new Map();
+    // Agent sockets whose sessions are being held open, and the timer that gives up on each.
+    // Keyed by the dead socket, never by session id: a rebind moves sessions off that socket, so an
+    // expiry that fires late has nothing left to evict. That is the invariant — releasing the hold
+    // on the way back is hygiene on top of it, not a second thing holding the property up. The late
+    // expiry is not a complete no-op either: it still drops the socket's resource entry.
+    agentHolds = new Map();
+    // Set by `stop()`. Its own `terminate()` loop fires a close for every socket, and a hold armed
+    // from there would outlive the server it belongs to — the exact hazard the clearing above it is
+    // for, arriving a few lines later.
+    stopping = false;
     // True when the connection's remote IP is public (not loopback / private LAN) — the agent uses
     // this to downscale harder for bandwidth on external viewers.
     wsExternal = new Map();
     backpressureBytes;
     screenshotTimeoutMs;
+    agentGraceMs;
     corsAllowed;
     // One-shot warning when XFF arrives on a loopback socket but TAPFLOW_TRUSTED_PROXIES is unset.
     warnedProxyMisconfig = false;
@@ -128,6 +151,24 @@ export class RelayServer {
         // itself may take up to 10s before it errors out.
         this.uiTreeTimeoutMs = options.uiTreeTimeoutMs ?? 15_000;
         this.corsAllowed = new Set(options.corsOrigins ?? []);
+        // Constructor option first, then env. It cannot be env-only: `IDLE_TIMEOUT_MS` is read at module
+        // load, which is why no test can set it, and the tests that need a different window here run in
+        // the same process as the default.
+        // Validated, not just parsed, and blank treated as unset rather than as a number. Three ways
+        // this silently switches the feature off if read naively: `parseInt('15s')` is 15 — and the
+        // documented default reads "15000 (15 s)", so that is the typo the docs invite; a non-numeric
+        // value is NaN, which `setTimeout` rounds to ~1ms; and `Number('')` is 0, not NaN, so an empty
+        // `.env` line would pass a `>= 0` check and give a zero-length window.
+        const graceRaw = process.env['TAPFLOW_AGENT_GRACE_MS']?.trim();
+        const graceEnv = graceRaw ? Number(graceRaw) : NaN;
+        const graceUsable = Number.isFinite(graceEnv) && graceEnv >= 0;
+        this.agentGraceMs = options.agentGraceMs ?? (graceUsable ? graceEnv : DEFAULT_AGENT_GRACE_MS);
+        // Say so rather than only documenting it. Both times this parsing was wrong the symptom was
+        // the same — the hold switched off and nothing mentioned it — and somebody who types `15s` is
+        // reading their terminal, not the configuration table.
+        if (options.agentGraceMs === undefined && graceRaw && !graceUsable) {
+            logger.warn(`TAPFLOW_AGENT_GRACE_MS="${graceRaw}" is not a usable number of milliseconds — using ${DEFAULT_AGENT_GRACE_MS}`);
+        }
         this.sessions = new SessionManager({ idleTimeoutMs: options.idleTimeoutMs });
         this.publicDir = options.publicDir ?? path.join(import.meta.dirname, '../public');
         this.uploadsDir = options.uploadsDir ?? path.join(import.meta.dirname, '../uploads');
@@ -281,6 +322,12 @@ export class RelayServer {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = null;
         }
+        // `unref()` would not do: the test runner's process outlives the server, so an un-cleared hold
+        // still fires — against a server that has already stopped.
+        this.stopping = true;
+        for (const timer of this.agentHolds.values())
+            clearTimeout(timer);
+        this.agentHolds.clear();
         return new Promise((resolve, reject) => {
             this.wss.clients.forEach((ws) => ws.terminate());
             this.wss.close(() => {
@@ -319,7 +366,7 @@ export class RelayServer {
             lastAt = now;
             const session = this.sessions.get(sessionId);
             if (session?.agentSocket.readyState === WebSocket.OPEN) {
-                session.agentSocket.send(JSON.stringify({ type: 'stream:request-idr', sessionId }));
+                this.sendTo(session.agentSocket, { type: 'stream:request-idr', sessionId });
             }
         };
     }
@@ -416,19 +463,35 @@ export class RelayServer {
                 }
                 return;
             }
+            let parsed;
             try {
-                const msg = JSON.parse(data.toString());
-                this.route(ws, msg);
+                parsed = JSON.parse(data.toString());
             }
             catch {
-                // ignore malformed messages
+                return; // genuinely malformed — there is no type to answer on
+            }
+            // `JSON.parse` returns bare `null`, numbers and strings without throwing, and `route` reads
+            // `.type` off whatever it is handed. Rejecting non-objects here is what lets the catch below
+            // name the message safely.
+            if (typeof parsed !== 'object' || parsed === null)
+                return;
+            const msg = parsed;
+            try {
+                this.route(ws, msg);
+            }
+            catch (e) {
+                // A throw inside a handler used to land in the same catch as a parse failure and vanish.
+                // Anything reaching here is a bug in routing, not a bad message, and the caller is left
+                // waiting either way — so at least say so once instead of dropping it silently.
+                logger.error(`route failed for ${String(msg.type)}:`, e);
             }
         });
         ws.on('close', () => {
             this.wsRoles.delete(ws);
             this.wsExternal.delete(ws);
-            // Agent main socket disconnected → remove its sessions, reject in-flight screenshots, drop resources
-            if (this.evictAgentSocket(ws))
+            // Agent main socket disconnected → hold its sessions open for a moment in case the agent is
+            // coming back (#426), rather than ending them where they stand.
+            if (this.holdAgentSocket(ws))
                 return;
             // Stream socket disconnected → clear the streamSocket reference
             const streamSession = this.sessions.getByStreamSocket(ws);
@@ -442,11 +505,11 @@ export class RelayServer {
                 this.sessions.clearBrowser(browserSession.id, () => {
                     const session = this.sessions.get(browserSession.id);
                     if (session?.agentSocket.readyState === WebSocket.OPEN) {
-                        session.agentSocket.send(JSON.stringify({
+                        this.sendTo(session.agentSocket, {
                             type: 'device:shutdown',
                             sessionId: session.id,
                             payload: { deviceId: session.deviceId },
-                        }));
+                        });
                     }
                 });
             }
@@ -493,7 +556,7 @@ export class RelayServer {
                 this.handleUITreeError(msg);
                 break;
             case 'agents:list': {
-                ws.send(JSON.stringify({ type: 'agents:listed', sessions: this.sessions.list() }));
+                this.sendTo(ws, { type: 'agents:listed', sessions: this.sessions.list() });
                 break;
             }
             // ── Session / Stream lifecycle ─────────────────────────────────────────
@@ -524,7 +587,7 @@ export class RelayServer {
                 const session = this.sessions.get(msg.sessionId);
                 if (session) {
                     this.sessions.setStreamSocket(session.id, ws);
-                    ws.send(JSON.stringify({ type: 'stream:registered' }));
+                    this.sendTo(ws, { type: 'stream:registered' });
                 }
                 break;
             }
@@ -533,6 +596,10 @@ export class RelayServer {
                 const session = this.sessions.get(msg.sessionId);
                 if (!session)
                     break;
+                // Cast, not a check: nothing validates inbound messages, so the relay takes the agent's
+                // word for the shape. It only stores and forwards this, so a wrong shape surfaces in the
+                // viewer rather than here — but this is where a runtime validator belongs when one exists
+                // (see packages/protocol/AGENTS.md).
                 this.sessions.setChromeData(session.id, msg.payload);
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
                     session.browserSocket.send(JSON.stringify(msg));
@@ -572,6 +639,7 @@ export class RelayServer {
                 if (!session)
                     break;
                 this.sessions.updateDeviceStatus(session.id, 'shutdown');
+                this.sessions.setReadySent(session.id, false);
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
                     session.browserSocket.send(JSON.stringify(msg));
                 }
@@ -582,6 +650,7 @@ export class RelayServer {
                 if (!session)
                     break;
                 this.sessions.updateDeviceStatus(session.id, 'booted');
+                this.sessions.setReadySent(session.id, true);
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
                     session.browserSocket.send(JSON.stringify(msg));
                 }
@@ -597,6 +666,8 @@ export class RelayServer {
             case 'app:clear-state-error':
             case 'input:type-done':
             case 'input:type-error':
+            case 'input:done':
+            case 'input:error':
             case 'keyboard:toggled': {
                 const session = this.sessions.get(msg.sessionId);
                 if (session?.browserSocket?.readyState === WebSocket.OPEN) {
@@ -604,10 +675,38 @@ export class RelayServer {
                 }
                 break;
             }
+            // Bound to the session's own agent socket, unlike the replies above: this payload
+            // lands on the viewer's host OS clipboard, so a second agent (another Mac on the
+            // same relay) must not be able to address someone else's session.
+            case 'clipboard:data':
+            case 'clipboard:write-done':
+            case 'clipboard:error': {
+                const session = this.sessions.get(msg.sessionId);
+                if (session?.agentSocket !== ws)
+                    break;
+                if (session.browserSocket?.readyState === WebSocket.OPEN) {
+                    session.browserSocket.send(JSON.stringify(msg));
+                }
+                break;
+            }
             // ── Browser → Agent ────────────────────────────────────────────────────
             case 'device:boot':
             case 'device:shutdown': {
                 const session = this.sessions.get(msg.sessionId);
+                if (session?.agentSocket.readyState !== WebSocket.OPEN && msg.type === 'device:boot') {
+                    // A boot the agent never receives leaves the viewer on "Waiting for first frame…" with
+                    // nothing said. `device:shutdown` gets no such reply: nothing waits on it, and inventing
+                    // a `device:shutdown-error` would grow the contract for a message no one reads.
+                    //
+                    // The two are worth telling apart: `bootDevice` is the first call an MCP caller makes, so
+                    // reporting a stale session id as a dead Mac sends the reader after the wrong problem.
+                    this.sendTo(ws, {
+                        type: 'device:boot-error',
+                        sessionId: msg.sessionId,
+                        message: session ? 'agent offline' : 'Session not found',
+                    });
+                    break;
+                }
                 if (session?.agentSocket.readyState === WebSocket.OPEN) {
                     // Tag the boot with whether the viewer is external (public IP) so the agent can pick the
                     // downscale tier. The browser already reports secureContext in the payload.
@@ -630,7 +729,7 @@ export class RelayServer {
                     session.agentSocket.send(JSON.stringify(msg));
                 }
                 else {
-                    ws.send(JSON.stringify({ type: 'open-url:error', sessionId: msg.sessionId, message: 'agent offline' }));
+                    this.sendTo(ws, { type: 'open-url:error', sessionId: msg.sessionId, message: 'agent offline' });
                 }
                 break;
             }
@@ -640,7 +739,7 @@ export class RelayServer {
                     session.agentSocket.send(JSON.stringify(msg));
                 }
                 else {
-                    ws.send(JSON.stringify({ type: 'app:clear-state-error', sessionId: msg.sessionId, message: 'agent offline' }));
+                    this.sendTo(ws, { type: 'app:clear-state-error', sessionId: msg.sessionId, message: 'agent offline' });
                 }
                 break;
             }
@@ -659,6 +758,28 @@ export class RelayServer {
                 if (session?.agentSocket.readyState === WebSocket.OPEN) {
                     session.agentSocket.send(JSON.stringify(msg));
                 }
+                else if (TERMINAL_INPUT_TYPES.has(msg.type) && ws.readyState === WebSocket.OPEN) {
+                    // Agent offline or session evicted: a terminal input can't be dispatched.
+                    // Reply to the sender (the MCP/browser socket) so it fails truthfully
+                    // instead of falling through to its optimistic 2s timeout.
+                    this.sendTo(ws, { type: 'input:error', sessionId: msg.sessionId, message: 'agent offline' });
+                }
+                break;
+            }
+            // Kept out of the input:* chain above: these need their own error type, and the caller
+            // is waiting on a bounded deadline, so an undeliverable request fails now rather than
+            // hanging until the browser gives up.
+            case 'clipboard:read':
+            case 'clipboard:write': {
+                const session = this.sessions.get(msg.sessionId);
+                if (session?.agentSocket.readyState === WebSocket.OPEN) {
+                    session.agentSocket.send(JSON.stringify(msg));
+                }
+                else if (ws.readyState === WebSocket.OPEN) {
+                    this.sendTo(ws, {
+                        type: 'clipboard:error', sessionId: msg.sessionId, requestId: msg.requestId, message: 'agent offline',
+                    });
+                }
                 break;
             }
         }
@@ -678,28 +799,124 @@ export class RelayServer {
     // Removes an agent socket's sessions + resources and rejects its in-flight
     // screenshot / ui-tree requests. Shared by socket close and re-register
     // eviction. Returns true if `ws` had agent sessions.
-    evictAgentSocket(ws) {
-        const agentSessions = this.sessions.getAllByAgentSocket(ws);
-        if (agentSessions.length === 0)
-            return false;
-        const agentSessionIds = new Set(agentSessions.map((s) => s.id));
-        for (const [reqId, pending] of this.pendingScreenshots.entries()) {
-            if (agentSessionIds.has(pending.sessionId)) {
+    /**
+     * Every message the relay *originates* goes through here. The union checks the shape where the
+     * literal is written — a mistyped `type`, a missing field or one that does not belong are all
+     * compile errors — and the readyState guard replaces the check that was repeated (and sometimes
+     * omitted) at each call site.
+     *
+     * Messages the relay merely *forwards* do not use this: they are re-serialised unchanged, so
+     * they keep their inbound type and there is nothing new to check.
+     */
+    sendTo(socket, msg) {
+        if (socket.readyState !== WebSocket.OPEN)
+            return;
+        socket.send(JSON.stringify(msg));
+    }
+    /**
+     * Settle every in-flight screenshot / UI-tree request belonging to these sessions. Both callers
+     * are moments where the agent that was going to answer them no longer exists — it disconnected,
+     * or it restarted and its session moved to the new process. Left alone these reject on their own
+     * timeout, minutes later, having told the caller nothing in between.
+     */
+    rejectPending(sessionIds, reason) {
+        for (const pendings of [this.pendingScreenshots, this.pendingUITrees]) {
+            for (const [reqId, pending] of pendings.entries()) {
+                if (!sessionIds.has(pending.sessionId))
+                    continue;
                 clearTimeout(pending.timer);
-                this.pendingScreenshots.delete(reqId);
-                pending.reject(new Error('Agent disconnected'));
+                pendings.delete(reqId);
+                pending.reject(new Error(reason));
             }
         }
-        for (const [reqId, pending] of this.pendingUITrees.entries()) {
-            if (agentSessionIds.has(pending.sessionId)) {
-                clearTimeout(pending.timer);
-                this.pendingUITrees.delete(reqId);
-                pending.reject(new Error('Agent disconnected'));
+    }
+    /**
+     * The agent's socket went away. Keep its sessions and wait for that agent to come back, instead
+     * of ending them here — a restarting agent registers about a second later, and until #426 stage 3
+     * the close always won that race, so a restart cost the tester their place.
+     *
+     * The sessions stay exactly where they are. They are NOT moved to a holding structure of their
+     * own: `getAgentSocketsByIdentity` finds the returning agent's previous socket by walking
+     * `sessions` and reading `agentSocket`, so a session parked anywhere else is a session that can
+     * never be reclaimed.
+     *
+     * @returns whether this was an agent socket, matching `evictAgentSocket`'s contract — the close
+     *   handler uses it to decide whether to keep looking.
+     */
+    holdAgentSocket(ws) {
+        // Shutting down: nothing is coming back, and arming a timer here would leave it running after
+        // `stop()` resolved.
+        if (this.stopping)
+            return this.evictAgentSocket(ws);
+        const sessions = this.sessions.getAllByAgentSocket(ws);
+        if (sessions.length === 0) {
+            // No sessions to hold, but the socket may still own a resource entry — `evictAgentSocket`
+            // returns before dropping it in exactly this case.
+            this.sessions.removeResources(ws);
+            return false;
+        }
+        // Not held for the window: these were addressed to a process that is gone, and a returning
+        // agent is a new one that never saw them. Waiting would only delay the same failure.
+        this.rejectPending(new Set(sessions.map((s) => s.id)), 'Agent disconnected');
+        for (const s of sessions) {
+            if (s.browserSocket)
+                this.sendTo(s.browserSocket, { type: 'session:agent-away', sessionId: s.id });
+        }
+        const timer = setTimeout(() => {
+            this.agentHolds.delete(ws);
+            // Whatever is still on this socket never got reclaimed. A rebind moves sessions off it, so
+            // after a successful one this evicts nothing.
+            if (this.evictAgentSocket(ws))
+                logger.info(`agent did not come back within ${this.agentGraceMs}ms — session(s) ended`);
+            // Not inside that branch: `evictAgentSocket` returns before dropping resources when the
+            // socket has no sessions left, and the sessions can leave by routes other than a rebind —
+            // `session:end` among them. This is the last moment anything holds a reference to the dead
+            // socket, so it is the last chance to drop its entry.
+            this.sessions.removeResources(ws);
+        }, this.agentGraceMs);
+        this.agentHolds.set(ws, timer);
+        logger.info(`agent socket lost — holding ${sessions.length} session(s) for ${this.agentGraceMs}ms`);
+        return true;
+    }
+    /** Stop waiting on a socket, whether or not anything was reclaimed from it. */
+    releaseHold(ws) {
+        const timer = this.agentHolds.get(ws);
+        if (!timer)
+            return;
+        clearTimeout(timer);
+        this.agentHolds.delete(ws);
+    }
+    /**
+     * @param cause  `'disconnect'` — the socket closed. `'replaced'` — the same agent re-registered
+     *   and this is its previous socket. Only affects the log line: a restart otherwise reads as a
+     *   crash followed by a recovery, which is not what happened.
+     */
+    evictAgentSocket(ws, cause = 'disconnect') {
+        const agentSessions = this.sessions.getAllByAgentSocket(ws);
+        if (agentSessions.length === 0)
+            return false;
+        this.rejectPending(new Set(agentSessions.map((s) => s.id)), 'Agent disconnected');
+        // Tell whoever is attached before the session stops existing — after `remove()` the socket
+        // reference is gone. Without this the browser keeps a live socket addressed to a sessionId the
+        // relay no longer knows, so everything it sends is dropped as unknown and nothing streams back:
+        // the tab sits on "Waiting for first frame..." with no explanation (#426).
+        //
+        // `sendTo` skips a socket that is not OPEN, and a session nobody has joined has no
+        // `browserSocket` at all. An attached MCP client does have one and will receive this; its
+        // dispatcher drops messages no waiter matches, so that is harmless.
+        for (const s of agentSessions) {
+            if (s.browserSocket) {
+                this.sendTo(s.browserSocket, {
+                    type: 'session:terminated', sessionId: s.id, reason: 'agent-disconnected',
+                });
             }
         }
         for (const s of agentSessions)
             this.sessions.remove(s.id);
         this.sessions.removeResources(ws);
+        logger.info(cause === 'replaced'
+            ? `agent re-registered — ${agentSessions.length} previous session(s) replaced`
+            : `agent disconnected — ${agentSessions.length} session(s) ended`);
         return true;
     }
     handleAgentRegister(ws, msg) {
@@ -709,34 +926,109 @@ export class RelayServer {
         // its socket before creating the new ones. Identity is agentId (unique per Mac) when present,
         // else agentName. (Heartbeat backstop for never-reconnecting agents: #313.)
         const identity = msg.agentId ?? msg.agentName;
+        // Deduplicate first. Everything below is keyed by device id, so a payload naming one device
+        // twice would collapse to a single entry in `registeredSessions` while `create()` had already
+        // made two sessions — leaving one the agent is never told about. That is the same orphan the
+        // rebind exists to prevent, arriving by a different door.
+        const devices = [...new Map((msg.devices ?? []).map((d) => [d.id, d])).values()];
+        const agent = {
+            agentId: msg.agentId, agentName: msg.agentName,
+            agentPlatform: msg.platform, agentCapabilities: msg.capabilities,
+        };
+        // deviceId → the session id kept across the restart. Also the guard that a device is rebound at
+        // most once (#426): before rebinding existed, `create()` ran after every old session had been
+        // evicted, so one device could not be behind two sessions. It can now, and `list()` does not
+        // deduplicate — the second card would name a session the agent has never heard of, which is the
+        // symptom this whole change is fixing.
+        const rebound = new Map();
         if (identity) {
             for (const old of this.sessions.getAgentSocketsByIdentity(identity, msg.platform)) {
                 if (old === ws)
                     continue;
+                // Before any decision about what to rebind: the eviction below settles this socket either
+                // way, so the timer has nothing left to do. Releasing here rather than after a successful
+                // rebind also covers the case where nothing is rebound at all — a restart that reports a
+                // completely different device list still leaves a timer keyed to a dead socket.
+                this.releaseHold(old);
+                for (const s of this.sessions.getAllByAgentSocket(old)) {
+                    if (rebound.has(s.deviceId))
+                        continue;
+                    const device = devices.find((d) => d.id === s.deviceId);
+                    // The device is gone from this agent's list — unplugged, deleted, renamed away. Leave it
+                    // for the eviction below, which tells the browser the session ended.
+                    if (!device)
+                        continue;
+                    this.sessions.rebind(s.id, ws, device, agent);
+                    rebound.set(s.deviceId, s.id);
+                }
                 // Evict before terminate: the old socket's close fires async, by which point its sessions are
                 // gone and its in-flight screenshots would be undiscoverable — reject them here instead.
-                this.evictAgentSocket(old);
+                // The rebound sessions have already moved off `old`, so this no longer covers them.
+                this.evictAgentSocket(old, 'replaced');
                 old.terminate();
             }
         }
-        const sessionIds = this.sessions.create(ws, msg.devices ?? [], msg.agentName, msg.platform, msg.agentId);
-        const registeredSessions = (msg.devices ?? []).map((d, i) => ({
-            deviceId: d.id,
-            sessionId: sessionIds[i],
-        }));
-        ws.send(JSON.stringify({ type: 'agent:registered', registeredSessions }));
+        // Their in-flight requests are addressed to a process that is gone, and the eviction above can
+        // no longer see them. Nothing else would ever settle these.
+        if (rebound.size > 0)
+            this.rejectPending(new Set(rebound.values()), 'Agent restarted');
+        // A device can be back under an agent this session cannot be rebound to — identity is
+        // `agentId ?? agentName`, and the upgrade that prompted the restart is often the one that
+        // starts sending an agentId. The device is demonstrably present, so holding its old session
+        // any longer strands that viewer while someone else picks the very same simulator. End it now
+        // and say so, which is what would have happened before the hold existed.
+        for (const d of devices) {
+            if (rebound.has(d.id))
+                continue;
+            for (const s of this.sessions.getAllByDeviceId(d.id)) {
+                if (s.agentSocket.readyState === WebSocket.OPEN)
+                    continue;
+                if (s.browserSocket) {
+                    this.sendTo(s.browserSocket, { type: 'session:terminated', sessionId: s.id, reason: 'agent-disconnected' });
+                }
+                this.sessions.remove(s.id);
+            }
+        }
+        // Only devices without a surviving session get a new one. Passing all of them here is what
+        // would produce the duplicate card described above.
+        const fresh = devices.filter((d) => !rebound.has(d.id));
+        const freshIds = this.sessions.create(ws, fresh, msg.agentName, msg.platform, msg.agentId, msg.capabilities);
+        const byDeviceId = new Map(rebound);
+        fresh.forEach((d, i) => byDeviceId.set(d.id, freshIds[i]));
+        // Keyed by deviceId, not by position. The old form paired `msg.devices[i]` with `sessionIds[i]`,
+        // which only held while every device got a session — now that some are rebound, the arrays have
+        // different lengths and index alignment would hand the agent someone else's session id.
+        const registeredSessions = devices.map((d) => ({ deviceId: d.id, sessionId: byDeviceId.get(d.id) }));
+        this.sendTo(ws, { type: 'agent:registered', registeredSessions });
+        // After the state is final: the browser answers this with `device:boot` on the same session id.
+        for (const sessionId of rebound.values()) {
+            const s = this.sessions.get(sessionId);
+            if (s?.browserSocket) {
+                this.sendTo(s.browserSocket, { type: 'session:rebound', sessionId, capabilities: msg.capabilities ?? [] });
+            }
+        }
+        if (rebound.size > 0)
+            logger.info(`agent restarted — ${rebound.size} session(s) kept across the restart`);
+        // The startup banner prints "Waiting for agents..." once and then the relay says nothing either
+        // way, so a terminal gives no signal about whether an agent is attached. One line per
+        // transition, matching the disconnect line in evictAgentSocket.
+        logger.info(`agent connected: ${msg.agentName ?? msg.agentId ?? 'unknown'} (${msg.platform ?? 'unknown'}) — ${registeredSessions.length} device(s)`);
     }
     handleSessionStart(ws, msg) {
         const session = this.sessions.get(msg.sessionId);
         if (!session) {
-            ws.send(JSON.stringify({ type: 'error', message: 'Session not found' }));
+            this.sendTo(ws, { type: 'error', message: 'Session not found' });
             return;
         }
-        const resources = this.sessions.getResources(session.agentSocket);
+        // Read before the resource gate, and answered before it too. The gate would otherwise read the
+        // dead socket's last sample — and an overloaded Mac is a common reason to restart an agent, so
+        // the tester would be told the Mac is exhausted at the exact moment it is recovering.
+        const agentAway = session.agentSocket.readyState !== WebSocket.OPEN;
+        const resources = agentAway ? undefined : this.sessions.getResources(session.agentSocket);
         if (resources) {
             const memPercent = (resources.memUsedMB / resources.memTotalMB) * 100;
             if (resources.cpuPercent > RESOURCE_THRESHOLD || memPercent > RESOURCE_THRESHOLD) {
-                ws.send(JSON.stringify({ type: 'error', message: 'Agent resources exhausted' }));
+                this.sendTo(ws, { type: 'error', message: 'Agent resources exhausted' });
                 return;
             }
         }
@@ -744,71 +1036,104 @@ export class RelayServer {
             this.sessions.join(msg.sessionId, ws);
         }
         catch {
-            ws.send(JSON.stringify({ type: 'error', message: 'Session busy' }));
+            this.sendTo(ws, { type: 'error', message: 'Session busy' });
+            return;
+        }
+        // Include the agent's capabilities so the viewer knows up front what is implemented on
+        // the other end — an agent that predates a feature omits it, and the dashboard degrades
+        // deliberately instead of inferring anything from a timeout.
+        this.sendTo(ws, {
+            type: 'session:joined', sessionId: msg.sessionId, capabilities: session.agentCapabilities ?? [],
+        });
+        if (agentAway) {
+            // Joining into a held session. Refusing instead would be worse than it sounds: the viewer
+            // sends `session:start` exactly once per reconnect and ignores a plain `error`, so a browser
+            // blip inside the window would leave a tab that no later `session:rebound` can reach — it is
+            // addressed to `browserSocket`, which the refusal never set. Saying what is happening keeps
+            // the tab inside the contract instead.
+            //
+            // Everything below describes the agent that went away, so it stops here. The viewer will get
+            // it all again from the boot it sends on `session:rebound`.
+            this.sendTo(ws, { type: 'session:agent-away', sessionId: msg.sessionId });
             return;
         }
-        ws.send(JSON.stringify({ type: 'session:joined', sessionId: msg.sessionId }));
         if (session.chromeData) {
-            ws.send(JSON.stringify({ type: 'session:chrome', payload: session.chromeData }));
+            this.sendTo(ws, { type: 'session:chrome', payload: session.chromeData });
         }
         if (session.deviceInfo) {
-            ws.send(JSON.stringify({ type: 'session:deviceInfo', payload: session.deviceInfo }));
+            this.sendTo(ws, { type: 'session:deviceInfo', payload: session.deviceInfo });
         }
-        // Replay device:ready if the device is already booted (browser WS blip reconnect)
-        if (session.deviceStatus === 'booted') {
-            ws.send(JSON.stringify({ type: 'device:ready', payload: { deviceId: session.deviceId } }));
+        // Replay device:ready only if this session actually announced one (browser WS blip reconnect).
+        // Not `deviceStatus`: that starts from the agent's `simctl list` snapshot, so a session for a
+        // simulator that was already running would fire this before the agent had done anything —
+        // telling the viewer a stream exists when none does (#440).
+        if (session.readySent) {
+            this.sendTo(ws, { type: 'device:ready', payload: { deviceId: session.deviceId } });
             // (Re)joining a live stream: ask the agent for an IDR so this viewer gets a decodable
             // keyframe immediately, instead of waiting for the next periodic one — and so it isn't
             // left blank when the encoder is static-skipping an unchanged screen. Agents that don't
             // support on-demand IDR ignore the message.
             if (session.agentSocket.readyState === WebSocket.OPEN) {
-                session.agentSocket.send(JSON.stringify({ type: 'stream:request-idr', sessionId: session.id }));
+                this.sendTo(session.agentSocket, { type: 'stream:request-idr', sessionId: session.id });
             }
         }
     }
+    /** Relay looks up file_path from DB and enriches it for the agent.
+     *
+     *  Every exit carries the request's `sessionId`, including the failures. A dashboard viewer holds
+     *  one session per socket, so an uncorrelated error still lands somewhere sensible — but an MCP
+     *  caller waits for the reply matching its own sessionId, so anything else is indistinguishable
+     *  from silence and it waits out the deadline (#445). `Session not found` is app-specific for the
+     *  same reason: a generic `error` cannot be correlated by construction. */
     handleBrowserAppInstall(ws, msg) {
-        // Relay looks up file_path from DB and enriches; includes sessionId for response routing
-        const session = this.sessions.get(msg.sessionId);
-        if (!session) {
-            ws.send(JSON.stringify({ type: 'error', message: 'Session not found' }));
-            return;
-        }
+        const sessionId = msg.sessionId;
+        const fail = (message) => this.sendTo(ws, { type: 'app:install-error', sessionId, message });
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return fail('Session not found');
+        // `JSON.parse` does not honour `RelayMessage`, so buildId is whatever the sender put there.
+        // better-sqlite3 binds a missing value as NULL but *throws* on an object or array — and that
+        // exception is swallowed by the message-loop catch, which is the silence this PR exists to
+        // remove. Checked here rather than trusted; general inbound validation is #444.
+        if (!Number.isInteger(msg.buildId))
+            return fail('Build not found');
         const build = getDb()
             .prepare('SELECT file_path, bundle_id FROM builds WHERE id = ?')
             .get(msg.buildId);
-        if (!build) {
-            ws.send(JSON.stringify({ type: 'app:install-error', message: 'Build not found' }));
-            return;
-        }
-        if (session.agentSocket.readyState === WebSocket.OPEN) {
-            session.agentSocket.send(JSON.stringify({
-                type: 'app:install',
-                sessionId: msg.sessionId,
-                payload: { filePath: build.file_path, bundleId: build.bundle_id },
-            }));
-        }
+        if (!build)
+            return fail('Build not found');
+        // Answer now rather than letting the caller time out — the same shape as `open-url` above.
+        if (session.agentSocket.readyState !== WebSocket.OPEN)
+            return fail('agent offline');
+        this.sendTo(session.agentSocket, {
+            type: 'app:install',
+            sessionId,
+            payload: { filePath: build.file_path, bundleId: build.bundle_id },
+        });
     }
+    /** Relay looks up bundle_id from DB. Same correlation rules as `handleBrowserAppInstall`. */
     handleBrowserAppLaunch(ws, msg) {
-        // Relay looks up bundle_id from DB; includes sessionId for response routing
-        const session = this.sessions.get(msg.sessionId);
-        if (!session) {
-            ws.send(JSON.stringify({ type: 'error', message: 'Session not found' }));
-            return;
-        }
+        const sessionId = msg.sessionId;
+        const fail = (message) => this.sendTo(ws, { type: 'app:launch-error', sessionId, message });
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return fail('Session not found');
+        // See handleBrowserAppInstall — an object here throws inside the driver and the exception is
+        // swallowed upstream.
+        if (!Number.isInteger(msg.buildId))
+            return fail('Bundle ID not available for this build');
         const build = getDb()
             .prepare('SELECT bundle_id FROM builds WHERE id = ?')
             .get(msg.buildId);
-        if (!build?.bundle_id) {
-            ws.send(JSON.stringify({ type: 'app:launch-error', message: 'Bundle ID not available for this build' }));
-            return;
-        }
-        if (session.agentSocket.readyState === WebSocket.OPEN) {
-            session.agentSocket.send(JSON.stringify({
-                type: 'app:launch',
-                sessionId: msg.sessionId,
-                payload: { bundleId: build.bundle_id },
-            }));
-        }
+        if (!build?.bundle_id)
+            return fail('Bundle ID not available for this build');
+        if (session.agentSocket.readyState !== WebSocket.OPEN)
+            return fail('agent offline');
+        this.sendTo(session.agentSocket, {
+            type: 'app:launch',
+            sessionId,
+            payload: { bundleId: build.bundle_id },
+        });
     }
     async handleGetScreenshot(req, res, params) {
         if (!requireViewAuth(req, res))
@@ -854,7 +1179,7 @@ export class RelayServer {
                 },
                 timer,
             });
-            session.agentSocket.send(JSON.stringify({ type: 'screenshot:request', sessionId, requestId, format }));
+            this.sendTo(session.agentSocket, { type: 'screenshot:request', sessionId, requestId, format });
         });
     }
     async handleGetUITree(req, res, params) {
@@ -897,7 +1222,7 @@ export class RelayServer {
                 },
                 timer,
             });
-            session.agentSocket.send(JSON.stringify({ type: 'ui:tree:request', sessionId, requestId }));
+            this.sendTo(session.agentSocket, { type: 'ui:tree:request', sessionId, requestId });
         });
     }
     handleUITreeResponse(msg) {