@tapflowio/relay 0.18.0 → 0.20.0

package/dist/RelayServer.js

@@ -6,6 +6,7 @@ import path from 'path';
 import { randomUUID } from 'crypto';
 import { WebSocketServer, WebSocket } from 'ws';
 import { SessionManager } from './SessionManager.js';
+import { directionOf, parseInbound } from '@tapflowio/protocol/validate';
 import { Router, json } from './router.js';
 import { requireViewAuth, requireAuth, getAuth, verifyPat } from './middleware/auth.js';
 import { classifyConnection } from './lib/connectionAuth.js';
@@ -13,6 +14,7 @@ import { resolveClientAddress } from './lib/clientAddress.js';
 import { resolveCorsHeaders } from './lib/cors.js';
 import { isCsrfBlocked } from './lib/csrf.js';
 import { pickLanAddress } from './lib/lanAddress.js';
+import { createTrailingRequester, systemTimerScheduler } from './lib/trailingRequester.js';
 import { getDb } from './db.js';
 import { handleLogin, handleLogout, handleMe, handleChangePassword, handleInit, handleAuthStatus } from './api/auth.js';
 import { handleVerify, handleAccept } from './api/invitations.js';
@@ -38,7 +40,14 @@ export function isExternalAddress(addr) {
 }
 // Min gap between IDR requests per session — one IDR resyncs the stream, so avoid
 // spamming the agent in the frames between request and the IDR arriving.
-const IDR_REQUEST_THROTTLE_MS = 500;
+/** Exported for the re-join test, which pins both edges of this window rather than hardcoding 500 —
+ *  a test carrying its own copy of the number passes when the constant moves, which is the drift the
+ *  wire-contract work keeps finding. Not re-exported from the package index. */
+export const IDR_REQUEST_THROTTLE_MS = 500;
+/** The same window for `network:request-state`, and a **separate constant on purpose**: the two share
+ *  a number today and not a policy. IDR drops inside the window; this one coalesces onto its trailing
+ *  edge (see `networkStateRequester`). Sharing the constant would mean tuning one tunes the other. */
+export const NETWORK_STATE_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).
@@ -46,6 +55,24 @@ const HEARTBEAT_MS = 30_000;
 // 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;
+/**
+ * What a buffer actually is, from its magic bytes, or `null` for anything else.
+ *
+ * Duplicated in `mcp-server` rather than shared: `protocol`'s entry must erase under `import type`
+ * so it cannot hold a runtime value, and `mcp-server` does not depend on `agent-core`. The same
+ * situation as `correlatesWith` across the two clients, and the same answer — each copy has tests.
+ * These two signatures have not changed since 1992 and 1996, so there is little for them to drift to.
+ */
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+function sniffImageFormat(buf) {
+    // All eight signature bytes — see the note on the `mcp-server` copy for why the trailing four earn
+    // their place. Here a false `png` would report a mismatch that is not one.
+    if (buf.length >= PNG_SIGNATURE.length && PNG_SIGNATURE.every((b, i) => buf[i] === b))
+        return 'png';
+    if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xd8)
+        return 'jpeg';
+    return null;
+}
 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';
@@ -78,23 +105,51 @@ const RESOURCE_THRESHOLD = Number.isFinite(_parsedThreshold) ? _parsedThreshold
 // 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',
