@tapflowio/relay 0.26.0 → 0.27.0

package/dist/RelayServer.js

@@ -9,7 +9,7 @@ import { SessionManager } from './SessionManager.js';
 import { directionOf, parseInbound } from '@tapflowio/protocol/validate';
 import { Router, json } from './router.js';
 import { requireViewAuth, requireAuth, getAuth, verifyPat, touchPat, findPat, findUser } from './middleware/auth.js';
-import { AGENT_SCOPE, WS_AGENT_OWNER_REASON, WS_SCOPE_REASON, classifyConnection, revalidatePrincipal } from './lib/connectionAuth.js';
+import { AGENT_SCOPE, WS_ACCESS_CHANGED_REASON, WS_AGENT_OWNER_REASON, WS_SCOPE_REASON, classifyConnection, isAffectedBy, revalidatePrincipal } from './lib/connectionAuth.js';
 import { isTunnelIngress, markTunnelIngress, resolveClientAddress, resolveRequestClient } from './lib/clientAddress.js';
 import { BuildTicketStore } from './lib/buildTickets.js';
 import { resolveBuildFile } from './lib/buildFiles.js';
@@ -22,7 +22,7 @@ import { createTrailingRequester, systemTimerScheduler } from './lib/trailingReq
 import { getDb } from './db.js';
 import { handleLogin, handleLogout, handleMe, handleChangePassword, handleInit, handleAuthStatus } from './api/auth.js';
 import { handleVerify, handleAccept } from './api/invitations.js';
-import { createLogger } from '@tapflowio/agent-core';
+import { createLogger, hasCapability } from '@tapflowio/agent-core';
 import { createKeyframeAwareSender, createRateLimitedDropWarn, sendAudioYieldingToVideo, DEFAULT_BACKPRESSURE_BYTES, hasEnvelope, patchRelayedAt, readEnvelopeFlags, CODEC_JPEG, CODEC_AUDIO, } from '@tapflowio/agent-core/utils';
 const logger = createLogger('relay');
 // True when a remote IP is public — i.e. not loopback, private LAN, or link-local. Used to pick the