-    'app:clear-state-done', 'app:clear-state-error',
-    'device:booting', 'device:boot-error', 'device:shutdown-done', 'device:ready',
-    '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: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',
-]);
+/** Why a session is not this socket's to command. One reason, two prose strings — the treatment `#492`
+ *  settled for `agent offline` / `Session not found`: telling a caller the session is in use when it is
+ *  idle steers it off a device it could have had. Shared so the two never drift. */
+function ownershipRefusal(session) {
+    return session.browserSocket ? 'session held by another client' : 'session not joined';
+}
+/**
+ * The owner key a connection speaks for, from the authenticated user and the client id it claimed.
+ *
+ * **Both halves, and a pure function so both can be tested.** The user id is what keeps a leaked client id
+ * useless to anyone else — without it this would be the relay's first ownership claim a caller can forge,
+ * where socket identity could not be. It comes from the cookie *or* the PAT: reading only the cookie would
+ * have made every agent and every non-browser client `anon:`, which is the population most likely to have
+ * its handshake URL end up in a reverse proxy's access log. The mint is what removes the fallback branch: a connection that
+ * claims nothing gets an identity of its own, which is per-socket, which is the behaviour ownership had
+ * before it moved off the socket.
+ *
+ * Exported for the test that holds the pairing. Inline in the handler it was unreachable without standing
+ * up an authenticated handshake, and a mutation dropping the user id survived the whole suite.
+ */
+export function ownerKeyFor(userId, claimed) {
+    const user = String(userId ?? 'anon');
+    // **Mintedness is a separate field, not a marker inside the key.** A first version prefixed the mint
+    // with `minted-` and had `mayShutDown` recover the fact with `includes(':minted-')` — which the client
+    // controls, because `claimed` comes straight off the handshake query and is never validated. Connecting
+    // as `?client=minted-1` produced `anon:minted-1` and silently disabled the shutdown gate for that
+    // holder; `?client=x:minted-y` did it while keeping a real user id, so a *different* user could then
+    // power the device off. Encoding a security-relevant fact in a caller-supplied string is the forgery
+    // this whole key was introduced to avoid, reintroduced one layer down.
+    return { key: `${user}:${claimed || randomUUID()}`, user, minted: !claimed };
+}
+/** One line per rejecting socket per second, at most. See `RelayServer.logInboundRejection`. */
+const REJECT_LOG_INTERVAL_MS = 1_000;
+/** What the door refused, as one line. The throttling that decides whether to write it is the
+ *  caller's, because it is per socket and this function has no state. */
+function describeRejection(failure, suppressed) {
+    if (failure.reason === 'not-an-object')
+        return null;
+    const also = suppressed > 0 ? ` (+${suppressed} more from this socket in the last second)` : '';
+    if (failure.reason === 'unknown-type') {
+        return `[tapflow] inbound frame of unknown type ${failure.type} — dropped${also}`;
+    }
+    const outcome = failure.reason === 'bad-payload' ? 'refused, and the sender told' : 'dropped';
+    return `[tapflow] inbound ${failure.type} does not match the contract — ${outcome}${also}:\n${failure.detail}`;
+}
 export class RelayServer {
     options;
     httpServer;
@@ -111,8 +166,36 @@ export class RelayServer {
     purgeBuildsTimer = null;
     flushResourcesTimer = null;
     heartbeatTimer = null;
-    // Liveness per socket for the heartbeat sweep. WeakMap → no manual cleanup on close (GC handles it).
-    wsAlive = new WeakMap();
+    /**
+     * When each socket last answered a ping. WeakMap → no manual cleanup on close (GC handles it).
+     *
+     * **A timestamp, not the swept boolean it replaced.** That flag was set `false` for *every* socket at the
+     * start of each sweep and back to `true` only when the pong returned, so a perfectly healthy socket read
+     * as dead for the whole round trip — a normal state on a 30s cycle rather than an edge case. And the
+     * window is longest for exactly the socket that matters: video goes out on `browserSocket`, and the ping
+     * is written behind whatever is already queued there, so an external viewer's pong can take a second or
+     * two.
+     *
+     * That was invisible while the flag only decided termination, because a sweep that finds `false` has by
+     * definition already waited a full interval. Reading it to answer *"is this holder alive right now"* is
+     * what exposes it: occupancy would hand a live tester's session away, and `busy` would flash a device as
+     * free every 30 seconds — the dashboard polls every 5s and `disabled={isBusy}`, so the UI would open the
+     * button rather than a race being needed.
+     */
+    lastPongAt = new WeakMap();
+    /**
+     * Who each socket speaks for — `<userId>:<clientId>`, the key a session's ownership is compared against.
+     *
+     * **Two parts, and both are load-bearing.** The client id is supplied by the caller (`?client=`), so on
+     * its own it is the relay's first *forgeable* ownership claim: today's ownership is socket identity,
+     * which nothing can spoof. Binding it to the authenticated user — which `getAuth` already resolves at
+     * the handshake — keeps a leaked id useless to anyone else's account.
+     *
+     * **A connection that supplies no client id is given one**, rather than falling back to socket identity.
+     * There is deliberately no fallback branch: one model, and a client that does not identify itself gets an
+     * identity that happens to be per-socket, which is exactly today's behaviour.
+     */
+    ownerKey = new WeakMap();
     dropHandlers = new Map();
     // Per-session throttled drop-warn for audio (kept separate so audio drops don't mask video drops in logs).
     audioDropHandlers = new Map();
@@ -120,7 +203,13 @@ export class RelayServer {
     droppers = new Map();
     // Per-session throttled "request an IDR from the agent" callbacks (drop recovery).
     idrRequesters = new Map();
+    /** Unlike `idrRequesters` these hold a timer, which is why the value is not a bare closure — see
+     *  `forgetSessionState`. */
+    networkStateRequesters = new Map();
     wsRoles = new Map();
+    /** Per-socket throttle state for `logInboundRejection`. A `WeakMap` so a closed socket's entry goes
+     *  with the socket — there is no cleanup to forget, unlike the maps keyed by session id nearby. */
+    rejectionLog = new WeakMap();
     // 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
@@ -328,6 +417,14 @@ export class RelayServer {
         for (const timer of this.agentHolds.values())
             clearTimeout(timer);
         this.agentHolds.clear();
+        // Same argument one line up. **Not** because the send would land — `sendTo` drops a socket that is
+        // not OPEN, which is why `fire` carries no check of its own — but because `unref()` only excuses a
+        // timer from keeping the process alive, and the test runner's process outlives the server anyway.
+        // An armed edge therefore still runs, holding a closure over the session map of a relay that has
+        // already stopped.
+        for (const requester of this.networkStateRequesters.values())
+            requester.dispose();
+        this.networkStateRequesters.clear();
         return new Promise((resolve, reject) => {
             this.wss.clients.forEach((ws) => ws.terminate());
             this.wss.close(() => {
@@ -341,25 +438,86 @@ export class RelayServer {
     // Terminate sockets that missed the previous pong; ping the rest. Covers all roles via wss.clients.
     runHeartbeat(clients = this.wss.clients) {
         for (const ws of clients) {
-            if (this.wsAlive.get(ws) === false) {
+            if (!this.isAlive(ws)) {
                 ws.terminate();
                 continue;
             }
-            this.wsAlive.set(ws, false);
             if (ws.readyState === WebSocket.OPEN)
                 ws.ping();
         }
     }
+    /**
+     * Has this socket answered recently enough to be treated as present?
+     *
+     * `1.5` intervals rather than one: a pong that arrives *during* a sweep must not be read as late, and a
+     * socket pinged at the end of one interval has until halfway through the next. The cost is that a
+     * genuinely dead socket is recognised in up to 45s instead of 30 — **and 45 seconds with no false
+     * negative beats 30 with one every cycle**, because a false negative here does not merely delay: it
+     * hands a live tester's session to whoever asked next.
+     */
+    isAlive(ws) {
+        const at = this.lastPongAt.get(ws);
+        // **No entry means just connected, not dead.** `handleConnection` seeds one, but a socket is in
+        // `wss.clients` from the upgrade, so there is a tick where a sweep could see it first — and the flag
+        // this replaced was explicitly safe there ("alive until proven otherwise"). Reading absence as dead
+        // would terminate a connection that had done nothing wrong, and occupancy would read the same absence
+        // as a free session.
+        if (at === undefined)
+            return true;
+        return Date.now() - at <= HEARTBEAT_MS * 1.5;
+    }
     // 갱신된 cert를 재시작 없이 핫스왑한다(https 종단일 때만 의미 있음).
     updateTlsContext(material) {
         if (this.httpServer instanceof https.Server) {
             this.httpServer.setSecureContext({ cert: material.cert, key: material.key });
         }
     }
-    // Throttled callback asking the session's agent for an on-demand IDR (fast drop recovery); ignored by agents that don't support it.
-    makeIdrRequester(sessionId) {
+    /**
+     * Drop every per-session stream record keyed by this id.
+     *
+     * **Four maps that have to move together, called from four places that did not.** They were deleted
+     * inline in `session:end` and `session:leave` and nowhere else, so a session ending any other way —
+     * the agent going away, the idle timer, a device disappearing from a re-register — left all four
+     * behind for the life of the process.
+     *
+     * Pre-existing, and this slice is what makes it worth fixing here rather than filing: `idrRequesters`
+     * used to be populated only by the binary drop path, i.e. only under backpressure, and a re-join now
+     * creates an entry for any streaming session (#515). The leak went from rare to ordinary.
+     *
+     * **Now five maps, and the fifth is not dropped the same way.** `networkStateRequesters` holds a
+     * *coalescing* requester, so its closure owns a pending `setTimeout` — and deleting a map entry does
+     * not cancel a timer. Leaving it armed is not a leak but a double send: `session:leave` followed by a
+     * re-join inside the window fires the orphaned trailing edge *and* the new requester's leading edge,
+     * which is the second budget for one session that this map exists to prevent. Hence `dispose()`
+     * rather than `delete` alone. It was named `forgetSessionStreamState` while all four were stream
+     * records; the network requester is not one, so the name lost the word rather than the entry
+     * lost the function.
+     */
+    forgetSessionState(sessionId) {
+        this.dropHandlers.delete(sessionId);
+        this.audioDropHandlers.delete(sessionId);
+        this.droppers.delete(sessionId);
+        this.idrRequesters.delete(sessionId);
+        this.networkStateRequesters.get(sessionId)?.dispose();
+        this.networkStateRequesters.delete(sessionId);
+    }
+    /**
+     * Throttled callback asking the session's agent for an on-demand IDR (fast drop recovery); ignored by
+     * agents that don't support it.
+     *
+     * **One per session, and the construction is folded in here on purpose.** The throttle is `lastAt` in
+     * the closure, so a second requester for the same session is a second budget — which is what the
+     * `idrRequesters` map exists to prevent, and it prevented it only as long as every caller remembered
+     * to look the session up first. There are two callers now (the drop path and the re-join in
+     * `handleSessionStart`), and a separate `makeIdrRequester` was a factory either of them could reach
+     * past the map. Measured: calling it directly from one caller left every test green.
+     */
+    idrRequester(sessionId) {
+        const existing = this.idrRequesters.get(sessionId);
+        if (existing)
+            return existing;
         let lastAt = 0;
-        return () => {
+        const requester = () => {
             const now = Date.now();
             if (now - lastAt < IDR_REQUEST_THROTTLE_MS)
                 return;
@@ -369,6 +527,50 @@ export class RelayServer {
                 this.sendTo(session.agentSocket, { type: 'stream:request-idr', sessionId });
             }
         };
+        this.idrRequesters.set(sessionId, requester);
+        return requester;
+    }
+    /**
+     * Throttled callback asking the session's agent to re-read and report the device's network
+     * condition (#614); ignored by agents that don't support it.
+     *
+     * **Coalescing, where `idrRequester` above drops — and the difference is not a preference.** A
+     * dropped IDR request costs nothing: the next periodic keyframe repairs it. Nothing re-produces a
+     * `network:state`, so a request dropped inside the window leaves that viewer rendering "unknown"
+     * for the life of the session. The trailing edge fires after the last join in a burst, and the
+     * relay addresses the reply to whichever socket holds the session *when it arrives* — so the
+     * viewer that ends up watching is the one served, which a leading edge cannot promise.
+     *
+     * The burst this is for is the dirty blip, not two people: `join()` refuses a live holder, and a
+     * clean `session:leave` runs `forgetSessionState` and builds a fresh requester. A browser socket
+     * that dies in its close handler does neither, so `lastAt` survives into the re-join — which is
+     * the very path this slice exists to serve.
+     *
+     * One per session, constructed here, for the reason written on `idrRequester`: the throttle lives
+     * in the closure, so a second requester is a second budget.
+     */
+    networkStateRequester(sessionId) {
+        const existing = this.networkStateRequesters.get(sessionId);
+        if (existing)
+            return existing;
+        const requester = createTrailingRequester({
+            scheduler: systemTimerScheduler,
+            windowMs: NETWORK_STATE_REQUEST_THROTTLE_MS,
+            fire: () => {
+                const session = this.sessions.get(sessionId);
+                // `sendTo` already drops a socket that is not OPEN, so a closed agent needs no check here —
+                // an earlier draft duplicated it and no mutation could tell the copy from the original.
+                //
+                // The lookup is the guard that remains, and it should be unreachable: **every path that removes
+                // a session runs `forgetSessionState`, which disposes this timer.** It is kept as the cheap half
+                // of that pair rather than as a live case — a trailing edge is the one call here that outlives
+                // the statement scheduling it, so the invariant holding is worth not assuming.
+                if (session)
+                    this.sendTo(session.agentSocket, { type: 'network:request-state', sessionId });
+            },
+        });
+        this.networkStateRequesters.set(sessionId, requester);
+        return requester;
     }
     // Extracted so tests can simulate non-loopback origins (all test traffic is loopback).
     remoteAddressOf(request) {
@@ -411,9 +613,19 @@ export class RelayServer {
             return;
         }
         this.wsExternal.set(ws, isExternalAddress(addr));
-        // Heartbeat liveness: alive until proven otherwise; each pong revives it (see runHeartbeat).
-        this.wsAlive.set(ws, true);
-        ws.on('pong', () => this.wsAlive.set(ws, true));
+        // Read from the upgrade URL because a browser cannot set WebSocket headers, and because it has to be
+        // known **per connection** rather than per join: the dashboard socket that sends the unmount teardown
+        // never joins anything. `new URL` against a dummy base — `request.url` is path-relative.
+        const claimed = new URL(request.url ?? '/', 'http://relay').searchParams.get('client');
+        // **The PAT counts as a principal, and a first version dropped it.** `getAuth` reads the cookie only,
+        // so every agent, `mcp-server` and `flow-runner` connection would have been `anon:` — and the whole
+        // point of pairing the claim with a user is that a leaked client id is useless to anyone else. Two
+        // processes on the same PAT are the same principal, which is right; two on different PATs are not,
+        // which is what this restores. `pat` is already resolved above and was being discarded.
+        this.ownerKey.set(ws, ownerKeyFor(getAuth(request)?.userId ?? pat?.userId, claimed));
+        // Heartbeat liveness: a fresh socket counts as having just answered, and each pong renews it.
+        this.lastPongAt.set(ws, Date.now());
+        ws.on('pong', () => this.lastPongAt.set(ws, Date.now()));
         if (decision.role === 'browser')
             this.wsRoles.set(ws, 'browser');
         // 'first-message' → role is determined by the first message (agent:register / stream:register)
@@ -447,11 +659,7 @@ export class RelayServer {
                         dropper = createKeyframeAwareSender();
                         this.droppers.set(session.id, dropper);
                     }
-                    let requestIdr = this.idrRequesters.get(session.id);
-                    if (!requestIdr) {
-                        requestIdr = this.makeIdrRequester(session.id);
-                        this.idrRequesters.set(session.id, requestIdr);
-                    }
+                    const requestIdr = this.idrRequester(session.id);
                     // JPEG and H.264 IDRs are resync points; only P-frames must wait for a keyframe after a drop.
                     let isKeyframe = true;
                     if (hasEnvelope(frameBuf)) {
@@ -470,20 +678,48 @@ export class RelayServer {
             catch {
                 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)
+            // **The frame becomes a union here, and not by a cast.** `#550` asked for `RelayMessage` — a flat
+            // interface where `type` is the only required member — to become a discriminated union, and doing
+            // that with an `as` at this line would have been a downgrade: the visible cast at the
+            // `session:chrome` handler would have turned into an invisible `msg.payload`, with the compiler
+            // vouching for JSON that arrived over a socket. So the union is the *product* of a parse (#444),
+            // and what the parse could not prove is not in the type. Non-objects, unknown types and shape
+            // failures are all refused in there — including the bare `null` / number / string that
+            // `JSON.parse` returns without throwing.
+            const inbound = parseInbound(parsed);
+            // **Role and direction are settled before the shape is, and the order is load-bearing.** A first
+            // draft rejected a malformed frame and returned, which silently dropped an agent-only type a
+            // browser socket had spoofed *badly* — the 1008 that closes such a socket never fired, so the
+            // spoofer kept its connection. The direction is a fact about the `type` alone, and the type is
+            // known on a shape failure too, so nothing about that check needs the payload to be valid.
+            // **Logged before the gate, not after it.** A first draft called `settleRole` first and logged in
+            // the `!ok` branch below it — which never ran for two of the three failure reasons, because
+            // `settleRole` returns `false` for them. The case that mattered was a malformed handshake on a
+            // role-less socket: dropped in silence, which is precisely the agent-registration skew this log
+            // exists to make visible.
+            if (!inbound.ok)
+                this.logInboundRejection(ws, inbound);
+            if (!this.settleRole(ws, inbound))
                 return;
-            const msg = parsed;
+            if (!inbound.ok) {
+                // **After the role gate, never before it**, so a browser spoofing an agent-only type gets 1008
+                // and no reply. That is the whole of the claim: an agent- or stream-role socket sending a
+                // malformed browser request passes the gate and *is* answered, because the gate only refuses a
+                // `browser` role sending a non-browser type. Harmless, and worth stating rather than implying
+                // otherwise — such a socket already gets an answer on the well-formed path (`refuseInput` tells
+                // it `not-session-owner`), and this reply says strictly less than that one.
+                if (inbound.reason === 'bad-payload')
+                    this.refuseMalformed(ws, inbound);
+                return;
+            }
             try {
-                this.route(ws, msg);
+                this.route(ws, inbound.msg, inbound.raw);
             }
             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);
+                logger.error(`route failed for ${inbound.msg.type}:`, e);
             }
         });
         ws.on('close', () => {
@@ -493,48 +729,137 @@ export class RelayServer {
             // coming back (#426), rather than ending them where they stand.
             if (this.holdAgentSocket(ws))
                 return;
-            // Stream socket disconnected → clear the streamSocket reference
+            // Stream socket disconnected → clear the streamSocket reference.
+            //
+            // **No `return`.** One socket can be both: the role gate refuses a `browser`-role socket sending a
+            // non-browser type, and says nothing about a `stream`-role one sending `session:start` — so a
+            // socket that registered a stream first can go on to hold sessions. Returning here skipped the
+            // release below for exactly those, which is the state the loop exists to end.
             const streamSession = this.sessions.getByStreamSocket(ws);
-            if (streamSession) {
+            if (streamSession)
                 this.sessions.clearStreamSocket(streamSession.id);
+            // Browser socket disconnected → release **every** session it held, each with its own idle timer.
+            //
+            // `getByBrowserSocket` used to answer with one session because the index held one, and a socket
+            // holding several is not exotic: `mcp-server` runs one socket for the whole process and joins a
+            // session per device. So closing it released the last join and left the rest bound to a dead
+            // socket — `busy: true` forever, no timer, and their devices booted with nobody watching (#507).
+            //
+            // The `stopping` guard is `holdAgentSocket`'s, for its stated reason: `stop()` terminates every
+            // client, and a timer armed on the way out survives the promise `stop()` resolves. That was one
+            // stray timer per relay before this loop and is one per held session after it.
+            if (this.stopping)
                 return;
-            }
-            // Browser socket disconnected → clear browserSocket, start idle timer
-            const browserSession = this.sessions.getByBrowserSocket(ws);
-            if (browserSession) {
-                this.sessions.clearBrowser(browserSession.id, () => {
-                    const session = this.sessions.get(browserSession.id);
-                    if (session?.agentSocket.readyState === WebSocket.OPEN) {
-                        this.sendTo(session.agentSocket, {
-                            type: 'device:shutdown',
-                            sessionId: session.id,
-                            payload: { deviceId: session.deviceId },
-                        });
-                    }
-                });
+            for (const held of this.sessions.getByBrowserSocket(ws)) {
+                this.sessions.clearBrowser(held.id, () => this.idleShutdown(held.id));
             }
         });
     }
-    route(ws, msg) {
-        // Assign role on the first message for local no-auth connections (agents / streams)
+    /**
+     * @param msg  what the door proved — see `parseInbound`. An Envelope-tier member arrives carrying
+     *             `type` and its correlators and nothing else, so a payload the parser did not check
+     *             cannot be read off it.
+     * @param raw  the frame as it arrived. Agent-origin messages are **forwarded as this**, so a field
+     *             a newer agent added survives a relay that does not know it — `z.object` strips, and
+     *             stripping is wrong in the one direction where the sender is the more recently
+     *             updated side. Browser-origin messages are forwarded as `msg` instead, so a key an attacker
+     *             appended does not survive. It is also where the two stored Envelope payloads come
+     *             from, which is the point: a value read off `raw` is one the parser did not vouch for.
+     */
+    /**
+     * Assign this socket's role if it does not have one, then refuse a message its role may not send.
+     *
+     * @returns `false` when the caller must stop — the socket was closed, or the frame is a failed
+     *          handshake that must not confer a role.
+     */
+    settleRole(ws, inbound) {
+        // Every reason that carries a type, which is all of them but the two that have none to carry.
+        // Missing `bad-payload` here returned `false` before the caller could answer, so the thirteen
+        // answerable requests were classified correctly and then dropped anyway — the regression this
+        // whole path exists to prevent, reintroduced one line above it.
+        const type = inbound.ok ? inbound.msg.type
+            : inbound.reason === 'bad-shape' || inbound.reason === 'bad-payload' ? inbound.type
+                : undefined;
+        if (type === undefined)
+            return false;
+        // **The role comes from the two handshake literals, deliberately not from `directionOf`.** Reading
+        // it from the message's own direction is the obvious simplification now that one exists, and it
+        // inverts the check below: a socket whose first frame is `screenshot:done` would be handed the
+        // `agent` role and then waved through the gate that exists to refuse exactly that.
+        const handshake = type === 'agent:register' || type === 'stream:register';
         if (!this.wsRoles.has(ws)) {
-            if (msg.type === 'agent:register') {
+            // A handshake that did not parse confers nothing. Returning here rather than falling through to
+            // `browser` is what keeps an agent whose register is malformed from being closed with
+            // `Forbidden` — the caller has already logged it, and the next frame still gets to introduce it.
+            if (handshake && !inbound.ok)
+                return false;
+            if (type === 'agent:register')
                 this.wsRoles.set(ws, 'agent');
-            }
-            else if (msg.type === 'stream:register') {
+            else if (type === 'stream:register')
                 this.wsRoles.set(ws, 'stream');
-            }
-            else {
-                // Local connection whose first message is not an agent/stream handshake —
-                // treat it as a browser (e.g. dashboard opened on the same machine).
+            // Local connection whose first message is not an agent/stream handshake — treat it as a browser
+            // (e.g. dashboard opened on the same machine). This fallback is what puts such a socket under
+            // the gate below.
+            else
                 this.wsRoles.set(ws, 'browser');
-            }
         }
-        // Browser sockets must not spoof agent control messages
-        if (this.wsRoles.get(ws) === 'browser' && AGENT_MSG_TYPES.has(msg.type)) {
+        // Browser sockets must not spoof agent control messages.
+        //
+        // This was a hand-copied array of 29 literals with two type assertions holding it against the
+        // protocol. `directionOf` derives the same set from the schema map — verified member for member
+        // against the array it replaces, no literal added and none lost.
+        if (this.wsRoles.get(ws) === 'browser' && directionOf(type) !== 'browser') {
             ws.close(1008, 'Forbidden');
+            return false;
+        }
+        return true;
+    }
+    /**
+     * What the door refused, said once and in a form an operator can act on.
+     *
+     * This is where `isAddressed` and `isCorrelated` ended up. Both were predicates whose whole
+     * observable output was a `console.warn` — an id-less request resolved no session and was dropped by
+     * the miss anyway — and the schemas now reject the same frames earlier, including the empty-string
+     * case a bare `z.string()` would have let through. What is new is that the log names the *field*:
+     * "requestId: Too small" instead of "dropped, cannot correlate a reply".
+     *
+     * Worth logging at all for the reason `isCorrelated` gave: the three places a bad frame can be
+     * dropped are otherwise silent, and an operator who upgrades the relay but not an independently
+     * installed `mcp-server` would watch commands do nothing with no trace.
+     *
+     * **Throttled per socket, and the "per socket" is the whole design.** A first draft wrote one line
+     * per rejected frame, on the direction a viewer with devtools controls and at the rate a gesture
+     * produces — the unbounded, attacker-driven log volume this file already refuses at
+     * `forwardUnacked`, with the reason written beside it. A single module-level timestamp would fix the
+     * volume and break the diagnostic: one noisy socket would silence the *other* socket's first bad
+     * frame, which is the skewed-client case the log exists for. So the state is keyed by socket, in a
+     * `WeakMap` that needs no cleanup, and **the first rejection from any socket is always written** —
+     * the one that names the skew is never the hundredth. What is dropped is only repetition, and the
+     * next line says how much.
+     *
+     * `unknown-type` stays at debug: eleven relay-produced literals land here whenever a client echoes
+     * one back, and none of them is a defect. It shares the throttle so turning debug on cannot
+     * reintroduce the volume.
+     */
+    logInboundRejection(ws, failure) {
+        const now = Date.now();
+        const state = this.rejectionLog.get(ws);
+        if (state && now - state.at < REJECT_LOG_INTERVAL_MS) {
+            state.suppressed++;
             return;
         }
+        const line = describeRejection(failure, state?.suppressed ?? 0);
+        // Recorded even when there is nothing to write, so a burst of `not-an-object` frames cannot reset
+        // the window for the reasons that do write.
+        this.rejectionLog.set(ws, { at: now, suppressed: 0 });
+        if (line === null)
+            return;
+        if (failure.reason === 'unknown-type')
+            logger.debug(line);
+        else
+            logger.warn(line);
+    }
+    route(ws, msg, raw) {
         switch (msg.type) {
             // ── Agent → Relay ─────────────────────────────────────────────────────
             case 'agent:resources':
@@ -556,30 +881,44 @@ export class RelayServer {
                 this.handleUITreeError(msg);
                 break;
             case 'agents:list': {
-                this.sendTo(ws, { type: 'agents:listed', sessions: this.sessions.list() });
+                this.sendTo(ws, {
+                    type: 'agents:listed',
+                    sessions: this.sessions.list(this.ownerOf(ws), (holder) => this.isAlive(holder)),
+                });
                 break;
             }
             // ── Session / Stream lifecycle ─────────────────────────────────────────
             case 'session:start':
                 this.handleSessionStart(ws, msg);
                 break;
+            // ── the two session commands, gated but not answered ───────────────────────────────────────
+            //
+            // Both destroy state a viewer depends on, and until L5c both acted on the strength of the session
+            // existing. `session:leave` is the sharper of the two: it nulls `browserSocket`, so an unguarded one
+            // strips ownership out from under a mounted viewer — and then that tester's own input is refused,
+            // which is why `not-session-owner` needed real copy in the dashboard rather than the `null` a first
+            // draft gave it.
+            //
+            // No address check here at all any more: the schema declares `sessionId` with `.min(1)`, so an absent
+            // id, an empty one and a non-string are all refused before this case is reached. It used to be a bare
+            // `msg.sessionId &&` rather than the `isAddressed` predicate, because a falsy check already covered
+            // both halves and the predicate would have added only its log.
+            //
+            // **Dropped rather than refused, and that is the contract**: neither has a reply, so there is no
+            // waiter to tell. The same asymmetry as the input frames nothing acks. Inventing a
+            // `session:leave-error` would grow the wire for a message no consumer reads — and `session:end` has
+            // no in-repo sender at all, so it would be a reply to nobody.
             case 'session:end': {
-                if (msg.sessionId) {
+                if (this.ownsSession(ws, this.sessions.get(msg.sessionId))) {
                     this.sessions.remove(msg.sessionId);
-                    this.dropHandlers.delete(msg.sessionId);
-                    this.audioDropHandlers.delete(msg.sessionId);
-                    this.droppers.delete(msg.sessionId);
-                    this.idrRequesters.delete(msg.sessionId);
+                    this.forgetSessionState(msg.sessionId);
                 }
                 break;
             }
             case 'session:leave': {
-                if (msg.sessionId) {
+                if (this.ownsSession(ws, this.sessions.get(msg.sessionId))) {
                     this.sessions.clearBrowser(msg.sessionId);
-                    this.dropHandlers.delete(msg.sessionId);
-                    this.audioDropHandlers.delete(msg.sessionId);
-                    this.droppers.delete(msg.sessionId);
-                    this.idrRequesters.delete(msg.sessionId);
+                    this.forgetSessionState(msg.sessionId);
                 }
                 break;
             }
@@ -596,13 +935,21 @@ 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);
+                // **Off `raw`, and still a cast — deliberately both.**
+                //
+                // `session:chrome` is Envelope tier, so the parser proved `type` and `sessionId` and nothing
+                // about this value; reading it from `raw` is what makes that visible at the line rather than
+                // in a header. The old comment here promised a validator would replace the cast. It did not,
+                // and the reason is worth having instead of the promise: `ChromePayload` is a **closed
+                // two-member union** while `AgentRegister.platform` is `string`, open so that a third-party
+                // platform can register through `AgentRegistry.register()` (root AGENTS.md, OCP). Validating
+                // this would refuse a platform the repo promises to support — and refusing costs more than a
+                // dropped frame, because the message arrives once per boot and skipping `setChromeData` also
+                // empties what the re-join replay reads. The relay never looks inside; the viewer does, and it
+                // is where the variants are already told apart.
+                this.sessions.setChromeData(session.id, raw['payload']);
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
-                    session.browserSocket.send(JSON.stringify(msg));
+                    session.browserSocket.send(JSON.stringify(raw));
                 }
                 break;
             }
@@ -610,9 +957,10 @@ export class RelayServer {
                 const session = this.sessions.get(msg.sessionId);
                 if (!session)
                     break;
-                this.sessions.setDeviceInfo(session.id, msg.payload);
+                // See `session:chrome` above for why this one is a cast off `raw` too.
+                this.sessions.setDeviceInfo(session.id, raw['payload']);
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
-                    session.browserSocket.send(JSON.stringify(msg));
+                    session.browserSocket.send(JSON.stringify(raw));
                 }
                 break;
             }
@@ -623,14 +971,14 @@ export class RelayServer {
                     break;
                 this.sessions.clearDeviceCache(session.id);
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
-                    session.browserSocket.send(JSON.stringify(msg));
+                    session.browserSocket.send(JSON.stringify(raw));
                 }
                 break;
             }
             case 'device:boot-error': {
                 const session = this.sessions.get(msg.sessionId);
                 if (session?.browserSocket?.readyState === WebSocket.OPEN) {
-                    session.browserSocket.send(JSON.stringify(msg));
+                    session.browserSocket.send(JSON.stringify(raw));
                 }
                 break;
             }
@@ -641,18 +989,23 @@ export class RelayServer {
                 this.sessions.updateDeviceStatus(session.id, 'shutdown');
                 this.sessions.setReadySent(session.id, false);
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
-                    session.browserSocket.send(JSON.stringify(msg));
+                    session.browserSocket.send(JSON.stringify(raw));
                 }
                 break;
             }
             case 'device:ready': {
+                // The one inbound member whose `sessionId` is declared optional, and it is a reasoned deferral
+                // rather than an oversight — see `DeviceReady`. So this is a real guard, not a dropped `!`:
+                // an agent that omits it resolves no session here, exactly as before.
+                if (msg.sessionId === undefined)
+                    break;
                 const session = this.sessions.get(msg.sessionId);
                 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));
+                    session.browserSocket.send(JSON.stringify(raw));
                 }
                 break;
             }
@@ -671,13 +1024,18 @@ export class RelayServer {
             case 'keyboard:toggled': {
                 const session = this.sessions.get(msg.sessionId);
                 if (session?.browserSocket?.readyState === WebSocket.OPEN) {
-                    session.browserSocket.send(JSON.stringify(msg));
+                    session.browserSocket.send(JSON.stringify(raw));
                 }
                 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.
+            // Bound to the session's own agent socket for the same reason clipboard is: this reply says
+            // whether a **specific tester's** device is on the network, and a second agent must not be
+            // able to tell that tester's viewer something about it.
+            case 'network:state':
+            case 'network:error':
             case 'clipboard:data':
             case 'clipboard:write-done':
             case 'clipboard:error': {
@@ -685,38 +1043,101 @@ export class RelayServer {
                 if (session?.agentSocket !== ws)
                     break;
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
-                    session.browserSocket.send(JSON.stringify(msg));
+                    session.browserSocket.send(JSON.stringify(raw));
                 }
                 break;
             }
             // ── Browser → Agent ────────────────────────────────────────────────────
-            case 'device:boot':
+            //
+            // These two shared one fall-through clause. Separated because the sharing is the trap for
+            // whoever adds the door gate: a correlator check written into a shared body would gate
+            // `device:shutdown` too, and the relay originates that message with no id — so the dashboard's
+            // four senders and the relay's own idle timer would stop reaching the agent, silently, in the
+            // one direction no reply reports. That gate is a schema now and cannot be written into a case at
+            // all, which is what makes the trap unreachable rather than merely avoided.
+            case 'device:boot': {
+                // The door gate that stood here is now the schema: `device:boot` declares `sessionId` and
+                // `requestId` required, and the parser rejects an absent **or empty** one before this case is
+                // reached. The policy it enforced is unchanged and its reason still holds — both things the
+                // relay could do with an id-less boot are downstream of here (forward it, or answer it with a
+                // `device:boot-error`), so gating only one of them would leave the guarantee resting on
+                // whichever branch was not gated.
+                //
+                // A boot the agent never receives leaves the viewer on "Waiting for first frame…" with nothing
+                // said, and the reasons it might not arrive 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. `dispatchTarget` decides which of the four it is.
+                //
+                // **The relay is a producer of this reply, so it echoes the correlator itself.** An MCP caller
+                // that receives this diagnosis uncorrelated reads it as unsolicited and waits out its deadline —
+                // the diagnosis arrives and is discarded. That defect shipped twice from agent code
+                // (`open-url:error`, then `clipboard:error`); here the producer is the relay, where
+                // `correlatedRequestsGated` cannot see it because the field is optional.
+                const boot = this.dispatchTarget(ws, msg.sessionId);
+                if (!boot.ok) {
+                    this.sendTo(ws, {
+                        type: 'device:boot-error',
+                        sessionId: msg.sessionId,
+                        requestId: msg.requestId,
+                        message: boot.message,
+                    });
+                    break;
+                }
+                // 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.
+                //
+                // **Mutating the parse product, not the frame that arrived**, which is what makes this safe as
+                // well as correct: `payload` is a fresh object the parser built, so `raw` is untouched. The
+                // presence check the old line carried is gone because the schema requires the payload — and
+                // `external` is deliberately not declared on `DeviceBoot`, since the browser never sends it.
+                msg.payload['external'] = this.wsExternal.get(ws) ?? false;
+                // The parse product, so a key a viewer appended from devtools is gone before the agent sees it.
+                boot.session.agentSocket.send(JSON.stringify(msg));
+                break;
+            }
             case 'device:shutdown': {
+                // Deliberately **un**correlated: the relay sends this itself from the idle timer, with no browser and
+                // no id behind it, so a correlator cannot be required and an absent one is not an error.
+                //
+                // Addressing used to have no gate either, on the grounds that an unaddressed shutdown resolves no
+                // session and is dropped by the miss, so a gate would buy only its log. That reasoning is now moot
+                // rather than wrong: the schema declares `sessionId` required, so the parser refuses the frame and
+                // the log it would have bought is the one `logInboundRejection` writes.
+                //
+                // **`reachableTargetWithoutOwnership`, not `dispatchTarget`** — that clause is #527, and its blocker is in
+                // the dashboard, not here. What this fixes is the other half: until #542 this case resolved the
+                // session inline and dropped the frame when it could not, making it the only browser-originated
+                // command the relay never answers. `mcp-server`'s `shutdownDevice` waits 30s on `device:shutdown-done`
+                // and then reports `Request timed out` with no cause, which is the silence, not a diagnosis.
                 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.
+                if (session && !this.mayShutDown(ws, session)) {
                     this.sendTo(ws, {
-                        type: 'device:boot-error',
+                        type: 'device:shutdown-error',
                         sessionId: msg.sessionId,
-                        message: session ? 'agent offline' : 'Session not found',
+                        ...(msg.requestId === undefined ? {} : { requestId: msg.requestId }),
+                        message: ownershipRefusal(session),
                     });
                     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.
-                    if (msg.type === 'device:boot' && msg.payload && typeof msg.payload === 'object') {
-                        msg.payload.external = this.wsExternal.get(ws) ?? false;
-                    }
-                    session.agentSocket.send(JSON.stringify(msg));
+                const target = this.reachableTargetWithoutOwnership(msg.sessionId);
+                if (!target.ok) {
+                    // Echoed, and the relay is the producer — the same obligation `device:boot-error` carries and for
+                    // the same reason: an MCP caller that receives a diagnosis uncorrelated reads it as unsolicited
+                    // and waits out the deadline anyway, so the answer arrives and is discarded. `requestId` is
+                    // optional on both sides here, so an absent one stays absent rather than being invented.
+                    this.sendTo(ws, {
+                        type: 'device:shutdown-error',
+                        sessionId: msg.sessionId,
+                        ...(msg.requestId === undefined ? {} : { requestId: msg.requestId }),
+                        message: target.message,
+                    });
+                    break;
                 }
+                target.session.agentSocket.send(JSON.stringify(msg));
                 break;
             }
+            // Door checks, one policy per request: an uncorrelatable request is not forwarded, not rebuilt and
+            // not answered, because every reply these produce declares `requestId` as required.
             case 'app:install':
                 this.handleBrowserAppInstall(ws, msg);
                 break;
@@ -724,46 +1145,88 @@ export class RelayServer {
                 this.handleBrowserAppLaunch(ws, msg);
                 break;
             case 'open-url': {
-                const session = this.sessions.get(msg.sessionId);
-                if (session?.agentSocket.readyState === WebSocket.OPEN) {
-                    session.agentSocket.send(JSON.stringify(msg));
+                // **At the door, before either branch.** A correlator is required on this request, and the
+                // relay has two things it could do with one that lacks it — forward it, or answer it — so
+                // putting the check inside one branch means having two policies. A first draft did exactly
+                // that: it refused to *answer* without an id while still *forwarding* without one, which
+                // leaves the whole guarantee resting on the receiving agent. Both in-repo agents drop it, but
+                // an agent that predates this field would execute the request and reply uncorrelated, and
+                // then nothing downstream can attribute the reply.
+                //
+                // **The check is the validator now**, and the argument for it is unchanged. It read "here rather
+                // than in a validator because this is one required field on one message"; #444 built the
+                // validator, and the schema for `open-url` demands the correlator before this case is reached.
+                //
+                // Dropping is still the only honest answer: `open-url:error` requires the correlator too, so
+                // answering would mean shipping a frame that violates its own declaration — `JSON.stringify`
+                // erases the absent key, every correlating consumer discards the result, and "agent offline"
+                // becomes a caller waiting out its full deadline. That was the first draft's other half,
+                // `requestId: msg.requestId!` — an assertion in an *outbound* frame, unlike the inbound
+                // `sessionId!` this file used to carry, which fed a read whose miss still produced a visible
+                // error. Neither exists any more.
+                const target = this.dispatchTarget(ws, msg.sessionId);
+                if (target.ok) {
+                    target.session.agentSocket.send(JSON.stringify(msg));
                 }
                 else {
-                    this.sendTo(ws, { type: 'open-url:error', sessionId: msg.sessionId, message: 'agent offline' });
+                    this.sendTo(ws, {
+                        type: 'open-url:error',
+                        sessionId: msg.sessionId,
+                        requestId: msg.requestId,
+                        message: target.message,
+                    });
                 }
                 break;
             }
             case 'app:clear-state': {
-                const session = this.sessions.get(msg.sessionId);
-                if (session?.agentSocket.readyState === WebSocket.OPEN) {
-                    session.agentSocket.send(JSON.stringify(msg));
+                // Verbatim forward like `open-url`, so the correlator rides for free; the door check and the echo
+                // are the same two lines.
+                const target = this.dispatchTarget(ws, msg.sessionId);
+                if (target.ok) {
+                    target.session.agentSocket.send(JSON.stringify(msg));
                 }
                 else {
-                    this.sendTo(ws, { type: 'app:clear-state-error', sessionId: msg.sessionId, message: 'agent offline' });
+                    this.sendTo(ws, {
+                        type: 'app:clear-state-error',
+                        sessionId: msg.sessionId,
+                        requestId: msg.requestId,
+                        message: target.message,
+                    });
                 }
                 break;
             }
+            // ── input, split by whether an ack answers it ──────────────────────────────────────────────
+            //
+            // These eleven shared one clause until L5c, and the sharing was the trap. Only five of them are
+            // answered — the four terminal frames plus `input:type` — so only those five carry a
+            // required `requestId`, and a gate written into a shared body would have dropped every opening
+            // and move frame with it: no swipe, no pinch, no rotation, and nothing said. Splitting the clause
+            // is what makes the gate unable to reach them. `correlatedRequestsGated` resolves fall-through by
+            // sharing the next non-empty body, so it would have read one gate as covering all eleven.
             case 'input:touch:start':
             case 'input:touch:move':
-            case 'input:touch:end':
             case 'input:pinch:start':
             case 'input:pinch:move':
+            case 'input:rotate':
+            case 'input:keyboard:toggle': {
+                // No ack, so no correlator to check and nothing to answer. An unowned frame is dropped rather
+                // than refused for the same reason: there is no waiter to tell.
+                //
+                // These carry no correlator by declaration, so nothing was ever gated on one here — and the
+                // address is now the schema's business rather than this clause's. What the split still buys is
+                // unchanged and is the reason it exists: a correlator gate written into a shared body would have
+                // reached these six as well, dropping every opening and move frame with the answered five.
+                this.forwardUnacked(ws, msg);
+                break;
+            }
+            case 'input:touch:end':
             case 'input:pinch:end':
             case 'input:key':
-            case 'input:type':
             case 'input:button':
-            case 'input:rotate':
-            case 'input:keyboard:toggle': {
-                const session = this.sessions.get(msg.sessionId);
-                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' });
-                }
+            case 'input:type': {
+                // One policy at the door, as for the app commands: an uncorrelatable request is not forwarded and
+                // not answered, because every reply it could produce declares `requestId` required.
+                this.handleAckedInput(ws, msg);
                 break;
             }
             // Kept out of the input:* chain above: these need their own error type, and the caller
@@ -771,13 +1234,41 @@ export class RelayServer {
             // 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));
+                // Not part of this layer's pair set — clipboard has carried a required `requestId` since it was
+                // written — but it had the identical defect, and leaving it would make this layer's claim of one
+                // policy at the door false the moment it landed. It answered with `requestId: msg.requestId!`,
+                // which is a **write into an outbound frame**: `JSON.stringify` erases the absent key and ships a
+                // `clipboard:error` whose required correlator is missing, which `useClipboardBridge` discards on
+                // `if (!msg.requestId) return` — so "agent offline" became the caller waiting out its budget.
+                // Removed once already in `e98abd4`, for `open-url`, and still here.
+                // Ownership matters most here of all of them: a `clipboard:write` from a socket that does not hold
+                // the session pastes its text into someone else's device, and a `clipboard:read` presses the copy
+                // or cut chord on it — and the reply routes to the session's own browser, so the payload lands on
+                // **that** tester's host OS clipboard. The agent-side mirror of this check has been here since the
+                // bridge was written, with the reason beside it; the browser side had none.
+                const clip = this.dispatchTarget(ws, msg.sessionId);
+                if (clip.ok) {
+                    clip.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',
+                        type: 'clipboard:error', sessionId: msg.sessionId, requestId: msg.requestId, message: clip.message,
+                    });
+                }
+                break;
+            }
+            // Ownership is not decoration here: taking a device off the network is the most disruptive
+            // thing a non-holder could do to someone else's session short of shutting it down, and unlike
+            // a shutdown it leaves the device *looking* fine. `dispatchTarget` rather than the weaker
+            // `reachableTarget` `device:shutdown` uses — there is no teardown race to accommodate.
+            case 'network:set': {
+                const net = this.dispatchTarget(ws, msg.sessionId);
+                if (net.ok) {
+                    net.session.agentSocket.send(JSON.stringify(msg));
+                }
+                else if (ws.readyState === WebSocket.OPEN) {
+                    this.sendTo(ws, {
+                        type: 'network:error', sessionId: msg.sessionId, requestId: msg.requestId, message: net.message,
                     });
                 }
                 break;
@@ -785,8 +1276,6 @@ export class RelayServer {
         }
     }
     handleAgentResources(ws, msg) {
-        if (!msg.resources)
-            return;
         this.sessions.setResources(ws, msg.resources);
         const agentName = this.sessions.getAllByAgentSocket(ws)[0]?.agentName;
         if (agentName) {
@@ -902,8 +1391,9 @@ export class RelayServer {
         // 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.
+        // `browserSocket` at all. An attached MCP client does have one and will receive this — and as of
+        // #512 it **acts** on it, settling that session's pending requests instead of waiting them out. The
+        // clause here used to say the client drops it as unmatched, which was true and was the problem.
         for (const s of agentSessions) {
             if (s.browserSocket) {
                 this.sendTo(s.browserSocket, {
@@ -911,8 +1401,10 @@ export class RelayServer {
                 });
             }
         }
-        for (const s of agentSessions)
+        for (const s of agentSessions) {
             this.sessions.remove(s.id);
+            this.forgetSessionState(s.id);
+        }
         this.sessions.removeResources(ws);
         logger.info(cause === 'replaced'
             ? `agent re-registered — ${agentSessions.length} previous session(s) replaced`
@@ -987,6 +1479,7 @@ export class RelayServer {
                     this.sendTo(s.browserSocket, { type: 'session:terminated', sessionId: s.id, reason: 'agent-disconnected' });
                 }
                 this.sessions.remove(s.id);
+                this.forgetSessionState(s.id);
             }
         }
         // Only devices without a surviving session get a new one. Passing all of them here is what
@@ -1012,12 +1505,38 @@ export class RelayServer {
         // 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)`);
+        // `||`, not `??`: the schema defaults both of these to `''` for an agent that omits them, so `??`
+        // would print an empty name and an empty platform where this used to print `unknown`.
+        logger.info(`agent connected: ${msg.agentName || msg.agentId || 'unknown'} (${msg.platform || 'unknown'}) — ${registeredSessions.length} device(s)`);
     }
+    /** The only producer of `error` — all five exits below, and nothing else in the repo sends that message.
+     *
+     *  That is what makes the address possible rather than aspirational: `msg.sessionId` is narrowed to a
+     *  non-empty `string` by the door — the inbound schema, `isAddressed` before it — so every refusal can
+     *  name the join it refuses. Before
+     *  L5d they carried none, and the clients' join waiters matched `sessionId === undefined || sessionId ===
+     *  mine` — with no such key the left half was always true, so any refusal resolved any pending join. */
     handleSessionStart(ws, msg) {
         const session = this.sessions.get(msg.sessionId);
         if (!session) {
-            this.sendTo(ws, { type: 'error', message: 'Session not found' });
+            this.sendTo(ws, { type: 'error', sessionId: msg.sessionId, message: 'Session not found', reason: 'session-not-found' });
+            return;
+        }
+        // Occupancy first, because it is the more specific answer and both can be true at once. A tester
+        // joining a device someone else has open on a loaded Mac was being told "this Mac is overloaded,
+        // pick another" — advice for a problem they cannot act on, while the actual reason went unreported.
+        // It is a map read the relay has already done, so ordering it first costs nothing.
+        //
+        // `!== ws` because a socket re-joining the session it already holds is not contending with anyone:
+        // `SessionList` sends `session:start` before a shutdown, so pressing shutdown twice hit this.
+        // The same three conditions `join()` applies, and they have to agree: this one answers the caller and
+        // that one performs the bind, so a disagreement is a refusal for a session the bind would have allowed.
+        if (session.browserSocket &&
+            session.owner !== null &&
+            session.owner !== this.ownerOf(ws) &&
+            session.browserSocket.readyState === WebSocket.OPEN &&
+            this.isAlive(session.browserSocket)) {
+            this.sendTo(ws, { type: 'error', sessionId: msg.sessionId, message: 'Session busy', reason: 'session-busy' });
             return;
         }
         // Read before the resource gate, and answered before it too. The gate would otherwise read the
@@ -1028,15 +1547,35 @@ export class RelayServer {
         if (resources) {
             const memPercent = (resources.memUsedMB / resources.memTotalMB) * 100;
             if (resources.cpuPercent > RESOURCE_THRESHOLD || memPercent > RESOURCE_THRESHOLD) {
-                this.sendTo(ws, { type: 'error', message: 'Agent resources exhausted' });
+                this.sendTo(ws, { type: 'error', sessionId: msg.sessionId, message: 'Agent resources exhausted', reason: 'agent-resources-exhausted' });
                 return;
             }
         }
         try {
-            this.sessions.join(msg.sessionId, ws);
+            const joined = this.sessions.join(msg.sessionId, ws, this.ownerRecord(ws), (h) => this.isAlive(h));
+            if (!joined.ok) {
+                // Both of these are answered above, so arriving here means the state moved between that check and
+                // this call. They are **values now rather than throws** (#515), and that is what fixes the defect:
+                // the most common way into the old `catch` was a socket re-joining the session it already holds —
+                // exempted by the `!== ws` check above, then refused by `join()`, then reported as
+                // `session-not-found` for a live session the caller was holding.
+                const reason = joined.failure === 'held-by-another' ? 'session-busy' : 'session-not-found';
+                const message = joined.failure === 'held-by-another' ? 'Session busy' : 'Session not found';
+                this.sendTo(ws, { type: 'error', sessionId: msg.sessionId, message, reason });
+                return;
+            }
         }
-        catch {
-            this.sendTo(ws, { type: 'error', message: 'Session busy' });
+        catch (e) {
+            // Only a bug reaches here now — the two expected failures return above instead of throwing, which is
+            // what stops this arm from having to guess. It still answers rather than dropping: both clients await
+            // `session:joined | error` on this request, so silence costs them a full deadline.
+            //
+            // `session-not-found` is chosen for **the action it names**, not as a diagnosis. Its own declaration
+            // says "nothing else is ever coming for it", and that half is true of any failed join — no
+            // `session:joined` will follow. `session-busy` would be the wrong action: it tells a viewer the
+            // session is alive and someone else has it. The prose carries what is actually known.
+            logger.error(`session:start could not join ${msg.sessionId}:`, e);
+            this.sendTo(ws, { type: 'error', sessionId: msg.sessionId, message: 'Session could not be joined', reason: 'session-not-found' });
             return;
         }
         // Include the agent's capabilities so the viewer knows up front what is implemented on
@@ -1057,11 +1596,15 @@ export class RelayServer {
             this.sendTo(ws, { type: 'session:agent-away', sessionId: msg.sessionId });
             return;
         }
+        // These three replay a session's cached state to a re-joining viewer. They carry `sessionId`
+        // because both agents stamp it on every copy they send, and the relay was the only producer that
+        // did not — so the shared declaration had to be `sessionId?` to stay honest about the two of us.
+        // Stamping it here is what let that be tightened to required.
         if (session.chromeData) {
-            this.sendTo(ws, { type: 'session:chrome', payload: session.chromeData });
+            this.sendTo(ws, { type: 'session:chrome', sessionId: session.id, payload: session.chromeData });
         }
         if (session.deviceInfo) {
-            this.sendTo(ws, { type: 'session:deviceInfo', payload: session.deviceInfo });
+            this.sendTo(ws, { type: 'session:deviceInfo', sessionId: session.id, payload: session.deviceInfo });
         }
         // 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
@@ -1073,11 +1616,301 @@ export class RelayServer {
             // 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) {
-                this.sendTo(session.agentSocket, { type: 'stream:request-idr', sessionId: session.id });
-            }
+            //
+            // **Through the session's throttled requester, not a bare `sendTo`.** This was unreachable for a
+            // socket that already held the session — `join()` threw and the handler answered above this line —
+            // and #515 made a re-join run the whole body. A client re-sending `session:start` therefore drives
+            // one forced keyframe per frame it sends, and a 1080p IDR is two orders of magnitude larger than
+            // the P-frames around it, so the amplification lands on the tester who is actually watching. The
+            // backpressure path already throttles this exact message per session; sharing that requester is
+            // what keeps the two callers from having two policies.
+            this.idrRequester(session.id)();
+            // And ask what the device's network is doing (#614). `NetworkState` is agent-produced and is not
+            // among the three replayed above, so without this a viewer that reconnects has no way to learn
+            // whether the device is offline and its control renders in a guessed position.
+            //
+            // **Gated on the capability, unlike the IDR request beside it.** That one is safe to send blind
+            // because an agent without it loses nothing — the next periodic keyframe arrives anyway. This one
+            // has no such repair, so an agent that never answers is indistinguishable from one that failed to
+            // read; a viewer arming a deadline would then render "could not read" on every re-join, for an
+            // agent that already said it cannot do this at all. iOS is exactly that agent until #607's last
+            // slice. Fifty lines up, `session:joined` carries these capabilities for the stated reason that a
+            // consumer must not infer support from a timeout — asking anyway would make the relay do it.
+            //
+            // **Inside `readySent` too, and there as an optimisation rather than a correctness condition.**
+            // `readySent` is the *stream's* readiness: `clearStreamSocket` lowers it while `deviceStatus`
+            // stays `'booted'`, so a booted, genuinely offline device with a dead stream socket is not asked
+            // about here — and the agent would have answered, since it still holds that serial. What makes
+            // skipping safe is not the agent's silence but the viewer's: with `readySent` false the
+            // `device:ready` above is not replayed either, so nothing is rendering a live device to be wrong
+            // about. `deviceStatus` is not the fix — the comment on `device:ready` says why (#440).
+            if (session.agentCapabilities?.includes('network-control'))
+                this.networkStateRequester(session.id)();
+        }
+    }
+    /** Shut the device down because nobody is watching it any more. The idle timer's payload, hoisted out
+     *  of the close handler so the release loop there reads as one line per session. */
+    idleShutdown(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session?.agentSocket.readyState !== WebSocket.OPEN)
+            return;
+        this.sendTo(session.agentSocket, {
+            type: 'device:shutdown',
+            sessionId: session.id,
+            payload: { deviceId: session.deviceId },
+        });
+    }
+    /** Where a browser-role command can be dispatched, or what its sender needs to be told instead.
+     *
+     *  Three refusals used to be spread across seven `case` bodies as two conditions each, and the ownership
+     *  one was in none of them. Collapsed here so the set is decided once: a command reaches an agent only if
+     *  the session exists, **this socket holds it**, and the agent is connected. Anything else has prose the
+     *  caller can act on, and each case wraps that prose in the reply type its own waiter reads.
+     *
+     *  The two ownership strings are one reason with different prose, the treatment `#492` settled: telling a
+     *  caller the session is in use when it is idle steers it off a device it could have had.
+     */
+    dispatchTarget(ws, sessionId) {
+        // Ownership first and liveness second, which is the order the refusals were written in and worth
+        // keeping: a non-owner is told it does not hold the session rather than being handed the agent's
+        // state. Composed rather than inlined so `device:shutdown` can take the other two checks alone.
+        const session = this.sessions.get(sessionId);
+        if (session && !this.ownsSession(ws, session))
+            return { ok: false, message: ownershipRefusal(session) };
+        return this.reachableTargetWithoutOwnership(sessionId);
+    }
+    /** `dispatchTarget` without the ownership clause: is there a session here, and is its agent listening?
+     *
+     *  **The name carries the omission because a doc block does not reach an autocomplete.** This is the
+     *  resolver a future handler must not pick by accident — it is the general-looking one and the unsafe
+     *  one at the same time, which is the pairing worth spelling out.
+     *
+     *  **Still here after #527, and this paragraph used to say it would not be.** It predicted that
+     *  answering "who may shut a device down" would move `device:shutdown` up to `dispatchTarget`. The
+     *  answer turned out to be a *different* gate rather than that one: `mayShutDown` refuses a session
+     *  another client holds and permits an unheld one, because the dashboard's unmount teardown races its
+     *  own viewer socket's close and an owns-it gate refuses the teardown whenever the close lands first —
+     *  leaving the device booted until the idle timer, which is the cost #527 was filed to avoid.
+     *
+     *  So the two are ordered rather than merged: `mayShutDown` decides *who*, this decides *whether it can
+     *  be delivered at all*, and without the second a shutdown addressed to a missing session or a closed
+     *  agent socket is dropped in silence and `mcp-server`'s caller burns a 30s deadline (#542).
+     *
+     *  The disclosure it was written to record stands: a caller that is not the holder still learns whether
+     *  a session id exists and whether its agent is up.
+     */
+    reachableTargetWithoutOwnership(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return { ok: false, message: 'Session not found' };
+        if (session.agentSocket.readyState !== WebSocket.OPEN)
+            return { ok: false, message: 'agent offline' };
+        return { ok: true, session };
+    }
+    /** Is `ws` the socket this session is bound to?
+     *
+     *  Until L5c the input path resolved the session and forwarded without asking. `clipboard:data` asks the
+     *  mirror-image question one branch up (`session?.agentSocket !== ws`) with the reason written beside it —
+     *  a second agent on the same relay must not address someone else's session — and the browser direction
+     *  had no equivalent. So any authenticated client that knew a session id could drive a device another
+     *  tester was looking at, and the agent's ack went to the session holder rather than to whoever asked.
+     *
+     *  An **unheld** session (no `browserSocket`, or one that has gone) is also not owned by the sender. That
+     *  is deliberate rather than incidental: it makes an input arriving inside the reconnect grace fail fast
+     *  instead of being applied to a device with nobody watching the result. */
+    ownsSession(ws, session) {
+        return session?.owner !== null && session?.owner === this.ownerOf(ws);
+    }
+    /** Which owner this socket speaks for. Every connection has one — supplied or minted — so this never
+     *  answers `undefined` and two anonymous sockets can never match by both lacking an identity. */
+    ownerOf(ws) {
+        return this.ownerRecord(ws).key;
+    }
+    /** The principal behind a socket — a user id, or `anon` for a connection carrying no cookie and no PAT. */
+    userOf(ws) {
+        return this.ownerRecord(ws).user;
+    }
+    /** Everything the bind needs to record about who is joining.
+     *
+     *  **A socket with no record gets one of its own rather than a shared sentinel.** `handleConnection`
+     *  seeds every accepted connection before a message can arrive, so the fallback is unreachable today —
+     *  but a literal would make any two unseeded sockets *equal*, and equal keys pass `ownsSession` while
+     *  equal users pass `mayShutDown`'s same-principal exemption. That rests the whole ownership invariant
+     *  on one call site staying total, which is the shape of dependency the sentinel is supposed to remove.
+     *  Minting keeps the answer "this socket and no other"; storing it keeps repeat calls consistent, since
+     *  a fresh value each time would fail to recognise the very socket that bound the session. `minted` is
+     *  `false` deliberately — the legacy exemption exists for a client that identified itself with nothing,
+     *  not for one the relay failed to record. */
+    ownerRecord(ws) {
+        const known = this.ownerKey.get(ws);
+        if (known)
+            return known;
+        const unseeded = `unidentified:${randomUUID()}`;
+        const record = { key: unseeded, user: unseeded, minted: false };
+        this.ownerKey.set(ws, record);
+        return record;
+    }
+    /**
+     * May this socket shut the session's device down?
+     *
+     * **"Not someone else's" rather than "mine", and the difference is the reason #527 stayed open.** The
+     * dashboard's unmount teardown sends `device:shutdown` from one socket while another socket's `close`
+     * races it to the relay — two connections, no ordering — and if the close lands first the session is
+     * unheld. An owns-it gate refuses the teardown there, and the device stays booted until the five-minute
+     * idle timer: the path #527 named as the reason a gate could not be added at all.
+     *
+     * An unheld session therefore stays shutdownable by anyone authenticated, which is unchanged from today
+     * — this command has never had a gate — and is written down rather than implied. What changes is the
+     * case the issue is about: a device another tester is *holding* can no longer be powered off.
+     */
+    mayShutDown(ws, session) {
+        if (session?.owner == null)
+            return true;
+        if (session.owner === this.ownerOf(ws))
+            return true;
+        // **A holder that never identified itself is not gated**, because it cannot pass a gate: every one of
+        // its sockets was minted a separate identity, so its own teardown socket is a stranger to the socket
+        // holding the session — deterministically, not as a race. An older dashboard bundle re-attaching to an
+        // upgraded relay is exactly that, and refusing it would leave a device booted until the idle timer on
+        // every Back press: the cost #527 was filed to avoid, reintroduced by #527's fix.
+        //
+        // **Scoped to the same principal, though.** The exemption exists so a legacy client's own teardown
+        // works, and its own teardown is by definition the same signed-in user — so extending it across users
+        // buys nothing and would leave one tester able to power off another's device for as long as anyone is
+        // running an older build. That is unchanged from before this gate existed, but "unchanged" is not a
+        // reason to carry it forward when the narrower rule costs one comparison.
+        return session.ownerMinted && session.ownerUser === this.userOf(ws);
+    }
+    /** Input that no ack answers: opening and move frames, rotation, the keyboard-forwarding toggle.
+     *
+     *  Dropped rather than refused when unowned, and that asymmetry with `handleAckedInput` is the whole
+     *  reason these have their own clause: refusing means answering, and there is no waiter here to answer.
+     *  `clipboard:data`'s silent `break` is the precedent that fits — a frame nobody is waiting on. */
+    forwardUnacked(ws, msg) {
+        const session = this.sessions.get(msg.sessionId);
+        if (session && !this.ownsSession(ws, session)) {
+            // **Deliberately silent.** A first draft logged here, which is one line per `input:touch:move` — the
+            // dashboard sends those per `pointermove`, so ~60/s for as long as a finger is down, unbounded and
+            // outside `logger`. It says nothing new either: a gesture's terminal frame goes through
+            // `handleAckedInput`, which answers, so a non-owner attempting real input is already visible there.
+            return;
+        }
+        if (session?.agentSocket.readyState === WebSocket.OPEN) {
+            session.agentSocket.send(JSON.stringify(msg));
+        }
+    }
+    /** The five inputs an ack answers, so the five that carry a required correlator.
+     *
+     *  Every exit answers the sender. That is the rule this method exists to hold: a request with a waiter on
+     *  a 2s deadline must not be dropped silently, because the caller's fallback reports silence from a
+     *  session that has never acked as **success** (#457) — so a silent drop here would report an input that
+     *  never left the relay as landed, which is worse than the misrouting it replaced. */
+    handleAckedInput(ws, msg) {
+        // No `!`: the parameter is narrowed by the door, which is the parse now rather than a predicate.
+        const session = this.sessions.get(msg.sessionId);
+        if (session && !this.ownsSession(ws, session)) {
+            // `not-session-owner` rather than `channel-unavailable`, on that set's own rule — a reason exists per
+            // thing a consumer must do differently. That one means reconnect or re-join *this* session; this one
+            // means the caller does not hold it, so the move is to join first. It is also the only reason that can
+            // promise nothing reached the device, because the refusal happens here, before any agent saw the frame.
+            //
+            // **Two situations, one reason, different prose** — the treatment `#492` settled for the pair below.
+            // Someone else holding the session and nobody holding it want the same *action* (join, and if that is
+            // refused pick another device), so splitting the reason would grow the vocabulary for nothing. But one
+            // string cannot be true of both: telling a caller the session is in use when it is idle steers it off
+            // a device it could have had.
+            this.refuseInput(ws, msg, ownershipRefusal(session), 'not-session-owner');
+            return;
+        }
+        if (session?.agentSocket.readyState === WebSocket.OPEN) {
+            session.agentSocket.send(JSON.stringify(msg));
+            return;
+        }
+        // A request that cannot be dispatched. Two situations reach here and only one is the agent's fault:
+        // the session may be held with a socket that is no longer open, or there may be no such session —
+        // evicted after the reconnect grace, or never valid. In the second the agent can be perfectly healthy,
+        // so `agent offline` is a wrong diagnosis, and it is the same pair `device:boot` tells apart above for
+        // the same reason. Same two strings as there.
+        //
+        // The reason is `channel-unavailable` either way, and that is the point rather than an approximation:
+        // the set is derived from what a consumer must do differently, and both of these want a reconnect or a
+        // re-join. The machine field was right for both while the prose was wrong for one (#492).
+        this.refuseInput(ws, msg, session ? 'agent offline' : 'Session not found', 'channel-unavailable');
+    }
+    /**
+     * Tells the sender its payload was refused, in the shape that request's own waiter reads.
+     *
+     * **This is what keeps the door from turning an answered failure into silence.** Before it, a
+     * malformed `open-url` reached the agent and the agent's own guard answered `open-url:error`;
+     * `IOSAgent.ts` says so beside that guard, and names this validation as what would take it over.
+     * Taking the responsibility without taking the answer would have been a regression — worst on the
+     * inputs, and not obviously: `awaitInputAck` reports silence from a session that has never acked as
+     * **success** (#457), so a dropped `input:key` reads to an MCP caller as an input that landed.
+     *
+     * The address and the correlator come from the envelope, which `parseInbound` judges separately from
+     * the payload for exactly this reason — a frame with a good envelope carries everything a reply
+     * needs. `reason: 'malformed'` is not a new member; the input vocabulary already had it, and until
+     * now only agents produced it.
+     *
+     * No ownership check, deliberately: the reply goes to the socket that sent the frame and says only
+     * that its own message was malformed, so it discloses nothing about the session. Every other refusal
+     * in this file answers a question about the session's state and is gated for that reason.
+     */
+    refuseMalformed(ws, f) {
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        const { sessionId, requestId } = f;
+        const message = `malformed ${f.type} payload`;
+        switch (f.type) {
+            case 'device:boot':
+                this.sendTo(ws, { type: 'device:boot-error', sessionId, requestId, message });
+                break;
+            case 'app:install':
+                this.sendTo(ws, { type: 'app:install-error', sessionId, requestId, message });
+                break;
+            case 'app:launch':
+                this.sendTo(ws, { type: 'app:launch-error', sessionId, requestId, message });
+                break;
+            case 'app:clear-state':
+                this.sendTo(ws, { type: 'app:clear-state-error', sessionId, requestId, message });
+                break;
+            case 'open-url':
+                this.sendTo(ws, { type: 'open-url:error', sessionId, requestId, message });
+                break;
+            // Its waiters key on the `input:type-*` pair and ignore an `input:error` entirely — the same
+            // reason `refuseInput` below splits these two.
+            case 'input:type':
+                this.sendTo(ws, { type: 'input:type-error', sessionId, requestId, message, reason: 'malformed' });
+                break;
+            case 'clipboard:read':
+            case 'clipboard:write':
+                this.sendTo(ws, { type: 'clipboard:error', sessionId, requestId, message });
+                break;
+            case 'network:set':
+                this.sendTo(ws, { type: 'network:error', sessionId, requestId, message });
+                break;
+            // The four remaining acked inputs. A `default` rather than four labels because the union is
+            // closed and exhaustive: adding a fourteenth answerable request without a case here would land
+            // it on `input:error`, which `answerableRequestsAnswered` is what stops.
+            default:
+                this.sendTo(ws, { type: 'input:error', sessionId, requestId, message, reason: 'malformed' });
         }
     }
+    /** Answers the sender in the shape its waiter is keyed on.
+     *
+     *  `input:type` needs `input:type-error`, not `input:error` — its waiters in `mcp-server` and
+     *  `flow-runner` match on the `input:type-*` pair and ignore an `input:error` entirely. That is why
+     *  adding `input:type` to the terminal set was never the fix for it, and answering it properly here is
+     *  closes the gap `relay/AGENTS.md` recorded: before L5c an `input:type` on an offline agent got nothing
+     *  and burned its caller's full deadline. */
+    refuseInput(ws, msg, message, reason) {
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        const { sessionId, requestId } = { sessionId: msg.sessionId, requestId: msg.requestId };
+        this.sendTo(ws, msg.type === 'input:type'
+            ? { type: 'input:type-error', sessionId, requestId, message, reason }
+            : { type: 'input:error', sessionId, requestId, message, reason });
+    }
     /** 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
@@ -1087,16 +1920,29 @@ export class RelayServer {
      *  same reason: a generic `error` cannot be correlated by construction. */
     handleBrowserAppInstall(ws, msg) {
         const sessionId = msg.sessionId;
-        const fail = (message) => this.sendTo(ws, { type: 'app:install-error', sessionId, message });
+        const { requestId } = msg;
+        // Closing over the narrowed correlator covers all four failure exits at once. It does **not** cover a
+        // fifth: a throw out of `getDb().prepare(…).get(…)` — SQLITE_BUSY, a closed db, I/O — unwinds to the
+        // message-loop catch and answers nothing at all. Pre-existing and unchanged here, but "every exit
+        // carries the request's id" would be false.
+        const fail = (message) => this.sendTo(ws, { type: 'app:install-error', sessionId, requestId, 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');
+        // Ownership only, and **not** `dispatchTarget`: that resolver also decides agent liveness, and using it
+        // here would move the `agent offline` check ahead of the build lookup below — changing which of two
+        // simultaneous problems the caller is told about. Until L5c this branch asked whether the session
+        // existed and not who was asking, so a socket that never joined could install a build onto a device
+        // someone else was testing, with the reply going to that session's browser rather than to it.
+        if (!this.ownsSession(ws, session))
+            return fail(ownershipRefusal(session));
+        // The schema already refused a non-integer `buildId`, so this is now belt-and-braces rather than
+        // the only guard. Kept because it is also the *answer*: the parser drops a bad frame silently and
+        // No `Number.isInteger` guard here any more: `buildId` is `z.number().int()` at the door, and a bad
+        // one is answered there by `refuseMalformed` with a diagnosis this branch could not give — "not
+        // found" describes a lookup, and for a malformed id no lookup ran. The guard existed because
+        // better-sqlite3 binds a missing value as NULL but **throws** on an object or array, and that
+        // exception was swallowed by the message-loop catch; the door makes both unreachable.
         const build = getDb()
             .prepare('SELECT file_path, bundle_id FROM builds WHERE id = ?')
             .get(msg.buildId);
@@ -1105,23 +1951,38 @@ export class RelayServer {
         // 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');
+        // The correlator rides across the rebuild. `open-url` got this for free — the relay re-serialises
+        // that message whole — but this is a *different* message from the one the browser sent, and the
+        // agent's reply is forwarded back generically without the relay looking at it. So if the id does not
+        // reach the agent, nothing downstream can attribute the reply. Nothing type-checks that the value is
+        // the *request's*: a brand cannot express provenance, so a test carries it.
         this.sendTo(session.agentSocket, {
             type: 'app:install',
             sessionId,
+            requestId,
             payload: { filePath: build.file_path, bundleId: build.bundle_id },
         });
     }
     /** Relay looks up bundle_id from DB. Same correlation rules as `handleBrowserAppInstall`. */
     handleBrowserAppLaunch(ws, msg) {
         const sessionId = msg.sessionId;
-        const fail = (message) => this.sendTo(ws, { type: 'app:launch-error', sessionId, message });
+        const { requestId } = msg;
+        // Closing over the narrowed correlator covers all four failure exits at once. It does **not** cover a
+        // fifth: a throw out of `getDb().prepare(…).get(…)` — SQLITE_BUSY, a closed db, I/O — unwinds to the
+        // message-loop catch and answers nothing at all. Pre-existing and unchanged here, but "every exit
+        // carries the request's id" would be false.
+        const fail = (message) => this.sendTo(ws, { type: 'app:launch-error', sessionId, requestId, 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');
+        // Ownership only, and **not** `dispatchTarget`: that resolver also decides agent liveness, and using it
+        // here would move the `agent offline` check ahead of the build lookup below — changing which of two
+        // simultaneous problems the caller is told about. Until L5c this branch asked whether the session
+        // existed and not who was asking, so a socket that never joined could install a build onto a device
+        // someone else was testing, with the reply going to that session's browser rather than to it.
+        if (!this.ownsSession(ws, session))
+            return fail(ownershipRefusal(session));
+        // See `handleBrowserAppInstall` — the door refuses a malformed id and answers it.
         const build = getDb()
             .prepare('SELECT bundle_id FROM builds WHERE id = ?')
             .get(msg.buildId);
@@ -1129,9 +1990,12 @@ export class RelayServer {
             return fail('Bundle ID not available for this build');
         if (session.agentSocket.readyState !== WebSocket.OPEN)
             return fail('agent offline');
+        // See `handleBrowserAppInstall` — the correlator rides across the rebuild, and only a test says the
+        // value is the request's.
         this.sendTo(session.agentSocket, {
             type: 'app:launch',
             sessionId,
+            requestId,
             payload: { bundleId: build.bundle_id },
         });
     }
@@ -1226,37 +2090,46 @@ export class RelayServer {
         });
     }
     handleUITreeResponse(msg) {
-        if (!msg.requestId)
-            return;
         const pending = this.pendingUITrees.get(msg.requestId);
         if (!pending)
             return;
-        pending.resolve(msg.elements ?? []);
+        pending.resolve(msg.elements);
     }
     handleUITreeError(msg) {
-        if (!msg.requestId)
-            return;
         const pending = this.pendingUITrees.get(msg.requestId);
         if (!pending)
             return;
-        pending.reject(new Error(msg.message ?? 'UI tree query failed'));
+        // `||`, not `??`: the schema defaults an absent message to `''` rather than leaving it undefined,
+        // so the fallback has to treat empty as absent or an older agent's error would read as blank.
+        pending.reject(new Error(msg.message || 'UI tree query failed'));
     }
     handleScreenshotDone(msg) {
-        if (!msg.requestId)
-            return;
         const pending = this.pendingScreenshots.get(msg.requestId);
         if (!pending)
             return;
-        const buf = Buffer.from(msg.data ?? '', 'base64');
-        pending.resolve(buf, msg.format ?? 'png');
+        // The `?? ''` / `?? 'png'` these two used to carry are now `.default()`s in the schema, where a
+        // reader can see that the tolerance is for an older agent rather than for any absent field.
+        const buf = Buffer.from(msg.data, 'base64');
+        const claimed = msg.format;
+        // Logged, **not** overwritten. The field means what the agent says it produced, and correcting it
+        // here would make the relay the authority on something only the agent can know — a contract
+        // change, where this is a drift detector. It costs four bytes of an already-decoded buffer.
+        //
+        // Worth having because the consumer-side fix for #508 sniffs the bytes and would otherwise hide a
+        // lying agent forever: #508 was found by a person noticing, and nothing would have reported it.
+        const actual = sniffImageFormat(buf);
+        if (actual !== null && actual !== claimed) {
+            logger.warn(`[relay] screenshot from session ${msg.sessionId ?? '?'} is ${actual} but the agent called it ` +
+                `${claimed} — the Content-Type will be wrong. Upgrade the agent (#508).`);
+        }
+        pending.resolve(buf, claimed);
     }
     handleScreenshotError(msg) {
-        if (!msg.requestId)
-            return;
         const pending = this.pendingScreenshots.get(msg.requestId);
         if (!pending)
             return;
-        pending.reject(new Error(msg.message ?? 'Screenshot failed'));
+        // `||` for the reason `handleUITreeError` gives.
+        pending.reject(new Error(msg.message || 'Screenshot failed'));
     }
     flushResourceBuffers() {
         if (this.resourceBuffers.size === 0)