@@ -171,6 +171,19 @@ function describeRejection(failure, suppressed) {
     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}`;
 }
+/** Just past `mcp-server`'s 30s shutdown deadline, so an entry outlives every caller still waiting on it. */
+const SHUTDOWN_REQUESTER_TTL_MS = 35_000;
+/**
+ * How long a tracked boot lives without an answer. The same horizon as both clients'
+ * `BOOT_DEADLINE_MS`: past it the caller has already timed out, so the entry is pure
+ * bookkeeping. Expiry forgets silently — it sends no failure, because the client timeout
+ * owns that case. This bounds the map, not the boot: it changes nothing about how long a
+ * boot may take, which is #588's question, not this one's.
+ */
+const PENDING_BOOT_TTL_MS = 180_000;
+/** Said when a session ends with a shutdown unanswered — which is not the same as the shutdown failing. */
+const SHUTDOWN_OUTCOME_LOST = 'The session ended before its agent confirmed the shutdown, so whether the device shut down is unknown.';
+const shutdownRequesterKey = (sessionId, requestId) => `${sessionId}\n${requestId}`;
 export class RelayServer {
     options;
     httpServer;
@@ -278,6 +291,9 @@ export class RelayServer {
     backpressureBytes;
     screenshotTimeoutMs;
     agentGraceMs;
+    /** How long a tracked boot lives without an answer. An option so tests can shrink the
+     *  180s horizon; production always takes the default. */
+    pendingBootTtlMs;
     corsAllowed;
     // One-shot warning when XFF arrives on a loopback socket but TAPFLOW_TRUSTED_PROXIES is unset.
     warnedProxyMisconfig = false;
@@ -287,6 +303,39 @@ export class RelayServer {
     pendingScreenshots = new Map();
     uiTreeTimeoutMs;
     pendingUITrees = new Map();
+    /**
+     * Who asked for each correlated `device:shutdown` still waiting on its agent (#567). The agent's answer
+     * goes to the session's `browserSocket`, and a caller that never joined — an MCP client shutting down a
+     * session nobody holds, which `mayShutDown` permits — has no socket there, so it waited out its 30s for a
+     * shutdown that had happened. Keyed by session **and** id, because the id is chosen by the client and
+     * would alone let one session's answer reach another session's caller.
+     *
+     * **Settled when the session is removed, never when the agent socket drops — the opposite of a boot.**
+     * Both agents reconnect without restarting, and a shutdown that finishes after the reconnect is answered
+     * on the new socket, so an agent going away or being rebound is not evidence that the answer is lost.
+     * For a boot it is (#885): the binding a boot creates is exactly what a rebind loses. Folding the two
+     * into one rule would tell a caller its shutdown failed for a device that then powered off.
+     */
+    shutdownRequesters = new Map();
+    /**
+     * In-flight `device:boot` requests, keyed by session and correlator (#885).
+     *
+     * The relay is the only layer that knows which agent socket each boot was actually dispatched
+     * to, so it owns settling the ones a rebind strands. The client cannot tell "issued before the
+     * rebound" from "delivered to the old agent", which is why the previous client-side settle on
+     * `session:rebound` answered boots the new agent was already handling. Entries record the
+     * concrete agent socket from the `device:boot` dispatch, so a rebind invalidates only the boots
+     * tied to the replaced socket and leaves a boot dispatched to the new socket alone.
+     *
+     * Cleared when a correlated `device:ready` or `device:boot-error` arrives, when the boot is
+     * invalidated at rebind, when its session is forgotten or evicted — and by its own expiry
+     * (`PENDING_BOOT_TTL_MS`) when none of those happen first, so a live agent that never answers
+     * cannot pin the entry past every caller that could have waited on it. An absent `requestId`
+     * answers no request (protocol/AGENTS.md 「Lifecycle correlation」), so id-less replies clear
+     * nothing. A leftover entry is harmless: its id names no waiter, so both clients and the
+     * dashboard drop the synthetic error it would produce.
+     */
+    pendingBoots = new Map();
     constructor(options) {
         this.options = options;
         // 0 on both sides is two ephemeral ports, which is what the tests ask for.
@@ -311,6 +360,7 @@ export class RelayServer {
         const graceEnv = graceRaw ? Number(graceRaw) : NaN;
         const graceUsable = Number.isFinite(graceEnv) && graceEnv >= 0;
         this.agentGraceMs = options.agentGraceMs ?? (graceUsable ? graceEnv : DEFAULT_AGENT_GRACE_MS);
+        this.pendingBootTtlMs = options.pendingBootTtlMs ?? PENDING_BOOT_TTL_MS;
         // Say so rather than only documenting it. Both times this parsing was wrong the symptom was
         // the same — the hold switched off and nothing mentioned it — and somebody who types `15s` is
         // reading their terminal, not the configuration table.
@@ -550,6 +600,13 @@ export class RelayServer {
         for (const requester of this.networkStateRequesters.values())
             requester.dispose();
         this.networkStateRequesters.clear();
+        for (const entry of this.shutdownRequesters.values())
+            clearTimeout(entry.timer);
+        this.shutdownRequesters.clear();
+        // Same argument as the holds above: an expiry firing after `stop()` would run against a dead
+        // server, and an unref'd 180s timer still outlives the test runner's process.
+        for (const key of this.pendingBoots.keys())
+            this.forgetBoot(key);
         const closeTunnel = new Promise((resolve, reject) => {
             // Not listening means `start()` never reached it, or its listen failed; `close()` would reject.
             if (!this.tunnelServer?.listening)
@@ -618,15 +675,22 @@ export class RelayServer {
     }
     /**
      * Injected into the handlers whose write can take access away — member update and removal, token
-     * revocation, a password reset or change — and called after the write commits. It carries no argument on
-     * purpose: the sweep re-derives every socket's standing from the database, so no handler has to know
-     * which sockets its change affects.
+     * revocation, a password reset or change — and called after the write commits. The sweep re-derives
+     * every socket's standing from the database, so when the database answers, no handler has to know which
+     * sockets its change affects.
+     *
+     * `affected` names the credential the write just reduced (`AuthChange`), and matters only when a lookup
+     * fails: the sockets resting on that credential are closed anyway (fail closed), because the one thing
+     * known for certain is that it just went down. Scoped to what the write touched, so revoking an unused
+     * CI token cannot take down the owner's agents and every session running on them. Every other socket is
+     * left alone as before.
      */
-    onAuthChanged = () => {
-        this.revalidateSockets(this.wss.clients);
+    onAuthChanged = (affected) => {
+        this.revalidateSockets(this.wss.clients, affected);
     };
-    revalidateSockets(clients) {
+    revalidateSockets(clients, affected) {
         const now = Math.floor(Date.now() / 1000);
+        let fault = null;
         for (const ws of clients) {
             const principal = this.principals.get(ws);
             if (!principal || this.revokedSockets.has(ws) || ws.readyState !== WebSocket.OPEN)
@@ -651,13 +715,20 @@ export class RelayServer {
             }
             catch (err) {
                 // A database fault is not a revocation: closing every socket on a transient `SQLITE_BUSY` would
-                // disconnect the whole team. The next sweep asks again.
-                logger.error('socket re-validation failed:', err);
-                return;
+                // disconnect the whole team, so the others wait for the next sweep. The exception is the member
+                // whose access this sweep was run for: a write just took it away, and letting their socket keep
+                // sending until the database recovers is the hole this closes. Keep going rather than stopping at
+                // the first fault, or a socket of that member later in the set would never be reached.
+                fault ??= err;
+                if (affected && isAffectedBy(principal, affected))
+                    this.closeForAuth(ws, WS_ACCESS_CHANGED_REASON);
+                continue;
             }
             if (reason !== null)
                 this.closeForAuth(ws, reason);
         }
+        if (fault !== null)
+            logger.error('socket re-validation failed:', fault);
     }
     closeForAuth(ws, reason) {
         this.revokedSockets.add(ws);
@@ -743,6 +814,13 @@ export class RelayServer {
         this.idrRequesters.delete(sessionId);
         this.networkStateRequesters.get(sessionId)?.dispose();
         this.networkStateRequesters.delete(sessionId);
+        // Tracked boots die with the session too (#885 review). These paths — `session:end`,
+        // `session:leave`, the cross-identity removal — bypass `evictAgentSocket`, so without this
+        // the entry outlives the session it names. Harmless but unbounded: a late correlated reply
+        // still clears via `settleBoot`, and `invalidateBootsFor` sends nothing for a gone session,
+        // so this only bounds the map. Scoped by session, never by socket, so a rebound session's
+        // entry — which lives on under the same id — is untouched.
+        this.forgetEvictedBoots(new Set([sessionId]));
     }
     /**
      * Throttled callback asking the session's agent for an on-demand IDR (fast drop recovery); ignored by
@@ -1010,6 +1088,7 @@ export class RelayServer {
         ws.on('close', () => {
             this.wsRoles.delete(ws);
             this.wsExternal.delete(ws);
+            this.forgetShutdownRequesters(ws);
             // Agent main socket disconnected → hold its sessions open for a moment in case the agent is
             // coming back (#426), rather than ending them where they stand.
             if (this.holdAgentSocket(ws))
@@ -1223,7 +1302,12 @@ export class RelayServer {
             // `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 (this.ownsSession(ws, this.sessions.get(msg.sessionId))) {
+                const ended = this.sessions.get(msg.sessionId);
+                if (this.ownsSession(ws, ended)) {
+                    // Silently: the holder ended it, and the shutdown may still complete on the device — saying it
+                    // failed would be a guess. The caller keeps its own deadline, as it did before #567.
+                    if (ended)
+                        this.settleShutdownRequesters(ended, null);
                     this.sessions.remove(msg.sessionId);
                     this.forgetSessionState(msg.sessionId);
                 }
@@ -1307,6 +1391,10 @@ export class RelayServer {
                 break;
             }
             case 'device:boot-error': {
+                // A correlated reply answers a tracked boot, whatever else it does — so the entry goes
+                // even when nobody is left to forward to. An id-less frame answers no request, so it
+                // clears nothing.
+                this.settleBoot(msg.sessionId, msg.requestId);
                 const session = this.sessions.get(msg.sessionId);
                 if (session?.browserSocket?.readyState === WebSocket.OPEN) {
                     session.browserSocket.send(JSON.stringify(raw));
@@ -1322,6 +1410,19 @@ export class RelayServer {
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
                     session.browserSocket.send(JSON.stringify(raw));
                 }
+                this.answerShutdownRequester(session, msg.requestId, raw);
+                break;
+            }
+            case 'device:shutdown-error': {
+                // The agent's half of the pair (#455). Device status is left alone: the shutdown was attempted
+                // and not confirmed, so the device may well still be running.
+                const session = this.sessions.get(msg.sessionId);
+                if (!session)
+                    break;
+                if (session.browserSocket?.readyState === WebSocket.OPEN) {
+                    session.browserSocket.send(JSON.stringify(raw));
+                }
+                this.answerShutdownRequester(session, msg.requestId, raw);
                 break;
             }
             case 'device:ready': {
@@ -1330,6 +1431,8 @@ export class RelayServer {
                 // an agent that omits it resolves no session here, exactly as before.
                 if (msg.sessionId === undefined)
                     break;
+                // Correlated only: a replay or an old agent's id-less ready answers no tracked boot.
+                this.settleBoot(msg.sessionId, msg.requestId);
                 const session = this.sessions.get(msg.sessionId);
                 if (!session)
                     break;
@@ -1383,7 +1486,7 @@ export class RelayServer {
             // 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
+            // three id-less 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': {
@@ -1422,6 +1525,9 @@ export class RelayServer {
                 // 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;
+                // Tracked by the socket it actually goes to (#885): a rebind invalidates only the boots
+                // tied to the replaced socket, so a boot dispatched after the rebind stays answerable.
+                this.rememberBoot(msg.sessionId, msg.requestId, boot.session.agentSocket);
                 // 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;
@@ -1464,6 +1570,7 @@ export class RelayServer {
                     });
                     break;
                 }
+                this.rememberShutdownRequester(ws, target.session.id, msg.requestId);
                 target.session.agentSocket.send(JSON.stringify(msg));
                 break;
             }
@@ -1629,6 +1736,58 @@ export class RelayServer {
      * Messages the relay merely *forwards* do not use this: they are re-serialised unchanged, so
      * they keep their inbound type and there is nothing new to check.
      */
+    rememberShutdownRequester(ws, sessionId, requestId) {
+        // The idle timer's shutdown and the dashboard's teardown carry no id, and nobody waits on either.
+        if (requestId === undefined)
+            return;
+        const key = shutdownRequesterKey(sessionId, requestId);
+        const prior = this.shutdownRequesters.get(key);
+        if (prior)
+            clearTimeout(prior.timer);
+        // Bounds an entry an older agent will never answer — it has no failure reply to send.
+        const timer = setTimeout(() => this.shutdownRequesters.delete(key), SHUTDOWN_REQUESTER_TTL_MS);
+        this.shutdownRequesters.set(key, { sessionId, requestId, ws, timer });
+    }
+    /** Hands the agent's answer to whoever asked for it, when that is not the holder — who already has it. */
+    answerShutdownRequester(session, requestId, raw) {
+        if (requestId === undefined)
+            return;
+        const key = shutdownRequesterKey(session.id, requestId);
+        const entry = this.shutdownRequesters.get(key);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        this.shutdownRequesters.delete(key);
+        // Compared now rather than at dispatch: a caller that has joined since holds the session, and was sent
+        // this a line ago.
+        if (entry.ws === session.browserSocket)
+            return;
+        if (entry.ws.readyState === WebSocket.OPEN)
+            entry.ws.send(JSON.stringify(raw));
+    }
+    /**
+     * The session is being removed, so an answer from its agent — if one ever comes — is dropped at
+     * `sessions.get`. `message` null settles in silence; otherwise a caller that never joined is told.
+     */
+    settleShutdownRequesters(session, message) {
+        for (const [key, entry] of this.shutdownRequesters) {
+            if (entry.sessionId !== session.id)
+                continue;
+            clearTimeout(entry.timer);
+            this.shutdownRequesters.delete(key);
+            if (message === null || entry.ws === session.browserSocket)
+                continue;
+            this.sendTo(entry.ws, { type: 'device:shutdown-error', sessionId: session.id, requestId: entry.requestId, message });
+        }
+    }
+    forgetShutdownRequesters(ws) {
+        for (const [key, entry] of this.shutdownRequesters) {
+            if (entry.ws !== ws)
+                continue;
+            clearTimeout(entry.timer);
+            this.shutdownRequesters.delete(key);
+        }
+    }
     sendTo(socket, msg) {
         if (socket.readyState !== WebSocket.OPEN)
             return;
@@ -1651,6 +1810,77 @@ export class RelayServer {
             }
         }
     }
+    bootKey(sessionId, requestId) {
+        return `${sessionId}${requestId}`;
+    }
+    /** Record a boot against the agent socket it was dispatched to. The door guarantees both ids. */
+    rememberBoot(sessionId, requestId, agentSocket) {
+        const key = this.bootKey(sessionId, requestId);
+        // Replacing, not doubling: a client never reuses a correlator, but forgetting the old timer
+        // here is what keeps a replaced entry from firing after its successor was settled.
+        this.forgetBoot(key);
+        const timer = setTimeout(() => this.forgetBoot(key), this.pendingBootTtlMs);
+        this.pendingBoots.set(key, { sessionId, requestId, agentSocket, timer });
+    }
+    /** The one way an entry leaves: every removal path funnels through here so no timer survives it. */
+    forgetBoot(key) {
+        const pending = this.pendingBoots.get(key);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.pendingBoots.delete(key);
+    }
+    /**
+     * Drop the tracked boot a correlated reply answers. The key needs no live session: an agent
+     * answering after its session was removed still answers that request. An absent `requestId`
+     * is not the answer to anything, so it drops nothing.
+     */
+    settleBoot(sessionId, requestId) {
+        if (typeof sessionId !== 'string' || typeof requestId !== 'string')
+            return;
+        this.forgetBoot(this.bootKey(sessionId, requestId));
+    }
+    /**
+     * Answer the tracked boots tied to a replaced agent socket (#885). Called after the
+     * `session:rebound` frames are sent, so the client records `needsReboot` first and the error
+     * below is classified with the cause attached. Boots dispatched to any other socket — in
+     * particular to the new agent after the rebind — are left pending.
+     */
+    invalidateBootsFor(oldSockets) {
+        if (oldSockets.size === 0)
+            return;
+        for (const [key, pending] of this.pendingBoots.entries()) {
+            if (!oldSockets.has(pending.agentSocket))
+                continue;
+            this.forgetBoot(key);
+            const session = this.sessions.get(pending.sessionId);
+            // `sendTo` skips a socket that is not OPEN, and a session nobody has joined has no
+            // `browserSocket` at all — either way the entry is still gone, so nothing later answers
+            // a request nobody holds.
+            if (!session?.browserSocket)
+                continue;
+            this.sendTo(session.browserSocket, {
+                type: 'device:boot-error',
+                sessionId: pending.sessionId,
+                requestId: pending.requestId,
+                message: `session ${pending.sessionId} rebounded to a new agent while this boot was in flight, ` +
+                    'and that agent never saw this request',
+            });
+        }
+    }
+    /**
+     * Silently drop the tracked boots of sessions that no longer exist. Their callers were already
+     * settled with the better diagnosis (`session:terminated`), so answering as well would send a
+     * second failure for the same request. Scoped to the evicted sessions rather than the socket:
+     * rebound sessions have already moved off it, and their entries are `invalidateBootsFor`'s to
+     * answer, not this one's to drop.
+     */
+    forgetEvictedBoots(sessionIds) {
+        for (const [key, pending] of this.pendingBoots.entries()) {
+            if (sessionIds.has(pending.sessionId))
+                this.forgetBoot(key);
+        }
+    }
     /**
      * The agent's socket went away. Keep its sessions and wait for that agent to come back, instead
      * of ending them here — a restarting agent registers about a second later, and until #426 stage 3
@@ -1725,6 +1955,10 @@ export class RelayServer {
         if (agentSessions.length === 0)
             return false;
         this.rejectPending(new Set(agentSessions.map((s) => s.id)), 'Agent disconnected');
+        // Their tracked boots go with them, silently: the `session:terminated` below settles those
+        // callers with the better diagnosis. Rebound sessions are not in this set — they moved off
+        // this socket — so their boots survive for `invalidateBootsFor` to answer.
+        this.forgetEvictedBoots(new Set(agentSessions.map((s) => s.id)));
         // Tell whoever is attached before the session stops existing — after `remove()` the socket
         // reference is gone. Without this the browser keeps a live socket addressed to a sessionId the
         // relay no longer knows, so everything it sends is dropped as unknown and nothing streams back:
@@ -1741,7 +1975,10 @@ export class RelayServer {
                 });
             }
         }
+        // After `session:terminated`, so a caller that holds the session is settled by that — it carries the
+        // better diagnosis — and only a caller that never joined hears from `settleShutdownRequesters`.
         for (const s of agentSessions) {
+            this.settleShutdownRequesters(s, SHUTDOWN_OUTCOME_LOST);
             this.sessions.remove(s.id);
             this.forgetSessionState(s.id);
         }
@@ -1774,6 +2011,10 @@ export class RelayServer {
         // deduplicate — the second card would name a session the agent has never heard of, which is the
         // symptom this whole change is fixing.
         const rebound = new Map();
+        // Sockets a rebind actually moved a session off of. Only boots tied to one of these are
+        // stranded: a boot dispatched after the rebind below rides the new socket, and the eviction
+        // further down must not sweep the entries this set protects (see `forgetEvictedBoots`).
+        const reboundOldSockets = new Set();
         if (identity) {
             for (const old of this.sessions.getAgentSocketsByIdentity(identity, msg.platform)) {
                 if (old === ws)
@@ -1793,6 +2034,7 @@ export class RelayServer {
                         continue;
                     this.sessions.rebind(s.id, ws, device, agent);
                     rebound.set(s.deviceId, s.id);
+                    reboundOldSockets.add(old);
                 }
                 // Evict before terminate: the old socket's close fires async, by which point its sessions are
                 // gone and its in-flight screenshots would be undiscoverable — reject them here instead.
@@ -1803,6 +2045,7 @@ export class RelayServer {
         }
         // Their in-flight requests are addressed to a process that is gone, and the eviction above can
         // no longer see them. Nothing else would ever settle these.
+        // Shutdowns are deliberately not settled here — see `shutdownRequesters` for why they follow the session.
         if (rebound.size > 0)
             this.rejectPending(new Set(rebound.values()), 'Agent restarted');
         // A device can be back under an agent this session cannot be rebound to — identity is
@@ -1819,6 +2062,7 @@ export class RelayServer {
                 if (s.browserSocket) {
                     this.sendTo(s.browserSocket, { type: 'session:terminated', sessionId: s.id, reason: 'agent-disconnected' });
                 }
+                this.settleShutdownRequesters(s, SHUTDOWN_OUTCOME_LOST);
                 this.sessions.remove(s.id);
                 this.forgetSessionState(s.id);
             }
@@ -1841,6 +2085,11 @@ export class RelayServer {
                 this.sendTo(s.browserSocket, { type: 'session:rebound', sessionId, capabilities: msg.capabilities ?? [] });
             }
         }
+        // After the rebound frames, so the client records `needsReboot` before the error below
+        // arrives and classifies it with the cause attached. Only boots tied to the replaced
+        // sockets: a boot sent after the rebind above was dispatched to the new agent, which boots
+        // the device and answers — settling it here would fail a boot that succeeds (#885).
+        this.invalidateBootsFor(reboundOldSockets);
         if (rebound.size > 0)
             logger.info(`agent restarted — ${rebound.size} session(s) kept across the restart`);
         // The startup banner prints "Waiting for agents..." once and then the relay says nothing either
@@ -1868,8 +2117,9 @@ export class RelayServer {
         // 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.
+        // `owner !== ownerOf(ws)` because a client re-joining a session it already holds is not contending
+        // with anyone: the viewer re-sends `session:start` each time its socket reconnects, and `mcp-server`
+        // and `flow-runner` keep one `clientId` per process, so their explicit re-join is the same client.
         // 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 &&
@@ -1988,7 +2238,7 @@ export class RelayServer {
             // 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'))
+            if (hasCapability(session.agentCapabilities, 'network-control'))
                 this.networkStateRequester(session.id)();
         }
     }
@@ -2350,7 +2600,7 @@ export class RelayServer {
      * laptop waking up would otherwise repeat this indefinitely. Same shape as `warnedProxyMisconfig`.
      */
     warnLegacyInstaller(identity, capabilities) {
-        if (capabilities.includes('build-download') || this.warnedLegacyInstaller.has(identity))
+        if (hasCapability(capabilities, 'build-download') || this.warnedLegacyInstaller.has(identity))
             return;
         this.warnedLegacyInstaller.add(identity);
         logger.warn(`[relay] agent ${identity} predates build downloading. If it is not on the same machine as ` +
@@ -2654,6 +2904,17 @@ export class RelayServer {
     serveStatic(req, res) {
         const urlPath = (req.url ?? '/').split('?')[0];
         let filePath = path.join(this.publicDir, urlPath === '/' ? '/index.html' : urlPath);
+        // **Contained before anything is read or probed.** `req.url` is the raw request target and Node does
+        // not normalise it, so `/../../etc/passwd` reached `path.join` intact and the join walked out of
+        // `publicDir` — unauthenticated, and the relay's environment and database were one request away.
+        // `serveUpload` has had this check since #173. Checked on the joined path because the index lookup and
+        // the `.br`/`.gz` siblings below are all derived from it; the separator keeps a sibling directory
+        // whose name starts with `publicDir`'s outside.
+        if (!path.resolve(filePath).startsWith(path.resolve(this.publicDir) + path.sep)) {
+            res.writeHead(404);
+            res.end('Not found');
+            return;
+        }
         // Next.js static export: try exact path, then path/index.html (trailingSlash)
         if (!fs.existsSync(filePath)) {
             const withIndex = path.join(filePath, 'index.html');